@junghanacs/entwurf 0.12.0

package/pi-extensions/lib/project-trust-handler.ts

@@ -0,0 +1,154 @@
+/**
+ * project-trust-handler — the "human directly opens pi" safety net of Trust 2층
+ * (0.11 Stage 0, F5b/Trust 2층). It maps a single preflight outcome to pi's
+ * `project_trust` result so a human at a TUI gets a consistent decision, and —
+ * critically — provides the ONE escape from an inherited distrust: an active
+ * prompt whose "yes" writes a DIRECT child trust that beats the ancestor's false.
+ *
+ * This module is the HANDLER half; the controlled-launch (launcher) half does
+ * NOT go through here — a controlled launch short-circuits on pi's
+ * `trustOverride` (`--approve`) and never reaches `project_trust` at all (N3a).
+ * So the active-prompt escape is, by construction, human-interactive only; an
+ * agent cannot self-promote trust. That asymmetry is an intended security
+ * property, not a gap.
+ *
+ * Boundaries baked in (GLG 6 review points, 2026-06-10):
+ *  ① Single writer. This handler NEVER calls `store.set`. Returning
+ *     `{trusted:"yes", remember:true}` makes pi's `resolveProjectTrusted`
+ *     persist the decision (project-trust.js). A direct write here would be a
+ *     double-write + lock contention.
+ *  ② Every branch returns a value. `undefined` is forbidden — pi's runner reads
+ *     `result.trusted` and would throw. Cancel/ESC and the no answer both map to
+ *     a concrete result.
+ *  ③ Non-interactive is explicit. `pi -p` (mode "print") and the rpc/json modes
+ *     never get an active prompt; they return `undecided` so pi's own degraded
+ *     path decides (inherited false → deny). We do not lean on the UI adapter
+ *     happening to return undefined.
+ *  ④ ctx.ui injection. The pure core `decideProjectTrust(outcome, ctx, prompt)`
+ *     takes an injectable `prompt`; the adapter wires `ctx.ui.select` to it, so
+ *     the gate drives the matrix with a fake prompt and never opens a real pi UI.
+ *  ⑤ Alignment. The handler consumes ONLY the preflight outcome — it reads no
+ *     file under the cwd. `prefixRoots` is an operator-policy input (no package
+ *     default); tests inject a temp agentDir.
+ *  ⑥ Registration is the consumer's job — see createProjectTrustHandler.
+ */
+
+import type {
+	ProjectTrustContext,
+	ProjectTrustEventResult,
+	ProjectTrustHandler,
+} from "@earendil-works/pi-coding-agent";
+
+// ExtensionMode is not a public root export; recover it from the public
+// ProjectTrustContext rather than reaching into a private subpath (frozen
+// decision 9). = "tui" | "rpc" | "json" | "print".
+type ExtensionMode = ProjectTrustContext["mode"];
+
+// Explicit `.ts` extension (NOT `.js`): Node's strip-types resolver — which runs
+// the gates and the bridges — resolves `.ts` specifiers literally, but refuses
+// to substitute a `.ts` for a `.js` specifier (root tsconfig note). A lib→lib
+// VALUE import therefore has to be `.ts` to be runnable under strip-types. Same
+// fence as mcp/entwurf-bridge → entwurf-core.ts and meta-bridge-hook.ts → its
+// lib: this file is excluded from the emit-capable root tsconfig (which can't
+// allow .ts extensions) and typechecked by scripts/tsconfig.json instead.
+import { formatPreflightDenial, type PreflightDenial, type PreflightOutcome, preflight } from "./entwurf-preflight.ts";
+
+/** The human's answer to the inherited-distrust escape prompt. */
+export type ActivePromptChoice = "trust-here" | "no" | "cancel";
+/** Injectable prompt — the adapter wires this to `ctx.ui.select`. */
+export type ActivePrompt = (denial: PreflightDenial) => Promise<ActivePromptChoice>;
+
+/** Selector labels — also the gate's fake-prompt contract. */
+export const TRUST_HERE_LABEL = "Trust this folder only";
+export const KEEP_DISTRUSTED_LABEL = "Keep it distrusted";
+
+/**
+ * Interactive = a human is at a TUI and can actually answer. "rpc"/"json" are
+ * programmatic and "print" is `pi -p` (headless) — never actively prompt there.
+ */
+function isInteractive(mode: ExtensionMode, hasUI: boolean): boolean {
+	return hasUI && mode === "tui";
+}
+
+/** The escape-prompt title (reuses F5a evidence) + the two selectable options. */
+export function formatActivePrompt(denial: PreflightDenial): { title: string; options: string[] } {
+	return { title: formatPreflightDenial(denial), options: [TRUST_HERE_LABEL, KEEP_DISTRUSTED_LABEL] };
+}
+
+/**
+ * Pure mapping: preflight outcome → project_trust result. Never undefined (②),
+ * never persists (①). `prompt` is only invoked for the inherited-distrust escape
+ * while interactive.
+ */
+export async function decideProjectTrust(
+	outcome: PreflightOutcome,
+	ctx: { hasUI: boolean; mode: ExtensionMode },
+	prompt: ActivePrompt,
+): Promise<ProjectTrustEventResult> {
+	// approve / trusted-no-arg → yes, do NOT persist (prefix = policy SSOT, frozen
+	// decision 6: never dirty trust.json from a prefix auto-approve).
+	if (outcome.kind === "approve" || outcome.kind === "trusted-no-arg") {
+		return { trusted: "yes", remember: false };
+	}
+
+	if (outcome.reason === "saved-false") {
+		if (!outcome.trustStoreInherited) {
+			// Direct distrust on this cwd: say no, don't re-persist (already stored).
+			return { trusted: "no", remember: false };
+		}
+		// Inherited distrust: the ONLY escape is a human active prompt.
+		if (!isInteractive(ctx.mode, ctx.hasUI)) {
+			// ③ non-interactive: do not prompt. undecided → pi falls through to the
+			// store's inherited false = safe deny (pi -p degraded semantics).
+			return { trusted: "undecided" };
+		}
+		const choice = await prompt(outcome);
+		if (choice === "trust-here") {
+			// pi persists a DIRECT child true (single writer ①) which beats the
+			// inherited false (the escape direction proven in check-pi-preflight #13b).
+			return { trusted: "yes", remember: true };
+		}
+		if (choice === "no") {
+			// R3a: do not write a child false — the inherited false already covers it.
+			return { trusted: "no", remember: false };
+		}
+		// cancel / ESC → defer; the store's inherited false denies = safe (②).
+		return { trusted: "undecided" };
+	}
+
+	// fail-fast (undecided + trust inputs + no prefix root): defer to pi's OWN
+	// default prompt instead of actively prompting here. undecided lets pi prompt
+	// when interactive and returns false when headless — never undefined (②).
+	return { trusted: "undecided" };
+}
+
+export interface ProjectTrustHandlerOptions {
+	/** Operator-policy auto-approve roots (GLG ⑤ / frozen decision 7). No default. */
+	prefixRoots: readonly string[];
+	/** pi agent dir holding trust.json. Defaults to getAgentDir(); temp in tests. */
+	agentDir?: string;
+}
+
+/**
+ * Thin extension adapter (④/⑥): wires `event.cwd` → preflight and `ctx.ui.select`
+ * → the injectable prompt, then delegates to the pure core.
+ *
+ * Registration is the CONSUMER's job (agent-config), as a USER/GLOBAL extension:
+ * `project_trust` fires BEFORE project resources load, so a project-local
+ * registration (this repo's `package.json` `pi.extensions`) would load too late
+ * to be a safety net. The operator surface also supplies `prefixRoots` (frozen
+ * decision 7 — no package default).
+ */
+export function createProjectTrustHandler(opts: ProjectTrustHandlerOptions): ProjectTrustHandler {
+	return async (event, ctx: ProjectTrustContext): Promise<ProjectTrustEventResult> => {
+		const outcome = preflight({ cwd: event.cwd, agentDir: opts.agentDir, prefixRoots: opts.prefixRoots });
+		const prompt: ActivePrompt = async (denial) => {
+			const { title, options } = formatActivePrompt(denial);
+			const choice = await ctx.ui.select(title, options);
+			if (choice === TRUST_HERE_LABEL) return "trust-here";
+			if (choice === KEEP_DISTRUSTED_LABEL) return "no";
+			return "cancel"; // undefined (ESC) or any unexpected label
+		};
+		return decideProjectTrust(outcome, { hasUI: ctx.hasUI, mode: ctx.mode }, prompt);
+	};
+}

