fix(test-env): register the network-escape guard's afterEach per test file, not per worker (objectui#8537)

[os-justin]

Fixes #8537

What was wrong

vitest.setup.network-escape-guard.ts promises "the afterEach that fails ANY escape in ANY file". In the unit project (isolate: false) it registered that hook in its module scope, and the module is IMPORTED by vitest.setup.base.ts rather than being a setupFiles entry. Vitest 4.1.10 re-executes a setup file per test file by invalidating that file's own module node (importFile(filepath, "setup") in vitest/dist/chunks/test.DNmyFkvJ.js, around line 4287) and nothing else — so the guard's body, and its afterEach, ran once per worker and attached to the worker's first test file only.

Measurement first, on 1cca4415e (unfixed), with a lit control

Three byte-identical test files (label only differs), each fetching an absolute http://localhost:3000/... URL, run on the real unit project:

run	result
one worker, three files (--maxWorkers=1 --fileParallelism=false)	Test Files 1 failed, 2 passed (3) — only the first in execution order (ZZORDER 1) was reported
three workers, same three files (--maxWorkers=3)	Test Files 3 failed (3) — each file is first in its own worker
each file alone	red, every time

So coverage today is exactly one file per worker, and the three-worker leg shows it is per worker rather than per run. Vitest's default worker count is max(availableParallelism - 1, 1) (getDefaultThreadsCount), so on a 4-thread box that is 3 of the project's 991 files; on a 4-shard CI run it is roughly a dozen of 991. The card's reading holds: premise_still_valid: true.

With the hook armed for every file (this branch), the same three files in one worker read Test Files 3 failed (3).

Blast radius, measured

