@wrongstack/core 0.1.10 → 0.2.0

package/dist/index.js

@@ -3116,11 +3116,11 @@ function validateAgainstSchema(value, schema) {
   walk2(value, schema, "", errors);
   return { ok: errors.length === 0, errors };
 }
-function walk2(value, schema, path17, errors) {
+function walk2(value, schema, path18, errors) {
   if (schema.enum !== void 0) {
     if (!schema.enum.some((e) => deepEqual(e, value))) {
       errors.push({
-        path: path17 || "<root>",
+        path: path18 || "<root>",
         message: `expected one of ${JSON.stringify(schema.enum)}, got ${JSON.stringify(value)}`
       });
       return;
@@ -3129,7 +3129,7 @@ function walk2(value, schema, path17, errors) {
   if (typeof schema.type === "string") {
     if (!checkType(value, schema.type)) {
       errors.push({
-        path: path17 || "<root>",
+        path: path18 || "<root>",
         message: `expected ${schema.type}, got ${describeType(value)}`
       });
       return;
@@ -3139,19 +3139,19 @@ function walk2(value, schema, path17, errors) {
     const obj = value;
     for (const req of schema.required ?? []) {
       if (!(req in obj)) {
-        errors.push({ path: joinPath(path17, req), message: "required property missing" });
+        errors.push({ path: joinPath(path18, req), message: "required property missing" });
       }
     }
     if (schema.properties) {
       for (const [key, subSchema] of Object.entries(schema.properties)) {
         if (key in obj) {
-          walk2(obj[key], subSchema, joinPath(path17, key), errors);
+          walk2(obj[key], subSchema, joinPath(path18, key), errors);
         }
       }
     }
   }
   if (schema.type === "array" && Array.isArray(value) && schema.items) {
-    value.forEach((item, i) => walk2(item, schema.items, `${path17}[${i}]`, errors));
+    value.forEach((item, i) => walk2(item, schema.items, `${path18}[${i}]`, errors));
   }
 }
 function checkType(value, type) {
@@ -3439,6 +3439,12 @@ var FileSessionWriter = class {
   tokenIn = 0;
   tokenOut = 0;
   filePath;
+  /** Public accessor for the JSONL path — required by SessionWriter so
+   *  observability surfaces (`/fleet log`, FleetPanel) can locate the
+   *  transcript without recomputing the path from session metadata. */
+  get transcriptPath() {
+    return this.filePath || void 0;
+  }
   initDone = false;
   resumed;
   appendFailCount = 0;
@@ -4368,6 +4374,272 @@ var SessionAnalyzer = class {
     return last - first;
   }
 };
+async function loadTodosCheckpoint(filePath) {
+  let raw;
+  try {
+    raw = await fsp2.readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed?.version !== 1 || !Array.isArray(parsed.todos)) return null;
+    return parsed.todos.filter(
+      (t2) => !!t2 && typeof t2.id === "string" && typeof t2.content === "string" && typeof t2.status === "string"
+    );
+  } catch {
+    return null;
+  }
+}
+async function saveTodosCheckpoint(filePath, sessionId, todos) {
+  const payload = {
+    version: 1,
+    sessionId,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    todos: [...todos]
+  };
+  try {
+    await atomicWrite(filePath, JSON.stringify(payload, null, 2), { mode: 384 });
+  } catch (err) {
+    console.warn(
+      "[todos-checkpoint] save failed:",
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+function attachTodosCheckpoint(state, filePath, sessionId) {
+  let timer = null;
+  let pending = null;
+  const flush = () => {
+    timer = null;
+    if (pending) {
+      void saveTodosCheckpoint(filePath, sessionId, pending);
+      pending = null;
+    }
+  };
+  const unsubscribe = state.onChange((change) => {
+    if (change.kind !== "todos_replaced") return;
+    pending = change.todos;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(flush, 150);
+  });
+  return () => {
+    unsubscribe();
+    if (timer) {
+      clearTimeout(timer);
+      flush();
+    }
+  };
+}
+async function loadPlan(filePath) {
+  let raw;
+  try {
+    raw = await fsp2.readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed?.version !== 1 || !Array.isArray(parsed.items)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function savePlan(filePath, plan) {
+  try {
+    await atomicWrite(filePath, JSON.stringify(plan, null, 2), { mode: 384 });
+  } catch (err) {
+    console.warn(
+      "[plan-store] save failed:",
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+function emptyPlan(sessionId, title) {
+  return {
+    version: 1,
+    sessionId,
+    title,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    items: []
+  };
+}
+function addPlanItem(plan, title, details) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const item = {
+    id: `plan_${Date.now()}_${randomUUID().slice(0, 6)}`,
+    title,
+    details,
+    status: "open",
+    createdAt: now,
+    updatedAt: now
+  };
+  return {
+    plan: { ...plan, items: [...plan.items, item], updatedAt: now },
+    item
+  };
+}
+function removePlanItem(plan, idOrIndex) {
+  const idx = matchIndex(plan, idOrIndex);
+  if (idx === -1) return plan;
+  return {
+    ...plan,
+    items: plan.items.filter((_, i) => i !== idx),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function setPlanItemStatus(plan, idOrIndex, status) {
+  const idx = matchIndex(plan, idOrIndex);
+  if (idx === -1) return plan;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const items = plan.items.map(
+    (it, i) => i === idx ? { ...it, status, updatedAt: now } : it
+  );
+  return { ...plan, items, updatedAt: now };
+}
+function clearPlan(plan) {
+  return { ...plan, items: [], updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function formatPlan(plan) {
+  if (plan.items.length === 0) return "Plan is empty.";
+  const lines = [];
+  if (plan.title) lines.push(`# ${plan.title}`);
+  plan.items.forEach((it, i) => {
+    const mark = it.status === "done" ? "[x]" : it.status === "in_progress" ? "[~]" : "[ ]";
+    lines.push(`${i + 1}. ${mark} ${it.title}`);
+    if (it.details) {
+      for (const line of it.details.split("\n")) lines.push(`     ${line}`);
+    }
+  });
+  return lines.join("\n");
+}
+function matchIndex(plan, idOrIndex) {
+  const asNum = Number.parseInt(idOrIndex, 10);
+  if (!Number.isNaN(asNum) && asNum >= 1 && asNum <= plan.items.length) return asNum - 1;
+  const byId = plan.items.findIndex((it) => it.id === idOrIndex);
+  if (byId !== -1) return byId;
+  const lower = idOrIndex.toLowerCase();
+  return plan.items.findIndex((it) => it.title.toLowerCase().includes(lower));
+}
+function attachPlanCheckpoint(_state, _filePath, _sessionId) {
+  return () => void 0;
+}
+async function loadDirectorState(filePath) {
+  let raw;
+  try {
+    raw = await fsp2.readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed?.version !== 1) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+var DirectorStateCheckpoint = class {
+  snapshot;
+  filePath;
+  timer = null;
+  debounceMs;
+  writing = false;
+  rewriteRequested = false;
+  constructor(filePath, init, debounceMs = 250) {
+    this.filePath = filePath;
+    this.debounceMs = debounceMs;
+    this.snapshot = {
+      version: 1,
+      directorRunId: init.directorRunId,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      spawnCount: 0,
+      maxSpawns: init.maxSpawns,
+      spawnDepth: init.spawnDepth,
+      maxSpawnDepth: init.maxSpawnDepth,
+      subagents: [],
+      tasks: []
+    };
+  }
+  current() {
+    return this.snapshot;
+  }
+  recordSpawn(sub, spawnCount) {
+    this.snapshot = {
+      ...this.snapshot,
+      spawnCount,
+      subagents: [...this.snapshot.subagents.filter((s) => s.id !== sub.id), sub]
+    };
+    this.bumpUpdatedAt();
+    this.schedule();
+  }
+  recordTaskAssigned(task) {
+    const exists = this.snapshot.tasks.some((t2) => t2.taskId === task.taskId);
+    this.snapshot = {
+      ...this.snapshot,
+      tasks: exists ? this.snapshot.tasks.map((t2) => t2.taskId === task.taskId ? { ...t2, ...task } : t2) : [...this.snapshot.tasks, task]
+    };
+    this.bumpUpdatedAt();
+    this.schedule();
+  }
+  recordTaskStatus(taskId, patch) {
+    this.snapshot = {
+      ...this.snapshot,
+      tasks: this.snapshot.tasks.map(
+        (t2) => t2.taskId === taskId ? { ...t2, ...patch } : t2
+      )
+    };
+    this.bumpUpdatedAt();
+    this.schedule();
+  }
+  setUsage(usage) {
+    this.snapshot = { ...this.snapshot, usage };
+    this.bumpUpdatedAt();
+    this.schedule();
+  }
+  /** Force a synchronous flush — used by Director.shutdown(). */
+  async flush() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    await this.persist();
+  }
+  bumpUpdatedAt() {
+    this.snapshot = { ...this.snapshot, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  }
+  schedule() {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.persist();
+    }, this.debounceMs);
+  }
+  async persist() {
+    if (this.writing) {
+      this.rewriteRequested = true;
+      return;
+    }
+    this.writing = true;
+    try {
+      await atomicWrite(this.filePath, JSON.stringify(this.snapshot, null, 2), {
+        mode: 384
+      });
+    } catch (err) {
+      console.warn(
+        "[director-state] checkpoint write failed:",
+        err instanceof Error ? err.message : String(err)
+      );
+    } finally {
+      this.writing = false;
+      if (this.rewriteRequested) {
+        this.rewriteRequested = false;
+        this.schedule();
+      }
+    }
+  }
+};
 var DefaultPermissionPolicy = class {
   policy = {};
   loaded = false;
@@ -4476,6 +4748,18 @@ var DefaultPermissionPolicy = class {
     return void 0;
   }
 };
+var AutoApprovePermissionPolicy = class {
+  async evaluate(tool) {
+    if (tool.permission === "deny") {
+      return { permission: "deny", source: "default", reason: "tool default deny" };
+    }
+    return { permission: "auto", source: "yolo" };
+  }
+  async trust() {
+  }
+  async reload() {
+  }
+};
 var DefaultSkillLoader = class {
   dirs;
   cache;
@@ -5516,6 +5800,10 @@ var FleetBus = class {
       "iteration.started",
       "iteration.completed",
       "provider.text_delta",
+      // Subagent extended-thinking output. Forwarded so the FleetPanel /
+      // /fleet log can surface "the planner is thinking…" instead of a
+      // silent gap between iteration.started and the first text_delta.
+      "provider.thinking_delta",
       "provider.response",
       "provider.retry",
       "provider.error",
@@ -5764,14 +6052,34 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
   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;
+  }
   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: [],
@@ -5815,6 +6123,7 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
   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;
@@ -5822,6 +6131,7 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
     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() {
@@ -5855,7 +6165,14 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
   tryDispatchNext() {
     while (this.canDispatch()) {
       const subagentId = this.findIdleSubagent();
-      if (!subagentId) return;
+      if (!subagentId) {
+        if (this.pendingTasks.length > 0 && !this.hasLiveSubagent()) {
+          this.drainPendingAsAborted(
+            "No live subagent available \u2014 all stopped or mid-termination"
+          );
+        }
+        return;
+      }
       const task = this.pendingTasks.shift();
       if (!task) return;
       this.runDispatched(subagentId, task).catch((err) => {
@@ -5863,7 +6180,7 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
           subagentId,
           taskId: task.id,
           status: "failed",
-          error: err instanceof Error ? err.message : String(err),
+          error: classifySubagentError(err),
           iterations: 0,
           toolCalls: 0,
           durationMs: 0
@@ -5877,13 +6194,76 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
   }
   findIdleSubagent() {
     for (const [id, s] of this.subagents) {
-      if (s.status === "idle") return id;
+      if (s.status === "idle" && !this.terminating.has(id)) return id;
     }
     return null;
   }
+  /**
+   * 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 t2 of dropped) {
+      const synthetic = {
+        subagentId: t2.subagentId ?? "unassigned",
+        taskId: t2.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: t2, 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;
@@ -5929,7 +6309,9 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
         subagentId,
         taskId: task.id,
         status,
-        error: err instanceof Error ? err.message : String(err),
+        error: classifySubagentError(err, {
+          parentAborted: subagent.abortController.signal.aborted
+        }),
         iterations: usage.iterations,
         toolCalls: usage.toolCalls,
         durationMs: Date.now() - startTime
@@ -5968,19 +6350,14 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
     }
     const subagent = this.subagents.get(result.subagentId);
     if (subagent && subagent.status !== "stopped") {
-      const failed = result.status === "failed" || result.status === "timeout";
-      subagent.status = failed ? "error" : "idle";
+      result.status === "failed" || result.status === "timeout";
+      subagent.status = "idle";
       subagent.currentTask = void 0;
       if (subagent.abortController.signal.aborted) {
         subagent.abortController = new AbortController();
       }
-      if (subagent.status === "error") {
-        queueMicrotask(() => {
-          if (subagent.status === "error") subagent.status = "idle";
-          this.tryDispatchNext();
-        });
-      }
     }
+    this.terminating.delete(result.subagentId);
     this.emit("task.completed", {
       task: subagent?.context.tasks.find((t2) => t2.id === result.taskId) ?? { id: result.taskId },
       result
@@ -6003,6 +6380,99 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
     return false;
   }
 };
+function classifySubagentError(err, hints = {}) {
+  const cause = err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : void 0;
+  const baseMessage = err instanceof Error ? err.message : String(err);
+  if (err instanceof ProviderError) {
+    return providerErrorToSubagentError(err, baseMessage, cause);
+  }
+  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/coordination/director.ts
 var DirectorBudgetError = class extends Error {
@@ -6066,6 +6536,27 @@ var Director = class {
   spawnDepth;
   /** Live spawn counter for `maxSpawns` enforcement. */
   spawnCount = 0;
+  /** Optional checkpoint mirror — writes the live task graph + roster to disk. */
+  stateCheckpoint;
+  /** Optional session writer for emitting task_* / agent_* lifecycle events. */
+  sessionWriter;
+  /** Debounce timer for periodic manifest writes. */
+  manifestTimer = null;
+  manifestDebounceMs;
+  /** Resolves task descriptions back from `assign()` so completion events
+   *  can also carry a human-readable title. */
+  taskDescriptions = /* @__PURE__ */ new Map();
+  /** Snapshot of which subagent owns each task — drives state-checkpoint
+   *  status updates without re-walking the manifest. */
+  taskOwners = /* @__PURE__ */ new Map();
+  /**
+   * Handle to the coordinator-side `task.completed` listener so we can
+   * unsubscribe in `shutdown()`. Without this, repeated Director
+   * construction (e.g. tests, hot reloads) accumulates listeners on a
+   * cached coordinator and slowly drifts the EventEmitter past its
+   * default cap.
+   */
+  taskCompletedListener = null;
   constructor(opts) {
     this.id = opts.config.coordinatorId || randomUUID();
     this.manifestPath = opts.manifestPath;
@@ -6076,6 +6567,14 @@ var Director = class {
     this.maxSpawns = opts.maxSpawns ?? Number.POSITIVE_INFINITY;
     this.maxSpawnDepth = opts.maxSpawnDepth ?? 2;
     this.spawnDepth = opts.spawnDepth ?? 0;
+    this.sessionWriter = opts.sessionWriter ?? null;
+    this.manifestDebounceMs = opts.manifestDebounceMs ?? 2e3;
+    this.stateCheckpoint = opts.stateCheckpointPath ? new DirectorStateCheckpoint(opts.stateCheckpointPath, {
+      directorRunId: this.id,
+      maxSpawns: opts.maxSpawns,
+      spawnDepth: this.spawnDepth,
+      maxSpawnDepth: this.maxSpawnDepth
+    }) : null;
     if (this.sharedScratchpadPath) {
       void fsp2.mkdir(this.sharedScratchpadPath, { recursive: true }).catch(() => void 0);
     }
@@ -6094,7 +6593,7 @@ var Director = class {
       { ...opts.config, coordinatorId: this.id },
       { runner: opts.runner }
     );
-    this.coordinator.on("task.completed", (payload) => {
+    this.taskCompletedListener = (payload) => {
       const r = payload.result;
       this.completed.set(r.taskId, r);
       const waiter = this.taskWaiters.get(r.taskId);
@@ -6102,7 +6601,54 @@ var Director = class {
         waiter.resolve(r);
         this.taskWaiters.delete(r.taskId);
       }
-    });
+      const title = this.taskDescriptions.get(r.taskId) ?? payload.task.description ?? r.taskId;
+      const failed = r.status !== "success";
+      const errorString = r.error ? `${r.error.kind}: ${r.error.message}` : void 0;
+      this.stateCheckpoint?.recordTaskStatus(r.taskId, {
+        status: failed ? r.status : "completed",
+        completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        iterations: r.iterations,
+        toolCalls: r.toolCalls,
+        durationMs: r.durationMs,
+        error: errorString
+      });
+      this.stateCheckpoint?.setUsage(this.usage.snapshot());
+      void this.appendSessionEvent(
+        failed ? {
+          type: "task_failed",
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          taskId: r.taskId,
+          title,
+          error: errorString ?? r.status
+        } : {
+          type: "task_completed",
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          taskId: r.taskId,
+          title
+        }
+      );
+      this.scheduleManifest();
+    };
+    this.coordinator.on("task.completed", this.taskCompletedListener);
+  }
+  /** Best-effort session-writer append. Swallows failures — the director
+   *  must not break a fleet run because the session JSONL handle closed. */
+  async appendSessionEvent(event) {
+    if (!this.sessionWriter) return;
+    try {
+      await this.sessionWriter.append(event);
+    } catch {
+    }
+  }
+  /** Debounced manifest writer. A burst of spawn/assign/complete events
+   *  collapses into one write. Set `manifestDebounceMs` to 0 to disable. */
+  scheduleManifest() {
+    if (!this.manifestPath || this.manifestDebounceMs <= 0) return;
+    if (this.manifestTimer) return;
+    this.manifestTimer = setTimeout(() => {
+      this.manifestTimer = null;
+      void this.writeManifest().catch(() => void 0);
+    }, this.manifestDebounceMs);
   }
   /**
    * Spawn a subagent. Identical to the coordinator's `spawn()` but
@@ -6141,6 +6687,25 @@ var Director = class {
       model: config.model,
       taskIds: []
     });
+    const spawnedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.stateCheckpoint?.recordSpawn(
+      {
+        id: result.subagentId,
+        name: config.name,
+        role: config.role,
+        provider: config.provider,
+        model: config.model,
+        spawnedAt
+      },
+      this.spawnCount
+    );
+    void this.appendSessionEvent({
+      type: "agent_spawned",
+      ts: spawnedAt,
+      agentId: result.subagentId,
+      role: config.role ?? config.name
+    });
+    this.scheduleManifest();
     return result.subagentId;
   }
   /**
@@ -6261,13 +6826,42 @@ var Director = class {
    * — calling shutdown twice is a no-op on the second invocation.
    */
   async shutdown() {
+    if (this.manifestTimer) {
+      clearTimeout(this.manifestTimer);
+      this.manifestTimer = null;
+    }
+    if (this.taskCompletedListener) {
+      this.coordinator.off("task.completed", this.taskCompletedListener);
+      this.taskCompletedListener = null;
+    }
     await this.coordinator.stopAll();
     for (const b of this.subagentBridges.values()) {
-      await b.stop().catch(() => void 0);
+      await b.stop().catch((err) => this.logShutdownError("subagent_bridge_stop", err));
     }
     this.subagentBridges.clear();
-    await this.bridge.stop().catch(() => void 0);
-    if (this.manifestPath) await this.writeManifest().catch(() => void 0);
+    await this.bridge.stop().catch((err) => this.logShutdownError("director_bridge_stop", err));
+    if (this.manifestPath)
+      await this.writeManifest().catch((err) => this.logShutdownError("manifest_write", err));
+    if (this.stateCheckpoint) {
+      this.stateCheckpoint.setUsage(this.usage.snapshot());
+      await this.stateCheckpoint.flush().catch((err) => this.logShutdownError("state_checkpoint_flush", err));
+    }
+  }
+  /**
+   * Funnel for shutdown-phase errors. We can't throw — `shutdown()` is
+   * called from process-exit paths where an uncaught throw would lose
+   * the manifest write that comes after. But we MUST NOT silently
+   * swallow either — a persistent bridge-close failure would otherwise
+   * mask a real bug. `process.emitWarning` is the right tier:
+   * surfaces on stderr by default, lets the host plug a warning
+   * listener for structured collection, and never affects exit code.
+   */
+  logShutdownError(phase, err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    process.emitWarning(
+      `Director shutdown phase "${phase}" failed: ${detail}`,
+      "DirectorShutdownWarning"
+    );
   }
   /**
    * Hand a task to the coordinator. Returns the assigned task id so
@@ -6281,6 +6875,23 @@ var Director = class {
       if (entry) entry.taskIds.push(taskWithId.id);
     }
     await this.coordinator.assign(taskWithId);
+    this.taskDescriptions.set(taskWithId.id, taskWithId.description);
+    if (taskWithId.subagentId) this.taskOwners.set(taskWithId.id, taskWithId.subagentId);
+    const assignedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.stateCheckpoint?.recordTaskAssigned({
+      taskId: taskWithId.id,
+      subagentId: taskWithId.subagentId,
+      description: taskWithId.description,
+      status: "running",
+      assignedAt
+    });
+    void this.appendSessionEvent({
+      type: "task_created",
+      ts: assignedAt,
+      taskId: taskWithId.id,
+      title: taskWithId.description
+    });
+    this.scheduleManifest();
     return taskWithId.id;
   }
   /**
@@ -6340,6 +6951,23 @@ var Director = class {
   snapshot() {
     return this.usage.snapshot();
   }
+  /**
+   * Look up provider/model metadata for a spawned subagent. Returns
+   * undefined when the subagent id is unknown (not yet spawned, or
+   * already torn down). Callers — notably the TUI fleet panel — use
+   * this to render human-readable provider/model tags next to each
+   * subagent row without reaching into private state.
+   */
+  getSubagentMeta(id) {
+    const usage = this.subagentMeta.get(id);
+    const manifest = this.manifestEntries.get(id);
+    if (!usage && !manifest) return void 0;
+    return {
+      provider: usage?.provider ?? manifest?.provider,
+      model: usage?.model ?? manifest?.model,
+      name: manifest?.name
+    };
+  }
   /**
    * Compose the leader/director-agent system prompt: fleet preamble +
    * (optional) roster summary + user base prompt. Pass the result to your
@@ -6639,12 +7267,260 @@ function makeFleetUsageTool(director) {
     }
   };
 }
+function createDelegateTool(opts) {
+  const defaultTimeoutMs = opts.defaultTimeoutMs ?? 4 * 60 * 60 * 1e3;
+  const rosterIds = opts.roster ? Object.keys(opts.roster) : [];
+  const inputSchema = {
+    type: "object",
+    properties: {
+      task: {
+        type: "string",
+        description: "What the subagent should do \u2014 natural language, complete sentence(s). The subagent has its own tool slice, its own LLM call, and returns when its task is done."
+      },
+      role: {
+        type: "string",
+        description: rosterIds.length > 0 ? `Roster role (preferred). One of: ${rosterIds.join(", ")}. Picks a pre-tuned config (prompt, budgets, tools) for that role.` : "No roster is configured \u2014 pass `name` instead.",
+        enum: rosterIds.length > 0 ? rosterIds : void 0
+      },
+      name: {
+        type: "string",
+        description: "Display name for the subagent when not using a roster role. Required when `role` is omitted."
+      },
+      provider: {
+        type: "string",
+        description: 'Provider id (e.g. "anthropic", "openai"). Defaults to the host provider when omitted.'
+      },
+      model: {
+        type: "string",
+        description: "Model id within the provider. Defaults to the host model when omitted."
+      },
+      systemPromptOverride: {
+        type: "string",
+        description: "Optional extra prompt text appended to the role baseline."
+      },
+      timeoutMs: {
+        type: "number",
+        description: `Wall-clock budget for this delegate in milliseconds. No hard cap \u2014 set as high as the task realistically needs (a monorepo audit can take hours, a single-file lint takes seconds). Default ${Math.round(defaultTimeoutMs / 1e3 / 60)} minutes.`
+      },
+      maxIterations: {
+        type: "number",
+        description: "Maximum LLM iterations the subagent may take. Unset = use the role/coordinator default. Raise this for tasks with many tool-think-tool cycles (deep code analysis, multi-file refactors)."
+      },
+      maxToolCalls: {
+        type: "number",
+        description: "Maximum number of tool invocations the subagent may make. Unset = use the role/coordinator default. Raise this for tasks that touch many files (large grep + read + report)."
+      }
+    },
+    required: ["task"]
+  };
+  return {
+    name: "delegate",
+    description: "Hand a discrete piece of work to a dedicated subagent and wait for its result. The subagent has its own context, its own LLM call, and its own budget \u2014 use this when a task is self-contained, would otherwise blow up your context, or benefits from a specialized role (bug-hunter, security-scanner, refactor-planner, audit-log). YOU decide how big the budget is: pass `timeoutMs`, `maxIterations`, and `maxToolCalls` sized to the actual work. There is no hidden cap forcing a 3-minute / 80-iteration limit \u2014 if a monorepo audit needs 2 hours and 500 tool calls, ask for that. Call multiple delegates in parallel through the provider's parallel-tool-call surface to fan work out across roles.",
+    usageHint: "Set `task` to a complete instruction. Either pick `role` from the roster or pass `name` + `provider` + `model`. For non-trivial work, also pass `timeoutMs` (the wall-clock budget you actually need), `maxIterations`, and `maxToolCalls` \u2014 defaults are intentionally generous (4 hours) but the right values depend on scope. Returns the subagent's `TaskResult` \u2014 including the textual `result`, iteration count, tool count, and duration. Auto-promotes the host into director mode on first call.",
+    permission: "auto",
+    mutating: false,
+    inputSchema,
+    async execute(input) {
+      const i = input ?? {};
+      if (typeof i.task !== "string" || !i.task.trim()) {
+        return { ok: false, error: "`task` is required." };
+      }
+      let director = await opts.host.ensureDirector();
+      if (!director) {
+        director = await opts.host.promoteToDirector();
+      }
+      if (!director) {
+        const reason = opts.host.getPromotionBlockReason?.();
+        return {
+          ok: false,
+          error: reason ?? "Director could not be activated \u2014 multi-agent host already running in legacy non-director mode. Restart with `--director` for fleet support."
+        };
+      }
+      const timeoutMs = i.timeoutMs ?? defaultTimeoutMs;
+      let cfg;
+      if (i.role) {
+        const base = opts.roster?.[i.role];
+        if (!base) {
+          return {
+            ok: false,
+            error: `Unknown role "${i.role}". Available: ${rosterIds.join(", ") || "(no roster configured)"}.`
+          };
+        }
+        cfg = { ...base };
+        if (i.systemPromptOverride) cfg.systemPromptOverride = i.systemPromptOverride;
+        if (i.provider) cfg.provider = i.provider;
+        if (i.model) cfg.model = i.model;
+      } else {
+        if (!i.name) {
+          return {
+            ok: false,
+            error: "Either `role` (from the roster) or `name` is required."
+          };
+        }
+        cfg = {
+          name: i.name,
+          provider: i.provider,
+          model: i.model,
+          systemPromptOverride: i.systemPromptOverride
+        };
+      }
+      if (typeof i.maxIterations === "number" && i.maxIterations > 0) {
+        cfg.maxIterations = i.maxIterations;
+      }
+      if (typeof i.maxToolCalls === "number" && i.maxToolCalls > 0) {
+        cfg.maxToolCalls = i.maxToolCalls;
+      }
+      const SUBAGENT_TIMEOUT_BUFFER_MS = 3e4;
+      const desiredSubTimeout = Math.max(3e4, timeoutMs - SUBAGENT_TIMEOUT_BUFFER_MS);
+      if (!cfg.timeoutMs || cfg.timeoutMs > desiredSubTimeout) {
+        cfg.timeoutMs = desiredSubTimeout;
+      }
+      try {
+        const subagentId = await director.spawn(cfg);
+        const taskId = await director.assign({
+          id: "",
+          description: i.task,
+          subagentId
+        });
+        const result = await Promise.race([
+          director.awaitTasks([taskId]).then((r) => r[0]),
+          new Promise(
+            (resolve4) => setTimeout(() => resolve4({ __timeout: true }), timeoutMs)
+          )
+        ]);
+        if ("__timeout" in result) {
+          const partial2 = await readSubagentPartial(opts, subagentId);
+          return {
+            ok: false,
+            stopReason: "host_timeout",
+            error: `Subagent did not finish within ${timeoutMs}ms.`,
+            hint: "Reduce scope of the next delegate, raise timeoutMs, or use spawn_subagent + await_tasks for long-running work.",
+            subagentId,
+            taskId,
+            partial: partial2
+          };
+        }
+        const baseStopReason = result.status === "success" ? "end_turn" : result.status === "timeout" ? "subagent_timeout" : result.status === "stopped" ? "aborted" : "budget_exhausted";
+        const partial = result.status === "success" ? void 0 : await readSubagentPartial(opts, subagentId);
+        const errorKind = result.error?.kind;
+        const retryable = result.error?.retryable;
+        const backoffMs = result.error?.backoffMs;
+        return {
+          ok: result.status === "success",
+          status: result.status,
+          stopReason: baseStopReason,
+          errorKind,
+          retryable,
+          backoffMs,
+          subagentId: result.subagentId,
+          taskId: result.taskId,
+          result: result.result,
+          error: result.error,
+          iterations: result.iterations,
+          toolCalls: result.toolCalls,
+          durationMs: result.durationMs,
+          ...partial ? { partial } : {},
+          ...hintForKind(errorKind, retryable, backoffMs) ? { hint: hintForKind(errorKind, retryable, backoffMs) } : {}
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          stopReason: "error",
+          error: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }
+  };
+}
+function hintForKind(kind, retryable, backoffMs) {
+  if (!kind) return void 0;
+  switch (kind) {
+    case "provider_rate_limit":
+      return `Provider rate-limited. Retry safe after ${backoffMs ?? 5e3}ms backoff. Consider a smaller model or fewer parallel delegates.`;
+    case "provider_5xx":
+      return `Provider server error. Retry safe after ${backoffMs ?? 3e3}ms backoff \u2014 usually transient.`;
+    case "provider_timeout":
+      return "Provider network timeout. Retry safe; reduce input size if it persists.";
+    case "provider_auth":
+      return "Provider rejected credentials. Cannot retry \u2014 fix the API key / config and re-invoke.";
+    case "context_overflow":
+      return "Subagent context exceeded the model limit. Narrow the task, use a larger-context model, or split into multiple delegates.";
+    case "budget_iterations":
+    case "budget_tool_calls":
+    case "budget_tokens":
+    case "budget_cost":
+      return "Subagent exhausted its budget. Raise the matching `max*` field on the next delegate or narrow task scope.";
+    case "budget_timeout":
+      return "Subagent hit its wall-clock budget. Raise `timeoutMs` on the next delegate or split the task.";
+    case "aborted_by_parent":
+      return "Subagent was aborted (user Ctrl+C, parent unwound, or sibling failure cascade). Not retryable until the abort condition is resolved.";
+    case "empty_response":
+      return "Subagent ended its turn with no text and no tool calls. Almost always a prompt / config issue \u2014 clarify the task or check the model.";
+    case "tool_failed":
+      return "A tool inside the subagent returned ok:false. Inspect `partial.lastAssistantText` for the agent reasoning, then retry with corrected inputs.";
+    case "bridge_failed":
+      return "Parent-child bridge transport failed. This is rare \u2014 restart the session and retry.";
+    default:
+      return retryable ? "Failure classified as retryable. Try again with the same input." : void 0;
+  }
+}
+async function readSubagentPartial(opts, subagentId) {
+  if (!opts.sessionsRoot) return void 0;
+  const candidates = [];
+  if (opts.directorRunId) {
+    candidates.push(path6.join(opts.sessionsRoot, opts.directorRunId, `${subagentId}.jsonl`));
+  } else {
+    try {
+      const runDirs = await fsp2.readdir(opts.sessionsRoot);
+      for (const r of runDirs) {
+        candidates.push(path6.join(opts.sessionsRoot, r, `${subagentId}.jsonl`));
+      }
+    } catch {
+      return void 0;
+    }
+  }
+  for (const file of candidates) {
+    let raw;
+    try {
+      raw = await fsp2.readFile(file, "utf8");
+    } catch {
+      continue;
+    }
+    const lines = raw.split("\n").filter((l) => l.trim());
+    let lastAssistantText;
+    let lastStopReason;
+    let toolUses = 0;
+    for (const line of lines) {
+      try {
+        const ev = JSON.parse(line);
+        if (ev.type === "tool_use") toolUses += 1;
+        if (ev.type === "llm_response") {
+          if (typeof ev.stopReason === "string") lastStopReason = ev.stopReason;
+          if (Array.isArray(ev.content)) {
+            const txt = ev.content.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n").trim();
+            if (txt) lastAssistantText = txt;
+          }
+        }
+      } catch {
+      }
+    }
+    return {
+      lastAssistantText,
+      lastStopReason,
+      toolUsesObserved: toolUses,
+      events: lines.length
+    };
+  }
+  return void 0;
+}
 
 // src/coordination/agent-subagent-runner.ts
 function makeAgentSubagentRunner(opts) {
   const format = opts.formatTaskInput ?? defaultFormatTaskInput;
   return async (task, ctx) => {
-    const { agent, events } = await opts.factory(ctx.config);
+    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();
     let budgetError = null;
     const onBudgetError = (err) => {
@@ -6658,13 +7534,19 @@ function makeAgentSubagentRunner(opts) {
         budgetError.message += ` (caused by: ${err.message})`;
       }
     };
+    let lastToolFailed = null;
     const unsub = [];
     unsub.push(
-      events.on("tool.started", () => {
+      events.on("tool.executed", (e) => {
         try {
           ctx.budget.recordToolCall();
-        } catch (e) {
-          onBudgetError(e);
+        } catch (eb) {
+          onBudgetError(eb);
+        }
+        if (e.ok === false) {
+          lastToolFailed = e.name;
+        } else if (e.ok === true) {
+          lastToolFailed = null;
         }
       }),
       events.on("provider.response", (e) => {
@@ -6681,6 +7563,26 @@ function makeAgentSubagentRunner(opts) {
         } catch (e) {
           onBudgetError(e);
         }
+      }),
+      // 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) {
+          onBudgetError(e);
+        }
       })
     );
     const onParentAbort = () => aborter.abort();
@@ -6689,8 +7591,15 @@ function makeAgentSubagentRunner(opts) {
     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) throw budgetError;
     if (result.status === "failed") {
@@ -6703,6 +7612,13 @@ function makeAgentSubagentRunner(opts) {
       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,
@@ -6768,10 +7684,12 @@ Working rules:
 - Never fabricate numbers \u2014 read the actual logs first
 - Always include file:line references for errors
 - If sessionPath is missing, ask the director to provide it
-- Report confidence level: high (>90% accuracy), medium, low`,
-  maxIterations: 50,
-  maxToolCalls: 200,
-  timeoutMs: 12e4
+- Report confidence level: high (>90% accuracy), medium, low`
+  // No hardcoded budgets — the orchestrator (delegate tool or
+  // spawn_subagent) decides per-task how much room a subagent gets.
+  // A monorepo audit needs hours; a single-file lint check needs
+  // seconds. Pinning a number here forces the orchestrator to fight
+  // the role's default instead of just asking for what it needs.
 };
 var BUG_HUNTER_AGENT = {
   id: "bug-hunter",
@@ -6811,10 +7729,8 @@ Working rules:
 - Never scan node_modules \u2014 it's noise
 - Always include file:line for every finding
 - If >30% of findings are false positives, note the confidence level
-- Ask director for clarification if paths are ambiguous`,
-  maxIterations: 80,
-  maxToolCalls: 300,
-  timeoutMs: 18e4
+- Ask director for clarification if paths are ambiguous`
+  // Budgets are set by the orchestrator per task — see fleet.ts header.
 };
 var REFACTOR_PLANNER_AGENT = {
   id: "refactor-planner",
@@ -6854,10 +7770,8 @@ Working rules:
 - Always include rollback strategy \u2014 every refactor can fail
 - Merge tasks that take <1h into a single phase
 - Respect team constraints (reviewer availability, parallelization)
-- Never plan without analyzing the actual code first`,
-  maxIterations: 60,
-  maxToolCalls: 250,
-  timeoutMs: 15e4
+- Never plan without analyzing the actual code first`
+  // Budgets are set by the orchestrator per task — see fleet.ts header.
 };
 var SECURITY_SCANNER_AGENT = {
   id: "security-scanner",
@@ -6905,10 +7819,8 @@ Working rules:
 - Never scan node_modules \u2014 use npm audit instead
 - Always provide remediation steps, not just findings
 - Verify regex-based secrets before flagging (false positive risk)
-- When in doubt, flag as medium rather than ignoring potential issues`,
-  maxIterations: 70,
-  maxToolCalls: 280,
-  timeoutMs: 16e4
+- When in doubt, flag as medium rather than ignoring potential issues`
+  // Budgets are set by the orchestrator per task — see fleet.ts header.
 };
 var FLEET_ROSTER = {
   "audit-log": AUDIT_LOG_AGENT,
@@ -8177,7 +9089,7 @@ async function startMetricsServer(opts) {
   const tls = opts.tls;
   const useHttps = !!(tls?.cert && tls?.key);
   const host = opts.host ?? "127.0.0.1";
-  const path17 = opts.path ?? "/metrics";
+  const path18 = opts.path ?? "/metrics";
   const healthPath = opts.healthPath ?? "/healthz";
   const healthRegistry = opts.healthRegistry;
   const listener = (req, res) => {
@@ -8187,7 +9099,7 @@ async function startMetricsServer(opts) {
       return;
     }
     const url = req.url.split("?")[0];
-    if (url === path17) {
+    if (url === path18) {
       let body;
       try {
         body = renderPrometheus(opts.sink.snapshot());
@@ -8251,7 +9163,7 @@ async function startMetricsServer(opts) {
   const protocol = useHttps ? "https" : "http";
   return {
     port: boundPort,
-    url: `${protocol}://${host}:${boundPort}${path17}`,
+    url: `${protocol}://${host}:${boundPort}${path18}`,
     close: () => new Promise((resolve4, reject) => {
       server.close((err) => err ? reject(err) : resolve4());
     })
@@ -9177,7 +10089,7 @@ var Agent = class {
     this.autoExtendLimit = init.autoExtendLimit ?? true;
     this.tracer = init.tracer;
     this.toolExecutor = new ToolExecutor(this.tools, {
-      permissionPolicy: this.permission,
+      permissionPolicy: init.permissionPolicy ?? this.permission,
       secretScrubber: this.scrubber,
       renderer: this.renderer,
       events: this.events,
@@ -9931,6 +10843,7 @@ var DefaultSystemPromptBuilder = class {
     const layer3 = await this.buildEnvironment(ctx);
     const layer4 = await this.buildMemoryAndSkills();
     const layer5 = await this.buildMode();
+    const layer6 = ctx.subagent ? "" : await this.buildActivePlan();
     const blocks = [
       { type: "text", text: layer1 },
       { type: "text", text: layer2 },
@@ -9950,8 +10863,52 @@ var DefaultSystemPromptBuilder = class {
         cache_control: { type: "ephemeral" }
       });
     }
+    if (layer6.trim()) {
+      blocks.push({
+        type: "text",
+        text: layer6,
+        cache_control: { type: "ephemeral" }
+      });
+    }
     return blocks;
   }
+  /**
+   * Reads `<sessionId>.plan.json` (when configured) and produces a short
+   * "Active plan" block listing open items so the model is anchored to
+   * the strategic roadmap every turn. Reads on every `build()` so a
+   * plan edit (via `/plan` or the `plan` tool) reflects on the next
+   * turn without restarting the session.
+   */
+  async buildActivePlan() {
+    const planPath = typeof this.opts.planPath === "function" ? this.opts.planPath() : this.opts.planPath;
+    if (!planPath) return "";
+    let raw;
+    try {
+      raw = await fsp2.readFile(planPath, "utf8");
+    } catch {
+      return "";
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return "";
+    }
+    if (!Array.isArray(parsed.items) || parsed.items.length === 0) return "";
+    const open3 = parsed.items.filter((i) => i?.status !== "done");
+    if (open3.length === 0) return "";
+    const lines = ["## Active plan"];
+    if (parsed.title) lines.push(`*${parsed.title}*`, "");
+    parsed.items.forEach((it, idx) => {
+      const mark = it?.status === "done" ? "[x]" : it?.status === "in_progress" ? "[~]" : "[ ]";
+      lines.push(`${idx + 1}. ${mark} ${it?.title ?? "(untitled)"}`);
+    });
+    lines.push(
+      "",
+      "Use `/plan` (user) or the `plan` tool to update status as you progress. The roadmap survives session resume."
+    );
+    return lines.join("\n");
+  }
   buildToolUsage(tools) {
     if (tools.length === 0) return "## Tool usage\n\nNo tools registered.";
     const lines = ["## Tool usage"];
@@ -9971,6 +10928,78 @@ ${hint.trim()}`);
 - **Batch ops:** Use \`replace\` with glob patterns for multi-file surgical changes
 
 When unsure about a file's current state, read it first rather than assuming.`);
+    const hasDelegate = tools.some((t2) => t2.name === "delegate");
+    if (hasDelegate) {
+      const delegateTool = tools.find((t2) => t2.name === "delegate");
+      const enumValues = (() => {
+        const role = delegateTool?.inputSchema?.properties?.role?.enum;
+        return Array.isArray(role) ? role.filter((r) => typeof r === "string") : [];
+      })();
+      const roleList = enumValues.length > 0 ? enumValues.join(", ") : "(no roster configured)";
+      lines.push(`
+## Delegation
+
+You have a \`delegate\` tool that hands a discrete piece of work to a
+dedicated subagent (its own context, its own LLM call, its own budget
+cap) and waits for the result. Use it proactively when:
+
+- **The task fans out naturally** \u2014 e.g. "audit these 5 files for
+  security issues" splits cleanly into 5 parallel \`delegate\` calls,
+  one per file or per role. Fire them through the provider's
+  parallel-tool-call surface in the same turn.
+- **A specialized role exists** \u2014 the roster has tuned prompts and
+  budgets for: ${roleList}. Reach for a role when the description
+  matches your subtask; otherwise pass \`name\` + \`provider\` + \`model\`.
+- **A subtask would blow up your context** \u2014 long log analyses, large
+  diff reviews, multi-file refactor plans. The subagent absorbs the
+  reading cost and hands back a summary.
+- **You'd otherwise switch hats mid-turn** \u2014 instead of stopping a code
+  fix to do a security pass, delegate the security pass.
+
+### Scope it tight \u2014 narrow tasks succeed, broad tasks time out
+
+A subagent has a finite iteration / tool-call budget (typically 50\u201380
+iterations, 200\u2013300 tool calls). Tasks that mention "ALL files" or "the
+entire codebase" reliably exhaust that budget without producing a clean
+answer \u2014 the delegate returns with \`stopReason: budget_exhausted\` and
+no useful output.
+
+- \u274C BAD: \`"Analyze ALL .ts files in src/ for bugs"\`
+- \u274C BAD: \`"Audit the codebase for security issues"\`
+- \u274C BAD: \`"Plan a refactor of the whole project"\`
+- \u2705 GOOD: \`"Audit src/auth/session.ts for null-deref bugs in the login flow"\`
+- \u2705 GOOD: \`"Check packages/core/src/storage/*.ts for unhandled promise rejections (~6 files)"\`
+- \u2705 GOOD: \`"Plan a phased refactor of the InMemoryBridge transport (3 files in coordination/)"\`
+
+If you need fleet-wide coverage, **fan out**: list the target files
+yourself first (one quick \`glob\` call), then fire one \`delegate\` per
+chunk of \u22645\u201310 files in parallel.
+
+### Reading the result
+
+\`delegate\` returns a structured object. Look at \`stopReason\`:
+
+- \`end_turn\` \u2014 subagent finished cleanly, \`result\` has the answer.
+- \`budget_exhausted\` \u2014 task was too broad; \`partial.lastAssistantText\`
+  has whatever it managed. Narrow the next try.
+- \`subagent_timeout\` / \`host_timeout\` \u2014 likewise partial; raise
+  \`timeoutMs\` only if you have a reason to believe more time would help.
+- \`aborted\` \u2014 the user or another tool stopped this worker; don't retry
+  silently.
+- \`error\` \u2014 infrastructure problem; surface it.
+
+Stay in-process (no \`delegate\`) when:
+- The task is trivial or atomic.
+- The information needed is already in your context.
+- The user is mid-conversation and expects an immediate reply from you,
+  not a research detour through a subagent.
+
+\`delegate\` auto-promotes the host into director mode the first time
+it's called \u2014 you do not need to call any setup tool. For fine-grained
+control over a long-running fleet (spawn N workers, hand them tasks
+one by one, roll up results), use \`spawn_subagent\` + \`assign_task\` +
+\`await_tasks\` directly; \`delegate\` is the one-call shortcut.`);
+    }
     const hasContextManager = tools.some((t2) => t2.name === "context_manager");
     if (hasContextManager) {
       const maxCtx = this.opts.modelCapabilities?.maxContextTokens ?? 128e3;
@@ -10659,6 +11688,6 @@ function wrapApiForCapabilityCheck(plugin, api, log) {
   });
 }
 
-export { ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, Agent, AgentError, AutoCompactionMiddleware, AutonomousRunner, BUG_HUNTER_AGENT, BudgetExceededError, ConfigError, ConfigMigrationError, Container, Context, ConversationState, DEFAULT_CONFIG_MIGRATIONS, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_MAX_ITERATIONS, DEFAULT_MODES, DEFAULT_RECOVERY_STRATEGIES, DEFAULT_SPEC_TEMPLATE, DEFAULT_SUBAGENT_BASELINE, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultPluginAPI, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultSystemPromptBuilder, DefaultTaskStore, DefaultTokenCounter, Director, DirectorBudgetError, DoneConditionChecker, EventBus, FLEET_ROSTER, FleetBus, FleetUsageAggregator, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, InputBuilder, IntelligentCompactor, KERNEL_API_VERSION, LAYER_1_IDENTITY, LLMSelector, NoopMetricsSink, NoopTracer, OTelTracer, PROMETHEUS_CONTENT_TYPE, Pipeline, PluginError, ProviderError, ProviderRegistry, QueueStore, REFACTOR_PLANNER_AGENT, RecoveryLock, RunController, SECURITY_SCANNER_AGENT, SelectiveCompactor, SessionAnalyzer, SessionError, SlashCommandRegistry, SpecDrivenDev, SpecParser, SubagentBudget, TOKENS, TaskFlow, TaskGenerator, TaskTracker, ToolError, ToolExecutor, ToolRegistry, WrongStackError, allServers, asBlocks, asText, atomicWrite, awsServer, blockServer, braveSearchServer, buildChildEnv, buildOtlpMetricsRequest, buildOtlpTracesRequest, buildRecoveryStrategies, classifyFamily, color, compileGlob, composeDirectorPrompt, composeSubagentPrompt, computeTaskProgress, context7Server, contextManagerTool, createContextManagerTool, createDefaultPipelines, createMessage, createToolOutputSerializer, decryptConfigSecrets, detectNewlineStyle, encryptConfigSecrets, ensureDir, estimateTextTokens, estimateToolInputTokens, estimateToolResultTokens, everArtServer, extractRunEnv, filesystemServer, findCriticalPath, formatTodosList, githubServer, googleMapsServer, isAgentError, isConfigError, isImageBlock, isPluginError, isSessionError, isTextBlock, isThinkingBlock, isToolError, isToolResultBlock, isToolUseBlock, isWrongStackError, loadPlugins, loadProjectModes, loadUserModes, makeAgentSubagentRunner, makeDirectorSessionFactory, matchAny, matchGlob, migratePlaintextSecrets, normalizeToLf, projectHash, renderPrometheus, resolveWstackPaths, rewriteConfigEncrypted, rosterSummaryFromConfigs, runConfigMigrations, safeParse, safeStringify, sanitizeJsonString, sentinelServer, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, stripAnsi, toStyle, toWrongStackError, topologicalSort, unifiedDiff, unloadPlugins, validateAgainstSchema, wireMetricsToEvents, wrapAsState };
+export { ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, Agent, AgentError, AutoApprovePermissionPolicy, AutoCompactionMiddleware, AutonomousRunner, BUG_HUNTER_AGENT, BudgetExceededError, ConfigError, ConfigMigrationError, Container, Context, ConversationState, DEFAULT_CONFIG_MIGRATIONS, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_MAX_ITERATIONS, DEFAULT_MODES, DEFAULT_RECOVERY_STRATEGIES, DEFAULT_SPEC_TEMPLATE, DEFAULT_SUBAGENT_BASELINE, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultPluginAPI, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultSystemPromptBuilder, DefaultTaskStore, DefaultTokenCounter, Director, DirectorBudgetError, DirectorStateCheckpoint, DoneConditionChecker, EventBus, FLEET_ROSTER, FleetBus, FleetUsageAggregator, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, InputBuilder, IntelligentCompactor, KERNEL_API_VERSION, LAYER_1_IDENTITY, LLMSelector, NoopMetricsSink, NoopTracer, OTelTracer, PROMETHEUS_CONTENT_TYPE, Pipeline, PluginError, ProviderError, ProviderRegistry, QueueStore, REFACTOR_PLANNER_AGENT, RecoveryLock, RunController, SECURITY_SCANNER_AGENT, SelectiveCompactor, SessionAnalyzer, SessionError, SlashCommandRegistry, SpecDrivenDev, SpecParser, SubagentBudget, TOKENS, TaskFlow, TaskGenerator, TaskTracker, ToolError, ToolExecutor, ToolRegistry, WrongStackError, addPlanItem, allServers, asBlocks, asText, atomicWrite, attachPlanCheckpoint, attachTodosCheckpoint, awsServer, blockServer, braveSearchServer, buildChildEnv, buildOtlpMetricsRequest, buildOtlpTracesRequest, buildRecoveryStrategies, classifyFamily, clearPlan, color, compileGlob, composeDirectorPrompt, composeSubagentPrompt, computeTaskProgress, context7Server, contextManagerTool, createContextManagerTool, createDefaultPipelines, createDelegateTool, createMessage, createToolOutputSerializer, decryptConfigSecrets, detectNewlineStyle, emptyPlan, encryptConfigSecrets, ensureDir, estimateTextTokens, estimateToolInputTokens, estimateToolResultTokens, everArtServer, extractRunEnv, filesystemServer, findCriticalPath, formatPlan, formatTodosList, githubServer, googleMapsServer, isAgentError, isConfigError, isImageBlock, isPluginError, isSessionError, isTextBlock, isThinkingBlock, isToolError, isToolResultBlock, isToolUseBlock, isWrongStackError, loadDirectorState, loadPlan, loadPlugins, loadProjectModes, loadTodosCheckpoint, loadUserModes, makeAgentSubagentRunner, makeDirectorSessionFactory, matchAny, matchGlob, migratePlaintextSecrets, normalizeToLf, projectHash, removePlanItem, renderPrometheus, resolveWstackPaths, rewriteConfigEncrypted, rosterSummaryFromConfigs, runConfigMigrations, safeParse, safeStringify, sanitizeJsonString, savePlan, saveTodosCheckpoint, sentinelServer, setPlanItemStatus, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, stripAnsi, toStyle, toWrongStackError, topologicalSort, unifiedDiff, unloadPlugins, validateAgainstSchema, wireMetricsToEvents, wrapAsState };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map