@oar-sh/oar 0.9.12 → 0.9.13

package/server/services/provider-model-selection.mjs

@@ -89,3 +89,198 @@ export function resolveProviderModelSelection({
     availableModels: Array.from(index.values()),
   };
 }
+
+// ─── Checking a model an agent names (remote_relay create_session / send) ───
+
+const PROVIDER_LABELS = Object.freeze({
+  github: 'Copilot',
+  openai: 'OpenAI',
+  claude: 'Claude',
+  cursor: 'Cursor',
+  grok: 'Grok',
+  'claude-cloud': 'Claude Cloud',
+});
+const CLAUDE_PROVIDERS = new Set(['claude', 'claude-cloud']);
+const LONG_CONTEXT_SUFFIX = /\[1m\]$/i;
+// A Copilot model with its effort, as the composer sends it ("gpt-5.4-high").
+const EFFORT_VARIANT_SUFFIX = /-(none|minimal|low|medium|high|xhigh|max)$/i;
+// A Claude alias ("opus", "sonnet[1m]"): one word, no version.
+const CLAUDE_ALIAS = /^([a-z]+)(\[1m\])?$/i;
+const SUGGESTIONS_MAX = 3;
+
+/** How a relay calls a provider in its messages. */
+export function providerModelLabel(provider) {
+  return PROVIDER_LABELS[String(provider || '').trim().toLowerCase()] || String(provider || '').trim() || 'this provider';
+}
+
+/** Lower case, no tier suffix, letters and digits only: "GPT-5.4" and "gpt-5-4" meet as "gpt54". */
+function looseModelKey(value) {
+  return normalizeProviderModelId(value).toLowerCase().replace(LONG_CONTEXT_SUFFIX, '').replace(/[^a-z0-9]+/g, '');
+}
+
+function editDistance(a, b) {
+  if (a === b) return 0;
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j += 1) {
+      current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    previous = current;
+  }
+  return previous[b.length];
+}
+
+/**
+ * The ids of `availableModels` closest to `requestedModel`, best first, at
+ * most `max`: the same id written with other separators or casing, then ids
+ * a few edits away, then ids that contain what was asked for.
+ */
+export function suggestProviderModelIds(requestedModel, availableModels = [], { max = SUGGESTIONS_MAX } = {}) {
+  const requested = normalizeProviderModelId(requestedModel).toLowerCase().replace(LONG_CONTEXT_SUFFIX, '');
+  const loose = looseModelKey(requestedModel);
+  if (!requested || !loose) return [];
+  const scored = [];
+  for (const candidate of buildCanonicalModelIndex(availableModels).values()) {
+    const plain = candidate.toLowerCase().replace(LONG_CONTEXT_SUFFIX, '');
+    const candidateLoose = looseModelKey(candidate);
+    let score = null;
+    if (candidateLoose === loose) score = 0;
+    else {
+      // A few edits for a real id, none for a stub ("x" is no typo of "o3").
+      const allowed = requested.length >= 4 ? Math.max(1, Math.floor(requested.length / 4)) : 0;
+      const distance = allowed ? editDistance(requested, plain) : Infinity;
+      if (distance <= allowed) score = 1 + distance;
+      else if (loose.length >= 3 && candidateLoose.includes(loose)) score = 100 + candidateLoose.length - loose.length;
+    }
+    if (score !== null) scored.push({ candidate, score });
+  }
+  return scored
+    .sort((a, b) => a.score - b.score || a.candidate.localeCompare(b.candidate))
+    .slice(0, Math.max(0, max))
+    .map((entry) => entry.candidate);
+}
+
+const DATE_SUFFIX = /-\d{8}$/;
+
+/** "claude-opus-4-1-20250805" → { version: [4, 1], dated: true }. */
+function claudeVersionOf(model, prefix) {
+  const rest = model.toLowerCase().slice(prefix.length);
+  const dated = DATE_SUFFIX.test(rest);
+  const version = rest.replace(DATE_SUFFIX, '').split(/[^0-9]+/).filter(Boolean).map(Number);
+  return { version, dated };
+}
+
+function compareVersionsDescending(a, b) {
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const difference = (b[index] ?? -1) - (a[index] ?? -1);
+    if (difference) return difference;
+  }
+  return 0;
+}
+
+/**
+ * The newest listed Claude model of an alias's family ("opus" →
+ * "claude-opus-5-5" over "claude-opus-5" and "claude-opus-4-1-20250805"):
+ * by version number, a date suffix ignored, the undated id before a dated
+ * one of the same version. "[1m]" ids are not the family's; with `longContext`
+ * the chosen model's "[1m]" id is taken when it is listed. Returns
+ * `{ model, tierDropped }`, or null for a family with no listed model.
+ */
+function resolveClaudeAlias(word, index, longContext) {
+  const prefix = `claude-${word.toLowerCase()}-`;
+  const members = (tiered) => [...index.values()]
+    .filter((model) => LONG_CONTEXT_SUFFIX.test(model) === tiered && model.toLowerCase().startsWith(prefix))
+    .map((model) => ({ model, ...claudeVersionOf(model.replace(LONG_CONTEXT_SUFFIX, ''), prefix) }))
+    .filter((entry) => entry.version.length);
+  let family = members(false);
+  // A list that holds the family only as "[1m]" ids: those are its models.
+  if (!family.length) {
+    family = members(true);
+    if (!family.length) return null;
+    family.sort((a, b) => compareVersionsDescending(a.version, b.version) || Number(a.dated) - Number(b.dated) || a.model.localeCompare(b.model));
+    return { model: family[0].model, tierDropped: false };
+  }
+  family.sort((a, b) => compareVersionsDescending(a.version, b.version) || Number(a.dated) - Number(b.dated) || a.model.localeCompare(b.model));
+  const chosen = family[0].model;
+  if (!longContext) return { model: chosen, tierDropped: false };
+  const tiered = index.get(`${chosen}[1m]`.toLowerCase());
+  return tiered ? { model: tiered, tierDropped: false } : { model: chosen, tierDropped: true };
+}
+
+/**
+ * Whether a provider offers the model an agent asked for, by the list New
+ * Chat offers for it. `models` is that list, or null when it is not known
+ * (discovery has not run, the relay did not answer). Returns one of:
+ *
+ * - `{ status: 'known', model }`: offered; `model` is the provider's own
+ *   casing, the same Claude model without its "[1m]" tier when only the
+ *   base is listed (`tierDropped`), or "auto". A Copilot model with its
+ *   effort ("gpt-5.4-high") also has `base` (the listed id) and `effort`:
+ *   the bootstrap knows base ids only, so callers pass them apart. Taken so
+ *   only when `effortsFor(base)` (the efforts the catalogue lists for it)
+ *   holds that effort; else the id is unknown, with the base suggested.
+ * - `{ status: 'alias', model, tierDropped }`: a Claude alias ("opus",
+ *   "sonnet[1m]"), taken as the newest listed model of its family.
+ * - `{ status: 'unchecked', model }`: no list to check against; the request
+ *   goes on as asked.
+ * - `{ status: 'unknown', model, suggestions, models }`: not offered.
+ */
+export function checkRequestedProviderModel({ requestedModel = '', provider = '', models = null, defaultModel = '', effortsFor = null } = {}) {
+  const requested = normalizeProviderModelId(requestedModel);
+  if (!requested || isAutoModelId(requested)) return { status: 'known', model: requested };
+  if (!Array.isArray(models)) return { status: 'unchecked', model: requested };
+  // "auto" is listed before discovery has run too: it makes no list.
+  const list = [...buildCanonicalModelIndex([defaultModel, ...models]).values()].filter((model) => !isAutoModelId(model));
+  if (!list.length) return { status: 'unchecked', model: requested };
+  const index = buildCanonicalModelIndex(list);
+  const exact = index.get(requested.toLowerCase());
+  if (exact) return { status: 'known', model: exact };
+  const claude = CLAUDE_PROVIDERS.has(String(provider || '').trim().toLowerCase());
+  if (claude && LONG_CONTEXT_SUFFIX.test(requested)) {
+    const base = index.get(requested.replace(LONG_CONTEXT_SUFFIX, '').toLowerCase());
+    if (base) return { status: 'known', model: base, tierDropped: true };
+  }
+  if (claude) {
+    const alias = CLAUDE_ALIAS.exec(requested);
+    const resolved = alias ? resolveClaudeAlias(alias[1], index, !!alias[2]) : null;
+    if (resolved) return { status: 'alias', ...resolved };
+  }
+  const variant = EFFORT_VARIANT_SUFFIX.exec(requested);
+  const base = variant ? requested.slice(0, variant.index) : '';
+  // Only Copilot takes a model with its effort in the id, and only an effort
+  // the listed model is known to take: "gpt-5.1-codex-max" is a model of its
+  // own, not gpt-5.1-codex at effort max.
+  const listedBase = base && String(provider || '').trim().toLowerCase() === 'github' ? index.get(base.toLowerCase()) : '';
+  const effort = variant ? variant[1].toLowerCase() : '';
+  if (listedBase) {
+    const efforts = typeof effortsFor === 'function' ? effortsFor(listedBase) : null;
+    if (Array.isArray(efforts) && efforts.map((value) => String(value || '').trim().toLowerCase()).includes(effort)) {
+      return { status: 'known', model: `${listedBase}-${effort}`, base: listedBase, effort };
+    }
+  }
+  const suggestions = suggestProviderModelIds(requested, list);
+  const baseFirst = listedBase ? [listedBase, ...suggestions.filter((model) => model !== listedBase)] : suggestions;
+  return {
+    status: 'unknown',
+    model: requested,
+    suggestions: (baseFirst.length || !base ? baseFirst : suggestProviderModelIds(base, list)).slice(0, SUGGESTIONS_MAX),
+    models: list,
+  };
+}
+
+const MODELS_LISTED_MAX = 20;
+
+/** The refusal of an unknown model: "Unknown model 'gpt-5-4' for Copilot; did you mean 'gpt-5.4'? …". */
+export function unknownProviderModelText({ model, provider, suggestions = [], models = [], where = '' } = {}) {
+  const label = providerModelLabel(provider);
+  const quoted = (value) => `'${value}'`;
+  const parts = [`Unknown model ${quoted(model)} for ${label}${where ? ` ${where}` : ''}`];
+  if (suggestions.length) parts.push(`; did you mean ${suggestions.map(quoted).join(' or ')}?`);
+  else parts.push('.');
+  const shown = models.slice(0, MODELS_LISTED_MAX);
+  if (shown.length) {
+    parts.push(` Valid ids: ${shown.join(', ')}${models.length > shown.length ? ` (and ${models.length - shown.length} more)` : ''}.`);
+  }
+  return parts.join('');
+}

