fix(scripts): row 211 R3 push guard tags, installer hooks dir, busy check errors (#1709)

(cherry picked from commit 80924f7d5d)

BUILD-LOG.md

@@ -5816,3 +5816,22 @@ Before: agents can read the library; supporting-path and push-credential depende
 2026-10-26 | Sage | mos1884/#662 scope after330/331landing | ReadQ222/Q261/Q263 and659/660/662; posted bounded human-only factory settings/triage/defaulttwo-roundmandate/trackedno-exemptionflake scope with10acceptance criteria, task662comment1338 exactwholebody/author13GETverified. No implementation/review/gate launched.660c1335notready(review/merge, noVM); gatefacts1329/1334 retained; target integration/fullrunner confirmation follows readiness, no localfallback. Landedproduct/evidence unchanged;657/658backlog.
 
 2026-10-26 | Sage | Mos1909/1915/1917 real postlanding reviews | Boyd/Dewey/Filbert/Gladstone real authored candidate52ba verdictfiles independently byte/hash-verified, allAPPROVE scoped; Dewey656broaderPARTIAL retained. Formal330R1/331R4 requests failedpre-send/no comments or approvals; no borrowed/copied/mintedkeys. LegacyhelperGETname jason.woltje is NOT ownJarvis, ownslotabsent; rows tracking-open/#436, files cited via normalqueue. NewFilbertNEW-330-01 filedtask665 exactreadback, notlandingreopen/gate. Repair646-648/652-656 remainOPEN untilactualcomments;1917 conditionalbacklog routing retained. #662scope1338posted;660PR405REVISE/notready. Product1968inputs unchanged; no source/helper/test/gate edits/runs; peerjournal prefixes preserved.
+
+## 2026-11-02T19:39:18Z: row 211 (#1709, #426) R3, push guard and busy check fixes from the GPT review
+
+Before: row 211 as picked onto 09a847eda for the lead's landing batch (5734c1a80, c8f2cb70c on
+`t3/row211-push-guard-r3-fix`). The GPT review (batch1-a-gpt.md) found five gaps: slot-busy.sh read a
+failed cmdline read as an exited process and didn't check its own status read; its shell-snapshot
+exclusion matched a substring; the pre-push hook let an existing tag be re-made or moved to a descendant;
+the installer wrote through a symlinked hooks directory; the snapshot fixture didn't kill its mutant. The
+hook also took hex object names of any length.
+
+After: one R3 commit by the lead's implementation sub-agent. An unreadable live process makes slot-busy.sh
+exit 2 and never print CLEAR, and an exited one is still skipped. The exclusion matches only the wrapper's
+shape. Any change to an existing `refs/tags/*` ref is refused. The installer refuses a symlinked hooks
+directory, or one that resolves elsewhere, before any write. Object names must be 40 or 64 hex
+characters. test-git-guard.sh: RED 67 passed, 18 failed (19:27:01Z to 19:27:06Z), GREEN 85 passed, 0
+failed (19:28:58Z to 19:29:04Z). The run before GREEN gave 80/5 because the new error text said "not
+CLEAR"; it was reworded. Mutants 21 of 21 killed (19:30:11Z to 19:33:22Z, base green). No 64-hex test
+pin names a changed path. Not pushed. Gaps: the installer's resolved-path refusal has no test of its own
+(it needs a bind mount); details in agents/darkwing/work/queue-211/BUILD.md, section "R3".

agents/darkwing/work/queue-211/BUILD.md

