@junghanacs/entwurf 0.12.0

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

@@ -0,0 +1,177 @@
+// ACP plugin — pi Context → ACP prompt conversion (S2c).
+//
+// S2c is spawn-per-turn: every streamSimple call spawns a fresh ACP session, so
+// the backend has NO memory of prior turns. Sending only the last user message
+// would silently drop multi-turn history — that is context loss, not a thin
+// substrate. So this flattens the whole pi conversation into ONE text transcript
+// and sends it as a single ACP user prompt block.
+//
+// S2c/S2d boundary (GPT S2c Q2): this is CONVERSATION TRANSCRIPT PASSTHROUGH, not
+// rich-carrier identity injection. Deliberately EXCLUDED here (all S2d):
+//   - `context.systemPrompt` — never read into the prompt or `_meta.systemPrompt`
+//     (the billing carrier stays absent — NEXT §S2-scout 핀1);
+//   - `~/AGENTS.md` / cwd AGENTS / bridge identity narrative;
+//   - first-user-message augment + project-context de-dup;
+//   - `context.tools` — the ACP child tool surface is the S2b
+//     `_meta.claudeCode.options` SSOT, never re-sent here.
+// Structured tool replay is also excluded: tool calls/results render as plain
+// transcript text, never as ACP tool invocations (the child runs its own tools).
+
+import type { AssistantMessage, Context, Message, ToolResultMessage, UserMessage } from "@earendil-works/pi-ai";
+
+// MUST equal event-mapper.ts `LIFECYCLE_NOTICE_SIGNATURE` (the SSOT/producer).
+// It is mirrored, not imported: the strip-types deterministic gates load these
+// lib files by their `.ts` source and cannot resolve a cross-sibling VALUE
+// import (`./event-mapper.js`) — the lib modules share TYPES only. The mirror is
+// kept honest behaviorally by check-acp-session-reuse (a drift would leave the
+// `[acp: …]` notices in the captured ACP prompt and fail the gate).
+const LIFECYCLE_NOTICE_SIGNATURE = "entwurf:lifecycle-notice-v1";
+
+/** An ACP text content block. */
+export interface AcpTextBlock {
+	type: "text";
+	text: string;
+}
+
+function textFromUserOrToolContent(content: UserMessage["content"] | ToolResultMessage["content"]): string {
+	if (typeof content === "string") return content;
+	// Render text verbatim; images are NOT dropped silently — they leave a text
+	// marker so the transcript honestly records an attachment the text-only S2c
+	// transcript cannot carry (real ACP image passthrough is a later lane).
+	return content
+		.map((c) => {
+			if (c.type === "text") return c.text;
+			if (c.type === "image") return `[image omitted: ${c.mimeType ?? "unknown"}]`;
+			return "";
+		})
+		.filter((s) => s !== "")
+		.join("\n");
+}
+
+function textFromAssistantContent(content: AssistantMessage["content"]): string {
+	// Assistant text only — thinking is omitted and tool calls are not replayed
+	// (the ACP child executes its own tools; replaying structured calls would be
+	// a lie). Tool RESULTS still appear via their own toolResult message below.
+	return (
+		content
+			.filter((c): c is { type: "text"; text: string; textSignature?: string } => c.type === "text")
+			// Drop S2f lifecycle progress notices (`[acp: …]`): display-only, stamped
+			// with LIFECYCLE_NOTICE_SIGNATURE. Replaying them into a `new` rebuild's
+			// full transcript would inject bridge-internal chatter into the ACP prompt.
+			.filter((c) => c.textSignature !== LIFECYCLE_NOTICE_SIGNATURE)
+			.map((c) => c.text)
+			.join("")
+	);
+}
+
+/** Render one pi message as a transcript line, or undefined to skip it. */
+function renderMessage(message: Message): string | undefined {
+	switch (message.role) {
+		case "user": {
+			const text = textFromUserOrToolContent(message.content).trim();
+			return text ? `User: ${text}` : undefined;
+		}
+		case "assistant": {
+			const text = textFromAssistantContent(message.content).trim();
+			return text ? `Assistant: ${text}` : undefined;
+		}
+		case "toolResult": {
+			const text = textFromUserOrToolContent(message.content).trim();
+			const tag = message.isError ? "Tool error" : "Tool result";
+			return text ? `${tag} (${message.toolName}): ${text}` : undefined;
+		}
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Flatten a pi Context into a single transcript string. Excludes
+ * `context.systemPrompt` and `context.tools` by construction.
+ */
+export function contextTranscript(context: Context): string {
+	const lines: string[] = [];
+	for (const message of context.messages) {
+		const line = renderMessage(message);
+		if (line) lines.push(line);
+	}
+	return lines.join("\n\n");
+}
+
+/**
+ * Convert a pi Context into the ACP `prompt` array (a single text block holding
+ * the flattened transcript). Empty history yields an empty array — the caller
+ * decides whether that is a hard error.
+ */
+export function contextToAcpPrompt(context: Context): AcpTextBlock[] {
+	const transcript = contextTranscript(context);
+	if (!transcript) return [];
+	return [{ type: "text", text: transcript }];
+}
+
+/**
+ * ACP session bootstrap path — the input that decides the prompt SCOPE (NEXT
+ * §S2-scout 핀4). S2c was spawn-per-turn (always a fresh session), so this stays
+ * `"new"` until S2d wires the session store that can actually produce the reuse
+ * paths.
+ */
+export type AcpBootstrapPath = "new" | "reuse" | "resume" | "load";
+
+/**
+ * The latest user turn only — the first user message AFTER the last assistant
+ * message. Ported from 0.11.0 `index.ts:732 extractPromptBlocks`: taking the
+ * FIRST user of the trailing group (not `reverse().find()`) skips the
+ * SessionStart hook user-message (`device=…, time_kst=…`) that pi appends AFTER
+ * the real prompt. Images leave a text marker (S2c decision — real ACP image
+ * passthrough is a later lane), never raw data.
+ *
+ * This is the prompt scope for a session that ALREADY holds the prior turns
+ * (reuse/resume/load): re-sending the whole transcript there would duplicate
+ * history the backend already remembers.
+ */
+export function latestUserDelta(context: Context): AcpTextBlock[] {
+	let lastAssistantIdx = -1;
+	for (let i = context.messages.length - 1; i >= 0; i--) {
+		if (context.messages[i].role === "assistant") {
+			lastAssistantIdx = i;
+			break;
+		}
+	}
+	const latestUser = context.messages.slice(lastAssistantIdx + 1).find((m): m is UserMessage => m.role === "user");
+	if (!latestUser) return [];
+	// The delta IS the user's actual prompt — preserve its body verbatim (0.11.0
+	// extractPromptBlocks sent it near-raw). Only the EMPTINESS test trims, so a
+	// whitespace-only turn yields no block.
+	const raw = textFromUserOrToolContent(latestUser.content);
+	return raw.trim() ? [{ type: "text", text: raw }] : [];
+}
+
+/**
+ * Build the ACP prompt array for a turn, scoping it by bootstrapPath (핀4):
+ *   - `"new"` (incompatible rebuild included): a fresh ACP session holds NO
+ *     history, so the whole transcript is the only history carrier (same as the
+ *     S2c spawn-per-turn path). Delta-only here would lose history on
+ *     rebuild/compaction/edited-history.
+ *   - `"reuse" | "resume" | "load"`: the stateful ACP session already holds the
+ *     prior turns, so send only the latest user delta — the whole transcript
+ *     would duplicate remembered history.
+ *
+ * The delta-only SAFETY for resume/load is owned by the caller's
+ * `contextMessageSignatures` prefix-compat gate (mismatch → fall back to
+ * `"new"` + full transcript); this pure function only splits the scope.
+ */
+export function buildAcpPrompt(context: Context, bootstrapPath: AcpBootstrapPath): AcpTextBlock[] {
+	switch (bootstrapPath) {
+		case "new":
+			return contextToAcpPrompt(context);
+		case "reuse":
+		case "resume":
+		case "load":
+			return latestUserDelta(context);
+		default:
+			// Fail-loud (핀4): a bad/unknown bootstrapPath must CRASH, never fall
+			// through to delta-only. A silent delta on a path that should carry the
+			// full transcript loses history — fail-OPEN toward the dangerous side.
+			throw new Error(`buildAcpPrompt: unknown bootstrapPath ${JSON.stringify(bootstrapPath)}`);
+	}
+}

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

@@ -0,0 +1,123 @@
+// ACP plugin — billing carrier (engraving) loader (S2d-1c).
+//
+// The engraving is the OPERATOR surface for the Claude `_meta.systemPrompt`
+// carrier — short, personal additions an operator wants attached to every ACP
+// session's system prompt. It is NOT the bridge-identity / AGENTS / pi-base
+// narrative: that rich context rides the first-user-message augment (augment.ts)
+// because the system-prompt carrier MUST stay tiny.
+//
+// Why a SMALL but NON-EMPTY default (the v1 memory-containment lever, restored):
+// shipping a non-empty string here makes claude-agent-acp REPLACE its
+// `claude_code` preset with this string (acp-agent.js: string-form
+// `_meta.systemPrompt` → full preset replacement). That replacement strips the
+// preset's auto-memory section, so the ACP model never learns it has a per-session
+// memory store — the containment the operator baseline depends on. An EMPTY
+// carrier keeps the preset and re-leaks auto-memory (the model writes memory/*.md
+// via Write): that regression is exactly what a non-empty default fixes.
+//
+// Billing axis is SIZE, not SHAPE (NEXT §S2-scout 핀1, oracle A): Anthropic
+// subscription billing (Claude Code OAuth, 정액제) reclassifies a call as metered
+// "extra usage" — HTTP 400 for users with no metered balance — when the carrier
+// materially GROWS past the SDK-default size (e.g. by injecting AGENTS.md or the
+// pi base prompt). A tiny placeholder string is shape-deviant yet v1-production-
+// safe, so the rule is keep the carrier SHORT, never "absent". Rich context still
+// rides the first-user-message augment (augment.ts), never this carrier.
+//
+// Stability contract (NEXT oracle C / 핀1): the rendered output MUST be a pure
+// function of (template content on disk, backend, mcpServerNames). No clock /
+// random / env-time. `bridgeConfigSignature` folds this string into its
+// `appendSystemPrompt` slot — if the rendered carrier drifted turn-to-turn, the
+// signature would drift and entwurf would rebuild the ACP session every
+// turn. The default-path source is cached once for exactly this reason, so a
+// resident's carrier never drifts mid-session. The env-override path instead
+// re-reads on EVERY call: editing that file mid-session INTENTIONALLY drifts the
+// rendered carrier → bridgeConfigSignature changes → the live session is judged
+// 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).
+
+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");
+
+export interface EngravingParams {
+	/** Claude-only this cut; kept as a field so the `{{backend}}` token interpolates. */
+	backend: string;
+	/** MCP server names exposed to the session. SORTED before render for determinism. */
+	mcpServerNames: readonly string[];
+}
+
+type CachedSource = { filePath: string; content: string };
+let cached: CachedSource | null = null;
+
+/** Point the loader at an alternate engraving file (A/B); bypasses the cache. */
+function resolveEngravingPath(): string {
+	const envPath = process.env.ENTWURF_ACP_ENGRAVING_PATH?.trim();
+	return envPath ? resolve(envPath) : DEFAULT_ENGRAVING_PATH;
+}
+
+function loadSource(filePath: string): string {
+	// Env-override path → always re-read (A/B experimentation). Default path →
+	// cache once so a mid-session operator edit cannot drift the carrier (and thus
+	// bridgeConfigSignature) between turns of a resident.
+	if (filePath !== DEFAULT_ENGRAVING_PATH) {
+		return readFileSync(filePath, "utf8");
+	}
+	if (!cached || cached.filePath !== filePath) {
+		cached = { filePath, content: readFileSync(filePath, "utf8") };
+	}
+	return cached.content;
+}
+
+function interpolate(template: string, params: EngravingParams): string {
+	// Sort so a caller-side ordering difference can never drift the rendered text
+	// (and therefore the config signature) — GPT c32a6c8 determinism guard.
+	const names = [...params.mcpServerNames].sort();
+	const mcpList = names.length > 0 ? names.join(", ") : "(none registered)";
+	return template.replace(/\{\{backend\}\}/g, params.backend).replace(/\{\{mcp_servers\}\}/g, mcpList);
+}
+
+/**
+ * The rendered engraving carrier, or null when an ENV-OVERRIDE engraving file
+ * (`ENTWURF_ACP_ENGRAVING_PATH`) is empty, whitespace-only, missing, or
+ * unreadable — that null is the operator opt-out. The SHIPPED default, by
+ * contrast, IS the auto-memory containment lever (its non-empty carrier replaces
+ * the claude_code preset, stripping the auto-memory advertisement) and MUST be
+ * present + non-empty: if the shipped default is missing/unpackaged/empty this
+ * THROWS (fail-loud, Detour C) rather than silently shipping with the carrier
+ * strip off. To opt the carrier out, point the env override at an empty file.
+ * 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.
+ */
+export function loadEngraving(params: EngravingParams): string | null {
+	const filePath = resolveEngravingPath();
+	const isShippedDefault = filePath === DEFAULT_ENGRAVING_PATH;
+	let source: string;
+	try {
+		source = loadSource(filePath);
+	} catch (err) {
+		if (isShippedDefault) {
+			throw new Error(
+				`entwurf: shipped engraving carrier unreadable at ${filePath} — it is the auto-memory ` +
+					`containment lever; refusing to proceed with containment silently degraded. (${(err as Error).message})`,
+			);
+		}
+		return null;
+	}
+	const rendered = interpolate(source, params).trim();
+	if (rendered.length === 0) {
+		if (isShippedDefault) {
+			throw new Error(
+				`entwurf: shipped engraving carrier at ${filePath} is empty — it is the auto-memory ` +
+					`containment lever; refusing to proceed with the carrier strip silently off. ` +
+					`(opt out via an empty ENTWURF_ACP_ENGRAVING_PATH file instead)`,
+			);
+		}
+		return null;
+	}
+	return rendered;
+}

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

@@ -0,0 +1,339 @@
+// ACP plugin — ACP session_notification → pi event stream mapper (S2c).
+//
+// Translates the ACP backend's streaming notifications into pi's
+// 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
+// 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.
+//
+// CRITICAL boundary (GPT S2c Q3): an ACP `tool_call` / `tool_call_update` is
+// rendered as an INFORMATIONAL TEXT NOTICE, never a structured pi `toolcall_*`
+// event. The ACP child already executes its own tools (Claude Code side); a
+// structured pi ToolCall would signal pi's agent loop to RE-EXECUTE it. Tools
+// surface honestly in the transcript as `[tool:*]` notices instead. Thinking
+// (`agent_thought_chunk`) IS structured — pi never executes thinking.
+
+import type { AssistantMessage, AssistantMessageEventStream } from "@earendil-works/pi-ai";
+
+const NOTICE_TITLE_MAX = 80;
+const NOTICE_SUMMARY_MAX = 160;
+
+/** Identity fields for the running assistant message. */
+export interface AcpStreamIdentity {
+	api: string;
+	provider: string;
+	model: string;
+}
+
+type ObservedToolState = {
+	title: string;
+	status?: string;
+	notifiedRunning?: boolean;
+};
+
+export type AcpPiStreamState = {
+	stream: AssistantMessageEventStream;
+	output: AssistantMessage;
+	openTextIndex?: number;
+	openThinkingIndex?: number;
+	/** When false, tool/permission notices are suppressed (kept terse for smokes). */
+	showToolNotifications?: boolean;
+	observedTools?: Map<string, ObservedToolState>;
+};
+
+/** A zeroed pi Usage block. */
+function zeroUsage(): AssistantMessage["usage"] {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+}
+
+/**
+ * Build a fresh stream state with an empty running AssistantMessage. The caller
+ * (streamSimple) pushes the `start` event, drives notifications through
+ * applyAcpSessionUpdate, then finalize + done.
+ */
+export function createAcpStreamState(
+	stream: AssistantMessageEventStream,
+	identity: AcpStreamIdentity,
+	opts?: { showToolNotifications?: boolean; timestamp?: number },
+): AcpPiStreamState {
+	const output: AssistantMessage = {
+		role: "assistant",
+		content: [],
+		api: identity.api,
+		provider: identity.provider,
+		model: identity.model,
+		usage: zeroUsage(),
+		stopReason: "stop",
+		timestamp: opts?.timestamp ?? Date.now(),
+	};
+	return {
+		stream,
+		output,
+		showToolNotifications: opts?.showToolNotifications ?? true,
+	};
+}
+
+function getObservedTools(state: AcpPiStreamState): Map<string, ObservedToolState> {
+	if (!state.observedTools) state.observedTools = new Map();
+	return state.observedTools;
+}
+
+function closeThinkingBlock(state: AcpPiStreamState): void {
+	if (state.openThinkingIndex == null) return;
+	const index = state.openThinkingIndex;
+	const block = state.output.content[index] as { thinking?: string };
+	state.stream.push({
+		type: "thinking_end",
+		contentIndex: index,
+		content: block?.thinking ?? "",
+		partial: state.output,
+	});
+	state.openThinkingIndex = undefined;
+}
+
+function closeTextBlock(state: AcpPiStreamState): void {
+	if (state.openTextIndex == null) return;
+	const index = state.openTextIndex;
+	const block = state.output.content[index] as { text?: string };
+	state.stream.push({ type: "text_end", contentIndex: index, content: block?.text ?? "", partial: state.output });
+	state.openTextIndex = undefined;
+}
+
+function ensureTextBlock(state: AcpPiStreamState): number {
+	if (state.openTextIndex != null) return state.openTextIndex;
+	closeThinkingBlock(state);
+	const index = state.output.content.length;
+	state.output.content.push({ type: "text", text: "" });
+	state.openTextIndex = index;
+	state.stream.push({ type: "text_start", contentIndex: index, partial: state.output });
+	return index;
+}
+
+function ensureThinkingBlock(state: AcpPiStreamState): number {
+	if (state.openThinkingIndex != null) return state.openThinkingIndex;
+	closeTextBlock(state);
+	const index = state.output.content.length;
+	state.output.content.push({ type: "thinking", thinking: "", thinkingSignature: "" });
+	state.openThinkingIndex = index;
+	state.stream.push({ type: "thinking_start", contentIndex: index, partial: state.output });
+	return index;
+}
+
+/**
+ * Emit a standalone one-line notice as its own text block. Used for tool /
+ * permission events — informational, NOT structured tool calls.
+ */
+function pushNotice(state: AcpPiStreamState, text: string): void {
+	if (!state.showToolNotifications || !text.trim()) return;
+	closeThinkingBlock(state);
+	closeTextBlock(state);
+	const index = state.output.content.length;
+	state.output.content.push({ type: "text", text });
+	state.stream.push({ type: "text_start", contentIndex: index, partial: state.output });
+	state.stream.push({ type: "text_delta", contentIndex: index, delta: text, partial: state.output });
+	state.stream.push({ type: "text_end", contentIndex: index, content: text, partial: state.output });
+}
+
+/**
+ * Sanitize an inline fragment for the one-line `[tool:*]` / `[permission:*]`
+ * notice surface: collapse whitespace, neutralize backtick fences (which would
+ * otherwise swallow following lines in chat renderers), truncate with ellipsis.
+ */
+export function sanitizeNoticeFragment(text: string | null | undefined, max: number): string {
+	if (!text) return "";
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	const fenceSafe = collapsed.replace(/`{3,}/g, "[fence]").replace(/`/g, "'");
+	if (fenceSafe.length <= max) return fenceSafe;
+	return `${fenceSafe.slice(0, max - 1)}…`;
+}
+
+function firstTextItem(arr: unknown[]): string | undefined {
+	for (const item of arr) {
+		if (item && typeof item === "object" && (item as { type?: string }).type === "text") {
+			const text = String((item as { text?: unknown }).text ?? "").trim();
+			if (text) return text;
+		}
+		// ACP-normalized shape: { type:"content", content:{ type:"text", text } }
+		if (item && typeof item === "object" && (item as { type?: string }).type === "content") {
+			const inner = (item as { content?: { type?: string; text?: unknown } }).content;
+			if (inner && typeof inner === "object" && inner.type === "text") {
+				const text = String(inner.text ?? "").trim();
+				if (text) return text;
+			}
+		}
+	}
+	return undefined;
+}
+
+/** Claude ACP rawOutput is an array of text items; tolerate a CallToolResult body too. */
+function firstTextContent(value: unknown): string | undefined {
+	if (Array.isArray(value)) {
+		const text = firstTextItem(value);
+		if (text) return text;
+	}
+	if (!value || typeof value !== "object") return undefined;
+	const inner = (value as { content?: unknown }).content;
+	if (Array.isArray(inner)) {
+		const text = firstTextItem(inner);
+		if (text) return text;
+	}
+	return undefined;
+}
+
+/** MCP-level error flag on a CallToolResult-shaped rawOutput. */
+function rawOutputHasError(rawOutput: unknown): boolean {
+	if (!rawOutput || typeof rawOutput !== "object") return false;
+	return (rawOutput as { isError?: unknown }).isError === true;
+}
+
+function titleForTool(update: Record<string, unknown>, previousTitle?: string): string {
+	const meta = update?._meta as { claudeCode?: { toolName?: string } } | undefined;
+	return String(update?.title ?? previousTitle ?? meta?.claudeCode?.toolName ?? update?.toolCallId ?? "Tool");
+}
+
+/**
+ * Render an ACP tool_call / tool_call_update as a text notice (NEVER a
+ * structured toolcall — the ACP child already executed it).
+ */
+function renderToolUpdate(state: AcpPiStreamState, update: Record<string, unknown>): void {
+	const toolCallId = String(update?.toolCallId ?? "");
+	if (!toolCallId) return;
+	const observedTools = getObservedTools(state);
+	const previous = observedTools.get(toolCallId);
+	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 });
+		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`);
+	}
+
+	if (status && status !== previous?.status) {
+		const summary = firstTextContent(update?.rawOutput) ?? firstTextContent(updateContent);
+		const suffix = summary ? ` — ${sanitizeNoticeFragment(summary, NOTICE_SUMMARY_MAX)}` : "";
+		if (status === "completed") {
+			const label = rawOutputHasError(update?.rawOutput) ? "tool:failed" : "tool:done";
+			pushNotice(state, `\n[${label}] ${sanitizeNoticeFragment(title, NOTICE_TITLE_MAX)}${suffix}\n`);
+		} else if (status === "failed") {
+			pushNotice(state, `\n[tool:failed] ${sanitizeNoticeFragment(title, NOTICE_TITLE_MAX)}${suffix}\n`);
+		} else if (status === "cancelled") {
+			pushNotice(state, `\n[tool:cancelled] ${sanitizeNoticeFragment(title, NOTICE_TITLE_MAX)}${suffix}\n`);
+		}
+	}
+
+	observedTools.set(toolCallId, { title, status, notifiedRunning });
+}
+
+/** Push a permission-decision notice (informational text, not a tool call). */
+export function pushPermissionNotice(state: AcpPiStreamState, title: string, decision: string): void {
+	pushNotice(state, `\n[permission:${decision}] ${sanitizeNoticeFragment(title, NOTICE_TITLE_MAX)}\n`);
+}
+
+/**
+ * The textSignature marker stamped on lifecycle progress notices (S2f). It is
+ * what lets the transcript flatten (context.ts) and the reuse-compat signature
+ * (session-store.ts) EXCLUDE these blocks: a lifecycle notice is display-only —
+ * it must never replay into an ACP prompt nor perturb a reuse signature, whether
+ * present or absent. Without the marker the "output-side only" claim is L0 hope.
+ */
+export const LIFECYCLE_NOTICE_SIGNATURE = "entwurf:lifecycle-notice-v1";
+
+/**
+ * Push a one-line ACP turn-lifecycle progress notice (`[acp: …]`) as its own
+ * text block, stamped with LIFECYCLE_NOTICE_SIGNATURE. Two ways it differs from
+ * tool/permission notices:
+ *   1. It IGNORES `showToolNotifications`. Turn progress is ALWAYS visible — a
+ *      silent bootstrap (overlay → spawn → init → newSession → setModel → first
+ *      token) reads as a hang. Only the verbose tool stream is suppressible.
+ *   2. The marker keeps it display-only — out of the transcript replay and the
+ *      reuse-compat signature (the two consumers filter on the signature).
+ */
+export function pushAcpLifecycleNotice(state: AcpPiStreamState, text: string): void {
+	const line = `\n[acp: ${sanitizeNoticeFragment(text, NOTICE_TITLE_MAX)}]\n`;
+	closeThinkingBlock(state);
+	closeTextBlock(state);
+	const index = state.output.content.length;
+	state.output.content.push({ type: "text", text: line, textSignature: LIFECYCLE_NOTICE_SIGNATURE });
+	state.stream.push({ type: "text_start", contentIndex: index, partial: state.output });
+	state.stream.push({ type: "text_delta", contentIndex: index, delta: line, partial: state.output });
+	state.stream.push({ type: "text_end", contentIndex: index, content: line, partial: state.output });
+}
+
+/**
+ * Apply one ACP `session_notification` update to the stream state. Unknown
+ * update kinds are ignored (forward-compatible).
+ */
+export function applyAcpSessionUpdate(
+	state: AcpPiStreamState,
+	update: Record<string, unknown> | null | undefined,
+): void {
+	if (!update || typeof update !== "object") return;
+
+	switch (update.sessionUpdate) {
+		case "agent_message_chunk": {
+			const content = update.content as { type?: string; text?: unknown } | undefined;
+			if (content?.type !== "text") return;
+			const delta = String(content.text ?? "");
+			if (!delta) return;
+			const index = ensureTextBlock(state);
+			(state.output.content[index] as { text: string }).text += delta;
+			state.stream.push({ type: "text_delta", contentIndex: index, delta, partial: state.output });
+			break;
+		}
+		case "agent_thought_chunk": {
+			const content = update.content as { type?: string; text?: unknown } | undefined;
+			if (content?.type !== "text") return;
+			const delta = String(content.text ?? "");
+			if (!delta) return;
+			const index = ensureThinkingBlock(state);
+			(state.output.content[index] as { thinking: string }).thinking += delta;
+			state.stream.push({ type: "thinking_delta", contentIndex: index, delta, partial: state.output });
+			break;
+		}
+		case "tool_call":
+		case "tool_call_update": {
+			renderToolUpdate(state, update);
+			break;
+		}
+		case "usage_update": {
+			// S2c maps COARSE ACP usage only: `used` is occupancy-shaped and does
+			// not split cleanly into pi's input/output/cache fields, so we fill
+			// totalTokens + cost.total and leave the rest zero. Richer accounting
+			// is a later lane (S2e/PR-polish).
+			if (typeof update.used === "number") state.output.usage.totalTokens = update.used;
+			const cost = update.cost as { amount?: unknown } | undefined;
+			if (typeof cost?.amount === "number") state.output.usage.cost.total = cost.amount;
+			break;
+		}
+		default:
+			break;
+	}
+}
+
+/** Close any open text/thinking block. Call before pushing the terminal done. */
+export function finalizeAcpStreamState(state: AcpPiStreamState): void {
+	closeThinkingBlock(state);
+	closeTextBlock(state);
+}