@junghanacs/entwurf 0.41.2 → 0.50.0

package/scripts/check-install-surface.ts

@@ -17,7 +17,10 @@
  *        compiled twin declared in tsconfig.build.json. The exact miss that killed the three.
  *   S3a  no npm bin points at a raw .ts at all; S3b every .sh bin that execs one branches.
  *   S4   dev-only gates are NOT emitted — the tarball ships operator surfaces, not 70+ gate
- *        leaves (a build bloat regression is as real as a missing artifact).
+ *        leaves (a build bloat regression is as real as a missing artifact). A gate with no
+ *        explicit arm is dispatched by its own name (`check-x` → `check_x`, run.sh's default
+ *        arm), so S4 reads those from the function definitions; a case-label reader alone would
+ *        lose every one of them and stay green on what it no longer sees.
  *   S5   no offline smoke carries an obvious write to the operator's real $HOME, and any
  *        smoke that swaps HOME into a sandbox swaps XDG_DATA_HOME with it — moving HOME
  *        alone still writes real install-state below the inherited XDG root, which is
@@ -39,6 +42,41 @@
  *        absent. S7c also pins that the tracked settings carry NO packages key — entwurf's own
  *        checkout self-registers through user scope alone (#110).
  *   S6   tracked first-party text sources are NUL-free (a stray NUL makes git show nothing).
+ *   S8   the by-name dispatch answers only for a gate function run.sh itself defined: a run.sh
+ *        function that is not a gate (`usage`), a gate name nothing defines, one only an
+ *        exported BASH_FUNC_* defines, and one only a comment/heredoc spells all stay the
+ *        Unknown command; an admitted gate runs once, with no argv, its streams and exact exit
+ *        status intact, and stops at its first failure.
+ *   S9   `entwurf --help`, `entwurf help all` and `entwurf help <command>` render root ENTWURF-CLI.json
+ *        through scripts/cli-help.mjs. The root forms and the Unknown path print the short root page,
+ *        byte for byte a reviewed literal fixture (pinned, written before the data and never generated
+ *        from it); `entwurf help all` prints the full catalog — the ce92dc7 usage bytes (a fixture
+ *        outside the tarball, pinned) with explicit amendments only, the `entwurf` prefix and the tool
+ *        count EXPECTED_TOOLS holds — and starts only node on the renderer with `--all`. Every command
+ *        the root page names is described, dispatchable and outside the debt, and an example naming
+ *        anything else fails the source by name. The source is read beside the renderer; of the PATH tools
+ *        it watches, a help run starts only node on that renderer (a PATH watch, not an exec audit —
+ *        the renderer's node:fs-only reach is read directly); a missing or malformed source fails by
+ *        name with no fallback text, exit 1 on every form, apart from a refused help request's 2; an
+ *        early-closed reader ends the page quietly, both pipe sides 0 under pipefail; the committed
+ *        bytes are canonical — the only guard against a duplicated JSON property, which JSON.parse
+ *        accepts. A help preflight between `cmd=${1:-}`
+ *        and the dispatch case answers `help <command>` and `<command> -h|--help` before any arm: on a
+ *        byte copy that stops at the case, every command run.sh has is asked — described ones print
+ *        their page, undescribed ones are refused (exit 2) and never run, the five vendor launchers
+ *        pass through — and extra argv, the `--help <command>` alias and odd names are refused on one
+ *        line. fresh-cut's longer text matches its ce92dc7 source literal minus the old invocation.
+ *        The root page is the #153 literal with three explicit #157 amendments (pinned). `entwurf help
+ *        team` / `help remote-pair` print guide topics byte for byte reviewed literal fixtures (pinned,
+ *        written before the data; remote-pair with one explicit review amendment, pinned too); only
+ *        `help <name>` reaches them, through node on the renderer with
+ *        `--name`; asked as a command (`team --help`) they are refused, their names are no command's,
+ *        `all` or each other's, and the package files they name are shipped by exact files entries.
+ *        Coverage reads owners independently of the data: operator commands are the labels of a case
+ *        byte-pinned to the reviewed ce92dc7 one (evidence for this change, not a ban on later work),
+ *        gate commands are the functions bash itself defines from run.sh — so a definition left only
+ *        as heredoc text is no command — and every description names one of them while the
+ *        undescribed are exactly the ce92dc7 debt.
  *
  * HONEST SCOPE — what a green run does and does not mean. S1-S4 are structural: they read the
  * dispatch graph and the build manifest, so they hold for any entrypoint written in this repo's
@@ -50,13 +88,34 @@
  * and not claimed here. Every S was mutation-checked, including bypasses found in
  * review — do not add an S without proving it fails on the bug it names.
  *
- * Read-only: parses sources, spawns nothing.
+ * Read-only for the repo: parses sources; spawns git, and S8's bounded bash probes — the
+ * checkout's run.sh on the Unknown path, a byte copy of run.sh in a tmp dir with one fixture gate
+ * defined ahead of the unchanged dispatch, and `bash -c` witnesses that an exported function
+ * really imports; S9's root-help runs of the checkout's run.sh and of tmp copies carrying a broken
+ * help source, under a PATH whose leading shims record what a help run starts, byte copies that
+ * stop before the dispatch to list the functions bash defined (scratch HOME/XDG, the same refusing
+ * shims), and a byte copy whose dispatch case is preceded by a sentinel exit, on which every command
+ * is asked for its help without any arm being reachable. Each probe gets PATH plus at most the BASH_FUNC_* or scratch HOME/XDG its cell names,
+ * never the host environment.
  */
 
-import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { FRESH_CUT_EXIT } from "../pi-extensions/lib/meta-session.ts";
+import { EXPECTED_TOOLS } from "./probe-bridge-command.ts";
 
 const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const RUN_SH = readFileSync(path.join(REPO, "run.sh"), "utf8");
@@ -64,6 +123,18 @@ const BUILD_TSCONFIG = readFileSync(path.join(REPO, "mcp/entwurf-bridge/tsconfig
 const PACKAGE_JSON = JSON.parse(readFileSync(path.join(REPO, "package.json"), "utf8")) as {
 	bin?: Record<string, string>;
 };
+// Bash parameter expansion, escaped so the string holds the literal `${1:-}` run.sh carries: the
+// line the top-level dispatch starts at.
+const DISPATCH = `\ncmd=\${1:-}\n`;
+const CLI_JSON = "ENTWURF-CLI.json";
+const CLI_RENDERER = "scripts/cli-help.mjs";
+
+/** Copy the help source and its renderer beside a fixture run.sh, where its usage() reads them. */
+function stageHelp(dir: string, json: string = readFileSync(path.join(REPO, CLI_JSON), "utf8")): void {
+	mkdirSync(path.join(dir, "scripts"), { recursive: true });
+	copyFileSync(path.join(REPO, CLI_RENDERER), path.join(dir, CLI_RENDERER));
+	writeFileSync(path.join(dir, CLI_JSON), json);
+}
 
 let failed = 0;
 function ok(label: string, cond: boolean, detail?: string): void {
@@ -171,6 +242,13 @@ function subcommandTargets(): Map<string, string[]> {
 
 const targets = subcommandTargets();
 const isDevGate = (cmd: string): boolean => cmd.startsWith("check-") || cmd.startsWith("smoke-");
+
+/** Gates no explicit arm claims: run.sh's default arm reaches them by name, check-x → check_x. */
+const byNameGates = new Map<string, string[]>();
+for (const [fn, ts] of functionTargets()) {
+	const cmd = fn.replace(/_/g, "-");
+	if (/^(?:check|smoke)_[a-z0-9_]+$/.test(fn) && !targets.has(cmd)) byNameGates.set(cmd, ts);
+}
 const operatorCmds = [...targets].filter(([cmd, ts]) => !isDevGate(cmd) && ts.length > 0);
 
 {
@@ -188,16 +266,1168 @@ const operatorCmds = [...targets].filter(([cmd, ts]) => !isDevGate(cmd) && ts.le
 			.join("\n\n"),
 	);
 
-	const bloat = [...targets].flatMap(([cmd, tss]) =>
+	// Counted from the raw text, not through functionTargets, so a reader that stopped seeing gate
+	// functions shrinks this set against an independent number instead of passing on fewer rows.
+	const gateFnDefs = [...RUN_SH.matchAll(/^((?:check|smoke)_[a-z0-9_]+)\(\)\s*\{/gm)].map((m) => m[1] as string);
+	const unaccounted = gateFnDefs.filter((fn) => {
+		const cmd = fn.replace(/_/g, "-");
+		return !targets.has(cmd) && !byNameGates.has(cmd);
+	});
+	ok(
+		`[QK:DEV-GATE-BY-NAME-READ] S4 reads every gate function: ${byNameGates.size} dispatched by name + the rest under an explicit arm`,
+		byNameGates.size > 0 && unaccounted.length === 0,
+		unaccounted.length ? `gate functions S4 cannot see: ${unaccounted.join(", ")}` : "no gate is dispatched by name",
+	);
+
+	// Names alone are not coverage: a reader that kept every name but lost its leaves would pass
+	// the bloat check on empty rows. Two gates the by-name arm reaches, with the leaf each one's
+	// run.sh function runs (read off run.sh by hand, not off this reader).
+	const knownLeaves: [cmd: string, leaf: string][] = [
+		["check-peer-facts", "check-peer-facts"],
+		["smoke-herdr-plugin-build-live", "smoke-herdr-plugin-build-live"],
+	];
+	const lostLeaves = knownLeaves.filter(([cmd, leaf]) => !(byNameGates.get(cmd) ?? []).includes(leaf));
+	ok(
+		"[QK:DEV-GATE-BY-NAME-LEAVES] S4 reads the run_ts leaf of a by-name gate, not only its name",
+		lostLeaves.length === 0,
+		lostLeaves.map(([cmd, leaf]) => `'${cmd}' should reach scripts/${leaf}.ts`).join("\n"),
+	);
+
+	const bloat = [...targets, ...byNameGates].flatMap(([cmd, tss]) =>
 		isDevGate(cmd) ? tss.filter((ts) => emitted.has(ts)).map((ts) => [cmd, ts]) : [],
 	);
 	ok(
-		"S4: dev-only gates are not emitted into the tarball",
+		"[QK:DEV-GATE-BY-NAME-NOT-EMITTED] S4: dev-only gates are not emitted into the tarball (explicit arms and by-name gates)",
 		bloat.length === 0,
 		bloat.map(([cmd, ts]) => `'${cmd}' is a dev gate but scripts/${ts}.ts is in the build include`).join("\n"),
 	);
 }
 
+// ─── S8 — the by-name dispatch answers only for a defined gate function ──────────────
+{
+	// Only PATH crosses: the probes end on the Unknown path, and no host identity or secret has a
+	// reason to reach them.
+	const probe = (cmd: string) =>
+		spawnSync("bash", [path.join(REPO, "run.sh"), cmd], {
+			cwd: REPO,
+			encoding: "utf8",
+			env: { PATH: process.env.PATH ?? "/usr/bin:/bin" },
+		});
+	// The Unknown path prints the root page: its first line, with its LF, read from the reviewed
+	// literal (S9 owns the whole-page comparison), marks that page here.
+	const UNKNOWN_PAGE_START = `${readFileSync(path.join(REPO, "test/fixtures/cli-help/root-compact-153.txt"), "utf8").split("\n", 1)[0]}\n`;
+	const isUnknown = (cmd: string): boolean => {
+		const r = probe(cmd);
+		return r.status === 1 && r.stderr === `Unknown command: ${cmd}\n` && r.stdout.startsWith(UNKNOWN_PAGE_START);
+	};
+	ok(
+		"[QK:BY-NAME-GATE-PREFIX] S8a a run.sh function that is not a gate (`usage`) is still the Unknown command, never run by name",
+		isUnknown("usage"),
+	);
+	ok(
+		"[QK:BY-NAME-GATE-DEFINED] S8b a gate name no function defines is still the Unknown command (rc 1 + usage), never a bash command-not-found",
+		isUnknown("check-no-such-gate"),
+	);
+
+	// A byte copy of run.sh with one fixture gate defined ahead of the dispatch, which stays
+	// exactly the production text. The gate fails at its third line, so a dispatcher that loses
+	// errexit runs the marker after it; a comment and a heredoc spell two more gate names that
+	// nothing defines.
+	const dir = mkdtempSync(path.join(os.tmpdir(), "entwurf-by-name-"));
+	try {
+		if (RUN_SH.split(DISPATCH).length !== 2)
+			throw new Error(`S8: run.sh no longer has exactly one \`cmd=\${1:-}\` line`);
+		const fixture = [
+			"check_dispatch_probe() {",
+			"  printf 'argc=%s\\n' \"$#\"",
+			"  echo probe-stderr >&2",
+			"  (exit 7)",
+			"  echo MARK-AFTER-FAILURE",
+			"}",
+			"# check_comment_only() { :; }",
+			": <<'TEXT_ONLY'",
+			"check_heredoc_only() { :; }",
+			"TEXT_ONLY",
+		].join("\n");
+		const copy = path.join(dir, "run.sh");
+		writeFileSync(copy, RUN_SH.replace(DISPATCH, `\n${fixture}${DISPATCH}`));
+		stageHelp(dir); // the Unknown path renders the usage, which reads beside run.sh
+		const run = (argv: string[], extraEnv: Record<string, string> = {}) =>
+			spawnSync("bash", [copy, ...argv], {
+				cwd: dir,
+				encoding: "utf8",
+				env: { PATH: process.env.PATH ?? "/usr/bin:/bin", ...extraEnv },
+			});
+		const unknownIn = (cmd: string, extraEnv: Record<string, string> = {}): boolean => {
+			const r = run([cmd], extraEnv);
+			return r.status === 1 && r.stderr === `Unknown command: ${cmd}\n` && r.stdout.startsWith(UNKNOWN_PAGE_START);
+		};
+		const probe = run(["check-dispatch-probe", "extra-a", "extra-b"]);
+		ok(
+			"[QK:BY-NAME-GATE-RUNS] S8c an admitted gate runs exactly once: its stdout/stderr pass through and its exact nonzero status (7) is run.sh's",
+			probe.status === 7 && probe.stdout.split("argc=").length === 2 && probe.stderr === "probe-stderr\n",
+			`rc=${probe.status} stdout=${JSON.stringify(probe.stdout)} stderr=${JSON.stringify(probe.stderr)}`,
+		);
+		ok(
+			"[QK:BY-NAME-GATE-NO-ARGV] S8d the gate is called with no arguments, as the explicit arm it replaced did",
+			probe.stdout.startsWith("argc=0\n"),
+			`stdout=${JSON.stringify(probe.stdout)}`,
+		);
+		ok(
+			"[QK:BY-NAME-GATE-STOPS] S8e the gate stops at its first failure: the line after it never runs",
+			!probe.stdout.includes("MARK-AFTER-FAILURE") && probe.status === 7,
+			`rc=${probe.status} stdout=${JSON.stringify(probe.stdout)}`,
+		);
+		// An exported function for `fn`, plus the witness that bash really imports that spelling —
+		// without it, a malformed variable would leave no function to refuse and a cell would pass
+		// on nothing.
+		const exportFn = (fn: string): { env: Record<string, string>; imported: boolean } => {
+			const env = { [`BASH_FUNC_${fn}%%`]: "() {  echo env-function-ran\n}" };
+			const w = spawnSync("bash", ["-c", fn], {
+				encoding: "utf8",
+				env: { PATH: process.env.PATH ?? "/usr/bin:/bin", ...env },
+			});
+			return { env, imported: w.stdout === "env-function-ran\n" };
+		};
+		const envOnly = exportFn("check_env_only");
+		ok(
+			"[QK:BY-NAME-GATE-DEFINED-HERE] S8f a gate only an exported environment function defines is the Unknown command",
+			envOnly.imported && unknownIn("check-env-only", envOnly.env),
+			`import witness: ${envOnly.imported}`,
+		);
+		// The same refusal for a name run.sh spells only in a comment or a heredoc, with a real
+		// exported function of that name present — the text must not vouch for it.
+		const textOnly = ["check_comment_only", "check_heredoc_only"].map((fn) => {
+			const e = exportFn(fn);
+			return { fn, imported: e.imported, unknown: unknownIn(fn.replace(/_/g, "-"), e.env) };
+		});
+		ok(
+			"S8g an exported function whose name run.sh spells only in a comment or a heredoc is the Unknown command",
+			textOnly.every((c) => c.imported && c.unknown),
+			JSON.stringify(textOnly),
+		);
+		const shadowed = run(["check-dispatch-probe"], { "BASH_FUNC_check_dispatch_probe%%": "() {  exit 0\n}" });
+		ok(
+			"S8h an environment function with the name of a gate run.sh defines does not replace it",
+			shadowed.status === 7 && shadowed.stdout === "argc=0\n",
+			`rc=${shadowed.status} stdout=${JSON.stringify(shadowed.stdout)}`,
+		);
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+// ─── S9 — `entwurf --help` renders ENTWURF-CLI.json, which describes only real commands ─
+{
+	// The independent oracle is what ce92dc7's usage() heredoc actually printed, kept byte for byte
+	// outside the tarball; the pin fences the fixture itself so neither can drift alone. It is the
+	// CONTENT oracle of the full catalog — the page `entwurf help all` prints, which was the root page
+	// until the root became the short page below — and no expected catalog text or inventory is
+	// derived from the description data. The command pages further down are checked against a page
+	// built from the data entry — a routing and format oracle; their content is bound by this catalog
+	// fixture (every synopsis and summary also prints in the catalog) and by fresh-cut's own fixture.
+	const OLD_USAGE_FIXTURE = "test/fixtures/cli-help/usage-ce92dc7.txt";
+	const OLD_USAGE_SHA256 = "e67f1cb97e5022b865f525d8fb37e3cd0fd0adac927323efd2f27beb9c9e23e6";
+	const oldUsage = readFileSync(path.join(REPO, OLD_USAGE_FIXTURE), "utf8");
+	const sha256 = (s: string): string => createHash("sha256").update(s).digest("hex");
+	if (sha256(oldUsage) !== OLD_USAGE_SHA256) throw new Error(`S9: ${OLD_USAGE_FIXTURE} is not the ce92dc7 usage`);
+	// The root page's own oracle: a reviewed literal, pinned, written before the data that renders it
+	// and never generated from it. Moving the root forms from the catalog bytes to these is the
+	// intended change; the catalog keeps its own oracle above, observed through `help all`.
+	const COMPACT_FIXTURE = "test/fixtures/cli-help/root-compact-153.txt";
+	const COMPACT_SHA256 = "30176fa0a2e8598a2ffca98c0e2c4ac773f57dc3428042e15286c87e2b8832ae";
+	const compact153 = readFileSync(path.join(REPO, COMPACT_FIXTURE), "utf8");
+	if (sha256(compact153) !== COMPACT_SHA256) {
+		throw new Error(`S9: ${COMPACT_FIXTURE} is not the reviewed root page`);
+	}
+	// #157 (main 0922fd, approved for GLG): the help row names a command or a topic, and one footer
+	// line points at the two guides; #157 stage 4 adds the Claude Code launch row. Exactly these three
+	// literal edits of the #153 page, each exactly once, and the result pinned too — the sha below was
+	// taken from the amended literal before the data changed.
+	const ROOT_AMENDMENTS_157: { old: string; next: string }[] = [
+		{
+			old: "  entwurf help [<command>]            this overview, or one command's full description\n",
+			next: "  entwurf help [<name>]               this overview, or command/topic help\n",
+		},
+		{
+			old: "not commands here. Advanced maintenance and development gates: entwurf help all\n",
+			next: "not commands here. Advanced maintenance and development gates: entwurf help all\nGuides: entwurf help team | entwurf help remote-pair\n",
+		},
+		// #157 stage 4 (GLG, relayed by main 07697d): the Claude Code launch row, right after
+		// pi-durable's — receipt: the run.sh `claude)` arm. Pinned below with the other two.
+		{
+			old: "  entwurf pi-durable [args...]        the packaged durable pi launcher\n",
+			next: "  entwurf pi-durable [args...]        the packaged durable pi launcher\n  entwurf claude [args...]            Claude Code itself; args go to claude unchanged\n",
+		},
+	];
+	let expectedCompact = compact153;
+	for (const a of ROOT_AMENDMENTS_157) {
+		if (expectedCompact.split(a.old).length !== 2) throw new Error(`S9: root amendment not exactly once: ${a.old}`);
+		expectedCompact = expectedCompact.replace(a.old, a.next);
+	}
+	if (sha256(expectedCompact) !== "24d41fb481b910d2c60a9c14d92dc75f200b7d1214c104b6f26e61a85a8b0949") {
+		throw new Error("S9: the amended root page is not the reviewed #157 page");
+	}
+	// The guide topics' oracles: reviewed literals, pinned, written before the data and never
+	// generated from it. Each names the package files it sends the reader to (S9w checks they ship).
+	const TOPIC_FIXTURES: { name: string; file: string; sha: string; ships: string[] }[] = [
+		{
+			name: "team",
+			file: "test/fixtures/cli-help/topic-team-157.txt",
+			sha: "c5691a0db1cb2dcccac0042fb1cf0439dd472e87623ea6af8419825062b2f672",
+			ships: ["team.json.example"],
+		},
+		{
+			name: "remote-pair",
+			file: "test/fixtures/cli-help/topic-remote-pair-157.txt",
+			sha: "eb60224e5b588b9c6cfed1cd43d816ec0f9a0d10abc2c6da8decc6f3e0808052",
+			ships: ["docs/setup-clean-host.md"],
+		},
+	];
+	const topicPage = new Map<string, string>();
+	for (const t of TOPIC_FIXTURES) {
+		const text = readFileSync(path.join(REPO, t.file), "utf8");
+		if (sha256(text) !== t.sha) throw new Error(`S9: ${t.file} is not the reviewed ${t.name} guide`);
+		topicPage.set(t.name, text);
+	}
+	// #157 review amendment (H1-AMEND-A1): the remote-pair guide's path rule is per host. Exactly this
+	// one literal edit of its baseline fixture, exactly once, and the result pinned — the sha below
+	// was taken by the coordinator before the data changed. The baseline fixture itself is unchanged.
+	const REMOTE_PAIR_AMENDMENT = {
+		old: "  moves the store; the file follows the store. The sending bridge and the\n  SSH receive side must resolve the same path.\n",
+		next: "  moves the store; the file follows the store. On each host, its bridge and\n  its incoming SSH receive process must resolve the same local opt-in path.\n  The paths on the two hosts need not be identical.\n",
+	};
+	const remoteBaseline = topicPage.get("remote-pair") ?? "";
+	if (remoteBaseline.split(REMOTE_PAIR_AMENDMENT.old).length !== 2) {
+		throw new Error("S9: the remote-pair amendment is not exactly once in its baseline fixture");
+	}
+	const remoteAmended = remoteBaseline.replace(REMOTE_PAIR_AMENDMENT.old, REMOTE_PAIR_AMENDMENT.next);
+	if (sha256(remoteAmended) !== "2c53d9050a3c76fdc73c43ac1339b82808dc0f45548ef73903b7e105a7b6780e") {
+		throw new Error("S9: the amended remote-pair guide is not the reviewed #157 page");
+	}
+	topicPage.set("remote-pair", remoteAmended);
+
+	// The catalog today is that ce92dc7 fixture with exactly these explicit amendments applied, each naming
+	// the source that justifies it — never a text regenerated from the new data. The prefix: a command
+	// line names the product, not the checkout's script; columns are absolute, so the character the
+	// prefix loses becomes one more space before `#`. The literals: an old phrase that is no longer
+	// true, replaced where it stands.
+	const respell = (l: string): string =>
+		l.replace(/^ {2}\.\/run\.sh (\S.*?)( +)# /, (_m, syn, gap) => `  entwurf ${syn}${gap} # `);
+	const toolCountWord = ({ 9: "nine" } as Record<number, string>)[EXPECTED_TOOLS.length];
+	const literalAmendments: { old: string; next: string; receipt: string }[] = [
+		{
+			old: "EXACTLY the eight shipped garden verbs",
+			next: `EXACTLY the ${toolCountWord} shipped garden verbs`,
+			receipt:
+				"scripts/probe-bridge-command.ts EXPECTED_TOOLS; check-entwurf-bridge-boot G1f checks the live tools/list",
+		},
+		{
+			old: "roots and BOTH component inverses read-only first; mutates only when every preflight is green; then Claude -> Pi user scope -> runtime -> ledger LAST. A component failure stops with the runtime and ledger intact as retry authority. With NO ledger it removes nothing: a clean host exits 0, and anything found at the plugin's journal/runtime/cache addresses is named",
+			next: "roots, BOTH component inverses and the operator link (#153) read-only first; mutates only when every preflight is green; then the operator link -> Claude -> Pi user scope -> runtime -> ledger LAST. A component failure stops with the runtime and ledger intact as retry authority. With NO ledger it removes nothing: a clean host exits 0, and anything found at the plugin's journal/runtime/cache addresses or its operator-link receipt is named",
+			receipt:
+				"scripts/herdr-plugin-deactivate.mjs: preflightOperatorLink beside the component preflights, removeOperatorLink before the components, operatorLinkLeftovers with no ledger (#153)",
+		},
+		{
+			old: "--continue (this directory's newest session) and --resume (choose one of its sessions) take none of them.",
+			next: "--continue (this directory's newest session), --resume (choose one of its sessions), and --session <native id> (reopen exactly that session of this directory) take none of them and are mutually exclusive.",
+			receipt:
+				"pi/pi-durable/bootstrap.mjs parseArgs: --session in VALUE_FLAGS; session-continue-exclusive, session-resume-exclusive and fresh-only-argument-with-session beside resume-continue-exclusive and the --resume/--continue fresh-only refusals (#157 G3 B-L1)",
+		},
+	];
+	const respelled = oldUsage.split("\n").filter((l) => respell(l) !== l).length;
+	let expectedCatalog = oldUsage.split("\n").map(respell).join("\n");
+	const amendmentProblems: string[] = [];
+	if (toolCountWord === undefined)
+		amendmentProblems.push(`EXPECTED_TOOLS has ${EXPECTED_TOOLS.length} tools, no reviewed word`);
+	for (const a of literalAmendments) {
+		if (expectedCatalog.split(a.old).length !== 2) amendmentProblems.push(`not exactly once in the fixture: ${a.old}`);
+		expectedCatalog = expectedCatalog.replace(a.old, a.next);
+	}
+	// A line the old usage never had: a debt name described since, inserted right after the fixture
+	// line it belongs beside. The text is a reviewed literal whose receipt is the arm it describes.
+	const insertedLines: { after: string; line: string; receipt: string }[] = [
+		{
+			after: "  entwurf pi-durable [args...]        # ",
+			line: "  entwurf pi [args...]                # #118: the MANAGED pi launch. exec()s the pi that `type -P` finds on PATH (a file, never a shell function or alias) in THIS terminal, with --entwurf-control added ahead of your argv, which passes through untouched. Refuses by name when ENTWURF_PI_LAUNCH_ACTIVE is non-empty (it exports that to the pi it starts), when no pi is on PATH (it launches the pi coding agent, it does not install one), or when that path is not an executable regular file",
+			receipt:
+				"run.sh `pi)` arm: type -P pi, the non-empty ENTWURF_PI_LAUNCH_ACTIVE refusal, the missing and non-regular refusals, exec with --entwurf-control",
+		},
+		{
+			after: "  entwurf pi [args...]                # ",
+			line: "  entwurf claude [args...]            # #157: the Claude Code launch. exec()s the claude that `type -P` finds on PATH (a file, never a shell function or alias) in THIS terminal and directory; your argv, --help included, reaches it untouched with nothing added, and its exit status and signals are its own. It sets ENTWURF_CLAUDE_LAUNCH_ACTIVE and removes an inherited PI_SESSION_ID/PI_AGENT_ID pair (another citizen's identity); no other variable is decided here. A garden citizen comes from the meta-bridge plugin and hooks setup installed, which this launch neither checks nor supplies: without them it is plain Claude Code. Refuses by name when ENTWURF_CLAUDE_LAUNCH_ACTIVE is non-empty, when no claude is on PATH (it launches Claude Code, it does not install one), when that path is not an executable regular file, or when it resolves to this run.sh",
+			receipt:
+				"run.sh `claude)` arm: type -P claude, the non-empty ENTWURF_CLAUDE_LAUNCH_ACTIVE refusal, the missing, non-regular and resolves-to-run.sh refusals, unset PI_SESSION_ID PI_AGENT_ID, export of the sentinel, exec with the operator argv alone (#157 stage 4)",
+		},
+		{
+			after: "  entwurf check-codex-app-server-launch  # ",
+			line: "  entwurf check-claude-launch         # #157 stage 4 gate: the Claude Code launch `entwurf claude`, driven through its public address against a FAKE VENDOR on a sandbox PATH. The verb dropped, the argv byte-identical with nothing injected, --help/-h reaching the vendor, the caller's cwd, the sentinel exported, an inherited PI_SESSION_ID/PI_AGENT_ID pair removed and no other environment change, the exit status, pid (exec) and signal passed through, and named refusals for an absent vendor, a non-regular PATH hit, the sentinel and a PATH claude that resolves to run.sh. Hermetic: no real Claude Code, no network, no model turn",
+			receipt: "run.sh check_claude_launch -> scripts/check-claude-launch.ts (#157 stage 4)",
+		},
+		{
+			after: "  entwurf herdr-plugin-deactivate    # ",
+			line: "  entwurf herdr-plugin-expose-operator --bin-dir <abs>  # #153 the ONE explicit operator link: creates exactly <abs>/entwurf -> the Herdr runtime's own node_modules/.bin/entwurf, recorded by a receipt beside the activation ledger (raised to schema 3 first, so an artifact that cannot undo the link refuses the host). Runs only as the active runtime's package, only from a settled runtime with an active ledger, only into a physical directory that is an entry of the caller's PATH with no earlier entwurf on it; an existing file there without a receipt is someone else's and is refused. Never edits a profile or picks a directory",
+			receipt: "run.sh `herdr-plugin-expose-operator)` arm -> scripts/herdr-operator-link.mjs expose (#153)",
+		},
+		{
+			after: "  entwurf herdr-plugin-expose-operator --bin-dir <abs>  # ",
+			line: "  entwurf herdr-plugin-withdraw-operator  # #153 the opt-out of herdr-plugin-expose-operator: removes exactly the receipt's link — only while it is still that link — and then the receipt; the ledger stays at schema 3. Runs only as the active runtime's package. herdr-plugin-deactivate removes the same link first, before any component",
+			receipt: "run.sh `herdr-plugin-withdraw-operator)` arm -> scripts/herdr-operator-link.mjs withdraw (#153)",
+		},
+	];
+	for (const ins of insertedLines) {
+		const rows = expectedCatalog.split("\n");
+		const at = rows.flatMap((l, i) => (l.startsWith(ins.after) ? [i] : []));
+		if (at.length !== 1) amendmentProblems.push(`insertion anchor not exactly once: ${ins.after}`);
+		else rows.splice(at[0] + 1, 0, ins.line);
+		expectedCatalog = rows.join("\n");
+	}
+
+	const helpEnv = { PATH: process.env.PATH ?? "/usr/bin:/bin" };
+	const runHelp = (runSh: string, argv: string[], cwd: string, env: Record<string, string> = helpEnv) =>
+		spawnSync("bash", [runSh, ...argv], { cwd, encoding: "utf8", env });
+	const rootForms: string[][] = [[], ["-h"], ["--help"], ["help"]];
+	/** Recording shims for the tools a help run must not start; `node` gets `nodeTail` instead. */
+	const makeShims = (dir: string, nodeTail: string): { bin: string; trace: string } => {
+		const bin = path.join(dir, "shims");
+		const trace = path.join(dir, "trace");
+		mkdirSync(bin);
+		writeFileSync(trace, "");
+		const watched = [
+			"python3",
+			"pnpm",
+			"npm",
+			"git",
+			"tmux",
+			"herdr",
+			"pi",
+			"claude",
+			"codex",
+			"copilot",
+			"ssh",
+			"curl",
+		];
+		for (const name of ["node", ...watched]) {
+			writeFileSync(
+				path.join(bin, name),
+				`#!/bin/sh\nprintf '%s' "${name}" >>'${trace}'; printf ' %s' "$@" >>'${trace}'; echo >>'${trace}'\n${name === "node" ? nodeTail : "exit 99"}\n`,
+				{ mode: 0o755 },
+			);
+		}
+		return { bin, trace };
+	};
+	const rendersRoot = (runSh: string, cwd: string): string[] => {
+		const bad: string[] = [];
+		for (const argv of rootForms) {
+			const r = runHelp(runSh, argv, cwd);
+			if (r.status !== 0 || r.stderr !== "" || r.stdout !== expectedCompact) {
+				bad.push(`${JSON.stringify(argv)}: rc=${r.status} stdout-sha=${sha256(r.stdout)} stderr=${r.stderr.trim()}`);
+			}
+		}
+		const u = runHelp(runSh, ["no-such-command"], cwd);
+		if (u.status !== 1 || u.stderr !== "Unknown command: no-such-command\n" || u.stdout !== expectedCompact) {
+			bad.push(`unknown: rc=${u.status} stdout-sha=${sha256(u.stdout)} stderr=${u.stderr.trim()}`);
+		}
+		return bad;
+	};
+	const rootBad = rendersRoot(path.join(REPO, "run.sh"), REPO);
+	ok(
+		`[QK:CLI-HELP-ROOT-COMPACT] S9a the root help (no argv, -h, --help, help) and the Unknown path print exactly the reviewed root page (${COMPACT_FIXTURE} with the three #157 amendments)`,
+		rootBad.length === 0,
+		rootBad.join("\n"),
+	);
+	// The catalog the root page used to be: `entwurf help all`, against the ce92dc7 oracle.
+	const allPage = runHelp(path.join(REPO, "run.sh"), ["help", "all"], REPO);
+	ok(
+		"[QK:CLI-HELP-ALL-BYTES] S9a* `entwurf help all` prints exactly the ce92dc7 usage bytes with the reviewed amendments, on stdout, exit 0, nothing on stderr",
+		allPage.status === 0 && allPage.stderr === "" && allPage.stdout === expectedCatalog,
+		`rc=${allPage.status} stdout-sha=${sha256(allPage.stdout)} stderr=${allPage.stderr.trim()}`,
+	);
+	const catalogNow = allPage.stdout;
+	ok(
+		"[QK:CLI-HELP-AMENDMENTS] S9a' each amendment is exact in the catalog `help all` prints: every command line is spelled `entwurf`, the tool count is the one EXPECTED_TOOLS holds, and no replaced phrase survives",
+		amendmentProblems.length === 0 &&
+			respelled === 189 &&
+			!/^ {2}\.\/run\.sh /m.test(catalogNow) &&
+			literalAmendments.every((a) => catalogNow.split(a.next).length === 2 && !catalogNow.includes(a.old)),
+		[...amendmentProblems, `respelled lines: ${respelled}`].join("\n"),
+	);
+	// pi left the description debt: its catalog line is the reviewed literal, once, beside
+	// pi-durable's, and `entwurf help pi` prints that same summary as its page.
+	const piRows = catalogNow.split("\n");
+	const piLine = insertedLines[0].line;
+	const piAt = piRows.flatMap((l, i) => (l === piLine ? [i] : []));
+	const piPage = runHelp(path.join(REPO, "run.sh"), ["help", "pi"], REPO);
+	const piSummary = piLine.slice(piLine.indexOf("# ") + 2);
+	ok(
+		"[QK:CLI-HELP-PI-DESCRIBED] S9a'' `pi` is described by the reviewed literal: one catalog line, right after pi-durable's, and `entwurf help pi` prints that summary",
+		piAt.length === 1 &&
+			piRows[piAt[0] - 1].startsWith(insertedLines[0].after) &&
+			piPage.status === 0 &&
+			piPage.stderr === "" &&
+			piPage.stdout === `Usage: entwurf pi [args...]\n\n${piSummary}\n`,
+		JSON.stringify({ lines: piAt.length, rc: piPage.status, stderr: piPage.stderr, page: piPage.stdout.slice(0, 200) }),
+	);
+	// #157 — each guide topic, asked `entwurf help <name>` on the real run.sh, prints its reviewed
+	// literal: stdout only, exit 0, nothing on stderr.
+	const topicBad = TOPIC_FIXTURES.flatMap((t) => {
+		const r = runHelp(path.join(REPO, "run.sh"), ["help", t.name], REPO);
+		return r.status === 0 && r.stderr === "" && r.stdout === topicPage.get(t.name)
+			? []
+			: [`help ${t.name}: rc=${r.status} stdout-sha=${sha256(r.stdout)} stderr=${r.stderr.trim()}`];
+	});
+	ok(
+		`[QK:CLI-HELP-TOPIC-BYTES] S9a''' \`entwurf help team\` and \`entwurf help remote-pair\` print exactly their reviewed guide pages (team: its fixture; remote-pair: its fixture with the one pinned review amendment), on stdout, exit 0, nothing on stderr`,
+		topicBad.length === 0,
+		topicBad.join("\n"),
+	);
+	// The files a guide sends its reader to must reach every install: each is an EXACT entry of the
+	// package.json files array (no glob reading here — the tarball proof is check-pack's), exists in
+	// this checkout, and is named by its guide's reviewed literal.
+	const packageFiles = (JSON.parse(readFileSync(path.join(REPO, "package.json"), "utf8")) as { files: string[] }).files;
+	const unshipped = TOPIC_FIXTURES.flatMap((t) =>
+		t.ships.flatMap((f) =>
+			packageFiles.includes(f) && existsSync(path.join(REPO, f)) && (topicPage.get(t.name) ?? "").includes(f)
+				? []
+				: [`${t.name} -> ${f}: files entry=${packageFiles.includes(f)} exists=${existsSync(path.join(REPO, f))}`],
+		),
+	);
+	ok(
+		"[QK:CLI-HELP-TOPIC-SHIPPED] S9w every package file a guide topic names (team.json.example, docs/setup-clean-host.md) is an exact package.json files entry, exists, and is named by that guide",
+		unshipped.length === 0,
+		unshipped.join("\n"),
+	);
+
+	const scratch = mkdtempSync(path.join(os.tmpdir(), "entwurf-cli-help-"));
+	try {
+		// A decoy source in the caller's cwd and HOME: the renderer must read the bytes beside itself.
+		const decoy = path.join(scratch, "decoy");
+		mkdirSync(path.join(decoy, "scripts"), { recursive: true });
+		writeFileSync(path.join(decoy, CLI_JSON), "{");
+		const r = runHelp(path.join(REPO, "run.sh"), ["--help"], decoy, { ...helpEnv, HOME: decoy });
+		const rAll = runHelp(path.join(REPO, "run.sh"), ["help", "all"], decoy, { ...helpEnv, HOME: decoy });
+		ok(
+			"[QK:CLI-HELP-MODULE-RELATIVE] S9b the help source is read beside the renderer, never from the caller's cwd or HOME",
+			r.status === 0 && r.stdout === expectedCompact && rAll.status === 0 && rAll.stdout === expectedCatalog,
+			`root rc=${r.status} stderr=${r.stderr.trim()}; help all rc=${rAll.status} stderr=${rAll.stderr.trim()}`,
+		);
+
+		// Production run.sh under a PATH whose first entries record what a help run starts, among the
+		// tools shimmed here: node is wrapped and then really runs, the rest refuse. This is a PATH
+		// watch, not a full exec audit — an absolute-path exec or a module node imports is not seen. The
+		// renderer's own reach is read directly: it imports node:fs alone and reads one module-relative
+		// file. Within that scope a help run starts one thing: node on the shipped renderer, no argument.
+		const { bin: shims, trace } = makeShims(scratch, `exec '${process.execPath}' "$@"`);
+		const traced = { PATH: `${shims}:${helpEnv.PATH}` };
+		for (const argv of [...rootForms, ["no-such-command"]]) runHelp(path.join(REPO, "run.sh"), argv, REPO, traced);
+		const want = `node ${path.join(REPO, CLI_RENDERER)}\n`.repeat(rootForms.length + 1);
+		const got = readFileSync(trace, "utf8");
+		ok(
+			"[QK:CLI-HELP-ONLY-RENDERER] S9c of the PATH tools watched (node, python3, pnpm, npm, git, tmux, herdr, pi, claude, codex, copilot, ssh, curl), a help run starts only node on scripts/cli-help.mjs",
+			got === want,
+			`trace:\n${got}`,
+		);
+		// The catalog's own route, watched the same way: `help all` starts node on the renderer with
+		// `--all`, the one argv that selects the catalog, and nothing else.
+		const allRouteDir = path.join(scratch, "all-route");
+		mkdirSync(allRouteDir);
+		const allShims = makeShims(allRouteDir, `exec '${process.execPath}' "$@"`);
+		runHelp(path.join(REPO, "run.sh"), ["help", "all"], REPO, { PATH: `${allShims.bin}:${helpEnv.PATH}` });
+		const allTrace = readFileSync(allShims.trace, "utf8");
+		ok(
+			"[QK:CLI-HELP-ALL-ROUTE] S9c' of the same watched PATH tools, `entwurf help all` starts exactly node on scripts/cli-help.mjs --all",
+			allTrace === `node ${path.join(REPO, CLI_RENDERER)} --all\n`,
+			`trace:\n${allTrace}`,
+		);
+		// A guide's own route, watched the same way: `help <topic>` starts node on the renderer with
+		// `--name <topic>` — the one mode that may answer with a topic — and nothing else.
+		const topicRouteDir = path.join(scratch, "topic-route");
+		mkdirSync(topicRouteDir);
+		const topicShims = makeShims(topicRouteDir, `exec '${process.execPath}' "$@"`);
+		for (const t of TOPIC_FIXTURES)
+			runHelp(path.join(REPO, "run.sh"), ["help", t.name], REPO, { PATH: `${topicShims.bin}:${helpEnv.PATH}` });
+		const topicTrace = readFileSync(topicShims.trace, "utf8");
+		ok(
+			"[QK:CLI-HELP-TOPIC-ROUTE] S9c'' of the same watched PATH tools, `entwurf help <topic>` starts exactly node on scripts/cli-help.mjs --name <topic>",
+			topicTrace === TOPIC_FIXTURES.map((t) => `node ${path.join(REPO, CLI_RENDERER)} --name ${t.name}\n`).join(""),
+			`trace:\n${topicTrace}`,
+		);
+
+		// A fixture copy whose description source is missing or malformed. Each must fail by name with
+		// nothing on stdout — the root forms and the Unknown path alike, no older text behind them.
+		// These are the RUNTIME refusals. A duplicated JSON property is not one of them: JSON.parse
+		// keeps the last value silently, so only S9g's check-time canonical comparison sees it.
+		const good = JSON.parse(readFileSync(path.join(REPO, CLI_JSON), "utf8")) as {
+			schemaVersion: number;
+			root: Record<string, unknown>;
+			topics: Record<string, unknown>[];
+			usage: { commandGroups: Record<string, unknown>[][] };
+		};
+		const variant = (edit: (d: typeof good) => void): string => {
+			const d = structuredClone(good);
+			edit(d);
+			return JSON.stringify(d);
+		};
+		const first = good.usage.commandGroups[0]?.[0];
+		const broken: [label: string, json: string | null][] = [
+			["missing", null],
+			["not JSON", "{"],
+			[
+				"unsupported schemaVersion",
+				variant((d) => {
+					d.schemaVersion = 1;
+				}),
+			],
+			[
+				"the previous schemaVersion (2, before the root page)",
+				variant((d) => {
+					d.schemaVersion = 2;
+				}),
+			],
+			[
+				"the previous schemaVersion (3, before the guide topics)",
+				variant((d) => {
+					d.schemaVersion = 3;
+				}),
+			],
+			[
+				"a topic with a field the schema does not know",
+				variant((d) => {
+					d.topics[0]!.run = "x";
+				}),
+			],
+			[
+				"a topic named like a described command",
+				variant((d) => {
+					d.topics[0]!.name = "setup";
+				}),
+			],
+			[
+				"a topic named all",
+				variant((d) => {
+					d.topics[0]!.name = "all";
+				}),
+			],
+			[
+				"one topic name twice",
+				variant((d) => {
+					d.topics[1]!.name = d.topics[0]!.name;
+				}),
+			],
+			[
+				"a root page with a field the schema does not know",
+				variant((d) => {
+					d.root.run = "x";
+				}),
+			],
+			[
+				"an entry with a field the schema does not know",
+				variant((d) => {
+					d.usage.commandGroups[0]![0]!.run = "x";
+				}),
+			],
+			[
+				"one command described twice",
+				variant((d) => {
+					d.usage.commandGroups[1]!.push({ ...first });
+				}),
+			],
+			[
+				"details that start on an empty line",
+				variant((d) => {
+					d.usage.commandGroups[0]![0]!.details = ["", "text"];
+				}),
+			],
+			[
+				"details that are not single-line strings",
+				variant((d) => {
+					d.usage.commandGroups[0]![0]!.details = ["one\ntwo"];
+				}),
+			],
+		];
+		const failures: string[] = [];
+		const strictness: Record<string, boolean> = {};
+		for (const [label, json] of broken) {
+			const dir = path.join(scratch, `broken-${Object.keys(strictness).length}`);
+			mkdirSync(dir);
+			writeFileSync(path.join(dir, "run.sh"), RUN_SH);
+			stageHelp(dir, json ?? "");
+			if (json === null) rmSync(path.join(dir, CLI_JSON));
+			let refused = true;
+			// The root forms, the Unknown path, the catalog and a command help: each must be the metadata
+			// failure — exactly 1, never the help refusal's 2 — with nothing on stdout.
+			for (const argv of [
+				["--help"],
+				["no-such-command"],
+				["help", "all"],
+				["peer-facts", "--help"],
+				["help", "team"],
+			]) {
+				const b = runHelp(path.join(dir, "run.sh"), argv, dir);
+				if (b.status !== 1 || b.stdout !== "" || !b.stderr.includes(`entwurf: ${CLI_JSON} `)) {
+					refused = false;
+					failures.push(
+						`${label} ${JSON.stringify(argv)}: rc=${b.status} stdout=${b.stdout.length}B stderr=${b.stderr.trim()}`,
+					);
+				}
+			}
+			strictness[label] = refused;
+		}
+		ok(
+			"[QK:CLI-HELP-FAIL-LOUD] S9d a missing or unparseable help source fails help by name, with no stdout and no fallback text",
+			strictness.missing === true && strictness["not JSON"] === true,
+			failures.join("\n"),
+		);
+		ok(
+			"[QK:CLI-HELP-STRICT-FIELDS] S9e the renderer refuses an old schemaVersion (2 and 3 included), a field the schema does not know in an entry, the root page or a topic, and details that start empty or span lines",
+			strictness["unsupported schemaVersion"] === true &&
+				strictness["the previous schemaVersion (2, before the root page)"] === true &&
+				strictness["the previous schemaVersion (3, before the guide topics)"] === true &&
+				strictness["an entry with a field the schema does not know"] === true &&
+				strictness["a root page with a field the schema does not know"] === true &&
+				strictness["a topic with a field the schema does not know"] === true &&
+				strictness["details that start on an empty line"] === true &&
+				strictness["details that are not single-line strings"] === true,
+			failures.join("\n"),
+		);
+		ok(
+			"[QK:CLI-HELP-UNIQUE] S9f the renderer refuses a command described twice",
+			strictness["one command described twice"] === true,
+			failures.join("\n"),
+		);
+		ok(
+			"[QK:CLI-HELP-TOPIC-DISJOINT] S9f'' the renderer refuses a topic that takes a described command's name, `all`, or another topic's name — one word, one page",
+			strictness["a topic named like a described command"] === true &&
+				strictness["a topic named all"] === true &&
+				strictness["one topic name twice"] === true,
+			failures.join("\n"),
+		);
+		// The two failure kinds stay apart: a broken source is exit 1 on every form above, while the
+		// same command-help shape against an intact source, naming nothing it describes, is the help
+		// refusal's exit 2.
+		const intactRefusal = runHelp(path.join(REPO, "run.sh"), ["help", "no-such-command"], REPO);
+		ok(
+			"[QK:CLI-HELP-METADATA-EXIT] S9f' a missing or malformed source is exit 1 on root, Unknown and command help alike — distinct from the exit 2 of a refused help request",
+			Object.keys(strictness).length === broken.length &&
+				Object.values(strictness).every(Boolean) &&
+				intactRefusal.status === 2 &&
+				intactRefusal.stdout === "" &&
+				intactRefusal.stderr.startsWith("entwurf: no help for "),
+			[...failures, `intact refusal: rc=${intactRefusal.status} stderr=${intactRefusal.stderr.trim()}`].join("\n"),
+		);
+	} finally {
+		rmSync(scratch, { recursive: true, force: true });
+	}
+
+	// Check time only: the committed bytes are the canonical serialisation of what they parse to.
+	// This is what catches a duplicated JSON property (JSON.parse keeps the last one silently, so it
+	// would change the rendering without failing), and it pins one format so a review reads one
+	// shape. It says nothing about a file someone edits after install.
+	const cliBytes = readFileSync(path.join(REPO, CLI_JSON), "utf8");
+	ok(
+		"[QK:CLI-HELP-CANONICAL] S9g ENTWURF-CLI.json is its own canonical serialisation (no duplicated property survives the commit)",
+		cliBytes === `${JSON.stringify(JSON.parse(cliBytes), null, "\t")}\n`,
+		'rewrite it with JSON.stringify(data, null, "\\t") + "\\n"',
+	);
+
+	// Coverage, read independently of the data. Operator commands are the case labels of the
+	// top-level dispatch: the `case "$cmd" in` after the `cmd=${1:-}` line, to the column-0 `esac`
+	// that closes it. That is a text read, so it is bound to the reviewed ce92dc7 case (plus its reviewed
+	// #153 two-arm amendment) by a byte pin
+	// — evidence for this change, not a ban on later dispatch work: a change to the case re-reviews
+	// its labels and moves the pin in the same change. The labels are not claimed to be
+	// runtime-proven. Gate commands are the check_/smoke_ functions bash itself defines when it reads
+	// run.sh — a definition spelled only in a heredoc or a comment defines nothing, and an
+	// environment function is not run.sh's.
+	const CASE_LINE = 'case "$cmd" in\n';
+	const start = RUN_SH.indexOf(DISPATCH);
+	const caseAt = RUN_SH.indexOf(`\n${CASE_LINE}`, start) + 1;
+	const end = RUN_SH.indexOf("\nesac\n", caseAt) + "\nesac\n".length;
+	// Moved for #153: two operator-link arms (herdr-plugin-expose-operator / -withdraw-operator), re-reviewed.
+	// Moved for #157 stage 4: one `claude)` arm, nothing removed (133 -> 134 labels, re-reviewed: `claude`
+	// is a described entry and outside the debt).
+	const REVIEWED_CASE_SHA256 = "bfdafcfad8645ea3651905dd08d73808a724c67e42f89f9721c917f3a494bef9";
+	ok(
+		"[QK:CLI-HELP-DISPATCH-REVIEWED] S9h the case the operator labels are read from is the reviewed ce92dc7 case plus the reviewed #153 two-arm amendment, byte for byte",
+		start > 0 && caseAt > start && sha256(RUN_SH.slice(caseAt, end)) === REVIEWED_CASE_SHA256,
+		"the top-level case changed: re-review its labels against ENTWURF-CLI.json and the debt below, then move the pin",
+	);
+	// The help preflight sits between `cmd=${1:-}` and that case, and nowhere else: the only case is
+	// the pinned one, and the preflight's code opens no case, esac or heredoc that could hide a
+	// second dispatch or move the pinned one.
+	const preflightCode = RUN_SH.slice(start + DISPATCH.length, caseAt)
+		.split("\n")
+		.filter((l) => !/^\s*#/.test(l))
+		.join("\n");
+	ok(
+		"[QK:CLI-HELP-PREFLIGHT-PLACEMENT] S9h' the help preflight is plain if/elif code between the dispatch's `cmd=` line and the one pinned case",
+		RUN_SH.split(CASE_LINE).length === 2 &&
+			/\bexec node "\$REPO_DIR\/scripts\/cli-help\.mjs" --command\b/.test(preflightCode) &&
+			!/\bcase\b|\besac\b|<</.test(preflightCode),
+		preflightCode,
+	);
+	const labels = [...RUN_SH.slice(caseAt, end).matchAll(/^ {2}([a-z][a-z0-9-]*)\)$/gm)].map((m) => m[1] as string);
+
+	// A byte copy that stops right before the dispatch and lists what bash defined while reading it.
+	// Everything above the dispatch runs — assignments and definitions — so the probe gets a scratch
+	// HOME/XDG and the same recording shims as S9c (node included, refusing): nothing may start and
+	// nothing may be written.
+	const bashDefinedGates = (text: string): { names: Set<string>; problems: string[] } => {
+		const dir = mkdtempSync(path.join(os.tmpdir(), "entwurf-gate-fns-"));
+		try {
+			if (text.split(DISPATCH).length !== 2) throw new Error("S9: the copy has no single dispatch line");
+			const home = path.join(dir, "home");
+			mkdirSync(home);
+			const { bin, trace } = makeShims(dir, "exit 99");
+			const copy = path.join(dir, "run.sh");
+			const probe = 'shopt -s extdebug\nfor __f in $(compgen -A function); do declare -F "$__f"; done\nexit 0';
+			writeFileSync(copy, text.replace(DISPATCH, `\n${probe}${DISPATCH}`));
+			const r = spawnSync("bash", [copy], {
+				cwd: dir,
+				encoding: "utf8",
+				env: {
+					PATH: `${bin}:${helpEnv.PATH}`,
+					HOME: home,
+					XDG_CONFIG_HOME: path.join(home, ".config"),
+					XDG_DATA_HOME: path.join(home, ".local/share"),
+					XDG_STATE_HOME: path.join(home, ".local/state"),
+					XDG_CACHE_HOME: path.join(home, ".cache"),
+				},
+			});
+			const problems: string[] = [];
+			if (r.status !== 0 || r.stderr !== "") problems.push(`probe rc=${r.status} stderr=${r.stderr.trim()}`);
+			const started = readFileSync(trace, "utf8");
+			if (started !== "") problems.push(`the probe started:\n${started}`);
+			if (readdirSync(home, { recursive: true }).length > 0) problems.push("the probe wrote below its HOME");
+			const names = new Set<string>();
+			for (const line of r.stdout.split("\n")) {
+				const m = line.match(/^((?:check|smoke)_[a-z0-9_]+) [1-9][0-9]* (.*)$/);
+				if (m && m[2] === copy) names.add((m[1] as string).replace(/_/g, "-"));
+			}
+			return { names, problems };
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	};
+	const defined = bashDefinedGates(RUN_SH);
+	const inventory = new Set([...labels, ...defined.names]);
+	const described = (
+		JSON.parse(cliBytes) as { usage: { commandGroups: { synopsis: string }[][] } }
+	).usage.commandGroups.flatMap((g) => g.map((e) => e.synopsis.split(" ", 1)[0] as string));
+	const orphansOf = (inv: Set<string>): string[] => described.filter((n) => !inv.has(n));
+	const orphans = orphansOf(inventory);
+	ok(
+		`[QK:CLI-HELP-NO-ORPHAN] S9i every described command is a reviewed dispatch label or a gate function bash defines from run.sh (${described.length} described, ${labels.length} labels + ${defined.names.size} gate functions)`,
+		labels.length > 0 && defined.names.size > 0 && defined.problems.length === 0 && orphans.length === 0,
+		[...defined.problems, orphans.length ? `described but not reachable: ${orphans.join(", ")}` : ""]
+			.filter(Boolean)
+			.join("\n"),
+	);
+
+	// The negative that makes the owner read worth having: a real, described gate whose definition
+	// survives only as heredoc text. A text reader still finds `check_peer_facts() {` there; bash
+	// defines nothing, so the name leaves the inventory and its description becomes an orphan.
+	const ownerAt = RUN_SH.indexOf("\ncheck_peer_facts() {\n");
+	const ownerEnd = RUN_SH.indexOf("\n}\n", ownerAt) + "\n}".length;
+	if (ownerAt < 0 || ownerEnd <= ownerAt) throw new Error("S9: run.sh no longer defines check_peer_facts");
+	const textOnlyOwner = bashDefinedGates(
+		`${RUN_SH.slice(0, ownerAt)}\n: <<'TEXT_ONLY'${RUN_SH.slice(ownerAt, ownerEnd)}\nTEXT_ONLY${RUN_SH.slice(ownerEnd)}`,
+	);
+	ok(
+		"[QK:CLI-HELP-REAL-OWNER] S9j a described gate whose definition is left only as heredoc text is not a command: it leaves the inventory and its description is an orphan",
+		defined.names.has("check-peer-facts") &&
+			textOnlyOwner.problems.length === 0 &&
+			!textOnlyOwner.names.has("check-peer-facts") &&
+			orphansOf(new Set([...labels, ...textOnlyOwner.names])).includes("check-peer-facts"),
+		JSON.stringify({ problems: textOnlyOwner.problems, stillDefined: textOnlyOwner.names.has("check-peer-facts") }),
+	);
+
+	// The commands that had no line in the ce92dc7 usage, computed from that commit's run.sh with
+	// the reader above. The set only shrinks: a new command arrives with its description, and a
+	// described debt name leaves this list in the same change.
+	const DESCRIPTION_DEBT = new Set([
+		"check-acp-backend-preflight",
+		"check-acp-carrier-augment",
+		"check-acp-config",
+		"check-acp-cortex",
+		"check-acp-event-mapper",
+		"check-acp-foreground-only",
+		"check-acp-launch-namespace",
+		"check-acp-overlay",
+		"check-acp-prompt-builder",
+		"check-acp-prompt-lifecycle",
+		"check-acp-provider-surface",
+		"check-acp-sdk-surface",
+		"check-acp-session-reuse",
+		"check-acp-session-store",
+		"check-acp-set-model-readback",
+		"check-acp-stop-reason",
+		"check-acp-stream-hooks",
+		"check-acp-tool-surface",
+		"check-acp-usage-accounting",
+		"check-acp-vendor-rejection",
+		"check-agent-guidance-beside",
+		"check-auth-boundary",
+		"check-cc-retire-pidfd",
+		"check-cc-retire-request",
+		"check-claude-floor-coherence",
+		"check-control-retire",
+		"check-control-send-receipt",
+		"check-control-socket-path",
+		"check-entwurf-control-rpc",
+		"check-entwurf-resume-args",
+		"check-entwurf-v2-native-push",
+		"check-entwurf-v2-production",
+		"check-entwurf-v2-retire",
+		"check-entwurf-v2-runner",
+		"check-entwurf-v2-send",
+		"check-entwurf-v2-surface",
+		"check-entwurf-v2-visible-resume",
+		"check-env-namespace",
+		"check-fresh-call-dispatch",
+		"check-fresh-call-provider",
+		"check-herdr-fresh-call",
+		"check-herdr-sandbox",
+		"check-herdr-supply",
+		"check-install-preflight",
+		"check-install-surface",
+		"check-mux-fresh-call",
+		"check-mux-launch",
+		"check-mux-launch-tmux",
+		"check-mux-placement",
+		"check-mux-placement-tmux",
+		"check-omp-receive-arm",
+		"check-pack-win32-carrier",
+		"check-pi-import-surface",
+		"check-pi-launch",
+		"check-pi-preflight",
+		"check-pi-queue-oracle",
+		"check-pi-retire-request",
+		"check-pi-runtime-version",
+		"check-probe-bridge-command",
+		"check-retirement-event",
+		"check-tests-beside-behavior",
+		"check-win32-preview",
+		"doctor-pi-provider",
+		"expose-dev-bin",
+		"remove-dev-bin",
+		"smoke-acp-bundled-mcp-live",
+		"smoke-acp-carrier-augment-live",
+		"smoke-acp-cortex-live",
+		"smoke-acp-long-turn-live",
+		"smoke-acp-mcp-live",
+		"smoke-acp-memory-containment-live",
+		"smoke-acp-ordering-probe-live",
+		"smoke-acp-overlay-live",
+		"smoke-acp-provider-live",
+		"smoke-acp-raw-turn-live",
+		"smoke-acp-rgg-live",
+		"smoke-acp-session-reuse-live",
+		"smoke-acp-skill-live",
+		"smoke-acp-socket-citizen-live",
+		"smoke-acp-v2-send-live",
+		"smoke-herdr-fresh-call-live",
+		"smoke-herdr-plugin-build-live",
+		"smoke-herdr-raw-install-live",
+		"smoke-mux-fresh-call-live",
+		"smoke-omp-receive-state",
+		"smoke-pi-provider-state",
+		"wire-agy-bridge",
+		"wire-agy-hooks",
+		"wire-agy-statusline",
+	]);
+	const undescribed = [...inventory].filter((n) => !described.includes(n));
+	const newDebt = undescribed.filter((n) => !DESCRIPTION_DEBT.has(n));
+	const paid = [...DESCRIPTION_DEBT].filter((n) => !undescribed.includes(n));
+	ok(
+		`[QK:CLI-HELP-DEBT-EXACT] S9k the commands with no description are exactly the ${DESCRIPTION_DEBT.size} the ce92dc7 usage already lacked`,
+		newDebt.length === 0 && paid.length === 0,
+		[
+			newDebt.length ? `no description in ${CLI_JSON}: ${newDebt.join(", ")}` : "",
+			paid.length ? `described or removed — drop from DESCRIPTION_DEBT: ${paid.join(", ")}` : "",
+		]
+			.filter(Boolean)
+			.join("\n"),
+	);
+
+	// The root page names only real, described commands. Read from the reviewed literal itself — not
+	// from the data — every `entwurf <name>` it shows (rows and examples; `help` is the help verb) must
+	// be a described entry, in the inventory, and outside the debt. Then the guard that keeps the data
+	// honest: one example in an otherwise valid source names an undescribed command, and the source
+	// fails by name at that example — an example prints verbatim, so without the guard it would be
+	// advertised, not crash.
+	const rootNamed = [
+		...new Set([...expectedCompact.matchAll(/^ {2}entwurf ([a-z][a-z0-9-]*)/gm)].map((m) => m[1] as string)),
+	].filter((n) => n !== "help");
+	const unreal = rootNamed.filter((n) => !described.includes(n) || !inventory.has(n) || DESCRIPTION_DEBT.has(n));
+	const BAD_NAME = "zz-undescribed";
+	const badExampleDir = mkdtempSync(path.join(os.tmpdir(), "entwurf-root-names-"));
+	let badExample: ReturnType<typeof runHelp>;
+	try {
+		const data = JSON.parse(cliBytes) as { root: { examples: { items: { command: string }[] } } };
+		data.root.examples.items[1]!.command = `entwurf ${BAD_NAME}`;
+		writeFileSync(path.join(badExampleDir, "run.sh"), RUN_SH);
+		stageHelp(badExampleDir, JSON.stringify(data));
+		badExample = runHelp(path.join(badExampleDir, "run.sh"), ["--help"], badExampleDir);
+	} finally {
+		rmSync(badExampleDir, { recursive: true, force: true });
+	}
+	ok(
+		`[QK:CLI-HELP-ROOT-NAMES-REAL] S9k' every command the root page names is described, dispatchable and outside the debt (${rootNamed.length} names), and an example naming an undescribed command fails the source by name at that example`,
+		rootNamed.length > 0 &&
+			unreal.length === 0 &&
+			!inventory.has(BAD_NAME) &&
+			badExample.status === 1 &&
+			badExample.stdout === "" &&
+			badExample.stderr ===
+				`entwurf: ${CLI_JSON} root.examples.items[1].command: ${JSON.stringify(BAD_NAME)} is not a command the catalog describes\n`,
+		JSON.stringify({
+			unreal,
+			rc: badExample.status,
+			stdout: badExample.stdout.slice(0, 120),
+			stderr: badExample.stderr,
+		}),
+	);
+	// ── the help preflight, proven on a copy that cannot dispatch ─────────────────────────
+	// A byte copy of run.sh with one line added right before the unchanged case: whatever gets past
+	// the preflight stops there (stderr DISPATCHED, exit 97) instead of entering an arm, so every
+	// command can be asked safely. The bare root forms and the Unknown path go through that case and
+	// are S9a's, on the real file. Expected pages are built from the entry the data holds; what is
+	// compared is the output of the whole run.sh path — routing and format, not content, which the
+	// catalog and fresh-cut fixtures bind.
+	const VENDORS = ["pi", "pi-durable", "claude", "copilot", "codex-app-server"];
+	type Entry = { synopsis: string; summary: string; details?: string[] };
+	const entryOf = new Map<string, Entry>();
+	for (const g of (JSON.parse(cliBytes) as { usage: { commandGroups: Entry[][] } }).usage.commandGroups)
+		for (const e of g) entryOf.set(e.synopsis.split(" ", 1)[0] as string, e);
+	const page = (e: Entry): string =>
+		`${[`Usage: entwurf ${e.synopsis}`, "", e.summary, ...(e.details ? ["", ...e.details] : [])].join("\n")}\n`;
+	const gated = mkdtempSync(path.join(os.tmpdir(), "entwurf-help-preflight-"));
+	try {
+		const copy = path.join(gated, "run.sh");
+		writeFileSync(copy, RUN_SH.replace(`\n${CASE_LINE}`, `\necho DISPATCHED >&2; exit 97\n${CASE_LINE}`));
+		stageHelp(gated);
+		const run = (argv: string[], env: Record<string, string> = helpEnv) =>
+			spawnSync("bash", [copy, ...argv], { cwd: gated, encoding: "utf8", env });
+		type R = ReturnType<typeof run>;
+		const dispatched = (r: R): boolean => r.status === 97 && r.stderr === "DISPATCHED\n" && r.stdout === "";
+		const refused = (r: R): boolean =>
+			r.status === 2 && r.stdout === "" && /^entwurf: [^\n]*\n$/.test(r.stderr) && !r.stderr.includes("DISPATCHED");
+		const answers =
+			(name: string) =>
+			(r: R): boolean => {
+				const e = entryOf.get(name);
+				return e !== undefined && r.status === 0 && r.stderr === "" && r.stdout === page(e);
+			};
+		const show = (argv: string[], r: R): string =>
+			`${JSON.stringify(argv)}: rc=${r.status} stdout=${r.stdout.length}B stderr=${JSON.stringify(r.stderr.slice(0, 160))}`;
+
+		// Axis 1 — every command run.sh has, asked `--help`, one run each, in order.
+		const t0 = Date.now();
+		const bad = { described: [] as string[], undescribed: [] as string[], vendor: [] as string[] };
+		const count = { described: 0, undescribed: 0, vendor: 0 };
+		for (const name of [...inventory].sort()) {
+			const argv = [name, "--help"];
+			const r = run(argv);
+			if (VENDORS.includes(name)) {
+				count.vendor++;
+				if (!dispatched(r)) bad.vendor.push(show(argv, r));
+			} else if (entryOf.has(name)) {
+				count.described++;
+				if (!answers(name)(r)) bad.described.push(show(argv, r));
+			} else {
+				count.undescribed++;
+				if (!(refused(r) && r.stderr.includes(JSON.stringify(name)))) bad.undescribed.push(show(argv, r));
+			}
+		}
+		const axisSeconds = ((Date.now() - t0) / 1000).toFixed(1);
+		ok(
+			`[QK:CLI-HELP-COMMAND] S9l every described command answers \`<command> --help\` with its own page on stdout, exit 0, nothing on stderr, and no arm entered (${count.described} commands, axis ${axisSeconds}s)`,
+			count.described > 0 && bad.described.length === 0,
+			bad.described.join("\n"),
+		);
+		ok(
+			`[QK:CLI-HELP-NO-DISPATCH] S9m every undescribed command asked \`--help\` is refused (one stderr line naming it, exit 2) and never run (${count.undescribed} commands)`,
+			count.undescribed > 0 && bad.undescribed.length === 0,
+			bad.undescribed.join("\n"),
+		);
+
+		// Axis 2 — the other shapes, on a few representative names.
+		const debtGate = [...DESCRIPTION_DEBT].find((n) => defined.names.has(n) && !VENDORS.includes(n)) as string;
+		const shapes = (cells: [string[], (r: R) => boolean][]): string[] =>
+			cells.flatMap(([argv, judge]) => {
+				const r = run(argv);
+				return judge(r) ? [] : [show(argv, r)];
+			});
+		const formsBad = shapes([
+			[["peer-facts", "-h"], answers("peer-facts")],
+			[["help", "peer-facts"], answers("peer-facts")],
+			[["help", "meta-bridge-fresh-cut"], answers("meta-bridge-fresh-cut")],
+			[["help", "copilot"], answers("copilot")],
+			[["help", debtGate], refused],
+			[["help", "pi"], answers("pi")],
+			[["help", "claude"], answers("claude")],
+			[["help", "no-such-command"], refused],
+			[["no-such-command", "--help"], refused],
+		]);
+		ok(
+			"[QK:CLI-HELP-FORMS] S9n `help <command>` and `<command> -h` answer like `--help`; a vendor launcher's own entry answers `help`; an undescribed or unknown name is refused",
+			formsBad.length === 0,
+			formsBad.join("\n"),
+		);
+		// #157 — a guide is not a command. Its name is no case label, gate function or described entry;
+		// asked the way one asks about something to run (`<topic> --help` / `-h`) it is refused like any
+		// undescribed name, one stderr line naming it, exit 2, nothing run; `help <topic>` still answers.
+		const named = (name: string) => (r: R) => refused(r) && r.stderr.includes(JSON.stringify(name));
+		const notCommandBad = [
+			...TOPIC_FIXTURES.filter((t) => inventory.has(t.name) || entryOf.has(t.name)).map(
+				(t) => `${t.name} is also a command`,
+			),
+			...shapes([
+				[["team", "--help"], named("team")],
+				[["team", "-h"], named("team")],
+				[["remote-pair", "--help"], named("remote-pair")],
+				[["help", "team"], (r) => r.status === 0 && r.stderr === "" && r.stdout === topicPage.get("team")],
+			]),
+		];
+		ok(
+			"[QK:CLI-HELP-TOPIC-NOT-COMMAND] S9n' a guide topic is not a command: its name is no dispatch label, gate or described entry, and `<topic> --help` / `-h` is refused like an undescribed name while `help <topic>` answers",
+			notCommandBad.length === 0,
+			notCommandBad.join("\n"),
+		);
+		const extraBad = shapes([
+			[["peer-facts", "--help", "x"], refused],
+			[["peer-facts", "-h", "x"], refused],
+			[["help", "peer-facts", "x"], refused],
+			[["help", "copilot", "x"], refused],
+			[["help", "pi", "x"], refused],
+			[["help", "all", "x"], refused],
+			[["help", "team", "x"], refused],
+			[[debtGate, "--help", "x"], refused],
+		]);
+		ok(
+			"[QK:CLI-HELP-EXTRA-REFUSED] S9o a help form with more argv after it is refused, exit 2, and runs nothing",
+			extraBad.length === 0,
+			extraBad.join("\n"),
+		);
+		const aliasBad = shapes([
+			[["--help", "peer-facts"], refused],
+			[["-h", "peer-facts"], refused],
+		]);
+		ok(
+			"[QK:CLI-HELP-ALIAS-REFUSED] S9p `--help <command>` / `-h <command>` are refused, not read as `help <command>`",
+			aliasBad.length === 0,
+			aliasBad.join("\n"),
+		);
+		const vendorBad = [
+			...bad.vendor,
+			...shapes([
+				[["copilot", "--help", "x"], dispatched],
+				[["pi", "-h", "x"], dispatched],
+			]),
+		];
+		ok(
+			`[QK:CLI-HELP-VENDOR-PASSTHROUGH] S9q the five vendor launchers keep every argv, help flags included: each reaches its arm (${count.vendor} of ${VENDORS.length})`,
+			count.vendor === VENDORS.length && vendorBad.length === 0,
+			vendorBad.join("\n"),
+		);
+		const positionBad = shapes([
+			[["peer-facts", "x", "--help"], dispatched],
+			[["peer-facts", "--", "--help"], dispatched],
+		]);
+		ok(
+			"[QK:CLI-HELP-NOT-HELP-POSITION] S9r a help flag anywhere but right after the command, or after `--`, is not a help request: it reaches the dispatch as before",
+			positionBad.length === 0,
+			positionBad.join("\n"),
+		);
+		const odd = "bad\nname\u0007";
+		const oddRun = run(["help", odd]);
+		ok(
+			"[QK:CLI-HELP-ONE-LINE] S9s an unknown name with a newline and a control character is quoted onto one stderr line",
+			refused(oddRun) && oddRun.stderr.includes(JSON.stringify(odd)),
+			show(["help", odd], oddRun),
+		);
+
+		// What a command help starts, among the watched PATH tools: node on the renderer, asked for that
+		// one command, and nothing else. #157 amendment: the `help` form asks with `--name`, the mode
+		// that may also answer with a guide topic; the `--help` form keeps `--command`, which may not.
+		const { bin, trace } = makeShims(gated, `exec '${process.execPath}' "$@"`);
+		for (const argv of [
+			["peer-facts", "--help"],
+			["help", "peer-facts"],
+		])
+			run(argv, { PATH: `${bin}:${helpEnv.PATH}` });
+		const traced = readFileSync(trace, "utf8");
+		ok(
+			"[QK:CLI-HELP-COMMAND-TRACE] S9t observed on peer-facts in both forms: of the watched PATH tools, only node on scripts/cli-help.mjs starts — `--command peer-facts` for `--help`, `--name peer-facts` for `help`",
+			traced ===
+				`node ${path.join(gated, CLI_RENDERER)} --command peer-facts\nnode ${path.join(gated, CLI_RENDERER)} --name peer-facts\n`,
+			`trace:\n${traced}`,
+		);
+	} finally {
+		rmSync(gated, { recursive: true, force: true });
+	}
+
+	// fresh-cut's longer text: kept whole as the ce92dc7 source literal of its usage() (the template
+	// slots filled with the constants it named) — read from the source, not captured from a run. The
+	// details carry it with one explicit amendment: the two lines that named the old `node
+	// --experimental-strip-types` invocation and the blank line after them, which the synopsis
+	// `entwurf meta-bridge-fresh-cut` replaces. Nothing else is trimmed. The exit numbers are checked
+	// against the constant the verb itself returns, here in the gate only.
+	const FC_FIXTURE = "test/fixtures/cli-help/fresh-cut-usage-ce92dc7.source-literal.txt";
+	const FC_SHA256 = "f31c766a64fc99705ce81cc413bc4eadc40edd8e031127551d92fa68a8ac35a2";
+	const fcText = readFileSync(path.join(REPO, FC_FIXTURE), "utf8");
+	if (sha256(fcText) !== FC_SHA256) throw new Error(`S9: ${FC_FIXTURE} is not the ce92dc7 source literal`);
+	const fcLines = fcText.slice(0, -1).split("\n"); // the file's final LF is framing, not a line
+	const invocationDropped =
+		fcLines[0]?.startsWith("usage: node --experimental-strip-types ") === true &&
+		fcLines[1]?.trimStart().startsWith("(dev clone:") === true &&
+		fcLines[2] === "";
+	const fcDetails = entryOf.get("meta-bridge-fresh-cut")?.details ?? [];
+	const exitMarks: [keyof typeof FRESH_CUT_EXIT, string][] = [
+		["COMPLETE", "cut complete:"],
+		["NO_MOVE", "NOTHING MOVED:"],
+		["USAGE", "usage."],
+		["HALF_CUT", "CUT TRANSITION INCOMPLETE:"],
+		["CLEANUP_INCOMPLETE", "CUT COMPLETE, CLEANUP INCOMPLETE:"],
+	];
+	const exitsAgree = exitMarks.every(
+		([k, mark]) => fcDetails.filter((l) => l.startsWith(`  ${FRESH_CUT_EXIT[k]}  ${mark}`)).length === 1,
+	);
+	ok(
+		"[QK:CLI-HELP-DETAILS-ORACLE] S9u fresh-cut's details are its ce92dc7 usage text minus only the old invocation lines, and every exit number is the one FRESH_CUT_EXIT returns",
+		invocationDropped && JSON.stringify(fcDetails) === JSON.stringify(fcLines.slice(3)) && exitsAgree,
+		`details=${fcDetails.length} lines, oracle=${fcLines.length - 3} lines, exits agree=${exitsAgree}`,
+	);
+
+	// A reader that stops early (`entwurf --help | head`) closes the pipe. Adopted as a UX amendment:
+	// that ends the page quietly with exit 0 — a stated choice, not a claim about what the old `cat`
+	// returned. pipefail is on and both sides' statuses are read back, so the producer's 0 is seen,
+	// not hidden behind head's. Both pages are read: the short root page can fit the pipe buffer
+	// before the reader closes, so the long catalog (`help all`) is where an early close really bites.
+	const runSh = path.join(REPO, "run.sh");
+	const piped = spawnSync(
+		"bash",
+		[
+			"-c",
+			`set -o pipefail; bash '${runSh}' --help | head -c 1 >/dev/null; root="\${PIPESTATUS[0]} \${PIPESTATUS[1]}"; ` +
+				`bash '${runSh}' help all | head -c 1 >/dev/null; all="\${PIPESTATUS[0]} \${PIPESTATUS[1]}"; ` +
+				`bash '${runSh}' help team | head -c 1 >/dev/null; echo "$root $all \${PIPESTATUS[0]} \${PIPESTATUS[1]}"`,
+		],
+		{ cwd: REPO, encoding: "utf8", env: helpEnv },
+	);
+	ok(
+		"[QK:CLI-HELP-EPIPE-QUIET] S9v `entwurf --help | head`, `entwurf help all | head` and `entwurf help team | head` end without an error on stderr",
+		piped.stderr === "",
+		`stderr=${piped.stderr.slice(0, 200)}`,
+	);
+	ok(
+		"[QK:CLI-HELP-EPIPE-EXIT] S9v' under pipefail, the help producer and head both end 0 when the reader stops early, on the root page, the catalog and a guide topic",
+		piped.status === 0 && piped.stdout === "0 0 0 0 0 0\n",
+		`rc=${piped.status} statuses=${JSON.stringify(piped.stdout)}`,
+	);
+}
+
 // ─── S3 — no npm bin can reach a raw .ts when installed ──────────────────────────────
 {
 	// Two ways a bin dies under node_modules: it IS a .ts, or it is a wrapper that execs one