@@ -0,0 +1,324 @@
+# Row 211 (#1709, Vikunja P19 #426): a pre-push hook that refuses force-pushes, and a busy check that fails on BUSY
+
+Darkwing, 2026-10-22. Brief: `docs/plans/2026-10-20_force-push-guard.md` (blob 3a8c2cf13). Moved from Rocko
+to me by sage-2801 (Q220, mos-1301). Base: 78b69e1e6 (r2; r1 was aca16404c). Branch: `darkwing/row211-r2`
+(r1 `darkwing/row211` 6db25b1f0 stays as pushed). Reviewer: Dewey. Gate owner: Sage.
+
+## What ships
+
+- `scripts/git-hooks/pre-push` (new, `/bin/sh`). For each ref line on stdin it refuses:
+  - a delete (local sha all zeros);
+  - a remote tip that isn't in this repository (`git cat-file -e <remote>^{commit}`), with "fetch first,
+    then push again";
+  - a remote tip that isn't an ancestor of the local tip (`git merge-base --is-ancestor`), naming the ref
+    and both shas;
+  - an ancestor check that fails for any other reason (exit above 1);
+  - a short or overlong ref line, or a non-hex object name.
+
+  A new ref (remote sha all zeros) passes, and so does an empty push. It fetches nothing. On any refusal
+  it prints one line per refused ref and a closing line, and exits 1, so git pushes no ref at all.
+- `scripts/install-git-hooks.sh` (new). Installs the hook as `pre-push` in the common `.git/hooks`
+  (`git rev-parse --git-common-dir`), so a `--repo` naming a worktree lands in the shared directory.
+  It refuses (exit 2):
+  - a set `core.hooksPath` at any scope;
+  - a different installed `pre-push`, unless `--force-install` is given;
+  - a symlinked `pre-push`, even with `--force-install`;
+  - any of `GIT_DIR`, `GIT_WORK_TREE`, `GIT_COMMON_DIR`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY` or
+    `GIT_ALTERNATE_OBJECT_DIRECTORIES` in the environment;
+  - a directory that isn't a git checkout.
+
+  It never writes the installed file in place. A new hook goes in by `link()` from a temporary copy, so
+  a hook that appeared meanwhile is kept and the install refuses. A replacement goes in by `rename()`.
+  Then it compares the bytes, checks the mode, and runs a canary through `git hook run` (git 2.55 here):
+  an empty push must pass and a delete line must be refused with the guard's message.
+- `scripts/slot-busy.sh` (new). Exit 0 CLEAR, 1 BUSY, 2 its own error, one `BUSY <pid> <rule> cwd=<cwd>
+  <command>` line per match. Rules: `node ... --test`, `*gate*.sh` (after a space, `/`, `_` or `-`), a
+  `mutant` substring, `test-*.sh`, `docker compose` and `docker-compose`. It skips its own pid and its
+  ancestors, empty command lines (kernel threads) and shell-snapshot wrappers.
+- `scripts/test-git-guard.sh` (new), 61 cases, and three Maintenance rows plus a short section in
+  `docs/TOOLS.md`.
+
+## Choices
+
+1. **A separate `scripts/install-git-hooks.sh`, not `queue-commit.sh --install-push-hook`.** The brief
+   left this open. `queue-commit.sh --install-hook` is the queue guard's installer. It is tied to the
+   canonical checkout and to the lead (jason/sage) and runs the queue guard's canary. The push guard has
+   neither tie: it must also be installable in a scratch clone for the tests, and every seat worktree
+   shares it. Putting it in `queue-commit.sh` would widen that script's reach for no gain. The cost is a
+   second installer with a similar shape. The install pattern (copy beside, link or rename, verify,
+   canary) follows `queue-commit.sh`.
+2. **No privilege check in the installer.** The brief makes the canonical install a separate step with
+   Sage after landing, and the tests need to install into scratch clones as the suite's user. So the
+   script installs wherever it is told. The guard is advisory on the client in any case (`--no-verify`).
+3. **The hook source is the working file next to the installer** (`$ROOT/scripts/git-hooks/pre-push`),
+   not a blob from a ref. That lets the mutant runner install a mutated copy from its own tree, and
+   matches how `queue-commit.sh` reads its guard.
+4. **A new `scripts/test-git-guard.sh`, not more cases in `test-land-work.sh`.** The brief allowed either.
+   Land-work's suite is about `land-work.sh`, and the gate runs every `scripts/test-*.sh`, so a new file
+   gets gated with no wiring.
+5. **`--proc-root DIR` is a test seam in `slot-busy.sh`.** On a live host the real `/proc` may hold
+   other seats' runs at any time, so the suite can't demand exit 0 there. Exit 0 and every rule are
+   tested against a fake `/proc` with pids above `pid_max` (4194304), so they can't collide with the
+   ancestor set, which always comes from the real `/proc`. The real `/proc` is tested with a stand-in:
+   a `/bin/sh` script named `node`, started as `node --test standin.test.mjs` in its own cwd. The suite
+   asserts its BUSY line with that cwd, exit 1, that `slot-busy > /dev/null && echo ran` prints nothing,
+   that the suite itself (an ancestor whose command line matches `test-*.sh`) has no BUSY line, and that
+   after the stand-in exits its pid is gone. The brief's "0 without one" is the fake-`/proc` case.
+6. **Ancestors are skipped**, not only its own pid as the brief says. A gate script that runs the busy
+   check matches its own rules (`*gate*.sh`, `test-*.sh`, `mutant`), so checking only `$$` would make
+   every such caller see itself as BUSY.
+7. **The gate rule is broader than `gate.sh`**: `[ /_-]gate[^ /]*\.sh `, so `sage-gate.sh` and
+   `gate-253.sh` match too. A false BUSY costs a wait; a false CLEAR costs a broken run.
+8. **Shell-snapshot wrappers are skipped.** An agent harness runs each command as `bash -c 'source
+   .../shell-snapshots/snapshot-*.sh && eval <command text>'`, so the wrapper's command line holds the
+   text of whatever the agent typed, including a busy check that names `test-*.sh`. The real child
+   processes the wrapper starts are still matched.
+
+## Tests (`scripts/test-git-guard.sh`)
+
+Scratch bare remote, a scratch clone with the guard installed, and a worktree of that clone. Git runs
+with `GIT_CONFIG_NOSYSTEM=1` and an empty `GIT_CONFIG_GLOBAL`, as in `test-land-work.sh`. Nothing touches
+origin, `~/.mosaic`, `~/.mosaic-dev` or `~/.config/mosaic-dev`.
+
+- Install: exit 0, the canary passed, bytes and mode, no temporary file left, and the worktree's git
+  resolves `hooks/pre-push` to the common file.
+- From the worktree: a new branch and a fast-forward pass. A `--force` push of a rewritten branch, a
+  `+refspec` push and a `--force-with-lease` push are refused by the guard's message, naming the ref and
+  both shas, and the remote ref is unchanged. `:ref` and `--delete` are refused and the branch stays.
+- A second clone moves the remote; a `--force` push from the worktree is then refused with "fetch
+  first", the remote stays where the other clone put it, and the guard fetched nothing.
+- The hook fed by hand: a short line, a non-hex name and an unknown local object are refused; an empty
+  push passes.
+- The installer: `core.hooksPath` set refuses with that message and writes no hook (in `.git/hooks` or
+  the hooks path). A different hook refuses and stays byte-identical. `--force-install` replaces it, and
+  a hard link to the old file keeps the old bytes, so the replacement was a rename. A second install of
+  the same bytes exits 0. A symlinked hook refuses even with `--force-install`. A `--repo` naming a
+  worktree lands in the common directory. `GIT_DIR` set, a plain directory and an unknown argument
+  refuse.
+- `slot-busy.sh`, fake `/proc`: CLEAR with exit 0 when nothing matches (a server, a `grep gate`, a
+  snapshot wrapper whose text holds `node --test`, an empty command line). Exit 1 and the BUSY line for
+  `node --test`, with no CLEAR in the output, and `> /dev/null && echo ran` prints nothing. Each rule
+  once more (7 cases). Exit 2 for a missing root, an empty root and an unknown argument.
+- `slot-busy.sh`, real `/proc`: the stand-in cases in choice 5.
+
+## Mutants (`agents/darkwing/work/queue-211/mutants.sh`)
+
+Each mutant copies the four scripts into its own tree, edits one site there (exactly one match), and runs
+that tree's suite under `timeout -k 10 180`. The worktree's files are never edited. The unmutated suite
+runs first and a red base stops the run. The brief's five come first:
+
+| Mutant | Site |
+|---|---|
+| ancestor-dropped | pre-push: `rc=0` in place of the `merge-base --is-ancestor` call |
+| unknown-object-passes | pre-push: the missing-remote-tip branch skips the ref without refusing |
+| delete-passes | pre-push: the delete branch skips the ref without refusing |
+| install-over-hookspath | installer: the `core.hooksPath` refusal is `true \|\| die` |
+| busy-exits-0 | slot-busy: `exit 0` when BUSY |
+| differing-hook-replaced | installer: a different hook is replaced without `--force-install` |
+| replace-in-place | installer: the replacement writes into the installed file (`cat >`) instead of renaming |
+| symlink-followed | installer: no symlink refusal |
+| ancestor-error-passes | pre-push: an ancestor check exiting above 1 doesn't refuse |
+| snapshot-matched | slot-busy: no shell-snapshot skip |
+| ancestors-matched | slot-busy: no ancestor skip |
+| no-node-rule | slot-busy: the `node --test` rule removed |
+| no-compose-rule | slot-busy: the `docker compose` rule removed |
+
+`install-over-hookspath` still exits 2, because its canary then fails (git looks for the hook in the hooks
+path). The suite kills it on the message and on "no hook was written", not on the exit code.
+
+## Rebase r2 (sage-4362, 2026-10-24)
+
+r1 6db25b1f0 sat on aca16404c, 555 commits behind refactor, and overlapped it in `docs/TOOLS.md`. r2
+cherry-picks it onto 78b69e1e6 as a new commit on a new branch; no force-push. The TOOLS.md hunk merged
+without a conflict, `git patch-id --stable` is the same for both commits (db451e11), and the four scripts,
+`mutants.sh` and this file's other text are byte-identical to r1, so no assertion or reviewed line
+changed. On the new base none of the six paths existed before, `scripts/git-hooks/` holds only the queue
+guard's `pre-commit` (untouched here), and no test reads or pins `docs/TOOLS.md`.
+
+## Runs
+
+Pending: nothing has run yet. Gander held the gate slot (row 253 run 5, from 16:32Z) while this was
+written, so only `bash -n`, `sh -n` and a `DRY=1` mutant pass (every site matched once, no suite run)
+happened. The suite, the mutants and every other `scripts/test-*.sh` run in a CLEAR Sage announces, with
+`TMPDIR` under `/mnt/storage/scratch/tmp`. Results and the measured suite time go here before review.
+
+## Known limits
+
+- `git push --no-verify` skips the hook. Gitea branch protection (ops-01, through Mos) is the guard that
+  holds.
+- The hook doesn't check tags differently from branches: a moved tag is refused like a rewritten branch.
+- `slot-busy.sh` can call a process BUSY that isn't a run, for example an editor with a `test-*.sh` open.
+  It never reads files under a seat's directory, so it can't tell.
+
+## R3, the GPT review (2026-11-02)
+
+The lead's implementation sub-agent (Claude Opus 5.5, a child of Sage's T3 c5c1e8ba) wrote this round from
+the brief `/mnt/storage/scratch/mosaic-lead/briefs/row211-r3-fix.md` and the review
+`/mnt/storage/scratch/mosaic-lead/reviews/batch1-a-gpt.md` (F1 to F5 and the edge-case table). Base
+09a847eda, branch `t3/row211-push-guard-r3-fix`: dca5f10cc and 3e39689c1 picked clean as 5734c1a80 and
+c8f2cb70c, then one R3 commit. The suite goes from 61 cases to 85 and the mutants from 13 to 21. The
+sections above stay as written; where R3 changes them, it says so here.
+
+### F1: a failed read counted as a vanished process
+
+What: `slot-busy.sh` skipped any process whose cmdline read failed, so a live process it couldn't read (a
+mode-000 cmdline of a `node --test`, say) could end in CLEAR. Its own status read was unchecked too: it put
+`$$` in the skip set first, and a failed read only ended the ancestor walk.
+
+Fix: after a failed read the scan checks the pid directory. Gone means the process exited, and it's
+skipped. Still there is an error: the scan names that cmdline, counts it and goes on, so BUSY lines still
+print, then exits 2 and never prints CLEAR. Its own status must read and give a numeric PPid, or it exits 2
+before the scan. A failed read further up the walk still only ends the walk, which can give a false BUSY but
+never a false CLEAR.
+
+Tests, section "slot-busy, read errors" (fake `/proc`): "a pid directory with no cmdline: exit 2", "it
+names that cmdline and never says CLEAR", "a cmdline that can't be read (a directory): exit 2, no CLEAR", "a
+read error beside a BUSY process: exit 2, the BUSY line kept, no CLEAR", "a node --test process whose
+cmdline is unreadable (mode 000) is never CLEAR", "a failing read (tr exits 1) with every pid directory
+still there: exit 2, no CLEAR", "a process that vanishes during its read isn't an error: exit 0 and CLEAR"
+(a `tr` shim on PATH removes the pid directory, then fails) and "its own process unreadable (awk exits 1):
+exit 2, no CLEAR" (an `awk` shim).
+
+Mutants: `unreadable-read-clear` (every failed read skipped), `vanished-is-error` (no directory check, so
+an exited process is an error), `read-errors-ignored` (no final error exit) and `self-read-unchecked` (its
+own failed read ends the walk, as before).
+
+### F2: the snapshot exclusion matched a substring
+
+What: any command line holding `/shell-snapshots/snapshot-` was skipped, so a real `node --test` of a file
+under a `shell-snapshots` directory read as CLEAR.
+
+Fix: `RE_SNAPSHOT` matches only the wrapper's shape: a shell (`sh`, `bash` or `zsh`, with or without a
+path), options that include `-c`, then `source` or `.` of a `shell-snapshots/snapshot-*.sh` file as the
+first command. Any other command line that names such a path goes through the rules.
+
+Tests: "busy on: node --test /seat/tests/shell-snapshots/snapshot-guard.test.mjs (node --test)" and "busy
+on: bash /seat/shell-snapshots/snapshot-gate.sh (gate)".
+
+Mutant: `snapshot-substring` (the old substring test put back).
+
+### F3: an existing tag could be replaced or moved
+
+What: tags went through the ancestor check, and `git merge-base --is-ancestor` peels a tag. A new annotated
+tag object on the same commit, or a lightweight tag moved to a descendant, passed as a fast-forward.
+
+Fix: after the delete and new-ref checks and before the object and ancestor checks, a `refs/tags/*` ref
+whose remote object name isn't zero and differs from the local one is refused ("an existing tag can't be
+moved or replaced"). A new tag still passes, and a tag delete is still refused as a delete. This corrects
+the tag line in "Known limits" above: a moved tag was refused only when it left its line, not when
+it moved to a descendant or was re-made on the same commit.
+
+Tests, section "tags": "a new annotated tag passes", "push --force of a new tag object on the same commit
+is refused", "the remote tag is still the first tag object", "a new lightweight tag passes", "push --force
+of a lightweight tag moved to a descendant is refused", "the remote lightweight tag hasn't moved" and "a
+tag delete is refused, and the tag stays".
+
+Mutant: `tag-replace-passes`.
+
+### F4: a symlinked hooks directory
+
+What: the installer wrote through `.git/hooks` even when it was a symlink, so an install could set the hook
+of every repository sharing that directory, or write outside the repository.
+
+Fix: `own_hooks` refuses (exit 2) when `<common>/hooks` is a symlink, or when it exists and its physical
+path isn't the common directory's physical path plus `/hooks`. It runs before the pre-push symlink check
+and again after `mkdir -p`, so both checks come before the temporary file and any install write. The
+existing refusals (`core.hooksPath`, a different hook without `--force-install`, a symlinked `pre-push`)
+are unchanged.
+
+Tests: "the install refuses a symlinked hooks directory (exit 2)", "it refuses it with --force-install too"
+and "nothing was written in the directory the symlink names".
+
+Mutant: `hooks-dir-symlink-followed` (`own_hooks` returns at once).
+
+### F5: the snapshot fixture proved nothing
+
+What: the fixture wrapper ran `eval 'node --test x.test.mjs'`. There `node` follows a quote, and the node
+rule needs a space or `/` before it, so the fixture wasn't BUSY even without the exclusion and the
+`snapshot-matched` mutant survived.
+
+Fix: two wrappers whose text matches a rule without the exclusion. Pid 4194403 runs `node --test
+x.test.mjs` straight after the `source ... &&`. Pid 4194405 has the harness's real shape: `source ...
+2>/dev/null || true && eval 'bash scripts/test-x.sh > x.log' && pwd -P >| ...`. The paired BUSY case is the
+same node command under `/bin/bash -c` with no snapshot source. The F2 cases are above.
+
+Tests: "an agent's shell-snapshot wrapper isn't a match" (now neither 4194403 nor 4194405) and "busy on:
+/bin/bash -c node --test x.test.mjs (node --test)".
+
+Mutant: `snapshot-matched`, whose site is now the `RE_SNAPSHOT` test. It is killed (3 FAIL). The suite
+alone can't fail before this fix, because the old substring exclusion skips these wrappers too; the killed
+mutant is the before-and-after evidence.
+
+### Object names of the wrong length (the review's table)
+
+What: the hook took any hex string as an object name, so a remote field of `0` read as a new ref.
+
+Fix: after the non-hex check, each field must be exactly 40 or 64 characters, or the ref is refused.
+
+Tests: "a remote object name of 0 is refused, not read as a new ref", "a 39-character local object name is
+refused" and the control "a 64-character object name passes the length check (64 zeros refuse as a
+delete)".
+
+Mutant: `short-sha-accepted`.
+
+### What didn't change
+
+The earlier cases all still pass: an empty push, a new branch and a fast-forward pass; a delete, `--force`,
+`+refspec` and `--force-with-lease` rewrites are refused; a remote tip missing locally is refused with
+"fetch first", and nothing is fetched.
+
+### R3 runs
+
+`TMPDIR` was a fresh `mktemp -d /mnt/storage/scratch/tmp/XXXXXX`. Every run was in the foreground, with
+output to files there.
+
+- RED, all 24 new cases in place and no fix: 67 passed, 18 failed, 2026-11-02 19:27:01Z to 19:27:06Z. The
+  six new cases that pass there are controls that must hold before and after: both new tags pass, the tag
+  delete is refused, the 64-character control, the bare `bash -c` node case and the vanished process.
+- GREEN: 85 passed, 0 failed, 19:28:58Z to 19:29:04Z. The run before it gave 80 passed, 5 failed: the new
+  closing error said "not CLEAR", which the "no CLEAR" assertions caught. It now says "the host isn't
+  known to be idle".
+- Mutants: 19:30:11Z to 19:33:22Z, base green (85/0), runner exit 0, 21 of 21 killed, none survived, no
+  NO MATCH. Every kill exited 1.
+
+| Mutant | FAIL | First failing case |
+|---|---|---|
+| ancestor-dropped | 8 | push --force of a rewritten branch is refused |
+| unknown-object-passes | 2 | a push over a remote tip missing locally is refused, saying fetch first |
+| delete-passes | 12 | the install into a clean clone exits 0 |
+| install-over-hookspath | 2 | it says core.hooksPath is set |
+| busy-exits-0 | 14 | a node --test process: exit 1 |
+| differing-hook-replaced | 3 | the install refuses a different installed pre-push (exit 2) |
+| replace-in-place | 1 | the replacement was a rename: the old file keeps its bytes |
+| symlink-followed | 1 | the install refuses a symlinked pre-push, even with --force-install |
+| ancestor-error-passes | 1 | a failed ancestor check (an unknown local object) is refused |
+| snapshot-matched | 3 | no matching process: exit 0 and CLEAR |
+| ancestors-matched | 1 | this suite, an ancestor, has no BUSY line |
+| no-node-rule | 9 | a node --test process: exit 1 |
+| no-compose-rule | 2 | busy on: docker compose -p x up -d (docker compose) |
+| unreadable-read-clear | 6 | a pid directory with no cmdline: exit 2 |
+| vanished-is-error | 1 | a process that vanishes during its read isn't an error: exit 0 and CLEAR |
+| read-errors-ignored | 6 | a pid directory with no cmdline: exit 2 |
+| self-read-unchecked | 1 | its own process unreadable (awk exits 1): exit 2, no CLEAR |
+| snapshot-substring | 2 | busy on: node --test /seat/tests/shell-snapshots/snapshot-guard.test.mjs (node --test) |
+| tag-replace-passes | 4 | push --force of a new tag object on the same commit is refused |
+| hooks-dir-symlink-followed | 3 | the install refuses a symlinked hooks directory (exit 2) |
+| short-sha-accepted | 2 | a remote object name of 0 is refused, not read as a new ref |
+
+- Real host: `bash scripts/slot-busy.sh` on the real `/proc` exited 1 on other seats' gate and `node
+  --test` runs, with no error line. Both live shell-snapshot wrappers on the host matched `RE_SNAPSHOT`.
+- Pins: `git grep -nE '[0-9a-f]{64}' -- 'packages/*/tests/*' 'scripts/test-*.sh'` gives 33 lines (the
+  positive control). None names a path this round changes. The only test that names one is
+  `scripts/test-git-guard.sh` itself, and no test reads `docs/TOOLS.md`.
+
+### Known limits after R3
+
+- The tag line in "Known limits" above is superseded by F3. The other two lines still hold.
+- The resolved-path refusal in `own_hooks` has no test of its own. A hooks directory that isn't a symlink
+  but resolves elsewhere needs a bind mount, so root, and the symlink check catches the symlink case first.
+  `hooks-dir-symlink-followed` turns off both checks together.
+- A wrapper that sources a test script into its own shell, with no child process, is still skipped, as
+  before R3. That script's children are still matched.
+- The installer's temporary file is named by pid (`.pre-push.install-git-hooks.$$`). R3 leaves it alone.
+- The "Runs" section above was written before any run. The R3 runs here are the ones on record for this
+  round.

agents/darkwing/work/queue-211/mutants.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Row 211 (#426) mutants. Run from the candidate worktree's root:
+#   TMPDIR=<scratch dir> LOG=<dir> bash agents/darkwing/work/queue-211/mutants.sh > mutants.txt
+# Each mutant copies the four row-211 scripts into its own tree, edits one
+# site there (exactly one match, else NO MATCH), and runs that tree's
+# scripts/test-git-guard.sh under a 180 s timeout. The worktree's files are
+# never edited. "killed" means the suite failed; "survived" means it passed.
+# The unmutated suite runs first, and a red base stops the run (exit 3).
+set -u
+LOG=${LOG:-.}
+FILES="scripts/git-hooks/pre-push scripts/install-git-hooks.sh scripts/slot-busy.sh scripts/test-git-guard.sh"
+WORK=$(mktemp -d "${TMPDIR:-/tmp}/r211-mutants.XXXXXX") || exit 2
+trap 'rm -rf "$WORK"' EXIT
+
+tree() { # $1: name. Prints the copy's root.
+  local t="$WORK/$1" f
+  for f in $FILES; do mkdir -p "$t/$(dirname "$f")" && cp -p -- "$f" "$t/$f" || return 1; done
+  echo "$t"
+}
+suite() { # $1: tree, $2: log
+  timeout -k 10 180 bash "$1/scripts/test-git-guard.sh" > "$2" 2>&1
+}
+edit() { # $1: file, $2: from, $3: to. Exit 3 unless $2 occurs exactly once.
+  python3 -B - "$1" "$2" "$3" <<'PY'
+import sys
+path, old, new = sys.argv[1:4]
+text = open(path).read()
+if text.count(old) != 1:
+    sys.exit(3)
+open(path, "w").write(text.replace(old, new))
+PY
+}
+
+base=$(tree base) || exit 2
+if [ -n "${DRY:-}" ]; then
+  echo "base: not run (DRY)"
+elif suite "$base" "$LOG/mut-base.log"; then
+  echo "base: green ($(tail -1 "$LOG/mut-base.log"))"
+else
+  echo "base: RED, stopping ($(tail -1 "$LOG/mut-base.log"))"
+  exit 3
+fi
+
+run() { # $1: name, $2: file, $3: from, $4: to
+  local name=$1 file=$2 t log
+  t=$(tree "$name") || { echo "$name: COPY FAILED"; return; }
+  if ! edit "$t/$file" "$3" "$4"; then echo "$name: NO MATCH"; return; fi
+  if [ -n "${DRY:-}" ]; then echo "$name: match"; return; fi
+  log="$LOG/mut-$name.log"
+  if suite "$t" "$log"; then
+    echo "$name: survived"
+  else
+    echo "$name: killed (exit $?, $(grep -c '^FAIL' "$log") FAIL; first: $(grep -m1 '^FAIL' "$log" | cut -c6-100))"
+  fi
+}
+H=scripts/git-hooks/pre-push
+I=scripts/install-git-hooks.sh
+S=scripts/slot-busy.sh
+
+# The brief's five.
+run ancestor-dropped $H $'    git merge-base --is-ancestor "$rsha" "$lsha" 2>/dev/null\n    rc=$?' '    rc=0'
+run unknown-object-passes $H $'        refuse "$rref: the remote tip $rsha isn\'t in this repository; fetch first, then push again"\n        continue' '        continue'
+run delete-passes $H $'        refuse "$rref: a delete (remote $rsha); seat branches are never deleted by push"\n        continue' '        continue'
+run install-over-hookspath $I '[ -z "$out" ] || die 2 "refused: core.hooksPath' '[ -z "$out" ] || true || die 2 "refused: core.hooksPath'
+run busy-exits-0 $S 'if [ "$busy" = 1 ]; then exit 1; fi' 'if [ "$busy" = 1 ]; then exit 0; fi'
+# Further sites the suite pins.
+run differing-hook-replaced $I '[ "$FORCE" = 1 ] || die 2 "refused: a different' 'true || die 2 "refused: a different'
+run replace-in-place $I 'mv -f -- "$tmp" "$HOOK" ||' 'cat -- "$tmp" > "$HOOK" && rm -f -- "$tmp" ||'
+run symlink-followed $I 'if [ -L "$HOOK" ]; then die 2' 'if false; then die 2'
+run ancestor-error-passes $H '        *) refuse "$rref: the ancestor check failed' '        *) : "$rref: the ancestor check failed'
+run snapshot-matched $S $'  if [[ "$c" =~ $RE_SNAPSHOT ]]; then return 1; fi\n' ''
+run ancestors-matched $S '  [ -z "${SKIP[$pid]:-}" ] || continue' '  :'
+run no-node-rule $S 'if [[ "$c" =~ $RE_NODE ]]; then echo "node --test"; return 0; fi' ':'
+run no-compose-rule $S 'if [[ "$c" =~ $RE_COMPOSE ]]; then echo "docker compose"; return 0; fi' ':'
+# R3, the GPT review (F1 to F5 and the object-name length check).
+run unreadable-read-clear $S '    [ -e "$d" ] || continue' '    continue'
+run vanished-is-error $S $'    [ -e "$d" ] || continue\n' ''
+run read-errors-ignored $S '[ "$errors" = 0 ] || {' 'true || {'
+run self-read-unchecked $S '  || { echo "slot-busy: error: cannot read its own process" >&2; exit 2; }' '  || p=""'
+run snapshot-substring $S '[[ "$c" =~ $RE_SNAPSHOT ]]' '[[ "$c" == *"/shell-snapshots/snapshot-"* ]]'
+run tag-replace-passes $H 'if [ "${rref#refs/tags/}" != "$rref" ] && [ "$lsha" != "$rsha" ]; then' 'if false; then'
+run hooks-dir-symlink-followed $I 'own_hooks() {' 'own_hooks() { return 0;'
+run short-sha-accepted $H '    if ! idlen "$lsha" || ! idlen "$rsha"; then' '    if false; then'

docs/SESSIONS.md

@@ -1879,3 +1879,5 @@ are never rewritten or removed; corrections are new entries.
 2026-10-26 | Sage | mos1884/#662 scope after330/331landing | ReadQ222/Q261/Q263 and659/660/662; posted bounded human-only factory settings/triage/defaulttwo-roundmandate/trackedno-exemptionflake scope with10acceptance criteria, task662comment1338 exactwholebody/author13GETverified. No implementation/review/gate launched.660c1335notready(review/merge, noVM); gatefacts1329/1334 retained; target integration/fullrunner confirmation follows readiness, no localfallback. Landedproduct/evidence unchanged;657/658backlog.
 
 2026-10-26 | Sage | Mos1909/1915/1917 real postlanding reviews | Boyd/Dewey/Filbert/Gladstone real authored candidate52ba verdictfiles independently byte/hash-verified, allAPPROVE scoped; Dewey656broaderPARTIAL retained. Formal330R1/331R4 requests failedpre-send/no comments or approvals; no borrowed/copied/mintedkeys. LegacyhelperGETname jason.woltje is NOT ownJarvis, ownslotabsent; rows tracking-open/#436, files cited via normalqueue. NewFilbertNEW-330-01 filedtask665 exactreadback, notlandingreopen/gate. Repair646-648/652-656 remainOPEN untilactualcomments;1917 conditionalbacklog routing retained. #662scope1338posted;660PR405REVISE/notready. Product1968inputs unchanged; no source/helper/test/gate edits/runs; peerjournal prefixes preserved.
+
+2026-11-02 | Sage implementation sub-agent (Claude Opus 5.5, child of T3 c5c1e8ba) | row 211 (#1709/#426) R3 from the GPT review, on t3/row211-push-guard-r3-fix over 09a847eda (picks 5734c1a80, c8f2cb70c) | F1-F5 and the object-name length check fixed with tests; suite RED 67/18, GREEN 85/0; 21 of 21 mutants killed; one local commit, not pushed

docs/TOOLS.md

@@ -166,8 +166,42 @@ resolved through the CLI.
 | `scripts/test-conductor.sh` | Auto-apply selftests (sandboxed) | 17 cases |
 | `scripts/test-auth.sh` | Auth checkpoint selftests (no Docker) | 13 cases |
 | `scripts/test-land-work.sh` | Land-work selftests (sandboxed, fake Docker) | 84 cases |
+| `scripts/test-git-guard.sh` | Push guard, its installer and `slot-busy.sh` (scratch bare remote, fake `/proc`) | 85 cases |
+| `scripts/install-git-hooks.sh [--repo DIR] [--force-install]` | Install the push guard as `pre-push` in the common `.git/hooks` | Refuses a set `core.hooksPath`, a symlinked hooks directory or a different installed hook; exit 0 ok · 1 failed · 2 refused · 4 usage |
+| `scripts/slot-busy.sh` | Busy check: one `BUSY` line per gate or test process, or `CLEAR` | Exit 0 CLEAR · 1 BUSY · 2 error, including a process it can't read; chain on the exit code |
 | `scripts/gitea-api.sh <METHOD> <path> [body]` | Gitea API helper; reads the JSON credential file or a raw per-seat token file | Token never on argv/stdout |
 
+### Push guard and busy check (row 211, #426)
+
+`scripts/git-hooks/pre-push` refuses a push that deletes a branch, or that
+moves a branch to a commit that doesn't descend from the remote tip (a
+`--force`, `--force-with-lease` or `+refspec` push of a rewritten branch). A
+new branch and a fast-forward pass. It refuses any change to an existing tag,
+including a new tag object on the same commit; a new tag passes. The hook
+fetches nothing: when the remote tip isn't in the local repository it refuses
+and says to fetch first.
+`git push --no-verify` skips it, so Gitea's branch protection (ops-01) is the
+guard that holds. `scripts/install-git-hooks.sh` copies it into the common
+`.git/hooks`, which every worktree of the checkout shares, refusing a hooks
+directory that is a symlink, then runs a canary
+through `git hook run`. Installing it in the canonical checkout is a step for
+the lead after the row lands.
+
+Chain the busy check on its exit code, and set `pipefail` in any script that
+pipes it:
+
+```bash
+bash scripts/slot-busy.sh > "$LOG" && gate
+```
+
+Never `bash scripts/slot-busy.sh | tail -1 && gate`: `tail` exits 0, so the
+gate runs while BUSY. It matches `node ... --test`, a `*gate*.sh`, `mutant`, a
+`test-*.sh` and `docker compose` command lines, skips itself, its ancestors
+and agent shell-snapshot wrappers (a shell whose `-c` text starts by sourcing
+`.../shell-snapshots/snapshot-*.sh`), and reads only `/proc/<pid>/cmdline`, the
+cwd link and its own and its ancestors' `status`. A process it can't read that
+hasn't exited makes it exit 2, never CLEAR.
+
 ## Seat launch with registration (`scripts/mosaic`)
 
 ```bash

