feat(bin): sync fork with upstream firstmate main

[remicaesar]

Intent

sync my fork with upstream

Context: the fork remicaesar/firstmate (remote origin) is at 3e1ee94, 5 commits behind upstream kunchenguid/firstmate (remote upstream, main at e5b9ddd) and 6 commits ahead with fork-only fixes (a macOS Bash 3.2 fix for fm_exec_timed, a supervision-engine test link, and an armed-PR-poll readability fix). The 5 upstream commits are: e5b9ddd worker-role skill-file fallback (kunchenguid#6647), 6a7b391 start tasks from a named base branch (kunchenguid#6442), 98d80a1 opt-in no-mistakes spend recording at teardown (kunchenguid#5354), f470a01 faster remote-job sequence claim cleanup (kunchenguid#6575), 9ea0c41 prevent unnecessary remote worker turnover (kunchenguid#6431). The previous sync (#2) found an upstream change that broke on this Mac's stock /bin/bash 3.2.57, so the running fleet stays on the current main until the synced tree is proven.

What Changed

• Merges 5 upstream commits into the fork. The fork's existing fixes stay as they were.
• Base branch: fm-brief.sh --base-branch and fm-spawn.sh can now start a task from a named base branch. The spawn resets the pooled copy to origin/<base> and records base_branch= in the task meta. The worker opens its PR against that branch, and review diffs, cleanup and scout promotion read the recorded base. Deliveries that are local-only or go to Gerrit refuse a named base.
• Spend recording: a new script, bin/fm-pipeline-spend.sh, records each ship task's no-mistakes pipeline spend at teardown. It is opt-in: it only runs when config/pipeline-spend exists, and it writes to data/pipeline-spend.jsonl. fm_nm_state_db is now the only place that decides where the no-mistakes state database lives.
• Remote jobs: the remote-job worker and its LaunchAgent no longer replace a healthy worker; LaunchAgent repair is serialized, and the worker checks owners that launchd is tracking. Expired .seq-claims directories are cleaned up in a single find walk.
• Other fixes: test fixture registries are kept out of git worktree roots. The worker role names the Firstmate skill file as a fallback.
• Adds tests and docs for each of these changes.

🤖 Generated with Claude Code

Risk Assessment

⚠️ Medium: The merge is clean, but it brings in about 2,400 lines of upstream shell code, including changes to the LaunchAgent remote-worker lifecycle and to spawn and teardown. The intent says this code has to be proven on stock /bin/bash 3.2.57 before the fleet moves to it, and that runtime proof belongs to the later test step.

Testing

I ran every test file the upstream sync touches, plus the fork's fm_exec_timed regression test, under the Mac's stock /bin/bash 3.2.57. That shell is the one that broke the previous sync. All 13 files passed. They cover the five upstream changes: the worker-role skill fallback in brief, named-base-branch spawn and review-diff, opt-in pipeline-spend recording at teardown, faster remote-job claim cleanup, and the remote worker turnover fix. The fork's Bash 3.2 fix still holds after the merge. I also ran the new fm-pipeline-spend.sh command by hand under Bash 3.2. Its usage output and exit codes were correct, and with recording disabled it exits 0. There is no UI surface, so there are no screenshots.

Evidence: Bash 3.2 results for each changed test file (all 13 pass)

Source: Bash 3.2 results for each changed test file (all 13 pass)

== fm-brief rc=0 (13s) ok - fm-brief.sh: every crewmate scaffold forbids administering the shared worktree pool
== fm-dod-lib rc=0 (5s) all fm-dod-lib tests passed
== fm-pipeline-spend rc=0 (4s) ok - missing tasks, secondmates, and unsafe ids are refused
== fm-remote-job-claim-reap rc=0 (5s) ok - a due claim sweep over ~17460 dirs does not starve job serving
== fm-remote-job-claim-retention rc=0 (0s) ok - claim sweep preserves numeric-name eligibility and whole-second expiry
== fm-remote-job-launchagent rc=0 (90s) ALL TESTS PASSED
== fm-remote-job rc=0 (153s) ALL TESTS PASSED
== fm-review-diff rc=0 (4s) ok - fm-review-diff compares a task against its recorded base branch
== fm-spawn-dispatch-profile rc=0 (300s) # all fm-spawn-dispatch-profile tests passed
== fm-spawn-pool-base-freshen rc=0 (107s) # all fm-spawn-pool-base-freshen tests passed
== fm-teardown rc=0 (280s) ok - the run abort and the leaked-process reap both complete before the destructive worktree return
== fm-test-fixture-cleanup rc=0 (1s) ok - test registries and fixture roots stay out of a git worktree TMPDIR
== fm-timeout-lib rc=0 (11s) ok - fm_timed_out accepts 124 and 137 and nothing else

Evidence: fm-pipeline-spend.sh CLI run under /bin/bash 3.2

Source: fm-pipeline-spend.sh CLI run under /bin/bash 3.2

$ /bin/bash --version | head -1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin25)
$ /bin/bash bin/fm-pipeline-spend.sh
fm-pipeline-spend.sh - attribute a task's no-mistakes pipeline spend to the
task and keep it in Firstmate's own records.

