@junghanacs/entwurf 0.35.1 → 0.36.1

package/scripts/check-codex-native-push.ts

@@ -181,18 +181,219 @@ assert.equal(
 	"[QK:CODEX-NATIVE-FIXED-SOCKET] CODEX_HOME owns the vendor default socket root",
 );
 
-const temp = fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-codex-native-"));
+// ── the control endpoint: a plain socket, or Codex's EXACT rendezvous alias (#141) ──────────
+// From Codex 0.162.1 the advertised path is a symlink to a 0600 socket the vendor binds under
+// `realpath(/tmp)/codex-daemon-<euid>/`, named by the sha256 hex of the canonical advertised
+// parent + "/" + basename (`[source]` rust-v0.162.1 `app-server-transport/src/transport/
+// unix_socket.rs:290-304`, `uds/src/daemon_directory.rs:13-38`). The expected target below is
+// derived HERE from that upstream rule, not read back from the product, and every cell builds
+// its own sandbox socket directory: `daemonRoot`/`euid` point the product at it, so the real
+// `/tmp/codex-daemon-<euid>` is never touched. Each refusal cell keeps every OTHER hop valid,
+// so it fails on its own rule and not on a neighbour's. A real other-uid owner needs root and
+// stays unmeasured; so does macOS, where `/tmp` canonicalizes to `/private/tmp`.
+//
+// The root and the socket directory names are SHORT on purpose: a bound socket path must fit
+// sun_path (108 bytes on Linux), and a 64-hex name under a long sandbox root does not — listen
+// fails with EINVAL. That limit is why the vendor keeps its own root at `/tmp/codex-daemon-<euid>`.
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-cnp-"));
+const euid = process.geteuid?.() ?? -1;
+const sandboxServers: net.Server[] = [];
+// A tree whose canonical path is longer than PATH_MAX can only be removed through the short
+// symlinked path that reaches it, so it is removed first, before the root.
+const overlongTrees: string[] = [];
 try {
 	const missing = checkCodexSocketFile(path.join(temp, "missing.sock"));
-	assert.deepEqual(missing.ok ? null : missing.status, "dead", "missing socket is a dead app-server");
+	assert.deepEqual(
+		missing.ok ? null : [missing.status, missing.status === "dead" ? missing.layout : null],
+		["dead", "absent"],
+		"missing socket is a dead app-server, and says it is the absent layout",
+	);
 	const regular = path.join(temp, "regular");
 	fs.writeFileSync(regular, "not a socket");
 	const wrongType = checkCodexSocketFile(regular);
 	assert.deepEqual(wrongType.ok ? null : wrongType.status, "indeterminate", "wrong path type never reads dead");
-	const link = path.join(temp, "link");
-	fs.symlinkSync(regular, link);
-	assert.match(JSON.stringify(checkCodexSocketFile(link)), /symlink/, "symlinked socket is refused by name");
+
+	const listen = async (socketPath: string, mode: number): Promise<void> => {
+		const server = net.createServer();
+		sandboxServers.push(server);
+		await new Promise<void>((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(socketPath, () => resolve());
+		});
+		fs.chmodSync(socketPath, mode);
+	};
+	const layout = (name: string): { caseRoot: string; advertised: string; daemonRoot: string; expected: string } => {
+		const caseRoot = path.join(temp, name);
+		const parent = path.join(caseRoot, "home", "app-server-control");
+		fs.mkdirSync(parent, { recursive: true });
+		const daemonRoot = path.join(caseRoot, "d");
+		fs.mkdirSync(daemonRoot);
+		fs.chmodSync(daemonRoot, 0o700);
+		const hash = crypto
+			.createHash("sha256")
+			.update(`${fs.realpathSync(parent)}/app-server-control.sock`)
+			.digest("hex");
+		return {
+			caseRoot,
+			advertised: path.join(parent, "app-server-control.sock"),
+			daemonRoot,
+			expected: path.join(daemonRoot, hash),
+		};
+	};
+	const classify = (advertised: string, daemonRoot: string, over: { euid?: number } = {}) =>
+		checkCodexSocketFile(advertised, { daemonRoot, euid, ...over });
+	const statusOf = (check: ReturnType<typeof checkCodexSocketFile>): string => (check.ok ? "ok" : check.status);
+
+	const plainDir = path.join(temp, "plain");
+	fs.mkdirSync(plainDir);
+	const plain = path.join(plainDir, "app-server-control.sock");
+	await listen(plain, 0o600);
+	assert.deepEqual(
+		classify(plain, path.join(temp, "no-daemon-dir")),
+		{ ok: true, connectPath: plain },
+		"(A) a plain socket owned by the effective uid is the endpoint itself — the <=0.153.4 layout is unchanged",
+	);
+
+	const exact = layout("exact");
+	await listen(exact.expected, 0o600);
+	fs.symlinkSync(exact.expected, exact.advertised);
+	assert.deepEqual(
+		classify(exact.advertised, exact.daemonRoot),
+		{ ok: true, connectPath: exact.expected },
+		"(B) Codex's exact rendezvous alias is accepted, and the endpoint is the verified physical socket, not the alias",
+	);
+
+	const wrongHash = layout("wrong-hash");
+	const elsewhere = path.join(wrongHash.daemonRoot, "0".repeat(64));
+	await listen(elsewhere, 0o600);
+	fs.symlinkSync(elsewhere, wrongHash.advertised);
+	const wrongHashCheck = classify(wrongHash.advertised, wrongHash.daemonRoot);
+	assert.equal(
+		statusOf(wrongHashCheck),
+		"indeterminate",
+		"[QK:CODEX-SOCKET-ALIAS-EXACT] an alias into Codex's own socket directory whose name is not the hash of THIS advertised path is refused — a valid 0600 socket in the right 0700 directory is not enough",
+	);
+	assert.match(JSON.stringify(wrongHashCheck), /not Codex's rendezvous alias/, "that refusal says why, by name");
+
+	const relative = layout("relative");
+	await listen(relative.expected, 0o600);
+	fs.symlinkSync(path.relative(path.dirname(relative.advertised), relative.expected), relative.advertised);
+	assert.equal(
+		statusOf(classify(relative.advertised, relative.daemonRoot)),
+		"indeterminate",
+		"a relative alias target is refused even when it resolves to the expected socket",
+	);
+
+	const chain = layout("chain");
+	await listen(chain.expected, 0o600);
+	const hop = path.join(chain.caseRoot, "hop.sock");
+	fs.symlinkSync(chain.expected, hop);
+	fs.symlinkSync(hop, chain.advertised);
+	assert.equal(
+		statusOf(classify(chain.advertised, chain.daemonRoot)),
+		"indeterminate",
+		"an alias that reaches the expected socket through a second link is refused; only the vendor's one hop is accepted",
+	);
+
+	const dangling = layout("dangling");
+	fs.symlinkSync(dangling.expected, dangling.advertised);
+	const danglingCheck = classify(dangling.advertised, dangling.daemonRoot);
+	assert.deepEqual(
+		danglingCheck.ok ? null : [danglingCheck.status, danglingCheck.status === "dead" ? danglingCheck.layout : null],
+		["dead", "dangling-alias"],
+		"the exact alias with its socket gone is dead, named as the dangling alias the vendor itself removes on start",
+	);
+
+	const openDir = layout("dir-0755");
+	await listen(openDir.expected, 0o600);
+	fs.symlinkSync(openDir.expected, openDir.advertised);
+	fs.chmodSync(openDir.daemonRoot, 0o755);
+	assert.equal(
+		statusOf(classify(openDir.advertised, openDir.daemonRoot)),
+		"indeterminate",
+		"a socket directory other users can enter is refused — the vendor's own rule is mode & 0o777 == 0o700",
+	);
+
+	const stickyDir = layout("dir-1700");
+	await listen(stickyDir.expected, 0o600);
+	fs.symlinkSync(stickyDir.expected, stickyDir.advertised);
+	fs.chmodSync(stickyDir.daemonRoot, 0o1700);
+	assert.deepEqual(
+		classify(stickyDir.advertised, stickyDir.daemonRoot),
+		{ ok: true, connectPath: stickyDir.expected },
+		"a sticky 01700 socket directory is accepted: the vendor masks with 0o777, so refusing it would reject a directory Codex itself uses",
+	);
+
+	const linkedDir = layout("dir-symlink");
+	await listen(linkedDir.expected, 0o600);
+	fs.symlinkSync(linkedDir.expected, linkedDir.advertised);
+	const realDir = path.join(linkedDir.caseRoot, "real-daemon-dir");
+	fs.renameSync(linkedDir.daemonRoot, realDir);
+	fs.symlinkSync(realDir, linkedDir.daemonRoot);
+	assert.equal(
+		statusOf(classify(linkedDir.advertised, linkedDir.daemonRoot)),
+		"indeterminate",
+		"a socket directory that is itself a symlink is refused, as the vendor refuses it",
+	);
+
+	const fileTarget = layout("physical-file");
+	fs.writeFileSync(fileTarget.expected, "", { mode: 0o600 });
+	fs.symlinkSync(fileTarget.expected, fileTarget.advertised);
+	assert.equal(
+		statusOf(classify(fileTarget.advertised, fileTarget.daemonRoot)),
+		"indeterminate",
+		"an exact alias whose target is a regular file is refused, never connected to",
+	);
+
+	const readable = layout("physical-0644");
+	await listen(readable.expected, 0o644);
+	fs.symlinkSync(readable.expected, readable.advertised);
+	assert.equal(
+		statusOf(classify(readable.advertised, readable.daemonRoot)),
+		"indeterminate",
+		"an exact alias whose socket group or other users can open is refused",
+	);
+
+	assert.deepEqual(
+		[
+			statusOf(classify(plain, path.join(temp, "no-daemon-dir"), { euid: euid + 1 })),
+			statusOf(classify(exact.advertised, exact.daemonRoot, { euid: euid + 1 })),
+		],
+		["indeterminate", "indeterminate"],
+		"ownership is compared with the EFFECTIVE uid (the vendor's geteuid): under another euid both layouts are refused",
+	);
+
+	// canonicalize(parent) failure is the alias state lstat cannot see coming. The advertised
+	// path is short, but it reaches its parent through a symlink, and the parent's canonical
+	// path is longer than PATH_MAX — the vendor's own `canonicalize` fails on it the same way.
+	// It must be indeterminate: never dead, and never a throw the launcher would read as an
+	// unrecognised status.
+	const canonicalCase = path.join(temp, "canonical");
+	let far = canonicalCase;
+	while (far.length < 3600) far = path.join(far, "d".repeat(200));
+	fs.mkdirSync(far, { recursive: true });
+	const via = path.join(canonicalCase, "via");
+	fs.symlinkSync(far, via);
+	overlongTrees.push(path.join(via, "e".repeat(200)));
+	let overlongParent = via;
+	for (let i = 0; i < 4; i += 1) overlongParent = path.join(overlongParent, "e".repeat(200));
+	fs.mkdirSync(overlongParent, { recursive: true });
+	const overlongAdvertised = path.join(overlongParent, "app-server-control.sock");
+	fs.symlinkSync(exact.expected, overlongAdvertised);
+	const overlongCheck = classify(overlongAdvertised, exact.daemonRoot);
+	assert.equal(
+		statusOf(overlongCheck),
+		"indeterminate",
+		"an alias whose parent cannot be canonicalized is indeterminate",
+	);
+	assert.match(
+		JSON.stringify(overlongCheck),
+		/could not verify/,
+		"that refusal names the verification it could not do",
+	);
 } finally {
+	for (const server of sandboxServers) server.close();
+	for (const tree of overlongTrees) fs.rmSync(tree, { recursive: true, force: true });
 	fs.rmSync(temp, { recursive: true, force: true });
 }
 
@@ -201,15 +402,33 @@ const firstPage = new FakeProtocol([
 	{ data: ["other"], nextCursor: "next" },
 	{ data: ["target"], nextCursor: null },
 ]);
+// The check is asked about the advertised default path, and everything after it — the probe's
+// connect AND the route the queue send uses — goes to the endpoint the check returned. Here
+// the two are different strings, so a probe that went back to the advertised path goes red.
+let checkedPath = "";
+let openedPath = "";
 const alive = await probeCodexThread("target", {
 	env: { CODEX_HOME: "/fixed" },
-	checkSocket: () => ({ ok: true }),
-	openProtocol: opener(firstPage),
+	checkSocket: (advertised) => {
+		checkedPath = advertised;
+		return { ok: true, connectPath: "/verified/physical.sock" };
+	},
+	openProtocol: {
+		open: async (socketPath) => {
+			openedPath = socketPath;
+			return firstPage;
+		},
+	},
 });
 assert.deepEqual(
 	alive,
-	{ status: "alive", route: { backend: "codex", socketPath: "/fixed/app-server-control/app-server-control.sock" } },
-	"[QK:CODEX-NATIVE-LOADED-PROBE] full loaded-thread pagination proves the volatile route",
+	{ status: "alive", route: { backend: "codex", socketPath: "/verified/physical.sock" } },
+	"[QK:CODEX-NATIVE-LOADED-PROBE] full loaded-thread pagination proves the volatile route, on the endpoint the socket check verified",
+);
+assert.deepEqual(
+	[checkedPath, openedPath],
+	["/fixed/app-server-control/app-server-control.sock", "/verified/physical.sock"],
+	"the socket check reads the advertised default path; the probe connects to the endpoint it verified, never the alias again",
 );
 assert.equal(firstPage.closed, true, "successful probe closes its connection");
 assert.deepEqual(
@@ -221,7 +440,7 @@ assert.deepEqual(firstPage.calls[3]?.params, { cursor: "next" }, "pagination car
 const absentProtocol = new FakeProtocol([{}, { data: [], nextCursor: null }]);
 const absent = await probeCodexThread("target", {
 	env: { CODEX_HOME: "/fixed" },
-	checkSocket: () => ({ ok: true }),
+	checkSocket: (advertised) => ({ ok: true, connectPath: advertised }),
 	openProtocol: opener(absentProtocol),
 });
 assert.equal(absent.status, "dead", "a clean loaded inventory without the target is not delivery-capable");
@@ -230,7 +449,7 @@ assert.equal(absentProtocol.closed, true, "negative probe closes its connection"
 const malformedProtocol = new FakeProtocol([{}, { data: [{ id: "wrong-shape" }], nextCursor: null }]);
 const malformed = await probeCodexThread("target", {
 	env: { CODEX_HOME: "/fixed" },
-	checkSocket: () => ({ ok: true }),
+	checkSocket: (advertised) => ({ ok: true, connectPath: advertised }),
 	openProtocol: opener(malformedProtocol),
 });
 assert.equal(malformed.status, "indeterminate", "a malformed inventory is unknown, never dead");
@@ -374,7 +593,7 @@ assert.deepEqual(
 
 const adapter = createCodexNativePushAdapter({
 	env: { CODEX_HOME: "/fixed" },
-	checkSocket: () => ({ ok: true }),
+	checkSocket: (advertised) => ({ ok: true, connectPath: advertised }),
 	openProtocol: opener(new FakeProtocol([{}, { data: ["target"], nextCursor: null }])),
 	runner: queueRunner,
 });

package/scripts/check-gate-qualification.ts

@@ -3442,7 +3442,7 @@ let manifestCount: number;
 		"acp-overlay": 1,
 		"acp-prompt-lifecycle": 15,
 		"acp-set-model-readback": 2,
-		"acp-stop-reason": 6,
+		"acp-stop-reason": 7,
 		"acp-stream-hooks": 10,
 		"acp-usage-accounting": 12,
 		"acp-vendor-rejection": 4,
@@ -3450,10 +3450,10 @@ let manifestCount: number;
 		"bridge-boot-resume": 5,
 		"bridge-command-boot": 12,
 		"capability-cache": 3,
-		"codex-app-server-launch": 9,
+		"codex-app-server-launch": 10,
 		"codex-caller-seat": 28,
 		"control-send-receipt": 19,
-		"codex-native": 82,
+		"codex-native": 87,
 		"compaction-send-guard": 7,
 		"control-socket-disconnect": 4,
 		"demo-reproducibility": 12,
@@ -3464,7 +3464,7 @@ let manifestCount: number;
 		"pi-bridge-sender": 4,
 		"pi-mcp-bridge": 2,
 		"pi-mcp-register": 3,
-		"pi-durable": 65,
+		"pi-durable": 78,
 		"copilot-receive": 20,
 		"entwurf-peers": 1,
 		"fresh-call-dispatch": 12,

package/scripts/check-herdr-supply.ts

@@ -32,7 +32,8 @@
  *   HSUP-CI-REQUIRES-HERDR    that floor runs with absence turned red
  *   HSUP-CI-LINUX-ONLY        only the Linux check job takes this; the other jobs are untouched
  *   HSUP-SETUP-NEVER-INSTALLS the product's own setup/package never installs herdr (Rule 17)
- *   HSUP-X86-UNEXECUTED       the x86_64 asset is pinned but recorded as never executed
+ *   HSUP-EXECUTION-RECEIPT-BOUND  an asset recorded as executed declares a receipt bound to this
+ *                                 pin's version and its own full digest; an unexecuted one has none
  */
 
 import assert from "node:assert/strict";
@@ -62,7 +63,34 @@ interface Supply {
 	measuredOn: string;
 	measuredArch: string;
 	releaseUrlPrefix: string;
-	assets: Record<string, { name: string; sha256: string; executed: boolean; executedNote: string }>;
+	assets: Record<
+		string,
+		{ name: string; sha256: string; executed: boolean; executedNote: string; executedReceipt?: string }
+	>;
+}
+
+/** An asset may be RECORDED as executed only with a declared receipt bound to THIS pin: the
+ * receipt BEGINS with the exact token `herdr <supply.version> ` (a substring match would let
+ * `herdr 0.9.40` stand for 0.9.4) and names the asset's FULL sha256. That checks the
+ * declaration's binding and nothing more — it is not a cryptographic receipt and cannot prove the
+ * binary ran. An unexecuted asset carries no receipt, both states keep a note, and the
+ * architecture the manifest says it was measured on must itself be recorded as executed. The
+ * architecture is never hardcoded: a future x86_64 `true` is admitted the same way, with its own. */
+function executionReceiptsBound(supply: Supply): boolean {
+	const assets = Object.values(supply.assets);
+	const noted = (note: unknown): boolean => typeof note === "string" && note.trim().length > 0;
+	return (
+		assets.length > 0 &&
+		assets.every((a) =>
+			a.executed === true
+				? typeof a.executedReceipt === "string" &&
+					a.executedReceipt.startsWith(`herdr ${supply.version} `) &&
+					a.executedReceipt.includes(a.sha256) &&
+					noted(a.executedNote)
+				: a.executed === false && a.executedReceipt === undefined && noted(a.executedNote),
+		) &&
+		supply.assets[supply.measuredArch]?.executed === true
+	);
 }
 
 function main(): void {
@@ -171,11 +199,8 @@ function main(): void {
 
 	// ── honesty about what has actually run ──────────────────────────────────────────────
 	ok(
-		"[QK:HSUP-X86-UNEXECUTED] the x86_64 asset is pinned but RECORDED AS NEVER EXECUTED — every measurement in this lane ran on aarch64, so a pinned digest must not read as evidence that the cell passes on the other architecture",
-		supply.assets.x86_64?.executed === false &&
-			supply.assets.aarch64?.executed === true &&
-			supply.measuredArch === "aarch64" &&
-			(supply.assets.x86_64?.executedNote ?? "").length > 0,
+		"[QK:HSUP-EXECUTION-RECEIPT-BOUND] an asset is recorded as executed only with a DECLARED receipt bound to this pin's version and its own full digest, and an unexecuted one carries none — a pinned digest is never evidence that its cell ran, and a receipt from another pin or another asset is not this one's. This checks the declaration's binding, not that the binary ran",
+		executionReceiptsBound(supply),
 	);
 
 	console.log(`\n[check-herdr-supply] ${passed} assertions ok`);

package/scripts/codex-app-server-launch.sh

@@ -156,38 +156,53 @@ done
 # --- is somebody already listening there? ----------------------------------
 # Three outcomes, and they are NOT the same repair. A live socket means a second server
 # would either lose the bind race or silently replace the endpoint every citizen's record
-# already points at — refuse and name the holder. An indeterminate path (symlink, not a
-# socket, owned by another uid) is the classification `checkCodexSocketFile` already uses in
-# the product, and a launcher that guessed past it would be clobbering something it cannot
-# identify. A dead socket file is the ordinary leftover of a Ctrl-C, and the vendor replaces
-# it — that one is a fact line, not a refusal.
-probe="$(python3 - "$SOCK" <<'PY'
-import os, socket, stat, sys
-
-path = sys.argv[1]
-try:
-	st = os.lstat(path)
-except FileNotFoundError:
-	print("absent")
-	raise SystemExit(0)
-except OSError as exc:
-	print(f"indeterminate\t{exc.strerror or exc}")
-	raise SystemExit(0)
-
-if stat.S_ISLNK(st.st_mode):
-	print("indeterminate\tthe path is a symlink")
-	raise SystemExit(0)
-if not stat.S_ISSOCK(st.st_mode):
-	print("indeterminate\tthe path exists and is not a socket")
-	raise SystemExit(0)
-if st.st_uid != os.getuid():
-	print(f"indeterminate\tthe socket is owned by uid {st.st_uid}, not {os.getuid()}")
-	raise SystemExit(0)
+# already points at — refuse and name the holder. An indeterminate path (a symlink that is not
+# Codex's own alias, not a socket, owned by another uid) is refused, because a launcher that
+# guessed past it would be clobbering something it cannot identify. A dead socket file is the
+# ordinary leftover of a Ctrl-C, and the vendor replaces it — that one is a fact line, not a
+# refusal. So is a dangling rendezvous alias: from Codex 0.162.1 the advertised path is a
+# symlink into the vendor's own socket directory, and the vendor removes exactly that alias
+# when it starts.
+#
+# WHAT A LAUNCH IS ALLOWED TO TRUST is decided ONCE, by the classifier delivery and preflight
+# use (`checkCodexSocketFile`). This launcher keeps no copy of it: telling Codex's exact alias
+# from any other symlink takes a hash and an exact readlink comparison, and a second
+# implementation here would be the transcription `codex-socket-path` already measured drifting.
+# It runs that classifier's COMPILED twin directly with `node`, in a checkout and in an installed
+# package alike: `build-bridge` emits it (`pnpm install` runs it through `prepare`, and the package
+# ships it through `prepack`), so a missing file is an incomplete installation, refused by name —
+# never a reason to fall back to the TypeScript source. The Python below only CONNECTS to the
+# endpoint the classifier verified, to tell a live server from a stale socket file. An answer the
+# classifier never gives is refused right here, before it can be read as one of the probe's own
+# verdicts.
+#
+# The gate's limit, stated rather than hidden: it executes this launcher on non-alias layouts
+# and on a non-exact symlink, so it proves the launcher accepts no more than the classifier.
+# The exact-alias accept path is proven on `checkCodexSocketFile` itself, with a sandbox socket
+# directory. This launcher's own alias branch is NOT exercised by an existing-server LIVE
+# diagnostic; that launch/refusal path needs its own explicitly authorised LIVE observation.
+CLASSIFIER="$REPO_DIR/mcp/entwurf-bridge/dist/scripts/codex-socket-classify.js"
+[ -f "$CLASSIFIER" ] \
+	|| fail "codex-app-server-classifier-missing: the compiled socket classifier is not at
+  $CLASSIFIER
+  This launcher runs it directly and keeps no other copy of it. Reinstall @junghanacs/entwurf (the
+  package ships it through prepack build-bridge), or run 'pnpm run build-bridge' in a source checkout."
+if ! classified="$(node "$CLASSIFIER")"; then
+	fail "could not classify the control socket at $SOCK.
+  'node $CLASSIFIER' failed; it is the only classification of this socket,
+  and this launcher will not guess past it. Its output above says why."
+fi
+classified_word="${classified%%	*}"
+classified_detail="${classified#*	}"
+case "$classified_word" in
+	socket)
+		probe="$(python3 - "$classified_detail" <<'PY'
+import socket, sys
 
 probe = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
 probe.settimeout(2)
 try:
-	probe.connect(path)
+	probe.connect(sys.argv[1])
 except (ConnectionRefusedError, FileNotFoundError):
 	print("stale")
 except OSError as exc:
@@ -197,7 +212,17 @@ else:
 finally:
 	probe.close()
 PY
-)" || fail "could not classify the control socket at $SOCK (python3 is required by this launcher)."
+)" || fail "could not probe the control socket at $classified_detail (python3 is required by this launcher)."
+		;;
+	absent) probe="absent" ;;
+	dangling) probe="stale	$classified_detail" ;;
+	indeterminate) probe="indeterminate	$classified_detail" ;;
+	*)
+		fail "codex-app-server-socket-probe-unrecognised: the socket classifier answered
+  '$classified_word', which is not one of socket/absent/dangling/indeterminate. Refusing to launch on a
+  reading nothing understands."
+		;;
+esac
 
 probe_status="${probe%%	*}"
 probe_reason="${probe#*	}"

