command-center/agent/managed-skills/agenttrash-purger-invocation/SKILL.md

name, description

name	description
agenttrash-purger-invocation	Invoke the .AGENTTRASH purger (scripts/purge-agenttrash.sh) to clear staged deletions, and diagnose its guaranteed exit 1 on hosts whose find is uutils (Rust) rather than GNU.

Purging .AGENTTRASH — invocation and the uutils-find trap

scripts/purge-agenttrash.sh (serverAppConfigs, merged in PR #79 fad87aa) is the tool form of the fleet's deletion policy: files land in .AGENTTRASH, and an approved purge runs this instead of being improvised per session.

Invoke

sh scripts/purge-agenttrash.sh                      # plan only — prints, deletes nothing
sh scripts/purge-agenttrash.sh --execute             # perform the plan
sh scripts/purge-agenttrash.sh --execute /some/root  # scope to one root (default: $HOME)

• --quiet silences per-line output; errors and the summary still print. --log PATH overrides the default ~/.AGENTTRASH-cleanup.log (one dated line per run — written even for a dry run, so pass a scratch --log when you only want to look).
• Every printable line is fixed at plan time in $HOME/.agenttrash-purge.lock/plan, so dry-run and --execute output cannot drift. Exit 0 ok · 1 any refusal or failure · 2 usage.
• Rule: a root's own .AGENTTRASH is emptied (the directory survives); deeper .AGENTTRASH trees are removed; symlinked or foreign-owned candidates are refused, never followed; / is refused outright.

The trap: uutils find makes it exit 1 on the dev box

On the workstation, sh scripts/purge-agenttrash.sh reports refused /home/blank (find failed) and exits 1 even though the plan is correct — and an --execute there acts on the recorded plan while still reporting failure.

• Cause: find --version reports find 0.8.0 (Rust uutils, errors as Error: <path>: Permission denied (os error 13)), not GNU findutils. It exits 1 whenever any directory under the root is unreadable — and ~/.local/share/containers/storage/** (podman overlay layers, mode 0700 dirs) is unreadable. collect_root turns any nonzero find status into a root refusal.
• Proved by: find /home/blank -xdev -name .AGENTTRASH >/dev/null 2>&1; echo $? → 1, while find /home/blank/.omp -xdev ... → 0.
• Fix, if it ever comes up (don't invent it): treat unreadable-directory errors as warnings, or accept find's partial output and reserve refusal for a hard find failure. Note bash -n is not the gate — shellcheck / sh -n is.