@oar-sh/oar 0.9.11 → 0.9.13

package/server/services/restart-resume-service.mjs

@@ -0,0 +1,303 @@
+'use strict';
+
+/**
+ * "After a relay restart, tell interrupted sessions to carry on" (opt-in,
+ * per relay, off by default).
+ *
+ * Session workers outlive the relay's runtime, and a turn whose worker lived
+ * through the restart simply goes on. A turn whose worker did not (it died
+ * with the relay, or came back without the turn) is dealt with by the
+ * recovery paths, and most of them requeue it: the row runs again by itself,
+ * and nothing more is needed. A few cannot run again, because the prompt
+ * already reached the agent and a second delivery would run it twice:
+ *
+ *  - a background continuation (a turn the agent opened itself), torn down;
+ *  - a steer the CLI had already taken (`consumed_at`), failed;
+ *  - a turn that had started (activity, a stream) when its live worker no
+ *    longer claimed it, failed instead of replayed (`turn-replay-blocked`).
+ *
+ * The agent never hears that its turn stopped. With the setting on, such a
+ * session gets ONE note of the relay's in the conversation once its rows are
+ * settled: the relay restarted, the turn was interrupted, check what you
+ * were doing and carry on. The user's message is never sent again.
+ *
+ * Which turns count: the rows that were `processing` when this runtime
+ * started (`captureBoot`), followed through the recovery paths
+ * (`noteOutcome`). A row its worker claims after the start (a heartbeat
+ * that lists it: the worker lived through the restart and has the turn) is
+ * the restart's no more: whatever ends it later is not put down to it.
+ * A conversation gets a note when one of its rows was cut off and none was
+ * requeued (that one runs again: a note would double the work), claimed by
+ * a worker that lived through the restart, or failed for another reason.
+ * Nothing for idle sessions, nothing when
+ * the setting is off when the note would be sent, nothing for an archived or
+ * deleted conversation, nothing while a usage-limit follow-up is held (it
+ * carries the turn on itself), at most one note per conversation and
+ * runtime. The note is an ordinary pending row, queued behind whatever the
+ * user has queued already, so it never jumps ahead of a user message; its
+ * delivery starts the session's worker as for any message.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+export const RESTART_RESUME_SETTING_KEY = 'restart_resume_notes';
+export const RESTART_RESUME_KIND = 'relay-restart-resume';
+export const RESTART_RESUME_LEAD = 'Automatic message from OAR, not from the user:';
+
+// How long after the start a cut-off turn is still put down to the restart.
+const DEFAULT_WINDOW_MS = 30 * 60_000;
+
+/** The stored value as on or off; off unless it was switched on. */
+export function readRestartResumeSetting(raw) {
+  return ['1', 'true', 'on'].includes(String(raw ?? '').trim().toLowerCase());
+}
+
+export function parseRestartResumeUpdate(value) {
+  if (typeof value !== 'boolean') return { ok: false, error: 'enabled must be true or false' };
+  return { ok: true, enabled: value };
+}
+
+function defaultFormatTime(ms) {
+  const at = new Date(Number(ms));
+  if (!Number.isFinite(at.getTime())) return 'just now';
+  return `${at.toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+
+/** The note's text. */
+export function buildRestartResumeNoteText({ restartedAt, formatTime = defaultFormatTime } = {}) {
+  return `${RESTART_RESUME_LEAD} the relay restarted at ${formatTime(restartedAt)}, and the turn you were working on was interrupted before it finished. `
+    + 'Check where you were (the files you changed, the commands and background tasks you started) and carry on from there. '
+    + 'Do not repeat steps that already completed; if the work was already done, say so briefly.';
+}
+
+const OUTCOMES = new Set(['cut', 'requeued', 'failed', 'claimed']);
+
+function text(value) {
+  return String(value ?? '').trim();
+}
+
+export function createRestartResumeService({
+  db,
+  stmts,
+  isEnabled = () => false,
+  emit = () => {},
+  wake = () => {},
+  now = () => Date.now(),
+  bootAt = now(),
+  windowMs = DEFAULT_WINDOW_MS,
+  formatTime = defaultFormatTime,
+  logger = console,
+} = {}) {
+  if (!db || !stmts) throw new Error('createRestartResumeService requires db and stmts');
+  const listProcessing = db.prepare(`
+    SELECT id, conversation_id, model, model_variant_id, reasoning_effort, context_tier, relay_mode,
+           owner_sdk_session_id, runtime_session_id
+    FROM queue WHERE status = 'processing'
+  `);
+  const statusOf = db.prepare(`SELECT status FROM queue WHERE id = ?`);
+  let heldPause = null;
+  try {
+    // A held usage-limit follow-up (usage-limit-pause-service.mjs).
+    heldPause = db.prepare(`
+      SELECT 1 FROM queue
+      WHERE conversation_id = ? AND status = 'pending' AND usage_limit_pause IS NOT NULL
+      LIMIT 1
+    `);
+  } catch {}
+
+  // queue id → conversation id, for the rows processing at the start.
+  const watched = new Map();
+  // conversation id → { rows: Map(queue id → { row, outcome }) }
+  const conversations = new Map();
+  // Conversations that had their note in this runtime.
+  const noted = new Set();
+
+  function log(line) {
+    try { logger?.log?.(`[restart-resume] ${line}`); } catch {}
+  }
+
+  function expired() {
+    return now() - bootAt > windowMs;
+  }
+
+  /** The rows processing when this runtime started; returns how many. */
+  function captureBoot() {
+    let rows = [];
+    try { rows = listProcessing.all(); } catch {}
+    for (const row of rows) {
+      const conversationId = text(row.conversation_id);
+      const id = text(row.id);
+      if (!conversationId || !id) continue;
+      watched.set(id, conversationId);
+      let entry = conversations.get(conversationId);
+      if (!entry) conversations.set(conversationId, entry = { rows: new Map() });
+      entry.rows.set(id, { row, outcome: null });
+    }
+    if (rows.length) log(`${rows.length} turn(s) were running when the relay started; following them`);
+    return rows.length;
+  }
+
+  /**
+   * What a recovery path did with a row: `cut` (it cannot run again),
+   * `requeued` (it runs again by itself) or `failed` (ended for another
+   * reason); or `claimed`: its worker, alive after the restart, holds it.
+   * Only the rows of the start count, and only their first outcome.
+   */
+  function noteOutcome(row, outcome) {
+    const id = text(row?.id ?? row);
+    const conversationId = watched.get(id);
+    if (!conversationId || !OUTCOMES.has(outcome)) return false;
+    watched.delete(id);
+    const entry = conversations.get(conversationId)?.rows.get(id);
+    if (entry && !entry.outcome) entry.outcome = outcome;
+    settle(conversationId);
+    return true;
+  }
+
+  // Decides a conversation once none of its rows of the start is processing.
+  function settle(conversationId) {
+    const entry = conversations.get(conversationId);
+    if (!entry) return;
+    for (const [id, item] of entry.rows) {
+      if (item.outcome) continue;
+      let status = '';
+      try { status = text(statusOf.get(id)?.status).toLowerCase(); } catch {}
+      if (status === 'processing') return;
+      // Back in the queue by a path that did not say so: it runs again.
+      item.outcome = status === 'pending' || status === 'parked' ? 'requeued' : 'settled';
+      watched.delete(id);
+    }
+    conversations.delete(conversationId);
+    const outcomes = [...entry.rows.values()].map((item) => item.outcome);
+    if (!outcomes.includes('cut')) return;
+    if (outcomes.includes('requeued')) {
+      log(`conv=${conversationId.slice(0, 8)} no note: the interrupted turn runs again by itself`);
+      return;
+    }
+    if (outcomes.includes('claimed')) {
+      log(`conv=${conversationId.slice(0, 8)} no note: its worker lived through the restart and has its turn`);
+      return;
+    }
+    if (outcomes.includes('failed')) {
+      log(`conv=${conversationId.slice(0, 8)} no note: the turn failed, the failure says what to do`);
+      return;
+    }
+    const cut = [...entry.rows.values()].find((item) => item.outcome === 'cut')?.row || null;
+    sendNote(conversationId, cut);
+  }
+
+  function skip(conversationId, why) {
+    log(`conv=${conversationId.slice(0, 8)} no note: ${why}`);
+    return null;
+  }
+
+  function sendNote(conversationId, cutRow) {
+    if (noted.has(conversationId)) return skip(conversationId, 'it had one after this restart');
+    let enabled = false;
+    try { enabled = isEnabled() === true; } catch {}
+    if (!enabled) return skip(conversationId, 'the setting is off');
+    const conversation = stmts.getConvAnyStatus?.get?.(conversationId) || null;
+    if (!conversation || text(conversation.status) === 'deleted') return skip(conversationId, 'the conversation is gone');
+    if (Number(conversation.archived) === 1) return skip(conversationId, 'the conversation is archived');
+    try {
+      if (heldPause?.get(conversationId)) return skip(conversationId, 'a usage-limit follow-up carries the turn on');
+    } catch {}
+    noted.add(conversationId);
+
+    const at = new Date(now()).toISOString();
+    const messageId = randomUUID();
+    const noteText = buildRestartResumeNoteText({ restartedAt: bootAt, formatTime });
+    const runtimeSession = stmts.getRuntimeSessionByConversation?.get?.(conversationId) || null;
+    const latestModel = stmts.getLatestConversationModel?.get?.(conversationId)?.model || null;
+    // The model and mode the interrupted turn ran with.
+    const model = text(cutRow?.model) || text(latestModel) || text(runtimeSession?.provider_model) || text(runtimeSession?.model) || null;
+    const modelVariant = text(cutRow?.model_variant_id) || model;
+    const relayMode = text(cutRow?.relay_mode) || 'agent';
+    const owner = text(cutRow?.owner_sdk_session_id) || text(runtimeSession?.sdk_session_id) || null;
+    const write = db.transaction(() => {
+      stmts.insertMsg.run(
+        messageId,
+        conversationId,
+        'user',
+        noteText,
+        modelVariant || null,
+        relayMode,
+        null,
+        at,
+        modelVariant || null,
+        null,
+        text(modelVariant).toLowerCase() === 'auto' ? 'auto' : 'manual',
+      );
+      stmts.setMessageKind?.run?.(RESTART_RESUME_KIND, messageId);
+      stmts.updateConvTime?.run?.(at, conversationId);
+      const queueArgs = [
+        messageId,
+        conversationId,
+        text(cutRow?.runtime_session_id) || runtimeSession?.id || null,
+        0,
+        model,
+        modelVariant || null,
+        text(cutRow?.reasoning_effort) || null,
+        text(cutRow?.context_tier) || null,
+        relayMode,
+        noteText,
+        null,
+        at,
+        owner,
+        owner ? at : null,
+        null,
+        null,
+      ];
+      if (stmts.queueHasImageOperationId || stmts.insertQ?.source?.includes?.('image_operation_id')) queueArgs.push(null);
+      stmts.insertQ.run(...queueArgs);
+    });
+    try {
+      write();
+    } catch (error) {
+      noted.delete(conversationId);
+      try { logger?.warn?.(`[restart-resume] conv=${conversationId.slice(0, 8)} note not queued: ${error?.message || error}`); } catch {}
+      return null;
+    }
+    try {
+      emit('user_message', {
+        conversationId,
+        messageId,
+        senderClientId: null,
+        message: {
+          role: 'user',
+          text: noteText,
+          model: modelVariant || null,
+          mode: relayMode,
+          attachments: [],
+          timestamp: at,
+          kind: RESTART_RESUME_KIND,
+        },
+      });
+    } catch {}
+    try { emit('message_status', { messageId, conversationId, status: 'pending' }); } catch {}
+    try { wake({ conversationId, ownerSessionId: owner, messageId }); } catch {}
+    log(`conv=${conversationId.slice(0, 8)} note queued: its turn was cut off by the restart`);
+    return messageId;
+  }
+
+  /** Decides the conversations whose rows settled on their own; ends the watch after the window. */
+  function tick() {
+    if (!conversations.size) return;
+    if (expired()) {
+      watched.clear();
+      conversations.clear();
+      return;
+    }
+    for (const conversationId of [...conversations.keys()]) settle(conversationId);
+  }
+
+  return {
+    captureBoot,
+    noteOutcome,
+    tick,
+    /** What is still followed, for tests and diagnostics. */
+    pending() {
+      return [...conversations.keys()];
+    },
+  };
+}

package/server/services/session-activity-tracker.mjs

@@ -249,7 +249,9 @@ export function createSessionActivityTracker({
     };
   }
 
-  function finishTask(conversationId, task, { status, summary = null, exitCode = null, reported = true, absent = false } = {}) {
+  // `replaceSummary`: the end as the worker reported it, whose summary (or
+  // none) replaces the live row's, which was a progress line.
+  function finishTask(conversationId, task, { status, summary = null, exitCode = null, reported = true, absent = false, replaceSummary = false } = {}) {
     if (task.graceTimer) {
       clearTimer(task.graceTimer);
       task.graceTimer = null;
@@ -260,6 +262,7 @@ export function createSessionActivityTracker({
     task.status = normalizeTaskStatus(status || 'completed');
     task.statusReported = reported;
     if (summary) task.summary = toText(summary).slice(0, 500);
+    else if (replaceSummary) task.summary = null;
     const code = Number.isInteger(exitCode) ? exitCode : exitCodeFromSummary(task.summary);
     task.exitCode = code;
     task.endedAtMs = now();
@@ -406,6 +409,7 @@ export function createSessionActivityTracker({
       status: normalizeTaskStatus(status || 'completed'),
       summary: toText(summary) || null,
       exitCode: Number.isInteger(exitCode) ? exitCode : null,
+      replaceSummary: true,
     };
     entry.lastActivityAt = now();
     if (!task && key && endedByAbsence.delete(`${id}:${key}`)) {
@@ -416,7 +420,7 @@ export function createSessionActivityTracker({
       if (ended) {
         ended.status = settled.status;
         ended.statusReported = true;
-        if (settled.summary) ended.summary = settled.summary.slice(0, 500);
+        ended.summary = settled.summary ? settled.summary.slice(0, 500) : null;
         ended.exitCode = settled.exitCode ?? exitCodeFromSummary(ended.summary);
       }
       return;

package/server/services/session-worker-process-service.mjs

@@ -296,6 +296,8 @@ export function createSessionWorkerProcessInspector({
   platform = process.platform,
   execFileSyncImpl = execFileSync,
   execFileImpl = execFile,
+  // Where Windows keeps PowerShell (the bare name when it is not there).
+  systemToolPath = windowsSystemToolPath,
   now = () => Date.now(),
   snapshotCacheMs = SNAPSHOT_CACHE_MS,
   slowReadMs = SLOW_READ_MS,
@@ -320,7 +322,7 @@ export function createSessionWorkerProcessInspector({
 
   function getWindowsProcessSnapshot() {
     if (platform !== 'win32') return [];
-    const output = execFileSyncImpl(windowsSystemToolPath('powershell.exe'), ['-NoProfile', '-Command', WINDOWS_PROCESS_SNAPSHOT_SCRIPT], {
+    const output = execFileSyncImpl(systemToolPath('powershell.exe'), ['-NoProfile', '-Command', WINDOWS_PROCESS_SNAPSHOT_SCRIPT], {
       // stderr is kept (not shown): a failed read reports it.
       stdio: ['ignore', 'pipe', 'pipe'],
       windowsHide: true,
@@ -376,7 +378,7 @@ export function createSessionWorkerProcessInspector({
     if (platform !== 'win32') return Promise.resolve([]);
     return new Promise((resolve, reject) => {
       execFileImpl(
-        windowsSystemToolPath('powershell.exe'),
+        systemToolPath('powershell.exe'),
         ['-NoProfile', '-Command', WINDOWS_PROCESS_SNAPSHOT_SCRIPT],
         { windowsHide: true, timeout: WINDOWS_PROCESS_SNAPSHOT_TIMEOUT_MS, maxBuffer: WINDOWS_PROCESS_SNAPSHOT_MAX_BUFFER },
         (error, stdout, stderr) => {
@@ -545,7 +547,7 @@ export function createSessionWorkerProcessInspector({
   function stopWindowsPids(pids) {
     const ids = uniquePids(pids);
     if (!ids.length) return [];
-    execFileSyncImpl(windowsSystemToolPath('powershell.exe'), ['-NoProfile', '-Command', buildStopWindowsPidsScript(ids)], {
+    execFileSyncImpl(systemToolPath('powershell.exe'), ['-NoProfile', '-Command', buildStopWindowsPidsScript(ids)], {
       stdio: ['ignore', 'ignore', 'ignore'],
     });
     return ids;
@@ -557,7 +559,7 @@ export function createSessionWorkerProcessInspector({
     if (!ids.length) return Promise.resolve([]);
     return new Promise((resolve, reject) => {
       execFileImpl(
-        windowsSystemToolPath('powershell.exe'),
+        systemToolPath('powershell.exe'),
         ['-NoProfile', '-Command', buildStopWindowsPidsScript(ids)],
         { windowsHide: true, timeout: WINDOWS_STOP_TIMEOUT_MS, maxBuffer: WINDOWS_PROCESS_SNAPSHOT_MAX_BUFFER },
         (error) => {

package/server/services/task-output-rooms.mjs

@@ -0,0 +1,259 @@
+'use strict';
+
+// Who receives a background task's output live: the pages whose console
+// shows that task. The console joins with `task_output_watch { conversationId,
+// taskId, offset }` (on open and after every reconnect) and leaves with
+// `task_output_unwatch`; a socket is in at most one task room. While a room
+// has members the relay stats the task's file every second and sends what
+// was appended as `task_output_chunk { conversationId, taskId, offset,
+// endOffset, text, size, mtime, ended }` (at most 64 KB per emit, cleaned like
+// every other read). A page whose next expected offset is not `offset`
+// fetches the tail again; a file that shrank is sent as an empty chunk with
+// `reset: true`. Nobody watching costs nothing: the room's poller stops when
+// it empties.
+
+import { TASK_OUTPUT_LIMITS } from '../../shared/task-output-text.mjs';
+import { inspectOutputFile, readRange, taskOutputSource } from './task-output-service.mjs';
+
+const ROOM_PREFIX = 'task-output:';
+// Chunks one tick may send for a fast writer (4 × 64 KB a second).
+const MAX_CHUNKS_PER_TICK = 4;
+// A watcher whose offset is this far behind the room is caught up by itself;
+// further back, it fetches the tail.
+const CATCH_UP_BYTES = 256 * 1024;
+
+export function taskOutputRoom(conversationId, taskId) {
+  return `${ROOM_PREFIX}${String(conversationId || '')}:${String(taskId || '')}`;
+}
+
+function safeAck(ack, payload) {
+  if (typeof ack !== 'function') return;
+  try { ack(payload); } catch {}
+}
+
+function idOf(value) {
+  const text = String(value ?? '').trim();
+  return text && text.length <= 200 && !/[\s\0]/.test(text) ? text : '';
+}
+
+/**
+ * `resolveTask(conversationId, taskId)` returns `{ task, ended, key }` for a
+ * task in the conversation's live or ended set, or null: the same access
+ * check as the output route. Sockets reaching `registerSocket` are already
+ * authenticated.
+ */
+export function createTaskOutputRooms({
+  io,
+  resolveTask,
+  intervalMs = 1000,
+  chunkBytes = TASK_OUTPUT_LIMITS.chunkBytes,
+  roomSize = (room) => io?.sockets?.adapter?.rooms?.get?.(room)?.size || 0,
+  readChunk = readRange,
+  inspect = inspectOutputFile,
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+  logger = console,
+} = {}) {
+  if (typeof resolveTask !== 'function') throw new Error('createTaskOutputRooms requires resolveTask');
+  // room → { conversationId, taskId, path, offset, timer, busy }
+  const watched = new Map();
+
+  function stopRoom(room) {
+    const entry = watched.get(room);
+    if (!entry) return;
+    if (entry.timer) clearIntervalImpl(entry.timer);
+    watched.delete(room);
+  }
+
+  function leave(socket) {
+    const current = socket.data?.taskOutputRoom;
+    if (current) socket.leave(current);
+    if (socket.data) socket.data.taskOutputRoom = null;
+    if (current && roomSize(current) === 0) stopRoom(current);
+  }
+
+  function lookup(conversationId, taskId) {
+    try {
+      return resolveTask(conversationId, taskId);
+    } catch {
+      return undefined;
+    }
+  }
+
+  // Where a room may start in a file of `size` bytes: after the last line
+  // break of its last 64 KB (never inside a character, an escape or a line
+  // whose credentials would be scrubbed in two halves), 0 when there is none
+  // in a shorter file.
+  async function safeOffset(path, size) {
+    if (!(size > 0)) return 0;
+    const start = Math.max(0, size - chunkBytes);
+    try {
+      const probe = await readChunk(path, { start, maxBytes: size - start, holdOpenLine: true, longLineBytes: chunkBytes });
+      return probe?.ok && Number.isInteger(probe.endOffset) ? probe.endOffset : size;
+    } catch {
+      return size;
+    }
+  }
+
+  // `flush`: send the open last line too (the writer is idle, the task ended,
+  // or the bytes were already sent to the room).
+  async function sendRange(target, entry, start, end, ended, { flush = true } = {}) {
+    let offset = start;
+    for (let sent = 0; sent < MAX_CHUNKS_PER_TICK && offset < end; sent += 1) {
+      const chunk = await readChunk(entry.path, {
+        start: offset,
+        maxBytes: Math.min(chunkBytes, end - offset),
+        holdOpenLine: !flush,
+        longLineBytes: chunkBytes,
+      });
+      if (!chunk.ok || chunk.endOffset <= offset) break;
+      target.emit('task_output_chunk', {
+        conversationId: entry.conversationId,
+        taskId: entry.taskId,
+        offset: chunk.offset,
+        endOffset: chunk.endOffset,
+        text: chunk.text,
+        size: chunk.size,
+        mtime: chunk.mtime,
+        ended,
+      });
+      offset = chunk.endOffset;
+    }
+    return offset;
+  }
+
+  async function poll(room) {
+    const entry = watched.get(room);
+    if (!entry || entry.busy) return;
+    if (roomSize(room) === 0) {
+      stopRoom(room);
+      return;
+    }
+    entry.busy = true;
+    try {
+      const found = lookup(entry.conversationId, entry.taskId);
+      // The task left both sets (an hour after its end): nothing more comes.
+      if (found === null) {
+        stopRoom(room);
+        return;
+      }
+      const ended = !!found?.ended;
+      const info = await inspect(entry.path);
+      // Not there (yet, or any more): keep waiting.
+      if (!info.ok) return;
+      const target = io.to(room);
+      // Unchanged since the last tick: the writer is idle, an open line goes out.
+      const idle = info.size === entry.lastSize;
+      entry.lastSize = info.size;
+      if (info.size < entry.offset) {
+        entry.offset = await safeOffset(entry.path, info.size);
+        target.emit('task_output_chunk', {
+          conversationId: entry.conversationId,
+          taskId: entry.taskId,
+          offset: entry.offset,
+          endOffset: entry.offset,
+          text: '',
+          size: info.size,
+          mtime: info.mtimeMs,
+          ended,
+          reset: true,
+        });
+        return;
+      }
+      if (info.size > entry.offset) {
+        entry.offset = await sendRange(target, entry, entry.offset, info.size, ended, { flush: idle || ended });
+      }
+    } catch (error) {
+      logger?.warn?.(`[task-output] live read failed for task ${String(entry.taskId).slice(0, 12)}: ${error?.message || error}`);
+    } finally {
+      const still = watched.get(room);
+      if (still) still.busy = false;
+    }
+  }
+
+  async function watch(socket, payload) {
+    const conversationId = idOf(payload?.conversationId);
+    const taskId = idOf(payload?.taskId);
+    if (!conversationId || !taskId) return { ok: false, code: 'missing-id' };
+    const found = lookup(conversationId, taskId);
+    if (found === undefined) return { ok: false, code: 'unavailable' };
+    if (!found) return { ok: false, code: 'not-found' };
+    const { kind, path } = taskOutputSource(found.task);
+    // A snapshot is fetched again by the console, `none` has nothing.
+    if (!path) return { ok: false, code: kind === 'snapshot' ? 'snapshot' : 'no-output' };
+    let info = await inspect(path);
+    // A file not there yet (a spool is named before its first byte) is
+    // waited for: the room starts at offset 0.
+    if (!info.ok && info.code === 'missing') info = { ok: true, size: 0, mtimeMs: null };
+    if (!info.ok) return { ok: false, code: info.code || 'unreadable' };
+
+    const room = taskOutputRoom(conversationId, taskId);
+    if (socket.data?.taskOutputRoom !== room) {
+      leave(socket);
+      socket.join(room);
+      if (socket.data) socket.data.taskOutputRoom = room;
+    } else if (!socket.rooms?.has?.(room)) {
+      // A recovered socket keeps its data; its rooms may or may not be back.
+      socket.join(room);
+    }
+
+    const requested = Number(payload?.offset);
+    const wanted = Number.isInteger(requested) && requested >= 0 && requested <= info.size ? requested : null;
+    // Where the page's tail ended, so nothing written between its fetch and
+    // this watch is lost; a page far behind (or one that names no offset)
+    // starts at a safe place near the end and fetches the tail up to it.
+    const startOffset = watched.has(room) ? 0
+      : (wanted !== null && info.size - wanted <= CATCH_UP_BYTES ? wanted : await safeOffset(path, info.size));
+    let entry = watched.get(room);
+    if (!entry) {
+      entry = {
+        conversationId,
+        taskId,
+        path,
+        offset: startOffset,
+        lastSize: info.size,
+        timer: null,
+        busy: false,
+      };
+      watched.set(room, entry);
+      entry.timer = setIntervalImpl(() => { poll(room).catch(() => {}); }, intervalMs);
+      entry.timer?.unref?.();
+    } else if (wanted !== null && wanted < entry.offset && entry.offset - wanted <= CATCH_UP_BYTES) {
+      // A second page joins behind the room: it gets the gap on its own.
+      await sendRange(socket, entry, wanted, entry.offset, !!found.ended);
+    }
+    return { ok: true, taskId, offset: entry.offset, size: info.size };
+  }
+
+  function registerSocket(socket) {
+    if (!socket || typeof socket.on !== 'function') return;
+    socket.on('task_output_watch', (payload, ack) => {
+      watch(socket, payload)
+        .then((result) => {
+          // A refused watch leaves no stale room behind: the page shows another task now.
+          if (!result.ok) leave(socket);
+          safeAck(ack, result);
+        })
+        .catch(() => {
+          leave(socket);
+          safeAck(ack, { ok: false, code: 'unavailable' });
+        });
+    });
+    socket.on('task_output_unwatch', (_payload, ack) => {
+      leave(socket);
+      safeAck(ack, { ok: true });
+    });
+    // socket.io takes a closed socket out of its rooms; the poller stops at
+    // its next tick when that emptied the room.
+  }
+
+  return {
+    registerSocket,
+    /** Rooms with a poller, for tests and diagnostics. */
+    watchedRooms: () => [...watched.keys()],
+    poll,
+    stop() {
+      for (const room of [...watched.keys()]) stopRoom(room);
+    },
+  };
+}