@junghanacs/entwurf 0.12.9 → 0.13.0

package/pi-extensions/entwurf-control.ts

@@ -108,9 +108,10 @@ const SESSION_MESSAGE_TYPE = "entwurf-message";
 // with the receive-side [entwurf received ⟵] box. The provider-level context
 // filter in index.ts drops this customType before the LLM sees it — colocated
 // with the emitter so sessions without --entwurf-control are still protected.
-// Layer A (native path) reuses the same Box builder via renderSentMessage() but
-// does NOT emit a CustomMessage; the native tool result already lives in the
-// toolResult role and never enters LLM context as a user message.
+// There is no second emitter: the v1 native send path ("Layer A") that also drew
+// this box through renderSentMessage() was removed in the 0.12 cutover, and
+// renderSentMessage is now registered for exactly one customType (see
+// registerMessageRenderer below). Do not describe a native sender-side box.
 const SENDER_INFO_PATTERN = /<sender_info>[\s\S]*?<\/sender_info>/g;
 
 // ============================================================================
@@ -509,8 +510,8 @@ const renderSessionMessage: MessageRenderer = (message, { expanded }, theme) =>
 };
 
 // Sender-side payload — what renderSentMessage needs to draw the [entwurf sent →]
-// box. Carried verbatim by both Layer A (native renderResult) and Layer B
-// (CustomMessage details for ACP path). All four envelope fields are intentionally
+// box. Carried by the ACP path's CustomMessage `details` — the ONLY carrier since
+// the v1 native renderResult path was removed (0.12 cutover). All four envelope fields are intentionally
 // echoed in the box even though the sender is "this same session" — operators
 // reading a busy multi-session transcript should be able to verify at a glance
 // which 담당자 is on the wire (cwd) and which model identity (agentId) actually
@@ -520,9 +521,10 @@ const renderSessionMessage: MessageRenderer = (message, { expanded }, theme) =>
 // re-renders (resize, expand toggle) keep showing the moment the message was
 // actually delivered rather than drifting forward to "now".
 //
-// wants_reply mirrors the receive-side etiquette badge. Native schema does not
-// yet expose it (see registerSessionTool's entwurfSendParameters); leave undefined
-// from the native call site until the schema grows the field.
+// wants_reply mirrors the receive-side etiquette badge. It stays optional because
+// the box is drawn from a CustomMessage whose `details` may predate the field; the
+// v1 `registerSessionTool` / `entwurfSendParameters` schema this note used to point
+// at is gone (0.12 cutover), so there is no native call site left to grow.
 interface SentBoxData {
 	to: string; // target sessionId
 	from?: string; // sender agentId, e.g. "entwurf/claude-opus-5"
@@ -1274,9 +1276,18 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		target: Type.String({ description: "Target garden id (use entwurf_peers to discover)" }),
 		intent: StringEnum(["fire-and-forget", "owned-outcome"] as const, {
 			description:
-				"fire-and-forget = send/reply/hand-off to a LIVE or meta-session target (set wants_reply for an answer); " +
-				"owned-outcome = wake a DORMANT pi via spawn-bg resume ONLY — on a live target it is rejected " +
-				"(owned-live-no-autosend) and never auto-converted",
+				"fire-and-forget = send/reply/hand-off to a LIVE socket target (currently backend pi) or to any " +
+				"citizen with no socket liveness — the decider picks that citizen's rail, and a rail can also " +
+				"REJECT: self-fetch (e.g. Claude Code) → meta-bridge mailbox while that mailbox is DELIVERABLE, " +
+				"else rejected as mailbox-undeliverable; native-push (e.g. Antigravity) → direct injection into " +
+				"its live conversation, which has NO mailbox, and its probe is three-valued — alive: injected, " +
+				"dead: native-push-target-dead, indeterminate: native-push-probe-indeterminate (two rejects, " +
+				"not one). " +
+				"Set wants_reply for an answer. " +
+				"owned-outcome = wake a DORMANT socket-domain citizen via spawn-bg resume ONLY — on a live target " +
+				"rejected as owned-live-no-autosend, on self-fetch as backend-liveness-unsupported, on " +
+				"native-push as native-push-no-resume-authority (both lack resume authority, but the reasons " +
+				"differ because native-push IS probe-measured), and never auto-converted",
 		}),
 		message: Type.String({
 			description:
@@ -1285,7 +1296,9 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		}),
 		mode: Type.Optional(
 			StringEnum(["steer", "follow_up"] as const, {
-				description: "Delivery mode for a live send: steer (immediate) or follow_up (after task)",
+				description:
+					"Injection style for a CONTROL-SOCKET send only: steer (immediate) or follow_up (after task). " +
+					"The mailbox, native-push, and spawn-bg plans carry no mode, so it has no effect on those rails.",
 			}),
 		),
 		wants_reply: Type.Optional(Type.Boolean({ description: "Human-conversation reply hint (default false)" })),
@@ -1299,6 +1312,11 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		wants_reply?: boolean;
 	};
 
