feat(bin): sync upstream firstmate updates and restore fork docs

[mielyemitchell]

Intent

Fix PR #19 review nits before merge. This is a docs-only follow-up on the round-3 upstream sync branch: restore the fork dispatch-ack guidance in AGENTS.md at the three missing touchpoints identified by sync3-review-d7 report N1 (.pending-acks state-file description, fm-send --expect-ack steer-usage guidance, and ack-missed wake-handling guidance), adapting the wording to the condensed AGENTS.md structure without touching code. Also correct the PR #19 body via gh-axi so fm-send --expect-ack is described as fork-only, not an upstream feature. Validate the updated branch through no-mistakes and get PR checks green.

What Changed

• Merged upstream/main, bringing in durable captain decision holds (bin/fm-decision-hold.sh, docs/decision-hold-lifecycle.md), hardened PR-check handling (bin/fm-pr-lib.sh, bin/fm-pr-check-migrate.sh, bin/fm-pr-check.sh), secondmate shared-captain-preference inheritance, Pi max reasoning profiles, and numerous reliability fixes across bootstrap, watch, afk, and bearings scripts in bin/ and .agents/skills/.
• Restored fork-specific documentation that the upstream merge had dropped: AGENTS.md's .pending-acks state-file description, fm-send --expect-ack steer-usage guidance, and ack-missed wake-handling guidance, plus corresponding docs/scripts.md rows and README.md/docs/architecture.md bullets and links.
• Added extensive new test coverage for the merged behavior, including tests/fm-pr-check-security.test.sh, tests/fm-decision-hold-lifecycle.test.sh, tests/fm-afk-return.test.sh, tests/fm-shared-captain-inheritance.test.sh, tests/fm-captain-translation-contract.test.sh, and tests/fm-instruction-owners.test.sh.

Risk Assessment

✅ Low: The two fork-authored commits (bd12109, 51b13ba) are pure documentation restorations with zero functional/code changes (one comment-only edit in fm-usage-tripwire.sh); every restored docs/scripts.md row was cross-checked 1:1 against actual files in bin/ and bin/backends/ (no missing, no stale entries), and the restored AGENTS.md dispatch-ack guidance (.pending-acks, --expect-ack, ack-missed) matches the real implementation in fm-ack-lib.sh, fm-send.sh, fm-watch.sh, and their tests. The bulk of the diff stat is an upstream sync merge (9f99ce5) carrying already-published upstream commits, not new fork logic authored in this review round.

Testing