Usage:
  fm-pipeline-spend.sh record <task-id>

record appends the task's pipeline spend as one JSON object on one line of
data/pipeline-spend.jsonl, at most once per task incarnation (task id plus
the record's spawn_gen): repeating it for an incarnation already in the
ledger appends nothing, so a retried cleanup never counts a task twice.
Recording is disabled unless config/pipeline-spend is present; in that case
this command exits before reading task metadata, no-mistakes state, or ledger.
When enabled, bin/fm-teardown.sh calls record for every ship task whose
local copy it cleans up, before it deletes the task branch this script
attributes runs by and before it removes state/<id>.meta. The ledger is
private and gitignored with the rest of data/.
Exit status: 0 when a record was recorded or already present, its source is
unavailable, or recording is disabled; 1 when the task record is missing,
names a secondmate, or the record could not be built or written; 2 for bad usage.

Source. no-mistakes keeps each agent invocation's token usage only in its
local state database, one agent_invocations row per invocation; its
environment reference documents those fields, and `no-mistakes stats --run
<id>` renders the same rows as a human table. There is no machine-readable
export yet, so this script reads the database read-only (mode=ro), located
by bin/fm-nm-run-lib.sh's fm_nm_state_db, and bounded by 30 seconds per
no-mistakes or database call.

Attribution. A task's runs are the runs no-mistakes recorded for the task
copy's repository and current branch since that branch was created:
  - repository: the `repo:` line `no-mistakes axi` prints from the task copy,
    which is the CLI's own resolution (a pooled worker copy resolves to the
    registered primary clone), matched exactly against repos.working_path;
  - branch: the task copy's current branch, the one bin/fm-crew-state.sh
    reads;
  - since: the oldest surviving reflog entry of that branch. spawn_gen cannot
    bound the task, because a relaunch mints a new one while the same branch
    keeps validating. Teardown deletes the branch, so a later task that
    reuses the id and branch name starts a fresh reflog and never inherits an
    earlier task's runs. With no reflog, every run on the branch counts and
    since is null.
Two live tasks sharing one branch name in one repository would both count
its runs; each record lists run ids, so such an overlap stays visible.

