@oar-sh/oar 0.9.19 → 0.9.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.19",
+  "version": "0.9.21",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "!server/README.md",
     "!server/data/",
     "!server/logs/",
+    "!server/backups/",
     "!server/config.json",
     "!server/uploads/",
     "server/uploads/README.md",
@@ -43,8 +44,9 @@
     "preinstall": "node server/services/package-data-rescue-preinstall.mjs",
     "start": "node server/server.js",
     "copilot:relay": "gh copilot -- --allow-all",
-    "test": "node --import ./scripts/node-test-keep-alive.mjs --test \"server/**/*.test.mjs\" \"shared/**/*.test.mjs\" \".github/extensions/web-relay/**/*.test.mjs\" \"scripts/**/*.test.mjs\"",
+    "test": "node --import ./scripts/node-test-keep-alive.mjs --import ./scripts/node-test-worktree-guard.mjs --test \"server/**/*.test.mjs\" \"shared/**/*.test.mjs\" \".github/extensions/web-relay/**/*.test.mjs\" \"scripts/**/*.test.mjs\"",
     "test:agents:smoke": "node --test \"tests/agents/**/*.test.mjs\"",
+    "test:packed-update": "node --test tests/packed-update/packed-update.test.mjs",
     "test:e2e": "node tests/run-e2e.mjs",
     "setup:git": "node scripts/setup-git.mjs",
     "land": "node scripts/land.mjs",

package/server/claude-cloud-worker/claude-cloud-event-normalizer.mjs

@@ -1,4 +1,5 @@
 import { capThought } from '../../shared/thought-cap.mjs';
+import { tokenUsageModel } from '../../shared/turn-token-usage.mjs';
 import {
   compactBoundaryActivityAction,
   displayToolName,
@@ -68,6 +69,57 @@ export function readCloudResult(payload) {
   };
 }
 
