Skip to content

fix: wait for Treehouse pool slot handoff before spawning - #5495

Open
slee029 wants to merge 6 commits into
kunchenguid:mainfrom
slee029:fm/treehouse-slot-not-clean-race
Open

slee029 wants to merge 6 commits into
kunchenguid:mainfrom
slee029:fm/treehouse-slot-not-clean-race

Conversation

@slee029

@slee029 slee029 commented Sep 24, 2026 •

Copy link
Copy Markdown

Intent

Rebase of upstream PR #5495 onto current upstream main (30ef650) with its intent unchanged; the only conflicts were in docs/configuration.md, where upstream had restructured the Runtime backend section into subsections, so the PR three Treehouse handoff sentences were placed right after the Treehouse worktree-provider sentence. Original intent: fm-spawn refused a pooled Treehouse slot as "not clean" that read clean seconds later, because it checked cleanliness while Treehouse was still handing the slot off (checkout still being written). The fix waits, for Treehouse pool slots only, until Treehouse records a live owner and no lease before checking cleanliness, allowing up to 600 seconds of checkout settling beyond the ordinary 60-second pane wait; if handoff never completes spawn refuses without claiming the slot or publishing task metadata; a genuinely dirty pooled slot is still left untouched; inspecting pool ownership requires jq even on tmux and spawn refuses promptly when it is missing. Do not hand-create worktrees. No new behavior beyond the original PR; do not expand scope.

What Changed

  • Wait for a Treehouse pool slot to have a live owner and no lease before checking cleanliness, with up to 600 seconds of checkout settling beyond the ordinary pane wait.
  • Refuse an unfinished handoff without claiming the slot or publishing task metadata; require jq to inspect pool ownership, including on tmux.
  • Add regression coverage for slow and stalled checkouts, leased slots, and missing jq, and document the handoff behavior.

Risk Assessment

✅ Low: The change is limited to Treehouse pool-slot handoff detection and its wait allowance, with no substantiated material issue found.

Testing

The focused settle test passed its checkout, lease, never-completes, and missing-jq cases. Initial pool-base cases passed before that command timed out. No live Herdr/Treehouse lab was run, and no reviewer-visible artifacts were captured; the result remains inconclusive.

  • Live validation: ⚠️ inconclusive - 0 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Spawn waits for a pooled slot checkout to finish, then launches without a false dirty-work refusal ⏸️ untested no A live Herdr/Treehouse lab was not provisioned; drive this through bin/fm-herdr-lab.sh to obtain product-level evidence.
