fix(pm): the dispatch-gates gate kill branch exits 3, so its code says what its text says - #18271

Fixes #18267

scripts/pm/check-dispatch-gates.mjs's result.signal branch printed 「⛔ Do not record it as a run」 and then exited 2. dispatch-gates.mjs --ran classifies a recorded exit from the code: 3 is the repo-wide NOT MEASURED code, 124 and the 128 + signum floor are kills, everything else is a run. 2 is none of those. The two carriers disagreed about one reading, and the code won.

The probe, driven — the reading BEFORE any change

The card named this probe and nobody had executed it. It was the first act of this branch. Both forms the dispatch suggested were measured, and one of them does not work:

timeout -s TERM 5 node scripts/pm/check-dispatch-gates.mjs does NOT reach the branch. The wrapper registers no SIGTERM listener, so it takes the default disposition and dies with its child; nothing prints, and the shell reads timeout's own 124:

PROBE_A_WRAPPER_EXIT=124
--- grep for the signal branch text ---
0

Signalling the wrapper's CHILD does reach it. Spawn the wrapper, read its child pid from the process table, kill -TERM that pid, and wait on the wrapper:

SENT SIGTERM to child 14627
PROBE_B_WRAPPER_EXIT=2

✗ check:pm-dispatch-gates: scripts/pm/dispatch-gates.mjs --self-test was killed by SIGTERM after 4.0s — NOTHING was measured.
  Every case decided before the kill is in the output above and every case after it is unjudged, so this run grades neither the tool nor your diff. ⛔ Do not record it as a run.
  Remedy — detach it and read the log, the invocation this file's header prescribes for a capped container:
      nohup pnpm check:pm-dispatch-gates > pm-dispatch-gates.log 2>&1 &
  then tail that log until it stops growing. CI runs this step with no such cap.

Recorded honestly as pnpm check:pm-dispatch-gates :: exit 2 and reconciled through --ran, against the 31 families a card touching this file derives:

### exit 2  ->  --ran exit 0
Run reconciliation — 31 derived, 31 run, 0 NOT-MEASURED, 0 UNRUN.

The reconciler accounted the kill as a RUN. Exit 0, nothing to notice, a family counted as measured on a run that measured nothing. The two controls, same record, same derivation:

### exit 3  ->  --ran exit 0
Run reconciliation — 31 derived, 30 run, 1 NOT-MEASURED, 0 UNRUN.
    - pnpm check:pm-dispatch-gates   [recorded exit 3 on line 27 — PREREQUISITE NOT MET]

### exit 143  ->  --ran exit 1
Run reconciliation — 31 derived, 30 run, 0 NOT-MEASURED, 1 UNRUN.
    - pnpm check:pm-dispatch-gates   [recorded exit 143 on line 27 — killed by SIGTERM, so no verdict was reached; declare it as `NOT-MEASURED (command) :: (reason)` beside the code to count it NOT-MEASURED]

That third reading is why the fix is not 143: a bare kill code is read as UNRUN unless the runner also writes a NOT-MEASURED claim with a stated reason beside it. That default is right for a runner relaying a kill it did not diagnose; it is wrong here, where the branch has already identified the kill, printed the reason and named the remedy before it exits. EXIT_PREREQUISITE_NOT_MET carries all of that in the code itself.

What changed

• The result.signal branch exits EXIT_PREREQUISITE_NOT_MET (3) and names the code in its own remedy text, so the two carriers cannot drift apart silently again.
• A child that RAN keeps result.status — untouched.
• result.error keeps 2, deliberately, and the reason is now at the branch: a spawn that never started has two causes this file cannot tell apart — the tool is gone from the tree (a finding about the tree) and the box could not fork (not a finding at all). 3 would assert the second reading over both. Its current reading costs a rerun rather than a false green, which is the safe direction, so nothing here justified moving it without a measurement that separates the two.
• A new header section carries the four-row exit contract and the argument above.
• ⛔ Nothing else: no timeout wrapper, no skip, no weakening. The detached-form header stands.

The self-test, and the shape it needed

