@junghanacs/entwurf 0.12.9 → 0.13.0

package/pi-extensions/lib/acp/models.ts

@@ -1,14 +1,17 @@
-// ACP plugin — curated Claude model surface (S0 loader/fence slice).
+// ACP plugin — curated model surface (S0 loader/fence slice; cortex rows added
+// in 0.13).
 //
 // entwurf is an ACP *plugin* on the v2 core, NOT a general-purpose
 // Anthropic provider. It deliberately does not expose the full pi-ai model
-// registry — the surface is curated to the Claude anchor the plugin commits to
-// driving through a real ACP backend (the backend lands in S2; S0 only stands
-// the provider/model surface up).
+// registry — the surface is curated to the ids the plugin commits to driving
+// through a real ACP backend.
 //
-// Claude-first scope (NEXT §스코프): Codex is already a native garden citizen
-// and Gemini / major tools use native, so the curated surface is Claude-only on
-// this lane. A second governed backend would EXTEND this set — it does not change
+// Two curated sets live here, one per adapter on the rail
+// (backend-adapter.ts): the unprefixed Claude ids (the reference backend) and
+// the `cortex-` prefixed Snowflake Cortex Code ids (the second backend, landed
+// 0.13.0 — docs/acp-backend-rail.md §6/§11-8). Codex is already a native garden
+// citizen and Gemini/major tools use native, so neither is an ACP backend here.
+// A third governed backend EXTENDS this file the same way — it does not change
 // the pattern.
 
 // pi 0.80 migration: the standalone root `getModels()` moved to the deprecated
@@ -81,6 +84,65 @@ function claudeContextWindow(model: { id: string; contextWindow: number }): numb
 	return Math.min(model.contextWindow, CLAUDE_CONTEXT_DEFAULT);
 }
 
