@junghanacs/entwurf 0.12.0

package/pi-extensions/lib/entwurf-peers-render.ts

@@ -0,0 +1,154 @@
+/**
+ * entwurf-peers-render — the PURE render/payload layer for the MCP `entwurf_peers`
+ * surface (0.11 Stage 0 step 4, slice 4c). The MCP handler stays thin: it does IO
+ * (readdir the meta-store + probe sockets via `listEntwurfFacts`) and then calls
+ * THIS to shape the text + JSON. No IO here, so the gate drives it without a
+ * filesystem and the SAME facts can feed pi-native / doctor / v2 dispatch later
+ * (a handler that did its own brain work would deny them that reuse).
+ *
+ * Three hard rules carried from the frozen contract (동결결정 10):
+ *   - FACTS ONLY, NO VERB-ROUTING. Neither the payload nor the text may carry a
+ *     `sendable`/`resumable`/`dispatch`/`action`/`transport`/`mailboxDeliverable`
+ *     field or word. Whether a target is sent-to or resumed is computed at call
+ *     time by the entwurf_v2 dispatch table from `liveness` — baking it into the
+ *     listing is exactly what makes `entwurf_peers` lie. The gate scans both the
+ *     JSON keys AND the text for the forbidden words (a section title like
+ *     "resumable peers" leaks routing that a key scan would miss).
+ *   - THREE SECTIONS, NEVER MERGED. `peers` (citizens, 4-value liveness) and
+ *     `socketOnly` (record-less sockets, 3-value liveness) are DISTINCT subjects
+ *     (slice 2's two-array split); `diagnostics` is a third. Merging them into one
+ *     array collapses the subject separation at the surface.
+ *   - LEGACY `sessions` IS A PROJECTION OF FACTS, not a second scan. We do NOT
+ *     re-run the old `getLiveSessions` (a separate live-socket scan would bypass
+ *     the provider's quarantine — a non-pi citizen colliding with a socket, which
+ *     `listEntwurfFacts` removes from BOTH normal arrays, could reappear in
+ *     `sessions`). `sessions` is derived from the SAME facts: alive pi citizens +
+ *     alive socket-only entries. Its socketPath is built by `controlSocketPath`
+ *     (the SSOT helper), never re-concatenated, so the filename↔gardenId
+ *     correlation authority (동결결정3) cannot drift between scan and render.
+ */
+
+import type { EntwurfDiagnostic, EntwurfFactsResult } from "./entwurf-fact-provider.ts";
+import type { PeerFact, SocketOnlyFact } from "./entwurf-facts.ts";
+import { controlSocketPath } from "./socket-discovery.ts";
+
+/** The legacy-compatible active-session shape (sessionId + socketPath), retained
+ * for old consumers. A PROJECTION of the facts (alive only), not a second scan. */
+export interface LegacySession {
+	sessionId: string;
+	socketPath: string;
+}
+
+/** The full `entwurf_peers` JSON payload. `sessions` is the legacy projection;
+ * `peers`/`socketOnly`/`diagnostics` are the additive facts surface. NO
+ * verb-routing field anywhere (the gate enforces this by deep key scan). */
+export interface EntwurfPeersPayload {
+	controlDir: string;
+	count: number;
+	sessions: LegacySession[];
+	peers: PeerFact[];
+	socketOnly: SocketOnlyFact[];
+	diagnostics: EntwurfDiagnostic[];
+}
+
+export interface EntwurfPeersRender {
+	text: string;
+	payload: EntwurfPeersPayload;
+}
+
+/**
+ * Derive the legacy `sessions` projection from the facts: an active session is an
+ * alive pi citizen OR an alive record-less socket. `peers` and `socketOnly` are
+ * gid-disjoint (resolveFactList guarantees a gid is in one or the other, never
+ * both), so the concatenation needs no dedup. socketPath via `controlSocketPath`
+ * (SSOT). Sorted by sessionId for determinism.
+ */
+function deriveSessions(peers: PeerFact[], socketOnly: SocketOnlyFact[], controlDir: string): LegacySession[] {
+	const sessions: LegacySession[] = [];
+	for (const p of peers) {
+		if (p.backend === "pi" && p.liveness === "alive") {
+			sessions.push({ sessionId: p.gardenId, socketPath: controlSocketPath(p.gardenId, controlDir) });
+		}
+	}
+	for (const s of socketOnly) {
+		if (s.liveness === "alive") {
+			sessions.push({ sessionId: s.gardenId, socketPath: controlSocketPath(s.gardenId, controlDir) });
+		}
+	}
+	sessions.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0));
+	return sessions;
+}
+
+function renderPeerLine(p: PeerFact): string {
+	const model = p.model ?? "(unknown)";
+	const entwurf = p.isEntwurf ? " entwurf" : "";
+	return `- ${p.gardenId}  backend=${p.backend}  liveness=${p.liveness}  cwd=${p.cwd}  model=${model}${entwurf}`;
+}
+
+function renderSocketOnlyLine(s: SocketOnlyFact): string {
+	// Null enrich is "(not enriched)" — NOT "(unknown)", which would read as
+	// identity-unknown rather than not-yet-fetched / not available for this socket.
+	const cwd = s.cwd ?? "(not enriched)";
+	const model = s.model ?? "(not enriched)";
+	const idle = s.idle === null ? "" : `  idle=${s.idle ? "yes" : "no"}`;
+	const infoError = s.infoError === null ? "" : `  infoError=${s.infoError}`;
+	return `- ${s.gardenId}  liveness=${s.liveness}  cwd=${cwd}  model=${model}${idle}${infoError}`;
+}
+
+function renderDiagnosticLine(d: EntwurfDiagnostic): string {
+	switch (d.kind) {
+		case "meta-record-read-error":
+			return `- meta-record-read-error ${d.filename}: ${d.message}`;
+		case "garden-id-socket-conflict":
+			return `- garden-id-socket-conflict ${d.gardenId} (backend=${d.backend}): ${d.message}`;
+		case "socket-symlink-rejected":
+			return `- socket-symlink-rejected ${d.gardenId}: ${d.message}`;
+		case "malformed-socket-name":
+			return `- malformed-socket-name ${d.name}: ${d.message}`;
+		case "socket-dir-read-error":
+			return `- socket-dir-read-error: ${d.message}`;
+	}
+}
+
+function compactLines(lines: string[], max: number = 32): string[] {
+	if (lines.length <= max) return lines;
+	const omitted = lines.length - max;
+	return [`  … (${omitted} older entries omitted; showing latest ${max})`, ...lines.slice(-max)];
+}
+
+function section(title: string, lines: string[], opts: { compact?: boolean } = {}): string {
+	// Empty sections render "(none)" — hiding them would erase the honesty the
+	// listing exists to provide (especially diagnostics: "(none)" is a trust
+	// signal, and an `unsupported` peer must never be silently dropped).
+	const rendered = opts.compact ? compactLines(lines) : lines;
+	return rendered.length > 0 ? `${title}\n${rendered.join("\n")}` : `${title}\n  (none)`;
+}
+
+/**
+ * Shape the facts into the `entwurf_peers` text + JSON. Pure over its inputs.
+ * `controlDir` is the same directory the socket scan used — passing it here (not
+ * re-deriving) keeps the socketPath SSOT.
+ */
+export function renderEntwurfPeers(result: EntwurfFactsResult, controlDir: string): EntwurfPeersRender {
+	const { peers, socketOnly } = result.facts;
+	const { diagnostics } = result;
+	const sessions = deriveSessions(peers, socketOnly, controlDir);
+
+	const text = [
+		section("Garden citizens (meta-record):", peers.map(renderPeerLine), { compact: true }),
+		"",
+		section("Socket-only control sockets (no meta-record):", socketOnly.map(renderSocketOnlyLine), { compact: true }),
+		"",
+		section("Diagnostics:", diagnostics.map(renderDiagnosticLine)),
+	].join("\n");
+
+	const payload: EntwurfPeersPayload = {
+		controlDir,
+		count: sessions.length,
+		sessions,
+		peers,
+		socketOnly,
+		diagnostics,
+	};
+	return { text, payload };
+}

