@oar-sh/oar 0.9.10 → 0.9.12

package/server/services/background-task-store.mjs

@@ -0,0 +1,365 @@
+'use strict';
+
+/**
+ * Live background-task sets, published by the session workers (REPLACE
+ * semantics, mirroring the SDK's background_tasks_changed signal) and keyed
+ * by the id the worker posts, its SDK session id.
+ *
+ * Memory only, and a relay restart starts it empty while the workers and
+ * their tasks keep running. The worker is the source of truth: its heartbeat
+ * carries a digest of its task ids, the relay compares it with the set held
+ * here and asks for the full set when the two differ (a restart, a lost
+ * post). `reported` remembers which workers this runtime has heard from
+ * about their tasks at all: until then "no set" means "not told yet", not
+ * "no tasks".
+ *
+ * Ended tasks: a task that leaves the set while it names an `outputPath` (a
+ * shell or Monitor task with a console) is kept as an ended row for an hour,
+ * at most 20 per key, so the panel can still show how it ended and open its
+ * output. A settle post (`settle`) says how; one that arrives before the set
+ * drops the task is kept until it does. Memory only, like the sets.
+ *
+ * Health: the health poller's last reading per live task (`setHealth`), served
+ * with the task rows (`withHealth`) and carried onto the ended row, where the
+ * poller's reading after the end replaces it (`setEndedHealth`).
+ */
+
+import { backgroundTaskDigest, sameBackgroundTaskDigest } from '../../shared/worker-runtime/background-task-digest.mjs';
+import { TASK_OUTPUT_LIMITS } from '../../shared/task-output-text.mjs';
+
+function keyOf(value) {
+  return String(value || '').trim();
+}
+
+const ENDED_STATUSES = new Set(['completed', 'failed', 'stopped', 'unknown']);
+
+/** A worker's word for how a task ended, as one of completed, failed, stopped, unknown. */
+export function normalizeEndedTaskStatus(status, exitCode = null) {
+  const text = String(status || '').trim().toLowerCase();
+  if (ENDED_STATUSES.has(text)) return text;
+  if (['complete', 'done', 'success', 'succeeded', 'ok', 'exited'].includes(text)) {
+    return Number.isInteger(exitCode) && exitCode !== 0 ? 'failed' : 'completed';
+  }
+  if (['error', 'errored', 'failure'].includes(text)) return 'failed';
+  if (['killed', 'cancelled', 'canceled', 'aborted', 'interrupted', 'timeout', 'timed_out'].includes(text)) return 'stopped';
+  if (Number.isInteger(exitCode)) return exitCode === 0 ? 'completed' : 'failed';
+  return 'unknown';
+}
+
+function exitCodeOf(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const number = Number(value);
+  return Number.isInteger(number) ? number : null;
+}
+
+export function createBackgroundTaskStore({
+  now = () => Date.now(),
+  endedKeepMs = TASK_OUTPUT_LIMITS.endedKeepMs,
+  endedMax = TASK_OUTPUT_LIMITS.endedMax,
+} = {}) {
+  const sets = new Map();
+  // key → Map(taskId → ended row), newest last.
+  const endedRows = new Map();
+  // key → Map(taskId → { status, exitCode, outputPath, at }): how a task
+  // ended, told before the set dropped it.
+  const settledAhead = new Map();
+  // key → Map(taskId → the health poller's last reading).
+  const healthByKey = new Map();
+  const reported = new Set();
+  // key → the order of the newest set applied, `{ epoch, seq }` as the
+  // worker numbered it. `epoch` names the worker process; it is compared
+  // for equality only, never as a time.
+  const applied = new Map();
+  // key → the pid of the worker process whose heartbeat came last: the
+  // process that holds the session, by the worker's own word.
+  const holders = new Map();
+  // Keys whose pages were told of the placeholder for unreported work.
+  const announced = new Set();
+
+  return {
+    sets,
+    replace(conversationId, tasks) {
+      const id = keyOf(conversationId);
+      if (!id) return;
+      reported.add(id);
+      const next = Array.isArray(tasks) ? tasks : [];
+      const nextIds = new Set(next.map((task) => keyOf(task?.taskId)).filter(Boolean));
+      // Tasks that left the set with a console become ended rows.
+      for (const task of sets.get(id)?.tasks || []) {
+        const taskId = keyOf(task?.taskId);
+        if (!taskId || nextIds.has(taskId) || !task?.outputPath) continue;
+        const ahead = settledAhead.get(id)?.get(taskId) || null;
+        addEnded(id, {
+          ...task,
+          ...(ahead?.steps !== undefined ? { steps: ahead.steps } : {}),
+          status: ahead?.status || 'unknown',
+          exitCode: ahead ? ahead.exitCode : (task.exitCode ?? null),
+          health: healthByKey.get(id)?.get(taskId) || task.health || undefined,
+        });
+      }
+      // A task back in the set (a resync after a restart) is not ended.
+      for (const taskId of nextIds) {
+        endedRows.get(id)?.delete(taskId);
+        settledAhead.get(id)?.delete(taskId);
+      }
+      const health = healthByKey.get(id);
+      if (health) {
+        for (const taskId of [...health.keys()]) if (!nextIds.has(taskId)) health.delete(taskId);
+        if (!health.size) healthByKey.delete(id);
+      }
+      if (next.length === 0) {
+        sets.delete(id);
+        return;
+      }
+      sets.set(id, { tasks: next, updatedAt: now() });
+    },
+    /**
+     * How a task ended (`/api/background-task-settled`): updates its ended
+     * row, or is kept for the moment the set drops it, or, for a task this
+     * runtime never saw live that names its output, becomes an ended row of
+     * its own. Returns the ended row when there is one.
+     */
+    settle(conversationId, taskId, { status, exitCode, outputPath, description, taskType, startedAt, outputKind, steps } = {}) {
+      const id = keyOf(conversationId);
+      const task = keyOf(taskId);
+      if (!id || !task) return null;
+      prune(id);
+      const code = exitCodeOf(exitCode);
+      const normalized = normalizeEndedTaskStatus(status, code);
+      const stepCount = Number.isInteger(steps) && steps >= 0 ? steps : undefined;
+      const existing = endedRows.get(id)?.get(task);
+      if (existing) {
+        existing.status = normalized;
+        existing.exitCode = code;
+        if (!existing.outputPath && outputPath) {
+          existing.outputPath = outputPath;
+          if (existing.outputKind !== 'file' && existing.outputKind !== 'spool') existing.outputKind = outputKind === 'spool' ? 'spool' : 'file';
+        }
+        if (stepCount !== undefined) existing.steps = stepCount;
+        return existing;
+      }
+      const live = (sets.get(id)?.tasks || []).find((entry) => keyOf(entry?.taskId) === task);
+      if (live) {
+        let ahead = settledAhead.get(id);
+        if (!ahead) settledAhead.set(id, ahead = new Map());
+        ahead.set(task, { status: normalized, exitCode: code, steps: stepCount, at: now() });
+        // The first path a task names wins. A row that had none was read
+        // from a snapshot (or not at all): from now on it is the file.
+        if (outputPath && !live.outputPath) {
+          live.outputPath = outputPath;
+          if (live.outputKind !== 'file' && live.outputKind !== 'spool') live.outputKind = outputKind === 'spool' ? 'spool' : 'file';
+        }
+        return null;
+      }
+      if (!outputPath) return null;
+      return addEnded(id, {
+        taskId: task,
+        taskType: keyOf(taskType) || 'local_bash',
+        description: String(description || '').trim().slice(0, 500),
+        startedAt: Number(startedAt) || null,
+        outputPath,
+        outputKind: outputKind || 'file',
+        stoppable: false,
+        status: normalized,
+        exitCode: code,
+        ...(stepCount !== undefined ? { steps: stepCount } : {}),
+      });
+    },
+    /** The ended rows of these keys, newest first. */
+    ended(...keys) {
+      const rows = [];
+      for (const id of new Set(keys.map(keyOf).filter(Boolean))) {
+        prune(id);
+        rows.push(...(endedRows.get(id)?.values() || []));
+      }
+      return rows.sort((a, b) => b.endedAt - a.endedAt).map((row) => ({ ...row }));
+    },
+    /** The poller's last reading for a live task, or null. */
+    health(conversationId, taskId) {
+      return healthByKey.get(keyOf(conversationId))?.get(keyOf(taskId)) || null;
+    },
+    setHealth(conversationId, taskId, value) {
+      const id = keyOf(conversationId);
+      const task = keyOf(taskId);
+      if (!id || !task) return;
+      let health = healthByKey.get(id);
+      if (!value) {
+        health?.delete(task);
+        return;
+      }
+      if (!health) healthByKey.set(id, health = new Map());
+      health.set(task, value);
+    },
+    /** The keys that hold ended rows. */
+    endedKeys() {
+      return [...endedRows.keys()];
+    },
+    /**
+     * The poller's reading of an ended task's file, taken after the end: the
+     * last output (a test runner's summary) often lands between two readings
+     * of the live task. Returns false when there is no such row.
+     */
+    setEndedHealth(conversationId, taskId, value) {
+      const row = endedRows.get(keyOf(conversationId))?.get(keyOf(taskId));
+      if (!row || !value) return false;
+      row.health = value;
+      return true;
+    },
+    /** Task rows with the poller's last reading on each as `health`. */
+    withHealth(tasks, ...keys) {
+      const ids = keys.map(keyOf).filter(Boolean);
+      return (Array.isArray(tasks) ? tasks : []).map((task) => {
+        const taskId = keyOf(task?.taskId);
+        const health = ids.map((id) => healthByKey.get(id)?.get(taskId)).find(Boolean);
+        return health ? { ...task, health } : task;
+      });
+    },
+    /**
+     * A task of these keys, live or ended: `{ key, task, ended }` or null.
+     * The live set wins over an ended row.
+     */
+    findTask(keys, taskId) {
+      const task = keyOf(taskId);
+      const ids = [...new Set((Array.isArray(keys) ? keys : [keys]).map(keyOf).filter(Boolean))];
+      if (!task) return null;
+      for (const id of ids) {
+        const live = (sets.get(id)?.tasks || []).find((entry) => keyOf(entry?.taskId) === task);
+        if (live) {
+          const health = healthByKey.get(id)?.get(task);
+          return { key: id, task: health ? { ...live, health } : live, ended: false };
+        }
+      }
+      for (const id of ids) {
+        prune(id);
+        const row = endedRows.get(id)?.get(task);
+        if (row) return { key: id, task: { ...row }, ended: true };
+      }
+      return null;
+    },
+    get(conversationId) {
+      return sets.get(keyOf(conversationId))?.tasks || [];
+    },
+    /** The digest of the set held under the first of `keys` that has one. */
+    digestFor(...keys) {
+      const held = keys.map(keyOf).find((key) => key && sets.has(key));
+      return backgroundTaskDigest((held ? sets.get(held).tasks : []).map((task) => task?.taskId));
+    },
+    /**
+     * A worker's heartbeat digest against the set held for it: true when
+     * they agree. Agreement counts as a report, an empty set included.
+     */
+    matches(digest, ...keys) {
+      const same = sameBackgroundTaskDigest(digest, this.digestFor(...keys));
+      if (same) for (const key of keys.map(keyOf).filter(Boolean)) reported.add(key);
+      return same;
+    },
+    /** Whether this runtime has heard from the worker about its tasks. */
+    hasReport(...keys) {
+      return keys.map(keyOf).some((key) => key && reported.has(key));
+    },
+    /**
+     * Whether a set with this order may be applied, as `{ accepted, reason }`.
+     * Accepting records it. `seq` is the worker process's count of set
+     * posts, `epoch` names that process. A set without an order, from a
+     * worker that numbers none, always applies.
+     *
+     * Refused are:
+     *  - `older`: same process, a count not above the newest applied. The
+     *    post was overtaken on the way.
+     *  - `not-holder`: the post's `pid` is not the pid of the process whose
+     *    heartbeat came last for the session (`noteHolder`): a late post of
+     *    the process before it, or a new process that has not beaten yet,
+     *    which is told so and beats.
+     *
+     * A different epoch from the holder, or from a process that cannot be
+     * placed (no pid on the post, no heartbeat yet), is a new process and
+     * starts the count over, whichever of the two epochs is the larger: a clock that
+     * stepped back between two starts must not turn every set away. A late
+     * post that slips through that way is put right by the next heartbeat's
+     * digest.
+     */
+    acceptOrder(conversationId, order, { pid = null } = {}) {
+      const id = keyOf(conversationId);
+      const epoch = Number(order?.epoch);
+      const seq = Number(order?.seq);
+      if (!id || !Number.isFinite(epoch) || !Number.isInteger(seq) || seq < 0) return { accepted: true, reason: null };
+      const holder = holders.get(id);
+      const from = Number(pid);
+      if (holder && Number.isInteger(from) && from > 0 && from !== holder) return { accepted: false, reason: 'not-holder' };
+      const last = applied.get(id);
+      if (last && epoch === last.epoch && seq <= last.seq) return { accepted: false, reason: 'older' };
+      applied.set(id, { epoch, seq });
+      return { accepted: true, reason: null };
+    },
+    /** A heartbeat of the session's worker came from this process. */
+    noteHolder(conversationId, pid) {
+      const id = keyOf(conversationId);
+      const from = Number(pid);
+      if (id && Number.isInteger(from) && from > 0) holders.set(id, from);
+    },
+    /** Records whether the pages know of the key's placeholder; true when that changed. */
+    announce(conversationId, shown) {
+      const id = keyOf(conversationId);
+      if (!id || announced.has(id) === !!shown) return false;
+      if (shown) announced.add(id);
+      else announced.delete(id);
+      return true;
+    },
+    /** The conversation is gone: everything held for these keys goes. */
+    /**
+     * Drops expired ended rows and pending settles of every key, also of
+     * conversations nobody reads again (the per-key prune runs on reads).
+     * Called from the health poller's tick.
+     */
+    pruneAll() {
+      for (const id of new Set([...endedRows.keys(), ...settledAhead.keys()])) prune(id);
+    },
+    forget(...keys) {
+      for (const id of keys.map(keyOf).filter(Boolean)) {
+        sets.delete(id);
+        reported.delete(id);
+        applied.delete(id);
+        holders.delete(id);
+        announced.delete(id);
+        endedRows.delete(id);
+        settledAhead.delete(id);
+        healthByKey.delete(id);
+      }
+    },
+  };
+
+  function prune(id) {
+    const cutoff = now() - endedKeepMs;
+    const rows = endedRows.get(id);
+    if (rows) {
+      for (const [taskId, row] of rows) if (row.endedAt < cutoff) rows.delete(taskId);
+      if (!rows.size) endedRows.delete(id);
+    }
+    const ahead = settledAhead.get(id);
+    if (ahead) {
+      for (const [taskId, entry] of ahead) if (entry.at < cutoff) ahead.delete(taskId);
+      if (!ahead.size) settledAhead.delete(id);
+    }
+  }
+
+  function addEnded(id, task) {
+    let rows = endedRows.get(id);
+    if (!rows) endedRows.set(id, rows = new Map());
+    const taskId = keyOf(task.taskId);
+    rows.delete(taskId);
+    const row = {
+      ...task,
+      taskId,
+      status: normalizeEndedTaskStatus(task.status, exitCodeOf(task.exitCode)),
+      exitCode: exitCodeOf(task.exitCode),
+      endedAt: now(),
+      stoppable: false,
+    };
+    if (!row.health) delete row.health;
+    rows.set(taskId, row);
+    settledAhead.get(id)?.delete(taskId);
+    while (rows.size > endedMax) rows.delete(rows.keys().next().value);
+    prune(id);
+    return row;
+  }
+}

