@oar-sh/oar 0.9.12 → 0.9.14

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

@@ -32,6 +32,13 @@
  * boot. A subscription ends on unsubscribe, when its watcher is archived or
  * deleted, when its last listed session is, or after firing (`once`).
  *
+ * relay_restarted is the relay's own event, opt-in by name: each start of
+ * the runtime (noteRelayStarted) wakes the subscriptions of this relay's
+ * watchers that name it, once, with how the run before ended
+ * (noteRelayExit). A conversation whose turn answered relay_restarted when
+ * the restart was requested (noteRestartRequested) is not woken by it: a
+ * woken turn that restarts again ends the chain.
+ *
  * Across paired relays (migrations/0012-cross-relay-event-subscriptions.mjs)
  * this service plays both sides:
  *
@@ -57,13 +64,21 @@ import {
   RELAY_EVENT_LINK_LOST_TYPE,
   RELAY_EVENT_LINK_RESTORED_TYPE,
   RELAY_EVENT_MESSAGE_KIND,
+  RELAY_EVENT_RELAY_LEVEL_TYPES,
+  RELAY_EVENT_RELAY_RESTARTED_TYPE,
+  RELAY_EVENT_SUBAGENT_FINISHED_TYPE,
+  RELAY_EVENT_SUBSCRIBABLE_TYPES,
   RELAY_EVENT_TYPES,
   RELAY_EVENT_VERSION,
   buildRelayEventMessageText,
   compileRelayEventMatch,
+  effectiveRelayEventTypes,
+  isLegacyDefaultRelayEventTypes,
   isRelayEventType,
+  isRelayLevelOnly,
   isUrgentRelayEventType,
   relayEventMatchText,
+  relayEventTypesTake,
 } from '../../shared/relay-events.mjs';
 
 export const RELAY_EVENT_SUBSCRIPTIONS_SOCKET_EVENT = 'relay_event_subscriptions';
@@ -72,6 +87,12 @@ export const RELAY_EVENT_SELF_RELAY_ID = 'self';
 // conversation id, so nothing a paired relay asks for is ever written into
 // one of this relay's conversations.
 export const RELAY_EVENT_SERVED_WATCHER_PREFIX = 'remote:';
+// app_settings: how the runtime before this one ended, written on its way
+// out (noteRelayExit) and taken by the next start (noteRelayStarted).
+export const RELAY_LAST_EXIT_SETTING_KEY = 'relay_last_exit';
+// Older than this, a record is not of the run just before this one. Long:
+// a relay stopped for a weekend still says how; the line shows the stop time.
+export const RELAY_LAST_EXIT_MAX_AGE_MS = 30 * 24 * 60 * 60_000;
 
 const HOUR_MS = 60 * 60_000;
 const DAY_MS = 24 * HOUR_MS;