package/server/services/push-dispatch-service.mjs

@@ -10,7 +10,7 @@
  * reports outcomes through the status-events store instead.
  */
 
-export const PUSH_EVENT_TYPES = Object.freeze(['question', 'turnComplete', 'turnFailed', 'board', 'cliOffline', 'hostSuspend']);
+export const PUSH_EVENT_TYPES = Object.freeze(['question', 'turnComplete', 'turnFailed', 'board', 'cliOffline', 'hostSuspend', 'relayRestart']);
 
 export const VAPID_PUBLIC_KEY_SETTING = 'push_vapid_public_key';
 export const VAPID_PRIVATE_KEY_SETTING = 'push_vapid_private_key';
@@ -35,11 +35,12 @@ const EVENT_LABELS = Object.freeze({
   board: { title: 'Plan ready for review', generic: 'The agent posted a board for review.' },
   cliOffline: { title: 'CLI offline', generic: 'The relay lost its connection to the CLI host.' },
   hostSuspend: { title: 'Host suspend', generic: 'The queued host suspend changed state.' },
+  relayRestart: { title: 'Relay restart waiting', generic: 'The queued relay restart has waited its maximum time.' },
 });
 
 // System events carry their own body: no conversation text to preview, and
 // the body is the message itself regardless of the preview preference.