scripts/git-hooks/pre-push

@@ -0,0 +1,64 @@
+#!/bin/sh
+# Mosaic push guard (row 211, #426). Installed as pre-push in the common
+# .git/hooks by `scripts/install-git-hooks.sh`; never edit the installed copy.
+# For each ref git is about to push, it refuses a delete and any update whose
+# remote tip isn't an ancestor of the local tip: a force-push or a +refspec.
+# It refuses any change to an existing tag, and an object name that isn't 40
+# or 64 hex characters. A new ref passes. It fetches nothing, so a remote tip
+# that isn't in this repository refuses. Any failure of the check refuses too.
+# `git push --no-verify` skips this hook; Gitea's branch protection is the
+# guard that holds (ops-01). Canon: never force-push.
+refused=0
+refuse() {
+    echo "mosaic push guard: refused: $*" >&2
+    refused=1
+}
+zero() {
+    case "$1" in *[!0]*) return 1 ;; esac
+    return 0
+}
+idlen() { # $1: an object name. True at 40 (SHA-1) or 64 (SHA-256) characters.
+    [ "${#1}" -eq 40 ] || [ "${#1}" -eq 64 ]
+}
+while read -r lref lsha rref rsha extra || [ -n "${lref:-}" ]; do
+    if [ -z "${rsha:-}" ] || [ -n "${extra:-}" ]; then
+        refuse "unreadable ref line from git: $lref ${lsha:-} ${rref:-} ${rsha:-} ${extra:-}"
+        continue
+    fi
+    case "$lsha$rsha" in
+        *[!0-9a-f]*) refuse "$rref: a ref line with a non-hex object name (local $lsha, remote $rsha)"; continue ;;
+    esac
+    if ! idlen "$lsha" || ! idlen "$rsha"; then
+        refuse "$rref: a ref line with an object name that isn't 40 or 64 hex characters (local $lsha, remote $rsha)"
+        continue
+    fi
+    if zero "$lsha"; then
+        refuse "$rref: a delete (remote $rsha); seat branches are never deleted by push"
+        continue
+    fi
+    if zero "$rsha"; then
+        continue
+    fi
+    # An existing tag never changes. A new tag object on the same commit, or
+    # a tag moved to a descendant, would pass the ancestor check below.
+    if [ "${rref#refs/tags/}" != "$rref" ] && [ "$lsha" != "$rsha" ]; then
+        refuse "$rref: an existing tag can't be moved or replaced (remote $rsha, local $lsha); push a new tag instead"
+        continue
+    fi
+    if ! git cat-file -e "$rsha^{commit}" 2>/dev/null; then
+        refuse "$rref: the remote tip $rsha isn't in this repository; fetch first, then push again"
+        continue
+    fi
+    git merge-base --is-ancestor "$rsha" "$lsha" 2>/dev/null
+    rc=$?
+    case $rc in
+        0) ;;
+        1) refuse "$rref: not a fast-forward; remote $rsha isn't an ancestor of local $lsha (a force-push or a rewritten branch)" ;;
+        *) refuse "$rref: the ancestor check failed (exit $rc) for remote $rsha and local $lsha" ;;
+    esac
+done
+if [ "$refused" != 0 ]; then
+    echo "mosaic push guard: nothing was pushed; a pushed branch only moves forward (canon: never force-push)" >&2
+    exit 1
+fi
+exit 0

