@junghanacs/entwurf 0.13.0 → 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`.
@@ -54,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;
@@ -121,7 +122,7 @@ export const claudeAdapter = {
  *  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:
+// 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);
@@ -131,7 +132,7 @@ const SUPPORTED_CORTEX_IDS = new Set(SUPPORTED_CORTEX_MODEL_IDS);
 export const CORTEX_CONNECTION_ENV = "ENTWURF_ACP_CORTEX_CONNECTION";
 export const cortexAdapter = {
     backend: "cortex",
-    // Cortex owns the reserved `cortex-` prefix (§9-1). routeModel strips it to the
+    // 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))
@@ -213,7 +214,7 @@ export const cortexAdapter = {
         });
         return { envOverrides: { HOME: overlay.home, SNOWFLAKE_HOME: overlay.snowflakeHome } };
     },
-    // System-prompt-carrier-less (§9-4/§11-8): Cortex ACP exposes no
+    // 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
@@ -242,7 +243,7 @@ export const cortexAdapter = {
         }
         await setConfig.call(connection, { sessionId: acpSessionId, configId: "model", value: nativeModelId });
     },
-    // A connection change must invalidate a reused session (§4/§7). Flat,
+    // 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) {
@@ -254,7 +255,7 @@ 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).
  *
@@ -278,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

@@ -23,7 +23,7 @@
 // the backend-invariant exclude-tools preflight and folds every one of them into
 // `bridgeConfigSignature` (so changing one still invalidates a reused cortex
 // session). Backend-OWNED settings never land here: they ride the opaque
-// `adapterSettings` seam (§10 B), which is what keeps a backend-named key like
+// `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):

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

@@ -9,8 +9,8 @@
 // Two curated sets live here, one per adapter on the rail
 // (backend-adapter.ts): the unprefixed Claude ids (the reference backend) and
 // the `cortex-` prefixed Snowflake Cortex Code ids (the second backend, landed
-// 0.13.0 — docs/acp-backend-rail.md §6/§11-8). Codex is already a native garden
-// citizen and Gemini/major tools use native, so neither is an ACP backend here.
+// 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
@@ -77,9 +77,9 @@ function claudeContextWindow(model) {
 // ── Cortex (Snowflake Cortex Code) curated surface ──────────────────────────
 //
 // entwurf's ACP rail is backend-extensible: Cortex is the first NON-claude
-// backend to land through it (docs/acp-backend-rail.md §6). pi-ai carries no
+// 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 (§9-1): the prefix is the SINGLE routing
+// 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

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

@@ -15,7 +15,7 @@
 // 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
+// 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.
 //
@@ -201,11 +201,11 @@ 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).
+// (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 — §11-8 D-numbers):
+// (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

package/mcp/entwurf-bridge/src/index.ts

