@aitne/daemon 0.1.10 → 0.1.11

package/dist/core/backends/claude-code-core.js

@@ -7,6 +7,7 @@ import { OBSERVATIONS_MCP_SERVER_NAME, createObservationsMcpServer, } from "../.
 import { parseMcpToolName } from "../../services/mcp/risk.js";
 import { logMcpToolCall, updateMcpToolCallResult } from "../../services/mcp/tool-audit.js";
 import { BackendQuotaError, BackendDecisiveFailure, } from "../agent-core.js";
+import { PriceFetcher } from "./price-fetcher.js";
 import { flattenToolResultContent } from "../../services/delegated-tool-runtime.js";
 import { runDelegatedTool as runDelegatedToolFn, runDelegatedTask as runDelegatedTaskFn, } from "./claude-delegated.js";
 import { createSessionWorkdir, cleanupSessionWorkdir } from "../workdir.js";
@@ -15,7 +16,7 @@ import { buildDaemonApiCliEnv } from "../daemon-api-cli.js";
 import { createLogger } from "../../logging.js";
 import { DEFAULT_CLAUDE_HIGH_MODEL, DEFAULT_CLAUDE_MEDIUM_MODEL, findRegisteredModel, getModelsForBackend, } from "./model-registry.js";
 import { ALWAYS_DISALLOWED_TOOLS } from "../../safety/always-disallowed.js";
-import { loadFetchWindowSystemPrompt, resetFetchWindowSystemPromptForTest, } from "../fetch-window-prompt-loader.js";
+import { loadFetchWindowSystemPrompt, loadSlimSystemPrompt, resetFetchWindowSystemPromptForTest, } from "../slim-system-prompt-loader.js";
 import { CliPathCache } from "./cli-utils.js";
 import { extractSilentApiErrors, logSilentApiErrors, } from "./silent-api-error-detector.js";
 import { CLAUDE_PROBE_TOOLS_PROMPT, computeDelegatedClaudeTools, computeNativeClaudeTools, describeClaudeProbeResultError, extractClaudeProbeTools, } from "./claude-probe.js";
@@ -74,35 +75,56 @@ const logger = createLogger("claude-code-core");
  */
 const CLAUDE_SDK_SETTING_SOURCES = ["user", "project"];
 /**
- * `routine.fetch_window` is a short, lite-tier pre-pass with high
- * per-session prompt-cache write cost (docs/design/appendices/fetch-window-cost-reduction.md
- * §1). The full `preset: "claude_code"` system prompt drags in ~30 K tokens
- * of built-in tool descriptions, the skills index, the memory-system docs,
- * and tone/style guidance — none of which the fetcher uses. Phase 1
- * replaces the preset with a fully custom systemPrompt string for this
- * one process key (SDK 0.2.98 has no `presetOptions` granularity to drop
- * sub-sections of the preset, so a string prompt is the only lever).
+ * Slim, lite-tier process keys swap the verbose `preset: "claude_code"`
+ * system prompt (~30 K tokens of built-in tool descriptions, the skills
+ * index, the memory-system docs, and tone/style guidance the key never
+ * uses) for a tight custom systemPrompt string. SDK 0.2.98 has no
+ * `presetOptions` granularity to drop sub-sections of the preset, so a
+ * string prompt is the only lever. `buildSystemPrompt` resolves membership
+ * through the shared registry in `core/slim-system-prompt-loader.ts`
+ * (`loadSlimSystemPrompt`) — the SAME loader the `SkillsCompiler` uses to
+ * write the byte-identical body into Codex / Gemini AGENTS.md / GEMINI.md,
+ * so adding a slim key is a one-line registry edit that wires both backends.
+ * Per-key agent profiles + task-flow bodies still ship the operational
+ * rules; the slim system prompt only sets the broad stance, and the SDK
+ * still loads the per-cwd CLAUDE.md the SkillsCompiler materializes.
+ *   - `routine.fetch_window` — docs/design/appendices/fetch-window-cost-reduction.md
+ *     Phase 1 / 1.5.
+ *   - `routine.research_cluster_update` — RESEARCH_CLUSTER_COST_FIX_PLAN.md F4.
+ */
+/**
+ * Slim keys whose Claude SDK session ALSO sheds the daemon user's `~/.claude`
+ * scope: `settingSources` drops to `["project"]` and `strictMcpConfig` is
+ * forced on. On a dev machine the `"user"` source pulls in the user's plugin
+ * SKILL.md tree (~178 files) + the ~25 K-token user-scope claude.ai MCP
+ * connector schemas (`mcp__claude_ai_*`) into EVERY session's prompt-cache
+ * prefix (RESEARCH_CLUSTER_COST_FIX_PLAN.md RC4). Dropping it is pure win
+ * for a key that reaches no integration through those connectors.
+ *
+ * This is a STRICT SUBSET of the slim-system-prompt keys, NOT the same set:
+ * a key only qualifies when it serves NO native-mode integration. In native
+ * integration mode the fetcher reaches Gmail / Calendar / Notion precisely
+ * through the user-scope claude.ai connectors, so `routine.fetch_window` keeps
+ * `["user", "project"]` and is deliberately ABSENT here even though it has a
+ * slim system prompt. `routine.research_cluster_update` only ever curls the
+ * daemon's own browser-history + context REST API (no claude.ai connector),
+ * so shedding the user scope cannot starve it.
  *
- * Phase 1.5 promotes the same template to a single source of truth across
- * backends: the loader lives in `core/fetch-window-prompt-loader.ts` so the
- * `SkillsCompiler` can write the same body verbatim into Codex / Gemini
- * instruction files (AGENTS.md / GEMINI.md) without a cross-backend
- * import. The agent profile (`agent-assets/agent-profiles/routine-fetch-window.md`)
- * and the task-flow body still ship their operational rules — the system
- * prompt only sets the broad stance, and the SDK still loads the per-cwd
- * CLAUDE.md the SkillsCompiler materializes per session.
+ * `strictMcpConfig` is defense-in-depth on top of the `settingSources` drop:
+ * it shuts out any settings-file-sourced MCP server, while the daemon's own
+ * servers (including the in-process `aitne-observations` server) are passed
+ * programmatically via `options.mcpServers` (`composeMcpServers`) which
+ * `strictMcpConfig` does not touch. Typed `ReadonlySet<ProcessKey>` so a
+ * key rename in @aitne/shared lights up at the literal below.
  */
