Skip to content

fix: consolidate slot cleanup and add verified stop handling - #321

Merged
dnth merged 4 commits into
mainfrom
fm/fm-cleanup-slot-consolidation
Nov 18, 2026
Merged

dnth merged 4 commits into
mainfrom
fm/fm-cleanup-slot-consolidation

Conversation

@dnth

@dnth dnth commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

Summary

 .agents/skills/cleanup/SKILL.md
+  Pooled working copies: inventory -> removal tiers -> remote -> stop
+  tracked-file comparison is evidence only; large ignored content named
+  remote removal: fm-on + --apply-slot <exact path>, never bulk or a steer
+  local stop marker honored between clean slots
 bin/fm-treehouse-sweep.sh
+  --stop     write state/treehouse-sweep-stop
+  --measure  named paths: existence + du -sk + classification
 docs/configuration.md
-  sweep procedure prose
+  flag contract + pointer to the cleanup skill
 tests/fm-treehouse-sweep.test.sh
+  unnamed, outside-pool, stopped, and measured cases

Evidence

  • Before: --all was the only remote route and remote pools were report-only; a running local --apply-clean had no stop path; the config document restated the sweep procedure; and there was no host measurement command.
    After: Remote removal is one exact captain-named path per fm-on invocation; local --stop is honored between clean slots; --measure reports existence, size, and tier through the same tracked command. tests/fm-treehouse-sweep.test.sh passes 14 checks, and the PR has 20 green checks.
$ TMPDIR="$PWD/.test-cleanup-tmp" bash tests/fm-treehouse-sweep.test.sh
ok - read-only measurement reports clean, damaged, partial, and fully removed paths
ok - measurement refuses unnamed, outside, symlinked, traversal, and mutating requests
ok - --stop writes the marker and the next apply pass stops before removing anything
ok - a stop marker is honored between clean slots
# 14 ok lines; exit 0

Merge Danger

Door: two-way

Blast Radius: Contained

The PR changes cleanup procedure and adds read-only measurement plus a local stop marker; it adds no automatic removal, and the existing --apply-slot and --apply-clean guards are unchanged.

Testing