package/pi-extensions/lib/entwurf-preflight.ts

@@ -0,0 +1,247 @@
+/**
+ * entwurf-preflight — 0.11 Stage 0 (2): the SINGLE trust/launch decision owner.
+ *
+ * The controlled-launch surface, the global `project_trust` handler, and any
+ * MCP fact tool ALL consume this module's outcome — nobody else re-derives a
+ * prefix, re-reads `trust.json`, or re-probes trust inputs. pi's raw trust
+ * semantics are followed by importing pi's PUBLIC root exports directly (frozen
+ * decision 9, 재구현 금지): `ProjectTrustStore` (the canonical `trust.json`
+ * reader, which itself canonicalizes the cwd and takes a `proper-lockfile` on
+ * every read) and `hasTrustRequiringProjectResources` (the trust-input probe).
+ * We never copy pi's trust detail — if pi changes it, this import tracks it.
+ *
+ * The returned `PreflightOutcome` is deliberately RICH, not just {kind,reason}:
+ * a fact tool must explain *why* a cwd is approved and *what* it may load
+ * without re-running the probe, and an error/handler must name the matched root
+ * or the trust-store value. Thin outcomes would push callers to recompute, which
+ * is exactly the re-derivation this module exists to prevent.
+ *
+ * trust ≠ discovery: this decision touches the store for a SINGLE launch-time
+ * cwd only. `peers`/`who-can` discovery does not call here (frozen decision 4).
+ *
+ * Precedence (frozen decision 8) — saved distrust is stronger than a prefix
+ * allow; a prefix only promotes the UNDECIDED (null) case; no-trust-inputs is
+ * trusted but needs no launch arg; everything else is fail-fast:
+ *
+ *   saved === false        → deny           (explicit distrust; store wins)
+ *   saved === true         → approve        (saved trust → internal --approve)
+ *   null + prefix match    → approve        (operator prefix promotes null→yes)
+ *   null + no trust inputs → trusted-no-arg (no trust-gated input — pi 0.79.x
+ *                                             excludes AGENTS.md/CLAUDE.md, so
+ *                                             context files may still be loaded)
+ *   else (null + inputs)   → fail-fast      (unknown/untrusted controlled launch)
+ *
+ * Injection (frozen decision 4): `agentDir` defaults to `getAgentDir()` but is
+ * overridable so tests point `ProjectTrustStore` at a temp dir (or set
+ * `PI_CODING_AGENT_DIR`, same isolation as 0.10.0) and never read or dirty the
+ * operator's real `~/.pi/agent/trust.json`. `prefixRoots` is an OPERATOR-policy
+ * input with NO package default (frozen decision 7): a public package must not
+ * hardcode a broad auto-approve, so an empty roots list means "no prefix
+ * promotion" — the caller injects the operator's roots (e.g. `~/repos/gh`).
+ */
+
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import {
+	getAgentDir,
+	hasTrustRequiringProjectResources,
+	type ProjectTrustDecision,
+	ProjectTrustStore,
+} from "@earendil-works/pi-coding-agent";
+
+export interface PreflightInput {
+	/** The single launch-time cwd whose trust is being decided. */
+	cwd: string;
+	/**
+	 * pi agent dir holding `trust.json`. Defaults to `getAgentDir()` (which
+	 * honors `PI_CODING_AGENT_DIR`). Override to a temp dir for isolated tests.
+	 */
+	agentDir?: string;
+	/**
+	 * Operator-policy auto-approve roots. NO package default (frozen decision 7).
+	 * Roots may be `~`-relative (`~/repos/gh`) or relative; they are normalized
+	 * the same way as the cwd. A cwd at or under one of these (canonical path +
+	 * separator boundary) promotes an UNDECIDED trust into approve. Empty ⇒ no
+	 * prefix promotion.
+	 */
+	prefixRoots?: readonly string[];
+}
+
+/** Fields present on every outcome — the fact/handler/error evidence. */
+interface PreflightEvidence {
+	/**
+	 * Args the launcher must add. `["--approve"]` when approving, `[]` otherwise.
+	 * Frozen decision 6: never `--no-approve` (that is a silent degraded launch).
+	 */
+	readonly launchArgs: readonly string[];
+	/**
+	 * The trust decision that applies to this cwd: `ProjectTrustStore.getEntry(cwd)
+	 * ?.decision ?? null`. Identical value to the old `.get(cwd)`, but sourced from
+	 * `getEntry` so the deciding entry's path/inheritance survive (below).
+	 */
+	readonly trustStoreDecision: ProjectTrustDecision;
+	/**
+	 * The pi-canonical path of the trust-store entry that decided this cwd, or
+	 * undefined when neither the cwd nor any ancestor carries a decision
+	 * (trustStoreDecision === null). On 0.79.x `getEntry` walks up to the nearest
+	 * ancestor with an explicit decision and returns ITS path — so this is the
+	 * source a deny message must name (N3b `inheritedFrom`). pi-canonical =
+	 * `canonicalizePath(resolvePath())`, the same realpath axis as `canonicalCwd`.
+	 */
+	readonly trustStoreEntryPath?: string;
+	/**
+	 * True when the deciding entry is an ANCESTOR, not the cwd itself — the
+	 * decision is INHERITED (0.79.x nearest-ancestor walk-up). False for a direct
+	 * decision on the cwd or for no decision at all. The inherited-false case is
+	 * the one that silently blocks a human's active prompt (Trust 2층): the
+	 * handler defers `undecided`, then the store's inherited false wins anyway, so
+	 * only an active prompt → `{trusted:"yes", remember:true}` escapes it.
+	 */
+	readonly trustStoreInherited: boolean;
+	/** `hasTrustRequiringProjectResources(cwd)` — computed even when a prefix already won. */
+	readonly hasTrustInputs: boolean;
+	/** The canonical operator root that matched, if the decision is prefix-driven. */
+	readonly matchedPrefixRoot?: string;
+	/** The cwd after tilde-expand → resolve → realpath (raw-resolved fallback). */
+	readonly canonicalCwd: string;
+}
+
+/**
+ * Controlled-launch decision. The launcher maps:
+ *   approve         → spawn child with `launchArgs` (`--approve`; load project files)
+ *   trusted-no-arg  → spawn child, no `--approve` needed (no project files)
+ *   deny            → refuse to spawn (throw); never a silent `--no-approve`
+ */
+export type PreflightOutcome =
+	| (PreflightEvidence & { readonly kind: "approve"; readonly reason: "saved-true" | "prefix-match" })
+	| (PreflightEvidence & { readonly kind: "trusted-no-arg"; readonly reason: "no-trust-inputs" })
+	| (PreflightEvidence & { readonly kind: "deny"; readonly reason: "saved-false" | "fail-fast" });
+
+/** A deny outcome — the only shape `formatPreflightDenial` accepts. */
+export type PreflightDenial = Extract<PreflightOutcome, { kind: "deny" }>;
+
+/**
+ * Render the human-facing reason a controlled launch was refused (N3b). This is
+ * a PURE formatter over a deny outcome — it does NOT touch a launcher, a socket,
+ * or pi; wiring it into the controlled-launch surface is bucket B (step 5), not
+ * here. The launcher/handler/error layers all call this so the refusal text is
+ * identical everywhere and always sourced from F5a evidence.
+ *
+ * The inherited-false branch is the one that matters: an operator distrust on an
+ * ANCESTOR (e.g. `~/repos/gh`) silently denies a child cwd, and an agent CANNOT
+ * lift it — that is an intended security property (N3a: a controlled launch
+ * short-circuits on `trustOverride` and never reaches the human-only active
+ * prompt). So the message must (1) name the inherited source (`inheritedFrom`)
+ * and (2) give the only real remedy: open an interactive pi AT the cwd and
+ * approve, which writes a direct child trust that beats the inherited decision
+ * (the "escape direction" proven in check-pi-preflight #13b).
+ */
+export function formatPreflightDenial(outcome: PreflightDenial): string {
+	const cwd = outcome.canonicalCwd;
+	const openHere = `open an interactive pi at ${cwd} and approve when prompted`;
+	if (outcome.reason === "saved-false") {
+		if (outcome.trustStoreInherited && outcome.trustStoreEntryPath !== undefined) {
+			return (
+				`Controlled launch refused: ${cwd} is distrusted by inheritance from ${outcome.trustStoreEntryPath} ` +
+				`(an ancestor carries a saved "no"). An agent cannot self-promote trust — this is an intended ` +
+				`security property. To trust THIS cwd only, ${openHere}; that writes a direct decision for ${cwd} ` +
+				`which overrides the inherited one.`
+			);
+		}
+		return `Controlled launch refused: ${cwd} is explicitly distrusted (a saved "no" on this directory). To change it, ${openHere}.`;
+	}
+	// fail-fast: undecided + trust inputs + no operator prefix root.
+	return (
+		`Controlled launch refused: ${cwd} is untrusted — it has trust inputs but no saved decision and no ` +
+		`operator prefix root. Refusing a silent degraded launch. Either add ${cwd} under an operator prefix ` +
+		`root, or ${openHere}.`
+	);
+}
+
+/**
+ * Normalize a path the way pi resolves one before the trust store sees it:
+ * expand a leading `~`, make it absolute (`path.resolve`), then `realpathSync`;
+ * on a resolve failure fall back to the RESOLVED absolute path (not the raw
+ * input), so a not-yet-existing root still compares on an absolute basis.
+ */
+function normalizePath(p: string): string {
+	let expanded = p;
+	if (p === "~") {
+		expanded = homedir();
+	} else if (p.startsWith("~/")) {
+		expanded = join(homedir(), p.slice(2));
+	}
+	const abs = isAbsolute(expanded) ? expanded : resolve(expanded);
+	try {
+		return realpathSync(abs);
+	} catch {
+		return abs;
+	}
+}
+
+/**
+ * Return the canonical operator root that contains `canonicalCwd`, by canonical
+ * path + separator boundary (frozen decision 7). `/org` matches `/org/a` but NOT
+ * `/org2` — never a bare `startsWith`. Roots are normalized the same as the cwd.
+ */
+function matchedPrefixRoot(canonicalCwd: string, roots: readonly string[]): string | undefined {
+	for (const root of roots) {
+		const r = normalizePath(root);
+		if (canonicalCwd === r || canonicalCwd.startsWith(r + sep)) {
+			return r;
+		}
+	}
+	return undefined;
+}
+
+/** Decide trust for a single controlled-launch cwd. See module header. */
+export function preflight(input: PreflightInput): PreflightOutcome {
+	const agentDir = input.agentDir ?? getAgentDir();
+	const prefixRoots = input.prefixRoots ?? [];
+
+	const canonicalCwd = normalizePath(input.cwd);
+	const store = new ProjectTrustStore(agentDir);
+	// getEntry, not get: get() throws away which path decided. getEntry returns
+	// `{ path, decision } | null` — the nearest ancestor (or the cwd itself)
+	// carrying an explicit decision. We recover the same decision value AND the
+	// deciding path, so the fact/handler/error layers can name an inherited
+	// source without re-walking the store. entry.path is pi-canonical, the same
+	// realpath axis as `canonicalCwd`, so an entry on the cwd ITSELF compares
+	// equal (= direct) and an ancestor compares unequal (= inherited).
+	const entry = store.getEntry(input.cwd);
+	const trustStoreDecision: ProjectTrustDecision = entry?.decision ?? null;
+	const trustStoreInherited = entry !== null && entry.path !== canonicalCwd;
+	// Computed unconditionally: a fact tool must report what a prefix-approved
+	// cwd could load, so the probe runs even when a prefix already decides.
+	const hasTrustInputs = hasTrustRequiringProjectResources(input.cwd);
+	const matched = matchedPrefixRoot(canonicalCwd, prefixRoots);
+
+	const evidence: PreflightEvidence = {
+		launchArgs: [],
+		trustStoreDecision,
+		trustStoreInherited,
+		hasTrustInputs,
+		canonicalCwd,
+		...(entry !== null ? { trustStoreEntryPath: entry.path } : {}),
+		...(matched !== undefined ? { matchedPrefixRoot: matched } : {}),
+	};
+
+	// Explicit distrust wins over everything, including a prefix match.
+	if (trustStoreDecision === false) {
+		return { ...evidence, kind: "deny", reason: "saved-false" };
+	}
+	if (trustStoreDecision === true) {
+		return { ...evidence, kind: "approve", reason: "saved-true", launchArgs: ["--approve"] };
+	}
+
+	// trustStoreDecision === null (undecided): a prefix promotes it; otherwise the
+	// absence of trust inputs makes it trusted-but-no-arg; otherwise fail-fast.
+	if (matched !== undefined) {
+		return { ...evidence, kind: "approve", reason: "prefix-match", launchArgs: ["--approve"] };
+	}
+	if (!hasTrustInputs) {
+		return { ...evidence, kind: "trusted-no-arg", reason: "no-trust-inputs" };
+	}
+	return { ...evidence, kind: "deny", reason: "fail-fast" };
+}