-const SYSTEM_BODY_TYPES = new Set(['hostSuspend']);
+const SYSTEM_BODY_TYPES = new Set(['hostSuspend', 'relayRestart']);
 
 function clampInt(value, min, max, fallback) {
   const numeric = Number(value);
@@ -493,8 +494,14 @@ export function createPushDispatchService({
     return dispatch({ type: 'hostSuspend', body: body || null, data: { hostSuspendAt: Date.now() } });
   }
 
+  // The queued restart's maximum wait ran out: it asks, it does not restart.
+  function notifyRelayRestart({ body = null } = {}) {
+    return dispatch({ type: 'relayRestart', body: body || null, data: { relayRestartAt: Date.now() } });
+  }
+
   return {
     notifyHostSuspend,
+    notifyRelayRestart,
     listDevices,
     getDevice,
     upsertSubscription,

package/server/services/relay-event-service.mjs

@@ -57,13 +57,18 @@ import {
   RELAY_EVENT_LINK_LOST_TYPE,
   RELAY_EVENT_LINK_RESTORED_TYPE,
   RELAY_EVENT_MESSAGE_KIND,
+  RELAY_EVENT_SUBAGENT_FINISHED_TYPE,
+  RELAY_EVENT_SUBSCRIBABLE_TYPES,
   RELAY_EVENT_TYPES,
   RELAY_EVENT_VERSION,
   buildRelayEventMessageText,
   compileRelayEventMatch,
+  effectiveRelayEventTypes,
+  isLegacyDefaultRelayEventTypes,
   isRelayEventType,
   isUrgentRelayEventType,
   relayEventMatchText,
+  relayEventTypesTake,
 } from '../../shared/relay-events.mjs';
 
 export const RELAY_EVENT_SUBSCRIPTIONS_SOCKET_EVENT = 'relay_event_subscriptions';
@@ -403,6 +408,11 @@ export function createRelayEventService({
     return !!row && Number(row.archived || 0) !== 1 && toText(row.status) !== 'deleted';
   }
 
+  /** A subscription's events; the old default list counts as today's default. */
+  function storedTypes(row) {
+    return effectiveRelayEventTypes(parseJson(row?.events_json, []));
+  }
+
   function shapeSubscription(row) {
     if (!row) return null;
     const scope = toText(row.scope) === 'all' ? 'all' : 'sessions';
@@ -431,7 +441,10 @@ export function createRelayEventService({
       sessions: scope === 'all'
         ? 'all'
         : sessionIds.map((id) => ({ id, title: mirror ? (remoteTitles.get(id) || null) : (toText(conversation(id)?.title) || null) })),
-      events: parseJson(row.events_json, []).filter((type) => RELAY_EVENT_TYPES.includes(type)),
+      // A mirror shows what the paired relay applies; a subscription here,
+      // stored with the old default, the default that applies now.
+      events: (mirror ? parseJson(row.events_json, []) : storedTypes(row))
+        .filter((type) => RELAY_EVENT_SUBSCRIBABLE_TYPES.includes(type)),
       once: Number(row.once || 0) === 1,
       ...(toText(row.match) ? { match: row.match } : {}),
       stalledMinutes: Number(row.stalled_minutes) || RELAY_EVENT_LIMITS.stalledMinutesDefault,
@@ -504,9 +517,13 @@ export function createRelayEventService({
       throw new RelayEventError('notFound', `No live session with id ${missing.join(', ')} on this relay (archived sessions cannot be watched).`, { sessions: missing });
     }
     const types = Array.isArray(events) && events.length
-      ? [...new Set(events.map(toText).filter((type) => RELAY_EVENT_TYPES.includes(type)))]
+      ? [...new Set(events.map(toText).filter((type) => RELAY_EVENT_SUBSCRIBABLE_TYPES.includes(type)))]
       : [...RELAY_EVENT_DEFAULT_TYPES];
-    if (!types.length) throw new RelayEventError('invalid', `events must name some of: ${RELAY_EVENT_TYPES.join(', ')}`);
+    if (!types.length) throw new RelayEventError('invalid', `events must name some of: ${RELAY_EVENT_SUBSCRIBABLE_TYPES.join(', ')}`);
+    // Named exactly as the old default was stored, this list would be read
+    // as today's default and lose its task_finished (effectiveRelayEventTypes);
+    // subagent_finished beside it changes nothing it takes and keeps it named.
+    if (isLegacyDefaultRelayEventTypes(types)) types.push(RELAY_EVENT_SUBAGENT_FINISHED_TYPE);
     const compiled = compileRelayEventMatch(match);
     if (!compiled.ok) throw new RelayEventError('invalid', compiled.error);
     const stalled = Number.isFinite(Number(stalledMinutes)) && stalledMinutes !== null && stalledMinutes !== ''
@@ -771,8 +788,9 @@ export function createRelayEventService({
     return parseJson(row.session_ids_json, []).map(toText).includes(sessionId);
   }
 
-  function wants(row, type) {
-    return parseJson(row.events_json, []).includes(type);
+  /** `event` is `{ type, detail }`: a task_finished's kind decides under subagent_finished. */
+  function wants(row, event) {
+    return relayEventTypesTake(storedTypes(row), event);
   }
 
   /** `match` filters the events it can be tried on; the others pass. */
@@ -807,7 +825,7 @@ export function createRelayEventService({
     if (!available || !RELAY_EVENT_TYPES.includes(type)) return 0;
     const id = toText(sessionId);
     if (!id) return 0;
-    const rows = localWatchRows().filter((row) => wants(row, type) && subscriptionCovers(row, id));
+    const rows = localWatchRows().filter((row) => wants(row, { type, detail }) && subscriptionCovers(row, id));
     if (!rows.length) return 0;
     const event = buildEvent(type, id, detail);
     return enqueueForRows(rows, event, id);
@@ -1271,7 +1289,7 @@ export function createRelayEventService({
     const sessions = all ? [] : (Array.isArray(remote.sessions) ? remote.sessions : [])
       .map((session) => ({ id: toText(session?.id), title: toText(session?.title) || null }))
       .filter((session) => session.id);
-    const types = (Array.isArray(remote.events) ? remote.events : []).filter((type) => RELAY_EVENT_TYPES.includes(type));
+    const types = (Array.isArray(remote.events) ? remote.events : []).filter((type) => RELAY_EVENT_SUBSCRIBABLE_TYPES.includes(type));
     const id = `sub_${randomBytes(5).toString('hex')}`;
     const at = isoNow();
     remoteSql.insertMirror.run(
@@ -1814,7 +1832,7 @@ export function createRelayEventService({
       }
       busyBySubscription.set(row.id, false);
       idleSinceBySubscription.delete(row.id);
-      if (!wants(row, 'all_idle')) continue;
+      if (!wants(row, { type: 'all_idle' })) continue;
       const count = toText(row.scope) === 'all' ? null : parseJson(row.session_ids_json, []).length;
       const event = buildEvent('all_idle', '', { scope: toText(row.scope), sessionCount: count, subscriptionId: row.id });
       enqueueForRows([row], event, '');
@@ -1832,7 +1850,7 @@ export function createRelayEventService({
   function evaluateStalled() {
     const at = now();
     for (const row of localWatchRows()) {
-      if (!wants(row, 'stalled')) continue;
+      if (!wants(row, { type: 'stalled' })) continue;
       const limitMs = (Number(row.stalled_minutes) || RELAY_EVENT_LIMITS.stalledMinutesDefault) * 60_000;
       for (const sessionId of candidateSessions(row)) {
         const view = describe(sessionId);

package/server/services/relay-prompt-sanitizer.mjs

@@ -14,6 +14,7 @@ const DEFAULT_RELAY_TOOL_GUIDANCE = [
   'For relay restarts in extension-managed mode, require explicit user permission first, then use the authenticated localhost API `POST /api/relay/shutdown`. Do not restart by killing processes or using respawn scripts.',
   'Note: shutdown is queued and only completes when the current turn finishes, so it is pointless to wait for it to interrupt an active turn.',
   'Use `restart: true` in the request body when the user wants a real relay restart rather than a plain shutdown. Example request body: `{ "reason": "manual-restart", "requestedBy": "localhost-api", "restart": true }`.',
+  'Never pass `immediate` in that request body: it restarts without waiting for the running turns, which only the user may decide, with Restart now in the web UI.',
 ].join(' ');
 
 function loadRelayToolGuidance() {
@@ -32,6 +33,10 @@ function loadRelayToolGuidance() {
 }
 
 const RELAY_TOOL_GUIDANCE = loadRelayToolGuidance();
+// Prompts stored before the `immediate` line was added carry the guidance
+// without it.
+const IMMEDIATE_GUIDANCE_LINE = 'Never pass `immediate` in that request body: it restarts without waiting for the running turns, which only the user may decide, with Restart now in the web UI.';
+const PREVIOUS_RELAY_TOOL_GUIDANCE = RELAY_TOOL_GUIDANCE.replace(` ${IMMEDIATE_GUIDANCE_LINE}`, '');
 
 const MODE_MARKERS = {
   plan: '[Relay mode: plan]',
@@ -117,6 +122,8 @@ function buildPromptPrefixPatterns(mode) {
     return [
       new RegExp(`^${whitespaceFlexiblePattern(currentFullPrefix)}\\s*`, 'i'),
       new RegExp(`^${whitespaceFlexiblePattern(legacyFullPrefix)}\\s*`, 'i'),
+      new RegExp(`^${whitespaceFlexiblePattern(`${marker} ${MODE_INSTRUCTIONS[key]} ${PREVIOUS_RELAY_TOOL_GUIDANCE}`)}\\s*`, 'i'),
+      new RegExp(`^${whitespaceFlexiblePattern(`${marker} ${LEGACY_MODE_INSTRUCTIONS[key]} ${PREVIOUS_RELAY_TOOL_GUIDANCE}`)}\\s*`, 'i'),
       new RegExp(`^${whitespaceFlexiblePattern(marker)}\\s*`, 'i'),
     ];
   });

package/server/services/relay-restart-picture.mjs

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * What a relay restart (or shutdown) waits for, holds and leaves running,
+ * read from the state the relay already has:
+ *
+ *  - waitingFor: the sessions with a processing turn. A queued restart waits
+ *    for these and only these (relay-shutdown-gate.mjs); "Restart now" does
+ *    not wait for them.
+ *  - held: pending and parked messages. While a restart is queued none of
+ *    them is handed to a worker; they run after it.
+ *  - backgroundTasks: sessions with running background work of a live
+ *    worker (shell, monitor, sub-agents; the task panel's data, through
+ *    background-work-view.mjs), each with whether it survives.
+ *
+ * Whether background work survives is a property of the session workers,
+ * not of the relay runtime: every worker is its own process (tmux, a
+ * detached process, a console window on Windows) and keeps its tasks when
+ * the runtime exits. A restart (exit 75) is taken by the relay's own
+ * supervisor or by the Copilot CLI extension, which start a new runtime;
+ * the workers report back to it. A shutdown under a systemd service is
+ * different: the service stops, and systemd stops every process of the
+ * service, which takes the workers with it unless they live outside it (a
+ * tmux session on a tmux server the user started elsewhere survives). The
+ * relay cannot tell which, so they "may stop". A Claude Cloud session runs at
+ * Anthropic and is never affected. `oar restart` and `oar stop` through
+ * systemd do not come through here at all.
+ */
+
+import fs from 'node:fs';
+
+const MAX_ROWS = 50;
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+/**
+ * How this relay process is run, from its environment and argv: whether a
+ * systemd service runs it, and whether an outer supervisor (the Copilot CLI
+ * extension, `--supervised`) owns its restarts.
+ */
+export function detectRelayHosting({
+  env = process.env,
+  argv = process.argv,
+  platform = process.platform,
+  readCgroup = () => fs.readFileSync('/proc/self/cgroup', 'utf8'),
+} = {}) {
+  // systemd sets INVOCATION_ID for the processes of a unit, and a service's
+  // cgroup ends in `.service` (a terminal's shell sits in a `.scope`).
+  let systemd = false;
+  if (platform === 'linux' && toText(env?.INVOCATION_ID)) {
+    let cgroup = '';
+    try { cgroup = String(readCgroup() || ''); } catch {}
+    systemd = cgroup.split('\n').some((line) => /\.service\/?$/.test(line.trim()));
+  }
+  const supervised = Array.isArray(argv) && argv.includes('--supervised');
+  return { systemd, supervised, platform };
+}
+
+/** Whether the session workers outlive this action, and why, in one line each. */
+export function describeRestartSurvival({ action = 'restart', hosting = {} } = {}) {
+  const restart = action === 'restart';
+  if (restart) {
+    return {
+      action: 'restart',
+      workersSurvive: true,
+      summary: 'Session workers are separate processes and keep running through a relay restart, with their background tasks; '
+        + 'they report back to the new relay within a minute.',
+    };
+  }
+  if (hosting.systemd) {
+    return {
+      action: 'shutdown',
+      workersSurvive: false,
+      summary: 'The relay runs as a systemd service: shutting it down stops the service and every process in it, '
+        + 'so session workers and their background tasks may stop too (a worker in a tmux session the service did not start keeps running).',
+    };
+  }
+  return {
+    action: 'shutdown',
+    workersSurvive: true,
+    summary: 'Session workers are separate processes and keep running while the relay is down, with their background tasks; '
+      + 'they report back when it starts again.',
+  };
+}
+
+/**
+ * The picture for one action. `queueRows` is the queue grouped by
+ * conversation and status ({ conversation_id, status, cnt, title });
+ * `backgroundBlockers` the `background` rows of background-work-view.mjs.
+ */
+export function buildRestartPicture({
+  action = 'restart',
+  queueRows = [],
+  backgroundBlockers = [],
+  // Tasks held since a relay restart (background-task-store.mjs
+  // `listRestored`, mapped to conversations): `{ conversationId, description }`.
+  heldTasks = [],
+  hosting = {},
+  providerOf = () => '',
+  titleOf = (conversationId) => toText(conversationId).slice(0, 8),
+} = {}) {
+  const survival = describeRestartSurvival({ action, hosting });
+  const turns = new Map();
+  const held = new Map();
+  for (const row of Array.isArray(queueRows) ? queueRows : []) {
+    const conversationId = toText(row?.conversation_id);
+    const count = Number(row?.cnt || 0);
+    if (!conversationId || !(count > 0)) continue;
+    const status = toText(row?.status);
+    const target = status === 'processing' ? turns : (status === 'pending' || status === 'parked') ? held : null;
+    if (!target) continue;
+    const entry = target.get(conversationId) || { conversationId, title: toText(row?.title) || titleOf(conversationId), count: 0 };
+    entry.count += count;
+    target.set(conversationId, entry);
+  }
+  const waitingFor = [...turns.values()].slice(0, MAX_ROWS).map((entry) => ({
+    conversationId: entry.conversationId,
+    title: entry.title,
+    turns: entry.count,
+  }));
+  const heldConversations = [...held.values()];
+  const backgroundTasks = (Array.isArray(backgroundBlockers) ? backgroundBlockers : [])
+    .filter((blocker) => blocker && blocker.kind === 'background' && toText(blocker.conversationId))
+    .slice(0, MAX_ROWS)
+    .map((blocker) => {
+      const conversationId = toText(blocker.conversationId);
+      const cloud = toText(providerOf(conversationId)).toLowerCase() === 'claude-cloud';
+      const survives = cloud || survival.workersSurvive;
+      return {
+        conversationId,
+        title: toText(blocker.title) || titleOf(conversationId),
+        count: Number(blocker.count) > 0 ? Math.trunc(Number(blocker.count)) : 1,
+        detail: toText(blocker.detail).slice(0, 400),
+        survives,
+        why: cloud
+          ? 'runs in the cloud'
+          : survives ? 'its worker keeps running' : 'its worker may stop with the service',
+      };
+    });
+  // Held since the last restart: neither running nor ended as far as the
+  // relay knows, until the worker's set confirms them. Whether they survive
+  // the next one is not known either.
+  const listed = new Set(backgroundTasks.map((task) => task.conversationId));
+  const unconfirmed = new Map();
+  for (const entry of Array.isArray(heldTasks) ? heldTasks : []) {
+    const conversationId = toText(entry?.conversationId);
+    if (!conversationId || listed.has(conversationId)) continue;
+    const list = unconfirmed.get(conversationId) || [];
+    list.push(toText(entry?.description) || 'task');
+    unconfirmed.set(conversationId, list);
+  }
+  for (const [conversationId, descriptions] of unconfirmed) {
+    if (backgroundTasks.length >= MAX_ROWS) break;
+    const count = descriptions.length;
+    backgroundTasks.push({
+      conversationId,
+      title: titleOf(conversationId),
+      count,
+      detail: `${count} task${count === 1 ? '' : 's'} not yet confirmed since the last relay restart: ${descriptions.slice(0, 3).map((text) => text.slice(0, 80)).join('; ')}`,
+      survives: null,
+      why: 'its worker has not confirmed it since the last restart',
+    });
+  }
+  return {
+    waitingFor,
+    held: {
+      count: heldConversations.reduce((sum, entry) => sum + entry.count, 0),
+      conversations: heldConversations.slice(0, MAX_ROWS).map((entry) => ({
+        conversationId: entry.conversationId,
+        title: entry.title,
+        count: entry.count,
+      })),
+    },
+    backgroundTasks,
+    survival,
+  };
+}
+
+/** The live collector over the relay's database and background-work view. */
+export function createRestartPictureCollector({
+  db,
+  backgroundWorkView = null,
+  // () => [{ conversationId, description }]: tasks held since a restart.
+  listHeldTasks = () => [],
+  hosting = detectRelayHosting(),
+  providerOf = () => '',
+  titleOf = undefined,
+} = {}) {
+  let listQueue = null;
+  try {
+    listQueue = db?.prepare(`
+      SELECT q.conversation_id, q.status, COUNT(*) AS cnt, MAX(c.title) AS title
+      FROM queue q LEFT JOIN conversations c ON c.id = q.conversation_id
+      WHERE q.status IN ('pending','processing','parked')
+      GROUP BY q.conversation_id, q.status
+    `) || null;
+  } catch {}
+  return function collectRestartPicture({ action = 'restart' } = {}) {
+    let queueRows = [];
+    try { queueRows = listQueue?.all() || []; } catch {}
+    let backgroundBlockers = [];
+    try { backgroundBlockers = backgroundWorkView?.backgroundBlockers?.() || []; } catch {}
+    let heldTasks = [];
+    try { heldTasks = listHeldTasks() || []; } catch {}
+    return buildRestartPicture({ action, queueRows, backgroundBlockers, heldTasks, hosting, providerOf, ...(titleOf ? { titleOf } : {}) });
+  };
+}