feat: guard against missed secondmate reports

[kunchenguid]

Intent

Implement parent-owned guards that detect and recover missed secondmate communication.

Captain direction (2026-07-22): guard and detect a missed report, not pretend agent routing mistakes can be prevented. A secondmate may ignore instructions or answer only in its visible conversation. The safety property is that the parent notices the missing correlated report without scraping that conversation, requests one bounded repost, and escalates once if the repost is also missed.

Design decisions:

• Every marked parent-to-secondmate request gets a privacy-safe corr=<16hex> correlation id and a durable parent-owned pending-reply expectation under state/pending-replies/ before delivery (bin/fm-pending-reply-lib.sh).
• Delivery success and reply success are separate: successful fm-send never resolves the expectation; only a correlated parent status line or status-pointed document does, idempotently.
• Turn completion is proven via backend busy/idle observation (fm_backend_busy_state abstraction for Pi/Claude paths), never by reading conversation text.
• After a bounded grace (FM_PENDING_REPLY_GRACE_SECS, default 120) with turn completed and no correlated report, send exactly one automatic recovery repost; track that recovery turn separately; if it also completes without a report, escalate once via blocked status + wake queue and retain the unresolved durable record forever (expiration never silently erases unresolved replies).
• Wrong-home reports are counted as supporting evidence only, never acknowledgement.
• Direct unmarked captain/crewmate messages create no expectation.
• Optional bin/fm-secondmate-report.sh helper exists but correctness does not depend on the agent using it.
• Escalation lines use pending-reply-id= (not corr=) so parent-written escalations cannot self-resolve.
• Avoided overlap with concurrent test-runner work: did not edit canonical runner, CI topology, or test-family manifest.

What Changed

• Add durable parent-owned correlation records for marked secondmate requests, keeping delivery and correlated reply acknowledgement separate.
• Extend the watcher to detect completed turns without reports, issue one bounded recovery repost, and escalate once while retaining unresolved records.
• Add an optional correlated-report helper, operational documentation, and coverage for delivery, recovery, resolution, and escalation behavior.

Risk Assessment

✅ Low: The final change closes the late-report gap, and the full branch now satisfies the correlated acknowledgement, bounded recovery, one-shot escalation, and durable-state requirements without a substantiated remaining source defect.

Testing

At the requested target commit, I inspected the focused diff, ran both pending-reply behavior suites, exercised the complete missed-report recovery and escalation lifecycle through the actual send and watcher functions, verified the captured evidence assertions, and confirmed the worktree remained clean; all checks passed.

Evidence: Parent-owned pending-reply end-to-end transcript

PARENT-OWNED PENDING REPLY - END-TO-END TRANSCRIPT

1. Marked secondmate delivery
record_exists_before_transport=yes
phase_before_transport=awaiting_report
marker_present=yes
delivered_payload_after_marker=corr=6c79c35ed8e6c7ac audit the build
corr_length=16
phase_after_transport=awaiting_report
transport_resolved_expectation=no

2. Wrong-home report is evidence, not acknowledgement
wrong_home_hits=1
phase_after_wrong_home_report=awaiting_report

3. Parent watcher observes request turn busy -> idle with no parent report
phase_after_first_miss=recovery_sent
automatic_recovery_send_count=1
recovery_payload=[fm-from-firstmate]⁣corr=6c79c35ed8e6c7ac REPOST REQUIRED: previous marked request had no correlated parent report. Reply on the parent status channel including corr=6c79c35ed8e6c7ac. Original request: audit the build

4. Parent watcher observes recovery turn busy -> idle with no report
phase_after_second_miss=escalated
escalation_count=1
escalation_line=blocked: pending-reply-missed: task=hibit pending-reply-id=6c79c35ed8e6c7ac request=audit the build
escalation_contains_corr_token=no

5. Long-later watcher tick
phase_after_long_later_tick=escalated
unresolved_record_retained=yes

6. Direct unmarked crewmate message
delivered_payload=captain says hello
pending_record_count_before=1
pending_record_count_after=1

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 5 issues found → auto-fixed (10) ✅

