security: fail cache-trash permanent deletion closed

CHANGELOG.md

@@ -104,6 +104,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ### Security
 
+- Return a stable cache-cleanup argument error without reflecting an untrusted option payload into
+  terminal or automation logs; permanent cache-Trash deletion remains fail closed.
 - Default personal cloud-provider OAuth consent to read-only; upload scope and API write
   authority now require an explicit user opt-in.
 - Catalog the Cargo registry source tree as an explicit, identity-bound regenerable-cache target;

docs/architecture/adr/0002-cache-cleanup-is-per-item-evidence-bound.md

@@ -1,6 +1,6 @@
 # ADR-0002: Cache cleanup is per-item active-use evidence bound
 
-**Status:** Accepted
+**Status:** Superseded by ADR-0012
 **Date:** 2026-08-20
 
 ## Context
@@ -99,5 +99,6 @@ applies to user files or cloud-provider placeholders.
 ## References
 
 - [ADR-0001: Provider evidence drives the cloud-offload Goal](0001-cloud-offload-goal-state.md)
+- [ADR-0012: Cache Trash permanent deletion fails closed](0012-cache-trash-permanent-delete-fails-closed.md)
 - `src-tauri/src/cache_cleanup.rs`
 - `src-tauri/src/rules.rs`

docs/architecture/adr/0012-cache-trash-permanent-delete-fails-closed.md

@@ -0,0 +1,84 @@
+# ADR-0012: Cache Trash permanent deletion fails closed
+
+**Status:** Proposed
+**Date:** 2026-09-03
+**Supersedes:** ADR-0002 only for permanent deletion of cache entries already in OS Trash
+
+## Context
+
+ADR-0002 allowed a separate `--execute --purge-proven-cache-trash` path to permanently remove
+structurally recognized cache directories from operating-system Trash after pathname-based
+revalidation. Subsequent implementation review showed that the final irreversible deletion syscall
+was not bound to the exact reviewed filesystem object. A pathname can be replaced after review and
+before recursive removal, so the earlier policy could not satisfy DiskSage's deletion-safety
+boundary even when the candidate name, structure, size, and symlink checks were repeated.
+
+DiskSage already has a reversible, identity-bound cleanup path that moves inactive regenerable cache
+children into OS Trash. Permanent removal is different: once Trash is bypassed there is no product
+undo boundary, so evidence that is sufficient for staging is not sufficient for irreversible
+deletion.
+
+## Decision
+
+DiskSage does not perform in-app permanent deletion of reviewed cache-Trash entries until the final
+irreversible filesystem operation can be bound to the exact object that was reviewed and approved.
+
+- `--purge-proven-cache-trash` remains a read-only evidence operation.
+- `--execute --purge-proven-cache-trash` returns
+  `cache-trash-identity-bound-permanent-delete-unavailable` before journal or filesystem mutation.
+- The library boundary also fails closed and does not call pathname-recursive permanent-deletion
+  primitives.
+- Candidate names, signatures, byte counts, and approval phrases are review evidence only; they do
+  not create irreversible mutation authority.
+- Operators who intend permanent reclaim must inspect the candidate evidence and empty the native
+  Trash manually through the operating system. DiskSage does not claim those bytes as physically
+  reclaimed until the operating system reports the resulting availability change.
+- User files, cloud-provider placeholders, and arbitrary Trash entries remain outside this cache
+  evidence path.
+
+This decision leaves ADR-0002's per-item active-use checks and reversible OS-Trash staging intact.
+Only its separate permanent-delete authorization is superseded.
+
+## Consequences
+
+- The CLI and desktop remain conservative under disk pressure: they can identify regenerable cache
+  material but cannot silently turn that evidence into an irreversible delete.
+- Automation receives a stable refusal code rather than a partial journal or ambiguous success
+  receipt.
+- Physical space recovery may require an explicit operating-system Trash action after DiskSage has
+  completed its reversible cleanup.
+- A future permanent-delete capability requires a new or superseding ADR, a real object-bound
+  deletion primitive for each supported platform, race/alias/mount/hardlink tests, recovery and
+  audit semantics, and current-head release evidence before it can become Accepted.
+
+## Alternatives rejected
+
+- **Keep pathname revalidation plus recursive deletion.** Rejected because repeated pathname checks
+  do not bind the final syscall to the reviewed object and leave a check/use race at an irreversible
+  boundary.
+- **Treat a candidate-set approval phrase as delete authority.** Rejected because a phrase proves
+  what the user reviewed, not that the pathname still names the same filesystem object at mutation
+  time.
+- **Delete first and rely on the journal for recovery.** Rejected because a journal cannot restore an
+  object after a genuinely permanent delete and journal failure can itself occur after mutation.
+- **Broaden automatic cleanup instead of using Trash.** Rejected because reversible OS-Trash staging
+  is the product's established safety and recovery boundary for regenerable cache content.
+
+## Evidence and acceptance
+
+The production CLI regression creates a real cache-shaped directory under a temporary Trash,
+invokes `--execute --purge-proven-cache-trash`, and requires the refusal code while proving both the
+cache object and journal remain untouched. Documentation contract coverage requires the runbook and
+ADR index to describe the same fail-closed behavior.
+
+This ADR remains Proposed while the implementing PR is unmerged. Acceptance requires an unchanged
+exact head with the repository's required tests, security gates, coverage, review, and release
+verification all passing under live protection rules.
+
+## References
+
+- [ADR-0002: Cache cleanup is per-item active-use evidence bound](0002-cache-cleanup-is-per-item-evidence-bound.md)
+- `src-tauri/src/bin/disksage-cache-cleanup.rs`
+- `src-tauri/src/cache_cleanup.rs`
+- `src-tauri/tests/cache_cleanup_cli_purge_fail_closed.rs`
+- [Cache cleanup operator runbook](../../development/cache-cleanup-operator-runbook.md)