Counting. Every invocation of those runs counts, whatever its exit status
(ok, error, cancelled), and each token field is no-mistakes' own, summed
without reinterpretation (whether input includes cache reads differs by
agent; see no-mistakes' environment reference):
  - input_tokens, output_tokens, cache_read_tokens sum the per-round
    delta_* columns, because a resumed session's raw counters are cumulative
    for some agents (codex) and summing them would count earlier review
    rounds again. A row with no delta (written before the delta columns
    existed) falls back to its raw counter only when its session_mode is not
    `resumed`, since no-mistakes defines a cold, started, or fallback row's
    delta as its raw counter.
  - cache_creation_tokens sums the raw counter, which has no per-round
    delta, so it counts only for a row whose counters are proven
    per-invocation: not resumed, or every delta equal to its raw counter.
  - reasoning is not summed: no-mistakes counts it inside output and keeps no
    per-round delta for it.
A value no-mistakes did not record is unknown, never zero: each token field
carries its known total and how many invocations were unknown, so a total
with unknown > 0 is a lower bound.

Record schema (this header is its one owner). One JSON object:
  task, spawn_gen         the task id and the incarnation recorded in its meta
  recorded_at             UTC time the record was built
  source                  "no-mistakes-state", or "unavailable" when the runs
                          could not be read; reason then says why, total
                          is null, and runs and purposes are empty
  repo, branch, since     the attribution above (since as UTC time or null)
  total                   a tally over every counted invocation
  runs[]                  {id, status, created_at} plus a tally, oldest first
  purposes[]              {purpose} plus a tally, by no-mistakes' purpose
                          name (review, review-fix, test, document, ci, ...)
A tally is {invocations, exit: {<exit status>: count}, duration_ms,
input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens}, and
each token field is {total, unknown}.
exit=2
$ /bin/bash bin/fm-pipeline-spend.sh record demo-task   # recording disabled (no config/pipeline-spend)
exit=0
$ /bin/bash bin/fm-spawn.sh t1 /tmp --relaunch --base-branch dev 2>&1 | head -3
error: no-mistakes gate agent must not drive the fleet (NO_MISTAKES_GATE set)

Full-suite results on stock macOS Bash 3.2.57

All 248 test scripts were run locally under /bin/bash 3.2.57 (the only bash on the host), sharded as CI does: portable-parallel-1, portable-parallel-2, portable-serial and real-herdr-gated.
A /bin/bash -n parse sweep of all 458 shell scripts found no failures, and bin/fm-lint.sh exits 0 once the pinned actionlint 1.7.12 is installed.
The incoming diff was also audited for Bash 4+ constructs; none needed a fix.

Nine scripts failed in the lane runs.
Three passed when re-run after the cause was removed: fm-lint-workflows needed actionlint, while fm-remote-reply and fm-spawn-compact-adviser-disable-remote were timing flakes.
Six failures are pre-existing: each fails with the same assertion on unmodified fork main 3e1ee94 and on upstream main e5b9ddd, so the merge introduced none of them.

Test	Failing assertion	Likely cause
fm-afk-return	evidence publication failure should retain catch-up	pre-existing on both baselines
fm-cursor-harness	a real cursor-agent ancestor must detect cursor	process-ancestry detection on this host
fm-harness-precedence	codex ancestry alone resolved ''	process-ancestry detection on this host
fm-muse-harness	fm-harness.sh under a muse process reported ''	process-ancestry detection on this host
fm-gate-refuse	tmux is required for the lab socket behavioral test	tmux not installed
fm-procevent	could not read the draining holder's identity	pre-existing on both baselines

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - medium risk

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• /bin/bash tests/fm-brief.test.sh (pass)
• /bin/bash tests/fm-dod-lib.test.sh (pass)
• /bin/bash tests/fm-pipeline-spend.test.sh (pass)
• /bin/bash tests/fm-remote-job-claim-reap.test.sh (pass)
• /bin/bash tests/fm-remote-job-claim-retention.test.sh (pass)
• /bin/bash tests/fm-remote-job-launchagent.test.sh (pass)
• /bin/bash tests/fm-remote-job.test.sh (pass)
• /bin/bash tests/fm-review-diff.test.sh (pass)
• /bin/bash tests/fm-spawn-dispatch-profile.test.sh (pass)
• /bin/bash tests/fm-spawn-pool-base-freshen.test.sh (pass)
• /bin/bash tests/fm-teardown.test.sh (pass)
• /bin/bash tests/fm-test-fixture-cleanup.test.sh (pass)
• /bin/bash tests/fm-timeout-lib.test.sh (pass; the fork's fm_exec_timed Bash 3.2 fix)
• Ran the CLI by hand under /bin/bash 3.2: bin/fm-pipeline-spend.sh with no arguments prints its usage text and exits 2; fm-pipeline-spend.sh record demo-task with recording disabled exits 0

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 1)

✅ **Push** - passed

✅ No issues found.