package/pi-extensions/lib/session-id.js

@@ -0,0 +1,57 @@
+/**
+ * session-id — garden-native session id SSOT (`YYYYMMDDTHHMMSS-[0-9a-f]{6}`).
+ *
+ * Authored as `.js` for the exact reason protocol.js is (see its header): this
+ * leaf is imported from BOTH runtime paths —
+ *   - tsc-emit path: pi-extension `.ts` files under the root tsconfig (allowJs),
+ *   - `node --experimental-strip-types` path: pure unit gates (check-meta-session,
+ *     new-session-id) that import a lib with a literal specifier.
+ * strip-types does not substitute `.ts` for a literal `.js` import specifier, and
+ * the root config cannot enable `allowImportingTsExtensions` without losing the
+ * tsc emit that check-models relies on. A real `.js` leaf resolves identically in
+ * every path, so the id grammar has ONE definition instead of one-per-importer.
+ *
+ * Keep dependency-free except `node:crypto`. The validator/grammar here is the
+ * same one the 0.9.0 resident garden guard and entwurf spawn collision pre-check
+ * enforce — do NOT fork it.
+ */
+
+import { randomBytes } from "node:crypto";
+
+/** `YYYYMMDDTHHMMSS-[0-9a-f]{6}`. Anchored; no surrounding slop. */
+export const SESSION_ID_RE = /^\d{8}T\d{6}-[0-9a-f]{6}$/;
+
+/**
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isValidSessionId(value) {
+	return typeof value === "string" && SESSION_ID_RE.test(value);
+}
+
+/**
+ * Local (KST on operator machines) denote-style timestamp `YYYYMMDDTHHMMSS`.
+ * Garden sort sense. Local components on purpose — the denote corpus is local.
+ *
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function formatSessionTimestamp(now = new Date()) {
+	const p = (n, w = 2) => String(n).padStart(w, "0");
+	return (
+		`${p(now.getFullYear(), 4)}${p(now.getMonth() + 1)}${p(now.getDate())}` +
+		`T${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`
+	);
+}
+
+/**
+ * Durable garden sessionId minted at the session's true birth. 6 hex suffix
+ * defeats same-second parallel-spawn collision; callers that spawn still
+ * header-scan pre-check (assertSessionIdAvailableForSpawn).
+ *
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function generateSessionId(now = new Date()) {
+	return `${formatSessionTimestamp(now)}-${randomBytes(3).toString("hex")}`;
+}

package/pi-extensions/lib/socket-discovery.ts

@@ -0,0 +1,346 @@
+/**
+ * socket-discovery — the SOCKET-axis wiring for the fact-provider (0.11 Stage 0
+ * step 4, slice 3). Turns the control-socket directory + the in-domain citizen
+ * list into the `SocketProbe[]` that `resolveFactList` (slice 2) consumes.
+ *
+ * Why a probe per in-domain citizen, not just a directory listing: slice 2's
+ * frozen invariant is that EVERY in-domain (pi) citizen must arrive PROBED — a
+ * dormant citizen whose socket file is gone must read as `dead` (ENOENT =
+ * positive proof of absence) so it routes dormant→resumable, never as an
+ * unprobed `null`/`indeterminate` that would strand it (resolveFactList throws
+ * on an unprobed in-domain citizen). So we probe the union of
+ *   (sockets present in the dir) ∪ (every in-domain citizen's canonical path):
+ * a dir-present socket yields alive / indeterminate / dead; a citizen with no
+ * file yields `dead` via ENOENT. Three-valued throughout (`probeSocketLiveness`)
+ * — an indeterminate stall is NEVER folded to dead (F3). This is exactly why we
+ * cannot reuse the legacy `getLiveSessions` (alive-only listing): folding the
+ * hidden indeterminate/dead sockets into "absent" would resurrect the F3 split.
+ *
+ * This slice fills the LIVENESS axis and, for live sockets, best-effort runtime
+ * enrich via the control RPC `get_info` (cwd / model / idle). `SocketProbe`'s
+ * enrich fields remain nullable-by-design: a dead/indeterminate socket or a
+ * failed enrich is HONEST, not synthetic, and carries `infoError` when known.
+ *
+ * Three socket-axis hazards are surfaced (slice 4c, Fable 검수), never swallowed:
+ *   - SYMLINK (P1, security): a `<gid>.sock` that is a symlink can redirect to
+ *     another session's listener, so gid X would probe ALIVE on Y's socket — a
+ *     forgery of 동결결정3's correlation authority (the socket filename = the gid).
+ *     The legacy bridge `getLiveSessions` guarded this (`entry.isSymbolicLink()`);
+ *     deriving the listing from facts would drop that guard unless we re-assert it
+ *     here. A symlinked socket is NEVER probed: a citizen owning one is forced to
+ *     `dead` (→ dormant → resume a fresh process, never SEND to a hijacked
+ *     listener); a record-less one is quarantined out of the listing entirely.
+ *     Both surface as `symlinkedGardenIds`.
+ *   - MALFORMED NAME (P3): a `*.sock` whose stem is not a garden id has no citizen
+ *     to correlate to and is dropped — but VISIBLY (`malformedNames`), not
+ *     silently (the legacy path listed any non-empty name; a silent regex drop
+ *     would violate "no silent drops").
+ *   - DIR-READ ERROR (P2e②): a missing dir (ENOENT) is the normal fresh-install
+ *     empty; ANY OTHER readdir failure (EACCES, …) is asymmetric loss of the whole
+ *     socket axis and is surfaced as `dirError`, not catch-all'd to empty (which
+ *     would silently vanish every socket-only session). When the dir is untrusted
+ *     this way, in-domain citizens are NOT probed (a non-ENOENT readdir failure
+ *     means we cannot confirm the canonical path is not a symlink, and `connect()`
+ *     would follow one) — they are reported `indeterminate` (liveness unknown),
+ *     held not stranded: once the dir reads again they route normally (GPi Q2/P1).
+ * The provider (slice 4b) folds these three into kind-tagged `EntwurfDiagnostic`s;
+ * this lib only reports the raw facts so the import stays one-way (provider →
+ * socket-discovery, never back).
+ *
+ * Deps (dir / readdir / probe) are injectable so the gate drives it without IO.
+ */
+
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fetchControlSocketRuntimeInfo, formatRuntimeModel } from "./entwurf-control-rpc.ts";
+import type { SocketProbe } from "./entwurf-facts.ts";
+import { SESSION_ID_RE } from "./session-id.js";
+import { probeSocketLiveness, type SocketLiveness } from "./socket-probe.ts";
+
+/** Canonical control-socket directory; the socket filename IS the gardenId
+ * (동결결정3 correlation authority). */
+export const CONTROL_SOCKET_DIR = path.join(os.homedir(), ".pi", "entwurf-control");
+export const SOCKET_SUFFIX = ".sock";
+
+// A control-socket filename is a bare garden id. We reuse the repo-wide
+// `SESSION_ID_RE` SSOT (not a local copy): 동결결정3 makes the socket filename the
+// correlation authority, which only holds if the socket axis and the meta-record
+// axis speak the SAME id grammar — a drifted local regex would silently drop a
+// legitimate gid's socket from the scan. A malformed name has no citizen to
+// correlate to and is ignored.
+
+export function controlSocketPath(gardenId: string, dir: string = CONTROL_SOCKET_DIR): string {
+	return path.join(dir, `${gardenId}${SOCKET_SUFFIX}`);
+}
+
+/**
+ * Target-specific control-socket inspection for the v2 decider (？2 — lstat-then-
+ * connect). The listing scan (`scanSocketProbes`) reads readdir dirents; a dispatch
+ * decision needs a fresh, single-target lstat UNDER the per-gid lock so a symlink
+ * planted between listing and dispatch cannot forge an alive liveness and hijack a
+ * control-socket send (the P1 reopening `probeSocketLiveness`-alone would allow,
+ * since it is connect-only and follows symlinks). This helper NEVER connects — it
+ * only classifies the canonical path's type so the decider can decide whether a
+ * probe is even safe:
+ *   - `absent` (ENOENT only)            → in-domain ⇒ dead (dormant)
+ *   - `socket-file`                     → safe to probe (connect) now
+ *   - `address-conflict` (symlink OR    → reject `target-address-conflict` (the gid
+ *      not-a-socket)                       resolves to a forged/corrupt address)
+ *   - `indeterminate` (EACCES/unknown)  → not provably absent, never connect, no spawn
+ * Every variant carries `socketPath` so the decider plants the SAME path into the
+ * plan (no re-derivation — 4c SSOT). `lstatFn` is injectable so the gate drives
+ * every branch without a real filesystem; the default is `fs.lstat` (which, unlike
+ * connect, does NOT follow the final symlink — that is the whole point).
+ */
+export type TargetSocketInspection =
+	| { kind: "absent"; socketPath: string }
+	| { kind: "socket-file"; socketPath: string }
+	| { kind: "address-conflict"; socketPath: string; reason: "symlink" | "not-socket" }
+	| { kind: "indeterminate"; socketPath: string; error: string };
+
+/**
+ * A1 narrow (0.11.0): does this PROBE-FREE single-lstat inspection of a gid's canonical
+ * control socket mean a record-LESS pi endpoint is addressable as a socket-only target?
+ * TRUE only for a confirmed NON-SYMLINK socket file (`socket-file`); a symlinked /
+ * absent / not-socket / `indeterminate` path is conservatively NOT promoted (never trust a
+ * symlink, never claim a target on an unprovable lstat). Shared by the v2 production
+ * `resolveTarget` so the socket-only acceptance uses the SAME lstat classification the
+ * listing/conflict paths use — listing↔dispatch cannot drift on what counts as a real
+ * control socket. The decider still does its own under-lock `inspectSocket` probe; this is
+ * only the presence hint that promotes `bad-target` → fire-and-forget socket-only pi.
+ */
+export function isSocketOnlyPiCandidate(inspection: TargetSocketInspection): boolean {
+	return inspection.kind === "socket-file";
+}
+
+export interface LstatLike {
+	isSymbolicLink(): boolean;
+	isSocket(): boolean;
+}
+
+/**
+ * Inspect the EXACT control-socket path given (no gid re-derivation) and classify it by
+ * lstat alone. This is the path-addressed core of the inspection: the 5c-3 spawn-bg watcher
+ * observes `plan.expectedSocketPath` and MUST inspect that exact path (its contract forbids
+ * re-deriving a path from the gid), so the path-taking form is the SSOT and
+ * `inspectTargetControlSocket` is the thin gid→path wrapper over it. `lstatFn` is injectable
+ * so the gate drives every branch without a real filesystem; the default is `fs.lstat`
+ * (which, unlike connect, does NOT follow the final symlink — that is the whole point: a
+ * symlink is caught as an address-conflict and never connected, P1).
+ */
+export async function inspectControlSocketPath(
+	socketPath: string,
+	lstatFn: (p: string) => Promise<LstatLike> = (p) => fs.lstat(p),
+): Promise<TargetSocketInspection> {
+	let st: LstatLike;
+	try {
+		st = await lstatFn(socketPath);
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return { kind: "absent", socketPath };
+		// EACCES / unknown: not provably absent, so never treat as dead-and-spawn.
+		return { kind: "indeterminate", socketPath, error: code ?? "unknown lstat error" };
+	}
+	// lstat does NOT dereference the final component — a symlink is caught HERE and
+	// never connected (P1). A non-socket regular file / dir / fifo at the canonical
+	// path is address corruption, not a live socket.
+	if (st.isSymbolicLink()) return { kind: "address-conflict", socketPath, reason: "symlink" };
+	if (st.isSocket()) return { kind: "socket-file", socketPath };
+	return { kind: "address-conflict", socketPath, reason: "not-socket" };
+}
+
+/**
+ * The gid-addressed inspection (？2 — lstat-then-connect, v2 decider helper): derive the
+ * canonical control-socket path for `gardenId` and inspect it. A thin wrapper over
+ * `inspectControlSocketPath` so the decider's gid-keyed path and the watcher's exact-path
+ * observation share ONE lstat classifier (no drift in the P1 symlink guard).
+ */
+export async function inspectTargetControlSocket(
+	gardenId: string,
+	dir: string = CONTROL_SOCKET_DIR,
+	lstatFn: (p: string) => Promise<LstatLike> = (p) => fs.lstat(p),
+): Promise<TargetSocketInspection> {
+	return inspectControlSocketPath(controlSocketPath(gardenId, dir), lstatFn);
+}
+
+/**
+ * Map a target's socket inspection to a measured `SocketLiveness` (to feed
+ * resolveDispatch) or a pre-probe address-conflict signal. `absent` (ENOENT only) is
+ * the honest `dead` (the citizen is dormant; its canonical socket is the path a resume
+ * will create). `socket-file` is the only case that connects. `address-conflict`
+ * (symlink / not-a-socket) and `indeterminate` never connect.
+ *
+ * Shared SSOT for the v2 decider (5b, decideDispatch) AND the dead-control-send
+ * fallback resolver (5c-2b): both must map an inspection the SAME way, or one could
+ * route a stalled socket where the other reclaims it — exactly the F3 split this lib
+ * exists to prevent. A per-caller copy would drift; this is the single mapper.
+ */
+export async function mapInspectionToLiveness(
+	inspection: TargetSocketInspection,
+	probeSocket: (socketPath: string) => Promise<SocketLiveness>,
+): Promise<{ liveness: SocketLiveness; socketPath: string } | { addressConflict: true }> {
+	switch (inspection.kind) {
+		case "absent":
+			return { liveness: "dead", socketPath: inspection.socketPath };
+		case "socket-file": {
+			const liveness = await probeSocket(inspection.socketPath);
+			return { liveness, socketPath: inspection.socketPath };
+		}
+		case "indeterminate":
+			return { liveness: "indeterminate", socketPath: inspection.socketPath };
+		case "address-conflict":
+			return { addressConflict: true };
+	}
+}
+
+/** One control-socket directory entry, with the single bit the scan needs from
+ * the filesystem beyond its name: whether it is a symlink (P1 forgery guard).
+ * The real wiring maps `fs.readdir(dir, {withFileTypes:true})` Dirents to this. */
+export interface SocketDirEntry {
+	name: string;
+	isSymbolicLink: boolean;
+}
+
+export interface SocketRuntimeInfo {
+	cwd: string | null;
+	model: string | null;
+	idle: boolean | null;
+}
+
+export interface SocketScanDeps {
+	dir: string;
+	readdir: (dir: string) => Promise<SocketDirEntry[]>;
+	probe: (socketPath: string) => Promise<SocketLiveness>;
+	/** Best-effort live-socket runtime enrich. Called only when liveness === "alive". */
+	getInfo: (socketPath: string) => Promise<SocketRuntimeInfo>;
+}
+
+/**
+ * The socket axis result. `probes` is the listing input to `resolveFactList`;
+ * the other three are surfaced hazards (see the module header) the provider folds
+ * into diagnostics — never hidden.
+ */
+export interface SocketScanResult {
+	probes: SocketProbe[];
+	/** gid-shaped `*.sock` symlinks: quarantined from probing (P1). */
+	symlinkedGardenIds: string[];
+	/** `*.sock` names that are not garden ids: visibly dropped (P3). */
+	malformedNames: string[];
+	/** non-ENOENT readdir failure: socket axis lost, surfaced not swallowed (P2e②). */
+	dirError: string | null;
+}
+
+/**
+ * Probe the union of (control sockets present in `dir`) ∪ (`piCitizenGardenIds`)
+ * and return one `SocketProbe` per gardenId (liveness + live get_info enrich), plus
+ * the three surfaced hazards. A missing directory (ENOENT) is the normal empty
+ * (`dirError=null`) — the in-domain citizens are still probed (their absent
+ * canonical paths read `dead`); any OTHER readdir failure sets `dirError`. A
+ * symlinked `*.sock` is never probed (P1): a citizen owning one is forced `dead`,
+ * a record-less one is dropped from `probes` entirely. Output sorted by gardenId.
+ */
+export async function scanSocketProbes(
+	piCitizenGardenIds: readonly string[],
+	deps: Partial<SocketScanDeps> = {},
+): Promise<SocketScanResult> {
+	const dir = deps.dir ?? CONTROL_SOCKET_DIR;
+	const readdir =
+		deps.readdir ??
+		(async (d: string): Promise<SocketDirEntry[]> => {
+			const dirents = await fs.readdir(d, { withFileTypes: true });
+			return dirents.map((e) => ({ name: e.name, isSymbolicLink: e.isSymbolicLink() }));
+		});
+	const probe = deps.probe ?? ((p: string) => probeSocketLiveness(p));
+	// Deterministic gates commonly inject fake readdir/probe over fake paths. In that
+	// case, default enrich must stay no-op unless the test explicitly injects getInfo.
+	// Real production calls inject neither readdir nor probe, so they get live RPC
+	// enrich by default.
+	const getInfo =
+		deps.getInfo ??
+		(deps.readdir || deps.probe
+			? async (): Promise<SocketRuntimeInfo> => ({ cwd: null, model: null, idle: null })
+			: getRuntimeInfoOverControlSocket);
+
+	let entries: SocketDirEntry[] = [];
+	let dirError: string | null = null;
+	try {
+		entries = await readdir(dir);
+	} catch (err) {
+		// ENOENT = fresh install / no sessions yet = the normal empty. Anything else
+		// (EACCES, EIO, …) is real loss of the socket axis — surface it, don't hide it.
+		const code = (err as NodeJS.ErrnoException)?.code;
+		if (code !== "ENOENT") {
+			dirError = err instanceof Error ? err.message : String(err);
+		}
+		entries = [];
+	}
+
+	const socketGids = new Set<string>();
+	const symlinkedGardenIds: string[] = [];
+	const malformedNames: string[] = [];
+	for (const entry of entries) {
+		if (!entry.name.endsWith(SOCKET_SUFFIX)) continue;
+		const gid = entry.name.slice(0, -SOCKET_SUFFIX.length);
+		if (!SESSION_ID_RE.test(gid)) {
+			malformedNames.push(entry.name);
+			continue;
+		}
+		if (entry.isSymbolicLink) {
+			// Never trust a symlinked socket: it can point at another session's
+			// listener and forge an `alive` for this gid (동결결정3 authority forgery).
+			symlinkedGardenIds.push(gid);
+			continue;
+		}
+		socketGids.add(gid);
+	}
+	const symlinkSet = new Set(symlinkedGardenIds);
+
+	// A non-ENOENT readdir failure means the dir is untrusted: we could not enumerate
+	// it, so we cannot confirm a canonical path is not a symlink. connect() follows
+	// symlinks, so probing here would defeat the P1 guard — hold every citizen at
+	// `indeterminate` instead (the socket-dir-read-error diagnostic carries the why).
+	const dirUntrusted = dirError !== null;
+	const allGids = [...new Set([...socketGids, ...piCitizenGardenIds])].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+	const probes: SocketProbe[] = [];
+	for (const gardenId of allGids) {
+		// A citizen whose canonical socket is a symlink is forced `dead` (→ dormant →
+		// resume a fresh process) rather than probed through the untrusted link. A
+		// record-less symlink gid is not in `allGids` at all (dropped above).
+		let liveness: SocketLiveness;
+		if (symlinkSet.has(gardenId)) {
+			liveness = "dead";
+		} else if (dirUntrusted) {
+			liveness = "indeterminate";
+		} else {
+			liveness = await probe(controlSocketPath(gardenId, dir));
+		}
+		let cwd: string | null = null;
+		let model: string | null = null;
+		let idle: boolean | null = null;
+		let infoError: string | null = null;
+		if (liveness === "alive") {
+			try {
+				const info = await getInfo(controlSocketPath(gardenId, dir));
+				cwd = info.cwd;
+				model = info.model;
+				idle = info.idle;
+			} catch (err) {
+				infoError = err instanceof Error ? err.message : String(err);
+			}
+		}
+		probes.push({ gardenId, liveness, cwd, model, idle, infoError });
+	}
+	symlinkedGardenIds.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+	malformedNames.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+	return { probes, symlinkedGardenIds, malformedNames, dirError };
+}
+
+async function getRuntimeInfoOverControlSocket(socketPath: string): Promise<SocketRuntimeInfo> {
+	const info = await fetchControlSocketRuntimeInfo(socketPath, { timeout: 1500 });
+	return {
+		cwd: info.cwd ?? null,
+		model: formatRuntimeModel(info) ?? null,
+		idle: info.idle ?? null,
+	};
+}

