feat(bin): report watched tooling updates that are available or installed but inert

[Inthuson]

Intent

Add a periodic check that tells firstmate when tooling this home depends on has an update available, and, just as importantly, when an update was installed but did not take effect.

The motivating incident: on 2026-08-20 the captain updated Herdr. It self-installed correctly to ~/.local/bin/herdr at 0.8.2, but mise also managed Herdr with its own 0.8.0 copy, and mise's install dir sits at PATH position 9 while ~/.local/bin sits at 18, so command -v herdr still resolved to 0.8.0. The running Herdr server spoke protocol 20 and the stale client spoke 19, so every Herdr command failed with protocol_mismatch, and firstmate could not read its own fleet and reported two live workers as stopped. mise could not even offer 0.8.2 because its minimum_release_age gate hid the release. The update was installed and inert. A check that only asks "is a newer version published" would have reported everything up to date and missed this completely. Detecting that second case is the point of this task, not a nice-to-have.

Acceptance criteria the captain set:

1. A local registry of watched tools in config/, gitignored and local, never shipped to another home, firstmate-maintained but human-editable in the same spirit as config/crew-dispatch.json. Adding a tool must be a config edit, never a code change.
2. One script under bin/ that performs the check and prints nothing when everything is current, so it composes with firstmate's existing check-and-wake mechanism instead of needing a new one.
3. Report the two conditions distinctly: an update is available, and PATH skew where the version that actually resolves on PATH is not the newest copy installed on this host. Detect skew by asking every PATH hit for its own version and comparing them. Do not trust a single lookup, and do not infer a version from a directory name, because the incident's directory said "latest" while containing 0.8.0.
4. Cover at least four tools with their real update sources: firstmate itself (commits behind origin default in its clone), AgentsOnTheGo (commits behind origin/mainline), Herdr (the self-updating binary in ~/.local/bin against any other copy on PATH including a mise-managed one, the PATH-skew case), and no-mistakes (it already announces "A new version of no-mistakes is available: vX -> vY", so read that rather than reimplementing its version lookup).
5. Do not nag: the same pending update must not be reported on every poll. Reuse firstmate's existing state-check and wake contract, including its trust registration, rather than inventing a scheduler.
6. Colocated tests, including a regression that fails if the PATH-skew case goes undetected. That test is the deliverable's whole justification, so it must prove the point rather than assert that a call happened. A test that passes against a build with the skew detection removed is worthless.
7. shellcheck-clean at the pinned version.

Constraints the captain stated, which explain choices that would otherwise look surprising in the diff:

• This is firstmate's own shared tracked material, so the firstmate-coding-guidelines contract applies.
• Do not change the captain's mise configuration, PATH, or any installed tool. Detecting skew is this task's job. Fixing it is not, and a check that silently repaired the host would be worse than the problem. So the script reports and repairs nothing: it never installs, updates, uninstalls, reorders PATH, touches a version manager, or fetches into a watched repository, and every git probe is read-only.
• Do not issue any Herdr lifecycle command. Reading a version is fine. A live Herdr daemon and the captain's live fleet run on this host and nothing may disturb them.
• No em-dashes anywhere, including code comments, docs, and the commit message. Plain, simple, human-readable code and documentation, one sentence per line in docs, and no invented vocabulary.
• Never add an agent name as a commit co-author.

Decisions and tradeoffs made while doing the work:

• PATH skew is measured, never inferred. Every executable copy of a watched command on PATH is probed for its own version and those answers are compared. Copies are deduplicated by device and inode, so one install reached through a symlinked bin directory does not report skew against itself. A copy that will not report a version is a check failure rather than an assumed pass.
• The check rides the existing watcher state-check contract: arm writes state/tool-updates.check.sh and binds its bytes with bin/fm-check-register.sh, so the existing watcher polls it on its normal cadence and turns its one line into a check wake. No new scheduler, and no separate daemon.
• Deliberately not auto-armed from bin/fm-bootstrap.sh. Auto-arming would add a seventh documented mutating bootstrap sweep and would require editing the always-loaded AGENTS.md session-start contract, which is a much larger blast radius than this task needs. Firstmate arms once per home instead, and that is documented.
• Deliberately not added to the inherited-config set, because criterion 1 requires the registry never be shipped to another home. config/ is already gitignored wholesale, so no gitignore change was needed.
• Registry records are joined with the unit separator rather than a tab, because tab is IFS whitespace and read would collapse the empty fields an optional key leaves behind.
• The one-line report is cut through the shared bounded-line owner (bin/fm-line-cap-lib.sh) so an over-long report carries the repo's standard visible truncation marker instead of ending mid-finding as if that were all of it. A wider max than the digest default is used on purpose, because a single skew finding names two absolute paths and two versions.
• The finding is printed before the report record is written, so a record that cannot be written costs a repeated report rather than a lost one. A sweep killed part way through writes no record and is retried.
• Optional announce_args was added after live probing showed a real gap: no-mistakes --version prints the version but not the update announcement, while its other commands carry it. Without a second probe command the no-mistakes source in criterion 4 would silently never fire. The announcement probe is asked only of the copy PATH resolves.
• The git default-branch resolution gained a bounded read-only ls-remote --symref fallback after a live single-branch clone with no local record of origin HEAD produced a check failure the operator could not act on.
• Environment override seams follow the repo's existing pattern (FM_HOME, FM_STATE_OVERRIDE, FM_CONFIG_OVERRIDE) and two unused seams were removed rather than left as dead configuration.
• Tests are classified into the watcher-wake-lock family in bin/fm-test-run.sh because the suite drives the real watcher checkpoint end to end.
• The PATH-skew regression was verified by mutation, not just by passing: replacing the skew report with a no-op, and stopping after the first PATH hit as a single lookup would, each make that test fail. Removing the second announcement probe likewise fails its test.
• docs/configuration.md is declared the single owner of the registry schema, and the copyable example is registered in docs/documentation-audiences.json as an operator example.

Two pre-existing environment gaps were deliberately left alone, because fixing either would require installing a tool or changing the captain's mise configuration, which the captain forbade: actionlint is absent on this host (so the workflow lint tests cannot run), and tasks-axi resolves to a mise shim with no version set (so the decision-hold and bearings-board tests fail). Both reproduce identically from a pristine default-branch tree, so they are not caused by this change.

What Changed

