@oar-sh/oar 0.9.16 → 0.9.18

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

@@ -68,6 +68,11 @@ import {
   outputDirOf,
   usableOutputPath,
 } from './task-output-discovery.mjs';
+import {
+  checkClaudeSubscriptionInit,
+  describeClaudeSubscriptionFailure,
+  isKnownApiKeySource,
+} from './claude-subscription-key-check.mjs';
 
 /**
  * Which system-prompt append a relay mode gets (claude-sdk-adapter's
@@ -448,6 +453,13 @@ function isPhantomResult(sdkMessage) {
  * every live task is stopped via the SDK and the wind-down proceeds through
  * the normal notification/continuation path.
  */
+
+// A Claude chat's billing named by a delivered row or a worker kind: the
+// subscription ('claude') or the saved API key ('claude-api'); '' otherwise.
+function claudeBillingOf(value) {
+  const billing = String(value || '').trim().toLowerCase();
+  return billing === 'claude' || billing === 'claude-api' ? billing : '';
+}
 export function createClaudeSessionRunner({
   api,
   sdkSessionId,
@@ -532,6 +544,9 @@ export function createClaudeSessionRunner({
   // by the first turn to open regardless.
   compactReplayAdoptionMs = 60_000,
   continuationRetryDelayMs = 500,
+  // How long a delivered turn that opens over a finished continuation waits
+  // for that continuation's row to register, so its answer publishes first.
+  continuationRegistrationWaitMs = 10_000,
   // Backoff between attempts to save a consumed steer's settle marker (~31 s
   // in all); after the last one the row fails terminally instead.
   settleRetryDelaysMs = [1_000, 2_000, 4_000, 8_000, 8_000, 8_000],
@@ -568,21 +583,56 @@ export function createClaudeSessionRunner({
   // worker asks for a heartbeat, on which the relay learns which process
   // holds the session and asks for the set again.
   onBackgroundTaskSetStale = () => {},
-  // Whether CLI processes carry the relay's `remote_relay` tool
+  // Whether CLI processes carry the relay's `relay_tool` tool
   // (shared/remote-relay-tool-core.mjs). Default: ask the relay.
   remoteRelayToolGate = null,
   // Records every sub-agent's frames as its timeline, run-scoped (see
   // subagent-timeline-recorder.mjs). Injectable for tests.
   subagentTimelineRecorder = null,
+  // Another endpoint for the CLI (../deepseek-worker/deepseek-claude-backend.mjs):
+  // its spawn environment, model ids and effort, and what it reports. null is
+  // Claude through the host's login.
+  backend = null,
   dbg = () => {},
 } = {}) {
+  // The backend that maps models, effort, thinking and images into its own
+  // terms. A backend on Claude's own models (`claudeModels`, the Claude API
+  // backend) brings only its environment, its failures and what it reports:
+  // everything model-shaped stays exactly as the Claude worker has it.
+  const modelBackend = backend && backend.claudeModels !== true ? backend : null;
+  // The kind of worker this runner is part of: 'claude' on the host's login,
+  // else the backend's provider ('claude-api', 'deepseek').
+  const workerKind = String(backend?.providerType || backend?.id || 'claude').trim().toLowerCase();
+  // A relay-announced billing swap is noted once per worker.
+  let billingSwapNoted = false;
+  // Neither Claude's plan windows nor its usage limit exist on another backend.
+  const readPlanUsageForTurn = backend && !backend.reportsPlanUsage ? async () => null : readPlanUsageImpl;
   const timelineRecorder = subagentTimelineRecorder || createSubagentTimelineRecorder({ api, conversationId: sdkSessionId, dbg });
   const publisher = createClaudeTurnPublisher({
     api,
     dbg,
     takeWorkflowRuns: () => drainSettledWorkflowRuns(),
+    // Both Claude billings report to the Claude API booking; DeepSeek has
+    // its own.
+    ...(claudeBillingOf(workerKind) ? { billingUsageRoute: '/api/claude-api-usage', billingKind: workerKind } : {}),
+    ...(backend
+      ? {
+          describeFailure: backend.describeFailure,
+          runtimeLabel: backend.label || 'DeepSeek',
+          failureCodePrefix: backend.id || 'deepseek',
+          reportsPlanUsage: backend.reportsPlanUsage !== false,
+          usageRoute: backend.usageRoute || null,
+          ...(modelBackend
+            ? {
+                usageModelKey: modelBackend.relayModel,
+                relayModel: (value) => (value ? modelBackend.relayModel(value) : value),
+              }
+            : {}),
+        }
+      // The subscription worker's own refusal: a turn that came up on an API key.
+      : { describeFailure: describeClaudeSubscriptionFailure }),
   });
-  // `remote_relay` is registered only while this relay has paired remotes.
+  // `relay_tool` is registered only while this relay has paired remotes.
   // Asked once when the worker starts, and again whenever a CLI process winds
   // down, so a remote paired later reaches the next process. A cold spawn
   // waits for the pending answer (handlePendingPayload): the tool list is
@@ -591,7 +641,9 @@ export function createClaudeSessionRunner({
   void remoteRelayGate.refresh();
   // The subscription's usage limit as the CLI reports it. Runner-level: the
   // limit is the account's, not the CLI process's.
-  const usageLimit = createUsageLimitTracker();
+  const usageLimit = backend && !backend.reportsUsageLimit
+    ? { observe: () => null, classifyResult: () => null, classifyException: () => null }
+    : createUsageLimitTracker();
   const resolveWorkflowSessionDir = resolveWorkflowSessionDirImpl || createDefaultWorkflowSessionDirResolver();
   let claudeNativeSessionId = '';
   let proc = null;
@@ -657,13 +709,19 @@ export function createClaudeSessionRunner({
   // Row id → the latest in-flight /api/queue-consumed POST touching it.
   const consumedMarkChains = new Map();
 
-  async function persistNativeSessionId(conversationId, sessionId) {
+  /**
+   * `cliStartedAt` (ms) is a backend CLI's spawn time, sent at its first
+   * init even when the session id is the known one: the relay records each
+   * CLI start of a DeepSeek session to find its shell snapshot on delete.
+   */
+  async function persistNativeSessionId(conversationId, sessionId, { cliStartedAt = null } = {}) {
     const normalized = String(sessionId || '').trim();
-    if (!normalized || normalized === claudeNativeSessionId) return;
+    if (!normalized || (normalized === claudeNativeSessionId && !cliStartedAt)) return;
     try {
       await api('POST', '/api/claude-native-session', {
         conversationId,
         claudeNativeSessionId: normalized,
+        ...(cliStartedAt ? { cliStartedAt } : {}),
       });
       // Only cache after the server accepted it, so a failed persist is
       // retried on the next init — resume across worker restarts depends on
@@ -678,7 +736,8 @@ export function createClaudeSessionRunner({
     // Per-message model wins so the composer can switch Claude models between
     // turns; the conversation's provider model and worker default are fallbacks.
     const requestedModel = String(message.model || '').trim();
-    const perTurnModel = requestedModel.toLowerCase() !== 'auto' && requestedModel.toLowerCase().startsWith('claude-')
+    const ownModel = modelBackend ? modelBackend.isModel(requestedModel) : requestedModel.toLowerCase().startsWith('claude-');
+    const perTurnModel = requestedModel.toLowerCase() !== 'auto' && ownModel
       ? requestedModel
       : '';
     return perTurnModel
@@ -813,6 +872,12 @@ export function createClaudeSessionRunner({
         modelUsage: null,
       },
       planBoardPosted: false,
+      // The CLI process the turn ran in, as its usage report names it: taken
+      // from the process here and again when the context is made active, and
+      // read from the context at finalize — a late continuation flush
+      // finalizes after the process died, when `proc` is null or a newer one.
+      runId: proc?.runId || '',
+      resumedSessionId: proc?.resumedSessionId || '',
       // Set only on a context attached by post-compaction adoption, and only
       // until that turn produces output — see handBackAdoptedContext.
       adoptedFromCompaction: false,
@@ -846,6 +911,8 @@ export function createClaudeSessionRunner({
 
   function activateContext(ctx) {
     proc.activeCtx = ctx;
+    ctx.runId = proc.runId || '';
+    ctx.resumedSessionId = proc.resumedSessionId || '';
     proc.lastBoundary = null;
     proc.continuationInitPending = false;
     proc.notificationPendingAt = 0;
@@ -1173,7 +1240,7 @@ export function createClaudeSessionRunner({
   }
 
   /** Wait until a continuation context has its relay queue row (or gave up). */
-  async function waitForContextRegistration(ctx, timeoutMs = 10_000) {
+  async function waitForContextRegistration(ctx, timeoutMs = continuationRegistrationWaitMs) {
     const deadline = Date.now() + timeoutMs;
     while (!ctx.registered && !ctx.discarded && Date.now() < deadline) {
       await new Promise((resolve) => setTimeout(resolve, 50));
@@ -1432,9 +1499,13 @@ export function createClaudeSessionRunner({
     ctx.finalized = true;
     controlPoller?.stop?.(ctx.controlState);
     // A late continuation flush can land after the process died; usage reads
-    // and model fallbacks must survive that.
+    // and model fallbacks must survive that. The process the report names is
+    // the context's own (set when it was made active), never the one that
+    // happens to be current now.
     const turnRef = proc?.turn || null;
     const procModel = proc?.model || null;
+    const runId = ctx.runId || '';
+    const resumedSessionId = ctx.resumedSessionId || '';
     // Steers pushed into this turn and still unsettled: the CLI has their
     // prompts, so the relay marks them consumed with this turn's commit and
     // never re-runs them even if this worker dies before settling them.
@@ -1461,12 +1532,12 @@ export function createClaudeSessionRunner({
         await publisher.publishFinalStream(ctx.message, ctx.state.lastStreamedText);
         const [contextUsage, planUsage] = await Promise.all([
           readContextUsageImpl(turnRef, dbg),
-          readPlanUsageImpl(turnRef, dbg),
+          readPlanUsageForTurn(turnRef, dbg),
         ]);
         ctx.state.contextUsage = contextUsage;
         ctx.state.planUsage = planUsage;
         await publisher.publishContextUsage({ message: ctx.message, state: ctx.state, model: procModel, sdkSessionId });
-        await publisher.publishPlanUsage({ message: ctx.message, state: ctx.state, sdkSessionId });
+        await publisher.publishPlanUsage({ message: ctx.message, state: ctx.state, sdkSessionId, runId, resumedSessionId });
       })().catch((error) => dbg('stopped-turn publish failed', error?.message || String(error)));
       lingerStoppedRow(ctx, publishChain);
       closeContext(ctx, true);
@@ -1478,13 +1549,13 @@ export function createClaudeSessionRunner({
     // indicator updates with each reply.
     const [contextUsage, planUsage] = await Promise.all([
       readContextUsageImpl(turnRef, dbg),
-      readPlanUsageImpl(turnRef, dbg),
+      readPlanUsageForTurn(turnRef, dbg),
     ]);
     ctx.state.contextUsage = contextUsage;
     ctx.state.planUsage = planUsage;
     const responseModel = ctx.state.responseModel || procModel || null;
     await publisher.publishContextUsage({ message: ctx.message, state: ctx.state, model: procModel, sdkSessionId });
-    await publisher.publishPlanUsage({ message: ctx.message, state: ctx.state, sdkSessionId });
+    await publisher.publishPlanUsage({ message: ctx.message, state: ctx.state, sdkSessionId, runId, resumedSessionId });
 
     if (ctx.state.result?.isError) {
       await publisher.publishErrorResult({ message: ctx.message, state: ctx.state, responseModel, consumedSteerIds });
@@ -1511,10 +1582,17 @@ export function createClaudeSessionRunner({
     }
     // The transport is gone, so nothing new can be read — but usage already
     // captured on this context (a result seen before the stream died) still
-    // reaches the relay. Best-effort by definition of this path.
+    // reaches the relay, under the process the context ran in. Best-effort by
+    // definition of this path.
     if (ctx.state.contextUsage || ctx.state.planUsage) {
       await publisher.publishContextUsage({ message: ctx.message, state: ctx.state, model, sdkSessionId }).catch(() => {});
-      await publisher.publishPlanUsage({ message: ctx.message, state: ctx.state, sdkSessionId }).catch(() => {});
+      await publisher.publishPlanUsage({
+        message: ctx.message,
+        state: ctx.state,
+        sdkSessionId,
+        runId: ctx.runId || '',
+        resumedSessionId: ctx.resumedSessionId || '',
+      }).catch(() => {});
     }
     if (ctx.interrupted || aborted) {
       await publisher.publishFinalStream(ctx.message, ctx.state.lastStreamedText);
@@ -1769,7 +1847,13 @@ export function createClaudeSessionRunner({
         const agentLike = SUBAGENT_TASK_TYPES.has(String(task.taskType || ''));
         const pinnedModel = (task.toolUseId && processRef.subagentSpawns.get(task.toolUseId)) || '';
         const activity = (task.toolUseId && processRef.subagentActivity.get(task.toolUseId)) || {};
-        const model = agentLike ? (activity.model || pinnedModel || processRef.initModel || null) : null;
+        const knownModel = agentLike ? (activity.model || pinnedModel || processRef.initModel || null) : null;
+        // A backend's CLI names a sub-agent's model in Claude's terms (the
+        // spawn's "opus", a Claude id of a CLI without the alias pins): the
+        // badge shows the backend's model that runs it.
+        const model = knownModel && modelBackend?.subagentModel
+          ? (modelBackend.subagentModel(knownModel, processRef.initModel || processRef.model) || knownModel)
+          : knownModel;
         return {
           taskId,
           taskType: task.taskType,
@@ -2393,7 +2477,9 @@ export function createClaudeSessionRunner({
       // init lands, and skipping that init settled the message with a pointer
       // and dropped its real answer.
       if (!firstInit && proc.pendingDelivered.length) turnStartedForWaitingDeliveries();
-      persistNativeSessionId(sdkSessionId, sdkMessage.session_id).catch(() => {});
+      persistNativeSessionId(sdkSessionId, sdkMessage.session_id, {
+        cliStartedAt: backend && firstInit ? proc.spawnedAt : null,
+      }).catch(() => {});
       // Tracked on the process too (not only through the persist round-trip):
       // the workflow poller needs the native id to find the session dir even
       // when the persist call is still in flight or failed.
@@ -2402,7 +2488,9 @@ export function createClaudeSessionRunner({
       // normalizer never sees it — capture the CLI's actual model here and
       // seed it into every context at activation. Without this, a composer
       // set to `auto` published responses with model: null.
-      proc.initModel = String(sdkMessage.model || '').trim() || proc.initModel;
+      // A backend's CLI names the model in its own terms ("deepseek-flash[1m]").
+      const initModel = String(sdkMessage.model || '').trim();
+      proc.initModel = (modelBackend && initModel ? modelBackend.relayModel(initModel) : initModel) || proc.initModel;
       // A fresh init with no active turn AND nothing queued to deliver is the CLI
       // opening a turn on its own — a background-task continuation ("you will be
       // notified"). The real SDK does NOT emit a user-message replay for these
@@ -2541,7 +2629,8 @@ export function createClaudeSessionRunner({
       // the composer pinned a model (adaptProcess repins via setModel). An
       // `auto` composer keeps the CLI's own behavior — only the recorded
       // model follows the switch.
-      const fallbackModel = String(sdkMessage.fallbackModel || '').trim();
+      const reportedFallback = String(sdkMessage.fallbackModel || '').trim();
+      const fallbackModel = modelBackend && reportedFallback ? modelBackend.relayModel(reportedFallback) : reportedFallback;
       if (fallbackModel) {
         proc.initModel = fallbackModel;
         if (String(sdkMessage.scope || '').trim().toLowerCase() === 'session') {
@@ -3522,10 +3611,7 @@ export function createClaudeSessionRunner({
         }
         continue;
       }
-      await finalizeContextOnStreamEnd(ctx, {
-        aborted: processRef.aborted,
-        model: processRef.model,
-      }).catch(() => {});
+      await finalizeContextOnStreamEnd(ctx, { aborted: processRef.aborted, model: processRef.model }).catch(() => {});
     }
     for (const entry of stoppedSteers) {
       await settleFoldedSteeredEntry(entry).catch((error) => {
@@ -3546,10 +3632,12 @@ export function createClaudeSessionRunner({
     if (missingFolder) throw missingFolder;
     const relayMode = message.relayMode || 'agent';
     const model = resolvePerTurnModel(message);
-    const effort = normalizeClaudeEffort(message.reasoningEffort);
+    // A backend's effort is its own (DeepSeek: low/high/max), and so is its
+    // thinking switch (DeepSeek: always on).
+    const effort = modelBackend ? modelBackend.effortFor(message.reasoningEffort) : normalizeClaudeEffort(message.reasoningEffort);
     const autoCompactWindow = normalizeAutoCompactWindow(getAutoCompactWindow());
     const thinkingState = getThinking() || {};
-    const thinkingEnabled = parseThinkingEnabled(thinkingState.enabled);
+    const thinkingEnabled = modelBackend ? modelBackend.thinkingEnabled(effort) : parseThinkingEnabled(thinkingState.enabled);
     const thinkingDisplay = parseThinkingDisplay(thinkingState.display);
     const attribution = getAttribution() || null;
     const backgroundCommandLimitMs = getBackgroundCommandLimitMs() ?? null;
@@ -3557,6 +3645,13 @@ export function createClaudeSessionRunner({
     const processRef = {
       turn: null,
       abortController,
+      // Names this CLI process in its usage reports: the relay tells a
+      // report that fell behind one of the same process from a process
+      // that started counting over.
+      runId: randomUUID(),
+      // When the CLI was spawned, reported with its first init (see
+      // persistNativeSessionId).
+      spawnedAt: Date.now(),
       model,
       relayMode,
       effort,
@@ -3574,6 +3669,12 @@ export function createClaudeSessionRunner({
       thinkingBudget: null,
       appendClass: modeAppendClass(relayMode),
       permissionMode: permissionModeForRelayMode(relayMode),
+      // What only a fresh CLI of the backend takes (adaptProcess compares it).
+      spawnKey: modelBackend ? modelBackend.spawnKey(message, { model }) : '',
+      // Whether the API answered since the last result (noteApiTraffic), and
+      // the error a backend's init check ended the process with.
+      trafficSinceResult: false,
+      failClosed: null,
       liveTasks: new Map(),
       knownTasks: new Set(),
       // taskId → the row of a task that left the live set, until its
@@ -3602,6 +3703,8 @@ export function createClaudeSessionRunner({
       // from `resume`, updated on init) — the workflow poller's key into
       // `~/.claude/projects`.
       nativeSessionId: '',
+      // The session the process was spawned to resume ('' for a fresh one).
+      resumedSessionId: '',
       // tool_use id → explicitly pinned model of a subagent spawn block; the
       // task panel's model column resolves through this at publish time.
       subagentSpawns: new Map(),
@@ -3721,6 +3824,10 @@ export function createClaudeSessionRunner({
 
     const resume = String(resumeOverride || message.claudeNativeSessionId || claudeNativeSessionId || '').trim();
     processRef.nativeSessionId = resume;
+    // The session this process continues, for its usage reports: the CLI's
+    // first result then carries that session's earlier totals (see
+    // claude-turn-publisher.mjs, runningCounts).
+    processRef.resumedSessionId = resume;
     // The CLI resolves `resume` inside the project directory for *this* CWD, so
     // a session whose workspace root changed has to bring its transcript along
     // or every turn from here on fails with "No conversation found".
@@ -3752,6 +3859,7 @@ export function createClaudeSessionRunner({
         || '',
       ),
       remoteRelayTool: remoteRelayGate.isEnabled(),
+      backend,
       dbg,
     });
     processRef.lifecycleTimer = setInterval(() => evaluateLifecycle(), lifecyclePollMs);
@@ -3760,6 +3868,17 @@ export function createClaudeSessionRunner({
       let streamError = null;
       try {
         for await (const sdkMessage of processRef.turn) {
+          // A backend that checks the CLI's credential (the Claude API
+          // backend: the key's source on every init) stops the process on a
+          // wrong one before the init is handled: the open turns fail with
+          // its note (cleanupProcess), and nothing more is read.
+          const refused = refuseOnInit(processRef, sdkMessage);
+          if (refused) {
+            streamError = refused;
+            abortController.abort();
+            break;
+          }
+          noteApiTraffic(processRef, sdkMessage);
           await onSdkMessage(processRef, sdkMessage);
           syncDeliveryReadiness();
         }
@@ -3773,6 +3892,11 @@ export function createClaudeSessionRunner({
         try {
           processRef.turn.endInput?.();
         } catch {}
+        // The CLI refused a backend's live flag settings (its key and
+        // endpoint pins, claude-sdk-adapter.mjs): nothing was sent, and the
+        // SDK aborted the query, which reads like a stop. The open turns fail
+        // with that note instead.
+        if (!streamError && processRef.turn?.liveFlagSettingsError) streamError = processRef.turn.liveFlagSettingsError;
         await cleanupProcess(processRef, streamError);
       }
     })();
@@ -3780,6 +3904,42 @@ export function createClaudeSessionRunner({
     return processRef;
   }
 
+  /**
+   * The backend's verdict on a `system/init` (`checkInit`): null to go on, or
+   * the Error that ends the process. `afterTraffic` says whether the turn had
+   * already talked to the API since the last result.
+   */
+  function refuseOnInit(processRef, sdkMessage) {
+    // A backend checks its own credential; the subscription worker checks
+    // that the CLI took no API key (claude-subscription-key-check.mjs).
+    const checkInit = typeof backend?.checkInit === 'function'
+      ? backend.checkInit
+      : (backend ? null : checkClaudeSubscriptionInit);
+    if (typeof checkInit !== 'function') return null;
+    if (sdkMessage?.type !== 'system' || sdkMessage?.subtype !== 'init') return null;
+    if (!backend && sdkMessage.apiKeySource !== undefined && !isKnownApiKeySource(sdkMessage.apiKeySource) && !processRef.unknownKeySourceLogged) {
+      processRef.unknownKeySourceLogged = true;
+      dbg('init names an API key source this relay does not know; the subscription turn goes on', String(sdkMessage.apiKeySource).slice(0, 40));
+    }
+    let refused = null;
+    try {
+      refused = checkInit(sdkMessage, { afterTraffic: processRef.trafficSinceResult === true });
+    } catch (error) {
+      refused = error instanceof Error ? error : new Error(String(error));
+    }
+    if (!refused) return null;
+    processRef.failClosed = refused;
+    dbg('init refused by the backend', refused.code || '', refused.message);
+    return refused;
+  }
+
+  /** Whether the API has answered since the last result: a stream event or an assistant frame. */
+  function noteApiTraffic(processRef, sdkMessage) {
+    const type = sdkMessage?.type;
+    if (type === 'stream_event' || type === 'assistant') processRef.trafficSinceResult = true;
+    else if (type === 'result') processRef.trafficSinceResult = false;
+  }
+
   function expectSettingsReinit() {
     settingsReinitsOwed += 1;
     settingsWindowOpen = true;
@@ -3798,6 +3958,24 @@ export function createClaudeSessionRunner({
     return !proc.suppressingTurn;
   }
 
+  /**
+   * What keeps the live process from being released now, for the relay's
+   * billing swap ('' when nothing does, or there is no process): 'question',
+   * 'compaction', 'turn' or 'background'. The same conditions as
+   * canReleaseForRespawn, named.
+   */
+  function releaseHold() {
+    // A delivered message on its way in (waiting for a draining process or
+    // a cold spawn): a turn, though no process may exist yet.
+    if (admittingDeliveries > 0) return 'turn';
+    if (!proc || proc.closing || proc.aborted) return '';
+    if (proc.pendingControlRequests > 0) return 'question';
+    if (isCompacting() || Date.now() < proc.compactReplayUntil) return 'compaction';
+    if (proc.activeCtx || proc.pendingDelivered.length || proc.suppressingTurn) return 'turn';
+    if (proc.liveTasks.size || isContinuationImminent()) return 'background';
+    return '';
+  }
+
   /**
    * The running CLI's compaction window (the one it was spawned with) and
    * whether background work would block the respawn that applies another
@@ -3821,7 +3999,18 @@ export function createClaudeSessionRunner({
   async function adaptProcess(message, delivery = {}) {
     const relayMode = message.relayMode || 'agent';
     const model = resolvePerTurnModel(message);
-    const effort = normalizeClaudeEffort(message.reasoningEffort);
+    const effort = modelBackend ? modelBackend.effortFor(message.reasoningEffort) : normalizeClaudeEffort(message.reasoningEffort);
+
+    // A backend's effort, and the model its CLI pins Claude Code's aliases
+    // to, are read by the CLI at spawn only: a change takes a fresh process
+    // on the same session, when nothing lives in the old one. Busy, the
+    // delivery runs on the old process (setModel below) and the next
+    // turn-opening one tries again.
+    if (modelBackend && modelBackend.spawnKey(message, { model }) !== proc.spawnKey && canReleaseForRespawn()) {
+      gracefulShutdown('backend-spawn');
+      await drainClosingProcess(10_000);
+      return null;
+    }
 
     // A mode change that would alter the spawn-time system prompt append gets
     // a fresh process — but only when nothing lives in the old one.
@@ -3874,13 +4063,14 @@ export function createClaudeSessionRunner({
     const repinAfterFallback = Boolean(proc.modelFallback) && Boolean(model);
     if (model !== proc.model || repinAfterFallback) {
       expectSettingsReinit();
-      await Promise.resolve(proc.turn.setModel?.(model || undefined)).catch((error) => {
+      const cliModel = modelBackend && model ? modelBackend.cliModel(model) : model;
+      await Promise.resolve(proc.turn.setModel?.(cliModel || undefined)).catch((error) => {
         dbg('setModel failed', error?.message || String(error));
       });
       proc.model = model;
       if (model) proc.modelFallback = '';
     }
-    if (effort !== proc.effort) {
+    if (!modelBackend && effort !== proc.effort) {
       // 'ultracode' is not an effortLevel the CLI accepts — it maps to the
       // session-scoped ultracode/enableWorkflows flags (with the effort pinned
       // to the xhigh the flag implies); every other change clears those flags
@@ -3922,7 +4112,8 @@ export function createClaudeSessionRunner({
     const thinkingEnabled = parseThinkingEnabled(thinkingState.enabled);
     const thinkingDisplay = parseThinkingDisplay(thinkingState.display);
     let reassertDisplay = false;
-    if (thinkingEnabled !== proc.thinkingEnabled) {
+    // A backend's thinking is fixed at spawn (above).
+    if (!modelBackend && thinkingEnabled !== proc.thinkingEnabled) {
       if (thinkingEnabled === true) {
         // Enabling applies live. The display MUST be re-sent afterwards, in
         // this order: a session spawned with thinking off carries no display
@@ -4053,9 +4244,14 @@ export function createClaudeSessionRunner({
   function steeringState() {
     // A closing/aborted process is about to die — nothing about its last turn
     // should hold the composer of the worker that replaces it.
+    // `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.
     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,
       };
     }
     const ctx = proc.activeCtx || null;
@@ -4083,7 +4279,18 @@ export function createClaudeSessionRunner({
     // `supported` is the worker-advertised opt-in the client's composer reads
     // (the same flag the Copilot SDK worker publishes) — its only steering
     // gate, so every snapshot carries it, idle ones included.
-    return { turnActive, canSteer, holdReason, messageId, supported: true, autoCompactWindow };
+    const hold = releaseHold();
+    return {
+      turnActive,
+      canSteer,
+      holdReason,
+      messageId,
+      supported: true,
+      autoCompactWindow,
+      releasable: !hold,
+      releaseHold: hold || null,
+      backgroundTaskCount: proc.liveTasks.size,
+    };
   }
 
   /**
@@ -4108,6 +4315,20 @@ export function createClaudeSessionRunner({
   async function handlePendingPayload(pending) {
     const message = pending?.message || null;
     if (!message) return false;
+    // A Claude chat's row runs only on a worker of its billing: one of the
+    // other kind (a relay that missed a switch) goes back to the queue, with
+    // no retry penalty, for the worker the switch brings up.
+    const deliveredBilling = claudeBillingOf(message.billing || message.providerType);
+    if (deliveredBilling && claudeBillingOf(workerKind) && deliveredBilling !== workerKind) {
+      dbg('delivery of another billing handed back', message.id || '(no id)', `${deliveredBilling} != ${workerKind}`);
+      if (message.id) {
+        await api('POST', '/api/requeue', { messageId: message.id, class: 'kind-mismatch', ...attemptFields(message) }).catch((error) => {
+          if (isStaleAttemptError(error)) dbg('kind-mismatch hand-back refused as stale_attempt', message.id);
+          else dbg('kind-mismatch hand-back failed', message.id, error?.message || String(error));
+        });
+      }
+      return false;
+    }
     // An older relay (the worker updated on disk before the relay restarted)
     // treats the hand-back as a failed delivery — retry, backoff, worker
     // marked errored — so against one the message is pushed the legacy way.
@@ -4124,6 +4345,21 @@ export function createClaudeSessionRunner({
       syncDeliveryReadiness();
     };
     syncDeliveryReadiness();
+    // The relay replaced the previous worker for a billing switch: said once,
+    // on the first message this worker runs.
+    const billingSwap = pending?.settings?.billingSwap;
+    if (billingSwap && typeof billingSwap === 'object' && !billingSwapNoted) {
+      billingSwapNoted = true;
+      const to = claudeBillingOf(billingSwap.to) || workerKind;
+      publisher.postActivity(
+        message,
+        to === 'claude-api'
+          ? 'Restarted the session on the Claude API key (billing switch)'
+          : 'Restarted the session on the Claude subscription (billing switch)',
+        null,
+        { kind: 'billing_switch_respawn', from: claudeBillingOf(billingSwap.from) || null, to },
+      );
+    }
     // This delivery's own record: a window respawn taken for it (one at most).
     const delivery = { windowRespawn: null };
     // Its note goes on this message's row, once, whichever delivery's spawn
@@ -4155,7 +4391,7 @@ export function createClaudeSessionRunner({
         // Awaited only when there is one: a cold spawn with the decision
         // already in pushes synchronously.
         if (proc) await drainClosingProcess();
-        // The tool set is fixed per CLI process: let the remote_relay
+        // The tool set is fixed per CLI process: let the relay_tool
         // decision settle first. The worker's first delivery can arrive
         // before its startup GET has answered (seen live: 180 ms after the
         // spawn). ready() never rejects and is bounded by the gate's timeout.
@@ -4175,14 +4411,20 @@ export function createClaudeSessionRunner({
         // seconds (transcript load + first request); say so instead of
         // showing bare dots. Posted once here — not in spawnProcess — so a
         // push-race respawn cannot duplicate the line.
+        // In a DeepSeek chat the CLI is Claude Code talking to DeepSeek; the
+        // line names the backend so the wait is not read as a Claude turn.
+        const startingWhat = backend ? `Claude Code for ${backend.label || 'DeepSeek'}` : 'the Claude CLI';
         publisher.postActivity(message, (respawnResume || message.claudeNativeSessionId || claudeNativeSessionId)
-          ? 'Starting the Claude CLI (cold start — resuming the session transcript)…'
-          : 'Starting the Claude CLI (cold start)…');
+          ? `Starting ${startingWhat} (cold start — resuming the session transcript)…`
+          : `Starting ${startingWhat} (cold start)…`);
       }
       // Released for the window, then joined a process another delivery
       // spawned in the meantime.
       noteWindowRespawn();
-      const content = buildClaudeUserContent(message);
+      // A model that takes no image input gets every image by its path.
+      const content = buildClaudeUserContent(message, {
+        embedImages: modelBackend ? modelBackend.acceptsImages(resolvePerTurnModel(message)) : true,
+      });
       for (let attempt = 0; attempt < 2; attempt += 1) {
         const procRef = proc;
         const ctx = createDeliveredContext(message);
@@ -4314,6 +4556,7 @@ export function createClaudeSessionRunner({
   }
 
   return {
+    workerKind,
     handlePendingPayload,
     canAcceptSteering,
     isDeliveryHeld,