+// ── Cortex (Snowflake Cortex Code) curated surface ──────────────────────────
+//
+// entwurf's ACP rail is backend-extensible: Cortex is the first NON-claude
+// backend to land through it (docs/acp-backend-rail.md §6). pi-ai carries no
+// snowflake/cortex model source, so this surface is HAND-CURATED. Every id
+// carries the reserved `cortex-` prefix (§9-1): the prefix is the SINGLE routing
+// authority (backend-adapter.ts `routeModel`) and keeps the ids off the Claude
+// native ids Cortex routes to (`cortex-claude-sonnet-5` vs the unprefixed
+// `claude-sonnet-5` the claude adapter owns). `routeModel` strips the prefix to
+// recover the native id, which is enforced per-turn via
+// session/set_config_option — never a launch `-m` pin (CP0-M).
+//
+// The 4-row set is the GLG-decided curation (2026-07-29) — a subset of the 11
+// native ids cortex v1.1.52 exposed live when authenticated. A curated id that
+// the running cortex no longer serves fails LOUD at set-model, before the
+// prompt (measured: `Unsupported model: …` names the live set). Adding an id
+// here is the same verify-both-axes commitment as the Claude set — do not
+// extend casually.
+export const CORTEX_MODEL_PREFIX = "cortex-";
+export const SUPPORTED_CORTEX_MODEL_IDS = [
+	"cortex-auto",
+	"cortex-claude-opus-5",
+	"cortex-claude-sonnet-5",
+	"cortex-openai-gpt-5.4",
+] as const;
+
+// Hand-set conservative context window. Cortex reports the LIVE window via its
+// own ACP session config, not this curated metadata — this is a floor for the
+// registry surface, deliberately not inflated to the Claude 1M.
+const CORTEX_CONTEXT_DEFAULT = 200_000;
+
+/**
+ * The curated Cortex model rows handed to the single `entwurf` provider via
+ * `allCuratedModels()`. The two Claude rows ride their OWN registry base
+ * (opus-5 / sonnet-5); `auto` (default family Claude) and the GPT row (no pi-ai
+ * source) ride the sonnet-5 base as a metadata floor. id / name / contextWindow
+ * are overridden; the `cortex-` prefix keeps them from colliding with the
+ * Claude curated ids. Same row shape as `curatedClaudeModels()` (AcpModelRow).
+ */
+export function curatedCortexModels() {
+	const sonnetBase = requireRegistryModel(ANTHROPIC_MODELS_ALL, "claude-sonnet-5");
+	const opusBase = requireRegistryModel(ANTHROPIC_MODELS_ALL, "claude-opus-5");
+	const row = (id: string, name: string, base: RegistryModel) => ({
+		id,
+		name,
+		reasoning: base.reasoning,
+		input: base.input,
+		cost: base.cost,
+		contextWindow: CORTEX_CONTEXT_DEFAULT,
+		maxTokens: base.maxTokens,
+	});
+	return [
+		row("cortex-auto", "Cortex · Auto", sonnetBase),
+		row("cortex-claude-opus-5", "Cortex · Claude Opus 5", opusBase),
+		row("cortex-claude-sonnet-5", "Cortex · Claude Sonnet 5", sonnetBase),
+		row("cortex-openai-gpt-5.4", "Cortex · OpenAI GPT-5.4", sonnetBase),
+	];
+}
+
 /**
  * The curated Claude model rows handed to `pi.registerProvider({ models })`.
  * Fail-loud if the anchor is absent from the pi-ai registry.

package/pi-extensions/lib/acp/overlay.ts

@@ -9,9 +9,15 @@
 // operator entries a backend needs (credentials, caches, built-in skills)
 // reachable through a TIGHT symlink whitelist — nothing else.
 //
-// Scope (NEXT §스코프 / §S2-scout 핀3): Claude-only on this lane. Codex/Gemini
-// overlays (CODEX_HOME / admin.toml) are 0.11.0 behavior-oracle territory and
-// out of scope — the bridge backends are not in v2 yet.
+// Scope (NEXT §스코프 / §S2-scout 핀3): the block above describes the CLAUDE
+// overlay — `ensureClaudeConfigOverlay` and its symlink whitelist are written for
+// claude-agent-acp's config surface alone. A second backend brings its OWN
+// materializer, and cortex did: `ensureCortexDualHomeOverlay` (+ projectCortexMcpJson /
+// sweepDeadCortexOverlays / cortexOverlayScopeId) lives further down this file with its
+// own D-number rationale — an isolated HOME rather than a redirect knob, because cortex
+// has no CLAUDE_CONFIG_DIR equivalent (§11-8 D2). The two share the module, never the
+// strategy. Codex/Gemini overlays (CODEX_HOME / admin.toml) remain behavior-oracle
+// territory and are out of scope here.
 //
 // Two deliberate divergences from the literal 0.11.0 illustrative comment block
 // (the 0.11.0 CODE already does both — only its top doc-comment drew projects/
@@ -27,6 +33,7 @@
 // which is exactly the "mailbox absence by design" the plugin commits to
 // (no meta-bridge hook on this child's settings surface → no mailbox).
 
+import { createHash } from "node:crypto";
 import {
 	existsSync,
 	lstatSync,
@@ -41,6 +48,8 @@ import {
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import type { AcpMcpServer } from "./config.js";
+
 /** Operator's real Claude config dir — the symlink-passthrough SOURCE. */
 export const CLAUDE_REAL_CONFIG_DIR = join(homedir(), ".claude");
 
@@ -218,3 +227,225 @@ export function ensureClaudeConfigOverlay(
 		}
 	}
 }
