@junghanacs/entwurf 0.12.0

package/scripts/check-shell-quote.ts

@@ -0,0 +1,121 @@
+/**
+ * check-shell-quote — deterministic POSIX-safety gate for remote SSH arg quoting.
+ *
+ * Background: the 2026-05-18 remote entwurf incident traced back to building
+ * SSH command strings with `JSON.stringify`, which is NOT a shell-safe escape.
+ * Backticks and `$(...)` inside a user prompt got executed by the remote shell
+ * before pi ever saw them. The fix introduced `shellQuote()` (POSIX `'...'`
+ * with `'\''` escape) in two places:
+ *   - pi-extensions/lib/entwurf-core.ts (legacy sync spawn/resume helper while v2 extraction is in progress)
+ *
+ * This script enforces two invariants:
+ *   1. `shellQuote()` source matches the reference implementation byte-for-byte.
+ *   2. The reference implementation produces POSIX-safe output for the exact
+ *      payload classes that caused the original incident — backtick command
+ *      substitution, `$(...)` command substitution, `$VAR` expansion, embedded
+ *      single quotes, whitespace, empty string, non-ASCII text.
+ *
+ * No process spawn, no SSH, no API. Pure-string verification — safe in `pnpm
+ * check` chain.
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// Reference implementation — must match the literal function body in both
+// production sites. If you need to change the algorithm, change the reference
+// FIRST, then sync both sites, then update SOURCE_SITES.
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+const REFERENCE_BODY = `function shellQuote(value: string): string {
+\treturn \`'\${value.replace(/'/g, \`'\\\\''\`)}\`;
+}`;
+
+const SOURCE_SITES = ["pi-extensions/lib/entwurf-core.ts"] as const;
+
+// Match the function block from `function shellQuote` up to the closing brace.
+// Tab indentation is required (matches the rest of the repo).
+const SHELL_QUOTE_BLOCK =
+	/function shellQuote\(value: string\): string \{\n\treturn `'\$\{value\.replace\(\/'\/g, `'\\\\''`\)\}'`;\n\}/;
+
+let assertions = 0;
+
+function check(label: string, fn: () => void): void {
+	fn();
+	assertions += 1;
+	process.stdout.write(`[check-shell-quote] ${label}: ok\n`);
+}
+
+// ------------------------------------------------------------------
+// Invariant 1 — source parity across the two duplication sites
+// ------------------------------------------------------------------
+
+for (const rel of SOURCE_SITES) {
+	check(`source parity — ${rel}`, () => {
+		const abs = path.join(REPO_ROOT, rel);
+		const text = fs.readFileSync(abs, "utf8");
+		const match = text.match(SHELL_QUOTE_BLOCK);
+		assert.ok(
+			match,
+			`shellQuote() block in ${rel} did not match the reference shape. ` +
+				`If you intentionally changed the algorithm, update both sites AND the ` +
+				`reference block in scripts/check-shell-quote.ts.`,
+		);
+	});
+}
+
+check("reference body byte-pattern is canonical", () => {
+	// Sanity: the reference declared above is itself a valid shellQuote
+	// definition. The string match is informational; the real check is the
+	// behavioral suite below.
+	assert.match(REFERENCE_BODY, /function shellQuote/);
+});
+
+// ------------------------------------------------------------------
+// Invariant 2 — POSIX-safety behavior on the payload classes that
+// caused the 2026-05-18 incident, plus general escape cases.
+// ------------------------------------------------------------------
+
+type Case = { label: string; input: string; expected: string };
+
+const CASES: Case[] = [
+	// The four incident payloads.
+	{ label: "backtick command substitution", input: "`date`", expected: "'`date`'" },
+	{ label: "$() command substitution", input: "$(rm -rf /)", expected: "'$(rm -rf /)'" },
+	{ label: "$VAR expansion", input: "$HOME/.pi/agent", expected: "'$HOME/.pi/agent'" },
+	{
+		label: "korean token broken by SSH (denotecli read 어제)",
+		input: "denotecli read 어제",
+		expected: "'denotecli read 어제'",
+	},
+
+	// General escape correctness.
+	{ label: "plain alphanumeric", input: "hello", expected: "'hello'" },
+	{ label: "whitespace preserved", input: "hello world", expected: "'hello world'" },
+	{ label: "embedded single quote", input: "it's fine", expected: `'it'\\''s fine'` },
+	{ label: "multiple single quotes", input: "''", expected: `''\\'''\\'''` },
+	{ label: "empty string", input: "", expected: "''" },
+	{ label: "double quote literal", input: 'she said "hi"', expected: `'she said "hi"'` },
+	{ label: "backslash literal", input: "a\\b", expected: "'a\\b'" },
+	{ label: "newline literal", input: "a\nb", expected: "'a\nb'" },
+	{ label: "ampersand + semicolon", input: "a && b ; c", expected: "'a && b ; c'" },
+];
+
+for (const c of CASES) {
+	check(`behavior — ${c.label}`, () => {
+		const actual = shellQuote(c.input);
+		assert.equal(actual, c.expected, `input=${JSON.stringify(c.input)}`);
+	});
+}
+
+// ------------------------------------------------------------------
+// Done
+// ------------------------------------------------------------------
+
+process.stdout.write(`[check-shell-quote] ${assertions} assertions ok\n`);

package/scripts/check-socket-discovery.ts

@@ -0,0 +1,428 @@
+/**
+ * check-socket-discovery — deterministic gate for the fact-provider's SOCKET
+ * axis (0.11 Stage 0 step 4, slice 3). Drives `scanSocketProbes` with injected
+ * readdir/probe (no IO) and proves the slice-2 contract is fed correctly:
+ *
+ *   - union: every dir-present socket AND every in-domain citizen is probed,
+ *   - dormant trap: a pi citizen with NO socket file reads `dead` (ENOENT), so
+ *     downstream it routes dormant→resumable (never an unprobed gap),
+ *   - F3 preserve: a stalled socket reads `indeterminate`, never folded to dead,
+ *   - dir hygiene: non-`.sock` names ignored; malformed (non-garden-id) names
+ *     are VISIBLY dropped (`malformedNames`), not silently (P3),
+ *   - symlink guard (P1): a gid-shaped `*.sock` symlink is never probed — a
+ *     citizen owning one is forced `dead`, a record-less one dropped — and is
+ *     surfaced in `symlinkedGardenIds`,
+ *   - dir-read error (P2e②): ENOENT → `dirError=null` (normal empty); any other
+ *     failure → `dirError` set (socket axis loss surfaced, not swallowed),
+ *   - dedup: a gid present in BOTH the dir and the citizen list is probed once,
+ *   - missing dir: citizens are still probed (→ dead),
+ *   - determinism: output sorted by gardenId,
+ *   - enrich: default fake scans stay null; live sockets can carry get_info cwd/model/idle,
+ *   - end-to-end: scanSocketProbes → resolveFactList yields the dormant citizen
+ *     as a resumable `dead` PeerFact (no throw — all in-domain citizens probed).
+ *
+ * No IO, no backend, no API — readdir/probe are injected fakes.
+ */
+
+import assert from "node:assert/strict";
+import * as path from "node:path";
+import { resolveFactList } from "../pi-extensions/lib/entwurf-facts.ts";
+import type { MetaBackendV2, MetaIdentity } from "../pi-extensions/lib/meta-session.ts";
+import {
+	controlSocketPath,
+	inspectControlSocketPath,
+	inspectTargetControlSocket,
+	type LstatLike,
+	mapInspectionToLiveness,
+	SOCKET_SUFFIX,
+	type SocketDirEntry,
+	scanSocketProbes,
+} from "../pi-extensions/lib/socket-discovery.ts";
+import type { SocketLiveness } from "../pi-extensions/lib/socket-probe.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const DIR = "/fake/entwurf-control";
+const GID_LIVE = "20260611T115213-3aa371"; // socket present → alive
+const GID_STALL = "20260611T135517-5f0d25"; // socket present → indeterminate (F3)
+const GID_DORMANT = "20260611T093858-14984d"; // pi citizen, no socket file → dead
+const GID_SOCKET_ONLY = "20260611T222222-bbbbbb"; // socket present, no citizen
+
+const PROBE_MAP: Record<string, SocketLiveness> = {
+	[GID_LIVE]: "alive",
+	[GID_STALL]: "indeterminate",
+	[GID_SOCKET_ONLY]: "alive",
+	// GID_DORMANT intentionally absent → fakeProbe returns "dead" (ENOENT)
+};
+
+// Plain regular-file entries (the common case). A name may be passed as a
+// `{name, isSymbolicLink}` tuple to mark it a symlink.
+function fakeReaddir(names: Array<string | SocketDirEntry>): (dir: string) => Promise<SocketDirEntry[]> {
+	return async () => names.map((n) => (typeof n === "string" ? { name: n, isSymbolicLink: false } : n));
+}
+
+// Probe keyed by the gardenId embedded in the canonical socket path. An absent
+// gid → "dead", mirroring an ENOENT connect on a missing socket file.
+function fakeProbe(byGid: Record<string, SocketLiveness>): (socketPath: string) => Promise<SocketLiveness> {
+	return async (socketPath: string) => {
+		const base = path.basename(socketPath, SOCKET_SUFFIX);
+		return byGid[base] ?? "dead";
+	};
+}
+
+const NAMES = [`${GID_LIVE}.sock`, `${GID_STALL}.sock`, `${GID_SOCKET_ONLY}.sock`, "README.txt", "not-a-gid.sock"];
+
+async function main(): Promise<void> {
+	// ── union: dir sockets ∪ pi citizens, each probed ──────────────────────────
+	{
+		const { probes } = await scanSocketProbes([GID_DORMANT, GID_LIVE], {
+			dir: DIR,
+			readdir: fakeReaddir(NAMES),
+			probe: fakeProbe(PROBE_MAP),
+		});
+		const byGid = Object.fromEntries(probes.map((p) => [p.gardenId, p]));
+		ok("union: dir sockets + pi citizens all probed (LIVE/STALL/SOCKET_ONLY/DORMANT)", probes.length === 4);
+		ok("alive socket → alive", byGid[GID_LIVE]?.liveness === "alive");
+		ok("F3: stalled socket → indeterminate (never folded to dead)", byGid[GID_STALL]?.liveness === "indeterminate");
+		ok("dormant pi citizen (no socket file) → dead (ENOENT)", byGid[GID_DORMANT]?.liveness === "dead");
+		ok("record-less socket → alive", byGid[GID_SOCKET_ONLY]?.liveness === "alive");
+		ok(
+			"enrich default null under injected fake scan (honest)",
+			byGid[GID_LIVE]?.cwd === null && byGid[GID_LIVE]?.model === null,
+		);
+	}
+
+	// ── live get_info enrich: only alive sockets carry cwd/model/idle ───────────
+	{
+		const calls: string[] = [];
+		const { probes } = await scanSocketProbes([GID_DORMANT], {
+			dir: DIR,
+			readdir: fakeReaddir([`${GID_LIVE}.sock`, `${GID_STALL}.sock`]),
+			probe: fakeProbe(PROBE_MAP),
+			getInfo: async (socketPath) => {
+				calls.push(path.basename(socketPath, SOCKET_SUFFIX));
+				return { cwd: "/work/cos", model: "gpt-5.4", idle: false };
+			},
+		});
+		const byGid = Object.fromEntries(probes.map((p) => [p.gardenId, p]));
+		ok("get_info called only for alive sockets", calls.length === 1 && calls[0] === GID_LIVE);
+		ok("alive socket enrich carries cwd", byGid[GID_LIVE]?.cwd === "/work/cos");
+		ok("alive socket enrich carries model", byGid[GID_LIVE]?.model === "gpt-5.4");
+		ok("alive socket enrich carries idle", byGid[GID_LIVE]?.idle === false);
+		ok(
+			"indeterminate socket does not get_info",
+			byGid[GID_STALL]?.cwd === null && byGid[GID_STALL]?.infoError === null,
+		);
+	}
+
+	// ── get_info failure is surfaced but liveness remains alive ─────────────────
+	{
+		const { probes } = await scanSocketProbes([], {
+			dir: DIR,
+			readdir: fakeReaddir([`${GID_LIVE}.sock`]),
+			probe: fakeProbe(PROBE_MAP),
+			getInfo: async () => {
+				throw new Error("boom get_info");
+			},
+		});
+		ok("get_info failure keeps alive liveness", probes[0]?.liveness === "alive");
+		ok("get_info failure surfaces infoError", probes[0]?.infoError?.includes("boom get_info") === true);
+	}
+
+	// ── dir hygiene: non-.sock ignored; malformed names VISIBLY dropped (P3) ────
+	{
+		const { probes, malformedNames } = await scanSocketProbes([], {
+			dir: DIR,
+			readdir: fakeReaddir(NAMES),
+			probe: fakeProbe(PROBE_MAP),
+		});
+		const gids = probes.map((p) => p.gardenId);
+		ok("non-.sock entry ignored (README.txt)", !gids.includes("README"));
+		ok("malformed socket name (not a garden id) not probed", !gids.some((g) => g.includes("not-a-gid")));
+		ok(
+			"only well-formed garden ids surface",
+			gids.every((g) => /^\d{8}T\d{6}-[0-9a-f]{6}$/.test(g)),
+		);
+		ok("P3: malformed .sock name surfaced (not silently dropped)", malformedNames.includes("not-a-gid.sock"));
+		ok("P3: non-.sock entry is NOT a malformed-name diagnostic", !malformedNames.includes("README.txt"));
+	}
+
+	// ── symlink guard (P1): gid-shaped .sock symlink never probed, surfaced ─────
+	{
+		// GID_LIVE is a symlink (forgery vector) AND a pi citizen; GID_SOCKET_ONLY is
+		// a symlink with no citizen (record-less). GID_DORMANT is a clean citizen.
+		const { probes, symlinkedGardenIds } = await scanSocketProbes([GID_LIVE, GID_DORMANT], {
+			dir: DIR,
+			readdir: fakeReaddir([
+				{ name: `${GID_LIVE}.sock`, isSymbolicLink: true },
+				{ name: `${GID_SOCKET_ONLY}.sock`, isSymbolicLink: true },
+				`${GID_DORMANT}.sock`,
+			]),
+			// probe would return "alive" for both — proving we did NOT probe the symlinks.
+			probe: fakeProbe({ [GID_LIVE]: "alive", [GID_SOCKET_ONLY]: "alive", [GID_DORMANT]: "alive" }),
+		});
+		const byGid = Object.fromEntries(probes.map((p) => [p.gardenId, p]));
+		ok("P1: symlinked sockets surfaced in symlinkedGardenIds", symlinkedGardenIds.length === 2);
+		ok("P1: symlinked citizen forced dead (NOT probed alive)", byGid[GID_LIVE]?.liveness === "dead");
+		ok("P1: record-less symlink dropped from probes entirely", byGid[GID_SOCKET_ONLY] === undefined);
+		ok("P1: clean citizen still probed normally", byGid[GID_DORMANT]?.liveness === "alive");
+		ok(
+			"P1: symlinkedGardenIds sorted",
+			symlinkedGardenIds[0] !== undefined && symlinkedGardenIds[0] < (symlinkedGardenIds[1] ?? "~"),
+		);
+	}
+
+	// ── dedup: gid in BOTH dir and citizen list → probed once ──────────────────
+	{
+		const { probes } = await scanSocketProbes([GID_LIVE], {
+			dir: DIR,
+			readdir: fakeReaddir([`${GID_LIVE}.sock`]),
+			probe: fakeProbe(PROBE_MAP),
+		});
+		ok("dedup: gid in dir AND citizen list → one probe", probes.filter((p) => p.gardenId === GID_LIVE).length === 1);
+	}
+
+	// ── dir-read error (P2e②): ENOENT empty vs other-error surfaced ────────────
+	{
+		const enoent = await scanSocketProbes([GID_DORMANT], {
+			dir: DIR,
+			readdir: async () => {
+				const e = new Error("ENOENT: no such directory") as NodeJS.ErrnoException;
+				e.code = "ENOENT";
+				throw e;
+			},
+			probe: fakeProbe(PROBE_MAP),
+		});
+		ok("missing dir (ENOENT) → empty listing, citizen still probed", enoent.probes.length === 1);
+		ok("missing dir → dormant citizen reads dead", enoent.probes[0]?.liveness === "dead");
+		ok("P2e②: ENOENT is the normal empty → dirError null (not surfaced)", enoent.dirError === null);
+
+		// probe returns "alive" — proving the citizen is NOT probed when the dir is
+		// untrusted (a non-ENOENT readdir failure): connect() would follow a symlink,
+		// so we hold the citizen at indeterminate instead (GPi Q2/P1).
+		let probeCalled = false;
+		const eacces = await scanSocketProbes([GID_DORMANT], {
+			dir: DIR,
+			readdir: async () => {
+				const e = new Error("EACCES: permission denied, scandir") as NodeJS.ErrnoException;
+				e.code = "EACCES";
+				throw e;
+			},
+			probe: async () => {
+				probeCalled = true;
+				return "alive";
+			},
+		});
+		ok("P2e②: non-ENOENT readdir failure → dirError surfaced", typeof eacces.dirError === "string");
+		ok("P2e②: EACCES message preserved in dirError", eacces.dirError?.includes("EACCES") === true);
+		ok("P2e②: citizen still reported (socket axis lost, not blinded)", eacces.probes.length === 1);
+		ok("P2e②/P1: untrusted dir → citizen NOT probed (no connect through unverified path)", !probeCalled);
+		ok(
+			"P2e②/P1: untrusted dir → citizen held at indeterminate (not alive, not stranded)",
+			eacces.probes[0]?.liveness === "indeterminate",
+		);
+	}
+
+	// ── determinism: sorted by gardenId ────────────────────────────────────────
+	{
+		const { probes } = await scanSocketProbes(["20260611T333333-cccccc", "20260611T111111-aaaaaa"], {
+			dir: DIR,
+			readdir: async () => [],
+			probe: async () => "dead",
+		});
+		ok("determinism: probes sorted by gardenId", probes[0]?.gardenId === "20260611T111111-aaaaaa");
+	}
+
+	// ── canonical socket path shape ────────────────────────────────────────────
+	ok("controlSocketPath = <dir>/<gid>.sock", controlSocketPath(GID_LIVE, DIR) === `${DIR}/${GID_LIVE}.sock`);
+
+	// ── end-to-end: scanSocketProbes → resolveFactList (dormant resumable) ──────
+	{
+		const identity = (gid: string, backend: MetaBackendV2): MetaIdentity => ({
+			schemaVersion: 2,
+			gardenId: gid,
+			backend,
+			nativeSessionId: "n",
+			cwd: "/x",
+			model: null,
+			transcriptPath: null,
+			parentGardenId: null,
+			isEntwurf: false,
+			createdAt: "2026-06-11T00:00:00.000Z",
+			recordUpdatedAt: "2026-06-11T00:00:00.000Z",
+		});
+		const citizens = [identity(GID_LIVE, "pi"), identity(GID_DORMANT, "pi")];
+		const { probes } = await scanSocketProbes([GID_LIVE, GID_DORMANT], {
+			dir: DIR,
+			readdir: fakeReaddir([`${GID_LIVE}.sock`]),
+			probe: fakeProbe(PROBE_MAP),
+		});
+		const out = resolveFactList(citizens, probes);
+		ok("e2e: 2 pi citizens → 2 PeerFacts (no throw — all probed)", out.peers.length === 2);
+		ok("e2e: live citizen alive", out.peers.find((p) => p.gardenId === GID_LIVE)?.liveness === "alive");
+		ok(
+			"e2e: dormant citizen dead (resumable, not stranded)",
+			out.peers.find((p) => p.gardenId === GID_DORMANT)?.liveness === "dead",
+		);
+		ok("e2e: dir held only LIVE socket → no record-less SocketOnlyFact", out.socketOnly.length === 0);
+	}
+
+	// ── inspectTargetControlSocket (？2 — lstat-then-connect, v2 decider helper) ──
+	// The single-target, lock-time inspection. lstat is injected so every branch is
+	// driven without a real fs; every variant carries the canonical socketPath.
+	{
+		const DIR2 = "/fake/ctl";
+		const expectedPath = controlSocketPath(GID_LIVE, DIR2);
+		const stat = (over: Partial<Record<"sym" | "sock", boolean>>): LstatLike => ({
+			isSymbolicLink: () => over.sym === true,
+			isSocket: () => over.sock === true,
+		});
+		const lstatThrowing = (code: string) => async (): Promise<LstatLike> => {
+			const e = new Error(`${code}: lstat`) as NodeJS.ErrnoException;
+			e.code = code;
+			throw e;
+		};
+
+		// ENOENT → absent (the citizen is dormant; this is the path a resume creates).
+		const absent = await inspectTargetControlSocket(GID_LIVE, DIR2, lstatThrowing("ENOENT"));
+		ok("inspect: ENOENT → absent", absent.kind === "absent");
+		ok("inspect: absent carries socketPath", absent.socketPath === expectedPath);
+
+		// symlink → address-conflict (NEVER connected — P1), reason symlink.
+		const sym = await inspectTargetControlSocket(GID_LIVE, DIR2, async () => stat({ sym: true }));
+		ok("inspect: symlink → address-conflict", sym.kind === "address-conflict");
+		ok("inspect: symlink reason", sym.kind === "address-conflict" && sym.reason === "symlink");
+
+		// a real socket file → socket-file (safe to connect now).
+		const sock = await inspectTargetControlSocket(GID_LIVE, DIR2, async () => stat({ sock: true }));
+		ok("inspect: socket file → socket-file", sock.kind === "socket-file");
+		ok("inspect: socket-file carries socketPath", sock.socketPath === expectedPath);
+
+		// a non-socket regular file/dir at the canonical path → address-conflict.
+		const notSock = await inspectTargetControlSocket(GID_LIVE, DIR2, async () => stat({}));
+		ok("inspect: non-socket → address-conflict", notSock.kind === "address-conflict");
+		ok("inspect: non-socket reason", notSock.kind === "address-conflict" && notSock.reason === "not-socket");
+
+		// EACCES / unknown lstat error → indeterminate (never connect, never spawn).
+		const indet = await inspectTargetControlSocket(GID_LIVE, DIR2, lstatThrowing("EACCES"));
+		ok("inspect: EACCES → indeterminate", indet.kind === "indeterminate");
+		ok("inspect: indeterminate carries error code", indet.kind === "indeterminate" && indet.error === "EACCES");
+		// symlink is decided BEFORE socket — a symlink that also reports isSocket is still a conflict.
+		const symSock = await inspectTargetControlSocket(GID_LIVE, DIR2, async () => stat({ sym: true, sock: true }));
+		ok("inspect: symlink wins over isSocket (never connect a symlink)", symSock.kind === "address-conflict");
+	}
+
+	// ── inspectControlSocketPath (5c-3c R1 — the path-addressed SSOT) ────────────────
+	// The 5c-3 spawn-bg watcher observes plan.expectedSocketPath and MUST inspect THAT exact
+	// path (no gid re-derivation). Proves the path-taking core classifies every branch
+	// identically to the gid wrapper, and that the wrapper just feeds it controlSocketPath(gid).
+	{
+		const EXACT = "/fake/ctl/some-exact.sock";
+		const WRAP_DIR = "/fake/ctl";
+		const stat = (over: Partial<Record<"sym" | "sock", boolean>>): LstatLike => ({
+			isSymbolicLink: () => over.sym === true,
+			isSocket: () => over.sock === true,
+		});
+		const lstatThrowing = (code: string) => async (): Promise<LstatLike> => {
+			const e = new Error(`${code}: lstat`) as NodeJS.ErrnoException;
+			e.code = code;
+			throw e;
+		};
+
+		// Inspects the EXACT path handed in (carried verbatim on every variant).
+		const absent = await inspectControlSocketPath(EXACT, lstatThrowing("ENOENT"));
+		ok("path-inspect: ENOENT → absent", absent.kind === "absent");
+		ok("path-inspect: absent carries the EXACT path (no re-derivation)", absent.socketPath === EXACT);
+
+		const sym = await inspectControlSocketPath(EXACT, async () => stat({ sym: true }));
+		ok("path-inspect: symlink → address-conflict (never connected, P1)", sym.kind === "address-conflict");
+		ok("path-inspect: symlink reason", sym.kind === "address-conflict" && sym.reason === "symlink");
+
+		const sock = await inspectControlSocketPath(EXACT, async () => stat({ sock: true }));
+		ok("path-inspect: socket file → socket-file", sock.kind === "socket-file");
+		ok("path-inspect: socket-file carries the EXACT path", sock.socketPath === EXACT);
+
+		const notSock = await inspectControlSocketPath(EXACT, async () => stat({}));
+		ok("path-inspect: non-socket → address-conflict", notSock.kind === "address-conflict");
+		ok("path-inspect: non-socket reason", notSock.kind === "address-conflict" && notSock.reason === "not-socket");
+
+		const indet = await inspectControlSocketPath(EXACT, lstatThrowing("EACCES"));
+		ok("path-inspect: EACCES → indeterminate", indet.kind === "indeterminate");
+		ok("path-inspect: indeterminate carries error code", indet.kind === "indeterminate" && indet.error === "EACCES");
+
+		// The gid wrapper feeds the path-core controlSocketPath(gid, dir) verbatim — same
+		// classification, just a derived path. Proves the thin-wrapper equivalence.
+		const wrapped = await inspectTargetControlSocket(GID_LIVE, WRAP_DIR, async () => stat({ sock: true }));
+		const direct = await inspectControlSocketPath(controlSocketPath(GID_LIVE, WRAP_DIR), async () =>
+			stat({ sock: true }),
+		);
+		ok(
+			"path-inspect: gid wrapper === path-core over controlSocketPath(gid)",
+			wrapped.socketPath === direct.socketPath && wrapped.kind === direct.kind,
+		);
+	}
+
+	// mapInspectionToLiveness — the shared inspection→liveness mapper (SSOT for the 5b
+	// decider AND the 5c-2b dead-control-send resolver). Proves the 4-way mapping that
+	// both callers depend on, so a drift between them is impossible: absent→dead,
+	// socket-file→(probe result), indeterminate→indeterminate, address-conflict→conflict.
+	{
+		const SP = "/fake/ctl/m.sock";
+		const absent = await mapInspectionToLiveness({ kind: "absent", socketPath: SP }, async () => "alive");
+		ok(
+			"map: absent → dead (ENOENT = honest dormant), carries socketPath",
+			!("addressConflict" in absent) && absent.liveness === "dead" && absent.socketPath === SP,
+		);
+
+		let probed = "";
+		const live = await mapInspectionToLiveness({ kind: "socket-file", socketPath: SP }, async (p) => {
+			probed = p;
+			return "alive";
+		});
+		ok(
+			"map: socket-file → probe result (the ONLY case that connects)",
+			!("addressConflict" in live) && live.liveness === "alive" && probed === SP,
+		);
+
+		const stall = await mapInspectionToLiveness({ kind: "socket-file", socketPath: SP }, async () => "indeterminate");
+		ok(
+			"map: socket-file + probe indeterminate → indeterminate (never folded to dead)",
+			!("addressConflict" in stall) && stall.liveness === "indeterminate",
+		);
+
+		let connectedOnIndet = false;
+		const indet = await mapInspectionToLiveness(
+			{ kind: "indeterminate", socketPath: SP, error: "EACCES" },
+			async () => {
+				connectedOnIndet = true;
+				return "alive";
+			},
+		);
+		ok(
+			"map: inspect indeterminate → indeterminate, NEVER connects",
+			!("addressConflict" in indet) && indet.liveness === "indeterminate" && connectedOnIndet === false,
+		);
+
+		let connectedOnConflict = false;
+		const conflict = await mapInspectionToLiveness(
+			{ kind: "address-conflict", socketPath: SP, reason: "symlink" },
+			async () => {
+				connectedOnConflict = true;
+				return "alive";
+			},
+		);
+		ok(
+			"map: address-conflict → {addressConflict:true}, NEVER connects",
+			"addressConflict" in conflict && connectedOnConflict === false,
+		);
+	}
+
+	console.log(`\n[check-socket-discovery] ${passed} assertions ok`);
+}
+
+await main();

