@oar-sh/oar 0.9.15 → 0.9.17

package/server/routes/sessions-routes.mjs

@@ -17,7 +17,7 @@ import {
 } from '../services/conversation-history-page.mjs';
 import { MESSAGE_PIN_LIMIT, buildPinList } from '../services/message-pin-list.mjs';
 import { buildHiddenMessageList } from '../services/hidden-message-list.mjs';
-import { persistConversationPreferences } from '../services/conversation-preferences-service.mjs';
+import { persistConversationPreferences, readMayCreateSessions } from '../services/conversation-preferences-service.mjs';
 import { parseAutoCompactWindow } from '../../shared/auto-compact-window.mjs';
 import {
   claudeBackgroundCommandLimitSettingsFields,
@@ -46,6 +46,14 @@ import { stopSessionWorkerProcesses } from '../services/session-worker-stop-serv
 import { createClaudeAuthService } from '../services/claude-auth-service.mjs';
 import { createCliInstallService } from '../services/cli-install-service.mjs';
 import { createGrokAuthService } from '../services/grok-auth-service.mjs';
+import { parseDeepSeekSettingsUpdateRequest } from '../services/deepseek-settings-service.mjs';
+import {
+  DEEPSEEK_PROVIDER_TYPE,
+  DEEPSEEK_REASONING_EFFORTS,
+  DEFAULT_DEEPSEEK_MODEL,
+  DEFAULT_DEEPSEEK_REASONING_EFFORT,
+  deepseekReasoningEffortFor,
+} from '../../shared/deepseek-models.mjs';
 import {
   isWithinAllowedPrefix,
   readWorkspaceRootPathFromBody,
@@ -61,7 +69,7 @@ import { requestHostOf } from '../services/request-boundary.mjs';
 import { parseRemoteRelayOriginJson } from '../repositories/remote-relay-repository.mjs';
 import { createShareRepository } from '../repositories/share-repository.mjs';
 import { createShareAccessLog, readShareRequestViewer } from '../services/share-access-log-service.mjs';
-import { resolveGroupDisplayName } from '../repositories/conversation-group-repository.mjs';
+import { GROUP_NAME_MAX, resolveGroupDisplayName } from '../repositories/conversation-group-repository.mjs';
 import { conversationGroupPosition, conversationGroupRole, groupActivityTimes, pageConversationRows } from '../public/app/conversation-group-order.mjs';
 import { admitRemoteRelayRequest, publicRemoteRelayOrigin, readRemoteRelayRequest } from '../services/remote-relay-inbound.mjs';
 import {
@@ -82,6 +90,14 @@ import {
 } from '../../shared/model-id.mjs';
 import { openAIReasoningEffortsForModel } from '../../shared/openai-reasoning.mjs';
 import { stripModelTierSuffix } from '../../shared/claude-cloud/repo-url.mjs';
+import {
+  REMOTE_RELAY_ERROR_CODES,
+  REMOTE_RELAY_GROUP_LIMITS,
+  REMOTE_RELAY_SESSION_SETTINGS,
+  formatSessionGroupList,
+  resolveSessionGroupReference,
+  validateRemoteRelaySessionSettings,
+} from '../../shared/remote-relay-contract.mjs';
 import {
   buildCloudSourceRecord,
   buildConversationCloudPayload,
@@ -125,6 +141,10 @@ import {
   derivePwaShortName,
 } from '../../shared/pwa-app-name.mjs';
 import { parseRestartResumeUpdate } from '../services/restart-resume-service.mjs';
+import { removeClaudeSessionLeftovers } from '../services/claude-session-leftovers.mjs';
+import { deepseekStartingBalanceNote } from '../services/plan-usage-deepseek.mjs';
+import { DEEPSEEK_USAGE_CHECKPOINTS_TABLE } from '../migrations/0024-deepseek-usage-totals.mjs';
+import { claudeProjectDirSlug } from '../services/claude-session-root-service.mjs';
 
 export { mapUsageSnapshotRow };
 
@@ -786,6 +806,55 @@ export function buildModelCatalogWithGrokProvider(modelState = {}, grokSettings
   };
 }
 
+export function buildModelCatalogWithDeepSeekProvider(modelState = {}, deepseekSettings = {}) {
+  const configured = deepseekSettings?.enabled === true;
+  const model = String(deepseekSettings?.model || '').trim();
+  if (!configured || !model) return { ...modelState };
+  const deepseekModels = [];
+  const seenDeepSeekModels = new Set();
+  const listed = Array.isArray(deepseekSettings?.models) ? deepseekSettings.models : [];
+  for (const candidate of [model, ...listed]) {
+    const modelId = String(candidate || '').trim();
+    const lowerId = modelId.toLowerCase();
+    if (!modelId || seenDeepSeekModels.has(lowerId)) continue;
+    seenDeepSeekModels.add(lowerId);
+    deepseekModels.push(modelId);
+  }
+  const models = Array.from(new Set([...(Array.isArray(modelState?.models) ? modelState.models : []), ...deepseekModels]));
+  const reasoningByModel = { ...(modelState?.reasoningByModel || {}) };
+  const deepseekReasoningByModel = {};
+  const modelMetadataByModel = { ...(modelState?.modelMetadataByModel || {}) };
+  const providersByModel = { ...(modelState?.providersByModel || {}) };
+  // DeepSeek's ids are its own ("deepseek-*"): no other provider lists them,
+  // so the provider tag is never shared with Copilot.
+  for (const deepseekModel of deepseekModels) {
+    const lowerKey = deepseekModel.toLowerCase();
+    deepseekReasoningByModel[lowerKey] = [...DEEPSEEK_REASONING_EFFORTS];
+    if (!Array.isArray(reasoningByModel[lowerKey]) || reasoningByModel[lowerKey].length === 0) {
+      reasoningByModel[lowerKey] = [...DEEPSEEK_REASONING_EFFORTS];
+    }
+    const existingProviders = Array.isArray(providersByModel[deepseekModel])
+      ? providersByModel[deepseekModel]
+      : (Array.isArray(providersByModel[lowerKey]) ? providersByModel[lowerKey] : []);
+    providersByModel[deepseekModel] = Array.from(new Set([...existingProviders, DEEPSEEK_PROVIDER_TYPE]));
+    modelMetadataByModel[deepseekModel] = {
+      ...(modelMetadataByModel[deepseekModel] || {}),
+      provider: modelMetadataByModel[deepseekModel]?.provider || DEEPSEEK_PROVIDER_TYPE,
+    };
+  }
+  return {
+    ...modelState,
+    models,
+    reasoningByModel,
+    reasoningByProvider: {
+      ...(modelState?.reasoningByProvider || {}),
+      [DEEPSEEK_PROVIDER_TYPE]: deepseekReasoningByModel,
+    },
+    modelMetadataByModel,
+    providersByModel,
+  };
+}
+
 function normalizeRequestedProviderType(value = '') {
   const normalized = String(value || '').trim().toLowerCase();
   if (normalized === 'openai' || normalized === 'openai-byok') return 'openai';
@@ -795,6 +864,7 @@ function normalizeRequestedProviderType(value = '') {
   if (normalized === 'claude-cloud') return 'claude-cloud';
   if (normalized === 'cursor') return 'cursor';
   if (normalized === 'grok' || normalized === 'xai' || normalized === 'xai-grok') return 'grok';
+  if (normalized === 'deepseek') return 'deepseek';
   if (normalized === 'github' || normalized === 'github-copilot') return 'github';
   return '';
 }
@@ -1413,6 +1483,8 @@ export function buildConversationSessionRootPayload({
   claudeNativeSessionId = '',
   workspaceRootPath = '',
   resolveClaudeSessionRoot = null,
+  // The same Claude Code layout, in the DeepSeek workers' own config dir.
+  resolveDeepSeekSessionRoot = null,
   resolveCursorSessionRoot = null,
 } = {}) {
   const sid = String(sdkSessionId || '').trim() || String(conversationId || '').trim();
@@ -1435,10 +1507,12 @@ export function buildConversationSessionRootPayload({
   // Claude sessions have no ~/.copilot/session-state entry — only the Copilot
   // CLI creates those — so they resolve against the Agent SDK's own layout and
   // never fall through to the branch below.
-  if (String(providerType || '').trim().toLowerCase() === 'claude') {
+  const claudeCodeProvider = String(providerType || '').trim().toLowerCase();
+  if (claudeCodeProvider === 'claude' || claudeCodeProvider === 'deepseek') {
     const nativeSessionId = String(claudeNativeSessionId || '').trim();
-    if (!nativeSessionId || typeof resolveClaudeSessionRoot !== 'function') return null;
-    const claudeRoot = resolveClaudeSessionRoot({
+    const resolveRoot = claudeCodeProvider === 'deepseek' ? resolveDeepSeekSessionRoot : resolveClaudeSessionRoot;
+    if (!nativeSessionId || typeof resolveRoot !== 'function') return null;
+    const claudeRoot = resolveRoot({
       claudeNativeSessionId: nativeSessionId,
       workspaceRootPath: String(workspaceRootPath || '').trim(),
     });
@@ -2060,6 +2134,10 @@ export function registerSessionsRoutes(app, deps) {
     // is simply off.
     claudeCloudSettingsService = null,
     claudeCloudSessionService = null,
+    // DeepSeek (provider `deepseek`): its key, models, base URL and
+    // attribution (services/deepseek-settings-service.mjs). Absent in older
+    // wiring and most tests, where the provider is simply off.
+    deepseekSettingsService = null,
     reconcileUnstartedConversationProviders = async () => ({
       updatedUnstartedConversations: 0,
       skippedStartedConversations: 0,
@@ -2100,6 +2178,13 @@ export function registerSessionsRoutes(app, deps) {
     // nothing while Claude Cloud is off, and absent (tests, older wiring) the
     // Claude card stays the last turn's snapshot.
     claudeAccountUsageService = null,
+    // Optional DeepSeek balance (deepseek-balance-service.mjs); it reads
+    // nothing while DeepSeek is off, and absent (tests, older wiring) the
+    // DeepSeek card shows the relay's estimated spend alone.
+    deepseekBalanceService = null,
+    // Optional DeepSeek usage export (deepseek-usage-import.mjs): its figures
+    // replace the estimate on the days it covers; absent, the card is the estimate.
+    deepseekUsageImportService = null,
     getCursorPlanAllowanceSettings = () => ({ cursorModelsUsd: null, otherModelsUsd: null, resetDay: 1 }),
     setCursorPlanAllowanceSettings = () => ({ ok: false, error: 'Cursor allowance settings are unavailable' }),
     getGrokPlanAllowanceSettings = () => ({ monthlyUsd: null, resetDay: 1 }),
@@ -2131,6 +2216,10 @@ export function registerSessionsRoutes(app, deps) {
     sessionWorkerStopOverrides = null,
     resolveSessionStateRoot,
     resolveClaudeSessionRoot = null,
+    resolveDeepSeekSessionRoot = null,
+    // DeepSeek's Claude Code config directory, which the relay owns: a deleted
+    // conversation's leftovers there go with it (claude-session-leftovers.mjs).
+    deepseekClaudeConfigDir = '',
     resolveCursorSessionRoot = null,
     getTurnCeilingMinutes = () => DEFAULT_TURN_CEILING_MINUTES,
     setTurnCeilingMinutes = () => ({ ok: false, error: 'Turn ceiling settings are unavailable' }),
@@ -2167,6 +2256,12 @@ export function registerSessionsRoutes(app, deps) {
     // Relay events: what each session is doing (state, tasks) and the
     // subscriptions that end with an archived or deleted conversation.
     relayEventService = null,
+    // Relay schedules: the ones that fire into or were set by an archived or
+    // deleted conversation end with it.
+    relayScheduleService = null,
+    // Questions that don't block: the pending ones in an archived or deleted
+    // conversation end with it.
+    relayAskService = null,
     sessionActivityTracker = null,
     // Public shares and their access log (migration 0016); built on `db` when
     // the wiring does not pass one.
@@ -2342,6 +2437,9 @@ export function registerSessionsRoutes(app, deps) {
     FROM message_usage_snapshots
     WHERE conversation_id = ?
   `);
+  // Asked on each delete: the usage service creates the table at its own
+  // start, which may come after these routes'.
+  const findDeepSeekUsageCheckpointsTable = db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`);
   const hardDeleteConversationRows = db.transaction((conversationId) => {
     if (typeof stmts.deleteConvQuestions?.run === 'function') {
       stmts.deleteConvQuestions.run(conversationId);
@@ -2371,6 +2469,11 @@ export function registerSessionsRoutes(app, deps) {
     db.prepare(`DELETE FROM queue WHERE conversation_id = ?`).run(conversationId);
     db.prepare(`DELETE FROM messages WHERE conversation_id = ?`).run(conversationId);
     db.prepare(`DELETE FROM runtime_sessions WHERE conversation_id = ?`).run(conversationId);
+    // A DeepSeek conversation's usage checkpoints are only good for diffing its
+    // later reports; the totals and days they fed stay, as history.
+    if (findDeepSeekUsageCheckpointsTable.get(DEEPSEEK_USAGE_CHECKPOINTS_TABLE)) {
+      db.prepare(`DELETE FROM ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} WHERE conversation_id = ?`).run(conversationId);
+    }
     // The share access log goes with it; the share rows follow the foreign key.
     shares().forgetConversation(conversationId);
     db.prepare(`DELETE FROM conversations WHERE id = ?`).run(conversationId);
@@ -2396,17 +2499,25 @@ export function registerSessionsRoutes(app, deps) {
   const sessionLaunchMutex = createKeyedMutex();
   const relaunchCoalescer = createRelaunchCoalescer({ windowMs: RELAUNCH_COALESCE_WINDOW_MS });
 
+  function getDeepSeekProviderSettings() {
+    return deepseekSettingsService?.getSettings?.()
+      || { configured: false, enabled: false, model: DEFAULT_DEEPSEEK_MODEL, models: [], availableModels: [] };
+  }
+
   // Layer every enabled provider's models onto the base Copilot catalog.
   function buildModelCatalogWithProviders(modelState, openAISettings = getOpenAIProviderSettings()) {
-    return buildModelCatalogWithGrokProvider(
-      buildModelCatalogWithCursorProvider(
-        buildModelCatalogWithClaudeProvider(
-          buildModelCatalogWithOpenAIProvider(modelState, openAISettings),
-          getClaudeProviderSettings(),
+    return buildModelCatalogWithDeepSeekProvider(
+      buildModelCatalogWithGrokProvider(
+        buildModelCatalogWithCursorProvider(
+          buildModelCatalogWithClaudeProvider(
+            buildModelCatalogWithOpenAIProvider(modelState, openAISettings),
+            getClaudeProviderSettings(),
+          ),
+          getCursorProviderSettings(),
         ),
-        getCursorProviderSettings(),
+        getGrokProviderSettings(),
       ),
-      getGrokProviderSettings(),
+      getDeepSeekProviderSettings(),
     );
   }
 
@@ -2522,10 +2633,10 @@ export function registerSessionsRoutes(app, deps) {
    * it. Nothing else in the project folder is touched — it holds every other
    * session of that workspace and the project memory.
    */
-  function deleteClaudeCliSession({ conversation, runtimeSession }) {
+  function deleteClaudeCliSession({ conversation, runtimeSession, resolveRoot = resolveClaudeSessionRoot }) {
     const nativeSessionId = String(runtimeSession?.claude_native_session_id || '').trim();
-    if (!nativeSessionId || typeof resolveClaudeSessionRoot !== 'function') return { deleted: null };
-    const anchors = resolveClaudeSessionRoot({
+    if (!nativeSessionId || typeof resolveRoot !== 'function') return { deleted: null };
+    const anchors = resolveRoot({
       claudeNativeSessionId: nativeSessionId,
       workspaceRootPath: String(
         conversation?.runtime_workspace_root_path || conversation?.configured_workspace_root_path || '',
@@ -2539,7 +2650,25 @@ export function registerSessionsRoutes(app, deps) {
       .filter((target) => path.dirname(target) === projectDir
         && [nativeSessionId, `${nativeSessionId}.jsonl`].includes(path.basename(target)));
     for (const target of targets) fs.rmSync(target, { recursive: true, force: true });
-    return { deleted: targets.length > 0 };
+    return { deleted: targets.length > 0, projectDirPath: projectDir };
+  }
+
+  /**
+   * A DeepSeek conversation's Claude Code session: the transcript as for
+   * Claude, then what the killed CLI left in the relay's own config directory
+   * (its hook environment, registration, shell snapshot, and the project
+   * folder once no session is left in it).
+   */
+  function deleteDeepSeekCliSession({ conversation, runtimeSession }) {
+    const outcome = deleteClaudeCliSession({ conversation, runtimeSession, resolveRoot: resolveDeepSeekSessionRoot });
+    const configRoot = String(deepseekClaudeConfigDir || '').trim();
+    const nativeSessionId = String(runtimeSession?.claude_native_session_id || '').trim();
+    if (!configRoot || !nativeSessionId) return { deleted: outcome.deleted };
+    const workspaceRoot = String(conversation?.runtime_workspace_root_path || conversation?.configured_workspace_root_path || '').trim();
+    const projectDirPath = outcome.projectDirPath
+      || (workspaceRoot ? path.join(configRoot, 'projects', claudeProjectDirSlug(workspaceRoot)) : '');
+    const removed = removeClaudeSessionLeftovers({ configRoot, nativeSessionId, projectDirPath });
+    return { deleted: outcome.deleted === null && removed.length ? true : outcome.deleted };
   }
 
   /**
@@ -2580,6 +2709,7 @@ export function registerSessionsRoutes(app, deps) {
     const provider = String(runtimeSession?.provider_type || '').trim().toLowerCase();
     try {
       if (provider === 'claude') return deleteClaudeCliSession({ conversation, runtimeSession });
+      if (provider === 'deepseek') return deleteDeepSeekCliSession({ conversation, runtimeSession });
       if (!sdkSessionId) return { deleted: null };
       if (!provider || provider === 'github' || provider === 'openai') {
         return await deleteCopilotCliSession({ sdkSessionId, conversationId });
@@ -2616,6 +2746,8 @@ export function registerSessionsRoutes(app, deps) {
       io.emit('conversation_deleted', { conversationId });
       if (leftGroupId) emitGroupChanged(leftGroupId, [conversationId]);
       try { relayEventService?.noteConversationGone?.(conversationId, { deleted: true }); } catch {}
+      try { relayScheduleService?.noteConversationGone?.(conversationId, { deleted: true }); } catch {}
+      try { relayAskService?.noteConversationGone?.(conversationId); } catch {}
       finalized.push(conversationId);
     }
     return finalized;
@@ -2641,6 +2773,8 @@ export function registerSessionsRoutes(app, deps) {
       parentConversationId: group.parentConversationId || null,
       memberCount: members.length,
       liveMemberCount: members.filter((member) => !member.archived).length,
+      // An owner's group an agent emptied, which stays until the owner acts.
+      keptEmptyAt: group.keptEmptyAt || null,
     };
   }
 
@@ -2702,6 +2836,38 @@ export function registerSessionsRoutes(app, deps) {
     });
   }
 
+  // A session group named at bootstrap (an agent's create_session `group`):
+  // what the lookup sees is what an agent may see (GET /api/conversation-groups).
+  const autoTitle = (title) => resolveConversationTitle({ title, titleSource: 'auto' });
+  const listGroupsForAgents = () => conversationGroups?.listGroups?.({ headTitle: autoTitle }) || [];
+
+  /** The 400 body for a group this relay does not have, or has several of by that name. */
+  function bootstrapGroupRefusal(found, requested, groups) {
+    const ambiguous = found.status === 'ambiguous';
+    const listed = ambiguous ? found.matches : groups;
+    const asked = String(requested || '').replace(/["\r\n]+/g, ' ').slice(0, 80);
+    let error;
+    if (ambiguous) error = `"${asked}" names several session groups here: ${formatSessionGroupList(listed)}. Pass the id.`;
+    else if (groups.length) error = `No session group "${asked}" here. Groups: ${formatSessionGroupList(groups)}.`;
+    else error = `No session group "${asked}" here: this relay has no session groups.`;
+    return {
+      ok: false,
+      code: ambiguous ? 'SESSION_GROUP_AMBIGUOUS' : 'SESSION_GROUP_NOT_FOUND',
+      error: `${error} No conversation was created.`,
+      groups: listed.slice(0, REMOTE_RELAY_GROUP_LIMITS.refusalMax).map((group) => ({ id: group.id, name: group.name })),
+      // How many there are when `groups` is cut to the cap.
+      ...(listed.length > REMOTE_RELAY_GROUP_LIMITS.refusalMax ? { groupsTotal: listed.length } : {}),
+    };
+  }
+
+  /** `{ id, name, role }` of the group a conversation sits in (list_sessions' shape), or null. */
+  function conversationGroupField(conversationId) {
+    const membership = conversationGroups?.membershipsOf?.([conversationId])?.[conversationId];
+    if (!membership?.groupId) return null;
+    const described = conversationGroups.describeGroup?.(membership.groupId, { headTitle: autoTitle }) || null;
+    return { id: membership.groupId, name: described?.displayName || null, role: membership.role === 'head' ? 'head' : 'member' };
+  }
+
   /** The `cloud` field of a conversation payload; null unless it is a cloud one. */
   function conversationCloudPayload(conversation, runtimeSession) {
     return buildConversationCloudPayload({
@@ -3116,6 +3282,8 @@ 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),
+        // The owner let this agent-started session's agents start sessions.
+        mayCreateSessions: readMayCreateSessions(r),
         // Set on Claude Cloud conversations: repository, branch, session link.
         cloud: buildConversationCloudPayload({
           cloudSourceJson: r.cloud_source_json,
@@ -3140,6 +3308,14 @@ export function registerSessionsRoutes(app, deps) {
     for (const groupId of new Set(page.rows.map((row) => String(row?.group_id || '')).filter((id) => groups.has(id)))) {
       groupsPayload[groupId] = groupSummaryPayload(groups.get(groupId));
     }
+    // The owner's groups an agent emptied have no row to come with: the live
+    // list's first page brings them, so the sidebar shows them as empty
+    // groups the owner can rename or dissolve.
+    if (archivedMode !== 'only' && !beforeConversationId) {
+      for (const group of conversationGroups?.listKeptEmptyGroups?.() || []) {
+        groupsPayload[group.id] = groupSummaryPayload(group);
+      }
+    }
 
     return res.json({
       conversations,
@@ -3467,9 +3643,10 @@ export function registerSessionsRoutes(app, deps) {
     const providerType = String(runtimeSession?.provider_type || 'github').trim().toLowerCase();
     // 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.
+    // usage), and so does the DeepSeek worker (the Claude one, pointed at
+    // DeepSeek), so all five providers share the stored reader.
     const usesStoredContextUsage = providerType === 'claude' || providerType === 'cursor'
-      || providerType === 'grok' || providerType === 'claude-cloud';
+      || providerType === 'grok' || providerType === 'claude-cloud' || providerType === 'deepseek';
 
     const parsed = usesStoredContextUsage
       ? (() => {
@@ -3498,11 +3675,12 @@ export function registerSessionsRoutes(app, deps) {
       String(runtimeSession?.conversation_id || '').trim() || lookupId,
     );
     const autoCompactWindow = parseAutoCompactWindow(conversationRow?.auto_compact_window);
-    // Only the local Claude worker runs a CLI whose window the slider sets;
-    // it reports that CLI on its heartbeat's steering snapshot.
+    // Only the local Claude worker (and the DeepSeek one, the same runner)
+    // runs a CLI whose window the slider sets; it reports that CLI on its
+    // heartbeat's steering snapshot.
     const windowStatus = resolveAutoCompactWindowStatus({
       storedWindow: autoCompactWindow,
-      steering: providerType === 'claude' && copilotSessionId
+      steering: (providerType === 'claude' || providerType === 'deepseek') && copilotSessionId
         ? sessionWorkerRegistry?.getWorker?.(copilotSessionId)?.steering || null
         : null,
     });
@@ -3753,6 +3931,7 @@ export function registerSessionsRoutes(app, deps) {
       claudeNativeSessionId: runtimeSession?.claude_native_session_id || '',
       workspaceRootPath: workspaceState?.currentWorkspaceRootPath || '',
       resolveClaudeSessionRoot,
+      resolveDeepSeekSessionRoot,
       resolveCursorSessionRoot,
     });
     const dbMessages = stmts.getMessages.all(conversationId);
@@ -3862,6 +4041,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),
+      mayCreateSessions: readMayCreateSessions(conv),
       cloud: conversationCloudPayload(conv, runtimeSession),
       group: conversationGroupPayload(conversationId),
       groupPosition: conversationGroupPositionOf(conv),
@@ -4425,6 +4605,7 @@ export function registerSessionsRoutes(app, deps) {
       claudeNativeSessionId: runtimeSession?.claude_native_session_id || '',
       workspaceRootPath: workspaceState?.currentWorkspaceRootPath || '',
       resolveClaudeSessionRoot,
+      resolveDeepSeekSessionRoot,
       resolveCursorSessionRoot,
     });
     const historyCursor = { limit, beforeMessageId, beforeTimestamp, afterMessageId, afterTimestamp, aroundMessageId };
@@ -4563,6 +4744,7 @@ 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),
+      mayCreateSessions: readMayCreateSessions(conv),
       // Set on Claude Cloud conversations: repository, branch, session link.
       cloud: conversationCloudPayload(conv, runtimeSession),
       // The session group it is in, with the other members; null when none.
@@ -4738,42 +4920,36 @@ export function registerSessionsRoutes(app, deps) {
     });
   });
 
-  app.patch('/api/conversation/:id/preferences', auth, (req, res) => {
-    const conversationId = String(req.params.id || '').trim();
-    if (!conversationId) return res.status(400).json({ error: 'Missing conversation id' });
-    const senderClientId = String(req.body?.clientId || '').trim() || null;
-
-    const existing = stmts.getConvAnyStatus.get(conversationId);
-    if (existing && String(existing.status || '').trim() === 'deleted') {
-      return res.status(404).json({ error: 'Conversation not found' });
-    }
-
+  /**
+   * Writes a conversation's preferences and tells every open page: the one
+   * code path of PATCH …/preferences (the composer, the context modal) and of
+   * an agent's update_session (PATCH …/settings). `body` uses the preferences
+   * route's keys; a key it does not mention keeps the stored value.
+   */
+  function applyConversationPreferences({ conversationId, existing, body = {}, senderClientId = null }) {
     const now = new Date().toISOString();
     // Every write replaces all four columns, so a caller that only wants to
     // change one field (the context modal's auto-compact slider) must not have
     // the others reset to their defaults: an unmentioned key keeps the stored
     // value. The composer always sends all three, so its behaviour — including
     // clearing a preference with an explicit '' — is unchanged.
-    const mentions = (key) => Object.prototype.hasOwnProperty.call(req.body || {}, key);
+    const mentions = (key) => Object.prototype.hasOwnProperty.call(body || {}, key);
     const preferredRelayMode = normalizeRelayModePreference(
-      mentions('preferredRelayMode') ? req.body?.preferredRelayMode : existing?.preferred_relay_mode,
+      mentions('preferredRelayMode') ? body.preferredRelayMode : existing?.preferred_relay_mode,
       {
         supportedRelayModes: SUPPORTED_RELAY_MODES,
         fallbackMode: DEFAULT_RELAY_MODE,
       },
     );
     const preferredModel = normalizePreferredModel(
-      mentions('preferredModel') ? req.body?.preferredModel : existing?.preferred_model,
+      mentions('preferredModel') ? body.preferredModel : existing?.preferred_model,
     );
     const preferredReasoningEffort = normalizePreferredReasoningEffort(
-      mentions('preferredReasoningEffort') ? req.body?.preferredReasoningEffort : existing?.preferred_reasoning_effort,
+      mentions('preferredReasoningEffort') ? body.preferredReasoningEffort : existing?.preferred_reasoning_effort,
     );
     // Only an explicit mention rewrites the window (null = Auto is a real
     // value, so a plain falsy check would not do). Same for the thinking
     // control, where null = Host default.
-    const mentionsAutoCompactWindow = mentions('autoCompactWindow');
-    const mentionsThinkingEnabled = mentions('thinkingEnabled');
-    const mentionsThinkingDisplay = mentions('thinkingDisplay');
     const persisted = persistConversationPreferences({
       db,
       stmts,
@@ -4781,21 +4957,21 @@ export function registerSessionsRoutes(app, deps) {
       preferredRelayMode,
       preferredModel,
       preferredReasoningEffort,
-      ...(mentionsAutoCompactWindow
-        ? { autoCompactWindow: parseAutoCompactWindow(req.body?.autoCompactWindow) }
+      ...(mentions('autoCompactWindow')
+        ? { autoCompactWindow: parseAutoCompactWindow(body.autoCompactWindow) }
         : {}),
-      ...(mentionsThinkingEnabled
-        ? { thinkingEnabled: parseThinkingEnabled(req.body?.thinkingEnabled) }
+      ...(mentions('thinkingEnabled')
+        ? { thinkingEnabled: parseThinkingEnabled(body.thinkingEnabled) }
         : {}),
-      ...(mentionsThinkingDisplay
-        ? { thinkingDisplay: parseThinkingDisplay(req.body?.thinkingDisplay) }
+      ...(mentions('thinkingDisplay')
+        ? { thinkingDisplay: parseThinkingDisplay(body.thinkingDisplay) }
         : {}),
+      ...(mentions('mayCreateSessions') ? { mayCreateSessions: body.mayCreateSessions === true } : {}),
       updatedAt: now,
       createIfMissing: !existing,
       createTitle: 'Session',
     });
-
-    io.emit('conversation_preferences_updated', {
+    const payload = {
       conversationId,
       preferredRelayMode: persisted.preferredRelayMode,
       preferredModel: persisted.preferredModel,
@@ -4803,22 +4979,447 @@ export function registerSessionsRoutes(app, deps) {
       autoCompactWindow: persisted.autoCompactWindow ?? null,
       thinkingEnabled: persisted.thinkingEnabled ?? null,
       thinkingDisplay: persisted.thinkingDisplay ?? null,
+      mayCreateSessions: persisted.mayCreateSessions === true,
       updatedAt: persisted.updatedAt,
       senderClientId,
+    };
+    io.emit('conversation_preferences_updated', payload);
+    return { ...payload, created: persisted.created };
+  }
+
+  app.patch('/api/conversation/:id/preferences', auth, (req, res) => {
+    const conversationId = String(req.params.id || '').trim();
+    if (!conversationId) return res.status(400).json({ error: 'Missing conversation id' });
+    const senderClientId = String(req.body?.clientId || '').trim() || null;
+
+    const existing = stmts.getConvAnyStatus.get(conversationId);
+    if (existing && String(existing.status || '').trim() === 'deleted') {
+      return res.status(404).json({ error: 'Conversation not found' });
+    }
+    // "Agents in this conversation may start sessions" is the owner's alone:
+    // an agent (of this relay or a paired one) could grant it to itself.
+    if (Object.prototype.hasOwnProperty.call(req.body || {}, 'mayCreateSessions')) {
+      if (readRemoteRelayRequest(req, remoteRelayInbound).remote) {
+        return res.status(403).json({ error: 'Whether agents in a conversation may start sessions is the owner\'s setting alone.' });
+      }
+      if (typeof req.body.mayCreateSessions !== 'boolean') {
+        return res.status(400).json({ error: 'mayCreateSessions must be true or false' });
+      }
+      if (!stmts.conversationsHaveMayCreateSessions) {
+        return res.status(503).json({ error: 'This setting is unavailable until the relay restarts (its storage is missing).' });
+      }
+    }
+
+    const persisted = applyConversationPreferences({ conversationId, existing, body: req.body || {}, senderClientId });
+    return res.json({ ok: true, ...persisted });
+  });
+
+  // ─── PATCH /api/conversation/:id/settings — the remote_relay tool's update_session ───
+  //
+  // `{ settings: { model, effort, mode, auto_compact_window, title, group,
+  // thinking_enabled, thinking_display, cwd }, dry_run, owner_approved }`.
+  // Reached by an agent of this relay (the loopback) and by a paired relay's
+  // agent (under the inbound switch); the owner may call it too. It applies
+  // this relay's own rule: an agent changes freely only a session its own
+  // conversation started (the request's origin against the session's); any
+  // other changes only with `owner_approved` (the calling relay asked its
+  // user). A dry run checks everything, writes nothing, and says whether
+  // approval is needed. A group the owner made never goes through this path
+  // (it may stay empty); one an agent made here goes once empty. A step that
+  // fails after an earlier one wrote answers `changed` with what was written.
+  // Every write goes through the code the owner's
+  // own controls use (preferences, title, group, workspace root), with their
+  // socket events, so an open page shows the change at once. The owner's
+  // "may start sessions" switch is not among the settings.
+
+  const SESSION_SETTINGS_INVALID = 'SESSION_SETTINGS_INVALID';
+
+  function currentSessionSettings(conversationId) {
+    const conv = stmts.getConvAnyStatus.get(conversationId) || {};
+    const runtime = stmts.getRuntimeSessionByConversation?.get?.(conversationId) || null;
+    const workspace = resolveConversationWorkspaceState?.({ conversationId }) || null;
+    const window = parseAutoCompactWindow(conv.auto_compact_window);
+    return {
+      model: normalizePreferredModel(conv.preferred_model) || String(runtime?.provider_model || runtime?.model || '').trim() || null,
+      effort: normalizePreferredReasoningEffort(conv.preferred_reasoning_effort) || null,
+      mode: normalizeRelayModePreference(conv.preferred_relay_mode, { supportedRelayModes: SUPPORTED_RELAY_MODES, fallbackMode: DEFAULT_RELAY_MODE }),
+      auto_compact_window: window === null ? 'auto' : window,
+      title: resolveConversationTitle({ title: conv.title, titleSource: conv.title_source }) || null,
+      group: conversationGroupField(conversationId),
+      thinking_enabled: parseThinkingEnabled(conv.thinking_enabled),
+      thinking_display: parseThinkingDisplay(conv.thinking_display),
+      cwd: String(workspace?.currentWorkspaceRootPath || workspace?.configuredWorkspaceRootPath || conv.configured_workspace_root_path || '').trim() || null,
+    };
+  }
+
+  /**
+   * Whether the agent calling the settings route started this session from
+   * its own conversation: the session's origin names that conversation, and
+   * this relay's own agent (the loopback) for a local origin, the same
+   * paired relay for one from there.
+   */
+  function sessionStartedByCaller(createdBy, remoteRequest) {
+    const caller = remoteRequest?.remote ? remoteRequest.origin : null;
+    if (!createdBy || !caller) return false;
+    const callerConversation = String(caller.conversationId || '').trim();
+    if (!callerConversation || String(createdBy.conversationId || '').trim() !== callerConversation) return false;
+    if (remoteRequest.local === true) return createdBy.local === true && caller.local === true;
+    const relayId = String(createdBy.relayId || '').trim();
+    return createdBy.local !== true && !!relayId && relayId === String(caller.relayId || '').trim();
+  }
+
+  /** Why a session cannot move to another folder now ('' when it can). */
+  function sessionBusyReason(conversationId) {
+    if (Number(countActiveConversationQueueRows.get(conversationId)?.count || 0) > 0) return 'a turn is queued or running there';
+    const state = describeSessionActivity(conversationId)?.sessionState;
+    if (state === 'running_turn') return 'a turn is running there';
+    if (state === 'background_only') return 'a background task is running there';
+    return '';
+  }
+
+  /**
+   * What update_session would do: `{ ok, plan }` or `{ ok:false, status,
+   * body }`. The plan holds what changes (`changed`, in the order of the
+   * contract's settings) and how.
+   */
+  function planSessionSettings(conversation, raw) {
+    const conversationId = String(conversation.id);
+    const fail = (status, error, extra = {}) => ({ ok: false, status, body: { ok: false, error, ...extra } });
+    const settingsInput = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null;
+    if (!settingsInput) return fail(400, 'settings must be an object', { code: SESSION_SETTINGS_INVALID });
+    const unknown = Object.keys(settingsInput).filter((key) => !REMOTE_RELAY_SESSION_SETTINGS.includes(key));
+    if (unknown.length) {
+      return fail(400, `Not a setting an agent may change: ${unknown.slice(0, 10).join(', ')}. Settings: ${REMOTE_RELAY_SESSION_SETTINGS.join(', ')}.`, { code: SESSION_SETTINGS_INVALID });
+    }
+    const checked = validateRemoteRelaySessionSettings(settingsInput);
+    if (!checked.ok) return fail(400, checked.error, { code: SESSION_SETTINGS_INVALID });
+    const wanted = checked.values;
+    const current = currentSessionSettings(conversationId);
+    const runtime = stmts.getRuntimeSessionByConversation?.get?.(conversationId) || null;
+    const provider = String(runtime?.provider_type || 'github').trim().toLowerCase() || 'github';
+    const plan = { conversationId, provider, current, wanted, changed: [], preferences: {}, notes: [] };
+    const change = (key) => { if (!plan.changed.includes(key)) plan.changed.push(key); };
+
+    if (wanted.model !== undefined && normalizePreferredModel(wanted.model) !== normalizePreferredModel(conversation.preferred_model)) {
+      plan.preferences.preferredModel = wanted.model;
+      change('model');
+    }
+    if (wanted.effort !== undefined && wanted.effort !== normalizePreferredReasoningEffort(conversation.preferred_reasoning_effort)) {
+      plan.preferences.preferredReasoningEffort = wanted.effort;
+      change('effort');
+    }
+    if (wanted.mode !== undefined) {
+      if (!SUPPORTED_RELAY_MODES.includes(wanted.mode)) {
+        return fail(400, `This relay has no mode "${wanted.mode}". Modes: ${SUPPORTED_RELAY_MODES.join(', ')}.`, { code: SESSION_SETTINGS_INVALID });
+      }
+      if (wanted.mode !== current.mode) {
+        plan.preferences.preferredRelayMode = wanted.mode;
+        change('mode');
+      }
+    }
+    if (wanted.auto_compact_window !== undefined) {
+      const window = wanted.auto_compact_window === 'auto' ? null : parseAutoCompactWindow(wanted.auto_compact_window);
+      if (window !== parseAutoCompactWindow(conversation.auto_compact_window)) {
+        plan.preferences.autoCompactWindow = window;
+        change('auto_compact_window');
+      }
+      if (window !== null && window !== wanted.auto_compact_window) {
+        plan.notes.push(`auto_compact_window ${wanted.auto_compact_window} was taken as ${window}, the nearest window this relay offers.`);
+      }
+    }
+    if (wanted.thinking_enabled !== undefined && wanted.thinking_enabled !== current.thinking_enabled) {
+      plan.preferences.thinkingEnabled = wanted.thinking_enabled;
+      change('thinking_enabled');
+    }
+    if (wanted.thinking_display !== undefined && wanted.thinking_display !== current.thinking_display) {
+      plan.preferences.thinkingDisplay = wanted.thinking_display;
+      change('thinking_display');
+    }
+    if (provider !== 'claude' && ['auto_compact_window', 'thinking_enabled', 'thinking_display'].some((key) => wanted[key] !== undefined)) {
+      plan.notes.push(`auto_compact_window and thinking apply to Claude sessions only; this one runs on ${provider}, so they are stored but change nothing there.`);
+    }
+    if (wanted.title !== undefined) {
+      const title = normalizeConversationTitle(wanted.title);
+      if (title !== current.title) {
+        plan.title = title;
+        change('title');
+      }
+    }
+    if (Object.prototype.hasOwnProperty.call(wanted, 'group')) {
+      if (!conversationGroups?.enabled) {
+        return fail(503, 'Session groups are not available on this relay (its storage for them is missing). Nothing was changed.', { code: 'SESSION_GROUPS_UNAVAILABLE' });
+      }
+      if (wanted.group === null) {
+        if (current.group) {
+          plan.group = { action: 'leave', previous: current.group };
+          change('group');
+        }
+      } else {
+        const groups = listGroupsForAgents();
+        const found = resolveSessionGroupReference(groups, wanted.group);
+        if (found.status === 'ambiguous') {
+          const refusal = bootstrapGroupRefusal(found, wanted.group, groups);
+          return fail(400, refusal.error.replace('No conversation was created.', 'Nothing was changed.'), { code: refusal.code, groups: refusal.groups, ...(refusal.groupsTotal ? { groupsTotal: refusal.groupsTotal } : {}) });
+        }
+        if (found.status === 'found') {
+          if (current.group?.id !== found.group.id) {
+            plan.group = { action: 'join', id: found.group.id, name: found.group.name };
+            change('group');
+          }
+        } else if (/^grp_/i.test(wanted.group)) {
+          // An id that is not there names no group to make.
+          const refusal = bootstrapGroupRefusal(found, wanted.group, groups);
+          return fail(400, refusal.error.replace('No conversation was created.', 'Nothing was changed.'), { code: refusal.code, groups: refusal.groups, ...(refusal.groupsTotal ? { groupsTotal: refusal.groupsTotal } : {}) });
+        } else if (wanted.group.replace(/\s+/g, ' ').length > GROUP_NAME_MAX) {
+          return fail(400, `A group name has at most ${GROUP_NAME_MAX} characters. Nothing was changed.`, { code: SESSION_SETTINGS_INVALID });
+        } else {
+          plan.group = { action: 'create', name: wanted.group.replace(/\s+/g, ' ') };
+          change('group');
+        }
+      }
+    }
+    if (wanted.cwd !== undefined) {
+      if (provider === 'claude-cloud') {
+        return fail(400, 'cwd does not apply to a Claude Cloud session: it works on a clone of its repository. Nothing was changed.', { code: SESSION_SETTINGS_INVALID });
+      }
+      if (typeof updateConversationConfiguredWorkspaceRoot !== 'function') {
+        return fail(503, 'Conversation workspace updates are unavailable on this relay. Nothing was changed.', { code: SESSION_SETTINGS_INVALID });
+      }
+      const validated = validateRequestedWorkspaceRoot(wanted.cwd, { allowList: workspaceRootAllowList });
+      if (!validated.ok) {
+        return fail(validated.code === 'root-path-not-allowed' ? 403 : 400, `${validated.error || 'cwd is not a folder this relay may use'}. Nothing was changed.`, { code: validated.code || SESSION_SETTINGS_INVALID });
+      }
+      if (normalizeWorkspaceRootKey(validated.realPath) !== normalizeWorkspaceRootKey(current.cwd || '')) {
+        const busy = sessionBusyReason(conversationId);
+        if (busy) {
+          return fail(409, `The session cannot move to another folder now: ${busy}. Wait for it to finish (wait or read_session), then try again. Nothing was changed.`, { code: 'SESSION_BUSY', reason: busy });
+        }
+        plan.cwd = validated.realPath;
+        change('cwd');
+      }
+    }
+    plan.changed.sort((a, b) => REMOTE_RELAY_SESSION_SETTINGS.indexOf(a) - REMOTE_RELAY_SESSION_SETTINGS.indexOf(b));
+    return { ok: true, plan };
+  }
+
+  /** The session's folder through the owner's CWD path: saved, and its CLI relaunched there when it has one. */
+  async function applySessionCwd(plan, req) {
+    const { conversationId } = plan;
+    const rateLimited = consumeWorkspaceRootRateLimit(conversationId, req);
+    if (!rateLimited.ok) {
+      return { ok: false, status: 429, body: { ok: false, code: 'rate-limited', error: 'Too many CWD updates. Try again shortly. Nothing was changed.' } };
+    }
+    const sdkSessionId = String(resolveConversationWorkspaceState?.({ conversationId })?.sdkSessionId || '').trim();
+    if (!sdkSessionId) {
+      // Never launched: the folder is saved for its first launch.
+      const saved = await sessionLaunchMutex.runExclusive(`conv:${conversationId}`, () => {
+        const busy = sessionBusyReason(conversationId);
+        return busy ? { ok: false, busyReason: busy } : updateConversationConfiguredWorkspaceRoot({ conversationId, rootPath: plan.cwd });
+      });
+      if (saved?.busyReason) {
+        return { ok: false, status: 409, body: { ok: false, code: 'SESSION_BUSY', reason: saved.busyReason, error: `The session cannot move to another folder now: ${saved.busyReason}. Wait for it to finish, then try again. Nothing was changed.` } };
+      }
+      if (!saved?.ok) return { ok: false, status: 400, body: { ok: false, error: `${saved?.error || 'Failed to update the session\'s folder'}. Nothing was changed.` } };
+      const state = saved.state || null;
+      io.emit('conversation_workspace_root_updated', {
+        conversationId,
+        sdkSessionId: state?.sdkSessionId || null,
+        configuredWorkspaceRootPath: state?.configuredWorkspaceRootPath || null,
+        configuredWorkspaceRootName: state?.configuredWorkspaceRootName || null,
+        runtimeWorkspaceRootPath: state?.runtimeWorkspaceRootPath || null,
+        runtimeWorkspaceRootName: state?.runtimeWorkspaceRootName || null,
+        currentWorkspaceRootPath: state?.currentWorkspaceRootPath || null,
+        currentWorkspaceRootName: state?.currentWorkspaceRootName || null,
+        recentWorkspaceRoots: Array.isArray(workspaceRootPayload()?.recentWorkspaceRoots) ? workspaceRootPayload().recentWorkspaceRoots : [],
+      });
+      return { ok: true, relaunched: false };
+    }
+    let attempt;
+    try {
+      attempt = await sessionLaunchMutex.tryRunExclusive(sdkSessionId, () => {
+        // Asked again under the lock, right before the relaunch: a turn or a
+        // task may have started since the plan.
+        const busy = sessionBusyReason(conversationId);
+        if (busy) return { busyReason: busy };
+        return runWorkspaceRootRelaunch({ conversationId, sdkSessionId, rootPath: plan.cwd });
+      });
+    } catch (error) {
+      return { ok: false, status: 500, body: { ok: false, code: 'relaunch-error', error: error?.message || 'Failed to relaunch the CLI' } };
+    }
+    if (attempt.busy) {
+      return { ok: false, status: 409, body: { ok: false, code: 'SESSION_BUSY', reason: 'its CLI is being relaunched', error: 'The session cannot move to another folder now: its CLI is being relaunched. Try again shortly. Nothing was changed.' } };
+    }
+    const outcome = attempt.result || {};
+    if (outcome.busyReason) {
+      return { ok: false, status: 409, body: { ok: false, code: 'SESSION_BUSY', reason: outcome.busyReason, error: `The session cannot move to another folder now: ${outcome.busyReason}. Wait for it to finish, then try again. Nothing was changed.` } };
+    }
+    // The relay could not read its process list, so it cannot tell whether
+    // the session's CLI still runs: nothing is stopped or started.
+    if (/^process-list-unreadable/.test(String(outcome.error || ''))) {
+      return {
+        ok: false,
+        status: 503,
+        body: {
+          ok: false,
+          code: 'PROCESS_LIST_UNREADABLE',
+          error: 'This relay could not read its process list, so it cannot tell whether the session\'s CLI still runs; the folder was not changed. Try again shortly. Nothing was changed.',
+        },
+      };
+    }
+    if (outcome.statusCode !== 200 || outcome.body?.ok !== true) {
+      const body = outcome.body || {};
+      const busy = body.code === 'relaunch-not-eligible';
+      // A CLI that would not stop or start: the folder is saved for the next
+      // launch all the same (the owner's route does the same), so cwd changed.
+      const saved = !busy && !!body.configuredWorkspaceRootPath;
+      return {
+        ok: false,
+        status: outcome.statusCode || 500,
+        body: {
+          ...body,
+          ok: false,
+          ...(busy ? { code: 'SESSION_BUSY', reason: 'a turn is queued or running there' } : {}),
+          error: busy
+            ? `The session cannot move to another folder now: ${body.error || 'it is busy'}. Nothing was changed.`
+            : `${body.error || 'Failed to relaunch the CLI'}${saved ? ' The folder is saved for its next launch; nothing else was changed.' : ' Nothing was changed.'}`,
+          changed: saved ? ['cwd'] : [],
+        },
+      };
+    }
+    return {
+      ok: true,
+      relaunched: outcome.body.relaunched === true,
+      ...(outcome.body.relaunched === true ? {} : { warning: outcome.body.message || 'The folder is saved for the next launch, but the running CLI kept its current folder.' }),
+    };
+  }
+
+  app.patch('/api/conversation/:id/settings', auth, async (req, res) => {
+    const remoteRequest = admitRemoteRelayRequest(req, res, remoteRelayInbound);
+    if (!remoteRequest) return;
+    const requestedId = String(req.params.id || '').trim();
+    const conversation = requestedId ? resolveConversationByIdOrSdkSessionId(requestedId) : null;
+    if (!conversation || String(conversation.status || '').trim() === 'deleted') {
+      return res.status(404).json({ ok: false, code: 'SESSION_NOT_FOUND', error: 'Conversation not found' });
+    }
+    const conversationId = String(conversation.id);
+    const body = req.body && typeof req.body === 'object' ? req.body : {};
+    const planned = planSessionSettings(conversation, body.settings);
+    if (!planned.ok) return res.status(planned.status).json(planned.body);
+    const { plan } = planned;
+    const createdBy = parseRemoteRelayOriginJson(conversation.origin_json);
+    const byCaller = sessionStartedByCaller(createdBy, remoteRequest);
+    // An agent changes freely only a session its own conversation started;
+    // any other (the owner's, another agent's, its own creator's) needs the
+    // owner's Allow, which the calling relay asks for and states.
+    const approvalNeeded = remoteRequest.remote === true && !byCaller;
+    const facts = { session: conversationId, provider: plan.provider, ownerStarted: !createdBy, startedByCaller: byCaller, approvalNeeded };
+    if (body.dry_run === true) {
+      return res.json({
+        ok: true,
+        dryRun: true,
+        ...facts,
+        settings: plan.current,
+        changed: plan.changed,
+        ...(plan.group ? { group: plan.group } : {}),
+        ...(plan.notes.length ? { notes: plan.notes } : {}),
+      });
+    }
+    // This relay's own rule, whatever the calling relay checked.
+    if (approvalNeeded && body.owner_approved !== true) {
+      return res.status(403).json({
+        ok: false,
+        code: REMOTE_RELAY_ERROR_CODES.permission,
+        ...facts,
+        error: 'This session was not started by the calling conversation: an agent changes its settings only after the relay\'s owner allowed that for the calling conversation.',
+      });
+    }
+    if (!plan.changed.length) {
+      return res.json({ ok: true, ...facts, settings: plan.current, changed: [], ...(plan.notes.length ? { notes: plan.notes } : {}) });
+    }
+
+    // What is written so far: a step that fails later answers it, so a
+    // partial change is never passed off as none.
+    const written = [];
+    const failAfter = (status, payload) => res.status(status).json({
+      ...payload,
+      ok: false,
+      error: `${payload.error}${written.length ? ` These settings were changed before: ${written.join(', ')}.` : ' Nothing was changed.'}`,
+      changed: [...written],
     });
+    // The folder first: it is the one change that can fail after the checks
+    // (a CLI that does not stop or start), and then nothing else is written.
+    let cwdResult = null;
+    if (plan.cwd) {
+      cwdResult = await applySessionCwd(plan, req);
+      if (!cwdResult.ok) return res.status(cwdResult.status).json(cwdResult.body);
+      written.push('cwd');
+    }
+    if (plan.title !== undefined) {
+      const titled = persistConversationTitle({ db, stmts, io, conversationId, title: plan.title, resolveSessionStateRoot });
+      if (!titled.ok) return failAfter(titled.statusCode || 500, { error: titled.error || 'Failed to update the title.' });
+      written.push('title');
+    }
+    if (Object.keys(plan.preferences).length) {
+      applyConversationPreferences({
+        conversationId,
+        existing: stmts.getConvAnyStatus.get(conversationId),
+        body: plan.preferences,
+      });
+      written.push(...plan.changed.filter((key) => !['cwd', 'title', 'group'].includes(key)));
+    }
+    // Groups through the agent path: an owner's group the session leaves is
+    // never removed (it stays, empty if it was the last member); a group an
+    // agent made goes once empty.
+    const groupOptions = { keepOwnerGroups: remoteRequest.remote === true };
+    let groupCreated = null;
+    let groupPlan = plan.group;
+    if (groupPlan?.action === 'create') {
+      // Looked up once more right before it is made: a call that ran beside
+      // this one may have made the group of that name meanwhile.
+      const groups = listGroupsForAgents();
+      const found = resolveSessionGroupReference(groups, groupPlan.name);
+      if (found.status === 'found') groupPlan = { action: 'join', id: found.group.id, name: found.group.name };
+      // Several of that name by now: refused as the first lookup refuses.
+      if (found.status === 'ambiguous') {
+        const refusal = bootstrapGroupRefusal(found, groupPlan.name, groups);
+        return failAfter(400, {
+          code: refusal.code,
+          error: refusal.error.replace(' No conversation was created.', ''),
+          groups: refusal.groups,
+          ...(refusal.groupsTotal ? { groupsTotal: refusal.groupsTotal } : {}),
+        });
+      }
+    }
+    if (groupPlan?.action === 'leave') {
+      const left = conversationGroups.setMembership(conversationId, null, undefined, groupOptions);
+      if (left.ok && left.changed) emitGroupChanged(left.previousGroupId, [conversationId]);
+    } else if (groupPlan?.action === 'join') {
+      const joined = conversationGroups.setMembership(conversationId, groupPlan.id, undefined, groupOptions);
+      if (!joined.ok) {
+        return failAfter(400, { code: 'SESSION_GROUP_NOT_FOUND', error: `The session group ${groupPlan.id} is gone.` });
+      }
+      if (joined.changed) {
+        emitGroupChanged(groupPlan.id, [conversationId]);
+        if (joined.previousGroupId && joined.previousGroupId !== groupPlan.id) emitGroupChanged(joined.previousGroupId, [conversationId]);
+      }
+    } else if (groupPlan?.action === 'create') {
+      const previousGroupId = conversationGroups.groupOfConversation(conversationId)?.id || null;
+      const group = conversationGroups.createGroup({ name: groupPlan.name, conversationIds: [conversationId], agentMade: remoteRequest.remote === true, ...groupOptions });
+      groupCreated = group ? { id: group.id, name: group.name } : null;
+      if (group) emitGroupChanged(group.id, [conversationId]);
+      if (previousGroupId) emitGroupChanged(previousGroupId, [conversationId]);
+    }
 
+    const notes = [...plan.notes];
+    if (cwdResult?.warning) notes.push(cwdResult.warning);
     return res.json({
       ok: true,
-      conversationId,
-      preferredRelayMode: persisted.preferredRelayMode,
-      preferredModel: persisted.preferredModel,
-      preferredReasoningEffort: persisted.preferredReasoningEffort,
-      autoCompactWindow: persisted.autoCompactWindow ?? null,
-      thinkingEnabled: persisted.thinkingEnabled ?? null,
-      thinkingDisplay: persisted.thinkingDisplay ?? null,
-      updatedAt: persisted.updatedAt,
-      created: persisted.created,
-      senderClientId,
+      ...facts,
+      settings: currentSessionSettings(conversationId),
+      changed: plan.changed,
+      ...(cwdResult ? { relaunched: cwdResult.relaunched } : {}),
+      ...(groupCreated ? { groupCreated } : {}),
+      ...(notes.length ? { notes } : {}),
     });
   });
 
@@ -5426,6 +6027,8 @@ export function registerSessionsRoutes(app, deps) {
     if (wasShared) io.emit('share_revoked', { conversationId: id });
     if (leftGroupId) emitGroupChanged(leftGroupId, [id]);
     try { relayEventService?.noteConversationGone?.(id, { deleted: true }); } catch {}
+    try { relayScheduleService?.noteConversationGone?.(id, { deleted: true }); } catch {}
+    try { relayAskService?.noteConversationGone?.(id); } catch {}
     return { statusCode: 200, body: { ok: true, workerStopped, cliSessionDeleted: cliSession.deleted } };
   }
 
@@ -5516,6 +6119,9 @@ export function registerSessionsRoutes(app, deps) {
         io.emit('conversation_archived', { conversationId: id, archived: true });
         // Its subscriptions end, and so does its place in others'.
         try { relayEventService?.noteConversationGone?.(id); } catch {}
+        // So do its schedules.
+        try { relayScheduleService?.noteConversationGone?.(id); } catch {}
+        try { relayAskService?.noteConversationGone?.(id); } catch {}
         // The cloud session of a Claude Cloud conversation is archived with it;
         // best effort and not waited for.
         if (!sharedWithConversationId) {
@@ -5700,6 +6306,12 @@ export function registerSessionsRoutes(app, deps) {
       ...(Array.isArray(grokSettings?.models) ? grokSettings.models : []),
     ].map((value) => String(value || '').trim()).filter(Boolean);
     const availableGrokModels = new Set(grokModelCatalog.map((value) => value.toLowerCase()));
+    const deepseekSettings = getDeepSeekProviderSettings();
+    const deepseekModelCatalog = [
+      String(deepseekSettings?.model || '').trim(),
+      ...(Array.isArray(deepseekSettings?.models) ? deepseekSettings.models : []),
+    ].map((value) => String(value || '').trim()).filter(Boolean);
+    const availableDeepSeekModels = new Set(deepseekModelCatalog.map((value) => value.toLowerCase()));
     const useOpenAIProvider = requestedProviderType === 'openai'
       || requestedProviderType === 'openai-image'
       || (
@@ -5735,6 +6347,15 @@ export function registerSessionsRoutes(app, deps) {
         && availableGrokModels.has(requestedBootstrapModel.toLowerCase())
       )
     );
+    const useDeepSeekProvider = !useOpenAIProvider && !useClaudeProvider && !useCursorProvider && !useGrokProvider && (
+      requestedProviderType === 'deepseek'
+      || (
+        requestedProviderType === ''
+        && requestedBootstrapModel
+        && requestedBootstrapModel.toLowerCase() !== 'auto'
+        && availableDeepSeekModels.has(requestedBootstrapModel.toLowerCase())
+      )
+    );
     // Managed providers resolve the request against their own catalog only.
     // Routing it through the merged Copilot catalog first (resolveBootstrapModelSelection)
     // silently substituted that catalog's current model whenever the requested
@@ -5780,7 +6401,13 @@ export function registerSessionsRoutes(app, deps) {
                 configuredModel: grokSettings.model,
                 availableModels: grokModelCatalog,
               })
-            : null)));
+            : (useDeepSeekProvider
+              ? resolveProviderModelSelection({
+                  requestedModel: providerRequestedModel(deepseekModelCatalog),
+                  configuredModel: deepseekSettings.model,
+                  availableModels: deepseekModelCatalog,
+                })
+              : null))));
     // The single rejection for "this provider does not offer that model".
     // Per-provider pre-checks used to duplicate it and had drifted apart in
     // wording, casing rules and whether they listed the alternatives.
@@ -5789,14 +6416,16 @@ export function registerSessionsRoutes(app, deps) {
         ? 'Claude Cloud'
         : (useOpenAIProvider
           ? 'OpenAI'
-          : (useClaudeProvider ? 'Claude' : (useCursorProvider ? 'Cursor' : 'Grok')));
+          : (useClaudeProvider ? 'Claude' : (useCursorProvider ? 'Cursor' : (useGrokProvider ? 'Grok' : 'DeepSeek'))));
       const providerCode = useClaudeCloudProvider
         ? 'CLAUDE_CLOUD_MODEL_UNAVAILABLE'
         : (useOpenAIProvider
           ? 'OPENAI_MODEL_UNAVAILABLE'
           : (useClaudeProvider
             ? 'CLAUDE_MODEL_UNAVAILABLE'
-            : (useCursorProvider ? 'CURSOR_MODEL_UNAVAILABLE' : 'GROK_MODEL_UNAVAILABLE')));
+            : (useCursorProvider
+              ? 'CURSOR_MODEL_UNAVAILABLE'
+              : (useGrokProvider ? 'GROK_MODEL_UNAVAILABLE' : 'DEEPSEEK_MODEL_UNAVAILABLE'))));
       return res.status(400).json({
         ok: false,
         error: `${providerLabel} model "${providerModelSelection.requestedModel}" is not available`,
@@ -5816,6 +6445,7 @@ export function registerSessionsRoutes(app, deps) {
     if (
       remoteRequest.remote
       && !useClaudeCloudProvider && !useOpenAIProvider && !useClaudeProvider && !useCursorProvider && !useGrokProvider
+      && !useDeepSeekProvider
     ) {
       const mergedModels = Array.isArray(modelState?.models) ? modelState.models : [];
       const providersByModel = modelState?.providersByModel && typeof modelState.providersByModel === 'object'
@@ -5881,6 +6511,39 @@ export function registerSessionsRoutes(app, deps) {
         code: 'GROK_NOT_CONFIGURED',
       });
     }
+    if (useDeepSeekProvider && deepseekSettings?.enabled !== true) {
+      return res.status(400).json({
+        ok: false,
+        error: deepseekSettings?.configured === true
+          ? 'DeepSeek is switched off for new conversations'
+          : 'DeepSeek API key is not configured',
+        code: 'DEEPSEEK_NOT_CONFIGURED',
+      });
+    }
+
+    // The session group an agent's create_session names (an id or an exact
+    // name): resolved before anything is written, so an unknown one creates
+    // nothing. It wins over the creator's group. Only the row created here is
+    // ever placed; the group routes stay the owner's.
+    const rawGroup = req.body?.group;
+    if (rawGroup !== undefined && rawGroup !== null && typeof rawGroup !== 'string') {
+      return res.status(400).json({ ok: false, code: 'SESSION_GROUP_INVALID', error: 'group must be text: a group id or name' });
+    }
+    const requestedGroup = String(rawGroup || '').trim();
+    let bootstrapGroupId = '';
+    if (requestedGroup) {
+      if (!conversationGroups?.enabled) {
+        return res.status(503).json({
+          ok: false,
+          code: 'SESSION_GROUPS_UNAVAILABLE',
+          error: 'Session groups are not available on this relay (its storage for them is missing). No conversation was created.',
+        });
+      }
+      const groups = listGroupsForAgents();
+      const found = resolveSessionGroupReference(groups, requestedGroup);
+      if (found.status !== 'found') return res.status(400).json(bootstrapGroupRefusal(found, requestedGroup, groups));
+      bootstrapGroupId = found.group.id;
+    }
 
     // Optional launch CWD from the New Chat modal. Validated before insertConv
     // so a rejected path never leaves an orphaned conversation behind.
@@ -5911,7 +6574,7 @@ export function registerSessionsRoutes(app, deps) {
         code: 'OPENAI_IMAGE_MODEL_REQUIRED',
       });
     }
-    if (!useClaudeCloudProvider && !useOpenAIProvider && !useClaudeProvider && !useCursorProvider && !useGrokProvider) {
+    if (!useClaudeCloudProvider && !useOpenAIProvider && !useClaudeProvider && !useCursorProvider && !useGrokProvider && !useDeepSeekProvider) {
       const selectedProviders = Array.isArray(modelState?.providersByModel?.[String(selectedModel || '').trim().toLowerCase()])
         ? modelState.providersByModel[String(selectedModel || '').trim().toLowerCase()]
         : [];
@@ -5951,6 +6614,15 @@ export function registerSessionsRoutes(app, deps) {
           code: 'GROK_PROVIDER_REQUIRED',
         });
       }
+      const deepseekOnlySelection = selectedProviders.length > 0
+        && selectedProviders.every((provider) => String(provider || '').trim().toLowerCase() === DEEPSEEK_PROVIDER_TYPE);
+      if (deepseekOnlySelection) {
+        return res.status(400).json({
+          ok: false,
+          error: `Model "${selectedModel}" requires the DeepSeek provider`,
+          code: 'DEEPSEEK_PROVIDER_REQUIRED',
+        });
+      }
     }
 
     const bootstrapProviderType = useClaudeCloudProvider
@@ -5961,7 +6633,7 @@ export function registerSessionsRoutes(app, deps) {
           ? 'claude'
           : (useCursorProvider
             ? 'cursor'
-            : (useGrokProvider ? 'grok' : 'github'))));
+            : (useGrokProvider ? 'grok' : (useDeepSeekProvider ? 'deepseek' : '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
@@ -5977,6 +6649,9 @@ export function registerSessionsRoutes(app, deps) {
     const bootstrapReasoning = resolveProviderReasoningEffort({
       requestedEffort: req.body?.reasoningEffort || copilotVariantEffort,
       strict: bootstrapProviderType === 'openai',
+      ...(bootstrapProviderType === 'deepseek'
+        ? { defaultEffort: DEFAULT_DEEPSEEK_REASONING_EFFORT, aliasFor: deepseekReasoningEffortFor }
+        : {}),
       supportedEfforts: supportedReasoningEffortsForProviderModel({
         providerType: bootstrapProviderType,
         model: selectedModel,
@@ -6000,14 +6675,23 @@ export function registerSessionsRoutes(app, deps) {
       // binding and preferences: every later reader treats these three as a
       // single canonical tuple.
       let attachedGroupId = null;
+      let attachedGroupIds = [];
       const commitBootstrapState = db.transaction(() => {
         stmts.insertConv.run(conversationId, title, now, now);
         if (remoteRequest.origin) remoteRelayInbound?.repository?.setConversationOrigin?.(conversationId, remoteRequest.origin);
-        // A session an agent of this relay created joins its creator's group
-        // (or starts one with the creator as head). A creator on a paired
-        // relay has no local flag and groups nothing.
-        if (remoteRequest.origin?.local === true && remoteRequest.origin.conversationId) {
+        if (bootstrapGroupId) {
+          // The group named in the request. Dissolved since it was looked up:
+          // the whole bootstrap rolls back, and the caller hears it as unknown.
+          const placed = conversationGroups.setMembership(conversationId, bootstrapGroupId, now);
+          if (!placed?.ok) throw Object.assign(new Error('session group gone'), { bootstrapGroupGone: true });
+          attachedGroupId = bootstrapGroupId;
+          attachedGroupIds = [conversationId];
+        } else if (remoteRequest.origin?.local === true && remoteRequest.origin.conversationId) {
+          // A session an agent of this relay created joins its creator's group
+          // (or starts one with the creator as head). A creator on a paired
+          // relay has no local flag and groups nothing.
           attachedGroupId = conversationGroups?.attachCreatedConversation?.(conversationId, remoteRequest.origin.conversationId, now) || null;
+          attachedGroupIds = [conversationId, remoteRequest.origin.conversationId];
         }
         const boundRuntimeSession = ensureRuntimeSessionBinding(
           conversationId,
@@ -6017,7 +6701,7 @@ export function registerSessionsRoutes(app, deps) {
           {
             assignConfiguredProvider: true,
             providerType: bootstrapProviderType,
-            providerModel: (useClaudeCloudProvider || useOpenAIProvider || useClaudeProvider || useCursorProvider || useGrokProvider) ? selectedModel : null,
+            providerModel: (useClaudeCloudProvider || useOpenAIProvider || useClaudeProvider || useCursorProvider || useGrokProvider || useDeepSeekProvider) ? selectedModel : null,
           },
         );
         // What the cloud session will clone, stored with the conversation so
@@ -6037,7 +6721,7 @@ export function registerSessionsRoutes(app, deps) {
         return { boundRuntimeSession, preferences };
       });
       const { boundRuntimeSession, preferences } = commitBootstrapState();
-      if (attachedGroupId) emitGroupChanged(attachedGroupId, [conversationId, remoteRequest.origin.conversationId]);
+      if (attachedGroupId) emitGroupChanged(attachedGroupId, attachedGroupIds);
       const runtimeSession = boundRuntimeSession;
       const preferredRelayMode = preferences?.preferredRelayMode || bootstrapRelayMode;
       const preferredModel = preferences?.preferredModel || selectedModel;
@@ -6138,6 +6822,9 @@ export function registerSessionsRoutes(app, deps) {
         cloud: bootstrapCloudSource
           ? buildConversationCloudPayload({ cloudSourceJson: bootstrapCloudSource })
           : null,
+        // Always present (null outside a group): a caller that asked for a
+        // group tells this relay from one that predates it by the key.
+        group: conversationGroupField(conversationId),
         runtimeSessionId: runtimeSession?.id || null,
         ownerSessionId,
         worker: ownerWorker,
@@ -6156,6 +6843,10 @@ export function registerSessionsRoutes(app, deps) {
         ...workspaceRootPayload(),
       });
     } catch (error) {
+      if (error?.bootstrapGroupGone) {
+        const groups = listGroupsForAgents();
+        return res.status(400).json(bootstrapGroupRefusal({ status: 'unknown' }, requestedGroup, groups));
+      }
       console.warn(`[bootstrap] conversation bootstrap failed: ${error?.message || error}`);
       return res.status(500).json({
         ok: false,
@@ -6985,6 +7676,40 @@ export function registerSessionsRoutes(app, deps) {
     });
   });
 
+  // A rotated API key only reaches a worker's environment at spawn: live
+  // workers of the provider keep the old key and fail each turn after the
+  // rotation. Stops them; the primer or the next delivery respawns them with
+  // the fresh key from settings.
+  async function stopLiveProviderWorkersForKeyRotation(providerType) {
+    const rows = db.prepare(`
+      SELECT DISTINCT NULLIF(sdk_session_id, '') AS sdk_session_id
+      FROM runtime_sessions
+      WHERE LOWER(COALESCE(provider_type, '')) = ?
+        AND NULLIF(sdk_session_id, '') IS NOT NULL
+    `).all(providerType);
+    for (const row of rows) {
+      const sid = String(row.sdk_session_id || '').trim();
+      if (!sid) continue;
+      const workerState = sessionWorkerSupervisor?.getWorkerState?.(sid) || null;
+      if (!workerState) continue;
+      try {
+        const stopped = await stopIdleWorkspaceRootSession({
+          sdkSessionId: sid,
+          worker: sessionWorkerRegistry?.getWorker?.(sid) || null,
+          sessionWorkerSupervisor,
+          sessionWorkerRegistry,
+          sessionWorkerProcessInspector,
+        });
+        if (stopped.ok) {
+          sessionWorkerSupervisor?.clearRestartSchedule?.(sid, { resetKilledMarker: true });
+          console.log(`[sessions] ${providerType} worker ${sid.slice(0, 8)} stopped for API key rotation`);
+        }
+      } catch (error) {
+        console.warn(`[sessions] ${providerType} worker ${sid.slice(0, 8)} stop failed on key rotation: ${error?.message || error}`);
+      }
+    }
+  }
+
   app.get('/api/settings/cursor', auth, (_req, res) => {
     const settings = getCursorProviderSettings();
     return res.json({
@@ -7016,33 +7741,7 @@ export function registerSessionsRoutes(app, deps) {
     // fail each turn after the rotation. Stop them now; the primer or the
     // next delivery respawns them with the fresh key from settings.
     if (parsed.apiKey && previous?.configured === true) {
-      const cursorSessionRows = db.prepare(`
-        SELECT DISTINCT NULLIF(sdk_session_id, '') AS sdk_session_id
-        FROM runtime_sessions
-        WHERE LOWER(COALESCE(provider_type, '')) = 'cursor'
-          AND NULLIF(sdk_session_id, '') IS NOT NULL
-      `).all();
-      for (const row of cursorSessionRows) {
-        const sid = String(row.sdk_session_id || '').trim();
-        if (!sid) continue;
-        const workerState = sessionWorkerSupervisor?.getWorkerState?.(sid) || null;
-        if (!workerState) continue;
-        try {
-          const stopped = await stopIdleWorkspaceRootSession({
-            sdkSessionId: sid,
-            worker: sessionWorkerRegistry?.getWorker?.(sid) || null,
-            sessionWorkerSupervisor,
-            sessionWorkerRegistry,
-            sessionWorkerProcessInspector,
-          });
-          if (stopped.ok) {
-            sessionWorkerSupervisor?.clearRestartSchedule?.(sid, { resetKilledMarker: true });
-            console.log(`[sessions] cursor worker ${sid.slice(0, 8)} stopped for API key rotation`);
-          }
-        } catch (error) {
-          console.warn(`[sessions] cursor worker ${sid.slice(0, 8)} stop failed on key rotation: ${error?.message || error}`);
-        }
-      }
+      await stopLiveProviderWorkersForKeyRotation('cursor');
     }
     const shouldDiscover = result.enabled === true && (
       !!parsed.apiKey
@@ -7100,6 +7799,96 @@ export function registerSessionsRoutes(app, deps) {
     });
   });
 
+  // --- DeepSeek ----------------------------------------------------------
+  // The key is written here and never read back: GET and every answer carry
+  // `configured` only. A rotated key reaches a worker only at spawn, so the
+  // live DeepSeek workers are stopped; the next message starts them again.
+  // What the tab shows: the stored settings, and whether the starting
+  // balance still applies (a top-up since it was set replaces it), judged
+  // on the currency the card's bar uses: the last balance read's main one.
+  function describeDeepSeekSettings() {
+    const described = deepseekSettingsService.describe();
+    let references = [];
+    try {
+      references = planUsageService?.readDeepSeekBalanceReferences?.() || [];
+    } catch {}
+    let balances = null;
+    try {
+      balances = deepseekBalanceService?.peekBalance?.()?.balances || null;
+    } catch {}
+    const startingBalanceNote = deepseekStartingBalanceNote(
+      described.startingBalance ? { amount: described.startingBalance, setAt: described.startingBalanceSetAt } : null,
+      references,
+      { balances },
+    );
+    return { ...described, startingBalanceNote };
+  }
+
+  app.get('/api/settings/deepseek', auth, (_req, res) => {
+    if (!deepseekSettingsService) return res.status(501).json({ error: 'DeepSeek settings are unavailable' });
+    return res.json(describeDeepSeekSettings());
+  });
+
+  app.post('/api/settings/deepseek', auth, async (req, res) => {
+    if (!deepseekSettingsService) return res.status(501).json({ error: 'DeepSeek settings are unavailable' });
+    const parsed = parseDeepSeekSettingsUpdateRequest(req.body);
+    if (!parsed.ok) return res.status(400).json({ error: parsed.error });
+    // A starting balance a top-up has replaced is set anew when it is saved
+    // again, the same amount too.
+    const before = describeDeepSeekSettings();
+    const startingBalanceReplaced = !!before.startingBalanceNote;
+    const result = deepseekSettingsService.update(parsed, { startingBalanceReplaced });
+    if (!result?.ok) {
+      return res.status(result?.code === 'deepseek-key-removal-blocked' ? 409 : 400).json({
+        error: result?.error || 'Failed to update DeepSeek settings',
+        code: result?.code || null,
+        activeConversationCount: Number(result?.activeConversationCount || 0),
+        startedConversationCount: Number(result?.startedConversationCount || 0),
+        activeQueueConversationCount: Number(result?.activeQueueConversationCount || 0),
+      });
+    }
+    if (result.keyChanged) await stopLiveProviderWorkersForKeyRotation(DEEPSEEK_PROVIDER_TYPE);
+    const discovery = result.discover
+      ? await deepseekSettingsService.refreshModels()
+      : { ok: true, models: [], error: null };
+    // A starting balance set anew: the balance is read right then and noted
+    // as the latest read, so a later top-up is a rise from a balance read
+    // after the setting, and one made before it is already in this read
+    // (deepseekStartingBalanceState). A failed read changes nothing: the
+    // setting then stays until a rise seen after a read that followed it.
+    const setAt = result.settings?.startingBalanceSetAt || null;
+    if (setAt && setAt !== before.startingBalanceSetAt) {
+      try {
+        const balance = await deepseekBalanceService?.getBalance?.({ force: true });
+        planUsageService?.recordDeepSeekBalance?.(balance);
+      } catch {}
+    }
+    // Removing the key moves unstarted DeepSeek conversations back to the
+    // default provider, as for OpenAI and Cursor.
+    const reconciliationResult = parsed.remove === true
+      ? await reconcileUnstartedConversationProviders({ enabled: false, model: DEFAULT_DEEPSEEK_MODEL, provider: DEEPSEEK_PROVIDER_TYPE })
+      : { updatedUnstartedConversations: 0, skippedStartedConversations: 0, skippedActiveQueueConversations: 0, failedConversations: [] };
+    const failedConversations = Array.isArray(reconciliationResult?.failedConversations) ? reconciliationResult.failedConversations : [];
+    const settingsPayload = {
+      ...describeDeepSeekSettings(),
+      reconciliation: {
+        updatedUnstartedConversations: Number(reconciliationResult?.updatedUnstartedConversations || 0),
+        skippedStartedConversations: Number(reconciliationResult?.skippedStartedConversations || 0),
+        skippedActiveQueueConversations: Number(reconciliationResult?.skippedActiveQueueConversations || 0),
+        failedConversations,
+      },
+    };
+    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('deepseek_settings_updated', settingsPayload);
+    return res.json({
+      ok: true,
+      ...settingsPayload,
+      warning: failedConversations.length
+        ? `${failedConversations.length} unstarted conversation(s) could not switch provider.`
+        : (discovery?.ok ? null : (discovery?.error || 'DeepSeek model discovery failed')),
+    });
+  });
+
   app.get('/api/settings/turn-ceiling', auth, (_req, res) => {
     res.json({
       ceilingMinutes: getTurnCeilingMinutes(),
@@ -7667,6 +8456,7 @@ export function registerSessionsRoutes(app, deps) {
     const claudeSettings = getClaudeProviderSettings();
     const cursorSettings = getCursorProviderSettings();
     const grokSettings = getGrokProviderSettings();
+    const deepseekSettings = getDeepSeekProviderSettings();
     return {
       ...buildModelVariantCatalogPayload({
         rows,
@@ -7696,6 +8486,13 @@ export function registerSessionsRoutes(app, deps) {
             enabledModels: Array.isArray(grokSettings.models) ? grokSettings.models : [],
           }
         : null,
+      deepseekModels: deepseekSettings?.enabled === true
+        ? {
+            defaultModel: deepseekSettings.model,
+            availableModels: Array.isArray(deepseekSettings.availableModels) ? deepseekSettings.availableModels : [],
+            enabledModels: Array.isArray(deepseekSettings.models) ? deepseekSettings.models : [],
+          }
+        : null,
     };
   }
 
@@ -7714,6 +8511,7 @@ export function registerSessionsRoutes(app, deps) {
       const claudeSettings = getClaudeProviderSettings();
       const cursorSettings = getCursorProviderSettings();
       const grokSettings = getGrokProviderSettings();
+      const deepseekSettings = getDeepSeekProviderSettings();
       const refreshTasks = [
         refreshModelVariantCatalogFromCli(),
         openAISettings?.enabled === true
@@ -7734,8 +8532,11 @@ export function registerSessionsRoutes(app, deps) {
         typeof copilotModelDiscoveryService?.refresh === 'function'
           ? copilotModelDiscoveryService.refresh('manual-refresh')
           : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
+        deepseekSettings?.enabled === true && deepseekSettingsService
+          ? deepseekSettingsService.refreshModels()
+          : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
       ];
-      const [cliRefresh, openAIRefresh, claudeRefresh, cursorRefresh, grokRefresh, copilotDiscoveryRefresh] = await Promise.allSettled(refreshTasks);
+      const [cliRefresh, openAIRefresh, claudeRefresh, cursorRefresh, grokRefresh, copilotDiscoveryRefresh, deepseekRefresh] = await Promise.allSettled(refreshTasks);
       if (cliRefresh.status === 'rejected') throw cliRefresh.reason;
       const openAIModelDiscovery = openAIRefresh.status === 'fulfilled'
         ? openAIRefresh.value
@@ -7765,6 +8566,13 @@ export function registerSessionsRoutes(app, deps) {
             models: Array.isArray(grokSettings?.models) ? grokSettings.models : [],
             error: grokRefresh.reason?.message || 'Grok model discovery failed',
           };
+      const deepseekModelDiscovery = deepseekRefresh.status === 'fulfilled'
+        ? deepseekRefresh.value
+        : {
+            ok: false,
+            models: Array.isArray(deepseekSettings?.models) ? deepseekSettings.models : [],
+            error: deepseekRefresh.reason?.message || 'DeepSeek model discovery failed',
+          };
       const copilotModelDiscovery = copilotDiscoveryRefresh.status === 'fulfilled'
         ? copilotDiscoveryRefresh.value
         : { ok: false, models: [], error: copilotDiscoveryRefresh.reason?.message || 'Copilot model discovery failed' };
@@ -7778,6 +8586,7 @@ export function registerSessionsRoutes(app, deps) {
         claudeModelDiscovery,
         cursorModelDiscovery,
         grokModelDiscovery,
+        deepseekModelDiscovery,
         copilotModelDiscovery,
       });
     } catch (error) {
@@ -7873,8 +8682,9 @@ export function registerSessionsRoutes(app, deps) {
     copilotBilling: null, // { value, at }
     grokBilling: null,
     cursorBilling: null,
+    deepseekBalance: null,
   };
-  const USAGE_PROVIDER_IDS = ['github', 'claude', 'claude-cloud', 'cursor', 'grok'];
+  const USAGE_PROVIDER_IDS = ['github', 'claude', 'claude-cloud', 'cursor', 'grok', 'deepseek'];
 
   function parseUsageProviders(raw) {
     const text = Array.isArray(raw) ? raw.join(',') : String(raw ?? '');
@@ -7929,6 +8739,16 @@ export function registerSessionsRoutes(app, deps) {
     const claudeSettings = getClaudeProviderSettings();
     const cursorSettings = getCursorProviderSettings();
     const grokSettings = getGrokProviderSettings();
+    const deepseekSettings = getDeepSeekProviderSettings();
+    const deepseekEnabled = deepseekSettings?.enabled === true;
+    // An unreadable export is no reason to lose the card: the estimate stays.
+    const readDeepSeekActuals = () => {
+      try {
+        return deepseekUsageImportService?.readActuals?.() ?? null;
+      } catch {
+        return null;
+      }
+    };
     let claudeCloudEnabled = false;
     try {
       claudeCloudEnabled = claudeCloudSettingsService?.getSettings?.()?.enabled === true;
@@ -7950,7 +8770,7 @@ export function registerSessionsRoutes(app, deps) {
       : 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([
+    const [copilot, billingEntry, grokEntry, cursorEntry, deepseekEntry, claudeAccount] = await Promise.all([
       readCopilotSummary(),
       cachedOrLive('copilotBilling', live('github'), () => (
         typeof fetchCopilotBillingUsage === 'function'
@@ -7963,6 +8783,12 @@ export function registerSessionsRoutes(app, deps) {
       cachedOrLive('cursorBilling', live('cursor'), () => (
         cursorSettings?.enabled === true && typeof fetchCursorDashboardUsage === 'function' ? fetchCursorDashboardUsage() : null
       )),
+      // The service keeps its own minute of cache and answers a failure as
+      // `{ ok: false, … }`, so a failed read replaces the earlier answer here
+      // (which it carries as `previous`).
+      cachedOrLive('deepseekBalance', live('deepseek'), () => (
+        deepseekEnabled && typeof deepseekBalanceService?.getBalance === 'function' ? deepseekBalanceService.getBalance() : null
+      )),
       claudeAccountPromise,
     ]);
 
@@ -7995,6 +8821,14 @@ export function registerSessionsRoutes(app, deps) {
       grokConfigured: grokSettings?.enabled === true,
       grokAllowances: getGrokPlanAllowanceSettings(),
       grokBilling: grokEntry.value,
+      deepseekConfigured: deepseekEnabled,
+      deepseekBalance: deepseekEnabled ? deepseekEntry.value : null,
+      deepseekMonthlyBudget: deepseekEnabled ? (deepseekSettings?.monthlyBudget ?? null) : null,
+      deepseekMonthlyBudgetCurrency: deepseekEnabled ? (deepseekSettings?.monthlyBudgetCurrency ?? null) : null,
+      deepseekStartingBalance: deepseekEnabled && deepseekSettings?.startingBalance
+        ? { amount: deepseekSettings.startingBalance, setAt: deepseekSettings.startingBalanceSetAt }
+        : null,
+      deepseekActuals: deepseekEnabled ? readDeepSeekActuals() : null,
     });
 
     // Legacy top-level fields stay alongside `providers` so an older cached
@@ -8009,6 +8843,7 @@ export function registerSessionsRoutes(app, deps) {
         'claude-cloud': claudeAccount?.fetchedAt || null,
         cursor: cursorEntry.at,
         grok: grokEntry.at,
+        deepseek: deepseekEntry.value?.fetchedAt || deepseekEntry.at,
       },
     });
   });