@oar-sh/oar 0.9.11 → 0.9.12

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 };
+}

package/server/db-schema.mjs

@@ -22,6 +22,7 @@ import { migratePreviews } from './migrations/0013-previews.mjs';
 import { migrateConversationGroups } from './migrations/0014-conversation-groups.mjs';
 import { migrateConversationGroupPosition } from './migrations/0015-conversation-group-position.mjs';
 import { migrateShareAccessLog } from './migrations/0016-share-access-log.mjs';
+import { migrateConversationHistoryIndexes } from './migrations/0017-conversation-history-indexes.mjs';
 import { migrateImageConversationSchema } from './repositories/image-conversation-repository.mjs';
 
 // Mirrors DEFAULT_RELAY_MODE in server-runtime.mjs; used only by the one-time
@@ -836,6 +837,14 @@ try {
   console.warn(`[shares] migration 0016 failed; retrying on next boot: ${error?.message || error}`);
 }
 
+// Two indexes for the history of long conversations. Only speed depends on
+// them, so a failure is logged and retried next boot like 0016.
+try {
+  migrateConversationHistoryIndexes(db);
+} catch (error) {
+  console.warn(`[history] migration 0017 failed; retrying on next boot: ${error?.message || error}`);
+}
+
 const runtimeSessionColumns = db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((c) => c.name);
 if (runtimeSessionColumns.length) {
   if (!runtimeSessionColumns.includes('strategy')) {

package/server/grok-worker/acp-host-services.mjs

@@ -11,6 +11,7 @@
  * If a capability is dropped here, drop it from the initialize payload too.
  */
 import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import fs from 'node:fs/promises';
 import { windowsSystemToolPath } from '../../shared/windows-system-tools.mjs';
 
@@ -37,10 +38,18 @@ export function createAcpHostServices({
   spawnImpl = spawn,
   spawnSyncImpl = spawnSync,
   fsImpl = fs,
+  // Told about every terminal's life (grok-background-tasks.mjs publishes
+  // them as background tasks): `started`, `output`, `killed`, `released`,
+  // `exited`. Advisory: an observer that throws never disturbs a terminal.
+  taskObserver = null,
   dbg = () => {},
 } = {}) {
   const terminals = new Map();
   let nextTerminalId = 1;
+  // Terminal ids become task ids and spool file names on the relay side: a
+  // fresh set of host services (the handle is rebuilt after a failed turn)
+  // must not reuse the ids of the one before it.
+  const terminalIdPrefix = `term-${randomBytes(3).toString('hex')}`;
   let inflightRequests = 0;
   let cachedWindowsShell = '';
   let disposed = false;
@@ -77,9 +86,21 @@ export function createAcpHostServices({
     return { file: shell, args: ['-c', command] };
   }
 
+  function tell(hook, ...args) {
+    const fn = taskObserver?.[hook];
+    if (typeof fn !== 'function') return;
+    try {
+      const result = fn(...args);
+      if (result && typeof result.catch === 'function') result.catch(() => {});
+    } catch (error) {
+      dbg('terminal observer failed', hook, error?.message || String(error));
+    }
+  }
+
   function appendOutput(entry, chunk) {
     const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8');
     entry.lastActivityAt = Date.now();
+    tell('output', entry.terminalId, buf);
     entry.chunks.push(buf);
     entry.byteLength += buf.length;
     // ACP truncates from the start of the output: the most recent bytes win.
@@ -101,6 +122,7 @@ export function createAcpHostServices({
     if (entry.exitStatus) return;
     entry.exitStatus = exitStatus;
     for (const resolve of entry.exitWaiters.splice(0)) resolve(exitStatus);
+    tell('exited', entry.terminalId, exitStatus);
   }
 
   function getTerminal(terminalId) {
@@ -125,9 +147,12 @@ export function createAcpHostServices({
       windowsHide: true,
       shell: false,
     });
-    const terminalId = `term-${nextTerminalId++}`;
+    const terminalId = `${terminalIdPrefix}-${nextTerminalId++}`;
     const entry = {
       terminalId,
+      // What the task panel shows for it.
+      command: [command, ...(Array.isArray(params.args) ? params.args.map(String) : [])].join(' '),
+      startedAt: Date.now(),
       proc,
       chunks: [],
       byteLength: 0,
@@ -152,6 +177,12 @@ export function createAcpHostServices({
       });
     });
     terminals.set(terminalId, entry);
+    tell('started', {
+      terminalId,
+      command: entry.command,
+      startedAt: entry.startedAt,
+      kill: () => killEntryProcess(entry),
+    });
     dbg('terminal/create', terminalId, command.slice(0, 160));
     return { terminalId };
   }
@@ -188,15 +219,19 @@ export function createAcpHostServices({
   }
 
   function terminalKill(params = {}) {
-    killEntryProcess(getTerminal(params.terminalId));
+    const entry = getTerminal(params.terminalId);
+    if (!entry.exitStatus) tell('killed', entry.terminalId);
+    killEntryProcess(entry);
     return null;
   }
 
   function terminalRelease(params = {}) {
     const entry = terminals.get(String(params?.terminalId || ''));
     if (!entry) return null;
+    if (!entry.exitStatus) tell('killed', entry.terminalId);
     killEntryProcess(entry);
     terminals.delete(entry.terminalId);
+    tell('released', entry.terminalId);
     return null;
   }
 
@@ -270,7 +305,11 @@ export function createAcpHostServices({
 
   function disposeAll() {
     disposed = true;
-    for (const entry of terminals.values()) killEntryProcess(entry);
+    for (const entry of terminals.values()) {
+      if (!entry.exitStatus) tell('killed', entry.terminalId);
+      killEntryProcess(entry);
+      tell('released', entry.terminalId);
+    }
     terminals.clear();
   }
 

package/server/grok-worker/grok-background-tasks.mjs

@@ -0,0 +1,241 @@
+/**
+ * The Grok worker's background-tasks publisher: every ACP terminal the agent
+ * opens (acp-host-services.mjs) is a shell row in the composer's
+ * background-tasks panel, with a console the relay reads from the session's
+ * spool file (shared/worker-runtime/task-output-spool.mjs), a Stop that kills
+ * the terminal, and a settle notice with the exit code when it ends.
+ *
+ * Same relay contract as the Claude and Copilot workers: the set is posted
+ * whole (REPLACE semantics) with its place in this worker's order
+ * (`{ epoch, seq }`); the heartbeat carries the live ids and the relay asks
+ * for the set again when its own differs; a settle notice the relay was not
+ * there to take is kept and sent again after the next answered heartbeat.
+ */
+import { createKeptPosts } from '../../shared/worker-runtime/kept-posts.mjs';
+import { createTaskOutputSpool } from '../../shared/worker-runtime/task-output-spool.mjs';
+
+const MAX_DESCRIPTION_CHARS = 500;
+const SPOOL_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+// Ended terminals remembered for a late exit after their release.
+const MAX_TRACKED_TERMINALS = 200;
+// ACP runs every shell command through a terminal, most of them over in a
+// moment; only one that lives this long becomes a row (and later a settle
+// notice), so a `ls` never crowds the panel's ended rows.
+export const GROK_TERMINAL_PUBLISH_AFTER_MS = 2_000;
+
+export function createGrokTaskPublisher({
+  api,
+  sdkSessionId,
+  spool = null,
+  // The relay dropped the newest set: ask for a heartbeat (the worker wires
+  // it to requestPulse), at most once per ten seconds.
+  onBackgroundTaskSetStale = () => {},
+  publishAfterMs = GROK_TERMINAL_PUBLISH_AFTER_MS,
+  now = () => Date.now(),
+  dbg = () => {},
+} = {}) {
+  const taskSpool = spool || (() => {
+    try { return createTaskOutputSpool({ sessionId: sdkSessionId }); } catch (error) {
+      dbg('task output spool unavailable', error?.message || String(error));
+      return null;
+    }
+  })();
+  // terminalId → { taskId, description, startedAt, kill, live, published,
+  // publishTimer, exited, stopRequested, killRequested }. `live`: in the set.
+  const terminals = new Map();
+  const keptSettles = createKeptPosts({ api, dbg: (...args) => dbg('background task settle:', ...args) });
+  const epoch = now();
+  let seq = 0;
+  let staleNotedAt = 0;
+
+  // Ended tasks' files are kept about an hour for the relay; swept at start
+  // and hourly.
+  const sweep = () => {
+    try { taskSpool?.sweep(); } catch (error) { dbg('task output spool sweep failed', error?.message || String(error)); }
+  };
+  sweep();
+  const sweepTimer = setInterval(sweep, SPOOL_SWEEP_INTERVAL_MS);
+  sweepTimer.unref?.();
+
+  function outputPathFor(taskId) {
+    if (!taskSpool) return '';
+    try { return taskSpool.pathFor(taskId); } catch { return ''; }
+  }
+
+  function rowOf(entry) {
+    const outputPath = outputPathFor(entry.taskId);
+    return {
+      taskId: entry.taskId,
+      taskType: 'local_bash',
+      description: entry.description,
+      startedAt: entry.startedAt,
+      stoppable: true,
+      ...(outputPath ? { outputPath, outputKind: 'spool' } : {}),
+    };
+  }
+
+  function liveEntries() {
+    return [...terminals.values()].filter((entry) => entry.live);
+  }
+
+  function publish({ resync = false } = {}) {
+    const order = { epoch, seq: ++seq };
+    return Promise.resolve()
+      .then(() => api('POST', '/api/background-tasks', {
+        conversationId: sdkSessionId,
+        tasks: liveEntries().map(rowOf),
+        order,
+        ...(resync ? { resync: true } : {}),
+      }))
+      .then((answer) => {
+        // `stale` for the newest post: the relay holds no current set of
+        // this worker. An older one was only overtaken.
+        if (answer?.stale !== true || order.seq !== seq) return;
+        dbg('the relay dropped the newest background task set', answer.reason || '');
+        if (now() - staleNotedAt < 10_000) return;
+        staleNotedAt = now();
+        try { onBackgroundTaskSetStale(); } catch {}
+      })
+      .catch((error) => {
+        dbg('background task publish failed', error?.message || String(error));
+      });
+  }
+
+  function forgetOldest() {
+    while (terminals.size > MAX_TRACKED_TERMINALS) {
+      const oldest = [...terminals.entries()].find(([, entry]) => entry.exited || entry.released);
+      if (!oldest) break;
+      clearTimeout(oldest[1].publishTimer);
+      terminals.delete(oldest[0]);
+    }
+  }
+
+  /** `terminal/create` spawned a process. */
+  function started({ terminalId, command = '', startedAt = now(), kill = () => {} } = {}) {
+    const taskId = String(terminalId || '').trim();
+    if (!taskId) return Promise.resolve();
+    const entry = {
+      taskId,
+      description: String(command || '').trim().slice(0, MAX_DESCRIPTION_CHARS) || 'Terminal',
+      startedAt,
+      kill,
+      live: false,
+      published: false,
+      publishTimer: null,
+      exited: false,
+      released: false,
+      stopRequested: false,
+      killRequested: false,
+    };
+    terminals.set(taskId, entry);
+    forgetOldest();
+    // Output is spooled from the first byte (output() below), so the console
+    // is complete when the row appears.
+    const show = () => {
+      entry.publishTimer = null;
+      if (entry.exited || entry.released) return Promise.resolve();
+      entry.live = true;
+      entry.published = true;
+      return publish();
+    };
+    if (!(publishAfterMs > 0)) return show();
+    entry.publishTimer = setTimeout(show, publishAfterMs);
+    entry.publishTimer.unref?.();
+    return Promise.resolve();
+  }
+
+  /** A chunk of the terminal's stdout/stderr, as it arrives. */
+  function output(terminalId, chunk) {
+    const taskId = String(terminalId || '').trim();
+    if (!taskId || !taskSpool || !terminals.has(taskId)) return;
+    const result = taskSpool.append(taskId, chunk);
+    if (result && result.ok === false) dbg('task output spool append failed', taskId);
+  }
+
+  /** The agent killed its own terminal (terminal/kill or release): a stop, not a failure. */
+  function killed(terminalId) {
+    const entry = terminals.get(String(terminalId || '').trim());
+    if (entry && !entry.exited) entry.killRequested = true;
+  }
+
+  /** `terminal/release`: the agent is done with it; the row goes. */
+  function released(terminalId) {
+    const entry = terminals.get(String(terminalId || '').trim());
+    if (!entry || entry.released) return Promise.resolve();
+    entry.released = true;
+    clearTimeout(entry.publishTimer);
+    entry.publishTimer = null;
+    if (!entry.live) return Promise.resolve();
+    entry.live = false;
+    return publish();
+  }
+
+  /** The process exited: say how, then publish the set without it. */
+  async function exited(terminalId, exitStatus = {}) {
+    const taskId = String(terminalId || '').trim();
+    const entry = terminals.get(taskId);
+    if (!entry || entry.exited) return;
+    entry.exited = true;
+    clearTimeout(entry.publishTimer);
+    entry.publishTimer = null;
+    const wasLive = entry.live;
+    entry.live = false;
+    try { taskSpool?.end?.(taskId); } catch {}
+    // Never shown: nothing to settle (its spool file is swept with the rest).
+    if (!entry.published) return;
+    const exitCode = Number.isInteger(exitStatus?.exitCode) ? exitStatus.exitCode : null;
+    const signal = String(exitStatus?.signal || '').trim();
+    const status = entry.stopRequested || entry.killRequested
+      ? 'stopped'
+      : (exitCode === 0 ? 'completed' : 'failed');
+    const outputPath = outputPathFor(taskId);
+    await keptSettles.post('/api/background-task-settled', {
+      conversationId: sdkSessionId,
+      taskId,
+      toolUseId: null,
+      status,
+      summary: exitCode !== null ? `exit code ${exitCode}` : (signal ? `killed by ${signal}` : null),
+      description: entry.description,
+      taskType: 'local_bash',
+      startedAt: entry.startedAt,
+      // Absent rather than null: a killed process has no exit code.
+      ...(exitCode !== null ? { exitCode } : {}),
+      ...(outputPath ? { outputPath, outputKind: 'spool' } : {}),
+    });
+    if (wasLive) await publish();
+  }
+
+  /** The panel's Stop (worker control `stop_background_task`). */
+  function stop(taskId) {
+    const entry = terminals.get(String(taskId || '').trim());
+    if (!entry || !entry.live || entry.exited) return false;
+    entry.stopRequested = true;
+    try {
+      entry.kill();
+      return true;
+    } catch (error) {
+      dbg('terminal stop failed', entry.taskId, error?.message || String(error));
+      return false;
+    }
+  }
+
+  return {
+    started,
+    output,
+    killed,
+    released,
+    exited,
+    stop,
+    /** The ids of the live terminals, for the heartbeat's digest. */
+    backgroundTaskIds: () => liveEntries().map((entry) => entry.taskId),
+    /** The relay asked for the set again (heartbeat answer). */
+    resync: () => publish({ resync: true }),
+    /** The relay answered a heartbeat: settle notices kept for it go out. */
+    flushKeptSettles: () => keptSettles.flush(),
+    sweep,
+    close() {
+      clearInterval(sweepTimer);
+      for (const entry of terminals.values()) clearTimeout(entry.publishTimer);
+    },
+  };
+}

package/server/grok-worker/grok-sdk-adapter.mjs

@@ -85,6 +85,8 @@ export async function createGrokAgentHandle({
   model = '',
   AcpClientImpl = AcpClient,
   createHostServicesImpl = createAcpHostServices,
+  // Told about every terminal (the worker's background-tasks publisher).
+  taskObserver = null,
   dbg = () => {},
 } = {}) {
   const client = new AcpClientImpl({
@@ -109,7 +111,7 @@ export async function createGrokAgentHandle({
   // The terminal/fs handlers backing the capabilities initialize() advertises.
   // They must be attached before the first prompt, or the agent's first shell
   // command deadlocks the turn waiting on terminal/create.
-  const hostServices = createHostServicesImpl({ cwd, env, dbg });
+  const hostServices = createHostServicesImpl({ cwd, env, dbg, ...(taskObserver ? { taskObserver } : {}) });
   hostServices.attach(client);
 
   await client.initialize();

package/server/grok-worker/grok-session-worker.mjs

@@ -16,6 +16,7 @@ import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-fil
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createGrokTurnRunner } from './grok-turn-runner.mjs';
+import { createGrokTaskPublisher } from './grok-background-tasks.mjs';
 
 // Windows console launch: the launcher names the worker log, this copies
 // stdout/stderr into it. A no-op wherever the launcher redirects instead.
@@ -70,6 +71,16 @@ async function main() {
     abortAckNote: 'grok run cancelled',
     dbg,
   });
+  // Late-bound: the heartbeat controller is built after the runner.
+  let heartbeat = null;
+  // The agent's terminals, published as background tasks with a console
+  // (spooled output), a Stop and a settle notice.
+  const taskPublisher = createGrokTaskPublisher({
+    api,
+    sdkSessionId,
+    onBackgroundTaskSetStale: () => heartbeat?.requestPulse(),
+    dbg,
+  });
   const turnRunner = createGrokTurnRunner({
     api,
     sdkSessionId,
@@ -78,17 +89,23 @@ async function main() {
     command,
     alwaysApprove,
     controlPoller,
+    taskPublisher,
     dbg,
   });
 
   let heartbeatTimer = null;
-  const heartbeat = createHeartbeatController({
+  heartbeat = createHeartbeatController({
     api,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
     getHeartbeatTimer: () => heartbeatTimer,
     setHeartbeatTimer: (timer) => { heartbeatTimer = timer; },
     getActiveQueueMessageId: () => turnRunner.getActiveQueueMessageId(),
+    // The relay holds the task set in memory only: the live terminal ids
+    // ride every beat, and a relay that is out of step asks for the set again.
+    getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
+    onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
+    onAnswered: () => turnRunner.flushKeptTaskSettles(),
   });
 
   const wsLink = createWorkerWebSocketLink({
@@ -96,6 +113,9 @@ async function main() {
     token,
     dbg,
     getSessionReady: () => true,
+    // A relay that just (re)started learns of the terminals from the digest
+    // on the next beat; ask for it now.
+    onServerHello: () => heartbeat.requestPulse(),
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
     onDeliver: async (pending, reason) => {
@@ -111,6 +131,17 @@ async function main() {
         return false;
       }
     },
+    onControl: async (control) => {
+      const type = String(control?.type || '').trim();
+      if (type === 'stop_background_task') {
+        // The panel's Stop on a terminal row: kill its process.
+        const taskId = String(control?.taskId || '').trim();
+        dbg('stop background task control', taskId);
+        turnRunner.stopBackgroundTask(taskId);
+        return;
+      }
+      dbg('unknown worker control ignored', type || '(none)');
+    },
   });
 
   const shutdown = async (signal) => {
@@ -118,6 +149,7 @@ async function main() {
     try { wsLink.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
+    try { taskPublisher.close(); } catch {}
     // Bounded: a hung ACP agent teardown must never leave the process
     // ignoring the supervisor's SIGTERM.
     try {

package/server/grok-worker/grok-turn-runner.mjs

@@ -122,8 +122,12 @@ export function createGrokTurnRunner({
   // gets through ACP `mcpServers`; undefined builds the default for this
   // worker's conversation, null leaves Grok without it.
   oarMcpServer = undefined,
+  // The terminals' background-task rows (grok-background-tasks.mjs), built
+  // by the worker entry; without one no terminal is published.
+  taskPublisher = null,
   dbg = () => {},
 } = {}) {
+  const terminalTasks = taskPublisher;
   // The OAR MCP server gives Grok the relay's real tools — `preview`, and
   // `remote_relay` when remotes are paired — bound to this conversation.
   // `OAR_MCP_SERVER=0` is the operator's way back to the preview instruction
@@ -203,6 +207,7 @@ export function createGrokTurnRunner({
       alwaysApprove,
       nativeSessionId: resumeId,
       model,
+      ...(terminalTasks ? { taskObserver: terminalTasks } : {}),
       // The adapter builds the ACP client and opens the session in one step,
       // so the client it builds must already carry the MCP servers — for
       // session/new and for session/load alike.
@@ -611,6 +616,12 @@ export function createGrokTurnRunner({
     getActiveQueueAttempt,
     isTurnActive,
     dispose,
+    // The terminals as background tasks: the heartbeat's digest and resync,
+    // the panel's Stop, kept settle notices.
+    backgroundTaskIds: () => terminalTasks?.backgroundTaskIds() || [],
+    resyncBackgroundTasks: () => terminalTasks?.resync(),
+    stopBackgroundTask: (taskId) => terminalTasks?.stop(taskId) || false,
+    flushKeptTaskSettles: () => terminalTasks?.flushKeptSettles(),
     setTurnCeilingMs(value) {
       const ms = Number(value);
       turnCeilingMs = Number.isFinite(ms) && ms >= 0 ? ms : null;