@wrongstack/core 0.6.4 → 0.6.5

package/dist/execution/index.js

@@ -2,7 +2,8 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { randomBytes } from 'crypto';
+import { randomUUID, randomBytes } from 'crypto';
+import { EventEmitter } from 'events';
 
 // src/utils/token-estimate.ts
 var RoughTokenEstimate = (text, charsPerToken = 3.5) => Math.max(1, Math.ceil(text.length / charsPerToken));
@@ -2231,6 +2232,1369 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/coordination/subagent-budget.ts
+var BudgetExceededError = class extends Error {
+  kind;
+  limit;
+  observed;
+  constructor(kind, limit, observed) {
+    super(`Budget exceeded: ${kind} (limit=${limit}, observed=${observed})`);
+    this.name = "BudgetExceededError";
+    this.kind = kind;
+    this.limit = limit;
+    this.observed = observed;
+  }
+};
+var BudgetThresholdSignal = class extends Error {
+  kind;
+  limit;
+  used;
+  /** Resolves to 'extend' (with optional new limits) or 'stop' */
+  decision;
+  constructor(kind, limit, used, decision) {
+    super(`Budget soft limit: ${kind} (limit=${limit}, used=${used})`);
+    this.name = "BudgetThresholdSignal";
+    this.kind = kind;
+    this.limit = limit;
+    this.used = used;
+    this.decision = decision;
+  }
+};
+var SubagentBudget = class _SubagentBudget {
+  limits;
+  iterations = 0;
+  toolCalls = 0;
+  tokenInput = 0;
+  tokenOutput = 0;
+  costUsd = 0;
+  startTime = null;
+  _onThreshold;
+  /**
+   * Tracks which budget kinds currently have an extension request
+   * in flight. While a kind is here, further `checkLimit` calls for the
+   * same kind are no-ops — without this dedup, every `recordIteration`
+   * after the limit is reached spawns a fresh decision Promise (until
+   * the first one lands and patches limits), flooding the FleetBus
+   * with redundant threshold events. Cleared in `checkLimitAsync`'s
+   * `finally`.
+   */
+  pendingExtensions = /* @__PURE__ */ new Set();
+  /**
+   * Hard cap on how long `checkLimitAsync` waits for the coordinator to
+   * respond before defaulting to 'stop'. Without this fallback an absent
+   * or hung listener (Director not built / event filter detached mid-run)
+   * leaves the budget over-limit and never enforces anything, since
+   * `checkLimit` returns synchronously via `void this.checkLimitAsync`.
+   * Hardcoded for now — most fleets set their own per-task timeout that
+   * dwarfs this anyway. 30 s matches the existing event-emit timeoutMs.
+   */
+  static DECISION_TIMEOUT_MS = 3e4;
+  /**
+   * Injected by the runner when wiring the budget to its EventBus.
+   * Used by `checkLimitAsync` to emit `budget.threshold_reached` events.
+   */
+  _events;
+  /**
+   * Optional callback for soft-limit handling. When set, the budget will
+   * call this instead of throwing when a limit is first reached. The
+   * handler decides whether to throw, continue, or ask the coordinator.
+   */
+  get onThreshold() {
+    return this._onThreshold;
+  }
+  set onThreshold(fn) {
+    this._onThreshold = fn;
+  }
+  constructor(limits = {}) {
+    this.limits = Object.freeze({ ...limits });
+  }
+  start() {
+    this.startTime = Date.now();
+  }
+  /** Returns true if we're within 10% of any limit — useful for pre-flight checks. */
+  isNearLimit() {
+    const { maxIterations, maxToolCalls, maxTokens, maxCostUsd } = this.limits;
+    if (maxIterations && this.iterations >= maxIterations * 0.9) return true;
+    if (maxToolCalls && this.toolCalls >= maxToolCalls * 0.9) return true;
+    if (maxTokens && this.tokenInput + this.tokenOutput >= maxTokens * 0.9) return true;
+    if (maxCostUsd && this.costUsd >= maxCostUsd * 0.9) return true;
+    return false;
+  }
+  /**
+   * Synchronous budget check — always throws synchronously so callers
+   * (especially test event handlers using `expect().toThrow()`) get an
+   * unhandled rejection when the budget is exceeded without a handler.
+   * When `onThreshold` IS configured, the actual async threshold-handling
+   * is dispatched as a fire-and-forget promise.
+   */
+  checkLimit(kind, used, limit) {
+    if (!this._onThreshold) {
+      throw new BudgetExceededError(kind, limit, used);
+    }
+    const bus = this._events;
+    if (!bus || bus.listenerCount("budget.threshold_reached") === 0) {
+      throw new BudgetExceededError(kind, limit, used);
+    }
+    if (this.pendingExtensions.has(kind)) return;
+    this.pendingExtensions.add(kind);
+    const decision = this.negotiateExtension(kind, used, limit);
+    throw new BudgetThresholdSignal(kind, limit, used, decision);
+  }
+  /**
+   * Drive the threshold handler to a decision. Resolves with `'stop'`
+   * (signal the runner to abort) or `{ extend: ... }` (limits already
+   * patched in-place; the runner should not abort). Always releases the
+   * `pendingExtensions` slot in `finally`.
+   *
+   * The 'continue' return from a sync handler is treated as
+   * `{ extend: {} }` — keep going without patching, next overrun will
+   * fire a fresh signal.
+   */
+  async negotiateExtension(kind, used, limit) {
+    try {
+      const result = this._onThreshold({
+        kind,
+        used,
+        limit,
+        // Inject a requestDecision helper the handler can call to emit the
+        // budget.threshold_reached event and wait for the coordinator's verdict.
+        // A hard fallback timer guarantees the promise eventually resolves
+        // even if no listener responds — without it, an absent/detached
+        // Director would leave the budget permanently in "asking" state.
+        requestDecision: () => {
+          const bus = this._events;
+          if (!bus || bus.listenerCount("budget.threshold_reached") === 0) {
+            return Promise.resolve("stop");
+          }
+          return new Promise((resolve) => {
+            let resolved = false;
+            const respond = (d) => {
+              if (resolved) return;
+              resolved = true;
+              resolve(d);
+            };
+            const fallback = setTimeout(
+              () => respond("stop"),
+              _SubagentBudget.DECISION_TIMEOUT_MS
+            );
+            bus.emit("budget.threshold_reached", {
+              kind,
+              used,
+              limit,
+              timeoutMs: _SubagentBudget.DECISION_TIMEOUT_MS,
+              extend: (extra) => {
+                clearTimeout(fallback);
+                respond({ extend: extra });
+              },
+              deny: () => {
+                clearTimeout(fallback);
+                respond("stop");
+              }
+            });
+          });
+        }
+      });
+      if (result === "throw") return "stop";
+      if (result === "continue") return { extend: {} };
+      const decision = await result;
+      if (decision === "stop") return "stop";
+      const ext = decision.extend;
+      if (ext.maxIterations !== void 0) {
+        this.limits.maxIterations = ext.maxIterations;
+      }
+      if (ext.maxToolCalls !== void 0) {
+        this.limits.maxToolCalls = ext.maxToolCalls;
+      }
+      if (ext.maxTokens !== void 0) {
+        this.limits.maxTokens = ext.maxTokens;
+      }
+      if (ext.maxCostUsd !== void 0) {
+        this.limits.maxCostUsd = ext.maxCostUsd;
+      }
+      if (ext.timeoutMs !== void 0) {
+        this.limits.timeoutMs = ext.timeoutMs;
+      }
+      return decision;
+    } finally {
+      this.pendingExtensions.delete(kind);
+    }
+  }
+  recordIteration() {
+    this.iterations++;
+    if (this.limits.maxIterations !== void 0 && this.iterations > this.limits.maxIterations) {
+      void this.checkLimit("iterations", this.iterations, this.limits.maxIterations);
+    }
+  }
+  recordToolCall() {
+    this.toolCalls++;
+    if (this.limits.maxToolCalls !== void 0 && this.toolCalls > this.limits.maxToolCalls) {
+      void this.checkLimit("tool_calls", this.toolCalls, this.limits.maxToolCalls);
+    }
+  }
+  recordUsage(usage, costUsd = 0) {
+    this.tokenInput += usage.input;
+    this.tokenOutput += usage.output;
+    this.costUsd += costUsd;
+    const totalTokens = this.tokenInput + this.tokenOutput;
+    if (this.limits.maxTokens !== void 0 && totalTokens > this.limits.maxTokens) {
+      void this.checkLimit("tokens", totalTokens, this.limits.maxTokens);
+    }
+    if (this.limits.maxCostUsd !== void 0 && this.costUsd > this.limits.maxCostUsd) {
+      void this.checkLimit("cost", this.costUsd, this.limits.maxCostUsd);
+    }
+  }
+  /**
+   * Wall-clock budget check. Unlike other limits, timeout is treated as a
+   * warning-only event — it NEVER hard-stops the subagent. When the
+   * elapsed time exceeds timeoutMs, emits `budget.threshold_reached` with
+   * kind='timeout' so the Director can decide whether to extend or warn.
+   * Call this from the iteration loop so a hung tool gets a chance to
+   * negotiate more time before the coordinator's Promise.race kills it.
+   */
+  checkTimeout() {
+    if (this.startTime === null || this.limits.timeoutMs === void 0) return;
+    const elapsed = Date.now() - this.startTime;
+    if (elapsed > this.limits.timeoutMs) {
+      void this.checkLimit("timeout", elapsed, this.limits.timeoutMs);
+    }
+  }
+  /** Returns true if a timeout has occurred without throwing. Useful for races. */
+  isTimedOut() {
+    if (this.startTime === null || this.limits.timeoutMs === void 0) return false;
+    return Date.now() - this.startTime > this.limits.timeoutMs;
+  }
+  usage() {
+    return {
+      iterations: this.iterations,
+      toolCalls: this.toolCalls,
+      tokens: {
+        input: this.tokenInput,
+        output: this.tokenOutput,
+        total: this.tokenInput + this.tokenOutput
+      },
+      costUsd: this.costUsd,
+      elapsedMs: this.startTime === null ? 0 : Date.now() - this.startTime
+    };
+  }
+};
+
+// src/coordination/agent-subagent-runner.ts
+function makeAgentSubagentRunner(opts) {
+  const format = opts.formatTaskInput ?? defaultFormatTaskInput;
+  return async (task, ctx) => {
+    const factoryResult = await opts.factory(ctx.config);
+    const { agent, events } = factoryResult;
+    const detachFleet = opts.fleetBus?.attach(ctx.subagentId, events, task.id);
+    const aborter = new AbortController();
+    ctx.budget._events = events;
+    ctx.budget.onThreshold = ({ requestDecision }) => requestDecision();
+    let budgetError = null;
+    const onBudgetError = (err) => {
+      if (err instanceof BudgetThresholdSignal) {
+        err.decision.then((decision) => {
+          if (decision === "stop") {
+            budgetError = new BudgetExceededError(err.kind, err.limit, err.used);
+            aborter.abort();
+          }
+        }).catch(() => {
+          budgetError = new BudgetExceededError(err.kind, err.limit, err.used);
+          aborter.abort();
+        });
+        return;
+      }
+      aborter.abort();
+      budgetError = err instanceof BudgetExceededError ? err : new BudgetExceededError(
+        "tool_calls",
+        0,
+        0
+      );
+      if (budgetError !== err && err instanceof Error) {
+        budgetError.message += ` (caused by: ${err.message})`;
+      }
+    };
+    let lastToolFailed = null;
+    const unsub = [];
+    unsub.push(
+      events.on("tool.executed", (e) => {
+        try {
+          ctx.budget.recordToolCall();
+        } catch (eb) {
+          onBudgetError(eb);
+        }
+        if (e.ok === false) {
+          lastToolFailed = e.name;
+        } else if (e.ok === true) {
+          lastToolFailed = null;
+        }
+      }),
+      events.on("provider.response", (e) => {
+        try {
+          ctx.budget.recordUsage(e.usage);
+        } catch (e2) {
+          void onBudgetError(e2);
+        }
+      }),
+      events.on("iteration.started", () => {
+        try {
+          ctx.budget.recordIteration();
+        } catch (e) {
+          void onBudgetError(e);
+        }
+        const u = ctx.budget.usage();
+        const since = u.iterations - lastSummaryAtIteration;
+        if (since >= SUMMARY_INTERVAL) {
+          lastSummaryAtIteration = u.iterations;
+          events.emit("subagent.iteration_summary", {
+            subagentId: ctx.subagentId,
+            iteration: u.iterations,
+            toolCalls: u.toolCalls,
+            costUsd: u.costUsd,
+            currentTool: currentToolName,
+            partialText: streamingTextAcc.trim() || void 0
+          });
+        }
+      }),
+      // D3: cooperative timeout enforcement DURING a long tool call.
+      // The iteration-loop checkTimeout() only fires between agent
+      // iterations — a single `bash sleep 3600` call would otherwise
+      // park inside one tool execution while the timeout silently
+      // passes, relying solely on the coordinator's hard Promise.race
+      // to interrupt. Tools that emit `tool.progress` (bash chunks,
+      // fetch byte progress, spawn-stream stdout) give us a heartbeat
+      // we can hang the check on. When the budget trips here:
+      //   1. onBudgetError sets budgetError + aborter.abort()
+      //   2. aborter signal propagates to agent.run → tool executor
+      //   3. tool's own signal listener kills the child process
+      // Cheap: O(1) per progress event, and the budget short-circuits
+      // when timeoutMs is unset (most subagents have one set anyway).
+      events.on("tool.progress", () => {
+        try {
+          ctx.budget.checkTimeout();
+        } catch (e) {
+          void onBudgetError(e);
+        }
+      })
+    );
+    let currentToolName;
+    let streamingTextAcc = "";
+    let lastSummaryAtIteration = 0;
+    const SUMMARY_INTERVAL = 25;
+    unsub.push(
+      events.on("tool.started", (e) => {
+        currentToolName = e.name;
+      }),
+      events.on("provider.text_delta", (e) => {
+        streamingTextAcc = (streamingTextAcc + e.text).slice(-200);
+      })
+    );
+    const onParentAbort = () => aborter.abort();
+    ctx.signal.addEventListener("abort", onParentAbort);
+    let result;
+    try {
+      result = await agent.run(format(task, ctx.config), { signal: aborter.signal });
+    } finally {
+      detachFleet?.();
+      ctx.signal.removeEventListener("abort", onParentAbort);
+      for (const u of unsub) u();
+      if (factoryResult.dispose) {
+        try {
+          await factoryResult.dispose();
+        } catch {
+        }
+      }
+    }
+    if (budgetError) {
+      if ("decision" in budgetError) {
+        const decision = await budgetError.decision;
+        if (decision === "stop") {
+          budgetError = new BudgetExceededError(
+            budgetError.kind,
+            budgetError.limit,
+            budgetError.used
+          );
+        } else {
+          budgetError = null;
+        }
+      }
+      if (budgetError) throw budgetError;
+    }
+    if (result.status === "failed") {
+      throw result.error instanceof Error ? result.error : new Error(String(result.error ?? "agent failed"));
+    }
+    if (result.status === "aborted") {
+      throw new Error("agent aborted");
+    }
+    if (result.status === "max_iterations") {
+      throw new Error("agent exhausted iteration limit");
+    }
+    const usage = ctx.budget.usage();
+    const finalText = (result.finalText ?? "").trim();
+    if (finalText.length === 0 && usage.toolCalls === 0) {
+      throw new Error("empty response");
+    }
+    if (finalText.length === 0 && lastToolFailed !== null) {
+      throw new Error(`tool failed: ${lastToolFailed}`);
+    }
+    return {
+      result: result.finalText,
+      iterations: result.iterations,
+      toolCalls: usage.toolCalls
+    };
+  };
+}
+function defaultFormatTaskInput(task) {
+  return task.description ?? "";
+}
+
+// src/types/provider.ts
+var ProviderError = class extends WrongStackError {
+  status;
+  retryable;
+  providerId;
+  body;
+  constructor(message, status, retryable, providerId, opts = {}) {
+    super({
+      message,
+      code: providerStatusToCode(status, opts.body?.type),
+      subsystem: "provider",
+      severity: status >= 500 ? "error" : "warning",
+      recoverable: retryable,
+      context: { providerId, status },
+      cause: opts.cause
+    });
+    this.name = "ProviderError";
+    this.status = status;
+    this.retryable = retryable;
+    this.providerId = providerId;
+    this.body = opts.body;
+  }
+  /**
+   * Render a one-line, user-facing description. Designed for the CLI/TUI
+   * status line and the agent's retry warning. Avoids dumping raw JSON
+   * (which is what users see today when a 529 lands and the log message
+   * includes the full `{"type":"error",...}` body).
+   *
+   * Examples:
+   *   "minimax-coding-plan overloaded (529): High traffic detected. Upgrade for highspeed model. [req 06534785201de9c0…]"
+   *   "openai rate limited (429): Retry after 12s"
+   *   "anthropic invalid request (400): messages.0.role must be one of 'user'|'assistant'"
+   *   "groq HTTP 500 (server error)"
+   */
+  describe() {
+    const kind = describeStatus(this.status, this.body?.type);
+    const head = `${this.providerId} ${kind}`;
+    const detail = this.body?.message?.trim();
+    const reqId = this.body?.requestId ? ` [req ${this.body.requestId.slice(0, 16)}${this.body.requestId.length > 16 ? "\u2026" : ""}]` : "";
+    if (detail && detail.length > 0) {
+      return `${head}: ${truncate(detail, 240)}${reqId}`;
+    }
+    return `${head}${reqId}`;
+  }
+};
+function describeStatus(status, type) {
+  if (status === 0) return "network error";
+  if (type === "overloaded_error" || status === 529) return `overloaded (${status})`;
+  if (type === "rate_limit_error" || status === 429) return `rate limited (${status})`;
+  if (type === "authentication_error" || status === 401) return `auth failed (${status})`;
+  if (type === "permission_error" || status === 403) return `forbidden (${status})`;
+  if (type === "not_found_error" || status === 404) return `not found (${status})`;
+  if (type === "invalid_request_error" || status === 400) return `invalid request (${status})`;
+  if (status === 408) return `timeout (${status})`;
+  if (status >= 500 && status < 600) return `HTTP ${status} (server error)`;
+  if (type) return `${type} (${status})`;
+  return `HTTP ${status}`;
+}
+function truncate(s, n) {
+  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
+}
+function providerStatusToCode(status, type) {
+  if (status === 0) return "PROVIDER_NETWORK_ERROR";
+  if (type === "rate_limit_error" || status === 429) return "PROVIDER_RATE_LIMITED";
+  if (type === "authentication_error" || status === 401) return "PROVIDER_AUTH_FAILED";
+  if (type === "overloaded_error" || status === 529) return "PROVIDER_OVERLOADED";
+  if (type === "invalid_request_error" || status === 400) return "PROVIDER_INVALID_REQUEST";
+  if (status === 408) return "PROVIDER_NETWORK_ERROR";
+  if (status >= 500) return "PROVIDER_SERVER_ERROR";
+  return "PROVIDER_INVALID_REQUEST";
+}
+var FLEET_ROSTER_BUDGETS = {
+  "audit-log": { timeoutMs: 8 * 60 * 1e3, maxIterations: 150, maxToolCalls: 500 },
+  "bug-hunter": { timeoutMs: 15 * 60 * 1e3, maxIterations: 200, maxToolCalls: 600 },
+  "refactor-planner": { timeoutMs: 12 * 60 * 1e3, maxIterations: 180, maxToolCalls: 550 },
+  "security-scanner": { timeoutMs: 15 * 60 * 1e3, maxIterations: 200, maxToolCalls: 600 }
+};
+function applyRosterBudget(cfg) {
+  const defaultBudget = FLEET_ROSTER_BUDGETS[cfg.role ?? ""];
+  if (!defaultBudget) return cfg;
+  return {
+    ...cfg,
+    timeoutMs: cfg.timeoutMs ?? defaultBudget.timeoutMs,
+    maxIterations: cfg.maxIterations ?? defaultBudget.maxIterations,
+    maxToolCalls: cfg.maxToolCalls ?? defaultBudget.maxToolCalls,
+    maxTokens: cfg.maxTokens ?? defaultBudget.maxTokens,
+    maxCostUsd: cfg.maxCostUsd ?? defaultBudget.maxCostUsd
+  };
+}
+
+// src/coordination/multi-agent-coordinator.ts
+var DefaultMultiAgentCoordinator = class extends EventEmitter {
+  coordinatorId;
+  config;
+  runner;
+  subagents = /* @__PURE__ */ new Map();
+  pendingTasks = [];
+  completedResults = [];
+  totalIterations = 0;
+  inFlight = 0;
+  /**
+   * Subagents currently being stopped. Set on entry to `stop()`, cleared
+   * once `recordCompletion` lands the terminal TaskResult. Used by
+   * `runDispatched` and `findIdleSubagent` to refuse mid-flight dispatch
+   * to a subagent the caller has already asked to terminate — closes the
+   * assign+terminate race where a fresh task could land on a worker that
+   * was about to be killed.
+   */
+  terminating = /* @__PURE__ */ new Set();
+  constructor(config, options = {}) {
+    super();
+    this.coordinatorId = config.coordinatorId;
+    this.config = config;
+    this.runner = options.runner;
+  }
+  /**
+   * Replace the runner after construction. Used when the runner depends
+   * on infrastructure (e.g. FleetBus) that isn't available until after
+   * the coordinator's owning Director is built.
+   */
+  setRunner(runner) {
+    this.runner = runner;
+  }
+  /**
+   * Change the in-flight dispatch ceiling at runtime. Lowering does NOT
+   * preempt running tasks — already-dispatched subagents finish their
+   * current task; only future dispatches respect the new cap. Raising
+   * immediately tries to fill the freed slots from the pending queue.
+   */
+  setMaxConcurrent(n) {
+    if (!Number.isFinite(n) || n < 1) {
+      throw new Error(`maxConcurrent must be a finite integer >= 1, got ${n}`);
+    }
+    this.config.maxConcurrent = Math.floor(n);
+    this.tryDispatchNext();
+  }
+  async spawn(subagent) {
+    const id = subagent.id || randomUUID();
+    if (this.subagents.has(id)) {
+      throw new Error(`Subagent id "${id}" already exists \u2014 refusing to overwrite`);
+    }
+    const context = {
+      subagentId: id,
+      tasks: [],
+      // Wired later by the caller via setSubagentBridge() once the
+      // bidirectional bridge is created. Readers must null-check / use
+      // hasParentBridge() — the type now reflects this.
+      parentBridge: null,
+      doneCondition: this.config.doneCondition,
+      maxConcurrent: this.config.maxConcurrent ?? 4
+    };
+    this.subagents.set(id, {
+      config: { ...subagent, id },
+      context,
+      status: "idle",
+      abortController: new AbortController()
+    });
+    this.emit("subagent.started", { subagent: { ...subagent, id } });
+    return { subagentId: id, agentId: id };
+  }
+  async assign(task) {
+    this.pendingTasks.push(task);
+    this.tryDispatchNext();
+  }
+  async delegate(to, msg) {
+    const subagent = this.subagents.get(to);
+    if (!subagent) throw new Error(`Subagent "${to}" not found`);
+    if (!subagent.context.parentBridge) {
+      throw new Error(`Subagent "${to}" has no parentBridge \u2014 call setSubagentBridge() first`);
+    }
+    await subagent.context.parentBridge.send(msg);
+  }
+  /**
+   * Wire up the communication bridge for a subagent. Call after spawn() once
+   * the caller has created the bidirectional connection.
+   */
+  setSubagentBridge(subagentId, bridge) {
+    const subagent = this.subagents.get(subagentId);
+    if (!subagent) throw new Error(`Subagent "${subagentId}" not found`);
+    subagent.context.parentBridge = bridge;
+  }
+  async stop(subagentId) {
+    const subagent = this.subagents.get(subagentId);
+    if (!subagent) return;
+    this.terminating.add(subagentId);
+    subagent.abortController.abort();
+    subagent.status = "stopped";
+    subagent.currentTask = void 0;
+    subagent.context.parentBridge = null;
+    this.emit("subagent.stopped", { subagentId, reason: "stopped by coordinator" });
+  }
+  async stopAll() {
+    this.drainPendingAsAborted("Coordinator stopAll() drained the pending queue");
+    await Promise.allSettled([...this.subagents.keys()].map((id) => this.stop(id)));
+  }
+  getStatus() {
+    return {
+      coordinatorId: this.coordinatorId,
+      subagents: Array.from(this.subagents.entries()).map(([id, s]) => ({
+        id,
+        name: s.config.name,
+        status: s.status,
+        currentTask: s.currentTask
+      })),
+      pendingTasks: this.pendingTasks.length,
+      completedTasks: this.completedResults.length,
+      totalIterations: this.totalIterations,
+      done: this.isDone()
+    };
+  }
+  /** Expose snapshot of completed results — useful for callers awaiting all done. */
+  results() {
+    return this.completedResults;
+  }
+  /**
+   * Wait for one or more tasks to complete and return their results.
+   * If a task is already done when called, returns immediately.
+   * Resolves to an array in the same order as `taskIds`.
+   */
+  async awaitTasks(taskIds) {
+    return Promise.all(
+      taskIds.map((id) => {
+        const cached = this.completedResults.find((r) => r.taskId === id);
+        if (cached) return cached;
+        return new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            this.off("task.completed", handler);
+            reject(new Error(`awaitTasks timed out waiting for task "${id}"`));
+          }, this.config.timeoutMs ?? 3e5);
+          const handler = ({ result }) => {
+            if (result.taskId === id) {
+              clearTimeout(timeout);
+              this.off("task.completed", handler);
+              resolve(result);
+            }
+          };
+          this.on("task.completed", handler);
+        });
+      })
+    );
+  }
+  /**
+   * Manual completion — for callers that drive subagents without a runner
+   * (e.g. external orchestrators). When a runner is configured the coordinator
+   * calls this itself.
+   */
+  completeTask(result) {
+    this.recordCompletion(result);
+  }
+  // --- internal dispatching ---------------------------------------------
+  tryDispatchNext() {
+    while (this.canDispatch()) {
+      const dispatchable = this.takeNextDispatchableTask();
+      if (!dispatchable) {
+        if (this.pendingTasks.length > 0 && !this.hasLiveSubagent()) {
+          this.drainPendingAsAborted(
+            "No live subagent available \u2014 all stopped or mid-termination"
+          );
+        }
+        return;
+      }
+      const { subagentId, task } = dispatchable;
+      this.runDispatched(subagentId, task).catch((err) => {
+        this.recordCompletion({
+          subagentId,
+          taskId: task.id,
+          status: "failed",
+          error: classifySubagentError(err),
+          iterations: 0,
+          toolCalls: 0,
+          durationMs: 0
+        });
+      });
+    }
+  }
+  canDispatch() {
+    const max = this.config.maxConcurrent ?? 4;
+    return this.inFlight < max && this.pendingTasks.length > 0;
+  }
+  takeNextDispatchableTask() {
+    for (let i = 0; i < this.pendingTasks.length; i++) {
+      const task = this.pendingTasks[i];
+      const subagentId = task.subagentId ? this.isIdleSubagent(task.subagentId) ? task.subagentId : null : this.findIdleSubagent();
+      if (!subagentId) continue;
+      this.pendingTasks.splice(i, 1);
+      return { subagentId, task };
+    }
+    return null;
+  }
+  findIdleSubagent() {
+    for (const [id, s] of this.subagents) {
+      if (s.status === "idle" && !this.terminating.has(id)) return id;
+    }
+    return null;
+  }
+  isIdleSubagent(id) {
+    const subagent = this.subagents.get(id);
+    return !!subagent && subagent.status === "idle" && !this.terminating.has(id);
+  }
+  /**
+   * Returns true iff at least one spawned subagent could still
+   * process a task. A "live" subagent is one that is not stopped
+   * AND not mid-termination — `running` workers count because they
+   * will eventually finish and become idle.
+   *
+   * When no subagent has ever been spawned, returns `true` so a
+   * pre-spawn `assign()` simply queues (legacy behaviour). The
+   * dead-end detection only fires after `stop()` has retired every
+   * spawned worker.
+   *
+   * Used by `tryDispatchNext` to detect a dead-end pending queue.
+   */
+  hasLiveSubagent() {
+    if (this.subagents.size === 0) return true;
+    for (const [id, s] of this.subagents) {
+      if (s.status !== "stopped" && !this.terminating.has(id)) return true;
+    }
+    return false;
+  }
+  /**
+   * Drain every pending task with a synthetic `aborted_by_parent`
+   * completion event. Same shape as the `stopAll()` drain — we go
+   * around `recordCompletion` because pending tasks were never
+   * counted in `inFlight` and routing them through would trip the
+   * underflow guard on every task after the first.
+   */
+  drainPendingAsAborted(message) {
+    const dropped = this.pendingTasks.splice(0, this.pendingTasks.length);
+    for (const t of dropped) {
+      const synthetic = {
+        subagentId: t.subagentId ?? "unassigned",
+        taskId: t.id,
+        status: "stopped",
+        error: {
+          kind: "aborted_by_parent",
+          message,
+          retryable: false
+        },
+        iterations: 0,
+        toolCalls: 0,
+        durationMs: 0
+      };
+      this.completedResults.push(synthetic);
+      this.emit("task.completed", { task: t, result: synthetic });
+    }
+  }
+  async runDispatched(subagentId, task) {
+    const subagent = this.subagents.get(subagentId);
+    if (!subagent) return;
+    if (this.terminating.has(subagentId) || subagent.status === "stopped") {
+      this.recordCompletion({
+        subagentId,
+        taskId: task.id,
+        status: "stopped",
+        error: {
+          kind: "aborted_by_parent",
+          message: "Subagent was terminated before task could start",
+          retryable: false
+        },
+        iterations: 0,
+        toolCalls: 0,
+        durationMs: 0
+      });
+      return;
+    }
+    subagent.status = "running";
+    subagent.currentTask = task.id;
+    task.subagentId = subagentId;
+    subagent.context.tasks.push(task);
+    this.emit("task.assigned", { task, subagentId });
+    const configWithRosterDefaults = applyRosterBudget(subagent.config);
+    const budget = new SubagentBudget({
+      maxIterations: configWithRosterDefaults.maxIterations ?? this.config.defaultBudget?.maxIterations,
+      maxToolCalls: task.maxToolCalls ?? configWithRosterDefaults.maxToolCalls ?? this.config.defaultBudget?.maxToolCalls,
+      maxTokens: configWithRosterDefaults.maxTokens ?? this.config.defaultBudget?.maxTokens,
+      maxCostUsd: configWithRosterDefaults.maxCostUsd ?? this.config.defaultBudget?.maxCostUsd,
+      timeoutMs: task.timeoutMs ?? configWithRosterDefaults.timeoutMs ?? this.config.defaultBudget?.timeoutMs
+    });
+    subagent.activeBudget = budget;
+    if (!this.runner) {
+      return;
+    }
+    this.inFlight++;
+    const startTime = Date.now();
+    const runCtx = {
+      subagentId,
+      config: subagent.config,
+      budget,
+      signal: subagent.abortController.signal,
+      bridge: subagent.context.parentBridge || null
+    };
+    let result;
+    budget.start();
+    try {
+      const outcome = await this.executeWithTimeout(this.runner, task, runCtx, budget);
+      result = {
+        subagentId,
+        taskId: task.id,
+        status: "success",
+        result: outcome.result,
+        iterations: outcome.iterations,
+        toolCalls: outcome.toolCalls,
+        durationMs: Date.now() - startTime
+      };
+    } catch (err) {
+      const status = err instanceof BudgetExceededError && err.kind === "timeout" ? "timeout" : subagent.abortController.signal.aborted ? "stopped" : "failed";
+      const usage = budget.usage();
+      result = {
+        subagentId,
+        taskId: task.id,
+        status,
+        error: classifySubagentError(err, {
+          parentAborted: subagent.abortController.signal.aborted
+        }),
+        iterations: usage.iterations,
+        toolCalls: usage.toolCalls,
+        durationMs: Date.now() - startTime
+      };
+    }
+    this.recordCompletion(result);
+  }
+  async executeWithTimeout(runner, task, ctx, budget) {
+    const initialTimeoutMs = budget.limits.timeoutMs;
+    if (initialTimeoutMs === void 0) return runner(task, ctx);
+    const start = Date.now();
+    let timer = null;
+    const timeoutPromise = new Promise((_, reject) => {
+      const armFor = (ms) => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(async () => {
+          const elapsed = Date.now() - start;
+          const limit = budget.limits.timeoutMs ?? initialTimeoutMs;
+          if (!budget.onThreshold) {
+            this.subagents.get(ctx.subagentId)?.abortController.abort();
+            reject(new BudgetExceededError("timeout", limit, elapsed));
+            return;
+          }
+          try {
+            const result = budget.onThreshold({
+              kind: "timeout",
+              used: elapsed,
+              limit,
+              requestDecision: () => new Promise((resolveDecision) => {
+                budget._events?.emit("budget.threshold_reached", {
+                  kind: "timeout",
+                  used: elapsed,
+                  limit,
+                  timeoutMs: 3e4,
+                  extend: (extra) => resolveDecision({ extend: extra }),
+                  deny: () => resolveDecision("stop")
+                });
+              })
+            });
+            const decision = typeof result === "string" ? result : await result;
+            if (decision === "continue") {
+              armFor(Math.max(1e3, limit));
+              return;
+            }
+            if (decision === "throw" || decision === "stop") {
+              armFor(Math.max(1e3, limit));
+              return;
+            }
+            if (decision.extend.timeoutMs !== void 0) {
+              budget.limits.timeoutMs = decision.extend.timeoutMs;
+              const newLimit = decision.extend.timeoutMs;
+              const remaining = Math.max(1e3, newLimit - elapsed);
+              armFor(remaining);
+              return;
+            }
+            this.subagents.get(ctx.subagentId)?.abortController.abort();
+            reject(new BudgetExceededError("timeout", limit, elapsed));
+          } catch (err) {
+            this.subagents.get(ctx.subagentId)?.abortController.abort();
+            reject(
+              err instanceof BudgetExceededError ? err : new BudgetExceededError("timeout", limit, elapsed)
+            );
+          }
+        }, ms);
+      };
+      armFor(initialTimeoutMs);
+    });
+    try {
+      return await Promise.race([runner(task, ctx), timeoutPromise]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  recordCompletion(result) {
+    this.completedResults.push(result);
+    this.totalIterations += result.iterations;
+    if (this.inFlight > 0) {
+      this.inFlight--;
+    } else if (this.runner) {
+      this.emit("warning", {
+        type: "inFlight_underflow",
+        taskId: result.taskId,
+        subagentId: result.subagentId
+      });
+      return;
+    }
+    const subagent = this.subagents.get(result.subagentId);
+    if (subagent && subagent.status !== "stopped") {
+      result.status === "failed" || result.status === "timeout";
+      subagent.status = "idle";
+      subagent.currentTask = void 0;
+      if (subagent.abortController.signal.aborted) {
+        subagent.abortController = new AbortController();
+      }
+    }
+    this.terminating.delete(result.subagentId);
+    this.emit("task.completed", {
+      task: subagent?.context.tasks.find((t) => t.id === result.taskId) ?? { id: result.taskId },
+      result
+    });
+    this.tryDispatchNext();
+    if (this.isDone()) {
+      this.emit("done", {
+        results: this.completedResults,
+        totalIterations: this.totalIterations
+      });
+    }
+  }
+  isDone() {
+    if (this.config.doneCondition.type === "all_tasks_done") {
+      return this.pendingTasks.length === 0 && this.inFlight === 0;
+    }
+    if (this.config.doneCondition.maxIterations !== void 0 && this.totalIterations >= this.config.doneCondition.maxIterations) {
+      return true;
+    }
+    return false;
+  }
+};
+function classifySubagentError(err, hints = {}) {
+  const cause = err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : void 0;
+  if (err instanceof ProviderError) {
+    const baseMessage2 = err.describe();
+    return providerErrorToSubagentError(err, baseMessage2, cause);
+  }
+  const baseMessage = err instanceof Error ? err.message : String(err);
+  if (err instanceof BudgetExceededError) {
+    const map = {
+      iterations: "budget_iterations",
+      tool_calls: "budget_tool_calls",
+      tokens: "budget_tokens",
+      cost: "budget_cost",
+      timeout: "budget_timeout"
+    };
+    return {
+      kind: map[err.kind],
+      message: baseMessage,
+      // Budgets are user-configured ceilings, not transient failures —
+      // retrying with the same budget will hit the same ceiling. The
+      // orchestrator must raise the budget or narrow the task first.
+      retryable: false,
+      cause
+    };
+  }
+  if (hints.parentAborted) {
+    return {
+      kind: "aborted_by_parent",
+      message: baseMessage,
+      retryable: false,
+      cause
+    };
+  }
+  const lower = baseMessage.toLowerCase();
+  if (/agent aborted$/i.test(baseMessage)) {
+    return {
+      kind: "aborted_by_parent",
+      message: baseMessage,
+      retryable: false,
+      cause
+    };
+  }
+  if (/agent exhausted iteration limit$/i.test(baseMessage)) {
+    return { kind: "budget_iterations", message: baseMessage, retryable: false, cause };
+  }
+  if (/empty response$/i.test(baseMessage)) {
+    return { kind: "empty_response", message: baseMessage, retryable: false, cause };
+  }
+  if (/^tool failed: /i.test(baseMessage)) {
+    return { kind: "tool_failed", message: baseMessage, retryable: false, cause };
+  }
+  if (lower.includes("bridge transport") || /bridge.*(closed|disconnect)/i.test(baseMessage)) {
+    return { kind: "bridge_failed", message: baseMessage, retryable: false, cause };
+  }
+  if (/context length|max.*tokens?.*exceeded|prompt is too long/i.test(baseMessage)) {
+    return { kind: "context_overflow", message: baseMessage, retryable: false, cause };
+  }
+  return {
+    kind: "unknown",
+    message: baseMessage,
+    retryable: false,
+    cause
+  };
+}
+function providerErrorToSubagentError(err, message, cause) {
+  const status = err.status;
+  if (status === 429 || err.body?.type === "rate_limit_error") {
+    return {
+      kind: "provider_rate_limit",
+      message,
+      retryable: true,
+      // Conservative default: 5s. Provider-specific code can override
+      // by emitting an error whose body carries an explicit hint.
+      backoffMs: 5e3,
+      cause
+    };
+  }
+  if (status === 401 || status === 403 || err.body?.type === "authentication_error") {
+    return { kind: "provider_auth", message, retryable: false, cause };
+  }
+  if (status === 408 || status === 0) {
+    return { kind: "provider_timeout", message, retryable: true, cause };
+  }
+  if (status >= 500 && status < 600) {
+    return {
+      kind: "provider_5xx",
+      message,
+      retryable: true,
+      backoffMs: 3e3,
+      cause
+    };
+  }
+  return { kind: "unknown", message, retryable: err.retryable, cause };
+}
+
+// src/execution/parallel-eternal-engine.ts
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var GOAL_COMPLETE_MARKER2 = /^\s*\[goal[_\s-]?complete\]\s*$/im;
+var ParallelEternalEngine = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.goalPath = goalFilePath(opts.projectRoot);
+    this.slots = Math.min(16, Math.max(1, opts.parallelSlots ?? 4));
+    this.timeoutMs = opts.iterationTimeoutMs ?? 3e5;
+    this.agentFactory = opts.subagentFactory ?? (async (config) => ({
+      agent: this.opts.agent,
+      events: this.opts.agent.events
+    }));
+  }
+  opts;
+  state = "idle";
+  stopRequested = false;
+  iterationsSinceCompact = 0;
+  iterations = 0;
+  consecutiveFailures = 0;
+  goalPath;
+  slots;
+  timeoutMs;
+  coordinator = null;
+  agentFactory;
+  get currentState() {
+    return this.state;
+  }
+  stop() {
+    this.stopRequested = true;
+    void this.persistState("stopped").catch(() => {
+    });
+    this.state = "stopped";
+  }
+  async prime() {
+    this.stopRequested = false;
+    this.state = "running";
+    await this.persistState("running");
+  }
+  async run() {
+    this.state = "running";
+    await this.persistState("running");
+    const config = {
+      coordinatorId: `parallel-${randomUUID().slice(0, 8)}`,
+      maxConcurrent: this.slots,
+      doneCondition: { type: "all_tasks_done" }
+    };
+    this.coordinator = new DefaultMultiAgentCoordinator(config);
+    const runner = makeAgentSubagentRunner({ factory: this.agentFactory });
+    this.coordinator.setRunner?.(runner);
+    try {
+      while (!this.stopRequested) {
+        try {
+          await this.runOneIteration();
+        } catch (err) {
+          this.consecutiveFailures++;
+          this.opts.onError?.(err instanceof Error ? err : new Error(String(err)), this.consecutiveFailures);
+          await this.appendFailure("engine error", err instanceof Error ? err.message : String(err));
+        }
+        if (this.stopRequested) break;
+        await sleep2(2e3);
+      }
+    } finally {
+      this.state = "stopped";
+      await this.persistState("stopped").catch(() => {
+      });
+    }
+  }
+  /**
+   * Execute one tick: decompose → fan-out → aggregate → compact.
+   * Called by the REPL in its main loop (REPL drives, engine is stateless per tick).
+   */
+  async runOneIteration() {
+    this.iterations++;
+    const goal = await loadGoal(this.goalPath);
+    if (!goal) {
+      this.stopRequested = true;
+      return false;
+    }
+    if (goal.goalState !== "active") {
+      this.stopRequested = true;
+      return false;
+    }
+    if (!this.coordinator) {
+      const config = {
+        coordinatorId: `parallel-${randomUUID().slice(0, 8)}`,
+        maxConcurrent: this.slots,
+        doneCondition: { type: "all_tasks_done" }
+      };
+      this.coordinator = new DefaultMultiAgentCoordinator(config);
+      const runner = makeAgentSubagentRunner({ factory: this.agentFactory });
+      this.coordinator.setRunner?.(runner);
+    }
+    const tasks = await this.decomposeGoal(goal);
+    if (!tasks || tasks.length === 0) {
+      await sleep2(5e3);
+      return false;
+    }
+    const fanOut = await this.fanOut(goal, tasks);
+    this.iterationsSinceCompact++;
+    const successCount = fanOut.results.filter((r) => r.status === "success").length;
+    const status = fanOut.goalComplete ? "success" : fanOut.allSuccessful ? "success" : "failure";
+    const note = [
+      `${successCount}/${fanOut.results.length} subagents succeeded`,
+      fanOut.goalComplete ? "[GOAL_COMPLETE]" : "",
+      fanOut.partialOutput ? `Output: ${fanOut.partialOutput.slice(0, 120)}` : ""
+    ].filter(Boolean).join(" | ");
+    await this.appendIterationEntry({
+      source: "parallel",
+      task: `parallel:${tasks.length} slots \u2014 ${tasks.slice(0, 3).join(", ")}${tasks.length > 3 ? "..." : ""}`,
+      status,
+      note
+    });
+    if (fanOut.goalComplete) {
+      this.stopRequested = true;
+      return true;
+    }
+    await this.maybeCompact();
+    return fanOut.allSuccessful;
+  }
+  // -------------------------------------------------------------------------
+  // Fan-out
+  // -------------------------------------------------------------------------
+  async fanOut(goal, tasks) {
+    const coordinator = this.coordinator;
+    const slotCount = Math.min(this.slots, tasks.length);
+    const recentJournal = goal.journal.slice(-5).map((e) => `  #${e.iteration} [${e.status}] ${e.task}${e.note ? ` \u2014 ${e.note.slice(0, 80)}` : ""}`).join("\n");
+    const directivePreamble = [
+      "\u2550\u2550\u2550 ETERNAL AUTONOMY \u2014 parallel task slot \u2550\u2550\u2550",
+      "",
+      `Mission: ${goal.goal}`,
+      `Total parallel slots: ${slotCount}`,
+      "",
+      recentJournal ? `Recent journal (last 5):
+${recentJournal}` : "No prior iterations.",
+      "",
+      "\u2500\u2500 EXECUTION PROTOCOL \u2500\u2500",
+      "\u2022 Execute the assigned task end-to-end using multiple tool calls.",
+      "\u2022 Emit `[done]` on its own line when the task is complete.",
+      "\u2022 Do not ask for confirmation \u2014 YOLO is active.",
+      "\u2022 If the overall Mission is accomplished, emit `[GOAL_COMPLETE]` followed by a verification recipe.",
+      "\u2022 Keep output concise \u2014 summarize findings, do not transcribe files."
+    ].join("\n");
+    const taskIds = [];
+    const subagentIds = [];
+    const spawnPromises = [];
+    for (let i = 0; i < slotCount; i++) {
+      const task = tasks[i];
+      const subagentId = `parallel-${this.iterations}-${i}`;
+      const taskId = randomUUID();
+      const spec = {
+        id: taskId,
+        description: `${directivePreamble}
+
+\u2500\u2500 SLOT ${i + 1}/${slotCount} \u2500\u2500
+Task: ${task}
+`,
+        subagentId
+      };
+      spawnPromises.push((async () => {
+        try {
+          await coordinator.spawn({
+            id: subagentId,
+            name: `slot-${subagentId.slice(-6)}`,
+            maxIterations: 50,
+            maxToolCalls: 200,
+            timeoutMs: this.timeoutMs
+          });
+          subagentIds.push(subagentId);
+          taskIds.push(taskId);
+          await coordinator.assign(spec);
+        } catch {
+        }
+      })());
+    }
+    await Promise.all(spawnPromises);
+    if (taskIds.length === 0) {
+      return { results: [], allSuccessful: false, goalComplete: false, partialOutput: "" };
+    }
+    let results = [];
+    try {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), this.timeoutMs + 6e4);
+      try {
+        results = await coordinator.awaitTasks(taskIds);
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch {
+      results = coordinator.results().slice(-taskIds.length);
+    }
+    const allSuccessful = results.length > 0 && results.every((r) => r.status === "success");
+    const goalComplete = results.some(
+      (r) => r.status === "success" && typeof r.result === "string" && GOAL_COMPLETE_MARKER2.test(r.result)
+    );
+    const partialOutput = results.map((r) => typeof r.result === "string" ? r.result : "").filter(Boolean).join("\n\n");
+    return { results, allSuccessful, goalComplete, partialOutput };
+  }
+  // -------------------------------------------------------------------------
+  // Goal decomposition
+  // -------------------------------------------------------------------------
+  async decomposeGoal(goal) {
+    const todos = this.opts.agent.ctx?.todos;
+    const tasks = [];
+    if (Array.isArray(todos)) {
+      const pending = todos.filter((t) => t.status === "pending").slice(0, this.slots);
+      for (const t of pending) {
+        tasks.push(`[todo] ${t.content}`);
+      }
+    }
+    if (tasks.length < this.slots) {
+      try {
+        const gitStatus = await (this.opts.gitStatusReader?.() ?? this.readGitStatus());
+        const dirty = gitStatus.trim();
+        if (dirty) {
+          const lines = dirty.split("\n").slice(0, this.slots - tasks.length);
+          for (const line of lines) {
+            const file = line.replace(/^[ MADRUC?]{2}\s*/, "").trim();
+            if (file) tasks.push(`[git] inspect and fix: ${file}`);
+          }
+        }
+      } catch {
+      }
+    }
+    if (tasks.length < this.slots) {
+      const remaining = this.slots - tasks.length;
+      const brainstormed = await this.brainstormSubtasks(goal, remaining);
+      tasks.push(...brainstormed);
+    }
+    return tasks.length > 0 ? tasks.slice(0, this.slots) : null;
+  }
+  async readGitStatus() {
+    const { execFile: execFile2 } = await import('child_process');
+    const { promisify: promisify2 } = await import('util');
+    const execFileP2 = promisify2(execFile2);
+    const { stdout } = await execFileP2("git", ["status", "--porcelain"], {
+      cwd: this.opts.projectRoot,
+      timeout: 5e3
+    });
+    return stdout;
+  }
+  async brainstormSubtasks(goal, count) {
+    const lastFew = goal.journal.slice(-5).map((e) => `  - [${e.status}] ${e.task}`).join("\n");
+    const directive = [
+      `Decompose this goal into exactly ${count} independent sub-tasks for parallel execution.`,
+      "",
+      `Goal: ${goal.goal}`,
+      "",
+      lastFew ? `Recent:
+${lastFew}` : "No prior iterations.",
+      "",
+      `Output exactly ${count} tasks, one per line, under 120 chars each.`,
+      "Format: TASK-1 | TASK-2 | ... (pipe-separated, no numbering, no preamble).",
+      "Each task must be independently actionable with no shared dependencies."
+    ].join("\n");
+    try {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 6e4);
+      try {
+        const result = await this.opts.agent.run([{ type: "text", text: directive }], {
+          signal: ctrl.signal,
+          maxIterations: 1
+        });
+        if (result.status !== "done") return [];
+        const text = (result.finalText ?? "").trim();
+        if (!text) return [];
+        const tasks = text.split("|").map((t) => t.trim()).filter((t) => t.length > 10 && t.length < 240);
+        return tasks.slice(0, count);
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch {
+      return [];
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Compaction
+  // -------------------------------------------------------------------------
+  async maybeCompact() {
+    const compactor = this.opts.compactor;
+    if (!compactor) return;
+    const ctx = this.opts.agent.ctx;
+    if (!ctx) return;
+    const shouldRun = this.iterationsSinceCompact >= (this.opts.compactEveryNIterations ?? 25);
+    if (!shouldRun) return;
+    const report = await compactor.compact(ctx, { aggressive: false });
+    this.iterationsSinceCompact = 0;
+    await this.appendIterationEntry({
+      source: "manual",
+      task: "compaction (cadence)",
+      status: "success",
+      note: `saved ~${report.before - report.after} tokens`
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Helpers
+  // -------------------------------------------------------------------------
+  async appendIterationEntry(entry) {
+    const current = await loadGoal(this.goalPath);
+    if (!current) return;
+    const updated = appendJournal(current, entry);
+    await saveGoal(this.goalPath, updated);
+    const entryWithMeta = {
+      at: (this.opts.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+      iteration: updated.iterations,
+      ...entry
+    };
+    this.opts.onIteration?.(entryWithMeta);
+  }
+  async appendFailure(task, note) {
+    await this.appendIterationEntry({ source: "manual", task, status: "failure", note });
+  }
+  async persistState(state) {
+    const current = await loadGoal(this.goalPath);
+    if (!current) return;
+    if (current.engineState === state) return;
+    await saveGoal(this.goalPath, { ...current, engineState: state });
+  }
+};
+
 // src/execution/autonomy-prompt-contributor.ts
 function makeAutonomyPromptContributor(opts) {
   return async (ctx) => {
@@ -2367,78 +3731,6 @@ function buildGoalPreamble(goal) {
   ].join("\n");
 }
 
-// src/types/provider.ts
-var ProviderError = class extends WrongStackError {
-  status;
-  retryable;
-  providerId;
-  body;
-  constructor(message, status, retryable, providerId, opts = {}) {
-    super({
-      message,
-      code: providerStatusToCode(status, opts.body?.type),
-      subsystem: "provider",
-      severity: status >= 500 ? "error" : "warning",
-      recoverable: retryable,
-      context: { providerId, status },
-      cause: opts.cause
-    });
-    this.name = "ProviderError";
-    this.status = status;
-    this.retryable = retryable;
-    this.providerId = providerId;
-    this.body = opts.body;
-  }
-  /**
-   * Render a one-line, user-facing description. Designed for the CLI/TUI
-   * status line and the agent's retry warning. Avoids dumping raw JSON
-   * (which is what users see today when a 529 lands and the log message
-   * includes the full `{"type":"error",...}` body).
-   *
-   * Examples:
-   *   "minimax-coding-plan overloaded (529): High traffic detected. Upgrade for highspeed model. [req 06534785201de9c0…]"
-   *   "openai rate limited (429): Retry after 12s"
-   *   "anthropic invalid request (400): messages.0.role must be one of 'user'|'assistant'"
-   *   "groq HTTP 500 (server error)"
-   */
-  describe() {
-    const kind = describeStatus(this.status, this.body?.type);
-    const head = `${this.providerId} ${kind}`;
-    const detail = this.body?.message?.trim();
-    const reqId = this.body?.requestId ? ` [req ${this.body.requestId.slice(0, 16)}${this.body.requestId.length > 16 ? "\u2026" : ""}]` : "";
-    if (detail && detail.length > 0) {
-      return `${head}: ${truncate(detail, 240)}${reqId}`;
-    }
-    return `${head}${reqId}`;
-  }
-};
-function describeStatus(status, type) {
-  if (status === 0) return "network error";
-  if (type === "overloaded_error" || status === 529) return `overloaded (${status})`;
-  if (type === "rate_limit_error" || status === 429) return `rate limited (${status})`;
-  if (type === "authentication_error" || status === 401) return `auth failed (${status})`;
-  if (type === "permission_error" || status === 403) return `forbidden (${status})`;
-  if (type === "not_found_error" || status === 404) return `not found (${status})`;
-  if (type === "invalid_request_error" || status === 400) return `invalid request (${status})`;
-  if (status === 408) return `timeout (${status})`;
-  if (status >= 500 && status < 600) return `HTTP ${status} (server error)`;
-  if (type) return `${type} (${status})`;
-  return `HTTP ${status}`;
-}
-function truncate(s, n) {
-  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
-}
-function providerStatusToCode(status, type) {
-  if (status === 0) return "PROVIDER_NETWORK_ERROR";
-  if (type === "rate_limit_error" || status === 429) return "PROVIDER_RATE_LIMITED";
-  if (type === "authentication_error" || status === 401) return "PROVIDER_AUTH_FAILED";
-  if (type === "overloaded_error" || status === 529) return "PROVIDER_OVERLOADED";
-  if (type === "invalid_request_error" || status === 400) return "PROVIDER_INVALID_REQUEST";
-  if (status === 408) return "PROVIDER_NETWORK_ERROR";
-  if (status >= 500) return "PROVIDER_SERVER_ERROR";
-  return "PROVIDER_INVALID_REQUEST";
-}
-
 // src/execution/retry-policy.ts
 var DefaultRetryPolicy = class _DefaultRetryPolicy {
   static NETWORK_ERR_RE = /ECONN|ETIMEDOUT|ETIME|ENOTFOUND|EAI_AGAIN|fetch failed/i;
@@ -2679,6 +3971,6 @@ function parseDescription(raw) {
   return { trigger, scope };
 }
 
-export { AutoCompactionMiddleware, AutonomousRunner, DefaultErrorHandler, DefaultRetryPolicy, DefaultSkillLoader, DoneConditionChecker, EternalAutonomyEngine, HybridCompactor, IntelligentCompactor, SelectiveCompactor, ToolExecutor, buildGoalPreamble, makeAutonomyPromptContributor };
+export { AutoCompactionMiddleware, AutonomousRunner, DefaultErrorHandler, DefaultRetryPolicy, DefaultSkillLoader, DoneConditionChecker, EternalAutonomyEngine, HybridCompactor, IntelligentCompactor, ParallelEternalEngine, SelectiveCompactor, ToolExecutor, buildGoalPreamble, makeAutonomyPromptContributor };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map