@junghanacs/entwurf 0.13.1 → 0.14.0

package/scripts/inventory-verification-surface.ts

@@ -0,0 +1,349 @@
+/**
+ * inventory-verification-surface — Phase 0 of issue #62 (vitest adoption).
+ *
+ * The issue's own measurements shifted with the glob used; this script FIXES the
+ * denominator. Review (2026-08-07) found the first cut mis-measured the migration
+ * itself, so the denominator is now BOTH verification axes together:
+ *
+ *   legacy axis     scripts/  (hand-built gates, lib, mutants, fixtures)
+ *   framework axis  test/ + vitest.config.ts  (vitest-managed lanes)
+ *
+ * both from `git ls-files --cached --others --exclude-standard` (tracked plus
+ * untracked-non-ignored — the same work surface qualification hashes), so moving a
+ * gate from scripts/ into test/ moves lines BETWEEN axes and the combined total
+ * stays honest: migration is not subtraction unless the combined number drops.
+ *
+ * PRIMARY classification is the issue's own six semantic classes, decided by the
+ * first matching rule below (re-derivable; narrow explicit overrides carry a
+ * reason and are printed). `unclassified` is asserted to be ZERO — a file no rule
+ * reaches is a loud error, never a silent bucket:
+ *
+ *   1 real-live             name *-live.* OR gates on LIVE=1 (needs real
+ *                           accounts/models/tmux; smoke-*-install-state is NOT
+ *                           live — it matches rule 2 first by name)
+ *   2 package-install       name carries pack|install (tarball/install surface)
+ *   3 hermetic-integration  spawns a subprocess, stands a local server, or is a
+ *                           .sh gate — real processes, no external accounts
+ *   4 source-topology       reads product source as text WITHOUT importing it
+ *   5 behavioral-contract   imports and executes product code, with fs/fixtures
+ *                           or auxiliary source reads
+ *   6 pure-unit             imports and executes product code, no fs, no text
+ *                           reads, no processes
+ *
+ * The SECONDARY style axis (imports-product / source-text / subprocess / mixed /
+ * shell / other) is the issue's measurement table, kept for continuity with the
+ * recorded e405d64 baseline snapshot — style describes HOW a gate is written,
+ * the six classes describe WHAT it proves.
+ *
+ * A test/*.test.ts file is classified together with the ./helpers/* bodies it
+ * imports: the helper is part of how that lane earns its green (a bridge boot
+ * hidden in a helper still makes the lane an integration lane).
+ *
+ * Plus the mutant inventory per lane, split by whether the mutant's SUBJECT is
+ * product code or the verification surface itself (scripts/).
+ *
+ * Read-only and not a gate: it never writes; its one assertion (unclassified=0)
+ * exists so the classification cannot silently rot. Phase 1–4 decisions cite this
+ * one reproducible table instead of ad-hoc greps.
+ */
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function git(args: string[]): string {
+	return execFileSync("git", args, { cwd: REPO_DIR, encoding: "utf8" });
+}
+
+function listWorkSurface(pathspec: string[]): string[] {
+	return [
+		...new Set(
+			git(["ls-files", "--cached", "--others", "--exclude-standard", "--", ...pathspec])
+				.split("\n")
+				.filter((f) => f.length > 0 && fs.existsSync(path.join(REPO_DIR, f))),
+		),
+	].sort();
+}
+
+const legacyFiles = listWorkSurface(["scripts/"]);
+const frameworkFiles = listWorkSurface(["test/", "vitest.config.ts"]);
+
+function countLines(rel: string): number {
+	const body = fs.readFileSync(path.join(REPO_DIR, rel), "utf8");
+	if (body.length === 0) return 0;
+	return body.split("\n").length - (body.endsWith("\n") ? 1 : 0);
+}
+
+// ── rule predicates (printed, so every number is re-derivable) ───────────────
+const H_IMPORTS = /(?:from\s+["']|import\(\s*["'])(?:\.\.\/)+(?:pi-extensions|mcp)\//;
+const H_TEXT = /readFileSync[^\n]*(?:pi-extensions|mcp\/|\.ts["'`]|SOURCE|SRC)|\bread\(["'](?:pi-extensions|mcp)\//;
+const H_PROC = /\b(?:spawn|spawnSync|execFile|execFileSync|execSync|fork)\s*\(|subprocess\.(?:run|Popen|check_)/;
+const H_NET = /\b(?:http|net)\.createServer|\.listen\(/;
+const H_FS = /from\s+["']node:fs["']|require\(["']node:fs["']\)/;
+// H_LIVE asks whether the file's OWN CODE reads the LIVE switch — not whether the
+// three letters appear. The naive `\bLIVE=1\b` form classified
+// scripts/check-release-gate-outcomes.ts as real-live because that gate QUOTES the
+// sentence "a CUT needs LIVE=1, SKIP=0" and greps other files for the literal
+// "process.env.LIVE"; it spawns no live turn of its own. So the predicate runs on the
+// CODE-ONLY projection (comments and inert literals blanked, shell expansions kept)
+// and matches a variable READ or an assignment, never prose.
+const H_LIVE = /process\.env\.LIVE\b|\$\{LIVE[:}\-]|\$LIVE\b|(?:^|\n)\s*(?:export\s+)?LIVE=1\b/;
+
+/**
+ * Blank what cannot gate execution, so H_LIVE reads code and not prose.
+ *
+ * TS: `//` and block comments, and the contents of every quoted literal.
+ * Shell: `#` comments and single-quoted literals only — a double-quoted shell string
+ * still expands `${LIVE:-0}`, so blanking it would hide a real read.
+ */
+function codeOnly(body: string, isShell: boolean): string {
+	if (isShell) {
+		return body.replace(/(^|\s)#[^\n]*/g, "$1").replace(/'[^'\n]*'/g, "''");
+	}
+	return body
+		.replace(/\/\*[\s\S]*?\*\//g, "")
+		.replace(/(^|[^:])\/\/[^\n]*/g, "$1")
+		.replace(/`(?:[^`\\]|\\.)*`/g, "``")
+		.replace(/"(?:[^"\\\n]|\\.)*"/g, '""')
+		.replace(/'(?:[^'\\\n]|\\.)*'/g, "''");
+}
+
+type SemanticClass =
+	| "real-live"
+	| "package-install"
+	| "hermetic-integration"
+	| "source-topology"
+	| "behavioral-contract"
+	| "pure-unit";
+
+/** Narrow explicit overrides for files the mechanical rules cannot reach. Every
+ * entry carries its reason and is printed with the table — extending this map is
+ * a reviewed decision, not a default. */
+const CLASS_OVERRIDES: Record<string, { cls: SemanticClass; reason: string }> = {
+	// These three read repo files through paths assembled at runtime, so the
+	// H_TEXT line-level heuristic cannot see them; each is a structure-over-text
+	// gate with no product execution.
+	"scripts/check-entwurf-bridge-pi-free.ts": {
+		cls: "source-topology",
+		reason: "walks the bridge's static value-import closure as text to forbid @earendil-works imports",
+	},
+	"scripts/check-shell-quote.ts": {
+		cls: "source-topology",
+		reason: "reads the shellQuote() implementation sites as text and cross-checks the POSIX escape contract",
+	},
+	// Imports only scripts/lib (the shared launcher-fence), spawns nothing, and its
+	// smoke-wiring reads assemble paths at runtime — so no mechanical rule reaches it.
+	"scripts/check-mux-launcher-fence.ts": {
+		cls: "behavioral-contract",
+		reason:
+			"executes the shared claude-launcher-fence lib against disposable fs fixtures and source-reads both mux LIVE smoke wiring sites",
+	},
+	"scripts/check-mux-parent-artifact.ts": {
+		cls: "source-topology",
+		reason: "asserts the scrubbed parent-transcript fixture's recorded shape — an artifact contract, no product run",
+	},
+};
+
+/**
+ * A single class name is the file's STRONGEST tier; some gates also ship a weaker
+ * one. Recording that here keeps "real-live" from being read as "never runs without
+ * LIVE=1" — and keeps the reverse, a two-tier gate quietly counted as deterministic,
+ * from passing as honest either. Stale entries throw.
+ */
+const TWO_TIER_NOTES: Record<string, string> = {
+	"scripts/smoke-meta-async-drift.sh":
+		"deterministic default tier (pin/marker/doorbell contract — no model, no network) + LIVE=1 add-on tier that delegates to repro-plugin-idle-wake.sh and spawns one metered `claude -p`. Counted real-live because its strongest tier is a real live turn; `pnpm check` only ever runs the deterministic tier.",
+};
+
+type Style = "imports-product" | "source-text" | "subprocess" | "mixed" | "shell" | "other";
+
+interface Row {
+	file: string;
+	axis: "legacy" | "framework";
+	lines: number;
+	cls: SemanticClass;
+	overridden: boolean;
+	style: Style;
+}
+
+/** A test file is judged together with the ./helpers/ bodies it imports. */
+function effectiveBody(rel: string): string {
+	let body = fs.readFileSync(path.join(REPO_DIR, rel), "utf8");
+	if (rel.startsWith("test/") && rel.endsWith(".test.ts")) {
+		for (const m of body.matchAll(/from\s+["']\.\/(helpers\/[^"']+?)(?:\.ts)?["']/g)) {
+			const helper = path.join(REPO_DIR, "test", `${m[1]}.ts`.replace(/\.ts\.ts$/, ".ts"));
+			if (fs.existsSync(helper)) body += `\n${fs.readFileSync(helper, "utf8")}`;
+		}
+	}
+	return body;
+}
+
+function classify(rel: string, axis: "legacy" | "framework"): Row {
+	const lines = countLines(rel);
+	const isShell = rel.endsWith(".sh");
+	const body = isShell ? fs.readFileSync(path.join(REPO_DIR, rel), "utf8") : effectiveBody(rel);
+	const base = path.basename(rel);
+
+	const style: Style = (() => {
+		if (isShell) return "shell";
+		const axes = [H_IMPORTS.test(body), H_TEXT.test(body), H_PROC.test(body)];
+		const n = axes.filter(Boolean).length;
+		if (n >= 2) return "mixed";
+		if (axes[0]) return "imports-product";
+		if (axes[1]) return "source-text";
+		if (axes[2]) return "subprocess";
+		return "other";
+	})();
+
+	const override = CLASS_OVERRIDES[rel];
+	const cls: SemanticClass | null = override
+		? override.cls
+		: /-live\.(ts|sh)$/.test(base) || H_LIVE.test(codeOnly(body, isShell))
+			? "real-live"
+			: /pack|install/.test(base)
+				? "package-install"
+				: isShell || H_PROC.test(body) || H_NET.test(body)
+					? "hermetic-integration"
+					: H_TEXT.test(body) && !H_IMPORTS.test(body)
+						? "source-topology"
+						: H_IMPORTS.test(body) && (H_TEXT.test(body) || H_FS.test(body))
+							? "behavioral-contract"
+							: H_IMPORTS.test(body)
+								? "pure-unit"
+								: null;
+	if (cls === null) {
+		throw new Error(
+			`unclassified gate: ${rel} — no rule reaches it; extend the rules or add a reasoned CLASS_OVERRIDES entry`,
+		);
+	}
+	return { file: rel, axis, lines, cls, overridden: Boolean(override), style };
+}
+
+// ── buckets ──────────────────────────────────────────────────────────────────
+const legacyGates = legacyFiles.filter((f) => /^scripts\/(check-|smoke-)/.test(f));
+const frameworkGates = frameworkFiles.filter((f) => /^test\/.*\.test\.ts$/.test(f));
+const lib = legacyFiles.filter((f) => f.startsWith("scripts/lib/"));
+const mutantManifests = legacyFiles.filter((f) => f.startsWith("scripts/mutants/") && f.endsWith(".json"));
+const fixtures = legacyFiles.filter((f) => f.startsWith("scripts/fixtures/"));
+const legacyOther = legacyFiles.filter(
+	(f) => !legacyGates.includes(f) && !lib.includes(f) && !mutantManifests.includes(f) && !fixtures.includes(f),
+);
+const frameworkSupport = frameworkFiles.filter((f) => !frameworkGates.includes(f));
+
+const rows: Row[] = [
+	...legacyGates.map((f) => classify(f, "legacy")),
+	...frameworkGates.map((f) => classify(f, "framework")),
+];
+
+function sum(rs: Row[]): number {
+	return rs.reduce((a, r) => a + r.lines, 0);
+}
+function total(files: string[]): number {
+	return files.reduce((a, f) => a + countLines(f), 0);
+}
+
+const head = git(["rev-parse", "--short", "HEAD"]).trim();
+console.log(`inventory-verification-surface — work surface (tracked + untracked-non-ignored) @ HEAD ${head}`);
+console.log(`
+rule predicates (re-derive any number from these):
+  H_IMPORTS  ${H_IMPORTS}
+  H_TEXT     ${H_TEXT}
+  H_PROC     ${H_PROC}
+  H_NET      ${H_NET}
+  H_FS       ${H_FS}
+  H_LIVE     ${H_LIVE}
+H_LIVE is applied to the CODE-ONLY projection (comments and inert literals blanked;
+shell double-quoted expansions kept), so a gate that merely QUOTES "LIVE=1" is not
+real-live. Two-tier gates are listed under the class breakdown.
+semantic classes, first match wins: override → real-live (name -live | H_LIVE on code) →
+  package-install (name pack|install) → hermetic-integration (.sh | H_PROC | H_NET) →
+  source-topology (H_TEXT ∧ ¬H_IMPORTS) → behavioral-contract (H_IMPORTS ∧ (H_TEXT ∨ H_FS)) →
+  pure-unit (H_IMPORTS) → ERROR (unclassified is asserted zero)
+test/*.test.ts is classified together with the ./helpers/* bodies it imports.
+`);
+
+const legacyTotal = total(legacyFiles);
+const frameworkTotal = total(frameworkFiles);
+console.log(`legacy axis (scripts/):            ${legacyFiles.length} files, ${legacyTotal} lines`);
+console.log(
+	`  gates (check-*/smoke-*):         ${legacyGates.length} files, ${sum(rows.filter((r) => r.axis === "legacy"))} lines`,
+);
+console.log(`  scripts/lib/:                    ${lib.length} files, ${total(lib)} lines`);
+console.log(`  scripts/mutants/:                ${mutantManifests.length} manifests`);
+console.log(`  scripts/fixtures/:               ${fixtures.length} files`);
+console.log(`  other:                           ${legacyOther.length} files, ${total(legacyOther)} lines`);
+console.log(`framework axis (test/ + vitest.config.ts): ${frameworkFiles.length} files, ${frameworkTotal} lines`);
+console.log(
+	`  vitest lanes (test/**/*.test.ts):  ${frameworkGates.length} files, ${sum(rows.filter((r) => r.axis === "framework"))} lines`,
+);
+console.log(`  helpers/config:                    ${frameworkSupport.length} files, ${total(frameworkSupport)} lines`);
+console.log(
+	`COMBINED verification total:       ${legacyFiles.length + frameworkFiles.length} files, ${legacyTotal + frameworkTotal} lines`,
+);
+console.log("  (migration moves lines between axes; only a drop in THIS number is subtraction)");
+
+console.log("\nsemantic class breakdown (all gates, both axes):");
+const classes: SemanticClass[] = [
+	"pure-unit",
+	"behavioral-contract",
+	"source-topology",
+	"hermetic-integration",
+	"package-install",
+	"real-live",
+];
+for (const c of classes) {
+	const rs = rows.filter((r) => r.cls === c);
+	console.log(`  ${c.padEnd(21)} ${String(rs.length).padStart(3)} files ${String(sum(rs)).padStart(7)} lines`);
+}
+console.log(`  ${"unclassified".padEnd(21)}   0 files       0 lines (asserted: the classifier throws otherwise)`);
+
+console.log("\ntwo-tier gates (one class name, two execution tiers):");
+for (const [rel, note] of Object.entries(TWO_TIER_NOTES)) {
+	const row = rows.find((r) => r.file === rel);
+	if (!row) throw new Error(`stale TWO_TIER_NOTES entry: ${rel} is not a classified gate — remove or repoint it`);
+	console.log(`  ${rel} [${row.cls}] — ${note}`);
+}
+
+console.log("\nstyle axis (secondary, e405d64-baseline continuity):");
+const styles: Style[] = ["imports-product", "source-text", "subprocess", "mixed", "shell", "other"];
+for (const s of styles) {
+	const rs = rows.filter((r) => r.style === s);
+	console.log(`  ${s.padEnd(21)} ${String(rs.length).padStart(3)} files ${String(sum(rs)).padStart(7)} lines`);
+}
+
+const overridden = rows.filter((r) => r.overridden);
+if (overridden.length > 0) {
+	console.log("\nexplicit overrides in effect (each is a reviewed decision):");
+	for (const r of overridden) console.log(`  ${r.file} → ${r.cls} (${CLASS_OVERRIDES[r.file].reason})`);
+}
+
+// ── mutant inventory ─────────────────────────────────────────────────────────
+interface MutantEntry {
+	subject: string;
+}
+let totalMutants = 0;
+let infraMutants = 0;
+console.log("\nmutant lanes (subject=scripts/* counts as verification-infra):");
+for (const manifest of mutantManifests) {
+	const parsed = JSON.parse(fs.readFileSync(path.join(REPO_DIR, manifest), "utf8")) as {
+		lane: string;
+		mutants: MutantEntry[];
+	};
+	const infra = parsed.mutants.filter((m) => m.subject.startsWith("scripts/")).length;
+	totalMutants += parsed.mutants.length;
+	infraMutants += infra;
+	console.log(
+		`  ${parsed.lane.padEnd(24)} ${String(parsed.mutants.length).padStart(3)} mutants  (${infra} infra-subject)`,
+	);
+}
+console.log(`  ${"TOTAL".padEnd(24)} ${String(totalMutants).padStart(3)} mutants  (${infraMutants} infra-subject)`);
+
+console.log("\nper-gate table (axis, class, style, lines):");
+for (const r of rows) {
+	console.log(
+		`  ${r.axis.padEnd(9)} ${r.cls.padEnd(21)} ${r.style.padEnd(16)} ${String(r.lines).padStart(6)}  ${r.file}${r.overridden ? "  [override]" : ""}`,
+	);
+}

package/scripts/lib/claude-launcher-fence.ts

@@ -0,0 +1,322 @@
+/**
+ * claude-launcher-fence — the shared fail-closed protection for the operator's real `claude`
+ * launcher, owed by BOTH mux LIVE smokes (issue #67).
+ *
+ * The observed incident: a Claude child launched with the operator's real HOME but a fixture
+ * `XDG_DATA_HOME` self-updated INTO the fixture tree and rewrote the real launcher (the
+ * `~/.local/bin/claude` install shim) to point at `<fixture>/claude/versions/<v>`. Fixture
+ * teardown then deleted that tree and left the operator's launcher dangling. This module owns
+ * the three protections the smokes share, so neither carries its own copy:
+ *
+ *   1. PREFLIGHT (`snapshotClaudeLauncher`) — fail-closed. Before any Claude-capable child
+ *      starts, resolve the actual absolute launcher from the exact child PATH, require it and
+ *      its symlink/realpath-resolved target to be present, regular, executable and OUTSIDE the
+ *      fixture cleanup root, and capture enough identity/content evidence (kind, link text,
+ *      resolved path, content hash) to prove "unchanged" later. Any doubt throws — a smoke that
+ *      cannot pin the launcher's identity must not launch the child that could destroy it.
+ *   2. INTEGRITY ORACLE (`verifyClaudeLauncher`) — on success AND on every failure teardown,
+ *      before fixture removal, re-derive the same facts and report every mismatch by name.
+ *   3. CLEANUP GUARD (`launcherReferencesFixture`) — the one question that decides whether
+ *      `rm -rf <fixture>` is destructive: does the launcher, or what it currently resolves to,
+ *      live inside the fixture root? If yes, the smoke must BLOCK its own cleanup loudly and
+ *      leave the tree in place rather than dangle the operator's launcher.
+ *
+ * It also owns the env repair that removes the incident's trigger: `restoreOriginalXdg` gives a
+ * real-HOME Claude cell EXACT operator-env parity on the four XDG roots — each variable restored
+ * to its original value if it was set, and DELETED if it was originally absent. Filling a
+ * canonical default for an absent variable would be a guess about how the runtime reads its
+ * config; parity, not widening, is the contract. That parity covers the four PERSISTENT
+ * CONFIG/DATA/STATE/CACHE roots only: `XDG_RUNTIME_DIR` deliberately remains the smokes' private
+ * fixture runtime surface, so this is not a claim of total operator-env parity.
+ *
+ * This is a scripts-side harness module. It never inspects or alters anything unless the caller
+ * hands it an environment and a fixture root, and it must stay out of shipped production source.
+ */
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/** The four XDG roots a real-HOME Claude cell must see with exact operator parity. */
+export const CLAUDE_CELL_XDG_VARS = ["XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME"] as const;
+
+/** Original presence/value of each XDG root: a string if it was set (even empty), null if absent. */
+export type OriginalXdg = Record<string, string | null>;
+
+/** Capture the four XDG roots BEFORE any fixture redirect touches the environment. */
+export function snapshotOriginalXdg(env: NodeJS.ProcessEnv): OriginalXdg {
+	const out: OriginalXdg = {};
+	for (const name of CLAUDE_CELL_XDG_VARS) out[name] = env[name] ?? null;
+	return out;
+}
+
+/**
+ * Restore EXACT original presence/value of the four XDG roots on a cell env. An originally
+ * absent variable is deleted, never filled with a canonical default — parity, not a guess.
+ */
+export function restoreOriginalXdg(env: NodeJS.ProcessEnv, originals: OriginalXdg): NodeJS.ProcessEnv {
+	for (const name of CLAUDE_CELL_XDG_VARS) {
+		const original = originals[name];
+		if (original === null || original === undefined) delete env[name];
+		else env[name] = original;
+	}
+	return env;
+}
+
+/** Everything the preflight pinned, and the oracle later re-derives. */
+export interface ClaudeLauncherSnapshot {
+	/** Absolute launcher path selected from the exact child PATH. */
+	launcherPath: string;
+	/** What the launcher IS at its own path: a symlink or a regular file. */
+	kind: "symlink" | "file";
+	/** Raw readlink text when the launcher is a symlink, else null. */
+	linkText: string | null;
+	/** Fully realpath-resolved target the launcher executes. */
+	resolvedPath: string;
+	/** sha256 of the resolved target's content — the one axis that catches a same-path, same-link in-place rewrite. */
+	sha256: string;
+	/** Realpath of the fixture cleanup root the launcher must stay outside of. */
+	fixtureRoot: string;
+}
+
+function isInside(parent: string, p: string): boolean {
+	const rel = path.relative(parent, p);
+	return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+function sha256File(file: string): string {
+	return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function isExecutableFile(p: string): boolean {
+	try {
+		if (!fs.statSync(p).isFile()) return false;
+		fs.accessSync(p, fs.constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Resolve `cmd` the way the child's exec will: first PATH entry holding an executable file.
+ * Returns the joined candidate path (not yet symlink-resolved), or null when nothing matches.
+ */
+export function resolveFromPath(cmd: string, env: NodeJS.ProcessEnv): string | null {
+	for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+		if (!dir) continue;
+		const candidate = path.join(dir, cmd);
+		if (isExecutableFile(candidate)) return candidate;
+	}
+	return null;
+}
+
+/**
+ * FAIL-CLOSED PREFLIGHT. Pin the launcher's identity before any Claude-capable child starts,
+ * or throw. Every refusal names itself: a smoke that cannot prove the launcher is a real,
+ * executable, fixture-independent file must not launch the child that could rewrite it.
+ */
+export function snapshotClaudeLauncher(opts: { env: NodeJS.ProcessEnv; fixtureRoot: string }): ClaudeLauncherSnapshot {
+	const fixtureRoot = fs.realpathSync(opts.fixtureRoot);
+	const launcherPath = resolveFromPath("claude", opts.env);
+	if (!launcherPath) {
+		throw new Error(
+			"claude-launcher-fence: fail-closed — no executable `claude` on the exact child PATH, so the launcher's identity cannot be pinned before launch",
+		);
+	}
+	if (!path.isAbsolute(launcherPath)) {
+		throw new Error(
+			`claude-launcher-fence: fail-closed — \`claude\` resolved through a relative PATH entry (${launcherPath}); a cwd-dependent launcher cannot be pinned`,
+		);
+	}
+	if (isInside(fixtureRoot, launcherPath)) {
+		throw new Error(
+			`claude-launcher-fence: fail-closed — the selected launcher ${launcherPath} is INSIDE the fixture cleanup root ${fixtureRoot}`,
+		);
+	}
+	const lst = fs.lstatSync(launcherPath);
+	const kind: ClaudeLauncherSnapshot["kind"] = lst.isSymbolicLink() ? "symlink" : "file";
+	if (kind === "file" && !lst.isFile()) {
+		throw new Error(
+			`claude-launcher-fence: fail-closed — the launcher ${launcherPath} is neither a regular file nor a symlink`,
+		);
+	}
+	const linkText = kind === "symlink" ? fs.readlinkSync(launcherPath) : null;
+	let resolvedPath: string;
+	try {
+		resolvedPath = fs.realpathSync(launcherPath);
+	} catch (err) {
+		throw new Error(
+			`claude-launcher-fence: fail-closed — the launcher ${launcherPath} does not resolve to a real target: ${
+				err instanceof Error ? err.message : String(err)
+			}`,
+		);
+	}
+	if (!isExecutableFile(resolvedPath)) {
+		throw new Error(
+			`claude-launcher-fence: fail-closed — the launcher's resolved target ${resolvedPath} is not a regular executable file`,
+		);
+	}
+	if (isInside(fixtureRoot, resolvedPath)) {
+		throw new Error(
+			`claude-launcher-fence: fail-closed — the launcher's resolved target ${resolvedPath} is INSIDE the fixture cleanup root ${fixtureRoot}`,
+		);
+	}
+	return {
+		launcherPath,
+		kind,
+		linkText,
+		resolvedPath,
+		sha256: sha256File(resolvedPath),
+		fixtureRoot,
+	};
+}
+
+/**
+ * INTEGRITY ORACLE. Re-derive every pinned fact and return one problem string per mismatch —
+ * empty means the launcher, its link, its resolved target and that target's content are all
+ * exactly as the preflight saw them, and the target is still a regular executable. Runs on the
+ * success path AND on every failure teardown, BEFORE fixture removal.
+ */
+export function verifyClaudeLauncher(snapshot: ClaudeLauncherSnapshot): string[] {
+	const problems: string[] = [];
+	let lst: fs.Stats;
+	try {
+		lst = fs.lstatSync(snapshot.launcherPath);
+	} catch {
+		problems.push(`the launcher ${snapshot.launcherPath} no longer exists`);
+		return problems;
+	}
+	const kindNow: ClaudeLauncherSnapshot["kind"] = lst.isSymbolicLink() ? "symlink" : "file";
+	if (kindNow !== snapshot.kind) {
+		problems.push(`the launcher changed kind: was ${snapshot.kind}, is now ${kindNow}`);
+	}
+	if (kindNow === "symlink") {
+		// A raced-away link is an INTEGRITY PROBLEM, never an exception that could mask the run
+		// error this oracle runs alongside.
+		let linkNow: string | null = null;
+		try {
+			linkNow = fs.readlinkSync(snapshot.launcherPath);
+		} catch (err) {
+			problems.push(
+				`the launcher's link text could not be re-read: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+		if (linkNow !== null && linkNow !== snapshot.linkText) {
+			problems.push(`the launcher's link text changed: was ${snapshot.linkText ?? "(none)"}, is now ${linkNow}`);
+		}
+	}
+	let resolvedNow: string | null = null;
+	try {
+		resolvedNow = fs.realpathSync(snapshot.launcherPath);
+	} catch {
+		problems.push(`the launcher ${snapshot.launcherPath} no longer resolves to a real target`);
+	}
+	if (resolvedNow !== null) {
+		if (resolvedNow !== snapshot.resolvedPath) {
+			problems.push(`the launcher's resolved target moved: was ${snapshot.resolvedPath}, is now ${resolvedNow}`);
+		}
+		if (!isExecutableFile(resolvedNow)) {
+			problems.push(`the launcher's resolved target ${resolvedNow} is no longer a regular executable file`);
+		} else {
+			try {
+				if (sha256File(resolvedNow) !== snapshot.sha256) {
+					problems.push(`the launcher's resolved target ${resolvedNow} changed content (sha256 mismatch)`);
+				}
+			} catch (err) {
+				problems.push(
+					`the launcher's resolved target ${resolvedNow} could not be hashed: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+		if (isInside(snapshot.fixtureRoot, resolvedNow)) {
+			problems.push(
+				`the launcher's resolved target ${resolvedNow} now lies INSIDE the fixture cleanup root ${snapshot.fixtureRoot}`,
+			);
+		}
+	}
+	return problems;
+}
+
+/** What the cleanup guard could prove, stated honestly: a KNOWN fixture reference and an
+ * UNPROVABLE state both block removal, but each is named as itself in `problems`. */
+export interface LauncherCleanupVerdict {
+	/** True only when removal is PROVEN safe: the launcher demonstrably does not reference the fixture. */
+	safeToRemove: boolean;
+	/** Named reasons removal is blocked — a fixture reference, or a syscall that left safety unproven. */
+	problems: string[];
+}
+
+/**
+ * CLEANUP GUARD. Decides whether `rm -rf <fixture>` is destructive: does the launcher, its
+ * current link target, or its current resolved path lie inside the fixture cleanup root — the
+ * exact state in which removal would dangle the operator's launcher? FAIL-CLOSED on uncertainty:
+ * a readlink/lstat/realpath error blocks removal with a "not proven safe" problem rather than
+ * being laundered into either a false "references fixture" or a false all-clear. A launcher that
+ * is missing ENTIRELY is safe to clean around — nothing is left for removal to sever, and the
+ * integrity oracle reports that damage by name.
+ */
+export function assessLauncherCleanup(snapshot: ClaudeLauncherSnapshot): LauncherCleanupVerdict {
+	if (isInside(snapshot.fixtureRoot, snapshot.launcherPath)) {
+		return {
+			safeToRemove: false,
+			problems: [`the launcher ${snapshot.launcherPath} itself lies inside the fixture cleanup root`],
+		};
+	}
+	let lst: fs.Stats;
+	try {
+		lst = fs.lstatSync(snapshot.launcherPath);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return { safeToRemove: true, problems: [] };
+		return {
+			safeToRemove: false,
+			problems: [
+				`the launcher ${snapshot.launcherPath} could not be inspected (${
+					err instanceof Error ? err.message : String(err)
+				}) — removal is not proven safe`,
+			],
+		};
+	}
+	if (lst.isSymbolicLink()) {
+		let hop: string;
+		try {
+			hop = path.resolve(path.dirname(snapshot.launcherPath), fs.readlinkSync(snapshot.launcherPath));
+		} catch (err) {
+			return {
+				safeToRemove: false,
+				problems: [
+					`the launcher's link text could not be read (${
+						err instanceof Error ? err.message : String(err)
+					}) — removal is not proven safe`,
+				],
+			};
+		}
+		if (isInside(snapshot.fixtureRoot, hop)) {
+			return {
+				safeToRemove: false,
+				problems: [`the launcher's link target ${hop} lies inside the fixture cleanup root`],
+			};
+		}
+	}
+	try {
+		const resolved = fs.realpathSync(snapshot.launcherPath);
+		if (isInside(snapshot.fixtureRoot, resolved)) {
+			return {
+				safeToRemove: false,
+				problems: [`the launcher's resolved target ${resolved} lies inside the fixture cleanup root`],
+			};
+		}
+	} catch (err) {
+		// A dangling or unresolvable chain: the first hop above was proven outside the fixture, but
+		// the FULL chain was not — fail closed rather than guess.
+		return {
+			safeToRemove: false,
+			problems: [
+				`the launcher ${snapshot.launcherPath} could not be fully resolved (${
+					err instanceof Error ? err.message : String(err)
+				}) — removal is not proven safe`,
+			],
+		};
+	}
+	return { safeToRemove: true, problems: [] };
+}