Targeted regressions and five real local CLI scenarios passed after correcting a disposable origin's default branch. Transcripts were retained and fixtures removed. Remote transport was not exercised; no real pools or second mates were contacted.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Local synthetic pool inventory preserves files and rejects unapproved, unnamed, outside-pool, and damaged-slot removals ✅ pass live Live CLI transcript: default inventory, guard refusals, and unchanged file hashes.
A pending local stop prevents synthetic clean and dirty slots from being removed ✅ pass live Live CLI transcript: --stop followed by clean-pass and dirty-slot requests; paths preserved and marker consumed.
Stopping a running local synthetic sweep finishes the current slot and preserves the next slot ✅ pass live Live CLI transcript: real Treehouse removal completed for slot 1, sweep exited 3, and slot 2 survived.
Local host measurement distinguishes removed and surviving synthetic paths and refuses unsafe measurement requests ✅ pass live Live CLI transcript: repeated --measure output, independent du measurements, and invalid-path refusals.
An approved exact synthetic dirty path is removed while other copies survive ✅ pass live Live CLI transcript: captain-approved dirty-slot deletion and subsequent filesystem measurements.
Evidence: Live CLI transcript
$ git init -q -b main
[exit 0]
$ git config user.name Cleanup Fixture
[exit 0]
$ git config user.email fixture@example.invalid
[exit 0]
$ git add .
[exit 0]
$ git commit -qm landed fixture
[exit 0]
$ git init --bare -q {run-worktree}/.test-cleanup-tmp/product/origin.git
[exit 0]
$ git remote add origin {run-worktree}/.test-cleanup-tmp/product/origin.git
[exit 0]
$ git push -q origin main
[exit 0]
$ git remote set-head origin main
[exit 0]
$ git -C {run-worktree}/.test-cleanup-tmp/product/origin.git symbolic-ref HEAD refs/heads/main
[exit 0]
$ treehouse get --lease --no-fetch --json
🌳 Setting up worktree...
🌳 Leased worktree at {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/1/repo. Run 'treehouse return {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/1/repo' to release it.
{"path":"{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/1/repo","lease_id":"6149956235f8482b44630f143862cf07","lease_holder":"","leased_at":"2026-11-18T08:22:19.055918669+08:00","base_branch":"main"}
[exit 0]
$ treehouse get --lease --no-fetch --json
🌳 Setting up worktree...
🌳 Leased worktree at {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo. Run 'treehouse return {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo' to release it.
{"path":"{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo","lease_id":"f9f9ac7d34a15cf8402922f0251bf8e5","lease_holder":"","leased_at":"2026-11-18T08:22:19.096485746+08:00","base_branch":"main"}
[exit 0]
$ treehouse get --lease --no-fetch --json
A new version of treehouse is available: v3.1.1 → v3.1.8
Run "treehouse update" to update

🌳 Setting up worktree...
🌳 Leased worktree at {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo. Run 'treehouse return {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo' to release it.
{"path":"{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo","lease_id":"4720f887e10255b7d511a0019822ebf6","lease_holder":"","leased_at":"2026-11-18T08:22:19.145101501+08:00","base_branch":"main"}
[exit 0]
$ treehouse get --lease --no-fetch --json
A new version of treehouse is available: v3.1.1 → v3.1.8
Run "treehouse update" to update

🌳 Setting up worktree...
🌳 Leased worktree at {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo. Run 'treehouse return {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo' to release it.
{"path":"{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo","lease_id":"c17f81f8ebf93387b1e32d63135bb2ae","lease_holder":"","leased_at":"2026-11-18T08:22:19.188816914+08:00","base_branch":"main"}
[exit 0]
$ treehouse return {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/1/repo
A new version of treehouse is available: v3.1.1 → v3.1.8
Run "treehouse update" to update

🌳 Worktree returned to pool.
[exit 0]
$ treehouse return {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
A new version of treehouse is available: v3.1.1 → v3.1.8
Run "treehouse update" to update

🌳 Worktree returned to pool.
[exit 0]
$ treehouse return {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo
A new version of treehouse is available: v3.1.1 → v3.1.8
Run "treehouse update" to update

🌳 Worktree returned to pool.
[exit 0]
$ treehouse return {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo
A new version of treehouse is available: v3.1.1 → v3.1.8
Run "treehouse update" to update

🌳 Worktree returned to pool.
[exit 0]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --all
pool {run-worktree}/.test-cleanup-tmp/product/repo
  slot 1      clean    {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/1/repo
      clean, idle, unclaimed, merged; prune candidate
  slot 2      clean    {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
      clean, idle, unclaimed, merged; prune candidate
  slot 3      dirty    {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo
      uncommitted changes (?? unlanded.txt); captain may destroy by exact path
  slot 4      damaged  {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo
      broken worktree admin link; inspect-only, removal stays manual
  treehouse prune (dry run):
    A new version of treehouse is available: v3.1.1 → v3.1.8
    Run "treehouse update" to update
    
    🌳 Dry run: would prune 2 stale worktrees and reclaim 549.6 KiB.
    1     541.4 KiB  {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/1/repo
    2       8.2 KiB  {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
    🌳 Skipped 2 unsafe idle worktrees:
      uncommitted changes:
      3     {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo
      cannot verify worktree:
      4     no .git or .jj marker  {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo
    🌳 Re-run with --yes to delete these worktrees.
[exit 0]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --apply-clean
REFUSED: clean-tier removal is gated on the opt-in config/treehouse-sweep-clean flag file under the Firstmate home; create it to enable, or run without --apply-clean for a dry run
[exit 1]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --apply-slot
REFUSED: --apply-slot requires an exact slot worktree path
[exit 1]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --apply-slot {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo
REFUSED: --apply-slot req

... [9112 bytes truncated] ...

; untouched={run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo, {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo, {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/1/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/repo
path {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/1/repo
  classification: damaged/unreported
  existence: absent
  size_kib: 0 (absent)
path {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
  classification: clean
  existence: present
16	{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
path {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo
  classification: damaged
  existence: present
60	{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo
path {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/repo
  classification: damaged/unreported
  existence: present
8	{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/repo
[exit 0]
$ du -sk {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
16	{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
[exit 0]
$ du -sk {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo
60	{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/4/repo
[exit 0]
$ du -sk {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/repo
8	{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/repo
[exit 0]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --measure
REFUSED: --measure requires an exact slot worktree path
[exit 1]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --measure {run-worktree}/.test-cleanup-tmp/product/outside
REFUSED: --measure requires exact non-symlink paths inside a pool with readable treehouse-state.json
[exit 1]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/linked/repo
REFUSED: --measure requires exact non-symlink paths inside a pool with readable treehouse-state.json
[exit 1]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/../99/repo
REFUSED: --measure requires exact non-symlink paths inside a pool with readable treehouse-state.json
[exit 1]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo --apply-clean
REFUSED: --measure is read-only and cannot accompany apply, approval, or stop
[exit 1]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --apply-slot {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo --captain-approved
sweep: captain-approved destroy of dirty slot 3 at {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo
A new version of treehouse is available: v3.1.1 → v3.1.8
Run "treehouse update" to update

🌳 Destroyed 1 worktree in {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo and freed 8.2 KiB.
  3     [dirty]  8.2 KiB  {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo  (uncommitted changes)
[exit 0]
$ bash {run-worktree}/bin/fm-treehouse-sweep.sh --pool {run-worktree}/.test-cleanup-tmp/product/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo --measure {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/repo
path {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/3/repo
  classification: damaged/unreported
  existence: absent
  size_kib: 0 (absent)
path {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
  classification: clean
  existence: present
16	{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/2/repo
path {run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/repo
  classification: damaged/unreported
  existence: present
8	{run-worktree}/.test-cleanup-tmp/product/pools/.treehouse/repo-cac361/99/repo
[exit 0]
OBSERVED: only the exact captain-approved dirty path was removed; other synthetic copies survived.
Evidence: Validation scope and independent oracle
# Cleanup CLI validation

Executed the real `bin/fm-treehouse-sweep.sh` with Treehouse v3.1.1 and real Git repositories, entirely under a disposable worktree directory. No real pools or second mates were used. The remote transport was not exercised; the live results establish the local tracked command behavior used by the documented route.

The independent oracle was the author intent: report first; require exact dirty-path approval; refuse out-of-pool and damaged removal; consume stop before the next removal; finish only the current slot; and measure absent and surviving paths without changing them. File hashes, physical path existence, independently executed `du -sk`, and real Git/Treehouse persistent state were checked. A plausible wrong behavior would remove the second clean slot after the stop, delete damaged data, mutate data on a report pass, or report an absent path as present.

Five live scenarios passed:
- Default inventory and refused removal requests preserve synthetic pool contents.
- Pending stop prevents both clean-pass and exact dirty-slot deletion and is consumed.
- A stop requested while the first real deletion starts allows that slot to complete, preserves the second, and returns 3.
- Host measurement reports removed, clean, damaged, and synthetic partial paths; unnamed, outside, symlinked, traversal, and mutation combinations refuse.
- An approved exact dirty path is removed while the other surviving copies remain.

The first live attempt exposed an invalid fixture origin: its bare HEAD still named master while its only branch was main. Treehouse safely refused removal. The fixture was corrected and the entire driver rerun successfully. The original transcript is retained as setup evidence.

The targeted existing regression test also passed; it uses a fake Treehouse boundary and is supplementary deterministic evidence, not the live product proof. No lint, formatter, static analysis, full suite, fleet operation, pipeline operation, push, PR, or CI phase was run. All subprocesses were awaited, and disposable directories were removed.
Evidence: Targeted regression results
ok - default pass classifies all tiers and runs nothing destructive
ok - empty status response succeeds with zero classifications
ok - empty state keeps unregistered slots inspect-only
ok - read-only measurement reports clean, damaged, partial, and fully removed paths
ok - measurement refuses unnamed, outside, symlinked, traversal, and mutating requests
ok - --apply-clean removes only the proven-clean slots, behind the config flag
ok - --apply-slot destroys only the named dirty slot, captain-approved
ok - --apply-slot refuses an unnamed or out-of-pool path
ok - risky treehouse verbs stay manual
ok - --stop writes the marker and the next apply pass stops before removing anything
ok - --apply-slot consumes a pending stop marker and removes nothing
ok - a stop marker is honored between clean slots
ok - an unreadable claim refuses the apply pass
ok - fm-treehouse-sweep guarded classification and tier gates hold

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 3 issues found → auto-fixed ✅
  • 🚨 .agents/skills/cleanup/SKILL.md:72 - Requirement 2 permits remote removal “for exact captain-named paths only,” but this new remote --apply-clean route accepts no paths and inherits wholesale approval, allowing removal of every currently clean remote slot. It also cannot honor the advertised remote stop at SKILL.md:82: fm-remote-entrypoint.sh queues --stop behind the running sweep, and fm-remote-job-worker.sh:646 executes jobs synchronously; only delta reads are preemptible. All slots can therefore finish before the marker is written, violating AC4. Remove this unrequired remote bulk route and align the remote execution summary at SKILL.md:146 and stop guidance at :81–87 with the supported exact-path boundary; retaining bulk removal needs explicit authorization.
  • 🚨 .agents/skills/cleanup/SKILL.md:89 - The prescribed remote remeasurement cannot be performed through these commands. fm-on.sh accepts only tracked fm-*.sh executables, while fm-treehouse-sweep.sh:512–521 reports classifications and a prune dry run without path sizes or existence measurements. After partial deletion, this leaves the required fully/partly/untouched report at SKILL.md:88–91 without an executable measurement route. Document a supported read-only host command instead of requiring measurement through the same tracked commands.
  • ⚠️ docs/configuration.md:272 - The claim that an absent flag makes “every sweep pass” read-only is false: --apply-slot <dirty-path> --captain-approved still destroys the named slot without this flag, because the flag gates only --apply-clean. Narrow this statement to the clean-tier pass so the configuration documentation accurately describes the removal guard.

🔧 Fix applied.
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Local synthetic pool inventory preserves files and rejects unapproved, unnamed, outside-pool, and damaged-slot removals ✅ pass live Live CLI transcript: default inventory, guard refusals, and unchanged file hashes.
A pending local stop prevents synthetic clean and dirty slots from being removed ✅ pass live Live CLI transcript: --stop followed by clean-pass and dirty-slot requests; paths preserved and marker consumed.
Stopping a running local synthetic sweep finishes the current slot and preserves the next slot ✅ pass live Live CLI transcript: real Treehouse removal completed for slot 1, sweep exited 3, and slot 2 survived.
Local host measurement distinguishes removed and surviving synthetic paths and refuses unsafe measurement requests ✅ pass live Live CLI transcript: repeated --measure output, independent du measurements, and invalid-path refusals.
An approved exact synthetic dirty path is removed while other copies survive ✅ pass live Live CLI transcript: captain-approved dirty-slot deletion and subsequent filesystem measurements.
  • TMPDIR="$PWD/.test-cleanup-tmp" bash tests/fm-treehouse-sweep.test.sh
  • python3 ~/.no-mistakes/evidence/01M7NZFAN2XXJZJ97847WKDAXF/live-cleanup.py using real Git and Treehouse v3.1.1
  • Compared synthetic file hashes, path existence, and independent du -sk measurements.
  • Awaited all subprocesses, removed disposable fixtures, and confirmed a clean working tree.
✅ **Document** - passed

✅ No issues found.

🔧 **Lint** - 1 issue found → auto-fixed ✅
  • ⚠️ linter found issues (exit code 1)

🔧 Fix applied.
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.

dnth added 4 commits November 18, 2026 08:03
- Move the local and remote pooled-copy clearing procedure into the cleanup skill; docs and the verification record now point at it.
- Document the captain-approved remote removal route through fm-on, damaged-slot inventory evidence, and the limits of tracked-file comparisons.
- Add a sweep stop marker honored between clean slots, with regression tests for unnamed, out-of-pool, and stopped removals.
@dnth
dnth merged commit a037440 into main Nov 18, 2026
21 checks passed
@dnth
dnth deleted the fm/fm-cleanup-slot-consolidation branch November 18, 2026 00:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant