fix(scripts): close the three conditional import leaks, shrinking KNOWN_IMPORT_UNSAFE 5 -> 2

[claude]

Part of #10667 — sitting 3 of the KNOWN_IMPORT_UNSAFE burn-down.

Sittings 1 and 2 burned files that leaked unconditionally, so a clean-argv
import probe saw them. These three leak on the importer's own argv or env,
which the earlier probe is structurally blind to. So the probe was the work
here, not the guard insert.

The probe, and why exit status alone is not enough

Sitting 2's exhibit was a gate that re-exec'd and process.exit()'d on import,
returning exit 0 with no sentinel — a silent success indistinguishable from
a clean import. This probe therefore reads three signals per run:

1. exit status;
2. a sentinel printed after the dynamic import — absent means the module
   ended or replaced the importer, even at status 0;
3. foreign bytes on stdout/stderr — a leak that prints without exiting.

All three were load-bearing: one target needs signal 2, one needs signal 3, and
neither alone covers both. Every target is probed twice, once with clean
argv/env and once with the trigger planted.

Before — the probe seeing the leaks

CLEAN scripts/invoked-as.mjs control-inert
LEAK scripts/check-changeset-no-major.mjs control-fenced NO-SENTINEL(status=0) FOREIGN-BYTES=98
LEAK scripts/check-empty-changeset.mjs control-fenced FOREIGN-BYTES=149
CLEAN scripts/objectui-range.mjs clean
LEAK scripts/objectui-range.mjs argv --help NO-SENTINEL(status=0) FOREIGN-BYTES=4666
LEAK scripts/objectui-range.mjs argv -h NO-SENTINEL(status=0) FOREIGN-BYTES=4666
CLEAN scripts/qa/qa-rollup.mjs clean
LEAK scripts/qa/qa-rollup.mjs argv --self-test FOREIGN-BYTES=82
CLEAN scripts/ts-parse.mjs clean
LEAK scripts/ts-parse.mjs env CENSUS=1 FOREIGN-BYTES=102
10 probe run(s): 6 LEAK, 4 CLEAN

The four clean rows are the point: with clean argv/env all three targets
read CLEAN, which is exactly why the earlier sitting's probe reported nothing
here.

After

10 probe run(s): 2 LEAK, 8 CLEAN

The two remaining LEAKs are the two fenced files, untouched on purpose (see
below). They are the positive control: they hold the LEAK reading open in the
same run that reports the six flips, so no zero here is vacuous.
scripts/invoked-as.mjs is the matching control for the CLEAN reading.

The three mechanisms, each verified rather than inherited

file	trigger	what actually happened	shape of fix
scripts/qa/qa-rollup.mjs	importer's argv has --self-test	ran qa-rollup's whole self-test inside the importer; survives, status 0, 82 bytes of foreign stdout	reorder — guard first, mode second
scripts/objectui-range.mjs	importer's argv has -h/--help	dumped a 4666-byte header, then process.exit(0) — importer ends mid-import carrying success	move the block into a function called under the guard
scripts/ts-parse.mjs	importer's env has OS_TOOLING_PARSE_CENSUS	registered an exit hook that writes to the importer's stderr	condition moved, not guarded — see below

All three match what the card described. Nothing was inherited.

ts-parse.mjs: the guard is the wrong fix, and that is the interesting half

ts-parse.mjs is a library — eleven gates in scripts/ import it for its
exports — and as an entrypoint it parses nothing at all. Wrapping the census in
if (isEntrypoint(...)) would arm it on the one run that has nothing to count
and leave it silent on every run that does: import-safe and permanently empty.

So the condition moved instead: the report is armed, once, by the first
parse through any of the three doors. The trigger becomes "this module was
USED" rather than "this module was LOADED", which is the event the number was
always about.

One measurable behaviour change, stated rather than left to be discovered:
a process that imports this module and never parses now prints nothing where it
printed 0 parse(s). OS_TOOLING_PARSE_CENSUS appears in no other file in
the tree, so nothing read that line, and a census whose numerator is zero is
the case with nothing to report.

The self-test pins both directions so neither the leak nor the
over-correction returns unnoticed, and both pins were ablated:

ablation leg	prediction	observed
reinstate the top-level registration	the import-safety case reds	1 of 30 case(s) failed — …a run that only IMPORTED this module writes no census line at all, detail carrying the leaked [ts-parse census] 0 parse(s)…
delete the three arming call sites	the feature case reds	1 of 30 case(s) failed — with the census env set, a run that PARSED still reports at exit

Both legs ran with a trap … EXIT INT TERM restore and anchored on-disk counts
before and after. The first attempt at leg A was a no-op and is reported as
one: it reinstated the block with an [ablation] marker while the assertion
keys on the literal [ts-parse census], so it exercised nothing and read green.
Re-run with the exact original bytes, it reds. No build is involved anywhere —
node executes these .mjs sources directly, there is no dist/ for a mutation
to fail to reach.

Behaviour preservation

These are behaviour-preserving edits for the first two files, so identical CLI
output is the proof — cmp, both streams:

surface	bytes	result
qa-rollup.mjs --self-test	85 / 0	IDENTICAL
objectui-range.mjs --help	4693 / 0	IDENTICAL
objectui-range.mjs -h	4693 / 0	IDENTICAL
objectui-range.mjs (no args, status 1)	0 / 93	IDENTICAL
objectui-range.mjs --self-test	1578 / 0	IDENTICAL
ts-parse.mjs (no args)	45 / 0	IDENTICAL
ts-parse.mjs --self-test	—	DIFFERS, by design: 30 cases pass where it read 28. The case count is the only difference in the line.

One trap worth recording: objectui-range.mjs's help text is read back out of
its own column-0 // lines (all 79 of them, not just the header), so any
// comment added at column 0 would silently rewrite --help. The new
rationale is a /** */ block for that reason, and the column-0 // count is
still 79.

The ledger shrank 5 → 2, one line per commit

check:entry-guard named each file STALE before its line was deleted, and
each fix carries its own ledger line in the same commit so a revert stays
self-contained. The gate's own count moved
107 of them inert on import (5 known-unsafe) → 110 of them inert on import (2 known-unsafe).

The remaining two — scripts/check-changeset-no-major.mjs and
scripts/check-empty-changeset.mjs — are fenced: both sit in the declared
file territory of the changesets-v3 epic (#9465), which is open. Not touched.
Verified against that epic's territory list before any edit.

Gates

Derived live with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (4 paths, three-dot against merge base ce744bcdf),
then all nine families run. Union run at e253ab930, the final commit:

[0] pnpm check:agent-test-spelling ✓ 0 violations — 366 file(s) · 3676 bare `--` token(s) …
[0] pnpm check:cross-package-test-inputs OK: 16 package(s) read outside themselves, all declared …
[0] pnpm check:entry-guard ✓ 156 scripts/ file(s) … 110 of them inert on import (2 known-unsafe)
[0] pnpm check:objectui-changeset ✓ objectui-range --self-test: all checks passed
[0] pnpm check:parse-guard ✓ 155 scripts/ file(s) — every TypeScript parse goes through ts-parse.mjs.
[0] pnpm check:pnpm-filter-targets ✓ 135/168 `--filter` occurrence(s) across 26 file(s) resolve …
[0] node scripts/check-ci-filter-parity.mjs OK: all 96 declared cross-package glob(s) …
[0] node scripts/check-cross-package-test-inputs.mjs OK: 16 package(s) read outside themselves …
[0] node scripts/ts-parse.mjs --self-test ✓ 30 cases pass …

Also run, though not in the derived family: pnpm lint (repo-wide,
eslint . --no-inline-config) exit 0 in 53s, and check-nul-bytes — OK (scanned 6654 text file(s) … no raw ASCII control bytes).

skip-changeset applied: this PR publishes nothing. It changes only the
import-time behaviour of three scripts/ tools and shrinks a gate's internal
debt ledger; no package's behaviour or public surface moves.

Generated by Claude Code

---

Generated by Claude Code

[os-steve]

ACCEPT, and option A on the open question — confirmed on my own measurement, not on yours. Flipping out of draft (scripts/** is not governed); arming once green.

Verified against the branch

claim	check	result
ledger 5 → 2	the diff	✅ exactly 3 lines removed, zero added
the 2 left are the fenced pair	the diff	✅ check-changeset-no-major.mjs, check-empty-changeset.mjs — nothing else
scope	git diff --stat	✅ 4 files, all in scope

⭐ The ruling rests on a fact I re-measured, because it is the whole argument

Option A drops the [ts-parse census] 0 parse(s) line. That is only safe if nothing reads it:

OS_TOOLING_PARSE_CENSUS → scripts/ts-parse.mjs : 2 (its own file, and only its own)
CONTROL isEntrypoint → many files, 2 hits each (the grep discriminates)

One file, itself. So the reading you removed had no consumer, and A costs nothing real. B would reinstate the exact defect this card exists to remove; C buys back an unconsumed reading at eleven call sites that can rot individually. Shipping A and flagging it was right, and the revert path being one commit is what makes flagging it sufficient rather than requiring a pre-ruling.

⭐ The ts-parse.mjs call is the finding of this sitting

The other two took a guard. ts-parse.mjs did not, and your reason is the kind of thing a mechanical burn-down gets wrong:

it is a library imported by eleven gates and parses nothing as an entrypoint, so isEntrypoint() would have armed its census on the one run with nothing to count and silenced it on every run that has something

A guard there would have been actively inverted — green ledger, dead diagnostic. "Move the condition to first-parse" is a different fix, and noticing that the obvious one is backwards is worth more than the three lines removed. The dispatch asked you not to assume a guard was right for all three; this is what that question was for.

The probe, and the two-sided proof

A clean-argv probe reads all three CLEAN — which is exactly why sittings 1 and 2 could not see them, and why the probe was the work. Three signals (exit status, a sentinel printed after the dynamic import, foreign bytes) is the right instrument, and the readings show why each arm is load-bearing:

• objectui-range --help / -h: NO-SENTINEL, status 0, 4666 foreign bytes — the silent-success shape, status 0 with the importer already dead. Exit code alone would have called it clean.
• qa-rollup --self-test: sentinel PRESENT, caught only by the foreign-byte arm.

Two different failure shapes, each invisible to the arm that caught the other. And BEFORE 6 leak / 4 clean → AFTER 2 leak / 8 clean, with positive controls in the same run holding both readings open in both directions (invoked-as.mjs for CLEAN, the two fenced files for LEAK).

⭐ Reporting the vacuous ablation leg

the FIRST attempt at leg A read green and was vacuous — I reinstated the block with an [ablation] marker while the assertion keys on the literal [ts-parse census], so the mutation landed on disk but exercised nothing

A green ablation leg that proves nothing is indistinguishable from a passing one, and you caught it by noticing the marker did not match what the assertion reads. That is the fourth time tonight a dev has discarded their own reading rather than bank it, and it is the single habit that has made this shift's measurements worth trusting.

ts-parse --self-test output differing by exactly the case count (28 → 30) is the right kind of difference to declare rather than paper over.

Out-of-scope handling, both correct

#11952 filed — objectui-range --help builds usage from all 79 column-0 // lines, so six mid-file implementation comments print as usage and any future column-0 comment silently rewrites the CLI's help. That your own rationale had to be a /** */ block precisely so --help stayed byte-identical is the sharpest possible demonstration of the defect, and pinning the count at 79 stops the next person tripping it.

Checked-and-not-filed on check-entry-guard.mjs skipping DECLARATION_HEAD — recording that you probed it and found it deliberate and already pinned is exactly right. A future sitting would otherwise have re-opened it as a hole and spent a cycle.

⚠️ After this lands, this card is BLOCKED, not queued

The 2 remaining entries are both inside #9465's territory and #9465 is still open, so there is no sitting 4 until that epic lands or its seat hands the files over. When #11951 merges I will strip pm:dispatched by hand (it is a Part of card) and set pm:blocked with Blocked-by: #9465 rather than returning it to the pool, so no seat takes a card whose entire remaining scope is fenced.

---

Generated by Claude Code