The whole unit project on this branch, hook armed per file, four shards run sequentially on a shared box: 247 + 247 + 248 + 247 = 989 passed, 2 skipped (the two fixtures, inert outside the pin's child), 0 Network escape verdicts. The burn-down the card deferred is empty — every real escape had already been served from a double by objectui#7307's batches — so this lands as one PR, and the change adds no red to main.

The repair

The two halves of the guard are registered at two different times, deliberately:

• the recording half — the globalThis.fetch wrapper — stays a module-scope assignment on a shared global, once per worker (re-wrapping per file would stack a wrapper per file under isolate: false);
• the asserting half — the afterEach — moves into an exported installNetworkEscapeGuard() which vitest.setup.base.ts calls on every execution, which under isolate: false is every test file. Same split, same reason, as installI18nGlobalReset() beside it. The call sits where the side-effect import stood, so hook order is unchanged: registered first, runs last, after the i18n reset and after the DOM setups' RTL cleanup() — the order the guard's own Fix: text describes to test authors.

isolate: true was not reached for and was not priced: the repair does not touch isolation, and the per-file installer is the pattern the same file already uses one line below. Declared as a narrowing rather than measured.

The deliberate pin edit (objectui#6640's ledger pin)

scripts/__tests__/network-escape-ledger.test.ts pinned that the guard "exports nothing". That assertion is edited on purpose, not incidentally: it now pins that the guard exports exactly installNetworkEscapeGuard (a ledger coming back as a second export is still red), that the guard's ONE afterEach( in code sits inside that installer rather than at module scope, and that vitest.setup.base.ts calls it and no longer carries the bare side-effect import.

The behavioural pin, and the caricature it rejects

scripts/__tests__/network-escape-worker-coverage-8537.test.ts spawns a real vitest on the unit project with two byte-identical escaping fixtures forced into ONE worker and requires Test Files 2 failed (2) with each file named by the guard's own file: line. Live controls, read off a ledger file the fixtures write: both escapes ran, and exactly one fixture saw the other's mark on the shared global (one worker, and one of the two was not first in it). In the ordinary suite the fixtures are skipped.

Run, not predicted — each leg restored by state (empty git diff HEAD, blob hash equal to HEAD's) with an EXIT INT TERM trap on absolute paths:

leg	on-disk proof	child summary	pin
defect: guard + base restored to 1cca4415e	installNetworkEscapeGuard count in base.ts 0, export in guard 0	1 failed, 1 passed (2)	red on the discriminating assertion; ledger pin red on the export list
caricature: hook per file, detection lost (if (seen.length >= 0) return;)	marker count 1, original line 0, installer still exported	2 passed (2)	red on the same discriminating assertion
control: fixed tree, same fixtures in TWO workers	—	2 failed (2), saw_other=yes count 0	the one-worker control discriminates
fixed tree	—	2 failed (2)	green

One wrong-reason failure was found and fixed in the pin's own first draft (second commit, c30521fe5): with the liveness evidence on the child's console, the defect leg went red on "fixture b never ran its escape" — b had run and passed, and vitest's default reporter prints a passing test's console output nowhere, so the control fired exactly on the outcome it was meant to be independent of. The evidence now goes to a ledger file; re-run, both mutated legs fail on Test Files 2 failed (2) itself with the controls green.

Load dependence

The defect reproduces deterministically here because the pin forces one worker; it does not depend on scheduling. The only load-sensitive part is the child spawn's wall time (1.4 s locally; 300 s timeout, 360 s test timeout, same budget as vitest-timezone-pin-8366.test.ts).

Verification (tree c30521fe5)

• pnpm exec vitest run --project unit on the pin, both fixtures, the ledger pin and the shared-global-leak-guard pin: 3 passed, 2 skipped (5), exit 0.
• --project unit --shard=k/4 for k = 1..4: 989 passed, 2 skipped, 0 escapes (shard walls 57 s / 75 s / 35 s / 30 s on a shared box).
• pnpm type-check:scripts: 0 errors. pnpm type-check:vitest-setup: the same 4 errors before and after, all in vitest.setup.dom.tsx and all the documented missing-dist shape (the four packages it maps to are not built in this worktree) — no error in the two edited files; declared as a narrowing.
• pnpm lint:root: 0 errors (32 pre-existing warnings; the six in the touched root files are no-explicit-any on lines that pre-exist at 1cca4415e, 3 in the guard and 2 in base.ts, same count before and after).
• node scripts/check-changeset-presence.mjs green (empty-frontmatter changeset added — test harness only, nothing released); pnpm changeset:check, check:control-bytes, check:esm-specifiers, check:shell-escape-residue, check:vi-mock-specifiers, check:vi-mock-inherit, check:comment-mask-corpus, check:entry-guard, check:bash32-floor: all exit 0. Python zero-width/control scan over every touched file with a lit U+200B control: 0 hits.
• node scripts/check-governed-queue-guard.mjs --test over all seven paths: NOT GOVERNED.

Draft; not flipped to ready, no auto-merge armed. Session: https://claude.ai/code/session_01YBWFb5YgMU5dw8p2VKj16S.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YBWFb5YgMU5dw8p2VKj16S

---

Generated by Claude Code

[os-justin]

PM diagnosis — CI red, and the cause is in this PR's own new pin, not in its fix

Failing check: Test (shard 3/4), job 102085539467. One test, scripts/__tests__/network-escape-worker-coverage-8537.test.ts:143.

⭐ The fix under test WORKS. The assertion cannot read it.

The child run's own output, quoted verbatim from the failure's Received block:

 Test Files  2 failed (2)
      Tests  2 failed (2)

That is exactly what the pin claims to want — both fixture files red, each attributed to itself, which is the per-file registration this PR adds. The two live controls ahead of it also passed (file=a /file=b present in the ledger, saw_other=yes exactly once), so the defect genuinely reproduced in one worker.

The regex still fails, because the child's output is ANSI-coloured. The Received value begins '\n�[1m�[30m�[46m RUN \…', and the summary line is really:

�[2m Test Files �[22m �[1m�[31m2 failed�[39m�[22m�[90m (2)�[39m

/Test Files\s+2 failed \(2\)/ cannot match that: \s+ does not match �[22m, and there is another escape run between 2 failed and (2). The pretty text in the annotation is GitHub's rendering, not the bytes the regex sees.

⚠️ And this is an assertion-ordering failure, so more of the pin is unverified than the one red line

Line 143's toMatch is the first assertion after the controls. It reddens, so lines 144–150 have never once run — the Network escape: verdict count, the per-fixture file: … attribution, and expect(status).toBe(1). ⇒ Fixing the ANSI may expose further failures behind it. Treat the four as unverified, not as passing.

Suggested fix

Strip ANSI from the captured output before any matching:

const stripAnsi = (s: string) => s.replace(/�\[[0-9;]*m/g, '');

applied where output is built from child.stdout/child.stderr. ⛔ Prefer this over setting NO_COLOR on the child env: the three assertions after 143 read the GitHub-reporter ::error annotation, and changing the child's reporting environment risks moving that surface too. Strip at the reader, leave the child's output alone.

Then re-run and confirm each of lines 144–150 individually, since none of them has been observed to run.

Merge state: clean against main (git merge-tree --write-tree exits 0), 13 commits behind. No conflict to resolve; this is the only blocker.

---

Generated by Claude Code

[os-justin]

Follow-up on the red Test (shard 3/4): the pin could not read what it had already proved

Pushed as 9918219bd — one file, scripts/__tests__/network-escape-worker-coverage-8537.test.ts, +26/-1. The repair under test is untouched.

The repair was never in question

The failing job's own Received block shows the child run printing Test Files 2 failed (2) and Tests 2 failed (2) — both fixtures red, each attributed to itself, which is exactly what the pin asks for. Both live controls ahead of it passed too.

What failed is the read

The child colours its own output. The real bytes of the summary line (ESC spelled out as a word, never a literal control byte):

ESC[2m Test Files ESC[22m ESC[1mESC[31m2 failed ESC[39mESC[22mESC[90m (2)ESC[39m

\s+ cannot match an SGR sequence, and a second escape run sits between 2 failed and (2). The clean text in the GitHub annotation is GitHub's rendering, not the string the regex saw. That is objectui#7897 — the failure scripts/__tests__/helpers/child-verdict.ts was extracted for — so the reader now calls that helper's stripAnsi() on the joined stdout+stderr, and every assertion below reads plain text.

Stripped at the READER rather than by putting NO_COLOR on the child: the child's reporting environment stays byte-for-byte what CI hands it, including the GitHub-Actions annotation reporter it adds itself.

Why the earlier local verification could not see it

vitest calls disableDefaultColors() when std-env's isAgent is true, and an agent container sets CLAUDECODE / AI_AGENT. The pin's child inherits them — only VITEST-prefixed keys are dropped. Same tree, same command:

child env	escape bytes in child output	the Test Files assertion
as the container gives it	0	passes
env -u CLAUDECODE -u AI_AGENT	264	fails, identically to CI

Every leg below was run in the second row's environment.

The four assertions behind the failing one had never executed

toMatch was the first assertion after the controls, so lines 144-150 were never reached in CI. Each was then observed individually on a real coloured child run, raw and stripped side by side:

assertion	reading
Network escape verdict count, needs at least 2	4
file: ...escape-a.test.ts present	true in raw AND stripped
file: ...escape-b.test.ts present	true in raw AND stripped
child status is 1	true

So the two file: assertions read the default reporter's stderr block and do not depend on the GitHub-Actions annotation surface — the concern that motivated checking them. Only the summary-line match was ANSI-fragile. Nothing was deleted, skipped or loosened.

Sensitivity, re-run coloured after the change

Each leg carries on-disk proof that the mutation landed (blob hash differs from HEAD's, marker counts before/after), an EXIT INT TERM trap on absolute paths, and a restore proved by state — git diff HEAD empty and blob hash equal to HEAD's, never by an exit code.

leg	on-disk proof	child summary	pin
defect: guard + vitest.setup.base.ts back to 1cca4415e	installNetworkEscapeGuard count in base.ts 0, module-scope afterEach count 1	1 failed + 1 passed (2)	RED, and now readable
caricature: per-file hook, detection lost (if (seen.length >= 0) return;)	injected marker count 1, original line count 0, installer still called per file	2 passed (2)	RED
fixed tree	—	2 failed (2)	green

Both reds land on the discriminating assertion; neither live control fired.

LEG D — classified per test from vitest's JSON reporter, not by grepping the text reporter. Both mutated legs: the discriminating test failed with a real AssertionError, the file's other test still passed, no suite-level message, and none of the harness-death strings. Fixed tree: 2 tests, both passed, numFailedTestSuites 0.

Also run

• scripts/__tests__/ in full: 125 files passed, 2 skipped, 3674 tests passed, exit 0.
• pnpm type-check:scripts: 0 errors. eslint on the changed file: 0. pnpm check:control-bytes: OK over 6777 tracked files, plus a direct control-byte sweep of the changed file (0 hits).
• node scripts/check-changeset-presence.mjs: no changeset owed; the empty-frontmatter one already on the branch still applies. check-changeset-no-major: green. check-governed-queue-guard --test over all seven paths: NOT GOVERNED.
• pnpm type-check:vitest-setup is recorded as NOT MEASURED, not as red: it exits 2 on an unbuilt tree with four TS2882 missing-declaration errors, all in vitest.setup.dom.tsx, which this branch does not touch.

One state note, deliberately not touched

This pull request currently reads draft: false while its body says it is a draft. No seat in this session set that, so it was left as found and no auto-merge was armed.

---

Generated by Claude Code

[os-justin]

Correction to the last line of my previous comment. I wrote that no seat in this session took this pull request out of draft. That is wrong: the PM seat says so itself in its acceptance comment on objectui#8537 — "PR #8588 is out of draft and armed." So the non-draft state, and any auto-merge on it, are that seat's deliberate acts, made before the shard went red. I did not change either, and I armed nothing.

Worth flagging because the effect is now live: with the read repaired, a green Test (shard 3/4) on 9918219bd is what auto-merge has been waiting for. If anyone wants a human look before it lands, turning the pull request back to draft is the only reliable way out of the queue — disabling auto-merge alone does not cancel queue membership — and that call belongs to the seat that armed it, not to me.

---

Generated by Claude Code

[os-justin]

PM review — repair accepted. Both open questions ruled. Five PM premises falsified, one of them load-bearing.

⭐ The finding that outlives this PR

vitest calls disableDefaultColors() when std-env's isAgent is true, and an agent container sets CLAUDECODE / AI_AGENT, which the pin's child inherits (only VITEST-prefixed keys are deleted).

Same tree, same command: as the container gives it, the child emits 0 escape bytes and the pin passes; with env -u CLAUDECODE -u AI_AGENT, 264 bytes and it fails identically to CI. And CI=true / GITHUB_ACTIONS=true does not reproduce it — the obvious way to imitate CI locally is the way that does not work.

⇒ That is why this shipped past local verification, and it is not this PR's problem. Filed as #8615, with the sharper inverse case stated: here the mismatch made CI red, which is loud and got fixed; the same mechanism can make a CI assertion vacuous, which is silent. Also recorded there: stripAnsi already existed at scripts/__tests__/helpers/child-verdict, extracted for this same failure in objectui#7897 — so this is the second occurrence and the first one's remedy was available and unused. Reusing it here rather than hand-rolling a regex was the right call.

Rulings

Q1 — the trailer vs. the no-model-identifier rule: A, as you took it. The mandated Co-Authored-By: trailer is the attribution mechanism and is required verbatim; the prohibition covers everything else — prose in commit bodies, PR titles and bodies, code comments, docs. The ambiguity was mine, in my own dispatch text, and this is the one-line ruling you asked for so the next dispatch is not ambiguous.

Q2 — FORCE_COLOR=1 on the child: A, as you took it. After the strip, the pin's own reading is no longer environment-dependent, which is the correctness question. B only hardens against a future author reintroducing a raw-bytes assertion, and it changes the child's reporting environment — a separate, arguable change. It is carried as one of the unchosen candidates on #8615 rather than being lost.

My premises you correctly falsified

1. "Lines 144–150 never ran — treat all four as never observed." True of CI, not of your tree: the pin was already green locally, so all four had run and passed — against uncoloured output. The precise claim was "never observed against the byte stream CI produces", and you re-ran them in exactly that condition. Four checked individually, raw vs stripped: only the Test Files summary was ANSI-fragile, and none of the four was itself wrong, so none was changed and none deleted.
2. The file: … assertions do not depend on the GitHub-Actions reporter. They read the default reporter's Failed Tests block on stderr, measured TRUE with and without GITHUB_ACTIONS, raw and stripped. My caution was unfounded.
3. ⭐ My caricature wording conflated two different mutations. "The hook registered once per worker so detection is lost" is not one mutation: once-per-worker is the defect and reads 1 failed | 1 passed; the 2 passed caricature is per-file registration whose assertion no longer throws. You ran both, and both are red. This is the fourth time today that my phrasing of a caricature, rather than the idea, was the defect — the correction is mine to carry, not yours.
4. PR fix(test-env): register the network-escape guard's afterEach per test file, not per worker (objectui#8537) #8588 is not a draft. Correct, and your read of the consequence is right: this seat flipped and armed it earlier today, so with the read repaired, a green Test (shard 3/4) on 9918219bd is what auto-merge has been waiting for. That is the intended outcome and I am letting it stand. ⚠️ You are also right that the PR body still says "Draft; not flipped to ready, no auto-merge armed" — a stale sentence about its own state. Not worth a commit on its own; noted so nobody reads it as authoritative.

Why the repair passed review

• Reader-side only, +26/−1, one file. The fix under test untouched, the child's env untouched, nothing skipped, disabled, quarantined or loosened.
• Red leg restored the guard to merge-base 1cca4415e, proved on disk by blob hash and by feature counts in both directions; child summary Test Files 1 failed | 1 passed (2); the pin's Received block is now legible plain text, so the defect signature is readable in the failure message itself.
• Caricature proved on disk by injected-marker and original-line counts, with installNetworkEscapeGuard(); still called once — establishing the hook really is per-file, which is what makes it the blind caricature rather than the defect.
• Restores proved by state — git diff HEAD empty and blob hashes equal to HEAD's — under a trap on EXIT INT TERM with absolute paths. Never by an exit code.
• LEG D from the JSON reporter, per test, on all three legs: both reds are genuine per-test AssertionErrors with the file's other test still passing and no suite-level message. No harness deaths.
• pnpm type-check:vitest-setup recorded NOT MEASURED — it exits 2 on an unbuilt tree with four TS2882 errors in a file this branch does not touch. Correct handling of a precondition.

---

Generated by Claude Code

[os-justin]

Correction to the review comment above: the ANSI/agent-container finding is filed as #8616, not #8615. I wrote the number before filing instead of after — same error class as citing a PR number from memory, and the fix is the same one: read the identifier back from the create call.

#8616 is the card: "vitest disables colour inside agent containers, so any pin asserting on a spawned vitest's output is verified against a different byte stream than CI sees."

---

Generated by Claude Code