@oar-sh/oar 0.9.16 → 0.9.18

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

@@ -0,0 +1,269 @@
+// The body of the Claude session worker (claude-session-worker.mjs) and of the
+// DeepSeek one (../deepseek-worker/deepseek-session-worker.mjs): a
+// per-conversation Node process that speaks the same relay contracts as the
+// Copilot CLI workers (worker WebSocket, heartbeat, control polling, activity
+// channels) and executes turns through the Claude Agent SDK. A `backend`
+// (null for Claude) points the CLI elsewhere; see claude-session-process.mjs.
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import {
+  loadTokenFromConfig,
+  resolveRelayServerUrl,
+} from '../../shared/worker-runtime/config-loader.mjs';
+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 { createControlPoller } from '../../shared/control-poller.mjs';
+import { resolveDeliveredAutoCompactWindow } from '../../shared/auto-compact-window.mjs';
+import { resolveDeliveredThinking } from '../../shared/claude-thinking.mjs';
+import { resolveDeliveredAttribution } from '../../shared/claude-attribution.mjs';
+import {
+  DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS,
+  resolveDeliveredClaudeBackgroundCommandLimitMs,
+} from '../../shared/claude-background-command-limit.mjs';
+import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
+import { createClaudeSessionRunner } from './claude-session-process.mjs';
+import { createRunnerLinkBridge, failSettlingRowsOnShutdown } from './claude-worker-link-wiring.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HEARTBEAT_MS = 10_000;
+
+function parseSessionIdArg(argv = process.argv) {
+  const index = argv.indexOf('--session-id');
+  if (index !== -1 && argv[index + 1]) return String(argv[index + 1]).trim();
+  const inline = argv.find((arg) => String(arg || '').startsWith('--session-id='));
+  if (inline) return String(inline.split('=')[1] || '').trim();
+  return String(process.env.SESSION_ID || '').trim();
+}
+
+export async function runClaudeSessionWorker({
+  // The log line prefix and the name the crash guard reports.
+  logTag = 'claude-worker',
+  workerName = 'claude-session-worker',
+  // The model of a session whose delivery names none.
+  defaultModel = String(process.env.CLAUDE_RELAY_MODEL || '').trim(),
+  // Where the CLI's turns go and what it reports; null is Anthropic's API
+  // through the host's Claude login.
+  backend = null,
+} = {}) {
+  const dbg = (...parts) => {
+    const timestamp = new Date().toISOString();
+    console.log(`[${logTag} ${timestamp}]`, ...parts);
+  };
+  const sdkSessionId = parseSessionIdArg();
+  if (!sdkSessionId) {
+    console.error(`${workerName}: missing --session-id`);
+    process.exit(2);
+  }
+
+  const configPath = String(process.env.COPILOT_WEB_RELAY_CONFIG || '').trim()
+    || path.resolve(__dirname, '..', 'config.json');
+  const serverUrl = resolveRelayServerUrl({ configPath });
+  const token = loadTokenFromConfig(configPath);
+  const cwd = String(process.env.COPILOT_WORKSPACE_ROOT || '').trim() || process.cwd();
+  const pathToClaudeCodeExecutable = String(process.env.CLAUDE_CODE_EXECUTABLE || '').trim();
+  // How long background tasks alone may keep the CLI process alive (0 = no
+  // limit). Seeded from the environment; refreshed from every delivery payload
+  // so the settings slider applies without a worker restart.
+  let backgroundTaskTimeoutMs = Number(process.env.CLAUDE_RELAY_BACKGROUND_TASK_TIMEOUT_MS) || 0;
+  // Per-conversation auto-compact window (token count, null = Auto); arrives
+  // piggybacked on each queue delivery, like the timeouts above.
+  let autoCompactWindow = null;
+  // Per-conversation thinking control ({enabled: bool|null, display}); same
+  // piggyback. enabled null = host default; display defaults to 'summarized'
+  // (today's behavior — visible thought bubbles).
+  let thinking = resolveDeliveredThinking(null, null);
+  // What this session's commits and PRs say; same piggyback. null = the
+  // CLI's own attribution (vanilla).
+  let attribution = null;
+  // How long a backgrounded Bash command may run without its own timeout;
+  // same piggyback, applied when the CLI process is next spawned.
+  let backgroundCommandLimitMs = DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS;
+
+  const api = createApiClient({
+    serverUrl,
+    token,
+    getHeaders: () => ({
+      'X-Relay-Process-Pid': String(process.pid),
+      'X-Relay-Parent-Pid': String(process.ppid),
+      'X-Relay-Session-Id': sdkSessionId,
+      'X-Relay-Conversation-Id': sdkSessionId,
+    }),
+  });
+
+  const controlPoller = createControlPoller({
+    api,
+    sdkSessionId,
+    abortAckNote: 'claude query aborted',
+    // Backgrounded subagents are SDK tasks; their relay run id is the
+    // spawning tool_use id, which maps to a stoppable task id. (Late-bound:
+    // controls only poll while a turn is live, well after turnRunner exists.)
+    onAbortSubagent: (subagentRunId) => turnRunner.stopBackgroundTaskByToolUseId(subagentRunId),
+    dbg,
+  });
+  const linkBridge = createRunnerLinkBridge();
+  // Late-bound: the heartbeat controller is built after the runner.
+  let heartbeat = null;
+  const turnRunner = createClaudeSessionRunner({
+    api,
+    sdkSessionId,
+    cwd,
+    defaultModel,
+    controlPoller,
+    pathToClaudeCodeExecutable,
+    backend,
+    idleShutdownMs: Number(process.env.CLAUDE_RELAY_IDLE_SHUTDOWN_MS) > 0
+      ? Number(process.env.CLAUDE_RELAY_IDLE_SHUTDOWN_MS)
+      : undefined,
+    // 0 disables the watchdog (matching the background-task timeout's
+    // 0 = no-limit convention); unset/invalid falls back to the default.
+    pendingDeliveredTimeoutMs: (() => {
+      const raw = String(process.env.CLAUDE_RELAY_PENDING_DELIVERED_TIMEOUT_MS || '').trim();
+      const parsed = Number(raw);
+      return raw !== '' && Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+    })(),
+    getBackgroundTaskTimeoutMs: () => backgroundTaskTimeoutMs,
+    getAutoCompactWindow: () => autoCompactWindow,
+    getThinking: () => thinking,
+    getAttribution: () => attribution,
+    getBackgroundCommandLimitMs: () => backgroundCommandLimitMs,
+    // A readiness flip is a hold starting or ending (question card,
+    // compaction, a turn-opening delivery): the steering snapshot changed
+    // with it, so it goes out now rather than on the next 10 s heartbeat.
+    onBackgroundTaskSetStale: () => heartbeat?.requestPulse(),
+    onDeliveryReadinessChange: (ready) => {
+      linkBridge.onDeliveryReadinessChange(ready);
+      heartbeat?.requestPulse();
+    },
+    canHandBackHeldDelivery: () => linkBridge.canHandBackHeldDelivery(),
+    dbg,
+  });
+
+  let heartbeatTimer = null;
+  heartbeat = createHeartbeatController({
+    api,
+    // What this worker runs on: the relay hands it only rows of that billing.
+    workerKind: turnRunner.workerKind,
+    pollMs: HEARTBEAT_MS,
+    getSessionReady: () => true,
+    getHeartbeatTimer: () => heartbeatTimer,
+    setHeartbeatTimer: (timer) => { heartbeatTimer = timer; },
+    getActiveQueueMessageId: () => turnRunner.getActiveQueueMessageId(),
+    // The runner reports { id, attemptId } entries; the heartbeat's claim
+    // payload is id-only (its String() coercion would mangle an object), while
+    // the crash guard below takes the entries whole so its requeues stay
+    // fenced to this attempt.
+    getActiveQueueMessageIds: () => turnRunner.getActiveQueueMessageIds().map((entry) => entry.id),
+    // Composer steering snapshot. Holds reach the relay within a pulse window
+    // (onDeliveryReadinessChange above) and a relay that just came up gets it
+    // on its first hello; the periodic beat only backstops the rest.
+    getSteeringState: () => turnRunner.steeringState(),
+    // Consumed rows the runner could not fail itself; the relay fails them.
+    getSettleFailed: () => turnRunner.getSettleFailed(),
+    onSettleFailedHandled: (ids) => turnRunner.acknowledgeSettleFailed(ids),
+    // The relay holds the task set in memory only: the digest of the live
+    // task ids rides every beat, and a relay that is out of step (it
+    // restarted, a post was lost) asks for the set again.
+    getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
+    onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
+    onAnswered: () => turnRunner.flushKeptTaskSettles(),
+  });
+
+  const wsLink = createWorkerWebSocketLink({
+    serverUrl,
+    token,
+    dbg,
+    getSessionReady: () => true,
+    // Mid-turn steering: while a turn is running and the runner can absorb
+    // another message into it, the link keeps signalling readiness, so a
+    // message sent while Claude is thinking is pushed into the live turn
+    // instead of waiting for the result (docs/plans/2026-09-19-claude-mid-
+    // turn-steering.md).
+    getSteeringReady: () => turnRunner.canAcceptSteering(),
+    // A hold (open question card, compaction, adoption) suppresses readiness
+    // even between deliveries — a delivery drawn into it is only handed back.
+    getDeliveryHeld: () => turnRunner.isDeliveryHeld(),
+    // A relay that just (re)started knows nothing of this worker until it
+    // heartbeats; the composer's steering snapshot rides that beat, and so
+    // does the digest that makes the relay ask for the background tasks.
+    onServerHello: () => heartbeat.requestPulse(),
+    getSessionId: () => sdkSessionId,
+    getPid: () => process.pid,
+    workerKind: turnRunner.workerKind,
+    onDeliver: async (pending, reason) => {
+      dbg('queue.deliver received', `reason=${reason}`, `msgId=${pending?.message?.id || 'none'}`);
+      const deliveredTimeout = Number(pending?.settings?.backgroundTaskTimeoutMs);
+      if (Number.isFinite(deliveredTimeout) && deliveredTimeout >= 0) {
+        backgroundTaskTimeoutMs = deliveredTimeout;
+      }
+      // Absent (an older relay) leaves the last known value alone; an explicit
+      // null is the user choosing Auto and must clear the pin.
+      autoCompactWindow = resolveDeliveredAutoCompactWindow(autoCompactWindow, pending?.settings);
+      // Same presence semantics as the window: absent keys (an older relay)
+      // keep the last known state; an explicit null on thinkingEnabled is the
+      // user choosing Host default.
+      thinking = resolveDeliveredThinking(thinking, pending?.settings);
+      attribution = resolveDeliveredAttribution(attribution, pending?.settings);
+      backgroundCommandLimitMs = resolveDeliveredClaudeBackgroundCommandLimitMs(backgroundCommandLimitMs, pending?.settings);
+      try {
+        return await turnRunner.handlePendingPayload(pending);
+      } catch (error) {
+        dbg('turn handling failed', error?.message || String(error));
+        return false;
+      }
+    },
+    onControl: async (control) => {
+      const type = String(control?.type || '').trim();
+      if (type === 'stop_background_task') {
+        const taskId = String(control?.taskId || '').trim();
+        dbg('stop background task control', taskId);
+        await turnRunner.stopBackgroundTask(taskId);
+        return;
+      }
+      if (type === 'task_output_snapshot') {
+        // A console opened on a shell task with no output file: the CLI's
+        // last 8 KiB goes to the relay, which serves it as a static tail.
+        const taskId = String(control?.taskId || '').trim();
+        dbg('task output snapshot control', taskId);
+        await turnRunner.snapshotTaskOutput(taskId);
+        return;
+      }
+      dbg('unknown worker control ignored', type || '(none)');
+    },
+  });
+  linkBridge.attach(wsLink);
+
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    dbg(`shutting down (${signal})`);
+    try { wsLink.stop(); } catch {}
+    try { heartbeat.stopHeartbeat(); } catch {}
+    try { controlPoller.stop(); } catch {}
+    // Consumed steers still settling must fail, not be left for dead-worker
+    // recovery to requeue and run twice (same 2 s cap as the crash guard).
+    try {
+      const failed = await failSettlingRowsOnShutdown({ api, runner: turnRunner, timeoutMs: 2_000 });
+      if (failed) dbg(`failed ${failed} settling row(s) before exit`);
+    } catch {}
+    // Hard-close the persistent CLI process; a worker teardown cannot save
+    // its background tasks, and the orphan-notification replay on the next
+    // resume reports whatever they left behind.
+    try { turnRunner.shutdown({ graceful: false }); } catch {}
+    process.exit(0);
+  };
+  process.on('SIGTERM', () => { void shutdown('SIGTERM'); });
+  process.on('SIGINT', () => { void shutdown('SIGINT'); });
+  installWorkerCrashGuard({
+    api,
+    workerName,
+    getActiveQueueMessageIds: () => turnRunner.getActiveQueueMessageIds(),
+    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}` : ''}`);
+  heartbeat.startHeartbeat();
+  wsLink.start();
+}

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

