@oar-sh/oar 0.9.10 → 0.9.12

package/server/claude-worker/claude-session-process.mjs

@@ -43,6 +43,7 @@ import { createAskUserBridge } from '../../shared/ask-user-bridge.mjs';
 import { createRemoteRelayToolGate } from '../../shared/remote-relay-tool-core.mjs';
 import { buildRelayStopFailure } from '../../shared/relay-stop-failure.mjs';
 import { createTurnLiveness, resolveTurnStallWindows } from '../../shared/worker-runtime/turn-liveness.mjs';
+import { createKeptPosts } from '../../shared/worker-runtime/kept-posts.mjs';
 import {
   ANSWERED_ELSEWHERE_KIND,
   DELIVERY_ANSWERED_ELSEWHERE_TEXT,
@@ -57,6 +58,13 @@ import {
   withSlashCommandGuardContent,
 } from '../../shared/slash-command-guard.mjs';
 import { createUsageLimitTracker } from '../../shared/claude-usage-limit.mjs';
+import {
+  discoverTaskOutputPaths,
+  exitCodeFromSummary,
+  isShellTaskType,
+  outputDirOf,
+  usableOutputPath,
+} from './task-output-discovery.mjs';
 
 /**
  * Which system-prompt append a relay mode gets (claude-sdk-adapter's
@@ -76,6 +84,8 @@ export { STEER_FOLDED_TEXT, STEER_STOPPED_TEXT };
 /** Task types that run a model of their own (vs. bash/monitor/workflow). */
 const AGENT_TASK_TYPES = new Set(['local_agent', 'agent', 'subagent']);
 const MAX_TASK_TOOL_CALL_CHARS = 300;
+/** Output paths remembered per process (one per backgrounded shell). */
+const MAX_TASK_OUTPUT_PATHS = 200;
 
 // ---------------------------------------------------------------------------
 // Workflow progress sources (CLI 2.1.226 on-disk formats)
@@ -459,6 +469,10 @@ export function createClaudeSessionRunner({
   // leaves the CLI's own attribution. Piggybacked on deliveries like the
   // window above.
   getAttribution = () => null,
+  // How long a backgrounded Bash command may run without its own timeout
+  // (ms; the relay's Claude setting). Read at spawn only: the CLI takes it
+  // from its environment, so a change applies to the next process.
+  getBackgroundCommandLimitMs = () => null,
   // The per-conversation thinking state ({enabled, display}); read per turn
   // like the window, so a settings change reaches a running process on its
   // next delivery.
@@ -546,6 +560,10 @@ export function createClaudeSessionRunner({
   // the socket link: a hold withdraws the relay's readiness, and its end
   // re-arms it at once so a held message steers into the resumed turn.
   onDeliveryReadinessChange = () => {},
+  // 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 = () => {},
   // Whether CLI processes carry the relay's `remote_relay` tool
   // (shared/remote-relay-tool-core.mjs). Default: ask the relay.
   remoteRelayToolGate = null,
@@ -604,6 +622,34 @@ export function createClaudeSessionRunner({
   // id → terminalError for settling rows the worker gave up posting; reported
   // in the heartbeat's `settleFailed` until the relay confirms it failed them.
   const settleFailedTerminals = new Map();
+  // Settle notices of background tasks whose post failed (the relay was
+  // away): sent again after the next heartbeat it answers.
+  // Every post of the task set carries its place in this worker's order:
+  // two posts can overtake each other on the way, and the relay applies the
+  // newer one only. `epoch` tells this process from one before it.
+  const taskSetEpoch = Date.now();
+  let taskSetSeq = 0;
+  const nextTaskSetOrder = () => ({ epoch: taskSetEpoch, seq: ++taskSetSeq });
+  let taskSetStaleNotedAt = 0;
+  /**
+   * The relay's answer to a set post. `stale` for the newest one means the
+   * relay holds no current set of this worker; an older one was simply
+   * overtaken. At most one extra heartbeat per ten seconds: the periodic
+   * beat repeats the request anyway.
+   */
+  function noteTaskSetAnswer(answer, order) {
+    if (answer?.stale !== true || order.seq !== taskSetSeq) return;
+    dbg('the relay dropped the newest background task set', answer.reason || '');
+    if (Date.now() - taskSetStaleNotedAt < 10_000) return;
+    taskSetStaleNotedAt = Date.now();
+    try { onBackgroundTaskSetStale(); } catch {}
+  }
+  const postTaskSet = (body) => {
+    const order = nextTaskSetOrder();
+    return api('POST', '/api/background-tasks', { conversationId: sdkSessionId, ...body, order })
+      .then((answer) => noteTaskSetAnswer(answer, order));
+  };
+  const keptTaskSettles = createKeptPosts({ api, dbg: (...args) => dbg('background task settle:', ...args) });
   // Row id → the latest in-flight /api/queue-consumed POST touching it.
   const consumedMarkChains = new Map();
 
@@ -1694,10 +1740,19 @@ export function createClaudeSessionRunner({
    * which renders it as the composer's background-tasks panel. Membership
    * changes post immediately; chatty progress updates are trailing-edge
    * throttled. Advisory: failures must never disturb the stream consumer.
+   *
+   * `resync`: the relay asked for the set again on a heartbeat, because its
+   * own set for this worker differs (it restarted, or a post was lost). The
+   * same set, flagged, and "no tasks" is an answer too. Returns the post.
    */
-  function publishBackgroundTasks({ throttled = false } = {}) {
+  function publishBackgroundTasks({ throttled = false, resync = false } = {}) {
     const processRef = proc;
-    if (!processRef) return;
+    if (!processRef) {
+      if (!resync) return Promise.resolve();
+      return postTaskSet({ tasks: [], resync: true }).catch((error) => {
+        dbg('background task resync failed', error?.message || String(error));
+      });
+    }
     const send = () => {
       processRef.taskPublishTimer = null;
       const tasks = [...processRef.liveTasks.entries()].map(([taskId, task]) => {
@@ -1727,9 +1782,12 @@ export function createClaudeSessionRunner({
           // The workflow digest (poller below) rides the same row; the relay
           // sanitizer whitelists and re-clamps it before storing.
           ...(task.workflowProgress ? { workflowProgress: task.workflowProgress } : {}),
+          ...(agentLike && Number.isInteger(task.steps) ? { steps: task.steps } : {}),
+          // Where the relay reads the task's console from.
+          ...(isShellTaskType(task.taskType) ? taskOutputFields(processRef, taskId) : {}),
         };
       });
-      api('POST', '/api/background-tasks', { conversationId: sdkSessionId, tasks }).catch((error) => {
+      return postTaskSet({ tasks, ...(resync ? { resync: true } : {}) }).catch((error) => {
         dbg('background task publish failed', error?.message || String(error));
       });
     };
@@ -1738,12 +1796,95 @@ export function createClaudeSessionRunner({
         clearTimeout(processRef.taskPublishTimer);
         processRef.taskPublishTimer = null;
       }
-      send();
-      return;
+      return send();
     }
-    if (processRef.taskPublishTimer) return;
+    if (processRef.taskPublishTimer) return Promise.resolve();
     processRef.taskPublishTimer = setTimeout(send, 2_000);
     processRef.taskPublishTimer.unref?.();
+    return Promise.resolve();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Task output files
+  //
+  // The relay reads a shell task's console straight from the file the CLI
+  // writes (`<tasks dir>/<taskId>.output`); the worker only names it. Bash
+  // results announce the path (task-output-discovery.mjs); a Monitor result
+  // does not, but its file follows the same scheme next to any known one, and
+  // is named only once it exists. Without a path the relay falls back to the
+  // CLI's `getTaskOutput` snapshot (task_output_snapshot control).
+
+  function rememberTaskOutputPath(processRef, taskId, outputPath) {
+    const id = String(taskId || '').trim();
+    const usable = usableOutputPath(outputPath);
+    if (!id || !usable) return false;
+    const dir = outputDirOf(usable);
+    if (dir) processRef.taskOutputDir = dir;
+    // The first path a task names wins, here as on the relay.
+    if (processRef.taskOutputPaths.has(id)) return false;
+    processRef.taskOutputPaths.set(id, usable);
+    while (processRef.taskOutputPaths.size > MAX_TASK_OUTPUT_PATHS) {
+      processRef.taskOutputPaths.delete(processRef.taskOutputPaths.keys().next().value);
+    }
+    return true;
+  }
+
+  function taskOutputFields(processRef, taskId) {
+    const known = processRef.taskOutputPaths.get(taskId);
+    if (known) return { outputPath: known, outputKind: 'file' };
+    if (processRef.taskOutputDir) {
+      const candidate = nodePath.join(processRef.taskOutputDir, `${taskId}.output`);
+      let exists = false;
+      try { exists = nodeFs.existsSync(candidate); } catch {}
+      if (exists && rememberTaskOutputPath(processRef, taskId, candidate)) {
+        return { outputPath: candidate, outputKind: 'file' };
+      }
+    }
+    return { outputKind: 'snapshot' };
+  }
+
+  /** A backgrounded Bash/Monitor result: note its file, and show it on the live row. */
+  function recordTaskOutputPaths(sdkMessage) {
+    let liveChanged = false;
+    for (const { taskId, outputPath } of discoverTaskOutputPaths(sdkMessage)) {
+      if (rememberTaskOutputPath(proc, taskId, outputPath) && proc.liveTasks.has(taskId)) liveChanged = true;
+    }
+    if (liveChanged) publishBackgroundTasks();
+  }
+
+  /**
+   * The relay's fallback for a shell task with no file: the CLI's last 8 KiB
+   * (`Query.getTaskOutput`, implemented in sdk.mjs though sdk.d.ts does not
+   * declare it), posted for the relay to serve. Asked once per viewer open.
+   */
+  async function snapshotTaskOutput(taskId) {
+    const id = String(taskId || '').trim();
+    const processRef = proc;
+    if (!id || typeof processRef?.turn?.getTaskOutput !== 'function') {
+      dbg('task output snapshot unavailable', id || '(no task)');
+      return false;
+    }
+    let answer;
+    try {
+      answer = await processRef.turn.getTaskOutput(id);
+    } catch (error) {
+      dbg('getTaskOutput failed', id, error?.message || String(error));
+      return false;
+    }
+    const output = typeof answer?.output === 'string' ? answer.output : '';
+    const totalBytes = Number(answer?.total_bytes);
+    try {
+      await api('POST', `/api/background-tasks/${encodeURIComponent(id)}/output-snapshot`, {
+        conversationId: sdkSessionId,
+        output,
+        totalBytes: Number.isFinite(totalBytes) && totalBytes >= 0 ? totalBytes : Buffer.byteLength(output),
+        truncated: answer?.truncated === true,
+      });
+      return true;
+    } catch (error) {
+      dbg('task output snapshot post failed', id, error?.message || String(error));
+      return false;
+    }
   }
 
   // ---------------------------------------------------------------------------
@@ -2184,6 +2325,11 @@ export function createClaudeSessionRunner({
       recordSubagentActivity(sdkMessage);
       return;
     }
+    if (type === 'user') {
+      // Any agent's backgrounded shell, the main thread's or a subagent's.
+      recordTaskOutputPaths(sdkMessage);
+      return;
+    }
     if (type !== 'system') return;
     const subtype = String(sdkMessage.subtype || '');
     if (subtype === 'init') {
@@ -2441,7 +2587,12 @@ export function createClaudeSessionRunner({
       // capture a settling workflow's final digest for the transcript card
       // (the notification then refines the status when it lands).
       for (const [taskId, task] of previous) {
-        if (!proc.liveTasks.has(taskId)) bufferSettledWorkflowRun(taskId, task);
+        if (proc.liveTasks.has(taskId)) continue;
+        bufferSettledWorkflowRun(taskId, task);
+        // What the task was, for its settle notice: the row is gone by the
+        // time the notification says how it ended.
+        proc.departedTasks.set(taskId, task);
+        if (proc.departedTasks.size > 50) proc.departedTasks.delete(proc.departedTasks.keys().next().value);
       }
       syncWorkflowPoller(proc);
       publishBackgroundTasks();
@@ -2477,6 +2628,9 @@ export function createClaudeSessionRunner({
         known.toolUseId = String(sdkMessage.tool_use_id || '').trim() || known.toolUseId || '';
         const totalTokens = Number(sdkMessage.usage?.total_tokens);
         if (Number.isFinite(totalTokens)) known.totalTokens = totalTokens;
+        // The sub-agent's tool calls so far: the panel row's step count.
+        const toolUses = Number(sdkMessage.usage?.tool_uses);
+        if (Number.isFinite(toolUses) && toolUses >= 0) known.steps = Math.floor(toolUses);
         publishBackgroundTasks({ throttled: true });
       }
       return;
@@ -2491,14 +2645,37 @@ export function createClaudeSessionRunner({
       // this session (the live set only says it is gone). Ambient tasks are
       // not activity. Advisory: a failed post never disturbs the stream.
       if (taskId && sdkMessage.ambient !== true) {
-        api('POST', '/api/background-task-settled', {
+        // A task that was in the published set is described too, so that a
+        // relay which no longer knows it (it restarted meanwhile) can still
+        // tell its watchers the end. A failed post is kept and sent again.
+        const published = proc.liveTasks.get(taskId) || proc.departedTasks.get(taskId) || null;
+        proc.departedTasks.delete(taskId);
+        // A shell's file and exit code make the relay's ended row: its
+        // console stays readable after the task is gone.
+        rememberTaskOutputPath(proc, taskId, sdkMessage.output_file);
+        const shellLike = isShellTaskType(published?.taskType);
+        const outputPath = shellLike ? (proc.taskOutputPaths.get(taskId) || '') : '';
+        const exitCode = shellLike ? exitCodeFromSummary(sdkMessage.summary) : null;
+        const toolUses = Number(sdkMessage.usage?.tool_uses);
+        const steps = AGENT_TASK_TYPES.has(String(published?.taskType || '')) && Number.isFinite(toolUses) && toolUses >= 0
+          ? Math.floor(toolUses)
+          : null;
+        void keptTaskSettles.post('/api/background-task-settled', {
           conversationId: sdkSessionId,
           taskId,
-          toolUseId: String(sdkMessage.tool_use_id || '').trim() || null,
+          toolUseId: String(sdkMessage.tool_use_id || published?.toolUseId || '').trim() || null,
           status: String(sdkMessage.status || '').trim() || 'completed',
           summary: String(sdkMessage.summary || '').trim().slice(0, 500) || null,
           ...(sdkMessage.reason ? { reason: String(sdkMessage.reason).slice(0, 40) } : {}),
-        }).catch((error) => dbg('background task settle publish failed', error?.message || String(error)));
+          ...(published?.description ? {
+            description: String(published.description).slice(0, 500),
+            taskType: String(published.taskType || ''),
+            startedAt: published.startedAt || null,
+          } : {}),
+          ...(outputPath ? { outputPath } : {}),
+          ...(exitCode !== null ? { exitCode } : {}),
+          ...(steps !== null ? { steps } : {}),
+        });
       }
       // A settled session-level task means the CLI is about to dequeue a
       // continuation turn — the process must not idle out under it. The SDK
@@ -3249,7 +3426,7 @@ export function createClaudeSessionRunner({
     if (processRef.liveTasks.size) {
       processRef.liveTasks = new Map();
       if (wasCurrent) {
-        api('POST', '/api/background-tasks', { conversationId: sdkSessionId, tasks: [] }).catch(() => {});
+        postTaskSet({ tasks: [] }).catch(() => {});
       }
     }
     // Steers pushed into a turn the user stopped: if the Stop fell back to
@@ -3308,6 +3485,7 @@ export function createClaudeSessionRunner({
     const thinkingEnabled = parseThinkingEnabled(thinkingState.enabled);
     const thinkingDisplay = parseThinkingDisplay(thinkingState.display);
     const attribution = getAttribution() || null;
+    const backgroundCommandLimitMs = getBackgroundCommandLimitMs() ?? null;
     const abortController = new AbortController();
     const processRef = {
       turn: null,
@@ -3331,6 +3509,14 @@ export function createClaudeSessionRunner({
       permissionMode: permissionModeForRelayMode(relayMode),
       liveTasks: new Map(),
       knownTasks: new Set(),
+      // taskId → the row of a task that left the live set, until its
+      // notification arrives.
+      departedTasks: new Map(),
+      // taskId → the file a shell task's output goes to (first named wins),
+      // and the directory of the last one seen: a Monitor task's file sits
+      // next to it.
+      taskOutputPaths: new Map(),
+      taskOutputDir: '',
       // taskId → { runId, labels, digestJson } for live local_workflow tasks;
       // pruned by syncWorkflowPoller when a task leaves the live set.
       workflowStates: new Map(),
@@ -3478,6 +3664,7 @@ export function createClaudeSessionRunner({
       thinkingEnabled,
       thinkingDisplay,
       attribution,
+      backgroundCommandLimitMs,
       abortController,
       canUseTool,
       pathToClaudeCodeExecutable,
@@ -4034,6 +4221,21 @@ export function createClaudeSessionRunner({
     return false;
   }
 
+  /** The ids of the live background tasks, for the heartbeat's digest. */
+  function backgroundTaskIds() {
+    return proc ? [...proc.liveTasks.keys()] : [];
+  }
+
+  /** The relay asked for the task set again (heartbeat answer). */
+  function resyncBackgroundTasks() {
+    return publishBackgroundTasks({ resync: true });
+  }
+
+  /** The relay answered a heartbeat: settle notices kept for it go out. */
+  function flushKeptTaskSettles() {
+    return keptTaskSettles.flush();
+  }
+
   return {
     handlePendingPayload,
     canAcceptSteering,
@@ -4046,6 +4248,10 @@ export function createClaudeSessionRunner({
     isTurnActive,
     stopBackgroundTask,
     stopBackgroundTaskByToolUseId,
+    snapshotTaskOutput,
+    backgroundTaskIds,
+    resyncBackgroundTasks,
+    flushKeptTaskSettles,
     shutdown,
     // Test seams / observability.
     _getProcess: () => proc,

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

@@ -18,6 +18,10 @@ import { createControlPoller } from '../../shared/control-poller.mjs';
 import { resolveDeliveredAutoCompactWindow } from '../../shared/auto-compact-window.mjs';
 import { resolveDeliveredThinking } from '../../shared/claude-thinking.mjs';
 import { resolveDeliveredAttribution } from '../../shared/claude-attribution.mjs';
+import {
+  DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS,
+  resolveDeliveredClaudeBackgroundCommandLimitMs,
+} from '../../shared/claude-background-command-limit.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createClaudeSessionRunner } from './claude-session-process.mjs';
 import { createRunnerLinkBridge, failSettlingRowsOnShutdown } from './claude-worker-link-wiring.mjs';
@@ -70,6 +74,9 @@ async function main() {
   // What this session's commits and PRs say; same piggyback. null = the
   // CLI's own attribution (vanilla).
   let attribution = null;
+  // How long a backgrounded Bash command may run without its own timeout;
+  // same piggyback, applied when the CLI process is next spawned.
+  let backgroundCommandLimitMs = DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS;
 
   const api = createApiClient({
     serverUrl,
@@ -116,9 +123,11 @@ async function main() {
     getAutoCompactWindow: () => autoCompactWindow,
     getThinking: () => thinking,
     getAttribution: () => attribution,
+    getBackgroundCommandLimitMs: () => backgroundCommandLimitMs,
     // A readiness flip is a hold starting or ending (question card,
     // compaction, a turn-opening delivery): the steering snapshot changed
     // with it, so it goes out now rather than on the next 10 s heartbeat.
+    onBackgroundTaskSetStale: () => heartbeat?.requestPulse(),
     onDeliveryReadinessChange: (ready) => {
       linkBridge.onDeliveryReadinessChange(ready);
       heartbeat?.requestPulse();
@@ -147,6 +156,12 @@ async function main() {
     // Consumed rows the runner could not fail itself; the relay fails them.
     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(),
+    onAnswered: () => turnRunner.flushKeptTaskSettles(),
   });
 
   const wsLink = createWorkerWebSocketLink({
@@ -164,7 +179,8 @@ async function main() {
     // even between deliveries — a delivery drawn into it is only handed back.
     getDeliveryHeld: () => turnRunner.isDeliveryHeld(),
     // A relay that just (re)started knows nothing of this worker until it
-    // heartbeats; the composer's steering snapshot rides that beat.
+    // heartbeats; the composer's steering snapshot rides that beat, and so
+    // does the digest that makes the relay ask for the background tasks.
     onServerHello: () => heartbeat.requestPulse(),
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
@@ -182,6 +198,7 @@ async function main() {
       // user choosing Host default.
       thinking = resolveDeliveredThinking(thinking, pending?.settings);
       attribution = resolveDeliveredAttribution(attribution, pending?.settings);
+      backgroundCommandLimitMs = resolveDeliveredClaudeBackgroundCommandLimitMs(backgroundCommandLimitMs, pending?.settings);
       try {
         return await turnRunner.handlePendingPayload(pending);
       } catch (error) {
@@ -197,6 +214,14 @@ async function main() {
         await turnRunner.stopBackgroundTask(taskId);
         return;
       }
+      if (type === 'task_output_snapshot') {
+        // A console opened on a shell task with no output file: the CLI's
+        // last 8 KiB goes to the relay, which serves it as a static tail.
+        const taskId = String(control?.taskId || '').trim();
+        dbg('task output snapshot control', taskId);
+        await turnRunner.snapshotTaskOutput(taskId);
+        return;
+      }
       dbg('unknown worker control ignored', type || '(none)');
     },
   });

package/server/claude-worker/task-output-discovery.mjs

@@ -0,0 +1,126 @@
+// Where a Claude background shell writes its output, read off the SDK stream.
+//
+// The CLI writes every Bash task (and every Monitor tool task, which is a
+// `local_bash` task of kind "monitor") to `<tasks dir>/<taskId>.output`, and
+// tells the model the path in the Bash tool's result text: "Command running in
+// background with ID: <id>. Output is being written to: <path>." (wording
+// read from the bundled CLI, SDK 0.3.292). The structured result
+// (`SDKUserMessage.tool_use_result`, a BashOutput) names the task id as
+// `backgroundTaskId` but carries no path of its own. `task_notification`
+// repeats the path as `output_file` when the task ends.
+import nodePath from 'node:path';
+
+/** Task types whose output is a shell's stdout/stderr (getTaskOutput serves these too). */
+export const SHELL_TASK_TYPES = new Set(['local_bash', 'monitor', 'monitor_mcp', 'monitor_ws']);
+export const MAX_OUTPUT_PATH_CHARS = 1024;
+
+const OUTPUT_MARKER = 'Output is being written to';
+// The CLI's own file name: a path with spaces (a Windows profile dir) still
+// reads whole, up to its `.output` and the sentence's full stop.
+const OUTPUT_FILE_PATTERN = /Output is being written to:?\s+([^\n;]+?\.output)(?=[.;,]?(?:\s|$))/;
+// Any other shape: one token, without the trailing punctuation.
+const OUTPUT_TOKEN_PATTERN = /Output is being written to:?\s+(\S+?)[.;,]?(?:\s|$)/;
+const TASK_ID_PATTERN = /\bID:\s*([A-Za-z0-9_-]+)/;
+// What the CLI's own background notes start with (Bash, SDK 0.3.292). A
+// foreground command that merely prints "Output is being written to: ..."
+// must never bind a path to a task, so only these, the MCP form below, or a
+// result whose structured output names the task are read.
+const CLI_BACKGROUND_PREFIXES = [
+  'Command running in background',
+  'Command was manually backgrounded',
+  'Command was moved to the background',
+  'Command did not complete within',
+];
+// The backgrounded MCP task's note: no colon, then "; use <tool> on that path".
+const MCP_BACKGROUND_PATTERN = /Output is being written to (\S[^\n;]*?\.output); use \S/;
+
+export function isShellTaskType(taskType) {
+  return SHELL_TASK_TYPES.has(String(taskType || '').trim());
+}
+
+/** An absolute path of sane length, or ''. Windows shapes count on every host. */
+export function usableOutputPath(value) {
+  const text = String(value || '').trim();
+  if (!text || text.length > MAX_OUTPUT_PATH_CHARS) return '';
+  return nodePath.posix.isAbsolute(text) || nodePath.win32.isAbsolute(text) ? text : '';
+}
+
+/** `.../tasks/b8k2m4x7q.output` → `b8k2m4x7q`. */
+function taskIdFromOutputFile(filePath) {
+  const base = String(filePath).split(/[\\/]/).pop() || '';
+  return base.endsWith('.output') ? base.slice(0, -'.output'.length) : '';
+}
+
+/** The directory part of a path, for either separator. */
+export function outputDirOf(filePath) {
+  const text = String(filePath || '');
+  const cut = Math.max(text.lastIndexOf('/'), text.lastIndexOf('\\'));
+  return cut > 0 ? text.slice(0, cut) : '';
+}
+
+function toolResultText(block) {
+  const content = block?.content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((part) => part?.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('\n');
+}
+
+/** `{ taskId, outputPath }` from one tool result's text, or null. */
+export function parseOutputAnnouncement(text, knownTaskId = '') {
+  const source = String(text || '');
+  if (!source.includes(OUTPUT_MARKER)) return null;
+  const match = source.match(OUTPUT_FILE_PATTERN) || source.match(OUTPUT_TOKEN_PATTERN);
+  const outputPath = usableOutputPath(match?.[1]);
+  if (!outputPath) return null;
+  const taskId = String(knownTaskId || '').trim()
+    || taskIdFromOutputFile(outputPath)
+    || (source.match(TASK_ID_PATTERN)?.[1] || '');
+  return taskId ? { taskId, outputPath } : null;
+}
+
+/** The CLI's own note about a backgrounded call, not a command's printed output. */
+function isBackgroundNote(text) {
+  const source = String(text || '').trimStart();
+  if (CLI_BACKGROUND_PREFIXES.some((prefix) => source.startsWith(prefix))) return true;
+  const mcp = source.match(MCP_BACKGROUND_PATTERN);
+  return Boolean(mcp && taskIdFromOutputFile(mcp[1]));
+}
+
+/**
+ * Every task output file a `user` SDK message announces: the tool_result
+ * blocks of backgrounded Bash (and Monitor) calls. The structured result's
+ * `backgroundTaskId` names the task when the message answers a single call.
+ */
+export function discoverTaskOutputPaths(sdkMessage) {
+  if (String(sdkMessage?.type || '') !== 'user') return [];
+  const blocks = Array.isArray(sdkMessage?.message?.content) ? sdkMessage.message.content : [];
+  const results = blocks.filter((block) => block?.type === 'tool_result');
+  if (!results.length) return [];
+  const structured = sdkMessage.tool_use_result && typeof sdkMessage.tool_use_result === 'object'
+    ? sdkMessage.tool_use_result
+    : null;
+  const structuredTaskId = results.length === 1 ? String(structured?.backgroundTaskId || '').trim() : '';
+  const found = [];
+  for (const block of results) {
+    const text = toolResultText(block);
+    if (!structuredTaskId && !isBackgroundNote(text)) continue;
+    const announced = parseOutputAnnouncement(text, structuredTaskId);
+    if (announced) found.push(announced);
+  }
+  return found;
+}
+
+/**
+ * The exit code a shell task's settle summary names: `Background command
+ * "npm test" failed with exit code 2` / `... completed (exit code 0)`.
+ * The last mention wins (the command's own description may say "exit code").
+ */
+export function exitCodeFromSummary(summary) {
+  const matches = [...String(summary || '').matchAll(/exit code (-?\d+)/gi)];
+  if (!matches.length) return null;
+  const code = Number(matches[matches.length - 1][1]);
+  return Number.isInteger(code) ? code : null;
+}