cursedbelt 4.1.1 → 4.4.0

package/scripts/guardrailsEnforce.ts

@@ -8,13 +8,31 @@
 // invoked from each package's `lint`/`done` script, exiting non-zero on violation).
 //
 // Usage:
-//   bun run ../cursedbelt/scripts/guardrailsEnforce.ts <rule>[,<rule>...] [--scope <name>]
-//     [--reimplements <Name,Name,…>] [root...]
+//   bun run ../cursedbelt/scripts/guardrailsEnforce.ts <rule>[,<rule>...]
+//     [--scope <name> | --baseline <path>]
+//     [--reimplements <Name,Name,…> | --reimplements-from-belt]
+//     [--exclude <path>[,<path>…]] [root...]
 //
 // `--scope <name>` selects the ratchet baseline row (see "Ratchet baseline" below) for
 // the calling package — `cursedbelt` and `cursedshell` each pass their own scope name
 // from their `lint` script. Omitting `--scope` defaults every rule's baseline to 0.
 //
+// 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>
+//                  --baseline scripts/guardrails-baseline.json --reimplements-from-belt src"
+//
+//   --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.
+//                                The rows and the scanned rules must agree exactly, both
+//                                directions. See "a CONSUMER's ratchet" below.
+//   --reimplements-from-belt     derive `no-local-reimplementation`'s name list from THIS
+//                                package's own react index files, so no app hand-maintains
+//                                384 names. Fails closed on an empty list.
+//   --exclude <path>[,<path>…]   drop build output that lives under a source root. Fails
+//                                if it matches nothing.
+//
 // Currently implemented rules:
 //   no-raw-action-button — STANDARDS.md §4a: "a plugin or generated app must not render
 //     a raw <button> for an action (a raw <button> is acceptable only for a purely
@@ -148,7 +166,7 @@
 // ignored (its violations still fire) and a warning is printed.
 
 import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, extname, join, relative } from "node:path";
+import { basename, extname, join, relative, resolve } from "node:path";
 
 const IGNORE_DIR_NAMES = new Set(["node_modules", "dist", "dist-deploy", ".git", "build", "coverage"]);
 const SOURCE_EXTENSIONS = new Set([".tsx", ".jsx", ".css"]);
@@ -240,7 +258,24 @@ function skipQuoted(source: string, start: number): number {
 	return i;
 }
 
