@oar-sh/oar 0.9.5 → 0.9.7

package/server/routes/sessions-routes.mjs

@@ -11,6 +11,7 @@ import { applySafeServedContentHeaders } from '../services/safe-served-content.m
 import { stripRelayPromptContext } from '../services/relay-prompt-sanitizer.mjs';
 import { persistConversationPreferences } from '../services/conversation-preferences-service.mjs';
 import { parseAutoCompactWindow } from '../../shared/auto-compact-window.mjs';
+import { CLAUDE_ATTRIBUTION_MODES, DEFAULT_CLAUDE_ATTRIBUTION_MODE, claudeAttributionModelLabel, claudeAttributionTrailer, normalizeClaudeAttributionMode, resolveClaudeAttributionMode } from '../../shared/claude-attribution.mjs';
 import { parseThinkingDisplay, parseThinkingEnabled } from '../../shared/claude-thinking.mjs';
 import { isProviderModelAvailable, resolveProviderModelSelection } from '../services/provider-model-selection.mjs';
 import {
@@ -30,8 +31,7 @@ import { createGrokAuthService } from '../services/grok-auth-service.mjs';
 import {
   isWithinAllowedPrefix,
   readWorkspaceRootPathFromBody,
-  validateRequestedWorkspaceRoot,
-} from '../services/workspace-root-path-policy.mjs';
+  validateRequestedWorkspaceRoot, normalizeWorkspaceRootKey } from '../services/workspace-root-path-policy.mjs';
 import { workspaceRootDisplayName } from '../workspace-root.mjs';
 import { createKeyedMutex } from '../services/keyed-mutex-service.mjs';
 import { createFixedWindowRateLimiter } from '../services/rate-limit-service.mjs';
@@ -54,6 +54,13 @@ import {
   isSafeProviderModelId,
 } from '../../shared/model-id.mjs';
 import { openAIReasoningEffortsForModel } from '../../shared/openai-reasoning.mjs';
