@oar-sh/oar 0.9.10 → 0.9.12

package/server/copilot-worker/copilot-sdk-session-process.mjs

@@ -120,6 +120,10 @@ import {
   probeRuntime,
   resolveTurnStallWindows,
 } from '../../shared/worker-runtime/turn-liveness.mjs';
+import { createTaskOutputSpool } from '../../shared/worker-runtime/task-output-spool.mjs';
+import { createShellOutputMirror } from './copilot-shell-output-mirror.mjs';
+import { isTransientProgressText, settleForTask, shellExitFromEvent } from './copilot-task-settle.mjs';
+import { createKeptPosts } from '../../shared/worker-runtime/kept-posts.mjs';
 
 // How long the runtime may sit with no session activity before the worker
 // closes it. The worker process itself stays up and reconnects lazily on the
@@ -235,6 +239,8 @@ const STOPPED_ROW_PUBLISH_WAIT_MS = 5_000;
  * (which carries no payload and fires ~20 times per shell call).
  */
 const DEFAULT_TASK_REFRESH_MS = 250;
+/** How often the task output spool drops files of tasks that ended over an hour ago. */
+const SPOOL_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
 /** Trailing throttle for enrichment-only card updates (a live tool call, tokens). */
 const DEFAULT_TASK_PUBLISH_THROTTLE_MS = 2_000;
 /**
@@ -461,6 +467,13 @@ export function createCopilotSdkSessionRunner({
   // heartbeat snapshot, and a 10 s wait would often outlast the window in
   // which the runtime still holds the message (live check 2026-09-25).
   onCancellableChange = () => {},
+  // The relay turned this worker's newest task set away (`stale`): the
+  // worker asks for a heartbeat, on which the relay learns which process
+  // holds the session and asks for the set again.
+  onBackgroundTaskSetStale = () => {},
+  // Where attached shells' output is mirrored for the task console
+  // (shared/worker-runtime/task-output-spool.mjs). Tests pass their own.
+  taskOutputSpool = null,
   dbg = () => {},
 } = {}) {
   let client = null;
@@ -615,6 +628,24 @@ export function createCopilotSdkSessionRunner({
   // cards; the registry alone decides liveness (the lifecycle pin).
   let backgroundTasks = new Map();
   const agentDetails = new Map();
+  // A detached shell names its own log (`TaskShellInfo.logPath`); an attached
+  // one has only the runtime's recent-output window, mirrored into a spool
+  // file here so the task console can read it like any other log.
+  const spool = taskOutputSpool || (() => {
+    try { return createTaskOutputSpool({ sessionId: sdkSessionId }); } catch (error) {
+      dbg('task output spool unavailable', error?.message || String(error));
+      return null;
+    }
+  })();
+  const shellOutputMirror = createShellOutputMirror({ spool, dbg });
+  // Ended tasks' files are kept about an hour for the relay; swept at start
+  // and hourly.
+  const sweepSpool = () => {
+    try { spool?.sweep(); } catch (error) { dbg('task output spool sweep failed', error?.message || String(error)); }
+  };
+  sweepSpool();
+  const spoolSweepTimer = setInterval(sweepSpool, SPOOL_SWEEP_INTERVAL_MS);
+  spoolSweepTimer.unref?.();
   let taskRefreshTimer = null;
   let taskRefreshChain = Promise.resolve();
   // Reads of the registry that failed in a row. While there are some, "no
@@ -628,7 +659,15 @@ export function createCopilotSdkSessionRunner({
   let taskRefreshQueued = 0;
   let lastTaskRefreshAt = 0;
   let taskPublishTimer = null;
+  // The last set the relay took, as JSON, and the one on its way to it.
   let lastPublishedTasksSignature = '';
+  let inFlightTasksSignature = null;
+  let taskPublishSeq = 0;
+  // Every post of the set carries its place in this worker's order
+  // (`epoch` tells this process from one before it): posts can overtake
+  // each other on the way, and the relay applies the newer one only.
+  const taskSetEpoch = Date.now();
+  let taskSetStaleNotedAt = 0;
   // Cap expiry is bounded: a task whose cancel the runtime refuses (or that
   // keeps failing) this many times is abandoned — dropped from the live set so
   // it stops pinning the runtime — rather than held forever.
@@ -666,6 +705,16 @@ export function createCopilotSdkSessionRunner({
   // The detached shells this session has running. The lifecycle's pin, and the
   // reason a settled one is worth waiting for.
   const backgroundShells = createBackgroundShellTracker();
+  // How a background task ended, told to the relay (its live set only says
+  // the task is gone). A failed post is kept and sent again after the next
+  // heartbeat answer.
+  const keptTaskSettles = createKeptPosts({ api, dbg: (...args) => dbg('background task settle:', ...args) });
+  // shellId → the exit code the events reported (a `shell_completed`
+  // notification, a `read_bash` result), and the ends already noted
+  // (taskId → { body, exitCode, registryStatus }): a detached shell's code
+  // usually comes with the `read_bash` after its end, and is posted then.
+  const shellExitCodes = new Map();
+  const postedSettles = new Map();
   // When a shell settled and the continuation it should trigger has not opened
   // yet. Holds the runtime for `continuationGraceMs`; cleared by the
   // continuation opening, or by the grace expiring on a runtime that decided it
@@ -1541,6 +1590,7 @@ export function createCopilotSdkSessionRunner({
           startedAt,
           stoppable: true,
           ...(task.progressSummary ? { summary: task.progressSummary } : {}),
+          ...shellOutputFields(task),
         });
         continue;
       }
@@ -1560,37 +1610,98 @@ export function createCopilotSdkSessionRunner({
         ...(detail.lastToolCall ? { lastToolCall: detail.lastToolCall } : {}),
         ...(Number.isFinite(detail.totalTokens) && detail.totalTokens > 0 ? { totalTokens: detail.totalTokens } : {}),
         ...(task.progressSummary ? { summary: task.progressSummary } : {}),
+        ...(Number.isInteger(detail.steps) ? { steps: detail.steps } : {}),
       });
     }
     return cards;
   }
 
+  /** Where the task console reads a shell's output: its own log, or the spool mirror. */
+  function shellOutputFields(task) {
+    const logPath = String(task.logPath || '').trim();
+    if (logPath) return { outputPath: logPath, outputKind: 'file' };
+    if (spool && shellOutputMirror.has(task.id)) {
+      try { return { outputPath: spool.pathFor(task.id), outputKind: 'spool' }; } catch {}
+    }
+    return {};
+  }
+
   /**
    * Mirror the live background work into the relay's task panel (REPLACE
    * semantics, the same route the Claude worker publishes on). Set changes
    * publish at once; enrichment-only changes (a tool call, tokens) ride a
    * trailing throttle. Advisory: a failed post never disturbs events.
+   *
+   * A set equal to the last one the relay TOOK (or to the one on its way)
+   * is not sent again: the signature is recorded when the post succeeds, so
+   * a failed post is retried by the next publish instead of being
+   * remembered as sent.
+   * `resync`: the relay asked for the set again on a heartbeat (it
+   * restarted, or a post was lost); that goes out whatever the signature
+   * says, flagged. Returns the post.
    */