Spawn does not adopt a leased slot with a live owner before handoff ⏸️ untested no A live Herdr/Treehouse lab was not provisioned; drive this through bin/fm-herdr-lab.sh.
Spawn refuses an unfinished slot without claiming it or publishing task metadata ⏸️ untested no A live Herdr/Treehouse lab was not provisioned; drive this through bin/fm-herdr-lab.sh.
Spawn without jq promptly refuses a pooled slot without claiming it or publishing task metadata ⏸️ untested no A live isolated spawn with jq absent from its PATH was not run; provide a lab session configured for that condition.
Spawn leaves genuinely dirty pooled work untouched ⏸️ untested no The targeted command exceeded 180 seconds, and no live dirty-slot lab was run; provide time for a focused isolated Herdr/Treehouse run.
  • Outcome: ⚠️ 1 warning across 1 run (3m36s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

⚠️ **Test** - 1 warning
  • ⚠️ live validation verdict: inconclusive (0 of 5 scenarios were driven live against the product); untested: Spawn waits for a pooled slot checkout to finish, then launches without a false dirty-work refusal, Spawn does not adopt a leased slot with a live owner before handoff, Spawn refuses an unfinished slot without claiming it or publishing task metadata, Spawn without jq promptly refuses a pooled slot without claiming it or publishing task metadata, Spawn leaves genuinely dirty pooled work untouched
  • Live validation: ⚠️ inconclusive - 0 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Spawn waits for a pooled slot checkout to finish, then launches without a false dirty-work refusal ⏸️ untested no A live Herdr/Treehouse lab was not provisioned; drive this through bin/fm-herdr-lab.sh to obtain product-level evidence.
Spawn does not adopt a leased slot with a live owner before handoff ⏸️ untested no A live Herdr/Treehouse lab was not provisioned; drive this through bin/fm-herdr-lab.sh.
Spawn refuses an unfinished slot without claiming it or publishing task metadata ⏸️ untested no A live Herdr/Treehouse lab was not provisioned; drive this through bin/fm-herdr-lab.sh.
Spawn without jq promptly refuses a pooled slot without claiming it or publishing task metadata ⏸️ untested no A live isolated spawn with jq absent from its PATH was not run; provide a lab session configured for that condition.
Spawn leaves genuinely dirty pooled work untouched ⏸️ untested no The targeted command exceeded 180 seconds, and no live dirty-slot lab was run; provide time for a focused isolated Herdr/Treehouse run.
  • bash tests/fm-spawn-worktree-settle.test.sh
  • bash tests/fm-spawn-pool-base-freshen.test.sh (stopped by the 180-second timeout after its initial cases)
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

@slee029

slee029 commented Sep 24, 2026

Copy link
Copy Markdown
Author

The CI and Require no-mistakes workflow runs for this fork PR are waiting on maintainer approval (action_required). Could a maintainer please approve them? Thanks.

@slee029 slee029 changed the title fix: wait for Treehouse slots to finish checkout before spawning fix: wait for Treehouse pool slot handoff before checking cleanliness Sep 24, 2026
@kunchenguid

Copy link
Copy Markdown
Owner

Speaking as Kun's firstmate: stamped waiting-ci.

HEAD 2fff9576cbeec79916e6e822abb2760ed7c489a1. Attestation MATCH (body binds tip; all NM steps completed). CI 35986922187 and Require no-mistakes 35987439669 (plus sibling action_required runs on same head) approved this pass after author ask at 06:47Z. MERGEABLE/UNSTABLE. No Closes/Fixes refs. Fork workflows approved after safe diff review (workflow-zero vs main tip 9284978fe931; files: fm-spawn.sh, fm-wake-lib.sh, configuration.md, settle + pool-freshen tests).

contract-class: restore — unconfigured path inspected tip vs main. Main already waits for an isolated Treehouse worktree then refuses dirty pooled slots rather than discarding uncommitted work. Tip only: before cleanliness, wait until Treehouse records a live unleased owner for that pool slot (fm_treehouse_slot_acquired), with a separate ≤600s settle allowance inside the existing pane-wait loop; refuse unfinished handoff without claiming the slot or publishing task metadata; require jq (already a Firstmate dependency) and refuse by name if missing. Review narrowed the wait to Treehouse pool slots only (broader linked-worktree initializing path removed). Restores the concrete spawn cleanliness path that mid-checkout false-dirty broke; 600s is not a new always-on observer/wake/Bearings surface (FM-LEARN-4627) — it extends the existing settle wait for that broken case.

VISION per-rule:

  • One captain / one interface: aligns — fewer false spawn refuses; no new captain surface.
  • Authority explicit: aligns — still refuses genuine dirt; never discards; unfinished handoff leaves slot unclaimed.
  • Scripts own mechanics: aligns — deterministic pool-state poll via jq.
  • Restart is a non-event: aligns — refusal publishes no meta / no slot claim, so nothing stranded.
  • Delegation with a spine: aligns — pooled ship/scout spawns can finish acquisition honestly.
  • Fleet outlives any vendor: aligns — binds to Treehouse pool-state semantics already used elsewhere; jq already required in the fleet.
  • Scope: aligns — spawn settle mechanics + docs/tests only.

Waiting on CI/NM green, not author or captain. When green: auto-merge candidate (restore + MATCH + safe). Firstmate-flag no this pass (not otherwise ready while CI pending). Security tip: none. Author workflow-approval ask addressed.

@slee029

slee029 commented Sep 24, 2026

Copy link
Copy Markdown
Author

New workflow runs for the updated head are waiting on maintainer approval (action_required). Could a maintainer please approve them? Thanks.

slee029 added 6 commits September 27, 2026 04:11
…re adopting it

fm-spawn adopted the pane's first isolated read after treehouse get, but
git worktree add creates the slot's .git link first and runs its checkout
inside the slot, so a pane reporting its foreground cwd reads the new slot
while git status still lists every file not yet written. The spawn then
refused the slot as not clean, and a checkout slower than the 60s wait was
abandoned mid-write, leaving a partial slot folder behind.

A candidate whose checkout is in progress (git's initializing worktree
lock, or a pool slot Treehouse's state does not yet list with a live owner)
is now treated as a transient, waited out on a separate 600s allowance.
@slee029
slee029 force-pushed the fm/treehouse-slot-not-clean-race branch from 2fff957 to 4d42004 Compare September 27, 2026 04:17
@slee029 slee029 changed the title fix: wait for Treehouse pool slot handoff before checking cleanliness fix: wait for Treehouse pool slot handoff before spawning Sep 27, 2026
@slee029

slee029 commented Sep 27, 2026

Copy link
Copy Markdown
Author

Rebased onto current main (30ef650) and re-validated through no-mistakes; the attestation now matches head 4d42004. The CI and Require no-mistakes runs are waiting at action_required - could a maintainer please approve them? Thanks.

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.

2 participants