feat(bin): report watched tooling updates that are available or installed but inert - #2684
Open
Inthuson wants to merge 7 commits into
Open
feat(bin): report watched tooling updates that are available or installed but inert#2684Inthuson wants to merge 7 commits into
Inthuson wants to merge 7 commits into
Conversation
… inert
Firstmate had no way to notice that tooling this home depends on needs an
update, and no way at all to notice the worse case: an update that installed
correctly and then did nothing.
That second case is why this exists. A tool that self-installs into
~/.local/bin while a version manager keeps its own older copy earlier on PATH
looks completely up to date to anything that asks only "is a newer version
published". On 2026-08-20 a Herdr update landed at 0.8.2 while an older 0.8.0
copy stayed earlier on PATH, so every Herdr command failed on a protocol
mismatch and firstmate could not read its own fleet.
bin/fm-tool-update-check.sh reports the two conditions separately:
<tool> update available a newer version exists at the update source.
<tool> update not in effect a newer copy is installed on this host, but
PATH still resolves an older one.
PATH skew is measured, never inferred. Every executable copy of a watched
command on PATH is asked for its own version and those answers are compared,
so one lookup cannot hide the skew, and a directory name is never read as a
version because a version manager's "latest" directory can hold an older
build. A copy that will not report a version is a check failure, not a pass.
The watched tools live in local, gitignored config/watched-tools.json, so
adding a tool is a config edit rather than a code change, and the file is
never propagated to another home. Update sources cover both shapes: a local
clone's commit distance from its remote branch, and a command's own version
and update announcement, including a tool like no-mistakes that prints its
version on one command and announces a new release on another.
The check prints one line when something needs attention and prints nothing
otherwise, so it rides the existing watcher state-check contract with its
trust binding instead of introducing a schedule of its own, and
state/.tool-updates keeps the same pending update from being reported on
every poll.
The check only reports. It never installs, updates, reorders PATH, touches a
version manager, or fetches into a watched repository; every git probe is
read-only.
Tests cover the skew case as a regression, and it was verified by mutation:
removing the skew report, or stopping after the first PATH hit as a single
lookup would, each make that test fail.
…n docs and header
Owner
|
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. |
Owner
|
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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 herdrstill 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:
Constraints the captain stated, which explain choices that would otherwise look surprising in the diff:
Decisions and tradeoffs made while doing the work:
armwrites 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.readwould collapse the empty fields an optional key leaves behind.no-mistakes --versionprints 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.ls-remote --symreffallback after a live single-branch clone with no local record of origin HEAD produced a check failure the operator could not act on.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
bin/fm-tool-update-check.sh, a read-only check that reads the tools this home depends on from local, gitignoredconfig/watched-tools.jsonand prints one bounded line only when something needs attention. It reports two distinct conditions:<tool> update availablefrom an update source (commits behind a remote branch for a local clone, or a tool's own update announcement matched byannounce_pattern, optionally probed via a separateannounce_argscommand), and<tool> update not in effectwhen a newer copy is installed butPATHstill resolves an older one. Skew is measured by running every executable copy of the command found onPATHand 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, reordersPATH, touches a version manager, or fetches into a watched repo.armwritesstate/tool-updates.check.shand binds its bytes throughbin/fm-check-register.shso the existing watcher polls it on its normal cadence, anddisarmremoves the shim, its trust binding, and the record. Findings are recorded uncut instate/.tool-updatesafter 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 byFM_TOOL_UPDATE_INTERVALand bounded byFM_TOOL_UPDATE_PROBE_SECSandFM_TOOL_UPDATE_BUDGET_SECS, with the sweep budget cut down to whatFM_CHECK_TIMEOUTallows (and the cut named in the report) so a killed run cannot silently swallow a finding.tests/fm-tool-update-check.test.sh(74 cases, classified into thewatcher-wake-lockfamily inbin/fm-test-run.sh), includingtest_path_skew_is_reported_from_every_copy, which stages an older copy earlier onPATHthan 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 brokenannounce_patterndoes not suppress another tool's skew report. Documented the registry schema indocs/configuration.mdas its single owner, added the copyabledocs/examples/watched-tools.jsonregistered as an operator example, and listed the script and its config and state entries indocs/scripts.mdandAGENTS.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
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 bytesEvidence: The two conditions on real sources, and the incident reproduced against the real herdr binary
Evidence: The armed check arriving at the real watcher as an ordinary check wake
Evidence: Read-only proof: every herdr invocation the sweep made, and the watched clones before vs after
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=28185Evidence: Reproduction script for the transcript above
Evidence: Mutation harness used for the skew-regression proof
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.)
🔧 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_writesucceeds, thenFM_HOME="$home" "$REGISTER_BIN" "$CHECK_ID"fails andaction_armreturns 1 without removingstate/tool-updates.check.sh. Verified by running arm with a symlink planted at the trust path:ln -s .../elsewhere.txt state/tool-updates.check-trustmakes fm-check-register.sh:29 (fm_pr_regular_destination_on_device_or_absent "$TRUST") exit 1 witherror: custom check trust path is unavailable, arm exits 1, andstate/is left holding-rwx------ tool-updates.check.shwith 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 theelsebranch at bin/fm-watch.sh:944-947, appends the shim torejected_checks, and wakes firstmate withcheck: 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, whilefm-pr-check-migrate.shseparately 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 makesfm_custom_check_sha256fail, and the post-writefm_custom_check_registeredre-check can fail on a race. The repo's own arm pattern is to roll back:fmx_arm_failedcallsx_mode_remove_artifactsbefore reporting (bin/fm-bootstrap.sh:955-961). Fix: remove$CHECK_SHIMwhen 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 withFM_CHECK_TIMEOUTset sees spurious failures across the file.run_checkpassesFM_TOOL_UPDATE_INTERVAL=0but notFM_CHECK_TIMEOUT, andtests/lib.shdoes not sanitize the environment (its only export isFM_GATE_REFUSE_BYPASS=1). Because round 2 made the check read${FM_CHECK_TIMEOUT:-30}and clamp the default 20s budget againstCHECK_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: withenv -u FM_CHECK_TIMEOUTthe check is silent, withFM_CHECK_TIMEOUT=20it printstool updates: sweep budget 20s cut to 19s to stay inside the watcher check timeout of 20s, and withFM_CHECK_TIMEOUT=21it is silent again.FM_CHECK_TIMEOUTis 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: pinFM_CHECK_TIMEOUTinrun_check(and in the cases that build their ownenvline, 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_exhaustedandprobe_boundcompare whole seconds fromdate +%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 pastDEADLINE. Second,fm_run_external_timeoutruns"$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 setsFM_TOOL_UPDATE_BUDGET_SECS=60on a home with the defaultFM_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_processkills it, so nothing is printed andrecord_writenever 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: deriveBUDGET_MAXwith room for the second-boundary rounding plus the kill grace (for exampleCHECK_TIMEOUT - PROBE_MIN_SECS - 2, still floored at 1), which leaves the default 20s uncut atFM_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 512if ! git_probe "$repo" rev-parse --git-dir >/dev/null 2>&1; then emit "$name check failed: $repo is not a git repository", andgit_probereturns 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 forls-remote,cat-file,merge-base, andrev-list. Line 519'ssymbolic-refhas 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 networkls-remote --symrefprobe 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 areassert_not_contains "$report" "update available"andassert_contains "$report" "firstmate check failed", and it runs withFM_TOOL_UPDATE_PROBE_SECS=1. The fixture git wrapper only stalls oncat-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_findingsreturns early withorigin did not answer within 1sordid 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, becausegit_findingsissues up to three bounded probes after a singlebudget_allows.budget_allowsis called at line 604, thencat-file -e(605),merge-base --is-ancestor(614) andrev-list --count(621) all run unguarded, andprobe_boundfloors 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: withFM_TOOL_UPDATE_BUDGET_SECS=4and probes sleeping 0.9s each,rev-listwas 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 setsFM_TOOL_UPDATE_BUDGET_SECS=60on a default home, it is clamped to 27, a slow sweep crosses 30s,run_check_processkills the check (bin/fm-watch.sh:553, plaintimeoutwith no-k), nothing is printed,record_writenever 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. LoweringFM_CHECK_TIMEOUT, a documented operator tunable (docs/configuration.md:612), reaches the same state with the DEFAULT 20s budget, since 20 is then clamped toCHECK_TIMEOUT - 3. The file's own comment at lines 504-505, "Every probe consults the sweep budget first", is false formerge-base,rev-list, and the secondrev-parse --verify HEADat line 587. Earliest shared boundary: fold the budget check intogit_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 repeatedstatus=$?; 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_patternpresent): a fixture whose--versionanswers instantly and whose--helphangs, run withFM_TOOL_UPDATE_PROBE_SECS=2and the default budget, prints nothing at all and stampsreported=intostate/.tool-updates. Trace:resolved_versionis set from the fast--versionprobe, the budget is not exhausted so the review-12 branch at line 452 does not fire,probe_outputat 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, andbest_path == resolved_pathso 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 sourceannounce_argswas 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: captureprobe_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 pastMAX_LINEproduces no wake at all.fm_cap_line_varcuts the line at line 720, and both the comparison at line 726 andrecord_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 inreported=. 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 uncappedFINDINGS(or a digest of it) so a change past the cut is still news.state/.tool-updatesis internal state and no test pins thereported=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_arminstalls no signal handler, so HUP/INT/TERM betweenshim_write's rename (line 768) and the register call completing leavesstate/tool-updates.check.shpresent with no matching trust binding; the watcher then appends it torejected_checksand wakes firstmate withcheck: rejected unauthenticated state checkson 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 instate/, whichfm-check-register.shavoids for its own temp with a trap (fm-check-register.sh:34). (2)fm-check-register.sh:40removes an already-present$TRUSTwhen its post-write re-check fails, andshim_restoreonly 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 sameshim_restoreplus backup cleanup, so an interrupted arm leaves the home exactly as it found it. Separately, theshim_backupcomment at lines 776-778 gives the wrong reason:fm_custom_check_registeredbinds 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-updatesrecords 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; fiis 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 torm -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, sofm_custom_check_trust_readrejects it, and test_a_failed_rearm_leaves_no_shim_the_trust_binding_lost shadows both hash tools, sofm_custom_check_sha256cannot 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 itsmv, 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.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-coverageMutation: skew emit replaced with a no-op, thenbash tests/fm-tool-update-check.test.sh-> not ok on the skew regressionMutation:breakafter the first PATH hit (single lookup), thenbash tests/fm-tool-update-check.test.sh-> not ok on the skew regressionMutation: the announce_args branch forced false, thenbash tests/fm-tool-update-check.test.sh-> not ok on the second-command announcement testgit checkout -- bin/fm-tool-update-check.shafter each mutation, thengit status --porcelain(clean at b7caee6)Manual sweep:FM_HOME=<demo home> FM_TOOL_UPDATE_INTERVAL=0 bin/fm-tool-update-check.sh checkover 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 --helpManual incident reproduction: a 0.8.0 copy in a directory namedlatestat PATH position 1 with the real 0.8.2 at ~/.local/bin, pluscommand -v herdr; herdr --versionto show what one lookup can knowManual no-nag: three consecutivebin/fm-tool-update-check.sh checkpolls (report, silence, silence after the condition cleared)Manual arm and watcher:bin/fm-tool-update-check.sh armthenbin/fm-watch-checkpoint.sh --seconds 10on a fresh homeManual read-only audit: recording herdr wrapper as the only copy on PATH -> one invocation,herdr --versionManual repo snapshot diff: for-each-ref, HEAD, status, FETCH_HEAD, reflog and object count for both watched clones before vs after a sweepgit check-ignore -v config/watched-tools.jsonand. bin/fm-config-inherit-lib.sh; fm_config_inherit_itemsManual example check:docs/examples/watched-tools.jsoncopied verbatim ->armexits 0; with its placeholder paths filled in -> full four-source reportbin/fm-test-run.sh tests/fm-lint-workflows.test.sh,command -v actionlint,command -v tasks-axito confirm the declared environment gaps are host-leveldocs/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.✅ **Push** - passed
✅ No issues found.