@junghanacs/entwurf 0.12.10 → 0.13.1

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_*`
@@ -32,7 +39,6 @@ export interface AcpStreamIdentity {
 type ObservedToolState = {
 	title: string;
 	status?: string;
-	notifiedRunning?: boolean;
 };
 
 export type AcpPiStreamState = {
@@ -74,7 +80,12 @@ export function createAcpStreamState(
 		provider: identity.provider,
 		model: identity.model,
 		usage: zeroUsage(),
-		stopReason: "stop",
+		// Seed, not a verdict. pi 0.83 added "pending" for exactly this: a partial
+		// streaming message has not observed a terminal reason yet, and every pi
+		// provider seeds it here and treats a stream that ENDS still-pending as an
+		// error rather than a successful stop. Seeding "stop" instead would
+		// pre-claim success for the whole time the turn is in flight.
+		stopReason: "pending",
 		timestamp: opts?.timestamp ?? Date.now(),
 	};
 	return {
@@ -214,22 +225,21 @@ function renderToolUpdate(state: AcpPiStreamState, update: Record<string, unknow
 	const title = titleForTool(update, previous?.title);
 	const status = typeof update?.status === "string" ? (update.status as string) : previous?.status;
 	const updateContent = Array.isArray(update?.content) ? (update.content as unknown[]) : undefined;
-	const meta = update?._meta as { terminal_output?: unknown } | undefined;
-
-	let notifiedRunning = previous?.notifiedRunning;
 
 	if (update.sessionUpdate === "tool_call") {
-		observedTools.set(toolCallId, { title, status, notifiedRunning });
+		observedTools.set(toolCallId, { title, status });
 		pushNotice(state, `\n[tool:start] ${sanitizeNoticeFragment(title, NOTICE_TITLE_MAX)}\n`);
 		return;
 	}
 
-	// tool_call_update
-	if (meta?.terminal_output && !notifiedRunning) {
-		notifiedRunning = true;
-		pushNotice(state, `\n[tool:running] ${sanitizeNoticeFragment(title, NOTICE_TITLE_MAX)}\n`);
-	}
-
+	// tool_call_update. There is deliberately no mid-flight `[tool:running]`
+	// notice: it would have to be driven by the adapter's `_meta.terminal_output`,
+	// and that meta is gated upstream on `clientCapabilities._meta.terminal_output
+	// === true` while backend.ts initializes with `clientCapabilities: {}`. So the
+	// branch could never fire for any backend we ship — it claimed a transcript
+	// line the operator was never going to see. Declaring the terminal capability
+	// is a separate axis, not a one-line re-enable: the adapter would then send
+	// terminal widgets/metas this mapper cannot render honestly into a transcript.
 	if (status && status !== previous?.status) {
 		const summary = firstTextContent(update?.rawOutput) ?? firstTextContent(updateContent);
 		const suffix = summary ? ` — ${sanitizeNoticeFragment(summary, NOTICE_SUMMARY_MAX)}` : "";
@@ -243,7 +253,7 @@ function renderToolUpdate(state: AcpPiStreamState, update: Record<string, unknow
 		}
 	}
 
-	observedTools.set(toolCallId, { title, status, notifiedRunning });
+	observedTools.set(toolCallId, { title, status });
 }
 
 /** Push a permission-decision notice (informational text, not a tool call). */

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

@@ -1,14 +1,17 @@
-// ACP plugin — curated Claude model surface (S0 loader/fence slice).
+// ACP plugin — curated model surface (S0 loader/fence slice; cortex rows added
+// in 0.13).
 //
 // entwurf is an ACP *plugin* on the v2 core, NOT a general-purpose
 // Anthropic provider. It deliberately does not expose the full pi-ai model
-// registry — the surface is curated to the Claude anchor the plugin commits to
-// driving through a real ACP backend (the backend lands in S2; S0 only stands
-// the provider/model surface up).
+// registry — the surface is curated to the ids the plugin commits to driving
+// through a real ACP backend.
 //
-// Claude-first scope (NEXT §스코프): Codex is already a native garden citizen
-// and Gemini / major tools use native, so the curated surface is Claude-only on
-// this lane. A second governed backend would EXTEND this set — it does not change
+// Two curated sets live here, one per adapter on the rail
+// (backend-adapter.ts): the unprefixed Claude ids (the reference backend) and
+// the `cortex-` prefixed Snowflake Cortex Code ids (the second backend, landed
+// 0.13.0 — docs/acp-backend-rail.md “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
@@ -81,6 +84,65 @@ function claudeContextWindow(model: { id: string; contextWindow: number }): numb
 	return Math.min(model.contextWindow, CLAUDE_CONTEXT_DEFAULT);
 }
 
