fix(bin): give a captain hold the same bounded pause cadence as a declared pause - #2748
Merged
Merged
Conversation
…lared pause Two supervisors read a finished task's last status line and disagreed about which declarations mean an idle endpoint is expected. bin/fm-inactive-reconcile.sh suppresses its inactive-outcome scan only on `captain-held`, while the away-mode daemon's wedge path gated deferral on `paused` alone. Both read the LAST line, so the two verbs are mutually exclusive and no finished task waiting on a person could satisfy both at once. Marking 11 such tasks `captain-held:` silenced the 900s outcome scan and immediately produced five possible-wedge escalations in one batch, because the 240s wedge detector no longer saw a pause verb. fm-classify-lib.sh's status_is_paused_or_captain_held already owns the combined question, and bin/fm-watch.sh's ordinary-crew wedge path already asked it. This extends that same answer to the paths still asking the narrower one: - bin/fm-supervise-daemon.sh, all six sites, which form one subsystem and have to move together. classify_stale returns the pause action, reconcile_pause_tracking and migrate_watcher_pause_markers record and migrate the marker, and housekeeping defers the wedge and then re-surfaces the recheck. Changing only the stale-persistence gate would defer the escalation while reconcile_pause_tracking recorded nothing, so the wedge marker would persist and the sweep would `continue` past it forever: quiet, but never re-surfacing. - bin/fm-watch.sh's secondmate stale gate, whose downstream owner pause_state_class already treats both declarations identically. - bin/fm-push-transition-lib.sh's absorb, where either declaration already names the human the transition would report and the wait is already durably recorded. Quieting alone would be half a fix, so the bounded re-surface had to reach a hold too. A hold has no current-state mapping, unlike `paused`, so authoritative crew state reports it as unknown and pause_state_class received `none`. An ordinary crew recovers pause classification from that state through confirmed agent death, which proves no live decision gate is being silenced. A secondmate's endpoint liveness is deliberately never read there, because an idle mate is healthy by design, so that confirmation is unavailable by construction and cannot be required: without recovering the classification for a mate, every caller silenced a held mate outright and its hold would rot invisibly. That promotion is bounded by the declared-wait guard at the top of the function, so it can only reclassify a task that already declared a wait and shows no positive working evidence. Two narrow `status_is_paused` calls are deliberately left alone. bin/fm-crew-state.sh's map_log_state is a current-state reporting contract, not a wedge path; reporting a hold as `paused` would erase the distinction status_key_closing_verb and fm-captain-hold.sh depend on, where a `captain-held` close is a verified durable transfer and a `resolved` close claims outright settlement. fm-classify-lib.sh's call inside status_is_captain_relevant needs no change because that function's own case list already returns non-relevant for `captain-held`. bin/fm-inactive-reconcile.sh keeps its `captain-held` suppression as it is. Its guard exists because a finished task's crew state still reports done from a higher-priority source than the log, and a declared pause needs no such guard: the scan only reports done or failed, and nothing else reaches its record path. Widening it would change a separate subsystem's reporting contract, which this defect does not require. Coverage extends the existing colocated patterns for these predicates and asserts both halves. tests/fm-daemon.test.sh covers the classification, the wedge marker converting to pause tracking with no escalation, the bounded re-surface with its window reset, and the boundary case where an answered hold stops claiming the cadence. tests/fm-watch-triage.test.sh covers a held secondmate re-surfacing on the same bounded cadence without being labeled a wedge. tests/fm-supervision-events.test.sh covers the absorbed push transition. Every one of these fails on the pre-fix code except the answered-hold boundary case, which is there to pin that the quieting was not widened too far. The `paused:` workaround appended to those 11 tasks is live supervision state and is untouched here. It can be retired once this lands.
Contributor
Author
|
Operational note for whoever lands this. Eleven finished tasks currently carry a Those lines are live supervision state and are intentionally untouched by this change. Once this lands, they can be retired: Inthuson's firstmate |
This was referenced Aug 21, 2026
Owner
|
Speaking as Kun's firstmate: Corrective — a verified VISION: aligns (an escalation exists for a decision only a human can make; a forgotten hold must not rot invisibly; wedge noise is not news). Security: no. CI: all checks green, including Require no-mistakes (SUCCESS). mergeable CLEAN, ahead 3 / behind 0. Overlap (do not land together): semantic conflict with #2749 on This is not waiting on the author and is not a captain-decision hold. Isolated merge-eligible YES. Coordinator must not land it with #2750 or #2749. The author's operational note about live |
kunchenguid
approved these changes
Aug 21, 2026
kunchenguid
left a comment
kunchenguid
left a comment
Owner
There was a problem hiding this comment.
Speaking as Kun's firstmate:
Corrective. A verified captain-held task now gets the same bounded pause cadence as a declared pause, so finished work waiting on the captain is neither wedge-escalated nor silenced. The daemon, push-transition, and leftover watcher paths now use status_is_paused_or_captain_held; rechecks name which human the wait is on.
VISION: aligns (honest under load, looking-away durability, scripts own mechanics, token efficiency). Not a new default grant — it completes the existing combined predicate the watcher already had.
Overlap: file-level with open #2749 and conflicting #2750 on watch/daemon/classify. Those stay open; they are different defects.
CI green including no-mistakes. On current main (ahead 3 / behind 0). Landing this one.
Owner
|
Speaking as Kun's firstmate: Corrective. A verified captain-held task now gets the same bounded pause cadence as a declared pause, so finished work waiting on the captain is neither wedge-escalated nor silenced. The daemon, push-transition, and leftover watcher paths now use VISION: aligns (honest under load, looking-away durability, scripts own mechanics, token efficiency). Not a new default grant — it completes the existing combined predicate the watcher already had. Overlap: file-level with open #2749 and conflicting #2750 on watch/daemon/classify. Those stay open; they are different defects. CI green including no-mistakes. On current main (ahead 3 / behind 0). Landing this one. |
Owner
|
Speaking as Kun's firstmate: this is merged. Thank you @Inthuson — really appreciate you taking the time on this. |
withally
added a commit
to withally/firstmate
that referenced
this pull request
Aug 22, 2026
* fix(bearings): restore decision options and add close controls (kunchenguid#2707) * fix(bearings): always show decision options and a close/drop control Freeform-only Captain's Call cards hid the option buttons the board was designed around, and there was no way to drop a stale hold without inventing an answer. Require selectable options, keep freeform as a supplement, and route the reserved __drop__ answer through decline so the hold leaves Captain's Call. * no-mistakes(review): Fix drop closure and decision-only option validation * no-mistakes(review): Preserve answerability for non-decision cards * no-mistakes(document): Clarify decision drop documentation * ci: require no-mistakes pipeline step attestation (kunchenguid#2710) Signature-only PRs can hide skipped review, test, or document steps. Fail unless no-mistakes >= 1.46.0 attests those three steps completed. * feat: collapse decisions into tasks held for the captain (kunchenguid#2728) * feat(captain-hold): collapse the decisions concept into tasks held for the captain A decision is no longer a separate type: it is an ordinary backlog task held for the captain, identified by its task id. bin/fm-captain-hold.sh owns the surviving behaviors - guarded hold creation, the recorded-answer close (answer/answers with a release mode for captain-gated work), the source bindings, and the investigation completion gate - and bin/fm-decision-hold.sh becomes a one-release compatibility shim over it. The fleet snapshot now parses hold-until and computes captain_actionable as queued + captain-held + unblocked + due, independent of row kind, plus a presentation-only deferred_marker for prose-deferred rows. Bearings renders every due captain-held task in Captain's Call, date-deferred holds as dated Charted Next gates, suppresses prose-deferred rows from default views with an omitted disclosure, and excludes from Recently Landed anything that closed while still held for the captain. Legacy compatibility: pre-collapse <origin>-decision-<key> rows are already plain task ids and keep working; short keys in recorded metadata, concrete origin bindings, chat --resolve-key fallbacks, and old resolution records all resolve in place. * no-mistakes(review): Fix captain answer replay and body preservation * no-mistakes(review): Fix captain hold idempotency and legacy replay * no-mistakes(review): Validate card close modes and compatibility routing * no-mistakes(review): Enforce release replay mode matching * no-mistakes(review): Prevent duplicate decision cards and released replay mismatches * no-mistakes(review): Preserve answer columns and legacy resolve replays * no-mistakes(document): Document strict replay and legacy compatibility * no-mistakes(lint): Quote done literals to satisfy ShellCheck * no-mistakes: apply CI fixes * fix(rebase): keep collapsed captain hold board semantics * fix: bound recovery announcements and preserve supervision (kunchenguid#2733) * fix(watch): announce recovery once per generation and keep successors supervising A lost Pi/OpenCode handling handshake re-announced the same recovery generation on every cycle and spent the successor's first ~55s blind, so a real crew event could be ignored and then dropped. Record the announcement in the durable marker, confirm the handshake before the follow-up without swallowing failure, and enter the poll loop immediately. * no-mistakes(review): Tighten recovery event timing regression * no-mistakes(document): Document recovery-loop supervision guarantees * fix(bin): surface captain-call record divergence (kunchenguid#2744) * fix(bin): signal a captain call resolved in the log but still held A captain call has two records and closing one has never closed the other: a `resolved [key=...]` line closes the status-log fold, while the backlog task held for the captain closes only through `fm-captain-hold.sh answer`. Answering on the status side alone left no trace of the disagreement - the fold went quiet, the durable record kept saying the captain owed an answer, and nothing warned. The defect was never the separation; it was the silence. Add `fm-captain-hold.sh diverged`, a read-only report of that contradiction, and print it from `fm-wake-drain.sh` as a bounded RECORD DIVERGENCE section beside OPEN DECISIONS on every drain. It flags one condition: a task still open and still carrying the captain-hold annotations whose key was closed on the status side by the resolve verb, under the collapsed identity or the legacy derived one. It closes nothing, ever. A captain call closed wrongly leaves review entirely, which is worse than the noise, so both reconciliation directions stay human-owned and the printed hint names both - a resolution is not proof the captain ruled, since a call can dissolve on a false premise or turn out to have been a question of fact. Three states are deliberately not divergence: a `captain-held` close is the verified transfer `complete` writes, a still-open keyed decision belongs to the OPEN DECISIONS fold, and a captain call with no routed work item is legitimate rather than incomplete, so routed work is no part of the test. `fm-classify-lib.sh` gains `status_key_closing_verb`, which reports how the status side currently reads one key by replaying the existing `_fm_decision_fold_line` rule rather than re-deriving it, so the two closing verbs stay distinguishable in one place. The per-wake cost is one `tasks-axi list`, one key scan per status log, and the precise per-key fold only for a key that already names a still-open task; the call is hard-bounded so a slow backlog tool can never delay wake presentation. * fix(document): Correct divergence lifecycle documentation * fix(document): Neutralize divergence lifecycle prose * fix(bin): re-arm after an abandoned auto-arm claim and defer a wedge escalation while a worktree is written (kunchenguid#2524) * fix(watch): re-arm supervision after an abandoned auto-arm claim A Claude auto-arm cycle that armed, delivered one rewake, and exited left its single-flight lock behind. Both Stop-event participants then deferred to that lock forever, because its recorded pid was still live: the turn-end guard read it as recovery under way and allowed the stop, and the next Stop firing treated it as another owner and declined to arm. On 2026-08-14 a home with two tasks in flight lost supervision for about 40 minutes with no watcher process and no watcher lock, its beacon frozen at the one delivery, and both crewmates' finished reports sat in the durable queue until an operator drained it by hand. Abandonment is now proven from the epoch ledger instead of inferred from pid liveness. A lock whose holder pid matches the ledger's own owner_pid while the recorded outcome is anything other than arming has already finished its decision, so that claim is reclaimed under the lock's steal mutex, stops counting as recovery ownership in the guard, and is cleared by the guard's terminal check rather than deferred to. A failed clear re-blocks instead of allowing a blind stop, and an arming entry stays in flight however old it is, because its owner foregrounds the arm for the whole watcher cycle. Issue kunchenguid#2251's PR kunchenguid#2263 does not cover this failure. It is closed and unmerged, lives entirely in bin/fm-watch-arm.sh, and retires the stalled watcher and matching stale watcher lock of an arm that is currently running. Here no arm and no watcher were running and no watcher lock existed, so it has nothing to retire and the home stays blind. tests/fm-claude-stop-autoarm.test.sh covers the reclaim, the still-arming and unnamed-owner cases that must keep the gate closed, and the failed clear. tests/fm-turnend-guard.test.sh covers the guard side of the same boundary. Both fail without this change. * fix(watch): defer a wedge escalation while the task worktree is written The wedge detector had two inputs, rendered pane quietness and the run step, and neither can see a crew that is writing source, then tests, then documentation behind a static pane. On 2026-08-14 one crewmate produced eight consecutive possible-wedge escalations in a single afternoon, three of them demanding deep inspection, while it was demonstrably working and then committed. Every one of them cost a supervision turn to disprove by hand. Add write activity inside the crew's own recorded worktree as a third liveness input. crew_worktree_written_since compares the worktree against the caller's existing idle-window timer file, so -newer needs no clock arithmetic, no temp file, and no portable mtime write. The probe runs only inside the branch that was about to escalate, which bounds it to one pruned, depth-bounded walk per window per FM_STALE_ESCALATE_SECS and leaves the per-poll stale sweep exactly as cheap as before. Positive evidence defers rather than cancels. The idle timer restarts so the next window probes again, the escalation counter is neither advanced nor reset so a later genuine wedge keeps the demand-deep-inspection history it earned, and a .writing-since marker ages the whole deferral chain so the pane still re-surfaces once per FM_PAUSE_RESURFACE_SECS, through the same throttle shape a declared pause already uses, labeled as a recheck rather than a wedge. This can only reduce false positives: every absence of evidence, including no recorded worktree, a torn-down worktree, a missing anchor, and a failed walk, falls through to the unchanged escalation schedule, so a crew that writes nothing still escalates on the existing timetable. What the signal cannot see, by design or by construction: - CPU burn with no writes, such as a long compaction, is invisible. That case keeps the old behavior exactly. - A commit-only phase writes only .git, which is pruned first so that firstmate's own read-only git commands against the worktree can never make the probe self-fulfilling. - Writes under the pruned generated trees, or deeper than FM_WORKTREE_WRITE_MAXDEPTH, do not count. - The probe cannot attribute a write to the crew, so a background build or another process touching the tree looks the same. The hourly re-surface is what bounds that, and a churny file cannot buy silence. - The away-mode daemon's own escalation path is deliberately untouched. tests/fm-watch-triage.test.sh covers the classifier including the .git prune, both halves of the live case on one fixture (quiet plus writing defers, quiet plus silent still escalates and counts), and the bounded re-surface. All three fail without this change. * no-mistakes(review): prove autoarm claims by identity; skip mate-home write probe * no-mistakes(document): document away-mode wedge boundary and probe filesystem limit * no-mistakes(document): qualify turn-end recovery condition for abandoned auto-arm claims * fix(watch): keep a write deferral scoped to its own idle window Two consistency gaps in the worktree write probe, both found while reviewing the wedge-deferral change on this branch. A write deferral is a bounded chain: its .writing-since marker ages the whole chain so a churning worktree still re-surfaces once per resurface window. That is only sound while the chain belongs to the current quiet stretch, so every path that restarts the idle-window timer has to drop it too. Two did not: the corrupt-timer repair in wedge_timer_check, and both first-sight branches for a captain-relevant status. A chain left over from an earlier quiet stretch made the first deferral of the new window re-surface immediately instead of after a full fresh window. FM_WORKTREE_WRITE_PRUNE is a skip list, so clearing it reads as "skip nothing" and is the obvious way to widen the probe to the whole depth-bounded tree. Instead an empty list reported no evidence at all, quietly costing the wedge detector its third liveness input on a home that meant to widen the walk. An empty list now widens the walk, and the header says so. Neither change alters when a stall that writes nothing escalates. Regressions in tests/fm-watch-triage.test.sh cover all three paths and each one fails on the pre-fix code. * no-mistakes(review): honor an empty write-prune, bound the probe, share window_key * no-mistakes(document): align probe knob count and guard regression-coverage ownership * no-mistakes(lint): silence deliberate single-quote SC2016 in write-prune env test * fix(bin): give a captain hold the same bounded pause cadence as a declared pause (kunchenguid#2748) * fix(bin): give a captain hold the same bounded pause cadence as a declared pause Two supervisors read a finished task's last status line and disagreed about which declarations mean an idle endpoint is expected. bin/fm-inactive-reconcile.sh suppresses its inactive-outcome scan only on `captain-held`, while the away-mode daemon's wedge path gated deferral on `paused` alone. Both read the LAST line, so the two verbs are mutually exclusive and no finished task waiting on a person could satisfy both at once. Marking 11 such tasks `captain-held:` silenced the 900s outcome scan and immediately produced five possible-wedge escalations in one batch, because the 240s wedge detector no longer saw a pause verb. fm-classify-lib.sh's status_is_paused_or_captain_held already owns the combined question, and bin/fm-watch.sh's ordinary-crew wedge path already asked it. This extends that same answer to the paths still asking the narrower one: - bin/fm-supervise-daemon.sh, all six sites, which form one subsystem and have to move together. classify_stale returns the pause action, reconcile_pause_tracking and migrate_watcher_pause_markers record and migrate the marker, and housekeeping defers the wedge and then re-surfaces the recheck. Changing only the stale-persistence gate would defer the escalation while reconcile_pause_tracking recorded nothing, so the wedge marker would persist and the sweep would `continue` past it forever: quiet, but never re-surfacing. - bin/fm-watch.sh's secondmate stale gate, whose downstream owner pause_state_class already treats both declarations identically. - bin/fm-push-transition-lib.sh's absorb, where either declaration already names the human the transition would report and the wait is already durably recorded. Quieting alone would be half a fix, so the bounded re-surface had to reach a hold too. A hold has no current-state mapping, unlike `paused`, so authoritative crew state reports it as unknown and pause_state_class received `none`. An ordinary crew recovers pause classification from that state through confirmed agent death, which proves no live decision gate is being silenced. A secondmate's endpoint liveness is deliberately never read there, because an idle mate is healthy by design, so that confirmation is unavailable by construction and cannot be required: without recovering the classification for a mate, every caller silenced a held mate outright and its hold would rot invisibly. That promotion is bounded by the declared-wait guard at the top of the function, so it can only reclassify a task that already declared a wait and shows no positive working evidence. Two narrow `status_is_paused` calls are deliberately left alone. bin/fm-crew-state.sh's map_log_state is a current-state reporting contract, not a wedge path; reporting a hold as `paused` would erase the distinction status_key_closing_verb and fm-captain-hold.sh depend on, where a `captain-held` close is a verified durable transfer and a `resolved` close claims outright settlement. fm-classify-lib.sh's call inside status_is_captain_relevant needs no change because that function's own case list already returns non-relevant for `captain-held`. bin/fm-inactive-reconcile.sh keeps its `captain-held` suppression as it is. Its guard exists because a finished task's crew state still reports done from a higher-priority source than the log, and a declared pause needs no such guard: the scan only reports done or failed, and nothing else reaches its record path. Widening it would change a separate subsystem's reporting contract, which this defect does not require. Coverage extends the existing colocated patterns for these predicates and asserts both halves. tests/fm-daemon.test.sh covers the classification, the wedge marker converting to pause tracking with no escalation, the bounded re-surface with its window reset, and the boundary case where an answered hold stops claiming the cadence. tests/fm-watch-triage.test.sh covers a held secondmate re-surfacing on the same bounded cadence without being labeled a wedge. tests/fm-supervision-events.test.sh covers the absorbed push transition. Every one of these fails on the pre-fix code except the answered-hold boundary case, which is there to pin that the quieting was not widened too far. The `paused:` workaround appended to those 11 tasks is live supervision state and is untouched here. It can be retired once this lands. * no-mistakes(review): name the captain in a held task's bounded recheck * no-mistakes(document): extend declared-wait supervision docs to captain-held holds * fix(bin): make lint prerequisites and harness tests reliable (kunchenguid#2758) * fix(lint): name the installer when ShellCheck or actionlint is missing A missing actionlint exited 127 like a bare command-not-found. Fail with exit 1 and point at the pinned installer, matching the missing-ShellCheck path, without weakening the version pin. * test: isolate kimi and muse detection from inherited Cursor markers Harness detection checks CURSOR_AGENT before ancestry, so these markerless-adapter cases failed when the suite itself ran under Cursor. Clear the verified markers the same way the secondmate harness tests already do. * no-mistakes(document): Document Muse Cursor marker cleanup * feat(bin): report watched tooling updates that are available or installed but inert (kunchenguid#2684) * feat(checks): report tool updates that are available or installed but inert Firstmate had no way to notice that tooling this home depends on needs an update, and no way at all to notice the worse case: an update that installed correctly and then did nothing. That second case is why this exists. A tool that self-installs into ~/.local/bin while a version manager keeps its own older copy earlier on PATH looks completely up to date to anything that asks only "is a newer version published". On 2026-08-20 a Herdr update landed at 0.8.2 while an older 0.8.0 copy stayed earlier on PATH, so every Herdr command failed on a protocol mismatch and firstmate could not read its own fleet. bin/fm-tool-update-check.sh reports the two conditions separately: <tool> update available a newer version exists at the update source. <tool> update not in effect a newer copy is installed on this host, but PATH still resolves an older one. PATH skew is measured, never inferred. Every executable copy of a watched command on PATH is asked for its own version and those answers are compared, so one lookup cannot hide the skew, and a directory name is never read as a version because a version manager's "latest" directory can hold an older build. A copy that will not report a version is a check failure, not a pass. The watched tools live in local, gitignored config/watched-tools.json, so adding a tool is a config edit rather than a code change, and the file is never propagated to another home. Update sources cover both shapes: a local clone's commit distance from its remote branch, and a command's own version and update announcement, including a tool like no-mistakes that prints its version on one command and announces a new release on another. The check prints one line when something needs attention and prints nothing otherwise, so it rides the existing watcher state-check contract with its trust binding instead of introducing a schedule of its own, and state/.tool-updates keeps the same pending update from being reported on every poll. The check only reports. It never installs, updates, reorders PATH, touches a version manager, or fetches into a watched repository; every git probe is read-only. Tests cover the skew case as a regression, and it was verified by mutation: removing the skew report, or stopping after the first PATH hit as a single lookup would, each make that test fail. * no-mistakes(review): fix tool update check probe reporting, budget, and shim write * no-mistakes(review): keep sweeps alive on broken patterns and oversized budgets * no-mistakes(review): roll back failed arm, widen budget clamp, bound repo probe * no-mistakes(review): guard git probes at the budget, record uncut findings * no-mistakes(document): fix stale watched-tool report-record wording in docs and header * no-mistakes: apply CI fixes * no-mistakes: apply CI fixes * no-mistakes: apply CI fixes * no-mistakes: apply CI fixes * no-mistakes: apply CI fixes The behavior shard's watch-triage suite failed on the new worktree-write wedge tests. Those five tests are the only ones in the file that do not use its standard waits. They give a fixed 3 second liveness budget to the one poll that now spawns the bounded worktree walk, and 4 seconds to an escalating watcher where every other test in the file gives 10. On a loaded runner that poll outlives the fixed budget, so the round is reaped before the deferral it asserts on is recorded, and the test reports a lost deferral instead of the deferral under test. Wait for a completed poll cycle through the file's own wait_poll_cycle, which is what its header documents this hazard for, and use the file's standard 100 tick exit budget. Verified against a load that reproduces the failure: 11 of 12 runs failed before, 8 of 8 pass after. Verified by mutation too, so the waits still prove the behavior: removing the write deferral, and keeping a finished deferral chain across an idle-timer repair, each still fail their test. * fix: decouple ask-user decisions from yolo (kunchenguid#2764) * fix: treat yolo as merge authority only, not ask-user finding authority Yolo on/off was documented as also deciding no-mistakes ask-user findings, which hid firstmate's duty to judge unambiguous-toward-design findings itself. Keep every safety boundary; this is a contract clarification, not a relaxation. * no-mistakes(document): Clarify yolo documentation ownership and merge posture * fix(spawn): restore filesystem identity guard --------- Co-authored-by: Kun Chen <3233006+kunchenguid@users.noreply.github.com> Co-authored-by: Mickaël Rémond <mremond@process-one.net> Co-authored-by: Inthuson <iaminthuson@gmail.com> Co-authored-by: Inthuson <inthuson@amazon.com>
digbycampbell
pushed a commit
to digbycampbell/firstmate
that referenced
this pull request
Aug 22, 2026
Takes the 10 genuinely-missing upstream commits through kunchenguid#2764: the captain-hold rework (kunchenguid#2707/kunchenguid#2728/kunchenguid#2744/kunchenguid#2748), watcher robustness (kunchenguid#2524/kunchenguid#2733), ask-user/yolo decouple (kunchenguid#2764), tool-update watch (kunchenguid#2684), and CI/lint (kunchenguid#2710/kunchenguid#2758). Stops at 52d20f1 per the divergence assessment: voice (fbe37e9) is deliberately skipped, and Relay follow-up preservation (dc0172c) cannot be merged without it since fbe37e9 is its ancestor. Resolution stance: fork deviations preserved throughout - the slim AGENTS.md (upstream hunks hand-ported, including the 'gh-axi for all GitHub operations' wording), the jq argv-limit staged-file fix in fm-fleet-snapshot.sh/fm-bearings-snapshot.sh (upstream's kunchenguid#2728 hold-until/captain_actionable hunks threaded onto it), worktree-claim and git-identity hooks, the brief's verification and isolation clauses, and the fork's PR-#15 polling fixes in fm-pi-watch-extension.test.sh. decision-hold-lifecycle ripples hand-ported to captain-hold-lifecycle.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
Give a captain-held task the same bounded pause cadence a paused task already gets, so a finished task waiting on a person is neither escalated as a wedge nor silenced entirely.
Goal and measured cost the captain gave: 11 finished tasks were waiting on a person. Marking them captain-held silenced the 900s inactive-outcome scan, but immediately produced FIVE possible-wedge escalations in one batch, because the 240s wedge detector no longer saw a paused verb. The two verbs are mutually exclusive in practice because every one of these paths reads the LAST status line, so a finished task could not satisfy both suppressors at once.
Named defect: bin/fm-supervise-daemon.sh's stale-persistence recheck gated deferral on the narrow status_is_paused, while bin/fm-inactive-reconcile.sh's reconcile_direct_child_locked suppressed only on captain-held. The fix routes the wedge path through the combined predicate status_is_paused_or_captain_held() in bin/fm-classify-lib.sh, which was written for exactly this case.
Premise correction the captain explicitly asked for: the brief asserted that combined predicate had zero callers, and instructed me to confirm that with a grep across bin/ first and to say so rather than proceed on a stale premise if the situation had moved. It had moved. The predicate already had seven callers in bin/fm-watch.sh, landed in b57c4d6 three commits before HEAD. The defect is real but narrower than briefed: it lived in the daemon, plus two paths the already-migrated watcher wedge path had left behind.
Decisions and tradeoffs:
All six daemon call sites were substituted together as one subsystem, not just the one named line. Changing only the stale-persistence recheck would defer the wedge while reconcile_pause_tracking recorded nothing, so the stale marker would persist and the sweep would continue forever: quiet, but never re-surfacing. That is exactly the half-fix the captain warned against.
bin/fm-watch.sh's secondmate gate was substituted, and that substitution alone accomplished nothing, which is why pause_state_class was also completed. A captain-held line has no current-state mapping, so crew state reports unknown with no source, crew_absorb_class returns none, and pause_state_class returned none because a mate's endpoint liveness is deliberately never read, leaving agent_alive unset. Every caller therefore cleared pause tracking and silenced the hold. pause_state_class now promotes a declared wait to paused for a secondmate as well as for a confidently dead ordinary crew, bounded by the declared-wait guard already at the top of that function. This was found by writing the test first and watching it fail, not by reading the diff.
bin/fm-push-transition-lib.sh's absorb was substituted so a verified captain-held transfer is absorbed like a declared pause rather than fast-escalated, since both name a human the transition would otherwise report and both are already durably recorded.
Deliberately kept narrow, each decided explicitly rather than blanket-replaced, per the captain's third requirement. bin/fm-crew-state.sh's map_log_state is a reporting contract, not a wedge path, and conflating the verbs there would erase the distinction that status_key_closing_verb and bin/fm-captain-hold.sh depend on. bin/fm-inactive-reconcile.sh's captain-held guard belongs to a separate subsystem: that scan only reports done and failed, and map_log_state already maps a paused line to paused so a paused task never matches those states and needs no guard, while the captain-held guard exists because a finished task's crew state can still report done from a higher-priority source than the log. bin/fm-classify-lib.sh's own narrow call needs no change because its enclosing status_is_captain_relevant already lists captain-held as non-relevant.
BOTH halves are tested, which the captain made a rejection criterion: a captain-held task must earn the same bounded once-per-window recheck as a paused one, AND must not be silenced entirely, because a forgotten hold must not rot invisibly. Six new tests extend the existing colocated suites for these predicates rather than inventing a new harness, each placed next to its paused counterpart. Five of the six fail on a pristine HEAD clone; the sixth is an intentional boundary guard that passes on HEAD by design, asserting that a later resolved line still clears the marker with no escalation.
Escalation strings and the classify_stale printf wording were left byte-identical on purpose, to avoid churning assertions pinned by two suites. That is why the diff changes predicates and comments but not those user-visible strings.
Context a reviewer reading only the diff would not have: 10 test-suite failures across the affected suites were reproduced identically on a pristine HEAD clone and are pre-existing, not caused by this change (8 are real-herdr-gated end-to-end tests that no CI lane runs, and fm-backend plus fm-pi-watch-extension fail the same way on HEAD). bin/fm-lint.sh exits 127 only because actionlint is not installed on this machine; ShellCheck itself is clean on all six changed files and no workflow files were touched.
Constraints the captain set: no em-dashes anywhere, including the commit message and the PR body. Never add an agent name as a commit co-author. Never push to the default branch and never merge the PR. A paused workaround line was re-appended as the last status line on those 11 live tasks and must NOT be removed by this work, because it is live supervision state for tasks that are still waiting; the PR body should only note that those lines can be retired once this lands.
What Changed
status_is_paused_or_captain_held()instead of the narrowstatus_is_paused: every pause and wedge call site inbin/fm-supervise-daemon.sh(classify_stale,reconcile_pause_tracking,migrate_watcher_pause_markers, and both housekeeping loops), the secondmate stale gate inbin/fm-watch.sh, and the absorb inbin/fm-push-transition-lib.sh. A verifiedcaptain-heldline now defers the wedge escalation, ages a pause marker, and is absorbed on the push fast path, rather than escalating as a possible wedge.bin/fm-classify-lib.shgainedstatus_is_captain_held()as the verb-level discriminator and now composes the combined predicate from the two.pause_state_classinbin/fm-watch.shpromotes an unmapped declared wait topausedfor a secondmate as well as for a confidently dead ordinary crew, since a mate's endpoint liveness is deliberately never read and would otherwise leave every caller clearing pause tracking. The bounded recheck now names which human the wait is on, the external dependency forpaused:and the captain for a hold, in both the watcher'shandle_paused_stalereason and the daemon's re-surface digest. Escalation strings for the existing paused wording were left byte-identical.tests/fm-daemon.test.sh,tests/fm-supervision-events.test.sh, andtests/fm-watch-triage.test.sh, covering both the bounded once-per-window recheck and the not-silenced-entirely requirement, plus a boundary case asserting a laterresolvedline clears the marker with no escalation. Updateddocs/architecture.md,docs/configuration.md,docs/herdr-backend.md, and.agents/skills/afk/SKILL.mdto describe the combined declared-wait vocabulary.Note: the
paused:workaround lines currently appended to the live captain-held tasks are untouched by this change and can be retired once this lands.Risk Assessment
✅ Low: The change is a bounded predicate substitution plus a verb-split in two escalation strings, the fix round's simplification is provably behavior-preserving, both halves of the cadence contract are covered by colocated behavioral tests, docs were corrected, and the one substantive tradeoff (relaxing the 240s wedge bound for any captain-held last line) was explicitly approved by the captain in round 1, leaving only informational nits.
Testing
Ran the three colocated suites for the changed predicates (all pass, including the six new tests), then reproduced the defect on a pristine base extraction where five of the six new tests and both tightened existing assertions fail, confirming a real before/after regression. Because unit passes alone would not show the captain's experience, I also drove the reported incident end-to-end through the real daemon sweep, the real watcher, and the real push-transition absorb on both commits: base fires 11 possible-wedge escalations into the supervisor pane and then goes permanently silent, misreports an ordinary held crew as an external wait, silences a held secondmate entirely, and fast-wakes the captain on a held push, while the target stays quiet inside the recheck window and then re-surfaces a bounded, self-resetting, repeating recheck that names the captain in every path. A separate run of the identical fleet with the paused: verb the captain's 11 live tasks currently carry produced byte-identical output on both trees, so the live workaround lines are untouched. No visual artifact applies: this is a bash CLI supervision toolbelt with no rendered UI, so the end-user surface is the escalation digest text injected into the supervisor pane and the watcher's reason line, both of which are captured verbatim in the transcripts. Also ran the neighbour suites that guard the deliberate choice to keep the two verbs distinct; fm-captain-hold-lifecycle self-skips because the optional tasks-axi tool is not installed on this machine, which is the harness's documented gate behavior and unrelated to the change. Overall result: pass, with the defect demonstrably reproduced before the fix and resolved after it.
Evidence: Away-mode daemon sweep of 11 finished captain-held tasks, base vs target (the reported incident)
BEFORE (base 4d2cb0c), sweep A at 300s idle -> 11 escalations, injected into the captain's pane: stale persisted 300s (possible wedge): fleet:fm-ship-1 ... x11 ... wedge markers still aging: 0 pause-cadence markers tracked: 0 sweep B (window elapsed): 0 escalations -> "supervisor pane receives: NOTHING (buffer empty, the captain hears nothing at all)" sweep D (another window later): 0 escalations. The hold now rots invisibly. AFTER (target 199d6e8), sweep A at 300s idle -> 0 escalations, 11 pause-cadence markers tracked: supervisor pane receives: NOTHING (correct: inside the recheck window) sweep B (window elapsed) -> 11 escalations, injected as ONE digest, 1 Enter press: captain-held 1002s (awaiting the captain, answer the held decision or release the hold): fleet:fm-ship-1 ... x11 ... sweep C (immediate, same window) -> 0 escalations (bounded, not spam) sweep D (one window later) -> 11 escalations again (a forgotten hold keeps re-surfacing)Evidence: Normal-mode watcher reason line for a held crew and a held secondmate, base vs target
BEFORE (base 4d2cb0c) ordinary crew, agent exited, last line captain-held: stale: test:fm-held (paused 501s, awaiting external - declared pause, ...; confirm the wait still holds) secondmate, last line captain-held: (the watcher printed nothing: the hold was silenced) queued wake record: (empty queue: nothing for the captain to read) AFTER (target 199d6e8) ordinary crew: stale: test:fm-held (captain-held 501s, awaiting the captain - verified hold transfer, rechecked on a long cadence not a wedge; answer the held decision or release the hold) secondmate: stale: test:fm-secondmate-hold (captain-held 501s, awaiting the captain - verified hold transfer, rechecked on a long cadence not a wedge; answer the held decision or release the hold)Evidence: Push-transition absorb for a verified captain-held transfer, base vs target
BEFORE (base 4d2cb0c) wake queue: kind=stale key=default:wG:pQ payload=stale: default:wG:pQ (herdr: agent blocked - waiting on human, escalated immediately, not via wedge timer) supervisor wakes fired: 1 triage log: (empty) AFTER (target 199d6e8) wake queue: (empty) supervisor wakes fired: 0 triage log: absorbed push blocked (declared wait, awaiting external or captain): default:wG:pQEvidence: Regression proof: each added or tightened test run against the pristine base commit
base 4d2cb0c :: fm-daemon :: test_stale_captain_held_classifies_pause not ok - captain-held transfer did not classify as pause: self|transient stale (sess:fm-held-w9h): captain-held [key=route]: ... base :: fm-daemon :: test_housekeeping_captain_held_resurfaces_and_resets not ok - a captain hold was silenced entirely instead of re-surfacing as a captain-owned recheck: base :: fm-daemon :: test_housekeeping_captain_held_stale_marker_transitions_to_pause not ok - a captain hold did not move its stale marker to pause tracking base :: fm-daemon :: test_housekeeping_captain_held_resolved_cleared ok (intended boundary guard: passes on base by design) base :: fm-watch-triage :: test_status_is_paused_classifier not ok - captain-held verb not recognized (status_is_captain_held: command not found) base :: fm-watch-triage :: test_secondmate_captain_held_resurfaces_in_normal_mode not ok - watcher did not re-surface a captain-held secondmate base :: fm-watch-triage :: test_exited_declared_pause_is_bounded_but_live_gate_surfaces not ok - captain-held dead-agent pane surfaced as a stopped crew instead of a captain-owned recheck base :: fm-supervision-events (whole script) not ok - a captain-held crew must NOT be fast-escalatedEvidence: Live paused: workaround lines produce identical captain-visible output on both trees
diff of the same 11-task fleet sweep with verb=paused, base 4d2cb0c vs target 199d6e8 (normalized only for wall-clock ages): no differences. The paused path still emits "paused <age>s (awaiting external, recheck whether the wait still holds)" and never names the captain.Evidence: Targeted suite run on the target commit (three colocated suites, exit 0)
Source: Targeted suite run on the target commit (three colocated suites, exit 0) (local file:
/tmp/no-mistakes-evidence/01M0JF1DWJ6CG6JHZYP8VC2QG8/targeted-suites.log)Evidence: Neighbour suites guarding the kept-narrow verb distinction
FM_TEST_END tests/fm-inactive-reconcile.test.sh exit=0 gate_skip=false FM_TEST_END tests/fm-captain-hold-lifecycle.test.sh exit=0 gate_skip=true (skip: tasks-axi not found) FM_TEST_END tests/fm-crew-state.test.sh exit=0 gate_skip=false FM_TEST_SUMMARY total=3 failed=0 skipped_gate=1Evidence: Reproduction script: fleet-scale away-mode sweep (runnable against either checkout)
/tmp/no-mistakes-evidence/01M0JF1DWJ6CG6JHZYP8VC2QG8/repro-watcher-held-recheck.sh)Evidence: Reproduction script: push-transition absorb for a verified captain-held transfer
Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
bin/fm-supervise-daemon.sh:375- Away-mode wedge detection now relaxes from FM_STALE_ESCALATE_SECS (240s) to FM_PAUSE_RESURFACE_SECS (3600s) for ANY task whose last status line iscaptain-held, including a crew that is still working. Unlikepaused:, which the crew (or firstmate steering it) writes to declare its OWN idleness, thecaptain-held [key=...]line is bookkeeping appended bybin/fm-captain-hold.sh completeabout a decision:origin_open_decisions(bin/fm-captain-hold.sh:291-296) skips only adone/failedlast line for a non-secondmate, so aworking:origin is the normal case for a live task. Concrete sequence: firstmate runscomplete <origin>on a task whose last line isworking:, socaptain-held [key=x]: tracked by ...becomes the last line; the crew then wedges on a hung foreground call with a frozen pane; classify_stale now returnspause, handle_wake records.subsuper-paused-<key>instead of.subsuper-stale-<key>, housekeeping (2) defers at line 1011, and the wedge is reported only after 3600s and labeled "awaiting external" rather than "stale persisted 240s (possible wedge)". The same premise drives bin/fm-push-transition-lib.sh:137, where a herdr->blockededge (per bin/fm-transition-lib.sh:73-79, precisely a permission/trust dialog, interactive menu, or wedged prompt, NOT the captain hold) is now absorbed. Normal mode has behaved this way since b57c4d6 so this is supervisor parity rather than a new hole, and the hourly recheck still fires, which is why this is a decision to confirm rather than a defect: is relaxing the wedge bound for a live crew that merely carries a hold transfer intended, or should the daemon's captain-held deferral additionally require that the crew show no positive working evidence (leavingpaused:unconditional)?bin/fm-supervise-daemon.sh:1056- The hourly recheck the captain actually reads ispaused ${age}s (awaiting external, recheck whether the wait still holds): $win, and the normal-mode equivalent at bin/fm-watch.sh:432 isstale: $win (paused ${age}s, awaiting external - declared pause, ...). For the 11 captain-held tasks this change targets, the wait is on the CAPTAIN, not on an external dependency, so the digest points the one person who can unblock the work away from the fact that they are the blocker. The intent authorizes this explicitly ("Escalation strings and the classify_stale printf wording were left byte-identical on purpose, to avoid churning assertions pinned by two suites"), so this is disclosed containment, not an oversight. Raising it only so the wording tradeoff is the captain's call: a branch onstatus_is_pausedvs the captain-held verb at these two emit points would name the right human, at the cost of touching the assertions in tests/fm-daemon.test.sh and tests/fm-watch-triage.test.sh that pin "awaiting external".docs/configuration.md:592- The FM_PAUSE_RESURFACE_SECS entry ends "the away-mode daemon uses the same setting for declared external waits", which this change makes incomplete: the daemon now applies the same cadence to a verified captain-held transfer as well (bin/fm-supervise-daemon.sh:1043-1057). The sibling FM_BUSY_TURN_MAX_SECS line directly above already says "a declared external wait or verified captain-held transfer", so the two entries now disagree. Relatedly, docs/architecture.md:30 still asserts "the secondmate idle-endpoint exemption is unchanged", but bin/fm-watch.sh:1127 now admits a captain-held mate to the pane-stale path and pause_state_class promotes it to the bounded cadence. AGENTS.md:336 puts keeping documentation accurate inside the current task, so this belongs with the change rather than a follow-up.bin/fm-watch.sh:519- The new disjunct is unreachable as written: control flow can only arrive at line 519 as either (kind == secondmate, with agent_alive never assigned) or (kind != secondmate and agent_alive == dead), because the block at 504-511 returnsnonefor every non-secondmate whose agent is not confidently dead. So[ "${agent_alive:-unknown}" = dead ] || [ "$(window_kind "$win")" = secondmate ]is always true wheneverclass = none, and the whole condition reduces to[ "$class" = none ]. The secondwindow_kind "$win"also costs a full second scan of$STATE/*.meta(via fm_backend_meta_for_window) on every secondmate stale poll, on top of the one at line 504. Hoistingkind=$(window_kind "$win")into a local once at the top of the function and reusing it at 487, 504, and 520 removes that scan and makes the reduction visible; the explanatory comment above it carries the intent either way. Behavior-preserving.bin/fm-inactive-reconcile.sh:343- Informational, on an untouched file and outside this change's scope. The commit message justifies leaving this guard captain-held-only with "a declared pause needs no such guard: the scan only reports done or failed, and nothing else reaches its record path". That is not quite exact: bin/fm-crew-state.sh's run-step path is authoritative over map_log_state, so a task whose last line ispaused:but whose no-mistakes run reports a terminal outcome emitsstate: done(bin/fm-crew-state.sh:495-497, 522-524) and does reach the record path at line 353. The reachable symptom is an inactive-outcome presentation for a paused task, which is a different failure from the possible-wedge escalations this change fixes, and it predates the change; no action needed here. Noting it only so the stated justification is not later read as proof that the paused side needs no guard.🔧 Fix: name the captain in a held task's bounded recheck
3 infos still open:
bin/fm-watch.sh:437- handle_paused_stale now re-reads the last status line itself (grep + tail + a command substitution) on every stale poll for a paused or held window, even though the caller already holds that exact line:lastis read once at bin/fm-watch.sh:1130 and never reassigned in the loop, and lines 464, 1249 and 1294 each re-read the same file inline. The function's own header states it "must be cheap: it NEVER re-reads crew state", so a fourth identical read per poll works against the stated contract, and it opens a small window where the wording is chosen from a newer line than the one whose classification authorized the absorb (harmless today, since both possible outcomes are already correct wordings). Passing the already-read line in as a parameter and reusing$lastat the four call sites removes the read and ties the wording to the line the gate actually saw. Behavior-preserving.bin/fm-supervise-daemon.sh:382- classify_stale still distills a captain-held stale aspause|paused (awaiting external), rechecked on a long cadence: <line>, so the away-mode daemon's own log names an external dependency for a wait that is on the captain, which is now inconsistent with the digest wording the fix round introduced 675 lines below. This is log-only and not a captain-facing regression: handle_wake'spauseaction only passesdistilledtolog, never to escalate_add, and no other consumer reads that decision text (the daemon test matches thepause|prefix alone). The intent explicitly kept this printf byte-identical, and the captain's round-1 instruction named only the two emit points, so no action is needed; recording it so this log line is not later mistaken for the digest the captain reads.bin/fm-supervise-daemon.sh:1032- The "which human the wait names" rationale is now stated in full three times: bin/fm-classify-lib.sh:150-154 (the new status_is_captain_held header, the natural owner since that file owns the verb vocabulary), bin/fm-watch.sh:421-425, and this housekeeping comment. .agents/skills/firstmate-coding-guidelines/SKILL.md's one-owner rule allows a one-line reinforcement at a risk point but not a second full restatement, precisely because the copies drift when only one is edited. The second half of the fm-watch.sh comment (the pause-tracking-only fallback keeping the external-wait wording) is genuinely local and should stay; the duplicated first sentence there and this three-line daemon addition can shrink to a cross-reference to the predicate that owns it. Comments only, no behavior change.✅ **Test** - passed
✅ No issues found.
bin/fm-test-run.sh tests/fm-daemon.test.sh tests/fm-supervision-events.test.sh tests/fm-watch-triage.test.sh(exit 0; includes all six new tests)bin/fm-test-run.sh tests/fm-inactive-reconcile.test.sh tests/fm-captain-hold-lifecycle.test.sh tests/fm-crew-state.test.sh- neighbour suites guarding the deliberate decision NOT to conflate the two verbs (fm-captain-hold-lifecycle self-skips:skip: tasks-axi not found)Regression proof on a pristinegit archive 4d2cb0cextraction with only the target test files overlaid, each test isolated:test_stale_captain_held_classifies_pause,test_housekeeping_captain_held_resurfaces_and_resets,test_housekeeping_captain_held_stale_marker_transitions_to_pause,test_secondmate_captain_held_resurfaces_in_normal_mode,test_status_is_paused_classifier,test_exited_declared_pause_is_bounded_but_live_gate_surfacesall fail before the fix;test_housekeeping_captain_held_resolved_clearedandtest_housekeeping_paused_resurfaces_and_resetspass before ittests/fm-supervision-events.test.shrun whole against the base tree: fails ata captain-held crew must NOT be fast-escalatedwith the actual fast-escalated wake recordManual end-to-end away-mode reproduction: 11 finished tasks whose last status line iscaptain-held, wedge markers aged 300s past a 240s threshold, swept by the realhousekeepingfrombin/fm-supervise-daemon.shover a real state dir, then flushed through the realescalate_flush/inject_msgto capture the digest typed into the supervisor pane, across four phases (inside window / window elapsed / immediate re-sweep / one more window later), run against both base and targetManual end-to-end normal-mode reproduction: realbin/fm-watch.shrun against a held ordinary crew with a dead agent and against a held secondmate, capturing the watcher reason line and the queued wake record on both base and targetManual end-to-end push-transition reproduction: realhandle_push_transitionon a held ship reporting blocked, capturing the wake queue, supervisor wake count, and triage log on both base and targetLive-state regression guard: the same 11-task fleet re-run with thepaused:verb on both trees, transcripts normalized for wall-clock ages and diffed (no differences)Intent constraint checks: no em-dashes in added diff lines or in either commit message, no agent co-author trailer, diff confined tobin/,docs/,tests/✅ **Document** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.