package/pi-extensions/lib/entwurf-resume-args.ts

@@ -0,0 +1,88 @@
+/**
+ * entwurf-resume-args — the SINGLE source of truth for the `pi` argv a resume spawn is
+ * launched with (0.11 Stage 0 step 5c-3b). Two variants share this builder so the legacy
+ * async-entwurf worker and the v2 spawn-bg resident citizen can NEVER drift in their launch
+ * shape — the one place the `--no-extensions` / `--entwurf-control` decision lives.
+ *
+ * The load-bearing difference (A1):
+ *   - legacy — a one-shot async worker. `pi -p <prompt>` runs the resume turn and EXITS;
+ *     `proc.on('close')` then delivers the followUp. It is launched `--no-extensions` AND
+ *     WITHOUT `--entwurf-control` precisely BECAUSE a control-socket server would keep
+ *     `pi -p` from exiting (entwurf.ts:22 — that keep-alive was a bug for a one-shot worker).
+ *   - v2-control — a RESIDENT, addressable garden citizen. The resume turn STILL runs via
+ *     `-p <prompt>` (the prompt-as-turn authority is unchanged), but the child is launched
+ *     WITH `--entwurf-control` and WITHOUT `--no-extensions`, so the very keep-alive legacy
+ *     avoided is now the GOAL: the resumed session stands its control socket up and stays
+ *     live. The 5c-3a watcher's `socket-alive` is exactly that "resumed citizen is up and
+ *     addressable" observation (→ release the per-gid lock, child lives on); `child-exited`
+ *     is the early-exit/failure observation. `plan.launchArgs` (`--approve` or empty, from
+ *     the decider's preflight) rides along as pi flags before the prompt.
+ *
+ * Provider/model identity is the caller's existing authority (readSessionIdentity /
+ * getEntwurfExplicitExtensions) — this builder only LAYS OUT argv, it never resolves
+ * identity. `explicitExtensionArgs` is preserved verbatim in BOTH variants: a recorded
+ * `provider=entwurf` resume needs the bridge re-injected to resolve the provider, and
+ * dropping it when `--no-extensions` is removed would re-introduce the "Unknown provider"
+ * footgun (#29). (A future slice may dedup against settings-loaded extensions; not here.)
+ *
+ * This module is import-free on purpose: the legacy launcher (entwurf-async.ts) is
+ * root-typechecked and imports it as `./entwurf-resume-args.js`, while the v2 adapter and
+ * the gate import the same source — a self-contained string builder keeps both configs happy.
+ */
+
+export type ResumeArgsVariant = "legacy" | "v2-control";
+
+export interface ResumePiArgsInput {
+	/** legacy = one-shot worker (`--no-extensions`, no control socket); v2-control =
+	 * resident citizen (`--entwurf-control`, extensions loaded). */
+	variant: ResumeArgsVariant;
+	/** The garden id; `pi --session-id <gid>` resumes the existing JSONL AND, under
+	 * `--entwurf-control`, derives the control socket at ~/.pi/entwurf-control/<gid>.sock. */
+	sessionId: string;
+	/** The explicit `--extension …` re-injection (ACP bridge / provider resolution).
+	 * Preserved verbatim in BOTH variants — load-bearing for a entwurf resume. */
+	explicitExtensionArgs: readonly string[];
+	/** Recorded provider (may be null/undefined — then no `--provider` flag is emitted). */
+	provider: string | null | undefined;
+	/** The resolved launch model (caller applies `modelOverride ?? resumeModel`). */
+	model: string;
+	/** The resume prompt — the final positional, run as the model turn under `-p`. */
+	prompt: string;
+	/** v2-control ONLY: the decider's `plan.launchArgs` (`["--approve"]` or `[]`). Ignored
+	 * for legacy (the legacy path computes its own preflight elsewhere). */
+	launchArgs?: readonly string[];
+}
+
+/**
+ * Build the `pi` argv for a resume spawn. The SHARED prefix is `--mode json -p` (headless
+ * JSON child, prompt-as-turn); the variant then chooses the extension/socket posture; the
+ * SHARED suffix is `[…ext args] --session-id <gid> [--provider <p>] --model <m> <prompt>`.
+ *
+ * Invariants the gate pins:
+ *   - legacy  carries `--no-extensions` and NO `--entwurf-control`.
+ *   - v2-control carries `--entwurf-control` and NO `--no-extensions`, plus `-p` + prompt.
+ *   - `explicitExtensionArgs` appears exactly once in both.
+ *   - `launchArgs` is included for v2-control (before the suffix) and ignored for legacy.
+ *   - provider/model/prompt identity is laid out identically in both.
+ */
+export function buildResumePiArgs(input: ResumePiArgsInput): string[] {
+	const args: string[] = ["--mode", "json", "-p"];
+
+	if (input.variant === "legacy") {
+		// One-shot worker: no extensions, no control socket (so `pi -p` can exit).
+		args.push("--no-extensions");
+	} else {
+		// Resident citizen: stand the control socket up (A1) and keep extensions loaded.
+		// The keep-alive legacy avoided is the goal here. `--approve`/launchArgs ride along.
+		args.push("--entwurf-control");
+		args.push(...(input.launchArgs ?? []));
+	}
+
+	// Shared suffix — identical identity layout in both variants.
+	args.push(...input.explicitExtensionArgs);
+	args.push("--session-id", input.sessionId);
+	if (input.provider) args.push("--provider", input.provider);
+	args.push("--model", input.model, input.prompt);
+
+	return args;
+}

