rovecode 0.4.0-beta.2 → 0.4.0

package/src/core/stuck-detector.ts

@@ -0,0 +1,273 @@
+/**
+ * 5-pattern stuck detector core (eval P0-4 / gap G12).
+ *
+ * Ports OpenHands' agent-stuck-detector semantics (docs.openhands.dev/sdk/guides/
+ * agent-stuck-detector.md, thresholds verified in the harness research, G12) as a PURE
+ * module: no I/O, no clock, no loop imports, bounded memory (a 64-step window). The
+ * loop integration has a SINGLE OWNER by coordinator decision (Orca msg_ef37004c2122,
+ * 2026-09-14) — this file deliberately ships the detector + its API and stops there.
+ * Wire it as a middleware by calling `observe` per loop step and `detect` where a
+ * verdict is needed; nothing in the loop changes until that owner lands the seam.
+ *
+ * The five patterns (defaults follow the research: 4 / 3 / 3 / 6, context-window 2):
+ *  1. repeated-action-observation — the same (action, observation) pair repeated
+ *     ≥ 4 times consecutively; a CHANGED observation resets it (progress forgives).
+ *  2. repeated-action-error       — the same failing action ≥ 3 times consecutively.
+ *  3. monologue                   — ≥ 3 assistant turns with no tool call in a row
+ *                                     (talking instead of working); any action or user
+ *                                     turn resets.
+ *  4. ping-pong                   — two action signatures strictly alternating
+ *                                     ≥ 6 times (A,B,A,B,A,B); a third signature or a
+ *                                     repeat breaks it.
+ *  5. context-window-thrash       — ≥ 2 consecutive context-window errors (the G10
+ *                                     "compacted and immediately full" signature,
+ *                                     represented here via isContextWindowError).
+ *
+ * False-positive protections (the part that makes it shippable):
+ *  - poller exemption: `process` and *_get_result / *_poll style tools legitimately
+ *    repeat — they are exempt from the two repetition patterns (same list hermes'
+ *    guard uses, GUARDRAIL_DEFAULTS.repeatableTools/Suffixes).
+ *  - progress resets: a changed observation, a successful action or a user/steering
+ *    turn resets the relevant streaks; detection degrades to FEWER detections on
+ *    interleaved/parallel wiring, never to more.
+ *  - bounded window: only the last `windowSize` steps are remembered, so a single
+ *    stale pattern cannot shadow a fresh run forever — and a long clean history
+ *    cannot be re-judged from memory it no longer holds.
+ */
+
+export type StuckPattern =
+  | "repeated-action-observation"
+  | "repeated-action-error"
+  | "monologue"
+  | "ping-pong"
+  | "context-window-thrash";
+
+/** OpenHands-derived defaults. "Fires at" semantics: the pattern is reported once the
+ *  run reaches the threshold (4+ pairs, 3+ errors, 3+ turns, 6+ alternations, 2+ errors). */
+export const STUCK_THRESHOLDS = {
+  actionObservation: 4,
+  actionError: 3,
+  monologue: 3,
+  pingPong: 6,
+  contextWindowErrors: 2,
+  windowSize: 64,
+} as const;
+
+export interface StuckStep {
+  kind: "action" | "observation" | "assistant" | "user";
+  /** tool name (action/observation) */
+  tool?: string;
+  /** caller-computed canonical signature: action = tool+args hash, observation = output
+   *  hash. The detector compares signatures; it never sees payloads. */
+  signature?: string;
+  /** observation success flag (action-error pattern) */
+  ok?: boolean;
+  /** observation errored because the context window/limit was hit (thrash pattern) */
+  isContextWindowError?: boolean;
+  /** assistant text length — a no-tool turn (monologue pattern) */
+  textLength?: number;
+}
+
+export interface StuckEvent {
+  pattern: StuckPattern;
+  /** how many consecutive steps/pairs the pattern has run (≥ threshold) */
+  count: number;
+  detail: string;
+}
+
+export interface StuckThresholds {
+  actionObservation: number;
+  actionError: number;
+  monologue: number;
+  pingPong: number;
+  contextWindowErrors: number;
+}
+
+export interface StuckDetectorOptions {
+  thresholds?: Partial<StuckThresholds>;
+  /** tools exempt from the repetition patterns (default: hermes' poller list) */
+  repeatableTools?: readonly string[];
+  /** name suffixes exempt likewise (default: ["_get_result", "_poll"]) */
+  repeatableSuffixes?: readonly string[];
+}
+
+interface Resolved {
+  thresholds: StuckThresholds;
+  repeatableTools: ReadonlySet<string>;
+  repeatableSuffixes: readonly string[];
+  windowSize: number;
+}
+
+/** Severity order for report lists: hard errors first, chatty monologues last. */
+const PATTERN_ORDER: readonly StuckPattern[] = [
+  "context-window-thrash",
+  "repeated-action-error",
+  "repeated-action-observation",
+  "ping-pong",
+  "monologue",
+];
+
+function positiveInt(v: number | undefined, fallback: number): number {
+  if (v === undefined || !Number.isFinite(v)) return fallback;
+  const n = Math.trunc(v);
+  return n >= 1 ? n : fallback;
+}
+
+export class StuckDetector {
+  private readonly opts: Resolved;
+  private window: StuckStep[] = [];
+
+  constructor(opts?: StuckDetectorOptions) {
+    const d = STUCK_THRESHOLDS;
+    this.opts = {
+      thresholds: {
+        actionObservation: positiveInt(opts?.thresholds?.actionObservation, d.actionObservation),
+        actionError: positiveInt(opts?.thresholds?.actionError, d.actionError),
+        monologue: positiveInt(opts?.thresholds?.monologue, d.monologue),
+        pingPong: positiveInt(opts?.thresholds?.pingPong, d.pingPong),
+        contextWindowErrors: positiveInt(opts?.thresholds?.contextWindowErrors, d.contextWindowErrors),
+      },
+      repeatableTools: new Set(opts?.repeatableTools ?? ["process"]),
+      repeatableSuffixes: opts?.repeatableSuffixes ?? ["_get_result", "_poll"],
+      windowSize: d.windowSize,
+    };
+  }
+
+  /** Feed one loop step (action = the assistant's tool call, observation = its result).
+   *  Oldest steps beyond the window bound are forgotten. */
+  observe(step: StuckStep): void {
+    this.window.push(step);
+    if (this.window.length > this.opts.windowSize) this.window.splice(0, this.window.length - this.opts.windowSize);
+  }
+
+  /** Active stuck patterns over the current window, most severe first. */
+  detect(): StuckEvent[] {
+    const events: StuckEvent[] = [];
+    const push = (pattern: StuckPattern, count: number, detail: string): void => {
+      events.push({ pattern, count, detail });
+    };
+
+    // 1+2. consecutive (action, observation) pairs — by action signature, split ok / error
+    type Pair = { actionSig: string; obsSig: string | null; ok: boolean; tool: string };
+    const pairs: Pair[] = [];
+    let pending: { tool: string; sig: string } | null = null;
+    for (const step of this.window) {
+      if (step.kind === "action") {
+        pending = { tool: step.tool ?? "?", sig: step.signature ?? "" };
+        continue;
+      }
+      if (step.kind === "observation" && pending !== null) {
+        pairs.push({ actionSig: pending.sig, obsSig: step.signature ?? null, ok: step.ok !== false, tool: pending.tool });
+        pending = null;
+      } else if (step.kind === "user" || step.kind === "assistant") {
+        pending = null; // an interleaved non-observation breaks the pairing
+      }
+    }
+    const exempt = (tool: string): boolean =>
+      this.opts.repeatableTools.has(tool) || this.opts.repeatableSuffixes.some((s) => tool.endsWith(s));
+
+    let okStreak: { sig: string; obs: string | null; tool: string; count: number } | null = null;
+    let errStreak: { sig: string; tool: string; count: number } | null = null;
+    let okMax: { count: number; tool: string } | null = null;
+    let errMax: { count: number; tool: string } | null = null;
+    for (const p of pairs) {
+      const repeatable = exempt(p.tool);
+      // ok-pairs: same action AND same observation signature — changed obs = progress
+      if (!repeatable && p.ok && p.actionSig === okStreak?.sig && p.obsSig === okStreak.obs) {
+        okStreak.count++;
+      } else {
+        okStreak = p.ok && !repeatable ? { sig: p.actionSig, obs: p.obsSig, tool: p.tool, count: 1 } : null;
+      }
+      if (okStreak !== null && (okMax === null || okStreak.count > okMax.count)) {
+        okMax = { count: okStreak.count, tool: okStreak.tool };
+      }
+      // error-pairs: same action failing repeatedly
+      if (!repeatable && !p.ok && p.actionSig === errStreak?.sig) {
+        errStreak.count++;
+      } else {
+        errStreak = !p.ok && !repeatable ? { sig: p.actionSig, tool: p.tool, count: 1 } : null;
+      }
+      if (errStreak !== null && (errMax === null || errStreak.count > errMax.count)) {
+        errMax = { count: errStreak.count, tool: errStreak.tool };
+      }
+    }
+    if (okMax !== null && okMax.count >= this.opts.thresholds.actionObservation) {
+      push("repeated-action-observation", okMax.count, `identical action+observation pair repeated ${okMax.count}× (tool ${okMax.tool})`);
+    }
+    if (errMax !== null && errMax.count >= this.opts.thresholds.actionError) {
+      push("repeated-action-error", errMax.count, `the same failing action repeated ${errMax.count}× (tool ${errMax.tool})`);
+    }
+
+    // 3. monologue: consecutive assistant turns with no action in between
+    let mono = 0;
+    let monoMax = 0;
+    for (const step of this.window) {
+      if (step.kind === "assistant") {
+        mono++;
+        monoMax = Math.max(monoMax, mono);
+      } else if (step.kind === "action" || step.kind === "user") {
+        mono = 0;
+      }
+      // observations belong to their action; they do not reset the count
+    }
+    if (monoMax >= this.opts.thresholds.monologue) {
+      push("monologue", monoMax, `${monoMax} consecutive assistant turns with no tool call`);
+    }
+
+    // 4. ping-pong: strict two-signature alternation (a repeat or a third signature breaks it)
+    let cycle: string[] = [];
+    let cycleMax = 0;
+    for (const step of this.window) {
+      if (step.kind !== "action" || step.signature === undefined || exempt(step.tool ?? "?")) {
+        continue;
+      }
+      const sig = step.signature;
+      if (cycle.length >= 2 && cycle[cycle.length - 1] === sig) {
+        cycle = [sig]; // immediate repeat — that is pattern 1's territory, not alternation
+      } else if (cycle.length >= 2 && cycle[cycle.length - 2] === sig) {
+        cycle.push(sig); // continues the A,B,A… alternation
+      } else if (cycle.length < 2) {
+        cycle.push(sig);
+      } else {
+        cycle = [sig]; // a third signature broke it
+      }
+      cycleMax = Math.max(cycleMax, cycle.length);
+    }
+    if (cycleMax >= this.opts.thresholds.pingPong) {
+      push("ping-pong", cycleMax, `two actions strictly alternating ${cycleMax}× without progress`);
+    }
+
+    // 5. context-window thrash: consecutive context-window errors
+    let cw = 0;
+    let cwMax = 0;
+    for (const step of this.window) {
+      if (step.isContextWindowError === true) {
+        cw++;
+        cwMax = Math.max(cwMax, cw);
+      } else {
+        cw = 0;
+      }
+    }
+    if (cwMax >= this.opts.thresholds.contextWindowErrors) {
+      push("context-window-thrash", cwMax, `${cwMax} consecutive context-window errors — the window refills as fast as it compacts`);
+    }
+
+    return events.sort((a, b) => PATTERN_ORDER.indexOf(a.pattern) - PATTERN_ORDER.indexOf(b.pattern));
+  }
+
+  isStuck(): boolean {
+    return this.detect().length > 0;
+  }
+
+  /** Full reset (new run / new user turn). */
+  reset(): void {
+    this.window = [];
+  }
+}
+
+/** Stateless form over a recorded step list (eval/replay, tests, offline analysis). */
+export function detectStuck(steps: readonly StuckStep[], opts?: StuckDetectorOptions): StuckEvent[] {
+  const d = new StuckDetector(opts);
+  for (const s of steps) d.observe(s);
+  return d.detect();
+}