-// Typed as `ProcessKey` (not the inferred string literal) so that if
-// `ProcessKey` is ever narrowed in @aitne/shared/process-key.ts — e.g. the
-// pre-pass is renamed — this declaration is the compile error, not a
-// silently-dead branch in `buildSystemPrompt`.
-const FETCH_WINDOW_PROCESS_KEY = "routine.fetch_window";
+const USER_SCOPE_SHED_PROCESS_KEYS = new Set([
+    "routine.research_cluster_update",
+]);
 /**
- * Test-only surface: lets `claude-code-core.test.ts` exercise the
- * fetch_window prompt loader without reaching into module internals via
- * `as any` casts. Re-exports the shared loader (now hoisted to
- * `core/fetch-window-prompt-loader.ts`) so the existing test import path
- * keeps working after Phase 1.5's hoist.
+ * Test-only surface: lets `claude-code-core.test.ts` exercise the slim
+ * prompt loader without reaching into module internals via `as any` casts.
+ * Re-exports the shared loaders (hoisted to `core/slim-system-prompt-loader.ts`)
+ * so the existing fetch_window test import path keeps working.
  */
 export const _testInternals = {
     loadFetchWindowSystemPrompt,
@@ -129,9 +151,81 @@ export const _testInternals = {
  * question based on the CLI / SDK's own startup cost, not on
  * pattern-matching against one of the existing three.
  */
+// ── Partial-spend recovery (PREPASS_COST_REDUCTION_PLAN.md N1) ────────────
+//
+// The SDK populates authoritative usage/cost only on the terminal `result`
+// stream message. When the stream aborts before that message arrives —
+// the SDK's `max_budget_usd` kill, a wall-clock timeout, a transport
+// failure — the run's spend would otherwise be unrecoverable: the thrown
+// error carries no usage, and the dispatcher's post-hoc audit writer
+// (`recordPostHocBudgetSpend`) drops payload-less errors. The accumulator
+// below sums per-assistant-message usage during `consumeStream` so a
+// partial figure exists at throw time; `executeOnce` / `executeResumeOnce`
+// stamp the snapshot onto the propagating error via a symbol property,
+// and `classifyExecutionError` / `toBackendQuotaError` lift it onto the
+// classified `BackendQuotaError` / `BackendDecisiveFailure`.
+/** Carrier property for the partial-spend snapshot on a propagating error. */
+const PARTIAL_SPEND_PROP = Symbol("aitne.claudePartialSpend");
+function createPartialUsageAccumulator() {
+    return {
+        usage: {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheCreationInputTokens: 0,
+            cacheReadInputTokens: 0,
+        },
+        numTurns: 0,
+    };
+}
+/**
+ * Fold one SDK assistant message's API-call usage into the accumulator.
+ * The SDK reports usage per API call on each assistant message; summing
+ * them approximates the run's total the same way the terminal result
+ * message would have.
+ */
+function recordAssistantUsage(acc, rawUsage) {
+    acc.numTurns += 1;
+    if (typeof rawUsage !== "object" || rawUsage === null)
+        return;
+    const u = rawUsage;
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+    acc.usage.inputTokens += num(u.input_tokens);
+    acc.usage.outputTokens += num(u.output_tokens);
+    acc.usage.cacheCreationInputTokens += num(u.cache_creation_input_tokens);
+    acc.usage.cacheReadInputTokens += num(u.cache_read_input_tokens);
+}
+function accumulatorSawUsage(acc) {
+    return (acc.usage.inputTokens > 0
+        || acc.usage.outputTokens > 0
+        || acc.usage.cacheCreationInputTokens > 0
+        || acc.usage.cacheReadInputTokens > 0);
+}
+function attachPartialSpend(error, spend) {
+    if (typeof error !== "object" || error === null)
+        return;
+    try {
+        Object.defineProperty(error, PARTIAL_SPEND_PROP, {
+            value: spend,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    catch {
+        // Frozen/sealed error object — losing the snapshot is acceptable;
+        // the row simply stays payload-less like before N1.
+    }
+}
+/** Visible for testing. */
+export function getAttachedPartialSpend(error) {
+    if (typeof error !== "object" || error === null)
+        return null;
+    const value = error[PARTIAL_SPEND_PROP];
+    return value ? value : null;
+}
 export class ClaudeCodeCore {
     config;
     writeTracker;
+    priceFetcher;
     backendId = "claude";
     static RETRY_DELAY_MS = 5 * 60 * 1000;
     static MAX_RETRIES = 1;
@@ -176,12 +270,26 @@ export class ClaudeCodeCore {
      * Shared AgentWriteTracker. When present, the Write/Edit PreToolUse hook
      * pre-marks vault-scoped writes so the ObsidianWatcher attributes the
      * resulting chokidar event to `actor='agent'` instead of `'user'`. Without
-     * this wiring, the hourly_check dispatcher would re-discover the agent's
+     * this wiring, the activity_scan dispatcher would re-discover the agent's
      * own vault writes every cycle and loop.
      */
-    writeTracker) {
+    writeTracker, 
+    /**
+     * PREPASS_COST_REDUCTION_PLAN.md N1 — used only to estimate the
+     * dollar figure of a partial spend snapshot when the SDK stream
+     * terminates abnormally (budget abort, timeout, transport failure).
+     * Success-path cost still comes from the SDK's own metering.
+     * Defaulted like the CLI cores' fetchers so bootstrap stays
+     * unchanged; guarded on `dataDir` because several unit tests
+     * construct the core with a partial config — those fall back to
+     * cap-floor-only estimation in `stampPartialSpend`.
+     */
+    priceFetcher = config.dataDir
+        ? new PriceFetcher(config.dataDir)
+        : undefined) {
         this.config = config;
         this.writeTracker = writeTracker;
+        this.priceFetcher = priceFetcher;
         this.warnOnMissingCriticalTools();
         this.cliPathCache = new CliPathCache("claude");
     }
@@ -332,26 +440,27 @@ export class ClaudeCodeCore {
         };
     }
     buildSystemPrompt(processKey) {
-        // docs/design/appendices/fetch-window-cost-reduction.md Phase 1 — `routine.fetch_window`
-        // pays the full preset prompt cost on every fan-out (~30 K cache_create
-        // tokens per session, see §1.2). The fetcher does not use Skill / Read /
-        // Write / Edit / Glob / Grep / Task / WebFetch / WebSearch / NotebookEdit
-        // / EnterPlanMode / ScheduleWakeup, the memory-system documentation, or
-        // the skills index — every byte of preset for those is wasted cache
-        // creation amortized over only ~3 turns. Replace the preset with a
-        // small custom string for this one process key. Operational rules
-        // (acquisition-plan iteration, observations POST contract, hard
-        // guardrails) still ship via the per-cwd CLAUDE.md the SkillsCompiler
-        // materializes from `agent-assets/agent-profiles/routine-fetch-window.md`
-        // and the task-flow body in `agent-assets/task-flows/routine.fetch_window.md`.
+        // Slim process keys (RESEARCH_CLUSTER_COST_FIX_PLAN.md F4 generalizes the
+        // fetch-window-cost-reduction.md Phase 1 precedent) pay the full preset
+        // prompt cost on every dispatch (~30 K cache_create tokens per session).
+        // These keys never use Skill / Read / Write / Edit / Glob / Grep / Task /
+        // WebFetch / WebSearch / NotebookEdit / EnterPlanMode / ScheduleWakeup,
+        // the memory-system documentation, or the skills index — every byte of
+        // preset for those is wasted cache creation amortized over only a few
+        // turns. Replace the preset with a small custom string sourced from the
+        // shared registry (`core/slim-system-prompt-loader.ts`); the SkillsCompiler
+        // materializes the byte-identical body into AGENTS.md / GEMINI.md for CLI
+        // parity. Operational rules still ship via the per-cwd CLAUDE.md profile +
+        // task-flow body the SkillsCompiler materializes per session.
         //
         // Trade-off — `excludeDynamicSections` is a no-op when systemPrompt is
         // a string (per SDK 0.2.98 docs: "Has no effect when systemPrompt is a
         // string (custom prompt)"), but the entire string IS byte-stable
         // across sessions, so the prompt-cache prefix is naturally cacheable
         // on the same axis without needing the flag.
-        if (processKey === FETCH_WINDOW_PROCESS_KEY) {
-            return loadFetchWindowSystemPrompt();
+        const slimSystemPrompt = loadSlimSystemPrompt(processKey);
+        if (slimSystemPrompt !== null) {
+            return slimSystemPrompt;
         }
         // Character is NOT appended here — Phase 2 of the Character feature
         // (see docs/design/15-character.md §15.4.3) moved the injection into
@@ -383,6 +492,33 @@ export class ClaudeCodeCore {
             excludeDynamicSections: true,
         };
     }
+    /**
+     * Resolve the SDK `settingSources` for a session. Returns `["project"]`
+     * for `USER_SCOPE_SHED_PROCESS_KEYS` (dropping the daemon user's `~/.claude`
+     * scope — plugin SKILL.md tree + claude.ai connector schemas — from the
+     * prompt-cache prefix) and the default `["user", "project"]` otherwise. A
+     * fresh array per call: the SDK option type is mutable `SettingSource[]`.
+     *
+     * Applied at both `query()` sites (`executeOnce`, `executeResumeOnce`).
+     * Resume carries no `processKey` (it is always a reactive DM continuation,
+     * never a slim routine), so it always resolves to the full default.
+     */
+    resolveSettingSources(processKey) {
+        if (processKey !== undefined && USER_SCOPE_SHED_PROCESS_KEYS.has(processKey)) {
+            return ["project"];
+        }
+        return [...CLAUDE_SDK_SETTING_SOURCES];
+    }
+    /**
+     * Whether to force `strictMcpConfig` for a session — true exactly for the
+     * `USER_SCOPE_SHED_PROCESS_KEYS`, as defense-in-depth on top of the
+     * `settingSources` drop (shuts out settings-file-sourced MCP servers; the
+     * daemon's own servers are passed programmatically and unaffected). Resume
+     * carries no `processKey`, so it never qualifies.
+     */
+    resolveStrictMcpConfig(processKey) {
+        return processKey !== undefined && USER_SCOPE_SHED_PROCESS_KEYS.has(processKey);
+    }
     /**
      * Expand CLI-style aliases ("opus", "sonnet") to their current canonical
      * API IDs. Unrecognised strings pass through unchanged so custom or
@@ -452,6 +588,9 @@ export class ClaudeCodeCore {
             nativeToolCount: nativeTools.length,
             sessionDeniedToolCount: sessionDeniedTools.length,
         }, "Agent execute started");
+        // Declared outside the try so the catch can stamp a partial-spend
+        // snapshot onto the propagating error (PREPASS_COST_REDUCTION_PLAN.md N1).
+        const partialUsage = createPartialUsageAccumulator();
         try {
             const allowMode = this.config.claudeExecutionPermissionMode === "allow";
             // P22 §3.4 step 4 — when the dispatcher pins a per-execute
@@ -462,7 +601,7 @@ export class ClaudeCodeCore {
             // ALWAYS_DISALLOWED_TOOLS layer still applies.
             //
             // An EMPTY array (`[]`) is a deliberate "no tools" clamp — used by
-            // `routine.hourly_check.triage` (JSON-only triage spawn) and Stage B
+            // `routine.activity_scan.triage` (JSON-only triage spawn) and Stage B
             // of the morning-routine pipeline (daily-journal-daemon-write.md §3
             // corollary). A pre-2026-05-24 version of this gate required
             // `length > 0`, which silently fell through to the default `dontAsk`
@@ -540,7 +679,14 @@ export class ClaudeCodeCore {
                         const mcpServers = this.composeMcpServers(mcp.claudeMcpServers);
                         return mcpServers ? { mcpServers } : {};
                     })(),
-                    settingSources: [...CLAUDE_SDK_SETTING_SOURCES],
+                    // RESEARCH_CLUSTER_COST_FIX_PLAN.md F4 — `USER_SCOPE_SHED_PROCESS_KEYS`
+                    // drop to `["project"]` (+ `strictMcpConfig`) to shed the daemon
+                    // user's `~/.claude` scope from the prompt-cache prefix; all other
+                    // keys keep `["user", "project"]`.
+                    settingSources: this.resolveSettingSources(params.processKey),
+                    ...(this.resolveStrictMcpConfig(params.processKey)
+                        ? { strictMcpConfig: true }
+                        : {}),
                     // When the per-execute clamp is active we already swapped Allow
                     // mode back to strict `dontAsk` + an explicit allowedTools list.
                     // The PreToolUse hooks must follow the same posture: keeping
@@ -553,11 +699,12 @@ export class ClaudeCodeCore {
                     ...this.buildAdvisorSettings(),
                 },
             });
-            const result = await this.withTimeout(stream, () => this.consumeStream(stream, actualModelId, startMs, streamCallbacks, event.type), this.config.executeTimeoutMinutes);
+            const result = await this.withTimeout(stream, () => this.consumeStream(stream, actualModelId, startMs, streamCallbacks, event.type, partialUsage), this.config.executeTimeoutMinutes);
             logger.info({ eventType: event.type, model: actualModelId, durationMs: result.durationMs, costUsd: result.costUsd, numTurns: result.numTurns, isError: result.isError }, "Agent execute completed");
             return result;
         }
         catch (err) {
+            this.stampPartialSpend(err, partialUsage, actualModelId, startMs, maxBudgetUsd);
             logger.error({ err, eventType: event.type, model: actualModelId, durationMs: Date.now() - startMs }, "Agent execute failed");
             throw err;
         }
@@ -646,13 +793,24 @@ export class ClaudeCodeCore {
                     const mcpServers = this.composeMcpServers(mcp.claudeMcpServers);
                     return mcpServers ? { mcpServers } : {};
                 })(),
-                settingSources: [...CLAUDE_SDK_SETTING_SOURCES],
+                // Resume is always a reactive DM continuation (no `processKey`), so
+                // `resolveSettingSources()` returns the full `["user", "project"]`;
+                // routed through the helper for a single source of truth with the
+                // execute path (RESEARCH_CLUSTER_COST_FIX_PLAN.md F4).
+                settingSources: this.resolveSettingSources(),
                 hooks: this.getSecurityHooks(allowMode),
                 includePartialMessages: !!streamCallbacks,
                 ...this.buildAdvisorSettings(),
             },
         });
-        return await this.withTimeout(stream, () => this.consumeStream(stream, actualModelId, startMs, streamCallbacks, "message.received"), this.config.executeTimeoutMinutes);
+        const partialUsage = createPartialUsageAccumulator();
+        try {
+            return await this.withTimeout(stream, () => this.consumeStream(stream, actualModelId, startMs, streamCallbacks, "message.received", partialUsage), this.config.executeTimeoutMinutes);
+        }
+        catch (err) {
+            this.stampPartialSpend(err, partialUsage, actualModelId, startMs, maxBudgetUsd);
+            throw err;
+        }
     }
     async runWithRetry(fn, context) {
         let lastError;
@@ -700,6 +858,61 @@ export class ClaudeCodeCore {
         }
         return ClaudeCodeCore.NETWORK_ERROR_MESSAGE_PATTERN.test(this.getErrorMessage(error));
     }
+    /**
+     * PREPASS_COST_REDUCTION_PLAN.md N1 — build a spend snapshot from the
+     * stream's partial-usage accumulator and stamp it onto the propagating
+     * error so `classifyExecutionError` / `toBackendQuotaError` (which only
+     * see the error object) can lift it onto the classified failure.
+     *
+     * Dollar figure: estimated from the accumulated tokens via the shared
+     * price fetcher. For the SDK's `max_budget_usd` abort the figure is
+     * additionally floored at the cap — the SDK's own metering crossed it,
+     * so any lower estimate (e.g. usage observed only for the first few
+     * messages) would under-report what was actually billed. `costSource`
+     * is `"sdk_partial"` to mark the figure as a partial reconstruction.
+     *
+     * No-op when nothing recordable exists: no usage observed AND the
+     * error is not a budget abort with a known cap.
+     */
+    stampPartialSpend(error, acc, modelId, startMs, maxBudgetUsd) {
+        try {
+            if (error instanceof BackendQuotaError
+                || error instanceof BackendDecisiveFailure) {
+                // Already classified upstream (carries its own spend or lack of
+                // one) — re-stamping could only disagree with the classified
+                // payload.
+                return;
+            }
+            const isBudgetAbort = isClaudeCodeMaxBudgetError(error);
+            const sawUsage = accumulatorSawUsage(acc);
+            if (!sawUsage && !(isBudgetAbort && typeof maxBudgetUsd === "number")) {
+                return;
+            }
+            const estimated = sawUsage && this.priceFetcher
+                ? this.priceFetcher.estimateUsageCost({
+                    backendId: this.backendId,
+                    modelId,
+                    usage: acc.usage,
+                    fallbackModel: findRegisteredModel(this.backendId, modelId),
+                }).costUsd
+                : 0;
+            const costUsd = isBudgetAbort
+                ? Math.max(estimated, maxBudgetUsd ?? 0)
+                : estimated;
+            attachPartialSpend(error, {
+                usage: { ...acc.usage },
+                costUsd,
+                modelId,
+                numTurns: acc.numTurns,
+                durationMs: Date.now() - startMs,
+                costSource: "sdk_partial",
+            });
+        }
+        catch (stampErr) {
+            // Best-effort telemetry — never mask the original failure.
+            logger.warn({ err: stampErr, modelId }, "Failed to stamp partial spend onto Claude execution error");
+        }
+    }
     /** Visible for testing. */
     classifyExecutionError(error) {
         if (error instanceof BackendQuotaError ||
@@ -710,23 +923,28 @@ export class ClaudeCodeCore {
         if (quotaError) {
             return quotaError;
         }
+        const partialSpend = getAttachedPartialSpend(error);
         if (error instanceof AgentTimeoutError) {
-            return new BackendDecisiveFailure(this.backendId, "timeout", error);
+            return new BackendDecisiveFailure(this.backendId, "timeout", error, partialSpend);
         }
         if (this.isAuthError(error)) {
-            return new BackendDecisiveFailure(this.backendId, "auth", error);
+            return new BackendDecisiveFailure(this.backendId, "auth", error, partialSpend);
         }
-        return new BackendDecisiveFailure(this.backendId, "other_non_retryable", error);
+        return new BackendDecisiveFailure(this.backendId, "other_non_retryable", error, partialSpend);
     }
     toBackendQuotaError(error) {
         if (isClaudeCodeMaxBudgetError(error)) {
-            return new BackendQuotaError(this.backendId, "max_budget_usd", null, this.getErrorMessage(error));
+            // The partial-spend snapshot stamped by `stampPartialSpend` is the
+            // only usage figure that exists for a budget abort — the SDK kills
+            // the stream before the terminal `result` message
+            // (PREPASS_COST_REDUCTION_PLAN.md N1).
+            return new BackendQuotaError(this.backendId, "max_budget_usd", null, this.getErrorMessage(error), getAttachedPartialSpend(error));
         }
         if (!isClaudeCodeQuotaError(error)) {
             return null;
         }
         const hint = extractClaudeCodeQuotaResetHint(error);
-        return new BackendQuotaError(this.backendId, this.getErrorCode(error) ?? "rate_limited", hint ? this.toBackendQuotaResetHint(hint) : null, this.getErrorMessage(error));
+        return new BackendQuotaError(this.backendId, this.getErrorCode(error) ?? "rate_limited", hint ? this.toBackendQuotaResetHint(hint) : null, this.getErrorMessage(error), getAttachedPartialSpend(error));
     }
     toBackendQuotaResetHint(hint) {
         return {
@@ -914,7 +1132,14 @@ export class ClaudeCodeCore {
         const models = [...configuredModels, ...getModelsForBackend(this.backendId)];
         return models.filter((model, index, list) => list.findIndex((candidate) => candidate.modelId === model.modelId) === index);
     }
-    async consumeStream(stream, model, startMs, streamCallbacks, eventType) {
+    async consumeStream(stream, model, startMs, streamCallbacks, eventType, 
+    /**
+     * PREPASS_COST_REDUCTION_PLAN.md N1 — live per-message usage sink the
+     * caller keeps a reference to. When the stream throws before the
+     * terminal `result` message, the caller stamps a spend snapshot built
+     * from this accumulator onto the propagating error.
+     */
+    partialUsage) {
         let output = "";
         let streamedOutput = "";
         let sessionId = null;
@@ -966,6 +1191,9 @@ export class ClaudeCodeCore {
                     // Track Bash tool_use blocks that hit the context API + server-side
                     // advisor tool invocations.
                     const assistantMsg = message;
+                    if (partialUsage) {
+                        recordAssistantUsage(partialUsage, assistantMsg.message?.usage);
+                    }
                     const blocks = assistantMsg.message?.content;
                     if (Array.isArray(blocks)) {
                         for (const block of blocks) {

package/dist/core/backends/cli-quota-guards.d.ts

@@ -25,7 +25,7 @@
  *    message must update BOTH detectors.
  * Forcing those shapes through this module would be over-abstraction.
  */
-import type { BackendId } from "@aitne/shared";
+import type { BackendId, BackendUsage } from "@aitne/shared";
 import { BackendDecisiveFailure, BackendQuotaError, type BackendQuotaSpend } from "../agent-core.js";
 import type { PriceFetcher } from "./price-fetcher.js";
 /**
@@ -66,6 +66,24 @@ export declare function assertPromptCostWithinMaxBudget(params: {
     modelId: string;
     priceFetcher: PriceFetcher;
 }): void;
+/**
+ * PREPASS_COST_REDUCTION_PLAN.md N1 — recover a best-effort spend payload
+ * for a CLI run that failed after the provider already billed tokens.
+ * Returns `null` when the JSONL stream never surfaced usage (failure
+ * before the first `turn.completed` / stats event), so callers can pass
+ * the result straight to `classifyCliFailure` without an empty-usage
+ * guard. The dollar figure is a price-fetcher estimate from the observed
+ * token totals — same path the success branch uses — so a failed and a
+ * successful run with identical usage report identical cost.
+ */
+export declare function recoverCliFailureSpend(params: {
+    backendId: BackendId;
+    priceFetcher: PriceFetcher;
+    usage: BackendUsage;
+    modelId: string;
+    numTurns: number;
+    durationMs: number;
+}): BackendQuotaSpend | null;
 /**
  * Optional pre-auth classifier — given a failure `message`, returns a
  * `BackendDecisiveFailure` when it owns the message, else `null` to fall
@@ -97,4 +115,14 @@ export declare function classifyCliFailure(params: {
     rateLimitPattern: RegExp;
     authPattern: RegExp;
     extraClassifier?: CliFailureExtraClassifier;
+    /**
+     * PREPASS_COST_REDUCTION_PLAN.md N1 — best-effort spend recovered from
+     * the failed run's JSONL stream (usage totals + price-fetcher
+     * estimate). Attached to every error constructed here so the
+     * dispatcher's post-hoc audit writer can record what the provider
+     * already billed for a turn that produced no `AgentResult`. Errors
+     * returned by `extraClassifier` keep their own (usually absent) spend
+     * — the classifier owns the full construction of those.
+     */
+    spend?: BackendQuotaSpend | null;
 }): BackendQuotaError | BackendDecisiveFailure;

package/dist/core/backends/cli-quota-guards.js

@@ -53,6 +53,40 @@ export function assertPromptCostWithinMaxBudget(params) {
     }
     throw new BackendQuotaError(backendId, "max_budget_usd", null, `${label} estimated prompt cost $${costUsd.toFixed(4)} exceeded the per-turn budget limit $${maxBudgetUsd.toFixed(2)} for ${modelId}.`);
 }
+/**
+ * PREPASS_COST_REDUCTION_PLAN.md N1 — recover a best-effort spend payload
+ * for a CLI run that failed after the provider already billed tokens.
+ * Returns `null` when the JSONL stream never surfaced usage (failure
+ * before the first `turn.completed` / stats event), so callers can pass
+ * the result straight to `classifyCliFailure` without an empty-usage
+ * guard. The dollar figure is a price-fetcher estimate from the observed
+ * token totals — same path the success branch uses — so a failed and a
+ * successful run with identical usage report identical cost.
+ */
+export function recoverCliFailureSpend(params) {
+    const { backendId, priceFetcher, usage, modelId, numTurns, durationMs } = params;
+    const sawUsage = usage.inputTokens > 0
+        || usage.outputTokens > 0
+        || usage.cacheCreationInputTokens > 0
+        || usage.cacheReadInputTokens > 0;
+    if (!sawUsage) {
+        return null;
+    }
+    const { costUsd, costSource } = priceFetcher.estimateUsageCost({
+        backendId,
+        modelId,
+        usage,
+        fallbackModel: findRegisteredModel(backendId, modelId),
+    });
+    return {
+        usage,
+        costUsd,
+        modelId,
+        numTurns: numTurns || 1,
+        durationMs,
+        costSource,
+    };
+}
 /**
  * Shared failure-classification skeleton for the CLI backends. Maps a raw
  * failure `message` to the dispatcher's failover signals in a fixed order:
@@ -72,24 +106,25 @@ export function assertPromptCostWithinMaxBudget(params) {
  */
 export function classifyCliFailure(params) {
     const { backendId, message, rateLimitPattern, authPattern, extraClassifier } = params;
+    const spend = params.spend ?? null;
     if (isMaxBudgetMessage(message)) {
-        return new BackendQuotaError(backendId, "max_budget_usd", null, message);
+        return new BackendQuotaError(backendId, "max_budget_usd", null, message, spend);
     }
     if (rateLimitPattern.test(message)) {
         // Best-effort reset-time extraction so the dashboard can surface
         // "quota resets at HH:MM (TZ)" instead of a bare "rate_limited" tag.
         // Falls through to null when no reset-time pattern matches.
-        return new BackendQuotaError(backendId, "rate_limited", extractGenericQuotaResetHint(message), message);
+        return new BackendQuotaError(backendId, "rate_limited", extractGenericQuotaResetHint(message), message, spend);
     }
     const extra = extraClassifier?.(message, backendId);
     if (extra) {
         return extra;
     }
     if (authPattern.test(message)) {
-        return new BackendDecisiveFailure(backendId, "auth", new Error(message));
+        return new BackendDecisiveFailure(backendId, "auth", new Error(message), spend);
     }
     if (/timed out|timeout/i.test(message)) {
-        return new BackendDecisiveFailure(backendId, "timeout", new Error(message));
+        return new BackendDecisiveFailure(backendId, "timeout", new Error(message), spend);
     }
-    return new BackendDecisiveFailure(backendId, "other_non_retryable", new Error(message));
+    return new BackendDecisiveFailure(backendId, "other_non_retryable", new Error(message), spend);
 }

package/dist/core/backends/codex-core.d.ts

@@ -63,6 +63,12 @@ export declare class CodexCore implements IAgentCore {
     private buildArgs;
     private pickSummaryModel;
     private classifyFailure;
+    /**
+     * PREPASS_COST_REDUCTION_PLAN.md N1 — spend recovered from the failed
+     * run's JSONL usage so terminal errors carry what the provider already
+     * billed. Null when the stream never reported usage.
+     */
+    private recoverFailureSpend;
     private assertWithinMaxBudget;
     private assertPromptWithinMaxBudget;
     /**