@junghanacs/entwurf 0.12.10 → 0.13.1

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/acp-client.js

@@ -39,6 +39,18 @@ export function connectAcpClient(stream, handlers) {
         newSession: (params) => agent.request(AGENT_METHODS.session_new, params),
         prompt: (params) => agent.request(AGENT_METHODS.session_prompt, params),
         setSessionConfigOption: (params) => agent.request(AGENT_METHODS.session_set_config_option, params),
+        cancel: (params) => {
+            // Notification, not a request: nothing resolves it, and the connection
+            // may already be closing when the operator aborts. Swallow both the sync
+            // throw and the rejected send — the caller's abort path continues either
+            // way (it escalates to teardown after a bounded grace).
+            try {
+                void Promise.resolve(agent.notify(AGENT_METHODS.session_cancel, params)).catch(() => { });
+            }
+            catch {
+                // connection already closed — the abort path escalates on its own.
+            }
+        },
         close: (error) => {
             // Best-effort by contract (see AcpConnectionLike.close): a teardown-path
             // close that threw would mask the turn's real error and skip the child

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/backend-adapter.js

@@ -1,9 +1,10 @@
 // ACP backend adapter rail — the PRODUCT seam by which a curated model id selects
-// which ACP backend (claude / future backend / …) drives a turn. See docs/acp-backend-rail.md §9.
+// which ACP backend (claude / future backend / …) drives a turn. See the adapter contract in
+// docs/acp-backend-rail.md.
 //
 // This seam is DISTINCT from `AcpTurnDeps` (backend.ts), which is the test/runtime
-// seam (fake spawn/connection/clock for the gates). The two are kept apart on
-// purpose (GPT-agreed §9-2): merging them would make a fake-deps fixture look like
+// seam (fake spawn/connection/clock for the gates). Merging them would make a
+// fake-deps fixture look like
 // a fake backend and force the adapter to carry clock/sessionDir/createConnection.
 // The wiring is `defaultDeps(adapter)` — the turn loop in backend.ts stays
 // backend-invariant; only these per-backend functions change with `adapter`.
@@ -18,11 +19,22 @@
 // lib/acp modules — no new strip-types fence.
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { enrichMcpServersWithEnvelope } 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) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
 // ---------------------------------------------------------------------------
 // claude adapter — the first implementation (the rail's reference backend)
 // ---------------------------------------------------------------------------
@@ -43,7 +55,7 @@ function resolveClaudeLaunch() {
 }
 export const claudeAdapter = {
     backend: "claude",
-    // Claude owns its UNPREFIXED curated ids only (GPT-agreed §9-1). The native id
+    // Claude owns its UNPREFIXED curated ids only (rail “Adapter contract”). The native id
     // equals the curated id — claude carries no curation prefix to strip.
     routeModel(modelId) {
         return SUPPORTED_CLAUDE_IDS.has(modelId) ? { nativeModelId: modelId } : undefined;
@@ -105,13 +117,145 @@ export const claudeAdapter = {
 // Registry — modelId → adapter
 // ---------------------------------------------------------------------------
 /** 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 = [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, “Shipped adapters”). It adds ZERO to the common layer:
+// everything cortex-specific lives here + models.ts + overlay.ts + the gates.
+// ---------------------------------------------------------------------------
+const SUPPORTED_CORTEX_IDS = new Set(SUPPORTED_CORTEX_MODEL_IDS);
+/** 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 = {
+    backend: "cortex",
+    // Cortex owns the reserved `cortex-` prefix (rail “Adapter contract”). 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 }) {
+        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;
+        const connection = settings?.cortexConnection?.trim() || undefined;
+        const selectionArgs = [];
+        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 (ACP rail “Cortex Code audit”): 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 (rail: Adapter contract). Flat,
+    // sorted-stable primitive map; reads ONLY the opaque adapterSettings. `backend`
+    // + `nativeModelId` are added by backend.ts.
+    configSignatureFields(adapterSettings) {
+        const settings = adapterSettings;
+        return { cortexConnection: settings?.cortexConnection ?? null };
+    },
+};
+const ADAPTERS = [claudeAdapter, cortexAdapter];
 /**
  * Resolve the backend adapter that owns `modelId`.
  *
- * GPT-agreed §9-1 fail-fast contract:
+ * Routing fail-fast contract (rail “Adapter contract”):
  *  - 0 matches  → throw (unknown model — no silent default).
  *  - 2+ matches → throw (prefix collision — a startup-visible registry bug).
  *
@@ -135,7 +279,7 @@ export function resolveAcpBackendAdapter(modelId) {
     return matches[0];
 }
 /** Every curated model row across all registered adapters — for provider registration.
- *  GPT-agreed §9-6 registration-time fail-fast: every curated id must route to EXACTLY
+ *  Registration-time fail-fast (rail “Adapter contract”): every curated id must route to EXACTLY
  *  one adapter and no id may be duplicated across adapters. Catching it here means a
  *  prefix-collision / duplicate surfaces at provider registration, not mid-turn. */
 export function allCuratedModels() {

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/config.js

@@ -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 (rail “Adapter contract”), 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

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/engraving.js

@@ -35,11 +35,30 @@
 // incompatible and the next turn opens a fresh ACP session with the new carrier.
 // That per-turn rebuild is the accepted cost of the A/B opt-in surface, never the
 // shipped default (which stays cached precisely so a resident never rebuilds).
+//
+// A-JOIN (measured LIVE 2026-07-31, 0.64.0 adapter, fresh Claude ACP): the model's
+// system prompt arrived as
+//   `You are a Claude agent, built on Anthropic's Claude Agent SDK.# Engraving Here`
+// A string-form `_meta.systemPrompt` replaces the `claude_code` preset, but the
+// SDK still PREFIXES its own fixed identity sentence and joins the two with
+// NOTHING — so the operator's heading was swallowed into the tail of the SDK's
+// sentence. The boundary therefore belongs to the CARRIER, and it cannot be
+// delegated to engraving.md: the render is trimmed (below), so a leading blank
+// line in the markdown is eaten before it ever reaches the wire.
 import { readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ENGRAVING_PATH = join(HERE, "prompts", "engraving.md");
+/**
+ * The carrier's LEADING boundary — the one the Claude Agent SDK does not supply
+ * (see A-JOIN above). A constant, never derived from the template, so the render
+ * stays a pure function of (template, backend, mcpServerNames) and the operator's
+ * file whitespace can never drift `bridgeConfigSignature`. One blank line is the
+ * whole lever: it puts the carrier's first line at the start of its own block
+ * instead of at the end of the SDK's fixed sentence.
+ */
+export const CARRIER_LEAD_SEPARATOR = "\n\n";
 let cached = null;
 /** Point the loader at an alternate engraving file (A/B); bypasses the cache. */
 function resolveEngravingPath() {
@@ -65,6 +84,22 @@ function interpolate(template, params) {
     const mcpList = names.length > 0 ? names.join(", ") : "(none registered)";
     return template.replace(/\{\{backend\}\}/g, params.backend).replace(/\{\{mcp_servers\}\}/g, mcpList);
 }
+/**
+ * Render one template into a wire-ready carrier, or `""` when the template has no
+ * body (the caller turns that into the opt-out / fail-loud branches).
+ *
+ * The ORDER here is the A-join fix. Trim first: the operator template's own
+ * leading/trailing whitespace must not reach the wire (it would drift
+ * bridgeConfigSignature) and the emptiness test must see the BODY — a
+ * separator-only string is an opt-out, not a carrier. Then attach OUR boundary,
+ * which is what the SDK's fixed sentence has nothing of.
+ */
+function renderCarrier(source, params) {
+    const body = interpolate(source, params).trim();
+    if (body.length === 0)
+        return "";
+    return `${CARRIER_LEAD_SEPARATOR}${body}`;
+}
 /**
  * The rendered engraving carrier, or null when an ENV-OVERRIDE engraving file
  * (`ENTWURF_ACP_ENGRAVING_PATH`) is empty, whitespace-only, missing, or
@@ -77,6 +112,12 @@ function interpolate(template, params) {
  * Callers MUST treat null as "no carrier configured" and omit `_meta.systemPrompt`
  * entirely (passing "" as the `appendSystemPrompt` signature input) so
  * subscription billing is never reclassified.
+ *
+ * A non-null carrier always LEADS with `CARRIER_LEAD_SEPARATOR`, and callers must
+ * pass it on BYTE-FOR-BYTE: the same string feeds `bridgeConfigSignature`
+ * (`appendSystemPrompt`) and the wire (`_meta.systemPrompt`), so normalizing it at
+ * either hop both re-opens the A-join and makes reuse key on a string that was
+ * never sent.
  */
 export function loadEngraving(params) {
     const filePath = resolveEngravingPath();
@@ -92,7 +133,7 @@ export function loadEngraving(params) {
         }
         return null;
     }
-    const rendered = interpolate(source, params).trim();
+    const rendered = renderCarrier(source, params);
     if (rendered.length === 0) {
         if (isShippedDefault) {
             throw new Error(`entwurf: shipped engraving carrier at ${filePath} is empty — it is the auto-memory ` +

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/models.js

@@ -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 “Cortex Code audit”). Codex has native
+// delivery-probe evidence but no managed citizen lane; neither it nor Gemini 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
 // `@earendil-works/pi-ai/compat` entrypoint (the global-API churn). We import it
@@ -71,6 +74,62 @@ function requireRegistryModel(models, id) {
 function claudeContextWindow(model) {
     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, “Shipped adapters”). pi-ai carries no
+// snowflake/cortex model source, so this surface is HAND-CURATED. Every id
+// carries the reserved `cortex-` prefix: 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",
+];
+// 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, name, base) => ({
+        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/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/overlay.js

@@ -9,11 +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. Claude is the one
-// shipped ACP backend, so this materializer is written for its config surface alone.
-// Codex/Gemini overlays (CODEX_HOME / admin.toml) are behavior-oracle territory and
-// out of scope here; a SECOND ACP backend enters only once the entry conditions in
-// docs/acp-backend-rail.md are met, and it brings its own overlay.
+// 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 (ACP rail Cortex audit 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/
@@ -28,6 +32,7 @@
 // answering — 0.11.0 LIVE probe). Keeping it `{}` inherits NO operator hook —
 // 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, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -194,3 +199,183 @@ export function ensureClaudeConfigOverlay(realDir = CLAUDE_REAL_CONFIG_DIR, over
         }
     }
 }
+// ============================================================================
+// 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 “Cortex Code audit”).
+// ============================================================================
+//
+// Why this is NOT the claude-shaped `SNOWFLAKE_HOME`-only overlay PR #40 shipped
+// (each point is a measured defect, not a preference — Cortex audit 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";
+/** Deterministic per-(host process, session key) overlay dir name. */
+export function cortexOverlayScopeId(scopeKey, pid = process.pid) {
+    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() {
+    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, realHome) {
+    const out = {};
+    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;
+        const env = {};
+        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) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM = alive but not ours; anything else (ESRCH) = gone.
+        return error.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, isPidAlive = cortexPidAlive) {
+    let entries;
+    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, overlayPath) {
+    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) {
+    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 };
+}