@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/runs/background/subagent-wait.js

@@ -0,0 +1,529 @@
+import * as fs from "node:fs";
+import {
+  listBackgroundWorkWakeChannels,
+  snapshotBackgroundWork
+} from "../../api/background-work.js";
+import { formatAsyncRunList, listAsyncRuns } from "./async-status.js";
+import {
+  DIRS,
+  INTERCOM_DETACH_REQUEST_EVENT,
+  SUBAGENT_ASYNC_COMPLETE_EVENT,
+  SUBAGENT_FOREGROUND_COMPLETE_EVENT,
+  SUBAGENT_CONTROL_EVENT,
+  SUBAGENT_CONTROL_INTERCOM_EVENT,
+  SUBAGENT_RESULT_INTERCOM_EVENT
+} from "../../shared/types.js";
+import { formatDuration, shortenPath } from "../../shared/formatters.js";
+import { toAgentToolUsage } from "../../shared/utils.js";
+import { collectWaitCompletions } from "./wait-completions.js";
+import { formatResumeFirstFailedRunsNote } from "./resume-guidance.js";
+import { formatTimeoutRecoveryLines } from "../shared/mutation-evidence.js";
+export { WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV, WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig } from "./wait-config.js";
+const ACTIVE_STATES = ["queued", "running"];
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const MIN_POLL_INTERVAL_MS = 250;
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+const WAKE_CHANNELS = [
+  INTERCOM_DETACH_REQUEST_EVENT,
+  SUBAGENT_ASYNC_COMPLETE_EVENT,
+  SUBAGENT_FOREGROUND_COMPLETE_EVENT,
+  SUBAGENT_CONTROL_EVENT,
+  SUBAGENT_CONTROL_INTERCOM_EVENT,
+  SUBAGENT_RESULT_INTERCOM_EVENT
+];
+function defaultSleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function waitForWake(ms, signal, deps) {
+  const sleep = deps.sleep ?? defaultSleep;
+  const events = deps.events;
+  if (!events)
+    return sleep(ms, signal);
+  const providerChannels = deps.backgroundWork?.wakeChannels() ?? listBackgroundWorkWakeChannels();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const unsubs = [];
+    const wakeController = new AbortController;
+    const done = () => {
+      if (settled)
+        return;
+      settled = true;
+      wakeController.abort();
+      signal?.removeEventListener("abort", done);
+      for (const u of unsubs) {
+        try {
+          u();
+        } catch {}
+      }
+      resolve();
+    };
+    if (signal?.aborted) {
+      done();
+      return;
+    }
+    signal?.addEventListener("abort", done, { once: true });
+    try {
+      for (const channel of [...new Set([...WAKE_CHANNELS, ...providerChannels])]) {
+        unsubs.push(events.on(channel, done));
+      }
+    } catch (error) {
+      signal?.removeEventListener("abort", done);
+      for (const unsubscribe of unsubs) {
+        try {
+          unsubscribe();
+        } catch {}
+      }
+      reject(error);
+      return;
+    }
+    sleep(ms, wakeController.signal).then(done);
+  });
+}
+function matchesId(run, id) {
+  return run.id === id || run.id.startsWith(id);
+}
+function activeDetachedForegroundRuns(params, deps) {
+  if (!params.id || !deps.state.foregroundRuns)
+    return [];
+  const sessionId = deps.state.currentSessionId;
+  if (!sessionId)
+    return [];
+  return [...deps.state.foregroundRuns.values()].filter((run) => (run.runId === params.id || run.runId.startsWith(params.id)) && run.sessionId === sessionId && run.children.some((child) => child.status === "detached"));
+}
+function summarizeForegroundChildren(run, indices) {
+  const counts = new Map;
+  for (const child of run.children) {
+    if (!indices.has(child.index) || child.status === "detached")
+      continue;
+    counts.set(child.status, (counts.get(child.status) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(", ");
+}
+function foregroundChildrenNeedingAttention(run, indices) {
+  return run.children.filter((child) => indices.has(child.index) && child.status === "detached" && child.activityState === "needs_attention" && child.currentTool === "contact_supervisor");
+}
+function formatForegroundAttention(run, children, elapsedMs) {
+  const childList = children.map((child) => `${child.agent}${child.index !== undefined ? `#${child.index}` : ""}`).join(", ");
+  return result(`Waited ${formatDuration(elapsedMs)} for remembered detached foreground run "${run.runId}"; attention required. ${children.length} child run(s) need attention: ${childList}. Reply to any pending supervisor request, then call bg_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`);
+}
+function needsAttention(run) {
+  return run.activityState === "needs_attention" || run.steps.some((step) => step.activityState === "needs_attention");
+}
+function hasSupervisorTool(run) {
+  return run.currentTool === "contact_supervisor" || run.currentTool === "intercom" || run.steps.some((step) => step.currentTool === "contact_supervisor" || step.currentTool === "intercom");
+}
+function backgroundWorkIdentity(item) {
+  return `${item.provider}\x00${item.sessionId}\x00${item.id}`;
+}
+function backgroundWorkForSession(deps, nowMs) {
+  const sessionId = deps.state.currentSessionId;
+  if (!sessionId)
+    throw new Error("bg_wait requires an active session identity to scope background work safely.");
+  return deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);
+}
+function activeRunsForSession(params, deps) {
+  const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
+  const resultsDir = deps.resultsDir ?? DIRS.results;
+  const runs = listAsyncRuns(asyncDirRoot, {
+    states: [...ACTIVE_STATES],
+    sessionId: deps.state.currentSessionId ?? undefined,
+    resultsDir,
+    kill: deps.kill,
+    now: deps.now,
+    includeNested: false,
+    ...params.id ? { runId: params.id } : {}
+  });
+  return params.id ? runs.filter((run) => matchesId(run, params.id)) : runs;
+}
+function attentionRunsForSession(params, deps, initialIds) {
+  return activeRunsForSession(params, deps).filter((run) => needsAttention(run) && initialIds.has(run.id));
+}
+function runsForIds(runIds, deps) {
+  const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
+  const resultsDir = deps.resultsDir ?? DIRS.results;
+  return [...runIds].flatMap((runId) => listAsyncRuns(asyncDirRoot, {
+    sessionId: deps.state.currentSessionId ?? undefined,
+    resultsDir,
+    kill: deps.kill,
+    now: deps.now,
+    includeNested: false,
+    runId,
+    exactRunId: true
+  }));
+}
+function summarizeTerminalRuns(runs, providerFinishedCount = 0) {
+  if (runs.length === 0 && providerFinishedCount === 0)
+    return "";
+  const counts = { complete: 0, failed: 0, paused: 0 };
+  for (const run of runs) {
+    const count = counts[run.state];
+    if (count !== undefined)
+      counts[run.state] = count + 1;
+  }
+  const parts = [];
+  if (counts.complete)
+    parts.push(`${counts.complete} complete`);
+  if (counts.failed)
+    parts.push(`${counts.failed} failed`);
+  if (counts.paused)
+    parts.push(`${counts.paused} paused`);
+  if (providerFinishedCount > 0)
+    parts.push(`${providerFinishedCount} provider item(s) finished`);
+  return parts.join(", ");
+}
+function completionUsage(completions) {
+  if (!completions?.length)
+    return;
+  const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+  let projected = false;
+  for (const completion of completions) {
+    for (const child of completion.results ?? []) {
+      if (!child.usage || child.usage.input === 0 && child.usage.output === 0 && child.usage.cacheRead === 0 && child.usage.cacheWrite === 0 && child.usage.cost === 0 && child.usage.turns === 0)
+        continue;
+      projected = true;
+      usage.input += child.usage.input;
+      usage.output += child.usage.output;
+      usage.cacheRead += child.usage.cacheRead;
+      usage.cacheWrite += child.usage.cacheWrite;
+      usage.cost += child.usage.cost;
+      usage.turns += child.usage.turns;
+    }
+  }
+  return projected ? usage : undefined;
+}
+function result(text, isError = false, completions) {
+  const usage = completionUsage(completions);
+  return {
+    content: [{ type: "text", text }],
+    ...isError ? { isError: true } : {},
+    ...usage ? { usage: toAgentToolUsage(usage) } : {},
+    details: {
+      mode: "management",
+      results: [],
+      ...completions && completions.length > 0 ? { completions } : {}
+    }
+  };
+}
+function formatCompletionRecovery(completions) {
+  const lines = (completions ?? []).flatMap((completion) => (completion.results ?? []).flatMap((child) => formatTimeoutRecoveryLines(child.timeoutRecovery)));
+  return lines.length > 0 ? `
+${lines.join(`
+`)}` : "";
+}
+function windowElapsedResult(text, activeRunIds, activeProviderItems = []) {
+  return {
+    content: [{ type: "text", text }],
+    details: {
+      mode: "management",
+      results: [],
+      wait: {
+        reason: "window_elapsed",
+        timedOut: true,
+        activeRunIds,
+        activeProviderItems: activeProviderItems.map(({ provider, id }) => ({ provider, id }))
+      }
+    }
+  };
+}
+function asyncWaitUpdate(runs, providerCount, elapsedMs) {
+  const activity = runs.flatMap((run) => {
+    const activeSteps = run.steps.filter((step) => step.status === "pending" || step.status === "running");
+    if (activeSteps.length === 0) {
+      return [`${run.id}: ${run.state}`];
+    }
+    return activeSteps.map((step) => {
+      const current = step.currentTool ?? (step.status === "pending" ? "queued" : "thinking…");
+      return `${step.agent}: ${current}${step.currentPath ? ` ${shortenPath(step.currentPath)}` : ""}`;
+    });
+  });
+  const headline = [
+    `Waiting ${formatDuration(elapsedMs)} for ${runs.length} async run(s) and ${providerCount} provider item(s).`,
+    ...activity
+  ].join(" · ");
+  return result([headline, runs.length > 0 ? formatAsyncRunList(runs) : ""].filter(Boolean).join(`
+`));
+}
+const TRANSCRIPT_TAIL_BYTES = 128 * 1024;
+const TRANSCRIPT_PREVIEW_LINES = 3;
+const TRANSCRIPT_PREVIEW_WIDTH = 220;
+function compactTranscriptText(value, maxWidth = TRANSCRIPT_PREVIEW_WIDTH) {
+  if (typeof value !== "string")
+    return;
+  const compact = value.replace(/\s+/g, " ").trim();
+  if (!compact)
+    return;
+  return compact.length <= maxWidth ? compact : `${compact.slice(0, Math.max(1, maxWidth - 1))}…`;
+}
+function readTranscriptActivity(transcriptPath) {
+  if (!transcriptPath)
+    return;
+  let fd;
+  try {
+    const stat = fs.statSync(transcriptPath);
+    if (!stat.isFile() || stat.size <= 0)
+      return;
+    const start = Math.max(0, stat.size - TRANSCRIPT_TAIL_BYTES);
+    const length = stat.size - start;
+    const buffer = Buffer.allocUnsafe(length);
+    fd = fs.openSync(transcriptPath, "r");
+    const bytesRead = fs.readSync(fd, buffer, 0, length, start);
+    let lines = buffer.subarray(0, bytesRead).toString("utf-8").split(/\r?\n/);
+    if (start > 0)
+      lines = lines.slice(1);
+    let currentTool;
+    let currentToolArgs;
+    let latestAt;
+    const recent = [];
+    for (const line of lines) {
+      if (!line.trim())
+        continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (typeof record.ts === "number" && Number.isFinite(record.ts))
+        latestAt = record.ts;
+      if (record.recordType === "tool_start" && typeof record.toolName === "string") {
+        currentTool = record.toolName;
+        currentToolArgs = compactTranscriptText(record.argsPreview, 140);
+        const preview = currentToolArgs ? `${currentTool}: ${currentToolArgs}` : currentTool;
+        recent.push(`tool: ${preview}`);
+        continue;
+      }
+      if (record.recordType === "tool_end") {
+        currentTool = undefined;
+        currentToolArgs = undefined;
+        continue;
+      }
+      if (record.recordType === "message") {
+        if (record.sourceEventType === "initial_prompt" || record.role === "user")
+          continue;
+        const text = compactTranscriptText(record.text);
+        if (text)
+          recent.push(`${typeof record.role === "string" ? record.role : "message"}: ${text}`);
+        continue;
+      }
+      if (record.recordType === "stdout" || record.recordType === "stderr") {
+        const text = compactTranscriptText(record.text);
+        if (text)
+          recent.push(`${record.recordType}: ${text}`);
+      }
+    }
+    return { currentTool, currentToolArgs, latestAt, recent: recent.slice(-TRANSCRIPT_PREVIEW_LINES) };
+  } catch {
+    return;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {}
+    }
+  }
+}
+function detachedForegroundWaitUpdate(run, pendingIndices, nowMs, elapsedMs) {
+  const lines = [`Waiting for detached foreground run "${run.runId}" · ${formatDuration(elapsedMs)}`];
+  for (const child of run.children) {
+    if (!pendingIndices.has(child.index) || child.status !== "detached")
+      continue;
+    const activity = readTranscriptActivity(child.transcriptPath);
+    const age = activity?.latestAt !== undefined ? ` · activity ${formatDuration(Math.max(0, nowMs - activity.latestAt))} ago` : "";
+    lines.push(`${child.agent} · working after supervisor handoff${age}`);
+    if (activity?.currentTool) {
+      lines.push(`  current: ${activity.currentTool}${activity.currentToolArgs ? `: ${activity.currentToolArgs}` : ""}`);
+    }
+    for (const preview of activity?.recent ?? [])
+      lines.push(`  ${preview}`);
+    if (!activity && child.transcriptPath)
+      lines.push("  live transcript has no new activity yet");
+    if (!child.transcriptPath)
+      lines.push("  live transcript unavailable; waiting for completion event");
+  }
+  return result(lines.join(`
+`));
+}
+async function waitForDetachedForegroundRun(run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs) {
+  const initialDetachedIndices = new Set(run.children.filter((child) => child.status === "detached").map((child) => child.index));
+  while (true) {
+    if (deps.state.currentSessionId !== run.sessionId) {
+      return result(`Wait stopped because the active session changed while remembered foreground run "${run.runId}" was still detached. Return to the originating session to inspect or wait for it. Reply to any pending supervisor request before resuming or launching a replacement.`, true);
+    }
+    const current = deps.state.foregroundRuns?.get(run.runId);
+    if (!current || current.sessionId !== run.sessionId) {
+      return result(`Remembered foreground run "${run.runId}" disappeared before a terminal child result was recorded. Completion cannot be confirmed; do not launch a replacement without checking the originating child session.`, true);
+    }
+    const pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === "detached");
+    const attention = foregroundChildrenNeedingAttention(current, initialDetachedIndices);
+    if (attention.length > 0)
+      return formatForegroundAttention(current, attention, now() - startedAt);
+    if (pending.length === 0) {
+      const outcome = summarizeForegroundChildren(current, initialDetachedIndices);
+      return result(`Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run "${run.runId}"; done. Outcome: ${outcome || "no recovered child status"}. Completion event observed; inspect with subagent({ action: "status", id: "${run.runId}" }) for recovered output.`);
+    }
+    const updateNow = now();
+    deps.onUpdate?.(detachedForegroundWaitUpdate(current, initialDetachedIndices, updateNow, updateNow - startedAt));
+    if (signal?.aborted) {
+      return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Remembered foreground run "${run.runId}" remains detached. Reply to any pending supervisor request before resuming or launching a replacement.`, true);
+    }
+    if (now() - startedAt >= timeoutMs) {
+      return windowElapsedResult(`Wait window elapsed after ${formatDuration(timeoutMs)} with remembered foreground run "${run.runId}" still detached. Reply to any pending supervisor request, then call bg_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`, [run.runId]);
+    }
+    await waitForWake(pollIntervalMs, signal, deps);
+  }
+}
+export async function waitForSubagents(params, signal, deps) {
+  if (deps.enabled === false) {
+    return result('bg_wait is disabled by config.waitTool or DM_SUBAGENT_WAIT_TOOL_ENABLED; returning immediately without blocking background work. Active work keeps going, and you can inspect subagents with subagent({ action: "status" }) or rely on completion notifications.');
+  }
+  if (!deps.state.currentSessionId) {
+    return result("bg_wait requires an active session identity to scope background work safely.", true);
+  }
+  const now = deps.now ?? Date.now;
+  const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+  const timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0 ? params.timeoutMs : deps.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const startedAt = now();
+  const waitForAll = params.id ? true : params.all === true;
+  if (params.nonBlocking && !params.id) {
+    return result("Non-blocking wait subscriptions require id so the registration can bind one exact run identity.", true);
+  }
+  if (params.nonBlocking && params.all) {
+    return result("nonBlocking cannot be combined with all; subscribe to one exact run id.", true);
+  }
+  let active;
+  let foreground;
+  let providerSnapshot;
+  try {
+    active = activeRunsForSession(params, deps);
+    foreground = activeDetachedForegroundRuns(params, deps);
+    providerSnapshot = params.id ? { providers: [], items: [] } : backgroundWorkForSession(deps, startedAt);
+  } catch (error) {
+    return result(error instanceof Error ? error.message : String(error), true);
+  }
+  if (params.id) {
+    const candidates = [
+      ...active.map((run) => ({ kind: "async", id: run.id, run })),
+      ...foreground.map((run) => ({ kind: "foreground", id: run.runId, run }))
+    ];
+    const exact = candidates.filter((candidate) => candidate.id === params.id);
+    const matches = exact.length > 0 ? exact : candidates;
+    if (matches.length > 1) {
+      return result(`Ambiguous subagent run id prefix "${params.id}" matched ${matches.length} active runs: ${matches.map((candidate) => candidate.id).join(", ")}. Pass a longer id.`, true);
+    }
+    const selected = matches[0];
+    if (selected && params.nonBlocking) {
+      if (!deps.subscribe) {
+        return result("Non-blocking wait subscriptions require a long-lived interactive subagent runtime; this runtime can only use blocking bg_wait calls.", true);
+      }
+      try {
+        const registration = deps.subscribe({ targetKind: selected.kind, runId: selected.id, requestedId: params.id, timeoutMs });
+        return result(`Armed wait subscription ${registration.token} for exact ${selected.kind} run ${selected.id}. Returning immediately; this session will be woken on completion, failure, attention, reconciliation failure, or timeout. Inspect armed subscriptions with subagent({ action: "status" }).`);
+      } catch (error) {
+        return result(error instanceof Error ? error.message : String(error), true);
+      }
+    }
+    if (selected?.kind === "foreground") {
+      return waitForDetachedForegroundRun(selected.run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);
+    }
+    active = selected?.kind === "async" ? [selected.run] : [];
+  }
+  let providerActive = providerSnapshot.items;
+  if (active.length === 0 && providerActive.length === 0) {
+    return result(params.id ? `No active run matched "${params.id}". Nothing to wait for.` : "No active async runs or registered provider work in this session. Nothing to wait for.");
+  }
+  const waitParams = params.id ? { ...params, id: active[0].id } : params;
+  const initialAsyncIds = new Set(active.map((run) => run.id));
+  const initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+  const initialProviderNames = new Set(providerActive.map((item) => item.provider));
+  const initialCount = initialAsyncIds.size + initialProviderIds.size;
+  const stopOnAttention = params.stopOnAttention ?? deps.stopOnAttention !== false;
+  let attention = active.filter((run) => needsAttention(run));
+  const isDone = () => {
+    if (attention.some((run) => initialAsyncIds.has(run.id) && (stopOnAttention || hasSupervisorTool(run))))
+      return true;
+    const activeAsyncIds = new Set(active.map((run) => run.id));
+    const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+    if (waitForAll) {
+      return [...initialAsyncIds].every((id) => !activeAsyncIds.has(id)) && [...initialProviderIds].every((id) => !activeProviderIds.has(id));
+    }
+    return [...initialAsyncIds].some((id) => !activeAsyncIds.has(id)) || [...initialProviderIds].some((id) => !activeProviderIds.has(id));
+  };
+  while (!isDone()) {
+    const activeInitialRuns = active.filter((run) => initialAsyncIds.has(run.id));
+    const activeInitialProviderItems = providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item)));
+    const stillActive = [
+      ...activeInitialRuns.map((run) => `${run.id} (${run.state})`),
+      ...activeInitialProviderItems.map((item) => `${item.provider}/${item.id}`)
+    ].join(", ");
+    deps.onUpdate?.(asyncWaitUpdate(activeInitialRuns, activeInitialProviderItems.length, now() - startedAt));
+    if (signal?.aborted) {
+      return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Still active: ${stillActive}.`, true);
+    }
+    if (now() - startedAt >= timeoutMs) {
+      return windowElapsedResult(`Wait window elapsed after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call bg_wait again or inspect subagent status.`, activeInitialRuns.map((run) => run.id), activeInitialProviderItems);
+    }
+    try {
+      await waitForWake(pollIntervalMs, signal, deps);
+      active = activeRunsForSession(waitParams, deps);
+      attention = attentionRunsForSession(waitParams, deps, initialAsyncIds);
+      providerSnapshot = params.id ? providerSnapshot : backgroundWorkForSession(deps, now());
+      for (const provider of initialProviderNames) {
+        if (!providerSnapshot.providers.includes(provider)) {
+          return result(`Background-work provider '${provider}' disappeared while bg_wait was tracking its active work; completion cannot be confirmed.`, true);
+        }
+      }
+      providerActive = providerSnapshot.items;
+    } catch (error) {
+      return result(error instanceof Error ? error.message : String(error), true);
+    }
+  }
+  let terminalSummary;
+  let finishedAsyncCount;
+  let failedAsyncCount;
+  let completions;
+  let resumeGuidance = "";
+  const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+  const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
+  try {
+    const allNow = runsForIds(initialAsyncIds, deps);
+    const terminal = allNow.filter((run) => !ACTIVE_STATES.includes(run.state) && initialAsyncIds.has(run.id));
+    finishedAsyncCount = terminal.length;
+    failedAsyncCount = terminal.filter((run) => run.state === "failed" || run.state === "partial").length;
+    terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
+    resumeGuidance = formatResumeFirstFailedRunsNote(terminal);
+    completions = collectWaitCompletions(terminal, deps.state, deps.resultsDir ?? DIRS.results);
+  } catch (error) {
+    return result(error instanceof Error ? error.message : String(error), true);
+  }
+  const relevantAttention = attention.filter((run) => initialAsyncIds.has(run.id));
+  const supervisorAttentionHint = relevantAttention.some(hasSupervisorTool) ? ' Reply to any pending supervisor request. If subagent_supervisor({ action: "pending" }) is empty, check intercom({ action: "pending" }) because an external intercom tool may own the request.' : "";
+  const attentionNote = relevantAttention.length > 0 ? ` ${relevantAttention.length} run(s) need attention: ${relevantAttention.map((run) => run.id).join(", ")} —${supervisorAttentionHint} inspect with subagent({ action: "status" }) then steer a top-level live async child, resume a paused/completed/failed child, or interrupt explicitly.` : "";
+  const stillRunning = active.filter((run) => initialAsyncIds.has(run.id)).length + providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;
+  const elapsed = formatDuration(now() - startedAt);
+  const outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : "";
+  const recoveryNote = formatCompletionRecovery(completions);
+  if (waitForAll) {
+    const scope = params.id ? `run "${params.id}"` : initialProviderIds.size === 0 ? `${initialAsyncIds.size} async run(s)` : `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;
+    const status = relevantAttention.length > 0 ? "attention required" : "done";
+    return result(`Waited ${elapsed} for ${scope}; ${status}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`, deps.failOnFailedRuns === true && failedAsyncCount > 0 || deps.failOnAttention === true && relevantAttention.length > 0, completions);
+  }
+  const finishedCount = finishedAsyncCount + providerFinishedCount;
+  const subject = initialProviderIds.size === 0 ? "run(s)" : "item(s)";
+  const remainder = stillRunning > 0 ? ` ${stillRunning} ${subject} still in flight — call bg_wait again to catch the next one.` : relevantAttention.length > 0 ? " No other work is waitable until attention is handled." : initialProviderIds.size === 0 ? " No runs remain in flight." : " No work remains in flight.";
+  const progress = relevantAttention.length > 0 && finishedCount === 0 ? `${relevantAttention.length} of ${initialCount} ${subject} need attention` : `${finishedCount} of ${initialCount} ${subject} finished`;
+  return result(`Waited ${elapsed}; ${progress}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`, deps.failOnFailedRuns === true && failedAsyncCount > 0 || deps.failOnAttention === true && relevantAttention.length > 0, completions);
+}

package/extensions/dm-subagents/src/runs/background/terminal-run-index.js

@@ -0,0 +1,106 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readStatus } from "../../shared/utils.js";
+import { writeAtomicJson } from "../../shared/atomic-json.js";
+import { encodeIndexSegment } from "./index-segment.js";
+export const TERMINAL_RUN_INDEX_DIR = ".terminal-runs";
+const TERMINAL_RUN_INDEX_VERSION = 1;
+const TIMESTAMP_WIDTH = 16;
+function isTerminalState(state) {
+  return state === "complete" || state === "failed" || state === "partial" || state === "paused" || state === "stopped" || state === "rejected";
+}
+function indexRoot(asyncDirRoot) {
+  return path.join(asyncDirRoot, TERMINAL_RUN_INDEX_DIR);
+}
+function sessionIndexDir(asyncDirRoot, sessionId) {
+  return path.join(indexRoot(asyncDirRoot), encodeIndexSegment(sessionId));
+}
+function markerName(endedAt, runId) {
+  return `${Math.max(0, Math.floor(endedAt)).toString().padStart(TIMESTAMP_WIDTH, "0")}-${encodeIndexSegment(runId)}.json`;
+}
+function markerPath(asyncDir, sessionId, endedAt) {
+  return path.join(sessionIndexDir(path.dirname(asyncDir), sessionId), markerName(endedAt, path.basename(asyncDir)));
+}
+function parseEntry(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const entry = value;
+  if (entry.version !== TERMINAL_RUN_INDEX_VERSION || typeof entry.runId !== "string" || !entry.runId || typeof entry.sessionId !== "string" || !entry.sessionId || typeof entry.endedAt !== "number" || !Number.isFinite(entry.endedAt))
+    return;
+  return { version: TERMINAL_RUN_INDEX_VERSION, runId: entry.runId, sessionId: entry.sessionId, endedAt: entry.endedAt };
+}
+export function updateTerminalRunIndex(asyncDir, status) {
+  if (!isTerminalState(status.state) || typeof status.sessionId !== "string" || !status.sessionId)
+    return;
+  const endedAt = status.endedAt ?? status.lastUpdate ?? status.startedAt;
+  const marker = markerPath(asyncDir, status.sessionId, endedAt);
+  const entry = {
+    version: TERMINAL_RUN_INDEX_VERSION,
+    runId: status.runId || path.basename(asyncDir),
+    sessionId: status.sessionId,
+    endedAt
+  };
+  writeAtomicJson(marker, entry);
+}
+function removeInvalidMarker(marker) {
+  try {
+    fs.rmSync(marker, { force: true });
+  } catch {}
+}
+function markerFiles(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => ({ dir, name: entry.name }));
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
+      return [];
+    throw error;
+  }
+}
+function sessionDirs(asyncDirRoot, sessionId) {
+  if (sessionId)
+    return [sessionIndexDir(asyncDirRoot, sessionId)];
+  try {
+    return fs.readdirSync(indexRoot(asyncDirRoot), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => path.join(indexRoot(asyncDirRoot), entry.name));
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
+      return [];
+    throw error;
+  }
+}
+function recentMarkerFiles(dirs, limit) {
+  return dirs.flatMap(markerFiles).sort((left, right) => right.name.localeCompare(left.name)).slice(0, limit).map((marker) => path.join(marker.dir, marker.name));
+}
+export function readRecentTerminalRunIndex(asyncDirRoot, options = {}) {
+  const limit = options.limit === undefined ? Number.POSITIVE_INFINITY : Math.max(0, Math.floor(options.limit));
+  const candidates = recentMarkerFiles(sessionDirs(asyncDirRoot, options.sessionId), limit);
+  const runIds = [];
+  const seen = new Set;
+  for (const marker of candidates) {
+    let entry;
+    try {
+      entry = parseEntry(JSON.parse(fs.readFileSync(marker, "utf-8")));
+    } catch (error) {
+      if (error.code === "ENOENT")
+        continue;
+    }
+    if (!entry || options.sessionId !== undefined && entry.sessionId !== options.sessionId) {
+      removeInvalidMarker(marker);
+      continue;
+    }
+    const asyncDir = path.join(asyncDirRoot, entry.runId);
+    const status = readStatus(asyncDir);
+    if (!status || !isTerminalState(status.state) || status.sessionId !== entry.sessionId || status.runId && status.runId !== entry.runId) {
+      removeInvalidMarker(marker);
+      continue;
+    }
+    if (seen.has(entry.runId)) {
+      removeInvalidMarker(marker);
+      continue;
+    }
+    seen.add(entry.runId);
+    runIds.push(entry.runId);
+  }
+  return runIds;
+}

package/extensions/dm-subagents/src/runs/background/top-level-async.js

@@ -1,5 +1,5 @@
 export function applyForceTopLevelAsyncOverride(params, depth, forceTopLevelAsync) {
-  if (!(depth === 0 && forceTopLevelAsync))
+  if (params.foregroundOnly || !(depth === 0 && forceTopLevelAsync))
     return params;
   return { ...params, async: true, clarify: false };
 }