The wrapper had none. It could not have one without a way to stand the 435-second battery down, because the branch under test only fires when that battery is killed — so the smallest code change that lets a stub in is in scope, and it is a flag:

• --self-test-child (path) substitutes the child. ⛔ Not an OS_TEST_* env var: an environment variable is inherited from whatever shell started the runner, so it can arrive without appearing in any invocation anyone reads, and the one failure this affordance could introduce is a green gate over a child that is not the tool. A flag is spelled at the call site, and package.json holds the only invocation CI runs. The right boundary matters too — check-self-test-wired matches --self-test with one, so the longer flag is not credited as an invocation of the self-test.
• Every substituted run announces itself on stderr (SUBSTITUTED CHILD), and the self-test asserts that it does, so the loudness is live rather than promised.
• The killed stub kills itself. Measured both ways: signalling from outside needs the grandchild's pid, so it races the spawn and reads the process table; timeout -s TERM does not reach the branch at all (above). A stub that signals its own pid has no race and no lookup — node with no SIGTERM listener takes the default disposition, so spawnSync reports signal: 'SIGTERM', status: null, which is the exact shape a foreground-cap kill produces. That is the form pinned.

Eleven cases, sub-second, three directions plus the half that is not about this file — each exit is pushed through runReconciliation on a one-family derivation, so 3 means NOT MEASURED here rather than merely being three. parseRunRecord/runReconciliation are imported (43 ms) rather than spawned: what is under test is how a recorded code classifies, not how the derivation finds the family, and a spawned derivation would add a workflow-tree walk per case to every CI run of this gate.

✓ CONTROL: the killed stub really died by SIGNAL, so the branch under test is the one that ran
✓ ⭐ a child killed by a signal exits 3 — the code this branch's own text asks for
✓ …and the text that asks for it is still printed, so the two carriers cannot drift apart silently
✓ a child that RAN and failed keeps its own status
✓ a child that RAN and passed keeps its own status
✓ ⛔ and a substituted child announces itself on every one of those runs — a stub run is never quiet
✓ ⭐ …and a record of that exit reconciles as NOT-MEASURED, which is the whole contract
✓ …derived from the CODE, not claimed by the runner — so a killed battery cannot be recorded as a run by hand
✓ a red run reconciles as a RUN, and the reconciliation holds
✓ a green run reconciles as a RUN too
✓ ⛔ REGRESSION PIN: the code this branch used to exit still reconciles as a RUN — which is why it moved

The last one is the live one: delete the fix and that case reddens, because 2 still reconciles as a run.

Wiring. The repo's convention for a check:* script that ships a self-test is (script) --self-test && (script) — check:pm-skill-ratchet, check:pm-skill-id-lint, check:pm-label-desc-cap and check:pm-governed-prose all spell it that way — so check:pm-dispatch-gates now does too. That wires the self-test, and a wired script must leave check-self-test-wired's SELF_TEST_RUN_OTHERWISE ledger ("A row whose script gets wired FAILS. The list only ever shrinks"), so its row is deleted. node scripts/check-self-test-wired.mjs now reports 211 scripts, 208 through the flag, 3 through a recorded route (was 4).

Reverse verification

The ablation is the probe itself, re-driven against the changed tree, same script, same method:

SENT SIGTERM to child 16286
PROBE_B_WRAPPER_EXIT=3

✗ check:pm-dispatch-gates: scripts/pm/dispatch-gates.mjs --self-test was killed by SIGTERM after 4.0s — NOTHING was measured.
  Every case decided before the kill is in the output above and every case after it is unjudged, so this run grades neither the tool nor your diff. ⛔ Do not record it as a run.
  This exits 3, the repo-wide NOT MEASURED code, so a record line `(command) :: exit 3` reconciles as NOT-MEASURED rather than as a run that failed.

Before: wrapper exit 2, reconciled inside the run total. After: wrapper exit 3, reconciled NOT-MEASURED with source: 'exit-code' — derived from the code, so a runner cannot fail to declare it. A child that ran red still reconciles as a run (pinned above). No permanent test file was left behind; the pin lives in the self-test.