• 🚨 bin/fm-pending-reply-lib.sh:611 - Required behavior is absent for the default tmux backend and supported zellij path. This tick relies exclusively on fm_backend_busy_state, but those adapters always return unknown; consequently request_turn_completed_epoch is never set and a missed report is never recovered or escalated. This contradicts the required criteria that turn completion be observed and that a completed missed turn trigger one recovery followed by escalation.
• 🚨 bin/fm-send.sh:239 - Any message containing a correlation ID whose record exists reuses that record without checking its task_id or phase. Forwarding a correlated message to another secondmate therefore creates no expectation for the new target, while reusing a resolved record leaves a new send unguarded. This contradicts the requirement that every marked parent-to-secondmate request receive its own applicable durable expectation.
• 🚨 bin/fm-pending-reply-lib.sh:510 - Appending the blocked status and directly adding a check wake causes the same watcher cycle to detect the newly changed status and enqueue a second actionable signal wake. This deterministically surfaces two queue records for one miss, contradicting the required single escalation.
• 🚨 bin/fm-pending-reply-lib.sh:490 - The record is permanently transitioned to escalated before either escalation artifact is durably written, while both the status append and wake append discard errors. If both publications fail, later ticks refuse to retry, so the required blocked-status and wake-queue escalation is silently lost.
• ⚠️ bin/fm-pending-reply-lib.sh:525 - Every watcher tick increments wrong_home_hits again while the same historical correlated line remains present. Track distinct sightings or persist the last observed signature so this supporting-evidence count reflects reports rather than polling frequency.

🔧 Fix: Deduplicate wrong-home pending-reply sightings
4 errors still open:

• 🚨 bin/fm-pending-reply-lib.sh:625 - The required criterion says, "Turn completion is proven via backend busy/idle observation" and then requires recovery after a completed miss. This hunk only calls fm_backend_busy_state, while its existing contract returns unknown for tmux and every adapter except Herdr. On the default tmux backend and supported zellij path, neither completion epoch is ever set, so missed reports remain pending forever without recovery or escalation.
• 🚨 bin/fm-send.sh:239 - The required criterion says, "Every marked parent-to-secondmate request gets ... a durable parent-owned pending-reply expectation." This hunk reuses any correlation record found in message text without verifying its task_id or phase. Forwarding a correlated message to another secondmate creates no expectation for that target, and reusing a resolved record leaves the new send unguarded.
• 🚨 bin/fm-pending-reply-lib.sh:512 - The required criterion says to "escalate once via blocked status + wake queue." This direct check wake follows a newly appended blocked: status, but the same watcher cycle subsequently detects that changed status and appends a separate actionable signal wake. Wake deduplication keys by kind and key, so both records survive and one missed recovery produces two escalations.
• 🚨 bin/fm-pending-reply-lib.sh:492 - The required criterion says to "escalate once via blocked status + wake queue." The record is permanently changed to escalated before either artifact is published, while both the status append and wake append discard errors. If publication fails, later ticks refuse to retry and the required escalation is silently lost.

🔧 Fix: Harden pending-reply recovery and escalation guards
1 warning still open:

• ⚠️ bin/fm-pending-reply-lib.sh:668 - Every pending-reply record is probed through the backend before tick_one checks its phase. Resolved records are never removed, and escalated records are retained forever, so tmux/zellij will accumulate one pane capture per historical request every watcher cycle even though those phases cannot use busy-state evidence. Skip backend observation for resolved/escalated records, and preferably reuse one probe for multiple open records targeting the same secondmate.

🔧 Fix: Bound pending-reply backend polling
1 warning still open:

• ⚠️ bin/fm-pending-reply-lib.sh:671 - This preflight calls fm_pending_reply_try_resolve for every record, then each open record enters tick_one, which repeats the same full status-file scan before and after observation. Escalated records are retained forever and also rescan their growing parent status and wrong-home logs every cycle. Avoid the added scans by checking phase=resolved directly, resolving escalated records once, and relying on a cached or incremental status observation for open records.

🔧 Fix: Cache pending-reply status scans
1 error still open:

• 🚨 bin/fm-pending-reply-lib.sh:381 - The required durable guard can be lost in the create-before-delivery window. A watcher may see the newly created record while fm-send is still delivering it and write this negative-scan signature, while fm_pending_reply_mark_delivered concurrently rewrites delivered_epoch. Because fm_pending_reply_set performs unlocked whole-file read/replace operations, the signature writer can move its stale copy last and erase delivered_epoch; that expectation then remains permanently ineligible for turn observation, recovery, or escalation. The wrong-home signature write has the same race. Skip all record mutations until delivery is marked, or serialize record rewrites with a per-record lock.

🔧 Fix: Protect undelivered pending-reply records from scans
2 errors still open:

