@vellumai/assistant 0.10.3 → 0.10.4-dev.202607010028.1a4efcc

package/src/subagent/manager.ts

@@ -19,11 +19,17 @@ import {
   setSubagentConversation,
 } from "../daemon/conversation-registry.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
-import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { bootstrapConversation } from "../persistence/conversation-bootstrap.js";
+import {
+  deleteSubagentRecord,
+  loadAllSubagentRecords,
+  upsertSubagentRecord,
+} from "../persistence/subagent-store.js";
 import { wrapWithCallSiteRouting } from "../providers/call-site-routing.js";
 import { resolveDefaultProvider } from "../providers/connection-resolution.js";
 import { RateLimitProvider } from "../providers/ratelimit.js";
 import { listProviders } from "../providers/registry.js";
+import type { Message, TextContent } from "../providers/types.js";
 import { createAbortReason } from "../util/abort-reasons.js";
 import { ProviderNotConfiguredError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
@@ -58,6 +64,38 @@ export function mergeSkillIds(
   return [...new Set([...roleSkillIds, ...(configSkillIds ?? [])])];
 }
 
+// ── Final-text extraction helper ────────────────────────────────────────
+
+/**
+ * Concatenate the `text` blocks of the conversation's trailing assistant
+ * message. Used by `spawnAndAwait` to return the child's final synthesis to
+ * the awaiting caller. Returns an empty string when the conversation has no
+ * assistant message or the final assistant message carries no text blocks
+ * (e.g. it ended on a tool_use).
+ */
+function extractFinalAssistantText(messages: Message[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role !== "assistant") continue;
+    return message.content
+      .filter((block): block is TextContent => block.type === "text")
+      .map((block) => block.text)
+      .join("");
+  }
+  return "";
+}
+
+/**
+ * Pull the user-visible text out of a streaming delta event, or null for any
+ * other event type. Used by the synchronous `onText` tap to forward
+ * `assistant_text_delta` / `assistant_thinking_delta` chunks to the caller.
+ */
+function extractDeltaText(msg: ServerMessage): string | null {
+  if (msg.type === "assistant_text_delta") return msg.text;
+  if (msg.type === "assistant_thinking_delta") return msg.thinking;
+  return null;
+}
+
 // ── Default subagent system prompt ──────────────────────────────────────
 
 function buildSubagentSystemPrompt(
@@ -84,6 +122,73 @@ function buildSubagentSystemPrompt(
   return sections.join("\n");
 }
 
+/**
+ * Build the message injected into the parent conversation when a subagent
+ * reaches a terminal state.
+ *
+ * For a completed subagent the final synthesis is inlined directly, so the
+ * parent acts on the result without a `subagent_read` round-trip and has
+ * nothing left to re-spawn. The `subagent_read` pointer survives only as a
+ * fallback for the rare run that ends with no trailing assistant text.
+ *
+ * Exported for unit testing.
+ */
+export function buildSubagentTerminalMessage(opts: {
+  label: string;
+  subagentId: string;
+  isFork: boolean;
+  outcome: "completed" | "failed";
+  silent: boolean;
+  finalText?: string;
+  error?: string;
+  /** A follow-up turn is still queued, so the current synthesis is a snapshot. */
+  deferred?: boolean;
+}): string {
+  const {
+    label,
+    subagentId,
+    isFork,
+    outcome,
+    silent,
+    finalText,
+    error,
+    deferred,
+  } = opts;
+  const prefix = isFork ? "Fork" : "Subagent";
+
+  if (outcome === "failed") {
+    return (
+      `[${prefix} "${label}" failed]\n\n` +
+      `Error: ${error ?? "Unknown error"}\n` +
+      `Do NOT re-spawn or retry this ${prefix.toLowerCase()} unless the user explicitly asks.`
+    );
+  }
+
+  const trimmed = finalText?.trim() ?? "";
+  if (trimmed && !deferred) {
+    return (
+      `[${prefix} "${label}" completed — result below]\n\n` +
+      `${trimmed}\n\n` +
+      (silent
+        ? `(Use these findings internally; do not relay the raw ${prefix.toLowerCase()} output to the user.)`
+        : `(Incorporate this into your reply to the user as appropriate.)`)
+    );
+  }
+
+  // Read-pointer path: either the run left no trailing assistant text to inline,
+  // or a queued follow-up turn is still draining — so the current synthesis is a
+  // stale snapshot and the parent should read the latest output instead.
+  const lastN = isFork ? " and last_n: 1" : "";
+  const reason = deferred
+    ? `Queued follow-up guidance is still being processed`
+    : `The ${prefix.toLowerCase()} produced no final text`;
+  return (
+    `[${prefix} "${label}" completed]\n\n` +
+    `${reason}. Use subagent_read with subagent_id "${subagentId}"${lastN} for the latest output.` +
+    (silent ? ` Keep the result internal.` : ``)
+  );
+}
+
 // ── Manager ─────────────────────────────────────────────────────────────
 
 interface ManagedSubagent {
@@ -110,6 +215,19 @@ interface ManagedSubagent {
    * the release to the TTL sweep rather than tearing down mid-drain.
    */
   hadEnqueuedMessages?: boolean;
+  /**
+   * Set on the synchronous `spawnAndAwait` path. When true, `runSubagent`
+   * skips the terminal parent-injection (`notifyParentTerminal`) — the awaiting
+   * caller receives the child's final text directly, so re-injecting a
+   * "read the result" notification into the parent would be redundant noise.
+   */
+  synchronous?: boolean;
+  /**
+   * Optional text tap for the synchronous path. When set, `wrappedSendToClient`
+   * forwards each `assistant_text_delta` / `assistant_thinking_delta` chunk to
+   * this callback IN ADDITION to the normal `subagent_event` envelope.
+   */
+  onText?: (chunk: string) => void;
 }
 
 export interface SubagentNotificationInfo {
@@ -121,6 +239,21 @@ export interface SubagentNotificationInfo {
   objective?: string;
 }
 
+/**
+ * Thrown by `spawnAndAwait` when the run is aborted (e.g. an external timeout)
+ * before reaching a terminal `completed` state. Carries `partialText` — the
+ * child's trailing assistant text captured at the moment of abort — so a caller
+ * that times out a long generation can still surface the partial result instead
+ * of discarding it. Extends `Error` with the same legacy message, so callers
+ * that only inspect `.message` keep working.
+ */
+export class SubagentAbortedError extends Error {
+  constructor(readonly partialText: string) {
+    super("Subagent run aborted before completion.");
+    this.name = "SubagentAbortedError";
+  }
+}
+
 export class SubagentManager {
   /** subagentId → ManagedSubagent */
   private subagents = new Map<string, ManagedSubagent>();
@@ -130,8 +263,16 @@ export class SubagentManager {
   private labelIndex = new Map<string, string>();
 
   /**
-   * Shared rate-limit timestamps array from the daemon server.
-   * Set by DaemonServer at startup so subagents share the global rate limit.
+   * Set during `disposeAll()` (shutdown) so `dispose()` keeps the durable rows
+   * instead of deleting them — an in-flight subagent must survive as a row to
+   * be rehydrated as `interrupted` on the next boot.
+   */
+  private shuttingDown = false;
+
+  /**
+   * Cross-conversation rate-limit window. The conversation store reads this
+   * same array when building its per-conversation RateLimitProvider, so
+   * subagent requests and conversation requests share one global budget.
    */
   sharedRequestTimestamps: number[] = [];
 
@@ -145,6 +286,30 @@ export class SubagentManager {
     config: Omit<SubagentConfig, "id">,
     parentSendToClient: (msg: ServerMessage) => void,
   ): Promise<string> {
+    const { subagentId } = await this.setUpSubagent(config, parentSendToClient);
+
+    // ── Kick off the agent loop (fire-and-forget) ───────────────────
+    this.runSubagent(subagentId, config.objective).catch((err) => {
+      log.error({ subagentId, err }, "Subagent run failed unexpectedly");
+    });
+
+    return subagentId;
+  }
+
+  // ── Internal: shared spawn setup ──────────────────────────────────────
+
+  /**
+   * Perform all spawn-time setup shared by `spawn` and `spawnAndAwait`:
+   * enforce the depth limit, resolve role/provider/system prompt, construct
+   * the child Conversation, register it, and emit the `subagent_spawned`
+   * event. Does NOT start the agent loop — the caller decides whether to run
+   * fire-and-forget (`spawn`) or awaited (`spawnAndAwait`).
+   */
+  private async setUpSubagent(
+    config: Omit<SubagentConfig, "id">,
+    parentSendToClient: (msg: ServerMessage) => void,
+    opts?: { synchronous?: boolean; onText?: (chunk: string) => void },
+  ): Promise<{ subagentId: string; managed: ManagedSubagent }> {
     // ── Limit checks ────────────────────────────────────────────────
 
     // Depth check: prevent subagents from spawning nested subagents.
@@ -159,17 +324,20 @@ export class SubagentManager {
 
     // ── Resolve role ─────────────────────────────────────────────────
     const isFork = config.fork === true;
-    let role: SubagentRole = (config.role as SubagentRole) ?? "general";
+    const role: SubagentRole = (config.role as SubagentRole) ?? "general";
     if (isFork && role !== "general") {
+      // A context-inheriting subagent normally keeps the parent's `general`
+      // role so its KV cache stays aligned with the parent conversation. An
+      // explicit non-general role opts out of that alignment on purpose
+      // (e.g. the advisor role running on a stronger profile), so honor it.
       log.warn(
         {
           requestedRole: role,
           parentConversationId: config.parentConversationId,
           label: config.label,
         },
-        "Fork requested with non-general role — forcing general to preserve KV cache alignment",
+        "Fork requested with non-general role — caller opted out of parent KV-cache alignment",
       );
-      role = "general";
     }
     if (!SUBAGENT_ROLE_REGISTRY[role]) {
       throw new Error(
@@ -180,7 +348,7 @@ export class SubagentManager {
 
     // ── Create conversation ─────────────────────────────────────────
     const subagentId = uuid();
-    const conversationRecord = bootstrapConversation({
+    const conversationRecord = await bootstrapConversation({
       conversationType: "background",
       source: "subagent",
       origin: "subagent",
@@ -219,19 +387,21 @@ export class SubagentManager {
 
     let systemPrompt: string;
     if (isFork) {
-      // Forks use the parent's system prompt directly — no subagent preamble.
-      if (config.parentSystemPrompt) {
-        systemPrompt = config.parentSystemPrompt;
-      } else {
-        const resolved = parentConversation?.getCurrentSystemPrompt();
-        if (!resolved) {
-          throw new Error(
-            "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
-              "nor findConversation yielded one.",
-          );
-        }
-        systemPrompt = resolved;
+      // Forks default to the parent's system prompt verbatim — no subagent
+      // preamble — so the KV cache stays aligned with the parent. An explicit
+      // `systemPromptOverride` opts out of that alignment and takes precedence
+      // (e.g. the advisor role framing the inherited context as advice).
+      const resolved =
+        config.systemPromptOverride ??
+        config.parentSystemPrompt ??
+        parentConversation?.getCurrentSystemPrompt();
+      if (!resolved) {
+        throw new Error(
+          "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
+            "nor findConversation yielded one.",
+        );
       }
+      systemPrompt = resolved;
     } else {
       systemPrompt =
         config.systemPromptOverride ??
@@ -279,11 +449,20 @@ export class SubagentManager {
       conversation: null! as Conversation,
       state,
       parentSendToClient,
+      ...(opts?.synchronous ? { synchronous: true } : {}),
+      ...(opts?.onText ? { onText: opts.onText } : {}),
     };
 
     // Wrap sendToClient to envelope all events with the subagent ID.
     // Reads from managed.parentSendToClient so reconnects are picked up.
     const wrappedSendToClient = (msg: ServerMessage): void => {
+      // Tap streaming text/thinking deltas for the synchronous caller (if any),
+      // in addition to the normal envelope below. Reads from managed.onText so
+      // the synchronous path can forward chunks without altering event routing.
+      if (managed.onText) {
+        const text = extractDeltaText(msg);
+        if (text) managed.onText(text);
+      }
       managed.parentSendToClient({
         type: "subagent_event",
         subagentId,
@@ -298,7 +477,16 @@ export class SubagentManager {
       systemPrompt,
       wrappedSendToClient,
       workingDir,
-      { maxTokens, cacheTtl: "5m" },
+      {
+        maxTokens,
+        cacheTtl: "5m",
+        // The advisor consult runs tool-less for CLIENT tools but should ground
+        // its guidance with provider-native web search when the resolved
+        // provider supports it. This is a server tool the provider runs itself,
+        // so it stays one-shot — no client tool surfaced, allowlist unchanged.
+        // Other roles keep the default (no native search appended).
+        ...(role === "advisor" ? { enableNativeWebSearch: true } : {}),
+      },
     );
 
     // Mark conversation as having no direct client — it routes through parent.
@@ -325,16 +513,19 @@ export class SubagentManager {
       conversation.setAssistantId(parentConversation.assistantId);
     }
 
-    if (isFork) {
-      // Force the fork to use the parent's system prompt as-is without dynamic rebuild.
-      // This ensures KV cache alignment with the parent conversation.
+    if (isFork && !config.systemPromptOverride) {
+      // A verbatim-prompt fork pins the parent's system prompt as-is, skipping
+      // the dynamic rebuild so the KV cache stays aligned with the parent. A
+      // fork that supplies its own override prompt opts out of that alignment,
+      // so leave `hasSystemPromptOverride` at its default.
       conversation.hasSystemPromptOverride = true;
     }
 
-    // Apply role-based tool filter if the role defines one.
-    // Skip for forks — general role has allowedTools: undefined, and forks
-    // should have the same tool access as the parent.
-    if (!isFork && roleConfig.allowedTools) {
+    // Apply the role's tool allowlist when one is defined. The `general` role
+    // has `allowedTools: undefined`, so default forks (which keep the general
+    // role) are unaffected; a fork carrying an explicit role gets its
+    // allowlist applied like any other subagent.
+    if (roleConfig.allowedTools) {
       conversation.setSubagentAllowedTools(new Set(roleConfig.allowedTools));
     }
 
@@ -373,6 +564,9 @@ export class SubagentManager {
     }
     this.parentToChildren.get(config.parentConversationId)!.add(subagentId);
 
+    // Persist the initial record so the subagent survives a daemon restart.
+    this.persistState(managed.state);
+
     // Notify client that a subagent was spawned.
     parentSendToClient({
       type: "subagent_spawned",
@@ -393,12 +587,65 @@ export class SubagentManager {
       "Subagent spawned",
     );
 
-    // ── Kick off the agent loop (fire-and-forget) ───────────────────
-    this.runSubagent(subagentId, config.objective).catch((err) => {
-      log.error({ subagentId, err }, "Subagent run failed unexpectedly");
-    });
+    return { subagentId, managed };
+  }
 
-    return subagentId;
+  // ── Spawn and await (synchronous) ─────────────────────────────────────
+
+  /**
+   * Spawn a subagent and AWAIT its run, resolving to the child's final
+   * assistant text. Unlike `spawn` (fire-and-forget), the caller blocks until
+   * the child reaches a terminal state and receives the text directly — so the
+   * terminal parent-injection (`notifyParentTerminal`) is skipped on this path.
+   *
+   * `opts.signal` aborts the underlying run when triggered (e.g. an external
+   * timeout). `opts.onText` receives each streaming text/thinking chunk in
+   * addition to the normal `subagent_event` envelope.
+   */
+  async spawnAndAwait(
+    config: Omit<SubagentConfig, "id">,
+    parentSendToClient: (msg: ServerMessage) => void,
+    opts?: { signal?: AbortSignal; onText?: (chunk: string) => void },
+  ): Promise<string> {
+    const { subagentId, managed } = await this.setUpSubagent(
+      config,
+      parentSendToClient,
+      { synchronous: true, ...(opts?.onText ? { onText: opts.onText } : {}) },
+    );
+
+    // Wire the external signal to abort the child conversation. If the signal
+    // is already aborted, abort immediately so the run rejects promptly.
+    const signal = opts?.signal;
+    const onAbort = (): void => {
+      // Route through the manager abort path so the subagent is marked terminal
+      // ("aborted") and broadcast as such. A bare conversation.abort() leaves
+      // status non-terminal, so runSubagent's success branch would record the
+      // run as "completed" once runAgentLoop resolves the consumed cancellation.
+      // Suppress the parent notification: the awaiting caller observes the abort
+      // as a thrown rejection, so a "do NOT re-spawn" injection would be
+      // redundant noise.
+      this.abort(subagentId, managed.parentSendToClient, undefined, {
+        suppressNotification: true,
+      });
+    };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    try {
+      const finalText = await this.runSubagent(subagentId, config.objective);
+      // Surface aborts as a rejection so the caller's timeout path is
+      // observable — but carry the partial text on the error so a caller that
+      // timed out a long generation (e.g. the advisor consult) can still
+      // surface what was produced instead of throwing it away.
+      if (signal?.aborted) {
+        throw new SubagentAbortedError(finalText);
+      }
+      return finalText;
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+    }
   }
 
   // ── Internal: run the subagent ────────────────────────────────────────
@@ -406,19 +653,39 @@ export class SubagentManager {
   private async runSubagent(
     subagentId: string,
     objective: string,
-  ): Promise<void> {
+  ): Promise<string> {
     const managed = this.subagents.get(subagentId);
-    if (!managed) return;
+    if (!managed) return "";
 
     // Capture the live conversation — it is non-null at this point because
     // spawn() sets it before firing runSubagent.
     const conversation = managed.conversation!;
 
+    // The child's trailing assistant text, captured after runAgentLoop resolves
+    // (before the `finally` releases the conversation). Returned to the
+    // synchronous `spawnAndAwait` caller; the fire-and-forget `spawn` caller
+    // ignores it.
+    let finalText = "";
+
+    // Aborted before the run started (e.g. an already-aborted signal on the
+    // synchronous spawnAndAwait path): the subagent is already terminal. Do not
+    // start the agent loop or reset status back to "running" — but still release
+    // the conversation, exactly as the post-run `finally` does for a terminal
+    // run. The loop never started, so no messages were enqueued; this matches
+    // the finally's non-deferred release branch.
+    if (TERMINAL_STATUSES.has(managed.state.status)) {
+      this.releaseConversation(managed);
+      return finalText;
+    }
+
     // Read the current parent sender so reconnects are picked up.
     const getSender = () => managed.parentSendToClient;
 
-    this.setStatus(subagentId, "running", getSender());
+    // Stamp startedAt before the status transition so the persistence hook
+    // inside setStatus captures it on the running row (otherwise a crash mid-run
+    // rehydrates as interrupted with no start time).
     managed.state.startedAt = Date.now();
+    this.setStatus(subagentId, "running", getSender());
 
     try {
       // For forks, inject the parent's message history before the first message.
@@ -441,7 +708,16 @@ export class SubagentManager {
       // the fork tends to continue the parent conversation instead of
       // pivoting to the task — the inherited context is louder than a bare
       // objective buried after 100k+ tokens of chat history.
-      const message = managed.state.isFork
+      //
+      // The advisor consult is the exception: it is a fork, but its
+      // `systemPromptOverride` already frames the inherited context as advice
+      // ("you are a senior advisor … do not write its final deliverable"), so
+      // the generic "complete this task and return your findings" wrapper would
+      // fight that framing. The advisor's objective is already the bare advice
+      // request (`advisorRequestText()`), so it is sent uncontested.
+      const useForkFraming =
+        managed.state.isFork && managed.state.config.role !== "advisor";
+      const message = useForkFraming
         ? [
             "⎯⎯⎯ FORK TASK ⎯⎯⎯",
             "You have been forked from the parent conversation to execute a specific task.",
@@ -466,6 +742,9 @@ export class SubagentManager {
       });
 
       // Agent loop completed successfully.
+      // Capture the trailing assistant text before any release nulls the
+      // conversation reference. The fire-and-forget caller ignores the return.
+      finalText = extractFinalAssistantText(conversation.messages);
       // Copy usage stats from the conversation before sending status (which includes usage).
       managed.state.usage = { ...conversation.usageStats };
       // Only update state + notify if still non-terminal (guards against abort race).
@@ -475,8 +754,13 @@ export class SubagentManager {
 
         log.info({ subagentId }, "Subagent completed");
 
-        // Notify the parent conversation so the LLM can call subagent_read.
-        this.notifyParentTerminal(managed, "completed");
+        // Notify the parent conversation, inlining the subagent's final
+        // synthesis so the LLM acts on the result without a subagent_read
+        // round-trip. Skipped on the synchronous path — the awaiting caller
+        // receives the final text directly.
+        if (!managed.synchronous) {
+          this.notifyParentTerminal(managed, "completed", finalText);
+        }
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
@@ -489,10 +773,22 @@ export class SubagentManager {
       // Only update status if not already terminal (e.g. aborted).
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
         this.setStatus(subagentId, "failed", getSender(), errorMsg);
-        this.notifyParentTerminal(managed, "failed");
+        // Skip terminal parent-injection on the synchronous path — the failure
+        // surfaces to the awaiting caller as a rejected promise instead.
+        if (!managed.synchronous) {
+          this.notifyParentTerminal(managed, "failed");
+        }
       }
 
       log.error({ subagentId, err }, "Subagent failed");
+
+      // Surface the failure to the synchronous caller. The fire-and-forget
+      // path has no awaiter, so re-throwing there only feeds the `.catch()`
+      // logger in `spawn` — harmless but noisy — so it is confined to the
+      // synchronous path.
+      if (managed.synchronous) {
+        throw err;
+      }
     } finally {
       // Release the heavyweight Conversation — output is already persisted in DB.
       // drainQueue is async: it awaits buildPassthroughBatch (which awaits
@@ -516,6 +812,8 @@ export class SubagentManager {
         this.releaseConversation(managed);
       }
     }
+
+    return finalText;
   }
 
   // ── Abort ─────────────────────────────────────────────────────────────
@@ -592,6 +890,7 @@ export class SubagentManager {
       }
     } else {
       managed.state.status = "aborted";
+      this.persistState(managed.state);
     }
 
     log.info({ subagentId }, "Subagent aborted");
@@ -702,8 +1001,12 @@ export class SubagentManager {
   }
 
   /**
-   * Update the parent sender for all active children of a conversation.
-   * Called when the parent client reconnects to a new socket.
+   * Update the parent sender for all active children of a conversation and
+   * re-emit each child's current status to it. Called when the parent client
+   * reconnects to a new socket, so a reconnecting client resyncs any status it
+   * missed while disconnected (e.g. a subagent marked `interrupted` during
+   * rehydration after a daemon restart, whose card would otherwise stay stuck
+   * on a stale `running`).
    */
   updateParentSender(
     parentConversationId: string,
@@ -714,9 +1017,19 @@ export class SubagentManager {
 
     for (const childId of children) {
       const managed = this.subagents.get(childId);
-      if (managed && !TERMINAL_STATUSES.has(managed.state.status)) {
+      if (!managed) continue;
+      if (!TERMINAL_STATUSES.has(managed.state.status)) {
         managed.parentSendToClient = newSendToClient;
       }
+      // Re-emit the current status so the reconnecting client corrects any card
+      // it left in a stale state while disconnected.
+      newSendToClient({
+        type: "subagent_status_changed",
+        subagentId: childId,
+        status: managed.state.status,
+        error: managed.state.error,
+        usage: managed.state.usage,
+      } as ServerMessage);
     }
   }
 
@@ -768,6 +1081,17 @@ export class SubagentManager {
     }
     this.subagents.delete(subagentId);
 
+    // Drop the durable record too — but only during normal operation. On
+    // shutdown we keep rows so a subagent that was in flight can rehydrate as
+    // `interrupted` on the next boot.
+    if (!this.shuttingDown) {
+      try {
+        deleteSubagentRecord(subagentId);
+      } catch (err) {
+        log.warn({ subagentId, err }, "Failed to delete subagent record");
+      }
+    }
+
     // Remove from label index only if it still maps to this subagent
     // (guards against stale delete when a newer subagent reused the label).
     const label = managed.state.config.label;
@@ -790,12 +1114,122 @@ export class SubagentManager {
 
   /** Dispose all subagents. Called on daemon shutdown. */
   disposeAll(): void {
+    // Mark shutdown so dispose() keeps the durable rows: an in-flight subagent
+    // must survive as a row to be rehydrated as `interrupted` on the next boot.
+    this.shuttingDown = true;
     this.stopSweep();
     for (const id of [...this.subagents.keys()]) {
       this.dispose(id);
     }
   }
 
+  // ── Persistence / rehydration ─────────────────────────────────────────
+
+  /**
+   * Write the subagent's current state to the durable `subagents` table.
+   * Best-effort: persistence failures are logged, never thrown — a background
+   * subagent must not fail because its bookkeeping row could not be written.
+   */
+  private persistState(state: SubagentState): void {
+    try {
+      upsertSubagentRecord({
+        id: state.config.id,
+        parentConversationId: state.config.parentConversationId,
+        conversationId: state.conversationId,
+        label: state.config.label,
+        objective: state.config.objective,
+        role: state.config.role ?? "general",
+        isFork: state.isFork,
+        sendResultToUser: state.config.sendResultToUser ?? null,
+        status: state.status,
+        error: state.error ?? null,
+        createdAt: state.createdAt,
+        startedAt: state.startedAt ?? null,
+        completedAt: state.completedAt ?? null,
+        inputTokens: state.usage.inputTokens,
+        outputTokens: state.usage.outputTokens,
+        estimatedCost: state.usage.estimatedCost,
+      });
+    } catch (err) {
+      log.warn(
+        { subagentId: state.config.id, err },
+        "Failed to persist subagent record",
+      );
+    }
+  }
+
+  /**
+   * Rebuild in-memory subagent metadata from the durable table after a restart.
+   * Terminal records load as-is so `subagent_read`/`getState` keep working
+   * (output is read from the child conversation's persisted messages). Records
+   * still in flight when the process died are marked `interrupted` — the run is
+   * not resumed; the parent decides whether to re-spawn. Rehydrated entries
+   * carry a no-op sender and no live conversation, and are swept on the normal
+   * TTL like any other terminal subagent.
+   *
+   * Best-effort and idempotent: a second restart re-reads `interrupted` rows
+   * and leaves them unchanged.
+   */
+  rehydrateFromDb(): { rehydrated: number; interrupted: number } {
+    const records = loadAllSubagentRecords();
+    let interrupted = 0;
+    const now = Date.now();
+    for (const rec of records) {
+      const wasInFlight = !TERMINAL_STATUSES.has(rec.status as SubagentStatus);
+      const status: SubagentStatus = wasInFlight
+        ? "interrupted"
+        : (rec.status as SubagentStatus);
+      if (wasInFlight) interrupted++;
+
+      const state: SubagentState = {
+        config: {
+          id: rec.id,
+          parentConversationId: rec.parentConversationId,
+          label: rec.label,
+          objective: rec.objective,
+          role: rec.role as SubagentRole,
+          fork: rec.isFork,
+          ...(rec.sendResultToUser != null
+            ? { sendResultToUser: rec.sendResultToUser }
+            : {}),
+        },
+        status,
+        conversationId: rec.conversationId,
+        isFork: rec.isFork,
+        ...(rec.error != null ? { error: rec.error } : {}),
+        createdAt: rec.createdAt,
+        ...(rec.startedAt != null ? { startedAt: rec.startedAt } : {}),
+        ...(rec.completedAt != null ? { completedAt: rec.completedAt } : {}),
+        usage: {
+          inputTokens: rec.inputTokens,
+          outputTokens: rec.outputTokens,
+          estimatedCost: rec.estimatedCost,
+        },
+      };
+
+      const managed: ManagedSubagent = {
+        conversation: null,
+        state,
+        parentSendToClient: () => {},
+        retainedUntil: now + TERMINAL_RETENTION_MS,
+      };
+      this.subagents.set(rec.id, managed);
+
+      const labelKey = `${rec.parentConversationId}:${rec.label.toLowerCase().trim()}`;
+      this.labelIndex.set(labelKey, rec.id);
+
+      if (!this.parentToChildren.has(rec.parentConversationId)) {
+        this.parentToChildren.set(rec.parentConversationId, new Set());
+      }
+      this.parentToChildren.get(rec.parentConversationId)!.add(rec.id);
+
+      // Persist the interrupted transition so a second restart is a no-op.
+      if (wasInFlight) this.persistState(state);
+    }
+    if (records.length > 0) this.ensureSweepRunning();
+    return { rehydrated: records.length, interrupted };
+  }
+
   // ── TTL sweep for terminal metadata ──────────────────────────────────
 
   private sweepTimer?: ReturnType<typeof setInterval>;
@@ -884,6 +1318,9 @@ export class SubagentManager {
       error,
       usage: managed.state.usage,
     } as ServerMessage);
+
+    // Mirror the transition to the durable record.
+    this.persistState(managed.state);
   }
 
   // ── Child → Parent notification ────────────────────────────────────
@@ -952,43 +1389,36 @@ export class SubagentManager {
   }
 
   /**
-   * Inject a completion/failure notification into the parent conversation
-   * so the LLM automatically informs the user.
+   * Inject a completion/failure notification into the parent conversation so
+   * the LLM automatically informs the user. On completion the subagent's final
+   * synthesis is inlined (via `buildSubagentTerminalMessage`) so the parent acts
+   * on the result directly rather than issuing a `subagent_read` call.
    */
   private notifyParentTerminal(
     managed: ManagedSubagent,
     outcome: "completed" | "failed",
+    finalText?: string,
   ): void {
     const { config } = managed.state;
     const isFork = managed.state.isFork;
-    let message: string;
-
-    if (outcome === "completed") {
-      if (isFork) {
-        const silent = config.sendResultToUser !== true;
-        message =
-          `[Fork "${config.label}" completed]\n\n` +
-          `Use subagent_read with subagent_id "${config.id}" and last_n: 1 to retrieve the final synthesis.\n` +
-          (silent
-            ? `This fork was spawned for internal processing. Process the findings internally — do NOT share raw fork output with the user.`
-            : `Do NOT re-spawn this fork — just read and share the results.`);
-      } else {
-        const silent = config.sendResultToUser === false;
-        message =
-          `[Subagent "${config.label}" completed]\n\n` +
-          `Use subagent_read with subagent_id "${config.id}" to retrieve the full output.\n` +
-          (silent
-            ? `This subagent was spawned for internal processing. Read the result for your own use but do NOT share it with the user.\nDo NOT re-spawn this subagent.`
-            : `Do NOT re-spawn this subagent — just read and share the results.`);
-      }
-    } else {
-      const error = managed.state.error ?? "Unknown error";
-      const prefix = isFork ? "Fork" : "Subagent";
-      message =
-        `[${prefix} "${config.label}" failed]\n\n` +
-        `Error: ${error}\n` +
-        `Do NOT re-spawn or retry this ${prefix.toLowerCase()} unless the user explicitly asks.`;
-    }
+    // Forks default to internal/silent unless explicitly shared; regular
+    // subagents share with the user unless explicitly silenced.
+    const silent = isFork
+      ? config.sendResultToUser !== true
+      : config.sendResultToUser === false;
+
+    const message = buildSubagentTerminalMessage({
+      label: config.label,
+      subagentId: config.id,
+      isFork,
+      outcome,
+      silent,
+      finalText,
+      error: managed.state.error,
+      // A queued follow-up turn means the snapshot we hold is stale; defer to a
+      // read pointer so the parent picks up the queued turn's output instead.
+      deferred: managed.hadEnqueuedMessages === true,
+    });
 
     const notification: SubagentNotificationInfo = {
       subagentId: config.id,