@oar-sh/oar 0.9.5 → 0.9.7

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

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Claude Cloud session worker: a per-conversation Node process that speaks
+// the same relay contracts as the Claude/Cursor/Grok workers, but runs no
+// agent itself. The agent and its clone live in a Claude Code cloud session;
+// this process sends the user's messages there and follows the session's
+// event stream (claude-cloud-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 { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
+import { createControlPoller } from '../../shared/control-poller.mjs';
+import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
+import { createClaudeCloudCredentials } from '../../shared/claude-cloud/credentials.mjs';
+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';
+
+// 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-cloud-worker ${timestamp}]`, ...parts);
+}
+
+async function main() {
+  const sdkSessionId = parseSessionIdArg();
+  if (!sdkSessionId) {
+    console.error('claude-cloud-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 defaultModel = String(process.env.CLAUDE_CLOUD_RELAY_MODEL || '').trim();
+
+  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,
+    }),
+  });
+
+  // The Claude CLI's login, read by the client's own module (the credentials
+  // file, or CLAUDE_CODE_OAUTH_TOKEN where the relay runs on one): this
+  // process never logs it. A login that has run out is nudged through the
+  // relay, which can run the CLI (`claude auth status` refreshes a login
+  // whose refresh token is still good); the file is read again afterwards.
+  // The base URL is the Anthropic API unless a test names a fake one on this
+  // machine (base-url.mjs takes nothing else).
+  const cloud = createClaudeCloudClient({
+    credentials: createClaudeCloudCredentials({
+      nudge: async () => {
+        const answer = await api('POST', '/api/claude-cloud/login-nudge', {});
+        dbg('login nudge', answer?.nudged ? 'ran' : 'skipped', answer?.expired ? 'still expired' : `expires ${answer?.expiresAt || '?'}`);
+      },
+    }),
+    baseUrl: resolveClaudeCloudBaseUrl(process.env),
+  });
+
+  const controlPoller = createControlPoller({
+    api,
+    sdkSessionId,
+    abortAckNote: 'cloud turn interrupted',
+    dbg,
+  });
+  const runner = createClaudeCloudSessionRunner({
+    api,
+    cloud,
+    sdkSessionId,
+    defaultModel,
+    controlPoller,
+    dbg,
+  });
+
+  let heartbeatTimer = null;
+  const heartbeat = createHeartbeatController({
+    api,
+    pollMs: HEARTBEAT_MS,
+    getSessionReady: () => true,
+    getHeartbeatTimer: () => heartbeatTimer,
+    setHeartbeatTimer: (timer) => { heartbeatTimer = timer; },
+    getActiveQueueMessageId: () => runner.getActiveQueueMessageId(),
+  });
+
+  const wsLink = createWorkerWebSocketLink({
+    serverUrl,
+    token,
+    dbg,
+    getSessionReady: () => true,
+    getSessionId: () => sdkSessionId,
+    getPid: () => process.pid,
+    onDeliver: async (pending, reason) => {
+      dbg('queue.deliver received', `reason=${reason}`, `msgId=${pending?.message?.id || 'none'}`);
+      try {
+        return await runner.handlePendingPayload(pending);
+      } catch (error) {
+        dbg('turn handling failed', error?.message || String(error));
+        return false;
+      }
+    },
+  });
+
+  const shutdown = async (signal) => {
+    dbg(`shutting down (${signal})`);
+    try { wsLink.stop(); } catch {}
+    try { heartbeat.stopHeartbeat(); } catch {}
+    try { controlPoller.stop(); } catch {}
+    // The cloud session is left as it is: a turn in flight keeps running
+    // there, and the next worker finds it through the stored sequence number.
+    try { await runner.dispose(); } catch {}
+    process.exit(0);
+  };
+  process.on('SIGTERM', () => { shutdown('SIGTERM'); });
+  process.on('SIGINT', () => { shutdown('SIGINT'); });
+  installWorkerCrashGuard({
+    api,
+    workerName: 'claude-cloud-session-worker',
+    getActiveQueueMessageIds: () => [runner.getActiveQueueAttempt()],
+  });
+
+  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} model=${defaultModel || 'default'}`);
+  heartbeat.startHeartbeat();
+  wsLink.start();
+}
+
+main().catch((error) => {
+  console.error('claude-cloud-session-worker fatal:', error?.stack || error?.message || error);
+  process.exit(1);
+});

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

@@ -62,6 +62,8 @@ export const REMOTE_RELAY_TOOL_ZOD_SHAPE = {
   provider: choice('provider', REMOTE_RELAY_PROVIDERS),
   model: text('model'),
   cwd: text('cwd'),
+  repo: text('repo'),
+  branch: text('branch'),
   mode: choice('mode', REMOTE_RELAY_MODES),
   effort: text('effort'),
   title: text('title'),

package/server/claude-worker/claude-sdk-adapter.mjs

@@ -111,7 +111,7 @@ export function normalizeAutoCompactWindow(value) {
  * spreads of `settings` in the options literal would silently clobber each
  * other. Returns null when nothing needs to be set.
  */
-export function claudeSpawnSettings({ ultracode = false, autoCompactWindow = null, thinkingEnabled = null } = {}) {
+export function claudeSpawnSettings({ ultracode = false, autoCompactWindow = null, thinkingEnabled = null, attribution = null } = {}) {
   const window = normalizeAutoCompactWindow(autoCompactWindow);
   const thinking = strictThinkingEnabled(thinkingEnabled);
   const settings = {
@@ -122,10 +122,25 @@ export function claudeSpawnSettings({ ultracode = false, autoCompactWindow = nul
     // present; the omit path exists for direct callers that mean to say
     // nothing.
     ...(thinking !== null ? { alwaysThinkingEnabled: thinking } : {}),
+    // What commits and PRs say (shared/claude-attribution.mjs). null is
+    // vanilla: the key is left out and the CLI uses its own.
+    ...(attribution && typeof attribution === 'object' ? { attribution } : {}),
   };
   return Object.keys(settings).length ? settings : null;
 }
 
+/**
+ * Live twin of the attribution spawn setting, for a value (OAR or off). A
+ * running CLI takes a new text through the flag layer (it arrives as a fresh
+ * system-reminder on the next user turn) but cannot UNSET a value it was
+ * spawned with — `{}`, `null` and `true` all leave the spawn-time text in
+ * force (wire-logged probe, 2026-10-01). Back to vanilla therefore means a
+ * fresh process without the key; the session runner does that.
+ */
+export function claudeAttributionFlagSettings(attribution) {
+  return { attribution: attribution && typeof attribution === 'object' ? attribution : { commit: '', pr: '', sessionUrl: false } };
+}
+
 export function permissionModeForRelayMode(relayMode) {
   const mode = String(relayMode || 'agent').trim().toLowerCase();
   if (mode === 'plan') return 'plan';
@@ -228,6 +243,7 @@ export function startClaudeSession({
   reasoningEffort = '',
   autoCompactWindow = null,
   thinkingEnabled = null,
+  attribution = null,
   thinkingDisplay = '',
   abortController,
   canUseTool,
@@ -248,7 +264,7 @@ export function startClaudeSession({
   // only way to hand a fresh CLI the session-scoped ultracode flag, the
   // auto-compact window and the thinking pin, and all three share one
   // `settings` object.
-  const spawnSettings = claudeSpawnSettings({ ultracode, autoCompactWindow, thinkingEnabled });
+  const spawnSettings = claudeSpawnSettings({ ultracode, autoCompactWindow, thinkingEnabled, attribution });
   // Relay tools need the worker's authenticated API helper; a caller that
   // passes none (tests, probes) gets a session without them.
   const relayMcpServer = typeof api === 'function'

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

@@ -21,12 +21,14 @@ import {
   normalizeClaudeEffort,
   claudeUltracodeFlagSettings,
   claudeAutoCompactFlagSettings,
+  claudeAttributionFlagSettings,
   claudeThinkingFlagSettings,
   applyThinkingDisplay,
   normalizeAutoCompactWindow,
   permissionModeForRelayMode,
 } from './claude-sdk-adapter.mjs';
 import { parseThinkingDisplay, parseThinkingEnabled } from '../../shared/claude-thinking.mjs';
+import { sameClaudeAttribution } from '../../shared/claude-attribution.mjs';
 import { relocateClaudeTranscriptForCwd } from './claude-transcript-relocator.mjs';
 import {
   attemptFields,
@@ -37,6 +39,7 @@ import {
 import { createAskUserBridge } from '../../shared/ask-user-bridge.mjs';
 import { createRemoteRelayToolGate } from '../../shared/remote-relay-tool-core.mjs';
 import { buildRelayStopFailure } from '../../shared/relay-stop-failure.mjs';
+import { createTurnLiveness, resolveTurnStallWindows } from '../../shared/worker-runtime/turn-liveness.mjs';
 import {
   ANSWERED_ELSEWHERE_KIND,
   DELIVERY_ANSWERED_ELSEWHERE_TEXT,
@@ -49,6 +52,7 @@ import {
   stripSlashCommandGuardContent,
   withSlashCommandGuardContent,
 } from '../../shared/slash-command-guard.mjs';
+import { createUsageLimitTracker } from '../../shared/claude-usage-limit.mjs';
 
 /**
  * Which system-prompt append a relay mode gets (claude-sdk-adapter's
@@ -446,11 +450,19 @@ export function createClaudeSessionRunner({
   // per turn rather than captured, so a slider change picked up on the next
   // delivery reaches a process that is already running.
   getAutoCompactWindow = () => null,
+  // What this session's commits say (shared/claude-attribution.mjs); null
+  // leaves the CLI's own attribution. Piggybacked on deliveries like the
+  // window above.
+  getAttribution = () => null,
   // The per-conversation thinking state ({enabled, display}); read per turn
   // like the window, so a settings change reaches a running process on its
   // next delivery.
   getThinking = () => ({ enabled: null, display: '' }),
   lifecyclePollMs = 5_000,
+  // How long a RUNNING turn may go without a message from the CLI before
+  // that is written to the log. Nothing is failed over it: see
+  // `noteQuietTurn`. `{ model, tool }` in ms; 0 for either turns it off.
+  quietTurnWindowsMs = undefined,
   // A settled task's continuation normally begins within ~1s; when nothing
   // arrives inside this window the notification was silent (skip_transcript)
   // and must stop pinning the process.
@@ -546,6 +558,9 @@ export function createClaudeSessionRunner({
   // fixed per process, and the first delivery can beat the startup GET.
   const remoteRelayGate = remoteRelayToolGate || createRemoteRelayToolGate({ api });
   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 resolveWorkflowSessionDir = resolveWorkflowSessionDirImpl || createDefaultWorkflowSessionDirResolver();
   let claudeNativeSessionId = '';
   let proc = null;
@@ -2475,6 +2490,90 @@ export function createClaudeSessionRunner({
     return 'swallow';
   }
 
+  // ---------------------------------------------------------------------------
+  // A running turn that went quiet
+  //
+  // The other workers fail a turn whose runtime has been silent for too long
+  // (shared/worker-runtime/turn-liveness.mjs). This one only WRITES IT DOWN.
+  // What the CLI sends is known (SDK 0.3.283, measured 2026-09-28): a
+  // `tool_progress` heartbeat every 30 s while a tool runs in silence, for the
+  // Agent call as a whole when the tool runs inside a subagent; a
+  // `thinking_tokens` or stream frame about every second while the model
+  // works. What is not known is how long its silent stretches get in real
+  // sessions: a compaction (133 s seen), the backoff of an API retry, a
+  // request it is waiting on. Failing a turn here also means killing the CLI
+  // and its background tasks. So the windows are generous, the known silent
+  // stretches are holds, and a turn that outlasts them is logged with what
+  // the CLI was doing — the measurements a failing watchdog would need.
+
+  const quietWindows = (() => {
+    const windows = resolveTurnStallWindows({
+      // The CLI gives up on a silent model stream by itself after 300 s and
+      // says so (`api_retry`); a window of the same length would race it.
+      modelMs: quietTurnWindowsMs?.model ?? process.env.OAR_TURN_STALL_MODEL_MS ?? 600_000,
+      toolMs: quietTurnWindowsMs?.tool,
+    });
+    return { idle: 0, model: windows.model, tool: windows.tool };
+  })();
+
+  function observeQuietTurn(sdkMessage) {
+    const liveness = proc?.liveness;
+    if (!liveness) return;
+    const type = String(sdkMessage?.type || '');
+    const agent = String(sdkMessage?.parent_tool_use_id || '').trim() || 'root';
+    if (proc.quietLoggedAt) {
+      dbg(`the CLI spoke again after ${Math.round(liveness.quietMs() / 1000)}s of silence`, type);
+      proc.quietLoggedAt = 0;
+    }
+    liveness.traffic(type === 'system' ? `system/${sdkMessage?.subtype || ''}` : type);
+    const blocks = Array.isArray(sdkMessage?.message?.content) ? sdkMessage.message.content : [];
+    if (type === 'assistant') {
+      for (const block of blocks) {
+        if (block?.type === 'tool_use' && block.id) liveness.begin('tool', `${agent}:${block.id}`, block.name);
+      }
+    } else if (type === 'user') {
+      for (const block of blocks) {
+        if (block?.type !== 'tool_result' || !block.tool_use_id) continue;
+        liveness.end('tool', `${agent}:${block.tool_use_id}`);
+        // The result of an Agent call: whatever that agent had open ended with it.
+        liveness.endAgent(String(block.tool_use_id));
+      }
+    } else if (type === 'stream_event') {
+      const event = String(sdkMessage?.event?.type || '');
+      if (event === 'message_start') liveness.begin('model', agent);
+      else if (event === 'message_stop') liveness.end('model', agent);
+    } else if (type === 'result') {
+      liveness.reset();
+    }
+  }
+
+  /**
+   * Log a running turn the CLI has said nothing in for longer than its phase
+   * allows. Once per silence, and never while the silence has a known reason.
+   */
+  function noteQuietTurn() {
+    const liveness = proc?.liveness;
+    const ctx = proc?.activeCtx;
+    if (!liveness || !ctx || ctx.finalized || proc.closing || proc.quietLoggedAt) return;
+    // A human is deciding, a compaction is running, the relay is slow to take
+    // a publish (the stream is not read meanwhile), or the turn is being
+    // stopped: silence with a reason.
+    if (proc.pendingControlRequests > 0 || isCompacting() || proc.dispatching > 0 || ctx.interrupted) {
+      liveness.traffic('held');
+      return;
+    }
+    // Inside a turn the CLI is waiting for the model unless a tool is open.
+    const phase = liveness.phase() === 'tool' ? 'tool' : 'model';
+    const limitMs = quietWindows[phase];
+    if (!(limitMs > 0) || liveness.quietMs() < limitMs) return;
+    proc.quietLoggedAt = Date.now();
+    dbg(
+      `running turn quiet for ${Math.round(liveness.quietMs() / 1000)}s; left running (the quiet-turn watchdog only observes)`,
+      ctx.message?.id || '(continuation)',
+      liveness.describe(),
+    );
+  }
+
   async function onSdkMessage(processRef, sdkMessage) {
     // A superseded process (push-race respawn, mode-recycle timeout) may still
     // be draining its stream; its late messages must not mutate the state of
@@ -2482,6 +2581,21 @@ export function createClaudeSessionRunner({
     // cleanupProcess when the old stream ends.
     if (!proc || proc !== processRef) return;
     proc.lastEventAt = Date.now();
+    observeQuietTurn(sdkMessage);
+    // Counted for as long as this message is being handled: the stream is
+    // not read meanwhile, so the silence is this worker's, not the CLI's.
+    processRef.dispatching += 1;
+    try {
+      await handleSdkMessage(sdkMessage);
+    } finally {
+      processRef.dispatching -= 1;
+      if (proc === processRef) proc.liveness.traffic('handled');
+    }
+  }
+
+  async function handleSdkMessage(sdkMessage) {
+    const usageLimitReport = usageLimit.observe(sdkMessage);
+    if (usageLimitReport) publisher.publishUsageLimitReport({ conversationId: sdkSessionId, sdkSessionId, report: usageLimitReport });
     const suppressed = maybeSuppressStopFollowUp(sdkMessage);
     if (suppressed === 'swallow') return;
     observeProcessLevel(sdkMessage);
@@ -2502,6 +2616,8 @@ export function createClaudeSessionRunner({
     if (!ctx) return;
     const actions = ctx.normalizer.normalize(sdkMessage);
     for (const action of actions) {
+      // Decided here, while the reports the turn ran under are the latest.
+      if (action.channel === 'result') action.payload.usageLimit = usageLimit.classifyResult(sdkMessage);
       await dispatchToContext(ctx, action);
     }
   }
@@ -2917,6 +3033,7 @@ export function createClaudeSessionRunner({
     if (proc.stopFollowUp && !proc.suppressingTurn && !proc.pendingDelivered.some((entry) => entry.stoppedWithTurn)) {
       proc.stopFollowUp = null;
     }
+    noteQuietTurn();
     reapSilentProvisionalAdoption(now);
     // Before the 5-minute watchdog: a folded steered entry settles as merged
     // within the short fold grace instead of failing over.
@@ -3030,6 +3147,7 @@ export function createClaudeSessionRunner({
           await publisher.publishTurnException({
             message: ctx.message,
             errorText: String(streamError?.message || streamError || 'unknown error'),
+            usageLimit: usageLimit.classifyException(streamError),
           }).catch(() => {});
         }
         continue;
@@ -3058,6 +3176,7 @@ export function createClaudeSessionRunner({
     const thinkingState = getThinking() || {};
     const thinkingEnabled = parseThinkingEnabled(thinkingState.enabled);
     const thinkingDisplay = parseThinkingDisplay(thinkingState.display);
+    const attribution = getAttribution() || null;
     const abortController = new AbortController();
     const processRef = {
       turn: null,
@@ -3066,6 +3185,7 @@ export function createClaudeSessionRunner({
       relayMode,
       effort,
       autoCompactWindow,
+      attribution,
       // Seeded from what the process is SPAWNED with, so the adapt diff is
       // against reality rather than against a delivered setting the CLI may
       // never have honored.
@@ -3132,6 +3252,11 @@ export function createClaudeSessionRunner({
       settleSeqAtContinuationOpen: 0,
       pendingControlRequests: 0,
       lastEventAt: Date.now(),
+      // The quiet-turn log (see noteQuietTurn): what the CLI has in flight,
+      // messages being handled right now, and when the silence was logged.
+      liveness: createTurnLiveness({ windows: quietWindows }),
+      dispatching: 0,
+      quietLoggedAt: 0,
       heldForTasksSince: 0,
       taskSettledAt: 0,
       // Bumped by every task-settle signal; the Stop guard compares it.
@@ -3218,6 +3343,7 @@ export function createClaudeSessionRunner({
       autoCompactWindow,
       thinkingEnabled,
       thinkingDisplay,
+      attribution,
       abortController,
       canUseTool,
       pathToClaudeCodeExecutable,
@@ -3326,6 +3452,30 @@ export function createClaudeSessionRunner({
       });
       proc.autoCompactWindow = autoCompactWindow;
     }
+    // Attribution follows the window's pattern: a changed value (a settings
+    // change, a model switch that renames the trailer) reaches the live CLI
+    // through the flag layer, before the turn that may commit.
+    const attribution = getAttribution() || null;
+    if (!sameClaudeAttribution(attribution, proc.attribution)) {
+      if (attribution === null) {
+        // Back to the CLI's own attribution. A value the process was spawned
+        // with cannot be unset through the flag layer (probe 2026-10-01), so
+        // the honest way is a fresh process without the key — taken when
+        // nothing lives in the old one; a busy process keeps the old text and
+        // the next delivery tries again.
+        if (!hasLiveWork() && !proc.liveTasks.size) {
+          gracefulShutdown('attribution-vanilla');
+          await drainClosingProcess(10_000);
+          return null;
+        }
+      } else {
+        expectSettingsReinit();
+        await Promise.resolve(proc.turn.applyFlagSettings?.(claudeAttributionFlagSettings(attribution))).catch((error) => {
+          dbg('applyFlagSettings attribution failed', error?.message || String(error));
+        });
+        proc.attribution = attribution;
+      }
+    }
     // Thinking is NOT a symmetric copy of the window block: the probe
     // (2026-08-26, docs/plans/claude-thinking-control.md) showed the two
     // directions of the on/off axis are not equally reachable mid-session.
@@ -3631,7 +3781,7 @@ export function createClaudeSessionRunner({
       settingsWindowOpen = false;
       const errorText = String(error?.message || error || 'unknown error');
       dbg('claude turn failed', message.id, errorText);
-      await publisher.publishTurnException({ message, errorText });
+      await publisher.publishTurnException({ message, errorText, usageLimit: usageLimit.classifyException(error) });
       return true;
     } finally {
       endAdmission();

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

@@ -17,6 +17,7 @@ import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-fil
 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 { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createClaudeSessionRunner } from './claude-session-process.mjs';
 import { createRunnerLinkBridge, failSettlingRowsOnShutdown } from './claude-worker-link-wiring.mjs';
@@ -66,6 +67,9 @@ async function main() {
   // 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;
 
   const api = createApiClient({
     serverUrl,
@@ -111,6 +115,7 @@ async function main() {
     getBackgroundTaskTimeoutMs: () => backgroundTaskTimeoutMs,
     getAutoCompactWindow: () => autoCompactWindow,
     getThinking: () => thinking,
+    getAttribution: () => attribution,
     // 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.
@@ -176,6 +181,7 @@ async function main() {
       // 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);
       try {
         return await turnRunner.handlePendingPayload(pending);
       } catch (error) {

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

@@ -0,0 +1,92 @@
+// Why a Claude turn failed: the code the relay prints, and the advice that
+// fits the failure.
+//
+// A turn the API refused ends with a `result` of subtype 'success' and
+// `is_error: true`: the subtype says how the turn ended, not whether it
+// worked, so it names nothing. What names the failure, in this order:
+//
+//   1. the `error` field of the turn's last assistant message (the SDK's
+//      SDKAssistantMessageError: 'billing_error', 'oauth_org_not_allowed', …);
+//   2. the `api_error_status` of the result;
+//   3. the words of the refusal, for an account failure that came with
+//      neither;
+//   4. a subtype other than 'success' ('error_max_turns', …);
+//   5. the `terminal_reason` of the result.
+//
+// The relay prints `claude.<code>` as `relay.claude-<code>`, dashes for
+// underscores.
+
+// The user has to sign in again: a retry cannot succeed before that.
+const SIGN_IN_ERRORS = new Set(['authentication_failed']);
+// The account itself refuses: billing, or access its organisation withholds.
+const ACCOUNT_ERRORS = new Set([
+  'billing_error',
+  'oauth_org_not_allowed',
+  'account_on_hold',
+  'verification_required',
+  'account-access',
+]);
+
+const STATUS_CODES = new Map([
+  [401, 'authentication_failed'],
+  [402, 'billing_error'],
+  [429, 'rate_limit'],
+  [529, 'overloaded'],
+]);
+
+// Checked before the sign-in words: the organisation's refusal mentions an
+// API key too.
+const ACCOUNT_ACCESS_TEXT = /organi[sz]ation has disabled|subscription access|does not have access to claude/i;
+const BILLING_TEXT = /credit balance|billing|payment/i;
+const SIGN_IN_TEXT = /failed to authenticate|authentication_error|invalid api key|not logged in|please run \/login/i;
+
+export const CLAUDE_SIGN_IN_GUIDANCE =
+  'Sign in to Claude again in Settings → Providers → Claude → Relogin (or run `claude` on the relay host), '
+  + 'then send the message again.';
+export const CLAUDE_ACCOUNT_GUIDANCE =
+  'Check the Claude account the relay host is signed in to: its subscription, its payment method, and whether '
+  + 'its organisation allows Claude Code. Settings → Providers → Claude shows the account and signs in to '
+  + 'another one. Then send the message again.';
+export const CLAUDE_MODEL_GUIDANCE = 'Choose another model for this conversation, then send the message again.';
+
+function codeFromText(text) {
+  if (ACCOUNT_ACCESS_TEXT.test(text)) return 'account-access';
+  if (BILLING_TEXT.test(text)) return 'billing_error';
+  if (SIGN_IN_TEXT.test(text)) return 'authentication_failed';
+  return null;
+}
+
+/** The advice for a code, or null where the relay's own default fits. */
+export function claudeFailureGuidance(code) {
+  const token = String(code || '').trim().toLowerCase();
+  if (SIGN_IN_ERRORS.has(token)) return CLAUDE_SIGN_IN_GUIDANCE;
+  if (ACCOUNT_ERRORS.has(token)) return CLAUDE_ACCOUNT_GUIDANCE;
+  if (token === 'model_not_found') return CLAUDE_MODEL_GUIDANCE;
+  return null;
+}
+
+/**
+ * `result` is the normalized result payload of the turn (sdk-message-
+ * normalizer): `{ text, subtype, assistantError, apiErrorStatus,
+ * terminalReason }`. Returns `{ code, stableCode, guidance }`; `guidance` is
+ * null where the relay's default fits.
+ */
+export function classifyClaudeResultFailure(result = {}) {
+  const subtype = String(result?.subtype || '').trim();
+  const assistantError = String(result?.assistantError || '').trim().toLowerCase();
+  const status = Number(result?.apiErrorStatus);
+  const hasStatus = Number.isFinite(status) && status >= 400;
+  const terminalReason = String(result?.terminalReason || '').trim().toLowerCase();
+
+  let code = null;
+  if (assistantError && assistantError !== 'unknown') code = assistantError;
+  else if (hasStatus && STATUS_CODES.has(status)) code = STATUS_CODES.get(status);
+  else code = codeFromText(String(result?.text || ''));
+
+  if (!code && subtype && subtype !== 'success') code = subtype;
+  if (!code && (hasStatus || assistantError === 'unknown' || terminalReason === 'api_error')) code = 'api-error';
+  if (!code && terminalReason && terminalReason !== 'completed') code = terminalReason;
+  if (!code) code = 'turn-error';
+
+  return { code, stableCode: `claude.${code}`, guidance: claudeFailureGuidance(code) };
+}