fix(bin): coalesce watcher signals into one wake

[kunchenguid]

Intent

The firstmate watcher (bin/fm-watch.sh) produced duplicate wakes: a crewmate's final status-file write and the same turn's turn-end hook land seconds apart (observed 15s), and since the watcher exits on the first changed signal file and is restarted between wakes, one logical event (crewmate finished its turn) cost two full firstmate turns. The user asked to patch this duplicate-signal behavior. Change: the signal scan is now a pure read collecting all changed files; on the first detection the watcher lingers FM_SIGNAL_GRACE (default 30s, deliberately chosen to cover the observed 15s status-to-turn-end gap), re-scans, dedupes by file, and reports everything in one 'signal: ...' wake line. Seen-signatures are deliberately written only at wake time now, so a watcher killed mid-grace cannot mark a signal seen without reporting it (the old code wrote seen before waking). AGENTS.md section 8 wording updated to match the multi-file wake format. Single-signal wake format is unchanged ('signal: '), keeping existing wake-handling instructions valid. Tested end-to-end in a sandbox: coalescing of two signals 3s apart into one wake, no duplicate wake after restart, and solo-signal wake all verified. The added wake latency (one grace period) is an accepted tradeoff; crewmate tasks run minutes to hours.

What Changed

• Updated bin/fm-watch.sh to collect changed signal files, wait through a configurable FM_SIGNAL_GRACE window, and emit one deduped signal: <file>... wake for near-simultaneous status and turn-end signals.
• Delayed writing seen-signal markers until the coalesced wake is reported, so watcher restarts during the grace period do not silently consume pending signals.
• Documented the multi-file signal wake behavior in AGENTS.md and noted the default signal grace window in README.md.

Risk Assessment

✅ Low: The change is narrowly scoped to watcher signal coalescing and documentation, preserves the single-signal output shape, and I found no material correctness or operational risks in the changed code.

Testing

Exercised the actual bin/fm-watch.sh end-to-end with synthetic watcher state: coalesced status plus turn-end signals, verified no duplicate wake after restart, verified kill-during-grace does not swallow a signal, verified solo-signal output shape, captured a transcript artifact, and removed transient in-worktree state afterward.

Evidence: fm-watch coalescing transcript

Shows one wake containing both coalesced signal files, no duplicate wake after restart, preserved pending signal after kill during grace, and unchanged solo-signal wake format.

fm-watch signal coalescing end-to-end transcript
worktree: /Users/kunchen/.no-mistakes/worktrees/016d88035d58/01KTX4RWRT72G8HZECAEST4FR8
test isolation: PATH prepends fake tmux returning no fm-* windows, avoiding unrelated stale wakes from live sessions.

Scenario 1: status write and turn-end marker 1s apart coalesce into one wake.
wake: signal: /Users/kunchen/.no-mistakes/worktrees/016d88035d58/01KTX4RWRT72G8HZECAEST4FR8/state/demo.status /Users/kunchen/.no-mistakes/worktrees/016d88035d58/01KTX4RWRT72G8HZECAEST4FR8/state/demo.turn-ended 
result: PASS - one wake contained both changed signal files.

Scenario 2: restarting after the coalesced wake does not produce a duplicate signal wake.
wake: <none within 3s>
result: PASS - seen signatures suppressed duplicate wake after restart.

Scenario 3: a watcher killed during the grace period does not mark a signal seen before reporting it.
wake after restart: signal: /Users/kunchen/.no-mistakes/worktrees/016d88035d58/01KTX4RWRT72G8HZECAEST4FR8/state/grace.status 
result: PASS - killed watcher did not swallow the pending signal.

Scenario 4: a solo status signal keeps the original single-file wake shape.
wake: signal: /Users/kunchen/.no-mistakes/worktrees/016d88035d58/01KTX4RWRT72G8HZECAEST4FR8/state/solo.status 
result: PASS - solo signal reported as one signal wake with one file.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• FM_SIGNAL_GRACE=2 FM_POLL=1 FM_HEARTBEAT=9999 FM_HEARTBEAT_MAX=9999 FM_CHECK_INTERVAL=9999 bin/fm-watch.sh with a status write followed by a turn-end marker 1s later, isolated from live tmux windows by a fake tmux on PATH
• FM_SIGNAL_GRACE=1 FM_POLL=1 FM_HEARTBEAT=9999 FM_HEARTBEAT_MAX=9999 FM_CHECK_INTERVAL=9999 bin/fm-watch.sh restarted after the coalesced wake and observed for 3s to confirm no duplicate signal wake
• FM_SIGNAL_GRACE=5 ... bin/fm-watch.sh killed during the grace period, followed by a restart with FM_SIGNAL_GRACE=1, to confirm pending signals are not marked seen before a wake is reported
• FM_SIGNAL_GRACE=1 ... bin/fm-watch.sh with a single status-file signal to confirm the original single-file signal: <file> wake shape remains intact

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[frederikwalbech]

Reviewed clean by fresh reviewer (kb-i4-rev-s2: e2e maintenance CLI + demo-run inspection + full harness green) and merged into integration branch fm/npt-build-s8 (merge 2254afa; additive conflicts vs #3 union-resolved). Lands in the single batch PR to main.

[darwinposo]

Check state - correction to the Intent section above

The Intent section above, carried over from the task brief, states that GitHub Actions is permanently billing-refused on this repository and that 0 passed, 0 failed, no CI checks configured is the expected artifact.
That premise did not hold on this run and is corrected here. CI genuinely ran.

The verified state on head 4700f6b is 9 passed, 1 failed. That is not green, and it is not the billing artifact either.

Check	Result
Behavior portable serial	failure
Behavior timing aggregate	success
Behavior portable parallel 1	success
Behavior portable parallel 2	success
Behavior tests (Herdr)	success
Lint shell scripts	success
Test coverage guard	success
Repo invariants	success
Stock macOS Bash snapshot compatibility	success
PR must be raised via no-mistakes	success

The single failure, Behavior portable serial, is pre-existing and not caused by this change.
On origin/main (0d8f0b8) all 9 checks fail, including that one.
This branch's only difference from origin/main is one added file under docs/, which no test reads, so the failure is origin/main's behaviour rather than a regression introduced here.
Fixing it is out of scope for a document placement.

Two honest caveats worth recording:

• gh pr checks 4 summarizes this PR as 0 passed, 0 failed - this PR has no CI checks configured, which contradicts the check-runs API showing 10 completed checks. The API is the accurate source; the summary is misleading here.
• The pipeline's three CI auto-fix attempts each aborted on an agent session-quota limit rather than on the code, so no fix was actually attempted and none was applied.

No check was relaxed, disabled, or deleted. Merge evidence remains the three SHA-256 verifications, the supersession sweep, and the local suite counts.

[pruge]

Rebased onto current main (0a2f59e): resolved the documentation-audiences.json overlap by keeping task-grill's entries alongside task-design, and merged the AGENTS.md planning-family exception to cover task-planning, task-grill, and task-design with design documents included. The redundant task-planning audience-classification commit collapsed during rebase since main already carries those entries. Lint and documentation-audience checks pass; content unchanged from the previously validated pipeline run.