• Added bin/fm-tool-update-check.sh, a read-only check that reads the tools this home depends on from local, gitignored config/watched-tools.json and prints one bounded line only when something needs attention. It reports two distinct conditions: <tool> update available from an update source (commits behind a remote branch for a local clone, or a tool's own update announcement matched by announce_pattern, optionally probed via a separate announce_args command), and <tool> update not in effect when a newer copy is installed but PATH still resolves an older one. Skew is measured by running every executable copy of the command found on PATH and comparing the versions each one reports, deduplicated by device and inode; a copy that will not report a version is a check failure rather than an assumed pass. The script never installs, updates, reorders PATH, touches a version manager, or fetches into a watched repo.
• arm writes state/tool-updates.check.sh and binds its bytes through bin/fm-check-register.sh so the existing watcher polls it on its normal cadence, and disarm removes the shim, its trust binding, and the record. Findings are recorded uncut in state/.tool-updates after a sweep completes so a pending update is reported once instead of on every poll, while a changed or returning condition reports again. Probe sweeps are gated by FM_TOOL_UPDATE_INTERVAL and bounded by FM_TOOL_UPDATE_PROBE_SECS and FM_TOOL_UPDATE_BUDGET_SECS, with the sweep budget cut down to what FM_CHECK_TIMEOUT allows (and the cut named in the report) so a killed run cannot silently swallow a finding.
• Added tests/fm-tool-update-check.test.sh (74 cases, classified into the watcher-wake-lock family in bin/fm-test-run.sh), including test_path_skew_is_reported_from_every_copy, which stages an older copy earlier on PATH than a newer one and asserts the exact skew line with both paths and versions, plus negative cases that a published update is not reported as skew, that two copies of the same version are not skew, and that one broken announce_pattern does not suppress another tool's skew report. Documented the registry schema in docs/configuration.md as its single owner, added the copyable docs/examples/watched-tools.json registered as an operator example, and listed the script and its config and state entries in docs/scripts.md and AGENTS.md.

Risk Assessment

✅ Low: The change is additive (one new script that only runs once armed, one new test file, docs, and two single-line registrations), every acceptance criterion I could verify from source holds, I reproduced the key behaviors myself including the fix round's newest claim, and the only remaining findings are documentation accuracy and one untested-but-non-silent safety branch.

Testing

Ran the colocated suite and the two suites owning the other changed files (59 cases, all passing), then proved the deliverable's justification by mutation: removing the skew report, reducing probing to a single PATH lookup, and removing the second announcement probe each make the relevant test fail, and the worktree was restored to HEAD after each. Product-level verification on this host reproduced the 2026-08-20 incident against the real herdr binary (the report names 0.8.0 at the version-manager copy and 0.8.2 at ~/.local/bin, reported once, then silent, then silent again once cleared), swept the four real update sources including the host's genuine no-mistakes v1.46.0 -> v1.53.0 announcement read from --help, and drove the armed check through the real watcher to a check wake. I also confirmed the sweep repairs nothing (one herdr --version invocation, watched clones byte-identical) and that the registry is gitignored and never inherited. No screenshots apply: this change has no rendered surface, so CLI transcripts of the check, the watcher wake, and the shim are the end-user surface. The only failing test I saw, fm-lint-workflows, fails because actionlint is absent on this host and is unrelated to this change.

Evidence: End-to-end CLI transcript: registry, four real sources, incident reproduction, no-nag, read-only proof, armed watcher wake

########## 1. the watched tool registry an operator edits (config/, local, gitignored)

$ cat config/watched-tools.json
{
  "tools": [
    { "name": "firstmate", "git": { "repo": "/tmp/no-mistakes-evidence/01M0FM08RBH7MKKX9N7ZZWF5GG/demo/firstmate-clone", "remote": "origin" } },
    { "name": "agents-on-the-go", "git": { "repo": "/tmp/no-mistakes-evidence/01M0FM08RBH7MKKX9N7ZZWF5GG/demo/agents-on-the-go", "remote": "origin", "branch": "mainline" } },
    { "name": "herdr", "command": "herdr", "version_args": ["--version"] },
    { "name": "no-mistakes", "command": "no-mistakes", "version_args": ["--version"],
      "announce_args": ["--help"],
      "announce_pattern": "A new version of no-mistakes is available: [^ ]+ -> [^ ]+" }
  ]
}
$ git check-ignore -v config/watched-tools.json
.gitignore:13:config/	config/watched-tools.json

########## 2. one sweep over the four real update sources

$ FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check
tool updates: firstmate update available: local main is 3 commits behind origin/main; agents-on-the-go update available: local mainline is 2 commits behind origin/mainline; no-mistakes update available: A new version of no-mistakes is available: v1.46.0 -> v1.53.0

(herdr is silent: this host has one copy on PATH and it is the newest one.
 no-mistakes announces its own update on --help, not on --version, so
 announce_args asks the command that carries it.)

########## 3. the 2026-08-20 incident: an update that installed but never took effect

A version-manager copy of herdr is put back at PATH position 1, in a
directory named "latest" that holds 0.8.0, while the real self-installed
0.8.2 stays where it is at ~/.local/bin.

$ command -v herdr; herdr --version   # everything a single lookup can know
/tmp/no-mistakes-evidence/01M0FM08RBH7MKKX9N7ZZWF5GG/demo/incident/mise/installs/herdr/latest/herdr
herdr 0.8.0
$ /home/inthuson/.local/bin/herdr --version   # the newest copy installed here
herdr 0.8.2

A check that only asks "is a newer version published" sees 0.8.0 and the
newest release the version manager will offer, and reports nothing.

$ FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check   # poll 1
tool updates: herdr update not in effect: PATH resolves 0.8.0 at /tmp/no-mistakes-evidence/01M0FM08RBH7MKKX9N7ZZWF5GG/demo/incident/mise/installs/herdr/latest/herdr but 0.8.2 is installed at /home/inthuson/.local/bin/herdr

$ FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check   # poll 2, same condition
(no output: the same pending update is not reported twice)

$ FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check   # stale copy removed
(no output: PATH resolves the newest copy again)

########## 4. it reports and repairs nothing

$ every herdr invocation the sweep makes, with the only herdr on PATH recorded
tool updates: firstmate update available: local main is 3 commits behind origin/main; agents-on-the-go update available: local mainline is 2 commits behind origin/mainline
herdr --version
(one version read, no Herdr lifecycle command)

$ the watched clones before vs after the sweep
identical: refs, HEAD, working tree, FETCH_HEAD, reflog, object count

########## 5. armed once per home, then polled by the existing watcher

$ bin/fm-tool-update-check.sh arm
armed: state/tool-updates.check.sh
$ cat state/tool-updates.check.sh
#!/usr/bin/env bash
# Auto-generated by fm-tool-update-check.sh - watched tool update poll shim.
# The watcher validates these bytes, then dispatches the trusted check script.
export FM_HOME=/tmp/no-mistakes-evidence/01M0FM08RBH7MKKX9N7ZZWF5GG/demo/home-armed
exec /local/home/inthuson/.no-mistakes/worktrees/d4c7ad84348d/01M0FM08RBH7MKKX9N7ZZWF5GG/bin/fm-tool-update-check.sh check
$ head -1 state/tool-updates.check-trust
fm-custom-check-v1

$ bin/fm-watch-checkpoint.sh --seconds 10   # the real watcher, no new scheduler
check: /tmp/no-mistakes-evidence/01M0FM08RBH7MKKX9N7ZZWF5GG/demo/home-armed/state/tool-updates.check.sh: tool updates: herdr update not in effect: PATH resolves 0.8.0 at /tmp/no-mistakes-evidence/01M0FM08RBH7MKKX9N7ZZWF5GG/demo/incident/mise/installs/herdr/latest/herdr but 0.8.2 is installed at /home/inthuson/.local/bin/herdr

########## 6. the registry is never shipped to another home

$ . bin/fm-config-inherit-lib.sh; fm_config_inherit_items
config/crew-dispatch.json
config/crew-harness
config/backlog-backend
config/backend
config/herdr-presentation-spaces
config/startup-memory-budget
config/trace-context
data/captain-shared.md
(config/watched-tools.json is not in the inherited set)

Evidence: Mutation proof that the PATH-skew regression fails when skew detection is removed

===== mutation A: skew report replaced with a no-op ===== - emit "$name update not in effect: PATH resolves ... but ... is installed at ..." + : # mutation A: skew report removed not ok - PATH skew was not reported as an update that is not in effect --- test script exit=1 (non-zero means the mutation was caught) --- ===== mutation B: stop after the first PATH hit (single lookup) ===== + break # mutation B: stop after the first PATH hit not ok - PATH skew was not reported as an update that is not in effect --- test script exit=1 --- ===== mutation C: the second announcement probe is removed ===== - if [ "$announce_args" != "$args_joined" ]; then + if false; then not ok - the announcement was not read from the command that carries it --- test script exit=1 --- ===== worktree restored ===== bin/fm-tool-update-check.sh is back to its committed bytes

===== mutation A: skew report replaced with a no-op =====
 1 file changed, 1 insertion(+), 1 deletion(-)
-    emit "$name update not in effect: PATH resolves $resolved_version at $resolved_path but $best_version is installed at $best_path"
+    : # mutation A: skew report removed
--- test result ---
not ok - PATH skew was not reported as an update that is not in effect (missing: 'herdr update not in effect')
--- test script exit=1 (non-zero means the mutation was caught) ---

===== mutation B: stop after the first PATH hit (single lookup) =====
 1 file changed, 1 insertion(+)
+    break # mutation B: stop after the first PATH hit
--- test result ---
not ok - PATH skew was not reported as an update that is not in effect (missing: 'herdr update not in effect')
--- test script exit=1 (non-zero means the mutation was caught) ---

===== mutation C: the second announcement probe is removed =====
 1 file changed, 1 insertion(+), 1 deletion(-)
-    if [ "$announce_args" != "$args_joined" ]; then
+    if false; then # mutation C: second announcement probe removed
--- test result ---
ok - a copy that reports no version is a check failure, not a pass
ok - a watched command missing from PATH is reported
ok - a tool's own update announcement is read from its output
not ok - the announcement was not read from the command that carries it (missing: 'no-mistakes update available: A new version of no-mistakes is available: v1.46.0 -> v1.53.0')
--- test script exit=1 (non-zero means the mutation was caught) ---

===== worktree restored =====
bin/fm-tool-update-check.sh is back to its committed bytes

Evidence: The two conditions on real sources, and the incident reproduced against the real herdr binary

$ FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check
tool updates: firstmate update available: local main is 3 commits behind origin/main; agents-on-the-go update available: local mainline is 2 commits behind origin/mainline; no-mistakes update available: A new version of no-mistakes is available: v1.46.0 -> v1.53.0

$ command -v herdr; herdr --version # everything a single lookup can know
/tmp/.../demo/incident/mise/installs/herdr/latest/herdr
herdr 0.8.0
$ /home/inthuson/.local/bin/herdr --version # the newest copy installed here
herdr 0.8.2

$ FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check # poll 1
tool updates: herdr update not in effect: PATH resolves 0.8.0 at /tmp/.../demo/incident/mise/installs/herdr/latest/herdr but 0.8.2 is installed at /home/inthuson/.local/bin/herdr

$ FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check # poll 2, same condition
(no output: the same pending update is not reported twice)

Evidence: The armed check arriving at the real watcher as an ordinary check wake

$ bin/fm-tool-update-check.sh arm
armed: state/tool-updates.check.sh
$ head -1 state/tool-updates.check-trust
fm-custom-check-v1
$ bin/fm-watch-checkpoint.sh --seconds 10 # the real watcher, no new scheduler
check: /tmp/.../demo/home-armed/state/tool-updates.check.sh: tool updates: herdr update not in effect: PATH resolves 0.8.0 at /tmp/.../demo/incident/mise/installs/herdr/latest/herdr but 0.8.2 is installed at /home/inthuson/.local/bin/herdr

Evidence: Read-only proof: every herdr invocation the sweep made, and the watched clones before vs after

$ every herdr invocation the sweep makes, with the only herdr on PATH recorded
herdr --version
(one version read, no Herdr lifecycle command)

$ the watched clones before vs after the sweep
identical: refs, HEAD, working tree, FETCH_HEAD, reflog, object count

Evidence: Targeted test log (fm-tool-update-check, fm-documentation-audiences, fm-test-run)

FM_TEST_SUMMARY total=3 failed=0 skipped_gate=0 duration_ms=28185

FM_TEST_BEGIN 2026-08-20T15:30:08Z tests/fm-tool-update-check.test.sh family=watcher-wake-lock expected_gate_skip=none
ok - PATH skew is reported by asking every copy on PATH for its own version
ok - no report when PATH already resolves the newest installed copy
ok - two copies of the same version are not skew
ok - one copy reached through two PATH entries is probed once as one install
ok - a copy that reports no version is a check failure, not a pass
ok - a watched command missing from PATH is reported
ok - a tool's own update announcement is read from its output
ok - an announcement carried by another command is read from that command
ok - an announce_pattern that cannot be used is reported instead of read as silence
ok - a broken pattern is reported for its own tool and the rest of the sweep still reports
ok - an announcement source the budget could not reach is reported, not read as current
ok - an announcement probe that does not answer is reported, not read as current
ok - a tool that announces nothing stays silent
ok - commits behind the origin branch are reported without touching the repository
ok - an omitted branch is detected from the remote's default branch
ok - the default branch is asked of the remote when the clone has no local record
ok - a repository that is current or ahead of its origin branch is silent
ok - an unusable git source is reported as a check failure
ok - a remote that cannot be read is reported as unreadable, not as a missing branch
ok - a branch a readable remote does not have is still reported as missing
ok - git probes stop and name their tool once the sweep budget is gone
ok - a git probe that does not answer is reported as a failure, never as an update
ok - a stalled repository probe is reported as no answer, not as not a repository
ok - no watched tool registry means no output at all
ok - a malformed registry is reported instead of quietly skipped
ok - the same pending update is reported once, and a change is reported again
ok - an over-long report is cut with the shared truncation marker
ok - a finding that lands past the cut is still reported as news
ok - probes run once per interval, not on every poll
ok - a budget that cannot fit the watcher bound is cut and reported, and the sweep keeps working
ok - an out of range bound or unknown action refuses instead of guessing
ok - arm registers a trusted check and disarm removes every trace
ok - a symlink at the shim path is refused instead of followed
ok - a failed registration never leaves a shim without a matching trust binding
ok - a re-arm that loses the trust binding leaves no shim behind
ok - a relative home is resolved before it is persisted into the shim
ok - the armed check reaches the watcher as an ordinary check wake
FM_TEST_END 2026-08-20T15:30:20Z tests/fm-tool-update-check.test.sh exit=0 duration_ms=12348 gate_skip=false
FM_TEST_BEGIN 2026-08-20T15:30:20Z tests/fm-documentation-audiences.test.sh family=pure-contract-unit expected_gate_skip=none
ok - documentation inventory classifies every maintained prose surface exactly once
ok - classification, setup routing, and maintained-prose scope fail safely
ok - required documentation owner pointers cannot silently disappear
ok - local links resolve while dates, versions, commands, and incident prose remain semantically reviewed
FM_TEST_END 2026-08-20T15:30:21Z tests/fm-documentation-audiences.test.sh exit=0 duration_ms=762 gate_skip=false
FM_TEST_BEGIN 2026-08-20T15:30:21Z tests/fm-test-run.test.sh family=pure-contract-unit expected_gate_skip=none
ok - exact suite coverage: --all lists every tests/*.test.sh once
ok - family selection returns a proper subset of the suite
ok - single-script selection lists exactly that path
ok - changed-file selection stays conservative (never silent full suite)
ok - changed selection covers dependents and fails closed for unmapped source
ok - empty changed selection emits deterministic text and JSON summaries
ok - timing markers and JSON artifact are valid
ok - aggregate exit reflects any script failure
ok - gate-skip accounting is honest and non-failing
ok - fail-on-gate-skip converts herdr-not-found into a hard failure
ok - exclude-family drops the named primary family after selection
ok - portable shard union, disjointness, and coverage guard hold
ok - portable serial shards are a deterministic disjoint cover of the serial lane
ok - portable serial shard lanes refuse mismatched, out-of-range, and countless names
ok - --jobs refuses non-proven / stateful selections
ok - jobs scheduler runs proven scripts; failure propagates; non-proven refused
ok - Herdr CI family-run step times out at 20 min under a 75 min job backstop
ok - aggregate-json merges lane timing artifacts
FM_TEST_END 2026-08-20T15:30:36Z tests/fm-test-run.test.sh exit=0 duration_ms=14958 gate_skip=false
FM_TEST_SUMMARY total=3 failed=0 skipped_gate=0 duration_ms=28185
FM_TEST_SUMMARY_FAMILY family=pure-contract-unit count=2 duration_ms=15720 failed=0
FM_TEST_SUMMARY_FAMILY family=watcher-wake-lock count=1 duration_ms=12348 failed=0
FM_TEST_SLOWEST rank=1 script=tests/fm-test-run.test.sh duration_ms=14958
FM_TEST_SLOWEST rank=2 script=tests/fm-tool-update-check.test.sh duration_ms=12348
FM_TEST_SLOWEST rank=3 script=tests/fm-documentation-audiences.test.sh duration_ms=762

Evidence: Reproduction script for the transcript above

#!/usr/bin/env bash
# Manual end-to-end demonstration of bin/fm-tool-update-check.sh on this host.
# Fixtures were built by the test phase; see tool-update-check-demo.txt for the
# captured transcript.
set -u
EV=/tmp/no-mistakes-evidence/01M0FM08RBH7MKKX9N7ZZWF5GG
D=$EV/demo
W=/local/home/inthuson/.no-mistakes/worktrees/d4c7ad84348d/01M0FM08RBH7MKKX9N7ZZWF5GG
CHECK=$W/bin/fm-tool-update-check.sh
STALE=$D/incident/mise/installs/herdr/latest

hdr() { printf '\n########## %s\n\n' "$*"; }
run() { printf '$ %s\n' "$*"; }

hdr '1. the watched tool registry an operator edits (config/, local, gitignored)'
run "cat config/watched-tools.json"
cat "$D/home-real/config/watched-tools.json"
run "git check-ignore -v config/watched-tools.json"
(cd "$W" && git check-ignore -v config/watched-tools.json)

hdr '2. one sweep over the four real update sources'
run "FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check"
rm -f "$D/home-real/state/.tool-updates"
env FM_HOME="$D/home-real" FM_TOOL_UPDATE_INTERVAL=0 "$CHECK" check
printf '\n(herdr is silent: this host has one copy on PATH and it is the newest one.\n'
printf ' no-mistakes announces its own update on --help, not on --version, so\n'
printf ' announce_args asks the command that carries it.)\n'

hdr '3. the 2026-08-20 incident: an update that installed but never took effect'
printf 'A version-manager copy of herdr is put back at PATH position 1, in a\n'
printf 'directory named "latest" that holds 0.8.0, while the real self-installed\n'
printf '0.8.2 stays where it is at ~/.local/bin.\n\n'
run 'command -v herdr; herdr --version   # everything a single lookup can know'
env PATH="$STALE:$PATH" bash -c 'command -v herdr; herdr --version'
run '/home/inthuson/.local/bin/herdr --version   # the newest copy installed here'
/home/inthuson/.local/bin/herdr --version
printf '\nA check that only asks "is a newer version published" sees 0.8.0 and the\n'
printf 'newest release the version manager will offer, and reports nothing.\n\n'
run "FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check   # poll 1"
rm -f "$D/home-incident/state/.tool-updates"
env FM_HOME="$D/home-incident" PATH="$STALE:$PATH" FM_TOOL_UPDATE_INTERVAL=0 "$CHECK" check
printf '\n'
run "FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check   # poll 2, same condition"
env FM_HOME="$D/home-incident" PATH="$STALE:$PATH" FM_TOOL_UPDATE_INTERVAL=0 "$CHECK" check
printf '(no output: the same pending update is not reported twice)\n\n'
run "FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check   # stale copy removed"
env FM_HOME="$D/home-incident" FM_TOOL_UPDATE_INTERVAL=0 "$CHECK" check
printf '(no output: PATH resolves the newest copy again)\n'

hdr '4. it reports and repairs nothing'
run 'every herdr invocation the sweep makes, with the only herdr on PATH recorded'
: > "$D/audit/herdr-calls.log"
rm -f "$D/home-audit/state/.tool-updates"
env -i FM_HOME="$D/home-audit" PATH="$D/audit/bin:/usr/bin:/bin" HOME="$HOME" \
  HERDR_CALL_LOG="$D/audit/herdr-calls.log" FM_TOOL_UPDATE_INTERVAL=0 "$CHECK" check
cat "$D/audit/herdr-calls.log"
printf '(one version read, no Herdr lifecycle command)\n\n'
run 'the watched clones before vs after the sweep'
diff -u "$EV/repo-before.txt" "$EV/repo-after.txt" \
  && printf 'identical: refs, HEAD, working tree, FETCH_HEAD, reflog, object count\n'

hdr '5. armed once per home, then polled by the existing watcher'
run "bin/fm-tool-update-check.sh arm"
# a fresh home, so the one wake the checkpoint reports is this check's own
rm -rf "$D/home-armed"; mkdir -p "$D/home-armed/state" "$D/home-armed/config"
printf '%s\n' '{ "tools": [ { "name": "herdr", "command": "herdr", "version_args": ["--version"] } ] }' \
  > "$D/home-armed/config/watched-tools.json"
printf '%s\n' fm-pr-check-migration-scan-v1 > "$D/home-armed/state/.pr-check-migration-scan-v1"
printf '%s\n' fm-pr-check-migration-v1 > "$D/home-armed/state/.pr-check-migration-v1"
chmod 0600 "$D/home-armed/state/.pr-check-migration-scan-v1" "$D/home-armed/state/.pr-check-migration-v1"
FM_HOME="$D/home-armed" "$CHECK" arm
run "cat state/tool-updates.check.sh"
cat "$D/home-armed/state/tool-updates.check.sh"
run "head -1 state/tool-updates.check-trust"
head -1 "$D/home-armed/state/tool-updates.check-trust"
printf '\n'
run "bin/fm-watch-checkpoint.sh --seconds 10   # the real watcher, no new scheduler"
rm -f "$D/home-armed/state/.tool-updates"
env FM_HOME="$D/home-armed" PATH="$STALE:$PATH" FM_CHECK_TIMEOUT=30 FM_TOOL_UPDATE_INTERVAL=0 \
  FM_POLL=1 FM_SIGNAL_GRACE=1 FM_CHECK_INTERVAL=1 "$W/bin/fm-watch-checkpoint.sh" --seconds 10

hdr '6. the registry is never shipped to another home'
run '. bin/fm-config-inherit-lib.sh; fm_config_inherit_items'
(cd "$W" && bash -c '. bin/fm-config-inherit-lib.sh; fm_config_inherit_items')
printf '(config/watched-tools.json is not in the inherited set)\n'

Evidence: Mutation harness used for the skew-regression proof

#!/usr/bin/env bash
# Mutation check: each mutation below removes one part of the detection the
# regression tests exist to protect. A test that only asserted "a call happened"
# would keep passing. Each run must fail.
set -u
W=/local/home/inthuson/.no-mistakes/worktrees/d4c7ad84348d/01M0FM08RBH7MKKX9N7ZZWF5GG
cd "$W" || exit 1
SRC=bin/fm-tool-update-check.sh

mutate() { python3 - "$SRC" "$1" "$2" <<'PY'
import sys
path, old, new = sys.argv[1], sys.argv[2], sys.argv[3]
text = open(path).read()
if text.count(old) != 1:
    sys.exit("mutation anchor not unique: %d" % text.count(old))
open(path, "w").write(text.replace(old, new))
PY
}

run_case() {
  local label=$1
  printf '\n===== %s =====\n' "$label"
  git diff --stat -- "$SRC" | tail -1
  git diff -U0 -- "$SRC" | grep -E '^[-+][^-+]' 
  printf -- '--- test result ---\n'
  local status=0
  bash tests/fm-tool-update-check.test.sh 2>&1 | grep -E '^(ok|not ok)' | tail -4
  status=${PIPESTATUS[0]}
  printf -- '--- test script exit=%s (non-zero means the mutation was caught) ---\n' "$status"
  git checkout -- "$SRC"
}

# A: the PATH-skew report itself is removed.
mutate '    emit "$name update not in effect: PATH resolves $resolved_version at $resolved_path but $best_version is installed at $best_path"' \
       '    : # mutation A: skew report removed'
run_case 'mutation A: skew report replaced with a no-op'

# B: only the first PATH hit is probed, the way a single `command -v` lookup would.
mutate '      best_path=$hit
    fi
  done <<EOF' \
       '      best_path=$hit
    fi
    break # mutation B: stop after the first PATH hit
  done <<EOF'
run_case 'mutation B: stop after the first PATH hit (single lookup)'

# C: the separate announcement command is never asked.
mutate '    if [ "$announce_args" != "$args_joined" ]; then' \
       '    if false; then # mutation C: second announcement probe removed'
run_case 'mutation C: the second announcement probe is removed'

printf '\n===== worktree restored =====\n'
git status --porcelain -- "$SRC" | sed 's/^/dirty: /'
git diff --quiet -- "$SRC" && echo "bin/fm-tool-update-check.sh is back to its committed bytes"

- Outcome: ⚠️ 1 info across 1 run (12m20s)

Pipeline

Updates from git push no-mistakes

... (4 earlier update rounds omitted to keep the PR body within GitHub's 65536-char limit; full history is in the run log.)

⚠️ **Review** - 2 infos

🔧 Fix: keep sweeps alive on broken patterns and oversized budgets
5 issues (3 warnings, 2 infos) still open:

• ⚠️ bin/fm-tool-update-check.sh:782 - A failed registration leaves a written, unregistered check shim behind, which turns into a recurring false security wake. shim_write succeeds, then FM_HOME="$home" "$REGISTER_BIN" "$CHECK_ID" fails and action_arm returns 1 without removing state/tool-updates.check.sh. Verified by running arm with a symlink planted at the trust path: ln -s .../elsewhere.txt state/tool-updates.check-trust makes fm-check-register.sh:29 (fm_pr_regular_destination_on_device_or_absent "$TRUST") exit 1 with error: custom check trust path is unavailable, arm exits 1, and state/ is left holding -rwx------ tool-updates.check.sh with no valid .check-trust. The symlink's target is correctly untouched, so the round-2 shim guard works; the leftover shim is the problem. The watcher then takes the else branch at bin/fm-watch.sh:944-947, appends the shim to rejected_checks, and wakes firstmate with check: rejected unauthenticated state checks: .../tool-updates.check.sh (bin/fm-watch.sh:962-966) on every FM_CHECK_INTERVAL until someone deletes the file by hand, while fm-pr-check-migrate.sh separately treats it as a noncanonical artifact to quarantine (migration_needed at bin/fm-pr-check-migrate.sh:384-398). Other reachable register failures are the same shape: a host with neither shasum nor sha256sum makes fm_custom_check_sha256 fail, and the post-write fm_custom_check_registered re-check can fail on a race. The repo's own arm pattern is to roll back: fmx_arm_failed calls x_mode_remove_artifacts before reporting (bin/fm-bootstrap.sh:955-961). Fix: remove $CHECK_SHIM when registration fails, before returning 1.
• ⚠️ tests/fm-tool-update-check.test.sh:96 - The suite now depends on an unpinned ambient environment variable, so a developer with FM_CHECK_TIMEOUT set sees spurious failures across the file. run_check passes FM_TOOL_UPDATE_INTERVAL=0 but not FM_CHECK_TIMEOUT, and tests/lib.sh does not sanitize the environment (its only export is FM_GATE_REFUSE_BYPASS=1). Because round 2 made the check read ${FM_CHECK_TIMEOUT:-30} and clamp the default 20s budget against CHECK_TIMEOUT - 1, any ambient value of 20 or less adds a report line to a sweep that should print nothing. Verified directly against the script under review with two copies on PATH, newest first: with env -u FM_CHECK_TIMEOUT the check is silent, with FM_CHECK_TIMEOUT=20 it prints tool updates: sweep budget 20s cut to 19s to stay inside the watcher check timeout of 20s, and with FM_CHECK_TIMEOUT=21 it is silent again. FM_CHECK_TIMEOUT is a documented operator tunable (docs/configuration.md:612), so 20 or 10 is a plausible ambient value. That breaks at least test_newest_copy_first_on_path_is_silent, test_identical_versions_are_silent, test_one_copy_reached_twice_is_probed_once, test_quiet_tool_with_announce_pattern_is_silent, test_current_and_ahead_repositories_are_silent, the control home in test_announcement_is_read_from_a_second_command, and the cleared-finding step of test_findings_are_reported_once_until_they_change. Fix: pin FM_CHECK_TIMEOUT in run_check (and in the cases that build their own env line, including the shim run at line 785 and the checkpoint run at line 810) so the clamp is exercised only by the case that means to exercise it.
• ⚠️ bin/fm-tool-update-check.sh:158 - The new clamp does not actually leave enough room, so a clamped budget can still be killed by the watcher and reproduce the exact silence the clamp was added to prevent. BUDGET_MAX=$((CHECK_TIMEOUT - PROBE_MIN_SECS)) reserves one second, and the comment at lines 145-149 justifies that as "the margin a sweep can still need after its deadline". Two effects make the real overshoot larger. First, budget_exhausted and probe_bound compare whole seconds from date +%s, so a probe can be started when the integer arithmetic says one second remains while real remaining time is near zero, and it is then given a full one-second bound, ending up to a second past DEADLINE. Second, fm_run_external_timeout runs "$runner" -k 1 "$seconds" bash -c ... (bin/fm-timeout-lib.sh), so a probe that does not die on TERM is only KILLed a further second later. Concrete sequence: an operator sets FM_TOOL_UPDATE_BUDGET_SECS=60 on a home with the default FM_CHECK_TIMEOUT=30, so the budget is cut to 29 (the value test_an_oversized_budget_is_cut_to_fit_and_reported asserts). On an offline laptop the four watched tools spend the budget in 5s network probe bounds, the last probe starts just inside the deadline, and the run crosses 30s. run_check_process kills it, so nothing is printed and record_write never runs; because no record is written the cadence gate never engages and every subsequent poll repeats the same silence with no failure line. The default 20s budget has 9s of slack and is unaffected. Fix: derive BUDGET_MAX with room for the second-boundary rounding plus the kill grace (for example CHECK_TIMEOUT - PROBE_MIN_SECS - 2, still floored at 1), which leaves the default 20s uncut at FM_CHECK_TIMEOUT=30.
• ℹ️ bin/fm-tool-update-check.sh:512 - Round 2 taught three of the bounded git probes to keep "no answer" apart from "the answer no", but left the first two reading a hit bound as a semantic answer. At line 512 if ! git_probe "$repo" rev-parse --git-dir >/dev/null 2>&1; then emit "$name check failed: $repo is not a git repository", and git_probe returns 124 when the bound is hit, so a clone on a stalled network mount is reported as not being a git repository at all: a diagnosis the probe never established, and one the operator cannot act on, which is the same class the review-1 and review-14 fixes closed for ls-remote, cat-file, merge-base, and rev-list. Line 519's symbolic-ref has the quieter version: its status is discarded, so a timeout looks identical to a clone with no local record of the remote's default branch and silently costs an extra network ls-remote --symref probe out of the same budget. Fix: capture both statuses and report 124 as a probe that did not answer, naming the repository, the way the other five probes now do.
• ℹ️ tests/fm-tool-update-check.test.sh:533 - test_a_git_probe_that_does_not_answer_is_not_an_update can pass without exercising the fix it names. Its only assertions are assert_not_contains "$report" "update available" and assert_contains "$report" "firstmate check failed", and it runs with FM_TOOL_UPDATE_PROBE_SECS=1. The fixture git wrapper only stalls on cat-file, but three earlier probes run under the same 1s bound first (rev-parse --git-dir, ls-remote, rev-parse --verify refs/heads/main), each through an extra bash wrapper layer. If any of those hits its bound on a loaded machine, git_findings returns early with origin did not answer within 1s or did not answer where main points, both of which satisfy both assertions, and both of which would also satisfy them against the pre-fix code that read a hit bound as "this clone does not have that commit". So the test's mutation proof depends on timing rather than on its assertions. Fix: assert the object-query message specifically (did not answer whether it already has), so an unrelated earlier timeout cannot make the case pass for the wrong reason.

🔧 Fix: roll back failed arm, widen budget clamp, bound repo probe
4 issues (3 warnings, 1 info) still open:

• ⚠️ bin/fm-tool-update-check.sh:614 - The round-3 clamp still does not leave enough room, because git_findings issues up to three bounded probes after a single budget_allows. budget_allows is called at line 604, then cat-file -e (605), merge-base --is-ancestor (614) and rev-list --count (621) all run unguarded, and probe_bound floors at 1s once the budget is spent, so each can add ~1s and the last can add another 1s of kill grace. BUDGET_MAX=$((CHECK_TIMEOUT - PROBE_MIN_SECS - CLOCK_ROUNDING_SECS - KILL_GRACE_SECS)) reserves exactly 3s, which models only ONE probe running past the deadline. Reproduced locally with a logging git wrapper against the script under review: with FM_TOOL_UPDATE_BUDGET_SECS=4 and probes sleeping 0.9s each, rev-list was STARTED 1.3s past DEADLINE with no budget check and the sweep ended 2.23s past DEADLINE; with each probe consuming its full 1s floor bound and the last one timing out, the overshoot reaches 3-4s. Failure sequence: an operator sets FM_TOOL_UPDATE_BUDGET_SECS=60 on a default home, it is clamped to 27, a slow sweep crosses 30s, run_check_process kills the check (bin/fm-watch.sh:553, plain timeout with no -k), nothing is printed, record_write never runs, the cadence gate never engages, and every subsequent poll repeats the same silence with no failure line. That is exactly the failure review-18 was accepted to close. Lowering FM_CHECK_TIMEOUT, a documented operator tunable (docs/configuration.md:612), reaches the same state with the DEFAULT 20s budget, since 20 is then clamped to CHECK_TIMEOUT - 3. The file's own comment at lines 504-505, "Every probe consults the sweep budget first", is false for merge-base, rev-list, and the second rev-parse --verify HEAD at line 587. Earliest shared boundary: fold the budget check into git_probe, which already owns bound derivation, so no probe can be issued past the deadline and the one-probe reserve becomes true; that also removes the seven repeated status=$?; if [ "$status" -eq 124 ] blocks.
• ⚠️ bin/fm-tool-update-check.sh:459 - The separate announcement probe's exit status is discarded, and empty output falls through the [ -n "$announce_out" ] guard at line 462, so an announce command that hangs or fails silently kills that tool's update source while the sweep reports everything current. Reproduced against the script under review with the documented no-mistakes shape (version_args ["--version"], announce_args ["--help"], announce_pattern present): a fixture whose --version answers instantly and whose --help hangs, run with FM_TOOL_UPDATE_PROBE_SECS=2 and the default budget, prints nothing at all and stamps reported= into state/.tool-updates. Trace: resolved_version is set from the fast --version probe, the budget is not exhausted so the review-12 branch at line 452 does not fire, probe_output at line 459 hits its bound and returns empty with status 124 discarded, the guard at 462 is false so no grep runs and nothing is emitted, and best_path == resolved_path so no skew either. This contradicts the file's own invariant at lines 31-32 that a probe which will not answer is a check failure rather than an assumed pass, and it is the same silently dead source announce_args was added to close. It is realistic because no-mistakes' announcement comes from its own network version check, which is exactly the call that stalls on a flaky link. Fix: capture probe_output's status for the announcement probe and report a check failure when the probe did not answer, in the same shape as the budget-stopped message already at line 455. A probe that answers with nothing must stay silent as it does today.
• ⚠️ bin/fm-tool-update-check.sh:729 - The no-nag gate compares the TRUNCATED report line, so a finding that appears past MAX_LINE produces no wake at all. fm_cap_line_var cuts the line at line 720, and both the comparison at line 726 and record_write "$line" at line 729 use that cut value. Reproduced locally: a registry of 30 absent tools produces a report cut at 1000 characters with the [truncated] marker, and that cut line is what lands in reported=. Appending a real PATH-skew tool (two copies on PATH, 0.8.0 resolved first, 0.8.2 installed) as the last registry entry then produced NO output at all on the next sweep, because its finding falls past the cut and the capped line is byte-identical to the recorded one. So the exact condition this deliverable exists to detect is suppressed indefinitely once the report already exceeds 1000 characters. Fix: keep printing the capped line, but compare and record the uncapped FINDINGS (or a digest of it) so a change past the cut is still news. state/.tool-updates is internal state and no test pins the reported= value, so this is not a user-visible contract change.
• ℹ️ bin/fm-tool-update-check.sh:837 - Two residual paths of the review-16 rollback still leave an unregistered shim, which is the recurring false security wake that fix was accepted to remove. (1) action_arm installs no signal handler, so HUP/INT/TERM between shim_write's rename (line 768) and the register call completing leaves state/tool-updates.check.sh present with no matching trust binding; the watcher then appends it to rejected_checks and wakes firstmate with check: rejected unauthenticated state checks on every FM_CHECK_INTERVAL (bin/fm-watch.sh:945-968) until someone deletes it by hand. The same interrupt also leaks the mode-0700 backup temp file in state/, which fm-check-register.sh avoids for its own temp with a trap (fm-check-register.sh:34). (2) fm-check-register.sh:40 removes an already-present $TRUST when its post-write re-check fails, and shim_restore only puts the shim bytes back, so a home that was already armed ends with the shim present and the trust binding gone. Fix: trap HUP INT TERM around the write-then-register window and route through the same shim_restore plus backup cleanup, so an interrupted arm leaves the home exactly as it found it. Separately, the shim_backup comment at lines 776-778 gives the wrong reason: fm_custom_check_registered binds sha256, mode, device and link count (bin/fm-check-lib.sh:38-45), not the inode, so identical re-written bytes would satisfy the binding just as well; restoring the original bytes is still right, but not for that reason.

🔧 Fix: guard git probes at the budget, record uncut findings
2 infos still open:

• ℹ️ docs/configuration.md:386 - Two docs still describe the report record as holding the printed line, which the last fix round deliberately changed. docs/configuration.md:386 says "state/.tool-updates records the last reported line so the same pending update is reported once instead of on every poll", and AGENTS.md:108 says "Its report record .tool-updates keeps the last reported line so one pending update is reported once, not on every poll". The code now records and compares the whole uncut finding set (record_write "$FINDINGS" and [ "$FINDINGS" != "$RECORD_REPORTED" ], bin/fm-tool-update-check.sh:734-737), and the script header at lines 59-63 was updated to say so. The distinction is exactly the defect round 4 closed: a reader of these two sentences would conclude that a finding landing past the 1000-character cut leaves the printed line unchanged and is therefore suppressed, which is no longer true. I confirmed the new behavior directly: with 30 absent tools plus an appended PATH-skew tool, the second sweep prints a line byte-identical to the first and still reports, and the third sweep is silent. Fix: say the record carries the whole finding set the last report was made from, uncut, so a change past the one-line cut is still news. AGENTS.md is the always-loaded contract and docs/configuration.md is the declared owner of this section, so both should match the code.
• ℹ️ bin/fm-tool-update-check.sh:821 - arm_rollback's keep branch is reachable but unexercised, so removing it would leave the suite green. if fm_custom_check_registered "$STATE" "$CHECK_ID"; then return 0; fi is the only thing that keeps a home that was already armed armed after a failed or interrupted re-arm; without it every such failure falls through to rm -f -- "$CHECK_SHIM". Neither arm-failure test can reach it: test_a_failed_registration_leaves_no_unregistered_shim plants a symlink at the trust path, so fm_custom_check_trust_read rejects it, and test_a_failed_rearm_leaves_no_shim_the_trust_binding_lost shadows both hash tools, so fm_custom_check_sha256 cannot produce a hash either. Both therefore assert the removal branch. The keep branch does have a realistic trigger: an interrupt during a re-arm, where fm-check-register.sh's own trap removes its temp and exits before its mv, leaving the previous valid trust binding intact and matching the restored bytes, so the home stays armed instead of being unarmed by a Ctrl-C. Noting this as a coverage gap rather than requesting a test, because every register failure mode that leaves the trust valid needs either a missing fm-check-register.sh or a signal, and neither is available as a deterministic seam without adding one. The absence of the branch would also not be silent: the operator still sees "could not register" and a non-zero exit.

⚠️ **Test** - 1 info

• ℹ️ tests/fm-lint-workflows.test.sh - tests/fm-lint-workflows.test.sh fails on this host with 'current workflows must parse, got 127' because actionlint is not installed. Host-level and pre-existing: the change touches no workflow YAML and no lint script, and the intent already declares this gap as deliberately left alone (installing the tool is forbidden by the captain and by the worktree boundary). tasks-axi is likewise absent, which is the other declared gap. No action needed for this change; remote CI owns workflow lint.
• bin/fm-test-run.sh tests/fm-tool-update-check.test.sh (37 cases, all ok)
• bin/fm-test-run.sh tests/fm-documentation-audiences.test.sh tests/fm-test-run.test.sh (the other changed files; all ok)
• bin/fm-test-run.sh --check-coverage
• Mutation: skew emit replaced with a no-op, then bash tests/fm-tool-update-check.test.sh -> not ok on the skew regression
• Mutation: break after the first PATH hit (single lookup), then bash tests/fm-tool-update-check.test.sh -> not ok on the skew regression
• Mutation: the announce_args branch forced false, then bash tests/fm-tool-update-check.test.sh -> not ok on the second-command announcement test
• git checkout -- bin/fm-tool-update-check.sh after each mutation, then git status --porcelain (clean at b7caee6)
• Manual sweep: FM_HOME=<demo home> FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh check over a real firstmate clone 3 commits behind origin/main, a real agents-on-the-go repo 2 commits behind origin/mainline, the real herdr on PATH, and the real no-mistakes with announce_args --help
• Manual incident reproduction: a 0.8.0 copy in a directory named latest at PATH position 1 with the real 0.8.2 at ~/.local/bin, plus command -v herdr; herdr --version to show what one lookup can know
• Manual no-nag: three consecutive bin/fm-tool-update-check.sh check polls (report, silence, silence after the condition cleared)
• Manual arm and watcher: bin/fm-tool-update-check.sh arm then bin/fm-watch-checkpoint.sh --seconds 10 on a fresh home
• Manual read-only audit: recording herdr wrapper as the only copy on PATH -> one invocation, herdr --version
• Manual repo snapshot diff: for-each-ref, HEAD, status, FETCH_HEAD, reflog and object count for both watched clones before vs after a sweep
• git check-ignore -v config/watched-tools.json and . bin/fm-config-inherit-lib.sh; fm_config_inherit_items
• Manual example check: docs/examples/watched-tools.json copied verbatim -> arm exits 0; with its placeholder paths filled in -> full four-source report
• bin/fm-test-run.sh tests/fm-lint-workflows.test.sh, command -v actionlint, command -v tasks-axi to confirm the declared environment gaps are host-level

⚠️ **Document** - 1 info

• ℹ️ docs/fm-test-portable-shards.md:71 - The portable-serial CI shard table still records the 2026-08-02 measurement (15/18/17/19 scripts, 69 total), while bin/fm-test-run.sh now partitions 116 scripts as 29/29/29/29. This is pre-existing drift from roughly 47 tests added since that refresh; this change contributes one of them (tests/fm-tool-update-check.test.sh lands in the derived portable-serial lane). I left it alone rather than half-refreshing it: the doc's own procedure couples the table to a hint refresh from a green CI run's fm-test-timing-portable-serial artifacts, which are not available here, so recomputing counts from stale weight hints would pair current counts with 2026-08-02 durations. The adjacent parallel-lane table (11/13) is still current, and bin/fm-test-run.sh --check-coverage reports ok, so coverage is not at risk. Worth a follow-up that downloads the artifacts, replaces portable_serial_weight_hints, and updates both the table and the 69-script sentence at line 67.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 127)

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

Speaking as Kun's firstmate: I reviewed the full diff (opt-in watched-tool check, arm/disarm, PATH-skew detection, tests) and approved fork CI. Waiting on green checks including no-mistakes.

[kunchenguid]

Speaking as Kun's firstmate:

Re-reviewed the new HEAD (no-mistakes follow-ups after the earlier stamp). Still an opt-in watched-tool check: explicit arm, no auto-arm, reports only. I re-approved fork CI on the new commits. Waiting on green checks including no-mistakes.

[Inthuson]

Ready for a maintainer when you have a moment.

This one is complete on our side with all checks green. Nothing further is pending from this fork.

[kunchenguid]

Speaking as Kun's firstmate: Opt-in — watched-tool update check, explicit arm/disarm, no bootstrap auto-arm, reports only (never installs, never reorders PATH). Re-reviewed new HEAD d399c68f4506 after the prior stamp (rebase + CI-fix commit). PATH skew is measured by probing every PATH copy; git probes are read-only; registry is local gitignored config. No security risk. VISION: aligns (new capability as an option to enable; authority stays explicit). Author's "all checks green" is not visible here: fork workflows were still action_required. I approved CI and Require no-mistakes on this HEAD. Waiting on green including no-mistakes. Overlap is mostly bin/fm-test-run.sh family registration, plus AGENTS.md with #2524/#2744 on different sections.

[Inthuson]

Speaking as Inthuson's firstmate: correcting my own earlier comment. My "all checks green" at 11:02 was read off an older authorised head, not this one. Thank you for approving CI on d399c68f4506, which is what made the real result visible: 11 of 13 pass, and Behavior portable serial 2 and Behavior portable serial 4 fail. So this is not ready for a maintainer and I have withdrawn that claim. A worker is investigating both failures against current main, which has moved since this head. I will report back when it is genuinely green rather than when I believe it is.

[kunchenguid]

Speaking as Kun's firstmate:

Opt-in — watched-tool update check, explicit arm/disarm, no bootstrap auto-arm, reports only (never installs, never reorders PATH). Re-reviewed new HEAD 38733995859e (three further "apply CI fixes" commits after the prior stamp on d399c68f4506). PATH skew is still measured by probing every PATH copy; git probes are read-only; registry is local gitignored config.

VISION: aligns (new capability as an option to enable; authority stays explicit).

Security: no.

HEAD moved and outcome changed, so this is a restamp. Require no-mistakes is SUCCESS. CI is now red: Behavior portable serial 4 failed in tests/fm-watch-triage.test.sh (not ok - the stalled-crew escalation was not counted). This PR does not touch that suite; the branch is also ahead 10 / behind 2. Overlap remains mostly bin/fm-test-run.sh family registration plus AGENTS.md with other PRs on different sections.

This is waiting on the author, not the captain: make CI including no-mistakes green on this HEAD (rebase onto current main if the triage failure is from drift).

[kunchenguid]

Speaking as Kun's firstmate:

Newer HEAD 38733995859e after the earlier d399c68 stamp. Still opt-in (arm/disarm, not bootstrap). VISION aligns (new capability as an option to enable).

CI is not green: Behavior portable serial 4 FAILED. no-mistakes is SUCCESS. Waiting on CI/author — not waiting on the captain. Will not land while a required check is red.

[kunchenguid]

Speaking as Kun's firstmate:

VISION verdict: align. New capability ships as an option to enable: explicit arm/disarm, no bootstrap auto-arm, reports only, never installs or reorders PATH.

Class: opt-in.

Re-reviewed NEW HEAD debc17a82411 (merge of origin/main plus the watch-triage wait_poll_cycle / 100-tick exit waits). Last stamp was 2026-08-21T18:21:07Z HEAD 38733995859e class=opt-in, portable serial 4 FAILED. HEAD moved and outcome changed, so this is a restamp.

Security: no. PATH skew is still measured by probing every PATH copy; git probes stay read-only; the registry remains local gitignored config.

CI including no-mistakes is green on this HEAD: portable serial 1-4, both parallel shards, Herdr behavior, lint, repo invariants, macOS bash snapshot, coverage guard, and Require no-mistakes are all SUCCESS.

Ahead 12 / behind 1. mergeable MERGEABLE, mergeStateStatus BLOCKED (no GitHub review approval yet).
Overlap: bin/fm-test-run.sh with the held pair #2637/#2692 (family and weight-hint registration only). AGENTS.md also in #2755/#2757 on different lines. Not spawn-freshen.

Merge-eligible rec: YES. Coordinator decides landing (branch is 1 commit behind main; GitHub is BLOCKED on review approval). Not a captain-flag.

[kunchenguid]

Speaking as Kun's firstmate: opt-in tooling-update reports, explicit arm/disarm, green CI including no-mistakes on HEAD debc17a. Approving to land.

[kunchenguid]

Speaking as Kun's firstmate:

CI is green including no-mistakes. This is opt-in and review-approved. Squash is blocked by the repo ruleset (require_extra_approval_for_unattributed_changes / workflow-file policy on .github/workflows/ci.yml). I will not --admin around that.

Waiting on the captain for a policy go-ahead to land, not waiting on the author.

[kunchenguid]

Speaking as Kun's firstmate: this is merged. Thank you @Inthuson — really appreciate you taking the time on this.