@oar-sh/oar 0.9.13 → 0.9.14

package/server/services/package-data-rescue-preinstall.mjs

@@ -0,0 +1,22 @@
+/**
+ * The `preinstall` of @oar-sh/oar. Nothing of OAR loads before the `try`:
+ * a module of this package that cannot load (a broken file, a missing one)
+ * must not fail the install on any platform. Only a copy of an old
+ * database that failed (RescueCopyError) exits 1, so npm stops the update
+ * and puts the old package, data and all, back in place; anything else is
+ * one line and exit 0, as this script only ever copies. See
+ * package-data-rescue.mjs.
+ */
+import { fileURLToPath } from 'node:url';
+
+try {
+  const { rescuePackageData } = await import('./package-data-rescue.mjs');
+  rescuePackageData({ packageRoot: fileURLToPath(new URL('../..', import.meta.url)) });
+} catch (error) {
+  if (error?.rescueCopyFailed === true) {
+    console.error(`[oar] ${error.message}`);
+    process.exitCode = 1;
+  } else {
+    console.error(`[oar] Did not copy the data of the version being replaced: ${error?.message || error}`);
+  }
+}

package/server/services/package-data-rescue.mjs

@@ -0,0 +1,137 @@
+/**
+ * The preinstall's work (package-data-rescue-preinstall.mjs), on every
+ * platform. Relays before 0.9.14 could run on the database and uploads
+ * inside the package (Windows autostart, a plain `gh copilot`), and
+ * `npm i -g` deletes the old package. While install scripts run, npm keeps
+ * it as its retired folder (npmRetiredPath; a scan for npm-shaped names only
+ * when that is missing): its database (-wal, -shm), Cursor stores, uploads
+ * and config.json are copied, copy only, to
+ * `<data folder>/rescued-package-data/<time>/` (written as `.partial`, then
+ * renamed), and the relay takes them over at its next start. Any of them
+ * makes the old package a source (its uploads beyond the README.md and
+ * image_input.md it ships). Nothing to copy, or not an installed package:
+ * nothing happens, nothing is printed. A failed copy throws
+ * RescueCopyError: exit 1, npm puts the old package back. npm hides a successful script's output, hence the README.txt.
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+import { RESCUE_DIR_NAME, copyMissing, isRetiredName } from './earlier-database-service.mjs';
+import { resolveRelayStateDirs, resolveStateLayout } from './oar-state-layout.mjs';
+
+const DB_FILES = ['copilot.db', 'copilot.db-wal', 'copilot.db-shm'];
+
+// What a relay left in a package's server folder; a folder that cannot be
+// read throws (no copy failure: nothing was detected yet).
+function hasRelayData(fsImpl, serverDir) {
+  const has = (...parts) => fsImpl.existsSync(path.join(serverDir, ...parts));
+  const anyUpload = (...parts) => has(...parts) && fsImpl.readdirSync(path.join(serverDir, ...parts)).some((name) => /^[a-f0-9]{64}$/.test(name));
+  return has('data', 'copilot.db') || has('data', 'cursor-agents') || has('config.json') || anyUpload('uploads') || anyUpload('data', 'uploads');
+}
+
+/** Where npm's reify moves a package it replaces (@npmcli/arborist retire-path.js). */
+export function npmRetiredPath(packageDir) {
+  const hash = crypto.createHash('sha1').update(packageDir).digest('base64').replace(/[^a-zA-Z0-9]+/g, '').slice(0, 8);
+  return path.resolve(path.dirname(packageDir), `.${path.basename(packageDir)}-${hash}`);
+}
+
+/** A copy of an old database failed: the one error that stops the install. */
+export class RescueCopyError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'RescueCopyError';
+    this.rescueCopyFailed = true;
+  }
+}
+
+/**
+ * Returns { status: 'not-installed' | 'nothing' | 'rescued', rescued: [{ from,
+ * to }] }; throws a RescueCopyError, naming what to save, when a copy fails.
+ */
+export function rescuePackageData({
+  packageRoot,
+  env = process.env,
+  platform = process.platform,
+  now = () => new Date(),
+  fsImpl = fs,
+  logger = console,
+} = {}) {
+  const resolvedRoot = path.resolve(String(packageRoot || ''));
+  const scope = path.dirname(resolvedRoot);
+  if (path.basename(scope) !== '@oar-sh' || path.basename(path.dirname(scope)) !== 'node_modules') {
+    return { status: 'not-installed', rescued: [] };
+  }
+  // Detection: npm's retired name, else a scan for npm-shaped names (a path
+  // in another case hashes differently). Failing here is no copy failure.
+  let sources;
+  try {
+    const exact = npmRetiredPath(resolvedRoot);
+    const retired = fsImpl.existsSync(exact)
+      ? [exact]
+      : fsImpl.readdirSync(scope).filter((name) => isRetiredName(name, path.basename(resolvedRoot))).map((name) => path.join(scope, name));
+    sources = retired.filter((dir) => hasRelayData(fsImpl, path.join(dir, 'server')));
+  } catch (error) {
+    throw new Error(`Could not look for the data of the version being replaced: ${error?.message || error}`, { cause: error });
+  }
+  if (!sources.length) return { status: 'nothing', rescued: [] };
+
+  // Old data is there: any failure from here stops the install.
+  const exists = (file) => fsImpl.existsSync(file);
+  const kept = path.join(resolvedRoot, 'server');
+  const copyFailed = (from, to, error) => new RescueCopyError(
+    `Could not copy the data of the version being replaced (${from}) to ${to}: ${error?.message || error}. `
+    + `The update stops and the version installed stays as it is; copy ${path.join(kept, 'data')} and ${path.join(kept, 'uploads')} somewhere safe by hand, then update again.`,
+    { cause: error },
+  );
+  let rescueRoot;
+  try {
+    const layout = resolveStateLayout({ packageRoot: resolvedRoot, env, platform });
+    rescueRoot = path.join(resolveRelayStateDirs({ packageRoot: resolvedRoot, env, platform, layout }).dataDir, RESCUE_DIR_NAME);
+  } catch (error) {
+    throw copyFailed(path.join(sources[0], 'server'), 'the OAR data folder', error);
+  }
+  const stamp = now().toISOString().replace(/[:.]/g, '-');
+  const rescued = [];
+  for (const [index, source] of sources.entries()) {
+    const serverDir = path.join(source, 'server');
+    let target = path.join(rescueRoot, sources.length > 1 ? `${stamp}-${index}` : stamp);
+    // Written under a .partial name and renamed when complete: a half copy
+    // is never taken for a rescue.
+    try {
+      for (let n = 1; exists(target) || exists(`${target}.partial`); n += 1) target = `${path.join(rescueRoot, stamp)}-${n}`;
+      const partial = `${target}.partial`;
+      fsImpl.mkdirSync(rescueRoot, { recursive: true });
+      fsImpl.mkdirSync(partial);
+      fsImpl.mkdirSync(path.join(partial, 'data'));
+      for (const name of DB_FILES) {
+        const from = path.join(serverDir, 'data', name);
+        if (exists(from)) fsImpl.copyFileSync(from, path.join(partial, 'data', name), fs.constants.COPYFILE_EXCL);
+      }
+      if (exists(path.join(serverDir, 'data', 'cursor-agents'))) {
+        copyMissing(fsImpl, path.join(serverDir, 'data', 'cursor-agents'), path.join(partial, 'data', 'cursor-agents'));
+      }
+      // Uploads of server/uploads and server/data/uploads, content-addressed.
+      for (const uploads of [path.join(serverDir, 'uploads'), path.join(serverDir, 'data', 'uploads')]) {
+        if (exists(uploads)) copyMissing(fsImpl, uploads, path.join(partial, 'uploads'));
+      }
+      if (exists(path.join(serverDir, 'config.json'))) {
+        fsImpl.copyFileSync(path.join(serverDir, 'config.json'), path.join(partial, 'config.json'), fs.constants.COPYFILE_EXCL);
+      }
+      fsImpl.writeFileSync(path.join(partial, 'README.txt'), [
+        `Copied by the @oar-sh/oar update on ${now().toISOString()} from`,
+        `${serverDir}`,
+        'before npm deleted the version it replaced. The relay takes the',
+        'database in data\\ over at its next start if it is newer than the',
+        'one it has. Nothing here is deleted by OAR.',
+        '',
+      ].join('\r\n'));
+      fsImpl.renameSync(partial, target);
+    } catch (error) {
+      throw copyFailed(serverDir, target, error);
+    }
+    rescued.push({ from: serverDir, to: target });
+    logger.log?.(`[oar] Copied the data of the version being replaced from ${serverDir} to ${target}; the relay takes it over at its next start.`);
+  }
+  return { status: 'rescued', rescued };
+}

