fix(pi): restore watcher continuity across successor gaps and make extension log opt-in

[RibatTRW]

Intent

Work on the merge conflict for #5489.

Context needed to read the ask: that pull request, "fix(pi): restore watcher continuity across successor gaps and make extension log opt-in", comes from the fork RibatTRW/firstmate, head branch fm/firstmate-watcher-successor-gap-fix (head 3b237f6), base main, and closes #5492.
It treats a dead-but-unclosed arm child as an empty slot via liveArmChild so repair and retry start a fresh arm, pins handling confirmation to the restoration's own recovery token so a superseded generation is delivered without a failure appendix and nothing is retired unless the failed token names the exact current pid and generation, treats an already-acknowledged handling or downtime episode as a confirming no-op when the caller names its generation, and makes the Pi extension diagnostic log state/.watch-extension.log opt-in and off by default (only a positive FM_WATCH_EXTENSION_LOG_KEEP_LINES enables it).
GitHub now reports the pull request as conflicting with main, so it cannot merge.
The pull request's existing behavior must be preserved while bringing it up to date with current main.

Yes lets do the recommended fixes

Those recommended fixes are items 1-4 of a code review of that pull request:

1. A superseded handling delivery (the confirmation reports a generation mismatch) bypasses the Pi supervision branch and lands on main, while a confirmed delivery is offered to the branch first. A superseded delivery should route like a confirmed one - offered to the Pi supervision branch, with no failure appendix, retiring nothing - with a test that uses an accepting branch bus to assert the superseded wake is offered to the branch.
2. docs/watcher-continuity.md now says every adapter (Pi, omp, and OpenCode) confirms against the restoration's own recovery token, retries against that same token, and retires a successor only when the failed token names that exact pid and generation, but only Pi changed; omp and OpenCode still confirm against the current successor and retire it whenever the watcher pid is dead. Scope those sentences to Pi (or port the fix to omp and OpenCode).
3. Two claimed protections are untested: the narrowed retire guard (a failed confirmation must not retire a newer healthy arm that replaced the successor), and dead-but-unclosed slot handling in the scheduled retry and deferred-close paths (a retry must start a fresh arm over a dead-but-unclosed child). Add the missing tests, each failing when its fix is reverted.
4. test_handling_delivered_rejects_a_superseded_generation asserts something other than its label (its closing step is a plain arm check, not the handling-successor path, and it pins behavior that already exists on main): fix it or relabel it and its docs bullet. Its dead-pid rejection case uses pid 1, which is always alive; use a genuinely dead, reaped pid instead.

What Changed

• Pi extension (.pi/extensions/fm-primary-pi-watch.ts) now treats a dead-but-unclosed arm child as an empty slot (liveArmChild) in repair, scheduled retry and deferred close. Handling confirmation and its single retry use the restoration's own recovery token. A generation mismatch (exit status 3) is reported as superseded and is offered to the Pi supervision branch like a confirmed delivery, with no failure appendix and nothing retired. A failed confirmation retires the current arm only when the failed token names its exact pid and generation and that pid is dead.
• fm-wake-lib.sh treats an already-acknowledged handling or downtime episode as a confirming no-op when the caller names its generation. Without a named generation it is still rejected. The Pi extension diagnostic log state/.watch-extension.log is now opt-in and off by default. Only a positive FM_WATCH_EXTENSION_LOG_KEEP_LINES enables it, and the new knob is documented in docs/configuration.md.
• docs/watcher-continuity.md scopes the recovery-token confirm, retry and narrowed retire guard to Pi, since omp and OpenCode still confirm against the current successor. The extension and arm test suites cover:
  • the superseded wake being offered to an accepting branch bus;
  • the narrowed retire guard sparing a newer healthy arm;
  • a repair, retry and deferred close starting a fresh arm over a dead-but-unclosed child;
  • the already-acknowledged no-op, with a genuinely dead, reaped pid used for the dead-pid rejection case.

Risk Assessment

✅ Low: The change is well-bounded to the Pi extension and the handling-confirmation marker, and I found no concrete defect. Superseded deliveries now route like confirmed ones, the retire guard matches the recorded token including generation, and docs are scoped to Pi. Tests were added for each of the four requested items, but I did not run them.

