feat: adopt upstream multi-brain supervision and fleet upgrades

[rega10]

Intent

Bring the rega10 Firstmate fork fully up to the current kunchenguid/firstmate:main, preserving every intentional fork behavior, and ship the reconciliation through a reviewed fork PR. The captain explicitly requested the latest upstream Firstmate because upstream now includes Pi's persistent multi-brain supervision architecture (upstream commits 7b88520 persistent Pi supervision branch, d55e00a multi-brain architecture poster, 8fa0505 default-on branch supervision and heartbeat routing, plus later fixes through the exact live upstream tip) and wants to use it.

Required reconciliation, all accepted as stated: (1) fetch live fork and upstream refs and verify exact identities before branching (fork origin/main was bae3180, upstream/main was 038d0f7; fork diverged, 17 ahead / 231 behind, not fast-forwardable); (2) create a normal feature branch from fork origin/main and perform a history-preserving merge of exact upstream/main - never rebase, squash, reset, force-push, replace fork history, or write upstream; (3) resolve every semantic conflict deliberately, preserving intentional fork-specific safety, private-home behavior, dispatch preferences, runtime support, Herdr repairs (fork PRs #4, #6, #10), Claude worker transcript preservation (PR #8), spawn metadata-publication abort (PR #5), hosted Codex opaque lock owners (PR #1/#3/#9), and later fork fixes unless upstream supplies a demonstrably equivalent or stronger implementation; never mechanically choose ours/theirs for broad files; inventory every conflict and document each resolution; (4) adopt the complete upstream Pi multi-brain implementation and its later fixes as a coherent unit - branch extension, watcher dispatch, leases, outcome store, recovery, prompts, docs, tests, default-on heartbeat behavior - never cherry-pick only headline commits or create a competing implementation; (5) preserve the feature's upstream contract: default-on only for a Pi primary owning the fleet session; ordinary resolvable supervision and eligible heartbeat work moves to the persistent in-process branch; genuinely quiet heartbeat outcomes are silent; ordinary non-silent outcomes append a compact sailboat note; captain-relevant outcomes open exactly one main-session turn; fleet-wide/unresolvable events and watcher failures stay on main; away mode declines branch offers; broken/absent branch falls back to main without losing notifications; branch authority cannot merge, land local work, or freshly spawn; current captain approval and security boundaries remain unchanged; (6) verify whether any fork-only behavior conflicts with the upstream branch lease/role partition and adapt the smallest authoritative owner rather than bypassing new guards; (7) keep the diff to one reconciliation merge plus only narrowly necessary follow-up fixes for proven semantic conflicts or validation failures; do not opportunistically redesign unrelated systems.

Decisions and tradeoffs made while doing the work: fork PR #9 was squash-merged on GitHub (single-parent 3015811) although its branch had merged upstream f74d9e4, so git's raw merge base was the ancient 59ece45 and produced ~200 spurious add/add conflicts; a temporary LOCAL git replace --graft restoring that true parent was used only for merge-base computation, then deleted, and the resulting commit 17cd039 is an ordinary two-parent merge of bae3180 and 038d0f7 (both verified as ancestors). Ten real conflicts were resolved: harness-adapters skill (both fork sentences plus upstream's Zellij wording), ci.yml and docs/fm-test-portable-shards.md (upstream's measured timeout wording, same 20-minute value the fork raised in PR #9), bin/fm-session-start.sh (fork's opaque-owner completion read via fm_session_lock_owner_read retained plus upstream's COMPLETION_RECORDED flag), bin/fm-test-run.sh (both family entries; upstream's refreshed weight-hint table plus the fork's two fm-herdr-legacy-repair hints - hints are balance-only), tests/fm-gotmp.test.sh (all symlinks from both sides), tests/fm-pi-watch-extension.test.sh (upstream's later flake rework taken for every hunk because it supersedes the fork's PR #9 fix for the same flake; upstream's call list verbatim; the fork-original Node 22+ skip guard re-inserted before the Pi test calls; the fork's 500->1000 wait bound kept), tests/fm-session-start.test.sh and tests/fm-sessionstart-nudge.test.sh (conflicts split mid-function; regions rebuilt from both sides' complete functions so all tests survive), tests/fm-spawn-dispatch-profile.test.sh (the launch string now composes upstream's outer env -u CURSOR_AGENT -u CURSOR_INVOKED_AS with the fork's env -u CLAUDE_CODE_CHILD_SESSION -u CLAUDE_CODE_SESSION_ID -u CLAUDE_PID -u CLAUDE_JOB_DIR template, both intentional; expectations updated to the composed string). Every line the fork added over f74d9e4 was verified present in the merged tree except those deliberate resolutions. The fork's non-numeric Codex lock owners make fm_lease_live report not-live so lease guards are silent no-ops on non-Pi homes, exactly as upstream intends; no fork behavior needed adaptation.

Narrow follow-up commits, each justified by a proven validation failure: 9d21048 returns undefined explicitly from .pi/extensions/fm-calm.ts's terminal-input handler because installed Pi 0.83.0 types TerminalInputHandler as returning {consume?, data?} | undefined and the strict typecheck failed on the unmodified upstream file (upstream's evidence was against 0.80.10); f368599 records the dated Pi 0.83.0 real-SDK live guard and typecheck results in docs/verification/runtime-backends.md as that record's own refresh-after-upgrade contract requires; 2a2f3ed spells half-block glyphs literally in tests/fm-composer-lib.test.sh because stock macOS Bash 3.2 does not decode $'\uXXXX'; 9a3649e fixes bin/fm-public-followup.sh expanding empty arrays under set -u (fatal on Bash 3.2, so every Relay follow-up command died on macOS; reproduced on pristine upstream) using the repo's existing ${arr[@]+"${arr[@]}"} idiom, and fixes the rechain test's inline-quoted pattern substitution that Bash 3.2 splits at its first slash; 5fce5ef lets the fork-only CI contract test accept upstream's renamed Lint job (was Lint shell scripts); 3445ba5 applies the same empty-array idiom to bin/fm-remote-home-seed.sh so --no-projects remote seeding works on Bash 3.2 (both remote-secondmate suites failed on pristine upstream); 5e4f0cc adds a readability check before each adapter . in bin/fm-backend.sh's fm_backend_source because under set -e Bash 3.2 treats a failed . as fatal even inside ||, so a missing adapter killed teardown's Herdr preflight silently instead of refusing with its "nothing was changed" message (tests/fm-teardown.test.sh failed on pristine upstream). Stock macOS Bash 3.2 is a real runtime for the captain's fleet (#!/usr/bin/env bash resolves to /bin/bash here) and production scripts already guard BASHPID with ${BASHPID:-$$}, so these are in-scope compatibility fixes, not redesign.