+/**
+ * A cloud session's running token totals per model, for the token booking
+ * (POST /api/turn-token-usage with `sessionTotals`; the relay books what
+ * they grew by): `[{ model, inputTokens, cacheWriteTokens, cacheReadTokens,
+ * outputTokens, costUsd, costSource, costUnknown }]` out of a result's
+ * `modelUsage`. A field the entry does not carry is null, not 0. The cache
+ * fields of the session read (`sessionTokens`, readCloudSessionUsage) cover
+ * the whole session, so they stand in only when the session ran one model;
+ * with more, a missing field stays null. Model ids drop the `[1m]` tier.
+ */
+export function cloudSessionTokenTotals(modelUsage, sessionTokens = null) {
+  if (!modelUsage || typeof modelUsage !== 'object' || Array.isArray(modelUsage)) return [];
+  const count = (value) => {
+    const n = finiteOrNull(value);
+    return n === null || n < 0 ? null : Math.trunc(n);
+  };
+  const totals = new Map();
+  for (const [name, entry] of Object.entries(modelUsage)) {
+    const model = tokenUsageModel(name);
+    if (!model || !entry || typeof entry !== 'object') continue;
+    const costUsd = finiteOrNull(entry.costUSD);
+    const next = {
+      model,
+      inputTokens: count(entry.inputTokens),
+      cacheWriteTokens: count(entry.cacheCreationInputTokens),
+      cacheReadTokens: count(entry.cacheReadInputTokens),
+      outputTokens: count(entry.outputTokens),
+      costUsd: costUsd === null || costUsd < 0 ? null : costUsd,
+      costSource: null,
+      costUnknown: entry.costBasis === 'unknown',
+    };
+    const current = totals.get(model);
+    if (!current) {
+      totals.set(model, next);
+      continue;
+    }
+    for (const field of ['inputTokens', 'cacheWriteTokens', 'cacheReadTokens', 'outputTokens', 'costUsd']) {
+      if (next[field] !== null) current[field] = (current[field] ?? 0) + next[field];
+    }
+    current.costUnknown = current.costUnknown || next.costUnknown;
+  }
+  const entries = [...totals.values()];
+  if (entries.length === 1 && sessionTokens) {
+    const [only] = entries;
+    if (only.cacheWriteTokens === null) only.cacheWriteTokens = count(sessionTokens.cacheWriteTokens);
+    if (only.cacheReadTokens === null) only.cacheReadTokens = count(sessionTokens.cacheReadTokens);
+  }
+  for (const entry of entries) entry.costSource = entry.costUsd === null ? null : 'claude-code';
+  return entries;
+}
+
 /**
  * What `GET /v1/code/sessions/{id}` says after a turn, for the relay's usage
  * routes: the context occupancy in the shape `/api/claude-context-usage`
@@ -99,6 +151,14 @@ export function readCloudSessionUsage(sessionBody, { model = '' } = {}) {
     };
   return {
     contextUsage,
+    // The session's token totals over every model: what the token booking
+    // falls back on for the cache fields (cloudSessionTokenTotals).
+    tokens: {
+      inputTokens: finiteOrNull(usage.input_tokens),
+      outputTokens: finiteOrNull(usage.output_tokens),
+      cacheReadTokens: finiteOrNull(usage.cache_read_tokens),
+      cacheWriteTokens: finiteOrNull(usage.cache_write_tokens),
+    },
     costUsd: finiteOrNull(usage.cost_usd),
     sessionUrl: String(shape?.session_url || sessionBody?.sessionUrl || '').trim() || null,
     workerStatus: String(shape?.worker_status || '').trim().toLowerCase() || null,

package/server/claude-cloud-worker/claude-cloud-session-process.mjs

@@ -18,6 +18,7 @@ import {
 } from '../claude-worker/claude-turn-publisher.mjs';
 import { summarizeToolInput } from '../claude-worker/sdk-message-normalizer.mjs';
 import {
+  cloudSessionTokenTotals,
   createClaudeCloudEventNormalizer,
   readCloudResult,
   readCloudSessionUsage,
@@ -177,6 +178,18 @@ export function createClaudeCloudSessionRunner({
   // Background work is over and nothing has moved for this long: ask the
   // session whether the agent is still going to say something.
   backgroundQuietMs = 45_000,
+  // Between turns, while the cloud may still be working on something no
+  // relay turn owns (its last known status was not idle, or a turn ended here
+  // without its `result`), the session is read again this often: the relay
+  // waits on that answer before it replaces this worker (releaseHold).
+  statusRecheckMs = 20_000,
+  // A session that stays not idle this long is no longer read (one warning
+  // line); the next delivery starts the reads again. The hold stays: the
+  // relay does not replace a worker whose session it last saw working.
+  statusRecheckGiveUpMs = 2 * 60 * 60_000,
+  // How often the stored binding is asked for again at start when the relay
+  // does not answer (attachOnStart); three tries in all.
+  bindingRetryMs = 5_000,
 } = {}) {
   const publisher = createClaudeTurnPublisher({ api, dbg });
   // The account's usage limit as the sandbox's Claude Code reports it: the
@@ -210,10 +223,23 @@ export function createClaudeCloudSessionRunner({
   // - `attributionRequestId`: the request whose answer is still to come.
   // - `model`: the model this process last gave the sandbox (the create's,
   //   or a later set_model); undefined while it does not know.
+  // - `workerStatus`: the session's `worker_status` at the last read of it
+  //   ('idle' when the cloud has nothing running), null while unknown.
   let session = null;
   let turn = null;
   let stream = null;
   let idleTimer = null;
+  let statusTimer = null;
+  // A read of the session between turns that may attach it (syncSession):
+  // a delivery waits for it, so the two never read the log at once.
+  let pendingSync = null;
+  // When the current run of status rechecks began (null: none runs), and
+  // whether it was given up (statusRecheckGiveUpMs).
+  let recheckSince = null;
+  let recheckGivenUp = false;
+  // A turn the session started by itself is being registered with the relay.
+  let openingStrayTurn = false;
+  let disposed = false;
   // Events are handled one at a time and in order; posting a user message
   // takes a place in the same line, so no event of the turn it starts is
   // looked at before the turn's start is known.
@@ -248,6 +274,7 @@ export function createClaudeCloudSessionRunner({
       attribution: undefined,
       attributionRequestId: null,
       model: undefined,
+      workerStatus: null,
     };
   }
 
@@ -274,6 +301,33 @@ export function createClaudeCloudSessionRunner({
     return Boolean(turn);
   }
 
+  /**
+   * Why the relay may not stop this worker and launch a fresh one now, or ''
+   * when it may (the hold names of the relay's STEERING_RELEASE_HOLDS):
+   * - 'turn': a turn runs here, delivered or one the session started itself
+   *   (from the moment the relay is asked for its row).
+   * - 'background': no turn runs here, but the cloud may still be working on
+   *   one: a turn that ended here without its `result` (a Stop the cloud did
+   *   not confirm, the background-hold ceiling, a turn the relay would not
+   *   register), or a session whose last known status is not idle. A worker
+   *   replaced then would lose what that work still writes: the count lives
+   *   only in this process, and a fresh one reads on from the stored cursor
+   *   as if nothing were running.
+   * A session this process has not read yet holds nothing.
+   */
+  function releaseHold() {
+    if (turn || openingStrayTurn) return 'turn';
+    if (!session) return '';
+    if (session.unfinishedTurns > 0) return 'background';
+    if (session.workerStatus && session.workerStatus !== 'idle') return 'background';
+    return '';
+  }
+
+  /** Remember what a read of the session said about the cloud's work. */
+  function noteSessionRead(workerStatus) {
+    if (session) session.workerStatus = workerStatus || null;
+  }
+
   // ---------------------------------------------------------------------------
   // Relay-facing publishing
 