package/scripts/check-socket-probe.ts

@@ -0,0 +1,106 @@
+/**
+ * check-socket-probe — deterministic gate for 0.11 Stage 0 (F3 fix): the
+ * three-valued control-socket liveness probe and its GC/listing policies.
+ *
+ * Proves:
+ *   - classifyConnectError is a pure boundary: ECONNREFUSED/ENOENT → dead;
+ *     timeout/EACCES/unknown/undefined → indeterminate (default = don't destroy),
+ *   - shouldUnlinkOnGc reclaims ONLY dead (the F3 invariant: indeterminate and
+ *     alive both survive the sweep),
+ *   - shouldListAsLive lists ONLY alive (indeterminate hidden but not unlinked),
+ *   - probeSocketLiveness end-to-end on the two REPRODUCIBLE cases:
+ *       (a) a real listening socket  → "alive"  → survives GC,
+ *       (b) a nonexistent path       → "dead"   → eligible for GC.
+ *
+ * Why no timeout fixture: a connect that neither connects nor errors cannot be
+ * forged deterministically at the wire level (a dead unix socket gives
+ * ECONNREFUSED; Node's listener auto-accepts). The timeout→indeterminate edge
+ * is held by the pure classifier (ETIMEDOUT) + the probe's timer branch, not by
+ * a flaky wire test. (Per GLG: don't burn time on a wire timeout fixture.)
+ *
+ * Pure + two-socket integration; no backend, no API.
+ */
+
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	classifyConnectError,
+	probeSocketLiveness,
+	type SocketLiveness,
+	shouldListAsLive,
+	shouldUnlinkOnGc,
+} from "../pi-extensions/lib/socket-probe.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+function eq(label: string, actual: unknown, expected: unknown): void {
+	assert.strictEqual(actual, expected, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+// ── Pure classifier: only the two positive-absence codes are dead ──────────
+eq("classify ECONNREFUSED → dead", classifyConnectError("ECONNREFUSED"), "dead");
+eq("classify ENOENT → dead", classifyConnectError("ENOENT"), "dead");
+eq("classify ETIMEDOUT → indeterminate", classifyConnectError("ETIMEDOUT"), "indeterminate");
+eq("classify EACCES → indeterminate (unknown ≠ dead)", classifyConnectError("EACCES"), "indeterminate");
+eq("classify EPIPE → indeterminate", classifyConnectError("EPIPE"), "indeterminate");
+eq("classify undefined code → indeterminate", classifyConnectError(undefined), "indeterminate");
+
+// ── GC policy: reclaim ONLY dead — the F3 invariant ────────────────────────
+eq("GC unlinks dead", shouldUnlinkOnGc("dead"), true);
+eq("GC keeps indeterminate (F3: load-stalled live socket survives)", shouldUnlinkOnGc("indeterminate"), false);
+eq("GC keeps alive", shouldUnlinkOnGc("alive"), false);
+
+// ── Listing policy: list ONLY alive; GC scope ⊂ listing-hidden scope ───────
+eq("list alive", shouldListAsLive("alive"), true);
+eq("list hides dead", shouldListAsLive("dead"), false);
+eq("list hides indeterminate", shouldListAsLive("indeterminate"), false);
+// Structural invariant: nothing that GC reclaims is ever listed as live, and
+// the set GC reclaims (dead) is strictly narrower than the set hidden from the
+// listing (dead + indeterminate) — so a hidden socket is never auto-destroyed.
+for (const liveness of ["alive", "dead", "indeterminate"] as SocketLiveness[]) {
+	if (shouldUnlinkOnGc(liveness)) {
+		ok(`invariant: GC-reclaimed (${liveness}) is not listed live`, !shouldListAsLive(liveness));
+	}
+}
+
+// ── Integration: two reproducible cases on real paths ──────────────────────
+async function integration(): Promise<void> {
+	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "socket-probe-"));
+	const liveSock = path.join(dir, "live.sock");
+	const goneSock = path.join(dir, "absent.sock");
+
+	// (a) real listener → alive → survives GC
+	const server = net.createServer();
+	await new Promise<void>((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(liveSock, resolve);
+	});
+	try {
+		const live = await probeSocketLiveness(liveSock);
+		eq("integration: listening socket → alive", live, "alive");
+		eq("integration: alive socket survives GC", shouldUnlinkOnGc(live), false);
+		ok("integration: alive socket is listed", shouldListAsLive(live));
+	} finally {
+		await new Promise<void>((resolve) => server.close(() => resolve()));
+	}
+
+	// (b) nonexistent path → dead → eligible for GC
+	const dead = await probeSocketLiveness(goneSock);
+	eq("integration: nonexistent path → dead", dead, "dead");
+	eq("integration: dead path is GC-eligible", shouldUnlinkOnGc(dead), true);
+
+	await fs.rm(dir, { recursive: true, force: true });
+}
+
+await integration();
+
+console.log(`\ncheck-socket-probe: ${passed} assertions passed`);