+
+// ============================================================================
+// Cortex dual-HOME overlay — the as-measured containment for `cortex acp serve`
+// (CP0 audit 2026-07-29, Cortex Code v1.1.52; docs/acp-backend-rail.md §4/§11-8).
+// ============================================================================
+//
+// Why this is NOT the claude-shaped `SNOWFLAKE_HOME`-only overlay PR #40 shipped
+// (each point is a measured defect, not a preference — §11-8 D-numbers):
+//
+//   - D2: cortex reads `CONFIG_DIRS = [".claude", ".cortex"]` at `homedir()` and
+//     `~/.claude/skills` — a SNOWFLAKE_HOME redirect cannot move that axis. An
+//     overlay session carrying only auth symlinks still advertised the
+//     operator's 42 `~/.claude/skills` entries. Cortex has no
+//     `CLAUDE_CONFIG_DIR`-equivalent redirect knob (string occurs 0 times in the
+//     binary), so the only containment that closes the leak is an ISOLATED HOME:
+//     measured global-scope skill count 0, hook trace 0, bundled/project surface
+//     intact. Scope note: `homedir()`-anchored *operator-global* state is what
+//     the isolation closes; explicit cwd PROJECT scope (`<cwd>/.claude/*`) is
+//     retained by contract — a sibling working in a repo sees that repo's
+//     declared project surface.
+//   - D3: `CORTEX_HOME` beats `SNOWFLAKE_HOME` in cortex's own resolver, so one
+//     ambient operator variable would silently bypass the whole overlay. The
+//     adapter REFUSES to spawn when `CORTEX_HOME` is present at all (empty
+//     string included) — same presence-refusal family as the ordering probe's
+//     `CLAUDE_CODE_EXECUTABLE` precondition (backend-adapter.ts).
+//   - D9: cortex ACP `newSession` reads only `cwd` and `_meta` — the wire
+//     `mcpServers` param the backend-invariant turn loop passes is IGNORED. The
+//     explicit `entwurfProvider.mcpServers` (envelope-enriched) are therefore
+//     PROJECTED into the overlay-private `$SNOWFLAKE_HOME/cortex/mcp.json` (the
+//     door `cortex mcp add` writes). Exact-author every spawn; an entry type the
+//     file cannot represent fails loud BEFORE spawn (no silent drop).
+//   - D10: an isolated HOME also cuts `~/.pi/agent` (garden store, sockets,
+//     spawn surface) off the bundled entwurf-bridge — tools reach the model but
+//     see an EMPTY garden. Dual-HOME closes it: the `entwurf-bridge` mcp.json
+//     entry ALONE gets `HOME=<real operator home>` restored; every other MCP
+//     child stays in the isolated home. The real home is captured by the parent
+//     as an absolute path BEFORE spawn — never re-derived inside the child.
+//   - D4: cortex self-updates on launch by default, and `acp serve` accepts no
+//     `--no-auto-update` (the global flag position boots a TUI with exit 0 —
+//     protocol corruption, not a server). The one remaining door is the overlay
+//     writing `"autoUpdate": false` into its own `cortex/settings.json`. That is
+//     a mid-turn self-replacement OFF switch, not a version pin.
+//   - D5/F: auth passthrough is the measured MINIMUM: `connections.toml`,
+//     `config.toml` (optional — absent on the measured host),
+//     `cortex/cache/credential_cache` (auth succeeded with exactly this set).
+//     The WHOLE `cortex/cache` leaks operator tool_outputs/tip history; operator
+//     `cortex/skills` and operator `cortex/mcp.json` are denied outright.
+//     Symlink-through only — entwurf never copies/parses/mediates the Snowflake
+//     credential (AGENTS §ACP Plugin Boundary, Hard Rule 9).
+//
+// The overlay is SESSION/CHILD-SCOPED, never a static shared dir: two residents
+// with different envelopes/configs would race one mcp.json. Scope id =
+// `<host pid>-<sha256(scopeKey) 12 hex>`; the scope dir is torn down and
+// exact-rewritten on every spawn (the prior child for the key is already dead —
+// backend.ts tears it down before a "new" decision spawns), which is also the
+// memory containment: nothing cortex wrote into the isolated home survives into
+// the next session. Scope dirs whose host pid is gone are swept opportunistically.
+
+/** Root under which per-session cortex dual-HOME overlays are materialized. */
+export const CORTEX_OVERLAYS_ROOT = join(homedir(), ".pi", "agent", "cortex-overlays");
+
+/** The name of the ONE mcp.json entry whose child gets the real operator HOME
+ *  restored (D10 dual-HOME). Everything else stays in the isolated home. */
+export const CORTEX_DUAL_HOME_BRIDGE_SERVER = "entwurf-bridge";
+
+export interface CortexOverlayParams {
+	/** Session/child scope discriminator (PI_SESSION_ID, else a cwd-derived key).
+	 *  Identity for overlay-dir separation only — never an address authority. */
+	scopeKey: string;
+	/** Normalized + envelope-enriched MCP servers to project into mcp.json. */
+	mcpServers: readonly AcpMcpServer[];
+	/** Absolute real operator HOME captured by the parent BEFORE spawn (D10). */
+	realHome: string;
+	/** Real snowflake home (auth source). Defaults to `<realHome>/.snowflake`. */
+	realSnowflakeHome?: string;
+	/** Overlay root override (tests). Defaults to CORTEX_OVERLAYS_ROOT. */
+	overlaysRoot?: string;
+	/** pid-liveness probe override (tests) for the dead-scope sweep. */
+	isPidAlive?: (pid: number) => boolean;
+}
+
+export interface CortexOverlayResult {
+	/** Isolated HOME for the cortex child (spawn env HOME). */
+	home: string;
+	/** Isolated snowflake home (spawn env SNOWFLAKE_HOME) = `<home>/.snowflake`. */
+	snowflakeHome: string;
+	/** The scope dir owning both (for diagnostics/teardown). */
+	scopeDir: string;
+}
+
+/** Deterministic per-(host process, session key) overlay dir name. */
+export function cortexOverlayScopeId(scopeKey: string, pid: number = process.pid): string {
+	const digest = createHash("sha256").update(scopeKey).digest("hex").slice(0, 12);
+	return `${pid}-${digest}`;
+}
+
+/** Overlay-authored `$SNOWFLAKE_HOME/cortex/settings.json` — D4's one door. */
+export function cortexOverlaySettingsJson(): string {
+	return `${JSON.stringify({ autoUpdate: false }, null, "\t")}\n`;
+}
+
+/**
+ * Project the (envelope-enriched) explicit server list into cortex's
+ * `$SNOWFLAKE_HOME/cortex/mcp.json` shape (D9). Only stdio entries are measured
+ * through this door — an http/sse entry fails loud BEFORE spawn rather than
+ * being silently dropped. The `entwurf-bridge` entry alone carries
+ * `HOME=<realHome>` (D10); a bridge-declared HOME env is overridden, not merged.
+ */
+export function projectCortexMcpJson(servers: readonly AcpMcpServer[], realHome: string): string {
+	const out: Record<string, { type: "stdio"; command: string; args: string[]; env: Record<string, string> }> = {};
+	for (const server of servers) {
+		if ("type" in server && (server.type === "http" || server.type === "sse")) {
+			throw new Error(
+				`entwurf: cortex mcp.json projection cannot represent ${server.type} server ` +
+					`${JSON.stringify(server.name)} — only stdio entries are measured through ` +
+					`$SNOWFLAKE_HOME/cortex/mcp.json (CP0 D9). Remove it from entwurfProvider.mcpServers ` +
+					`for cortex models or front it with a stdio bridge.`,
+			);
+		}
+		const stdio = server as { name: string; command: string; args: string[]; env: { name: string; value: string }[] };
+		const env: Record<string, string> = {};
+		for (const kv of stdio.env) env[kv.name] = kv.value;
+		if (stdio.name === CORTEX_DUAL_HOME_BRIDGE_SERVER) env.HOME = realHome;
+		out[stdio.name] = { type: "stdio", command: stdio.command, args: [...stdio.args], env };
+	}
+	return `${JSON.stringify({ mcpServers: out }, null, "\t")}\n`;
+}
+
+function cortexPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM = alive but not ours; anything else (ESRCH) = gone.
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/**
+ * Opportunistic GC of overlay scope dirs whose HOST pid is gone (process
+ * resources only — the overlay holds no records/transcripts worth preserving;
+ * conversations state is contained BY DESIGN, Hard Rule 8 does not apply to it).
+ * Entries not matching the scope-id grammar are left alone.
+ */
+export function sweepDeadCortexOverlays(
+	overlaysRoot: string,
+	isPidAlive: (pid: number) => boolean = cortexPidAlive,
+): void {
+	let entries: string[];
+	try {
+		entries = readdirSync(overlaysRoot);
+	} catch {
+		return; // root absent — nothing to sweep
+	}
+	for (const entry of entries) {
+		const match = /^(\d+)-[0-9a-f]{12}$/.exec(entry);
+		if (!match) continue;
+		const pid = Number(match[1]);
+		if (pid === process.pid) continue;
+		if (isPidAlive(pid)) continue;
+		try {
+			rmSync(join(overlaysRoot, entry), { recursive: true, force: true });
+		} catch {
+			// Best-effort GC; a stuck dir is retried on the next spawn.
+		}
+	}
+}
+
+/** Symlink `realPath` at `overlayPath` when the operator actually has it.
+ *  The scope dir is freshly rebuilt by the caller, so no stale-link repair. */
+function cortexLinkIfExists(realPath: string, overlayPath: string): void {
+	if (!existsSync(realPath)) return;
+	try {
+		symlinkSync(realPath, overlayPath);
+	} catch (error) {
+		console.error(
+			`[entwurf:cortex-overlay] symlink failed for ${overlayPath}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+/**
+ * Materialize the session-scoped cortex dual-HOME overlay: tear down the scope
+ * dir and exact-rewrite it (auth symlinks + authored settings.json/mcp.json).
+ * Returns the isolated HOME/SNOWFLAKE_HOME the spawn env must carry.
+ */
+export function ensureCortexDualHomeOverlay(params: CortexOverlayParams): CortexOverlayResult {
+	if (!params.realHome || !params.realHome.startsWith("/")) {
+		throw new Error(
+			`entwurf: cortex dual-HOME overlay requires an absolute realHome captured by the parent (got ${JSON.stringify(params.realHome)})`,
+		);
+	}
+	const overlaysRoot = params.overlaysRoot ?? CORTEX_OVERLAYS_ROOT;
+	const realSnowflake = params.realSnowflakeHome ?? join(params.realHome, ".snowflake");
+	sweepDeadCortexOverlays(overlaysRoot, params.isPidAlive ?? cortexPidAlive);
+
+	const scopeDir = join(overlaysRoot, cortexOverlayScopeId(params.scopeKey));
+	// Exact rewrite (never merge): the prior child for this scope key is already
+	// torn down (backend.ts closes it before a "new" decision spawns), so
+	// everything it wrote — conversations, logs, $HOME dotfiles — is discarded
+	// here. rmSync does not follow symlinks, so the real auth files are untouched.
+	rmSync(scopeDir, { recursive: true, force: true });
+
+	const home = join(scopeDir, "home");
+	const snowflakeHome = join(home, ".snowflake");
+	const cortexDir = join(snowflakeHome, "cortex");
+	mkdirSync(join(cortexDir, "cache"), { recursive: true });
+
+	// D5/F — measured-minimum auth passthrough (symlink-through only).
+	cortexLinkIfExists(join(realSnowflake, "connections.toml"), join(snowflakeHome, "connections.toml"));
+	cortexLinkIfExists(join(realSnowflake, "config.toml"), join(snowflakeHome, "config.toml"));
+	cortexLinkIfExists(
+		join(realSnowflake, "cortex", "cache", "credential_cache"),
+		join(cortexDir, "cache", "credential_cache"),
+	);
+
+	// D4 — runtime self-replacement off; D9 — explicit-server projection.
+	writeFileSync(join(cortexDir, "settings.json"), cortexOverlaySettingsJson(), "utf8");
+	writeFileSync(join(cortexDir, "mcp.json"), projectCortexMcpJson(params.mcpServers, params.realHome), "utf8");
+
+	return { home, snowflakeHome, scopeDir };
+}

package/pi-extensions/lib/acp/tool-surface.ts

@@ -10,10 +10,18 @@
 //      if pi has excluded a built-in the backend will still expose, the declared
 //      surface diverges from the actual one — we fail fast rather than lie.
 //
-// Claude-only scope (NEXT §스코프). The function keeps a `backend` field so the
-// honest-divergence logic stays explicit and the matrix gate can exercise both
-// the "claude narrows via tools" and "native always exposes" branches, but the
-// only backend this lane supplies is claude.
+// The module's TWO jobs have different backend scopes — do not collapse them:
+//   - `buildClaudeSessionMeta` is claude-only by CONSTRUCTION, with exactly one
+//     caller (`claudeAdapter.buildSessionMeta`). Cortex exposes no
+//     `_meta.systemPrompt` and no tools/permission declaration surface (native
+//     tools + its own overlay mcp.json projection), so its adapter returns
+//     `undefined` and that function is never reached for a cortex turn.
+//   - `assertExcludeToolsHonored` is BACKEND-INVARIANT: backend.ts runs it for
+//     every adapter before any spawn, passing `backend: adapter.backend` and the
+//     resolved `config.tools`. A cortex turn DOES enter this module through it.
+// That split is why the `backend` field exists: the honest-divergence logic stays
+// explicit and the matrix gate can exercise both the "claude narrows via tools"
+// and "native always exposes" branches.
 //
 // Carrier guard (NEXT §S2-scout 핀1): `buildClaudeSessionMeta` only attaches
 // `_meta.systemPrompt` when a caller passes one. The shipped S2d path passes the

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

@@ -1,14 +1,29 @@
 /**
  * entwurf-core — sync entwurf execution, host-agnostic.
  *
- * Single implementation shared by:
- *   - pi-extensions/entwurf.ts (pi native tool surface)
- *   - mcp/entwurf-bridge/src/index.ts (MCP tool surface for ACP hosts)
+ * DIRECT importers, MEASURED from the import graph (2026-07-27) — not from memory:
+ *   - pi-extensions/entwurf-control.ts (the pi adapter)
+ *   - pi-extensions/lib/entwurf-v2-spawn-production.ts (v2 spawn-bg launch identity)
+ *   - pi-extensions/lib/project-trust-handler.ts · lib/acp/augment.ts ·
+ *     lib/native-push/adapter.ts
+ *   - plus gates/smokes (check-shell-quote, check-package-source-routing, …)
+ *
+ * The MCP bridge is a TRANSITIVE consumer, not a direct one, and the distinction is the
+ * whole point: `mcp/entwurf-bridge/src/index.ts → entwurf-v2-surface.ts →
+ * entwurf-v2-production.ts → entwurf-v2-spawn-production.ts → entwurf-core.ts`. So the old
+ * header's claim — that the bridge imports this shared implementation the way a v1 tool
+ * surface did — was false, but so is "the bridge does not reach it": it reaches it at
+ * runtime, only for spawn-bg production.
+ *
+ * NOT consumers on any path: `pi-extensions/entwurf.ts` (the v1 pi native tool surface) and
+ * `pi-extensions/lib/entwurf-async.ts` were REMOVED in the 0.12 cutover. Do not reintroduce
+ * either as a live consumer.
  *
  * This module MUST NOT import anything from @earendil-works/pi-coding-agent or any
- * other pi runtime API. It is pure Node + @sinclair/typebox-free.  Anything that
- * requires pi's ExtensionAPI (sendMessage, appendEntry, sessionManager) belongs
- * in the async entwurf path, which stays in pi-extensions/entwurf.ts for now.
+ * other pi runtime API. It is pure Node + @sinclair/typebox-free. Anything that
+ * requires pi's ExtensionAPI (sendMessage, appendEntry, sessionManager) belongs to a
+ * pi-adapter surface, never here — the v1 async entwurf path that used to hold that
+ * work went away with `pi-extensions/entwurf.ts`.
  *
  * Scope:
  *   - sync execution (spawn pi, collect message_end events, return summary)
@@ -67,9 +82,11 @@ const PI_SETTINGS_PATH = process.env.PI_SETTINGS_PATH
 	: path.join(AGENT_DIR, "settings.json");
 export const ENTWURF_CODEX_ACP_ENV = "ENTWURF_ACP_FOR_CODEX";
 
-// Currently unused: remote/SSH entwurf is fail-fast in 0.9.0 (garden-native
-// identity is local-FS only). Retained for #11 remote revival; parity-gated by
-// scripts/check-shell-quote.ts across entwurf.ts / entwurf-core.ts / entwurf-async.ts.
+// Currently unused: remote/SSH entwurf is fail-fast (garden-native identity is
+// local-FS only). Retained for #11 remote revival and pinned by
+// scripts/check-shell-quote.ts, whose SOURCE_SITES is now THIS FILE ALONE — the
+// entwurf.ts / entwurf-async.ts halves of that former parity check were removed
+// with those files, so there is no cross-file parity left to assert.
 // biome-ignore lint/correctness/noUnusedVariables: retained for #11 remote revival; parity-gated.
 function shellQuote(value: string): string {
 	return `'${value.replace(/'/g, `'\\''`)}'`;

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

@@ -18,9 +18,10 @@
  *    drains its own inbox on wake. A DIRECT-INJECT backend (pi / codex / antigravity)
  *    has no mailbox drain at all — enqueuing for it is the SE-1 false success
  *    ("✓ delivered" into a void). So deliverable = wakeMode === "self-fetch" AND the
- *    receiver is active. This is the guard that the v1 fallback, MCP v1, pi-native v1,
- *    and the v2 decider/send-fallback enqueue sites must all pass before writing a
- *    .msg (slice 2d).
+ *    receiver is active. Every enqueue site must pass this guard before writing a .msg
+ *    (slice 2d). The shipped sites are the v2 decider and its send-fallback re-resolve;
+ *    the v1 fallback / MCP v1 / pi-native v1 sites this once also listed were removed in
+ *    the 0.12 cutover — do not read them as live.
  *
  *  - nativePushDeliverable(facts): the SEPARATE deliverability predicate for a
  *    NATIVE-PUSH backend (antigravity). A native-push citizen has no mailbox and no
@@ -89,9 +90,12 @@ export interface ReceiverIdentityFacts {
  * Does this presence marker actually belong to the target identity? A marker that is
  * absent, or whose garden id / backend / native session id has drifted from the record,
  * is NOT this receiver — fail-closed (a stale/foreign marker must never raise a dead
- * target to "active"). The single source of truth for "marker ↔ identity match" shared
- * by the v1 mailbox guard (gatherMailboxDeliverabilityFacts) and the v2 production
- * `mailboxDeliverabilityFor` seam, so the two paths cannot drift to different meanings.
+ * target to "active"). The single source of truth for "marker ↔ identity match". Its
+ * PRODUCTION consumers are the v2 `mailboxDeliverabilityFor` seam and the MCP bridge's
+ * `entwurf_self`. There is no second implementation: `entwurf-mailbox-guard.ts` used to
+ * wrap this atom with its own enqueue orchestration, had ZERO production importers (import
+ * graph measured 2026-07-27), and was DELETED rather than left as a green gate proving only
+ * retired behaviour. A new enqueue site consults this predicate through that seam.
  */
 export function receiverMarkerMatchesIdentity(
 	marker: ReceiverIdentityFacts | null | undefined,

package/pi-extensions/lib/entwurf-fact-provider.ts

@@ -5,8 +5,8 @@
  * (one-way: provider → facts / socket-discovery / meta-session) — no import cycle
  * with `entwurf-facts.ts` (which owns `SocketProbe`/`resolveFactList`).
  *
- *   listAllMetaIdentities → pi gid 추출 → scanSocketProbes(piGids)
- *     → pre-quarantine non-pi/socket conflicts → resolveFactList(clean)
+ *   listAllMetaIdentities → socket-domain gid extraction → scanSocketProbes
+ *     → pre-quarantine out-of-domain/socket conflicts → resolveFactList(clean)
  *     → { facts, diagnostics }
  *
  * Two throw-vs-diagnostics policies, kept distinct (GPT힣 C-원칙):
@@ -20,14 +20,14 @@
  *     — that is not a re-implementation of the collision rule, it is input
  *     sanitation that leaves the pure-core invariant intact.
  *
- * The non-pi+socket collision quarantines BOTH sides (the PeerFact AND the
- * socket): gardenId is the universal address and a send path reads the socket
+ * An out-of-socket-domain record/socket collision quarantines BOTH sides (the
+ * PeerFact AND the socket): gardenId is the universal address and a send path
  * first, so surfacing the record alone (as a clean `unsupported` PeerFact) while
  * a same-gid socket exists would be half a lie. Both leave the normal output;
  * one diagnostic carries the fact. (pi + same-gid socket = the normal merge.)
  */
 
-import { type FactList, isNonPiGardenIdSocketConflict, resolveFactList } from "./entwurf-facts.ts";
+import { type FactList, isOutOfSocketDomainGardenIdConflict, resolveFactList } from "./entwurf-facts.ts";
 import { isLivenessSupported } from "./entwurf-v2-contract.ts";
 import {
 	type ActiveStoreEntry,
@@ -130,8 +130,8 @@ export async function listEntwurfFacts(deps: EntwurfFactsDeps): Promise<EntwurfF
 	// 2. socket axis — probe (dir sockets) ∪ (in-domain citizen canonical paths).
 	//    Its three hazards (symlink forgery / malformed name / dir-read error) are
 	//    folded into diagnostics here so the listing survives but never lies.
-	const piGids = identities.filter((i) => isLivenessSupported(i.backend)).map((i) => i.gardenId);
-	const scan = await scanSocketProbes(piGids, deps.socket ?? {});
+	const socketDomainGids = identities.filter((i) => isLivenessSupported(i.backend)).map((i) => i.gardenId);
+	const scan = await scanSocketProbes(socketDomainGids, deps.socket ?? {});
 	const probes = scan.probes;
 	const socketGids = new Set(probes.map((p) => p.gardenId));
 	const symlinkedGids = new Set(scan.symlinkedGardenIds);
@@ -158,24 +158,22 @@ export async function listEntwurfFacts(deps: EntwurfFactsDeps): Promise<EntwurfF
 		});
 	}
 