@@ -455,6 +509,7 @@ export function createClaudeCloudSessionRunner({
         let workerStatus = '';
         try {
           ({ workerStatus } = readCloudSessionUsage(await withTimeout(cloud.getSession(session.id), sessionReadTimeoutMs)));
+          noteSessionRead(workerStatus);
         } catch (error) {
           dbg('cloud session read failed', error?.message || String(error));
         }
@@ -531,6 +586,9 @@ export function createClaudeCloudSessionRunner({
     if (!response?.messageId) {
       dbg('stray cloud turn not registered; skipping it until its result');
       session.unfinishedTurns += 1;
+      // No turn here will end the wait on its `result`; the session's
+      // status will.
+      scheduleStatusRecheck();
       return null;
     }
     const message = {
@@ -568,6 +626,7 @@ export function createClaudeCloudSessionRunner({
         endTurn(t);
         if (turn === t) turn = null;
         scheduleIdleClose();
+        scheduleStatusRecheck();
       }
     })();
     return t;
@@ -591,7 +650,14 @@ export function createClaudeCloudSessionRunner({
     // continuation of its own, so the chat shows it.
     if (!t && session.attached && sequence !== null && session.unfinishedTurns === 0
       && sequence > session.cursorSeq && startsStrayTurn(event, payload, type)) {
-      t = await openStrayTurn(sequence, payload, type);
+      // The relay is asked for a row first: the turn runs already, and the
+      // release holds meanwhile as it will once the row is there.
+      openingStrayTurn = true;
+      try {
+        t = await openStrayTurn(sequence, payload, type);
+      } finally {
+        openingStrayTurn = false;
+      }
       if (!t) return;
     }
 
@@ -962,12 +1028,159 @@ export function createClaudeCloudSessionRunner({
   async function confirmUnfinishedTurns() {
     try {
       const { workerStatus } = readCloudSessionUsage(await withTimeout(cloud.getSession(session.id), sessionReadTimeoutMs));
+      noteSessionRead(workerStatus);
       if (workerStatus === 'idle') session.unfinishedTurns = 0;
     } catch (error) {
       dbg('cloud session read failed', error?.message || String(error));
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Between turns: the session's status, and the attach at start
+
+  /**
+   * The session's status, read once (bounded); null when the read failed, in
+   * which case what was known before stays.
+   */
+  async function readWorkerStatus() {
+    try {
+      const { workerStatus } = readCloudSessionUsage(await withTimeout(cloud.getSession(session.id), sessionReadTimeoutMs));
+      noteSessionRead(workerStatus);
+      return workerStatus || null;
+    } catch (error) {
+      dbg('cloud session read failed', error?.message || String(error));
+      return null;
+    }
+  }
+
+  /**
+   * Read the session again later while it holds the release with no turn
+   * here to end the wait (a turn's end schedules this itself), or while the
+   * session bound at start is not attached yet.
+   */
+  function scheduleStatusRecheck() {
+    if (statusTimer || disposed || !session || turn) return;
+    if (session.attached && !releaseHold()) {
+      recheckSince = null;
+      return;
+    }
+    if (recheckGivenUp) return;
+    if (recheckSince === null) {
+      recheckSince = now();
+    } else if (now() - recheckSince >= statusRecheckGiveUpMs) {
+      // Not forever: a session stuck in a working state would be read every
+      // statusRecheckMs for the life of the worker.
+      recheckGivenUp = true;
+      dbg(
+        `warning: the cloud session has not been idle for ${Math.round(statusRecheckGiveUpMs / 60_000)} min;`,
+        'no more status reads until the next delivery, and the relay does not replace this worker meanwhile',
+      );
+      return;
+    }
+    statusTimer = setTimeoutImpl(() => {
+      statusTimer = null;
+      void syncSession();
+    }, statusRecheckMs);
+    statusTimer?.unref?.();
+  }
+
+  function clearStatusRecheck() {
+    if (statusTimer) clearTimeoutImpl(statusTimer);
+    statusTimer = null;
+  }
+
+  /**
+   * Between turns: read the session, and act on an idle one. An idle cloud
+   * has no `result` left to send, so the turns that ended here without one
+   * are done with (as confirmUnfinishedTurns does before a send). An idle
+   * session bound at start but not attached yet is read on from the stored
+   * cursor up to now and its stream opened, so a turn the session starts by
+   * itself from here on is followed as a continuation, as the worker before
+   * this one did. A session that is working is not attached: the turn it
+   * runs may be a delivered one a dead worker left behind, which the relay
+   * delivers again and the delivery follows from the log (catchUp); taken
+   * for a turn of the session's own, it would be published twice.
+   * A delivery waits for this (pendingSync).
+   */
+  function syncSession() {
+    if (pendingSync) return pendingSync;
+    if (disposed || !session || turn || openingStrayTurn) return Promise.resolve(false);
+    const run = (async () => {
+      let attachedNow = false;
+      const status = await readWorkerStatus();
+      if (!disposed && session && !turn && status === 'idle') {
+        session.unfinishedTurns = 0;
+        if (!session.attached) {
+          await catchUp();
+          if (!disposed && session && !session.attached) {
+            session.attached = true;
+            ensureStream();
+            attachedNow = true;
+            dbg('cloud event stream opened between turns', `after=${session.lastSeq}`);
+          }
+        }
+      }
+      return attachedNow;
+    })();
+    pendingSync = run
+      .catch((error) => {
+        dbg('cloud session sync failed', error?.message || String(error));
+        return false;
+      })
+      .finally(() => {
+        pendingSync = null;
+        scheduleStatusRecheck();
+      });
+    return pendingSync;
+  }
+
+  /** The binding the relay stores for this conversation, or null. */
+  async function readStoredBinding() {
+    const routePath = `/api/claude-cloud-session?conversationId=${encodeURIComponent(sdkSessionId)}`;
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        return await api('GET', routePath);
+      } catch (error) {
+        // A relay without the route answers 404 for good: the first delivery
+        // binds the session, as before.
+        if (Number(error?.status) === 404 || attempt >= 3 || disposed) {
+          dbg('stored cloud session not read', error?.message || String(error));
+          return null;
+        }
+        await sleep(bindingRetryMs);
+      }
+    }
+  }
+
+  /**
+   * At worker start: bind the cloud session the relay stores for this
+   * conversation and open its event stream from the stored cursor, before
+   * any delivery. The worker this one replaces kept its stream open for its
+   * whole life (idleCloseMs = 0) and so mirrored the turns the session
+   * starts by itself (a message sent on claude.ai, the agent's closing turn
+   * after background work); without this a fresh worker would see none of
+   * them until its first delivery. A conversation with no cloud session yet
+   * has nothing to attach: its first delivery creates one. A session that is
+   * working at start is read again every statusRecheckMs and attached once
+   * idle (syncSession says why not before).
+   *
+   * Resolves true when the stream was opened.
+   */
+  async function attachOnStart() {
+    if (session || turn || disposed || pendingSync) return false;
+    const run = (async () => {
+      const binding = await readStoredBinding();
+      const id = String(binding?.sessionId || '').trim();
+      if (!id || session || disposed) return false;
+      session = newSession(id, { cursor: toCloudSequence(binding.lastSequence) ?? 0 });
+      return true;
+    })();
+    // A delivery that arrives meanwhile waits until the binding is known.
+    pendingSync = run.catch(() => false).finally(() => { pendingSync = null; });
+    if (!await pendingSync) return false;
+    return syncSession();
+  }
+
   /**
    * Before a message goes into a session that exists: hand the sandbox the
    * commit attribution the relay delivered, unless this process already did.
@@ -1172,6 +1385,7 @@ export function createClaudeCloudSessionRunner({
       dbg('cloud session read failed', error?.message || String(error));
     }
     if (usage.sessionUrl) session.url = usage.sessionUrl;
+    if (usage.workerStatus !== undefined) noteSessionRead(usage.workerStatus);
     const costUsd = usage.costUsd ?? state.result?.totalCostUsd ?? null;
     await reportSession(message, {
       ...(costUsd !== null ? { costUsd } : {}),
@@ -1180,6 +1394,32 @@ export function createClaudeCloudSessionRunner({
     state.contextUsage = usage.contextUsage;
     await publisher.publishContextUsage({ message, state, model, sdkSessionId });
     await publisher.publishPlanUsage({ message, state, sdkSessionId });
+    await publishTurnTokens(message, state, usage.tokens);
+  }
+
+  // A worker process names its run once: a turn requeued onto a restarted
+  // worker is another run of it (POST /api/turn-token-usage).
+  const tokenRunId = crypto.randomUUID();
+
+  /**
+   * The session's running token totals per model (the result's
+   * `modelUsage`), under the turn: the relay books what they grew by since
+   * the session's other turns. Advisory; nothing without `modelUsage`.
+   */
+  async function publishTurnTokens(message, state, sessionTokens) {
+    const sessionTotals = cloudSessionTokenTotals(state.result?.modelUsage, sessionTokens);
+    if (!sessionTotals.length || !session.id) return;
+    await api('POST', '/api/turn-token-usage', {
+      conversationId: message.conversationId,
+      turnId: String(message.id || ''),
+      runId: tokenRunId,
+      provider: 'claude-cloud',
+      nativeSessionId: session.id,
+      at: new Date().toISOString(),
+      sessionTotals,
+    }).catch((error) => {
+      dbg('turn token publish failed', error?.message || String(error));
+    });
   }
 
   async function finishTurn(t, outcome) {
@@ -1291,7 +1531,19 @@ export function createClaudeCloudSessionRunner({
       dbg('turn already active; rejecting concurrent deliver', message.id);
       return false;
     }
+    // The session is being read between turns (the attach at start, or a
+    // status check): this delivery binds and reads it after that, never
+    // beside it. A turn the session started meanwhile takes precedence.
+    while (pendingSync) await pendingSync;
+    if (turn) {
+      dbg('turn already active; rejecting concurrent deliver', message.id);
+      return false;
+    }
     clearIdleClose();
+    clearStatusRecheck();
+    // A delivery starts the status reads afresh, also after they were given up.
+    recheckSince = null;
+    recheckGivenUp = false;
     const t = openTurn(message);
     const relayHoldMs = Number(pending?.settings?.backgroundTaskTimeoutMs);
     if (Number.isFinite(relayHoldMs) && relayHoldMs > 0) t.holdMs = relayHoldMs;
@@ -1310,11 +1562,14 @@ export function createClaudeCloudSessionRunner({
       endTurn(t);
       turn = null;
       scheduleIdleClose();
+      scheduleStatusRecheck();
     }
   }
 
   async function dispose() {
+    disposed = true;
     clearIdleClose();
+    clearStatusRecheck();
     if (turn) endTurn(turn);
     const entry = stream;
     stream = null;
@@ -1326,6 +1581,8 @@ export function createClaudeCloudSessionRunner({
     getActiveQueueMessageId,
     getActiveQueueAttempt,
     isTurnActive,
+    releaseHold,
+    attachOnStart,
     dispose,
   };
 }

package/server/claude-cloud-worker/claude-cloud-session-worker.mjs

@@ -14,6 +14,7 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { resolveBuildId } from '../../shared/build-id.mjs';
 import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
@@ -21,6 +22,7 @@ import { createClaudeCloudCredentials } from '../../shared/claude-cloud/credenti
 import { createClaudeCloudClient } from '../../shared/claude-cloud/api-client.mjs';
 import { resolveClaudeCloudBaseUrl } from '../../shared/claude-cloud/base-url.mjs';
 import { createClaudeCloudSessionRunner } from './claude-cloud-session-process.mjs';
+import { buildClaudeCloudSteeringState } from './claude-cloud-worker-steering.mjs';
 
 // Windows console launch: the launcher names the worker log, this copies
 // stdout/stderr into it. A no-op wherever the launcher redirects instead.
@@ -51,6 +53,10 @@ async function main() {
 
   const configPath = String(process.env.COPILOT_WEB_RELAY_CONFIG || '').trim()
     || path.resolve(__dirname, '..', 'config.json');
+  // The code this process started on, read once from the repo root and kept
+  // for its whole life: the relay recycles a worker whose build differs from
+  // its own, and a tree that moves on under us must not change our answer.
+  const buildId = resolveBuildId(path.resolve(__dirname, '..', '..')).id;
   const serverUrl = resolveRelayServerUrl({ configPath });
   const token = loadTokenFromConfig(configPath);
   const defaultModel = String(process.env.CLAUDE_CLOUD_RELAY_MODEL || '').trim();
@@ -101,17 +107,28 @@ async function main() {
   let heartbeatTimer = null;
   const heartbeat = createHeartbeatController({
     api,
+    buildId,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
     getHeartbeatTimer: () => heartbeatTimer,
     setHeartbeatTimer: (timer) => { heartbeatTimer = timer; },
     getActiveQueueMessageId: () => runner.getActiveQueueMessageId(),
+    // No steering here; the snapshot tells the relay when it may replace
+    // this worker: between turns, with no turn that ended here without its
+    // result, and with the cloud session idle at its last read. Anything else
+    // is cloud work whose output only this process would still publish. The
+    // cloud session lives on in the cloud; the fresh worker binds it at start
+    // and re-opens its event stream from the cursor the relay stores
+    // (runner.attachOnStart below), so the turns the session starts by
+    // itself are still followed.
+    getSteeringState: () => buildClaudeCloudSteeringState(runner),
   });
 
   const wsLink = createWorkerWebSocketLink({
     serverUrl,
     token,
     dbg,
+    buildId,
     getSessionReady: () => true,
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
@@ -144,9 +161,13 @@ async function main() {
     getActiveQueueMessageIds: () => [runner.getActiveQueueAttempt()],
   });
 
-  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} model=${defaultModel || 'default'}`);
+  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} model=${defaultModel || 'default'} build=${buildId || 'unknown'}`);
   heartbeat.startHeartbeat();
   wsLink.start();
+  // Not awaited: deliveries wait for it inside the runner, and a relay that
+  // cannot say which cloud session this is leaves the binding to the first
+  // delivery, as before.
+  runner.attachOnStart().catch((error) => dbg('cloud session attach at start failed', error?.message || String(error)));
 }
 
 main().catch((error) => {

package/server/claude-cloud-worker/claude-cloud-worker-steering.mjs

@@ -0,0 +1,34 @@
+/**
+ * The heartbeat steering snapshot of the Claude Cloud worker. It steers
+ * nothing (`supported: false`, so the composer offers no mid-turn steering and
+ * reads neither the hold nor the cancellable ids); it is sent for the release
+ * fields, which tell the relay whether it may stop this worker and launch a
+ * fresh one now (its recycle after a deploy).
+ *
+ * The rule is the runner's (`releaseHold()` in claude-cloud-session-process.mjs):
+ * not while a turn runs here, not while a turn that ended here without its
+ * `result` may still run in the cloud, and not while the cloud session's last
+ * known status is not idle. The generic snapshot of the other small mains
+ * (shared/worker-runtime/simple-steering-state.mjs) knows only the turn; the
+ * cloud session can be busy with no relay turn at all.
+ *
+ * `runner` is the object createClaudeCloudSessionRunner returns.
+ */
+export function buildClaudeCloudSteeringState(runner) {
+  const attempt = runner?.getActiveQueueAttempt?.() || null;
+  const messageId = String(attempt?.id || '').trim() || null;
+  const turnActive = runner?.isTurnActive?.() === true || Boolean(messageId);
+  // A runner without the hold function still never says yes mid-turn.
+  const hold = String(runner?.releaseHold?.() || '').trim() || (turnActive ? 'turn' : '');
+  return {
+    turnActive,
+    canSteer: false,
+    holdReason: null,
+    messageId,
+    supported: false,
+    cancellableIds: [],
+    releasable: !hold,
+    releaseHold: hold || null,
+    backgroundTaskCount: 0,
+  };
+}

package/server/claude-worker/claude-remote-relay-tool.mjs

@@ -75,6 +75,7 @@ export const REMOTE_RELAY_TOOL_ZOD_SHAPE = {
   group: z.string().nullable().optional().describe(FIELDS.group.description),
   auto_compact_window: number('auto_compact_window'),
   thinking_enabled: z.boolean().optional().describe(FIELDS.thinking_enabled.description),
+  planOnly: z.boolean().optional().describe(FIELDS.planOnly.description),
   thinking_display: choice('thinking_display', REMOTE_RELAY_THINKING_DISPLAYS),
   question_id: text('question_id'),
   // ask: the contract's validator refuses a question or detail that is too

package/server/claude-worker/claude-session-process.mjs

@@ -615,6 +615,9 @@ export function createClaudeSessionRunner({
     // Both Claude billings report to the Claude API booking; DeepSeek has
     // its own.
     ...(claudeBillingOf(workerKind) ? { billingUsageRoute: '/api/claude-api-usage', billingKind: workerKind } : {}),
+    // Every Claude-family worker books its turns' tokens.
+    turnTokenProvider: workerKind,
+    ...(typeof backend?.turnTokenCost === 'function' ? { turnTokenCost: backend.turnTokenCost } : {}),
     ...(backend
       ? {
           describeFailure: backend.describeFailure,
@@ -4247,11 +4250,17 @@ export function createClaudeSessionRunner({
     // `releasable`: the relay may replace this worker now (a billing swap):
     // no CLI process and no delivery on its way in, or a process
     // canReleaseForRespawn would let go of.
+    // `cliAlive`: the CLI child is still up. The relay's recycle replaces a
+    // stale worker only once it is releasable AND its CLI is gone; a
+    // releasable worker whose CLI is up sits in the idle window, where a
+    // scheduled job may still wake it, and is left to its own idle-out. A
+    // closing process is not gone yet, so it still counts as alive.
     if (!proc || proc.closing || proc.aborted) {
       const admitting = admittingDeliveries > 0;
       return {
         turnActive: false, canSteer: false, holdReason: null, messageId: null, supported: true, autoCompactWindow: null,
         releasable: !admitting, releaseHold: admitting ? 'turn' : null, backgroundTaskCount: 0,
+        cliAlive: Boolean(proc),
       };
     }
     const ctx = proc.activeCtx || null;
@@ -4290,6 +4299,7 @@ export function createClaudeSessionRunner({
       releasable: !hold,
       releaseHold: hold || null,
       backgroundTaskCount: proc.liveTasks.size,
+      cliAlive: true,
     };
   }
 

package/server/claude-worker/claude-session-worker-main.mjs

@@ -14,6 +14,7 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { resolveBuildId } from '../../shared/build-id.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { resolveDeliveredAutoCompactWindow } from '../../shared/auto-compact-window.mjs';
 import { resolveDeliveredThinking } from '../../shared/claude-thinking.mjs';
@@ -59,6 +60,10 @@ export async function runClaudeSessionWorker({
 
   const configPath = String(process.env.COPILOT_WEB_RELAY_CONFIG || '').trim()
     || path.resolve(__dirname, '..', 'config.json');
+  // The code this process started on, read once from the repo root and kept
+  // for its whole life: the relay recycles a worker whose build differs from
+  // its own, and a tree that moves on under us must not change our answer.
+  const buildId = resolveBuildId(path.resolve(__dirname, '..', '..')).id;
   const serverUrl = resolveRelayServerUrl({ configPath });
   const token = loadTokenFromConfig(configPath);
   const cwd = String(process.env.COPILOT_WORKSPACE_ROOT || '').trim() || process.cwd();
@@ -143,6 +148,7 @@ export async function runClaudeSessionWorker({
   let heartbeatTimer = null;
   heartbeat = createHeartbeatController({
     api,
+    buildId,
     // What this worker runs on: the relay hands it only rows of that billing.
     workerKind: turnRunner.workerKind,
     pollMs: HEARTBEAT_MS,
@@ -191,6 +197,7 @@ export async function runClaudeSessionWorker({
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
     workerKind: turnRunner.workerKind,
+    buildId,
     onDeliver: async (pending, reason) => {
       dbg('queue.deliver received', `reason=${reason}`, `msgId=${pending?.message?.id || 'none'}`);
       const deliveredTimeout = Number(pending?.settings?.backgroundTaskTimeoutMs);
@@ -263,7 +270,7 @@ export async function runClaudeSessionWorker({
     onBeforeExit: () => { try { turnRunner.shutdown({ graceful: false }); } catch {} },
   });
 
-  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'}${backend ? ` backend=${backend.id}` : ''}`);
+  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'}${backend ? ` backend=${backend.id}` : ''} build=${buildId || 'unknown'}`);
   heartbeat.startHeartbeat();
   wsLink.start();
 }