cursedbelt 5.12.0 → 5.13.0

package/scripts/guardrailsEnforce.spec.ts

@@ -8,6 +8,8 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, expect, test } from 'bun:test';
 import {
+  APP_RULES,
+  BELT_INTERNAL_RULES,
   beltExportedComponentNames,
   parseFileAllows,
   RULES,
@@ -261,15 +263,15 @@ describe('no-raw-inputs', () => {
       expect(check('no-raw-inputs', source)).toHaveLength(0);
     });
 
-    test('a file-scoped allowance does not excuse it, and the run fails', () => {
-      withFixture(
+    test('a file-scoped allowance does not excuse it, and the run fails', async () => {
+      await withFixture(
         {
           'src/Choice.tsx':
             '// guardrails-file-allow no-raw-inputs: embeddable-primitive — pretend this is a standalone widget\n' +
             'export const C = () => <input type="radio" className="sr-only" />;\n',
         },
-        (dir) => {
-          const { code, report } = runCli(dir, ['no-raw-inputs', 'src']);
+        async (dir) => {
+          const { code, report } = await runCli(dir, ['no-raw-inputs', 'src']);
           expect(code).toBe(1);
           expect(report).toContain('Choice.tsx:2');
           expect(report).toContain('No opt-out');
@@ -277,14 +279,14 @@ describe('no-raw-inputs', () => {
       );
     });
 
-    test('nor does a baseline row that counts it', () => {
-      withFixture(
+    test('nor does a baseline row that counts it', async () => {
+      await withFixture(
         {
           'src/Choice.tsx': 'export const C = () => <input type="radio" className="sr-only" />;\n',
           'guardrails-baseline.json': JSON.stringify({ 'no-raw-inputs': 1 }),
         },
-        (dir) => {
-          const { code, report } = runCli(dir, ['no-raw-inputs', '--baseline', 'guardrails-baseline.json', 'src']);
+        async (dir) => {
+          const { code, report } = await runCli(dir, ['no-raw-inputs', '--baseline', 'guardrails-baseline.json', 'src']);
           expect(code).toBe(1);
           expect(report).toContain('No opt-out');
         },
@@ -1024,7 +1026,7 @@ describe('no-fast-tooltip', () => {
 
 const CLI = join(import.meta.dir, 'guardrailsEnforce.ts');
 
-function withFixture(files: Record<string, string>, body: (dir: string) => void): void {
+async function withFixture(files: Record<string, string>, body: (dir: string) => void | Promise<void>): Promise<void> {
   const root = mkdtempSync(join(tmpdir(), 'guardrails-cli-'));
   try {
     for (const [rel, contents] of Object.entries(files)) {
@@ -1032,15 +1034,20 @@ function withFixture(files: Record<string, string>, body: (dir: string) => void)
       mkdirSync(join(full, '..'), { recursive: true });
       writeFileSync(full, contents);
     }
-    body(root);
+    await body(root);
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 }
 
-function runCli(cwd: string, args: string[]): { code: number; report: string } {
-  const run = Bun.spawnSync([process.execPath, CLI, ...args], { cwd });
-  return { code: run.exitCode, report: `${run.stdout.toString()}${run.stderr.toString()}` };
+async function runCli(cwd: string, args: string[]): Promise<{ code: number; report: string }> {
+  const child = Bun.spawn([process.execPath, CLI, ...args], { cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  return { code, report: `${stdout}${stderr}` };
 }
 
 /** Two hex colours and one raw <input>: counts a baseline row can be wrong about. */
@@ -1052,10 +1059,49 @@ const FIXTURE = {
 const rowsFor = (colors: number, inputs: number) =>
   JSON.stringify({ 'no-hardcoded-colors': colors, 'no-raw-inputs': inputs });
 
+describe('--all-app-rules (task 2219: a new belt rule reaches every app by itself)', () => {
+  /** A baseline with a zero row for every app rule, then `overrides` on top. */
+  const allRows = (overrides: Record<string, number | undefined> = {}) => {
+    const rows: Record<string, number> = Object.fromEntries(APP_RULES.map((name) => [name, 0]));
+    rows['no-hardcoded-colors'] = 2;
+    rows['no-raw-inputs'] = 1;
+    for (const [name, count] of Object.entries(overrides)) {
+      if (count === undefined) delete rows[name];
+      else rows[name] = count;
+    }
+    return JSON.stringify(rows);
+  };
+
+  test('scans every rule in RULES except the belt-internal ones', () => {
+    expect(APP_RULES).toEqual(Object.keys(RULES).filter((name) => !BELT_INTERNAL_RULES.has(name)));
+    expect(APP_RULES).toContain('no-raw-lazy');
+    expect(APP_RULES).not.toContain('control-height-tokens');
+  });
+
+  test('passes when the baseline has a row for every app rule', async () => {
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': allRows() }, async (dir) => {
+      const { code, report } = await runCli(dir, ['--all-app-rules', '--baseline', 'scripts/baseline.json', 'src']);
+      expect(report).toContain('✓ no-raw-lazy: 0 violation(s)');
+      expect(report).not.toContain('control-height-tokens');
+      expect(code).toBe(0);
+    });
+  });
+
+  test('🔴 a baseline missing a row for a rule the belt added FAILS, naming the rule', async () => {
+    // The whole point: bump the belt, get a new rule, and the gate says so until the app
+    // records its count — rather than the rule never running there at all.
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': allRows({ 'no-raw-lazy': undefined }) }, async (dir) => {
+      const { code, report } = await runCli(dir, ['--all-app-rules', '--baseline', 'scripts/baseline.json', 'src']);
+      expect(code).toBe(2);
+      expect(report).toContain('no row for rule(s) being scanned: no-raw-lazy');
+    });
+  });
+});
+
 describe('--baseline (a consuming repo\'s ratchet)', () => {
-  test('passes when every row equals the count that is actually there', () => {
-    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, (dir) => {
-      const { code, report } = runCli(dir, [
+  test('passes when every row equals the count that is actually there', async () => {
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, async (dir) => {
+      const { code, report } = await runCli(dir, [
         'no-hardcoded-colors,no-raw-inputs',
         '--baseline',
         'scripts/baseline.json',
@@ -1067,11 +1113,11 @@ describe('--baseline (a consuming repo\'s ratchet)', () => {
     });
   });
 
-  test('🔴 a row ABOVE the real count FAILS, printing the number to paste', () => {
+  test('🔴 a row ABOVE the real count FAILS, printing the number to paste', async () => {
     // The half a one-sided ratchet gets wrong: fix a violation, leave the row where it
     // was, and the slack is available for the next one to grow back into silently.
-    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(9, 1) }, (dir) => {
-      const { code, report } = runCli(dir, [
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(9, 1) }, async (dir) => {
+      const { code, report } = await runCli(dir, [
         'no-hardcoded-colors,no-raw-inputs',
         '--baseline',
         'scripts/baseline.json',
@@ -1083,9 +1129,9 @@ describe('--baseline (a consuming repo\'s ratchet)', () => {
     });
   });
 
-  test('a count above its row fails, the way it always did', () => {
-    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 0) }, (dir) => {
-      const { code, report } = runCli(dir, [
+  test('a count above its row fails, the way it always did', async () => {
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 0) }, async (dir) => {
+      const { code, report } = await runCli(dir, [
         'no-hardcoded-colors,no-raw-inputs',
         '--baseline',
         'scripts/baseline.json',
@@ -1096,20 +1142,20 @@ describe('--baseline (a consuming repo\'s ratchet)', () => {
     });
   });
 
-  test('a row for a rule nobody scans is refused — coverage that is not there', () => {
-    withFixture(
+  test('a row for a rule nobody scans is refused — coverage that is not there', async () => {
+    await withFixture(
       { ...FIXTURE, 'scripts/baseline.json': JSON.stringify({ 'no-hardcoded-colors': 2, 'no-raw-zindex': 0 }) },
-      (dir) => {
-        const { code, report } = runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src']);
+      async (dir) => {
+        const { code, report } = await runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src']);
         expect(code).toBe(2);
         expect(report).toContain('row(s) for rules nobody scans: no-raw-zindex');
       },
     );
   });
 
-  test('a scanned rule with no row is refused — a silent 0 demands the whole pile at once', () => {
-    withFixture({ ...FIXTURE, 'scripts/baseline.json': JSON.stringify({ 'no-hardcoded-colors': 2 }) }, (dir) => {
-      const { code, report } = runCli(dir, [
+  test('a scanned rule with no row is refused — a silent 0 demands the whole pile at once', async () => {
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': JSON.stringify({ 'no-hardcoded-colors': 2 }) }, async (dir) => {
+      const { code, report } = await runCli(dir, [
         'no-hardcoded-colors,no-raw-inputs',
         '--baseline',
         'scripts/baseline.json',
@@ -1120,34 +1166,34 @@ describe('--baseline (a consuming repo\'s ratchet)', () => {
     });
   });
 
-  test('"$comment" carries the why; any OTHER non-number is a typo in a row', () => {
-    withFixture(
+  test('"$comment" carries the why; any OTHER non-number is a typo in a row', async () => {
+    await withFixture(
       {
         ...FIXTURE,
         'scripts/baseline.json': JSON.stringify({ $comment: ['the why', 'over several lines'], 'no-hardcoded-colors': 2 }),
       },
-      (dir) => {
-        expect(runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src']).code).toBe(0);
+      async (dir) => {
+        expect((await runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src'])).code).toBe(0);
       },
     );
-    withFixture({ ...FIXTURE, 'scripts/baseline.json': JSON.stringify({ 'no-hardcoded-colors': '2' }) }, (dir) => {
-      const { code, report } = runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src']);
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': JSON.stringify({ 'no-hardcoded-colors': '2' }) }, async (dir) => {
+      const { code, report } = await runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src']);
       expect(code).toBe(2);
       expect(report).toContain('"no-hardcoded-colors" is "2", not a violation count');
     });
   });
 
-  test('a missing baseline file stops the run rather than defaulting every row to 0', () => {
-    withFixture(FIXTURE, (dir) => {
-      const { code, report } = runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/nope.json', 'src']);
+  test('a missing baseline file stops the run rather than defaulting every row to 0', async () => {
+    await withFixture(FIXTURE, async (dir) => {
+      const { code, report } = await runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/nope.json', 'src']);
       expect(code).toBe(2);
       expect(report).toContain('no such file');
     });
   });
 
-  test('is not the packaged --scope ratchet, and says so rather than picking one', () => {
-    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, (dir) => {
-      const { code, report } = runCli(dir, [
+  test('is not the packaged --scope ratchet, and says so rather than picking one', async () => {
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, async (dir) => {
+      const { code, report } = await runCli(dir, [
         'no-hardcoded-colors',
         '--scope',
         'cursedbelt',
@@ -1160,12 +1206,12 @@ describe('--baseline (a consuming repo\'s ratchet)', () => {
     });
   });
 
-  test('--scope stays ONE-sided: below its row passes and only suggests', () => {
+  test('--scope stays ONE-sided: below its row passes and only suggests', async () => {
     // The packaged baseline lives inside node_modules, so a consumer cannot lower a row
     // in it. Failing them for a number only a cursedbelt release can change would be a
     // gate nobody can turn green — which is why only --baseline is two-sided.
-    withFixture(FIXTURE, (dir) => {
-      const { code, report } = runCli(dir, ['no-hardcoded-colors', '--scope', 'cursedbelt', 'src']);
+    await withFixture(FIXTURE, async (dir) => {
+      const { code, report } = await runCli(dir, ['no-hardcoded-colors', '--scope', 'cursedbelt', 'src']);
       expect(code).toBe(1); // 2 found against the packaged cursedbelt row of 0
       expect(report).toContain('exceeds baseline of 0');
     });
@@ -1173,16 +1219,16 @@ describe('--baseline (a consuming repo\'s ratchet)', () => {
 });
 
 describe('--reimplements-from-belt', () => {
-  test('flags a local component named after one this package exports', () => {
+  test('flags a local component named after one this package exports', async () => {
     // Read off this package's own react index files, so the list is the truth of the
     // version an app installed rather than a copy it maintains.
-    withFixture(
+    await withFixture(
       {
         'src/Button.tsx': 'export function Button() { return null; }\n',
         'scripts/baseline.json': JSON.stringify({ 'no-local-reimplementation': 0 }),
       },
-      (dir) => {
-        const { code, report } = runCli(dir, [
+      async (dir) => {
+        const { code, report } = await runCli(dir, [
           'no-local-reimplementation',
           '--baseline',
           'scripts/baseline.json',
@@ -1216,7 +1262,7 @@ describe('--reimplements-from-belt', () => {
 });
 
 describe('--exclude', () => {
-  test('drops build output that lives under a source root', () => {
+  test('drops build output that lives under a source root', async () => {
     // desk's `src/generated/assets.ts` is the compiled browser app inlined as a module:
     // 282 double-counted violations that move with the bundle, reddening a two-sided
     // ratchet over work nobody did.
@@ -1225,11 +1271,11 @@ describe('--exclude', () => {
       'src/generated/assets.css': '.x { color: #123456; }\n.y { color: #654321; }\n',
       'scripts/baseline.json': rowsFor(2, 1),
     };
-    withFixture(files, (dir) => {
-      const scanned = runCli(dir, ['no-hardcoded-colors,no-raw-inputs', '--baseline', 'scripts/baseline.json', 'src']);
+    await withFixture(files, async (dir) => {
+      const scanned = await runCli(dir, ['no-hardcoded-colors,no-raw-inputs', '--baseline', 'scripts/baseline.json', 'src']);
       expect(scanned.code).toBe(1); // 4 colours, not 2 — the artifact counted as source
 
-      const { code, report } = runCli(dir, [
+      const { code, report } = await runCli(dir, [
         'no-hardcoded-colors,no-raw-inputs',
         '--baseline',
         'scripts/baseline.json',
@@ -1242,9 +1288,9 @@ describe('--exclude', () => {
     });
   });
 
-  test('an exclusion matching nothing is refused, never read as handled', () => {
-    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, (dir) => {
-      const { code, report } = runCli(dir, [
+  test('an exclusion matching nothing is refused, never read as handled', async () => {
+    await withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, async (dir) => {
+      const { code, report } = await runCli(dir, [
         'no-hardcoded-colors,no-raw-inputs',
         '--baseline',
         'scripts/baseline.json',

package/scripts/guardrailsEnforce.ts

@@ -8,7 +8,7 @@
 // invoked from each package's `lint`/`done` script, exiting non-zero on violation).
 //
 // Usage:
-//   bun run ../cursedbelt/scripts/guardrailsEnforce.ts <rule>[,<rule>...]
+//   bun run ../cursedbelt/scripts/guardrailsEnforce.ts <rule>[,<rule>...] | --all-app-rules
 //     [--scope <name> | --baseline <path>]
 //     [--reimplements <Name,Name,…> | --reimplements-from-belt]
 //     [--exclude <path>[,<path>…]] [root...]
@@ -19,9 +19,17 @@
 //
 // A CONSUMING APP uses the other three instead, and needs no wrapper script of its own:
 //
-//   "guardrails": "bun node_modules/cursedbelt/scripts/guardrailsEnforce.ts <rules>
+//   "guardrails": "bun node_modules/cursedbelt/scripts/guardrailsEnforce.ts --all-app-rules
 //                  --baseline scripts/guardrails-baseline.json --reimplements-from-belt src"
 //
+//   --all-app-rules              in place of a rule list: every rule in `RULES` except the
+//                                belt-internal ones (`BELT_INTERNAL_RULES`). Task 2219,
+//                                2026-09-27: each app used to NAME its rules, so a rule the
+//                                belt added reached only the apps somebody remembered to
+//                                edit — `no-raw-lazy` (5.12.0) reached nine of eleven. With
+//                                this flag a belt bump that adds a rule reds the app's gate
+//                                (its two-sided `--baseline` has no row for it) until the app
+//                                records the row: adoption is a forced, visible step.
 //   --baseline <path>            a flat `{ "<rule>": <count> }` ratchet in the CALLER's
 //                                repo, TWO-SIDED — exceeding a row fails, and so does
 //                                falling below one, which prints the number to paste.
@@ -1832,6 +1840,15 @@ export const RULES: Record<string, Rule> = {
 	[noRawLazy.name]: noRawLazy,
 };
 
+/**
+ * Rules that are about cursedbelt's OWN source and mean nothing in an app's.
+ * `control-height-tokens` reads a fixed list of the belt's control-class files.
+ */
+export const BELT_INTERNAL_RULES: ReadonlySet<string> = new Set([controlHeightTokens.name]);
+
+/** What `--all-app-rules` scans: every rule an app's source can break. */
+export const APP_RULES: readonly string[] = Object.keys(RULES).filter((name) => !BELT_INTERNAL_RULES.has(name));
+
 // ── File-scoped allowances ──────────────────────────────────────────────────────
 // `guardrails-file-allow <rule>[,<rule>...]: <category> — <reason>` — a deliberate,
 // reviewable, header-only, category-tagged exemption for the rare file whose whole
@@ -2023,11 +2040,11 @@ export function beltExportedComponentNames(reactRoot: string = BELT_REACT_ROOT):
 
 function main() {
 	const [ruleArg, ...rest] = process.argv.slice(2);
-	const ruleNames = ruleArg ? ruleArg.split(",") : [];
+	const ruleNames = ruleArg === "--all-app-rules" ? [...APP_RULES] : ruleArg ? ruleArg.split(",") : [];
 	const rules = ruleNames.map((n) => RULES[n]).filter((r): r is Rule => Boolean(r));
 	if (ruleNames.length === 0 || rules.length !== ruleNames.length) {
 		console.error(
-			`Usage: bun run guardrailsEnforce.ts <rule>[,<rule>...] [--scope <name> | --baseline <path>]\n` +
+			`Usage: bun run guardrailsEnforce.ts <rule>[,<rule>...] | --all-app-rules [--scope <name> | --baseline <path>]\n` +
 				`       [--reimplements <Name,…> | --reimplements-from-belt] [--exclude <path>[,<path>…]] [root...]\n` +
 				`Known rules: ${Object.keys(RULES).join(", ")}`,
 		);

package/scripts/paths.ts

@@ -38,7 +38,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** The generation's tools this repo runs over its own tree, in the order they should fail. */
-const TOOLS = ["check-paths.ts", "check-doc-citations.ts", "check-gate-graph.ts"];
+const TOOLS = ["check-paths.ts", "check-doc-citations.ts", "check-gate-graph.ts", "check-test-spawn.ts"];
 
 /** How far up either walk looks before giving up — a bound, so a misuse is `null` in ms. */
 const MAX_HOPS = 16;

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -125,18 +125,21 @@ const STATIC_SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+
  * `.js` it emits — a stylesheet cannot import a package, so the CSS output is
  * irrelevant to the question and only the JS is read.
  */
-const staticExternalsOf = (entry: string): Set<string> => {
+const staticExternalsOf = async (entry: string): Promise<Set<string>> => {
   const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-barrel-scan/${entry.replace(/[^a-z0-9]+/gi, '-')}`;
-  const build = Bun.spawnSync(
+  const child = Bun.spawn(
     ['bun', 'build', entry, '--target=bun', '--packages=external', '--outdir', outdir],
-    { cwd: REPO, stdout: 'pipe', stderr: 'pipe' },
+    { cwd: REPO, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
   );
+  const [, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
   const emitted = [...new Bun.Glob('**/*.js').scanSync({ cwd: outdir, onlyFiles: true })];
   const bundle = emitted.map((f) => readFileSync(`${outdir}/${f}`, 'utf8')).join('\n');
-  if (build.exitCode !== 0 || bundle.trim() === '') {
-    throw new Error(
-      `could not bundle ${entry} (exit ${build.exitCode}) — a check that cannot measure is not a passing check:\n${build.stderr.toString()}`,
-    );
+  if (exitCode !== 0 || bundle.trim() === '') {
+    throw new Error(`could not bundle ${entry} (exit ${exitCode}) — a check that cannot measure is not a passing check:\n${stderr}`);
   }
   const found = new Set<string>();
   for (const match of bundle.matchAll(STATIC_SPECIFIER)) {
@@ -152,8 +155,8 @@ const staticExternalsOf = (entry: string): Set<string> => {
   return found;
 };
 
-const staticOptionalPeersOf = (entry: string): string[] =>
-  [...staticExternalsOf(entry)].filter((name) => OPTIONAL_PEERS.has(name)).sort();
+const staticOptionalPeersOf = async (entry: string): Promise<string[]> =>
+  [...(await staticExternalsOf(entry))].filter((name) => OPTIONAL_PEERS.has(name)).sort();
 
 /**
  * 🔴 The INVERSE of everything above, and the half task 149 had to add (2026-09-15).
@@ -213,17 +216,19 @@ describe('barrels reach no optional peer statically', () => {
   });
 
   for (const target of NO_STATIC_OPTIONAL_PEERS) {
-    it(`cursedbelt/${target.subpath.slice(2)} costs a consumer no optional peer to import`, () => {
+    it(`cursedbelt/${target.subpath.slice(2)} costs a consumer no optional peer to import`, async () => {
       expect(
-        staticOptionalPeersOf(target.entry),
+        await staticOptionalPeersOf(target.entry),
         `importing cursedbelt/${target.subpath.slice(2)} statically pulls these OPTIONAL peers, so every consumer must install them for code it may never call. Either import the leaf module that has what you need instead of a sibling INDEX (that is how 'otplib' got in here twice), or make the dependency lazy: \`const { x } = await import('pkg')\` inside the function that needs it.`,
       ).toEqual([]);
     });
   }
 });
 
+const reachedFromReactIndex = await staticExternalsOf('src/react/index.ts');
+
 describe('every runtime dependency is one the barrel actually needs', () => {
-  const reached = staticExternalsOf('src/react/index.ts');
+  const reached = reachedFromReactIndex;
   const declared = Object.keys(
     (pkg as { dependencies?: Record<string, string> }).dependencies ?? {},
   );

package/src/lockfileIsTracked.spec.ts

@@ -23,7 +23,6 @@
  * to skip it. Ignored-vs-not is the property that actually regresses.
  */
 import { describe, expect, test } from 'bun:test'
-import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
@@ -37,13 +36,18 @@ describe('bun.lock is part of the checkout', () => {
     ).toBe(true)
   })
 
-  test('git is not told to ignore it', () => {
-    const git = spawnSync('git', ['check-ignore', '-q', 'bun.lock'], { cwd: repoRoot })
-    if (git.error) return // no git on this host: nothing to assert about ignore rules
+  test('git is not told to ignore it', async () => {
+    let status: number
+    try {
+      const child = Bun.spawn(['git', 'check-ignore', '-q', 'bun.lock'], { cwd: repoRoot, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
+      status = await child.exited
+    } catch {
+      return // no git on this host: nothing to assert about ignore rules
+    }
 
     // exit 0 = the path IS ignored; 1 = it is not; anything else = git could not tell us.
     expect(
-      git.status,
+      status,
       'bun.lock is gitignored, so a fresh clone has no lockfile and `bun install --frozen-lockfile` cannot pass there. Delete the stanza from .gitignore rather than the assertion.',
     ).not.toBe(0)
   })

package/src/react/components/ErrorBoundary.tsx

@@ -1,6 +1,7 @@
 import { Component, type ErrorInfo, type ReactNode, useEffect, useState } from 'react';
 import { Alert } from './Alert.js';
 import { Spinner } from './Spinner.js';
+import { claimStaleChunkReload, staleChunkReloadedRecently } from '../lazy/staleChunk.js';
 import { ConnectionHealer, isUnreachableError, type ServerHealOptions } from './ConnectionHealer.js';
 
 /* ───────────────────────────────────────────────────────────────────────────
@@ -88,7 +89,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
     // visualizer, the owner's report of 2026-08-22), and `isUnreachableError` matches
     // the substring `failed to fetch`, so `autoHeal` would have claimed the server was
     // unreachable while it answered every request. `StaleDeployHealer` reloads exactly
-    // once per tab per URL and explains itself if that does not help.
+    // once per tab per minute and explains itself if that does not help.
     if (isStaleChunkError(error)) return <StaleDeployHealer error={error} />;
     if (autoHeal && isUnreachableError(error))
       return <ConnectionHealer error={error} {...(autoHeal === true ? {} : autoHeal)} />;
@@ -129,7 +130,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
  * hashes, and the route loads. If the chunk is genuinely missing from the
  * deployed artifact rather than merely stale, reloading would loop — so the
  * attempt is recorded in `sessionStorage` and only ever made ONCE per tab per
- * URL. The second failure stops and says what is actually wrong, which is a
+ * minute (the memory `lazyWithReload` shares). The second failure stops and says what is actually wrong, which is a
  * broken deployment and a sentence the owner can act on.
  *
  * Since 2026-08-22 the origin answers a missing build asset with a 404 rather
@@ -157,27 +158,19 @@ export function isStaleChunkError(error: unknown): boolean {
   return STALE_CHUNK_PATTERNS.some((p) => message.includes(p));
 }
 
-/** One key per tab per URL — a reload that did not help must not be repeated. */
-const attemptKey = (): string =>
-  `cwip.staleChunkReload:${typeof window === 'undefined' ? '' : window.location.pathname}`;
-
-/** Whether this tab has already tried reloading for this URL. Never throws. */
+/**
+ * Whether this tab already reloaded for a stale chunk inside the last minute — and
+ * true when storage is unavailable, so a reload loop is impossible in the one
+ * environment where we cannot remember trying. Never throws.
+ *
+ * 🔴 The memory is `lazyWithReload`'s (`../lazy/staleChunk.ts`), shared on purpose.
+ * Until 2026-09-27 this was its own flag, once per tab per URL FOREVER: a tab left
+ * open across a SECOND deploy — a film playing for hours — got "could not be
+ * loaded" instead of a reload, and the two guards could add up to two reloads.
+ */
 export function staleChunkReloadAttempted(): boolean {
-  try {
-    return window.sessionStorage.getItem(attemptKey()) !== null;
-  } catch {
-    // Private mode / disabled storage: treat as "already tried" so a reload loop
-    // is impossible in the one environment where we cannot remember trying.
-    return true;
-  }
-}
-
-function markStaleChunkReload(): void {
-  try {
-    window.sessionStorage.setItem(attemptKey(), '1');
-  } catch {
-    // Nothing to do — `staleChunkReloadAttempted` fails closed for the same reason.
-  }
+  if (typeof window === 'undefined') return true;
+  return staleChunkReloadedRecently();
 }
 
 export interface StaleDeployHealerProps {
@@ -198,11 +191,10 @@ export const StaleDeployHealer = ({ error, onRecover }: StaleDeployHealerProps)
 
   useEffect(() => {
     if (typeof window === 'undefined') return;
-    if (staleChunkReloadAttempted()) {
+    if (!claimStaleChunkReload()) {
       setExhausted(true);
       return;
     }
-    markStaleChunkReload();
     // A tick of delay so the banner paints first — an instant reload on a slow
     // connection reads as a flicker with no explanation.
     const timer = setTimeout(() => {

package/src/react/components/StaleDeployHealer.spec.tsx

@@ -1,5 +1,6 @@
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
 import { cleanup, render, screen, waitFor } from '@testing-library/react';
+import { STALE_CHUNK_RELOADED_AT_KEY } from '../lazy/staleChunk.js';
 import { ErrorBoundary, isStaleChunkError, StaleDeployHealer } from './ErrorBoundary.js';
 
 afterEach(() => {
@@ -105,3 +106,33 @@ describe('StaleDeployHealer recovers exactly once', () => {
     expect(screen.getByText(/VisualizerView-9pEZSQqW\.js/)).toBeTruthy();
   });
 });
+
+describe('StaleDeployHealer shares lazyWithReload\'s memory', () => {
+  /**
+   * 🔴 The old flag was once per tab per URL FOREVER, so a tab left open across a SECOND
+   * deploy — a film playing for hours — hit the dead end instead of reloading.
+   */
+  test('a tab open across two deploys heals both', async () => {
+    let recovered = 0;
+    const first = render(<StaleDeployHealer error={OWNERS_ERROR} onRecover={() => recovered++} />);
+    await waitFor(() => expect(recovered).toBe(1), { timeout: 2000 });
+    first.unmount();
+
+    const twoHoursLater = Date.now() + 2 * 60 * 60_000;
+    const clock = spyOn(Date, 'now').mockImplementation(() => twoHoursLater);
+    try {
+      render(<StaleDeployHealer error={OWNERS_ERROR} onRecover={() => recovered++} />);
+      await waitFor(() => expect(recovered).toBe(2), { timeout: 2000 });
+    } finally {
+      clock.mockRestore();
+    }
+  });
+
+  test('a reload lazyWithReload just made is not repeated by the boundary', async () => {
+    window.sessionStorage.setItem(STALE_CHUNK_RELOADED_AT_KEY, String(Date.now() - 1000));
+    let recovered = 0;
+    render(<StaleDeployHealer error={OWNERS_ERROR} onRecover={() => recovered++} />);
+    await waitFor(() => expect(screen.getByText(/could not be loaded/i)).toBeTruthy());
+    expect(recovered).toBe(0);
+  });
+});

package/src/react/lazy/staleChunk.spec.tsx

@@ -82,12 +82,31 @@ describe('a chunk a deploy removed', () => {
     expect(state.reloads).toBe(2);
   });
 
-  test('with no storage at all it still reloads rather than failing', async () => {
+  /*
+   * 🔴 Fail CLOSED. With no memory, a chunk genuinely missing from the deployed build
+   * would reload forever; the error goes to the boundary instead, which explains it.
+   */
+  test('with no storage it never reloads — the error goes to the boundary', async () => {
     const { state } = fakeEnv(1_000_000);
     const env: StaleChunkEnv = { storage: null, reload: () => void state.reloads++, now: () => 5 };
-    void reloadOnStaleChunk(gone, () => env)();
-    await tick();
-    expect(state.reloads).toBe(1);
+    await expect(reloadOnStaleChunk(gone, () => env)()).rejects.toThrow('dynamically imported');
+    expect(state.reloads).toBe(0);
+  });
+
+  test('storage that refuses a write is no memory either — no reload', async () => {
+    const { state } = fakeEnv(1_000_000);
+    const env: StaleChunkEnv = {
+      storage: {
+        getItem: () => null,
+        setItem: () => {
+          throw new DOMException('blocked', 'SecurityError');
+        },
+      },
+      reload: () => void state.reloads++,
+      now: () => 5,
+    };
+    await expect(reloadOnStaleChunk(gone, () => env)()).rejects.toThrow('dynamically imported');
+    expect(state.reloads).toBe(0);
   });
 });