scripts/install-git-hooks.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# install-git-hooks.sh: install the push guard (row 211, #426) as pre-push in
+# a repository's common .git/hooks, which every linked worktree shares.
+#
+# Usage:
+#   scripts/install-git-hooks.sh [--repo DIR] [--force-install]
+#
+# DIR defaults to this script's own checkout. The hook's bytes are this
+# checkout's scripts/git-hooks/pre-push. It refuses when core.hooksPath is set
+# (git would not run the hook), when the hooks directory is a symlink or
+# resolves anywhere but the common directory's hooks, and when a different
+# pre-push is installed, unless --force-install is given. It never edits an
+# installed hook in place:
+# a new hook is linked in, a replacement is renamed over the old one. A canary
+# then runs the installed hook through git and needs a delete refused.
+#
+# Exit codes: 0 installed (or already the same bytes); 1 failed; 2 refused;
+# 4 usage. Installing in the canonical checkout is its own step with the lead.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
+SRC="$ROOT/scripts/git-hooks/pre-push"
+TMPD=""
+
+say() { printf 'install-git-hooks: %s\n' "$*" >&2; }
+die() { local code=$1; shift; say "$*"; exit "$code"; }
+cleanup() { if [ -n "$TMPD" ]; then rm -rf -- "$TMPD"; fi; }
+trap cleanup EXIT
+
+usage() {
+  sed -n '5,6p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' >&2
+  exit 4
+}
+
+REPO=$ROOT
+FORCE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) [ $# -ge 2 ] || usage; REPO=$2; shift 2 ;;
+    --force-install) FORCE=1; shift ;;
+    -h|--help) usage ;;
+    *) say "unknown argument: $1"; usage ;;
+  esac
+done
+
+for v in GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES; do
+  if [ -n "${!v+x}" ]; then die 2 "refused: $v is set; run with the normal git environment"; fi
+done
+[ -f "$SRC" ] && [ ! -L "$SRC" ] || die 2 "refused: $SRC is missing or not a regular file"
+
+g() { git -C "$REPO" "$@"; }
+top=$(g rev-parse --show-toplevel 2>/dev/null) || die 2 "refused: $REPO is not a git checkout"
+common=$(g rev-parse --path-format=absolute --git-common-dir) || die 1 "cannot read $REPO's git common directory"
+HOOKS="$common/hooks"
+HOOK="$HOOKS/pre-push"
+
+out=$(g config --show-scope --get-all core.hooksPath 2>/dev/null)
+[ -z "$out" ] || die 2 "refused: core.hooksPath is set ($(printf '%s' "$out" | tr '\n\t' '; ')), so git would not run the push guard; unset it first"
+
+# The hooks directory must be the common directory's own. Through a symlink
+# to a shared directory, the install would set the hook of every repository
+# that shares it. Checked before and after mkdir, before any file is written.
+own_hooks() {
+  local real want
+  [ ! -L "$HOOKS" ] || die 2 "refused: $HOOKS is a symlink; install only into the repository's own hooks directory"
+  [ -e "$HOOKS" ] || return 0
+  real=$(cd -P -- "$HOOKS" && pwd -P) && want="$(cd -P -- "$common" && pwd -P)/hooks" || die 1 "cannot resolve $HOOKS"
+  [ "$real" = "$want" ] || die 2 "refused: $HOOKS resolves to $real, not $want"
+}
+own_hooks
+if [ -L "$HOOK" ]; then die 2 "refused: $HOOK is a symlink; remove it by hand if it is not wanted"; fi
+mkdir -p "$HOOKS" || die 1 "cannot create $HOOKS"
+own_hooks
+tmp="$HOOKS/.pre-push.install-git-hooks.$$"
+if [ -e "$HOOK" ]; then
+  [ -f "$HOOK" ] || die 2 "refused: $HOOK is not a regular file"
+  if cmp -s "$SRC" "$HOOK"; then
+    chmod 0755 "$HOOK" || die 1 "chmod failed"
+    note="the same bytes were already there"
+  else
+    [ "$FORCE" = 1 ] || die 2 "refused: a different pre-push hook is installed at $HOOK; compare it with $SRC, and pass --force-install to replace it"
+    cp -- "$SRC" "$tmp" && chmod 0755 "$tmp" || { rm -f -- "$tmp"; die 1 "cannot write $tmp"; }
+    # rename() swaps the whole file; the old hook's bytes are never edited.
+    mv -f -- "$tmp" "$HOOK" || { rm -f -- "$tmp"; die 1 "cannot replace $HOOK"; }
+    note="replaced a different hook (--force-install)"
+  fi
+else
+  cp -- "$SRC" "$tmp" && chmod 0755 "$tmp" || { rm -f -- "$tmp"; die 1 "cannot write $tmp"; }
+  # link() never replaces, so a hook that appeared meanwhile is kept.
+  if ! ln -- "$tmp" "$HOOK" 2>/dev/null; then rm -f -- "$tmp"; die 2 "refused: a pre-push hook appeared at $HOOK while installing"; fi
+  rm -f -- "$tmp"
+  note="new"
+fi
+
+cmp -s "$SRC" "$HOOK" || die 1 "$HOOK differs from $SRC after install"
+[ -x "$HOOK" ] || die 1 "$HOOK is not executable after install"
+
+# The canary: git runs the hook it would run for a push. A delete line needs
+# no objects; the guard must refuse it, and pass an empty push.
+TMPD=$(mktemp -d "${TMPDIR:-/tmp}/install-git-hooks.XXXXXX") || die 1 "mktemp failed"
+z=0000000000000000000000000000000000000000
+printf '(delete) %s refs/heads/install-canary 1%s\n' "$z" "${z#0}" > "$TMPD/delete"
+: > "$TMPD/empty"
+if ! out=$(cd "$top" && git hook run --to-stdin="$TMPD/empty" pre-push -- canary canary 2>&1); then
+  die 2 "refused: the canary's empty push failed, so git is not running the push guard as installed: $out"
+fi
+out=$(cd "$top" && git hook run --to-stdin="$TMPD/delete" pre-push -- canary canary 2>&1); rc=$?
+[ "$rc" -ne 0 ] && [[ "$out" == *"mosaic push guard: refused"* ]] \
+  || die 2 "refused: the canary's delete was not refused by the push guard (exit $rc)"
+
+printf 'ok installed the push guard at %s (%s, sha256 %s, mode 0755); canary passed\n' \
+  "$HOOK" "$note" "$(sha256sum < "$HOOK" | cut -d' ' -f1)"
+exit 0