Testing

I ran the two targeted test files that exercise this change, and both pass with exit 0. They cover superseded delivery being offered to the branch, dead-child fresh-arm restart on repair/retry/deferred close, the opt-in log, and handling confirmation. I did not run a real Pi or Herdr lab session, so no scenario is recorded as a live pass. I also did not revert each fix to confirm its test fails.

• Live validation: ⚠️ inconclusive - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
Superseded handling delivery is offered to the Pi supervision branch like a confirmed one, with no failure appendix	⏸️ untested	no	The prior payload only ran this through a test harness with a fake bus, not a live Pi session, so it did not establish a live result. Run a real Pi session under Herdr to drive it.
A dead-but-unclosed arm child is treated as an empty slot, so repair, scheduled retry and deferred close each start a fresh arm	⏸️ untested	no	The prior payload only ran this through a test harness, not a live Pi session, so it did not establish a live result. Run a real Pi session under Herdr to drive it.
Handling confirmation: an already-acknowledged confirmation is a no-op, and a churned generation reports a mismatch while an arm check keeps it	⏸️ untested	no	The prior payload ran this against fm-watch-arm.sh in a temp home, not a live fleet, so it did not establish a live result. Run against a live fleet to drive it.
The Pi extension diagnostic log stays off unless FM_WATCH_EXTENSION_LOG_KEEP_LINES is positive	⏸️ untested	no	The prior payload only ran this through a test harness, not a live Pi session, so it did not establish a live result. Run a real Pi session under Herdr to drive it.

Evidence: Pi extension test log

Source: Pi extension test log

ok - Pi extension reports external healthy watcher output
ok - Pi custom tool exposes repair-only metadata and returns automatic-continuation guidance
ok - Pi redundant tool call returns ownership guidance and spawns no second child
ok - Pi scheduled retry remains extension-owned after another tool call
ok - Pi actionable close starts one successor before wake delivery settles
ok - Pi actionable output waits for predecessor close before successor restoration
ok - Pi dispatcher branch offer owns accepted wakes and falls back to main
ok - Pi dispatcher flags a fleet-wide heartbeat offer as branch-eligible
ok - a co-present check row neither vetoes nor rides a heartbeat into main
ok - every main-only check class still reaches main, never the supervision branch
ok - a captain-held signal trigger reaches main with routine rows present
ok - an unread pending-reply escalation keeps later stale aliases on main
ok - a mixed batch of two distinct files - one routine, one needs-decision - routes wholly to main
ok - a co-present needs-decision row neither vetoes nor rides a heartbeat into main
ok - heartbeat restoration failure stays on main
ok - watcher-failure repair stays with main even with a live, accepting branch listener
ok - under the away-posture record every actionable row is offered to the branch while broken-queue wakes and watcher-failure alarms still reach main
ok - Pi refused handling handshake is classified and not swallowed
ok - Pi confirm failure retires the named arm with distinct watcher pid
ok - Pi confirm failure for a stale successor spares the newer arm
ok - Pi superseded handling delivery carries no rejection appendix and is logged
ok - Pi superseded handling delivery is offered to the branch like a confirmed one
ok - Pi extension diagnostic log stays off unless opted in
ok - Pi repair starts a fresh arm instead of no-opping on a dead child
ok - Pi scheduled retry starts a fresh arm instead of stalling on a dead child
ok - Pi deferred close starts a fresh arm instead of stalling on a dead child
ok - Pi hung successor falls back to one typed actionable wake
ok - Pi unretired successor falls back without an overlapping retry
ok - Pi late unretired closes resume classified supervision
ok - Pi clean empty close triggers a bounded continuity retry
ok - Pi established clean closes stop at the configured retry limit
ok - Pi close handler verifies session-lock ownership before successor launch
ok - Pi watcher arm distinguishes all session lock ownership states
ok - Pi session transitions auto-arm through a generation owner across /new /resume /fork/reload, stale callbacks, and quit
ok - Pi session replacement auto-arms and carries its in-flight actionable close
ok - Pi replacement replays a streaming follow-up before consumption
ok - Pi streaming-time wake delivery keeps the successor chain and replays only unconsumed wakes
ok - Pi retries a verified successor that failed during wake delivery once that delivery settles
ok - Pi replacement receives actionable closes after retirement timeout
ok - Pi replacement handoff tokens stay unique across fresh modules
ok - Pi replacement persistence failure keeps its predecessor until a successor commits
ok - Pi process-exit cleanup listener remains singular across session replacement
ok - Pi process-exit cleanup stops the attached arm child
ok - OpenCode plugins have an explicit ESM boundary even under a typeless parent package
ok - OpenCode watcher plugin uses the effective FM_HOME state
ok - OpenCode watcher plugin sources the effective config
ok - OpenCode watcher plugin requires session lock ownership
ok - OpenCode watcher coordinator respects primary scope
ok - OpenCode watcher plugin starts one successor before wake prompt delivery settles
ok - OpenCode watcher plugin runs the supervision host on an opted-in home and relays every host line (away record)
ok - OpenCode watcher plugin runs the supervision host on an opted-in home and relays every host line (quiet record)
ok - OpenCode pre-ready actionable close preserves its successor
ok - OpenCode hung successor falls back to one typed actionable wake
ok - OpenCode unretired successor falls back without an overlapping retry
ok - OpenCode late unretired closes resume classified supervision
ok - OpenCode clean empty close triggers a bounded continuity retry
ok - OpenCode established clean closes stop at the configured retry limit
ok - OpenCode close handler verifies session-lock ownership before successor launch
ok - OpenCode watcher plugin coordinates with the turn-end guard
ok - OpenCode healthy arm output does not suppress the turn-end guard
rc=0