docs/architecture/adr/README.md

@@ -7,7 +7,7 @@ new numbered record rather than rewriting history.
 | ADR | Decision | Status |
 | --- | --- | --- |
 | [0001](0001-cloud-offload-goal-state.md) | Provider evidence drives the cloud-offload Goal | Accepted |
-| [0002](0002-cache-cleanup-is-per-item-evidence-bound.md) | Cache cleanup is per-item evidence-bound | Accepted |
+| [0002](0002-cache-cleanup-is-per-item-evidence-bound.md) | Cache cleanup is per-item evidence-bound | Superseded by 0012 for permanent cache-Trash deletion |
 | [0003](0003-zotero-local-api-metadata-handoff.md) | Zotero Local API metadata handoff | Accepted |
 | [0004](0004-bounded-maintenance-command-execution.md) | Bounded maintenance command execution | Accepted |
 | [0005](0005-hourly-agent-loop-is-advisory.md) | Hourly agent loop is advisory | Superseded by 0008 |
@@ -17,6 +17,7 @@ new numbered record rather than rewriting history.
 | [0009](0009-path-free-lineage-relation-graph.md) | Export a path-free lineage relation graph | Accepted |
 | [0010](0010-rooted-organize-destinations.md) | Require rooted, process-independent organize destinations | Accepted |
 | [0011](0011-cloud-transfer-failure-and-materialization.md) | Durable failed-copy evidence and placeholder-safe adoption | Accepted |
+| [0012](0012-cache-trash-permanent-delete-fails-closed.md) | Cache Trash permanent deletion fails closed | Proposed |
 
 New records must state context, decision, consequences, rejected alternatives, and the evidence or
 standard that led to the decision. A record never grants cloud-write or source-eviction authority;

docs/development/cache-cleanup-operator-runbook.md

@@ -26,10 +26,15 @@ If the Trash is consuming space, inspect only structurally proven cache entries
 
 `cargo run --locked --manifest-path src-tauri/Cargo.toml --bin disksage-cache-cleanup -- --purge-proven-cache-trash --journal-path /ABSOLUTE/journal.jsonl`
 
-The command is read-only until both `--execute` and `--purge-proven-cache-trash` are supplied.
-That explicit path permanently removes only the known cache signatures already in OS Trash; it
-does not empty Trash generally and never targets cloud placeholders or user files. Review its JSON
-result and journal before treating the reported bytes as reclaimed.
+This command is read-only evidence. Supplying `--execute` together with
+`--purge-proven-cache-trash` is intentionally refused with
+`cache-trash-identity-bound-permanent-delete-unavailable` before journal or filesystem mutation,
+because DiskSage does not yet have an object-bound primitive for the final irreversible deletion
+syscall. Review the JSON candidate evidence, then empty the native Trash manually through the
+operating system when permanent reclaim is intended. Do not treat candidate logical bytes as
+physically reclaimed until the operating system reports the resulting availability change.
+DiskSage never treats this review path as authority to empty Trash generally or to mutate cloud
+placeholders or user files.
 
 The cache catalog includes the macOS `uv`, Hugging Face, Codex runtime, Gradle, npm, pip, and Cargo
 registry cache/source roots when present. The Cargo registry source root is catalogued for explicit