package/src/core/tasks.ts

@@ -0,0 +1,374 @@
+/** Background subagents as jobs (port #26): a bounded FIFO job manager over the ONE
+ *  agent loop. Every task runs through orchestrator.ts runChild (ADR-009), which runs
+ *  agentLoop (ADR-003) — this file only schedules, collects results and notifies. It is
+ *  NOT a second loop generation (research/anti_patterns.md:13; ADR-013 rejects lanes
+ *  that are not child sessions/jobs).
+ *
+ *  Pattern source: opencode packages/core/src/background-job.ts (MIT, snapshot
+ *  research/source_snapshots/opencode-2026 @ ebece6e) — a process-local, deliberately
+ *  non-durable job registry (:113-119); Status running|completed|error|cancelled (:7);
+ *  Info {id,type,title,status,started_at,completed_at,output,error} (:9-19); start forks
+ *  the run and settle() derives the terminal status from the exit (:126-171, :202-254);
+ *  wait with an optional timeout returns the snapshot on timeout (:292-301); cancel marks
+ *  the job and closes its scope (:337-358). Its task tool (packages/opencode/src/tool/
+ *  task.ts) injects a synthetic message into the PARENT session when the job settles
+ *  (:227-265 inject/notify) and tells the model not to poll (:31-35).
+ *  Departures: opencode starts every job at once (no bound); here a FIFO queue bounds
+ *  concurrency (default 3, env ROVECODE_TASKS_MAX) and a RUNNING task that waits on a QUEUED
+ *  one lends it its slot so nested pools cannot deadlock. Their notification is a new
+ *  prompt on the parent session; ours is a push into the parent's SteeringQueue, which
+ *  the loop drains before its next model call (loop.ts:136) — the loop stays untouched. */
+
+import { SteeringQueue } from "./loop.ts";
+import { DEFAULT_MAX_DEPTH, preflightSpawn, runChild, type ChildRunnerDeps } from "./orchestrator.ts";
+import type { SpawnRequest, SpawnResult, TokenUsage } from "./types.ts";
+
+export type TaskId = string;
+export type TaskStatus = "queued" | "running" | "done" | "failed" | "cancelled";
+
+export interface TaskInfo {
+  id: TaskId;
+  label: string;
+  agent: string;
+  /** bounded preview of the goal (≤200 chars) */
+  goal: string;
+  isolated: boolean;
+  /** the child's depth (parent depth + 1; root-started tasks run at 1) */
+  depth: number;
+  /** the RUNNING task that started this one (StartOptions.caller); absent for
+   *  root-started tasks — the sdk/dashboard agent tree hangs on this edge */
+  parent?: TaskId;
+  status: TaskStatus;
+  createdAt: number;
+  startedAt?: number;
+  finishedAt?: number;
+  /** the child's final text (done) — bounded by runChild (≤4000 chars) */
+  summary?: string;
+  /** failure reason (failed) or "cancelled" */
+  error?: string;
+  usage?: TokenUsage;
+  /** isolated children: line count of the patch merged back into the parent tree */
+  patchLines?: number;
+}
+
+export interface StartOptions {
+  label?: string;
+  /** depth of the loop starting this task (root = 0); the child runs at depth + 1,
+   *  mirroring the loop's own ctx.spawn contract (loop.ts:267) */
+  parentDepth?: number;
+  /** where the completion note lands; default = the queue attached to the manager */
+  notify?: SteeringQueue;
+  /** id of the RUNNING task that starts this one (nested) — enables slot lending */
+  caller?: TaskId;
+  /** the run that OWNS this task: its abort cancels the task (nested: the parent task's
+   *  own signal, so cancellation cascades). Default = the signal bound via bindRun(). */
+  owner?: AbortSignal;
+}
+
+/** `childPolicy` (fix-wave MED-2): how the child's rules derive from the starting run's —
+ *  "gated" when that config carries a prompt rule (children turn prompt→deny, orchestrator
+ *  deriveChildRules: read-only unless allow rules cover an action), "open" otherwise (yolo).
+ *  The `task` tool's start output says so, for the approver and the model. */
+export type StartResult = { ok: true; id: TaskId; childPolicy: "gated" | "open" } | { ok: false; reason: string };
+
+export interface WaitOptions {
+  /** max wait in ms; undefined = until settled (hold an abort signal); 0 = snapshot now */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /** the running task doing the waiting — its slot is lent to a queued waited-on task */
+  caller?: TaskId;
+}
+
+export interface TaskManagerOptions {
+  /** child runner deps, resolved at EACH start so defs/config follow the parent's
+   *  latest run; null = no provider configured (start refuses) */
+  deps: () => ChildRunnerDeps | null;
+  /** concurrent children bound; default tasksMaxFromEnv() */
+  maxConcurrent?: number;
+  maxDepth?: number;
+  /** injectable child runner (tests); default orchestrator runChild */
+  run?: typeof runChild;
+}
+
+export const DEFAULT_TASKS_MAX = 3;
+
+/** ROVECODE_TASKS_MAX: positive integer, else the default. */
+export function tasksMaxFromEnv(env: Record<string, string | undefined> = process.env): number {
+  const n = Number(env["ROVECODE_TASKS_MAX"] ?? "");
+  return Number.isInteger(n) && n >= 1 ? n : DEFAULT_TASKS_MAX;
+}
+
+interface TaskRecord {
+  info: TaskInfo;
+  req: SpawnRequest;
+  deps: ChildRunnerDeps;
+  ac: AbortController;
+  notify?: SteeringQueue;
+  done: Promise<void>;
+  resolveDone: () => void;
+  /** true once the child run has RETURNED (status alone is not enough: cancel() flips
+   *  status to "cancelled" while the aborted run is still winding down) */
+  settled: boolean;
+  /** detach the owner-abort listener (settle) */
+  unbind?: () => void;
+}
+
+const TERMINAL: ReadonlySet<TaskStatus> = new Set(["done", "failed", "cancelled"]);
+export const isTerminal = (s: TaskStatus): boolean => TERMINAL.has(s);
+
+function brief(text: string | undefined, max = 200): string {
+  const one = (text ?? "").split("\n").find((l) => l.trim() !== "")?.trim() ?? "";
+  return one.length > max ? one.slice(0, max - 1) + "…" : one || "(no output)";
+}
+
+/** The steer the parent sees on its next turn (opencode task.ts:241-249 renders a
+ *  <task state> block; ours is one line the model can act on). */
+export function taskNote(t: TaskInfo): string {
+  const head = `task ${t.id} (${t.label})`;
+  if (t.status === "done") return `${head} finished: ${brief(t.summary)} — call task_status result ${t.id} for details`;
+  if (t.status === "failed") return `${head} failed: ${brief(t.error)} — call task_status result ${t.id} for details`;
+  return `${head} cancelled`;
+}
+
+/** One line per task for /tasks and the tool's list action; newest last, ≤50 rows. */
+export function formatTaskList(tasks: TaskInfo[], now = Date.now()): string {
+  if (tasks.length === 0) return "(no background tasks)";
+  const rows = tasks.slice(-50).map((t) => {
+    const end = t.finishedAt ?? now;
+    const age = t.startedAt !== undefined ? ` ${Math.max(0, Math.round((end - t.startedAt) / 1000))}s` : "";
+    const tail = t.status === "failed" ? ` — ${brief(t.error, 80)}` : t.status === "done" ? ` — ${brief(t.summary, 80)}` : "";
+    return `${t.id.padEnd(4)} ${t.status.padEnd(9)}${age.padEnd(6)} ${t.label}${tail}`;
+  });
+  return (tasks.length > 50 ? `(showing 50 of ${tasks.length})\n` : "") + rows.join("\n");
+}
+
+export class TaskManager {
+  readonly maxConcurrent: number;
+  readonly maxDepth: number;
+  private readonly tasks = new Map<TaskId, TaskRecord>();
+  private readonly queue: TaskId[] = [];
+  private readonly listeners = new Set<(t: TaskInfo) => void>();
+  private readonly run: typeof runChild;
+  private sink: SteeringQueue | null = null;
+  private runSignal: AbortSignal | null = null;
+  private running = 0;
+  private seq = 0;
+
+  constructor(private readonly opts: TaskManagerOptions) {
+    this.maxConcurrent = Math.max(1, Math.floor(opts.maxConcurrent ?? tasksMaxFromEnv()));
+    // fix-wave L4: runChild re-preflights against the orchestrator's DEFAULT_MAX_DEPTH, so a
+    // LARGER manager cap would launch a child only to fail it there — clamp, and every depth
+    // refusal is start() data. Smaller caps are honored as given.
+    this.maxDepth = Math.min(opts.maxDepth ?? DEFAULT_MAX_DEPTH, DEFAULT_MAX_DEPTH);
+    this.run = opts.run ?? runChild;
+  }
+
+  /** Default notification target: the SAME SteeringQueue the surface hands to agentLoop. */
+  attach(steering: SteeringQueue): void { this.sink = steering; }
+
+  /** The surface's per-run controller signal (the one Esc / DELETE / session-cancel
+   *  aborts): root tasks started from now on are owned by that run and cancelled when it
+   *  aborts. NOT ToolContext.signal — the loop's own controller aborts on EVERY settle,
+   *  a normal run end included (loop.ts:91), which would kill background work the moment
+   *  the parent finishes its turn. Call before each agentLoop; tasks from earlier runs
+   *  keep their own owner. */
+  bindRun(signal: AbortSignal): void { this.runSignal = signal; }
+
+  /** Enqueue a child run. Refusals are data, never throws: unknown agent, no provider,
+   *  an already-aborted owner, and the orchestrator's own preflight (depth cap, spawn
+   *  policy "none"). */
+  start(req: SpawnRequest, opts: StartOptions = {}): StartResult {
+    const deps = this.opts.deps();
+    if (!deps) return { ok: false, reason: "no provider configured" };
+    const def = deps.defs.get(req.agent);
+    if (!def) return { ok: false, reason: `unknown agent '${req.agent}'` };
+    const owner = opts.owner ?? this.runSignal ?? undefined;
+    if (owner?.aborted) return { ok: false, reason: "parent run aborted" };
+    const depth = (opts.parentDepth ?? 0) + 1;
+    const gate = preflightSpawn(def, { depth, maxDepth: this.maxDepth, parentSessionId: opts.caller ?? "" });
+    if (!gate.ok) return { ok: false, reason: gate.reason ?? "spawn refused" };
+    const childPolicy = deps.baseConfig.permissionRules.some((r) => r.effect === "prompt") ? "gated" : "open";
+    const id: TaskId = `t${++this.seq}`;
+    let resolveDone: () => void = () => {};
+    const done = new Promise<void>((r) => { resolveDone = r; });
+    const goal = req.goal.replace(/\s+/g, " ").trim();
+    const rec: TaskRecord = {
+      info: {
+        id, label: (opts.label ?? "").trim() || (goal.length > 40 ? goal.slice(0, 39) + "…" : goal || "(no goal)"),
+        agent: req.agent, goal: goal.length > 200 ? goal.slice(0, 199) + "…" : goal,
+        isolated: req.isolated === true, depth, status: "queued", createdAt: Date.now(),
+        ...(opts.caller !== undefined ? { parent: opts.caller } : {}),
+      },
+      req, deps, ac: new AbortController(), notify: opts.notify, done, resolveDone, settled: false,
+    };
+    if (owner) {
+      // a parent-run abort reaches its children: cancel() aborts the child's own controller
+      const onAbort = (): void => { this.cancel(id); };
+      owner.addEventListener("abort", onAbort, { once: true });
+      rec.unbind = () => owner.removeEventListener("abort", onAbort);
+    }
+    this.tasks.set(id, rec);
+    this.queue.push(id);
+    this.emit(rec);
+    this.pump();
+    return { ok: true, id, childPolicy };
+  }
+
+  status(id: TaskId): TaskInfo | undefined {
+    const t = this.tasks.get(id);
+    return t ? { ...t.info } : undefined;
+  }
+
+  /** All tasks, oldest first. */
+  list(): TaskInfo[] { return [...this.tasks.values()].map((t) => ({ ...t.info })); }
+
+  counts(): Record<TaskStatus, number> {
+    const c: Record<TaskStatus, number> = { queued: 0, running: 0, done: 0, failed: 0, cancelled: 0 };
+    for (const t of this.tasks.values()) c[t.info.status]++;
+    return c;
+  }
+
+  /** Wait for a task to settle (bounded/abortable), then return its snapshot — on a
+   *  timeout or abort the snapshot still reports the live status. A cancelled task is
+   *  "settled" only once its aborted run has returned. Unknown id → undefined. */
+  async result(id: TaskId, opts: WaitOptions = {}): Promise<TaskInfo | undefined> {
+    const t = this.tasks.get(id);
+    if (!t) return undefined;
+    if (t.settled) return { ...t.info };
+    // slot lending: the waiter holds a slot but generates no load while it waits — under
+    // a full pool a parent waiting on its queued child would otherwise sit until the
+    // deadline (nested-pool deadlock). Promote the waited-on task now; `running` may
+    // exceed the bound by exactly the number of blocked waiters.
+    if (t.info.status === "queued" && opts.caller !== undefined && this.tasks.get(opts.caller)?.info.status === "running") {
+      this.dequeue(id);
+      this.launch(t);
+    }
+    await waitFor(t.done, opts.timeoutMs, opts.signal);
+    return { ...t.info };
+  }
+
+  /** Cancel: a queued task never runs; a running one has its child run aborted (the
+   *  signal threads runChild → agentLoop → fetch/tools) and settles when it returns.
+   *  Returns the snapshot (status already "cancelled"); unknown id → undefined. */
+  cancel(id: TaskId): TaskInfo | undefined {
+    const t = this.tasks.get(id);
+    if (!t) return undefined;
+    if (isTerminal(t.info.status)) return { ...t.info };
+    if (t.info.status === "queued") {
+      this.dequeue(id);
+      t.info.status = "cancelled"; t.info.error = "cancelled";
+      this.settle(t);
+    } else {
+      t.info.status = "cancelled"; t.info.error = "cancelled";
+      t.ac.abort(); // finish() → settle() runs (one terminal emission) when runChild returns
+    }
+    return { ...t.info };
+  }
+
+  /** Cancel every non-terminal task (surface shutdown); returns how many were live. */
+  cancelAll(): number {
+    let n = 0;
+    for (const t of this.tasks.values()) {
+      if (!isTerminal(t.info.status)) { this.cancel(t.info.id); n++; }
+    }
+    return n;
+  }
+
+  /** Resolve when nothing is queued or running (or the deadline passes → false). */
+  async drain(timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    while (this.running > 0 || this.queue.length > 0) {
+      if (Date.now() >= deadline) return false;
+      await new Promise<void>((r) => setTimeout(r, 10));
+    }
+    return true;
+  }
+
+  /** Status-transition listener (TUI live notes, tests). Returns the unsubscribe. */
+  subscribe(fn: (t: TaskInfo) => void): () => void {
+    this.listeners.add(fn);
+    return () => { this.listeners.delete(fn); };
+  }
+
+  private dequeue(id: TaskId): void {
+    const i = this.queue.indexOf(id);
+    if (i >= 0) this.queue.splice(i, 1);
+  }
+
+  private pump(): void {
+    while (this.running < this.maxConcurrent && this.queue.length > 0) {
+      const t = this.tasks.get(this.queue.shift()!);
+      if (t && t.info.status === "queued") this.launch(t);
+    }
+  }
+
+  private launch(t: TaskRecord): void {
+    t.info.status = "running"; t.info.startedAt = Date.now();
+    this.running++;
+    this.emit(t);
+    // the child's registry learns its task id (ChildContext) so a nested `task_status result`
+    // can identify its caller for slot lending
+    const deps: ChildRunnerDeps = {
+      ...t.deps,
+      registryFactory: (def, cwd, child) => t.deps.registryFactory(def, cwd, child ? { ...child, taskId: t.info.id } : undefined),
+    };
+    void this.run(deps, t.req, t.info.depth, t.ac.signal)
+      .then((r) => this.finish(t, r), (e: unknown) => this.finish(t, undefined, e))
+      .finally(() => { this.running--; this.pump(); });
+  }
+
+  private finish(t: TaskRecord, r: SpawnResult | undefined, err?: unknown): void {
+    const info = t.info;
+    if (info.status === "cancelled") {
+      if (r) info.usage = r.usage; // the aborted run's own summary ("run aborted") is not a result
+    } else if (r === undefined) {
+      info.status = "failed";
+      info.error = `child runner threw: ${err instanceof Error ? err.message : String(err)}`;
+    } else if (!r.ok) {
+      info.status = "failed"; info.error = r.summary; info.usage = r.usage;
+    } else {
+      info.status = "done"; info.summary = r.summary; info.usage = r.usage;
+      if (r.patch !== undefined) info.patchLines = r.patch.trim() === "" ? 0 : r.patch.split("\n").length;
+    }
+    this.settle(t);
+  }
+
+  /** Terminal tail shared by finish() and queued-cancel: stamp, notify the parent
+   *  (steer — queued BEFORE waiters wake, so a `result` waiter's next turn sees it),
+   *  release waiters, tell listeners. */
+  private settle(t: TaskRecord): void {
+    t.settled = true;
+    t.unbind?.();
+    t.info.finishedAt = Date.now();
+    (t.notify ?? this.sink)?.push(taskNote(t.info));
+    t.resolveDone();
+    this.emit(t);
+  }
+
+  private emit(t: TaskRecord): void {
+    for (const fn of this.listeners) {
+      try { fn({ ...t.info }); } catch { /* listeners never break the manager */ }
+    }
+  }
+}
+
+/** Resolve when `p` settles, the deadline passes, or `signal` aborts — whichever is
+ *  first; the timer and listener are always released (a pending timer would hold the
+ *  process; a parked promise with no timer hangs the Bun runner). */
+function waitFor(p: Promise<void>, timeoutMs: number | undefined, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let settled = false;
+    const finish = (): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      signal?.removeEventListener("abort", finish);
+      resolve();
+    };
+    if (signal?.aborted) { finish(); return; }
+    if (timeoutMs !== undefined) timer = setTimeout(finish, Math.max(0, timeoutMs));
+    signal?.addEventListener("abort", finish, { once: true });
+    void p.then(finish, finish);
+  });
+}