@junghanacs/entwurf 0.16.0 → 0.17.1

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

@@ -16,7 +16,7 @@
 // This module owns the `AcpConnectionLike` seam so the backend and the live
 // smokes both drive ONE adapter — the SDK method-name mapping lives here only,
 // and the backend's orchestration + the gate fakes stay untouched.
-import { AGENT_METHODS, CLIENT_METHODS, client } from "@agentclientprotocol/sdk";
+import { AGENT_METHODS, CLIENT_METHODS, client, } from "@agentclientprotocol/sdk";
 /**
  * Production factory — wrap the SDK 1.1 fluent `client()` into the
  * `AcpConnectionLike` seam the backend (and the live smokes) drive.

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

@@ -17,10 +17,9 @@
 //
 // Fence: imported by the root program with `.js` suffixes, same as the sibling
 // lib/acp modules — no new strip-types fence.
-import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { enrichMcpServersWithEnvelope } from "./config.js";
 import { loadEngraving } from "./engraving.js";
 import { CORTEX_MODEL_PREFIX, curatedClaudeModels, curatedCortexModels, SUPPORTED_ANTHROPIC_MODEL_IDS, SUPPORTED_CORTEX_MODEL_IDS, } from "./models.js";
@@ -39,19 +38,29 @@ function shellQuote(value) {
 // claude adapter — the first implementation (the rail's reference backend)
 // ---------------------------------------------------------------------------
 const SUPPORTED_CLAUDE_IDS = new Set(SUPPORTED_ANTHROPIC_MODEL_IDS);
-/** Resolve the claude-agent-acp launch — package bin (resolve), env override for debug.
- *  This is the single source for the claude launch spec; backend.ts holds no private copy. */
+/**
+ * Resolve the claude launch — an ENTWURF-OWNED launcher, or the env override for debug.
+ * This is the single source for the claude launch spec; backend.ts holds no private copy.
+ *
+ * The default no longer names the vendor bin directly. `claude-acp-launch.js`
+ * imports it in-process; that file's header carries the reason (#72: a janitor
+ * for another harness selects `claude-agent-acp` by argv substring and SIGTERMs
+ * it by age, and the vendor's own handler erases the signal into exit 0).
+ *
+ * `CLAUDE_AGENT_ACP_COMMAND` is an EXPLICIT operator override and is deliberately
+ * NOT routed through the launcher: an operator who names their own command owns
+ * the result, including the loss of the name split and the signal observation.
+ */
 function resolveClaudeLaunch() {
     const override = process.env.CLAUDE_AGENT_ACP_COMMAND?.trim();
     if (override)
         return { command: "bash", args: ["-lc", override] };
+    // Resolved here (not inside the launcher's own directory lookup) so a missing
+    // vendor package still fails at launch resolution, where it always failed.
     const require = createRequire(import.meta.url);
-    const pkgJsonPath = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
-    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
-    const binPath = typeof pkgJson.bin === "string" ? pkgJson.bin : pkgJson.bin?.["claude-agent-acp"];
-    if (!binPath)
-        throw new Error("@agentclientprotocol/claude-agent-acp resolved but exposes no bin entry");
-    return { command: process.execPath, args: [join(dirname(pkgJsonPath), binPath)] };
+    require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+    const launcher = fileURLToPath(new URL("./claude-acp-launch.js", import.meta.url));
+    return { command: process.execPath, args: [launcher] };
 }
 export const claudeAdapter = {
     backend: "claude",
@@ -112,6 +121,13 @@ export const claudeAdapter = {
         // `_adapterSettings` here.
         return {};
     },
+    // MEASURED (2026-09-02, #93): claude-agent-acp's `usage_update` carries a
+    // session-cumulative ESTIMATED cost (`cost.amount = message.total_cost_usd`)
+    // and a context-occupancy scalar (`used`; both read at 0.73.0
+    // `dist/acp-agent.js:2918-2924`). Both are measured, so backend.ts seals them.
+    // The token partition is NOT declared here: ACP's only token carrier is a
+    // per-turn round-trip aggregate, which is not what pi's four fields mean.
+    sealsTurnAccounting: true,
 };
 // ---------------------------------------------------------------------------
 // Registry — modelId → adapter
@@ -250,6 +266,14 @@ export const cortexAdapter = {
         const settings = adapterSettings;
         return { cortexConnection: settings?.cortexConnection ?? null };
     },
+    // NO sealsTurnAccounting — a DELIBERATE, permanent absence, not an omission to be
+    // filled in later by symmetry with claude. Nobody has measured what cortex's
+    // ACP `usage` (and its usage_update cost, if it sends one) MEAN: whether the
+    // token counts are a turn delta or a session total, and against which price
+    // table. Until that measurement exists, the honest report is no report:
+    // backend.ts seals nothing for a backend without this flag, so cortex's
+    // emitted usage is byte-identical to what it was before #93. Declaring this
+    // with a guess would mint exactly the silent misaccounting #93 exists to end.
 };
 const ADAPTERS = [claudeAdapter, cortexAdapter];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.16.0",