A regression the tool's own battery caught, and the trap behind it

Worth recording, because it reads as reasonable code. The first draft routed both the real and the substituted child through one spawnSync(process.execPath, [resolve(ROOT, child), '--self-test']). The tool's derivation follows that spawn as a RUN edge — it is how this gate inherits the tool's watch hints, the workflow tree among them — and its run scan refuses a rebound program component on purpose. So the edge vanished silently:

=== HEAD (first draft) ===   node scripts/pm/dispatch-gates.mjs --commands .github/workflows/board-snapshot.yml | grep -c pm-dispatch-gates
0
=== origin/main (before) ===
1

Five of the tool's 1730 cases went red on it, and a workflows-only card stopped deriving this gate at all. The substituted child now gets its own call and the production one is byte-for-byte the expression that was there before; the trap is written at the spawn site. Re-measured after the fix: 1.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack with no paths (derived from git off the merge base), every family run in the foreground, each exit captured by redirect before any pipe, then reconciled. Union re-run at the final head fed9c9e2.

Run reconciliation — 38 derived, 34 run, 4 NOT-MEASURED, 0 UNRUN.
  NOT-MEASURED · DERIVED (4) — your record carries exit 3 for these, the number a gate refusing its own prerequisite exits with.
    - pnpm check:dts-closure   [recorded exit 3 on line 24 — PREREQUISITE NOT MET]
    - pnpm check:dual-build-cjs-loads   [recorded exit 3 on line 25 — PREREQUISITE NOT MET]
    - pnpm check:lean-entry-closure   [recorded exit 3 on line 27 — PREREQUISITE NOT MET]
    - pnpm check:sourcemap-no-sources-content   [recorded exit 3 on line 35 — PREREQUISITE NOT MET]
✓ dispatch-gates --ran: 38 derived famil(ies) accounted for — 34 run, 4 NOT-MEASURED (4 DERIVED from a recorded exit 3).

Those four are derived by change KIND from the one-line edit to the private root manifest's scripts block, and all four read built dist/ output this diff contains none of; they refuse on an unbuilt worktree. CI runs them on a built tree. It is the reading this card is about, arriving by itself.

pnpm check:pm-dispatch-gates is owed beyond the derivation because this diff edits the wrapper, and it was run the way its own header prescribes — detached, then blocked on with tail --pid, the exit code captured through a wrapper rather than read off a pipe:

✓ dispatch-gates self-test: 1730 cases pass.
check:pm-dispatch-gates: the battery took 450.2s on this box.

Wall clock 450.2 s on a contended box, exit 0, with the wrapper's own eleven cases running in front of it under the new wiring.

Repo-wide pnpm lint (eslint . --no-inline-config) run in full, not narrowed: exit 0 in 82 s.

skip-changeset: the root manifest is private: true, and no published package's files[] ships scripts/. Nothing this diff touches publishes.

Acceptance notes

Noted, not filed — none of these is a reproducible defect, a contract violation, or a metadata-authoring trap:

• timeout -s TERM on this wrapper measures nothing about its signal branch. The shell reads timeout's 124 and the branch never prints. Not a defect in anything — timeout signals its direct child by design — but it is the obvious way to try this probe and it fails by looking like a result. Successor: the next author of a probe against this branch, who now finds the measurement in the file's own self-test docblock and in the header.
• result.error conflates two causes under exit 2. A missing tool is a finding about the tree; a box that cannot fork is not. Whichever code that branch carries is wrong for one of them, and its current one errs toward a rerun rather than a false green. Left alone deliberately, with the argument now written at the branch for whoever measures the split. Successor: none today — no card is queued against this branch, and it is recorded here rather than filed because filing it would ask someone to choose without a measurement to choose on.
• A one-line edit to the private root manifest's scripts block derives four build-artefact gates. Over-inclusive in the safe direction, and they announce themselves with exit 3 rather than a false green, so nothing is hidden. Successor: any PR editing root package.json — which is most of them — so the cost is a known four-line NOT-MEASURED block, not a surprise.

Generated by Claude Code