@junghanacs/entwurf 0.12.10 → 0.13.0

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 (§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/
@@ -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 §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";
+/** 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 };
+}

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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.12.10",
+	"version": "0.13.0",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for Claude Code, Codex, Antigravity, and pi harnesses.",
 	"license": "MIT",
 	"author": {
@@ -121,6 +121,8 @@
 		"check-acp-carrier-augment": "./run.sh check-acp-carrier-augment",
 		"check-agy-permission-matrix": "./run.sh check-agy-permission-matrix",
 		"check-gate-qualification": "./run.sh check-gate-qualification",
+		"check-probe-ordering": "./run.sh check-probe-ordering",
+		"check-probe-cli-shim": "./run.sh check-probe-cli-shim",
 		"check-pack": "./run.sh check-pack",
 		"check-pack-install": "./run.sh check-pack-install",
 		"check-install-container": "./run.sh check-install-container",
@@ -130,7 +132,7 @@
 		"format": "biome check --write .",
 		"check-meta-manifest-schema": "./run.sh check-meta-manifest-schema",
 		"check-package-source-routing": "./run.sh check-package-source-routing",
-		"check": "pnpm lint && pnpm typecheck && ./run.sh check-shell-quote && ./run.sh check-install-surface && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-capability-bundle-reach && ./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-hook-launch-topology && ./run.sh check-meta-identity-consumers && ./run.sh check-meta-capability-source && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh smoke-meta-install-state && ./run.sh check-meta-doctor-oracle && ./run.sh smoke-agy-install-state && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-package-source-routing && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-install-preflight && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-boot && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-v2-spawn && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-spawn-production && ./run.sh check-entwurf-facts && ./run.sh check-control-socket-path && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-agy-sender-identity && ./run.sh check-auth-boundary && ./run.sh check-acp-provider-surface && ./run.sh check-acp-sdk-surface && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-acp-carrier-augment && ./run.sh check-gate-qualification && ./run.sh check-pack"
+		"check": "pnpm lint && pnpm typecheck && ./run.sh check-shell-quote && ./run.sh check-install-surface && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-capability-bundle-reach && ./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-hook-launch-topology && ./run.sh check-meta-identity-consumers && ./run.sh check-meta-capability-source && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh smoke-meta-install-state && ./run.sh check-meta-doctor-oracle && ./run.sh smoke-agy-install-state && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-package-source-routing && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-install-preflight && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-boot && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-v2-spawn && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-spawn-production && ./run.sh check-entwurf-facts && ./run.sh check-control-socket-path && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-agy-sender-identity && ./run.sh check-auth-boundary && ./run.sh check-acp-provider-surface && ./run.sh check-acp-sdk-surface && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-acp-carrier-augment && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./run.sh check-gate-qualification && ./run.sh check-pack"
 	},
 	"pi": {
 		"extensions": [

package/pi/settings.reference.json

@@ -32,7 +32,7 @@
 			"WebFetch",
 			"WebSearch"
 		],
-		"codexDisabledFeatures": ["image_generation", "tool_suggest", "tool_search", "multi_agent", "apps", "memories"],
+		"cortexConnection": "MY_SNOWFLAKE_CONNECTION",
 		"mcpServers": {
 			"entwurf-bridge": {
 				"command": "/path/to/entwurf/mcp/entwurf-bridge/start.sh",

package/pi-extensions/acp-provider.ts

@@ -2,11 +2,19 @@
 //
 // This is the pi-extension entry point that registers `entwurf` as a pi
 // session provider/model. It is intentionally THIN: it stands up the provider
-// surface (curated Claude anchor + no-auth sentinel) and wires streamSimple to
-// the real ACP backend (lib/acp/backend.ts — spawn-per-turn claude-agent-acp).
-// It does NOT build a socket/peers/citizen protocol or touch the v2 core —
-// socket-citizenship is supplied by the host `--entwurf-control` pi session
-// (AGENTS §ACP Plugin Boundary).
+// surface (every registered adapter's curated rows + the no-auth sentinel) and
+// wires streamSimple to the real ACP backend (lib/acp/backend.ts — a
+// spawn-per-turn ACP child, `claude-agent-acp` or `cortex acp serve` depending
+// on which adapter the model id routes to). It does NOT build a
+// socket/peers/citizen protocol or touch the v2 core — socket-citizenship is
+// supplied by the host `--entwurf-control` pi session (AGENTS §ACP Plugin
+// Boundary).
+//
+// The model set comes from `allCuratedModels()` — the union across the adapter
+// registry (backend-adapter.ts), NOT a per-backend list spelled here. Adding a
+// backend therefore never edits this file. check-acp-provider-surface pins that
+// the compiled entry really registers the EXACT union
+// ([QK:CORTEX-PROVIDER-SIX-ROW-SURFACE]).
 //
 // Fence: this entry rides the emit-capable root tsconfig (it is not in the root
 // `exclude` list); its lib modules are imported with `.js` suffixes (the root
@@ -49,14 +57,16 @@ export default function (pi: ExtensionAPI) {
 		apiKey: ENTWURF_ACP_NO_AUTH_SENTINEL,
 		api: "entwurf",
 		models: allCuratedModels(),
-		// S2c: real ACP backend. Spawn-per-turn claude-agent-acp drive + event
-		// mapping (lib/acp/backend.ts). The S0 fail-loud stub is gone — the
-		// provider path is open. Backend auth still belongs to the operator's own
-		// Claude CLI child (no-auth sentinel above); this plugin only orchestrates.
+		// S2c: real ACP backend. Spawn-per-turn ACP child + event mapping
+		// (lib/acp/backend.ts); the routed adapter decides WHICH child. The S0
+		// fail-loud stub is gone — the provider path is open. Backend auth still
+		// belongs to the operator's own backend CLI child (no-auth sentinel above);
+		// this plugin only orchestrates.
 		streamSimple: streamShellAcp,
 	});
 
-	// Mark only AFTER a successful registration. If curatedClaudeModels() (a
+	// Mark only AFTER a successful registration. If allCuratedModels() (which
+	// fail-fasts on an unowned/duplicate curated id, and whose claude rows carry a
 	// fail-loud anchor check) or registerProvider throws, the runtime is not left
 	// poisoned with a "registered" marker — a retry can register cleanly.
 	markRegisteredOnRuntime(pi);

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`.