Evidence: watch-arm test log

Source: watch-arm test log

ok - watch-arm: an attached arm reports the wake its cycle delivered instead of a false failure
ok - watch-arm: a delivered wake consumed by the handling turn still closes the attached arm cleanly
ok - watch-arm: an unusable launch confirm window refuses to arm by name
ok - watch-arm: a disposable validation checkout refuses to arm
ok - watch-arm: a watcher exits when its state directory is removed
ok - watch-arm: a watcher exits when its home is removed
ok - watch-arm: the test reaper stops a watcher armed for a tracked temporary home
ok - watch-arm: a cycle that delivered no wake of its own still fails loudly
ok - watch-arm: an attached arm keeps following a slow live holder and reports its wake
ok - watch-arm: an attached arm hands a holder stalled past the bound to its owner's replacement
~/.no-mistakes/worktrees/f070a5b5bfb8/01M3ZKCH5EQGVYDFA762D0AA7M/bin/fm-watch-arm.sh: line 766: 1670150 Killed                     "$WATCH" > "$child_out"
WAKE_ACK_REQUIRED: after handling completes run bin/fm-wake-drain.sh --ack-through 2 --recovery-generation 1670710.1790988443.MrYnb5
ok - watch-arm: re-arm surfaces every queued wake and an open remote decision after downtime
~/.no-mistakes/worktrees/f070a5b5bfb8/01M3ZKCH5EQGVYDFA762D0AA7M/bin/fm-watch-arm.sh: line 766: 1677678 Killed                     "$WATCH" > "$child_out"
WAKE_ACK_REQUIRED: after handling completes run bin/fm-wake-drain.sh --ack-through 1 --recovery-generation 1678271.1790988448.knOAoN
ok - watch-arm: a re-arm whose recovery cycle runs slowly still surfaces it
watcher: recovery state could not be persisted; retaining stale lock evidence
ok - watch-arm: marker publication failure retains stale-lock recovery evidence
WAKE_ACK_REQUIRED: after handling completes run bin/fm-wake-drain.sh --ack-through 2 --recovery-generation 1685671.1790988464.8ULsOT
WAKE_ACK_REQUIRED: after handling completes run bin/fm-wake-drain.sh --ack-through 3 --recovery-generation 1688670.1790988465.tXD6vI
ok - watch-arm: a wake queued after handling drain is recovered once at successor arm
ok - watch-arm: interrupted handling leaves its wake durable for successor re-drain
WAKE_ACK_REQUIRED: after handling completes run bin/fm-wake-drain.sh --ack-through 0 --recovery-generation 1697028.1790988471.cKj7tL
ok - watch-arm: malformed recovery state is quarantined without a successor loop
WAKE_ACK_REQUIRED: after handling completes run bin/fm-wake-drain.sh --ack-through 1 --recovery-generation 1699528.1790988472.7nmsPk
ok - watch-arm: publication after recovery handoff is surfaced
ok - watch-arm: restart publishes recovery before clearing a reused-pid watcher lock
WAKE_ACK_REQUIRED: after handling completes run bin/fm-wake-drain.sh --ack-through 7 --recovery-generation 1702103.1790988475.79plo4
ok - watch-arm: markerless legacy queues are adopted and recovered
ok - watch-arm: an idle Lavish source stays quiet and its real result wakes promptly
ok - watch-arm: appending work reopens an announced empty recovery
ok - watch-arm: a watcher close during handling keeps the printed acknowledgement valid
ok - watch-arm: a moved recovery generation consumes handled rows and names its remedy
ok - watch-arm: downtime marker publication does not follow symlinks
ok - watch-arm: --stop ends only this home's watcher, publishes downtime, and reports when none runs
ok - watch-arm: an already-acknowledged handling confirmation succeeds as a no-op
ok - watch-arm: a churned generation's handling confirmation reports a mismatch and an arm check keeps it
ok - watch-arm: --take-over attaches to a cycle the named arm does not own and leaves it running
ok - watch-arm: --take-over owns a fresh cycle without a recovery wake and still surfaces queued work
watcher: secondmate liveness check failed
ok - watch-arm: takeover preserves self-exit downtime and surfaces a recovery wake
rc=0

