@oar-sh/oar 0.9.9 → 0.9.11

package/server/server-runtime.mjs

@@ -24,6 +24,7 @@ import {
   normalizeWorkspaceRootKey,
 } from './services/workspace-root-path-policy.mjs';
 import { stopSessionWorkerProcesses } from './services/session-worker-stop-service.mjs';
+import { createDetachedWorkerWatch } from './services/detached-worker-watch-service.mjs';
 import { applyCdnNoStoreHeaders } from './services/file-serving.mjs';
 import { pickLiveTurnRowId } from './services/live-turn-picker.mjs';
 import { buildSteerSettleFailure, steerAgentLabelForProvider } from '../shared/steer-settle-failure.mjs';
@@ -43,7 +44,11 @@ import { registerGitRoutes } from './routes/git-routes.mjs';
 import { registerClaudeCloudRoutes } from './routes/claude-cloud-routes.mjs';
 import { registerPreviewRoutes } from './routes/preview-routes.mjs';
 import { registerRemoteRelayRoutes } from './routes/remote-relay-routes.mjs';
+import { registerRelayEventRoutes } from './routes/relay-event-routes.mjs';
 import { createRemoteRelayRepository } from './repositories/remote-relay-repository.mjs';
+import { createConversationGroupRepository } from './repositories/conversation-group-repository.mjs';
+import { createShareRepository } from './repositories/share-repository.mjs';
+import { registerConversationGroupRoutes } from './routes/conversation-group-routes.mjs';
 import { createRemoteRelayClient } from './services/remote-relay-client.mjs';
 import { createRemoteRelayLoopbackClient } from './services/remote-relay-loopback.mjs';
 import { createRemoteRelayRegistry } from './services/remote-relay-registry-service.mjs';
@@ -68,12 +73,19 @@ import webpush from 'web-push';
 import { createPushDispatchService, ensurePushVapidKeys } from './services/push-dispatch-service.mjs';
 import { createHostSuspendService } from './services/host-suspend-service.mjs';
 import { USAGE_LIMIT_ACCOUNT_SOCKET_EVENT, createUsageLimitPauseService } from './services/usage-limit-pause-service.mjs';
+import { createSessionActivityTracker, resolveBootReportingWindowMs } from './services/session-activity-tracker.mjs';
+import { createBackgroundTaskStore } from './services/background-task-store.mjs';
+import { createBackgroundWorkView } from './services/background-work-view.mjs';
+import { createRelayEventService } from './services/relay-event-service.mjs';
+import { createRelayEventLinkService } from './services/relay-event-link-service.mjs';
 import { buildClaudeAttributionSettings, normalizeClaudeAttributionMode, resolveClaudeAttributionMode, DEFAULT_CLAUDE_ATTRIBUTION_MODE } from '../shared/claude-attribution.mjs';
 import { createWorkerLaunchNoteService } from './services/worker-launch-note-service.mjs';
 import { createGitHubCiActivityService } from './services/github-ci-activity-service.mjs';
 import { runHostSuspendToRam } from './services/host-suspend-command.mjs';
 import { createActiveDeviceTracker } from './services/push-active-device-service.mjs';
 import { registerPushRoutes } from './routes/push-routes.mjs';