Validation run on macOS 26.5.2 arm64 with /bin/bash 3.2.57, Node 24.19.0, Pi 0.83.0, pinned ShellCheck 0.11.0 and actionlint 1.7.12 (scratch installs, nothing global): bin/fm-lint.sh green, bin/fm-doc-audience-check.sh ok, coverage guard ok (167 tests), strict Pi typecheck ok against 0.83.0, tests/fm-pi-branch-extension.test.sh, tests/fm-branch-supervision.test.sh, tests/fm-pi-watch-extension.test.sh (36/36), and FM_PI_BRANCH_LIVE_E2E=1 real-SDK guard all green, proven-isolated lane 24/24, real-Herdr family 13/13, upstream's macos-stock-bash job steps replicated (207-file parse sweep, 15/15 and 42/42 snapshot suites). Known and deliberately unfixed: five tests still fail on this macOS/Bash 3.2 machine and fail identically on a pristine upstream/main export, none merge-caused - tests/fm-wake-queue.test.sh (new upstream self-held-lock reclaim case needs $BASHPID to distinguish a subshell; a lock-primitive change upstream should own), tests/fm-pending-reply.test.sh (test-only bare $BASHPID at line 692; production lib guards it), tests/fm-muse-harness.test.sh (macOS kills the fixture's unsigned copied bash; also fails on fork main), tests/fm-on.test.sh (upstream remote-root fixture omits fm-composer-lib.sh which the herdr adapter sources; also fails on fork main), tests/fm-bootstrap-network-parallel.test.sh (fake-ssh timing assertion failing 3/3 on both HEAD and pristine upstream here). Linux CI is the proof for those; no Bash >= 4 exists on this machine.

