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) — plus its two refusal traps: ENOSPC masquerading as a stale lock, and an unreadable container-storage directory poisoning the whole root scan.

Purging .AGENTTRASH — invocation, and the two traps that make it refuse

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).
• 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.
• Deleting a big staged item by hand (e.g. find <dir> -depth -delete) is the fallback only when the tool cannot run at all — see trap 1 — and the operator's purge approval covers exactly that.

Trap 1: a full filesystem makes it lie about a lock (measured 2026-10-30)

With 0 bytes free, three invocations refused with

purge-agenttrash: refused /home/<user>: exists and is not ours to reclaim

and no lock directory existed anywhere. The script writes its lock and its plan file before scanning; both hit ENOSPC, and the failure surfaced as the lock-reclaim message. There is nothing to reclaim — free space first (delete the staged item, move it to another volume, journalctl --vacuum-size=), then run plan + --execute. Never hunt a phantom lock because the message says so; check df first.

Trap 2: an unreadable directory spoils the whole root

collect_root turns any nonzero find status into a root refusal, so the plan is built from a partial scan and the root reports refused=1 even though find printed every .AGENTTRASH it found.

• On the dev box the cause is uutils find (find --version → find 0.8.0), which exits 1 on ~/.local/share/containers/storage/**. Proof: find /home/blank -xdev -name .AGENTTRASH >/dev/null 2>&1; echo $? → 1, while a narrower root → 0.
• On dankserver GNU find does the same, because rootless podman storage holds foreign-UID directories (overlay/*/diff/var/lib/mysql, valkey, calibre/plugins, apt/.../partial): find /home/dank -xdev -name .AGENTTRASH 2>&1 >/dev/null | head shows the denials.
• Fix to land in the script (not to improvise around): prune ~/.local/share/containers from the scan — a .AGENTTRASH never lives inside container storage — or accept partial output and reserve refusal for a hard find failure. sh -n / shellcheck is the gate; bash -n is not.

Verified good path (dankserver, 2026-10-30)

After freeing space by hand: /tmp-scoped plan → --execute deleted the staged item and reported removed=1 deleted=1; a second --execute /mnt/entropy cleaned that volume's root (refused=0). The cleanup log carries one dated line per run; read it instead of re-deriving what happened.