@junghanacs/entwurf 0.16.0 → 0.17.1

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

@@ -46,7 +46,12 @@ import { Readable, Writable } from "node:stream";
 import { ndJsonStream, PROTOCOL_VERSION } from "@agentclientprotocol/sdk";
 import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions } from "@earendil-works/pi-ai";
 import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
-import { type AcpClientHandlers, type AcpConnectionLike, connectAcpClient } from "./acp-client.js";
+import {
+	type AcpClientHandlers,
+	type AcpConnectionLike,
+	type AcpPromptResponse,
+	connectAcpClient,
+} from "./acp-client.js";
 import { prependNewPromptAugment } from "./augment.js";
 import { type AcpBackendAdapter, resolveAcpBackendAdapter } from "./backend-adapter.js";
 import {
@@ -104,6 +109,97 @@ const SET_MODEL_TIMEOUT_MS = 30_000;
 // to process-group teardown, so an abort always returns promptly.
 const ABORT_CANCEL_GRACE_MS = 5_000;
 
+/** Tokens below which a re-billed prefix is breakpoint granularity, not news.
+ *  This matches pi's token threshold for a native cache-miss notice, which also
+ *  considers a separate $0.10 cost threshold (read at pi-coding-agent
+ *  `dist/modes/interactive/interactive-mode.js:3130`). */
+const CACHE_MISS_NOTICE_FLOOR_TOKENS = 20_000;
+
+/** ONE turn's ACCOUNTING totals: the SUM over that turn's API round trips, as
+ *  ACP reports them. Carried on `usage.acp`, never on pi's four `Usage` fields —
+ *  those mean one REQUEST's prompt shape to readers that would misread a sum
+ *  (see `sealTurnUsage`). This is the vendor's own arithmetic, relayed. */
+interface AcpTurnAccounting {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+function finiteOrZero(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * ONE turn's ACCOUNTING totals, preferring the widest scope the backend offers.
+ *
+ * `_meta.quota.model_usage` comes from `result.modelUsage` and the vendor calls it
+ * "the accounting-grade figure per the SDK" — it also counts Task subagents,
+ * sidechains, and INTERNAL CALLS SUCH AS COMPACTION, so its rows "can total more
+ * than `token_count`" and are "the fuller picture, not a decomposition of it"
+ * (read at claude-agent-acp 0.73.0 `dist/acp-agent.js:5728-5748`). The narrower
+ * `PromptResponse.usage` (== `quota.token_count`) is the MAIN AGENT LOOP only.
+ *
+ * The wider one is the right numerator because the denominator already has that
+ * scope: `usage.cost.total` is the diff of the backend's running total, which
+ * includes those internal calls. Pairing a main-loop token sum with an
+ * all-inclusive cost understates the cache-effect badge exactly when compaction
+ * ran — and compaction is a live path again (#94). Rows are summed because a
+ * session may in principle report more than one model; with GLG's single-model
+ * rule there is exactly one.
+ *
+ * Falls back to `usage` when the sidecar is absent: `_meta` is a standard ACP
+ * extension slot whose contents a client may not assume, and `quota` is not in
+ * claude-agent-acp's exported types (#96 carries the re-measure-on-bump duty).
+ */
+function readTurnAccounting(promptResult: AcpPromptResponse): AcpTurnAccounting | undefined {
+	const rows = promptResult?._meta?.quota?.model_usage;
+	if (Array.isArray(rows) && rows.length > 0) {
+		const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+		for (const row of rows) {
+			const t = row?.token_count;
+			if (!t) continue;
+			total.input += finiteOrZero(t.inputTokens);
+			total.output += finiteOrZero(t.outputTokens);
+			total.cacheRead += finiteOrZero(t.cachedInputTokens);
+			total.cacheWrite += finiteOrZero(t.cachedWriteTokens);
+		}
+		return total;
+	}
+	const wire = promptResult?.usage;
+	if (!wire) return undefined;
+	return {
+		input: finiteOrZero(wire.inputTokens),
+		output: finiteOrZero(wire.outputTokens),
+		cacheRead: finiteOrZero(wire.cachedReadTokens),
+		cacheWrite: finiteOrZero(wire.cachedWriteTokens),
+	};
+}
+
+/**
+ * The MAIN AGENT LOOP's token totals (`PromptResponse.usage` ==
+ * `quota.token_count`). Same four fields as `readTurnAccounting`, different
+ * scope: this excludes Task subagents, sidechains, and internal calls such
+ * as compaction. The cache-miss bound's recurrence is a MAIN-LOOP identity
+ * — occupancy is main-context occupancy — so its IO terms come from here,
+ * never from the wide rows. Reporting still uses `readTurnAccounting`.
+ */
+function readMainLoopAccounting(promptResult: AcpPromptResponse): AcpTurnAccounting | undefined {
+	const wire = promptResult?.usage;
+	if (!wire) return undefined;
+	return {
+		input: finiteOrZero(wire.inputTokens),
+		output: finiteOrZero(wire.outputTokens),
+		cacheRead: finiteOrZero(wire.cachedReadTokens),
+		cacheWrite: finiteOrZero(wire.cachedWriteTokens),
+	};
+}
+
+/** 191,971 → "192k". Keeps the notice inside the 80-char fragment cap. */
+function formatTokenCount(tokens: number): string {
+	return tokens >= 1000 ? `${Math.round(tokens / 1000)}k` : String(Math.round(tokens));
+}
+
 type StdioChild = ChildProcessByStdio<Writable, Readable, Readable>;
 
 // ---------------------------------------------------------------------------
@@ -119,7 +215,13 @@ export interface AcpChildLike {
 	signalCode: NodeJS.Signals | null;
 	stdin: { destroy(): void; unref?(): void };
 	stdout: { destroy(): void; unref?(): void };
-	stderr: { on(event: "data", listener: (chunk: Buffer) => void): void; destroy(): void; unref?(): void };
+	stderr: {
+		on(event: "data", listener: (chunk: Buffer) => void): void;
+		/** Optional: absent on minimal fakes; the flush is best-effort, never load-bearing for liveness. */
+		once?(event: "close", listener: () => void): void;
+		destroy(): void;
+		unref?(): void;
+	};
 	kill(signal?: NodeJS.Signals | number): boolean;
 	unref(): void;
 	once(event: "exit" | "error", listener: (...args: unknown[]) => void): void;
@@ -210,6 +312,11 @@ interface BridgeSession {
 	 * nothing to diagnose it by (observed 2026-07-30 on a live sonnet reuse turn).
 	 */
 	stderrTail: string[];
+	/**
+	 * SESSION-scoped like `stderrTail`, and for the same reason: the launcher's
+	 * frame can arrive on a turn later than the one that spawned the child.
+	 */
+	launchObservation: AcpLaunchObservation;
 	/** How the child ended, once it has — folded into the prompt-phase error. */
 	exit?: { code: number | null; signal: NodeJS.Signals | null };
 	/**
@@ -234,6 +341,72 @@ interface BridgeSession {
 	childEnd: ChildEndLatch;
 	/** Set while a prompt is in flight so a child death can close it (awaitAcpPromptTurn). */
 	notifyChildGone?: (err: Error) => void;
+	/**
+	 * The SDK's last-observed SESSION-CUMULATIVE cost, in USD — the baseline the
+	 * NEXT turn's cost is differenced against — authoritative for this rail in
+	 * the sense that the backend's own estimate outranks any local recompute,
+	 * not in the sense of a billing statement (#93).
+	 *
+	 * BRIDGE-SESSION SCOPED, and that scope is the invariant. It must track the
+	 * live child, because the cumulative it measures is that child's own running
+	 * total and restarts at zero with a new one: a rebuilt session (config-signature
+	 * drift) gets a fresh object and therefore a fresh baseline, which is exactly
+	 * right. Hoisting this to the pi session would keep a dead child's total as the
+	 * baseline and make the next real turn's diff enormous or negative.
+	 *
+	 * `undefined` = no cumulative observed yet, which is NOT the same as 0: a turn
+	 * that reports no cost must HOLD this value, not zero it, or the amount it
+	 * carried would be double-counted by the next diff.
+	 */
+	sdkCumulativeCostUsd?: number;
+	/**
+	 * The last observed context OCCUPANCY (`usage_update.used`), carried forward
+	 * across a turn whose notification never arrived (#93).
+	 *
+	 * Without this, such a turn carries accounting at `usage.acp` but has zero
+	 * `totalTokens` and zero pi-native usage fields. pi's
+	 * `calculateContextTokens` (read at pi-coding-agent
+	 * `dist/core/compaction/compaction.js:86-88`) then returns 0, making
+	 * auto-compaction replace the vendor observation with its local estimate
+	 * (read at pi-coding-agent `dist/core/agent-session.js:1696-1699`). Carrying
+	 * the last measurement preserves the last known occupancy. Assigned, never
+	 * summed.
+	 */
+	contextOccupancyTokens?: number;
+	/**
+	 * The PREVIOUS turn's MAIN-LOOP `Σinput + Σoutput` (`PromptResponse.usage`,
+	 * never the wide `model_usage` sum) and the wall-clock ms at which that
+	 * turn SEALED. The idle gap is then measured from that seal to THIS turn's
+	 * START (`turnStartedAtMs`), never to its seal, so a turn's own duration can
+	 * never inflate the gap it reports. Together with `contextOccupancyTokens`,
+	 * they are the whole input to the cache-miss bound in `sealTurnUsage` — no
+	 * per-round-trip collection.
+	 *
+	 * Why these two and nothing else: within one turn Claude Code's cache
+	 * breakpoints make `cacheRead_i = cacheRead_(i-1) + cacheWrite_(i-1)`
+	 * (re-measured 2026-09-02 across the WHOLE ACP overlay corpus, not one ledger:
+	 * 2,398 of 2,410 adjacent pairs hold — 99.50% — over 30+ session transcripts
+	 * under `~/.pi/agent/claude-config-overlay/projects` spanning 2026-05 to
+	 * 2026-09. On the incident ledger alone it is 101 of 102, and that single break
+	 * IS the miss: cacheRead 0 against a predicted 195,177 at 2026-09-01T21:15:09Z.
+	 * Of the 12 corpus-wide breaks, 10 fall BELOW prediction — each one a real miss
+	 * or partial re-read — and the 2 that exceed it do so by 4,357 and 3,283 tokens,
+	 * both far under the notice floor, so neither could lift a quiet turn over the
+	 * threshold on its own). Telescoping that identity gives
+	 *
+	 *     cacheRead_first = used_end − ΣcacheWrite − (input_last + output_last)
+	 *
+	 * and the same identity on the previous turn gives what THIS turn's first
+	 * request would have read had the cache still been warm:
+	 *
+	 *     expected = used_prev − (input_last' + output_last')
+	 *
+	 * Only the LAST request's input+output is unknown at turn scope, and it is
+	 * bounded by the turn's own sums — so both quantities come out as PROVEN
+	 * INTERVALS, never estimates. Assigned, never summed.
+	 */
+	priorTurnInputOutputSum?: number;
+	priorTurnSealedAtMs?: number;
 	/**
 	 * This TURN owns reporting the child's end, so the next turn must not also
 	 * announce it. Raised at the top of a failure path — BEFORE the bounded
@@ -367,6 +540,85 @@ const CHILD_END_SETTLE_MS = 500;
  */
 const ACP_CONNECTION_CLOSED_TEXT = "ACP connection closed";
 
+/**
+ * The launcher's control frame — see `claude-acp-launch.js`.
+ *
+ * Matched as an EXACT FULL LINE and nothing else. The vendor writes prose that
+ * mentions signals; a substring test would let vendor text manufacture an
+ * entwurf observation, which is precisely the confusion #72 cost three
+ * diagnosis passes. Our own frame is a fixed enum, so exact-line matching is
+ * sufficient AND necessary.
+ */
+const LAUNCH_SIGNAL_FRAME_PREFIX = "ENTWURF_ACP_LAUNCH_SIGNAL=";
+const LAUNCH_SIGNAL_FRAME_VALUES: ReadonlySet<string> = new Set(["SIGTERM", "SIGINT"]);
+
+/** A mutable, session-scoped record of a terminating signal the LAUNCHER caught. */
+export type AcpLaunchObservation = { signal?: "SIGTERM" | "SIGINT" };
+
+/**
+ * Split a stderr chunk stream into lines, consuming our own frames and passing
+ * everything else through to the tail untouched.
+ *
+ * Line-buffered because a chunk boundary can fall inside a frame; the trailing
+ * partial line is held, not emitted, so a frame split across two reads is still
+ * recognised exactly.
+ */
+function makeLaunchFrameFilter(observation: AcpLaunchObservation, onText: (text: string) => void) {
+	let held = "";
+	return {
+		write(chunk: string): void {
+			held += chunk;
+			let nl = held.indexOf("\n");
+			let passed = "";
+			while (nl !== -1) {
+				const line = held.slice(0, nl);
+				if (
+					line.startsWith(LAUNCH_SIGNAL_FRAME_PREFIX) &&
+					LAUNCH_SIGNAL_FRAME_VALUES.has(line.slice(LAUNCH_SIGNAL_FRAME_PREFIX.length))
+				) {
+					// FIRST caught signal wins: a later one is our own teardown racing
+					// the external kill, and reporting that would bury the cause.
+					observation.signal ??= line.slice(LAUNCH_SIGNAL_FRAME_PREFIX.length) as "SIGTERM" | "SIGINT";
+				} else {
+					passed += `${line}\n`;
+				}
+				held = held.slice(nl + 1);
+				nl = held.indexOf("\n");
+			}
+			if (passed) onText(passed);
+		},
+		/**
+		 * The child's LAST words may arrive without a trailing newline — a process
+		 * dying mid-write is exactly when that happens, and it is exactly when the
+		 * tail matters most. Line buffering would otherwise hold that fragment
+		 * forever, so the stream's close flushes it VERBATIM.
+		 *
+		 * No frame check here, deliberately: the launcher writes its frame with a
+		 * single `writeSync` including the newline, well under PIPE_BUF, so a
+		 * complete frame can never be the un-terminated remainder. Anything left
+		 * without a newline is vendor text by construction.
+		 */
+		flush(): void {
+			if (!held) return;
+			onText(held);
+			held = "";
+		},
+	};
+}
+
+/**
+ * What the operator is told about a caught signal — and what they are NOT told.
+ *
+ * Absence is reported as "not observed", never as "no signal": the launcher can
+ * only see what reached it, and an override launch (`CLAUDE_AGENT_ACP_COMMAND`)
+ * has no launcher at all. Attribution of the SENDER is not claimed here either —
+ * that needs the host's journal, which this process cannot read.
+ */
+function launchSignalLine(observation: AcpLaunchObservation | undefined): string | undefined {
+	if (!observation?.signal) return undefined;
+	return `[acp] launch observed ${observation.signal} before child exit (sender not attributed)`;
+}
+
 function isAcpConnectionClosure(err: unknown): boolean {
 	const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
 	return message.trim() === ACP_CONNECTION_CLOSED_TEXT;
@@ -520,7 +772,7 @@ async function awaitAcpPromptTurn(
 	session: BridgeSession,
 	promptArgs: { sessionId: string; prompt: AcpTextBlock[] },
 	opts: { signal?: AbortSignal; graceMs: number },
-): Promise<{ stopReason?: string }> {
+): Promise<AcpPromptResponse> {
 	let rejectLifecycle: ((err: Error) => void) | undefined;
 	const lifecycle = new Promise<never>((_, reject) => {
 		rejectLifecycle = reject;
@@ -590,9 +842,12 @@ export type AcpStopVerdict = {
 /**
  * ACP prompt stopReason → pi verdict.
  *
- * The ACP terminal set is closed (`@agentclientprotocol/sdk` 1.3.0
- * `schema/types.gen`): end_turn | max_tokens | max_turn_requests | refusal |
- * cancelled. Only three of those are successful or benign ends. The previous
+ * The ACP terminal set is closed (`@agentclientprotocol/sdk` 1.4.0
+ * `dist/schema/types.gen.d.ts:3001`): end_turn | max_tokens | max_turn_requests |
+ * refusal | cancelled — no `| string` arm. 1.4.0 also ships an OPEN union at
+ * `dist/v2/schema/types.gen.d.ts:3607`, but that is behind the `./experimental/v2`
+ * export and entwurf imports the bare specifier, which resolves to the closed v1
+ * surface. Only three of those are successful or benign ends. The previous
  * implementation returned a bare StopReason with `default: "stop"`, which turned
  * `refusal`, `max_turn_requests`, any future member, AND a missing reason into a
  * clean successful turn — pi then rendered a silently truncated answer as if the
@@ -867,6 +1122,14 @@ export function streamAcpTurn(
 	deps: AcpTurnDeps,
 ): ReturnType<typeof createAssistantMessageEventStream> {
 	const stream = createAssistantMessageEventStream();
+	// When THIS turn began. The idle gap that expires a prompt cache is the time
+	// between turns, so it must be measured to a turn's START — measuring to its
+	// seal would fold this turn's own duration into the gap and call a 58-minute
+	// pause plus a 4-minute turn "62m idle", which crosses the 1h TTL in the
+	// report while nothing crossed it in fact. pi's native detector uses message
+	// timestamps for the same reason (read at pi-coding-agent
+	// `dist/core/cache-stats.js:14-37`, `idleMs`).
+	const turnStartedAtMs = Date.now();
 	const state: AcpPiStreamState = createAcpStreamState(stream, {
 		api: "entwurf",
 		provider: "entwurf",
@@ -893,13 +1156,258 @@ export function streamAcpTurn(
 		};
 	}
 
+	/**
+	 * Seal this turn's ACCOUNTING — the #93 authority boundary.
+	 *
+	 * Runs ONLY for a backend whose adapter declares `sealsTurnAccounting`. Flag
+	 * absence means that backend's usage semantics were never measured, so nothing
+	 * is sealed and its emitted usage is whatever the common mapper produced —
+	 * unchanged, not guessed at.
+	 *
+	 * Two INDEPENDENT axes, because they arrive on different wires:
+	 *
+	 *   tokens  the turn aggregate, relayed from PromptResponse on `usage.acp`.
+	 *   cost    an ADJACENT DIFF of the backend's own running session total, which
+	 *           arrives on `usage_update` and is captured raw by the mapper.
+	 *
+	 * The diff is what makes the session sum reproduce the backend's own running
+	 * total exactly — with no residue, which is what the gate measures. Read that
+	 * exactness for what it is: agreement with the BACKEND'S CUMULATIVE ESTIMATE,
+	 * never with an Anthropic invoice. The vendor calls `total_cost_usd` a
+	 * "Cumulative estimated cost" and "An estimate, not a billing statement"
+	 * (claude-agent-sdk `sdk.d.ts:4884`), and entwurf has measured no live
+	 * comparison against a bill.
+	 *
+	 * We prefer that estimate anyway for a STRUCTURAL reason, not because it is
+	 * more precise in general: it is computed UPSTREAM of a lossy flattening we
+	 * cannot undo. The observed cache-writes are entirely 1h, ACP carries no 1h
+	 * field, and pi prices a write with no `cacheWrite1h` at the 5m rate (read at
+	 * pi-coding-agent `dist/bundle/chunks/bedrock-converse-stream.js`,
+	 * `calculateCost`) — a local recompute measured $1.66 low on one live
+	 * ledger. Nothing here calls calculateCost: any price table we could apply
+	 * runs DOWNSTREAM of that flattening, so it would be a second, wronger
+	 * source.
+	 */
+	function sealTurnUsage(adapter: AcpBackendAdapter, session: BridgeSession, promptResult: AcpPromptResponse): void {
+		if (!adapter.sealsTurnAccounting) return;
+
+		// --- the turn's ACCOUNTING aggregate, verbatim ------------------------
+		// ACP reports one number set per turn and it is the SUM OVER THAT TURN'S API
+		// ROUND TRIPS. It is carried on its OWN key, never on pi's four, because
+		// those four mean ONE REQUEST's prompt shape to two readers that never go
+		// through `calculateContextTokens` and so cannot be rescued by an honest
+		// `totalTokens` (isContextOverflow, read at pi-ai
+		// `dist/utils/overflow.js:132-145`; cache-stats.detectMiss, read at
+		// pi-coding-agent `dist/core/cache-stats.js:14-37`). Projecting the
+		// aggregate onto them compacted a live 223,516-token session on a 1,000,000
+		// window (measured 2026-09-01).
+		//
+		// Nothing is computed here: these are the vendor's own four numbers, put
+		// somewhere they cannot be mistaken for a per-request reading. pi stores an
+		// assistant message as JSON and reads it back the same way (read at
+		// pi-coding-agent `dist/core/session-manager.js:768-777` appendMessage,
+		// `:98` parseSessionEntries), so a key pi does not know survives a resume.
+		const aggregate = readTurnAccounting(promptResult);
+		const mainLoop = readMainLoopAccounting(promptResult);
+		if (aggregate) {
+			(state.output.usage as unknown as { acp?: AcpTurnAccounting }).acp = aggregate;
+		}
+
+		// --- token axis: DELIBERATELY UNWRITTEN ------------------------------
+		// The four token fields stay at their zero initialisation. ACP's only token
+		// carrier is `PromptResponse.usage`, and that is the SUM OVER THIS TURN'S
+		// API ROUND TRIPS — measured 2026-09-02 on one 21-round-trip turn whose
+		// overlay rows summed to exactly the four numbers ACP reported
+		// (cacheRead 4,185,084) while the context it occupied was 223,516.
+		//
+		// pi reads these four as ONE REQUEST's prompt shape, in two places that do
+		// NOT go through `calculateContextTokens` and so cannot be rescued by the
+		// honest `totalTokens` written below:
+		//
+		//   isContextOverflow  `input + cacheRead > contextWindow` (read at pi-ai
+		//                      `dist/utils/overflow.js:132-145`). The aggregate made
+		//                      that true at 223k of a 1M window and compacted a live
+		//                      session — the defect this seal now refuses to feed.
+		//   detectMiss         `input + cacheRead + cacheWrite` vs the previous
+		//                      request (read at pi-coding-agent
+		//                      `dist/core/cache-stats.js:14-37`). Under the aggregate
+		//                      it invented two phantom misses and SILENCED the real
+		//                      195,177-token one after a 401-minute idle gap.
+		//
+		// Writing zeros is not a placeholder for a better number we could compute:
+		// the per-request partition is genuinely absent from the wire. The vendor
+		// builds it in `lastAssistantUsage` and sends only its scalar sum (read at
+		// claude-agent-acp 0.73.0 `dist/acp-agent.js:3273-3297`) — #96.
+		//
+		// But silence is NOT the resting state. A cache miss the operator never sees
+		// is a false reading, not a modest one: a session can run for hours believing
+		// its badge while a full prefix rewrite has already been paid for. So the
+		// aggregate rides its own key above, and the bound below reports the rewrite.
+
+		// --- context occupancy (NOT a turn total — see the field's note) -----
+		// Refresh from THIS turn's notification when there was one, then assign the
+		// session's value UNCONDITIONALLY. The assignment is not conditional on the
+		// notification having been missing: on this path the seal — not the mapper —
+		// is the authority for what pi reads as occupancy, and when a fresh value did
+		// arrive the two agree by construction.
+		//
+		// Why the field must be right rather than merely non-zero: pi's auto-compaction
+		// takes `calculateContextTokens(message.usage)` at face value and falls back to
+		// its own estimate ONLY when the message errored or that value is exactly 0
+		// (read at pi-coding-agent `dist/core/agent-session.js:1696-1697`). A turn
+		// aggregate written here would be non-zero and therefore never corrected — the
+		// session would read as nearly empty all the way to an overflow.
+		const priorOccupancy = session.contextOccupancyTokens;
+		const priorIoSum = session.priorTurnInputOutputSum;
+		const priorSealedAtMs = session.priorTurnSealedAtMs;
+
+		const occupancy = state.observedContextOccupancyTokens;
+		if (typeof occupancy === "number") session.contextOccupancyTokens = occupancy;
+		if (typeof session.contextOccupancyTokens === "number") {
+			state.output.usage.totalTokens = session.contextOccupancyTokens;
+		}
+
+		// --- cache-miss bound (the rewrite the operator must not miss) -------
+		// Both quantities below are PROVEN INTERVALS derived from numbers already in
+		// hand, not estimates. See `priorTurnInputOutputSum` for the identity and its
+		// telescoping. Only the LAST request's input+output is unknown at turn scope,
+		// and each turn's own sums bound it:
+		//
+		//   cacheRead_first ≤ used_end − ΣcacheWrite                     (upper)
+		//   expected        ≥ used_prev − (Σinput' + Σoutput')           (lower)
+		//   miss            ≥ expected_lower − cacheRead_first_upper
+		//
+		// The interval is proven only while the within-turn recurrence holds, and that
+		// recurrence is an OBSERVED property of Claude Code's breakpoint placement
+		// (measured 2026-09-02 corpus-wide: 2,398 of 2,410 adjacent pairs, 99.50%; see
+		// `priorTurnInputOutputSum` for the full count and the break characterisation),
+		// not a guarantee. If it breaks mid-turn — a 1h TTL expiring
+		// between round trips, or the child compacting itself — `used_end − ΣcacheWrite`
+		// goes negative and the `max(0, …)` below assumes cacheRead_first = 0. The
+		// notice is still TRUE (a rewrite did happen) but its N is then a floor of a
+		// weaker kind, not a telescoped bound. #96 carries that limit.
+		//
+		// A negative or small bound proves nothing was re-billed beyond breakpoint
+		// granularity, so nothing is said. The floor is the TOKEN half of pi's own
+		// native cache-miss display policy, which suppresses a notice only when the
+		// miss is under 20,000 tokens AND under $0.10 (read at pi-coding-agent
+		// `dist/modes/interactive/interactive-mode.js:3130`). The ACP rail borrows
+		// that familiar token threshold alone and claims no part of the cost half:
+		// this bound is a token interval, and pricing it locally is the very
+		// downstream reprice the cost axis above refuses.
+		// The re-billed size can never exceed what this turn's MAIN LOOP actually
+		// WROTE: a re-billed prefix is paid for as cache creation. Clamping to
+		// `mainLoop.cacheWrite` (not the wide aggregate) is what keeps the notice
+		// a statement about money that changed hands on the prefix rather than
+		// about the recurrence holding, or about an internal compaction write.
+		//
+		// Without it a context SHRINK reads as a giant miss. Worked counterexample
+		// (gpt-5.6-sol, 2026-09-02): prior occupancy 200,000, prior IO 1,000, this
+		// turn occupancy 20,000 with cacheWrite 1,000 — organic compaction, nothing
+		// re-billed — yields 200,000 − 1,000 − 19,000 = 180,000 and would announce
+		// "cache miss ≥180k" over a turn that wrote 1,000 tokens. The clamp answers
+		// 1,000, which is under the floor, so nothing is said. On the real incident
+		// the clamp does not bind: 191,971 ≤ cacheWrite 221,084.
+		//
+		// Both prior marks are read from ONE turn and written from ONE turn. Mixing
+		// an older occupancy with a newer IO sum puts two turns in one equation and
+		// can skew the bound HIGH, so the update below is all-or-nothing.
+		//
+		// The same all-or-nothing applies to SCOPE. Occupancy is main-context;
+		// the recurrence is a main-loop identity. `aggregate.cacheWrite` is the
+		// WIDE accounting figure (Task subagents, sidechains, internal compaction).
+		// A large unrelated wide write shrinks `max(0, occupancy − cacheWrite)`
+		// (less is subtracted) AND raises the `min(…, cacheWrite)` ceiling — both
+		// paths push the bound UP, so a warm main prefix can announce a miss and
+		// attach this turn's all-inclusive dollar figure to it. The IO terms
+		// therefore come from `mainLoop`, never from `aggregate`.
+		const derivable =
+			mainLoop !== undefined &&
+			typeof occupancy === "number" &&
+			typeof priorOccupancy === "number" &&
+			typeof priorIoSum === "number";
+		const cacheWriteForBound = mainLoop !== undefined ? mainLoop.cacheWrite : 0;
+		const rawBound = derivable
+			? (priorOccupancy as number) - (priorIoSum as number) - Math.max(0, (occupancy as number) - cacheWriteForBound)
+			: undefined;
+		const missLowerBound = rawBound === undefined ? undefined : Math.min(rawBound, cacheWriteForBound);
+
+		if (mainLoop && typeof occupancy === "number") {
+			session.priorTurnInputOutputSum = mainLoop.input + mainLoop.output;
+			session.priorTurnSealedAtMs = Date.now();
+		}
+
+		// --- cost axis ------------------------------------------------------
+		// ALWAYS assigned on this path, including the 0 cases: the mapper may have
+		// written the running cumulative into this field, and leaving it would put a
+		// session total on a dashboard that sums per-turn costs — the whole defect.
+		const observed = state.observedSessionCostUsd;
+		let turnCostUsd: number | undefined;
+		if (typeof observed !== "number") {
+			// No cumulative arrived this turn. HOLD the baseline: this turn's real
+			// amount is still inside the backend's running total and the next
+			// adjacent diff absorbs it. Attributed to the wrong turn, exact in the
+			// session sum. Zeroing the baseline here would double-count it instead.
+			state.output.usage.cost.total = 0;
+		} else {
+			const diff = observed - (session.sdkCumulativeCostUsd ?? 0);
+			if (diff < 0) {
+				// The backend's running total went BACKWARDS. TWO receipts, and the gap
+				// between them is exactly why the notice below names a MECHANISM and
+				// never a cause: claude-agent-acp's `conversation_reset` handler only
+				// switches the SDK to a fresh conversation and touches no cost at all
+				// (read at 0.73.0 `dist/acp-agent.js:3675-3682`), while claude-agent-sdk
+				// separately documents that "a mid-session /clear resets the running
+				// total" (read at 0.3.257 `sdk.d.ts:4884`). A reset therefore PLAUSIBLY
+				// explains a backwards total, but nothing here has MEASURED that it did,
+				// and asserting the cause would be the same unmeasured claim this lane
+				// exists to end.
+				// Rebaseline and attribute 0 — but SAY SO. Silently absorbing it would
+				// hide the one observation that can settle what a reset does to the
+				// total, which is precisely the "no silent misaccounting" this lane owes.
+				const detail = `${(session.sdkCumulativeCostUsd ?? 0).toFixed(6)} → ${observed.toFixed(6)} USD`;
+				session.sdkCumulativeCostUsd = observed;
+				state.output.usage.cost.total = 0;
+				// Kept under the notice fragment cap (80) so the two numbers survive
+				// verbatim — a truncated diagnostic is not evidence.
+				pushAcpLifecycleNotice(state, `cost baseline reset (${detail}) — this turn attributed $0`);
+				console.error(
+					`entwurf: ACP backend reported a DECREASING session cost (${detail}). Rebaselined; this turn is ` +
+						`attributed $0. The cause is NOT measured here. The one documented mechanism is a mid-session ` +
+						`/clear, which claude-agent-sdk (sdk.d.ts:4884) says resets the running total; the adapter's ` +
+						`conversation_reset event is NOT it — that handler switches conversation and touches no cost. ` +
+						`The session total from here on is measured against the new baseline.`,
+				);
+			} else {
+				session.sdkCumulativeCostUsd = observed;
+				state.output.usage.cost.total = diff;
+				turnCostUsd = diff;
+			}
+		}
+
+		// --- report the rewrite ----------------------------------------------
+		// Said LAST so it can quote what this turn actually cost. The cost is the
+		// SDK's own adjacent diff, never a local repricing.
+		if (typeof missLowerBound === "number" && missLowerBound >= CACHE_MISS_NOTICE_FLOOR_TOKENS) {
+			// Only when there is an idle gap worth naming. A sub-minute one explains
+			// nothing and "after 0m idle" reads as noise, so the clause is dropped —
+			// the re-billed size and the cost still stand on their own.
+			const idleMinutes =
+				typeof priorSealedAtMs === "number" ? Math.round((turnStartedAtMs - priorSealedAtMs) / 60_000) : 0;
+			const idle = idleMinutes >= 1 ? ` after ${idleMinutes}m idle` : "";
+			const paid = typeof turnCostUsd === "number" ? ` — this turn $${turnCostUsd.toFixed(2)}` : "";
+			pushAcpLifecycleNotice(state, `cache miss ≥${formatTokenCount(missLowerBound)} re-billed${idle}${paid}`);
+		}
+	}
+
 	/**
 	 * Seal the turn from the ACP prompt result. "Success" here means the RPC
 	 * returned, not that the turn ended well — a returned `refusal` /
 	 * `max_turn_requests` / unknown / absent reason is sealed as an error event,
 	 * never a `done`. `rawStopReason` carries the wire value out either way.
 	 */
-	function finishSuccess(promptResult: { stopReason?: string }): void {
+	function finishSuccess(adapter: AcpBackendAdapter, session: BridgeSession, promptResult: AcpPromptResponse): void {
+		sealTurnUsage(adapter, session, promptResult);
 		finalizeAcpStreamState(state);
 		const verdict = mapPromptStopReason(promptResult?.stopReason);
 		if (verdict.rawStopReason !== undefined) state.output.rawStopReason = verdict.rawStopReason;
@@ -921,14 +1429,24 @@ export function streamAcpTurn(
 		stream.end();
 	}
 
-	function finishError(err: unknown, aborted: boolean, stderrTail?: string[], lifecycle?: string): void {
+	function finishError(
+		err: unknown,
+		aborted: boolean,
+		stderrTail?: string[],
+		lifecycle?: string,
+		launchObservation?: AcpLaunchObservation,
+	): void {
 		finalizeAcpStreamState(state);
 		state.output.stopReason = aborted ? "aborted" : "error";
 		const base = err instanceof Error ? err.message : String(err);
 		// The FIRST failure stays first and verbatim (it is what the backend
 		// actually said); the lifecycle line is added, never substituted, so a
 		// reader can still match the transport's own text.
-		const diagnosed = lifecycle ? `${base}\n${lifecycle}` : base;
+		const withLifecycle = lifecycle ? `${base}\n${lifecycle}` : base;
+		// Its OWN line, above the vendor tail: an entwurf-owned observation must not
+		// have to be recovered by reading vendor prose.
+		const observed = launchSignalLine(launchObservation);
+		const diagnosed = observed ? `${withLifecycle}\n${observed}` : withLifecycle;
 		const tail = (stderrTail ?? []).join("").trim().slice(-1_000);
 		const full = tail ? `${diagnosed}\n--- backend stderr (tail) ---\n${tail}` : diagnosed;
 		// A-c: a real failure (not an abort) that looks like a context-window
@@ -1100,7 +1618,7 @@ export function streamAcpTurn(
 		inFlightKeys.add(sessionKey);
 		try {
 			if (decision.path === "reuse" && existing) {
-				await runReuseTurn(existing, ctxSigs);
+				await runReuseTurn(existing, ctxSigs, adapter);
 			} else {
 				await runNewTurn(params, ctxSigs, engraving, config, adapter, nativeModelId);
 			}
@@ -1124,6 +1642,8 @@ export function streamAcpTurn(
 		/** Which phase a failure belongs to — flipped once the prompt is on the wire. */
 		let phase: "pre-prompt" | "prompt" = "pre-prompt";
 		const stderrTail: string[] = [];
+		// Session-scoped alongside the tail — see the field's note on the session type.
+		const launchObservation: AcpLaunchObservation = {};
 		const sessionKey = resolveSessionKey(opts, cwd);
 		try {
 			if (signal?.aborted) throw new Error("aborted before launch");
@@ -1156,10 +1676,18 @@ export function streamAcpTurn(
 			const spawned = child;
 
 			// Drain stderr (an unconsumed pipe can backpressure-deadlock a long turn).
-			spawned.stderr.on("data", (c: Buffer) => {
-				stderrTail.push(c.toString());
+			// The launcher's own control frames are consumed here and kept OUT of the
+			// tail: the tail is vendor evidence, the observation is an entwurf fact,
+			// and mixing the two is the overloading #72 was made of.
+			const consumeStderr = makeLaunchFrameFilter(launchObservation, (text) => {
+				stderrTail.push(text);
 				if (stderrTail.length > 50) stderrTail.shift();
 			});
+			spawned.stderr.on("data", (c: Buffer) => consumeStderr.write(c.toString()));
+			// `close` rather than `end`: it covers the destroy path our own teardown
+			// takes, and on the EOF-first death it lands inside the post-mortem
+			// settle window, so the flushed fragment is in the tail before we seal.
+			spawned.stderr.once?.("close", () => consumeStderr.flush());
 
 			// Abort during BOOTSTRAP (spawn → initialize → newSession → set-model):
 			// there is no prompt turn for the agent to cancel yet, so the child is
@@ -1211,6 +1739,8 @@ export function streamAcpTurn(
 				// this turn with the session, so a later reuse turn can still report
 				// the child's dying words.
 				stderrTail,
+				// SAME object the frame filter writes into, for the same reason.
+				launchObservation,
 				// Armed at spawn, before ANY turn can fail on this child — the latch
 				// must already exist when the `exit` listener below can fire.
 				childEnd: makeChildEndLatch(),
@@ -1314,18 +1844,42 @@ export function streamAcpTurn(
 
 			session.activePromptHandler = undefined;
 			session.busy = false;
-			finishSuccess(promptResult);
 
 			// Retain ONLY a long-lived process-scoped session that survived the turn
 			// alive and un-aborted. A turn-scoped one-shot (and any aborted/dead
 			// turn) tears down so its stdio handle cannot pin pi's exit (S2c hang).
-			if (params.lifecyclePolicy === "process-scoped" && !signal?.aborted && session.alive) {
+			const retain = params.lifecyclePolicy === "process-scoped" && !signal?.aborted && session.alive;
+
+			// DISCOVERABILITY BEFORE THE SEAL. `finishSuccess` ends the stream, and
+			// ending the stream is what releases the caller — which may start the next
+			// turn on that event. A completed process-scoped session that is not yet in
+			// the map would send that turn down the NEW path: a second child, and with
+			// it a FRESH cost baseline, so a long session's accounting would silently
+			// reset at a turn boundary (#93).
+			//
+			// Two things make that window empty today — nothing here awaits, and the
+			// turn's in-flight claim is not released until after this returns — but both
+			// are invariants of surrounding code rather than of this ordering, and
+			// neither is visible from this line. Registering first makes the guarantee
+			// local: the session is discoverable before anything can act on the seal,
+			// whatever the code around it later does.
+			if (retain) {
 				bridgeSessions.set(sessionKey, session);
 				retainedChildren.add(spawned);
 				registerGlobalCleanup();
 				// unref so the retained stdio cannot pin pi's exit at resident
 				// shutdown — reuse is unaffected (unref ≠ destroy). GPT amber.
 				unrefRetainedChild(spawned);
+			}
+
+			finishSuccess(adapter, session, promptResult);
+
+			if (retain) {
+				// AFTER the seal, deliberately: persisting is bookkeeping about a turn
+				// that already answered, so a failed record write must not convert an
+				// answered turn into an error turn. If it throws, the catch below still
+				// un-registers this session and tears its child down — the same cleanup
+				// a sealing exception gets.
 				persistRecord(session, deps);
 			} else {
 				session.retiring = true;
@@ -1345,7 +1899,13 @@ export function streamAcpTurn(
 			// own SIGTERM; the tail collected by then is sealed before our cleanup
 			// touches the stderr pipe.
 			const lifecycle = await diagnoseTransportClosure({ err, session, phase, aborted });
-			finishError(err, aborted, session?.stderrTail ?? stderrTail, lifecycle);
+			finishError(
+				err,
+				aborted,
+				session?.stderrTail ?? stderrTail,
+				lifecycle,
+				session?.launchObservation ?? launchObservation,
+			);
 			// error/abort → drop the (uncertain) session and close its child; an
 			// uncertain connection must never be reused (GPT ④).
 			if (child) {
@@ -1360,7 +1920,7 @@ export function streamAcpTurn(
 	}
 
 	// --- reuse: send only the latest user delta to the live ACP session
-	async function runReuseTurn(session: BridgeSession, ctxSigs: string[]): Promise<void> {
+	async function runReuseTurn(session: BridgeSession, ctxSigs: string[], adapter: AcpBackendAdapter): Promise<void> {
 		/** Same phase discipline as a new turn — reuse just has no bootstrap to lose. */
 		let phase: "pre-prompt" | "prompt" = "pre-prompt";
 		try {
@@ -1396,7 +1956,7 @@ export function streamAcpTurn(
 			// prefix-compat check sees the full prior history (GPT ④: store the
 			// ctxSigs from the START of this call, only after the turn succeeds).
 			session.contextMessageSignatures = ctxSigs;
-			finishSuccess(promptResult);
+			finishSuccess(adapter, session, promptResult);
 			persistRecord(session, deps);
 		} catch (err) {
 			const aborted = Boolean(signal?.aborted);
@@ -1412,7 +1972,7 @@ export function streamAcpTurn(
 			// Without the session-scoped tail a mid-turn child death on a resident
 			// session surfaced as a bare "ACP connection closed" with nothing to read
 			// it by.
-			finishError(err, aborted, session.stderrTail, lifecycle);
+			finishError(err, aborted, session.stderrTail, lifecycle, session.launchObservation);
 			// error/abort on a reused session → drop it and close the child (GPT ④).
 			session.retiring = true;
 			retainedChildren.delete(session.child);