-  function publishBackgroundTasks({ immediate = false } = {}) {
+  function publishBackgroundTasks({ immediate = false, resync = false } = {}) {
     const run = () => {
       if (taskPublishTimer) {
         clearTimeout(taskPublishTimer);
         taskPublishTimer = null;
       }
-      const tasks = sessionRpc.tasks ? registryCards() : shellTrackerCards();
+      const tasks = currentTaskCards();
       const signature = JSON.stringify(tasks);
-      if (signature === lastPublishedTasksSignature) return;
-      lastPublishedTasksSignature = signature;
-      api('POST', '/api/background-tasks', { conversationId: sdkSessionId, tasks })
-        .catch((error) => dbg('background task publish failed', error?.message || String(error)));
+      const unchanged = inFlightTasksSignature === null
+        ? signature === lastPublishedTasksSignature
+        : signature === inFlightTasksSignature;
+      if (!resync && unchanged) return Promise.resolve();
+      const seq = ++taskPublishSeq;
+      inFlightTasksSignature = signature;
+      return api('POST', '/api/background-tasks', {
+        conversationId: sdkSessionId,
+        tasks,
+        order: { epoch: taskSetEpoch, seq },
+        ...(resync ? { resync: true } : {}),
+      })
+        .then((answer) => {
+          // Only the newest post says what the relay holds now.
+          if (seq !== taskPublishSeq) return;
+          inFlightTasksSignature = null;
+          if (answer?.stale === true) {
+            // Turned away, not taken: nothing is recorded as sent, and a
+            // heartbeat is asked for (at most one per ten seconds; the
+            // periodic beat repeats the relay's request anyway).
+            dbg('the relay dropped the newest background task set', answer.reason || '');
+            if (Date.now() - taskSetStaleNotedAt < 10_000) return;
+            taskSetStaleNotedAt = Date.now();
+            try { onBackgroundTaskSetStale(); } catch {}
+            return;
+          }
+          lastPublishedTasksSignature = signature;
+        })
+        .catch((error) => {
+          // Not taken: the signature stays at what the relay last took, so
+          // the next publish of this set is sent, not skipped.
+          if (seq === taskPublishSeq) inFlightTasksSignature = null;
+          dbg('background task publish failed', error?.message || String(error));
+        });
     };
-    if (immediate || !(taskPublishThrottleMs > 0)) {
-      run();
-      return;
-    }
-    if (taskPublishTimer) return;
+    if (resync || immediate || !(taskPublishThrottleMs > 0)) return run();
+    if (taskPublishTimer) return Promise.resolve();
     taskPublishTimer = setTimeout(run, taskPublishThrottleMs);
     taskPublishTimer.unref?.();
+    return Promise.resolve();
+  }
+
+  function currentTaskCards() {
+    return sessionRpc.tasks ? registryCards() : shellTrackerCards();
+  }
+
+  /** The ids of the live background tasks, for the heartbeat's digest. */
+  function backgroundTaskIds() {
+    return currentTaskCards().map((task) => task.taskId);
+  }
+
+  /** The relay asked for the task set again (heartbeat answer). */
+  function resyncBackgroundTasks() {
+    return publishBackgroundTasks({ resync: true });
   }
 
   // ------------------------------------------------------- background tasks --
@@ -1620,6 +1731,8 @@ export function createCopilotSdkSessionRunner({
         model: String(data.model || '').trim(),
         lastToolCall: '',
         totalTokens: 0,
+        // Tool calls so far: the panel row's step count.
+        steps: 0,
         startedAt: Date.now(),
       });
       scheduleTaskRefresh();
@@ -1644,6 +1757,7 @@ export function createCopilotSdkSessionRunner({
       const detail = agentDetails.get(agentId);
       if (type === 'tool.execution_start') {
         detail.lastToolCall = formatToolActivityText(data.toolName, data.arguments);
+        detail.steps += 1;
         publishBackgroundTasks();
       } else if (type === 'assistant.usage') {
         const used = (Number(data.inputTokens) || 0) + (Number(data.outputTokens) || 0);
@@ -1654,6 +1768,9 @@ export function createCopilotSdkSessionRunner({
       } else if (type === 'subagent.completed' || type === 'subagent.failed') {
         const total = Number(data.totalTokens);
         if (Number.isFinite(total) && total > 0) detail.totalTokens = total;
+        // The runtime's own count wins over the events this worker saw.
+        const toolCalls = Number(data.totalToolCalls);
+        if (Number.isFinite(toolCalls) && toolCalls >= 0) detail.steps = Math.floor(toolCalls);
         scheduleTaskRefresh();
       }
     }
@@ -1696,6 +1813,8 @@ export function createCopilotSdkSessionRunner({
     }
     if (session !== target) return;
     taskRefreshFailures = 0;
+    const listedById = new Map((Array.isArray(listed?.tasks) ? listed.tasks : [])
+      .map((task) => [String(task?.id || '').trim(), task]));
     const next = new Map();
     for (const task of Array.isArray(listed?.tasks) ? listed.tasks : []) {
       const id = String(task?.id || '').trim();
@@ -1711,6 +1830,10 @@ export function createCopilotSdkSessionRunner({
         next.set(id, { ...task, id, status, progressSummary: backgroundTasks.get(id)?.progressSummary || '' });
       }
     }
+    // Tasks that left the live set, with where a shell's output is (before
+    // its mirror ends below).
+    const departed = [...backgroundTasks.values()].filter((task) => !next.has(task.id));
+    const departedOutput = new Map(departed.map((task) => [task.id, task.type === 'shell' ? shellOutputFields(task) : {}]));
     // Progress lines for the live set: the agent's latest intent / last
     // activity, a shell's last output line. One RPC per live task per refresh
     // (refreshes are debounced), best effort.
@@ -1719,26 +1842,68 @@ export function createCopilotSdkSessionRunner({
         try {
           const progress = (await askRuntime('tasks.getProgress', () => target.rpc.tasks.getProgress({ id: task.id })))?.progress || null;
           task.progressSummary = summarizeTaskProgress(progress);
+          mirrorShellProgress(task, progress);
         } catch { /* a card without a progress line */ }
       }
+      // A mirrored shell that just left the live set: its last window, once
+      // (the runtime still tracks a finished task), then the mirror ends.
+      for (const id of shellOutputMirror.ids()) {
+        if (next.has(id)) continue;
+        try {
+          const progress = (await askRuntime('tasks.getProgress', () => target.rpc.tasks.getProgress({ id })))?.progress || null;
+          if (progress?.type === 'shell') shellOutputMirror.mirror(id, progress.recentOutput);
+        } catch { /* the file keeps what it had */ }
+        shellOutputMirror.forget(id);
+      }
     }
     if (session !== target) return;
     const setChanged = next.size !== backgroundTasks.size
       || [...next.keys()].some((id) => !backgroundTasks.has(id));
     backgroundTasks = next;
+    // How they ended: the registry's finished entry (its status, an agent's
+    // result) and a shell's exit code.
+    for (const task of departed) {
+      if (task.type !== 'shell' && task.type !== 'agent') continue;
+      const finished = listedById.get(task.id) || task;
+      const shell = task.type === 'shell';
+      postTaskSettle(task.id, {
+        ...settleForTask(finished, { exitCode: shell ? (shellExitCodes.get(task.id) ?? null) : null }),
+        description: task.description || task.displayName || task.command || (shell ? 'Background shell' : 'Background agent'),
+        taskType: shell ? 'local_bash' : 'local_agent',
+        startedAt: Date.parse(String(task.startedAt || '')) || null,
+        ...(task.toolCallId ? { toolUseId: String(task.toolCallId) } : {}),
+        ...(departedOutput.get(task.id) || {}),
+      }, { registryStatus: String(finished.status || '') });
+    }
     publishBackgroundTasks({ immediate: setChanged });
     // The lifecycle poll (every `lifecyclePollMs`) picks the new set up; a
     // re-evaluation here would re-schedule a refresh and spin.
   }
 
+  /**
+   * An attached shell's recent-output window into the spool (a detached one
+   * writes its own log). The refresh cadence is the registry's, unchanged:
+   * the window only stops being thrown away.
+   */
+  function mirrorShellProgress(task, progress) {
+    if (task.type !== 'shell' || progress?.type !== 'shell') return;
+    if (String(task.logPath || '').trim()) return;
+    shellOutputMirror.mirror(task.id, progress.recentOutput);
+  }
+
   function summarizeTaskProgress(progress) {
     if (!progress || typeof progress !== 'object') return '';
     if (progress.type === 'agent') {
+      // A spinner or status line ("⟳ Thinking…") says nothing the row does
+      // not; the newest line with content does, else none.
       const intent = String(progress.latestIntent || '').trim();
-      if (intent) return intent.slice(0, 300);
+      if (intent && !isTransientProgressText(intent)) return intent.slice(0, 300);
       const lines = Array.isArray(progress.recentActivity) ? progress.recentActivity : [];
-      const last = lines.length ? String(lines[lines.length - 1]?.message || '').trim() : '';
-      return last.slice(0, 300);
+      for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = String(lines[index]?.message || '').trim();
+        if (line && !isTransientProgressText(line)) return line.slice(0, 300);
+      }
+      return '';
     }
     if (progress.type === 'shell') {
       const output = String(progress.recentOutput || '').trim();
@@ -1910,7 +2075,46 @@ export function createCopilotSdkSessionRunner({
     dbg(`copilot session rpc surfaces: queue=${sessionRpc.queue} interruptMainTurn=${sessionRpc.interruptMainTurn} tasks=${sessionRpc.tasks}`);
   }
 
+  /** A shell's exit code from an event; a settle already posted without it goes again. */
+  function noteShellExit(event) {
+    let exit = null;
+    try { exit = shellExitFromEvent(event); } catch {}
+    if (!exit) return;
+    shellExitCodes.set(exit.shellId, exit.exitCode);
+    while (shellExitCodes.size > 200) shellExitCodes.delete(shellExitCodes.keys().next().value);
+    const posted = postedSettles.get(exit.shellId);
+    if (!posted || posted.exitCode !== null || posted.body.taskType !== 'local_bash') return;
+    postTaskSettle(exit.shellId, {
+      ...posted.body,
+      ...settleForTask({ type: 'shell', status: posted.registryStatus || '' }, { exitCode: exit.exitCode }),
+    }, { registryStatus: posted.registryStatus });
+  }
+
+  /**
+   * Tell the relay how a background task ended (advisory, kept on failure).
+   * An end nothing has told yet (`unknown`) is only noted: the relay already
+   * calls a task that left its set without a word unknown, and an exit code
+   * that comes later is posted then.
+   */
+  function postTaskSettle(taskId, { status, exitCode, summary, ...rest }, { registryStatus } = {}) {
+    const id = String(taskId || '').trim();
+    if (!id) return;
+    const body = {
+      conversationId: sdkSessionId,
+      taskId: id,
+      status,
+      summary: summary || null,
+      ...rest,
+      ...(Number.isInteger(exitCode) ? { exitCode } : {}),
+    };
+    postedSettles.set(id, { body, exitCode: Number.isInteger(exitCode) ? exitCode : null, registryStatus: registryStatus || '' });
+    while (postedSettles.size > 200) postedSettles.delete(postedSettles.keys().next().value);
+    if (status === 'unknown') return;
+    void keptTaskSettles.post('/api/background-task-settled', body);
+  }
+
   function observeBackgroundShells(event) {
+    noteShellExit(event);
     let changed;
     try {
       changed = backgroundShells.observe(event);
@@ -1924,6 +2128,17 @@ export function createCopilotSdkSessionRunner({
     }
     for (const shell of changed.settled) {
       dbg('detached shell settled', shell.shellId);
+      // Without the task registry the tracker's set is the panel's: the end
+      // of a shell it listed is told here (an id it never saw open, as a
+      // foreground shell's result names one, was never a task).
+      if (!sessionRpc.tasks && shell.startedAt) {
+        postTaskSettle(shell.shellId, {
+          ...settleForTask({ type: 'shell', status: '' }, { exitCode: shellExitCodes.get(shell.shellId) ?? null }),
+          description: shell.description || 'Detached shell',
+          taskType: 'local_bash',
+          startedAt: shell.startedAt || null,
+        });
+      }
       const note = describeSettledShell(shell);
       // Only carried when there is no turn to publish into: inside a turn the
       // normalizer already narrates the `read_bash` that reads the output. A
@@ -4679,6 +4894,7 @@ export function createCopilotSdkSessionRunner({
   async function dispose() {
     disposed = true;
     stopLifecycleTimer();
+    clearInterval(spoolSweepTimer);
     if (queueLaneTimer) {
       clearTimeout(queueLaneTimer);
       queueLaneTimer = null;
@@ -4700,6 +4916,10 @@ export function createCopilotSdkSessionRunner({
     steeringState,
     getSettleFailed,
     acknowledgeSettleFailed,
+    backgroundTaskIds,
+    resyncBackgroundTasks,
+    // The relay answered a heartbeat: settle notices kept for it go out.
+    flushKeptTaskSettles: () => keptTaskSettles.flush(),
     cancelPushedMessage,
     // The task panel's per-card Stop (`rpc.tasks.cancel`); also what a
     // subagent lane's Stop tries — the runtime tracks sync agents in the same
@@ -4726,6 +4946,7 @@ export function createCopilotSdkSessionRunner({
       ? new Promise((resolve) => { setTimeout(resolve, taskRefreshMs + 5); }).then(() => taskRefreshChain)
       : taskRefreshChain),
     // Test seams / observability.
+    _publishBackgroundTasks: publishBackgroundTasks,
     _getState: () => ({
       hasClient: !!client,
       hasSession: !!session,

package/server/copilot-worker/copilot-sdk-session-worker.mjs

@@ -121,6 +121,7 @@ async function main() {
     // A message became (or stopped being) cancellable: report it now rather
     // than on the next 10 s heartbeat (coalesced by the controller).
     onCancellableChange: () => heartbeat?.requestPulse(),
+    onBackgroundTaskSetStale: () => heartbeat?.requestPulse(),
     canHandBackHeldDelivery: () => linkBridge.canHandBackHeldDelivery(),
     dbg,
   });
@@ -144,6 +145,13 @@ async function main() {
     getSteeringState: () => turnRunner.steeringState(),
     getSettleFailed: () => turnRunner.getSettleFailed(),
     onSettleFailedHandled: (ids) => turnRunner.acknowledgeSettleFailed(ids),
+    // The relay holds the task set in memory only: the digest of the live
+    // task ids rides every beat, and a relay that is out of step (it
+    // restarted, a post was lost) asks for the set again.
+    getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
+    onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
+    // The relay answered: settle notices it missed go out.
+    onAnswered: () => turnRunner.flushKeptTaskSettles?.(),
   });
 
   const wsLink = createWorkerWebSocketLink({

package/server/copilot-worker/copilot-shell-output-mirror.mjs

@@ -0,0 +1,94 @@
+// An attached Copilot shell keeps its output in the runtime only: the worker
+// sees it as `tasks.getProgress().recentOutput`, a sliding window of the last
+// lines, on every registry refresh. The task console needs a file, so each
+// window's new part is appended to the session's spool
+// (shared/worker-runtime/task-output-spool.mjs).
+//
+// Consecutive windows overlap: the new part is what follows the longest
+// suffix of the previous window that is also a prefix of the new one. With no
+// overlap at all (more output between two refreshes than the window holds)
+// the lines in between are lost; the new window is appended whole after a
+// line break, and the modal says the output is mirrored from a window.
+
+/** The runtime's placeholder for a shell that has printed nothing yet. */
+const NO_OUTPUT_PLACEHOLDER = '(no output yet)';
+
+/**
+ * Length of the longest suffix of `previous` that is a prefix of `next`
+ * (prefix function over `next + sep + previous`, linear time: windows are
+ * kilobytes and are compared on every refresh).
+ */
+export function overlapLength(previous, next) {
+  const a = String(next || '');
+  const b = String(previous || '');
+  if (!a || !b) return 0;
+  const n = a.length;
+  const fail = new Int32Array(n);
+  for (let i = 1, k = 0; i < n; i += 1) {
+    while (k > 0 && a[i] !== a[k]) k = fail[k - 1];
+    if (a[i] === a[k]) k += 1;
+    fail[i] = k;
+  }
+  let k = 0;
+  for (let i = 0; i < b.length; i += 1) {
+    while (k > 0 && (k === n || b[i] !== a[k])) k = fail[k - 1];
+    if (b[i] === a[k]) k += 1;
+  }
+  return k;
+}
+
+/**
+ * What to append when the window moves from `previous` to `next`:
+ * `{ text, gap }`, `gap` true when the windows share nothing.
+ */
+export function newOutputSuffix(previous, next) {
+  const before = String(previous || '');
+  const after = String(next || '');
+  if (!after || after === before) return { text: '', gap: false };
+  if (!before) return { text: after, gap: false };
+  if (after.startsWith(before)) return { text: after.slice(before.length), gap: false };
+  const overlap = overlapLength(before, after);
+  if (overlap > 0) return { text: after.slice(overlap), gap: false };
+  return { text: after, gap: true };
+}
+
+export function createShellOutputMirror({ spool, dbg = () => {} } = {}) {
+  // taskId → { window, endsWithNewline }
+  const mirrors = new Map();
+
+  /** Feed one `recentOutput` window; returns the text appended. */
+  function mirror(taskId, recentOutput) {
+    const id = String(taskId || '').trim();
+    if (!id || !spool) return '';
+    const state = mirrors.get(id) || { window: '', endsWithNewline: true };
+    mirrors.set(id, state);
+    const window = typeof recentOutput === 'string' ? recentOutput : '';
+    if (!window || window.trim() === NO_OUTPUT_PLACEHOLDER) return '';
+    const { text, gap } = newOutputSuffix(state.window, window);
+    state.window = window;
+    if (!text) return '';
+    const written = gap && !state.endsWithNewline ? `\n${text}` : text;
+    const result = spool.append(id, written);
+    if (result && result.ok === false) dbg('task output spool append failed', id);
+    state.endsWithNewline = written.endsWith('\n');
+    return written;
+  }
+
+  /** Whether a window of this task was ever fed (its spool file is named). */
+  function has(taskId) {
+    return mirrors.has(String(taskId || '').trim());
+  }
+
+  /** The task ended: no more windows; the file stays for the relay. */
+  function forget(taskId) {
+    const id = String(taskId || '').trim();
+    if (!mirrors.delete(id)) return;
+    try { spool?.end?.(id); } catch {}
+  }
+
+  function ids() {
+    return [...mirrors.keys()];
+  }
+
+  return { mirror, has, forget, ids };
+}

package/server/copilot-worker/copilot-task-settle.mjs

@@ -0,0 +1,96 @@
+// How a Copilot background task ended, for the relay's settle post
+// (`/api/background-task-settled`), with no I/O so it can be tested against
+// the runtime's payloads.
+//
+// What the runtime gives (SDK 1.0.17, generated/rpc.d.ts and
+// generated/session-events.d.ts):
+//
+//  - `tasks.list()` keeps a finished task with `status` completed, failed or
+//    cancelled (`TaskStatus`); an agent adds `result` (its result text) or
+//    `error`. A shell entry (`TaskShellInfo`) carries no exit code.
+//  - `system.notification` of kind `shell_completed` (an attached shell) has
+//    an optional `exitCode`; `shell_detached_completed` has none, and its
+//    text only says to read the shell with `read_bash`.
+//  - a `read_bash` (or `bash`) result ends with
+//    `<detached command with shellId: 1 completed with exit code 0>` once
+//    the shell is done: the detached shell's exit code, when the model reads
+//    it.
+//
+// A progress line (`tasks.getProgress`: the agent's latest intent, its last
+// activity line) is how the task is doing, not how it ended: a spinner or
+// status line such as "⟳ Thinking…" is never a summary.
+
+// Spinner and progress glyphs a status line starts with.
+const SPINNER_PREFIX_RE = /^[\s⟳↻↺⏳⌛◌◐◓◑◒○●◴◷◶◵⠁-⣿·•…]+/u;
+const STATUS_WORD_RE = /^(?:thinking|working|waiting|running|loading|processing|starting|reasoning|planning)(?:\s*(?:\.{2,}|…))?$/i;
+// `<detached command with shellId: 1 completed with exit code 0>`,
+// `<shellId: 0 completed with exit code 0>`.
+const SHELL_EXIT_TEXT_RE = /shellId:\s*([^\s>,]+)[^<>]*?completed with exit code\s+(-?\d+)/i;
+
+const SUMMARY_MAX = 500;
+
+function text(value) {
+  return String(value ?? '').trim();
+}
+
+/** Whether a progress line is a transient status ("⟳ Thinking…") rather than content. */
+export function isTransientProgressText(value) {
+  const line = text(value);
+  if (!line) return true;
+  const glyphs = SPINNER_PREFIX_RE.exec(line)?.[0] || '';
+  const rest = line.slice(glyphs.length).trim();
+  if (!rest) return true;
+  // A status word alone, with or without a spinner in front.
+  return STATUS_WORD_RE.test(rest);
+}
+
+/**
+ * The exit code an event reports for a shell: `{ shellId, exitCode }` or
+ * null. From a `shell_completed` notification that has one, or from a shell
+ * tool's result text.
+ */
+export function shellExitFromEvent(event) {
+  const type = text(event?.type);
+  const data = event?.data && typeof event.data === 'object' ? event.data : {};
+  if (type === 'system.notification') {
+    const kind = data.kind && typeof data.kind === 'object' ? data.kind : {};
+    const shellId = text(kind.shellId);
+    if (kind.type === 'shell_completed' && shellId && Number.isInteger(kind.exitCode)) {
+      return { shellId, exitCode: kind.exitCode };
+    }
+    return null;
+  }
+  if (type === 'tool.execution_complete') {
+    const result = data.result && typeof data.result === 'object' ? data.result : {};
+    const match = SHELL_EXIT_TEXT_RE.exec(`${text(result.content)}\n${text(result.detailedContent)}`);
+    if (!match) return null;
+    const exitCode = Number(match[2]);
+    return Number.isInteger(exitCode) ? { shellId: match[1], exitCode } : null;
+  }
+  return null;
+}
+
+/**
+ * How a task that left the live set ended: `{ status, exitCode, summary }`.
+ * `task` is the runtime's entry as `tasks.list()` gives it now (finished),
+ * or the last running one when the list no longer has it; `exitCode` what
+ * the events said for a shell (null when nothing did).
+ */
+export function settleForTask(task, { exitCode = null } = {}) {
+  const status = text(task?.status).toLowerCase();
+  const code = Number.isInteger(exitCode) ? exitCode : null;
+  let settled;
+  if (status === 'cancelled') settled = 'stopped';
+  else if (status === 'failed') settled = 'failed';
+  else if (code !== null) settled = code === 0 ? 'completed' : 'failed';
+  else if (status === 'completed') settled = 'completed';
+  else settled = 'unknown';
+  let summary = null;
+  if (task?.type === 'agent') {
+    const result = text(settled === 'failed' ? (task.error || task.result) : (task.result || task.latestResponse));
+    if (result && !isTransientProgressText(result)) summary = result.slice(0, SUMMARY_MAX);
+  } else if (code !== null) {
+    summary = `exit code ${code}`;
+  }
+  return { status: settled, exitCode: code, summary };
+}