+// ── Cortex (Snowflake Cortex Code) curated surface ──────────────────────────
+//
+// entwurf's ACP rail is backend-extensible: Cortex is the first NON-claude
+// backend to land through it (docs/acp-backend-rail.md, “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",
+] as const;
+
+// Hand-set conservative context window. Cortex reports the LIVE window via its
+// own ACP session config, not this curated metadata — this is a floor for the
+// registry surface, deliberately not inflated to the Claude 1M.
+const CORTEX_CONTEXT_DEFAULT = 200_000;
+
+/**
+ * The curated Cortex model rows handed to the single `entwurf` provider via
+ * `allCuratedModels()`. The two Claude rows ride their OWN registry base
+ * (opus-5 / sonnet-5); `auto` (default family Claude) and the GPT row (no pi-ai
+ * source) ride the sonnet-5 base as a metadata floor. id / name / contextWindow
+ * are overridden; the `cortex-` prefix keeps them from colliding with the
+ * Claude curated ids. Same row shape as `curatedClaudeModels()` (AcpModelRow).
+ */
+export function curatedCortexModels() {
+	const sonnetBase = requireRegistryModel(ANTHROPIC_MODELS_ALL, "claude-sonnet-5");
+	const opusBase = requireRegistryModel(ANTHROPIC_MODELS_ALL, "claude-opus-5");
+	const row = (id: string, name: string, base: RegistryModel) => ({
+		id,
+		name,
+		reasoning: base.reasoning,
+		input: base.input,
+		cost: base.cost,
+		contextWindow: CORTEX_CONTEXT_DEFAULT,
+		maxTokens: base.maxTokens,
+	});
+	return [
+		row("cortex-auto", "Cortex · Auto", sonnetBase),
+		row("cortex-claude-opus-5", "Cortex · Claude Opus 5", opusBase),
+		row("cortex-claude-sonnet-5", "Cortex · Claude Sonnet 5", sonnetBase),
+		row("cortex-openai-gpt-5.4", "Cortex · OpenAI GPT-5.4", sonnetBase),
+	];
+}
+
 /**
  * The curated Claude model rows handed to `pi.registerProvider({ models })`.
  * Fail-loud if the anchor is absent from the pi-ai registry.

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

@@ -9,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/
@@ -29,6 +33,7 @@
 // which is exactly the "mailbox absence by design" the plugin commits to
 // (no meta-bridge hook on this child's settings surface → no mailbox).
 
+import { createHash } from "node:crypto";
 import {
 	existsSync,
 	lstatSync,
@@ -43,6 +48,8 @@ import {
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import type { AcpMcpServer } from "./config.js";
+
 /** Operator's real Claude config dir — the symlink-passthrough SOURCE. */
 export const CLAUDE_REAL_CONFIG_DIR = join(homedir(), ".claude");
 
@@ -220,3 +227,225 @@ export function ensureClaudeConfigOverlay(
 		}
 	}
 }
