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 two refusal traps: a false stale-lock error on a full filesystem, and $HOME refused on dankserver by podman-storage permission denials.

Purging .AGENTTRASH — invocation and two refusal traps

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.

Trap 1: a FULL filesystem makes it lie about a lock

The script acquires ~/.agenttrash-purge.lock and writes a plan file before it scans. On a filesystem with 0 bytes free both writes fail ENOSPC, and the run dies with:

purge-agenttrash: /home/…/.agenttrash-purge.lock exists and is not ours to reclaim

while no lock exists (find <root> -maxdepth 2 -name '.agenttrash-purge.lock' comes back empty, pgrep -af purge-agenttrash shows nothing). Do not hunt the phantom lock and do not delete anything to "reclaim" it: check df -h first. Free space by the purge's own intended action — delete the staged item the operator approved (a same-filesystem mv into .AGENTTRASH frees nothing; only deletion does) — then re-run the tool, which will clean the rest and log its summary.

Trap 2: $HOME is always refused on dankserver

sh scripts/purge-agenttrash.sh on dankserver reports refused /home/dank (find failed) and exits 1 even though the plan is otherwise right, and ~/.AGENTTRASH-cleanup.log records refused=1 beside whatever it did manage.

• Cause: find /home/dank -xdev -name .AGENTTRASH exits 1 there because rootless podman storage contains UID-mismatched directories — ~/.local/share/containers/storage/overlay/*/diff/var/lib/mysql, …/etc/valkey, …/.config/calibre/plugins, …/var/cache/apt/archives/partial — plus ~/Containers/romm/mariadb/*. collect_root turns any nonzero find status into a root refusal, so a partial scan becomes no plan.
• Find still prints every real tree (14 on dankserver: vLLM/, Containers/, four under serverAppConfigs, the swift15 checkout), so the refusal is about the scan status, not the candidates.
• This is the same class as the uutils-find trap on the dev box, with a different cause (GNU find + foreign-owned overlay internals). Minimal fix, safe because a .AGENTTRASH never lives inside container storage: prune -path "$HOME/.local/share/containers" from the scan, or accept find's partial output and reserve the refusal for a hard find failure. Verify with sh -n/shellcheck, not bash -n.
• Do not run the purger with sudo to dodge this: candidates are judged by ownership, and a root-owned scan changes the refusal outcome rather than fixing it. Retire the blocker, then re-run as the deploy user.