-	// 3. pre-quarantine non-pi citizens that collide with a control socket. The
-	//    predicate is SHARED with the v2 decider (isNonPiGardenIdSocketConflict) so
-	//    listing and dispatch cannot drift, and it unions socketGids with the
-	//    symlinkedGids: a symlinked socket is never probed (absent from socketGids),
-	//    so the old socketGids-only check let a non-pi citizen with a forged
-	//    (symlinked) socket survive as a clean PeerFact while the legacy send path
-	//    still followed the symlink — the gap this closes.
+	// 3. Pre-quarantine citizens outside the control-socket capability domain that
+	//    collide with a control socket. The predicate is SHARED with v2 dispatch so
+	//    listing and dispatch cannot drift. It unions real and symlinked socket gids:
+	//    the earlier real-socket-only check let an out-of-domain record survive as a
+	//    clean PeerFact beside a forged symlink receiver.
 	const conflictGids = new Set<string>();
 	for (const id of identities) {
-		if (isNonPiGardenIdSocketConflict(id.backend, id.gardenId, socketGids, symlinkedGids)) {
+		if (isOutOfSocketDomainGardenIdConflict(id.backend, id.gardenId, socketGids, symlinkedGids)) {
 			conflictGids.add(id.gardenId);
 			diagnostics.push({
 				kind: "garden-id-socket-conflict",
 				gardenId: id.gardenId,
 				backend: id.backend,
 				message:
-					`non-pi citizen (${id.backend}) shares its gardenId with a control socket (real or symlinked) — address ` +
-					"ambiguity; both the citizen and the socket are quarantined from the listing.",
+					`out-of-socket-domain citizen (${id.backend}) shares its gardenId with a control socket ` +
+					"(real or symlinked) — address ambiguity; both sides are quarantined from the listing.",
 			});
 		}
 	}

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

@@ -75,27 +75,27 @@ export function resolvePeerFact(identity: MetaIdentity, socket: SocketLiveness |
 }
 
 /**
- * A non-pi RECORD whose gardenId collides with a control socket — a real (probed)
- * one OR a symlinked/forged one. The gardenId is the universal address (동결결정3),
- * so a non-pi citizen sharing it with a socket means a send-path that reaches the
- * socket first hits a DIFFERENT receiver than the record names — an address split.
+ * An OUT-OF-SOCKET-DOMAIN record whose gardenId collides with a control socket —
+ * a real (probed) one OR a symlinked/forged one. The gardenId is the universal
+ * address, so a citizen without socket capability sharing it with a socket means
+ * the socket reaches a DIFFERENT receiver than the record names — an address split.
  * Both the citizen and the socket are quarantined from the facts listing.
  *
  * The union `socketGids ∪ symlinkedGardenIds` is load-bearing: `socketGids` are
  * gids with a real probed `*.sock`, but `symlinkedGardenIds` are NEVER probed (P1)
  * and so are absent from `socketGids`. Looking at `socketGids` alone (the
- * fact-provider:125 gap this closes) let a non-pi citizen with a *symlinked* socket
+ * fact-provider:125 gap this closes) let an out-of-domain citizen with a *symlinked* socket
  * survive as a clean PeerFact while the legacy send path still followed the symlink
  * to a forged receiver. Both axes claim the gid → both must quarantine it.
  *
- * SCOPE: this is the RECORD-side, non-pi conflict only — shared by the fact-provider
- * (listing) and the v2 decider (dispatch) so the two cannot drift (4c "재유도 금지"
- * 동형; only the observation-bit source is parameterized). A pi citizen whose own
- * canonical socket is a symlink is NOT this predicate's concern — that is a
+ * SCOPE: this is the record-side, out-of-socket-domain conflict only — shared by
+ * listing and dispatch so they cannot drift; only the observation-bit source is
+ * parameterized. A citizen IN the socket domain whose own canonical socket is a
+ * symlink is NOT this predicate's concern — that is a
  * target-specific lstat conflict the decider's `inspectTargetControlSocket` raises
  * as `address-conflict`, kept deliberately separate (GPT 1차 검수 C).
  */
-export function isNonPiGardenIdSocketConflict(
+export function isOutOfSocketDomainGardenIdConflict(
 	backend: string,
 	gardenId: string,
 	socketGids: ReadonlySet<string>,
@@ -163,8 +163,8 @@ export interface FactList {
  *     `indeterminate` and strand a dormant citizen as un-resumable); a dormant
  *     citizen's absent socket file is probed to `dead` (ENOENT) by the wiring and
  *     arrives here AS `dead` → dormant → resumable.
- *   - out-of-domain citizen WITH a control socket at its gardenId → fail-loud
- *     (address ambiguity; a non-pi citizen must not own a pi control socket).
+ *   - out-of-socket-domain citizen WITH a control socket at its gardenId → fail-loud
+ *     (address ambiguity; a backend without socket capability cannot own that rail).
  *   - out-of-domain citizen without a socket → `unsupported` (via resolvePeerFact).
  *   - a probed gardenId with NO citizen → `RecordLessSocketFact` (#50 C4: a
  *     diagnostic subject the provider folds into a `record-less-socket`
@@ -202,7 +202,7 @@ export function resolveFactList(identities: MetaIdentity[], socketProbes: Socket
 			if (probeMap.has(gid)) {
 				throw new Error(
 					`resolveFactList: out-of-domain citizen ${gid} (${identity.backend}) has a control socket — ` +
-						"address ambiguity (a non-pi citizen must not own a pi control socket)",
+						"address ambiguity (an out-of-socket-domain citizen cannot own a control socket)",
 				);
 			}
 			socket = null;