scripts/purge-agenttrash.sh — a POSIX-sh sweeper that clears every .AGENTTRASH
directory on a machine and nothing else, plus its bats seam and the vault wiring.
Why
The deletion policy parks deleted files in .AGENTTRASH/ (in-repo beside the item,
elsewhere $HOME/.AGENTTRASH/YYYYMMDD-topic) and waits for approval to purge. Until
now the approved purge had no tool — the act itself was improvised per session. This
is the deterministic form of that one step.
Shape
Dialect: #!/bin/sh, shellcheck -S style clean, bash -n clean. Externals
limited to find stat rm date mkdir (+ a probed find -delete). Portable to any
POSIX host with GNU or BSD findutils.
Rule (stated once in the script's collect_root comment block):
a root's own .AGENTTRASH — or a root named .AGENTTRASH — is emptied in
place; the directory is the convention and survives;
deeper .AGENTTRASH trees are removed whole, nested entries accounted once;
symlinked and foreign-owned candidates are refused, never followed (rm -rf
deletes symlink entries but never traverses them);
/ is refused outright.
CLI: dry-run by default; --execute performs the plan; --quiet; --log PATH
(default $HOME/.AGENTTRASH-cleanup.log, one dated line per run); positional roots
(default $HOME). Every printed line is fixed at plan time in the on-disk plan
table, so dry-run and execute output can never drift.
Exit codes: 0 success / nothing to do, 2 usage error, 1 any refusal or
failure.
Tests
tests/purge_agenttrash.bats — 14 tests, all green.
./tests/run.sh — ALL TESTS PASSED (576 assertions) on the exact committed tree.
Docs
serverAppConfigs-docs/Operations/Payload and Disk Reclaim.md gains section 6. The approved purge (one fact, one owner — no new vault page).
Notes
Tests 7 and 10 were merged into one fixture with Frank's approval: the two
blind-written fixtures pinned mutually exclusive verbs (plan remove vs plan empty) for the same path class; no implementation could satisfy both.
The commit landed on wt/20261028-122814 (the standing worktree for this
session's cwd); the grilling ledger is at local://grilling-state.md.
## What
`scripts/purge-agenttrash.sh` — a POSIX-sh sweeper that clears every `.AGENTTRASH`
directory on a machine and nothing else, plus its bats seam and the vault wiring.
## Why
The deletion policy parks deleted files in `.AGENTTRASH/` (in-repo beside the item,
elsewhere `$HOME/.AGENTTRASH/YYYYMMDD-topic`) and waits for approval to purge. Until
now the approved purge had no tool — the act itself was improvised per session. This
is the deterministic form of that one step.
## Shape
- **Dialect**: `#!/bin/sh`, `shellcheck -S style` clean, `bash -n` clean. Externals
limited to `find stat rm date mkdir` (+ a probed `find -delete`). Portable to any
POSIX host with GNU or BSD findutils.
- **Rule** (stated once in the script's `collect_root` comment block):
- a root's own `.AGENTTRASH` — or a root named `.AGENTTRASH` — is *emptied in
place*; the directory is the convention and survives;
- deeper `.AGENTTRASH` trees are *removed* whole, nested entries accounted once;
- symlinked and foreign-owned candidates are *refused*, never followed (`rm -rf`
deletes symlink entries but never traverses them);
- `/` is refused outright.
- **CLI**: dry-run by default; `--execute` performs the plan; `--quiet`; `--log PATH`
(default `$HOME/.AGENTTRASH-cleanup.log`, one dated line per run); positional roots
(default `$HOME`). Every printed line is fixed at plan time in the on-disk plan
table, so dry-run and execute output can never drift.
- **Exit codes**: `0` success / nothing to do, `2` usage error, `1` any refusal or
failure.
## Tests
- `tests/purge_agenttrash.bats` — 14 tests, all green.
- `./tests/run.sh` — **ALL TESTS PASSED** (576 assertions) on the exact committed tree.
## Docs
`serverAppConfigs-docs/Operations/Payload and Disk Reclaim.md` gains section
*6. The approved purge* (one fact, one owner — no new vault page).
## Notes
- Tests 7 and 10 were merged into one fixture with Frank's approval: the two
blind-written fixtures pinned mutually exclusive verbs (`plan remove` vs
`plan empty`) for the same path class; no implementation could satisfy both.
- The commit landed on `wt/20261028-122814` (the standing worktree for this
session's cwd); the grilling ledger is at `local://grilling-state.md`.
---
cwd: /home/blank/.omp/wt/wt-20261028-122814-6d1fc1f · session: 01a183fb-ffa1-719f-a742-4a36f7765717
Portable POSIX-sh purge of exactly the fleet's deletion-policy trash: a
root's own .AGENTTRASH is emptied in place (the convention survives),
deeper .AGENTTRASH trees are removed with their nested entries accounted
once, symlinked/foreign-owned candidates are refused, / is refused.
Dry-run by default; --execute performs the plan and appends one dated log
line; every printed line is fixed at plan time in the on-disk plan table,
so dry-run and execute output can never drift.
Documented in Operations/Payload and Disk Reclaim.md section 6 (one fact
one owner - no new vault page). Tests: 14 green, ./tests/run.sh 576 green.
dank
merged commit fad87aa522 into main2026-10-28 19:22:20 -07:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
What
scripts/purge-agenttrash.sh— a POSIX-sh sweeper that clears every.AGENTTRASHdirectory on a machine and nothing else, plus its bats seam and the vault wiring.
Why
The deletion policy parks deleted files in
.AGENTTRASH/(in-repo beside the item,elsewhere
$HOME/.AGENTTRASH/YYYYMMDD-topic) and waits for approval to purge. Untilnow the approved purge had no tool — the act itself was improvised per session. This
is the deterministic form of that one step.
Shape
#!/bin/sh,shellcheck -S styleclean,bash -nclean. Externalslimited to
find stat rm date mkdir(+ a probedfind -delete). Portable to anyPOSIX host with GNU or BSD findutils.
collect_rootcomment block):.AGENTTRASH— or a root named.AGENTTRASH— is emptied inplace; the directory is the convention and survives;
.AGENTTRASHtrees are removed whole, nested entries accounted once;rm -rfdeletes symlink entries but never traverses them);
/is refused outright.--executeperforms the plan;--quiet;--log PATH(default
$HOME/.AGENTTRASH-cleanup.log, one dated line per run); positional roots(default
$HOME). Every printed line is fixed at plan time in the on-disk plantable, so dry-run and execute output can never drift.
0success / nothing to do,2usage error,1any refusal orfailure.
Tests
tests/purge_agenttrash.bats— 14 tests, all green../tests/run.sh— ALL TESTS PASSED (576 assertions) on the exact committed tree.Docs
serverAppConfigs-docs/Operations/Payload and Disk Reclaim.mdgains section6. The approved purge (one fact, one owner — no new vault page).
Notes
blind-written fixtures pinned mutually exclusive verbs (
plan removevsplan empty) for the same path class; no implementation could satisfy both.wt/20261028-122814(the standing worktree for thissession's cwd); the grilling ledger is at
local://grilling-state.md.cwd: /home/blank/.omp/wt/wt-20261028-122814-6d1fc1f · session: 01a183fb-ffa1-719f-a742-4a36f7765717