fix: prevent stale supervision wake loops

[dnth]

Intent

Port upstream firstmate PR kunchenguid#3672 (fix: prevent stale supervision wake loops, merged as f4d7875 on upstream/main) into dnth/firstmate. Diff upstream against this fork current code and port only genuinely missing parts, reconciling fork-native supervision work including watcher-continuity PR #99 and kunchenguid#3532 if present; do not blindly re-apply upstream. Adapt any Pi-extension-specific changes to this fork's bash + OMP supervision structure (.omp/extensions and bin/fm-supervise-daemon.sh), omitting non-applicable Pi pieces. Prevent repeated stale supervision wake re-firing for parked declared waits or unchanged status and prevent stale acknowledgement loops. Add a colocated behavioral regression test in tests/ that fails without the fix and passes with it, through executable/public interfaces rather than source-byte assertions. Preserve existing supervision tests and wake handling/declared-pause behavior, keep every touched bin script shellcheck-clean, and include a short reconciliation of upstream changes, already-present fork behavior, newly ported behavior, and deliberate adaptations/omissions in docs or the PR description. Deliver a no-mistakes PR against main without merging it; hold for captain merge approval. Firstmate-Validation-Generation: 85e43d6d42e5ead5be9063eaff21d9e5

What Changed

• Bound stale supervision triage for live declared waits and captain-held transfers to declaration-scoped re-surface intervals, while preserving first-sight inspection and restarting cadence for replacement declarations.
• Scoped OMP branch reports to tasks named by granted wake rows and improved wake acknowledgements so stale cutoffs that consume nothing identify the current wake and exact command instead of replaying a loop.
• Added behavioral regression coverage and updated supervision, watcher-continuity, and configuration documentation for the new wake-handling behavior.

Risk Assessment

✅ Low: The port is internally consistent with the stated intent: stale live-wait panes are declaration-throttled, acknowledgements remain actor-scoped and generation-aware, and the added regression tests exercise executable behavior without source-byte assertions.

Testing

Ran the focused watcher triage, durable wake queue, and OMP supervision behavioral suites. They exercised stale wake suppression/resurfacing, declared-wait and AFK handling, enqueue-before-suppressor ordering, acknowledgement replay safety, and branch/main ownership boundaries; all completed successfully. No UI surface is involved, so screenshot evidence was not applicable.

Evidence: Focused watcher behavior evidence

ok - a bare turn-end whose crew is not provably working is surfaced (the swallowed-finish fix)
ok - a parked live worker surfaces once, absorbs pane churn for the whole re-surface window, then re-surfaces when it elapses
ok - an unacknowledged process-event result re-drains until handling is acknowledged
ok - with .afk present the watcher reverts to one-shot so the daemon owns triage (no double-triage)

Evidence: Wake queue safety evidence

ok - concurrent append plus drain preserves durable records through acknowledgement
ok - stale wake is queued before suppressor state is advanced
ok - concurrent drains replay until one post-handling acknowledgement consumes records
ok - a stale acknowledgement cannot retire or consume a newer recovery episode

Evidence: OMP supervision evidence

ok - a branch-actor scoped ack never swallows an unacked main-owned row, and main's later drain sees exactly what remains
ok - OMP dispatch resolves signal and stale rows to the branch report task and excludes checks

- Outcome: 🔧 1 issue found → auto-fixed ✅ across 3 runs (30m21s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅

• ⚠️ docs/architecture.md:30 - The new architecture text documents an opt-in config/turnend-churn-absorb mode and FM_TURNEND_CHURN_ABSORB_SECS bounded behavior, but neither the flag nor the environment variable is implemented anywhere in the changed source (or repository). Users enabling the documented option will see no effect; either remove this unsupported reconciliation text or authorize porting the missing implementation.

🔧 Fix: Removed unsupported churn docs and recorded future port
1 info still open:

• ℹ️ docs/configuration.md:707 - FM_STALE_ESCALATE_SECS is documented twice in docs/configuration.md; remove the duplicate entry to avoid ambiguous configuration guidance.

✅ No issues found.

🔧 **Test** - 1 issue found → auto-fixed ✅

• ⚠️ docs/configuration.md:707 - docs/configuration.md defines FM_STALE_ESCALATE_SECS twice (lines 703 and 707), creating contradictory duplicate configuration documentation.
• bash tests/fm-omp-branch-supervision.test.sh
• bash tests/fm-wake-queue.test.sh
• bash tests/fm-watch-triage.test.sh (targeted watcher triage cases exercised)
• bash tests/fm-watch-recovery-loop.test.sh

🔧 Fix: Removed duplicate stale escalation configuration documentation
✅ Re-checked - no issues remain.

• bash tests/fm-watch-triage.test.sh
• bash tests/fm-wake-queue.test.sh
• bash tests/fm-omp-branch-supervision.test.sh
• Checked git status --short --untracked-files=all and confirmed no transient test artifacts were left in the worktree.

✅ No issues found.

• bash tests/fm-watch-triage.test.sh
• bash tests/fm-wake-queue.test.sh
• bash tests/fm-omp-branch-supervision.test.sh
• git status --short (confirmed no transient worktree artifacts)

✅ **Document** - passed

✅ No issues found.

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

✅ No issues found.