src-tauri/src/bin/disksage-cache-cleanup.rs

@@ -3,16 +3,24 @@
 //! Without `--execute` this command is read-only. With it, the library path moves only inactive,
 //! identity-bound children of the npm, pnpm, Adobe, Edge, uv, and Trivy cache roots to OS Trash.
 
-use disksage_lib::cache_cleanup::{
-    clean_regenerable_caches_headless, proven_cache_trash_candidates, purge_proven_cache_trash,
-};
+use disksage_lib::cache_cleanup::{clean_regenerable_caches_headless, proven_cache_trash_snapshot};
 use std::ffi::OsString;
 use std::path::PathBuf;
 
+const PERMANENT_CACHE_TRASH_DELETE_UNAVAILABLE: &str =
+    "cache-trash-identity-bound-permanent-delete-unavailable";
 const USAGE: &str = "Usage: disksage-cache-cleanup [--execute] [--purge-proven-cache-trash] [--journal-path PATH]\n\
 Without --execute it reports the command is a no-op. With --execute it moves only observed,\n\
-inactive regenerable cache children to OS Trash. --purge-proven-cache-trash permanently removes\n\
-only structurally proven cache directories already in OS Trash.";
+inactive regenerable cache children to OS Trash. --purge-proven-cache-trash is read-only evidence;\n\
+permanent in-app deletion remains unavailable until the final syscall is object-bound.";
+
+fn read_only_notice(purge_proven_cache_trash: bool) -> &'static str {
+    if purge_proven_cache_trash {
+        "proven cache-Trash review is read-only; empty the native Trash manually to reclaim space; --execute cannot enable permanent deletion"
+    } else {
+        "pass --execute to move guarded cache children to OS Trash"
+    }
+}
 
 #[derive(Debug, PartialEq, Eq)]
 struct Args {
@@ -69,12 +77,31 @@ fn parse_args(raw_args: impl IntoIterator<Item = OsString>) -> Result<Option<Arg
     let mut execute = false;
     let mut purge_proven_cache_trash = false;
     let mut journal_path = default_journal_path()?;
+    let mut seen_execute = false;
+    let mut seen_purge_proven_cache_trash = false;
+    let mut seen_journal_path = false;
     let mut args = first_arg.into_iter().chain(args);
     while let Some(arg) = args.next() {
         match arg.to_str() {
-            Some("--execute") => execute = true,
-            Some("--purge-proven-cache-trash") => purge_proven_cache_trash = true,
+            Some("--execute") => {
+                if seen_execute {
+                    return Err("--execute may be supplied once".into());
+                }
+                seen_execute = true;
+                execute = true;
+            }
+            Some("--purge-proven-cache-trash") => {
+                if seen_purge_proven_cache_trash {
+                    return Err("--purge-proven-cache-trash may be supplied once".into());
+                }
+                seen_purge_proven_cache_trash = true;
+                purge_proven_cache_trash = true;
+            }
             Some("--journal-path") => {
+                if seen_journal_path {
+                    return Err("--journal-path may be supplied once".into());
+                }
+                seen_journal_path = true;
                 journal_path = PathBuf::from(
                     args.next()
                         .ok_or_else(|| "--journal-path requires PATH".to_string())?,
@@ -84,7 +111,7 @@ fn parse_args(raw_args: impl IntoIterator<Item = OsString>) -> Result<Option<Arg
                 }
             }
             Some("-h" | "--help") => return Err(format!("--help must be used alone\n{USAGE}")),
-            Some(value) => return Err(format!("unknown option: {value}\n{USAGE}")),
+            Some(_) => return Err(format!("cache-cleanup-invalid-argument\n{USAGE}")),
             None => return Err(format!("invalid UTF-8 option\n{USAGE}")),
         }
     }
@@ -108,11 +135,18 @@ fn run_with_args(raw_args: impl IntoIterator<Item = OsString>) -> Result<(), Str
         return Ok(());
     };
     if !args.execute {
-        let cache_trash = if args.purge_proven_cache_trash {
-            serde_json::to_value(proven_cache_trash_candidates(&home_directory()?))
-                .map_err(|error| error.to_string())?
+        let notice = read_only_notice(args.purge_proven_cache_trash);
+        let (cache_trash, cache_trash_snapshot) = if args.purge_proven_cache_trash {
+            let snapshot = proven_cache_trash_snapshot(&home_directory()?);
+            let candidates =
+                serde_json::to_value(&snapshot.candidates).map_err(|error| error.to_string())?;
+            let snapshot = serde_json::to_value(snapshot).map_err(|error| error.to_string())?;
+            (candidates, snapshot)
         } else {
-            serde_json::Value::Array(Vec::new())
+            (
+                serde_json::Value::Array(Vec::new()),
+                serde_json::Value::Null,
+            )
         };
         println!(
             "{}",
@@ -121,27 +155,18 @@ fn run_with_args(raw_args: impl IntoIterator<Item = OsString>) -> Result<(), Str
                 "journal_path": args.journal_path,
                 "purge_proven_cache_trash": args.purge_proven_cache_trash,
                 "proven_cache_trash": cache_trash,
-                "notice": "pass --execute to perform the guarded OS-Trash operation"
+                "proven_cache_trash_snapshot": cache_trash_snapshot,
+                "notice": notice
             })
         );
         return Ok(());
     }