@@ -344,54 +344,27 @@ function abbreviateHomeMcp(cwd: string): string {
 // sender replyability).
 server.tool(
 	"entwurf_v2",
-	"CANONICAL DELIVERY SURFACE for garden ids. When you have a garden id and want to reach " +
-		"whoever it names — message / reply / hand-off — use THIS verb. A garden id alone does " +
-		"not tell you which rail that citizen answers on — a live socket citizen, a dormant one, a " +
-		"mailbox-backed self-fetch session, or a native-push session — and entwurf_v2 is the one " +
-		'surface that reads that for you and routes correctly (so "when unsure which transport, use ' +
-		'entwurf_v2"). You give the target ' +
-		"garden id + your intent; the decider picks the transport from the target's liveness " +
-		"(live socket citizen → control-socket send; dormant socket citizen → spawn-bg resume; active " +
-		"deliverable self-fetch citizen → meta-bridge mailbox; probe-alive native-push citizen → direct " +
-		"injection into its live conversation) under the v2 lock policy, and reports ONE outcome " +
-		"(delivered / rejected / lock-retained / delivered-but-lock-dirty). LOCK POLICY (do not " +
-		"over-generalize it): the per-target lock is taken for a control-socket-DOMAIN dispatch, which is " +
-		"both the live send AND the dormant cell's spawn-bg resume — spawn-bg is a separate relaunch " +
-		"transport yet it still runs under that domain's lock. The mailbox and native-push rails are " +
-		"lock-free: the mailbox is guarded instead by active-receiver deliverability, and native-push by " +
-		"its adapter probe. The decider — not the " +
-		"caller — chooses the transport. Note: entwurf_v2 dispatches to EXISTING targets; " +
-		"brand-new sibling creation is deferred to a later v2 lane. " +
-		"CHOOSING INTENT (read this — picking wrong is rejected, never auto-fixed): to message / " +
-		"reply / hand off a peer that entwurf_peers shows as liveness=alive (a live socket citizen, " +
-		"currently backend pi) use intent: fire-and-forget — it routes to the live control-socket; set " +
-		"wants_reply:true if you need an answer (wants_reply is NOT owned-outcome). Replies to a citizen " +
-		"with NO socket liveness (liveness=unsupported) are ALSO fire-and-forget, and the decider picks " +
-		"that citizen's own rail: a self-fetch backend (e.g. Claude Code) gets the meta-bridge mailbox, " +
-		"while a native-push backend (e.g. Antigravity) gets direct injection into its live conversation " +
-		"and has NO mailbox at all — do not assume mailbox semantics for every unsupported citizen. A " +
-		"native-push target IS measured by its own adapter probe, and that probe is THREE-valued, so " +
-		"the send is never silently queued: alive → injected; dead → rejected as " +
-		"native-push-target-dead; indeterminate → rejected as native-push-probe-indeterminate. " +
-		"Those two rejects stay distinct because 'we could not establish it' is not 'it is gone' — " +
-		"collapsing them reports a guess as a fact. THERE IS A " +
-		"THIRD RESULT, so do not read liveness=unsupported as 'reachable by some rail': the mailbox path " +
-		"delivers only to a DELIVERABLE citizen (a self-fetch backend whose receiver is live and armed), " +
-		"so a terminated Claude Code session — and any record whose backend has no adapter on this lane, " +
-		"e.g. codex — is rejected as mailbox-undeliverable rather than queued into an inbox nobody drains. " +
-		"unsupported means only 'this backend has no control-socket probe'. " +
-		"owned-outcome is ONLY for waking a DORMANT socket-domain citizen (spawn-bg resume, currently " +
-		"backend pi); on a live target it is rejected as owned-live-no-autosend. Neither self-fetch nor " +
-		"native-push has resume authority, but they reject under DIFFERENT reasons — self-fetch as " +
-		"backend-liveness-unsupported, native-push as native-push-no-resume-authority. " +
-		"It is NEVER auto-converted — so pick the right intent up front. " +
-		"mode applies to a CONTROL-SOCKET send only — it is the injection style for a live pi turn, and " +
-		"the mailbox, native-push, and spawn-bg plans carry no mode at all, so setting it for those " +
-		"targets changes nothing (a native-push send IS live and still ignores it). wants_reply rides " +
-		"every rail. Use entwurf_peers to discover targets. " +
-		"Payload guidance: message hard cap 16000 chars. For larger reviews/logs, write an " +
-		"artifact and dispatch its path plus a short digest; avoid multi-part sends because " +
-		"mailbox doorbells may coalesce.",
+	"CANONICAL DELIVERY SURFACE for garden ids: message, reply, or hand off to whoever an id names. The id " +
+		"alone does not say which rail that citizen answers on. Give target + intent; the decider picks transport " +
+		"from liveness (live socket citizen → control-socket send; dormant socket citizen → spawn-bg resume; " +
+		"deliverable self-fetch citizen → meta-bridge mailbox; probe-alive native-push citizen → direct injection " +
+		"into its conversation) and reports ONE outcome (delivered / rejected / lock-retained / " +
+		"delivered-but-lock-dirty). EXISTING targets only; discover with entwurf_peers. INTENT — picking wrong is " +
+		"rejected, never auto-converted. A peer entwurf_peers shows as liveness=alive → fire-and-forget. A " +
+		"citizen with NO socket liveness (liveness=unsupported) is ALSO fire-and-forget — unsupported means only " +
+		'"no control-socket probe" — and the decider picks its own rail: a self-fetch backend (e.g. Claude Code) ' +
+		"gets the mailbox, a native-push backend (e.g. Antigravity) gets direct injection and has NO mailbox at " +
+		"all. THERE IS A THIRD RESULT: the mailbox delivers only to a DELIVERABLE citizen, so a terminated " +
+		"session, or a backend with no adapter here (e.g. codex), is mailbox-undeliverable, not queued for an " +
+		"inbox nobody drains. The native-push probe is 3-valued: alive → injected; dead → " +
+		"native-push-target-dead; indeterminate → native-push-probe-indeterminate (unestablished ≠ gone). " +
+		"owned-outcome wakes a DORMANT socket-domain citizen by spawn-bg resume ONLY — live target → " +
+		"owned-live-no-autosend, self-fetch → backend-liveness-unsupported, native-push → " +
+		"native-push-no-resume-authority. LOCK: taken for a control-socket-DOMAIN dispatch — the live send AND " +
+		"the dormant cell's spawn-bg resume, a separate transport that still runs under that domain's lock. The " +
+		"mailbox and native-push rails are lock-free — deliverability and the adapter probe guard them. mode " +
+		"applies to a CONTROL-SOCKET send only; other plans carry no mode. wants_reply rides every rail. message " +
+		"caps at 16000 chars; send an artifact path + digest for more.",
 	{
 		target: z.string().min(1).describe("Target garden id (use entwurf_peers to discover)"),
 		intent: z

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.13.0",
+	"version": "0.13.1",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for Claude Code, Codex, Antigravity, and pi harnesses.",
 	"license": "MIT",
 	"author": {
@@ -42,6 +42,9 @@
 		"demo/demo.sh",
 		"demo/demo-baseline.sh",
 		"docs/setup-clean-host.md",
+		"docs/external-mcp-host.md",
+		"docs/fresh-cut-policy.md",
+		"docs/acp-backend-rail.md",
 		"docs/assets/entwurf-hero.jpg",
 		"docs/assets/entwurf-demo.gif",
 		"docs/assets/entwurf-doomemacs.gif",
@@ -71,23 +74,23 @@
 		"claudeCodeFloor": ">=2.1.217"
 	},
 	"dependencies": {
-		"@agentclientprotocol/claude-agent-acp": "0.62.0",
+		"@agentclientprotocol/claude-agent-acp": "0.64.0",
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@anthropic-ai/sdk": "0.100.1",
 		"@modelcontextprotocol/sdk": "^1.12.1",
 		"zod": "^3.25.0 || ^4.0.0"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": ">=0.82.1 <0.83",
-		"@earendil-works/pi-coding-agent": ">=0.82.1 <0.83",
-		"@earendil-works/pi-tui": ">=0.82.1 <0.83",
+		"@earendil-works/pi-ai": ">=0.83.0 <0.84",
+		"@earendil-works/pi-coding-agent": ">=0.83.0 <0.84",
+		"@earendil-works/pi-tui": ">=0.83.0 <0.84",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.13",
-		"@earendil-works/pi-ai": "0.82.1",
-		"@earendil-works/pi-coding-agent": "0.82.1",
-		"@earendil-works/pi-tui": "0.82.1",
+		"@earendil-works/pi-ai": "0.83.0",
+		"@earendil-works/pi-coding-agent": "0.83.0",
+		"@earendil-works/pi-tui": "0.83.0",
 		"@types/node": "^24.3.0",
 		"husky": "^9.1.7",
 		"typescript": "^6.0.2"
@@ -132,7 +135,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-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./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-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./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-release-gate-outcomes && ./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-extensions/entwurf-control.ts

@@ -1322,55 +1322,26 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 	registerTool({
 		name: "entwurf_v2",
 		label: "Dispatch (v2)",
-		description: `CANONICAL delivery surface for a garden id. When you have a garden id and want to
-reach whoever it names — message / reply / hand-off — use THIS verb. A garden id alone does not
-reveal which rail that citizen answers on — a live socket session, a dormant one, a mailbox-backed
-self-fetch session, or a native-push session —
-and entwurf_v2 is the one surface that reads that and routes correctly (so "when unsure which
-transport, use entwurf_v2"). It dispatches to EXISTING targets; brand-new sibling creation is deferred
-to a later v2 lane. Dispatch to a garden citizen through the unified entwurf_v2 verb: the 5b decider
-picks the transport (live control-socket send / spawn-bg resume / meta-mailbox enqueue / native-push
-direct injection) from the target's liveness + your intent, runs it under the v2 lock policy, and reports
-one outcome (delivered / rejected / lock-retained / delivered-but-lock-dirty).
-
-LOCK POLICY (do not over-generalize it): the per-target lock is taken for a control-socket-DOMAIN
-dispatch, which is BOTH the live send AND the dormant cell's spawn-bg resume — spawn-bg is a separate
-relaunch transport yet it still runs under that domain's lock. The mailbox and native-push rails are
-lock-free: the mailbox is guarded instead by active-receiver deliverability, and native-push by its
-adapter probe.
-
-- target: the garden id of the citizen to reach (required).
-- intent: fire-and-forget (a send with no owned result) or owned-outcome (you own the result).
-- message: the message/prompt to dispatch (required).
-- mode: steer or follow_up for a CONTROL-SOCKET send (optional). The mailbox, native-push, and
-  spawn-bg plans carry no mode, so it has no effect on those rails — a native-push send IS live and
-  still ignores it.
-- wants_reply: reply hint; it rides every rail (optional, default false).
-
-CHOOSING INTENT (picking wrong is rejected, never auto-fixed): to message / reply / hand off a peer
-that entwurf_peers shows as liveness=alive (a live socket citizen, currently backend pi), use intent:
-fire-and-forget — it routes to the live control-socket; set wants_reply:true if you need an answer
-(wants_reply is NOT owned-outcome). Replies to a citizen with NO socket liveness
-(liveness=unsupported) are ALSO fire-and-forget, and the decider picks that citizen's own rail: a
-self-fetch backend (e.g. Claude Code) gets the meta-bridge mailbox, while a native-push backend
-(e.g. Antigravity) gets direct injection into its live conversation and has NO mailbox at all — do
-not assume mailbox semantics for every unsupported citizen. A native-push target IS measured by its
-own adapter probe, and that probe is THREE-valued, so the send is never silently queued: alive →
-injected; dead → rejected as native-push-target-dead; indeterminate → rejected as
-native-push-probe-indeterminate. Those last two stay separate on purpose — "we could not establish
-it" is not "it is gone". THERE IS A THIRD RESULT, so do not read
-liveness=unsupported as "reachable by some rail": the mailbox path delivers only to a DELIVERABLE
-citizen (a self-fetch backend whose receiver is live and armed), so a terminated Claude Code session —
-and any record whose backend has no adapter on this lane, e.g. codex — is rejected as
-mailbox-undeliverable rather than queued into an inbox nobody drains. unsupported means only "this
-backend has no control-socket probe".
-owned-outcome is ONLY for waking a DORMANT socket-domain citizen (spawn-bg resume, currently backend
-pi); on a live target it is rejected as owned-live-no-autosend. Neither self-fetch nor native-push
-has resume authority, but they reject under DIFFERENT reasons — self-fetch as
-backend-liveness-unsupported, native-push as native-push-no-resume-authority.
-It is NEVER auto-converted — so pick the right intent up front.
-
-The decider — not this surface — chooses the transport.`,
+		description: `CANONICAL DELIVERY SURFACE for garden ids: message, reply, or hand off to whoever an id names. The id alone
+does not say which rail that citizen answers on. Give target + intent; the decider picks transport from
+liveness (live socket citizen → control-socket send; dormant socket citizen → spawn-bg resume; deliverable
+self-fetch citizen → meta-bridge mailbox; probe-alive native-push citizen → direct injection into its
+conversation) and reports ONE outcome (delivered / rejected / lock-retained / delivered-but-lock-dirty).
+EXISTING targets only; discover with entwurf_peers. INTENT — picking wrong is rejected, never
+auto-converted. A peer entwurf_peers shows as liveness=alive → fire-and-forget. A citizen with NO socket
+liveness (liveness=unsupported) is ALSO fire-and-forget — unsupported means only "no control-socket probe" —
+and the decider picks its own rail: a self-fetch backend (e.g. Claude Code) gets the mailbox, a native-push
+backend (e.g. Antigravity) gets direct injection and has NO mailbox at all. THERE IS A THIRD RESULT: the
+mailbox delivers only to a DELIVERABLE citizen, so a terminated session, or a backend with no adapter here
+(e.g. codex), is mailbox-undeliverable, not queued for an inbox nobody drains. The native-push probe is
+3-valued: alive → injected; dead → native-push-target-dead; indeterminate → native-push-probe-indeterminate
+(unestablished ≠ gone). owned-outcome wakes a DORMANT socket-domain citizen by spawn-bg resume ONLY — live
+target → owned-live-no-autosend, self-fetch → backend-liveness-unsupported, native-push →
+native-push-no-resume-authority. LOCK: taken for a control-socket-DOMAIN dispatch — the live send AND the
+dormant cell's spawn-bg resume, a separate transport that still runs under that domain's lock. The mailbox
+and native-push rails are lock-free — deliverability and the adapter probe guard them. mode applies to a
+CONTROL-SOCKET send only; other plans carry no mode. wants_reply rides every rail. message caps at 16000
+chars; send an artifact path + digest for more.`,
 		parameters: entwurfV2Parameters,
 		async execute(
 			_toolCallId: string,

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

@@ -26,6 +26,17 @@ export interface AcpConnectionLike {
 	newSession(params: unknown): Promise<{ sessionId?: string }>;
 	prompt(params: { sessionId: string; prompt: AcpTextBlock[] }): Promise<{ stopReason?: string }>;
 	setSessionConfigOption?(params: unknown): Promise<unknown>;
+	/**
+	 * ACP `session/cancel` — the PROTOCOL way to end an in-flight prompt turn.
+	 *
+	 * The spec requires the agent to answer the pending `session/prompt` with
+	 * `stopReason: "cancelled"` after this notification, so a user abort ends the
+	 * turn as a protocol event (backend.ts maps cancelled → aborted) instead of a
+	 * signal race. Fire-and-forget by contract: it is a JSON-RPC notification, so
+	 * there is nothing to await and a send failure on an already-closed connection
+	 * must not mask the abort the caller is executing.
+	 */
+	cancel?(params: { sessionId: string }): void;
 	/**
 	 * Closes the underlying SDK connection before child process teardown. With
 	 * the fluent SDK connection this is load-bearing: otherwise a successful
@@ -76,6 +87,17 @@ export function connectAcpClient(stream: Stream, handlers: AcpClientHandlers): A
 		prompt: (params) =>
 			agent.request(AGENT_METHODS.session_prompt, params as never) as Promise<{ stopReason?: string }>,
 		setSessionConfigOption: (params) => agent.request(AGENT_METHODS.session_set_config_option, params as never),
+		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 as never)).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/pi-extensions/lib/acp/augment.ts

@@ -36,10 +36,10 @@ 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
+// Carrier-less backends expose no `_meta.systemPrompt` (docs/acp-backend-rail.md,
+// “Cortex Code audit”). 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)
+// cortex does read `_meta` for an unpromoted caller-session-id seam)
 // 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
@@ -48,6 +48,13 @@ const MAX_AUGMENT_BYTES = 50 * 1024;
 // carrier feeds bridgeConfigSignature.
 const CARRIER_LESS_BACKENDS: ReadonlySet<string> = new Set(["cortex"]);
 
+// The one sentence both rails owe the model: WHAT this block is and what it is
+// NOT. Shared so neither rail's frame can quietly lose it (and so the gate has a
+// single anchor to mutate). Everything after it is rail-specific, because the
+// rails really do differ — see the frame in buildPiContextAugment.
+const PROVENANCE_LEAD =
+	"This block is prepended to the FIRST USER MESSAGE of this session. It is not your system prompt.";
+
 // 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,
@@ -116,6 +123,38 @@ export function buildPiContextAugment(params: PiContextAugmentParams): string {
 		if (engraving) sections.push(engraving);
 	}
 
+	// PROVENANCE FRAME — leads the bridge narrative, and it is not decoration.
+	//
+	// Measured 2026-07-30: asked where its instructions came from, the Claude ACP
+	// model asserted that the two paragraphs below were its system prompt. They
+	// are not — they are text prepended to its FIRST USER MESSAGE. Nothing in the
+	// block said otherwise, and a model has no other way to tell: on the wire a
+	// long first user message and a system prompt read the same. So the block now
+	// states its own provenance, per rail, because the rails genuinely differ
+	// (backend-adapter.ts: claude's buildSessionMeta carries `_meta.systemPrompt`,
+	// cortex's returns undefined so no `_meta` key is sent at all).
+	//
+	// Honest about scope: this makes the boundary STATEABLE, not enforced. It
+	// tells the model what it cannot otherwise observe; it does not stop a model
+	// from guessing anyway.
+	sections.push(
+		CARRIER_LESS_BACKENDS.has(params.backend)
+			? [
+					"# entwurf: where this text comes from",
+					"",
+					PROVENANCE_LEAD,
+					`The ${params.backend} rail carries no system-prompt carrier at all — entwurf sends no \`_meta.systemPrompt\`, so everything entwurf tells you, including any operator engraving above, arrives here as user-message text.`,
+					"If you are asked what your system prompt says, do not quote this block as one.",
+				].join("\n")
+			: [
+					"# entwurf: where this text comes from",
+					"",
+					PROVENANCE_LEAD,
+					`The ${params.backend} rail does have a system-prompt carrier (\`_meta.systemPrompt\`), and entwurf keeps it deliberately tiny: it carries the operator engraving only — never this narrative, never AGENTS.md.`,
+					"So: system prompt = the short engraving; everything below = first-user-message text. If you are asked what your system prompt says, do not quote this block as one.",
+				].join("\n"),
+	);
+
 	// 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.