Constraints: never modify anything under projects/; never update, stop, or restart the shared no-mistakes service; do not change private data/, state/, or config/ except the generated task status protocol; never push or open anything against kunchenguid/firstmate - the delivery target is a new PR in rega10/firstmate:main only; never merge the fork PR; do not fold upstream PR kunchenguid#282 unless already in the upstream tip (it is not); do not touch other workers' branches. The private report with refs, ancestry, conflict inventory, fork preservation, activation requirements, validation and skip evidence, and the post-merge /updatefirstmate plus Pi restart procedure is at data/firstmate-upstream-multibrain-sync/report.md (private, not part of the PR).

Later accepted decisions, carried in their current form: the first pipeline run (01M0V9GQW0WQG4NFZ2VB6R5J0M) reached checks-passed as PR #11 with two accepted review-fix commits (84de0a2 semantic lint-job assertion plus Node-guard scoping so the OpenCode watcher tests keep running on old Node plus reconciled Pi version provenance; b925d75 requiring a parsed workflow step whose command token is bin/fm-lint.sh). Its CI auto-fix commit 097973e temporarily relaxed the fork's required "PR must be raised via no-mistakes" check to also accept the legacy pre-1.46.0 PR-body format because the shared gate was v1.45.4. The captain explicitly decided (Option B) to restore upstream's stronger structured-attestation requirement: after the shared no-mistakes was upgraded to v1.57.0, commit 9b724ab reverts exactly 097973e, returning .github/workflows/no-mistakes-required.yml to its byte-identical upstream-adopted form and removing the interim bin/fm-no-mistakes-pr-body-verify.sh, its test, and its runner family entry, while preserving every other commit. The revert of those interim files is deliberate and captain-approved, not a lost fix. The PR must remain unmerged; the same branch and PR are being revalidated.

What Changed

• Add default-on persistent Pi supervision with branch leases, heartbeat routing, durable outcomes, recovery, fallback behavior, documentation, and tests.
• Expand fleet operations with durable local and remote inboxes, captain-held task lifecycles, an interactive Bearings board, Cursor primary-harness support, and an optional voice relay.
• Preserve fork-specific runtime safeguards while hardening backends, watchers, Relay workflows, remote seeding, and CI compatibility across supported environments.

Risk Assessment

⚠️ Medium: The source review found no substantiated defect or intent contradiction, but the change remains a broad multi-brain runtime reconciliation whose size and concurrency-sensitive behavior warrant moderate integration risk.

Testing

The supplied baseline had already covered lint, documentation, coverage, Pi 0.83 typechecking/live guards, portable and Herdr lanes, and macOS Bash 3.2 checks; this phase reran the focused workflow contract and core multi-brain suites, reproduced the shell-bypass regression against the predecessor, verified all inheritance-level bypasses are now rejected, and captured persisted startup-replay evidence. All targeted checks passed; no UI screenshot was applicable because the change exposes shell/CLI and workflow behavior rather than a rendered interface.

Evidence: Workflow shell-override regression matrix

Source: Workflow shell-override regression matrix

fixed | baseline | expected=accepted observed=accepted
ok - no-mistakes stays targeted and CI owns broad behavior coverage
predecessor | step-shell | expected=accepted observed=accepted
ok - no-mistakes stays targeted and CI owns broad behavior coverage
fixed | step-shell | expected=rejected observed=rejected
not ok - no-mistakes and CI YAML contracts must remain intact
predecessor | job-shell | expected=accepted observed=accepted
ok - no-mistakes stays targeted and CI owns broad behavior coverage
fixed | job-shell | expected=rejected observed=rejected
not ok - no-mistakes and CI YAML contracts must remain intact
predecessor | workflow-shell | expected=accepted observed=accepted
ok - no-mistakes stays targeted and CI owns broad behavior coverage
fixed | workflow-shell | expected=rejected observed=rejected
not ok - no-mistakes and CI YAML contracts must remain intact

Evidence: Persistent Pi supervision startup replay

Source: Persistent Pi supervision startup replay

Persistent Pi supervision outcome replay
Persisted outcomes before replay: 3
BRANCH OUTCOMES (handled by the supervision branch, not yet seen by this session):
{"seq":2,"epoch":1787725829,"task":"routine-steer","wake":"task-end","verdict":"routine","summary":"Worker steer delivered","silent":false}
{"seq":3,"epoch":1787725829,"task":"captain-call","wake":"milestone","verdict":"captain","summary":"Captain decision required","silent":false}
Unread outcomes after replay: 0
Replay cursor: 3

Evidence: Persisted supervision outcome store

