@junghanacs/entwurf 0.13.0 → 0.13.1

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

@@ -35,6 +35,16 @@
 // 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";
@@ -43,6 +53,16 @@ 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";
+
 export interface EngravingParams {
 	/** Always "claude" in practice — a system-prompt-carrier-less backend (cortex)
 	 *  returns null from `loadCarrier` WITHOUT calling this loader, so claudeAdapter is
@@ -82,6 +102,22 @@ function interpolate(template: string, params: EngravingParams): string {
 	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: string, params: EngravingParams): string {
+	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
@@ -94,6 +130,12 @@ function interpolate(template: string, params: EngravingParams): string {
  * 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: EngravingParams): string | null {
 	const filePath = resolveEngravingPath();
@@ -110,7 +152,7 @@ export function loadEngraving(params: EngravingParams): string | null {
 		}
 		return null;
 	}
-	const rendered = interpolate(source, params).trim();
+	const rendered = renderCarrier(source, params);
 	if (rendered.length === 0) {
 		if (isShippedDefault) {
 			throw new Error(

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

@@ -39,7 +39,6 @@ export interface AcpStreamIdentity {
 type ObservedToolState = {
 	title: string;
 	status?: string;
-	notifiedRunning?: boolean;
 };
 
 export type AcpPiStreamState = {
@@ -81,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 {
@@ -221,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)}` : "";
@@ -250,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

@@ -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.
 
@@ -87,9 +87,9 @@ function claudeContextWindow(model: { id: string; contextWindow: number }): numb
 // ── 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/pi-extensions/lib/acp/overlay.ts

@@ -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.
 //
@@ -230,11 +230,11 @@ 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 §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/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