package/pi-extensions/lib/socket-probe.ts

@@ -0,0 +1,92 @@
+/**
+ * socket-probe — single source of truth for control-socket liveness.
+ *
+ * Why this is a shared lib (not a per-file copy): the entwurf-control
+ * extension (`pi-extensions/entwurf-control.ts`) AND the MCP bridge
+ * (`mcp/entwurf-bridge/src/index.ts`) both probe `~/.pi/entwurf-control/*.sock`.
+ * They used to carry independent `isSocketAlive` copies. If only one side
+ * learned the three-valued classification the two probes would diverge — the
+ * bridge routes a timeout target one way (mailbox fallback) while the
+ * extension's GC reclaims the same socket. Both now consume this module so the
+ * liveness semantics are identical on every surface. (0.11 Stage 0 step 4
+ * plans a probe lib extraction anyway; this is its first slice.)
+ *
+ * Three-valued, not boolean — the F3 fix. A connect probe can mean three
+ * different things, and collapsing them to a boolean is what let
+ * `gcStaleSockets` permanently unlink a *live* socket that merely stalled
+ * under load (→ every later probe sees it as dormant → live-session resume =
+ * identity split). The cure: never destroy a socket we do not understand.
+ *   - alive          → a listener accepted the connection (positive proof)
+ *   - dead           → ECONNREFUSED / ENOENT only (positive proof of absence)
+ *   - indeterminate  → timeout, EACCES, or any other/unknown error
+ *                      (no proof either way — keep the file, hide from listing)
+ */
+
+import * as net from "node:net";
+
+export type SocketLiveness = "alive" | "dead" | "indeterminate";
+
+export const DEFAULT_PROBE_TIMEOUT_MS = 300;
+
+/**
+ * Pure classification of a connect-time error code into liveness. Only the two
+ * codes that unambiguously mean "no live listener at this path" are dead:
+ * ECONNREFUSED (socket file exists, nothing listening) and ENOENT (no socket
+ * file). EVERYTHING else — EACCES, ETIMEDOUT, an undefined code, an unknown
+ * code — is indeterminate. The default direction matters: when we don't know,
+ * we do not destroy. (동결결정: "ECONNREFUSED/ENOENT만 dead", taken literally.)
+ */
+export function classifyConnectError(code: string | undefined): "dead" | "indeterminate" {
+	return code === "ECONNREFUSED" || code === "ENOENT" ? "dead" : "indeterminate";
+}
+
+/**
+ * GC policy: a stale-socket sweep may reclaim ONLY a demonstrably dead socket.
+ * An indeterminate probe (timeout / unknown error) must survive the sweep —
+ * reclaiming it is exactly the F3 live-session split. Alive obviously survives.
+ */
+export function shouldUnlinkOnGc(liveness: SocketLiveness): boolean {
+	return liveness === "dead";
+}
+
+/**
+ * Listing policy: a session appears in the live listing only on a positive
+ * connect. Indeterminate is hidden from the listing (preserving the prior
+ * boolean listing semantics) but — unlike GC — is NOT unlinked. dead is hidden
+ * too. This keeps "what GC reclaims" strictly narrower than "what is listed".
+ */
+export function shouldListAsLive(liveness: SocketLiveness): boolean {
+	return liveness === "alive";
+}
+
+/**
+ * Probe a control socket and classify it. Positive connect → alive; a
+ * connect-time error is routed through `classifyConnectError`; a connect that
+ * neither connects nor errors within `timeoutMs` → indeterminate (the load
+ * stall case F3 is about — never coerced to dead).
+ */
+export async function probeSocketLiveness(
+	socketPath: string,
+	opts: { timeoutMs?: number } = {},
+): Promise<SocketLiveness> {
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+	return await new Promise<SocketLiveness>((resolve) => {
+		const socket = net.createConnection(socketPath);
+		const timer = setTimeout(() => {
+			socket.destroy();
+			resolve("indeterminate");
+		}, timeoutMs);
+		const settle = (liveness: SocketLiveness) => {
+			clearTimeout(timer);
+			socket.removeAllListeners();
+			resolve(liveness);
+		};
+		socket.once("connect", () => {
+			socket.end();
+			settle("alive");
+		});
+		socket.once("error", (err: NodeJS.ErrnoException) => {
+			settle(classifyConnectError(err.code));
+		});
+	});
+}