@@ -3,265 +3,14 @@
 // relay contracts as the Copilot CLI workers (worker WebSocket, heartbeat,
 // control polling, activity channels) but executes turns through the Claude
 // Agent SDK using the host machine's logged-in Claude credentials.
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-import {
-  loadTokenFromConfig,
-  resolveRelayServerUrl,
-} from '../../shared/worker-runtime/config-loader.mjs';
-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 { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
-import { createControlPoller } from '../../shared/control-poller.mjs';
-import { resolveDeliveredAutoCompactWindow } from '../../shared/auto-compact-window.mjs';
-import { resolveDeliveredThinking } from '../../shared/claude-thinking.mjs';
-import { resolveDeliveredAttribution } from '../../shared/claude-attribution.mjs';
-import {
-  DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS,
-  resolveDeliveredClaudeBackgroundCommandLimitMs,
-} from '../../shared/claude-background-command-limit.mjs';
-import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
-import { createClaudeSessionRunner } from './claude-session-process.mjs';
-import { createRunnerLinkBridge, failSettlingRowsOnShutdown } from './claude-worker-link-wiring.mjs';
+import { runClaudeSessionWorker } from './claude-session-worker-main.mjs';
 
 // Windows console launch: the launcher names the worker log, this copies
 // stdout/stderr into it. A no-op wherever the launcher redirects instead.
 installWorkerLogFile();
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const HEARTBEAT_MS = 10_000;
-
-function parseSessionIdArg(argv = process.argv) {
-  const index = argv.indexOf('--session-id');
-  if (index !== -1 && argv[index + 1]) return String(argv[index + 1]).trim();
-  const inline = argv.find((arg) => String(arg || '').startsWith('--session-id='));
-  if (inline) return String(inline.split('=')[1] || '').trim();
-  return String(process.env.SESSION_ID || '').trim();
-}
-
-function dbg(...parts) {
-  const timestamp = new Date().toISOString();
-  console.log(`[claude-worker ${timestamp}]`, ...parts);
-}
-
-async function main() {
-  const sdkSessionId = parseSessionIdArg();
-  if (!sdkSessionId) {
-    console.error('claude-session-worker: missing --session-id');
-    process.exit(2);
-  }
-
-  const configPath = String(process.env.COPILOT_WEB_RELAY_CONFIG || '').trim()
-    || path.resolve(__dirname, '..', 'config.json');
-  const serverUrl = resolveRelayServerUrl({ configPath });
-  const token = loadTokenFromConfig(configPath);
-  const cwd = String(process.env.COPILOT_WORKSPACE_ROOT || '').trim() || process.cwd();
-  const defaultModel = String(process.env.CLAUDE_RELAY_MODEL || '').trim();
-  const pathToClaudeCodeExecutable = String(process.env.CLAUDE_CODE_EXECUTABLE || '').trim();
-  // How long background tasks alone may keep the CLI process alive (0 = no
-  // limit). Seeded from the environment; refreshed from every delivery payload
-  // so the settings slider applies without a worker restart.
-  let backgroundTaskTimeoutMs = Number(process.env.CLAUDE_RELAY_BACKGROUND_TASK_TIMEOUT_MS) || 0;
-  // Per-conversation auto-compact window (token count, null = Auto); arrives
-  // piggybacked on each queue delivery, like the timeouts above.
-  let autoCompactWindow = null;
-  // Per-conversation thinking control ({enabled: bool|null, display}); same
-  // piggyback. enabled null = host default; display defaults to 'summarized'
-  // (today's behavior — visible thought bubbles).
-  let thinking = resolveDeliveredThinking(null, null);
-  // What this session's commits and PRs say; same piggyback. null = the
-  // CLI's own attribution (vanilla).
-  let attribution = null;
-  // How long a backgrounded Bash command may run without its own timeout;
-  // same piggyback, applied when the CLI process is next spawned.
-  let backgroundCommandLimitMs = DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS;
-
-  const api = createApiClient({
-    serverUrl,
-    token,
-    getHeaders: () => ({
-      'X-Relay-Process-Pid': String(process.pid),
-      'X-Relay-Parent-Pid': String(process.ppid),
-      'X-Relay-Session-Id': sdkSessionId,
-      'X-Relay-Conversation-Id': sdkSessionId,
-    }),
-  });
-
-  const controlPoller = createControlPoller({
-    api,
-    sdkSessionId,
-    abortAckNote: 'claude query aborted',
-    // Backgrounded subagents are SDK tasks; their relay run id is the
-    // spawning tool_use id, which maps to a stoppable task id. (Late-bound:
-    // controls only poll while a turn is live, well after turnRunner exists.)
-    onAbortSubagent: (subagentRunId) => turnRunner.stopBackgroundTaskByToolUseId(subagentRunId),
-    dbg,
-  });
-  const linkBridge = createRunnerLinkBridge();
-  // Late-bound: the heartbeat controller is built after the runner.
-  let heartbeat = null;
-  const turnRunner = createClaudeSessionRunner({
-    api,
-    sdkSessionId,
-    cwd,
-    defaultModel,
-    controlPoller,
-    pathToClaudeCodeExecutable,
-    idleShutdownMs: Number(process.env.CLAUDE_RELAY_IDLE_SHUTDOWN_MS) > 0
-      ? Number(process.env.CLAUDE_RELAY_IDLE_SHUTDOWN_MS)
-      : undefined,
-    // 0 disables the watchdog (matching the background-task timeout's
-    // 0 = no-limit convention); unset/invalid falls back to the default.
-    pendingDeliveredTimeoutMs: (() => {
-      const raw = String(process.env.CLAUDE_RELAY_PENDING_DELIVERED_TIMEOUT_MS || '').trim();
-      const parsed = Number(raw);
-      return raw !== '' && Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
-    })(),
-    getBackgroundTaskTimeoutMs: () => backgroundTaskTimeoutMs,
-    getAutoCompactWindow: () => autoCompactWindow,
-    getThinking: () => thinking,
-    getAttribution: () => attribution,
-    getBackgroundCommandLimitMs: () => backgroundCommandLimitMs,
-    // A readiness flip is a hold starting or ending (question card,
-    // compaction, a turn-opening delivery): the steering snapshot changed
-    // with it, so it goes out now rather than on the next 10 s heartbeat.
-    onBackgroundTaskSetStale: () => heartbeat?.requestPulse(),
-    onDeliveryReadinessChange: (ready) => {
-      linkBridge.onDeliveryReadinessChange(ready);
-      heartbeat?.requestPulse();
-    },
-    canHandBackHeldDelivery: () => linkBridge.canHandBackHeldDelivery(),
-    dbg,
-  });
-
-  let heartbeatTimer = null;
-  heartbeat = createHeartbeatController({
-    api,
-    pollMs: HEARTBEAT_MS,
-    getSessionReady: () => true,
-    getHeartbeatTimer: () => heartbeatTimer,
-    setHeartbeatTimer: (timer) => { heartbeatTimer = timer; },
-    getActiveQueueMessageId: () => turnRunner.getActiveQueueMessageId(),
-    // The runner reports { id, attemptId } entries; the heartbeat's claim
-    // payload is id-only (its String() coercion would mangle an object), while
-    // the crash guard below takes the entries whole so its requeues stay
-    // fenced to this attempt.
-    getActiveQueueMessageIds: () => turnRunner.getActiveQueueMessageIds().map((entry) => entry.id),
-    // Composer steering snapshot. Holds reach the relay within a pulse window
-    // (onDeliveryReadinessChange above) and a relay that just came up gets it
-    // on its first hello; the periodic beat only backstops the rest.
-    getSteeringState: () => turnRunner.steeringState(),
-    // Consumed rows the runner could not fail itself; the relay fails them.
-    getSettleFailed: () => turnRunner.getSettleFailed(),
-    onSettleFailedHandled: (ids) => turnRunner.acknowledgeSettleFailed(ids),
-    // The relay holds the task set in memory only: the digest of the live
-    // task ids rides every beat, and a relay that is out of step (it
-    // restarted, a post was lost) asks for the set again.
-    getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
-    onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
-    onAnswered: () => turnRunner.flushKeptTaskSettles(),
-  });
-
-  const wsLink = createWorkerWebSocketLink({
-    serverUrl,
-    token,
-    dbg,
-    getSessionReady: () => true,
-    // Mid-turn steering: while a turn is running and the runner can absorb
-    // another message into it, the link keeps signalling readiness, so a
-    // message sent while Claude is thinking is pushed into the live turn
-    // instead of waiting for the result (docs/plans/2026-09-19-claude-mid-
-    // turn-steering.md).
-    getSteeringReady: () => turnRunner.canAcceptSteering(),
-    // A hold (open question card, compaction, adoption) suppresses readiness
-    // even between deliveries — a delivery drawn into it is only handed back.
-    getDeliveryHeld: () => turnRunner.isDeliveryHeld(),
-    // A relay that just (re)started knows nothing of this worker until it
-    // heartbeats; the composer's steering snapshot rides that beat, and so
-    // does the digest that makes the relay ask for the background tasks.
-    onServerHello: () => heartbeat.requestPulse(),
-    getSessionId: () => sdkSessionId,
-    getPid: () => process.pid,
-    onDeliver: async (pending, reason) => {
-      dbg('queue.deliver received', `reason=${reason}`, `msgId=${pending?.message?.id || 'none'}`);
-      const deliveredTimeout = Number(pending?.settings?.backgroundTaskTimeoutMs);
-      if (Number.isFinite(deliveredTimeout) && deliveredTimeout >= 0) {
-        backgroundTaskTimeoutMs = deliveredTimeout;
-      }
-      // Absent (an older relay) leaves the last known value alone; an explicit
-      // null is the user choosing Auto and must clear the pin.
-      autoCompactWindow = resolveDeliveredAutoCompactWindow(autoCompactWindow, pending?.settings);
-      // Same presence semantics as the window: absent keys (an older relay)
-      // keep the last known state; an explicit null on thinkingEnabled is the
-      // user choosing Host default.
-      thinking = resolveDeliveredThinking(thinking, pending?.settings);
-      attribution = resolveDeliveredAttribution(attribution, pending?.settings);
-      backgroundCommandLimitMs = resolveDeliveredClaudeBackgroundCommandLimitMs(backgroundCommandLimitMs, pending?.settings);
-      try {
-        return await turnRunner.handlePendingPayload(pending);
-      } catch (error) {
-        dbg('turn handling failed', error?.message || String(error));
-        return false;
-      }
-    },
-    onControl: async (control) => {
-      const type = String(control?.type || '').trim();
-      if (type === 'stop_background_task') {
-        const taskId = String(control?.taskId || '').trim();
-        dbg('stop background task control', taskId);
-        await turnRunner.stopBackgroundTask(taskId);
-        return;
-      }
-      if (type === 'task_output_snapshot') {
-        // A console opened on a shell task with no output file: the CLI's
-        // last 8 KiB goes to the relay, which serves it as a static tail.
-        const taskId = String(control?.taskId || '').trim();
-        dbg('task output snapshot control', taskId);
-        await turnRunner.snapshotTaskOutput(taskId);
-        return;
-      }
-      dbg('unknown worker control ignored', type || '(none)');
-    },
-  });
-  linkBridge.attach(wsLink);
-
-  let shuttingDown = false;
-  const shutdown = async (signal) => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    dbg(`shutting down (${signal})`);
-    try { wsLink.stop(); } catch {}
-    try { heartbeat.stopHeartbeat(); } catch {}
-    try { controlPoller.stop(); } catch {}
-    // Consumed steers still settling must fail, not be left for dead-worker
-    // recovery to requeue and run twice (same 2 s cap as the crash guard).
-    try {
-      const failed = await failSettlingRowsOnShutdown({ api, runner: turnRunner, timeoutMs: 2_000 });
-      if (failed) dbg(`failed ${failed} settling row(s) before exit`);
-    } catch {}
-    // Hard-close the persistent CLI process; a worker teardown cannot save
-    // its background tasks, and the orphan-notification replay on the next
-    // resume reports whatever they left behind.
-    try { turnRunner.shutdown({ graceful: false }); } catch {}
-    process.exit(0);
-  };
-  process.on('SIGTERM', () => { void shutdown('SIGTERM'); });
-  process.on('SIGINT', () => { void shutdown('SIGINT'); });
-  installWorkerCrashGuard({
-    api,
-    workerName: 'claude-session-worker',
-    getActiveQueueMessageIds: () => turnRunner.getActiveQueueMessageIds(),
-    onBeforeExit: () => { try { turnRunner.shutdown({ graceful: false }); } catch {} },
-  });
-
-  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'}`);
-  heartbeat.startHeartbeat();
-  wsLink.start();
-}
-
-main().catch((error) => {
+runClaudeSessionWorker().catch((error) => {
   console.error('claude-session-worker fatal:', error?.stack || error?.message || error);
   process.exit(1);
 });

package/server/claude-worker/claude-subscription-key-check.mjs

@@ -0,0 +1,64 @@
+// The subscription side of the Claude billing check (plan decision 4).
+//
+// A Claude chat on the host's subscription must never run on an API key
+// without being asked: the key's owner would pay. The worker strips every
+// Anthropic credential from the CLI's environment (WP0), but a settings
+// file's `env.ANTHROPIC_API_KEY`, an `apiKeyHelper` or a Console `/login`
+// can still hand Claude Code a key. Its `system/init` names where the
+// credential came from (`apiKeySource`); a turn that comes up on an API key
+// is stopped there, as the Claude API worker stops one that comes up on
+// anything but its key (claude-api-backend.mjs, checkClaudeApiInit). At most
+// the one request that may beat the init has gone out (decision 24).
+
+export const CLAUDE_SUBSCRIPTION_KEY_SOURCE_CODE = 'subscription-key-source';
+
+// The sources that bill an API key, not the subscription: a key in the
+// environment (a settings file's env block), a helper that prints one, and
+// the key a Console login keeps. Every other source (`none`, `oauth`, ...)
+// lets the turn go on; one the relay does not know is logged.
+export const API_BILLED_KEY_SOURCES = Object.freeze(['ANTHROPIC_API_KEY', 'apiKeyHelper', '/login managed key']);
+
+const KNOWN_KEY_SOURCES = Object.freeze([
+  ...API_BILLED_KEY_SOURCES,
+  'none',
+  'user',
+  'project',
+  'org',
+  'temporary',
+  'oauth',
+]);
+
+const GUIDANCE = 'Remove ANTHROPIC_API_KEY from the env of the host\'s Claude Code settings (~/.claude/settings.json, '
+  + 'or the folder\'s .claude/settings*.json), remove an apiKeyHelper, or sign the Console login out, then send the '
+  + 'message again. To run this chat on the API key saved in Settings, switch its billing to API key.';
+
+/** Whether a source the CLI named is one the relay knows. */
+export function isKnownApiKeySource(value) {
+  return KNOWN_KEY_SOURCES.includes(String(value ?? ''));
+}
+
+/**
+ * Null when the CLI's `system/init` came up without an API key, else the
+ * Error that stops the turn. `afterTraffic`: the turn had already talked to
+ * the API, so one request may have gone out on that key.
+ */
+export function checkClaudeSubscriptionInit(sdkMessage, { afterTraffic = false } = {}) {
+  if (!sdkMessage || sdkMessage.type !== 'system' || sdkMessage.subtype !== 'init') return null;
+  const source = typeof sdkMessage.apiKeySource === 'string' ? sdkMessage.apiKeySource : '';
+  if (!API_BILLED_KEY_SOURCES.includes(source)) return null;
+  const error = new Error(
+    `Claude Code took an API key for this subscription turn (source "${source}"), so the turn was stopped: `
+    + 'it would have been billed to that key, not the subscription.'
+    + (afterTraffic ? ' At most one request may have gone out on that key.' : ''),
+  );
+  error.code = CLAUDE_SUBSCRIPTION_KEY_SOURCE_CODE;
+  error.apiKeySource = source;
+  error.guidance = GUIDANCE;
+  return error;
+}
+
+/** `{ code, guidance }` for a turn the check stopped, else null (the publisher's describeFailure). */
+export function describeClaudeSubscriptionFailure(_errorText, { error = null } = {}) {
+  if (error?.code !== CLAUDE_SUBSCRIPTION_KEY_SOURCE_CODE) return null;
+  return { code: CLAUDE_SUBSCRIPTION_KEY_SOURCE_CODE, guidance: error.guidance || GUIDANCE };
+}

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

@@ -49,6 +49,14 @@ export const CLAUDE_ACCOUNT_GUIDANCE =
   + 'another one. Then send the message again.';
 export const CLAUDE_MODEL_GUIDANCE = 'Choose another model for this conversation, then send the message again.';
 
+// A spawn stopped because Claude Code did not take a backend's connection
+// settings over its control channel (claude-sdk-adapter.mjs,
+// `liveFlagSettings`): nothing was sent.
+export const CLAUDE_LIVE_FLAG_SETTINGS_CODE = 'claude-live-flag-settings';
+export const CLAUDE_LIVE_FLAG_SETTINGS_GUIDANCE =
+  'Send the message again. If it fails again, the Claude Code the relay runs does not take these settings: '
+  + 'update the relay, and check its log for the reason.';
+
 function codeFromText(text) {
   if (ACCOUNT_ACCESS_TEXT.test(text)) return 'account-access';
   if (BILLING_TEXT.test(text)) return 'billing_error';