• 🚨 bin/fm-send.sh:292 - The required criterion says every delivered marked request must remain guarded. After transport succeeds, this hunk discards any fm_pending_reply_mark_delivered error. A failed write or process exit in this window leaves the durable record permanently undelivered, and the watcher now skips such records forever, so the missing report is never recovered or escalated. Treat delivery-marker failure as a hard error and add a recoverable state for confirmed-but-uncommitted delivery.
• 🚨 bin/fm-pending-reply-lib.sh:570 - The required criterion says to "send exactly one automatic recovery repost." The recovery is delivered before phase=recovery_sent is persisted. If the process exits or the record rewrite fails after delivery, the record remains awaiting_report, and every later tick can resend the recovery. Persist an at-most-once recovery-attempt state before the external send and reconcile its outcome without reinjection.

🔧 Fix: Close pending-reply delivery durability gaps
2 errors still open:

• 🚨 bin/fm-pending-reply-lib.sh:347 - The required criterion separates delivery success from reply handling, but an attempted marker is promoted to delivered after grace without evidence that transport ran or succeeded. A sender crash before submission, a long-running send, or FM_PENDING_REPLY_GRACE_SECS=0 can therefore manufacture delivery and trigger recovery/escalation for a request that never landed. Only reconcile confirmed; keep attempted as an unknown state until backend evidence or an explicit failure resolves it.
• 🚨 bin/fm-pending-reply-lib.sh:652 - The required criterion says to "send exactly one automatic recovery repost" and track that recovery turn separately. This path calls fm_pending_reply_reconcile_recovery even when transport definitively fails, and reconciliation writes recovery_sent_epoch and phase=recovery_sent. The watcher can then observe and escalate a nonexistent recovery turn. Preserve failed/unknown attempt states and escalate a delivery failure explicitly without representing it as a sent repost.

🔧 Fix: Separate pending-reply transport outcomes
1 error still open:

• 🚨 bin/fm-pending-reply-lib.sh:351 - The required safety property says the parent notices a missing correlated report, but an attempted delivery marker is now ignored forever. If transport succeeds and fm-send exits before replacing that marker with confirmed, every watcher tick returns here, leaves delivered_epoch empty, and never resolves, recovers, or escalates the request. Preserve the unknown state without manufacturing delivery, but surface it once using sender/backend evidence or an explicit delivery-unknown escalation.

🔧 Fix: Escalate stalled pending-reply deliveries once
1 error still open:

• 🚨 bin/fm-pending-reply-lib.sh:769 - The required criterion says "only a correlated parent status line or status-pointed document" resolves the expectation, but this delivery-unknown escalation calls fm_pending_reply_try_resolve while delivered_epoch is empty, so that function always refuses before scanning status. If transport succeeded, the sender crashed before confirmation, and the secondmate reported correctly, the watcher still publishes a false delivery-unknown escalation. Treat a correlated parent report as delivery evidence and resolve it before escalating uncertainty.

🔧 Fix: Resolve attempted deliveries from correlated reports
1 error still open:

• 🚨 bin/fm-pending-reply-lib.sh:945 - The required criterion says a correlated parent status/document resolves the expectation idempotently, including late reports. After a delivery-unknown escalation, phase=escalated while delivered_epoch remains empty; this branch skips every such record before calling fm_pending_reply_try_resolve. A valid late report therefore never resolves automatically even though the resolver now supports attempted markers. Route undelivered escalated records through the resolver before continuing.

🔧 Fix: Resolve late reports after delivery escalation
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• git diff --stat b843c66b2d61b7a4dd257a07234ddd1a6227adad..9032ba0b96ab216434b1266a6165fe627af7a0ad and git diff --name-only b843c66b2d61b7a4dd257a07234ddd1a6227adad..9032ba0b96ab216434b1266a6165fe627af7a0ad
• bash tests/fm-pending-reply.test.sh
• bash tests/fm-send-secondmate-marker.test.sh
• Hermetic end-to-end scenario using bin/fm-send.sh hibit "audit the build", followed by initial and recovery fm_pending_reply_tick_one busy/idle observations
• Transcript assertions for pre-delivery persistence, one recovery, one escalation, no escalation corr= token, durable retention, and unchanged record count after direct unmarked delivery
• git rev-parse HEAD and git status --short confirmed target commit 9032ba0b96ab216434b1266a6165fe627af7a0ad and a clean worktree

✅ **Document** - passed

✅ No issues found.

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

• ⚠️ linter found issues (exit code 1)

🔧 Fix: Silence intentional pending-reply test fixture lint warnings
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.