+import { registerAboutRoutes } from './routes/about-routes.mjs';
+import { createAboutService, resolveBuildCommit } from './services/about-service.mjs';
 import { createImageOperationService } from './services/image-operation-service.mjs';
 import {
   normalizeDriveAbsolutePath as _normalizeDriveAbsolutePath,
@@ -115,13 +127,24 @@ import {
 } from './services/preview-registry-service.mjs';
 import { createPreviewProxyServer } from './services/preview-proxy-server.mjs';
 import { createPreviewHealthProbe } from './services/preview-health-probe.mjs';
+import { createSqlitePreviewStore, isSameHostBoot, readHostBootId } from './services/preview-store.mjs';
+import { validateStaticRootInAny } from './services/preview-static-handler.mjs';
 import { createTunnelWorkerPathGuard } from './services/tunnel-worker-path-guard.mjs';
+import {
+  createLocalRequestCheck,
+  expressRequestView,
+  isSameOriginRequest,
+  resolveTunnelMarkerHeaders,
+} from './services/request-boundary.mjs';
+import { createRelayAuth } from './services/relay-auth.mjs';
+import { guardUpgradeSocket } from './services/upgrade-socket-guard.mjs';
 import { createWindowsAutostartService } from './services/windows-autostart-service.mjs';
 import { createWindowsBootAutostartService } from './services/windows-boot-autostart-service.mjs';
 import { createSessionWorkerWebSocketService } from './services/session-worker-websocket-service.mjs';
 import { createTmuxInspectorAccessPolicy } from './services/tmux-inspector-access-policy.mjs';
 import { createTmuxInspectorStreamService } from './services/tmux-inspector-stream-service.mjs';
 import { createTmuxInspectorSocketService } from './services/tmux-inspector-socket-service.mjs';
+import { createSubagentViewerRooms } from './services/subagent-viewer-rooms.mjs';
 import {
   resolveDefaultSessionWorkspaceRootState as resolveDefaultSessionWorkspaceRootStateFromService,
   resolveLaunchWorkspaceRootPath,
@@ -142,6 +165,24 @@ import {
   readTurnCeilingSetting,
   turnCeilingMinutesToMs,
 } from '../shared/turn-ceiling.mjs';
+import {
+  SUBAGENT_RECORD_RETENTION_SETTING_KEY,
+  parseSubagentRecordRetentionUpdate,
+  readSubagentRecordRetentionSetting,
+} from '../shared/subagent-record-retention.mjs';
+import { createSubagentRecordRetention } from './services/subagent-record-retention.mjs';
+import {
+  SHARE_PATH_PRIVACY_SETTING_KEY,
+  parseSharePathPrivacyUpdate,
+  readSharePathPrivacySetting,
+} from '../shared/share-path-privacy.mjs';
+import { isRelayShutdownQueued, queuedShutdownCanProceed, relayShutdownGateReply } from './services/relay-shutdown-gate.mjs';
+import { createStaleRecoveryClockGuard } from './services/stale-recovery-clock-guard.mjs';
+import {
+  STALE_SUBAGENT_RUN_BOOT_DELAY_MS,
+  STALE_SUBAGENT_RUN_SWEEP_INTERVAL_MS,
+  createStaleSubagentRunSweep,
+} from './services/stale-subagent-run-sweep.mjs';
 import {
   normalizePwaAppName,
   readPwaAppNameSetting,
@@ -178,6 +219,8 @@ import {
 } from '../shared/model-id.mjs';
 import { createModelVariantCatalogService } from './services/model-variant-catalog-service.mjs';
 import { applyPwaManifestTheme, normalizePwaTheme } from './services/pwa-manifest-theme.mjs';
+import { mapSubagentRunHeader } from './services/subagent-timeline-service.mjs';
+import { describeExecError, describeSpawnEnvironment, windowsSystemToolPath } from '../shared/windows-system-tools.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..');
@@ -195,6 +238,10 @@ const RUNNING_VERSION = (() => {
   }
 })();
 const INSTALL_METHOD = fs.existsSync(path.join(PACKAGE_ROOT, '.git')) ? 'git-checkout' : 'npm-global';
+// When this relay process started, and the commit its code came from (read
+// once: a checkout moved on later still runs the code it started with).
+const RELAY_STARTED_AT = new Date(Date.now() - process.uptime() * 1000).toISOString();
+const BUILD_COMMIT = resolveBuildCommit(PACKAGE_ROOT);
 const PUBLIC_DIR = path.join(__dirname, 'public');
 const INDEX_HTML_PATH = path.join(PUBLIC_DIR, 'index.html');
 const PWA_MANIFEST_PATH = path.join(PUBLIC_DIR, 'manifest.webmanifest');
@@ -1792,6 +1839,8 @@ const OFFLINE_STALE_RECOVER_MS = 45_000;
 // reaches the browser.
 const SHUTDOWN_SOCKET_FLUSH_MS = 300;
 let runtimeShutdownStarted = false;
+// Set once the database is open (see the retention sweep near the other sweeps).
+let subagentRecordRetention = null;
 const runtimeTimers = {
   cliStatus: null,
   ownerWatchdog: null,
@@ -2000,6 +2049,51 @@ function setTurnCeilingMinutes(value) {
   return { ok: true, ceilingMinutes: parsed.minutes };
 }
 
+function getSubagentRecordRetentionDays() {
+  return readSubagentRecordRetentionSetting(readAppSettingValue(SUBAGENT_RECORD_RETENTION_SETTING_KEY));
+}
+
+function setSubagentRecordRetentionDays(value) {
+  if (typeof stmts?.upsertAppSetting?.run !== 'function') {
+    return { ok: false, error: 'Sub-agent record settings are unavailable' };
+  }
+  const parsed = parseSubagentRecordRetentionUpdate(value);
+  if (!parsed.ok) return parsed;
+  stmts.upsertAppSetting.run(SUBAGENT_RECORD_RETENTION_SETTING_KEY, String(parsed.days), new Date().toISOString());
+  // A shorter period takes effect now, not at the next daily sweep.
+  subagentRecordRetention?.scheduleSweep(5_000);
+  return { ok: true, retentionDays: parsed.days };
+}
+
+function getSharePathPrivacyMode() {
+  return readSharePathPrivacySetting(readAppSettingValue(SHARE_PATH_PRIVACY_SETTING_KEY));
+}
+
+function setSharePathPrivacyMode(value) {
+  if (typeof stmts?.upsertAppSetting?.run !== 'function') {
+    return { ok: false, error: 'Path privacy settings are unavailable' };
+  }
+  const parsed = parseSharePathPrivacyUpdate(value);
+  if (!parsed.ok) return parsed;
+  stmts.upsertAppSetting.run(SHARE_PATH_PRIVACY_SETTING_KEY, parsed.mode, new Date().toISOString());
+  return { ok: true, mode: parsed.mode };
+}
+
+// The relay host's own roots a shared view must not show: home, the relay's
+// checkout, data and upload dirs, the workspace roots it knows, and the OS
+// user name. The share routes add the conversation's own roots.
+function sharePathKnownRoots() {
+  const roots = [REPO_ROOT, DATA_DIR, UPLOAD_DIR, currentWorkspaceRootPath(), INITIAL_WORKSPACE_ROOT];
+  const userNames = [];
+  try { roots.push(os.homedir()); } catch {}
+  try { userNames.push(os.userInfo().username); } catch {}
+  try { roots.push(resolveDefaultSessionWorkspaceRootState()?.path || ''); } catch {}
+  try { roots.push(...listRecentWorkspaceRoots()); } catch {}
+  try { roots.push(resolveSessionStateRoot?.() || ''); } catch {}
+  roots.push(...workspaceRootAllowList);
+  return { roots: roots.filter(Boolean), userNames: userNames.filter(Boolean) };
+}
+
 const PWA_APP_NAME_SETTING_KEY = 'pwa_app_name';
 
 /** '' means "no custom name": the manifest falls back to the template default. */
@@ -2470,7 +2564,7 @@ function runCopilotCliCommand(args = [], timeoutMs = 30_000) {
     if (process.platform === 'win32') {
       const escapedArgs = commandArgs.map((part) => `'${String(part).replace(/'/g, "''")}'`).join(' ');
       const script = escapedArgs ? `& 'copilot' ${escapedArgs}` : "& 'copilot'";
-      execFile('powershell.exe', ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script], { windowsHide: true, timeout }, (error, stdout, stderr) => {
+      execFile(windowsSystemToolPath('powershell.exe'), ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script], { windowsHide: true, timeout }, (error, stdout, stderr) => {
         if (error) {
           const detail = String(stderr || stdout || error.message || '').trim();
           reject(new Error(detail || error.message || 'copilot command failed'));
@@ -2541,6 +2635,29 @@ const stmts = {
   ...createImageConversationRepository(db),
 };
 const statusEventService = createStatusEventService(db);
+// Public shares and their access log (migration 0016).
+const shareRepository = createShareRepository(db);
+// Session groups in the sidebar (migration 0014). Without the migration it
+// sees no groups and writes nothing. What a delete that did not know groups
+// left behind (a head whose row is gone, a group without a member) is
+// repaired once at boot.
+const conversationGroups = createConversationGroupRepository(db);
+try {
+  const repaired = conversationGroups.repair();
+  if (repaired.headsDetached > 0 || repaired.groupsRemoved > 0) {
+    console.log(`[session-groups] repaired: ${repaired.headsDetached} headless group(s), ${repaired.groupsRemoved} empty group(s) removed`);
+  }
+} catch (error) {
+  console.warn(`[session-groups] repair failed: ${error?.message || error}`);
+}
+// Relay events (built further down, next to the usage-limit pause): declared
+// here so recovery code that runs before then finds null, not a TDZ error.
+let sessionActivityTracker = null;
+let relayEventService = null;
+// Fetches the events of subscriptions on paired relays (built with the
+// remote relays below; the event service asks it to fetch at once when an
+// end or a new watcher must reach one).
+let relayEventLinkService = null;
 // Owns the `claude auth …` child processes, so the runtime (not the route
 // module) constructs it: shutdownRuntime() has to be able to dispose a login
 // PTY that is still holding a process group.
@@ -2681,7 +2798,7 @@ const imageOperationService = createImageOperationService({
 
 modelVariantCatalog.bindDatabase(db);
 
-const deleteArchiveService = createDeleteArchiveService(db, null, { resolveSessionStateRoot });
+const deleteArchiveService = createDeleteArchiveService(db, null, { resolveSessionStateRoot, conversationGroups });
 void deleteArchiveService.retryPendingDeletesOnStartup()
   .then((result) => {
     if (result?.pendingCount > 0) {
@@ -2909,8 +3026,13 @@ async function spawnSessionWorkerCli(targetSessionId, { allowProcessReuse = true
   }
   // An unreadable process list must not stop every launch on the relay
   // (2026-10-01: a control byte in one command line did, for an hour).
+  // The environment goes with the first report of a launch only; the pid poll
+  // reads the list up to ten more times.
+  let processListEnvironmentLogged = false;
   const warnProcessListUnreadable = (error) => {
-    console.warn(`${runtimeLogPrefix()}worker launcher: process list unreadable, launching session=${normalizedTargetSessionId.slice(0, 8)} without the reuse check: ${error?.message || error}`);
+    const environment = processListEnvironmentLogged ? '' : `; ${describeSpawnEnvironment(process.env)}`;
+    processListEnvironmentLogged = true;
+    console.warn(`${runtimeLogPrefix()}worker launcher: process list unreadable, launching session=${normalizedTargetSessionId.slice(0, 8)} without the reuse check: ${describeExecError(error)}${environment}`);
   };
   if (allowProcessReuse) {
     let liveWorker = null;
@@ -2937,6 +3059,7 @@ async function spawnSessionWorkerCli(targetSessionId, { allowProcessReuse = true
     processInspector: sessionWorkerProcessInspector,
     allowProcessReuse,
     onProcessListError: warnProcessListUnreadable,
+    log: (message) => console.warn(`${runtimeLogPrefix()}${message}`),
   });
   const workerPid = Number.isInteger(Number(launched?.pid)) ? Number(launched.pid) : null;
   const workerId = `worker-${normalizedTargetSessionId.slice(0, 8)}`;
@@ -3344,26 +3467,6 @@ function cancelRelayShutdown({ requestedBy = 'localhost-api' } = {}) {
   return { cancelled: true, dropped, ...relayShutdownStatePayload() };
 }
 
-const countPendingRowsByOwnerSession = db.prepare(`
-  SELECT owner_sdk_session_id AS sdk_session_id, COUNT(*) AS n
-  FROM queue
-  WHERE status = 'pending' AND owner_sdk_session_id IS NOT NULL AND owner_sdk_session_id != ''
-  GROUP BY owner_sdk_session_id
-`);
-
-function countPendingRowsOfStoppedSessions() {
-  try {
-    let stalled = 0;
-    for (const row of countPendingRowsByOwnerSession.all()) {
-      const lifecycle = sessionWorkerSupervisor?.getLifecycleState?.(String(row.sdk_session_id || '').trim());
-      if (lifecycle?.retriesStopped === true) stalled += Number(row.n || 0);
-    }
-    return stalled;
-  } catch {
-    return 0;
-  }
-}
-
 function requestRelayShutdown({ reason = 'manual-request', requestedBy = 'localhost-api', restart = false } = {}) {
   const safeReason = String(reason || 'manual-request').trim().slice(0, 140) || 'manual-request';
   const safeRequestedBy = String(requestedBy || 'localhost-api').trim().slice(0, 80) || 'localhost-api';
@@ -3379,7 +3482,11 @@ function requestRelayShutdown({ reason = 'manual-request', requestedBy = 'localh
     };
   }
 
-  // Shutdown is intentionally deferred until the queue is idle; it will not interrupt an active turn.
+  // Shutdown is deferred until no turn is processing; it never interrupts an
+  // active turn. From here on no pending row is handed out (the dequeue paths
+  // read relayShutdownQueued): a turn started meanwhile would postpone the
+  // restart again. Pending and parked rows wait in the database and run
+  // after the restart.
   if (!pendingRelayShutdownRequest) {
     pendingRelayShutdownRequest = {
       action: requestedAction,
@@ -3400,12 +3507,7 @@ function requestRelayShutdown({ reason = 'manual-request', requestedBy = 'localh
   const tryShutdownWhenIdle = () => {
     if (runtimeShutdownStarted) return;
     const counts = queueCounts();
-    // A row queued for a session whose launches the relay has stopped
-    // retrying makes no progress until somebody presses Retry; it must not
-    // hold the restart (which, fresh, is itself the next launch attempt).
-    const stalledPending = countPendingRowsOfStoppedSessions();
-    const queueFree = (counts.pendingCount - stalledPending + counts.processingCount + counts.parkedCount) <= 0;
-    if (!queueFree) return;
+    if (!queuedShutdownCanProceed(counts)) return;
     const requestInfo = pendingRelayShutdownRequest;
     pendingRelayShutdownRequest = null;
     if (runtimeTimers.shutdownDrain) {
@@ -3416,7 +3518,7 @@ function requestRelayShutdown({ reason = 'manual-request', requestedBy = 'localh
     const exitCode = action === 'restart' ? RELAY_RESTART_EXIT_CODE : 0;
     console.log(
       `${runtimeLogPrefix()}Relay ${action} request accepted by ${requestInfo?.requestedBy || 'unknown'}`
-      + `; queue is idle, exiting now (reason=${requestInfo?.reason || 'manual-request'})`,
+      + `; no turn is processing (${counts.pendingCount} pending, ${counts.parkedCount} parked wait), exiting now (reason=${requestInfo?.reason || 'manual-request'})`,
     );
     sessionWorkerWebSocketService.emitDraining(`api-${action}:${requestInfo?.reason || 'manual-request'}`);
     void shutdownRuntime(`api-${action}:${requestInfo?.reason || 'manual-request'}`, { exitCode });
@@ -4347,7 +4449,7 @@ function fetchDriveDirectoryEntries(absoluteDirPath, { includeHidden = false } =
     '$rows | ConvertTo-Json -Depth 4 -Compress',
   ].join(' ');
 
-  execFile('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', psScript], { windowsHide: true }, (err, stdout, stderr) => {
+  execFile(windowsSystemToolPath('powershell.exe'), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', psScript], { windowsHide: true }, (err, stdout, stderr) => {
     if (err) return cb(new Error(`drive list failed: ${stderr || err.message}`));
     const text = String(stdout || '').trim();
     if (!text) return cb(null, []);
@@ -4940,6 +5042,9 @@ function createCompactedConversation(sourceConversationId) {
     stmts.insertConv.run(targetConversationId, nextTitle, now, now);
     stmts.updateConvSeed.run(summarySeed, 1, sourceConversationId, now, targetConversationId);
     stmts.markConvCompacted.run(targetConversationId, now, sourceConversationId);
+    // The new conversation stays in the old one's session group, and heads
+    // it if the old one did; the archived source stays a member.
+    conversationGroups.carryToCompacted(sourceConversationId, targetConversationId, now);
     targetRuntimeSession = ensureRuntimeSessionBinding(targetConversationId, null, now);
   });
   tx();
@@ -5049,19 +5154,18 @@ function subagentRunsForResponse(responseMessageId) {
   return rows.map(mapSubagentRunRow).filter(Boolean).slice(0, 96);
 }
 
+// The run as a row of the panel, the reply bubble and the viewer header. Stop
+// is offered while it runs: a background run through its live task, a
+// foreground run through the sub-agent cancel route.
 function mapSubagentRunRow(row) {
-  const subagentRunId = String(row?.id || '').trim();
-  if (!subagentRunId) return null;
-  return {
-    subagentRunId,
-    messageId: String(row?.queue_message_id || '').trim() || null,
-    conversationId: String(row?.conversation_id || '').trim() || null,
-    parentSubagentId: row?.parent_subagent_id ? String(row.parent_subagent_id).trim() : null,
-    displayName: row?.display_name ? String(row.display_name).trim() : null,
-    status: String(row?.status || 'running').trim().toLowerCase() || 'running',
-    startedAt: row?.started_at || null,
-    updatedAt: row?.updated_at || null,
-  };
+  const status = String(row?.status || 'running').trim().toLowerCase();
+  let stoppable = false;
+  if (status === 'running') {
+    const tasks = backgroundTaskStore.get(row?.conversation_id);
+    const task = tasks.find((entry) => entry?.toolUseId && entry.toolUseId === String(row?.id || ''));
+    stoppable = task ? task.stoppable !== false : Number(row?.background || 0) !== 1;
+  }
+  return mapSubagentRunHeader(row, { stoppable });
 }
 
 // Final workflow digests persisted with an assistant message (the "Finished
@@ -5100,25 +5204,10 @@ function previewCardsForResponse(responseMessageId) {
     .slice(0, 5);
 }
 
-// Live background-task sets per conversation, published by Claude session
-// workers (REPLACE semantics, mirroring the SDK's background_tasks_changed
-// signal). In-memory only: the worker republishes on every change and clears
-// on teardown, so a relay restart simply starts empty until the next update.
-const backgroundTaskStore = {
-  sets: new Map(),
-  replace(conversationId, tasks) {
-    const id = String(conversationId || '').trim();
-    if (!id) return;
-    if (!Array.isArray(tasks) || tasks.length === 0) {
-      this.sets.delete(id);
-      return;
-    }
-    this.sets.set(id, { tasks, updatedAt: Date.now() });
-  },
-  get(conversationId) {
-    return this.sets.get(String(conversationId || '').trim())?.tasks || [];
-  },
-};
+// Live background-task sets, as the session workers publish them. Memory
+// only: after a runtime start the heartbeat's digest brings each set back
+// (services/background-task-store.mjs).
+const backgroundTaskStore = createBackgroundTaskStore();
 
 // ─── Deferred host suspend ───────────────────────────────────────────────────
 // "💤 Suspend host" waits until nothing runs any more: no queued/processing
@@ -5151,6 +5240,17 @@ function hostActivityTitle(conversationId, fallbackTitle = null) {
   const title = String(fallbackTitle || stmts.getConv?.get?.(conversationId)?.title || '').trim();
   return title || String(conversationId || '').slice(0, 8);
 }
+const backgroundWorkView = createBackgroundWorkView({
+  store: backgroundTaskStore,
+  db,
+  getRegistry: () => sessionWorkerRegistry,
+  getTracker: () => sessionActivityTracker,
+  isWorkerAlive: hostActivityWorkerAlive,
+  sessionIdOf: (conversationId) => stmts.getRuntimeSessionByConversation?.get?.(conversationId)?.sdk_session_id,
+  conversationIdOf: (sessionId) => resolveConversationRecord({ conversationId: sessionId, sdkSessionId: sessionId })?.id,
+  providerOf: (conversationId) => stmts.getRuntimeSessionByConversation?.get?.(conversationId)?.provider_type,
+  titleOf: (conversationId) => hostActivityTitle(conversationId),
+});
 function collectHostActivity({ request = null } = {}) {
   const blockers = [];
   const turnsByConversation = stmts.listActiveQueueCountsByConversation?.all?.() || [];
@@ -5174,20 +5274,11 @@ function collectHostActivity({ request = null } = {}) {
         : (count > 1 ? `${count} turns running` : 'turn running'),
     });
   }
-  for (const [key, entry] of backgroundTaskStore.sets) {
-    const tasks = Array.isArray(entry?.tasks) ? entry.tasks : [];
-    if (!tasks.length || !hostActivityWorkerAlive(key)) continue;
-    const worker = sessionWorkerRegistry?.getWorker?.(key) || sessionWorkerRegistry?.getWorkerByConversationId?.(key) || null;
-    const conversationId = String(worker?.conversationId || key);
-    hostSuspendWatchedConversationIds.add(conversationId);
-    const what = tasks.slice(0, 3).map((task) => String(task?.description || task?.taskType || 'task').slice(0, 80)).join('; ');
-    blockers.push({
-      kind: 'background',
-      conversationId,
-      title: hostActivityTitle(conversationId),
-      count: tasks.length,
-      detail: `${tasks.length} background agent${tasks.length === 1 ? '' : 's'}: ${what}`,
-    });
+  // Background work of live workers, and a runtime too young to know of it
+  // (services/background-work-view.mjs).
+  for (const blocker of backgroundWorkView.blockers()) {
+    if (blocker.conversationId) hostSuspendWatchedConversationIds.add(blocker.conversationId);
+    blockers.push(blocker);
   }
   const runningSubagents = Number(stmts.countRunningSubagentRuns?.get?.()?.cnt || 0);
   // CI is only worth a network round-trip for workspaces that were busy since
@@ -5228,6 +5319,50 @@ const usageLimitPauseService = createUsageLimitPauseService({
   logger: console,
 });
 
+// ─── Relay events ─────────────────────────────────────────────────────────────
+// What each session is doing (state, tasks, quiet time) and the subscriptions
+// through which a watching session is woken with the events of the sessions
+// it watches (docs: server/README.md "Relay event subscriptions").
+sessionActivityTracker = createSessionActivityTracker({
+  db,
+  onEdge: (edge) => relayEventService?.noteTaskEdge(edge),
+  hasUnreportedBackgroundWork: (conversationId) => backgroundWorkView.hasUnreportedWork(conversationId),
+  listUnreportedBackgroundWork: () => backgroundWorkView.listUnreportedConversationIds(),
+  runListedByWorker: (conversationId, row) => backgroundWorkView.runListed(conversationId, row),
+  bootReportingWindowMs: resolveBootReportingWindowMs(process.env, (line) => console.log(`[activity] ${line}`)),
+  logger: console,
+});
+relayEventService = createRelayEventService({
+  db,
+  stmts,
+  tracker: sessionActivityTracker,
+  emit: (event, payload) => io.emit(event, payload),
+  // The event row is an ordinary pending message: the primer starts a
+  // stopped worker, the socket service hands it to a running one.
+  wakeWatcher: () => {
+    void primePendingSessionWorkers('relay-event');
+    sessionWorkerWebSocketService?.emitQueueChanged?.('relay-event');
+  },
+  relayName: () => remoteRelayRegistry?.selfName?.() || getPwaAppName?.() || '',
+  onRemoteChange: (relayId) => { void relayEventLinkService?.fetchNow(relayId); },
+  logger: console,
+});
+
+/** A worker died: its tasks are gone, and whoever watches its sessions hears of it. */
+function noteWorkerDeathForEvents(sessionId, conversationIds, reason) {
+  const ids = new Set((conversationIds || []).map((id) => String(id || '').trim()).filter(Boolean));
+  if (!ids.size) {
+    const conversation = resolveConversationRecord({ conversationId: sessionId, sdkSessionId: sessionId });
+    if (conversation?.id) ids.add(String(conversation.id));
+  }
+  for (const conversationId of ids) {
+    try {
+      sessionActivityTracker?.noteWorkerDied(conversationId);
+      relayEventService?.noteError({ conversationId, kind: 'worker_died', message: `the session's worker process ended (${reason})` });
+    } catch {}
+  }
+}
+
 // The live turn among a conversation's processing rows. Mid-turn steering can
 // leave several processing at once — the running turn, steered messages the
 // CLI folded into it (no output of their own), a handed-off row still settling
@@ -5330,6 +5465,9 @@ function failRecoveredRowTerminally(row, reason, { failureRecord = null, failure
     message: { role: 'assistant', text: failureText, model: requestedModel || 'unknown', mode: String(row?.relay_mode || '').trim() || null, timestamp: now },
   });
   io.emit('message_status', { messageId: row.id, conversationId: row.conversation_id, status: 'failed' });
+  try {
+    relayEventService?.noteError({ conversationId: row.conversation_id, kind: 'turn_failed', message: failureText, queueMessageId: row.id });
+  } catch {}
   console.warn(`${runtimeLogPrefix()}${failureRecord ? 'CONSUMED FAILED' : 'RECOVERY LIMIT'} ${String(row.id).slice(0, 8)} conv=${String(row.conversation_id).slice(0, 8)} retries=${retryCount} reason=${reason}`);
 }
 
@@ -5354,6 +5492,12 @@ function recoverProcessingOlderThan(cutoffIso, requeueAtIso, { ceilingBeforeIso
   for (const row of staleContinuations) {
     stmts.dropStaleContinuation?.run?.(row.id);
     io.emit('message_status', { messageId: row.id, conversationId: row.conversation_id, status: 'failed' });
+    // A teardown is a turn ending with no reply; it must be visible in the
+    // console log (the only trace of a silent one was `ignored=already_failed`
+    // hours later, when the worker's reply arrived for the dead row).
+    const lastSeen = row.owner_last_claimed_at || row.processing_at || row.timestamp || null;
+    const reason = lastSeen && lastSeen < cutoffIso ? `inactive since ${lastSeen}` : `ceiling (started ${row.processing_at || row.timestamp})`;
+    console.warn(`${runtimeLogPrefix()}STALE CONTINUATION ${String(row.id).slice(0, 8)} conv=${String(row.conversation_id).slice(0, 8)} dropped: ${reason}`);
   }
   const listedRows = stmts.listRecoverableProcessing.all(params);
   for (const row of listedRows.filter((entry) => entry?.consumed_at)) failConsumedRowTerminally(row, 'stale-recovery');
@@ -5731,9 +5875,11 @@ const app        = express();
 // Trust boundary for X-Forwarded-* headers. Default 'loopback' matches the
 // localhost-first deployment (a cloudflared/caddy tunnel runs on the same host
 // and connects over 127.0.0.1), so req.protocol/req.secure/req.ip reflect the
-// real edge only when the immediate peer is trusted — a direct client can no
-// longer forge those headers. Operators behind a remote proxy can widen this
-// via config.trustProxy (e.g. a hop count or subnet).
+// real edge only when the immediate peer is trusted — a direct client cannot
+// forge those headers. Code that needs the client's address, host or scheme
+// reads req.ip / req.protocol / requestHostOf (services/request-boundary.mjs),
+// never the raw X-Forwarded-* headers. Operators behind a remote proxy can
+// widen this via config.trustProxy (e.g. a hop count or subnet).
 app.set('trust proxy', config.trustProxy ?? 'loopback');
 const httpServer = http.createServer(app);
 // Node closes an idle keep-alive connection after 5 s. A client that pools
@@ -5749,15 +5895,27 @@ httpServer.prependListener('request', (req, _res) => {
 httpServer.prependListener('upgrade', (req, _socket, _head) => {
   rewriteSocketIoRequestPath(req, remotePath);
 });
+// A client reset during an upgrade must not end the relay; see the guard.
+httpServer.prependListener('upgrade', (_req, socket, _head) => {
+  guardUpgradeSocket(socket);
+});
+// "Truly local": a loopback peer with no tunnel marker and no forwarding
+// header (services/request-boundary.mjs). The marker headers are `cf-ray`
+// plus config.tunnelMarkerHeaders plus COPILOT_TUNNEL_MARKER_HEADERS, merged:
+// neither source switches the other off.
+const localRequestCheck = createLocalRequestCheck({
+  markerHeaders: resolveTunnelMarkerHeaders(
+    config.tunnelMarkerHeaders,
+    process.env.COPILOT_TUNNEL_MARKER_HEADERS,
+  ),
+});
 // Public tunnels (Cloudflare, or a VPS/Caddy front) forward every path on the
 // bound hostname to this port, including the session-worker WebSocket plumbing.
-// Reject those before auth; local workers connect over 127.0.0.1 with no edge
-// marker header and are unaffected.
+// Reject every worker-path request that is not truly local before auth; local
+// workers connect over 127.0.0.1 without proxy traces and are unaffected.
 const tunnelWorkerPathGuard = createTunnelWorkerPathGuard({
   pathPrefix: remotePath,
-  extraMarkerHeaders: config.tunnelMarkerHeaders
-    || process.env.COPILOT_TUNNEL_MARKER_HEADERS
-    || [],
+  localRequestCheck,
   logger: console,
 });
 httpServer.prependListener('upgrade', (req, socket, _head) => {
@@ -5769,8 +5927,27 @@ httpServer.prependListener('upgrade', (req, socket, _head) => {
 // High-volume stream chunks are emitted volatile and deliberately excluded from
 // the replay buffer; see the io.volatile.emit('relay_stream') call site.
 const SOCKET_RECOVERY_WINDOW_MS = 10 * 60 * 1000;
+// The browser app opens its socket on the page's own origin (same host, the
+// `remotePath` socket.io path), so a handshake from another origin is refused:
+// a page elsewhere must not ride the relay cookie into a live socket. The
+// host compared is the one the client addressed (X-Forwarded-Host only from a
+// trusted proxy); config.allowedOrigins lists extra origins for a proxy that
+// rewrites the Host header. Clients that send no Origin (Node) pass.
+const socketAllowedOrigins = Array.isArray(config.allowedOrigins) ? config.allowedOrigins : [];
+const refusedSocketOrigins = new Set();
 const io         = new Server(httpServer, {
-  cors: { origin: '*' },
+  allowRequest: (req, callback) => {
+    if (isSameOriginRequest(expressRequestView(app, req), { allowedOrigins: socketAllowedOrigins })) {
+      callback(null, true);
+      return;
+    }
+    const origin = String(req.headers?.origin || '').slice(0, 200);
+    if (refusedSocketOrigins.size < 32 && !refusedSocketOrigins.has(origin)) {
+      refusedSocketOrigins.add(origin);
+      console.warn(`[socket] Refused a handshake from origin ${origin} (host ${String(req.headers?.host || '').slice(0, 200)}); list it in allowedOrigins if a proxy rewrites the Host header`);
+    }
+    callback('Origin not allowed', false);
+  },
   path: socketIoPath(),
   connectionStateRecovery: {
     maxDisconnectionDuration: SOCKET_RECOVERY_WINDOW_MS,
@@ -5958,6 +6135,9 @@ async function requestSessionWorkerSocketDelivery({ sessionId, pid, reason = 'wo
   if (runtimeState.relayPaused) {
     return { message: null, paused: true, reason: 'relay_paused' };
   }
+  if (isRelayShutdownQueued(runtimeState)) {
+    return relayShutdownGateReply(runtimeState);
+  }
   if (runtimeState.tunnelState?.blocking) {
     return {
       message: null,
@@ -6172,11 +6352,36 @@ async function isWorkerSessionProcessAlive(sessionId, hintPid = null) {
   return false;
 }
 
+// Runs a dead worker can no longer end: marked failed, each with the full
+// header and its own turn's messageId, so an open page settles the row
+// without a reload (the browser drops a status event it cannot place).
+function closeStrandedSubagentRuns(runs, queueMessageId = null) {
+  if (!runs.length) return;
+  const nowIso = new Date().toISOString();
+  for (const run of runs) {
+    stmts.updateSubagentRunStatus?.run?.('failed', nowIso, nowIso, run.id);
+    const closed = stmts.getSubagentRun?.get?.(run.id) || { ...run, status: 'failed', completed_at: nowIso };
+    const header = mapSubagentRunHeader(closed, { stoppable: false });
+    if (header) {
+      io.emit('subagent_status', {
+        ...header,
+        timestamp: nowIso,
+        queueMessageId: queueMessageId || header.messageId,
+        reconciled: true,
+      });
+    }
+  }
+}
+
 function recoverDeadWorkerProcessingRows(sessionId, reason) {
   const sid = String(sessionId || '').trim();
   if (!sid) return 0;
+  // A background agent outlives its turn, so its run is closed with the
+  // worker rather than with a processing row (its turn is usually done).
+  closeStrandedSubagentRuns(stmts.listRunningBackgroundSubagentRunsForSession?.all?.(sid, sid) || []);
   const rows = stmts.listProcessingRowsForOwner?.all?.(sid) || [];
   if (!rows.length) return 0;
+  noteWorkerDeathForEvents(sid, rows.map((row) => row.conversation_id), reason);
   let recovered = 0;
   const requeueAt = addMsIso(2_000);
   for (const row of rows) {
@@ -6196,22 +6401,7 @@ function recoverDeadWorkerProcessingRows(sessionId, reason) {
     }
     // The dead worker's subagent runs can never be terminated by the replay
     // (fresh worker, fresh call ids) — close them out now.
-    const strandedRuns = stmts.listRunningSubagentRunsByQueueMessage?.all?.(row.id) || [];
-    if (strandedRuns.length) {
-      const nowIso = new Date().toISOString();
-      stmts.closeRunningSubagentRunsByQueueMessage?.run?.('failed', nowIso, nowIso, row.id);
-      for (const run of strandedRuns) {
-        io.emit('subagent_status', {
-          conversationId: run.conversation_id,
-          subagentRunId: run.id,
-          parentSubagentId: run.parent_subagent_id || null,
-          displayName: run.display_name || null,
-          status: 'failed',
-          queueMessageId: row.id,
-          reconciled: true,
-        });
-      }
-    }
+    closeStrandedSubagentRuns(stmts.listRunningSubagentRunsByQueueMessage?.all?.(row.id) || [], row.id);
     stmts.recoverProcessingRowKeepOwner?.run?.(requeueAt, row.id);
     io.emit('message_status', { messageId: row.id, conversationId: row.conversation_id, status: 'pending' });
     recovered += 1;
@@ -6231,18 +6421,27 @@ function handleWorkerSocketClosed({ sessionId, pid = null } = {}) {
   if (runtimeShutdownStarted) return;
   const sid = String(sessionId || '').trim();
   if (!sid) return;
+  detachedWorkerWatch.noteSocketEnded(sid);
   const owned = stmts.listProcessingRowsForOwner?.all?.(sid) || [];
   // A dead worker's steering snapshot must not keep holding the composer even
   // when it owned no rows (the hold can outlive them, e.g. a continuation's).
   const heldSteering = Boolean(sessionWorkerRegistry?.getWorker?.(sid)?.steering);
-  if (!owned.length && !heldSteering) return;
+  // Background agents run between turns too: a worker that dies then owns no
+  // row, but its agents' runs still read "running".
+  const backgroundRuns = () => stmts.listRunningBackgroundSubagentRunsForSession?.all?.(sid, sid) || [];
+  if (!owned.length && !heldSteering && !backgroundRuns().length) return;
   const timer = setTimeout(async () => {
     try {
       if (runtimeShutdownStarted) return;
       if (await isWorkerSessionProcessAlive(sid, pid)) return; // reconnect or socket flap
       sessionWorkerRegistry?.clearSteering?.(sid);
       const stillOwned = stmts.listProcessingRowsForOwner?.all?.(sid) || [];
-      if (!stillOwned.length) return;
+      if (!stillOwned.length) {
+        const stranded = backgroundRuns();
+        closeStrandedSubagentRuns(stranded);
+        if (stranded.length) noteWorkerDeathForEvents(sid, stranded.map((run) => run.conversation_id), 'socket-close');
+        return;
+      }
       console.warn(`${runtimeLogPrefix()}WORKER DIED session=${sid.slice(0, 8)} rows=${stillOwned.length} trigger=socket-close — recovering owned turns`);
       recoverDeadWorkerProcessingRows(sid, 'socket-close');
     } catch (error) {
@@ -6280,6 +6479,64 @@ async function sweepDeadWorkerProcessingRowsOnce() {
   return recovered;
 }
 
+// A worker alive without its socket while a message waits: replaced after a
+// grace time (see the service). Stops the way the kill route does, but only
+// names the registry's pid when the process list confirms it is the
+// session's worker, then spawns the replacement.
+async function replaceDetachedSessionWorker(sid) {
+  const worker = sessionWorkerRegistry?.getWorker?.(sid) || null;
+  const found = process.platform === 'win32'
+    ? await sessionWorkerProcessInspector.findWindowsProcessTreeForSessionAsync(sid, { fresh: true })
+    : await sessionWorkerProcessInspector.findProcessesForSessionAsync(sid, { fresh: true });
+  const foundPids = new Set((found || []).map((entry) => Number(entry?.processId)));
+  const stopped = await stopSessionWorkerProcesses({
+    sdkSessionId: sid,
+    worker: worker && foundPids.has(Number(worker.pid)) ? worker : null,
+    processInspector: sessionWorkerProcessInspector,
+    isPidAliveImpl: isProcessAlive,
+    killTmuxSessionImpl: killTmuxSession,
+  });
+  if (!stopped.ok) return { ok: false, error: stopped.error || 'worker-survived-stop' };
+  sessionWorkerRegistry?.removeWorker?.(sid);
+  sessionWorkerSupervisor?.clearRestartSchedule?.(sid);
+  sessionWorkerSupervisor?.resetHealth?.(sid, { clearFailureCount: false });
+  const launched = await sessionWorkerSupervisor?.ensureWorker?.(sid);
+  return { ok: launched?.ok === true, error: launched?.error || null };
+}
+
+function sessionHasBackgroundWork(sid) {
+  if ((stmts.listRunningBackgroundSubagentRunsForSession?.all?.(sid, sid) || []).length) return true;
+  if (backgroundWorkView.hasUnreportedWork(sid)) return true;
+  const conversationId = resolveConversationRecord({ conversationId: sid, sdkSessionId: sid })?.id || '';
+  if (backgroundTaskStore.get(sid).length || (conversationId && backgroundTaskStore.get(conversationId).length)) return true;
+  return backgroundWorkView.backgroundBlockers()
+    .some((blocker) => blocker.conversationId === sid || (conversationId && blocker.conversationId === conversationId));
+}
+
+const detachedWorkerWatch = createDetachedWorkerWatch({
+  isEnabled: () => featureFlags?.SESSION_WORKER_ROUTING_ENABLED === true
+    && !runtimeShutdownStarted
+    && !pendingRelayShutdownRequest,
+  listWaitingSessionIds: () => (stmts.listPendingWorkerOwnerSessionIds?.all?.(25) || [])
+    .map((row) => row?.sdk_session_id),
+  hasWorkerSocket: (sid) => sessionWorkerWebSocketService.hasWorkerSocket(sid) === true,
+  hasRunningTurn: (sid) => (stmts.listProcessingRowsForOwner?.all?.(sid) || []).length > 0,
+  hasBackgroundWork: sessionHasBackgroundWork,
+  isLaunchBlocked: (sid) => sessionWorkerSupervisor?.isKillBlocked?.(sid) === true,
+  getLaunchState: (sid) => {
+    const lifecycle = sessionWorkerSupervisor?.getLifecycleState?.(sid) || null;
+    if (!lifecycle) return null;
+    return {
+      launchMode: lifecycle.launchMode,
+      launchAtMs: lifecycle.launchAt ? Date.parse(lifecycle.launchAt) : null,
+      awaitingHeartbeat: lifecycle.awaitingHeartbeat === true,
+    };
+  },
+  isWorkerProcessAlive: async (sid) => Boolean(await sessionWorkerProcessInspector?.findProcessForSessionAsync?.(sid)),
+  replaceWorker: replaceDetachedSessionWorker,
+  log: (message) => console.warn(`${runtimeLogPrefix()}${message}`),
+});
+
 const sessionWorkerWebSocketService = createSessionWorkerWebSocketService({
   WebSocketServerImpl: WebSocketServer,
   httpServer,
@@ -6414,7 +6671,27 @@ app.get(['/shared/:token', '/shared/:token/'], (req, res, next) => {
   try {
     const rawToken = String(req.params?.token || '').trim().toLowerCase();
     const shareToken = /^[a-f0-9]{32,128}$/.test(rawToken) ? rawToken : '';
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('X-Robots-Tag', 'noindex, nofollow, noarchive');
+    // An unknown, revoked or renewed link is a plain 404: no app shell, and
+    // nothing that tells it apart from a link that never existed.
+    if (!shareToken || !shareRepository.findLiveShare(shareToken)) {
+      res.status(404).type('text/plain').send('Not Found');
+      return;
+    }
     const html = renderIndexHtmlWithPwaVersion({ sharedToken: shareToken });
+    res.type('html').send(html);
+  } catch (error) {
+    next(error);
+  }
+});
+// "Preview as shared": the shared reader for the owner. The page holds
+// nothing of the conversation; its data comes from the owner-only preview route.
+app.get(['/share-preview/:conversationId', '/share-preview/:conversationId/'], (req, res, next) => {
+  try {
+    const conversationId = String(req.params?.conversationId || '').trim();
+    const sharePreviewConversationId = /^[A-Za-z0-9_.:-]{1,200}$/.test(conversationId) ? conversationId : '';
+    const html = renderIndexHtmlWithPwaVersion({ sharePreviewConversationId });
     res.setHeader('Cache-Control', 'no-store');
     res.setHeader('X-Robots-Tag', 'noindex, nofollow, noarchive');
     res.type('html').send(html);
@@ -6437,6 +6714,9 @@ const runtimeState = {
   set relayPaused(value) { relayPaused = value; },
   get ttyConsoleActive() { return Boolean(ttyConsoleRuntime?.tty); },
   get relayShutdown() { return getRelayShutdownState(); },
+  // A shutdown or restart waits for the processing turns: no pending row
+  // goes out meanwhile (see requestRelayShutdown).
+  get relayShutdownQueued() { return !!pendingRelayShutdownRequest && !runtimeShutdownStarted; },
   get hostSuspend() { return hostSuspendService.getState(); },
   get usageLimit() {
     return { account: usageLimitPauseService.getAccountState(), pauses: usageLimitPauseService.listPauses() };
@@ -6490,6 +6770,13 @@ const remoteRelayRegistry = createRemoteRelayRegistry({
   platform: process.platform,
   version: RUNNING_VERSION,
   emit: (event, payload) => io.emit(event, payload),
+  onRemove: (entry) => { void relayEventLinkService?.noteRelayRemoved(entry); },
+  logger: console,
+});
+relayEventLinkService = createRelayEventLinkService({
+  relayEvents: relayEventService,
+  registry: remoteRelayRegistry,
+  client: remoteRelayClient,
   logger: console,
 });
 const remoteRelayPairing = createRemoteRelayPairing({
@@ -6520,7 +6807,10 @@ const remoteRelayCallerContext = createRemoteRelayCallerContext({
   normalizeRelayMode,
   defaultRelayMode: DEFAULT_RELAY_MODE,
   emit: (event, payload) => io.emit(event, payload),
-  notifyQuestion: (question) => pushDispatchService.notifyQuestion?.(question),
+  notifyQuestion: (question) => {
+    try { relayEventService?.noteQuestion(question); } catch {}
+    return pushDispatchService.notifyQuestion?.(question);
+  },
   uuid: uuidv4,
   logger: console,
 });
@@ -6541,11 +6831,14 @@ const remoteRelayDispatcher = createRemoteRelayDispatcher({
   requestApproval: (request) => remoteRelayCallerContext.requestApproval(request),
   emitStatusEvent: ({ type, ...details }) => statusEventService.recordEvent(type, details),
   resolveConversationId: (id) => resolveConversationRecord({ conversationId: id, sdkSessionId: id })?.id || id,
+  relayEvents: relayEventService,
+  relayEventLink: relayEventLinkService,
   logger: console,
 });
 
 const sharedRouteDeps = {
   auth,
+  isTrulyLocalRequest: localRequestCheck.isTrulyLocal,
   gitChangesService,
   gitRemoteService,
   currentWorkspaceRootPath,
@@ -6665,9 +6958,12 @@ const sharedRouteDeps = {
   inFlightStateForConversation,
   resolveLiveTurnQueueRow,
   backgroundTaskStore,
+  backgroundWorkView,
   // A closure, not the registry itself: this deps object is built before the
   // preview lane is constructed further down the file.
   listConversationPreviews: (conversationId) => previewRegistry.listForConversation(conversationId),
+  closeConversationPreviews: (conversationId) => previewRegistry.closeForConversation(conversationId),
+  listKnownPreviewTokens: () => previewRegistry.knownTokens(),
   sendWorkerControl: (sessionId, control) => sessionWorkerWebSocketService.sendControlToSession(sessionId, control),
   emitToClientsExceptSessionId,
   relayBridgeOwnerService,
@@ -6729,6 +7025,11 @@ const sharedRouteDeps = {
   resolveCursorSessionRoot: cursorSessionRootResolver.resolveCursorSessionRoot,
   getTurnCeilingMinutes,
   setTurnCeilingMinutes,
+  getSubagentRecordRetentionDays,
+  setSubagentRecordRetentionDays,
+  getSharePathPrivacyMode,
+  setSharePathPrivacyMode,
+  sharePathKnownRoots,
   getBackgroundTaskTimeoutMinutes,
   setBackgroundTaskTimeoutMinutes,
   getFeatureFlagsSettingsState,
@@ -6741,6 +7042,9 @@ const sharedRouteDeps = {
   hostSuspendService,
   collectHostActivity,
   usageLimitPauseService,
+  relayEventService,
+  sessionActivityTracker,
+  resolveConversationRecord,
   markSharedViewerPresence,
   getSharedWatcherCount,
   statusEventService,
@@ -6756,9 +7060,12 @@ const sharedRouteDeps = {
   windowsBootAutostartService,
   pushDispatchService,
   remoteRelayInbound,
+  conversationGroups,
+  shareRepository,
 };
 registerMessagesRoutes(app, sharedRouteDeps);
 registerSessionsRoutes(app, sharedRouteDeps);
+registerConversationGroupRoutes(app, sharedRouteDeps);
 registerAskUserRoutes(app, sharedRouteDeps);
 registerRelayBoardRoutes(app, sharedRouteDeps);
 registerCacheRoutes(app, sharedRouteDeps);
@@ -6774,6 +7081,36 @@ registerRemoteRelayRoutes(app, {
   registry: remoteRelayRegistry,
   pairing: remoteRelayPairing,
   dispatcher: remoteRelayDispatcher,
+  remoteRelayInbound,
+});
+registerRelayEventRoutes(app, {
+  auth,
+  relayEventService,
+  remoteRelayInbound,
+});
+registerAboutRoutes(app, {
+  auth,
+  aboutService: createAboutService({
+    db,
+    dbPath: DB_PATH,
+    version: RUNNING_VERSION,
+    commit: BUILD_COMMIT,
+    installMethod: INSTALL_METHOD,
+    startedAt: RELAY_STARTED_AT,
+    packageRoot: PACKAGE_ROOT,
+    getProviderSettings: () => ({
+      github: { enabled: true, engine: getCopilotEngine() },
+      openai: { enabled: getOpenAIProviderSettings()?.enabled === true },
+      claude: { enabled: getClaudeProviderSettings()?.enabled === true },
+      'claude-cloud': { enabled: getClaudeCloudProviderSettings()?.enabled === true },
+      cursor: { enabled: getCursorProviderSettings()?.enabled === true },
+      grok: { enabled: getGrokProviderSettings()?.enabled === true },
+    }),
+    getCachedCliProviders: () => cliInstallService.getCachedStatusSnapshot()?.providers || {},
+    isRelayCliOnline: () => runtimeState.cliOnline === true,
+    listWorkers: () => sessionWorkerRegistry.listWorkers(),
+    getUpdateState: () => buildUpdateStatePayload(),
+  }),
 });
 function markCliOffline(reason = 'offline', { clearOwner = true } = {}) {
   cliLastSeen = null;
@@ -6817,9 +7154,22 @@ if (managedOwnerPid) {
 // The window is measured from the last heartbeat that named the message, not
 // from when the turn began, so a turn stays alive for as long as its worker
 // keeps reporting it — however many minutes of tool calls and subagents that
-// takes. The separate, user-configurable ceiling is the only elapsed-time cap,
-// and both exempt a turn that is waiting on an unanswered question.
+// takes. The separate, user-configurable ceiling is the only elapsed-time cap;
+// it counts from the last answered question rather than from the start, and
+// both exempt a turn that is waiting on an unanswered question (continuation
+// rows included — an interview hangs its cards on one).
+//
+// After a wall-clock jump (the host slept, the event loop was blocked) every
+// heartbeat looks old at once although the workers may be alive: the guard
+// skips recovery for a full inactivity window, so a live worker can report.
+const STALE_RECOVERY_INTERVAL_MS = 15_000;
+const staleRecoveryClockGuard = createStaleRecoveryClockGuard({
+  intervalMs: STALE_RECOVERY_INTERVAL_MS,
+  graceMs: Math.max(processingTimeoutMs, 60_000),
+  log: (line) => console.log(`${runtimeLogPrefix()}${line}`),
+});
 function recoverStaleMessages() {
+  if (staleRecoveryClockGuard.tick().skip) return;
   const staleWindowMs = cliOnline
     ? processingTimeoutMs
     : Math.min(processingTimeoutMs, OFFLINE_STALE_RECOVER_MS);
@@ -6835,7 +7185,7 @@ function recoverStaleMessages() {
     );
   }
 }
-runtimeTimers.staleRecovery = setInterval(recoverStaleMessages, 15_000);
+runtimeTimers.staleRecovery = setInterval(recoverStaleMessages, STALE_RECOVERY_INTERVAL_MS);
 recoverStaleMessages(); // run immediately on startup
 
 function expirePendingQuestions() {
@@ -6865,6 +7215,40 @@ if (sweptUploads > 0) {
 }
 runtimeTimers.uploadSweep = setInterval(sweepUnreferencedUploadBlobs, 6 * 60 * 60 * 1000);
 if (typeof runtimeTimers.uploadSweep.unref === 'function') runtimeTimers.uploadSweep.unref();
+// Old sub-agent records lose their tool inputs and output: shortly after
+// start (not in the boot path), then once a day.
+subagentRecordRetention = createSubagentRecordRetention({
+  db,
+  getRetentionDays: getSubagentRecordRetentionDays,
+  isStopped: () => runtimeShutdownStarted,
+  log: (line) => console.log(`${runtimeLogPrefix()}${line}`),
+  warn: (line) => console.warn(`${runtimeLogPrefix()}${line}`),
+});
+subagentRecordRetention.scheduleSweep(30_000);
+runtimeTimers.subagentRecordRetention = setInterval(() => { void subagentRecordRetention.sweep(); }, 24 * 60 * 60 * 1000);
+if (typeof runtimeTimers.subagentRecordRetention.unref === 'function') runtimeTimers.subagentRecordRetention.unref();
+// Sub-agent runs left `running` by a worker that is gone are closed: once
+// the previous runtime's workers have had time to reconnect after boot, then
+// periodically. A live worker's runs are never touched.
+const staleSubagentRunSweep = createStaleSubagentRunSweep({
+  db,
+  isConversationWorkerAlive: (conversationId) => {
+    if (hostActivityWorkerAlive(conversationId)) return true;
+    const sdkSessionId = String(stmts.getRuntimeSessionByConversation?.get?.(conversationId)?.sdk_session_id || '').trim();
+    return !!sdkSessionId && hostActivityWorkerAlive(sdkSessionId);
+  },
+  log: (line) => console.log(`${runtimeLogPrefix()}${line}`),
+  warn: (line) => console.warn(`${runtimeLogPrefix()}${line}`),
+});
+runtimeTimers.staleSubagentRunsBoot = setTimeout(() => {
+  runtimeTimers.staleSubagentRunsBoot = null;
+  if (!runtimeShutdownStarted) staleSubagentRunSweep.sweep();
+}, STALE_SUBAGENT_RUN_BOOT_DELAY_MS);
+if (typeof runtimeTimers.staleSubagentRunsBoot.unref === 'function') runtimeTimers.staleSubagentRunsBoot.unref();
+runtimeTimers.staleSubagentRuns = setInterval(() => {
+  if (!runtimeShutdownStarted) staleSubagentRunSweep.sweep();
+}, STALE_SUBAGENT_RUN_SWEEP_INTERVAL_MS);
+if (typeof runtimeTimers.staleSubagentRuns.unref === 'function') runtimeTimers.staleSubagentRuns.unref();
 // Arms the 12h update poller only when the user opted in; otherwise silent.
 updateCheckService?.startIfEnabled();
 const runtimeBindingsBootstrapped = bootstrapRuntimeSessionBindings();
@@ -6878,38 +7262,21 @@ function runtimeLogPrefix() {
 }
 
 // ─── Auth Middleware ──────────────────────────────────────────────────────────
-// Constant-time comparison so the auth token can't be recovered through response
-// timing. The token length is fixed (a UUID), so the length short-circuit leaks
-// nothing secret; any empty/missing value is a non-match.
-function tokensMatch(presented, expected) {
-  const a = Buffer.from(String(presented || ''), 'utf8');
-  const b = Buffer.from(String(expected || ''), 'utf8');
-  if (a.length === 0 || b.length === 0 || a.length !== b.length) return false;
-  return crypto.timingSafeEqual(a, b);
-}
+// Token check, wrong-token lockout and the Socket.IO handshake gate live in
+// services/relay-auth.mjs. `auth` stays a hoisted function: the route deps
+// above hand it out before this line runs.
+const relayAuth = createRelayAuth({
+  app,
+  getAuthToken: () => config.authToken,
+  cookieName: AUTH_COOKIE,
+  cookiePath: COOKIE_PATH,
+  parseCookies,
+  appendSetCookie,
+  localRequestCheck,
+  logger: console,
+});
 function auth(req, res, next) {
-  const cookies = parseCookies(req.headers.cookie);
-  // req.secure is derived through the configured `trust proxy` boundary, so a
-  // direct (untrusted) client can no longer force a non-Secure cookie by
-  // omitting X-Forwarded-Proto.
-  const secureAttr = req.secure ? '; Secure' : '';
-  // Note: the token is intentionally NOT read from req.body — a request body is
-  // an easy CSRF/logging vector and has no legitimate use here. Header, query
-  // (first-load bootstrap only), and the HttpOnly cookie remain.
-  const token =
-    (req.headers['authorization'] || '').replace(/^Bearer\s+/i, '') ||
-    req.query.token ||
-    cookies[AUTH_COOKIE];
-  if (tokensMatch(token, config.authToken)) {
-    if (res && !tokensMatch(cookies[AUTH_COOKIE], config.authToken)) {
-      appendSetCookie(res, `${AUTH_COOKIE}=${encodeURIComponent(config.authToken)}; Path=${COOKIE_PATH}; Max-Age=2592000; SameSite=Lax; HttpOnly${secureAttr}`);
-    }
-    return next();
-  }
-  if (res && cookies[AUTH_COOKIE]) {
-    appendSetCookie(res, `${AUTH_COOKIE}=; Path=${COOKIE_PATH}; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=Lax; HttpOnly${secureAttr}`);
-  }
-  res.status(401).json({ error: 'Unauthorized' });
+  return relayAuth.auth(req, res, next);
 }
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -7067,8 +7434,15 @@ function touchCli() {
 }
 sessionWorkerWebSocketService.start();
 void primePendingSessionWorkers('startup');
+// Undelivered events get their timers back; stalled, all_idle and the
+// heartbeat are swept from here on.
+relayEventService.start();
+relayEventLinkService.start();
 runtimeTimers.pendingWorkerPrime = setInterval(() => {
   void primePendingSessionWorkers('maintenance');
+  detachedWorkerWatch.sweep().catch((error) => {
+    console.warn(`${runtimeLogPrefix()}WORKER DETACHED sweep failed: ${error?.message || error}`);
+  });
 }, 5_000);
 if (typeof runtimeTimers.pendingWorkerPrime.unref === 'function') runtimeTimers.pendingWorkerPrime.unref();
 
@@ -7109,14 +7483,13 @@ function sanitizeRelayQuestionContext(rawContext) {
 
 
 // ─── Socket.io Auth ───────────────────────────────────────────────────────────
-function socketAuthToken(socket) {
-  const cookies = parseCookies(socket.request.headers.cookie);
-  return socket.handshake.auth?.token || socket.handshake.query?.token || cookies[AUTH_COOKIE];
-}
-io.use((socket, next) => {
-  if (tokensMatch(socketAuthToken(socket), config.authToken)) return next();
-  next(new Error('Unauthorized'));
+// A sub-agent's record goes live only to the pages whose viewer shows it.
+const subagentViewerRooms = createSubagentViewerRooms({
+  getRun: (runId) => stmts.getSubagentRun?.get?.(runId) || null,
 });
+// The handshake presents the token as `auth.token` or the cookie; a query
+// `token` is not read (see services/relay-auth.mjs).
+io.use(relayAuth.socketMiddleware);
 
 io.engine.on('initial_headers', (headers, req) => {
   const sessionId = ensureSessionId(req);
@@ -7128,7 +7501,7 @@ io.on('connection', (socket) => {
   // socket bypasses the io.use() token gate above. Re-validate here and drop it
   // on mismatch so a recovered session still requires the auth token (and a
   // rotated token takes effect immediately).
-  if (socket.recovered && !tokensMatch(socketAuthToken(socket), config.authToken)) {
+  if (socket.recovered && !relayAuth.socketTokenValid(socket)) {
     socket.disconnect(true);
     return;
   }
@@ -7150,6 +7523,7 @@ io.on('connection', (socket) => {
   // deviceVisible flag restored by connectionStateRecovery.
   activeDeviceTracker.registerSocket(socket);
   tmuxInspectorSocketService.registerSocket(socket);
+  subagentViewerRooms.registerSocket(socket);
 });
 
 // ─── SSH Reverse Tunnel ────────────────────────────────────────────────────────
@@ -7198,11 +7572,42 @@ const previewsConfig = normalizePreviewsConfig(config.previews || {}, {
 for (const previewConfigError of previewsConfig.errors) {
   console.warn(`${runtimeLogPrefix()}PREVIEW LANE disabled: ${previewConfigError}`);
 }
+// Static previews are jailed to the conversation's workspace root; a preview
+// registered without a conversation falls back to the server-wide root.
+const resolvePreviewWorkspaceRoot = (conversationId) => {
+  if (String(conversationId || '').trim()) {
+    const state = resolveConversationWorkspaceState({ conversationId });
+    const rootPath = String(state?.currentWorkspaceRootPath || '').trim();
+    if (rootPath) return rootPath;
+  }
+  return currentWorkspaceRootPath();
+};
+// Persisted in the previews table and restored here, each row checked again
+// with the registration rules (see createPreviewRegistry).
 const previewRegistry = createPreviewRegistry({
   config: previewsConfig,
   onChange: ({ previews }) => {
     try { io.emit('previews', { previews }); } catch {}
   },
+  store: createSqlitePreviewStore(db, { logger: console }),
+  hostBootId: readHostBootId(),
+  isSameHostBoot,
+  checkConversation: (conversationId) => {
+    const row = stmts.getConvAnyStatus.get(conversationId);
+    return !!row && row.status !== 'deleted';
+  },
+  // At boot no worker has reported, so the configured root comes first while
+  // the preview may have been registered under the worker's runtime root:
+  // either of the conversation's roots keeps it.
+  checkStaticRoot: (rootDir, conversationId) => {
+    const state = String(conversationId || '').trim()
+      ? resolveConversationWorkspaceState({ conversationId }) : null;
+    return validateStaticRootInAny(rootDir, [
+      resolvePreviewWorkspaceRoot(conversationId),
+      state?.runtimeWorkspaceRootPath,
+      state?.configuredWorkspaceRootPath,
+    ]);
+  },
 });
 const previewProxyServer = createPreviewProxyServer({
   registry: previewRegistry,
@@ -7226,16 +7631,7 @@ registerPreviewRoutes(app, {
   auth,
   previewRegistry,
   previewHealthProbe,
-  // Static previews are jailed to the conversation's workspace root; a preview
-  // registered without a conversation falls back to the server-wide root.
-  resolvePreviewWorkspaceRoot: (conversationId) => {
-    if (String(conversationId || '').trim()) {
-      const state = resolveConversationWorkspaceState({ conversationId });
-      const rootPath = String(state?.currentWorkspaceRootPath || '').trim();
-      if (rootPath) return rootPath;
-    }
-    return currentWorkspaceRootPath();
-  },
+  resolvePreviewWorkspaceRoot,
   // A preview published while a turn is processing gets pinned to that turn's
   // transcript (snapshot, keyed on the queue id and linked to the response at
   // finalize — the relay_activity two-step). No in-flight turn → no card.
@@ -7259,6 +7655,7 @@ function clearRuntimeTimers() {
     if (!timer) continue;
     try { clearInterval(timer); } catch {}
   }
+  subagentRecordRetention?.stop();
   runtimeTimers.cliStatus = null;
   runtimeTimers.ownerWatchdog = null;
   runtimeTimers.staleRecovery = null;
@@ -7306,15 +7703,17 @@ function shutdownRuntime(reason = 'unknown', { exitCode = 0 } = {}) {
     console.warn(`${runtimeLogPrefix()}Grok auth service shutdown failed: ${error?.message || error}`);
   }
   sessionWorkerWebSocketService.stop();
+  try { relayEventService.stop(); } catch {}
+  try { relayEventLinkService.stop(); } catch {}
   tmuxInspectorSocketService.stop();
   stopWorkspaceFileWatcher();
   sshTunnelManager.stop();
   cloudflaredTunnelManager.stop();
   previewHealthProbe.stop();
   try { remoteRelayRegistry.stopHealthLoop(); } catch {}
-  // Previews are in-memory by design: a restart is the only implicit cleanup,
-  // so every public link dies with the process.
-  previewRegistry.clear();
+  // Previews persist across the restart (the next runtime restores them); only
+  // the throttled last-use times still need writing.
+  previewRegistry.flushHits();
   void previewProxyServer.stop().catch(() => {});
   try { relaySingletonGuard.release(); } catch (error) {
     console.warn(`${runtimeLogPrefix()}Failed to release singleton lock: ${error?.message || error}`);