feat(bin): sync upstream fleet runtime capabilities

[purple-phoenix]

Intent

Captain's order: merge upstream kunchenguid/firstmate main (71 commits ahead, through fa0d85d) into this purple-phoenix fork, preserving the semantics of our six landed changes: #2 watcher hardening, #3 user-journey audits, #4 locale-invariant composer, #5 capacity dashboard, #6 dashboard redesign, #7 task-id contract. Hard constraints: MERGE, never rebase or force; never push to upstream (fetch only). Captain authorized merge-on-green for this sync PR.

Eleven files conflicted; each was reconciled semantically rather than by taking a side wholesale. Deliberate decisions a reviewer would not infer from the diff:

• fm-watch-arm.sh: both sides independently fixed silent watcher arm-cycle death. Upstream's rewrite won structurally (cycle ledger, bounded successor wait, successor-following attach, typed failures) as the better maintenance baseline. Four things from our PR 2 were ported onto it because upstream lacks them: the durable .watcher-arm-dead marker on every FAILED path (fm-guard.sh reads its detail= field), the loud report plus marker when a signal ends supervision with tasks in flight, the child reap before any successor check, and the wake-sequence check that keeps a normal wake handoff from being reported as a death. PR 2's idle exemption was deliberately DROPPED in favor of upstream's unconditional loudness: that is the stronger reading of PR 2's own goal and closes a hole for X-only homes. Our two PR 2 tests were adapted to upstream's typed failure line while still asserting marker and non-zero exit.
• Task-id minting converged with no code change: upstream's fm_task_id_creation_valid has the same name and contract as our existing quiet wrapper (path-safe, <= 64), so upstream's callers work unchanged against ours. Our captain-decision exemption in fm-decision-hold.sh (a kind=captain hold may exceed the length limit as non-dispatchable and never truncated, but must stay path-safe) is preserved with its tests.
• fm-spawn.sh: kept upstream's per-task spawn lock plus our diagnostic-emitting validator.
• fm-fleet-snapshot.sh: unioned upstream's multi-blocker resolution with our capacity evidence fields.
• docs/supervision-protocols/claude.md and docs/herdr-backend.md: took upstream's rewrites; for herdr, PR 4's locale-invariance content was re-homed into the surviving sections rather than dropped.

Beyond the merge itself, four pre-existing upstream defects had to be fixed because they reproduce on a clean upstream/main tree and blocked a green suite. These are intentional additions, not scope creep:

1. fm-brief.sh did not parse under stock macOS Bash 3.2 (apostrophe inside a heredoc nested in $( )), so no brief could be generated on macOS at all - upstream issue macOS bash 3.2: fm-brief.sh fails to parse at fa0d85d (unexpected EOF, heredoc-in-case); watcher cycles also exit 1 without reason since update kunchenguid/firstmate#1179. Fixed structurally by moving each Definition-of-done into a function body; upstream's wording restored verbatim.
2. tests/fm-bearings-snapshot.test.sh used sed 'a' which drops the newline on BSD sed and corrupted its own fixture. Replaced with awk.
3. fm-spawn.sh did not fail closed when task metadata could not be written - it printed "spawned ..." and exited 0, leaving a live worker nothing was tracking. Upstream's own orca test asserted this and was red.
4. tests/fm-session-start.test.sh read $BASHPID, which does not exist in Bash 3.2, so under set -u every racer subshell aborted and the exactly-one-winner session-lock assertion always saw zero.

Two failures were genuinely caused by the merge and are fixed: our two task-id tests widened upstream's pinned ShellCheck source graph (switched to the non-following directive form), and our capacity and user-journey-audit skills were unclassified in upstream's new documentation-audience inventory (both classified agent-runtime).

One nuance to read carefully: two commits touch cleanup_child's TERM handling. The failure that prompted them was NOT a code defect - it was an artifact of running the suite under nohup, which sets SIGHUP to ignored and passes that to every descendant, so the test's kill -HUP was discarded. What survives on merit is the latency change: an intermediate commit introduced an unbounded blocking wait measured at 5-6s against an 8s budget, and the bounded 1s grace brings it to 1-2s. Treat it as a latency improvement, not a bug fix.