Source: Persisted supervision outcome store

{"seq":1,"epoch":1787725828,"task":"quiet-heartbeat","wake":"heartbeat","verdict":"routine","summary":"No captain-facing change","silent":true}
{"seq":2,"epoch":1787725829,"task":"routine-steer","wake":"task-end","verdict":"routine","summary":"Worker steer delivered","silent":false}
{"seq":3,"epoch":1787725829,"task":"captain-call","wake":"milestone","verdict":"captain","summary":"Captain decision required","silent":false}

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed (6) ✅

• 🚨 tests/fm-nm-test-contract.test.sh:125 - The changed contract test still violates the test-quality rule: the serial-step check accepts echo bin/fm-test-run.sh --lane "$FM_SERIAL_LANE" because it searches any token subsequence, while lines 24, 90, 100-103, and 129-140 rely on raw YAML text and can pass on comments or unrelated content. Parse both YAML files semantically, require direct executable commands after optional environment assignments, assert companion-job behavior through normalized jobs/steps, and remove the commented-text assertion.

🔧 Fix: Make workflow contract assertions semantic
1 error still open:

• 🚨 tests/fm-nm-test-contract.test.sh:75 - The semantic lint assertion remains bypassable because an empty expected argument list makes every invocation beginning with bin/fm-lint.sh match. For example, changing the CI step to bin/fm-lint.sh --list-files would pass this test but exit before running ShellCheck or actionlint. Require the lint workflow command to have exactly the executable and no arguments.

🔧 Fix: Require exact lint workflow command
1 error still open:

• 🚨 tests/fm-nm-test-contract.test.sh:75 - The semantic workflow check remains bypassable because direct_command accepts any trailing tokens. For example, bin/fm-test-run.sh --lane portable-parallel-1 --list satisfies this assertion, but fm-test-run.sh then prints the inventory and exits 0 without running tests; the serial and Herdr assertions have the same bypass. Validate each command's complete permitted argument schema, rejecting --list, exclusion flags, shell operators, and other behavior-changing suffixes.

🔧 Fix: Enforce exact workflow command schemas
1 error still open:

• 🚨 tests/fm-nm-test-contract.test.sh:111 - The exact-token check still accepts dead commands. For example, a step containing exit 0 followed by bin/fm-lint.sh satisfies include?, succeeds, and never runs lint; every lane assertion has the same flaw. Validate each owning step’s complete permitted command sequence, including only its real prologue and exact invocation, and reject early terminators or unexpected commands.

🔧 Fix: Enforce exhaustive workflow step sequences
1 error still open:

• 🚨 tests/fm-nm-test-contract.test.sh:56 - The claimed exhaustive workflow-step check still ignores execution metadata. For example, adding if: ${{ false }} or continue-on-error: true to the exact run: bin/fm-lint.sh step leaves its normalized sequence unchanged, so this test passes while lint is skipped or cannot fail CI. This is another expansion of the same bespoke parser after four fix rounds: decide whether to extend the owning job/step model to require an enabled condition and failure propagation; that is the smallest correction and is recommended.

🔧 Fix: Enforce lint execution metadata
1 error still open:

• 🚨 tests/fm-nm-test-contract.test.sh:165 - The lint predicate still ignores the effective shell. A step with the exact run: bin/fm-lint.sh plus shell: true {0} passes this contract, but GitHub executes true and exits successfully without running lint; job- or workflow-level defaults.run.shell has the same path. Reject shell overrides for the required lint step, including inherited defaults, and cover the no-op-shell case.

🔧 Fix: Reject lint shell overrides
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• /bin/bash tests/fm-nm-test-contract.test.sh
• Temporary git archive fixture matrix comparing 450a1c4 and 4bf373c after step-, job-, and workflow-level shell: true {0} mutations; the predecessor accepted every bypass while the fix rejected all three
• /bin/bash tests/fm-branch-supervision.test.sh
• /bin/bash tests/fm-pi-branch-extension.test.sh
• Three bin/fm-branch-outcome.sh append calls followed by startup-replay and unread, demonstrating durable quiet/routine/captain outcomes, silent quiet replay, visible routine/captain replay, and cursor advancement

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 1)

🔧 Fix: Suppress intentional single-quoted Ruby ShellCheck warning
1 warning still open:

• ⚠️ linter found issues (exit code 1)

✅ **Push** - passed

✅ No issues found.