@oar-sh/oar 0.9.19 → 0.9.21

package/server/claude-worker/claude-turn-publisher.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import {
   CLAUDE_LIVE_FLAG_SETTINGS_CODE,
   CLAUDE_LIVE_FLAG_SETTINGS_GUIDANCE,
@@ -6,17 +7,12 @@ import {
   claudeFailureGuidance,
 } from './claude-turn-failure.mjs';
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
+import { PLAN_BOARD_ACTIONS } from '../../shared/plan-board-actions.mjs';
 import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
 import { buildSteerSettleFailure, steerSettleFailureText } from '../../shared/steer-settle-failure.mjs';
 import { buildUsageLimitFailure } from '../../shared/claude-usage-limit.mjs';
 import { WORKING_DIRECTORY_MISSING_CODE, isWorkingDirectoryMissingError } from '../../shared/worker-runtime/working-directory.mjs';
-import { claudeBillingTotals, claudeSearchTotals, claudeToolRequests, claudeUsageTotals } from './claude-usage-totals.mjs';
-
-const PLAN_BOARD_ACTIONS = [
-  { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
-  { id: 'interactive', label: 'Stop here and prompt myself', mode: 'agent' },
-  { id: 'exit_only', label: 'Stop here', mode: 'agent' },
-];
+import { claudeBillingTotals, claudeSearchTotals, claudeTokenTotals, claudeToolRequests, claudeUsageTotals } from './claude-usage-totals.mjs';
 
 /**
  * The attempt-fencing echo for a row's write bodies. Every publish that names
@@ -96,6 +92,13 @@ export function createClaudeTurnPublisher({
   // `billingKind` is the worker's kind.
   billingUsageRoute = null,
   billingKind = null,
+  // The token booking (POST /api/turn-token-usage): the provider a
+  // turn's tokens are reported under (the worker's kind: 'claude',
+  // 'claude-api', 'deepseek'), null for none. `turnTokenCost(entry, at)`
+  // prices a model's share of a turn where Claude Code's own estimate does
+  // not fit (DeepSeek: `{ costUsd, costSource }`, costUsd null when unknown).
+  turnTokenProvider = null,
+  turnTokenCost = null,
 } = {}) {
   /** `{ code, stableCode }` of a failure code, in the backend's namespace. */
   function failureCodes(code) {
@@ -230,6 +233,9 @@ export function createClaudeTurnPublisher({
    * Advisory: a failure here must not disturb the turn's response.
    */
   async function publishPlanUsage({ message, state, sdkSessionId, runId = '', resumedSessionId = '' }) {
+    // Fire-and-forget: the token post never holds the reply (the counting
+    // itself runs at once, before the next result can arrive).
+    if (turnTokenProvider) void publishTurnTokens({ message, state, runId, resumedSessionId });
     if (billingUsageRoute) await publishBillingUsage({ message, state, sdkSessionId, runId, resumedSessionId });
     if (usageRoute) {
       await publishBackendUsage({ message, state, sdkSessionId, runId, resumedSessionId });
@@ -252,6 +258,20 @@ export function createClaudeTurnPublisher({
     });
   }
 
+  // Three trackers below measure a turn from the CLI's results, one per
+  // booking, and mirror each other's rules: `run` / runningCounts (DeepSeek's
+  // card), `billingRun` / billingCounts (the Claude API booking) and
+  // `tokenRun` / turnCounts (the token booking). Each keys on the
+  // process (`runId`) and the CLI session id, so a `/clear` starts over;
+  // takes a fresh process's `modelUsage` growth over the last result's, but
+  // a resumed process's first result (and a result without `modelUsage`) as
+  // its turn `usage` alone, the main loop, and a result without `modelUsage`
+  // raises the baseline by that `usage`, so the next result's growth does
+  // not count it again; lets the baseline only rise, so a late result of an
+  // older turn books nothing twice; and counts a turn state once. They differ only in what they keep: hits and misses (cache
+  // writes inside) for the first two, the four token kinds apart for the
+  // third. A change to one rule belongs in all three.
+
   // The CLI process's own token totals and web search and fetch counts per
   // model, counted from zero for each process (`runId`) and CLI session id
   // (a `/clear` changes it and starts the CLI's totals over). `lastSession`
@@ -475,7 +495,10 @@ export function createClaudeTurnPublisher({
         }));
       }
       // The baseline only rises: a late result of an older turn below it
-      // must not make the next one count twice.
+      // must not make the next one count twice. A result without
+      // `modelUsage` grew the CLI's running totals by its `usage`, as `run`
+      // has it: the baseline grows by it too, so the next result's growth
+      // does not book that turn again.
       if (hasModelUsage) {
         for (const entry of session) {
           const last = billingRun.lastSession.get(entry.model) || { hitTokens: 0, missTokens: 0, outputTokens: 0, costUsd: 0 };
@@ -486,6 +509,16 @@ export function createClaudeTurnPublisher({
             costUsd: Math.max(last.costUsd, entry.costUsd),
           });
         }
+      } else {
+        for (const entry of claudeBillingTotals(null, { usage: result.usage, model })) {
+          const last = billingRun.lastSession.get(entry.model) || { hitTokens: 0, missTokens: 0, outputTokens: 0, costUsd: 0 };
+          billingRun.lastSession.set(entry.model, {
+            hitTokens: last.hitTokens + entry.hitTokens,
+            missTokens: last.missTokens + entry.missTokens,
+            outputTokens: last.outputTokens + entry.outputTokens,
+            costUsd: last.costUsd,
+          });
+        }
       }
       billingRun.results += 1;
     }
@@ -496,6 +529,128 @@ export function createClaudeTurnPublisher({
     };
   }
 
+  // The token booking's counts, measured like billingRun above,
+  // with the four token kinds apart, then summed per turn: a turn's results
+  // (a stopped turn's, the steered rows it folded in) post the turn's total
+  // so far under its id, which the relay keeps the larger of. A worker
+  // without a process id names one for its own life, so a requeued turn on
+  // a restarted worker is a second run, not the same row.
+  const tokenRun = { key: '', results: 0, lastSession: new Map() };
+  const tokenStates = new WeakSet();
+  const turnTokens = new Map();
+  const ownRunId = randomUUID();
+  const TOKEN_FIELDS = ['inputTokens', 'cacheWriteTokens', 'cacheReadTokens', 'outputTokens'];
+  const TURN_TOKENS_KEPT = 20;
+
+  function turnCounts(state, result, { turnId, runId, sessionId, resumedSessionId, modelKey }) {
+    const model = result.model || state.responseModel;
+    const key = `${runId}\n${sessionId}`;
+    if (tokenRun.key !== key) {
+      tokenRun.key = key;
+      tokenRun.results = 0;
+      tokenRun.lastSession = new Map();
+    }
+    // Per run and turn: a turn re-run by a new CLI process (after a crash)
+    // is a second row at the relay, holding that run's tokens only.
+    const turnKey = `${runId}\n${turnId}`;
+    let turn = turnTokens.get(turnKey);
+    if (!turn) {
+      turn = new Map();
+      turnTokens.set(turnKey, turn);
+      while (turnTokens.size > TURN_TOKENS_KEPT) turnTokens.delete(turnTokens.keys().next().value);
+    }
+    if (!tokenStates.has(state)) {
+      tokenStates.add(state);
+      const at = new Date().toISOString();
+      const hasModelUsage = Boolean(result.modelUsage) && typeof result.modelUsage === 'object' && !Array.isArray(result.modelUsage);
+      const resumed = tokenRun.results === 0 && Boolean(resumedSessionId) && sessionId === resumedSessionId;
+      const session = hasModelUsage ? claudeTokenTotals(result.modelUsage, modelKey) : [];
+      const grown = !hasModelUsage || resumed
+        ? claudeTokenTotals(null, { usage: result.usage, model, ...modelKey })
+        : session.map((entry) => {
+          const last = tokenRun.lastSession.get(entry.model);
+          const delta = { model: entry.model, costUnknown: entry.costUnknown };
+          for (const field of TOKEN_FIELDS) delta[field] = Math.max(0, entry[field] - (last?.[field] || 0));
+          delta.costUsd = entry.costUsd === null ? null : Math.max(0, entry.costUsd - (last?.costUsd || 0));
+          return delta;
+        });
+      for (const entry of grown) {
+        const priced = typeof turnTokenCost === 'function' ? turnTokenCost(entry, at) : null;
+        const costUsd = priced ? priced.costUsd : entry.costUsd;
+        const costSource = priced ? priced.costSource : (entry.costUsd === null ? null : 'claude-code');
+        const current = turn.get(entry.model) || {
+          model: entry.model, inputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0, outputTokens: 0, costUsd: null, costSource: null, costUnknown: false,
+        };
+        for (const field of TOKEN_FIELDS) current[field] += entry[field];
+        if (costUsd !== null && costUsd !== undefined) current.costUsd = (current.costUsd ?? 0) + costUsd;
+        current.costSource = current.costSource || costSource;
+        // A backend's own price wins over Claude Code's word on it (DeepSeek's
+        // models are unknown to Claude Code's table, yet OAR prices them).
+        const unknown = priced ? priced.costUsd === null || priced.costUsd === undefined : (entry.costUnknown || costUsd === null || costUsd === undefined);
+        current.costUnknown = current.costUnknown || unknown;
+        turn.set(entry.model, current);
+      }
+      // The baseline only rises: a late result of an older turn below it
+      // must not make the next one count twice. A result without
+      // `modelUsage` grew the CLI's running totals by its `usage`, as `run`
+      // has it: the baseline grows by it too.
+      for (const entry of session) {
+        const last = tokenRun.lastSession.get(entry.model) || {};
+        const next = { costUsd: Math.max(last.costUsd || 0, entry.costUsd || 0) };
+        for (const field of TOKEN_FIELDS) next[field] = Math.max(last[field] || 0, entry[field]);
+        tokenRun.lastSession.set(entry.model, next);
+      }
+      if (!hasModelUsage) {
+        for (const entry of grown) {
+          const last = tokenRun.lastSession.get(entry.model) || {};
+          const next = { costUsd: last.costUsd || 0 };
+          for (const field of TOKEN_FIELDS) next[field] = (last[field] || 0) + entry[field];
+          tokenRun.lastSession.set(entry.model, next);
+        }
+      }
+      tokenRun.results += 1;
+    }
+    return [...turn.values()]
+      .filter((entry) => TOKEN_FIELDS.some((field) => entry[field] > 0) || entry.costUsd > 0)
+      .map((entry) => ({ ...entry }));
+  }
+
+  /**
+   * Ship the turn's tokens per model to the token booking: the
+   * turn's total so far, under the turn's id and the process's run id.
+   * Reasoning is not reported apart by Claude, so it is left out (NULL).
+   * Advisory and fire-and-forget: it never throws and nothing waits on it.
+   */
+  async function publishTurnTokens({ message, state, runId = '', resumedSessionId = '' }) {
+    try {
+      const result = state.result;
+      const turnId = String(message?.id || '').trim();
+      if (!turnId || !result) return;
+      const sessionId = String(result.sessionId || '').trim();
+      const modelKey = typeof usageModelKey === 'function' ? { modelKey: usageModelKey } : {};
+      const run = String(runId || '') || ownRunId;
+      const models = turnCounts(state, result, {
+        turnId,
+        runId: run,
+        sessionId,
+        resumedSessionId: String(resumedSessionId || '').trim(),
+        modelKey,
+      });
+      if (!models.length) return;
+      await api('POST', '/api/turn-token-usage', {
+        conversationId: message.conversationId,
+        turnId,
+        runId: run,
+        provider: turnTokenProvider,
+        ...(sessionId ? { nativeSessionId: sessionId } : {}),
+        at: new Date().toISOString(),
+        models,
+      });
+    } catch (error) {
+      dbg('turn token publish failed', error?.message || String(error));
+    }
+  }
+
   /**
    * Ship the turn's counts to the Claude API booking: the process's own
    * running totals (`runCounts`) and the CLI's session totals

package/server/claude-worker/claude-usage-totals.mjs

@@ -159,3 +159,61 @@ export function claudeBillingTotals(modelUsage, { usage = null, model = '' } = {
   }
   return [...totals.values()].filter((entry) => entry.hitTokens + entry.missTokens + entry.outputTokens > 0 || entry.costUsd > 0);
 }
+
+/**
+ * The CLI's totals per model with the four token kinds apart, for the token
+ * booking (POST /api/turn-token-usage): `[{ model, inputTokens,
+ * cacheWriteTokens, cacheReadTokens, outputTokens, costUsd, costUnknown }]`.
+ * `inputTokens` is fresh input (Anthropic counts cache reads and writes
+ * apart). Read like claudeBillingTotals: `modelUsage` (running totals, with
+ * Claude Code's cost estimate) or `usage` alone under the turn's model (no
+ * cost: `costUsd` null). `modelKey` maps the CLI's model names to the
+ * relay's, as in claudeUsageTotals; the `[1m]` tier is dropped. Models with
+ * no tokens and no cost are left out.
+ */
+export function claudeTokenTotals(modelUsage, {
+  usage = null,
+  model = '',
+  modelKey = (value) => String(value ?? '').trim(),
+} = {}) {
+  const totals = new Map();
+  const add = (name, entry) => {
+    const key = String(modelKey(name) ?? '').trim().toLowerCase().replace(/\[1m\]$/, '');
+    if (!key) return;
+    const current = totals.get(key) || {
+      model: key, inputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0, outputTokens: 0, costUsd: null, costUnknown: false,
+    };
+    current.inputTokens += entry.inputTokens;
+    current.cacheWriteTokens += entry.cacheWriteTokens;
+    current.cacheReadTokens += entry.cacheReadTokens;
+    current.outputTokens += entry.outputTokens;
+    if (entry.costUsd !== null) current.costUsd = (current.costUsd ?? 0) + entry.costUsd;
+    current.costUnknown = current.costUnknown || entry.costUnknown;
+    totals.set(key, current);
+  };
+  if (modelUsage && typeof modelUsage === 'object' && !Array.isArray(modelUsage)) {
+    for (const [name, entry] of Object.entries(modelUsage)) {
+      if (!entry || typeof entry !== 'object') continue;
+      add(name, {
+        inputTokens: count(entry.inputTokens),
+        cacheWriteTokens: count(entry.cacheCreationInputTokens),
+        cacheReadTokens: count(entry.cacheReadInputTokens),
+        outputTokens: count(entry.outputTokens),
+        costUsd: costOf(entry.costUSD),
+        costUnknown: entry.costBasis === 'unknown',
+      });
+    }
+  } else if (usage && typeof usage === 'object') {
+    add(model, {
+      inputTokens: count(usage.input_tokens),
+      cacheWriteTokens: count(usage.cache_creation_input_tokens),
+      cacheReadTokens: count(usage.cache_read_input_tokens),
+      outputTokens: count(usage.output_tokens),
+      costUsd: null,
+      costUnknown: false,
+    });
+  }
+  return [...totals.values()].filter((entry) => (
+    entry.inputTokens + entry.cacheWriteTokens + entry.cacheReadTokens + entry.outputTokens > 0 || entry.costUsd > 0
+  ));
+}

package/server/copilot-worker/copilot-plan-board.mjs

@@ -14,16 +14,13 @@
 // shape of the final prose. Both paths are wired — the hook is primary, the
 // text heuristic is the fallback — which is the Claude worker's arrangement.
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
+import { PLAN_BOARD_ACTIONS } from '../../shared/plan-board-actions.mjs';
 
 /**
- * Kept identical across workers. `exit_only` dismisses; `autopilot` and
- * `interactive` queue a follow-up user message in the mapped relay mode.
+ * The one list every worker posts (shared/plan-board-actions.mjs): `exit_only`
+ * dismisses; the others queue a follow-up user message in the mapped mode.
  */
-export const PLAN_BOARD_ACTIONS = [
-  { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
-  { id: 'interactive', label: 'Stop here and prompt myself', mode: 'agent' },
-  { id: 'exit_only', label: 'Stop here', mode: 'agent' },
-];
+export { PLAN_BOARD_ACTIONS };
 
 /**
  * How many list-ish lines a final message needs before it is treated as a plan.

package/server/copilot-worker/copilot-sdk-event-normalizer.mjs

@@ -174,7 +174,7 @@ export function formatSubagentStats(data) {
  * figures keep the FIRST call's time-to-first-token (that is the number a user
  * experiences as "did it start answering").
  */
-function createUsageAccumulator() {
+function createUsageAccumulator({ debugTokenUsage = null } = {}) {
   const totals = {
     inputTokens: 0,
     outputTokens: 0,
@@ -195,8 +195,61 @@ function createUsageAccumulator() {
     isByok: null,
     quotaSnapshots: null,
   };
+  // The token booking's view (POST /api/turn-token-usage): the same calls,
+  // per model, the four token kinds apart. A field no call of the model
+  // carried stays null, so "not reported" is not booked as 0.
+  const byModel = new Map();
+  let compactionCalls = 0;
+  // A compaction's call as `session.compaction_complete` reports it, kept
+  // apart until the snapshot: it is booked only if no usage event of the
+  // compaction class came in the turn, before or after it.
+  const compactionTokens = new Map();
+  function addTokens(model, data, into = byModel) {
+    const key = String(model || '').trim();
+    const bucket = into.get(key) || {
+      model: key, inputTokens: null, outputTokens: null, cacheReadTokens: null, cacheWriteTokens: null, reasoningTokens: null,
+    };
+    const count = (value) => {
+      if (value === null || value === undefined || value === '') return null;
+      const n = Number(value);
+      return Number.isFinite(n) && n >= 0 ? n : null;
+    };
+    const cacheRead = count(data.cacheReadTokens);
+    const cacheWrite = count(data.cacheWriteTokens);
+    const prompt = count(data.inputTokens);
+    // Fresh input is the prompt count less the cache reads and writes, per
+    // call, floored at 0. Inferred, not verified: the bundled runtime reads
+    // OpenAI-style `prompt_tokens` with `prompt_tokens_details.cached_tokens`
+    // (and cache creation), where the prompt count includes the cache. A
+    // real-provider check at the merge gate confirms it, reading the raw
+    // counts that OAR_DEBUG_TOKEN_USAGE=1 logs.
+    const fresh = prompt === null ? null : Math.max(0, prompt - (cacheRead || 0) - (cacheWrite || 0));
+    for (const [field, value] of [
+      ['inputTokens', fresh],
+      ['outputTokens', count(data.outputTokens)],
+      ['cacheReadTokens', cacheRead],
+      ['cacheWriteTokens', cacheWrite],
+      ['reasoningTokens', count(data.reasoningTokens)],
+    ]) {
+      if (value !== null) bucket[field] = (bucket[field] ?? 0) + value;
+    }
+    into.set(key, bucket);
+  }
   function add(data, { allowModel = true } = {}) {
     if (!data || typeof data !== 'object') return;
+    if (typeof debugTokenUsage === 'function') {
+      debugTokenUsage({
+        model: data.model ?? null,
+        interactionType: data.interactionType ?? null,
+        inputTokens: data.inputTokens ?? null,
+        cacheReadTokens: data.cacheReadTokens ?? null,
+        cacheWriteTokens: data.cacheWriteTokens ?? null,
+        outputTokens: data.outputTokens ?? null,
+        reasoningTokens: data.reasoningTokens ?? null,
+      });
+    }
+    addTokens(data.model, data);
+    if (String(data.interactionType || '').trim() === 'conversation-compaction') compactionCalls += 1;
     totals.modelCalls += 1;
     if (!allowModel) totals.subagentModelCalls += 1;
     for (const key of ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens', 'cost']) {
@@ -222,13 +275,38 @@ function createUsageAccumulator() {
   }
   return {
     add,
+    /**
+     * A compaction's own model call, from `session.compaction_complete`'s
+     * `compactionTokensUsed`: booked unless the runtime reports it, before
+     * or after, as an `assistant.usage` of the compaction class.
+     */
+    addCompaction(tokensUsed, fallbackModel = '') {
+      if (!tokensUsed || typeof tokensUsed !== 'object') return;
+      addTokens(tokensUsed.model || fallbackModel, tokensUsed, compactionTokens);
+    },
     setQuotaSnapshots(snapshots) {
       if (snapshots && typeof snapshots === 'object' && Object.keys(snapshots).length) {
         totals.quotaSnapshots = snapshots;
       }
     },
     snapshot() {
-      return totals.modelCalls ? { ...totals } : (totals.quotaSnapshots ? { ...totals } : null);
+      // A call without a model id is the turn's main model's.
+      const models = [];
+      const buckets = [...byModel.values(), ...(compactionCalls > 0 ? [] : compactionTokens.values())];
+      for (const bucket of buckets) {
+        const model = bucket.model || totals.model;
+        const same = models.find((entry) => entry.model === model);
+        if (!same) {
+          models.push({ ...bucket, model });
+          continue;
+        }
+        for (const field of ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']) {
+          if (bucket[field] !== null) same[field] = (same[field] ?? 0) + bucket[field];
+        }
+      }
+      const tokenModels = models.filter((entry) => entry.model);
+      if (!totals.modelCalls && !totals.quotaSnapshots && !tokenModels.length) return null;
+      return { ...totals, models: tokenModels };
     },
   };
 }
@@ -242,6 +320,9 @@ export function createCopilotEventNormalizer({
   // The runner's answer to "is this agent id a background agent?" — shared
   // across turns, unlike this normalizer's own `backgroundRuns`.
   isBackgroundAgent = () => false,
+  // Called with the raw token counts of every model call (no ids), when the
+  // worker runs with OAR_DEBUG_TOKEN_USAGE=1.
+  debugTokenUsage = null,
 } = {}) {
   let sessionModel = '';
   let sessionId = '';
@@ -250,7 +331,7 @@ export function createCopilotEventNormalizer({
   let terminalEmitted = false;
   let contextUsage = null;
   let interactionId = '';
-  const usage = createUsageAccumulator();
+  const usage = createUsageAccumulator({ debugTokenUsage });
 
   // Assistant text is assembled per `messageId`. A tool-using request produces
   // several assistant messages (the first typically empty with `toolRequests`,
@@ -866,6 +947,8 @@ export function createCopilotEventNormalizer({
         return [activityAction('Compacting the conversation context…')];
       }
       case 'session.compaction_complete': {
+        // Its model call costs tokens too (booked with the turn it ran in).
+        usage.addCompaction(data.compactionTokensUsed, data.model || sessionModel);
         if (data.success === false) {
           const reason = String(data.error || '').trim();
           return [activityAction(truncate(reason ? `Context compaction failed: ${reason}` : 'Context compaction failed'))];

package/server/copilot-worker/copilot-sdk-session-process.mjs

@@ -523,6 +523,14 @@ export function createCopilotSdkSessionRunner({
   // The in-flight ingest POST, exposed only as a test seam. Never awaited by
   // the turn path — that is the entire point of it.
   let usagePostChain = Promise.resolve();
+  // The token booking's post (POST /api/turn-token-usage), a chain and a test
+  // seam like `usagePostChain`. Its run is the row's attempt (a row
+  // delivered again is another run of the turn); a row without one (an older
+  // relay) is booked under this process's own id, so a turn requeued onto a
+  // restarted worker is a second run of it, not the same row.
+  let tokenPostChain = Promise.resolve();
+  const postedTurnTokens = new WeakSet();
+  const tokenRunId = randomUUID();
   // The last catalog content this worker POSTed to `/api/models/snapshot`,
   // as a serialized signature. Identity of CONTENT, not of session: an idle
   // shutdown and resume onto the same catalog must not re-publish it.
@@ -701,6 +709,12 @@ export function createCopilotSdkSessionRunner({
   // card), so they hold the stall watchdog and the idle shutdown too — but
   // not steering: nobody is answering a card here.
   let pendingRelayToolCalls = 0;
+  // Deliveries `handlePendingPayload` is still working on. Most become (or
+  // steer into) `activeTurn` at once, but a steer that waits on the turn's
+  // send, its row or the relay context can find the turn gone and open its
+  // own afterwards: in that gap no turn exists, and the worker must still
+  // not read as replaceable (`releaseHold`).
+  let admittingDeliveries = 0;
   // `relay_tool` is registered only while this relay has paired remotes.
   // Asked once when the worker starts; a session build waits for that first
   // answer (it is async anyway), and every runtime stop asks again so the
@@ -1330,6 +1344,7 @@ export function createCopilotSdkSessionRunner({
       conversationId: message.conversationId,
       sdkSessionId,
       messageId: message.id,
+      attemptId: message.attemptId || null,
       model: result?.model || appliedModel() || defaultModel || '',
       usage,
       contextUsage,
@@ -1352,6 +1367,7 @@ export function createCopilotSdkSessionRunner({
       hasQuotaSnapshots: !!usage?.quotaSnapshots,
       cfiOverage: usage?.quotaSnapshots?.cfi_overage ?? null,
     }));
+    return lastTurnUsage;
   }
 
   /**
@@ -1372,9 +1388,10 @@ export function createCopilotSdkSessionRunner({
    * row still open — for as long as the socket stayed up. The result is unused
    * and the failure is already swallowed, so there was nothing to wait for.
    *
-   * BYOK sessions do not post at all: they spend the user's own OpenAI key
+   * BYOK sessions do not post here: they spend the user's own OpenAI key
    * rather than Copilot quota, and their usage events report `cost: 0`, so
-   * their numbers would only mislead on a card about the Copilot plan.
+   * their numbers would only mislead on a card about the Copilot plan. Their
+   * tokens still go to the token booking (postTurnTokens).
    */
   function postTurnUsage() {
     if (byokProvider || !lastTurnUsage || lastTurnUsage === postedTurnUsage) return;
@@ -1385,6 +1402,39 @@ export function createCopilotSdkSessionRunner({
       .catch((error) => { dbg('usage ingest failed', error?.message || String(error)); });
   }
 
+  /**
+   * Report a turn's own captured tokens per model to the token booking,
+   * from that turn's capture: a continuation that captured its
+   * usage meanwhile cannot take the turn's place. Fire-and-forget like the plan usage, but BYOK sessions post
+   * too, under their own billing (`byok-<provider type>`), which the relay
+   * keeps apart from the plan's. No cost: the plan bills in AI units, not
+   * dollars, and an own key's calls report 0.
+   */
+  function postTurnTokens(capture) {
+    if (!capture || postedTurnTokens.has(capture)) return;
+    postedTurnTokens.add(capture);
+    const models = (capture.usage?.models || []).map((entry) => ({
+      model: entry.model,
+      inputTokens: entry.inputTokens,
+      outputTokens: entry.outputTokens,
+      cacheWriteTokens: entry.cacheWriteTokens,
+      cacheReadTokens: entry.cacheReadTokens,
+      reasoningTokens: entry.reasoningTokens,
+    }));
+    if (!models.length || !capture.messageId) return;
+    const billing = byokProvider ? `byok-${String(byokProvider.type || 'openai').trim().toLowerCase()}` : '';
+    tokenPostChain = api('POST', '/api/turn-token-usage', {
+      conversationId: capture.conversationId,
+      turnId: capture.messageId,
+      runId: capture.attemptId || tokenRunId,
+      provider: 'github',
+      billing,
+      ...(sdkSessionId ? { nativeSessionId: sdkSessionId } : {}),
+      at: capture.capturedAt,
+      models,
+    }).catch((error) => { dbg('turn token ingest failed', error?.message || String(error)); });
+  }
+
   /**
    * Publish the session's model catalog to `/api/models/snapshot` (Phase 5A:
    * with the extension retired, worker snapshots and the server-side discovery
@@ -3161,7 +3211,14 @@ export function createCopilotSdkSessionRunner({
       model: '',
       // The runner's cross-turn knowledge of background agents rides in, so a
       // later turn's normalizer opens no lane for an agent spawned earlier.
-      normalizer: createNormalizerImpl({ isBackgroundAgent: (agentId) => agentDetails.has(agentId) }),
+      normalizer: createNormalizerImpl({
+        isBackgroundAgent: (agentId) => agentDetails.has(agentId),
+        // The raw counts of every model call, for checking the token rule
+        // against a real provider (counts only).
+        ...(String(env?.OAR_DEBUG_TOKEN_USAGE || '').trim() === '1'
+          ? { debugTokenUsage: (fields) => dbg('token usage', JSON.stringify(fields)) }
+          : {}),
+      }),
       result: null,
       failure: null,
       settled: false,
@@ -3730,7 +3787,7 @@ export function createCopilotSdkSessionRunner({
     const failure = turn.failure;
     // Capture only. The POST fires from driveTurn's `finally`, after the rows
     // have been published.
-    captureTurnUsage(turn.primaryEntry.message, result);
+    turn.usageCapture = captureTurnUsage(turn.primaryEntry.message, result) || null;
 
     const pending = turn.entries.filter((entry) => !entry.settled && entry.turn === turn);
     if (!pending.length) return;
@@ -4166,6 +4223,7 @@ export function createCopilotSdkSessionRunner({
       syncDeliveryReadiness();
       // The ingest is advisory, never awaited, and must never be able to
       // delay a reply that is already written.
+      postTurnTokens(turn.usageCapture);
       postTurnUsage();
     }
   }
@@ -4687,7 +4745,62 @@ export function createCopilotSdkSessionRunner({
     const canSteer = canAcceptSteering();
     const holdReason = turnActive && !canSteer ? steeringHoldReason(turn) : null;
     const messageId = String(turn?.currentOwner?.message?.id || turn?.message?.id || '').trim() || null;
-    return { turnActive, canSteer, holdReason, messageId, supported: true, cancellableIds: cancellableIds() };
+    // `releasable`: the relay may stop this worker and launch a fresh one now
+    // (its recycle after a deploy), the same fields the Claude worker sends.
+    const hold = releaseHold();
+    return {
+      turnActive,
+      canSteer,
+      holdReason,
+      messageId,
+      supported: true,
+      cancellableIds: cancellableIds(),
+      releasable: !hold,
+      releaseHold: hold || null,
+      // As the task panel counts them: with the registry it is the truth, and
+      // the event-scraped shell set would count its shells a second time.
+      backgroundTaskCount: sessionRpc.tasks ? backgroundTasks.size : backgroundShells.size(),
+      // The runtime process (the CLI child) is up: a client or a session
+      // handle exists until `stopRuntime` clears both. The relay's recycle
+      // replaces a stale worker only once it is releasable AND this is false;
+      // releasable with the runtime up is the idle window, left to the idle
+      // shutdown.
+      cliAlive: Boolean(client || session),
+    };
+  }
+
+  /**
+   * What keeps this worker from being replaced now ('' when nothing does):
+   * the idle shutdown's gates (`evaluateLifecycle`) and the runtime tree's
+   * busy check, named with the relay's hold words. Stopping the worker ends
+   * the runtime, and with it the turn, the card a human is answering, a
+   * compaction, and every background shell and agent.
+   *
+   *  - 'question': a question card or an ask-mode approval is open;
+   *  - 'compaction': the runtime is compacting the session;
+   *  - 'turn': a turn is running or still publishing its rows, a `relay_tool`
+   *    call is out, an image row is on the relay's image routes, or a
+   *    delivery is on its way in;
+   *  - 'background': a background shell or agent is live, a settled shell's
+   *    continuation is due (`continuationGraceMs`), a registry read is due
+   *    or under way, or the task registry has failed to answer: in the last
+   *    two "nothing is running" is not known (`backgroundWorkHoldsRuntime`
+   *    holds the runtime on the same grounds).
+   */
+  function releaseHold() {
+    if (pendingHumanRequests > 0) return 'question';
+    if (isCompacting()) return 'compaction';
+    if (
+      activeTurn || publishingTurns.size > 0 || pendingRelayToolCalls > 0
+      || directImageMessages.size > 0 || admittingDeliveries > 0
+    ) return 'turn';
+    if (backgroundShells.size() > 0 || backgroundTasks.size > 0) return 'background';
+    if (continuationDueSince && Date.now() - continuationDueSince < continuationGraceMs) return 'background';
+    // A read of the registry that is debounced, queued or on its way may
+    // still find a live agent or shell the last answer did not have.
+    if (sessionRpc.tasks && (taskRefreshTimer || taskRefreshQueued > 0 || taskRefreshInFlight)) return 'background';
+    if (sessionRpc.tasks && taskRefreshFailures > 0 && taskRefreshFailures < MAX_TASK_REFRESH_FAILURES) return 'background';
+    return '';
   }
 
   /**
@@ -4831,6 +4944,18 @@ export function createCopilotSdkSessionRunner({
   }
 
   async function handlePendingPayload(pending) {
+    // A payload without a message is refused at once, as it always was: it
+    // admits nothing.
+    if (!pending?.message) return false;
+    admittingDeliveries += 1;
+    try {
+      return await admitPendingPayload(pending);
+    } finally {
+      admittingDeliveries -= 1;
+    }
+  }
+
+  async function admitPendingPayload(pending) {
     const message = pending?.message || null;
     if (!message) return false;
     // An image model is no chat model: its row goes to the relay's image
@@ -5024,6 +5149,7 @@ export function createCopilotSdkSessionRunner({
     // never awaits this, which is what keeps a slow relay from holding a
     // finished reply.
     whenUsagePosted: () => usagePostChain,
+    whenTokensPosted: () => tokenPostChain,
     // The in-flight model-catalog snapshot POST — the same kind of seam.
     whenModelSnapshotPosted: () => modelSnapshotChain,
     // The in-flight queued-lane read — same kind of seam.