Verification: full suite 103/103 files with 3 failures, all environment-only and all skipping in CI (Pi 0.81.1+ vs local 0.80.10; Python 3.11+ for tomllib vs local 3.9.6; a harness-ancestry test that resolves the real Claude this runs under). fm-lint.sh clean. Every bin script parses under stock macOS Bash 3.2.

Mid-flight, PR #8 (persistent tailnet-only dashboard service) merged into origin/main. It was integrated as a second MERGE, never a rebase, because rebasing would flatten the upstream merge commit whose two parents are the record of this sync. That merge had three conflicts: .gitignore and AGENTS.md were additive on both sides, and bin/fm-fleet-snapshot.sh had #8 and upstream independently growing multi-blocker support. Both field families are emitted because both have live consumers (bin/fm-capacity.mjs reads #8's blocked_by_all, bin/fm-bearings-snapshot.sh reads upstream's blocked_by_ids/unresolved_blocker_ids). The one genuine contract collision was the scalar blocked_by on parsed backlog records: upstream captured only the last blocker while #8 joined all of them with commas. The join won because fm-capacity.mjs splits that scalar on commas, so it is the contract with a real consumer, whereas upstream's single-value form appeared only in test expectations and its information survives in blocked_by_ids; three upstream assertions were updated accordingly and still pin the structured fields. Captain-hold selection keeps upstream's stricter captain_actionable predicate so a blocked captain hold stays queued, with #8's origin and decision-key extraction layered on. docs/dashboard-service.md from #8 was classified maintainer-architecture in the documentation-audience inventory.

The PR body must be pipeline-generated. An earlier round of this work replaced the body by hand, which deleted the deterministic ## Pipeline section and its no-mistakes signature, failing the repository's PR-provenance check. That was corrected by moving the detailed conflict write-up into a PR comment and letting the pipeline own the body, per the guidance in CONTRIBUTING.md that the signature must never be pasted in by hand. Two sibling PRs, #8 and #9, merged into origin/main while this sync was in flight; both were integrated as merges rather than rebases for the same reason the upstream sync itself is a merge.

What Changed

• Sync upstream fleet runtime capabilities, including Kimi and pi-signed adapters, quota-aware dispatch, Pi Calm mode, Herdr presentation spaces, session-start nudges, and GitLab merge watching.
• Harden watcher, spawn, session, and cleanup lifecycles while preserving fork contracts for failure markers, task IDs, capacity evidence, and locale-invariant composer detection.
• Add canonical timed and sharded test tooling, isolation coverage, runtime verification, and documentation-audience checks.

Risk Assessment

⚠️ Medium: No material defects were substantiated, but the large multi-merge change spans critical supervision, backend, dispatch, and snapshot paths, leaving meaningful integration risk despite careful reconciliation.

Testing

Completed 1 recorded test check.