package/server/services/preview-registry-service.mjs

@@ -687,8 +687,9 @@ export function createPreviewRegistry({
       ok: false,
       status: 429,
       error: `Too many live previews (max ${settings.maxLive}); previews stay until closed. `
-        + `Oldest: ${oldest.join('; ')}. Close ${toClose === 1 ? 'one' : toClose} in Settings → Previews, with the preview tool's `
-        + `close action (list shows the tokens), or with DELETE /api/previews/:token.`,
+        + `Oldest: ${oldest.join('; ')}. Close ${toClose === 1 ? 'one' : toClose} in Settings → Previews; an agent can close `
+        + `its own conversation's with the preview tool's close action (list shows their tokens) or with `
+        + `DELETE /api/previews/:token?conversationId=<conv>.`,
     };
   }
 

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

@@ -1,5 +1,7 @@
 'use strict';
 
+import { providerDisplayName } from '../public/app/conversation-provider-indicator.mjs';
+
 /**
  * Web Push dispatch: decides whether a push should go out at all (suppressed
  * while any device is actively foregrounded), renders the notification per
@@ -29,7 +31,8 @@ const FAILURE_PRUNE_THRESHOLD = 8;
 const PUSH_TTL_SECONDS = 12 * 60 * 60;
 
 const EVENT_LABELS = Object.freeze({
-  question: { title: 'Copilot needs your input', generic: 'The agent asked a question.' },
+  // A question's title names the provider that asks (questionTitle).
+  question: { title: 'An agent needs your input', generic: 'The agent asked a question.' },
   turnComplete: { title: 'Turn completed', generic: 'The agent finished its turn.' },
   turnFailed: { title: 'Turn failed', generic: 'The agent turn failed.' },
   board: { title: 'Plan ready for review', generic: 'The agent posted a board for review.' },
@@ -38,6 +41,12 @@ const EVENT_LABELS = Object.freeze({
   relayRestart: { title: 'Relay restart waiting', generic: 'The queued relay restart has waited its maximum time.' },
 });
 
+function eventTitle(type, providerName) {
+  const name = String(providerName || '').trim();
+  if (type === 'question' && name) return `${name} needs your input`;
+  return EVENT_LABELS[type].title;
+}
+
 // 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', 'relayRestart']);
@@ -79,7 +88,7 @@ export function normalizePushPreferences(raw) {
  * Render the notification payload for one subscription. Pure so every content
  * preference combination is unit-testable.
  *
- * @param {{ type: string, conversationTitle?: string|null, body?: string|null, data?: object }} event
+ * @param {{ type: string, conversationTitle?: string|null, providerName?: string|null, body?: string|null, data?: object }} event
  * @param {object} preferences canonical shape from normalizePushPreferences
  */
 export function renderPushNotification(event, preferences) {
@@ -87,10 +96,11 @@ export function renderPushNotification(event, preferences) {
   const prefs = normalizePushPreferences(preferences);
   const labels = EVENT_LABELS[type];
 
-  let title = labels.title;
+  const baseTitle = eventTitle(type, event?.providerName);
+  let title = baseTitle;
   const conversationTitle = String(event?.conversationTitle || '').trim();
   if (prefs.content.includeTitle && conversationTitle) {
-    title = `${labels.title} — ${conversationTitle}`.slice(0, MAX_TITLE_CHARS);
+    title = `${baseTitle} — ${conversationTitle}`.slice(0, MAX_TITLE_CHARS);
   }
 
   let body = labels.generic;
@@ -116,7 +126,7 @@ export function renderPushNotification(event, preferences) {
   return {
     title,
     body,
-    tag: `copilot-${type}-${tagSeed}`,
+    tag: `oar-${type}-${tagSeed}`,
     timestamp: Date.now(),
     data,
   };
@@ -341,6 +351,21 @@ export function createPushDispatchService({
     }
   }
 
+  // The provider of a question's conversation, for the push title. Prepared
+  // lazily: a schema without runtime sessions just means "not known".
+  let providerTypeStatement = null;
+  function conversationProviderName(conversationId) {
+    const id = String(conversationId || '').trim();
+    if (!id) return null;
+    try {
+      providerTypeStatement ??= db.prepare(`SELECT provider_type FROM runtime_sessions WHERE conversation_id = ?`);
+      // Named as the question card's head names it; unknown stays neutral.
+      return providerDisplayName(providerTypeStatement.get(id)?.provider_type) || null;
+    } catch {
+      return null;
+    }
+  }
+
   async function sendToSubscription(row, event) {
     const preferences = normalizePushPreferences(parseJsonObject(row.preferences_json));
     const payload = renderPushNotification(event, preferences);
@@ -384,7 +409,7 @@ export function createPushDispatchService({
    * Fire-and-forget push for one event. Never throws; suppression failures
    * fail closed (no push when the active-device state is unknown).
    */
-  async function dispatch({ type, conversationId = null, body = null, data = {} }) {
+  async function dispatch({ type, conversationId = null, body = null, data = {}, providerName = null }) {
     try {
       if (!PUSH_EVENT_TYPES.includes(type)) return { outcome: 'invalid-type' };
 
@@ -410,6 +435,7 @@ export function createPushDispatchService({
       const event = {
         type,
         conversationTitle: conversationTitle(conversationId),
+        providerName,
         body,
         data: { ...data, conversationId: conversationId || undefined },
       };
@@ -445,6 +471,7 @@ export function createPushDispatchService({
     return dispatch({
       type: 'question',
       conversationId: question?.conversationId || null,
+      providerName: conversationProviderName(question?.conversationId),
       body: question?.prompt || null,
       data: {
         questionId: question?.id || undefined,

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,6 +64,8 @@ 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,
@@ -66,6 +75,7 @@ import {
   effectiveRelayEventTypes,
   isLegacyDefaultRelayEventTypes,
   isRelayEventType,
+  isRelayLevelOnly,
   isUrgentRelayEventType,
   relayEventMatchText,
   relayEventTypesTake,
@@ -77,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;
@@ -291,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
@@ -381,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();
@@ -500,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.`);
     }
@@ -555,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')}`;
@@ -577,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;
   }
@@ -1617,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) {
@@ -1962,6 +2136,10 @@ export function createRelayEventService({
     noteQuestion,
     noteTaskEdge,
     noteConversationGone,
+    noteRestartRequested,
+    noteRestartCancelled,
+    noteRelayExit,
+    noteRelayStarted,
     afterStateChange,
     sweep,
     start,

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

@@ -93,8 +93,8 @@ export function createRelayRestartQueue({
   // ({ action }) => { waitingFor, held, backgroundTasks, survival }; see
   // relay-restart-picture.mjs. Optional: without it the state names nothing.
   collectPicture = null,
-  // ({ action, reason, requestedBy, immediate, counts }) => void: exits the
-  // runtime. Called at most once per request.
+  // ({ action, reason, requestedBy, requestedAt, immediate, counts }) => void:
+  // exits the runtime. Called at most once per request.
   startShutdown,
   // () => the maximum wait in ms, 0 for no limit.
   getMaxWaitMs = () => DEFAULT_RELAY_RESTART_MAX_WAIT_MINUTES * 60_000,
@@ -231,7 +231,14 @@ export function createRelayRestartQueue({
       );
     }
     try {
-      startShutdown({ action, reason: info?.reason || 'manual-request', requestedBy: info?.requestedBy || 'unknown', immediate, counts: queue });
+      startShutdown({
+        action,
+        reason: info?.reason || 'manual-request',
+        requestedBy: info?.requestedBy || 'unknown',
+        requestedAt: iso(info?.requestedAt),
+        immediate,
+        counts: queue,
+      });
     } catch (error) {
       log(`Relay ${action} failed to start: ${error?.message || error}`);
     }