package/scripts/codex-socket-classify.ts

@@ -0,0 +1,46 @@
+/**
+ * codex-socket-classify — classify the Codex app-server default control socket for THIS
+ * environment, through the one product classifier, and print the answer for a shell.
+ *
+ * WHY A LEAF. `entwurf codex-app-server` is a bash launcher, and it has to decide whether a
+ * launch would clobber something. From Codex 0.162.1 the advertised socket path is a
+ * rendezvous alias into a vendor-owned directory, and telling the vendor's exact alias from any
+ * other symlink takes a hash, an exact readlink comparison and ownership/mode checks. Doing that
+ * in the launcher's Python would be a second implementation of a security classification, and
+ * `codex-socket-path.ts` records what a second spelling of this socket did once (it diverged).
+ * So the launcher asks `checkCodexSocketFile`, the classifier delivery and preflight use, and
+ * only connects to what it was told.
+ *
+ * HOW IT IS REACHED. The launcher runs this file's COMPILED twin,
+ * `mcp/entwurf-bridge/dist/scripts/codex-socket-classify.js`, directly with `node` — in a checkout
+ * and in an installed package alike. There is no `run.sh` verb and no `run_ts` crossing for it:
+ * `build-bridge` emits it (`pnpm install` runs that through `prepare`, packing through `prepack`),
+ * and a missing twin is an incomplete installation the launcher refuses by name.
+ *
+ * One line on stdout, a word then a tab-separated detail:
+ *   socket <connectPath>       a verified socket; the launcher connects there to tell live from stale
+ *   absent                     nothing at the advertised path
+ *   dangling <reason>          Codex's own alias whose socket is gone; the vendor removes it on start
+ *   indeterminate <reason>     anything else; the launcher refuses
+ *
+ * Reads `process.env` and takes no argument, for the reason `codex-socket-path.ts` gives: an argv
+ * seam would be a way to redirect the address. It has no daemon-root input either; the gate's
+ * exact-alias cells drive `checkCodexSocketFile` directly with a sandbox root.
+ */
+
+import {
+	checkCodexSocketFile,
+	resolveCodexDefaultSocketPath,
+} from "../pi-extensions/lib/native-push/codex-ws-client.ts";
+
+if (process.argv.length > 2) {
+	console.error("usage: codex-socket-classify   (no arguments; the environment is the input)");
+	process.exit(2);
+}
+
+const oneLine = (text: string): string => text.replace(/[\t\r\n]+/g, " ");
+const check = checkCodexSocketFile(resolveCodexDefaultSocketPath(process.env));
+if (check.ok) process.stdout.write(`socket\t${check.connectPath}`);
+else if (check.status === "dead" && check.layout === "absent") process.stdout.write("absent");
+else if (check.status === "dead") process.stdout.write(`dangling\t${oneLine(check.reason)}`);
+else process.stdout.write(`indeterminate\t${oneLine(check.reason)}`);