package/pi-extensions/lib/entwurf-self-address.ts

@@ -0,0 +1,117 @@
+/**
+ * entwurf-self-address — the PURE self-addressability predicate (SE-1/SE-2 slice 1).
+ *
+ * "Can a reply to THIS session actually land where its model will see it?"
+ *
+ * Today both the MCP bridge (buildStrictPiSenderEnvelope /
+ * buildTrustedMetaSenderEnvelope / entwurf_self) and pi-native answer that from env
+ * presence alone and hardcode `replyable: true`: a pi session with no
+ * --entwurf-control socket, or a meta citizen whose owner has exited / whose
+ * idle-watch was never armed, all claim replyable while delivery silently fails
+ * (SE-1: "all layers say yes, only delivery says no" = a Crash-Don't-Warn
+ * violation). This module is the single truth-table both surfaces compute from,
+ * with every fact INJECTED (no IO) so the gate can pin each row.
+ *
+ * Axes by origin:
+ *  - pi-session:  replyable ⟺ a live control socket exists at the canonical path.
+ *                 socketState distinguishes alive / expected (path computable but no
+ *                 live socket) / none (no session id to even compute a path).
+ *  - meta-session (self-fetch backend, e.g. claude-code): replyable ⟺ the 3-conjunct
+ *                 deliverability — recordBacked AND ownerAlive AND watchArmed (Q4-1
+ *                 lock: self-fetch(static) ∧ ownerPid-startKey-alive(runtime) ∧
+ *                 watch-armed(runtime)). The watchArmed FACT is sourced from the
+ *                 slice-2 meta-receiver presence marker; until that wiring lands the
+ *                 caller passes watchArmed=false, so meta-self is intentionally
+ *                 FAIL-CLOSED until slice 2. Slices 1 and 2 close in the SAME release
+ *                 block, so no intermediate "meta self all-false" state is ever pushed.
+ *  - external-mcp: never replyable — no authoritative reply address.
+ */
+
+import { computeMetaReceiverActive } from "./entwurf-deliverability.ts";
+
+export type SelfOrigin = "pi-session" | "meta-session" | "external-mcp";
+
+/**
+ * pi control-socket reachability for a reply addressed back to this session.
+ *
+ * NOTE on "alive": at this slice the caller establishes it with an existsSync on the
+ * canonical socket path — it means "the canonical control socket FILE is present",
+ * not "a listener is accepting connections". A stale socket file with a dead listener
+ * still reads as `alive` here. A real connect/probeSocketLiveness check is deliberate
+ * future hardening (a separate slice), kept out per the slice-1 existsSync-level
+ * agreement to avoid over-reach. Do not read `alive` as proven liveness.
+ */
+export type SocketState = "alive" | "expected" | "none";
+
+export interface SelfAddressabilityFacts {
+	origin: SelfOrigin;
+	/** pi-session: a live control socket exists at the canonical path (existsSync today). */
+	socketAlive?: boolean;
+	/** pi-session: a session id is present so the canonical socket path is computable. */
+	socketPathComputable?: boolean;
+	/** meta-session: the sender marker's identity is backed by a live meta-record. */
+	recordBacked?: boolean;
+	/** meta-session: the marker's owner pid is still the same process (start-key match). */
+	ownerAlive?: boolean;
+	/** meta-session: the idle-wake watch is armed (slice-2 presence marker; fail-closed until then). */
+	watchArmed?: boolean;
+}
+
+export interface SelfAddressabilityResult {
+	replyable: boolean;
+	socketState: SocketState;
+	reason: string;
+}
+
+/**
+ * Decide whether a reply to this session is actually deliverable, from injected
+ * facts only. Pure: no env reads, no fs, no probing — the caller gathers the facts
+ * (existsSync the socket, validate the marker against its record, read the presence
+ * marker) and hands them in, so every row is gate-pinnable.
+ */
+export function computeSelfAddressability(facts: SelfAddressabilityFacts): SelfAddressabilityResult {
+	switch (facts.origin) {
+		case "pi-session": {
+			if (facts.socketAlive === true) {
+				return { replyable: true, socketState: "alive", reason: "pi control socket alive at canonical path" };
+			}
+			if (facts.socketPathComputable === true) {
+				return {
+					replyable: false,
+					socketState: "expected",
+					reason: "pi control socket not found at expected path (session not run with --entwurf-control)",
+				};
+			}
+			return {
+				replyable: false,
+				socketState: "none",
+				reason: "no pi session id — cannot compute a control socket path",
+			};
+		}
+		case "meta-session": {
+			// Share the active-receiver atom with the deliverability predicate (one
+			// source of truth for "record backed AND owner alive AND watch armed").
+			const recv = computeMetaReceiverActive({
+				recordBacked: facts.recordBacked,
+				ownerAlive: facts.ownerAlive,
+				watchArmed: facts.watchArmed,
+			});
+			return {
+				replyable: recv.active,
+				socketState: "none",
+				reason: recv.active ? `meta receiver active (${recv.reason})` : `meta receiver inactive — ${recv.reason}`,
+			};
+		}
+		case "external-mcp":
+			return {
+				replyable: false,
+				socketState: "none",
+				reason: "external MCP host has no authoritative reply address",
+			};
+		default: {
+			// exhaustiveness — an unknown origin is a wiring bug; fail-closed.
+			const never: never = facts.origin;
+			return { replyable: false, socketState: "none", reason: `unknown origin: ${String(never)}` };
+		}
+	}
+}