scripts/slot-busy.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# slot-busy.sh: the shared busy check (row 211, #426). Is a gate or a test run
+# going on this host?
+#
+# Usage:
+#   scripts/slot-busy.sh [--proc-root DIR]
+#
+# It prints one BUSY line per matching process, or one CLEAR line. Exit codes:
+# 0 CLEAR, 1 BUSY, 2 its own error, which includes a process it can't read
+# that hasn't exited (it still prints any BUSY lines, never CLEAR). Chain it
+# on the exit code, never on a filter of its output:
+#   bash scripts/slot-busy.sh > LOG && gate          (set -o pipefail if piped)
+# never `bash scripts/slot-busy.sh | tail -1 && gate`, which runs while BUSY.
+#
+# A process matches when its command line holds `node ... --test`, a
+# `*gate*.sh`, `mutant`, a `test-*.sh` or `docker compose`/`docker-compose`.
+# It skips itself and its ancestors (a gate script may run the check), and an
+# agent harness's shell-snapshot wrapper (`bash -c 'source .../shell-snapshots/
+# snapshot-*.sh ...'`), whose command line is the agent's command text; that
+# shell's real children are still matched, and so is any other command line
+# that only names a shell-snapshots path. It reads only /proc/<pid>/cmdline,
+# the cwd link and its own and its ancestors' /proc/<pid>/status, never a
+# file under a seat's directory.
+# --proc-root names a stand-in for /proc in the selftests.
+set -uo pipefail
+
+PROC=/proc
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --proc-root) [ $# -ge 2 ] || { echo "slot-busy: error: --proc-root needs a directory" >&2; exit 2; }; PROC=$2; shift 2 ;;
+    -h|--help) sed -n '5,6p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' >&2; exit 2 ;;
+    *) echo "slot-busy: error: unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+[ -d "$PROC" ] || { echo "slot-busy: error: $PROC is not a directory" >&2; exit 2; }
+
+# This process and its ancestors, from the real /proc. Its own status must
+# read and name a parent; a failed read further up only ends the walk, which
+# can give a false BUSY but never a false CLEAR.
+declare -A SKIP=()
+p=$(awk '/^PPid:/{print $2; exit}' "/proc/$$/status" 2>/dev/null) && [[ "$p" =~ ^[0-9]+$ ]] \
+  || { echo "slot-busy: error: cannot read its own process" >&2; exit 2; }
+SKIP[$$]=1
+while [ -n "$p" ] && [ "$p" != 0 ]; do
+  SKIP[$p]=1
+  p=$(awk '/^PPid:/{print $2; exit}' "/proc/$p/status" 2>/dev/null) || p=""
+done
+
+RE_NODE='[ /]node[^ ]* (.* )?--test '
+RE_GATE='[ /_-]gate[^ /]*\.sh '
+RE_TEST='[ /]test-[^ /]*\.sh '
+RE_COMPOSE='[ /]docker( compose|-compose) '
+# The wrapper's shape: a shell, its options with -c, then `source` (or `.`)
+# of a shell-snapshots/snapshot-*.sh file as the first command.
+RE_SNAPSHOT='^ (/[^ ]*/)?(ba|z)?sh( -[a-zA-Z]+)* -[a-zA-Z]*c[a-zA-Z]*( -[a-zA-Z]+)* (source|\.) [^ ]*/shell-snapshots/snapshot-[^ /]*\.sh '
+match() { # $1: the command line, NULs as spaces. Prints the rule that matched.
+  local c=" $1 "
+  if [[ "$c" =~ $RE_SNAPSHOT ]]; then return 1; fi
+  if [[ "$c" =~ $RE_NODE ]]; then echo "node --test"; return 0; fi
+  if [[ "$c" =~ $RE_GATE ]]; then echo "gate"; return 0; fi
+  if [[ "$c" == *mutant* ]]; then echo "mutant"; return 0; fi
+  if [[ "$c" =~ $RE_TEST ]]; then echo "test script"; return 0; fi
+  if [[ "$c" =~ $RE_COMPOSE ]]; then echo "docker compose"; return 0; fi
+  return 1
+}
+
+seen=0
+busy=0
+errors=0
+for d in "$PROC"/[0-9]*; do
+  [ -d "$d" ] || continue
+  pid=${d##*/}
+  [[ "$pid" =~ ^[0-9]+$ ]] || continue
+  seen=$((seen + 1))
+  [ -z "${SKIP[$pid]:-}" ] || continue
+  # A process can exit between the listing and the read; that's not an error.
+  # A failed read while its directory is still there is: the scan can't say
+  # what that process runs.
+  if ! cmd=$(tr '\0' ' ' < "$d/cmdline" 2>/dev/null); then
+    [ -e "$d" ] || continue
+    echo "slot-busy: error: cannot read $d/cmdline" >&2
+    errors=$((errors + 1))
+    continue
+  fi
+  cmd=${cmd% }
+  [ -n "$cmd" ] || continue
+  rule=$(match "$cmd") || continue
+  cwd=$(readlink "$d/cwd" 2>/dev/null) || cwd="?"
+  printf 'BUSY %s %s cwd=%s %s\n' "$pid" "$rule" "$cwd" "${cmd:0:200}"
+  busy=1
+done
+[ "$seen" -ge 1 ] || { echo "slot-busy: error: no processes under $PROC" >&2; exit 2; }
+[ "$errors" = 0 ] || { echo "slot-busy: error: $errors process(es) could not be read, so the host isn't known to be idle" >&2; exit 2; }
+if [ "$busy" = 1 ]; then exit 1; fi
+echo "CLEAR"
+exit 0

scripts/test-git-guard.sh

@@ -0,0 +1,355 @@
+#!/usr/bin/env bash
+# Sandboxed selftests for the push guard, its installer and the busy check
+# (row 211, #426): scripts/git-hooks/pre-push, scripts/install-git-hooks.sh
+# and scripts/slot-busy.sh.
+#
+# Pushes go from a scratch clone and its worktree to a scratch bare remote,
+# never to origin. Git sees no user or system config. The busy check runs
+# against a fake /proc (pids above pid_max) for the exit codes and rules, and
+# against the real /proc with a sleeping stand-in whose argv is `node --test`.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+REPO="$(pwd)"
+unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
+
+SANDBOX="$(cd "$(mktemp -d)" && pwd -P)"
+STANDIN=""
+cleanup() {
+    if [ -n "$STANDIN" ]; then kill "$STANDIN" 2>/dev/null; wait "$STANDIN" 2>/dev/null; fi
+    rm -rf "$SANDBOX"
+}
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+# Status colors: terminal-only, NO_COLOR-respecting; plain when piped.
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+    C_OK=$'\033[0;32m'; C_FAIL=$'\033[0;31m'; C_RESET=$'\033[0m'
+else
+    C_OK=""; C_FAIL=""; C_RESET=""
+fi
+check() {
+    if [ "$2" = "0" ]; then PASS=$((PASS+1)); echo "${C_OK}OK${C_RESET}    $1"; else FAIL=$((FAIL+1)); echo "${C_FAIL}FAIL${C_RESET} $1"; fi
+}
+has() { [[ "$1" == *"$2"* ]]; }
+
+# Git sees no user or system config: no hooks path, no signing, a fixed identity.
+: > "$SANDBOX/gitconfig"
+export GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL="$SANDBOX/gitconfig"
+export GIT_AUTHOR_NAME=suite GIT_AUTHOR_EMAIL=suite@local GIT_COMMITTER_NAME=suite GIT_COMMITTER_EMAIL=suite@local
+
+HOOK_SRC="$REPO/scripts/git-hooks/pre-push"
+INSTALL="$REPO/scripts/install-git-hooks.sh"
+BUSY="$REPO/scripts/slot-busy.sh"
+
+B="$SANDBOX/remote.git"
+C="$SANDBOX/clone"
+W="$SANDBOX/wt"
+O="$SANDBOX/other"
+commit() { # $1: repo, $2: file and message
+    echo "$2" > "$1/$2" && git -C "$1" add "$2" && git -C "$1" commit -q -m "$2"
+}
+rtip() { git -C "$B" rev-parse -q --verify "refs/heads/$1"; }
+
+# ---- the remote, a clone with the guard, a worktree ----
+git init -q --bare -b main "$B"
+git init -q -b main "$SANDBOX/seed"
+commit "$SANDBOX/seed" base
+git -C "$SANDBOX/seed" push -q "$B" main
+git clone -q "$B" "$C"
+
+echo "== install =="
+out=$(bash "$INSTALL" --repo "$C" 2>&1); rc=$?
+check "the install into a clean clone exits 0" "$rc"
+check "it reports the install and a passed canary" "$(has "$out" "ok installed the push guard" && has "$out" "canary passed"; echo $?)"
+check "the hook is in the common .git/hooks, with the repository's bytes, executable" \
+    "$(cmp -s "$HOOK_SRC" "$C/.git/hooks/pre-push" && [ -x "$C/.git/hooks/pre-push" ]; echo $?)"
+check "no temporary file is left in .git/hooks" \
+    "$(ls -A "$C/.git/hooks" | grep -q '^\.pre-push\.install'; [ $? = 1 ]; echo $?)"
+git -C "$C" worktree add -q -b seat/w "$W" origin/main
+check "the worktree's git runs the common hook" \
+    "$([ "$(git -C "$W" rev-parse --path-format=absolute --git-path hooks/pre-push)" = "$C/.git/hooks/pre-push" ]; echo $?)"
+
+echo "== pushes from the worktree =="
+commit "$W" one
+out=$(git -C "$W" push origin seat/w 2>&1); rc=$?
+check "a new branch passes" "$rc"
+check "the remote branch is at the pushed commit" "$([ "$(rtip seat/w)" = "$(git -C "$W" rev-parse HEAD)" ]; echo $?)"
+
+commit "$W" two
+out=$(git -C "$W" push origin seat/w 2>&1); rc=$?
+check "a fast-forward passes" "$rc"
+check "the remote branch moved forward" "$([ "$(rtip seat/w)" = "$(git -C "$W" rev-parse HEAD)" ]; echo $?)"
+
+before=$(rtip seat/w)
+git -C "$W" reset -q --hard HEAD~1
+commit "$W" two-rewritten
+after=$(git -C "$W" rev-parse HEAD)
+out=$(git -C "$W" push --force origin seat/w 2>&1); rc=$?
+check "push --force of a rewritten branch is refused" "$([ "$rc" -ne 0 ]; echo $?)"
+check "the refusal is the guard's, and names the ref and both shas" \
+    "$(has "$out" "mosaic push guard: refused: refs/heads/seat/w: not a fast-forward" && has "$out" "$before" && has "$out" "$after"; echo $?)"
+check "the remote ref is unchanged after the refused --force" "$([ "$(rtip seat/w)" = "$before" ]; echo $?)"
+
+out=$(git -C "$W" push origin +seat/w:seat/w 2>&1); rc=$?
+check "a +refspec push is refused" "$([ "$rc" -ne 0 ] && has "$out" "not a fast-forward"; echo $?)"
+check "the remote ref is unchanged after the refused +refspec" "$([ "$(rtip seat/w)" = "$before" ]; echo $?)"
+
+out=$(git -C "$W" push --force-with-lease origin seat/w 2>&1); rc=$?
+check "push --force-with-lease is refused too" "$([ "$rc" -ne 0 ] && has "$out" "not a fast-forward"; echo $?)"
+
+out=$(git -C "$W" push origin :seat/w 2>&1); rc=$?
+check "a delete (:ref) is refused" "$([ "$rc" -ne 0 ] && has "$out" "mosaic push guard: refused: refs/heads/seat/w: a delete"; echo $?)"
+out=$(git -C "$W" push --delete origin seat/w 2>&1); rc=$?
+check "a delete (--delete) is refused" "$([ "$rc" -ne 0 ] && has "$out" "a delete"; echo $?)"
+check "the remote branch still exists after the refused deletes" "$([ "$(rtip seat/w)" = "$before" ]; echo $?)"
+
+# Another clone moves the remote; this clone never fetches it.
+git clone -q -b seat/w "$B" "$O"
+commit "$O" from-other
+git -C "$O" push -q origin seat/w
+moved=$(rtip seat/w)
+check "the other clone moved the remote, and this clone lacks that commit" \
+    "$([ "$moved" != "$before" ] && ! git -C "$C" cat-file -e "$moved^{commit}" 2>/dev/null; echo $?)"
+out=$(git -C "$W" push --force origin seat/w 2>&1); rc=$?
+check "a push over a remote tip missing locally is refused, saying fetch first" \
+    "$([ "$rc" -ne 0 ] && has "$out" "isn't in this repository; fetch first"; echo $?)"
+check "the remote ref is unchanged after that refusal" "$([ "$(rtip seat/w)" = "$moved" ]; echo $?)"
+check "the guard fetched nothing" "$(! git -C "$C" cat-file -e "$moved^{commit}" 2>/dev/null; echo $?)"
+
+echo "== tags =="
+# An existing tag never changes. Both cases below pass the ancestor check: a
+# new tag object on the same commit peels to that commit, and a moved
+# lightweight tag's old commit is an ancestor of its new one.
+tagtip() { git -C "$B" rev-parse -q --verify "refs/tags/$1"; }
+git -C "$W" tag -a -m first t-ann HEAD
+out=$(git -C "$W" push origin t-ann 2>&1); rc=$?
+check "a new annotated tag passes" "$([ "$rc" = 0 ] && [ "$(tagtip t-ann)" = "$(git -C "$W" rev-parse t-ann)" ]; echo $?)"
+first=$(tagtip t-ann)
+git -C "$W" tag -f -a -m second t-ann HEAD >/dev/null
+out=$(git -C "$W" push --force origin t-ann 2>&1); rc=$?
+check "push --force of a new tag object on the same commit is refused" \
+    "$([ "$rc" -ne 0 ] && has "$out" "mosaic push guard: refused: refs/tags/t-ann: an existing tag" && has "$out" "$first"; echo $?)"
+check "the remote tag is still the first tag object" "$([ "$(tagtip t-ann)" = "$first" ]; echo $?)"
+git -C "$W" tag t-light HEAD~1
+out=$(git -C "$W" push origin t-light 2>&1); rc=$?
+check "a new lightweight tag passes" "$rc"
+git -C "$W" tag -f t-light HEAD >/dev/null
+out=$(git -C "$W" push --force origin t-light 2>&1); rc=$?
+check "push --force of a lightweight tag moved to a descendant is refused" \
+    "$([ "$rc" -ne 0 ] && has "$out" "mosaic push guard: refused: refs/tags/t-light: an existing tag"; echo $?)"
+check "the remote lightweight tag hasn't moved" "$([ "$(tagtip t-light)" = "$(git -C "$W" rev-parse HEAD~1)" ]; echo $?)"
+out=$(git -C "$W" push origin :refs/tags/t-light 2>&1); rc=$?
+check "a tag delete is refused, and the tag stays" \
+    "$([ "$rc" -ne 0 ] && has "$out" "refs/tags/t-light: a delete" && [ -n "$(tagtip t-light)" ]; echo $?)"
+
+echo "== the hook, fed by hand =="
+z=0000000000000000000000000000000000000000
+hookrun() { (cd "$C" && printf '%s\n' "$1" | sh "$C/.git/hooks/pre-push" origin "$B" 2>&1); }
+out=$(hookrun "refs/heads/x $(git -C "$C" rev-parse HEAD) refs/heads/x"); rc=$?
+check "a short ref line is refused" "$([ "$rc" -ne 0 ] && has "$out" "unreadable ref line"; echo $?)"
+out=$(hookrun "refs/heads/x HEAD refs/heads/x $z"); rc=$?
+check "a non-hex object name is refused" "$([ "$rc" -ne 0 ] && has "$out" "non-hex"; echo $?)"
+out=$(hookrun "refs/heads/x $(git -C "$C" rev-parse HEAD) refs/heads/x 0"); rc=$?
+check "a remote object name of 0 is refused, not read as a new ref" \
+    "$([ "$rc" -ne 0 ] && has "$out" "isn't 40 or 64 hex characters"; echo $?)"
+out=$(hookrun "refs/heads/x $(git -C "$C" rev-parse HEAD | cut -c1-39) refs/heads/x $z"); rc=$?
+check "a 39-character local object name is refused" "$([ "$rc" -ne 0 ] && has "$out" "isn't 40 or 64 hex characters"; echo $?)"
+out=$(hookrun "refs/heads/x ${z}${z:0:24} refs/heads/x $(git -C "$C" rev-parse HEAD)"); rc=$?
+check "a 64-character object name passes the length check (64 zeros refuse as a delete)" \
+    "$([ "$rc" -ne 0 ] && has "$out" "refs/heads/x: a delete" && ! has "$out" "isn't 40 or 64"; echo $?)"
+out=$(hookrun "refs/heads/x 1234567890123456789012345678901234567890 refs/heads/x $(git -C "$C" rev-parse HEAD)"); rc=$?
+check "a failed ancestor check (an unknown local object) is refused" \
+    "$([ "$rc" -ne 0 ] && has "$out" "the ancestor check failed"; echo $?)"
+out=$(printf '' | (cd "$C" && sh "$C/.git/hooks/pre-push" origin "$B" 2>&1)); rc=$?
+check "an empty push passes" "$rc"
+
+echo "== installer refusals =="
+fresh() { rm -rf "$1"; git clone -q "$B" "$1"; }
+fresh "$SANDBOX/hp"
+git -C "$SANDBOX/hp" config core.hooksPath .husky
+out=$(bash "$INSTALL" --repo "$SANDBOX/hp" 2>&1); rc=$?
+check "the install refuses with core.hooksPath set (exit 2)" "$([ "$rc" = 2 ]; echo $?)"
+check "it says core.hooksPath is set" "$(has "$out" "core.hooksPath is set"; echo $?)"
+check "no hook was written under the hooksPath refusal" \
+    "$([ ! -e "$SANDBOX/hp/.git/hooks/pre-push" ] && [ ! -e "$SANDBOX/hp/.husky/pre-push" ]; echo $?)"
+
+fresh "$SANDBOX/df"
+printf '#!/bin/sh\nexit 0\n' > "$SANDBOX/df/.git/hooks/pre-push"
+chmod 0755 "$SANDBOX/df/.git/hooks/pre-push"
+ln "$SANDBOX/df/.git/hooks/pre-push" "$SANDBOX/df-old"
+out=$(bash "$INSTALL" --repo "$SANDBOX/df" 2>&1); rc=$?
+check "the install refuses a different installed pre-push (exit 2)" \
+    "$([ "$rc" = 2 ] && has "$out" "a different pre-push hook is installed"; echo $?)"
+check "the different hook is untouched" \
+    "$([ "$(cat "$SANDBOX/df/.git/hooks/pre-push")" = "$(printf '#!/bin/sh\nexit 0')" ]; echo $?)"
+out=$(bash "$INSTALL" --repo "$SANDBOX/df" --force-install 2>&1); rc=$?
+check "--force-install replaces it" \
+    "$([ "$rc" = 0 ] && has "$out" "replaced a different hook" && cmp -s "$HOOK_SRC" "$SANDBOX/df/.git/hooks/pre-push"; echo $?)"
+check "the replacement was a rename: the old file keeps its bytes" \
+    "$([ "$(cat "$SANDBOX/df-old")" = "$(printf '#!/bin/sh\nexit 0')" ]; echo $?)"
+out=$(bash "$INSTALL" --repo "$SANDBOX/df" 2>&1); rc=$?
+check "a second install over the same bytes exits 0" "$([ "$rc" = 0 ] && has "$out" "the same bytes"; echo $?)"
+
+fresh "$SANDBOX/ln"
+ln -s /dev/null "$SANDBOX/ln/.git/hooks/pre-push"
+out=$(bash "$INSTALL" --repo "$SANDBOX/ln" --force-install 2>&1); rc=$?
+check "the install refuses a symlinked pre-push, even with --force-install" "$([ "$rc" = 2 ] && has "$out" "is a symlink"; echo $?)"
+
+# A hooks directory that links to a shared one would put the hook outside
+# the repository, in every repository that shares it.
+fresh "$SANDBOX/sl"
+mkdir -p "$SANDBOX/shared-hooks"
+rm -rf "$SANDBOX/sl/.git/hooks"
+ln -s "$SANDBOX/shared-hooks" "$SANDBOX/sl/.git/hooks"
+out=$(bash "$INSTALL" --repo "$SANDBOX/sl" 2>&1); rc=$?
+check "the install refuses a symlinked hooks directory (exit 2)" "$([ "$rc" = 2 ] && has "$out" "/.git/hooks is a symlink"; echo $?)"
+out=$(bash "$INSTALL" --repo "$SANDBOX/sl" --force-install 2>&1); rc=$?
+check "it refuses it with --force-install too" "$([ "$rc" = 2 ] && has "$out" "/.git/hooks is a symlink"; echo $?)"
+check "nothing was written in the directory the symlink names" "$([ -z "$(ls -A "$SANDBOX/shared-hooks")" ]; echo $?)"
+
+fresh "$SANDBOX/wd"
+git -C "$SANDBOX/wd" worktree add -q -b seat/x "$SANDBOX/wd-wt" origin/main
+out=$(bash "$INSTALL" --repo "$SANDBOX/wd-wt" 2>&1); rc=$?
+check "an install named by a worktree path lands in the common .git/hooks" \
+    "$([ "$rc" = 0 ] && cmp -s "$HOOK_SRC" "$SANDBOX/wd/.git/hooks/pre-push"; echo $?)"
+
+out=$(GIT_DIR="$SANDBOX/wd/.git" bash "$INSTALL" --repo "$SANDBOX/wd" 2>&1); rc=$?
+check "the install refuses with GIT_DIR set" "$([ "$rc" = 2 ] && has "$out" "GIT_DIR is set"; echo $?)"
+mkdir -p "$SANDBOX/plain"
+out=$(bash "$INSTALL" --repo "$SANDBOX/plain" 2>&1); rc=$?
+check "the install refuses a directory that isn't a checkout" "$([ "$rc" = 2 ]; echo $?)"
+out=$(bash "$INSTALL" --nope 2>&1); rc=$?
+check "an unknown argument exits 4" "$([ "$rc" = 4 ]; echo $?)"
+
+echo "== slot-busy, fake /proc =="
+P="$SANDBOX/proc"
+fakeproc() { # $1: pid, $2: cwd, rest: argv
+    local pid=$1 cwd=$2; shift 2
+    mkdir -p "$P/$pid"
+    printf '%s\0' "$@" > "$P/$pid/cmdline"
+    ln -sfn "$cwd" "$P/$pid/cwd"
+}
+busyrun() { bash "$BUSY" --proc-root "$P" 2>&1; }
+fakeproc 4194401 /srv node server.mjs
+fakeproc 4194402 /srv grep -r gate .
+# Both wrappers' text would match a rule without the snapshot exclusion.
+fakeproc 4194403 /srv /bin/bash -c "source /home/u/.claude/shell-snapshots/snapshot-bash-1.sh && node --test x.test.mjs"
+fakeproc 4194405 /srv /usr/bin/bash -c "source /home/u/.claude/shell-snapshots/snapshot-bash-2-ab.sh 2>/dev/null || true && eval 'bash scripts/test-x.sh > x.log' && pwd -P >| /home/u/cwd"
+mkdir -p "$P/4194404"; : > "$P/4194404/cmdline"
+out=$(busyrun); rc=$?
+check "no matching process: exit 0 and CLEAR" "$([ "$rc" = 0 ] && [ "$out" = CLEAR ]; echo $?)"
+check "an agent's shell-snapshot wrapper isn't a match" "$(! has "$out" "4194403" && ! has "$out" "4194405"; echo $?)"
+
+fakeproc 4194410 /seat/a node --test packages/x/tests/a.test.mjs
+out=$(busyrun); rc=$?
+check "a node --test process: exit 1" "$([ "$rc" = 1 ]; echo $?)"
+check "its BUSY line names pid, rule and cwd" "$(has "$out" "BUSY 4194410 node --test cwd=/seat/a node --test"; echo $?)"
+check "BUSY output never says CLEAR" "$(! has "$out" "CLEAR"; echo $?)"
+ran=$(bash "$BUSY" --proc-root "$P" >/dev/null && echo ran)
+check "\`slot-busy > LOG && step\` doesn't run the step while BUSY" "$([ -z "$ran" ]; echo $?)"
+rm -rf "${P:?}/4194410"
+
+rule() { # $1: expected rule, rest: argv
+    local want=$1; shift
+    rm -rf "${P:?}/4194420"; fakeproc 4194420 /seat/b "$@"
+    out=$(busyrun); rc=$?
+    check "busy on: $* ($want)" "$([ "$rc" = 1 ] && has "$out" "BUSY 4194420 $want "; echo $?)"
+}
+rule "node --test" /usr/bin/node --experimental-strip-types --test a.test.ts
+rule "gate" bash /mnt/scratch/sage-gate.sh 253
+rule "gate" bash ./gate.sh
+rule "mutant" bash agents/x/work/queue-1/mutants.sh M3
+rule "test script" bash scripts/test-land-work.sh
+rule "docker compose" docker compose -p x up -d
+rule "docker compose" /usr/bin/docker-compose up
+# The snapshot exclusion is for the wrapper's shape only: the same command
+# without the snapshot source, and real runs whose arguments hold the path.
+rule "node --test" /bin/bash -c "node --test x.test.mjs"
+rule "node --test" node --test /seat/tests/shell-snapshots/snapshot-guard.test.mjs
+rule "gate" bash /seat/shell-snapshots/snapshot-gate.sh
+rm -rf "${P:?}/4194420"
+
+echo "== slot-busy, read errors =="
+# A pid directory that stays while its cmdline can't be read is an error,
+# never a vanished process: exit 2 and no CLEAR.
+mkdir -p "$P/4194430"
+out=$(busyrun); rc=$?
+check "a pid directory with no cmdline: exit 2" "$([ "$rc" = 2 ]; echo $?)"
+check "it names that cmdline and never says CLEAR" "$(has "$out" "cannot read $P/4194430/cmdline" && ! has "$out" CLEAR; echo $?)"
+rm -rf "${P:?}/4194430"
+mkdir -p "$P/4194431/cmdline"
+out=$(busyrun); rc=$?
+check "a cmdline that can't be read (a directory): exit 2, no CLEAR" "$([ "$rc" = 2 ] && ! has "$out" CLEAR; echo $?)"
+fakeproc 4194410 /seat/a node --test a.test.mjs
+out=$(busyrun); rc=$?
+check "a read error beside a BUSY process: exit 2, the BUSY line kept, no CLEAR" \
+    "$([ "$rc" = 2 ] && has "$out" "BUSY 4194410 node --test" && ! has "$out" CLEAR; echo $?)"
+rm -rf "${P:?}/4194431"
+chmod 000 "$P/4194410/cmdline"
+out=$(busyrun); rc=$?
+check "a node --test process whose cmdline is unreadable (mode 000) is never CLEAR" "$([ "$rc" != 0 ] && ! has "$out" CLEAR; echo $?)"
+rm -rf "${P:?}/4194410"
+
+mkdir -p "$SANDBOX/failtr" "$SANDBOX/vanishtr" "$SANDBOX/failawk"
+printf '#!/bin/sh\nexit 1\n' > "$SANDBOX/failtr/tr"
+printf '#!/bin/sh\nexit 1\n' > "$SANDBOX/failawk/awk"
+# This tr stands in for a process that exits during the read: for pid
+# 4194440 it removes the pid directory and fails; otherwise it is tr.
+cat > "$SANDBOX/vanishtr/tr" <<EOF
+#!/bin/sh
+f=\$(readlink "/proc/\$\$/fd/0")
+case "\$f" in */4194440/cmdline) rm -rf "\${f%/cmdline}"; exit 1 ;; esac
+exec $(command -v tr) "\$@"
+EOF
+chmod +x "$SANDBOX/failtr/tr" "$SANDBOX/failawk/awk" "$SANDBOX/vanishtr/tr"
+out=$(PATH="$SANDBOX/failtr:$PATH" bash "$BUSY" --proc-root "$P" 2>&1); rc=$?
+check "a failing read (tr exits 1) with every pid directory still there: exit 2, no CLEAR" \
+    "$([ "$rc" = 2 ] && has "$out" "cannot read" && ! has "$out" CLEAR; echo $?)"
+fakeproc 4194440 /seat/v node --test v.test.mjs
+out=$(PATH="$SANDBOX/vanishtr:$PATH" bash "$BUSY" --proc-root "$P" 2>&1); rc=$?
+check "a process that vanishes during its read isn't an error: exit 0 and CLEAR" \
+    "$([ "$rc" = 0 ] && [ "$out" = CLEAR ] && [ ! -e "$P/4194440" ]; echo $?)"
+rm -rf "${P:?}/4194440"
+out=$(PATH="$SANDBOX/failawk:$PATH" bash "$BUSY" --proc-root "$P" 2>&1); rc=$?
+check "its own process unreadable (awk exits 1): exit 2, no CLEAR" \
+    "$([ "$rc" = 2 ] && has "$out" "cannot read its own process" && ! has "$out" CLEAR; echo $?)"
+
+out=$(bash "$BUSY" --proc-root "$SANDBOX/no-such-proc" 2>&1); rc=$?
+check "a missing proc root: exit 2" "$([ "$rc" = 2 ]; echo $?)"
+mkdir -p "$SANDBOX/empty-proc"
+out=$(bash "$BUSY" --proc-root "$SANDBOX/empty-proc" 2>&1); rc=$?
+check "a proc root with no processes: exit 2" "$([ "$rc" = 2 ]; echo $?)"
+out=$(bash "$BUSY" --nope 2>&1); rc=$?
+check "an unknown argument: exit 2" "$([ "$rc" = 2 ]; echo $?)"
+
+echo "== slot-busy, real /proc =="
+mkdir -p "$SANDBOX/bin" "$SANDBOX/standin"
+cat > "$SANDBOX/bin/node" <<'EOF'
+#!/bin/sh
+trap 'exit 0' TERM
+while :; do sleep 0.2; done
+EOF
+chmod +x "$SANDBOX/bin/node"
+(cd "$SANDBOX/standin" && exec "$SANDBOX/bin/node" --test standin.test.mjs) &
+STANDIN=$!
+for _ in $(seq 50); do
+    has "$(tr '\0' ' ' < "/proc/$STANDIN/cmdline" 2>/dev/null)" "--test standin" && break
+    sleep 0.1
+done
+out=$(bash "$BUSY" 2>&1); rc=$?
+check "with a stand-in node --test running: exit 1" "$([ "$rc" = 1 ]; echo $?)"
+check "the stand-in has a BUSY line with its cwd" \
+    "$(printf '%s\n' "$out" | grep -q "^BUSY $STANDIN node --test cwd=$SANDBOX/standin "; echo $?)"
+check "this suite, an ancestor, has no BUSY line" "$(! printf '%s\n' "$out" | grep -q "^BUSY $$ "; echo $?)"
+ran=$(bash "$BUSY" >/dev/null && echo ran)
+check "\`slot-busy > LOG && step\` doesn't run the step with the stand-in up" "$([ -z "$ran" ]; echo $?)"
+kill "$STANDIN" 2>/dev/null; wait "$STANDIN" 2>/dev/null
+gone=$STANDIN; STANDIN=""
+out=$(bash "$BUSY" 2>&1); rc=$?
+check "after the stand-in exits, it has no BUSY line" "$(! printf '%s\n' "$out" | grep -q "^BUSY $gone "; echo $?)"
+check "the real-/proc run exits 0 or 1, never 2" "$([ "$rc" = 0 ] || [ "$rc" = 1 ]; echo $?)"
+
+echo "---"
+echo "git-guard selftests: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]