- Outcome: ⚠️ 1 warning across 1 run (5m58s)

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 4 scenarios were driven live against the product); untested: Superseded handling delivery is offered to the Pi supervision branch like a confirmed one, with no failure appendix, A dead-but-unclosed arm child is treated as an empty slot, so repair, scheduled retry and deferred close each start a fresh arm, Handling confirmation: an already-acknowledged confirmation is a no-op, and a churned generation reports a mismatch while an arm check keeps it, The Pi extension diagnostic log stays off unless FM_WATCH_EXTENSION_LOG_KEEP_LINES is positive
• Live validation: ⚠️ inconclusive - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
Superseded handling delivery is offered to the Pi supervision branch like a confirmed one, with no failure appendix	⏸️ untested	no	The prior payload only ran this through a test harness with a fake bus, not a live Pi session, so it did not establish a live result. Run a real Pi session under Herdr to drive it.
A dead-but-unclosed arm child is treated as an empty slot, so repair, scheduled retry and deferred close each start a fresh arm	⏸️ untested	no	The prior payload only ran this through a test harness, not a live Pi session, so it did not establish a live result. Run a real Pi session under Herdr to drive it.
Handling confirmation: an already-acknowledged confirmation is a no-op, and a churned generation reports a mismatch while an arm check keeps it	⏸️ untested	no	The prior payload ran this against fm-watch-arm.sh in a temp home, not a live fleet, so it did not establish a live result. Run against a live fleet to drive it.
The Pi extension diagnostic log stays off unless FM_WATCH_EXTENSION_LOG_KEEP_LINES is positive	⏸️ untested	no	The prior payload only ran this through a test harness, not a live Pi session, so it did not establish a live result. Run a real Pi session under Herdr to drive it.

• bash tests/fm-pi-watch-extension.test.sh (60 ok, exit 0)
• bash tests/fm-watch-arm.test.sh (30 ok, exit 0)

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

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

HEAD 7d0005b441498c0c34395eb0011b3d52ec5dae04. Attestation MATCH. Require no-mistakes SUCCESS. CI 35958032376 approved and in progress. MERGEABLE/UNSTABLE. Closes #5492 verified in body (issue open; defects match tip). Fork workflows approved after safe diff review.

contract-class: new-default (split: repair paths are restore; always-on log is new-default).