+	"version": "0.17.1",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for Claude Code, Codex, Antigravity, and pi harnesses.",
 	"license": "MIT",
 	"author": {
@@ -82,23 +82,23 @@
 		"claudeCodeFloor": ">=2.1.217"
 	},
 	"dependencies": {
-		"@agentclientprotocol/claude-agent-acp": "0.70.0",
-		"@agentclientprotocol/sdk": "1.3.0",
+		"@agentclientprotocol/claude-agent-acp": "0.73.0",
+		"@agentclientprotocol/sdk": "1.4.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.84.3 <0.85",
-		"@earendil-works/pi-coding-agent": ">=0.84.3 <0.85",
-		"@earendil-works/pi-tui": ">=0.84.3 <0.85",
+		"@earendil-works/pi-ai": ">=0.84.4 <0.85",
+		"@earendil-works/pi-coding-agent": ">=0.84.4 <0.85",
+		"@earendil-works/pi-tui": ">=0.84.4 <0.85",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.13",
-		"@earendil-works/pi-ai": "0.84.3",
-		"@earendil-works/pi-coding-agent": "0.84.3",
-		"@earendil-works/pi-tui": "0.84.3",
+		"@earendil-works/pi-ai": "0.84.4",
+		"@earendil-works/pi-coding-agent": "0.84.4",
+		"@earendil-works/pi-tui": "0.84.4",
 		"@types/node": "^24.3.0",
 		"husky": "^9.1.7",
 		"rregex": "1.13.1",
@@ -165,7 +165,7 @@
 		"check:toolchain": "pnpm lint && pnpm typecheck",
 		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface",
 		"check:contracts": "./run.sh check-shell-quote && ./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-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./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-copilot-statusline && ./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-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-resume-args && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./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-auth-boundary && ./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-carrier-augment",
-		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./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-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex",
+		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./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-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh smoke-setup-verdict && ./run.sh check-pack-pin-matcher && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"
 	},
 	"pi": {

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

@@ -17,14 +17,68 @@
 // smokes both drive ONE adapter — the SDK method-name mapping lives here only,
 // and the backend's orchestration + the gate fakes stay untouched.
 
-import { AGENT_METHODS, CLIENT_METHODS, client, type Stream } from "@agentclientprotocol/sdk";
+import {
+	type Usage as AcpWireUsage,
+	AGENT_METHODS,
+	CLIENT_METHODS,
+	client,
+	type Stream,
+} from "@agentclientprotocol/sdk";
 import type { AcpTextBlock } from "./context.js";
 
+/**
+ * What `session/prompt` answers with — entwurf's own narrow view of the SDK's
+ * `PromptResponse`.
+ *
+ * `stopReason` stays `string | undefined` DELIBERATELY, not the SDK's closed
+ * `StopReason` union: backend.ts's verdict mapping owes an honest answer for an
+ * unknown or absent reason (it seals those as errors), and typing the field as
+ * the closed union would make that branch look unreachable.
+ *
+ * `usage` reuses the SDK's own `Usage` type rather than a hand-copy, so a field
+ * rename upstream is a typecheck failure here instead of a silent zero. It is
+ * marked `@experimental` upstream and its per-field comments say "across all
+ * turns/session" while the outer one says "for this turn" — that contradiction
+ * is why NO common code interprets this shape — and #93 then measured that the
+ * counts are a per-turn ROUND-TRIP AGGREGATE, which is not what any of pi's four
+ * `Usage` fields mean. It is read in exactly ONE place, `sealTurnUsage`, which
+ * relays it verbatim onto `usage.acp` (an accounting key, never a per-request
+ * shape) and never onto those four. A field rename upstream fails the typecheck
+ * here rather than silently zeroing the operator's cache-effect badge.
+ */
+/** One `_meta.quota.token_count` row (claude-agent-acp 0.73.0
+ *  `dist/acp-agent.js:5750-5765`). `cachedInputTokens` is cache READS — the name
+ *  differs from `usage.cachedReadTokens` because the shape is shared with
+ *  codex-acp; `cachedWriteTokens` is Claude's extra sibling. */
+export type AcpQuotaTokenCount = {
+	totalTokens?: number | null;
+	inputTokens?: number | null;
+	cachedInputTokens?: number | null;
+	cachedWriteTokens?: number | null;
+	outputTokens?: number | null;
+};
+
+export type AcpPromptResponse = {
+	stopReason?: string;
+	usage?: AcpWireUsage | null;
+	/** Vendor-private, version-pinned. `_meta` is a standard ACP extension slot
+	 *  whose values a client may not assume, and `quota` is NOT in
+	 *  claude-agent-acp's exported types — it is produced by the private
+	 *  `turnQuotaMeta()` (read at 0.73.0 `dist/acp-agent.js:5738-5748`). Read
+	 *  defensively, never structurally required, and re-measure on a pin move. */
+	_meta?: {
+		quota?: {
+			token_count?: AcpQuotaTokenCount | null;
+			model_usage?: ReadonlyArray<{ model?: string; token_count?: AcpQuotaTokenCount | null }> | null;
+		} | null;
+	} | null;
+};
+
 /** The subset of the ACP agent connection the backend drives (real or fake). */
 export interface AcpConnectionLike {
 	initialize(params: unknown): Promise<unknown>;
 	newSession(params: unknown): Promise<{ sessionId?: string }>;
-	prompt(params: { sessionId: string; prompt: AcpTextBlock[] }): Promise<{ stopReason?: string }>;
+	prompt(params: { sessionId: string; prompt: AcpTextBlock[] }): Promise<AcpPromptResponse>;
 	setSessionConfigOption?(params: unknown): Promise<unknown>;
 	/**
 	 * ACP `session/cancel` — the PROTOCOL way to end an in-flight prompt turn.
@@ -84,8 +138,7 @@ export function connectAcpClient(stream: Stream, handlers: AcpClientHandlers): A
 		initialize: (params) => agent.request(AGENT_METHODS.initialize, params as never),
 		newSession: (params) =>
 			agent.request(AGENT_METHODS.session_new, params as never) as Promise<{ sessionId?: string }>,
-		prompt: (params) =>
-			agent.request(AGENT_METHODS.session_prompt, params as never) as Promise<{ stopReason?: string }>,
+		prompt: (params) => agent.request(AGENT_METHODS.session_prompt, params as never) as Promise<AcpPromptResponse>,
 		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

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

@@ -18,10 +18,9 @@
 // Fence: imported by the root program with `.js` suffixes, same as the sibling
 // lib/acp modules — no new strip-types fence.
 
-import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import type { AcpConnectionLike } from "./acp-client.js";
 import { enrichMcpServersWithEnvelope, type ResolvedAcpConfig } from "./config.js";
@@ -132,6 +131,30 @@ export interface AcpAdapterSettingsParams {
 	projectPath: string;
 }
 
+/**
+ * NO turn-usage evidence type lives here any more, and its absence is the #93
+ * finding, not an omission.
+ *
+ * ACP reports a turn's tokens ONLY as the SUM OVER THAT TURN'S API ROUND TRIPS
+ * (measured 2026-09-02: one 21-round-trip turn summed to cacheRead 4,185,084
+ * while the context it occupied was 223,516 — the overlay ledger's 21 rows add
+ * up to the four numbers `PromptResponse.usage` reported). pi's four `Usage`
+ * fields are not that quantity: `isContextOverflow` reads `input + cacheRead`
+ * as ONE REQUEST's prompt size (read at pi-ai `dist/utils/overflow.js:132-145`)
+ * and `cache-stats.detectMiss` reads input, cache-read, and cache-write as
+ * one request's prompt shape (read at pi-coding-agent
+ * `dist/core/cache-stats.js:14-37`). Projecting the turn
+ * aggregate into them fired a false overflow that compacted a live 223k session
+ * on a 1M window, invented two phantom cache misses, and SILENCED the one real
+ * 195,177-token miss the operator needed to see.
+ *
+ * During stream handling the vendor keeps a per-message snapshot in
+ * `lastAssistantUsage`, but its `usage_update` publishes only the scalar `used`
+ * value (read at claude-agent-acp 0.73.0 `dist/acp-agent.js:3273-3297`). Until
+ * that partition is carried on the wire, NOTHING honest can go in pi's four
+ * fields, so entwurf writes none of them.
+ */
+
 // ---------------------------------------------------------------------------
 // The adapter interface
 // ---------------------------------------------------------------------------
@@ -194,6 +217,24 @@ export interface AcpBackendAdapter {
 	 *  sorted-stable primitive map (JSON.stringify determinism — no nested objects /
 	 *  non-deterministic order). `backend` + `nativeModelId` are added by backend.ts. */
 	configSignatureFields(adapterSettings: unknown): Record<string, unknown>;
+
+	/** Declares that THIS backend's `usage_update` cost semantics have been
+	 *  MEASURED, so backend.ts may seal its context occupancy and its per-turn
+	 *  cost from the session baseline.
+	 *
+	 *  ABSENT means no measured semantics — permanent and static, not an omission
+	 *  to fill in by symmetry (cortex). backend.ts then seals NOTHING: no
+	 *  occupancy, no cost baseline, no diff. That is what keeps this lane's
+	 *  accounting out of a backend whose wire meaning nobody has measured.
+	 *
+	 *  This is deliberately NOT a method returning token evidence. It was one
+	 *  until #93 measured that ACP's only token carrier is a turn aggregate that
+	 *  pi's four `Usage` fields cannot honestly hold (see the note above
+	 *  `AcpBackendAdapter`). With no token axis left to extract, presence alone
+	 *  carries everything the seal needs, and a flag that gates only the two axes
+	 *  entwurf actually reads from a NOTIFICATION cannot desync from a response
+	 *  shape it never inspects. */
+	sealsTurnAccounting?: true;
 }
 
 // ---------------------------------------------------------------------------
@@ -202,17 +243,28 @@ export interface AcpBackendAdapter {
 
 const SUPPORTED_CLAUDE_IDS: ReadonlySet<string> = new Set(SUPPORTED_ANTHROPIC_MODEL_IDS);
 
-/** Resolve the claude-agent-acp launch — package bin (resolve), env override for debug.
- *  This is the single source for the claude launch spec; backend.ts holds no private copy. */
+/**
+ * Resolve the claude launch — an ENTWURF-OWNED launcher, or the env override for debug.
+ * This is the single source for the claude launch spec; backend.ts holds no private copy.
+ *
+ * The default no longer names the vendor bin directly. `claude-acp-launch.js`
+ * imports it in-process; that file's header carries the reason (#72: a janitor
+ * for another harness selects `claude-agent-acp` by argv substring and SIGTERMs
+ * it by age, and the vendor's own handler erases the signal into exit 0).
+ *
+ * `CLAUDE_AGENT_ACP_COMMAND` is an EXPLICIT operator override and is deliberately
+ * NOT routed through the launcher: an operator who names their own command owns
+ * the result, including the loss of the name split and the signal observation.
+ */
 function resolveClaudeLaunch(): AcpLaunchSpec {
 	const override = process.env.CLAUDE_AGENT_ACP_COMMAND?.trim();
 	if (override) return { command: "bash", args: ["-lc", override] };
+	// Resolved here (not inside the launcher's own directory lookup) so a missing
+	// vendor package still fails at launch resolution, where it always failed.
 	const require = createRequire(import.meta.url);
-	const pkgJsonPath = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
-	const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as { bin?: string | Record<string, string> };
-	const binPath = typeof pkgJson.bin === "string" ? pkgJson.bin : pkgJson.bin?.["claude-agent-acp"];
-	if (!binPath) throw new Error("@agentclientprotocol/claude-agent-acp resolved but exposes no bin entry");
-	return { command: process.execPath, args: [join(dirname(pkgJsonPath), binPath)] };
+	require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+	const launcher = fileURLToPath(new URL("./claude-acp-launch.js", import.meta.url));
+	return { command: process.execPath, args: [launcher] };
 }
 
 export const claudeAdapter: AcpBackendAdapter = {
@@ -287,6 +339,14 @@ export const claudeAdapter: AcpBackendAdapter = {
 		// `_adapterSettings` here.
 		return {};
 	},
+
+	// MEASURED (2026-09-02, #93): claude-agent-acp's `usage_update` carries a
+	// session-cumulative ESTIMATED cost (`cost.amount = message.total_cost_usd`)
+	// and a context-occupancy scalar (`used`; both read at 0.73.0
+	// `dist/acp-agent.js:2918-2924`). Both are measured, so backend.ts seals them.
+	// The token partition is NOT declared here: ACP's only token carrier is a
+	// per-turn round-trip aggregate, which is not what pi's four fields mean.
+	sealsTurnAccounting: true,
 };
 
 // ---------------------------------------------------------------------------
@@ -446,6 +506,15 @@ export const cortexAdapter: AcpBackendAdapter = {
 		const settings = adapterSettings as CortexAdapterSettings | undefined;
 		return { cortexConnection: settings?.cortexConnection ?? null };
 	},
+
+	// NO sealsTurnAccounting — a DELIBERATE, permanent absence, not an omission to be
+	// filled in later by symmetry with claude. Nobody has measured what cortex's
+	// ACP `usage` (and its usage_update cost, if it sends one) MEAN: whether the
+	// token counts are a turn delta or a session total, and against which price
+	// table. Until that measurement exists, the honest report is no report:
+	// backend.ts seals nothing for a backend without this flag, so cortex's
+	// emitted usage is byte-identical to what it was before #93. Declaring this
+	// with a guess would mint exactly the silent misaccounting #93 exists to end.
 };
 
 const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];