@junghanacs/entwurf 0.41.2 → 0.50.0

package/scripts/build-bridge.sh

@@ -19,6 +19,16 @@ TSC="$REPO_DIR/node_modules/.bin/tsc"
 [ -x "$TSC" ] || TSC=tsc
 "$TSC" -p "$REPO_DIR/mcp/entwurf-bridge/tsconfig.build.json"
 
+# One authored product-guidance source (#154). The fixed module-relative reader resolves
+# ../../ENTWURF.json from dist/pi-extensions/lib/, so its deterministic exact copy belongs at
+# the DIST ROOT, not beside the capability registry. This is transport, never another source.
+GUIDANCE_SOURCE="$REPO_DIR/ENTWURF.json"
+if [ ! -f "$GUIDANCE_SOURCE" ] || [ -L "$GUIDANCE_SOURCE" ]; then
+  echo "build-bridge: $GUIDANCE_SOURCE is missing or not a regular file" >&2
+  exit 1
+fi
+cp "$GUIDANCE_SOURCE" "$REPO_DIR/mcp/entwurf-bridge/dist/ENTWURF.json"
+
 # The capability registry must TRAVEL WITH the bundle.
 #
 # `metaCapabilitiesFilePath()` computes its path from the module's own location.

package/scripts/check-capability-bundle-reach.ts

