@oar-sh/oar 0.9.9 → 0.9.11

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

@@ -79,17 +79,21 @@ export function createStatusEventService(db, {
     for (const [key] of oldest) sharedAccessDedupe.delete(key);
   }
 
+  // `viewerIp` null or empty: the relay does not store viewer addresses, and
+  // the event carries none. `viewerKey` (a hash of address and browser) then
+  // keeps the dedupe per viewer instead of folding every viewer into one.
   function recordSharedAccess({
     shareToken,
     viewerIp,
+    viewerKey = '',
     conversationId,
     timestamp = Date.now(),
   } = {}) {
     const now = normalizeTimestamp(timestamp);
     const token = String(shareToken || '').trim();
-    const ip = String(viewerIp || '').trim() || 'unknown';
+    const ip = String(viewerIp || '').trim();
     const normalizedConversationId = String(conversationId || '').trim();
-    const dedupeKey = `${token}:${ip}`;
+    const dedupeKey = `${token}:${String(viewerKey || '').trim() || ip || 'unknown'}`;
     const previousSeenAt = sharedAccessDedupe.get(dedupeKey);
     if (Number.isFinite(previousSeenAt) && (now - previousSeenAt) <= normalizedDedupeTtlMs) {
       // A dedupe hit slides the window — a persisted event already backs it.
@@ -105,7 +109,7 @@ export function createStatusEventService(db, {
       source: 'server',
       details: {
         shareId: shareIdentifier(token),
-        viewerIp: ip,
+        viewerIp: ip || undefined,
         conversationId: normalizedConversationId || undefined,
       },
     };

package/server/services/subagent-record-retention.mjs

@@ -0,0 +1,164 @@
+'use strict';
+
+// Retention for sub-agent records. After the configured number of days a
+// finished run's tool results lose their text and its tool calls keep only
+// their one-line summary; both keep their row, marked
+// `{ pruned: true, prunedAt, originalChars, retentionDays }` so the viewer
+// can say what happened. Thoughts, reply text, notes, child rows and the
+// runs stay. The sweep runs at relay start and once a day, a few thousand
+// rows per transaction with the event loop free in between, and logs one
+// line. No VACUUM: SQLite reuses the freed pages.
+
+import { subagentToolCallSummary } from '../../shared/subagent-timeline.mjs';
+
+export const SUBAGENT_RETENTION_BATCH_SIZE = 2000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const METADATA_MAX_CHARS = 4096;
+
+function parseMetadata(raw) {
+  if (!raw) return {};
+  try {
+    const value = JSON.parse(raw);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+/** What a stripped entry keeps: text and metadata, from its stored row. */
+export function prunedTimelineEntry(row, { prunedAt, retentionDays }) {
+  const original = String(row?.text ?? '');
+  const text = row?.kind === 'tool_call' ? subagentToolCallSummary(original) : '';
+  const marker = { pruned: true, prunedAt, originalChars: original.length, retentionDays };
+  let metadataJson = JSON.stringify({ ...parseMetadata(row?.metadata_json), ...marker });
+  if (metadataJson.length > METADATA_MAX_CHARS) metadataJson = JSON.stringify(marker);
+  return { text, metadataJson, freedChars: Math.max(0, original.length - text.length) };
+}
+
+function columnExists(db, table, column) {
+  try {
+    return db.prepare(`PRAGMA table_info(${table})`).all().some((entry) => entry.name === column);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `getRetentionDays()` reads the setting (0 = off). `now()` and
+ * `yieldToLoop()` are injectable for tests.
+ */
+export function createSubagentRecordRetention({
+  db,
+  getRetentionDays,
+  now = () => Date.now(),
+  batchSize = SUBAGENT_RETENTION_BATCH_SIZE,
+  yieldToLoop = () => new Promise((resolve) => setImmediate(resolve)),
+  isStopped = () => false,
+  log = (line) => console.log(line),
+  warn = (line) => console.warn(line),
+} = {}) {
+  if (!db) throw new Error('createSubagentRecordRetention requires db');
+  if (typeof getRetentionDays !== 'function') throw new Error('createSubagentRecordRetention requires getRetentionDays');
+
+  let statements = null;
+  let running = null;
+  let scheduled = null;
+
+  function prepare() {
+    if (statements) return statements;
+    if (!columnExists(db, 'subagent_timeline', 'pruned_at')) return null;
+    statements = {
+      // The first condition repeats the partial index's WHERE word for word.
+      // A run still running keeps its whole record, however old.
+      candidates: db.prepare(`
+        SELECT t.id, t.kind, t.text, t.metadata_json
+        FROM subagent_timeline t
+        WHERE t.pruned_at IS NULL AND t.kind IN ('tool_call', 'tool_result')
+          AND t.updated_at < @cutoff
+          AND NOT EXISTS (
+            SELECT 1 FROM subagent_runs r
+            WHERE r.id = t.run_id AND r.status IN ('running', 'pending', 'processing')
+          )
+        ORDER BY t.updated_at
+        LIMIT @limit
+      `),
+      prune: db.prepare(`
+        UPDATE subagent_timeline
+        SET text = @text, metadata_json = @metadataJson, pruned_at = @prunedAt
+        WHERE id = @id AND pruned_at IS NULL
+      `),
+    };
+    return statements;
+  }
+
+  function pruneBatch(cutoff, prunedAt, retentionDays) {
+    const { candidates, prune } = statements;
+    return db.transaction(() => {
+      const rows = candidates.all({ cutoff, limit: batchSize });
+      let pruned = 0;
+      let freedChars = 0;
+      for (const row of rows) {
+        const next = prunedTimelineEntry(row, { prunedAt, retentionDays });
+        pruned += prune.run({ id: row.id, text: next.text, metadataJson: next.metadataJson, prunedAt }).changes;
+        freedChars += next.freedChars;
+      }
+      return { seen: rows.length, pruned, freedChars };
+    })();
+  }
+
+  async function runSweep() {
+    const retentionDays = Number(getRetentionDays()) || 0;
+    if (retentionDays <= 0) return { retentionDays: 0, pruned: 0, freedChars: 0, batches: 0, skipped: 'off' };
+    if (!prepare()) return { retentionDays, pruned: 0, freedChars: 0, batches: 0, skipped: 'unsupported' };
+    const startedAt = now();
+    const cutoff = new Date(startedAt - retentionDays * DAY_MS).toISOString();
+    const prunedAt = new Date(startedAt).toISOString();
+    let pruned = 0;
+    let freedChars = 0;
+    let batches = 0;
+    for (;;) {
+      if (isStopped()) break;
+      const batch = pruneBatch(cutoff, prunedAt, retentionDays);
+      if (!batch.seen) break;
+      batches += 1;
+      pruned += batch.pruned;
+      freedChars += batch.freedChars;
+      if (batch.seen < batchSize) break;
+      await yieldToLoop();
+    }
+    const elapsedMs = Math.max(0, now() - startedAt);
+    log(pruned
+      ? `SUBAGENT RETENTION stripped ${pruned} tool entr${pruned === 1 ? 'y' : 'ies'} (${freedChars} chars) older than ${retentionDays} d in ${batches} batch${batches === 1 ? '' : 'es'}, ${elapsedMs} ms`
+      : `SUBAGENT RETENTION nothing older than ${retentionDays} d to strip`);
+    return { retentionDays, pruned, freedChars, batches, cutoff };
+  }
+
+  /** One sweep at a time; a call while one runs gets that one. */
+  function sweep() {
+    if (running) return running;
+    running = runSweep()
+      .catch((error) => {
+        warn(`SUBAGENT RETENTION sweep failed: ${error?.message || error}`);
+        return { error: String(error?.message || error) };
+      })
+      .finally(() => { running = null; });
+    return running;
+  }
+
+  /** A sweep in `delayMs` (the relay's start, a changed setting); later calls move it. */
+  function scheduleSweep(delayMs = 0) {
+    if (scheduled) clearTimeout(scheduled);
+    scheduled = setTimeout(() => {
+      scheduled = null;
+      if (!isStopped()) void sweep();
+    }, Math.max(0, delayMs));
+    if (typeof scheduled.unref === 'function') scheduled.unref();
+  }
+
+  function stop() {
+    if (scheduled) clearTimeout(scheduled);
+    scheduled = null;
+  }
+
+  return { sweep, scheduleSweep, stop, DAY_MS };
+}

package/server/services/subagent-timeline-service.mjs

@@ -0,0 +1,328 @@
+'use strict';
+
+import {
+  SUBAGENT_TIMELINE_MAX_ENTRIES,
+  SUBAGENT_TIMELINE_TOOL_NAME_MAX_CHARS,
+  cutSubagentTimelineText,
+  isSubagentTimelineKind,
+  normalizeSubagentRunStatus,
+} from '../../shared/subagent-timeline.mjs';
+import { sanitizeSubagentRunId } from '../../shared/subagent-run-id.mjs';
+
+export const TIMELINE_READ_DEFAULT_LIMIT = 500;
+export const TIMELINE_READ_MAX_LIMIT = 2000;
+const ENTRY_KEY_MAX_CHARS = 200;
+const METADATA_MAX_CHARS = 4096;
+const LEGACY_ROW_LIMIT = 2000;
+export const TRUNCATED_NOTE_KEY = 'relay:truncated';
+
+function parseJson(raw) {
+  if (!raw) return null;
+  try {
+    const value = JSON.parse(raw);
+    return value && typeof value === 'object' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function finiteOrNull(value) {
+  const number = Number(value);
+  return value !== null && value !== undefined && value !== '' && Number.isFinite(number) ? number : null;
+}
+
+function cleanText(value, max) {
+  const text = String(value ?? '').trim();
+  return text ? text.slice(0, max) : null;
+}
+
+/** The run as the browser sees it: the row panel, bubble and viewer render. */
+export function mapSubagentRunHeader(row, { stoppable = false, legacy = false } = {}) {
+  const id = String(row?.id || '').trim();
+  if (!id) return null;
+  return {
+    subagentRunId: id,
+    messageId: String(row?.queue_message_id || '').trim() || null,
+    conversationId: String(row?.conversation_id || '').trim() || null,
+    parentSubagentId: row?.parent_subagent_id ? String(row.parent_subagent_id).trim() : null,
+    displayName: row?.display_name ? String(row.display_name).trim() : null,
+    status: String(row?.status || 'running').trim().toLowerCase() || 'running',
+    startedAt: row?.started_at || null,
+    updatedAt: row?.updated_at || null,
+    completedAt: row?.completed_at || null,
+    model: row?.model ? String(row.model) : null,
+    modelInherited: row?.model_inherited === null || row?.model_inherited === undefined ? null : Number(row.model_inherited) === 1,
+    subagentType: row?.subagent_type ? String(row.subagent_type) : null,
+    taskId: row?.task_id ? String(row.task_id) : null,
+    totalTokens: finiteOrNull(row?.total_tokens),
+    background: Number(row?.background || 0) === 1,
+    truncated: Number(row?.truncated || 0) === 1,
+    timelineOwner: row?.timeline_owner ? String(row.timeline_owner) : null,
+    stoppable: !!stoppable,
+    ...(legacy ? { legacy: true } : {}),
+  };
+}
+
+function mapTimelineRow(row) {
+  return {
+    seq: Number(row.seq),
+    kind: String(row.kind),
+    text: row.text === null || row.text === undefined ? '' : String(row.text),
+    toolName: row.tool_name || null,
+    toolUseId: row.tool_use_id || null,
+    metadata: parseJson(row.metadata_json),
+    done: Number(row.done) === 1,
+    createdAt: row.created_at || null,
+    updatedAt: row.updated_at || null,
+  };
+}
+
+/**
+ * One entry as a writer sent it, made safe to store: a known kind, a key, the
+ * text cut to its kind's limit (the original length goes into the metadata),
+ * small metadata only. Null for anything that cannot be stored.
+ */
+export function sanitizeTimelineEntry(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const kind = String(raw.kind || '').trim();
+  if (!isSubagentTimelineKind(kind)) return null;
+  const key = String(raw.key ?? '').trim().slice(0, ENTRY_KEY_MAX_CHARS);
+  if (!key) return null;
+  let metadata = raw.metadata && typeof raw.metadata === 'object' && !Array.isArray(raw.metadata) ? { ...raw.metadata } : null;
+  const priorCut = finiteOrNull(metadata?.cut);
+  const { text, cut } = cutSubagentTimelineText(kind, raw.text, { cut: priorCut });
+  if (cut !== null) metadata = { ...(metadata || {}), cut };
+  let metadataJson = metadata ? JSON.stringify(metadata) : null;
+  if (metadataJson && metadataJson.length > METADATA_MAX_CHARS) metadataJson = cut !== null ? JSON.stringify({ cut }) : null;
+  return {
+    key,
+    kind,
+    text,
+    toolName: cleanText(raw.toolName, SUBAGENT_TIMELINE_TOOL_NAME_MAX_CHARS),
+    toolUseId: sanitizeSubagentRunId(raw.toolUseId) || null,
+    metadataJson,
+    done: raw.done === false ? 0 : 1,
+  };
+}
+
+/** A header patch as a writer sent it. Unknown or empty fields stay null. */
+export function sanitizeRunHeaderPatch(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const totalTokens = finiteOrNull(raw.totalTokens);
+  const patch = {
+    model: cleanText(raw.model, 120),
+    modelInherited: typeof raw.modelInherited === 'boolean' ? (raw.modelInherited ? 1 : 0) : null,
+    subagentType: cleanText(raw.subagentType, 120),
+    taskId: cleanText(raw.taskId, 200),
+    totalTokens: totalTokens === null ? null : Math.max(0, Math.round(totalTokens)),
+    background: raw.background === true ? 1 : null,
+    truncated: raw.truncated === true ? 1 : null,
+    timelineOwner: cleanText(raw.timelineOwner, 40),
+    status: raw.status ? normalizeSubagentRunStatus(raw.status) : null,
+  };
+  return Object.values(patch).some((value) => value !== null) ? patch : null;
+}
+
+export function createSubagentTimelineService({ db, stmts, now = () => new Date().toISOString() } = {}) {
+  const supported = () => !!stmts?.subagentTimelineSupported && typeof stmts?.insertTimelineEntry?.run === 'function';
+  const headerSupported = () => typeof stmts?.updateSubagentRunHeader?.run === 'function';
+
+  /**
+   * Write a header patch onto a run. A status names the run's end (or its
+   * return to running); the end time is stamped once. Returns the updated row,
+   * or null when nothing was written.
+   */
+  function applyHeader(runId, patch) {
+    if (!patch) return null;
+    const at = now();
+    const { status, ...fields } = patch;
+    const hasFields = Object.values(fields).some((value) => value !== null);
+    if (hasFields && headerSupported()) {
+      stmts.updateSubagentRunHeader.run({ id: runId, updatedAt: at, ...fields });
+    }
+    if (status) {
+      const terminal = status === 'completed' || status === 'failed' || status === 'cancelled';
+      stmts.updateSubagentRunStatus?.run?.(status, at, terminal ? at : null, runId);
+    }
+    return stmts.getSubagentRun?.get?.(runId) || null;
+  }
+
+  /**
+   * Store a batch of entries for a run. A known key updates its entry in
+   * place; a new key takes the next seq. Past the per-run limit one note says
+   * the record was cut, the run is marked truncated, and later new entries are
+   * dropped (updates to entries already kept still land). Returns the entries
+   * as stored, for the live event.
+   */
+  function applyEntries(run, rawEntries) {
+    if (!supported() || !run) return { entries: [], truncated: false };
+    const runId = String(run.id);
+    const conversationId = String(run.conversation_id);
+    const queueMessageId = run.queue_message_id ? String(run.queue_message_id) : null;
+    const entries = (Array.isArray(rawEntries) ? rawEntries : []).map(sanitizeTimelineEntry).filter(Boolean);
+    const stored = [];
+    let truncated = false;
+    const tx = db.transaction(() => {
+      let maxSeq = Number(stmts.getMaxTimelineSeq.get(runId)?.max_seq || 0);
+      for (const entry of entries) {
+        const at = now();
+        const existing = stmts.getTimelineEntryByKey.get(runId, entry.key);
+        if (existing) {
+          stmts.updateTimelineEntryByKey.run({
+            runId,
+            entryKey: entry.key,
+            text: entry.text,
+            toolName: entry.toolName,
+            toolUseId: entry.toolUseId,
+            metadataJson: entry.metadataJson,
+            done: entry.done,
+            updatedAt: at,
+          });
+          stored.push(Number(existing.seq));
+          continue;
+        }
+        if (maxSeq >= SUBAGENT_TIMELINE_MAX_ENTRIES) {
+          if (!stmts.getTimelineEntryByKey.get(runId, TRUNCATED_NOTE_KEY)) {
+            maxSeq += 1;
+            stmts.insertTimelineEntry.run({
+              runId,
+              conversationId,
+              queueMessageId,
+              entryKey: TRUNCATED_NOTE_KEY,
+              seq: maxSeq,
+              kind: 'note',
+              text: `The record stops here: a sub-agent keeps at most ${SUBAGENT_TIMELINE_MAX_ENTRIES} entries.`,
+              toolName: null,
+              toolUseId: null,
+              metadataJson: JSON.stringify({ truncated: true }),
+              done: 1,
+              createdAt: at,
+              updatedAt: at,
+            });
+            stmts.setSubagentRunTruncated?.run?.(at, runId);
+            stored.push(maxSeq);
+          }
+          truncated = true;
+          continue;
+        }
+        maxSeq += 1;
+        stmts.insertTimelineEntry.run({
+          runId,
+          conversationId,
+          queueMessageId,
+          entryKey: entry.key,
+          seq: maxSeq,
+          kind: entry.kind,
+          text: entry.text,
+          toolName: entry.toolName,
+          toolUseId: entry.toolUseId,
+          metadataJson: entry.metadataJson,
+          done: entry.done,
+          createdAt: at,
+          updatedAt: at,
+        });
+        stored.push(maxSeq);
+      }
+    });
+    tx.immediate ? tx.immediate() : tx();
+    if (!stored.length) return { entries: [], truncated };
+    const seqs = new Set(stored);
+    const minSeq = Math.min(...stored);
+    const rows = stmts.listTimelineEntries.all({ runId, afterSeq: minSeq - 1, limit: TIMELINE_READ_MAX_LIMIT })
+      .filter((row) => seqs.has(Number(row.seq)));
+    return { entries: rows.map(mapTimelineRow), truncated };
+  }
+
+  /**
+   * A frame Copilot or Cursor published on a sub-agent lane, copied into the
+   * run's timeline (the Claude worker writes its own). The key keeps one entry
+   * per thought and one reply text per run, updated in place.
+   */
+  function mirrorFrame({ runId, kind, key, text, done = true, toolName = null, metadata = null }) {
+    if (!supported()) return null;
+    const run = stmts.getSubagentRun?.get?.(runId) || null;
+    if (!run || String(run.timeline_owner || '') === 'worker') return null;
+    const result = applyEntries(run, [{ key, kind, text, done, toolName, metadata }]);
+    if (!result.entries.length) return null;
+    return { run, entries: result.entries, truncated: result.truncated };
+  }
+
+  function legacyEntries(runId) {
+    const rows = [];
+    for (const row of stmts.listLegacyThoughtsBySubagentRun?.all?.(runId, LEGACY_ROW_LIMIT) || []) {
+      rows.push({ kind: 'thought', text: String(row.text || ''), done: Number(row.done) === 1, createdAt: row.created_at, order: 1 });
+    }
+    for (const row of stmts.listLegacyActivityBySubagentRun?.all?.(runId, LEGACY_ROW_LIMIT) || []) {
+      const text = String(row.text || '');
+      const toolMatch = /^Tool \(([^)]+)\)/.exec(text);
+      rows.push({
+        kind: toolMatch ? 'tool_call' : 'note',
+        text,
+        toolName: toolMatch ? toolMatch[1] : null,
+        done: true,
+        createdAt: row.created_at,
+        order: 2,
+        metadata: { legacy: true },
+      });
+    }
+    for (const row of stmts.listLegacyStreamBySubagentRun?.all?.(runId, LEGACY_ROW_LIMIT) || []) {
+      const text = String(row.text || '');
+      if (!text.trim()) continue;
+      rows.push({ kind: 'text', text, done: Number(row.done) === 1, createdAt: row.created_at, order: 3 });
+    }
+    rows.sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')) || a.order - b.order);
+    return rows.map((row, index) => ({
+      seq: index + 1,
+      kind: row.kind,
+      text: row.text,
+      toolName: row.toolName || null,
+      toolUseId: null,
+      metadata: row.metadata || null,
+      done: row.done,
+      createdAt: row.createdAt || null,
+      updatedAt: row.createdAt || null,
+    }));
+  }
+
+  /**
+   * A run's record for the viewer: entries after `afterSeq` (plus open ones),
+   * its child runs, and whether this page reached the end. A run with no
+   * timeline rows that no worker owns is served from what it recorded before
+   * the timeline existed.
+   */
+  function readTimeline(run, { afterSeq = 0, limit = TIMELINE_READ_DEFAULT_LIMIT, isStoppable = () => false } = {}) {
+    const runId = String(run.id);
+    const pageLimit = Math.max(1, Math.min(TIMELINE_READ_MAX_LIMIT, Number(limit) || TIMELINE_READ_DEFAULT_LIMIT));
+    const after = Math.max(0, Number(afterSeq) || 0);
+    const children = (stmts.listChildSubagentRuns?.all?.(runId) || [])
+      .map((row) => mapSubagentRunHeader(row, { stoppable: isStoppable(row) }))
+      .filter(Boolean);
+    let entries = [];
+    let legacy = false;
+    let complete = true;
+    if (supported()) {
+      const rows = stmts.listTimelineEntries.all({ runId, afterSeq: after, limit: pageLimit + 1 });
+      complete = rows.length <= pageLimit;
+      entries = rows.slice(0, pageLimit).map(mapTimelineRow);
+      const hasAny = after > 0 || entries.length > 0 || Number(stmts.getMaxTimelineSeq.get(runId)?.max_seq || 0) > 0;
+      if (!hasAny && !run.timeline_owner) {
+        entries = after > 0 ? [] : legacyEntries(runId);
+        legacy = entries.length > 0;
+        complete = true;
+      }
+    } else if (after === 0) {
+      entries = legacyEntries(runId);
+      legacy = entries.length > 0;
+    }
+    const lastSeq = entries.reduce((max, entry) => Math.max(max, entry.seq), after);
+    return {
+      run: mapSubagentRunHeader(run, { stoppable: isStoppable(run), legacy }),
+      entries,
+      children,
+      nextAfter: lastSeq,
+      complete,
+    };
+  }
+
+  return { applyHeader, applyEntries, mirrorFrame, readTimeline, supported };
+}

package/server/services/subagent-viewer-rooms.mjs

@@ -0,0 +1,119 @@
+'use strict';
+
+// Who receives a sub-agent's record live: only the pages whose viewer shows
+// that run. The viewer names its run with `subagent_viewer_watch` (on open,
+// on switching to a child or its parent, and after every reconnect) and
+// leaves with `subagent_viewer_unwatch`; the relay keeps each socket in at
+// most one viewer room. `emitSubagentTimeline` sends volatile to that room,
+// so a page without the viewer gets nothing and a connection that cannot take
+// a batch drops it — the viewer fetches whatever it misses.
+
+import { sanitizeSubagentRunId } from '../../shared/subagent-run-id.mjs';
+
+const ROOM_PREFIX = 'subagent-viewer:';
+
+export function subagentViewerRoom(runId) {
+  return `${ROOM_PREFIX}${String(runId || '')}`;
+}
+
+/**
+ * Sends a run's record batches to its viewers. socket.io drops a volatile
+ * packet whenever the connection is still writing an earlier one, even one
+ * sent in the same tick, and a worker post that changes the run's header
+ * emits the run's status just before its batch. So batches wait one tick,
+ * merged per run (the newest copy of an entry wins), and go out together:
+ * dropped only when the connection is really backed up.
+ */
+export function createSubagentTimelinePublisher(io, { defer = setImmediate } = {}) {
+  const pending = new Map();
+  let scheduled = false;
+
+  function flush() {
+    scheduled = false;
+    const batches = [...pending.values()];
+    pending.clear();
+    for (const batch of batches) {
+      const entries = [...batch.entries.values()].sort((a, b) => Number(a.seq) - Number(b.seq));
+      try {
+        io.to(subagentViewerRoom(batch.subagentRunId)).volatile.emit('subagent_timeline', { ...batch.head, entries });
+      } catch {}
+    }
+  }
+
+  return function publish(payload) {
+    const runId = String(payload?.subagentRunId || '');
+    if (!runId || !payload?.entries?.length) return;
+    let batch = pending.get(runId);
+    if (!batch) {
+      batch = { subagentRunId: runId, head: null, entries: new Map() };
+      pending.set(runId, batch);
+    }
+    const { entries, ...head } = payload;
+    batch.head = { ...head, truncated: !!(batch.head?.truncated || head.truncated) };
+    for (const entry of entries) batch.entries.set(Number(entry.seq), entry);
+    if (!scheduled) {
+      scheduled = true;
+      defer(flush);
+    }
+  };
+}
+
+function safeAck(ack, payload) {
+  if (typeof ack !== 'function') return;
+  try { ack(payload); } catch {}
+}
+
+/**
+ * `getRun(runId)` returns the run row (`id`, `conversation_id`) or null.
+ * Sockets reaching `registerSocket` are already authenticated (the `io.use`
+ * gate, and the re-check of recovered sockets in the connection handler).
+ */
+export function createSubagentViewerRooms({ getRun } = {}) {
+  if (typeof getRun !== 'function') throw new Error('createSubagentViewerRooms requires getRun');
+
+  function leave(socket) {
+    const current = socket.data?.subagentViewerRoom;
+    if (current) socket.leave(current);
+    if (socket.data) socket.data.subagentViewerRoom = null;
+  }
+
+  function watch(socket, payload) {
+    const conversationId = String(payload?.conversationId || '').trim();
+    const runId = sanitizeSubagentRunId(payload?.subagentRunId);
+    if (!conversationId || !runId) return { ok: false, code: 'missing-id' };
+    let run = null;
+    try {
+      run = getRun(runId);
+    } catch {
+      return { ok: false, code: 'unavailable' };
+    }
+    if (!run) return { ok: false, code: 'not-found' };
+    if (String(run.conversation_id || '') !== conversationId) return { ok: false, code: 'conversation-mismatch' };
+    const room = subagentViewerRoom(runId);
+    if (socket.data?.subagentViewerRoom !== room) {
+      leave(socket);
+      socket.join(room);
+      if (socket.data) socket.data.subagentViewerRoom = room;
+    } else if (!socket.rooms?.has?.(room)) {
+      // A recovered socket keeps its data; its rooms may or may not be back.
+      socket.join(room);
+    }
+    return { ok: true, subagentRunId: runId };
+  }
+
+  function registerSocket(socket) {
+    if (!socket || typeof socket.on !== 'function') return;
+    socket.on('subagent_viewer_watch', (payload, ack) => {
+      const result = watch(socket, payload);
+      // A refused watch leaves no stale room behind: the page shows another run now.
+      if (!result.ok) leave(socket);
+      safeAck(ack, result);
+    });
+    socket.on('subagent_viewer_unwatch', (_payload, ack) => {
+      leave(socket);
+      safeAck(ack, { ok: true });
+    });
+  }
+
+  return { registerSocket };
+}