package/server/services/background-work-view.mjs

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * What the relay can say about background work whose details it may not
+ * hold, because its task store and activity tracker live in memory and
+ * start empty at every runtime start while the workers keep running:
+ *
+ *  - the placeholder: a live worker that says it has background work (the
+ *    Claude worker's `autoCompactWindow.backgroundWork` on its heartbeat)
+ *    while this runtime was never told its task set. Workers that answer a
+ *    resync request fill the real set in within one heartbeat; this is for
+ *    the ones still running older code. It is read, never stored: it goes
+ *    when the set arrives, when the flag goes false and when the worker is
+ *    gone, and it raises no start or end event.
+ *  - the suspend blockers for background work, from the store and from the
+ *    activity tracker (which also reads running sub-agent runs from the
+ *    database), and the blocker for a runtime that only just started.
+ */
+
+import {
+  UNREPORTED_BACKGROUND_TASK_DESCRIPTION,
+  UNREPORTED_BACKGROUND_TASK_ID,
+} from './session-activity-tracker.mjs';
+
+// Providers whose worker lists every running background sub-agent in its
+// task set, by the run's id. Others may run background agents no set lists
+// (their run rows are their only trace), so a set says nothing about a row.
+const RUN_LISTING_PROVIDERS = new Set(['claude']);
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+/** The placeholder as a row of the task panel: no details, no Stop button. */
+export function unreportedBackgroundTaskCard() {
+  return {
+    taskId: UNREPORTED_BACKGROUND_TASK_ID,
+    taskType: 'unreported',
+    description: UNREPORTED_BACKGROUND_TASK_DESCRIPTION,
+    startedAt: null,
+    stoppable: false,
+    placeholder: true,
+  };
+}
+
+export function createBackgroundWorkView({
+  store,
+  db = null,
+  getRegistry = () => null,
+  getTracker = () => null,
+  isWorkerAlive = () => false,
+  // A conversation's id and its worker's session id are two ids, usually
+  // equal and not always. The tracker and the database speak of
+  // conversations; the registry, the store and the workers' own headers of
+  // sessions. These two map between them through the runtime session.
+  sessionIdOf = () => '',
+  conversationIdOf = () => '',
+  // conversationId → its provider ('claude', 'github', …).
+  providerOf = () => '',
+  titleOf = (conversationId) => toText(conversationId).slice(0, 8),
+} = {}) {
+  let listRunningRuns = null;
+  if (db) {
+    try {
+      listRunningRuns = db.prepare(`
+        SELECT DISTINCT conversation_id FROM subagent_runs
+        WHERE status = 'running' AND background = 1 AND parent_subagent_id IS NULL
+      `);
+    } catch {}
+  }
+
+  function mapped(resolve, id) {
+    try { return toText(resolve(id)); } catch { return ''; }
+  }
+
+  /** The worker of a session id or of a conversation id. */
+  function workerOf(key) {
+    const registry = getRegistry();
+    const id = toText(key);
+    if (!registry || !id) return null;
+    // The registry's own indexes first; the mapping is a database read.
+    const direct = registry.getWorker?.(id) || registry.getWorkerByConversationId?.(id) || null;
+    if (direct) return direct;
+    const sessionId = mapped(sessionIdOf, id);
+    return (sessionId && sessionId !== id && registry.getWorker?.(sessionId)) || null;
+  }
+
+  /** The conversation a worker serves; the registry's own field may hold its session id. */
+  function conversationOf(worker, fallback = '') {
+    return mapped(conversationIdOf, worker?.sdkSessionId) || toText(worker?.conversationId) || toText(fallback);
+  }
+
+  function workerAlive(key) {
+    const worker = workerOf(key);
+    return !!worker && isWorkerAlive(worker.sdkSessionId) === true;
+  }
+
+  /** Whether the placeholder stands for this worker (by session or conversation id). */
+  function hasUnreportedWork(key) {
+    const worker = workerOf(key);
+    if (!worker || worker.steering?.autoCompactWindow?.backgroundWork !== true) return false;
+    const keys = [worker.sdkSessionId, worker.conversationId, conversationOf(worker), key];
+    if (store.hasReport(...keys)) return false;
+    if (keys.some((entry) => store.get(entry).length > 0)) return false;
+    return isWorkerAlive(worker.sdkSessionId) === true;
+  }
+
+  function listUnreportedConversationIds() {
+    const workers = getRegistry()?.listWorkers?.() || [];
+    return workers
+      .filter((worker) => worker?.steering?.autoCompactWindow?.backgroundWork === true && hasUnreportedWork(worker.sdkSessionId))
+      .map((worker) => conversationOf(worker, worker.sdkSessionId))
+      .filter(Boolean);
+  }
+
+  /**
+   * Whether the task set of a conversation's worker lists a sub-agent run
+   * (by the run's id or its task id): true or false, and null where the set
+   * cannot answer, because the worker has reported none in this runtime
+   * or its provider's sets do not list every background run. The tracker
+   * drops a `running` row that is not listed and has long been quiet.
+   */
+  function runListed(conversationId, row) {
+    const conversation = toText(conversationId);
+    if (!RUN_LISTING_PROVIDERS.has(mapped(providerOf, conversation).toLowerCase())) return null;
+    const keys = [...new Set([conversation, mapped(sessionIdOf, conversation), toText(workerOf(conversation)?.sdkSessionId)].filter(Boolean))];
+    if (!store.hasReport(...keys)) return null;
+    const runId = toText(row?.id);
+    const taskId = toText(row?.task_id);
+    return keys.some((key) => store.get(key).some((task) => (runId && toText(task?.toolUseId) === runId)
+      || (taskId && toText(task?.taskId) === taskId)));
+  }
+
+  /** The task panel's rows for a conversation: its set, else the placeholder. */
+  function panelTasks(...keys) {
+    for (const key of keys) {
+      const tasks = store.get(key);
+      if (tasks.length) return tasks;
+    }
+    return keys.some((key) => toText(key) && hasUnreportedWork(key)) ? [unreportedBackgroundTaskCard()] : [];
+  }
+
+  /**
+   * One `background` blocker per conversation with running background work
+   * of a live worker: the tasks of its published set, the running tasks the
+   * tracker knows (a background sub-agent run in the database, the
+   * placeholder), each task once.
+   */
+  function backgroundBlockers() {
+    const byConversation = new Map();
+    const add = (conversationId, id, description) => {
+      const conversation = toText(conversationId);
+      if (!conversation) return;
+      let tasks = byConversation.get(conversation);
+      if (!tasks) byConversation.set(conversation, tasks = new Map());
+      const taskId = toText(id) || `task-${tasks.size + 1}`;
+      if (!tasks.has(taskId)) tasks.set(taskId, toText(description) || 'task');
+    };
+    for (const [key, entry] of store.sets) {
+      const tasks = Array.isArray(entry?.tasks) ? entry.tasks : [];
+      if (!tasks.length || !workerAlive(key)) continue;
+      const conversationId = conversationOf(workerOf(key), mapped(conversationIdOf, key) || key);
+      for (const task of tasks) add(conversationId, task?.taskId, task?.description || task?.taskType);
+    }
+    const tracker = getTracker();
+    if (tracker) {
+      const candidates = new Set();
+      try { for (const id of tracker.knownConversationIds?.() || []) candidates.add(toText(id)); } catch {}
+      try { for (const row of listRunningRuns?.all() || []) candidates.add(toText(row.conversation_id)); } catch {}
+      for (const conversationId of candidates) {
+        if (!conversationId || !workerAlive(conversationId)) continue;
+        let view = null;
+        try { view = tracker.describe(conversationId); } catch {}
+        for (const task of view?.tasks || []) {
+          // A run inside a turn is the turn's work; the turn is the blocker.
+          if (task.status !== 'running' || task.inTurn) continue;
+          add(conversationId, task.id, task.description || task.type);
+        }
+      }
+    }
+    return [...byConversation].map(([conversationId, tasks]) => {
+      // The placeholder's text names the way out; it is not cut short.
+      const what = [...tasks].slice(0, 3)
+        .map(([id, text]) => (id === UNREPORTED_BACKGROUND_TASK_ID ? text : text.slice(0, 80)))
+        .join('; ');
+      return {
+        kind: 'background',
+        conversationId,
+        title: titleOf(conversationId),
+        count: tasks.size,
+        detail: `${tasks.size} background agent${tasks.size === 1 ? '' : 's'}: ${what}`,
+      };
+    });
+  }
+
+  /**
+   * The blocker of a runtime that only just started: workers that outlived
+   * the one before it may not have reported their background work yet, so
+   * "nothing runs" is not known. Null once the window is over. Its text
+   * does not change while it stands: every change of a blocker goes out to
+   * every page.
+   */
+  function bootBlocker() {
+    let boot = null;
+    try { boot = getTracker()?.bootReporting?.() || null; } catch {}
+    if (!boot?.active) return null;
+    return {
+      kind: 'boot',
+      detail: 'the relay just started, sessions are still reporting',
+    };
+  }
+
+  /** What holds a host suspend back for background work: the two above. */
+  function blockers() {
+    const boot = bootBlocker();
+    return [...backgroundBlockers(), ...(boot ? [boot] : [])];
+  }
+
+  return {
+    hasUnreportedWork,
+    listUnreportedConversationIds,
+    runListed,
+    panelTasks,
+    backgroundBlockers,
+    bootBlocker,
+    blockers,
+  };
+}

package/server/services/cache-rebuild-service.mjs

@@ -62,6 +62,12 @@ export function createCacheRebuildService({
   bootstrapRuntimeSessionBindings,
   collectOrphanedUploadsFromConversation,
   deleteOrphanedUploads,
+  // (conversationId) => void: a hard-deleted conversation takes its preview
+  // links with it, as a delete from the UI does. Archiving keeps them.
+  closeConversationPreviews = null,
+  // Session groups: a purged head leaves its group, and a wipe is followed
+  // by a repair of what the wiped rows headed. Absent in older wiring.
+  conversationGroups = null,
 }) {
   const legacyConversationList = buildLegacyConversationList(db);
   const boundConversationList = buildBoundConversationList(db);
@@ -81,6 +87,7 @@ export function createCacheRebuildService({
     if (!sid) return [];
     const orphanedUploads = collectOrphanedUploadsFromConversation(sid);
     db.transaction(() => {
+      try { conversationGroups?.forgetConversation?.(sid); } catch {}
       db.prepare(`DELETE FROM relay_questions WHERE conversation_id = ?`).run(sid);
       db.prepare(`DELETE FROM relay_boards WHERE conversation_id = ?`).run(sid);
       db.prepare(`DELETE FROM relay_activity WHERE conversation_id = ?`).run(sid);
@@ -91,10 +98,19 @@ export function createCacheRebuildService({
       db.prepare(`DELETE FROM runtime_sessions WHERE conversation_id = ?`).run(sid);
       db.prepare(`DELETE FROM conversations WHERE id = ?`).run(sid);
     })();
+    closePreviews(sid);
     deleteOrphanedUploads(orphanedUploads);
     return orphanedUploads;
   }
 
+  function closePreviews(conversationId) {
+    try {
+      closeConversationPreviews?.(conversationId);
+    } catch (error) {
+      console.warn(`[preview] closing the previews of a purged conversation failed: ${error?.message || error}`);
+    }
+  }
+
   function archiveConversation(conversationId) {
     const sid = normalizeId(conversationId);
     if (!sid) return false;
@@ -112,6 +128,12 @@ export function createCacheRebuildService({
         AND title_source = 'manual'
     `).all().map((row) => normalizeId(row?.id)).filter(Boolean);
     const manualTitleConversationSet = new Set(manualTitleConversations);
+    // The groups headed by a row about to go keep the head's title as their
+    // name, so a group whose hand-titled members survive is not nameless; the
+    // head link stays for a re-import under the same id.
+    try {
+      conversationGroups?.freezeNamesForHeads?.(conversationIds.filter((id) => !manualTitleConversationSet.has(id)), now);
+    } catch {}
     const uploadHashes = [];
     for (const conversationId of conversationIds) {
       for (const hash of collectOrphanedUploadsFromConversation(conversationId)) {
@@ -147,8 +169,16 @@ export function createCacheRebuildService({
       db.prepare(`DELETE FROM sdk_session_imports`).run();
       db.prepare(`DELETE FROM upload_refs`).run();
       db.prepare(`DELETE FROM uploaded_files`).run();
+      // Groups whose rows are all gone go too; one whose head was wiped but
+      // whose hand-titled members stay keeps the frozen name and the head
+      // link (a re-imported head takes it up again).
+      try { conversationGroups?.sweepEmpty?.(); } catch {}
     })();
 
+    for (const conversationId of conversationIds) {
+      if (!manualTitleConversationSet.has(conversationId)) closePreviews(conversationId);
+    }
+
     deleteOrphanedUploads(uploadHashes);
 
     if (uploadsDir && fs?.existsSync?.(uploadsDir)) {