@@ -32,6 +32,8 @@
  *         the installer copies, and the hook staged with only that closure runs.
  *   - D (#147 G3): the compiled Claude Code retire adapter resolves its helper beside itself,
  *         byte-identical to pi-extensions/lib/cc-retire-pidfd.py.
+ *   - F (#154): the fixed guidance carrier has the canonical Root bytes, and its emitted
+ *         reader exports that Root's version/tools (plain JSON expected data, not a source reader).
  *
  * Deterministic: filesystem, import, and ONE shipped-hook child process (C2) that writes a
  * record into its own private store under a private HOME and XDG roots. No backend, vendor
@@ -48,6 +50,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+import { FRESH_CUT_PRESCRIPTION } from "../pi-extensions/lib/meta-session.ts";
 import { hookImportClosure, installerCopiedLibFiles, stageMetaHookBundle } from "./lib/meta-hook-bundle.ts";
 import { reclaimOnExit } from "./lib/reclaim-on-exit.ts";
 
@@ -260,4 +264,86 @@ for (const copy of copies) {
 	);
 }
 
+// F — one guidance carrier/current-reader contract, rooted in canonical authored bytes (#154).
+// Presence/type are preconditions. The reader is NOT first loaded here: since #154 C1-C the compiled
+// retire adapter that D imports reaches it through entwurf-v2-visible-resume, so the module is
+// already evaluated and cached. A carrier that still parses and validates (a byte divergence) loaded
+// fine there and fails the intended F1 byte assertion; a carrier the reader refuses already threw at
+// D's import, unlabelled. The import below is skipped on divergence so F1 stays the reported cause.
+{
+	const carrier = path.join(BRIDGE_DIST, "ENTWURF.json");
+	const reader = path.join(BRIDGE_DIST, "pi-extensions", "lib", "agent-guidance.js");
+	for (const file of [carrier, reader]) {
+		const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+		ok(
+			`F0: the compiled guidance file is regular and non-symlink: ${rel(file)}`,
+			stat !== undefined && stat.isFile() && !stat.isSymbolicLink(),
+		);
+	}
+	const rootBytes = fs.readFileSync(path.join(REPO, "ENTWURF.json"));
+	const root = JSON.parse(rootBytes.toString("utf8"));
+	const sameBytes = fs.readFileSync(carrier).equals(rootBytes);
+	const loaded = sameBytes ? await import(pathToFileURL(reader).href) : undefined;
+	ok(
+		"F1: the fixed guidance carrier has canonical Root bytes and its reader exports the current version/tools [QK:BUNDLE-REACH-GUIDANCE-CARRIER]",
+		sameBytes &&
+			isDeepStrictEqual(loaded?.ENTWURF_GUIDANCE_VERSION, {
+				schemaVersion: root.schemaVersion,
+				revision: root.revision,
+			}) &&
+			isDeepStrictEqual(loaded?.ENTWURF_TOOL_GUIDANCE, root.tools),
+	);
+	// F2 — the second authored family reaches the compiled reader too. Separate from F1 so a reader
+	// that mis-exports only the hints fails here while the carrier and tool payload stay green.
+	ok(
+		"F2: the compiled reader exports the canonical Root static reject hints [QK:BUNDLE-REACH-REJECT-HINTS]",
+		sameBytes && isDeepStrictEqual(loaded?.ENTWURF_REJECT_HINTS, root.rejectHints),
+	);
+	// F3 — the third family (#154 C1-C), separate for the same reason as F2.
+	ok(
+		"F3: the compiled reader exports the canonical Root visible-resume reject hints [QK:BUNDLE-REACH-RESUME-REJECT-HINTS]",
+		sameBytes && isDeepStrictEqual(loaded?.ENTWURF_RESUME_REJECT_HINTS, root.resumeRejectHints),
+	);
+	// F4 — the two tmux launch-stage families (#154 C1-D), one assertion because they enter together;
+	// this proves the compiled reader's exports, not the compiled mux renderers that read them.
+	ok(
+		"F4: the compiled reader exports the canonical Root fresh and resume launch-stage reject hints [QK:BUNDLE-REACH-LAUNCH-REJECT-HINTS]",
+		sameBytes &&
+			isDeepStrictEqual(loaded?.ENTWURF_FRESH_LAUNCH_REJECT_HINTS, root.freshLaunchRejectHints) &&
+			isDeepStrictEqual(loaded?.ENTWURF_RESUME_LAUNCH_REJECT_HINTS, root.resumeLaunchRejectHints),
+	);
+	// F5 — the delivery-result clauses (#154 E1a), separate for the same reason as F2; this proves the
+	// compiled reader's export, not the compiled receipt renderers that read it.
+	ok(
+		"F5: the compiled reader exports the canonical Root delivery-result clauses [QK:BUNDLE-REACH-DELIVERY-RESULT-CLAUSES]",
+		sameBytes && isDeepStrictEqual(loaded?.ENTWURF_DELIVERY_RESULT_CLAUSES, root.deliveryResultClauses),
+	);
+	// F6 — the slotted reject-hint segments (#154 E1b), separate for the same reason as F2; this proves the
+	// compiled reader's export, not the compiled surface that composes them with the code-owned slot.
+	ok(
+		"F6: the compiled reader exports the canonical Root slotted reject-hint segments [QK:BUNDLE-REACH-SLOTTED-REJECT-HINTS]",
+		sameBytes && isDeepStrictEqual(loaded?.ENTWURF_SLOTTED_REJECT_HINTS, root.slottedRejectHints),
+	);
+	// F7 — the first COMPILED CONSUMER proof (#154 E1b): the compiled surface, not only the reader, renders
+	// the record-less-socket hint from the Root segments around the compiled owner's fix command, and that
+	// command is the source owner's value (an emptied or drifted slot cannot pass by composing with itself).
+	// Imported only when the carrier matches, for the same reason as the reader import above.
+	const surface = sameBytes
+		? await import(pathToFileURL(path.join(BRIDGE_DIST, "pi-extensions", "lib", "entwurf-v2-surface.js")).href)
+		: undefined;
+	const metaSession = sameBytes
+		? await import(pathToFileURL(path.join(BRIDGE_DIST, "pi-extensions", "lib", "meta-session.js")).href)
+		: undefined;
+	const rls = root.slottedRejectHints["record-less-socket"];
+	ok(
+		"F7: the compiled surface renders the record-less-socket hint as the Root text around the compiled owner's fix command, which equals the source owner's [QK:BUNDLE-REACH-RECORD-LESS-SOCKET-CONSUMER]",
+		sameBytes &&
+			typeof metaSession?.FRESH_CUT_PRESCRIPTION === "string" &&
+			metaSession.FRESH_CUT_PRESCRIPTION.length > 0 &&
+			metaSession.FRESH_CUT_PRESCRIPTION === FRESH_CUT_PRESCRIPTION &&
+			surface?.actionableRejectHint("record-less-socket") ===
+				`${rls.beforeFreshCutPrescription}${FRESH_CUT_PRESCRIPTION}${rls.afterFreshCutPrescription}`,
+	);
+}
+
 console.log(`\ncheck-capability-bundle-reach: PASS (${passed} assertions)`);

package/scripts/check-claude-launch.ts

@@ -0,0 +1,341 @@
+/**
+ * check-claude-launch — deterministic gate for the Claude Code launch (`entwurf claude`, #157 stage 4).
+ * Hermetic: no real Claude Code, no network, no model turn, no write outside its own temp root. Linux
+ * only: the fake vendor reads its own environment from /proc/$$/environ (it runs in the Linux check job).
+ *
+ * SAME ORACLE AS check-pi-launch and check-copilot-launch: the subject is a process REPLACEMENT, so
+ * the truth is a FAKE VENDOR — a real executable named `claude` on a sandbox PATH that reports the
+ * argv, cwd, environment and pid it was actually handed. Nothing below is asserted by reading the
+ * launcher's source, and the launcher is driven through its PUBLIC address (`run.sh claude`),
+ * because the dispatcher's own argv handling — the help preflight included — is part of the contract.
+ *
+ * WHAT THE LAUNCH PROMISES, AND WHAT IT DOES NOT. It is a spelling: the vendor's argv, cwd, exit
+ * status and signal are Claude Code's own, and `--help` is Claude Code's help, not an Entwurf page.
+ * It adds nothing to the argv. Its only environment changes are the recursion sentinel and the
+ * REMOVAL of an inherited PI_SESSION_ID/PI_AGENT_ID pair, which is another citizen's identity. It
+ * does not promise a garden citizen: that comes from the meta-bridge plugin and hooks `setup`
+ * installed, which this launch neither checks nor supplies, so nothing here models them.
+ *
+ * WHY TWO RECURSION FENCES WHEN PI HAS ONE. pi's single fence rests on the flag it injects: a PATH
+ * `pi` symlinked to run.sh re-enters as the unknown verb `--entwurf-control`. This launch injects
+ * nothing, so the same symlink would re-enter with the operator's argv as the VERB. The resolved-path
+ * fence refuses that, and the cell measuring it hands the loop an EMPTY argv on purpose: with the
+ * fence mutated away, the re-entry prints the root page and exits 0 instead of running any verb.
+ *
+ * TWO CELLS CARRY NO MUTANT, and the reason is measured coupling rather than a gap. run.sh is
+ * `set -euo pipefail`, so dropping `exec` still propagates a non-zero vendor status (set -e exits
+ * with it) and turns a vendor death by signal into a status of 128+n. The mutation that breaks the
+ * exit or signal claim is therefore the one that breaks the pid claim, and the pid cell is asserted
+ * first so that mutant lands on exactly one QK. The exit and signal cells stand on their assertions.
+ */
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	symlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const RUN_SH = path.join(REPO, "run.sh");
+const SENTINEL = "ENTWURF_CLAUDE_LAUNCH_ACTIVE";
+/** The variables bash itself maintains across a script and an exec — not the launcher's choice. */
+const BASH_OWNED = new Set(["SHLVL", "_", "PWD", "OLDPWD"]);
+
+let passed = 0;
+function ok(label: string, cond: boolean, detail = ""): void {
+	assert.ok(cond, detail ? `${label}\n${detail}` : label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const root = mkdtempSync(path.join(tmpdir(), "entwurf-claude-launch."));
+try {
+	const bin = path.join(root, "bin");
+	const work = path.join(root, "work");
+	mkdirSync(bin, { recursive: true });
+	mkdirSync(work, { recursive: true });
+	const envDump = path.join(root, "vendor.environ");
+
+	// The fake vendor, installed under the REAL name `claude`. It reports what exec handed it: its
+	// own initial environment is read from the kernel (/proc/$$/environ), not from its shell's view,
+	// so bash's own bookkeeping inside the fake is not mistaken for the launcher's.
+	const vendor = path.join(bin, "claude");
+	writeFileSync(
+		vendor,
+		`#!/usr/bin/env bash
+echo "PID=$$"
+echo "CWD=$(pwd -P)"
+echo "SENTINEL=[\${${SENTINEL}-<unset>}]"
+cat "/proc/$$/environ" >"$FAKE_CLAUDE_ENV_OUT"
+for a in "$@"; do printf 'ARG<%s>\\n' "$a"; done
+if [ -n "\${FAKE_CLAUDE_SIGNAL:-}" ]; then kill -s "$FAKE_CLAUDE_SIGNAL" "$$"; sleep 5; fi
+exit "\${FAKE_CLAUDE_EXIT:-0}"
+`,
+	);
+	chmodSync(vendor, 0o755);
+
+	// TOTAL sandbox, as the sibling launch gates: the launcher writes nothing, but it EXECS a vendor.
+	const sandboxEnv = {
+		HOME: path.join(root, "home"),
+		XDG_DATA_HOME: path.join(root, "xdg", "data"),
+		XDG_CONFIG_HOME: path.join(root, "xdg", "config"),
+		XDG_STATE_HOME: path.join(root, "xdg", "state"),
+		XDG_CACHE_HOME: path.join(root, "xdg", "cache"),
+		XDG_RUNTIME_DIR: path.join(root, "xdg", "runtime"),
+		PI_CODING_AGENT_DIR: path.join(root, "pi-agent"),
+		CLAUDE_CONFIG_DIR: path.join(root, "claude-config"),
+	};
+	for (const d of Object.values(sandboxEnv)) mkdirSync(d, { recursive: true });
+
+	// A PATH with no `claude` anywhere on it: every real entry that holds one is dropped, rather than
+	// emptying PATH (the launcher still needs bash, dirname and readlink).
+	const pathWithoutVendor = (process.env.PATH ?? "")
+		.split(":")
+		.filter((d) => d !== "" && !existsSync(path.join(d, "claude")))
+		.join(":");
+
+	/**
+	 * Every bash this gate starts gets a NON-SOCKET stdin. Node's default stdin is a socketpair, and
+	 * bash reads `-c` with a socket on stdin as a remote shell and sources the system bashrc — measured
+	 * here on NixOS, where that re-runs set-environment and resets PATH, dropping the sandbox bin
+	 * (S4CLI-F01-BASHC-REMOTE-SHELL-R1). The sibling gates never see it because they pass the
+	 * operator's whole environment; this one builds its environment from scratch to compare it.
+	 */
+	const STDIO: ["ignore", "pipe", "pipe"] = ["ignore", "pipe", "pipe"];
+
+	/** The caller's whole environment, built explicitly so the vendor's can be compared to it. */
+	function callerEnv(pathValue: string, extra: Record<string, string> = {}): Record<string, string> {
+		return { ...sandboxEnv, PATH: pathValue, LANG: "C.UTF-8", FAKE_CLAUDE_ENV_OUT: envDump, ...extra };
+	}
+
+	interface Run {
+		status: number | null;
+		signal: NodeJS.Signals | null;
+		out: string;
+		args: string[];
+		sentinel: string;
+		pid: string;
+		cwd: string;
+		env: Map<string, string> | null;
+	}
+	function launch(args: string[], env: Record<string, string>, cwd = work): Run {
+		rmSync(envDump, { force: true });
+		const r = spawnSync("bash", [RUN_SH, "claude", ...args], {
+			cwd,
+			encoding: "utf8",
+			env,
+			timeout: 30_000,
+			stdio: STDIO,
+		});
+		const out = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+		const argv: string[] = [];
+		for (const line of out.split("\n")) {
+			const m = /^ARG<([\s\S]*)>$/.exec(line);
+			if (m) argv.push(m[1] as string);
+		}
+		let vendorEnv: Map<string, string> | null = null;
+		if (existsSync(envDump)) {
+			vendorEnv = new Map();
+			for (const entry of readFileSync(envDump, "utf8").split("\0")) {
+				if (entry === "") continue;
+				const eq = entry.indexOf("=");
+				vendorEnv.set(entry.slice(0, eq), entry.slice(eq + 1));
+			}
+		}
+		return {
+			status: r.status,
+			signal: r.signal,
+			out,
+			args: argv,
+			sentinel: /^SENTINEL=\[(.*)\]$/m.exec(out)?.[1] ?? "<no-launch>",
+			pid: /^PID=(.*)$/m.exec(out)?.[1] ?? "",
+			cwd: /^CWD=(.*)$/m.exec(out)?.[1] ?? "",
+			env: vendorEnv,
+		};
+	}
+	const withVendor = `${bin}:${pathWithoutVendor}`;
+
+	// ── 1. the dispatcher verb must not reach the vendor ────────────────────────
+	{
+		const r = launch(["--model", "x"], callerEnv(withVendor));
+		ok(
+			"[QK:CLAUDELAUNCH-VERB-DROPPED] the dispatcher verb never reaches the vendor — without the shift, `claude` arrives as a prompt argument",
+			r.status === 0 && r.pid !== "" && !r.args.includes("claude"),
+			`status=${r.status} argv=${JSON.stringify(r.args)}\n${r.out}`,
+		);
+	}
+
+	// ── 2. operator argv crosses byte-identical, and nothing is added to it ─────
+	{
+		const operator = ["--model", "a b", "", "-", "--", "한글 인자", "  spaced  ", "--help"];
+		const r = launch(operator, callerEnv(withVendor));
+		ok(
+			"[QK:CLAUDELAUNCH-ARGV-UNTOUCHED] the vendor's argv IS the operator's, element for element — empty strings, spaces, a bare dash, the terminator, non-ASCII and a trailing --help — with nothing injected",
+			r.status === 0 && JSON.stringify(r.args) === JSON.stringify(operator),
+			`expected: ${JSON.stringify(operator)}\nactual:   ${JSON.stringify(r.args)}`,
+		);
+	}
+
+	// ── 3. the vendor's own help, never an Entwurf page in its place ───────────
+	{
+		const bad = (["--help", "-h"] as const).flatMap((flag) => {
+			const r = launch([flag], callerEnv(withVendor));
+			return r.status === 0 && r.pid !== "" && JSON.stringify(r.args) === JSON.stringify([flag])
+				? []
+				: [`${flag}: status=${r.status} argv=${JSON.stringify(r.args)} out=${JSON.stringify(r.out.slice(0, 160))}`];
+		});
+		ok(
+			"[QK:CLAUDELAUNCH-VENDOR-HELP] `entwurf claude --help` and `-h` reach Claude Code itself — the help preflight lets this verb through instead of answering with the command's description",
+			bad.length === 0,
+			bad.join("\n"),
+		);
+	}
+
+	// ── 4. the caller's directory is the vendor's ───────────────────────────────
+	{
+		const r = launch([], callerEnv(withVendor));
+		ok(
+			"[QK:CLAUDELAUNCH-CWD-KEPT] the vendor starts in the caller's directory, not the package's — Claude Code keys its project and session to that directory",
+			r.status === 0 && r.cwd === realpathSync(work),
+			`expected=${realpathSync(work)} actual=${r.cwd}`,
+		);
+	}
+
+	// ── 5–7. the environment: a sentinel added, a foreign identity removed, nothing else ──
+	{
+		const caller = callerEnv(withVendor, { PI_SESSION_ID: "foreign-garden", PI_AGENT_ID: "pi-agent-fixture" });
+		const r = launch([], caller);
+		ok(
+			"[QK:CLAUDELAUNCH-SENTINEL-EXPORTED] the sentinel is EXPORTED, so a PATH `claude` that shells back to `entwurf claude` sees it on re-entry",
+			r.sentinel === "1",
+			`sentinel=${r.sentinel}`,
+		);
+		ok(
+			"[QK:CLAUDELAUNCH-CARRIERS-SCRUBBED] an inherited PI_SESSION_ID/PI_AGENT_ID pair is another citizen's identity and BOTH are gone from the vendor's environment — absent, not emptied",
+			r.env !== null && !r.env.has("PI_SESSION_ID") && !r.env.has("PI_AGENT_ID"),
+			`vendor env keys: ${JSON.stringify(r.env === null ? null : [...r.env.keys()].filter((k) => k.startsWith("PI_")))}`,
+		);
+		const expected = new Map(Object.entries(caller));
+		expected.delete("PI_SESSION_ID");
+		expected.delete("PI_AGENT_ID");
+		expected.set(SENTINEL, "1");
+		const diff: string[] = [];
+		const actual = r.env ?? new Map<string, string>();
+		for (const [k, v] of expected)
+			if (actual.get(k) !== v) diff.push(`expected ${k}=${JSON.stringify(v)}, got ${JSON.stringify(actual.get(k))}`);
+		for (const [k, v] of actual)
+			if (!expected.has(k) && !BASH_OWNED.has(k)) diff.push(`added ${k}=${JSON.stringify(v)}`);
+		ok(
+			`[QK:CLAUDELAUNCH-ENV-EXACT] beyond those two changes the vendor's environment IS the caller's (${expected.size} variables; ${[...BASH_OWNED].join(", ")} are bash's own) — no auth, model, permission or settings variable is decided here`,
+			r.env !== null && diff.length === 0,
+			diff.join("\n"),
+		);
+	}
+
+	// ── 8. the vendor's exit status is this command's exit status (no mutant: see header) ──
+	{
+		const r = launch([], callerEnv(withVendor, { FAKE_CLAUDE_EXIT: "7" }));
+		ok(
+			"[QK:CLAUDELAUNCH-EXIT-PASSTHROUGH] the vendor's exit status is the launch's exit status",
+			r.status === 7,
+			`status=${r.status}`,
+		);
+	}
+
+	// ── 9. exec, not fork: the pid survives ─────────────────────────────────────
+	{
+		const r = spawnSync("bash", ["-c", `echo "SHELL_PID=$$"; exec bash "${RUN_SH}" claude`], {
+			cwd: work,
+			encoding: "utf8",
+			env: callerEnv(withVendor),
+			timeout: 30_000,
+			stdio: STDIO,
+		});
+		const shellPid = /^SHELL_PID=(\d+)$/m.exec(r.stdout ?? "")?.[1];
+		const vendorPid = /^PID=(\d+)$/m.exec(r.stdout ?? "")?.[1];
+		ok(
+			"[QK:CLAUDELAUNCH-EXEC-KEEPS-PID] the vendor REPLACES this process — a fork would leave run.sh as a parent that owns nothing, between Claude Code and the terminal",
+			Boolean(shellPid) && shellPid === vendorPid,
+			`shell=${shellPid} vendor=${vendorPid}`,
+		);
+	}
+
+	// ── 10. a vendor death by signal is the caller's to see (no mutant: see header) ──
+	{
+		const r = launch([], callerEnv(withVendor, { FAKE_CLAUDE_SIGNAL: "TERM" }));
+		ok(
+			"[QK:CLAUDELAUNCH-SIGNAL-PASSTHROUGH] a vendor killed by a signal is reported as that signal, not as a shell's 128+n status",
+			r.status === null && r.signal === "SIGTERM",
+			`status=${r.status} signal=${r.signal}`,
+		);
+	}
+
+	// ── 11. an absent vendor is a NAMED refusal, never a quiet success ──────────
+	{
+		const r = launch([], callerEnv(pathWithoutVendor));
+		ok(
+			"[QK:CLAUDELAUNCH-VENDOR-ABSENT] with no `claude` on PATH the launch refuses by name and non-zero, and runs nothing",
+			r.status === 1 && r.out.includes("no 'claude' executable found on PATH") && r.pid === "",
+			`status=${r.status}\n${r.out}`,
+		);
+	}
+
+	// ── 12. a PATH hit that is not a regular file is refused before exec ────────
+	{
+		const fifoBin = path.join(root, "fifobin");
+		mkdirSync(fifoBin, { recursive: true });
+		const made = spawnSync("mkfifo", [path.join(fifoBin, "claude")], { encoding: "utf8" });
+		assert.equal(made.status, 0, `mkfifo failed: ${made.stderr}`);
+		chmodSync(path.join(fifoBin, "claude"), 0o755);
+		const r = launch([], callerEnv(`${fifoBin}:${pathWithoutVendor}`));
+		ok(
+			"[QK:CLAUDELAUNCH-NOT-REGULAR] an executable PATH `claude` that is not a regular file (a FIFO) is refused by name, not handed to exec",
+			r.status === 1 && r.out.includes("is not an executable regular file") && r.pid === "",
+			`status=${r.status}\n${r.out}`,
+		);
+	}
+
+	// ── 13. the sentinel fence ──────────────────────────────────────────────────
+	{
+		const r = launch([], callerEnv(withVendor, { [SENTINEL]: "1" }));
+		ok(
+			"[QK:CLAUDELAUNCH-RECURSION-FENCE] a re-entered launch refuses by name instead of spinning behind a hung terminal",
+			r.status === 1 && r.out.includes("recursive managed launch detected") && r.pid === "",
+			`status=${r.status}\n${r.out}`,
+		);
+	}
+
+	// ── 14. the resolved-path fence: a PATH `claude` that IS run.sh ─────────────
+	{
+		// Two hops, the first relative, so the walk itself is exercised: loop/claude -> ../hop/claude
+		// -> run.sh. The argv is EMPTY on purpose (see header): without this fence the re-entry would
+		// print the root page and exit 0, never run a verb.
+		const loopBin = path.join(root, "loop");
+		const hop = path.join(root, "hop");
+		mkdirSync(loopBin, { recursive: true });
+		mkdirSync(hop, { recursive: true });
+		symlinkSync(RUN_SH, path.join(hop, "claude"));
+		symlinkSync(path.join("..", "hop", "claude"), path.join(loopBin, "claude"));
+		const r = launch([], callerEnv(`${loopBin}:${pathWithoutVendor}`));
+		ok(
+			"[QK:CLAUDELAUNCH-SELF-EXEC-FENCE] a PATH `claude` that resolves through symlinks to this run.sh is refused by name — with nothing injected, re-entry would make the operator's argv an entwurf verb",
+			r.status === 1 && r.out.includes(`resolves to entwurf's own '${realpathSync(RUN_SH)}'`) && r.pid === "",
+			`status=${r.status}\n${r.out.slice(0, 400)}`,
+		);
+	}
+
+	console.log(`\ncheck-claude-launch: ${passed} checks passed`);
+} finally {
+	rmSync(root, { recursive: true, force: true });
+}

package/scripts/check-entwurf-self-address.ts

@@ -253,9 +253,9 @@ function functionBody(name: string): string {
 
 /** Extract a `server.tool("NAME", ...)` call region by brace-counting from its open paren. */
 function toolRegion(name: string): string {
-	const sig = `server.tool(\n\t"${name}"`;
-	const at = src.indexOf(sig);
-	assert.ok(at >= 0, `server.tool("${name}") present`);
+	const matches = [...src.matchAll(/server\.tool\(\s*"entwurf_self"\s*,/g)];
+	assert.equal(matches.length, 1, `server.tool("${name}") present exactly once`);
+	const at = matches[0].index;
 	const open = src.indexOf("(", at);
 	let depth = 0;
 	for (let i = open; i < src.length; i++) {