+    if args.purge_proven_cache_trash {
+        return Err(PERMANENT_CACHE_TRASH_DELETE_UNAVAILABLE.into());
+    }
     if let Some(parent) = args.journal_path.parent() {
         std::fs::create_dir_all(parent).map_err(|error| error.to_string())?;
     }
-    if args.purge_proven_cache_trash {
-        let results = purge_proven_cache_trash(&home_directory()?, &args.journal_path, now_ms())?;
-        println!(
-            "{}",
-            serde_json::json!({
-                "executed": true,
-                "purge_proven_cache_trash": true,
-                "journal_path": args.journal_path,
-                "results": results
-            })
-        );
-        return Ok(());
-    }
     let evidence = clean_regenerable_caches_headless(&args.journal_path, now_ms())?;
     println!(
         "{}",
@@ -172,11 +197,8 @@ mod tests {
 
     #[test]
     fn help_must_be_used_alone() {
-        let error = parse_args([
-            OsString::from("--help"),
-            OsString::from("--execute"),
-        ])
-        .unwrap_err();
+        let error =
+            parse_args([OsString::from("--help"), OsString::from("--execute")]).unwrap_err();
         assert!(error.starts_with("--help must be used alone"));
     }
 
@@ -190,6 +212,34 @@ mod tests {
         assert_eq!(error, "--journal-path must be absolute");
     }
 
+    #[test]
+    fn duplicate_authority_singletons_are_rejected() {
+        let duplicate_execute = parse_args([
+            OsString::from("--execute"),
+            OsString::from("--execute"),
+        ])
+        .unwrap_err();
+        assert_eq!(duplicate_execute, "--execute may be supplied once");
+
+        let duplicate_purge = parse_args([
+            OsString::from("--purge-proven-cache-trash"),
+            OsString::from("--purge-proven-cache-trash"),
+        ])
+        .unwrap_err();
+        assert_eq!(
+            duplicate_purge,
+            "--purge-proven-cache-trash may be supplied once"
+        );
+    }
+
+    #[test]
+    fn unknown_argument_is_not_reflected() {
+        let payload = "--unknown-with-sensitive-value";
+        let error = parse_args([OsString::from(payload)]).unwrap_err();
+        assert!(error.contains("cache-cleanup-invalid-argument"));
+        assert!(!error.contains(payload));
+    }
+
     #[test]
     fn purge_cache_trash_flag_is_explicit() {
         let args = parse_args([OsString::from("--purge-proven-cache-trash")])
@@ -198,4 +248,12 @@ mod tests {
         assert!(!args.execute);
         assert!(args.purge_proven_cache_trash);
     }
+
+    #[test]
+    fn read_only_notice_matches_the_requested_action() {
+        assert!(read_only_notice(false).contains("pass --execute"));
+        assert!(read_only_notice(true).contains("read-only"));
+        assert!(read_only_notice(true).contains("empty the native Trash"));
+        assert!(!read_only_notice(true).contains("pass --execute to move"));
+    }
 }