+
+// ============================================================================
+// Cortex dual-HOME overlay — the as-measured containment for `cortex acp serve`
+// (CP0 audit 2026-07-29, Cortex Code v1.1.52; docs/acp-backend-rail.md “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";
+
+export interface CortexOverlayParams {
+	/** Session/child scope discriminator (PI_SESSION_ID, else a cwd-derived key).
+	 *  Identity for overlay-dir separation only — never an address authority. */
+	scopeKey: string;
+	/** Normalized + envelope-enriched MCP servers to project into mcp.json. */
+	mcpServers: readonly AcpMcpServer[];
+	/** Absolute real operator HOME captured by the parent BEFORE spawn (D10). */
+	realHome: string;
+	/** Real snowflake home (auth source). Defaults to `<realHome>/.snowflake`. */
+	realSnowflakeHome?: string;
+	/** Overlay root override (tests). Defaults to CORTEX_OVERLAYS_ROOT. */
+	overlaysRoot?: string;
+	/** pid-liveness probe override (tests) for the dead-scope sweep. */
+	isPidAlive?: (pid: number) => boolean;
+}
+
+export interface CortexOverlayResult {
+	/** Isolated HOME for the cortex child (spawn env HOME). */
+	home: string;
+	/** Isolated snowflake home (spawn env SNOWFLAKE_HOME) = `<home>/.snowflake`. */
+	snowflakeHome: string;
+	/** The scope dir owning both (for diagnostics/teardown). */
+	scopeDir: string;
+}
+
+/** Deterministic per-(host process, session key) overlay dir name. */
+export function cortexOverlayScopeId(scopeKey: string, pid: number = process.pid): string {
+	const digest = createHash("sha256").update(scopeKey).digest("hex").slice(0, 12);
+	return `${pid}-${digest}`;
+}
+
+/** Overlay-authored `$SNOWFLAKE_HOME/cortex/settings.json` — D4's one door. */
+export function cortexOverlaySettingsJson(): string {
+	return `${JSON.stringify({ autoUpdate: false }, null, "\t")}\n`;
+}
+
+/**
+ * Project the (envelope-enriched) explicit server list into cortex's
+ * `$SNOWFLAKE_HOME/cortex/mcp.json` shape (D9). Only stdio entries are measured
+ * through this door — an http/sse entry fails loud BEFORE spawn rather than
+ * being silently dropped. The `entwurf-bridge` entry alone carries
+ * `HOME=<realHome>` (D10); a bridge-declared HOME env is overridden, not merged.
+ */
+export function projectCortexMcpJson(servers: readonly AcpMcpServer[], realHome: string): string {
+	const out: Record<string, { type: "stdio"; command: string; args: string[]; env: Record<string, string> }> = {};
+	for (const server of servers) {
+		if ("type" in server && (server.type === "http" || server.type === "sse")) {
+			throw new Error(
+				`entwurf: cortex mcp.json projection cannot represent ${server.type} server ` +
+					`${JSON.stringify(server.name)} — only stdio entries are measured through ` +
+					`$SNOWFLAKE_HOME/cortex/mcp.json (CP0 D9). Remove it from entwurfProvider.mcpServers ` +
+					`for cortex models or front it with a stdio bridge.`,
+			);
+		}
+		const stdio = server as { name: string; command: string; args: string[]; env: { name: string; value: string }[] };
+		const env: Record<string, string> = {};
+		for (const kv of stdio.env) env[kv.name] = kv.value;
+		if (stdio.name === CORTEX_DUAL_HOME_BRIDGE_SERVER) env.HOME = realHome;
+		out[stdio.name] = { type: "stdio", command: stdio.command, args: [...stdio.args], env };
+	}
+	return `${JSON.stringify({ mcpServers: out }, null, "\t")}\n`;
+}
+
+function cortexPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM = alive but not ours; anything else (ESRCH) = gone.
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/**
+ * Opportunistic GC of overlay scope dirs whose HOST pid is gone (process
+ * resources only — the overlay holds no records/transcripts worth preserving;
+ * conversations state is contained BY DESIGN, Hard Rule 8 does not apply to it).
+ * Entries not matching the scope-id grammar are left alone.
+ */
+export function sweepDeadCortexOverlays(
+	overlaysRoot: string,
+	isPidAlive: (pid: number) => boolean = cortexPidAlive,
+): void {
+	let entries: string[];
+	try {
+		entries = readdirSync(overlaysRoot);
+	} catch {
+		return; // root absent — nothing to sweep
+	}
+	for (const entry of entries) {
+		const match = /^(\d+)-[0-9a-f]{12}$/.exec(entry);
+		if (!match) continue;
+		const pid = Number(match[1]);
+		if (pid === process.pid) continue;
+		if (isPidAlive(pid)) continue;
+		try {
+			rmSync(join(overlaysRoot, entry), { recursive: true, force: true });
+		} catch {
+			// Best-effort GC; a stuck dir is retried on the next spawn.
+		}
+	}
+}
+
+/** Symlink `realPath` at `overlayPath` when the operator actually has it.
+ *  The scope dir is freshly rebuilt by the caller, so no stale-link repair. */
+function cortexLinkIfExists(realPath: string, overlayPath: string): void {
+	if (!existsSync(realPath)) return;
+	try {
+		symlinkSync(realPath, overlayPath);
+	} catch (error) {
+		console.error(
+			`[entwurf:cortex-overlay] symlink failed for ${overlayPath}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+/**
+ * Materialize the session-scoped cortex dual-HOME overlay: tear down the scope
+ * dir and exact-rewrite it (auth symlinks + authored settings.json/mcp.json).
+ * Returns the isolated HOME/SNOWFLAKE_HOME the spawn env must carry.
+ */
+export function ensureCortexDualHomeOverlay(params: CortexOverlayParams): CortexOverlayResult {
+	if (!params.realHome || !params.realHome.startsWith("/")) {
+		throw new Error(
+			`entwurf: cortex dual-HOME overlay requires an absolute realHome captured by the parent (got ${JSON.stringify(params.realHome)})`,
+		);
+	}
+	const overlaysRoot = params.overlaysRoot ?? CORTEX_OVERLAYS_ROOT;
+	const realSnowflake = params.realSnowflakeHome ?? join(params.realHome, ".snowflake");
+	sweepDeadCortexOverlays(overlaysRoot, params.isPidAlive ?? cortexPidAlive);
+
+	const scopeDir = join(overlaysRoot, cortexOverlayScopeId(params.scopeKey));
+	// Exact rewrite (never merge): the prior child for this scope key is already
+	// torn down (backend.ts closes it before a "new" decision spawns), so
+	// everything it wrote — conversations, logs, $HOME dotfiles — is discarded
+	// here. rmSync does not follow symlinks, so the real auth files are untouched.
+	rmSync(scopeDir, { recursive: true, force: true });
+
+	const home = join(scopeDir, "home");
+	const snowflakeHome = join(home, ".snowflake");
+	const cortexDir = join(snowflakeHome, "cortex");
+	mkdirSync(join(cortexDir, "cache"), { recursive: true });
+
+	// D5/F — measured-minimum auth passthrough (symlink-through only).
+	cortexLinkIfExists(join(realSnowflake, "connections.toml"), join(snowflakeHome, "connections.toml"));
+	cortexLinkIfExists(join(realSnowflake, "config.toml"), join(snowflakeHome, "config.toml"));
+	cortexLinkIfExists(
+		join(realSnowflake, "cortex", "cache", "credential_cache"),
+		join(cortexDir, "cache", "credential_cache"),
+	);
+
+	// D4 — runtime self-replacement off; D9 — explicit-server projection.
+	writeFileSync(join(cortexDir, "settings.json"), cortexOverlaySettingsJson(), "utf8");
+	writeFileSync(join(cortexDir, "mcp.json"), projectCortexMcpJson(params.mcpServers, params.realHome), "utf8");
+
+	return { home, snowflakeHome, scopeDir };
+}

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

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

package/prompts/engraving.md

@@ -1,11 +1,15 @@
 <!-- ═══════════════════════════════════════════════════════════════════════
      SAMPLE — operator engraving carrier (entwurf)
 
-     What this is: the markdown body below this comment is loaded VERBATIM
-     into the backend's identity slot (Claude `_meta.systemPrompt`). It is
-     the one place an operator stamps a short identity onto every entwurf
-     ACP turn — replacing Claude's `claude_code` preset (which also strips
-     the preset's auto-memory advertisement, the memory-containment lever).
+     What this is: the engraving file is loaded VERBATIM into the backend's
+     identity slot (Claude `_meta.systemPrompt`). It is the one place an
+     operator stamps a short identity onto every entwurf ACP turn —
+     replacing Claude's `claude_code` preset (which also strips the preset's
+     auto-memory advertisement, the memory-containment lever).
+
+     VERBATIM means the WHOLE file, this comment included — the loader does
+     not strip markdown comments. Copy this sample and delete everything you
+     do not want on the wire; do not point the runtime at it as-is.
 
      Where it loads from:
        • Runtime default = pi-extensions/lib/acp/prompts/engraving.md
@@ -22,6 +26,10 @@
          tool catalogs here — a large Claude carrier can route OAuth
          sessions to metered "extra usage" billing.
        • An empty or missing file = opt-out (no engraving). That is fine.
+       • Do NOT open the file with a blank line to separate yourself from
+         Claude's fixed SDK sentence. Your leading/trailing whitespace is
+         trimmed (it would otherwise drift the reuse signature) and the
+         loader opens the carrier with that blank line itself.
      ═══════════════════════════════════════════════════════════════════════ -->
 
 # Engraving Here