-/** Slice from a `<button` (or similar) match to the end of its opening tag, tolerating
+/** One opening tag, in the two forms its checks need. Both strings cover the SAME span
+ *  and have the same length, so a line number or offset taken from one is valid in the
+ *  other. */
+interface OpeningTag {
+	/** Exactly as written, comments included — what a `guardrails-ignore <rule>:` check
+	 *  must read, since the thing it is looking for IS a comment. */
+	readonly text: string;
+	/** The same span with comment bodies blanked to spaces (newlines kept, so offsets and
+	 *  line numbers hold) — what an ATTRIBUTE check must read. An attribute check run over
+	 *  `text` is fooled by prose that merely QUOTES the attribute: a comment reading
+	 *  ``role="radio" + aria-checked says so to a screen reader`` matched
+	 *  `PRESENTATIONAL_MARKER_RE` and silently opted a raw `<button>` out of
+	 *  no-raw-action-button (task 42). Narrowing such a regex only moves the goalposts —
+	 *  the input was wrong, so the input is what changed. */
+	readonly code: string;
+}
+
+/** Read from a `<button` (or similar) match to the end of its opening tag, tolerating
  *  `{...}` JS expressions in attribute values that may themselves contain `>`
  *  (`onClick={() => …}`, which works because that `>` sits inside braces).
  *
@@ -248,30 +283,40 @@ function skipQuoted(source: string, start: number): number {
  *  so it may contain an angle bracket ("a radio-like list rather than a `<select>`").
  *  Those are skipped the same way `blankComments` skips them, because a `>` written in prose
  *  used to end the tag here and make every attribute below it invisible — the
- *  `guardrails-ignore` opt-out included. `blankComments` cannot simply be run first: the
- *  opt-out checks read this slice and must see the ORIGINAL comment text (see the
- *  no-raw-action-button check below), so the skip only suppresses TERMINATION; the comment
- *  stays in what is returned. */
-function extractOpeningTag(source: string, startIndex: number): string {
+ *  `guardrails-ignore` opt-out included. The skip therefore suppresses only TERMINATION;
+ *  the comment text survives in `.text` for the opt-out checks, and is blanked in `.code`
+ *  for the attribute checks. */
+function readOpeningTag(source: string, startIndex: number): OpeningTag {
+	const blank = (span: string) => span.replaceAll(/[^\n]/g, " ");
 	let i = startIndex;
 	let braceDepth = 0;
+	let code = "";
 	while (i < source.length) {
 		const two = source.slice(i, i + 2);
 		if (two === "//") {
 			const end = source.indexOf("\n", i);
-			i = end === -1 ? source.length : end;
+			const stop = end === -1 ? source.length : end;
+			code += blank(source.slice(i, stop));
+			i = stop;
 			continue;
 		}
 		if (two === "/*") {
 			const end = source.indexOf("*/", i + 2);
-			i = end === -1 ? source.length : end + 2;
+			const stop = end === -1 ? source.length : end + 2;
+			code += blank(source.slice(i, stop));
+			i = stop;
 			continue;
 		}
 		const ch = source[i];
 		if (ch === '"' || ch === "'" || ch === "`") {
-			i = skipQuoted(source, i);
+			// A quoted attribute VALUE is real markup, not prose — `role="radio"` must
+			// survive into `.code`, which is the whole point of the attribute checks.
+			const stop = skipQuoted(source, i);
+			code += source.slice(i, stop);
+			i = stop;
 			continue;
 		}
+		code += ch;
 		if (ch === "{") braceDepth++;
 		else if (ch === "}") braceDepth--;
 		else if (ch === ">" && braceDepth <= 0) {
@@ -280,7 +325,7 @@ function extractOpeningTag(source: string, startIndex: number): string {
 		}
 		i++;
 	}
-	return source.slice(startIndex, i);
+	return { text: source.slice(startIndex, i), code };
 }
 
 function lineOf(source: string, index: number): number {
@@ -427,10 +472,13 @@ const noRawActionButton: Rule = {
 		const scannable = blankNonMarkupText(source);
 		RAW_BUTTON_RE.lastIndex = 0;
 		for (const match of scannable.matchAll(RAW_BUTTON_RE)) {
-			// Re-extract the tag from the ORIGINAL source so opt-out comments (which were
-			// just blanked out of `scannable`) are still visible to the ignore checks.
-			const tag = extractOpeningTag(source, match.index);
-			if (IGNORE_COMMENT_RE.test(tag) || PRESENTATIONAL_MARKER_RE.test(tag)) continue;
+			// Re-read the tag from the ORIGINAL source so opt-out comments (which were
+			// just blanked out of `scannable`) are still visible to the ignore check.
+			// The two halves take DIFFERENT inputs, and that is the point: the ignore
+			// check is looking for a comment, the marker check for a real attribute, so
+			// prose quoting `role="radio"` opts nothing out.
+			const tag = readOpeningTag(source, match.index);
+			if (IGNORE_COMMENT_RE.test(tag.text) || PRESENTATIONAL_MARKER_RE.test(tag.code)) continue;
 			const line = lineOf(source, match.index);
 			violations.push({
 				file: filePath,
@@ -492,9 +540,10 @@ const noRawInputs: Rule = {
 		const scannable = blankNonMarkupText(source);
 		RAW_INPUT_RE.lastIndex = 0;
 		for (const match of scannable.matchAll(RAW_INPUT_RE)) {
-			const tag = extractOpeningTag(source, match.index);
+			const tag = readOpeningTag(source, match.index);
 			const ignoreRe = /guardrails-ignore\s+no-raw-inputs\s*:/;
-			if (ignoreRe.test(tag)) continue;
+			// `.text`: this rule's only opt-out IS a comment, so it reads the comments.
+			if (ignoreRe.test(tag.text)) continue;
 			const line = lineOf(source, match.index);
 			violations.push({
 				file: filePath,
@@ -820,6 +869,12 @@ const ISDIRTY_PROP_RE = /\bisDirty\s*=/;
  * primitive. The `(?<!\[)` matters — `body().querySelector('[role="dialog"]')`
  * contains the same characters and is a test READING a dialog, not declaring one;
  * without it every dialog spec in the fleet is a violation.
+ *
+ * 🔴 Run it over COMMENT-BLANKED source only (`blankComments`, as `check` does below),
+ * never over raw text. It is an attribute regex, so prose quoting `role="dialog"` reads
+ * to it as a declaration — the same defect that let a quoted `role="radio"` suppress
+ * no-raw-action-button (task 42, see `OpeningTag`). Here it would fire the other way, on
+ * a comment explaining why a dialog role is wrong.
  */
 const HANDROLLED_DIALOG_RE =
 	/(?<!\[)\brole\s*=\s*(?:['"]dialog['"]|\{\s*['"]dialog['"]\s*\})|<DialogContent\b/g;
@@ -1041,9 +1096,12 @@ const noRawTitleAttr: Rule = {
 			// to delete an a11y requirement. (unit 11)
 			if (match[1] === "iframe") continue;
 			const index = match.index ?? 0;
-			const tag = extractOpeningTag(source, index);
-			if (!TITLE_ATTR_RE.test(tag)) continue;
-			if (TITLE_ATTR_IGNORE_RE.test(tag)) continue;
+			const tag = readOpeningTag(source, index);
+			// Same split as no-raw-action-button, the other way up: reading comments with
+			// an ATTRIBUTE regex here flags an element that has no `title` at all because
+			// a comment in its attribute list mentions one ("not a title= hover hint").
+			if (!TITLE_ATTR_RE.test(tag.code)) continue;
+			if (TITLE_ATTR_IGNORE_RE.test(tag.text)) continue;
 			const line = lineOf(source, index);
 			const windowStart = Math.max(0, line - 3);
 			if (TITLE_ATTR_IGNORE_RE.test(lines.slice(windowStart, line).join("\n"))) continue;
@@ -1678,18 +1736,122 @@ function loadBaseline(): Baseline {
 	}
 }
 
+// ── `--baseline <path>`: a CONSUMER's ratchet, in the consumer's own repo ───────
+// The packaged baseline above cannot be a consuming app's: it lives inside
+// `node_modules/cursedbelt`, so nobody can check their debt ceiling in beside their
+// code. Nine apps each carried an identical ~140-line wrapper to work around that
+// (`apps/*/scripts/guardrails.ts`, deleted 2026-09-18 by tasks/…/202-*.md); this flag
+// is that wrapper, folded into the one place it belongs.
+//
+// The file is FLAT — `{ "<rule>": <count> }`, no scope level, because a repo's
+// baseline is about one repo. A `"$comment"` key is reserved for the why (desk's row
+// list carries fifty lines of it) and is the only non-numeric value tolerated:
+// anything else non-numeric is a typo in a row, and a typo read as `?? 0` would demand
+// a whole inherited pile in one commit, so it is refused by name instead.
+//
+// 🔴 It is TWO-SIDED, and the packaged `--scope` baseline is not. Deliberate, and the
+// asymmetry is the point: `--scope` names a row the CALLER cannot edit (it ships inside
+// the package), so failing a consumer for a number only a cursedbelt release can lower
+// would be a gate nobody can turn green. `--baseline` names a file in the caller's own
+// repo, which they lower in the same commit — so falling below a row fails, printing
+// the number to paste. A one-sided ratchet accumulates slack: fix forty colours, leave
+// the row at 353, and forty may quietly come back. Same idiom as the generation's
+// `check-paths` baseline — inherited debt only falls.
+type FlatBaseline = Record<string, number>;
+
+const BASELINE_COMMENT_KEY = "$comment";
+
+/** Parse a flat `{rule: count}` baseline, refusing anything that is not a count. */
+function parseFlatBaseline(json: string, label: string): FlatBaseline {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(json);
+	} catch (error) {
+		throw new Error(`${label}: invalid JSON — ${(error as Error).message}`);
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		throw new Error(`${label}: expected an object of {"<rule>": <count>}`);
+	}
+	const rows: FlatBaseline = {};
+	for (const [rule, value] of Object.entries(raw as Record<string, unknown>)) {
+		if (rule === BASELINE_COMMENT_KEY) continue;
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+			throw new Error(`${label}: "${rule}" is ${JSON.stringify(value)}, not a violation count`);
+		}
+		rows[rule] = value;
+	}
+	return rows;
+}
+
+/**
+ * Both directions of "the rows and the rules must agree", which is the hole this
+ * closes for the wrappers that used to do it by hand. A rule with no row is scored 0
+ * and demands its whole inherited pile in one commit; a row with no rule is coverage
+ * that is not there — the same defect as a `check-paths` baseline entry matching
+ * nothing. Returns the complaints, empty when the two lists agree.
+ */
+function baselineDisagreements(rows: FlatBaseline, ruleNames: readonly string[]): string[] {
+	const complaints: string[] = [];
+	const missing = ruleNames.filter((name) => !(name in rows));
+	const orphans = Object.keys(rows).filter((name) => !ruleNames.includes(name));
+	if (missing.length > 0) complaints.push(`no row for rule(s) being scanned: ${missing.join(", ")}`);
+	if (orphans.length > 0) complaints.push(`row(s) for rules nobody scans: ${orphans.join(", ")}`);
+	return complaints;
+}
+
+// ── `--reimplements-from-belt`: the name list, off this package's own exports ───
+// `no-local-reimplementation` matches app-declared names against the ones cursedbelt
+// exports (384 of them as this lands). A hand-kept copy of a dependency's export list
+// is a second source of truth that drifts the moment the belt publishes, so the list
+// is read off the react index files of the INSTALLED package — this file's own
+// package, whatever version resolved. `--reimplements <Name,…>` stays for a caller
+// with a list of its own (the CURSEDBELT_INVENTORY.md path in the rule's header).
+const BELT_REACT_ROOT = join(import.meta.dir, "..", "src", "react");
+
+export function beltExportedComponentNames(reactRoot: string = BELT_REACT_ROOT): string[] {
+	const names = new Set<string>();
+	const indexFiles: string[] = [];
+	// `withFileTypes` rather than a `statSync` per entry — the react tree is ~1,300
+	// entries, and one syscall each is 4s of a gate that is meant to be under a minute.
+	const collect = (dir: string) => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) collect(full);
+			else if (entry.name === "index.ts" || entry.name === "index.tsx") indexFiles.push(full);
+		}
+	};
+	collect(reactRoot);
+	for (const file of indexFiles) {
+		const source = readFileSync(file, "utf8");
+		for (const block of source.matchAll(/export\s*\{([^}]*)\}/gs)) {
+			for (const part of block[1]?.split(",") ?? []) {
+				const trimmed = part.trim();
+				if (!trimmed || trimmed.startsWith("type ")) continue;
+				const name = (trimmed.split(/\s+as\s+/).pop() ?? "").trim();
+				if (/^[A-Z][A-Za-z0-9]*$/.test(name)) names.add(name);
+			}
+		}
+	}
+	return [...names];
+}
+
 function main() {
 	const [ruleArg, ...rest] = process.argv.slice(2);
 	const ruleNames = 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>] [--reimplements <Name,…>] [root...]\nKnown rules: ${Object.keys(RULES).join(", ")}`,
+			`Usage: bun run guardrailsEnforce.ts <rule>[,<rule>...] [--scope <name> | --baseline <path>]\n` +
+				`       [--reimplements <Name,…> | --reimplements-from-belt] [--exclude <path>[,<path>…]] [root...]\n` +
+				`Known rules: ${Object.keys(RULES).join(", ")}`,
 		);
 		process.exit(2);
 	}
 
 	let scope: string | undefined;
+	let baselinePath: string | undefined;
+	let fromBelt = false;
+	const excludes: string[] = [];
 	const roots: string[] = [];
 	for (let i = 0; i < rest.length; i++) {
 		if (rest[i] === "--scope") {
@@ -1697,6 +1859,12 @@ function main() {
 			i++;
 			continue;
 		}
+		// A flat `{rule: count}` ratchet in the CALLER's repo — see "a CONSUMER's ratchet".
+		if (rest[i] === "--baseline") {
+			baselinePath = rest[i + 1];
+			i++;
+			continue;
+		}
 		// The inventoried component names `no-local-reimplementation` looks for. Passed
 		// in rather than hardcoded so the list lives beside the inventory it comes from
 		// (fleet/standards/CURSEDBELT_INVENTORY.md) — see that rule's header.
@@ -1705,10 +1873,73 @@ function main() {
 			i++;
 			continue;
 		}
+		if (rest[i] === "--reimplements-from-belt") {
+			fromBelt = true;
+			continue;
+		}
+		// Build output that lives under a source root (desk's `src/generated/assets.ts` is
+		// the compiled browser app, inlined as a module and rewritten by every build). Named
+		// here rather than by listing every sibling root, because "name the siblings" fails
+		// OPEN — a directory added later is silently unscanned.
+		if (rest[i] === "--exclude") {
+			for (const part of (rest[i + 1] ?? "").split(",")) {
+				const trimmed = part.trim();
+				if (trimmed) excludes.push(resolve(trimmed));
+			}
+			i++;
+			continue;
+		}
 		roots.push(rest[i]);
 	}
+
+	if (scope && baselinePath) {
+		console.error("--scope and --baseline are two different ratchets; pass one.");
+		process.exit(2);
+	}
+
+	let flatBaseline: FlatBaseline | undefined;
+	if (baselinePath) {
+		if (!existsSync(baselinePath)) {
+			console.error(`--baseline ${baselinePath}: no such file (relative to ${process.cwd()})`);
+			process.exit(2);
+		}
+		try {
+			flatBaseline = parseFlatBaseline(readFileSync(baselinePath, "utf8"), baselinePath);
+		} catch (error) {
+			console.error((error as Error).message);
+			process.exit(2);
+		}
+		const complaints = baselineDisagreements(flatBaseline, ruleNames);
+		if (complaints.length > 0) {
+			console.error(`${baselinePath} and the rules being scanned disagree:`);
+			for (const complaint of complaints) console.error(`  ${complaint}`);
+			process.exit(2);
+		}
+	}
+
+	if (fromBelt) {
+		// 🔴 Fails CLOSED. An empty list makes `no-local-reimplementation` inert — it would
+		// print "0 violations" for a check that never ran, and a ratchet row of 0 would then
+		// look earned. If the react tree has moved, the run stops instead.
+		let names: string[] = [];
+		try {
+			names = beltExportedComponentNames();
+		} catch (error) {
+			console.error(`--reimplements-from-belt: cannot read ${BELT_REACT_ROOT} — ${(error as Error).message}`);
+			process.exit(2);
+		}
+		if (names.length === 0) {
+			console.error(`--reimplements-from-belt: ${BELT_REACT_ROOT} exports no component names — refusing to scan against an empty list.`);
+			process.exit(2);
+		}
+		setReimplementedNames(names);
+	}
+
 	const baseline = loadBaseline();
-	const scopeBaseline = (scope && baseline[scope]) || {};
+	const scopeBaseline: Record<string, number> = flatBaseline ?? (scope ? (baseline[scope] ?? {}) : {});
+	// `--baseline` names a file the caller owns and can lower; `--scope` does not. That is
+	// the whole reason one is two-sided and the other suggests.
+	const twoSided = flatBaseline !== undefined;
 
 	const searchRoots = roots.length > 0 ? roots : ["."];
 	const files: string[] = [];
@@ -1721,6 +1952,17 @@ function main() {
 			// every directory, e.g. a plugin package with no `apps/` dir)
 		}
 	}
+	if (excludes.length > 0) {
+		const kept = files.filter((file) => !excludes.some((dir) => resolve(file) === dir || resolve(file).startsWith(`${dir}/`)));
+		if (kept.length === files.length) {
+			// An exclusion matching nothing is either a typo or a directory that has moved,
+			// and both read as "that build output is handled" while it is being scanned.
+			console.error(`--exclude matched no scanned file: ${excludes.join(", ")}`);
+			process.exit(2);
+		}
+		files.length = 0;
+		files.push(...kept);
+	}
 
 	const sourcesByFile = new Map<string, string>();
 	for (const file of files) sourcesByFile.set(file, readFileSync(file, "utf8"));
@@ -1751,13 +1993,28 @@ function main() {
 		}
 
 		const allowedByBaseline = scopeBaseline[rule.name] ?? 0;
-		if (violations.length <= allowedByBaseline) {
+		if (violations.length === allowedByBaseline) {
 			console.log(
 				`✓ ${rule.name}: ${violations.length} violation(s) across ${files.length} files (baseline allows ${allowedByBaseline})`,
 			);
-			if (violations.length < allowedByBaseline) {
+			continue;
+		}
+		if (violations.length < allowedByBaseline) {
+			// The ratchet's other side. Under `--scope` this is a suggestion printed at the
+			// end; under `--baseline` it is a failure, because the caller owns that file and
+			// leaving slack in it is how a row stops meaning anything.
+			if (!twoSided) {
+				console.log(
+					`✓ ${rule.name}: ${violations.length} violation(s) across ${files.length} files (baseline allows ${allowedByBaseline})`,
+				);
 				lowerableBaselines[rule.name] = violations.length;
+				continue;
 			}
+			anyExceededBaseline = true;
+			console.error(
+				`✗ ${rule.name}: ${violations.length} violation(s), below the baseline of ${allowedByBaseline} — lower "${rule.name}" ` +
+					`to ${violations.length} in ${baselinePath} (the ratchet only falls)`,
+			);
 			continue;
 		}
 

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"];
+const TOOLS = ["check-paths.ts", "check-doc-citations.ts", "check-gate-graph.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/demoFixture.spec.ts

@@ -4,6 +4,8 @@ import { resolve } from 'node:path';
 import {
 	DEMO_COMMAND,
 	DEMO_DEV_SCRIPT,
+	DEMO_DIST_DIR,
+	DEMO_HOST,
 	DEMO_PACKAGE_DIR,
 	DEMO_PORT,
 	DEMO_ROOT,
@@ -12,7 +14,8 @@ import {
 } from '../demo/devServer';
 import { DEMO_TSCONFIG, derivePaths, readDemoTsconfig, renderPathsBlock } from '../demo/generatePaths';
 import pkg from '../package.json';
-import { STAGES } from '../scripts/verify';
+// The declared graph, read as data — there is no scheduler in this repo to import from.
+const STAGES: readonly { script: string }[] = (pkg as { gate?: { stages?: { script: string }[] } }).gate?.stages ?? [];
 
 /**
  * 🔴 The e2e suite must never be able to sit green while it drives nothing.
@@ -56,19 +59,38 @@ describe('the e2e fixture exists', () => {
 		}
 		expect(pkg.scripts.demo, 'the demo script must start vite on the demo config').toInclude('demo/vite.config.ts');
 		// Playwright drives the BUILT bundle, not the dev server — see demo/devServer.ts.
-		expect(pkg.scripts['demo:serve'], 'demo:serve must build before it previews').toInclude('demo:build');
-		expect(pkg.scripts['demo:serve']).toInclude('vite preview');
+		expect(pkg.scripts['demo:serve'], 'demo:serve must build before it serves').toInclude('demo:build');
+		// 🔴 And it serves it from OUR server, never `vite preview` — which under Bun 1.4.2
+		// exits 1 with ERR_STREAM_WRITE_AFTER_END when a Playwright worker hangs up
+		// mid-response, reddening this gate about one run in four (task 388, 2026-09-18).
+		// Going back to it is a one-word edit, so it is a one-line assertion.
+		expect(pkg.scripts['demo:serve'], 'demo:serve must run scripts/demoServer.ts').toInclude('scripts/demoServer.ts');
+		expect(pkg.scripts['demo:serve'], '`vite preview` dies on a client hang-up under Bun').not.toInclude(
+			'vite preview',
+		);
 	});
 
-	it('both servers serve the port the specs are pointed at', () => {
+	it('every server serves the port the specs are pointed at', () => {
 		// vite silently walks to the next free port unless `strictPort` is set, which is
 		// the same outage wearing a costume: a server that starts perfectly well and a
-		// suite that times out against the port nobody is listening on.
+		// suite that times out against the port nobody is listening on. `Bun.serve` throws
+		// EADDRINUSE rather than walking, and `demoStaticServer.spec.ts` proves it does.
 		const viteConfig = readFileSync(resolve(DEMO_ROOT, 'vite.config.ts'), 'utf8');
-		expect(DEMO_URL).toBe(`http://localhost:${DEMO_PORT}`);
-		// Once for `server` (dev), once for `preview` (what e2e drives).
-		expect(viteConfig.match(/port: DEMO_PORT/g) ?? [], 'both server and preview must pin the port').toHaveLength(2);
-		expect(viteConfig.match(/strictPort: true/g) ?? [], 'both must set strictPort').toHaveLength(2);
+		expect(DEMO_URL).toBe(`http://${DEMO_HOST}:${DEMO_PORT}`);
+		// 🔴 A literal address, never `localhost`. Measured 2026-09-18: two demo servers
+		// bound 4318 at the same time — one on `[::1]`, one on `127.0.0.1` — because
+		// `localhost` resolves to both and each process took whichever its resolver offered
+		// first. Neither bind collided, and which one a client reached was its own
+		// resolution order. A name here is a gate that can silently test a stale bundle.
+		expect(DEMO_HOST, 'the fixture must not be reached through a name that resolves twice').toBe('127.0.0.1');
+		expect(viteConfig, 'the dev server must bind the same one address').toInclude('host: DEMO_HOST');
+		// Once, for `server` — the dev server a human runs. There is no `preview` block any
+		// more, and a second match here would mean one grew back unread.
+		expect(viteConfig.match(/port: DEMO_PORT/g) ?? [], 'the dev server must pin the port').toHaveLength(1);
+		expect(viteConfig.match(/strictPort: true/g) ?? [], 'and must set strictPort').toHaveLength(1);
+		expect(viteConfig, 'the preview block is dead config now — e2e is served by scripts/demoServer.ts').not.toInclude(
+			'preview:',
+		);
 	});
 
 	it('every page the specs navigate to is a real demo entry point', () => {
@@ -98,13 +120,35 @@ describe('the e2e fixture exists', () => {
 		expect(unlisted, `demo/vite.config.ts's rollup input omits:\n  ${unlisted.join('\n  ')}`).toEqual([]);
 	});
 
+	it('🔴 never reuses a server somebody else started', () => {
+		// The gate's meaning must not depend on what the previous agent in this checkout
+		// left running. `reuseExistingServer: !process.env.CI` meant exactly that: `CI` is
+		// unset on this Mac, so a stale listener on 4318 was silently adopted and the demo
+		// build was skipped. Two agents measured the same command at 34.8s and 45.0s on
+		// 2026-09-18 for that reason — the fast one tested a bundle nobody had rebuilt.
+		const config = readFileSync(resolve(e2eDir, 'playwright.config.ts'), 'utf8');
+		expect(config, 'the webServer must always be ours').toInclude('reuseExistingServer: false');
+		expect(config, 'reuse must not be conditional on an env var this machine never sets').not.toMatch(
+			/reuseExistingServer:\s*!?\s*process\.env/,
+		);
+	});
+
+	it('serves exactly the directory the demo build writes', () => {
+		// `scripts/demoServer.ts` serves DEMO_DIST_DIR; vite writes to `outDir` resolved
+		// against its `root`. A custom `outDir` would leave the server pointed at an empty
+		// directory and every spec 404ing against a 200-answering process.
+		const viteConfig = readFileSync(resolve(DEMO_ROOT, 'vite.config.ts'), 'utf8');
+		expect(DEMO_DIST_DIR).toBe(resolve(DEMO_ROOT, 'dist'));
+		expect(viteConfig, 'demoServer.ts assumes vite’s default outDir').not.toInclude('outDir');
+	});
+
 	it('verify actually runs the suite', () => {
 		// Everything above proves the fixture resolves. Only this proves anybody looks:
 		// without it, `e2e` drops back out of the gate and this whole file becomes a
 		// comment about a suite nothing runs.
 		//
 		// 🔴 `verify` stopped being an `&&` chain on 2026-09-15 and became a dependency
-		// graph (`scripts/verify.ts`), so "the script mentions e2e" is no longer where the
+		// graph (the `gate` block in `package.json`), so "the script mentions e2e" is no longer where the
 		// answer lives. Asking the graph is strictly stronger than asking the string was:
 		// `verifyGraph.spec.ts` additionally pins that every OTHER stage of the old chain
 		// is still in it, which the `toInclude` never checked for any of them.