• Outcome: ⚠️ 1 error across 1 run (22m27s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - medium risk

✅ No issues found.

⚠️ **Test** - 1 error

• 🚨 tests failed with exit code 1
• 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"

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[purple-phoenix]

Merge resolution detail

Posted as a comment rather than in the PR body: the body is owned by the no-mistakes pipeline, which writes the deterministic ## Pipeline section.

Merges 71 commits from kunchenguid/firstmate main (through fa0d85d) into this fork, preserving the semantics of the six changes landed here: #2 watcher hardening, #3 user-journey audits, #4 locale-invariant composer, #5 capacity dashboard, #6 dashboard redesign, #7 task-id contract.

A real merge commit with both parents. Nothing was rebased or force-pushed, and nothing was pushed to upstream.

Conflict resolutions

Eleven files conflicted. For each, which side's approach won and why:

bin/fm-watch-arm.sh - upstream baseline, our semantics ported on

Both sides independently fixed silent watcher arm-cycle death. Upstream's rewrite (kunchenguid#693, kunchenguid#997) is the better maintenance baseline and won structurally: the bounded lifecycle ledger in state/.watch-cycle-exits.log, the bounded wait_for_healthy_successor, an attached arm that follows identity-matched successors instead of exiting, and typed nonzero failures.

Four things from our PR 2 were ported onto it, because upstream has no equivalent:

Ported	Why it had to survive
state/.watcher-arm-dead marker on every FAILED path	bin/fm-guard.sh reads its detail= field to name a supervision gap on the next fleet action; upstream only signals on stdout, which is lost if nothing is reading it
Loud report + marker when a signal ends supervision with tasks in flight	Upstream's signal handlers only write a ledger row
Hardened child reap (TERM, wait, escalate to KILL, wait) before any successor check	A still-fresh dying child otherwise reads as a healthy successor and suppresses the alarm on Linux
Wake-sequence handoff check in attach_and_wait	An attached arm cannot read the watcher's output, so without it every normal wake handoff observed by a second attached arm is reported as an unexplained death

One PR 2 behavior was deliberately dropped: the idle exemption that exited 0 when no state/<id>.meta existed. Upstream fails loudly whenever an attached cycle ends without a successor, regardless of fleet size. That is the stronger reading of PR 2's own stated goal - supervision gaps must not be silent - and it closes a hole PR 2 left open, since an X-only home still needs a live cycle with no fleet work. Our two PR 2 tests were adapted to upstream's typed failure line while still asserting the marker and non-zero exit.

bin/fm-spawn.sh - both

Kept upstream's new per-task spawn lock and our diagnostic-emitting fm_task_id_creation_check, which names the charset or length reason instead of upstream's bare error: invalid task id.

Task-id minting - converged, no code change needed

The briefed expectation was that upstream had its own implementation to reconcile against. It does: fm_task_id_creation_valid (path-safe plus <= 64). Our fm-pr-lib.sh already exposes a function of that exact name and contract as a quiet wrapper over our diagnostic fm_task_id_creation_check, and FM_TASK_ID_MAX_LENGTH is 64, so upstream's callers (fm-herdr-session-cleanup.sh, tests/fm-pr-check-security.test.sh) work unchanged against ours. Upstream's name and contract are the baseline; our richer diagnostics sit underneath. Our captain-decision exemption in bin/fm-decision-hold.sh - a kind=captain hold may exceed the length limit as a non-dispatchable, never-truncated id, but must still be path-safe - is preserved intact, along with tests/fm-task-add.test.sh and tests/fm-decision-hold-lifecycle.test.sh.

bin/fm-fleet-snapshot.sh - union

Upstream added multi-blocker resolution (unresolved_blocker_ids, blocked_by_ids, hold_reason/hold_kind selection); PR 5/6 added capacity evidence (repo, kind, since, delivery_mode, project_resolved). Both are on both blocked-record projections now. Verified end-to-end that upstream's captain_actionable routing and our delivery_mode/order projection both survive.

docs/supervision-protocols/claude.md - upstream

Upstream's Stop-hook-owned supervision rewrite replaces manual background-task arming and already carries PR 2's requirement to treat a watcher-failure wake as an alarm, so nothing needed porting.

docs/herdr-backend.md - upstream restructure, our content re-homed

Upstream's kunchenguid#994 split current guidance from verification evidence, deleting ~650 lines of incident chronology in favor of a pointer. Taking that wholesale would have dropped PR 4's locale-invariance documentation, so it was re-homed: the behavior rule into "Composer and injection safety", its regression evidence into docs/verification/runtime-backends.md.

docs/architecture.md, docs/configuration.md - union

Both sides' additions kept; the herdr references in configuration.md were repointed at the sections that survived the split, so no reference dangles.

tests/fm-watcher-lock.test.sh, tests/fm-brief.test.sh, tests/fm-cd-pretool-check.test.sh - union

Both sides' new tests kept. Two of our watcher assertions were adapted: the attached-death test now expects upstream's typed failure line with our marker detail, and the unconfirmable-watcher test uses upstream's looser stdout assertion (upstream loosened it deliberately, because their refactor changed which FAILED line appears) plus our marker assertions.

.github/workflows/ci.yml

Bearings test count is 43 - the merged total (36 base + 1 ours + 6 upstream) - not either side's 37 or 42. Verified by running the suite, not by arithmetic alone.

Four upstream defects fixed here

The merged result could not go green without these. All four are pre-existing on upstream main and reproduce on a clean upstream/main tree; none was introduced by this merge. The first matches upstream issue kunchenguid#1179, which reports exactly this breakage at fa0d85d. Two of the four are the same root cause - code that assumes Bash 4+ while the repo ships a stock-macOS-Bash-3.2 CI lane.

1. bin/fm-brief.sh did not parse under stock macOS Bash 3.2 - no brief could be generated on macOS at all.

Bash 3.2 tracks quote state through a heredoc body while scanning for the closing paren of a command substitution, so a single apostrophe inside DOD=$(cat <<EOF ... EOF) makes the whole file unparseable. Upstream added firstmate's to one Definition-of-done body.

The repo already had a regression guard for this exact class (test_script_parses, from issue kunchenguid#166), but it ran bash -n against the PATH bash - Bash 4+ on most machines - so the regression sailed past it.

Fixed structurally rather than by avoiding apostrophes: each mode's Definition-of-done text moved into its own function body, where a heredoc parses normally. Upstream's wording is restored verbatim, so tests/fm-ask-user-authority.test.sh still passes. Also extended test_script_parses to check the stock interpreter when it differs from the PATH one, and added a CI step that parses every shipped script under macOS Bash 3.2.

2. tests/fm-bearings-snapshot.test.sh built a fixture with BSD-incompatible sed.

sed '/## In flight/a\' drops the newline after the appended text on BSD sed, gluing the ## Queued header onto the appended row. The corrupted backlog made the SSHHIP captain-hold assertion fail. Replaced with an equivalent awk append.

3. bin/fm-spawn.sh did not fail closed when it could not record task metadata.

The write used a bare redirect, and the script runs under set -u without set -e, so a failed write was ignored: it went on to print spawned <id> ... and exit 0 with no state/<id>.meta on disk. That record is what makes a worker supervisable - the watcher, recovery, and teardown all locate a task through it - so a successful-looking spawn could leave a live worker nothing was tracking. It now stops with a non-zero exit. tests/fm-backend-orca.test.sh already asserted this and was failing on upstream.

Endpoint teardown on that path remains owned only by the Orca and Herdr projection cleanup; see the pipeline-rounds section below for why per-backend rollback was deliberately left out of this change.

4. tests/fm-session-start.test.sh could never pass under stock macOS Bash 3.2.

Each of its 40 racer subshells read $BASHPID, which arrived in Bash 4.0. Under set -u that aborts every racer, so the exactly-one-winner session-lock assertion always saw zero winners. The fallback execs sh in the substitution subshell so its PPID is that racer's own pid; $$ would report the shared parent and defeat the race the test exists to prove.

Known environment prerequisite (not a code change)

tests/fm-calm-pi-extension.test.sh pins upstream's new Pi Calm work to Pi 0.81.1/0.82.0. This machine has 0.80.10, so two cases fail locally. They skip in CI, which does not install the Pi package, so this does not affect the PR's checks - but running Pi Calm mode from this sync needs a local Pi upgrade to 0.81.1 or newer. Left as-is rather than loosening upstream's deliberate compatibility guard.

Second merge: origin/main (#8) landed mid-flight

PR #8 (persistent tailnet-only dashboard service) merged into main while this sync was in flight. The validation pipeline's rebase step wanted to rebase onto it; that would have flattened the upstream merge commit whose two parents are the record of this sync, so it was integrated as a second merge instead. Re-running the pipeline afterwards, the rebase step passed as a no-op, confirming the integration.

Three conflicts. .gitignore and AGENTS.md were additive on both sides. bin/fm-fleet-snapshot.sh was substantive: #8 and upstream had independently grown multi-blocker support.

Side	Added
#8	blocked_by_all, plus captain-hold origin / decision-key extraction from the hold body
upstream	blocked_by_ids with resolution tracking via unresolved_blocker_ids

Both are emitted, because both have live consumers: bin/fm-capacity.mjs reads #8's fields, bin/fm-bearings-snapshot.sh reads upstream's.

The one genuine contract collision was the scalar blocked_by on parsed backlog records - upstream captured only the last blocker, #8 joined all of them with commas, and the merged test file asserted both against the same fixture shape. The join won on evidence rather than preference: fm-capacity.mjs:717 splits that scalar on commas, so it is the contract with real production code behind it, while upstream's single-value form appeared only in test expectations and its information survives intact in blocked_by_ids. Three upstream assertions were updated and still pin the structured fields alongside.

Captain-hold selection keeps upstream's stricter captain_actionable predicate, so a captain hold that is itself blocked stays queued rather than surfacing as actionable, with #8's origin and decision-key extraction layered on top. docs/dashboard-service.md from #8 was classified maintainer-architecture in the audience inventory, which the merged tree otherwise failed its own completeness check on.

A note on the watcher shutdown-latency commit

Two commits here touch cleanup_child's TERM handling, and the second one's message overstates its case. The failure that prompted them - tests/fm-watcher-lock.test.sh's HUP regression timing out - was not a code defect. It was an artifact of running the suite under nohup, which sets SIGHUP to ignored and passes that disposition to every descendant, so the test's kill -HUP was silently discarded and the arm never exited. Instrumenting the signal handler showed it receiving only TERM, never a single HUP; the same test through the same runner in the foreground is 29/29 green.

What survives on its own merit is the latency change. The intermediate commit replaced the original bounded poll with an unbounded blocking wait, which sat through a whole FM_POLL interval because Bash defers the watcher's TERM trap until its sleep returns - measured at 5-6s against the regression's 8s budget, via a direct probe unaffected by the nohup issue. The bounded 1s grace brings that to 1-2s. So the net effect against the merge baseline is a real improvement in shutdown latency and margin, but it should be read as that, not as a bug fix.

Verification

• Full suite via bin/fm-test-run.sh --all: 103/103 files, 3 failures, all environment-only (see below). Run without nohup, so the HUP-dependent watcher tests genuinely exercise their signal.
• bin/fm-lint.sh: clean (pinned ShellCheck 0.11.0).
• Every bin/*.sh and bin/backends/*.sh parses under stock macOS Bash 3.2.
• Every skill named in AGENTS.md section 13 resolves to a real SKILL.md; both sides' skills coexist.
• No files lost from either side; upstream's deletion of the vestigial dispatch selector (fix(bin): remove vestigial dispatch selector kunchenguid/firstmate#1026) applied cleanly with no dangling references.

The three remaining failures are local toolchain shortfalls, not code, and all skip in CI:

Test	Needs
fm-calm-pi-extension	Pi 0.81.1+ (this machine: 0.80.10)
fm-kimi-harness	Python 3.11+ for tomllib (this machine: 3.9.6)
fm-secondmate-harness	No claude process ancestry; resolves the real host harness

Validation-pipeline rounds

The review step raised one finding against this branch's own spawn fix: the comment claimed the abort cleanup owns backend teardown, when spawn_abort_cleanup only removes Orca resources and Herdr presentation projections. It suggested tracking and rolling back endpoint creation for every backend plus atomic metadata publication.

That was scoped deliberately. The comment correction was taken. Per-backend endpoint rollback across tmux, flat Herdr, Zellij, and cmux was declined as a rider on an upstream sync - the residual gap predates this branch, and before the fail-closed fix the same failure reported a successful spawn and exited 0, so an untracked endpoint was strictly more likely, not less. It deserves its own task and tests.

Atomic publication was attempted and then backed out, because it broke two upstream structural guards that pin the expected source shape of bin/fm-spawn.sh:

• tests/fm-gotmp.test.sh requires the literal echo "tasktmp=$TASK_TMP".
• tests/fm-backend-herdr.test.sh requires the literal } > "$STATE/$ID.meta" to appear after the lock acquisition and after the backend case, proving the lock spans backend creation through metadata publication.

A temp-file-and-rename necessarily changes both. Rewriting upstream's invariant guards to accommodate optional hardening is a poor trade inside a large sync, and the fail-closed fix alone was already green across the full suite. The atomicity idea can be taken up separately, updating those guards deliberately.

A third failure in that round, tests/fm-backend-tmux-smoke.test.sh, was a 10-second live-tmux readiness wait failing under pipeline load; it passes 7/7 on an idle machine and was left alone. The two environment failures were explicitly excluded from the fix instructions so the pipeline could not "resolve" them by weakening upstream's Pi and Python version guards.