• Restore parts (tip vs main): dead-but-unclosed arm child gated via liveArmChild so repair/retry recover; handling confirmation pinned to restoration's own recovery token (superseded ≠ rejected; retire only on exact pid+generation match); already-acked confirmation is a no-op when generation is named — these repair a broken continuity path from Pi watcher continuity: successor-gap confirmations and a dead-but-unclosed arm child block repair/retry recovery #5492.
• New-default part: appendExtensionLog writes always-on to state/.watch-extension.log; FM_WATCH_EXTENSION_LOG_KEEP_LINES defaults to 200, and positiveInteger treats <=0 as fallback 200 so logging cannot be turned off — new default-on observer surface (FM-LEARN-4627). Not opt-in.

Overall class for auto-merge: new-default — will not auto-merge even when green. Firstmate-flag deferred until otherwise ready (CI still running). Help the PR; no competing PR.

VISION: One captain/interface — repair aligns; always-on log adds below-deck noise surface (partial); Authority aligns (no new autonomy grant); Scripts/judgment aligns; Restart — continuity repair aligns; Delegation n/a; Fleet/vendor — Pi adapter repair aligns; Scope — watcher continuity aligns, new diagnostic file is scope creep. Overall: aligns on repair, does not auto-admit for the new default-on log.

[greptile-apps]

Confidence Score: 5/5

[High risk] Modifies watcher continuity and recovery logic for process lifecycle.

The PR appears safe to merge; the latest changes preserve durable wake delivery and watcher ownership while closing the identified successor-gap cases.

_{Reviews (4) · Last reviewed commit: "Route superseded Pi deliveries like conf..."}

[RibatTRW]

Replying to the scope review on the diagnostic log: it is now opt-in and default-off. Setting FM_WATCH_EXTENSION_LOG_KEEP_LINES to a positive line count enables state/.watch-extension.log; unset, empty, non-numeric, zero, or negative values disable it entirely with no fallback, and a disabled log returns before touching the filesystem, so the file is never created. The watcher-continuity repair behavior (dead-slot gating, recovery-token confirmation, already-acked no-op) is unchanged. This comment was written with AI assistance; the change is covered by the repo regression suites and the pipeline's recorded live validation.

[kunchenguid]

Speaking as Kun's firstmate: whole thread re-read (prior waiting-ci new-default stamp on 7d0005b4; author reply that log is now opt-in default-off; tip rebound).

HEAD 3b237f6a284f98fd785489ae6028f79c4d4096d9. Attestation MATCH. Tip NM 36374833255 / 36373277908 SUCCESS. Tip CI 36373277882 in_progress after this-pass approve. Author RibatTRW not blocked. MERGEABLE pending checks.

Closes #5492: body Fixes #5492 — accurate (dead-but-unclosed arm, wrong-token confirm, already-acked rejection).

Contract-class: restore (own tip-vs-main; FM-LEARN-CLAIMS / FM-LEARN-4627). Continuity repair restores the already-specified watcher recovery path: liveArmChild empty-slot gating, confirmation pinned to restoration's own recovery token (superseded ≠ rejected; retire only on exact pid+generation), already-acked confirmation no-op when generation is named. The diagnostic log is now opt-in and default-off (FM_WATCH_EXTENSION_LOG_KEEP_LINES positive enables; unset/0/negative disable and never touch the filesystem) — no longer the always-on observer that previously forced new-default. Overall auto-merge class once green: restore (opt-in log does not block).

VISION.md (each rule)

1. One captain, one interface — aligns (continuity holds; opt-in log stays below deck when off).
2. Authority explicit — aligns (log gated; no new autonomy grant).
3. Scripts own mechanics — aligns (arm/confirm/retire stay scripted).
4. Restart non-event — aligns (repair restores durable watcher continuity).
5. Delegation with a spine — aligns (n/a beyond supervision continuity).
6. Fleet outlives vendor — aligns (Pi adapter repair + version-pinned reading debt unchanged).
7. Scope — aligns (watcher continuity; diagnostic file only when opted in).

Outcome: waiting-ci. Firstmate flag no. Workflow approvals this pass: CI 36373277882, NM 36373277908, NM 36374833255. If tip goes fully green + MATCH + CLEAN, eligible for auto-merge (restore).

[kunchenguid]

Speaking as Kun's firstmate: this is merged. Thank you @RibatTRW — really appreciate you taking the time on this.