+	// TS2589 ("type instantiation is excessively deep") workaround: pi's registerTool
+	// generic infers the handler signature from the TypeBox schema, and this schema is
+	// deep enough to blow the instantiation budget. Casting the FUNCTION (not the
+	// argument) keeps the schema itself typed while stopping the inference walk.
+	// Revisit when pi's registerTool takes an explicit params type parameter.
 	const registerTool = pi.registerTool as (def: any) => void;
 
 	registerTool({
@@ -1306,28 +1324,51 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		label: "Dispatch (v2)",
 		description: `CANONICAL delivery surface for a garden id. When you have a garden id and want to
 reach whoever it names — message / reply / hand-off — use THIS verb. A garden id alone does not
-reveal whether the target is a live pi session, a dormant pi session, or a Claude Code meta-session,
+reveal which rail that citizen answers on — a live socket session, a dormant one, a mailbox-backed
+self-fetch session, or a native-push session —
 and entwurf_v2 is the one surface that reads that and routes correctly (so "when unsure which
 transport, use entwurf_v2"). It dispatches to EXISTING targets; brand-new sibling creation is deferred
 to a later v2 lane. Dispatch to a garden citizen through the unified entwurf_v2 verb: the 5b decider
-picks the transport (live control-socket send / spawn-bg resume / meta-mailbox enqueue) from the
-target's liveness + your intent, runs it under the v2 lock policy (pi paths take a per-target lock;
-the mailbox path is lock-free, guarded by active-receiver deliverability), and reports one outcome
-(delivered / rejected / lock-retained / delivered-but-lock-dirty).
+picks the transport (live control-socket send / spawn-bg resume / meta-mailbox enqueue / native-push
+direct injection) from the target's liveness + your intent, runs it under the v2 lock policy, and reports
+one outcome (delivered / rejected / lock-retained / delivered-but-lock-dirty).
+
+LOCK POLICY (do not over-generalize it): the per-target lock is taken for a control-socket-DOMAIN
+dispatch, which is BOTH the live send AND the dormant cell's spawn-bg resume — spawn-bg is a separate
+relaunch transport yet it still runs under that domain's lock. The mailbox and native-push rails are
+lock-free: the mailbox is guarded instead by active-receiver deliverability, and native-push by its
+adapter probe.
 
 - target: the garden id of the citizen to reach (required).
 - intent: fire-and-forget (a send with no owned result) or owned-outcome (you own the result).
 - message: the message/prompt to dispatch (required).
-- mode: steer or follow_up for a live send (optional).
-- wants_reply: reply hint for a live send (optional, default false).
+- mode: steer or follow_up for a CONTROL-SOCKET send (optional). The mailbox, native-push, and
+  spawn-bg plans carry no mode, so it has no effect on those rails — a native-push send IS live and
+  still ignores it.
+- wants_reply: reply hint; it rides every rail (optional, default false).
 
 CHOOSING INTENT (picking wrong is rejected, never auto-fixed): to message / reply / hand off a peer
-that entwurf_peers shows as liveness=alive (a live pi citizen), use intent: fire-and-forget
-— it routes to the live control-socket; set wants_reply:true if you need an answer (wants_reply is NOT
-owned-outcome). For a meta-session (liveness=unsupported, e.g. Claude Code), replies are ALSO
-fire-and-forget (→ mailbox). owned-outcome is ONLY for waking a DORMANT pi citizen (spawn-bg resume);
-on a live target it is rejected as owned-live-no-autosend, on an unsupported backend as
-backend-liveness-unsupported, and is NEVER auto-converted — so pick the right intent up front.
+that entwurf_peers shows as liveness=alive (a live socket citizen, currently backend pi), use intent:
+fire-and-forget — it routes to the live control-socket; set wants_reply:true if you need an answer
+(wants_reply is NOT owned-outcome). Replies to a citizen with NO socket liveness
+(liveness=unsupported) are ALSO fire-and-forget, and the decider picks that citizen's own rail: a
+self-fetch backend (e.g. Claude Code) gets the meta-bridge mailbox, while a native-push backend
+(e.g. Antigravity) gets direct injection into its live conversation and has NO mailbox at all — do
+not assume mailbox semantics for every unsupported citizen. A native-push target IS measured by its
+own adapter probe, and that probe is THREE-valued, so the send is never silently queued: alive →
+injected; dead → rejected as native-push-target-dead; indeterminate → rejected as
+native-push-probe-indeterminate. Those last two stay separate on purpose — "we could not establish
+it" is not "it is gone". THERE IS A THIRD RESULT, so do not read
+liveness=unsupported as "reachable by some rail": the mailbox path delivers only to a DELIVERABLE
+citizen (a self-fetch backend whose receiver is live and armed), so a terminated Claude Code session —
+and any record whose backend has no adapter on this lane, e.g. codex — is rejected as
+mailbox-undeliverable rather than queued into an inbox nobody drains. unsupported means only "this
+backend has no control-socket probe".
+owned-outcome is ONLY for waking a DORMANT socket-domain citizen (spawn-bg resume, currently backend
+pi); on a live target it is rejected as owned-live-no-autosend. Neither self-fetch nor native-push
+has resume authority, but they reject under DIFFERENT reasons — self-fetch as
+backend-liveness-unsupported, native-push as native-push-no-resume-authority.
+It is NEVER auto-converted — so pick the right intent up front.
 
 The decider — not this surface — chooses the transport.`,
 		parameters: entwurfV2Parameters,
@@ -1433,8 +1474,9 @@ async function renderEntwurfPeersForSurface(): Promise<{ text: string; payload:
 }
 
 function registerListSessionsTool(pi: ExtensionAPI): void {
-	// Same TS2589 workaround as registerSessionTool — see the comment block
-	// in that function for the revisit conditions.
+	// Same TS2589 workaround as registerEntwurfV2Tool — see the comment block there
+	// for the revisit conditions. (It used to point at registerSessionTool, which was
+	// removed in the 0.12 cutover, so the pointer dangled.)
 	const registerTool = pi.registerTool as (def: any) => void;
 	registerTool({
 		name: "entwurf_peers",

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

@@ -30,14 +30,64 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { ENTWURF_PROJECT_CONTEXT_OPEN_TAG } from "../../../protocol.js";
 import type { AcpTextBlock } from "./context.js";
 
 const MAX_AUGMENT_BYTES = 50 * 1024;
 
+// Carrier-less backends expose no `_meta.systemPrompt` (docs/acp-backend-rail.md
+// §9-4). claude folds the operator engraving into that carrier; a carrier-less
+// backend (cortex, the first — precisely: SYSTEM-PROMPT-carrier-less, since
+// cortex does read `_meta` for an unpromoted caller-session-id seam, §11-8)
+// has nowhere to put it — so its operator engraving
+// rides HERE, prepended as the LEADING section of the first-user augment. It
+// travels on the WIRE only (new-only, never the config signature), so an
+// engraving change applies to the NEXT new cortex session rather than
+// invalidating a live reused one — the documented asymmetry vs claude, where the
+// carrier feeds bridgeConfigSignature.
+const CARRIER_LESS_BACKENDS: ReadonlySet<string> = new Set(["cortex"]);
+
+// The env var an operator points at a personal engraving file. Shared surface
+// with the claude carrier (engraving.ts) BY NAME, but read INLINE here (not
+// imported): augment.ts is loaded raw by the strip-types carrier-augment gate,
+// which cannot resolve a `.js` VALUE import of the sibling `.ts` engraving
+// module (augment.ts only value-imports real `.js` files). So the carrier-less
+// override read is self-contained. Unlike engraving.ts's shipped-default path,
+// this ONLY ever reads the operator OVERRIDE file: the shipped claude default
+// (a preset-replacement / auto-memory lever) is meaningless for a non-claude
+// backend and is never injected into a carrier-less augment.
+const ENGRAVING_OVERRIDE_ENV = "ENTWURF_ACP_ENGRAVING_PATH";
+
+/**
+ * Render the operator engraving OVERRIDE for a carrier-less backend, or null
+ * when unset / empty / whitespace / unreadable. Pure w.r.t. (override file
+ * contents, backend, sorted mcpServerNames). Mirrors engraving.ts's `{{backend}}`
+ * / `{{mcp_servers}}` token substitution so the operator's file behaves the same
+ * on the augment as it would on the claude carrier.
+ */
+function loadCarrierlessOperatorEngraving(backend: string, mcpServerNames: readonly string[]): string | null {
+	const envPath = process.env[ENGRAVING_OVERRIDE_ENV]?.trim();
+	if (!envPath) return null;
+	let source: string;
+	try {
+		source = readFileSync(resolve(envPath), "utf8");
+	} catch {
+		return null;
+	}
+	const names = [...mcpServerNames].sort();
+	const mcpList = names.length > 0 ? names.join(", ") : "(none registered)";
+	const rendered = source
+		.replace(/\{\{backend\}\}/g, backend)
+		.replace(/\{\{mcp_servers\}\}/g, mcpList)
+		.trim();
+	return rendered.length > 0 ? rendered : null;
+}
+
 export interface PiContextAugmentParams {
-	/** Claude-only this cut; kept as a field so the narrative names the backend. */
+	/** The routed backend ("claude" | "cortex"). Load-bearing, not decorative: the
+	 *  narrative names it AND `CARRIER_LESS_BACKENDS` keys off it to decide whether
+	 *  the operator engraving leads the augment. */
 	backend: string;
 	cwd: string;
 	mcpServerNames: readonly string[];
@@ -58,6 +108,14 @@ export function buildPiContextAugment(params: PiContextAugmentParams): string {
 
 	const sections: string[] = [];
 
+	// System-prompt-carrier-less backend (cortex): the operator engraving leads the augment,
+	// since there is no `_meta.systemPrompt` carrier to hold it. null when no
+	// override is configured — the shipped claude default is never injected here.
+	if (CARRIER_LESS_BACKENDS.has(params.backend)) {
+		const engraving = loadCarrierlessOperatorEngraving(params.backend, params.mcpServerNames);
+		if (engraving) sections.push(engraving);
+	}
+
 	// Bridge identity + caller-side sibling stance. The closing line is a
 	// caller-perspective statement: when THIS session throws an entwurf, the peer
 	// on the other end is a sibling, not a worker.

package/pi-extensions/lib/acp/backend-adapter.ts

@@ -19,15 +19,32 @@
 
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import type { AcpConnectionLike } from "./acp-client.js";
-import type { ResolvedAcpConfig } from "./config.js";
+import { enrichMcpServersWithEnvelope, type ResolvedAcpConfig } from "./config.js";
 import { loadEngraving } from "./engraving.js";
-import { curatedClaudeModels, SUPPORTED_ANTHROPIC_MODEL_IDS } from "./models.js";
-import { claudeLaunchEnvDefaults, ensureClaudeConfigOverlay } from "./overlay.js";
+import {
+	CORTEX_MODEL_PREFIX,
+	curatedClaudeModels,
+	curatedCortexModels,
+	SUPPORTED_ANTHROPIC_MODEL_IDS,
+	SUPPORTED_CORTEX_MODEL_IDS,
+} from "./models.js";
+import { claudeLaunchEnvDefaults, ensureClaudeConfigOverlay, ensureCortexDualHomeOverlay } from "./overlay.js";
 import { buildClaudeSessionMeta } from "./tool-surface.js";
 
+// POSIX-safe single-quote wrapper for shell arg interpolation. Byte-for-byte
+// identical to the reference in entwurf-core.ts; PARITY-PINNED by
+// scripts/check-shell-quote.ts (SOURCE_SITES). Used only by the cortex override
+// path below, where operator-configured connection/model tokens are appended to
+// an operator `bash -lc` string — quoting keeps a connection name with shell
+// metacharacters from being reinterpreted by the shell.
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
 // ---------------------------------------------------------------------------
 // Shared shapes
 // ---------------------------------------------------------------------------
@@ -64,13 +81,19 @@ export interface AcpCarrierParams {
 
 /** ensureOverlay input — cwd + (native) model id + the resolved config. A backend
  *  whose overlay/env depends on its OWN settings reads them off `config.adapterSettings`
- *  here; backend.ts never inspects config. Same shape as AcpLaunchParams (overlay and
- *  launch are distinct phases, so they keep distinct names). */
+ *  here; backend.ts never inspects config. Same shape as AcpLaunchParams plus the
+ *  session key (overlay and launch are distinct phases, so they keep distinct names). */
 export interface AcpOverlayParams {
 	cwd: string;
 	modelId: string;
 	nativeModelId: string;
 	config: ResolvedAcpConfig;
+	/** The AUTHORITATIVE per-session key backend.ts already computed
+	 *  (resolveSessionKey: opts.sessionId → PI_SESSION_ID → cwd). A session-scoped
+	 *  overlay MUST scope on this value, never on an ambient re-derivation — the
+	 *  re-derived form drops `opts.sessionId`, so two sessions in one process/cwd
+	 *  would alias one overlay (GPT review 2026-07-29, cortex P0-1). */
+	sessionKey: string;
 }
 
 /** buildSessionMeta input — mirrors the newSession `_meta` inputs. */
@@ -270,9 +293,161 @@ export const claudeAdapter: AcpBackendAdapter = {
 // ---------------------------------------------------------------------------
 
 /** Registered adapters. Order carries NO routing authority — routeModel decides.
- *  Step A: claude only. A second backend appends here with its reserved prefix
- *  (e.g. `<backend>-*`), and the fail-fast below proves no two adapters claim one id. */
-const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter];
+ *  claude (unprefixed ids) + cortex (the `cortex-` prefix). A further backend
+ *  appends here with its own reserved prefix; the fail-fast below proves no two
+ *  adapters claim one id. */
+// ---------------------------------------------------------------------------
+// cortex adapter — Snowflake Cortex Code, the first non-claude backend on the
+// rail (docs/acp-backend-rail.md §4/§6). It adds ZERO to the common layer:
+// everything cortex-specific lives here + models.ts + overlay.ts + the gates.
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_CORTEX_IDS: ReadonlySet<string> = new Set(SUPPORTED_CORTEX_MODEL_IDS);
+
+/** Cortex's OWN settings (§10 B): a Snowflake connection name, or null. Opaque to
+ *  config.ts / backend.ts — only cortexAdapter reads it (casting back). */
+export interface CortexAdapterSettings {
+	cortexConnection: string | null;
+}
+
+/** The env var an operator sets to pin a Snowflake connection per-shell without
+ *  editing settings.json. Wins over `entwurfProvider.cortexConnection`. The
+ *  ENTWURF_ACP_* convention (PR #40's legacy PI_SHELL_ACP* cortex-connection var renamed). */
+export const CORTEX_CONNECTION_ENV = "ENTWURF_ACP_CORTEX_CONNECTION";
+
+export const cortexAdapter: AcpBackendAdapter = {
+	backend: "cortex",
+
+	// Cortex owns the reserved `cortex-` prefix (§9-1). routeModel strips it to the
+	// native id: `cortex-auto` → "auto", `cortex-claude-sonnet-5` → "claude-sonnet-5".
+	routeModel(modelId) {
+		if (!SUPPORTED_CORTEX_IDS.has(modelId)) return undefined;
+		return { nativeModelId: modelId.slice(CORTEX_MODEL_PREFIX.length) };
+	},
+
+	curatedModels() {
+		return curatedCortexModels();
+	},
+
+	// Cortex's ONLY own setting is the connection name. env override wins over
+	// settings (per-shell pin); empty/whitespace → null (Cortex falls back to its
+	// own default connection). A non-string settings value fails loud.
+	resolveAdapterSettings({ mergedBlock, projectBlock, globalPath, projectPath }): CortexAdapterSettings {
+		const raw = mergedBlock.cortexConnection;
+		if (raw !== undefined && typeof raw !== "string") {
+			const offending = projectBlock.cortexConnection !== undefined ? projectPath : globalPath;
+			throw new Error(`${offending}: invalid entwurfProvider settings: cortexConnection must be a string`);
+		}
+		const envConn = process.env[CORTEX_CONNECTION_ENV]?.trim();
+		const settingsConn = raw?.trim();
+		const cortexConnection = envConn || settingsConn || null;
+		return { cortexConnection };
+	},
+
+	// `cortex acp serve` resolved from PATH (the CLI itself IS the ACP server — no
+	// `*-acp` npm package, unlike claude). `-c <conn>` appended when a connection
+	// is pinned. NO `-m`: the model is enforced per-turn via
+	// session/set_config_option (enforceModel below, CP0-M measured GO) and a
+	// launch pin would be a SECOND model authority that drifts from it.
+	// CORTEX_ACP_COMMAND override runs via `bash -lc` with the selection flags
+	// appended so the bridge's choice wins (later yargs args override earlier ones).
+	resolveLaunch({ config }) {
+		const settings = config.adapterSettings as CortexAdapterSettings | undefined;
+		const connection = settings?.cortexConnection?.trim() || undefined;
+		const selectionArgs: string[] = [];
+		if (connection) selectionArgs.push("-c", connection);
+		const override = process.env.CORTEX_ACP_COMMAND?.trim();
+		if (override) {
+			const command = selectionArgs.length > 0 ? `${override} ${selectionArgs.map(shellQuote).join(" ")}` : override;
+			return { command: "bash", args: ["-lc", command] };
+		}
+		return { command: "cortex", args: ["acp", "serve", ...selectionArgs] };
+	},
+
+	// The overlay location is SESSION-SCOPED (never static), so the spawn env
+	// rides ensureOverlay(...).envOverrides; there is no static launch env. The
+	// v1.1.8-era CORTEX_DISABLE_AUTO_APPLY_PROFILES knob was retired with the
+	// dual-HOME redesign: profiles now live inside the overlay-owned isolated
+	// home (empty by construction), and the knob is unmeasured on v1.1.52.
+	launchEnvDefaults() {
+		return {};
+	},
+
+	// Dual-HOME containment (CP0 D2/D3/D9/D10 — see the overlay module header):
+	// refuse an ambient CORTEX_HOME outright, then materialize the session-scoped
+	// isolated HOME with auth symlinks, `autoUpdate:false`, and the mcp.json
+	// projection of the envelope-enriched explicit servers (cortex ignores the
+	// wire mcpServers param, so this file IS how tools reach a cortex session).
+	ensureOverlay({ modelId, config, sessionKey }) {
+		// D3 — presence refusal, empty string included: upstream's resolver treats
+		// a set-but-empty CORTEX_HOME differently from unset, and one ambient value
+		// would silently bypass SNOWFLAKE_HOME (the probe's CLAUDE_CODE_EXECUTABLE
+		// precondition is the same family). Refuse the ambiguity; never pick a side.
+		if ("CORTEX_HOME" in process.env) {
+			throw new Error(
+				"entwurf: CORTEX_HOME is present in the environment (empty string included) — it overrides " +
+					"SNOWFLAKE_HOME inside cortex and would bypass the dual-HOME overlay entirely (CP0 D3). " +
+					"Unset it to run a cortex ACP turn.",
+			);
+		}
+		// The scope authority is the AUTHORITATIVE params.sessionKey backend.ts
+		// computed — never an ambient re-derivation, which would drop opts.sessionId
+		// and alias two same-process/cwd sessions onto one overlay (P0-1). The
+		// envelope below still reads PI_SESSION_ID: that is the identity CARRIER for
+		// the bridge child (the same source the turn loop's wire enrichment uses),
+		// a different axis from overlay-dir scoping.
+		const piSessionId = process.env.PI_SESSION_ID?.trim() || undefined;
+		const enriched = enrichMcpServersWithEnvelope(config.mcpServers, { modelId, piSessionId });
+		const overlay = ensureCortexDualHomeOverlay({
+			scopeKey: sessionKey,
+			mcpServers: enriched,
+			realHome: homedir(),
+		});
+		return { envOverrides: { HOME: overlay.home, SNOWFLAKE_HOME: overlay.snowflakeHome } };
+	},
+
+	// System-prompt-carrier-less (§9-4/§11-8): Cortex ACP exposes no
+	// `_meta.systemPrompt` and has no developer_instructions / GEMINI_SYSTEM_MD
+	// equivalent. (It does READ `_meta` — a caller-session-id seam, measured but
+	// unexplored and deliberately not part of this contract.) loadCarrier returns
+	// null WITHOUT calling loadEngraving, so the cortex turn never touches the
+	// shipped-engraving / appendSystemPrompt signature; buildSessionMeta returns
+	// undefined so backend.ts omits the `_meta` key entirely. The operator
+	// engraving instead rides the first-user augment (augment.ts).
+	loadCarrier() {
+		return null;
+	},
+
+	buildSessionMeta() {
+		return undefined;
+	},
+
+	// Per-turn enforcement via session/set_config_option — the SAME wire call the
+	// claude adapter makes, measured live against cortex v1.1.52 (CP0-M): the
+	// option id is "model", accepted values are the NATIVE ids (`auto`,
+	// `claude-sonnet-5`, `openai-gpt-5.4`, …), and a value cortex no longer
+	// serves fails loud BEFORE the prompt (`Unsupported model: …`). PR #40's
+	// launch-time `-m` pin was retired for this: set-model is the single model
+	// authority (resolveLaunch never passes `-m`), and "auto" is set explicitly
+	// rather than treated as an unspoken default.
+	async enforceModel({ connection, acpSessionId, nativeModelId, modelId }) {
+		const setConfig = connection.setSessionConfigOption;
+		if (typeof setConfig !== "function") {
+			throw new Error(`setSessionConfigOption unsupported — cannot enforce model ${modelId}`);
+		}
+		await setConfig.call(connection, { sessionId: acpSessionId, configId: "model", value: nativeModelId });
+	},
+
+	// A connection change must invalidate a reused session (§4/§7). Flat,
+	// sorted-stable primitive map; reads ONLY the opaque adapterSettings. `backend`
+	// + `nativeModelId` are added by backend.ts.
+	configSignatureFields(adapterSettings) {
+		const settings = adapterSettings as CortexAdapterSettings | undefined;
+		return { cortexConnection: settings?.cortexConnection ?? null };
+	},
+};
+
+const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];
 
 /**
  * Resolve the backend adapter that owns `modelId`.

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

@@ -644,7 +644,11 @@ export function streamAcpTurn(
 			pushAcpLifecycleNotice(state, `preparing ${adapter.backend} session`);
 			// GPT §9-5: materialize the overlay first, then spawn with launchEnvDefaults
 			// + overlay.envOverrides merged over process.env (defaultDeps spawnChild).
-			const overlay = adapter.ensureOverlay({ cwd, modelId: model.id, nativeModelId, config });
+			// sessionKey is the AUTHORITATIVE per-session identity (resolveSessionKey:
+			// opts.sessionId → PI_SESSION_ID → cwd) — a session-scoped overlay must
+			// scope on it, so it rides the params explicitly and the adapter never
+			// re-derives a weaker key from ambient env (P0-1).
+			const overlay = adapter.ensureOverlay({ cwd, modelId: model.id, nativeModelId, config, sessionKey });
 			const launch = adapter.resolveLaunch({ cwd, modelId: model.id, nativeModelId, config });
 			child = deps.spawnChild(launch, cwd, { ...adapter.launchEnvDefaults(), ...overlay.envOverrides });
 			const spawned = child;

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

@@ -8,11 +8,23 @@
 // config and hands it to the backend so the documented passthrough actually
 // reaches `newSession`.
 //
-// Claude-only scope (NEXT §스코프). Ported from the v0.11.0 behavior oracle
-// (index.ts `loadProviderSettings`/`readSettingsFile` + acp-bridge.ts
+// Scope. Ported from the v0.11.0 behavior oracle (index.ts
+// `loadProviderSettings`/`readSettingsFile` + acp-bridge.ts
 // `normalizeMcpServers`/`enrichMcpServersWithEnvelope`) — structure new, behavior
-// preserved. Codex/Gemini fields (codexDisabledFeatures, …) are out of scope and
-// deliberately NOT carried.
+// preserved. Retired Codex/Gemini-era fields (codexDisabledFeatures, …) are NOT
+// carried and are silently ignored if present.
+//
+// The COMMON keys parsed here are Claude-SHAPED by origin (tools / permissionAllow /
+// disallowedTools / settingSources / skillPlugins are claude-agent-acp's surface).
+// What varies per backend is whether they are PROJECTED ONTO THE BACKEND SESSION —
+// not whether they are read at all. Cortex runs native tools and reaches MCP through
+// its own overlay mcp.json projection, so none of those keys shape a cortex session;
+// they nonetheless stay live on the common path, where backend.ts reads `tools` for
+// the backend-invariant exclude-tools preflight and folds every one of them into
+// `bridgeConfigSignature` (so changing one still invalidates a reused cortex
+// session). Backend-OWNED settings never land here: they ride the opaque
+// `adapterSettings` seam (§10 B), which is what keeps a backend-named key like
+// `cortexConnection` off this common shape.
 //
 // PURITY / SIGNATURE contract (NEXT oracle C / 핀1 / GPT `…2f9325` boost):
 //   - `normalizeMcpServers` is pure: a SORTED, validated server list + a sha256
@@ -71,7 +83,9 @@ export interface ProviderSettings {
 	disallowedTools?: string[];
 }
 
-/** The fully-resolved Claude provider config the backend hands to newSession. */
+/** The fully-resolved common provider config the turn loop hands to newSession.
+ *  Claude-shaped by origin; a backend reads only the fields it consumes, and its
+ *  OWN keys ride `adapterSettings`. */
 export interface ResolvedAcpConfig {
 	/** Operator-declared backend (diagnostic guard only — see ProviderSettings.backend).
 	 *  backend.ts asserts this matches the adapter the model id routes to. */

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

@@ -44,7 +44,9 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ENGRAVING_PATH = join(HERE, "prompts", "engraving.md");
 
 export interface EngravingParams {
-	/** Claude-only this cut; kept as a field so the `{{backend}}` token interpolates. */
+	/** Always "claude" in practice — a system-prompt-carrier-less backend (cortex)
+	 *  returns null from `loadCarrier` WITHOUT calling this loader, so claudeAdapter is
+	 *  its only caller. Kept as a field so the `{{backend}}` token interpolates. */
 	backend: string;
 	/** MCP server names exposed to the session. SORTED before render for determinism. */
 	mcpServerNames: readonly string[];

package/pi-extensions/lib/acp/event-mapper.ts

@@ -4,11 +4,18 @@
 // AssistantMessageEvent protocol (text/thinking blocks + tool/permission
 // notices + usage), maintaining a running `partial: AssistantMessage`.
 //
-// Claude-only collapse (NEXT §스코프 + oracle F): the 0.11.0 event-mapper
+// Single-dialect collapse (NEXT §스코프 + oracle F): the 0.11.0 event-mapper
 // reconciled three backend dialects (Claude rawOutput=array / Codex
 // CallToolResult / Gemini content[]) plus an entwurf_v2 sent-box custom promotion.
-// This lane drives ONLY claude-agent-acp, so the dialect collapses to one
-// (rawOutput=array) and the entwurf/gemini/codex special-casing is dropped.
+// This lane collapsed that to ONE dialect (rawOutput=array) and dropped the
+// entwurf/gemini/codex special-casing.
+//
+// This module is COMMON layer, not a claude module: the cortex landing reused THIS
+// FILE with no adapter branch and no edit, and the CP2 LIVE turn ran through it.
+// (That is a fact about this mapper only — the landing did touch other common files,
+// e.g. backend.ts's overlay call site.) The collapse is therefore a standing bet,
+// not a proof: a future backend whose session_notification dialect differs from
+// rawOutput=array reopens this file rather than forking it per backend.
 //
 // CRITICAL boundary (GPT S2c Q3): an ACP `tool_call` / `tool_call_update` is
 // rendered as an INFORMATIONAL TEXT NOTICE, never a structured pi `toolcall_*`