+import { stripModelTierSuffix } from '../../shared/claude-cloud/repo-url.mjs';
+import {
+  buildCloudSourceRecord,
+  buildConversationCloudPayload,
+  isClaudeCloudProviderType,
+  validateCloudSourceRequest,
+} from '../services/claude-cloud-session-service.mjs';
 import {
   DEFAULT_TURN_CEILING_MINUTES,
   TURN_CEILING_MAX_MINUTES,
@@ -252,18 +259,69 @@ export function parseClaudeSettingsUpdateRequest(body = {}) {
   const model = hasModel ? (String(payload.model || '').trim() || 'claude-sonnet-5') : undefined;
   const hasModels = Array.isArray(payload.models);
   const hasEnabledModels = Array.isArray(payload.enabledModels);
-  if (!hasEnabled && !hasModel && !hasModels && !hasEnabledModels) {
+  const hasAttributionMode = Object.prototype.hasOwnProperty.call(payload, 'attributionMode');
+  const attributionMode = hasAttributionMode ? normalizeClaudeAttributionMode(payload.attributionMode) : undefined;
+  if (!hasEnabled && !hasModel && !hasModels && !hasEnabledModels && !hasAttributionMode) {
     return { ok: false, error: 'No Claude settings update provided' };
   }
   if (hasModel && !isSafeClaudeModelId(model)) {
     return { ok: false, error: 'Invalid Claude model ID' };
   }
+  if (hasAttributionMode && !attributionMode) {
+    return { ok: false, error: `Invalid Claude attribution mode (one of ${CLAUDE_ATTRIBUTION_MODES.join(', ')})` };
+  }
   return {
     ok: true,
     ...(hasEnabled ? { enabled: payload.enabled } : {}),
     ...(hasModel ? { model } : {}),
     ...(hasModels ? { models: payload.models } : {}),
     ...(hasEnabledModels ? { enabledModels: payload.enabledModels } : {}),
+    ...(hasAttributionMode ? { attributionMode } : {}),
+  };
+}
+
+/**
+ * A folder's attribution override update: `{ path, attributionMode }` with
+ * the mode one of the three, or null to inherit the provider setting again.
+ */
+export function parseWorkspaceRootAttributionUpdate(body = {}) {
+  const payload = body && typeof body === 'object' ? body : {};
+  const path = String(payload.path || '').trim();
+  if (!path) return { ok: false, error: 'Missing path' };
+  if (!Object.prototype.hasOwnProperty.call(payload, 'attributionMode')) {
+    return { ok: false, error: 'Missing attributionMode (oar, vanilla, off, or null to inherit)' };
+  }
+  if (payload.attributionMode === null || payload.attributionMode === '') return { ok: true, path, attributionMode: null };
+  const attributionMode = normalizeClaudeAttributionMode(payload.attributionMode);
+  if (!attributionMode) {
+    return { ok: false, error: `Invalid attribution mode (one of ${CLAUDE_ATTRIBUTION_MODES.join(', ')}, or null to inherit)` };
+  }
+  return { ok: true, path, attributionMode };
+}
+
+/** What a folder's Claude sessions will say, given the provider setting and the folder's own choice. */
+export function buildWorkspaceRootAttributionPayload({ path = '', folderMode = null, providerMode = null, model = '' } = {}) {
+  const effectiveMode = resolveClaudeAttributionMode({ providerMode, folderMode });
+  return {
+    path: String(path || '').trim(),
+    attributionMode: normalizeClaudeAttributionMode(folderMode),
+    providerMode: normalizeClaudeAttributionMode(providerMode) || DEFAULT_CLAUDE_ATTRIBUTION_MODE,
+    effectiveMode,
+    attributionModes: [...CLAUDE_ATTRIBUTION_MODES],
+    attributionExample: effectiveMode === 'oar'
+      ? claudeAttributionTrailer(claudeAttributionModelLabel(String(model || 'claude-sonnet-5')))
+      : (effectiveMode === 'off' ? '' : null),
+  };
+}
+
+/** The attribution fields every Claude settings payload carries, with the trailer the default model would get. */
+export function claudeAttributionSettingsFields(settings = {}) {
+  const attributionMode = normalizeClaudeAttributionMode(settings?.attributionMode) || DEFAULT_CLAUDE_ATTRIBUTION_MODE;
+  const model = String(settings?.model || 'claude-sonnet-5').trim() || 'claude-sonnet-5';
+  return {
+    attributionMode,
+    attributionModes: [...CLAUDE_ATTRIBUTION_MODES],
+    attributionExample: claudeAttributionTrailer(claudeAttributionModelLabel(model)),
   };
 }
 
@@ -676,6 +734,8 @@ function normalizeRequestedProviderType(value = '') {
   if (normalized === 'openai' || normalized === 'openai-byok') return 'openai';
   if (normalized === 'openai-image' || normalized === 'openai-image-byok') return 'openai-image';
   if (normalized === 'claude' || normalized === 'claude-agent-sdk' || normalized === 'anthropic') return 'claude';
+  // Its own provider, never read as `claude`: a cloud chat is asked for by name.
+  if (normalized === 'claude-cloud') return 'claude-cloud';
   if (normalized === 'cursor') return 'cursor';
   if (normalized === 'grok' || normalized === 'xai' || normalized === 'xai-grok') return 'grok';
   if (normalized === 'github' || normalized === 'github-copilot') return 'github';
@@ -1169,6 +1229,9 @@ export function buildSessionWorkerStatusPayload({
   featureFlags = null,
   supervisorSnapshot = null,
   queueRows = [],
+  // What the last read of the process list did ({ at, durationMs, processes,
+  // error }); a slow box shows here before it shows as 502s.
+  processList = null,
 } = {}) {
   const snapshot = supervisorSnapshot && typeof supervisorSnapshot === 'object'
     ? supervisorSnapshot
@@ -1273,6 +1336,7 @@ export function buildSessionWorkerStatusPayload({
     workerCount: toSafeNonNegativeInt(snapshot.workerCount, workers.length),
     onlineCount,
     onlineProcessCount,
+    processList: processList && typeof processList === 'object' ? { ...processList } : null,
     onlineBoundProcessCount,
     onlineUnassignedProcessCount,
     counts: snapshot.counts && typeof snapshot.counts === 'object' ? snapshot.counts : {},
@@ -1295,6 +1359,9 @@ export function buildConversationSessionRootPayload({
   resolveCursorSessionRoot = null,
 } = {}) {
   const sid = String(sdkSessionId || '').trim() || String(conversationId || '').trim();
+  // A Claude Cloud session lives in Anthropic's cloud: there is no session
+  // folder on this host, and it must not be looked up as a Copilot one.
+  if (isClaudeCloudProviderType(providerType)) return null;
   // Cursor sessions have no ~/.copilot/session-state entry either — their
   // on-disk footprint is the worker's per-session agent store, created on the
   // first turn.
@@ -2011,6 +2078,12 @@ export function registerSessionsRoutes(app, deps) {
     // Owns the relay-wide single-flight Grok device-code login, on the same
     // terms as claudeAuthService above.
     grokAuthService = null,
+    // Claude Cloud (provider `claude-cloud`): its settings (the switch, the
+    // default model, the environment) and what the relay keeps per cloud
+    // conversation. Absent in older wiring and most tests, where the provider
+    // is simply off.
+    claudeCloudSettingsService = null,
+    claudeCloudSessionService = null,
     reconcileUnstartedConversationProviders = async () => ({
       updatedUnstartedConversations: 0,
       skippedStartedConversations: 0,
@@ -2047,6 +2120,10 @@ export function registerSessionsRoutes(app, deps) {
     getCursorDashboardTokenSettings = () => ({ configured: false }),
     setCursorDashboardTokenSettings = () => ({ ok: false, error: 'Cursor dashboard token settings are unavailable' }),
     planUsageService = null,
+    // Optional live Claude account usage for the Check Usage modal; it reads
+    // nothing while Claude Cloud is off, and absent (tests, older wiring) the
+    // Claude card stays the last turn's snapshot.
+    claudeAccountUsageService = null,
     getCursorPlanAllowanceSettings = () => ({ cursorModelsUsd: null, otherModelsUsd: null, resetDay: 1 }),
     setCursorPlanAllowanceSettings = () => ({ ok: false, error: 'Cursor allowance settings are unavailable' }),
     getGrokPlanAllowanceSettings = () => ({ monthlyUsd: null, resetDay: 1 }),
@@ -2093,6 +2170,7 @@ export function registerSessionsRoutes(app, deps) {
     uploadPathForSha,
     hostSuspendService = null,
     collectHostActivity = null,
+    usageLimitPauseService = null,
     hostSuspendPlatform = process.platform,
     // Remote relays (server/services/remote-relay-inbound.mjs): origin on
     // conversations another relay's agent created, and the inbound switch.
@@ -2460,6 +2538,14 @@ export function registerSessionsRoutes(app, deps) {
     return finalized;
   }
 
+  /** The `cloud` field of a conversation payload; null unless it is a cloud one. */
+  function conversationCloudPayload(conversation, runtimeSession) {
+    return buildConversationCloudPayload({
+      cloudSourceJson: conversation?.cloud_source_json,
+      costUsd: runtimeSession?.claude_cloud_cost_usd,
+    });
+  }
+
   function resolveConversationByIdOrSdkSessionId(requestedId) {
     const lookupId = String(requestedId || '').trim();
     if (!lookupId) return null;
@@ -2720,11 +2806,13 @@ export function registerSessionsRoutes(app, deps) {
 
   // GET /api/conversations — list all conversations
   app.get('/api/conversations', auth, (req, res) => {
-    const includeArchived = String(req.query.archived || '').trim().toLowerCase() === 'true';
+    // `archived=true` lists both, `archived=only` the archived ones (the
+    // sidebar's Archived view), nothing: the live ones.
+    const archivedMode = String(req.query.archived || '').trim().toLowerCase();
     const limit = normalizeConversationListLimit(req.query.limit, DEFAULT_CONVERSATION_LIST_LIMIT);
     const beforeConversationId = String(req.query.beforeConversationId || '').trim();
     const beforeUpdatedAt = String(req.query.beforeUpdatedAt || '').trim();
-    const rows = stmts.listConvs.all(includeArchived ? 1 : 0);
+    const rows = stmts.listConvs.all(archivedMode === 'true' ? 1 : 0, archivedMode === 'only' ? 1 : 0);
     const page = selectConversationListPage(rows, {
       limit,
       beforeConversationId,
@@ -2781,6 +2869,11 @@ export function registerSessionsRoutes(app, deps) {
         draftUpdatedByClientId: r.draft_updated_by_client_id || null,
         // Set on conversations another relay's agent created ("via <relay>").
         origin: parseRemoteRelayOriginJson(r.origin_json),
+        // Set on Claude Cloud conversations: repository, branch, session link.
+        cloud: buildConversationCloudPayload({
+          cloudSourceJson: r.cloud_source_json,
+          costUsd: r.runtime_claude_cloud_cost_usd,
+        }),
       };
     });
 
@@ -3107,10 +3200,11 @@ export function registerSessionsRoutes(app, deps) {
       || null;
     const copilotSessionId = String(runtimeSessionBySdkSessionId?.sdk_session_id || runtimeSession?.sdk_session_id || '').trim() || null;
     const providerType = String(runtimeSession?.provider_type || 'github').trim().toLowerCase();
-    // The cursor and grok workers post the same Claude-shaped usage blob, so
-    // all three providers share the stored reader.
+    // The cursor and grok workers post the same Claude-shaped usage blob, and
+    // so does the Claude Cloud worker (the cloud session's context and token
+    // usage), so all four providers share the stored reader.
     const usesStoredContextUsage = providerType === 'claude' || providerType === 'cursor'
-      || providerType === 'grok';
+      || providerType === 'grok' || providerType === 'claude-cloud';
 
     const parsed = usesStoredContextUsage
       ? (() => {
@@ -3147,6 +3241,19 @@ export function registerSessionsRoutes(app, deps) {
       autoCompactWindow: parseAutoCompactWindow(conversationRow?.auto_compact_window),
       thinkingEnabled: parseThinkingEnabled(conversationRow?.thinking_enabled),
       thinkingDisplay: parseThinkingDisplay(conversationRow?.thinking_display),
+      // What this folder's Claude commits say (the 🧠 modal's override row).
+      // A Claude Cloud chat has the row when it was started from a folder,
+      // with its own model in the example.
+      ...(providerType === 'claude'
+        ? { attribution: workspaceRootAttributionFor(conversationRow) }
+        : {}),
+      ...(providerType === 'claude-cloud' && cloudConversationFolder(conversationRow)
+        ? {
+          attribution: workspaceRootAttributionFor(conversationRow, '', {
+            model: runtimeSession?.provider_model || runtimeSession?.model || '',
+          }),
+        }
+        : {}),
       runtimeSessionId: runtimeSession?.id || null,
       copilotSessionId,
       providerType: usesStoredContextUsage ? providerType : 'github',
@@ -3167,6 +3274,60 @@ export function registerSessionsRoutes(app, deps) {
     };
   }
 
+  // --- Per-folder commit attribution (shared/claude-attribution.mjs) -----
+  function workspaceRootSettingsRow(rootPath) {
+    const root = String(rootPath || '').trim();
+    if (!root || typeof stmts?.getWorkspaceRootSettings?.get !== 'function') return null;
+    try {
+      return stmts.getWorkspaceRootSettings.get(normalizeWorkspaceRootKey(root)) || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** The folder a Claude Cloud chat was started from, if it was started from one. */
+  function cloudConversationFolder(conversationRow) {
+    return String(conversationRow?.runtime_workspace_root_path || conversationRow?.configured_workspace_root_path || '').trim();
+  }
+
+  function workspaceRootAttributionFor(conversationRow, explicitPath = '', { model = '' } = {}) {
+    const path = String(explicitPath
+      || conversationRow?.runtime_workspace_root_path
+      || conversationRow?.configured_workspace_root_path
+      || '').trim();
+    const provider = typeof getClaudeProviderSettings === 'function' ? getClaudeProviderSettings() : {};
+    return buildWorkspaceRootAttributionPayload({
+      path,
+      folderMode: workspaceRootSettingsRow(path)?.attribution_mode || null,
+      providerMode: provider?.attributionMode,
+      model: String(model || '').trim() || provider?.model,
+    });
+  }
+
+  app.get('/api/workspace-root/attribution', auth, (req, res) => {
+    const path = String(req.query.path || '').trim();
+    if (!path) return res.status(400).json({ error: 'Missing path' });
+    res.json({ ok: true, ...workspaceRootAttributionFor(null, path) });
+  });
+
+  app.post('/api/workspace-root/attribution', auth, (req, res) => {
+    const parsed = parseWorkspaceRootAttributionUpdate(req.body);
+    if (!parsed.ok) return res.status(400).json({ error: parsed.error });
+    if (typeof stmts?.upsertWorkspaceRootAttribution?.run !== 'function') {
+      return res.status(503).json({ error: 'Folder settings are unavailable' });
+    }
+    const key = normalizeWorkspaceRootKey(parsed.path);
+    const now = new Date().toISOString();
+    if (parsed.attributionMode === null) {
+      stmts.deleteWorkspaceRootSettings.run(key);
+    } else {
+      stmts.upsertWorkspaceRootAttribution.run(key, parsed.path, parsed.attributionMode, now);
+    }
+    const payload = workspaceRootAttributionFor(null, parsed.path);
+    try { io.emit('workspace_root_attribution_updated', payload); } catch {}
+    res.json({ ok: true, ...payload });
+  });
+
   app.get('/api/context/:conversationId', auth, (req, res) => {
     const conversationId = String(req.params.conversationId || '').trim();
     if (!conversationId) return res.status(400).json({ error: 'Missing conversationId' });
@@ -3423,6 +3584,7 @@ export function registerSessionsRoutes(app, deps) {
       draftUpdatedAt: conv.draft_updated_at || null,
       draftUpdatedByClientId: conv.draft_updated_by_client_id || null,
       origin: parseRemoteRelayOriginJson(conv.origin_json),
+      cloud: conversationCloudPayload(conv, runtimeSession),
       messages: history.messages,
       pageInfo: history.pageInfo,
       refreshed: true,
@@ -3823,6 +3985,7 @@ export function registerSessionsRoutes(app, deps) {
       // "cancelled" with it.
       activeTurn: Number(stmts.getConversationActiveQueueCount?.get?.(resolvedConversationId)?.count || 0) > 0,
       backgroundTasks: backgroundTaskStore?.get?.(resolvedConversationId) || [],
+      usageLimitPause: usageLimitPauseService?.getPause?.(resolvedConversationId) || null,
       previews: listConversationPreviews?.(resolvedConversationId) || [],
       preferredRelayMode: preferences.preferredRelayMode,
       preferredModel: preferences.preferredModel,
@@ -3833,6 +3996,8 @@ export function registerSessionsRoutes(app, deps) {
       draftUpdatedByClientId: conv.draft_updated_by_client_id || null,
       // Set on conversations another relay's agent created ("via <relay>").
       origin: parseRemoteRelayOriginJson(conv.origin_json),
+      // Set on Claude Cloud conversations: repository, branch, session link.
+      cloud: conversationCloudPayload(conv, runtimeSession),
       messages: history.messages,
       pageInfo: history.pageInfo,
     });
@@ -4176,7 +4341,14 @@ export function registerSessionsRoutes(app, deps) {
     // A session that is not 'ready' can still own a live process (status 'error',
     // or no registry entry at all). Detect that, or the stop is skipped and the
     // launch silently reuses the old process in the old directory.
-    const liveProcessDetected = !!sessionWorkerProcessInspector?.findProcessForSession?.(sdkSessionId);
+    let liveProcessDetected = false;
+    try {
+      liveProcessDetected = !!(await sessionWorkerProcessInspector?.findProcessForSessionAsync?.(sdkSessionId, { fresh: true }));
+    } catch (error) {
+      // An unreadable list must not pass for "no process": the relaunch would
+      // start a second CLI next to the one it could not see.
+      return { ok: false, statusCode: 409, error: `process-list-unreadable: ${error?.message || error}` };
+    }
     const eligibility = evaluateWorkspaceRootRelaunch({
       workerStatus: worker?.status,
       activeQueueCount,
@@ -4529,6 +4701,16 @@ export function registerSessionsRoutes(app, deps) {
       for (const key of new Set([id, workerSessionId])) backgroundTaskStore?.replace?.(key, []);
     }
 
+    // A Claude Cloud conversation takes its cloud session along: archived
+    // there, nothing destroyed. Started here, while the binding can still be
+    // read, and not waited for: the delete never depends on Anthropic.
+    if (!sharedWithConversationId) {
+      claudeCloudSessionService?.archiveSessionInBackground?.({
+        conversationId: id,
+        runtimeSession: stmts.getRuntimeSessionByConversation?.get?.(id) || null,
+      });
+    }
+
     const deletedAt = new Date().toISOString();
     markConversationDeleted.run(deletedAt, id);
     // Tombstones keep the SDK session importer from bringing it back.
@@ -4561,7 +4743,11 @@ export function registerSessionsRoutes(app, deps) {
     return { statusCode: 200, body: { ok: true, workerStopped, cliSessionDeleted: cliSession.deleted } };
   }
 
-  // POST /api/conversation/:id/archive — archive conversation
+  // POST /api/conversation/:id/archive — archive conversation. The chat
+  // leaves the sidebar's live list (it is kept, and comes back with
+  // /unarchive); its idle worker is stopped like a deleted chat's; a Claude
+  // Cloud chat's cloud session is archived with it. A chat that is working
+  // is not archived: stop it first.
   app.post('/api/conversation/:id/archive', auth, async (req, res) => {
     if (!admitRemoteRelayRequest(req, res, remoteRelayInbound)) return;
     const id = String(req.params.id || '').trim();
@@ -4571,15 +4757,118 @@ export function registerSessionsRoutes(app, deps) {
       if (!existing || String(existing.status || '').trim() === 'deleted') {
         return res.json({ ok: true, alreadyDeleted: true });
       }
-      db.prepare(`UPDATE conversations SET archived = 1, updated_at = ? WHERE id = ?`).run(new Date().toISOString(), id);
-      io.emit('conversation_archived', { conversationId: id });
-      return res.json({ ok: true });
+      if (Number(existing.archived || 0) === 1) return res.json({ ok: true, alreadyArchived: true });
+      const sdkSessionId = String(existing.sdk_session_id || '').trim() || null;
+      const workerSessionId = sdkSessionId || id;
+      const outcome = await sessionLaunchMutex.runExclusive(workerSessionId, async () => {
+        const activity = describeConversationActivity(id, workerSessionId);
+        if (activity.turnRunning) {
+          return {
+            statusCode: 409,
+            body: {
+              ok: false,
+              error: 'conversation-active',
+              reason: 'turn-running',
+              message: 'This conversation is still working on a reply. Stop it, then archive it.',
+            },
+          };
+        }
+        if (activity.backgroundTaskCount > 0) {
+          return {
+            statusCode: 409,
+            body: {
+              ok: false,
+              error: 'conversation-active',
+              reason: 'background-tasks',
+              message: activity.unstoppableTaskCount > 0
+                ? 'Background tasks are still running in this conversation, and some have no Stop button. Use Kill session in its ⋯ menu, then archive it.'
+                : 'Background tasks are still running in this conversation. Stop them in the task panel, then archive it.',
+            },
+          };
+        }
+        // A worker another live conversation still uses stays.
+        const sharedWithConversationId = sdkSessionId
+          ? String(findOtherLiveConversationForSdkSession.get(sdkSessionId, id)?.id || '').trim() || null
+          : null;
+        const importedOnly = !!sdkSessionId && sdkSessionImportService?.isImportedOnly?.(sdkSessionId) === true;
+        let workerStopped = false;
+        if (!sharedWithConversationId && !importedOnly) {
+          const stopped = await stopIdleWorkspaceRootSession({
+            sdkSessionId: workerSessionId,
+            worker: sessionWorkerRegistry?.getWorker?.(workerSessionId) || null,
+            sessionWorkerSupervisor,
+            sessionWorkerRegistry,
+            sessionWorkerProcessInspector,
+            stopOverrides: sessionWorkerStopOverrides,
+          });
+          if (!stopped.ok) {
+            return {
+              statusCode: 409,
+              body: {
+                ok: false,
+                error: 'worker-stop-failed',
+                message: "Couldn't stop this conversation's session, so it was not archived. Try again in a moment.",
+                remainingPids: stopped.remainingPids || [],
+              },
+            };
+          }
+          workerStopped = (stopped.stoppedPids || []).length > 0;
+          // Nothing may respawn a worker for an archived chat.
+          sessionWorkerSupervisor?.markKilled?.(workerSessionId);
+        }
+        db.prepare(`UPDATE conversations SET archived = 1, updated_at = ? WHERE id = ?`).run(new Date().toISOString(), id);
+        io.emit('conversation_archived', { conversationId: id, archived: true });
+        // The cloud session of a Claude Cloud conversation is archived with it;
+        // best effort and not waited for.
+        if (!sharedWithConversationId) {
+          try {
+            claudeCloudSessionService?.archiveSessionInBackground?.({
+              conversationId: id,
+              runtimeSession: stmts.getRuntimeSessionByConversation?.get?.(id) || null,
+            });
+          } catch (error) {
+            console.warn(`[archive] Cloud session archive not started for ${id}: ${error?.message || error}`);
+          }
+        }
+        return { statusCode: 200, body: { ok: true, workerStopped } };
+      });
+      return res.status(outcome.statusCode).json(outcome.body);
     } catch (error) {
       console.warn(`[archive] Archive failed for ${id}: ${error?.message || error}`);
       return res.status(500).json({ error: 'Failed to archive conversation' });
     }
   });
 
+  // POST /api/conversation/:id/unarchive — back to the live list. A Claude
+  // Cloud chat's cloud session is brought back too, so the next message
+  // reaches it; a stopped worker is launched again by the next delivery.
+  app.post('/api/conversation/:id/unarchive', auth, (req, res) => {
+    if (!admitRemoteRelayRequest(req, res, remoteRelayInbound)) return;
+    const id = String(req.params.id || '').trim();
+    if (!id) return res.status(400).json({ error: 'Missing conversation id' });
+    try {
+      const existing = stmts.getConvAnyStatus.get(id);
+      if (!existing || String(existing.status || '').trim() === 'deleted') {
+        return res.status(404).json({ ok: false, error: 'Conversation not found' });
+      }
+      if (Number(existing.archived || 0) !== 1) return res.json({ ok: true, alreadyLive: true });
+      db.prepare(`UPDATE conversations SET archived = 0, updated_at = ? WHERE id = ?`).run(new Date().toISOString(), id);
+      io.emit('conversation_archived', { conversationId: id, archived: false });
+      try {
+        claudeCloudSessionService?.unarchiveSessionInBackground?.({
+          conversationId: id,
+          runtimeSession: stmts.getRuntimeSessionByConversation?.get?.(id) || null,
+        });
+      } catch (error) {
+        console.warn(`[archive] Cloud session unarchive not started for ${id}: ${error?.message || error}`);
+      }
+      return res.json({ ok: true });
+    } catch (error) {
+      console.warn(`[archive] Unarchive failed for ${id}: ${error?.message || error}`);
+      return res.status(500).json({ error: 'Failed to unarchive conversation' });
+    }
+  });
+
   app.post('/api/conversation/bootstrap', auth, async (req, res) => {
     // Another relay's agent starting a session: refused while the inbound
     // switch is off, otherwise the conversation keeps its provenance.
@@ -4603,6 +4892,47 @@ export function registerSessionsRoutes(app, deps) {
     const title = (requestedTitle || 'New Conversation').slice(0, 80);
     const openAISettings = getOpenAIProviderSettings();
     const requestedProviderType = normalizeRequestedProviderType(req.body?.providerType || req.body?.provider);
+    // Claude Cloud is asked for by name only: its model ids are the Claude
+    // provider's own, so a model never selects it. Refused before anything
+    // else is looked at while the provider is off, so a relay that has not
+    // switched it on answers every such request the same way.
+    const useClaudeCloudProvider = requestedProviderType === 'claude-cloud';
+    const claudeCloudSettings = useClaudeCloudProvider
+      ? (claudeCloudSettingsService?.getSettings?.() || null)
+      : null;
+    let bootstrapCloudSource = null;
+    if (useClaudeCloudProvider) {
+      const refuseCloud = (code, error) => res.status(400).json({ ok: false, error, code });
+      if (claudeCloudSettings?.enabled !== true) {
+        return refuseCloud('claude_cloud_disabled', 'Claude Cloud is not enabled on this relay');
+      }
+      const validatedSource = validateCloudSourceRequest(req.body?.cloudSource);
+      if (!validatedSource.ok) return refuseCloud(validatedSource.code, validatedSource.error);
+      // The stored environment, else the account's first active one (which
+      // is then stored). Nothing is created at Anthropic here.
+      let cloudEnvironmentId = String(claudeCloudSettings.environmentId || '').trim();
+      if (!cloudEnvironmentId) {
+        try {
+          cloudEnvironmentId = String(await claudeCloudSettingsService.resolveEnvironmentId?.() || '').trim();
+        } catch {
+          cloudEnvironmentId = '';
+        }
+      }
+      if (!cloudEnvironmentId) {
+        return refuseCloud(
+          'claude_cloud_environment_missing',
+          'No cloud environment is set. Pick one on Settings → Providers → Claude Cloud (opening claude.ai/code once creates the default one).',
+        );
+      }
+      if (typeof stmts.updateConvCloudSource?.run !== 'function') {
+        return res.status(500).json({ ok: false, error: 'Claude Cloud storage is unavailable' });
+      }
+      bootstrapCloudSource = buildCloudSourceRecord({
+        repoUrl: validatedSource.repoUrl,
+        branch: validatedSource.branch,
+        environmentId: cloudEnvironmentId,
+      });
+    }
     const modelState = buildModelCatalogWithProviders(
       getModelCatalogState(),
       openAISettings,
@@ -4689,7 +5019,15 @@ export function registerSessionsRoutes(app, deps) {
       requestedBootstrapModel
       || (isProviderModelAvailable(catalogSelectedModel, availableModels) ? catalogSelectedModel : '')
     );
-    const providerModelSelection = useOpenAIProvider
+    const providerModelSelection = useClaudeCloudProvider
+      // The cloud takes plain ids; with no model in the request the tab's
+      // default applies (never the shared catalog's current model).
+      ? resolveProviderModelSelection({
+          requestedModel: stripModelTierSuffix(requestedBootstrapModel),
+          configuredModel: claudeCloudSettings.defaultModel,
+          availableModels: Array.isArray(claudeCloudSettings.models) ? claudeCloudSettings.models : [],
+        })
+      : useOpenAIProvider
       ? resolveProviderModelSelection({
           requestedModel: providerRequestedModel(availableOpenAIModels),
           // The removed resolveOpenAISessionModel carried this last-resort id.
@@ -4719,14 +5057,18 @@ export function registerSessionsRoutes(app, deps) {
     // Per-provider pre-checks used to duplicate it and had drifted apart in
     // wording, casing rules and whether they listed the alternatives.
     if (providerModelSelection && !providerModelSelection.ok) {
-      const providerLabel = useOpenAIProvider
-        ? 'OpenAI'
-        : (useClaudeProvider ? 'Claude' : (useCursorProvider ? 'Cursor' : 'Grok'));
-      const providerCode = useOpenAIProvider
-        ? 'OPENAI_MODEL_UNAVAILABLE'
-        : (useClaudeProvider
-          ? 'CLAUDE_MODEL_UNAVAILABLE'
-          : (useCursorProvider ? 'CURSOR_MODEL_UNAVAILABLE' : 'GROK_MODEL_UNAVAILABLE'));
+      const providerLabel = useClaudeCloudProvider
+        ? 'Claude Cloud'
+        : (useOpenAIProvider
+          ? 'OpenAI'
+          : (useClaudeProvider ? 'Claude' : (useCursorProvider ? 'Cursor' : 'Grok')));
+      const providerCode = useClaudeCloudProvider
+        ? 'CLAUDE_CLOUD_MODEL_UNAVAILABLE'
+        : (useOpenAIProvider
+          ? 'OPENAI_MODEL_UNAVAILABLE'
+          : (useClaudeProvider
+            ? 'CLAUDE_MODEL_UNAVAILABLE'
+            : (useCursorProvider ? 'CURSOR_MODEL_UNAVAILABLE' : 'GROK_MODEL_UNAVAILABLE')));
       return res.status(400).json({
         ok: false,
         error: `${providerLabel} model "${providerModelSelection.requestedModel}" is not available`,
@@ -4792,7 +5134,7 @@ export function registerSessionsRoutes(app, deps) {
         code: 'OPENAI_IMAGE_MODEL_REQUIRED',
       });
     }
-    if (!useOpenAIProvider && !useClaudeProvider && !useCursorProvider && !useGrokProvider) {
+    if (!useClaudeCloudProvider && !useOpenAIProvider && !useClaudeProvider && !useCursorProvider && !useGrokProvider) {
       const selectedProviders = Array.isArray(modelState?.providersByModel?.[String(selectedModel || '').trim().toLowerCase()])
         ? modelState.providersByModel[String(selectedModel || '').trim().toLowerCase()]
         : [];
@@ -4834,13 +5176,15 @@ export function registerSessionsRoutes(app, deps) {
       }
     }
 
-    const bootstrapProviderType = useOpenAIProvider
-      ? 'openai'
-      : (useClaudeProvider
-        ? 'claude'
-        : (useCursorProvider
-          ? 'cursor'
-          : (useGrokProvider ? 'grok' : 'github')));
+    const bootstrapProviderType = useClaudeCloudProvider
+      ? 'claude-cloud'
+      : (useOpenAIProvider
+        ? 'openai'
+        : (useClaudeProvider
+          ? 'claude'
+          : (useCursorProvider
+            ? 'cursor'
+            : (useGrokProvider ? 'grok' : 'github'))));
     // Preferences are written in the same transaction as the conversation, so
     // the caller's current mode has to arrive with the request: without it every
     // new chat would be stored as the default one and reset the composer. An
@@ -4889,9 +5233,14 @@ export function registerSessionsRoutes(app, deps) {
           {
             assignConfiguredProvider: true,
             providerType: bootstrapProviderType,
-            providerModel: (useOpenAIProvider || useClaudeProvider || useCursorProvider || useGrokProvider) ? selectedModel : null,
+            providerModel: (useClaudeCloudProvider || useOpenAIProvider || useClaudeProvider || useCursorProvider || useGrokProvider) ? selectedModel : null,
           },
         );
+        // What the cloud session will clone, stored with the conversation so
+        // a cloud conversation never exists without its repository.
+        if (bootstrapCloudSource) {
+          stmts.updateConvCloudSource.run(JSON.stringify(bootstrapCloudSource), conversationId);
+        }
         const preferences = persistConversationPreferences({
           db,
           stmts,
@@ -5001,6 +5350,9 @@ export function registerSessionsRoutes(app, deps) {
         conversationId,
         conversation,
         origin: parseRemoteRelayOriginJson(conversation?.origin_json),
+        cloud: bootstrapCloudSource
+          ? buildConversationCloudPayload({ cloudSourceJson: bootstrapCloudSource })
+          : null,
         runtimeSessionId: runtimeSession?.id || null,
         ownerSessionId,
         worker: ownerWorker,
@@ -5043,6 +5395,7 @@ export function registerSessionsRoutes(app, deps) {
       featureFlags,
       supervisorSnapshot: sessionWorkerSupervisor?.snapshot?.({ pendingQuestionSessionIds }) || null,
       queueRows: listSessionWorkerQueueRows.all(...SESSION_WORKER_STATUS_QUEUE_STATES),
+      processList: sessionWorkerProcessInspector?.getLastRead?.() || null,
     });
     const activeRuntimeSessionCount = featureFlags?.SESSION_WORKER_ROUTING_ENABLED === true
       ? Number(sessionWorkerStatus?.onlineBoundProcessCount || 0)
@@ -5103,6 +5456,7 @@ export function registerSessionsRoutes(app, deps) {
       restartOrchestrator: relayRestartOrchestrator?.getState?.() || null,
       relayShutdown: runtimeState.relayShutdown || null,
       hostSuspend: runtimeState.hostSuspend || null,
+      usageLimit: runtimeState.usageLimit || null,
       platform: process.platform,
       features: featureFlags || {},
       sessionWorker: sessionWorkerStatus,
@@ -5259,6 +5613,7 @@ export function registerSessionsRoutes(app, deps) {
       model: String(settings?.model || 'claude-sonnet-5').trim() || 'claude-sonnet-5',
       models: Array.isArray(settings?.models) ? settings.models : [],
       availableModels: Array.isArray(settings?.availableModels) ? settings.availableModels : [],
+      ...claudeAttributionSettingsFields(settings),
     });
   });
 
@@ -5307,6 +5662,7 @@ export function registerSessionsRoutes(app, deps) {
       model: String(currentSettings?.model || result.model || 'claude-sonnet-5').trim() || 'claude-sonnet-5',
       models: Array.isArray(currentSettings?.models) ? currentSettings.models : [],
       availableModels: Array.isArray(currentSettings?.availableModels) ? currentSettings.availableModels : [],
+      ...claudeAttributionSettingsFields(currentSettings),
       reconciliation,
     };
     io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
@@ -6250,6 +6606,39 @@ export function registerSessionsRoutes(app, deps) {
     return res.json({ ok: true, cancelled: !!result.cancelled, state: result.state });
   });
 
+  // Turns paused at the Claude usage limit (usage-limit-pause-service): the
+  // held follow-up can be sent before the reset, or dropped.
+  app.get('/api/usage-limit', auth, (req, res) => {
+    if (!usageLimitPauseService) {
+      return res.status(501).json({ ok: false, error: 'Usage limit handling is unavailable' });
+    }
+    return res.json({
+      ok: true,
+      account: usageLimitPauseService.getAccountState(),
+      pauses: usageLimitPauseService.listPauses(),
+    });
+  });
+
+  app.post('/api/usage-limit/resume', auth, (req, res) => {
+    if (!usageLimitPauseService) {
+      return res.status(501).json({ ok: false, error: 'Usage limit handling is unavailable' });
+    }
+    const conversationId = String(req.body?.conversationId || '').trim();
+    if (!conversationId) return res.status(400).json({ ok: false, error: 'Missing conversationId' });
+    const result = usageLimitPauseService.resumeNow({ conversationId });
+    return res.json({ ok: true, resumed: !!result.resumed, messageId: result.messageId || null, pause: result.state });
+  });
+
+  app.post('/api/usage-limit/cancel', auth, (req, res) => {
+    if (!usageLimitPauseService) {
+      return res.status(501).json({ ok: false, error: 'Usage limit handling is unavailable' });
+    }
+    const conversationId = String(req.body?.conversationId || '').trim();
+    if (!conversationId) return res.status(400).json({ ok: false, error: 'Missing conversationId' });
+    const result = usageLimitPauseService.cancel({ conversationId });
+    return res.json({ ok: true, cancelled: !!result.cancelled, messageId: result.messageId || null, pause: result.state });
+  });
+
   app.get('/api/restart-orchestrator', auth, (req, res) => {
     ensureSessionId(req, res);
     return res.json({ orchestrator: relayRestartOrchestrator?.getState?.() || null });
@@ -6567,78 +6956,155 @@ export function registerSessionsRoutes(app, deps) {
   // token/cost diagnostics carried as collapsible detail sections. Each
   // provider is independent — a failing source yields an "unavailable" card
   // rather than a failed response — so the modal always renders something.
+  // The live reads behind the usage modal (GitHub quota and billing, Grok,
+  // Cursor, the Claude account) each take a second or more. The modal asks
+  // for the provider on screen only (`?providers=github,claude`); the other
+  // cards are built from the last live answer kept here, and the answer says
+  // which cards are live (`live`) and when each was read (`fetchedAt`). No
+  // parameter = everything live, as before.
+  const usageLiveCache = {
+    copilot: null, // { summary, error, at }
+    copilotBilling: null, // { value, at }
+    grokBilling: null,
+    cursorBilling: null,
+  };
+  const USAGE_PROVIDER_IDS = ['github', 'claude', 'claude-cloud', 'cursor', 'grok'];
+
+  function parseUsageProviders(raw) {
+    const text = Array.isArray(raw) ? raw.join(',') : String(raw ?? '');
+    if (!text.trim()) return null;
+    const ids = text.split(',').map((part) => part.trim().toLowerCase()).filter(Boolean);
+    if (ids.includes('all')) return null;
+    return new Set(ids.filter((id) => USAGE_PROVIDER_IDS.includes(id)));
+  }
+
   app.get('/api/usage', auth, async (req, res) => {
     const wantsLegacyOnly = String(req.query?.legacy || '').trim() === '1';
-
-    let summary = null;
-    let summaryError = null;
-    try {
-      summary = await fetchUsageSummaryPromise(fetchUsageSummary);
-    } catch (error) {
-      summaryError = String(error?.message || error || 'Failed to fetch usage data');
-    }
+    const requested = parseUsageProviders(req.query?.providers);
+    const live = (id) => requested === null || requested.has(id);
+    const nowIso = () => new Date().toISOString();
+
+    // The Copilot quota: live, or the last live answer.
+    const readCopilotSummary = async () => {
+      if (!live('github') && usageLiveCache.copilot) return usageLiveCache.copilot;
+      let summary = null;
+      let error = null;
+      try {
+        summary = await fetchUsageSummaryPromise(fetchUsageSummary);
+      } catch (fetchError) {
+        error = String(fetchError?.message || fetchError || 'Failed to fetch usage data');
+      }
+      const entry = { summary, error, at: nowIso() };
+      // A failure is not kept over a good answer.
+      if (summary || !usageLiveCache.copilot) usageLiveCache.copilot = entry;
+      return entry;
+    };
 
     if (wantsLegacyOnly || !planUsageService) {
-      if (!summary) return res.status(500).json({ error: summaryError || 'Usage is unavailable' });
+      const { summary, error } = await readCopilotSummary();
+      if (!summary) return res.status(500).json({ error: error || 'Usage is unavailable' });
       return res.json(summary);
     }
 
-    // Billing detail is best-effort and must never delay or fail the card.
-    let billing = null;
-    if (typeof fetchCopilotBillingUsage === 'function') {
+    // Each best-effort read: live when asked for, else the cached answer.
+    const cachedOrLive = async (key, wanted, read) => {
+      if (!wanted && usageLiveCache[key]) return usageLiveCache[key];
+      let value = null;
       try {
-        billing = await fetchCopilotBillingUsage();
-      } catch (error) {
-        billing = { items: [], timePeriod: null, scope: null, error: String(error?.message || error) };
+        value = await read();
+      } catch {
+        value = null;
       }
-    }
+      const entry = { value, at: nowIso() };
+      if (value !== null || !usageLiveCache[key]) usageLiveCache[key] = entry;
+      return entry;
+    };
 
     const claudeSettings = getClaudeProviderSettings();
     const cursorSettings = getCursorProviderSettings();
     const grokSettings = getGrokProviderSettings();
-    // Live Grok subscription quota is best-effort like Copilot billing.
-    let grokBilling = null;
-    if (grokSettings?.enabled === true && typeof fetchGrokBillingUsage === 'function') {
-      try {
-        grokBilling = await fetchGrokBillingUsage();
-      } catch {
-        grokBilling = null;
-      }
-    }
-    // Live Cursor plan quota (dashboard session token) — same best-effort rule.
-    let cursorBilling = null;
+    let claudeCloudEnabled = false;
+    try {
+      claudeCloudEnabled = claudeCloudSettingsService?.getSettings?.()?.enabled === true;
+    } catch {
+      claudeCloudEnabled = false;
+    }
+
+    // Live Claude account usage, three seconds at most; without it the
+    // Claude card shows the last turn's snapshot. The service keeps its own
+    // minute of cache; when the modal did not ask for a Claude card live,
+    // the last answer is used however old it is.
+    const wantsClaudeLive = live('claude') || live('claude-cloud');
+    const claudeAccountPromise = typeof claudeAccountUsageService?.getAccountUsage === 'function'
+      ? (wantsClaudeLive
+        ? Promise.resolve()
+          .then(() => claudeAccountUsageService.getAccountUsage({ timeoutMs: 3000 }))
+          .catch(() => null)
+        : Promise.resolve(claudeAccountUsageService.peekAccountUsage?.() ?? null))
+      : Promise.resolve(null);
+
+    // All reads side by side: the modal waits for the slowest, not the sum.
+    const [copilot, billingEntry, grokEntry, cursorEntry, claudeAccount] = await Promise.all([
+      readCopilotSummary(),
+      cachedOrLive('copilotBilling', live('github'), () => (
+        typeof fetchCopilotBillingUsage === 'function'
+          ? fetchCopilotBillingUsage().catch((error) => ({ items: [], timePeriod: null, scope: null, error: String(error?.message || error) }))
+          : null
+      )),
+      cachedOrLive('grokBilling', live('grok'), () => (
+        grokSettings?.enabled === true && typeof fetchGrokBillingUsage === 'function' ? fetchGrokBillingUsage() : null
+      )),
+      cachedOrLive('cursorBilling', live('cursor'), () => (
+        cursorSettings?.enabled === true && typeof fetchCursorDashboardUsage === 'function' ? fetchCursorDashboardUsage() : null
+      )),
+      claudeAccountPromise,
+    ]);
+
+    // Whether a token exists at all decides which of the two very different
+    // "no live bars" explanations the Cursor card shows.
     let cursorDashboardAuth = null;
-    if (cursorSettings?.enabled === true && typeof fetchCursorDashboardUsage === 'function') {
-      try {
-        cursorBilling = await fetchCursorDashboardUsage();
-      } catch {
-        cursorBilling = null;
-      }
-      // Whether a token exists at all decides which of the two very different
-      // "no live bars" explanations the card shows.
+    if (cursorSettings?.enabled === true) {
       try {
         cursorDashboardAuth = getCursorDashboardTokenSettings() || null;
       } catch {
         cursorDashboardAuth = null;
       }
     }
+
     const report = planUsageService.buildReport({
-      copilotSummary: summary,
-      copilotError: summaryError,
-      copilotBilling: billing,
+      copilotSummary: copilot.summary,
+      copilotError: copilot.error,
+      copilotCapturedAt: copilot.at,
+      copilotBilling: billingEntry.value,
       claudeConfigured: claudeSettings?.enabled === true,
+      claudeAccount,
+      claudeCloudConfigured: claudeCloudEnabled,
+      // The conversation the modal was opened from: a cloud conversation gets
+      // its own cost on the Claude Cloud card.
+      conversationId: String(req.query?.conversationId || '').trim(),
       cursorConfigured: cursorSettings?.enabled === true,
       cursorAllowances: getCursorPlanAllowanceSettings(),
-      cursorBilling,
+      cursorBilling: cursorEntry.value,
       cursorDashboardAuth,
       grokConfigured: grokSettings?.enabled === true,
       grokAllowances: getGrokPlanAllowanceSettings(),
-      grokBilling,
+      grokBilling: grokEntry.value,
     });
 
     // Legacy top-level fields stay alongside `providers` so an older cached
     // client shell keeps working through a PWA update.
-    return res.json({ ...(summary || {}), ...report });
+    return res.json({
+      ...(copilot.summary || {}),
+      ...report,
+      live: USAGE_PROVIDER_IDS.filter(live),
+      fetchedAt: {
+        github: copilot.at,
+        claude: claudeAccount?.fetchedAt || null,
+        'claude-cloud': claudeAccount?.fetchedAt || null,
+        cursor: cursorEntry.at,
+        grok: grokEntry.at,
+      },
+    });
   });
 
   app.get('/api/settings/cursor-allowance', auth, (_req, res) => {