@@ -286,6 +307,19 @@ export function createRelayEventService({
         AND COALESCE(m.kind, '') <> ?
     `),
     deleteDeliveredBefore: db.prepare(RELAY_EVENT_PRUNE_SQL.deleteDeliveredBefore),
+    // The loop guard: conversations whose running turn answers relay_restarted.
+    listRestartWokenRunning: db.prepare(`
+      SELECT DISTINCT q.conversation_id FROM queue q JOIN relay_events e ON e.message_id = q.id
+      WHERE q.status = 'processing' AND e.type = ?
+    `),
+  } : null;
+  const exitSql = available && tableExists('app_settings') ? {
+    get: db.prepare(`SELECT value FROM app_settings WHERE key = ?`),
+    put: db.prepare(`
+      INSERT INTO app_settings (key, value, updated_at) VALUES (?, ?, ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+    `),
+    take: db.prepare(`DELETE FROM app_settings WHERE key = ?`),
   } : null;
   // Without migration 0012 the table has no remote_sync column.
   const deleteEndedSubscriptionsBefore = available
@@ -376,6 +410,12 @@ export function createRelayEventService({
   let sweepTimer = null;
   let started = false;
   let lastPruneAt = 0;
+  // relay_restarted: the conversations a requested restart does not wake
+  // (the loop guard), whether this runtime's end is written, and whether its
+  // start was noted.
+  const restartNoWake = new Set();
+  let exitNoted = false;
+  let startNoted = false;
 
   function isoNow() {
     return new Date(now()).toISOString();
@@ -403,6 +443,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 +476,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,
@@ -487,12 +535,25 @@ export function createRelayEventService({
   /**
    * What a subscribe asks for, checked: `{ all, ids, types, matchText,
    * stalled, heartbeat }`. Throws RelayEventError (`invalid`, `notFound`).
-   * `exclude` is the watcher, never watched by itself.
+   * `exclude` is the watcher, never watched by itself. `relayLevel` allows
+   * relay_restarted (this relay's own watchers only); a subscription that
+   * names nothing else needs no sessions.
    */
-  function prepareSubscription({ scope, sessionIds, events, match, stalledMinutes, heartbeatMinutes, exclude = '' }) {
+  function prepareSubscription({ scope, sessionIds, events, match, stalledMinutes, heartbeatMinutes, exclude = '', relayLevel = false }) {
     const all = scope === 'all';
     const ids = all ? [] : [...new Set((Array.isArray(sessionIds) ? sessionIds : []).map(toText).filter(Boolean))];
-    if (!all && !ids.length) throw new RelayEventError('invalid', 'subscribe needs sessions (ids from list_sessions) or "all".');
+    const named = Array.isArray(events) ? events.map(toText).filter(Boolean) : [];
+    const relayLevelNamed = named.filter((type) => RELAY_EVENT_RELAY_LEVEL_TYPES.includes(type));
+    if (relayLevelNamed.length && !relayLevel) {
+      throw new RelayEventError('invalid', `${relayLevelNamed.join(', ')} is about the relay the watcher runs on and cannot be watched on another relay (an outage there shows as link_lost and link_restored).`);
+    }
+    if (!all && !ids.length && !isRelayLevelOnly(named)) {
+      throw new RelayEventError('invalid', `subscribe needs sessions (ids from list_sessions) or "all"${relayLevel ? ', unless events names only relay_restarted' : ''}.`);
+    }
+    // No session, no work that could run: a heartbeat would never come.
+    if (!all && !ids.length && heartbeatMinutes !== null && heartbeatMinutes !== undefined && heartbeatMinutes !== '') {
+      throw new RelayEventError('invalid', 'heartbeat_minutes needs sessions to watch; relay_restarted alone has none.');
+    }
     if (ids.length > RELAY_EVENT_LIMITS.sessionsMax) {
       throw new RelayEventError('invalid', `subscribe takes at most ${RELAY_EVENT_LIMITS.sessionsMax} sessions; use "all" for more.`);
     }
@@ -504,9 +565,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 !== ''
@@ -538,7 +603,7 @@ export function createRelayEventService({
     if (!available) throw new RelayEventError('unavailable', 'Event subscriptions are not available on this relay right now (its storage is missing; see the server log).');
     const watcher = toText(watcherConversationId);
     if (!isLive(conversation(watcher))) throw new RelayEventError('notFound', 'The watching conversation was not found or is archived.');
-    const prepared = prepareSubscription({ scope, sessionIds, events, match, stalledMinutes, heartbeatMinutes, exclude: watcher });
+    const prepared = prepareSubscription({ scope, sessionIds, events, match, stalledMinutes, heartbeatMinutes, exclude: watcher, relayLevel: true });
     const { all, ids, types } = prepared;
     checkWatcherCapacity(watcher);
     const id = `sub_${randomBytes(5).toString('hex')}`;
@@ -560,7 +625,8 @@ export function createRelayEventService({
     // The watched set starts from what it is doing now: all_idle fires when
     // work that is running now (or starts later) has ended.
     noteBusy(sql.getSubscription.get(id));
-    log(`conv=${shortId(watcher)} subscribed ${id} to ${all ? 'all sessions' : `${ids.length} session${ids.length === 1 ? '' : 's'}`} (${types.join(',')})${once ? ' once' : ''}`);
+    const what = all ? 'all sessions' : (ids.length ? `${ids.length} session${ids.length === 1 ? '' : 's'}` : 'this relay');
+    log(`conv=${shortId(watcher)} subscribed ${id} to ${what} (${types.join(',')})${once ? ' once' : ''}`);
     broadcast();
     return subscription;
   }
@@ -771,8 +837,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 +874,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 +1338,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(
@@ -1599,6 +1666,131 @@ export function createRelayEventService({
     return ended;
   }
 
+  // ─── The relay's own start: relay_restarted ────────────────────────────────
+
+  /** Conversations whose running turn answers a relay_restarted event. */
+  function restartWokenConversations() {
+    if (!available) return [];
+    try {
+      return sql.listRestartWokenRunning.all(RELAY_EVENT_RELAY_RESTARTED_TYPE).map((row) => toText(row.conversation_id)).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * A restart or shutdown was requested: a conversation whose turn answers
+   * relay_restarted right now is not woken by it (the request may be that
+   * turn's). Called on every request while one is queued; returns them.
+   */
+  function noteRestartRequested() {
+    const woken = restartWokenConversations();
+    for (const id of woken) restartNoWake.add(id);
+    if (woken.length) log(`restart requested while ${woken.map(shortId).join(', ')} answer${woken.length === 1 ? 's' : ''} relay_restarted: not woken by it`);
+    return [...restartNoWake];
+  }
+
+  /** The queued request was withdrawn (or never queued): nothing is held back. */
+  function noteRestartCancelled() {
+    restartNoWake.clear();
+  }
+
+  /**
+   * This runtime ends cleanly: how, for the next start to tell. The first
+   * call wins (a queued request's details before the generic exit's); none
+   * before noteRelayStarted. `requestedAt` set means the end was a queued (or immediate) request.
+   */
+  function noteRelayExit({ action = 'shutdown', reason = '', requestedBy = null, requestedAt = null } = {}) {
+    // A runtime stopped before it listened (and took the record) leaves the
+    // record of the run before it for the next start.
+    if (!exitSql || exitNoted || !startNoted) return false;
+    exitNoted = true;
+    const requested = !!toText(requestedAt);
+    // The runtime's own reasons may carry a process id (`owner-pid-missing:<pid>`):
+    // not for an agent's eyes.
+    const ownReason = requested ? toText(reason) : toText(reason).replace(/:\d+\b/g, '');
+    const record = {
+      v: 1,
+      requested,
+      action: action === 'restart' ? 'restart' : 'shutdown',
+      reason: ownReason.slice(0, 140) || null,
+      requestedBy: toText(requestedBy).slice(0, 80) || null,
+      requestedAt: toText(requestedAt) || null,
+      stoppedAt: isoNow(),
+      noWake: [...restartNoWake],
+    };
+    try {
+      exitSql.put.run(RELAY_LAST_EXIT_SETTING_KEY, JSON.stringify(record), record.stoppedAt);
+      return true;
+    } catch (error) {
+      warn(`how this run ended was not stored: ${toText(error?.message || error).slice(0, 200)}`);
+      return false;
+    }
+  }
+
+  function restartedDetail(exit, startedAt) {
+    if (!exit) return { stop: 'unknown', startedAt };
+    const base = { startedAt, stoppedAt: toText(exit.stoppedAt) || null, reason: toText(exit.reason) || null };
+    if (exit.requested !== true) return { stop: 'stopped', ...base };
+    return {
+      stop: 'requested',
+      ...base,
+      action: exit.action === 'shutdown' ? 'shutdown' : 'restart',
+      requestedBy: toText(exit.requestedBy) || null,
+      requestedAt: toText(exit.requestedAt) || null,
+    };
+  }
+
+  /**
+   * The runtime started (it listens). Takes how the run before ended (read
+   * and deleted with the events written, so a start is told once) and gives
+   * every active subscription of this relay's live watchers that names
+   * relay_restarted one event; a `once` one ends with it. Watchers the
+   * restart's request held back (noteRestartRequested) are left out, and
+   * their `once` subscriptions end too (`held-back`): that restart was the
+   * one they were for, and a later one would wake them with a stale "carry
+   * on". A record older than RELAY_LAST_EXIT_MAX_AGE_MS is not the run just
+   * before (an older OAR, which neither writes nor takes it, may have run in
+   * between): it is dropped unread. Once per runtime. Returns `{ recorded,
+   * skipped }`.
+   */
+  function noteRelayStarted() {
+    if (!available || startNoted) return { recorded: 0, skipped: [] };
+    startNoted = true;
+    const startedAt = isoNow();
+    let recorded = 0;
+    let skipped = [];
+    const heldBack = [];
+    db.transaction(() => {
+      let exit = null;
+      if (exitSql) {
+        exit = parseJson(exitSql.get.get(RELAY_LAST_EXIT_SETTING_KEY)?.value, null);
+        exitSql.take.run(RELAY_LAST_EXIT_SETTING_KEY);
+        const stoppedAt = Date.parse(String(exit?.stoppedAt || ''));
+        if (exit && !(Number.isFinite(stoppedAt) && now() - stoppedAt <= RELAY_LAST_EXIT_MAX_AGE_MS)) exit = null;
+      }
+      const noWake = new Set((Array.isArray(exit?.noWake) ? exit.noWake : []).map(toText));
+      const rows = activeRows().filter((row) => !isMirror(row)
+        && !isServedKey(row.watcher_conversation_id)
+        && wants(row, { type: RELAY_EVENT_RELAY_RESTARTED_TYPE })
+        && isLive(conversation(row.watcher_conversation_id)));
+      const held = rows.filter((row) => noWake.has(row.watcher_conversation_id));
+      skipped = [...new Set(held.map((row) => row.watcher_conversation_id))];
+      for (const row of held) {
+        if (Number(row.once || 0) === 1 && endSubscription(row.id, 'held-back')) heldBack.push(row.id);
+      }
+      const woken = rows.filter((row) => !noWake.has(row.watcher_conversation_id));
+      if (!woken.length) return;
+      recorded = enqueueForRows(woken, buildEvent(RELAY_EVENT_RELAY_RESTARTED_TYPE, '', restartedDetail(exit, startedAt)), '');
+    })();
+    if (recorded || skipped.length) {
+      log(`relay started: ${recorded} watcher${recorded === 1 ? '' : 's'} told${skipped.length ? `; not woken (answering relay_restarted when this restart was requested): ${skipped.map(shortId).join(', ')}` : ''}`
+        + `${heldBack.length ? `; one-shot ${heldBack.join(', ')} ended (held-back)` : ''}`);
+    }
+    if (heldBack.length) broadcast();
+    return { recorded, skipped };
+  }
+
   // ─── Hooks ─────────────────────────────────────────────────────────────────
 
   function isRelayEventTurn(queueMessageId) {
@@ -1814,7 +2006,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 +2024,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);
@@ -1944,6 +2136,10 @@ export function createRelayEventService({
     noteQuestion,
     noteTaskEdge,
     noteConversationGone,
+    noteRestartRequested,
+    noteRestartCancelled,
+    noteRelayExit,
+    noteRelayStarted,
     afterStateChange,
     sweep,
     start,

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 } : {}) });
+  };
+}