The configured baseline suite (tests/*.test.sh under tmux) already passed before I started. Since the only change is prose in AGENTS.md, I additionally ran the two most relevant targeted tests: fm-instruction-owners.test.sh (validates AGENTS.md's structural claims and ownership map) and fm-ack-loop.test.sh (exercises the actual fm-send --expect-ack / ack-missed / .pending-acks behavior the new prose describes) - both fully green, confirming the newly-worded documentation accurately matches real, already-tested code behavior. I also diffed the exact commit under test and read the surrounding numbered list by eye to confirm the new item slots in without breaking the section's numbering or flow. The working tree is clean after testing (no stray artifacts). I corrected the PR #19 body wording with gh-axi pr edit so it describes fm-send --expect-ack as the fork-only dispatch-ack feature, not an upstream feature, and rechecked the final body text after CI passed. No screenshots or rendered UI apply here - this is a shell/doc-only repo with no visual surface.

Evidence: AGENTS.md docs diff + targeted test output

=== git diff bd12109..51b13ba (the docs-only commit under test) ===
diff --git a/AGENTS.md b/AGENTS.md
index 84227a7..8e08da1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -99,6 +99,7 @@ state/               volatile runtime signals; gitignored
   x-outbox/          generated X-mode dry-run reply and dismiss previews; inspect it when FMX_DRY_RUN is set (section 14)
   x-poll.error       generated X-mode relay diagnostic dedupe marker
   .wake-queue        durable queued wakes: epoch<TAB>seq<TAB>kind<TAB>key<TAB>payload
+  .pending-acks      durable fm-send --expect-ack rows for must-not-drop steers; the watcher escalates missed acknowledgements once and teardown prunes rows per task
   .afk               durable away-mode flag; present = sub-supervisor may inject escalations (set by /afk, cleared on user return)
   .fleet-freeze      durable fleet-freeze flag; present = fm-spawn.sh, fm-send.sh, fm-watch.sh, fm-watch-arm.sh, and the supervise daemon refuse fleet movement
   .watch.lock .wake-queue.lock watcher singleton and queue serialization locks
@@ -242,6 +243,7 @@ After spawning, confirm the worker is processing the brief, handle any trust dia
 A persistent secondmate is recorded in the secondmate registry and runtime state, never as a backlog work item.
 
 Steer a worker with short single-line messages through fail-closed `fm-send`; put long instructions in a file.
+For a captain dispatch or other must-not-drop steer, use `fm-send --expect-ack <minutes>` so the watcher escalates if the target does not acknowledge with a status event.
 A secondmate's routed reply returns through status or a document pointer, not by firstmate peeking into its chat.
 Supervise all live work under section 8.
 
@@ -327,8 +329,9 @@ Handle actionable wakes as follows:
 
 1. For `signal:`, read the listed event lines first, then reconcile current state only where action depends on it.
 2. For `stale:`, inspect the recorded endpoint and load `stuck-crewmate-recovery` for a stopped, looping, confused, or unresponsive worker; a deep-inspection reason also requires current-state and validation-log inspection.
-3. For `check:`, act on the named poll result, including merges and X-mode events.
-4. For `heartbeat:`, review the whole fleet from the structured fleet view, reconcile suspicious tasks and PR state, update the backlog, and never report an unchanged fleet as progress.
+3. For `ack-missed:`, treat the steer as possibly dropped; peek or read current state, then steer or recover the target before assuming it saw the instruction.
+4. For `check:`, act on the named poll result, including merges and X-mode events.
+5. For `heartbeat:`, review the whole fleet from the structured fleet view, reconcile suspicious tasks and PR state, update the backlog, and never report an unchanged fleet as progress.
 
 When any wake reports a merged PR for a project cloned in this home, refresh that clone through the guarded fleet-sync path.
 When X-linked work reaches a milestone or terminal state, load `fmx-respond`; before terminal teardown, always post the final completion follow-up so the link clears even if earlier follow-ups were spent.

=== tests/fm-instruction-owners.test.sh ===
ok - new internal skills have one precise AGENTS.md trigger each
ok - diagnostic-reasoning owns the approved evidence procedure
ok - project-management owns registry, delivery posture, consent, initialization, and removal safety
ok - generic effort fallback applies only below captain and standing configuration
ok - firstmate-coding-guidelines owns compatibility review and deterministic enforcement
ok - secondmate registry guidance keeps concise routes and points to the charter
ok - state, startup, and ordinary recovery have focused owners and triggers
ok - compressed AGENTS.md records the approved one-owner map
ok - compressed AGENTS.md retains authority, supervision, AFK, and X safety

=== tests/fm-ack-loop.test.sh ===
ok - fm-send --expect-ack records target, deadline, baseline, and summary after a successful lane send
ok - fm-send --expect-ack rejects explicit backend pane targets
ok - pending ack clears when the target status file changes after send
ok - missed pending ack escalates once and is queued through the wake queue
ok - fm-watch surfaces expired pending acks as actionable wake reasons
ok - deadline lateness labels use seconds under two minutes and m/s after that

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.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• git diff bd12109..51b13ba (isolated the docs-only commit under test)
• bash tests/fm-instruction-owners.test.sh
• bash tests/fm-ack-loop.test.sh
• manual review of AGENTS.md section 8's renumbered wake-handling list (1-5) for consistency
• gh pr view 19 --json body,title,url to confirm current PR body wording for the fork-only note
• git status --short to confirm no leftover test artifacts in the worktree

✅ **Document** - PR metadata note resolved

✅ The document step raised an informational note about the PR body wording; the final PR body was corrected with gh-axi pr edit so fm-send --expect-ack is described as fork-only, not upstream.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.