@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/acp/session-manager.ts

@@ -5,9 +5,9 @@
 
 import { randomUUID } from "node:crypto";
 
-import { inArray } from "drizzle-orm";
+import { eq, inArray } from "drizzle-orm";
 
-import { findConversation } from "../daemon/conversation-store.js";
+import { findConversation } from "../daemon/conversation-registry.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import type { AcpSessionUpdate } from "../daemon/message-types/acp.js";
 import { getDb } from "../memory/db-connection.js";
@@ -16,10 +16,43 @@ import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { getLogger } from "../util/logger.js";
 import { AcpAgentProcess } from "./agent-process.js";
 import { VellumAcpClientHandler } from "./client-handler.js";
+import { prepareAgentEnv } from "./prepare-agent-env.js";
+import {
+  adapterCommandOf,
+  formatResolveFailure,
+  resolveAcpAgent,
+} from "./resolve-agent.js";
+import { claudeResumeHint } from "./resume-hint.js";
 import type { AcpAgentConfig, AcpSessionState } from "./types.js";
 
 const log = getLogger("acp:session-manager");
 
+/**
+ * The manager's "unknown session id" error. Thrown whenever an operation
+ * references an acpSessionId with no in-memory entry (and, for resume, no
+ * persisted history row). Callers (acp_steer tool, /v1/acp/:id/steer route)
+ * use `instanceof` checks to map this to their transport's not-found shape.
+ */
+export class AcpSessionNotFoundError extends Error {
+  constructor(public readonly acpSessionId: string) {
+    super(`ACP session "${acpSessionId}" not found`);
+    this.name = "AcpSessionNotFoundError";
+  }
+}
+
+/**
+ * Wraps failures from the resume-then-steer phase of `steerOrResume` so
+ * transport callers can distinguish them (HTTP 424 with the actionable
+ * resume hint) from plain steer failures (404). The message mirrors the
+ * underlying error's message; the original error rides on `cause`.
+ */
+export class AcpResumeError extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = "AcpResumeError";
+  }
+}
+
 /** Maximum number of update events kept in a session's ring buffer. */
 const MAX_BUFFER_EVENTS = 200;
 /** Maximum aggregate JSON size of a session's ring buffer, in bytes. */
@@ -41,11 +74,22 @@ interface SessionEntry {
   currentPrompt: Promise<unknown> | null;
   parentConversationId: string;
   cwd: string;
-  /** The adapter binary that was spawned. Used to gate resume hints to
-   *  the only adapter (claude-agent-acp) whose CLI accepts `--resume`. */
+  /** Canonical adapter command for the spawned config (e.g.
+   *  "claude-agent-acp" even when the adapter runs via `bun x`). Used to
+   *  gate resume hints to the only adapter (claude-agent-acp) whose CLI
+   *  accepts `--resume`. */
   command: string;
 }
 
+/**
+ * An `acp_session_history` row that passed resumeFromHistory's validation
+ * guards: `cwd` (nullable in the schema for pre-resume-support rows) is
+ * guaranteed present.
+ */
+type ResumableHistoryRow = typeof acpSessionHistory.$inferSelect & {
+  cwd: string;
+};
+
 export class AcpSessionManager {
   private sessions = new Map<string, SessionEntry>();
   /**
@@ -55,6 +99,25 @@ export class AcpSessionManager {
    * `acp_session_history` on terminal transition, then cleared.
    */
   private eventBuffers = new Map<string, BufferedAcpUpdate[]>();
+  /**
+   * In-flight resumes by session id, keyed to the promise of the resume's
+   * async body. Reserved SYNCHRONOUSLY before the first await so concurrent
+   * resumes of the same id cannot both pass the guards (the loser would
+   * overwrite the winner's map entry and leak its child process), and so N
+   * concurrent resumes of distinct ids cannot exceed maxConcurrent. The
+   * entry lives until the resume settles so `steerOrResume` can await a
+   * concurrent caller's resume instead of failing the already-active guard.
+   * The spawn path needs no such reservation: its check-then-register is
+   * synchronous.
+   */
+  private pendingResumes = new Map<string, Promise<void>>();
+
+  /**
+   * Set by dispose() (the daemon-shutdown path). Resumes that are mid-await
+   * when the manager is disposed re-check this flag before spawning a child
+   * process nothing would ever kill.
+   */
+  private disposed = false;
 
   constructor(private readonly maxConcurrent: number) {
     this.cleanupStaleRunningRows();
@@ -91,6 +154,33 @@ export class AcpSessionManager {
     }
   }
 
+  /**
+   * Ids that must be treated as live: registered sessions plus in-flight
+   * resume reservations (deduped, since a resuming session appears in both maps
+   * between registration and settle). Delete guards use this so a history
+   * row cannot be removed out from under a resume that is still awaiting
+   * env preparation; the later terminal upsert would resurrect it.
+   */
+  getActiveAndPendingIds(): string[] {
+    return [
+      ...new Set([...this.sessions.keys(), ...this.pendingResumes.keys()]),
+    ];
+  }
+
+  /**
+   * Concurrency guard shared by spawn() and resumeFromHistory(). Counts
+   * both registered sessions and in-flight resume reservations so the cap
+   * holds even while a resume is still awaiting prepareAgentEnv.
+   */
+  private assertCapacity(): void {
+    if (this.getActiveAndPendingIds().length >= this.maxConcurrent) {
+      throw new Error(
+        `ACP concurrency limit reached (max ${this.maxConcurrent}). ` +
+          `Close an existing session before spawning a new one.`,
+      );
+    }
+  }
+
   /**
    * Spawns a new ACP agent session. Returns the generated acpSessionId.
    *
@@ -105,12 +195,7 @@ export class AcpSessionManager {
     parentConversationId: string,
     sendToVellum: (msg: ServerMessage) => void,
   ): Promise<{ acpSessionId: string; protocolSessionId: string }> {
-    if (this.sessions.size >= this.maxConcurrent) {
-      throw new Error(
-        `ACP concurrency limit reached (max ${this.maxConcurrent}). ` +
-          `Close an existing session before spawning a new one.`,
-      );
-    }
+    this.assertCapacity();
 
     const acpSessionId = randomUUID();
     log.info(
@@ -124,40 +209,103 @@ export class AcpSessionManager {
       "ACP spawn requested",
     );
 
+    const entry = this.registerSession({
+      acpSessionId,
+      agentId,
+      agentConfig,
+      parentConversationId,
+      cwd,
+      startedAt: Date.now(),
+      sendToVellum,
+    });
+    const { process: agentProcess, state } = entry;
+
+    try {
+      log.info({ acpSessionId, agentId }, "ACP spawning child process");
+      agentProcess.spawn(cwd);
+      log.info(
+        { acpSessionId, agentId },
+        "ACP initializing protocol connection",
+      );
+      await agentProcess.initialize();
+      log.info({ acpSessionId, agentId }, "ACP creating session");
+      const acpProtocolSessionId = await agentProcess.createSession(cwd);
+      state.acpSessionId = acpProtocolSessionId;
+      state.status = "running";
+      log.info(
+        { acpSessionId, agentId, acpProtocolSessionId },
+        "ACP session running",
+      );
+    } catch (err) {
+      log.error({ acpSessionId, agentId, err }, "ACP spawn failed");
+      // No prompt has fired yet, so no permissions can be pending.
+      this.teardownSession(acpSessionId, entry);
+      throw err;
+    }
+
+    this.sendSpawnedEvent(acpSessionId, entry);
+
+    // Fire prompt in the background — don't await
+    entry.currentPrompt = this.firePromptInBackground(
+      acpSessionId,
+      entry,
+      state.acpSessionId,
+      task,
+    );
+
+    return { acpSessionId, protocolSessionId: state.acpSessionId };
+  }
+
+  /**
+   * Wires up the in-memory plumbing shared by spawn() and
+   * resumeFromHistory(): the per-session ring buffer, the buffer-mirroring
+   * sender, the client handler, the agent process, and the SessionEntry.
+   * Registers the entry in the session map (reserving a concurrency slot
+   * before any async work) and returns it. Does NOT start the process.
+   */
+  private registerSession(opts: {
+    acpSessionId: string;
+    agentId: string;
+    agentConfig: AcpAgentConfig;
+    parentConversationId: string;
+    cwd: string;
+    startedAt: number;
+    sendToVellum: (msg: ServerMessage) => void;
+  }): SessionEntry {
+    const { acpSessionId } = opts;
+
     // Initialize the per-session ring buffer before any update can fire.
     this.eventBuffers.set(acpSessionId, []);
 
     // Wrap the sender so every emitted message is mirrored into the buffer
     // when it's an `acp_session_update`. The wrapper preserves the original
-    // call semantics — it forwards every message unchanged.
+    // call semantics: it forwards every message unchanged.
     const wrappedSend = (msg: ServerMessage) => {
       if (msg.type === "acp_session_update") {
         this.appendToBuffer(acpSessionId, msg);
       }
-      sendToVellum(msg);
+      opts.sendToVellum(msg);
     };
 
     const clientHandler = new VellumAcpClientHandler(
       acpSessionId,
       wrappedSend,
-      parentConversationId,
+      opts.parentConversationId,
     );
 
     const agentProcess = new AcpAgentProcess(
-      agentId,
-      agentConfig,
+      opts.agentId,
+      opts.agentConfig,
       (_agent) => clientHandler,
     );
 
-    // Reserve a slot in the map before any async work to enforce the
-    // concurrency limit even when multiple spawn() calls race.
     const state: AcpSessionState = {
       id: acpSessionId,
-      agentId,
-      acpSessionId: "", // placeholder until createSession resolves
-      parentConversationId,
+      agentId: opts.agentId,
+      acpSessionId: "", // placeholder until createSession/resume resolves
+      parentConversationId: opts.parentConversationId,
       status: "initializing",
-      startedAt: Date.now(),
+      startedAt: opts.startedAt,
     };
 
     const entry: SessionEntry = {
@@ -166,54 +314,208 @@ export class AcpSessionManager {
       clientHandler,
       sendToVellum: wrappedSend,
       currentPrompt: null,
-      parentConversationId,
-      cwd,
-      command: agentConfig.command,
+      parentConversationId: opts.parentConversationId,
+      cwd: opts.cwd,
+      command: adapterCommandOf(opts.agentConfig),
     };
 
     this.sessions.set(acpSessionId, entry);
+    return entry;
+  }
+
+  /**
+   * Notifies connected clients that a session is live. Shared by spawn()
+   * and the resume path (resumed sessions reuse the spawned event so
+   * clients render them; a dedicated acp_session_resumed event is a
+   * possible follow-up, not in scope here).
+   */
+  private sendSpawnedEvent(acpSessionId: string, entry: SessionEntry): void {
+    entry.sendToVellum({
+      type: "acp_session_spawned",
+      acpSessionId,
+      agent: entry.state.agentId,
+      parentConversationId: entry.parentConversationId,
+    });
+  }
+
+  /**
+   * Resumes a terminal-state session from its persisted
+   * `acp_session_history` row, reattaching to the agent's stored
+   * conversation via ACP `session/resume` (preferred: no history replay) or
+   * `session/load` (replayed history is suppressed; see
+   * VellumAcpClientHandler.beginReplaySuppression).
+   *
+   * The resumed session reuses the original vellum session id,
+   * parentConversationId, and startedAt, and re-seeds its ring buffer from
+   * the persisted event log so the terminal upsert after the resumed run
+   * merges new events into the original row instead of losing them.
+   *
+   * Throws with an actionable message when the row is missing, was recorded
+   * before resume support (no cwd), the agent cannot be resolved, or the
+   * agent advertises neither resume capability.
+   */
+  async resumeFromHistory(
+    acpSessionId: string,
+    sendToVellum: (msg: ServerMessage) => void,
+  ): Promise<void> {
+    if (
+      this.sessions.has(acpSessionId) ||
+      this.pendingResumes.has(acpSessionId)
+    ) {
+      throw new Error(`ACP session "${acpSessionId}" is already active`);
+    }
+    this.assertCapacity();
+
+    const row = getDb()
+      .select()
+      .from(acpSessionHistory)
+      .where(eq(acpSessionHistory.id, acpSessionId))
+      .get();
+    if (!row) {
+      throw new AcpSessionNotFoundError(acpSessionId);
+    }
+    if (!row.cwd) {
+      throw new Error(
+        `ACP session "${acpSessionId}" was recorded before resume support ` +
+          `(no working directory persisted) and cannot be resumed. ` +
+          `Spawn a new session instead.`,
+      );
+    }
+    if (!row.acpSessionId) {
+      throw new Error(
+        `ACP session "${acpSessionId}" has no protocol session id ` +
+          `persisted and cannot be resumed. Spawn a new session instead.`,
+      );
+    }
+
+    const resolved = resolveAcpAgent(row.agentId);
+    if (!resolved.ok) {
+      throw new Error(formatResolveFailure(row.agentId, resolved));
+    }
+
+    // Everything up to here is synchronous. Reserve the id + concurrency
+    // slot BEFORE the first await so a concurrent resume of the same id
+    // (or a spawn racing the cap) fails the guards above instead of
+    // double-registering and leaking the first child process. The
+    // reservation holds the resume's promise until it settles so
+    // steerOrResume can await a concurrent caller's in-flight resume, and
+    // so the delete guards see the id as live while the row's terminal
+    // status still reflects the previous run.
+    const resumePromise = this.performResume(
+      acpSessionId,
+      row as ResumableHistoryRow,
+      resolved.agent,
+      sendToVellum,
+    );
+    this.pendingResumes.set(acpSessionId, resumePromise);
+    try {
+      await resumePromise;
+    } finally {
+      this.pendingResumes.delete(acpSessionId);
+    }
+  }
+
+  /**
+   * The async body of resumeFromHistory, split out so the caller can store
+   * its promise in `pendingResumes` synchronously before the first await.
+   * All guards and row validation have already passed.
+   */
+  private async performResume(
+    acpSessionId: string,
+    row: ResumableHistoryRow,
+    agent: AcpAgentConfig,
+    sendToVellum: (msg: ServerMessage) => void,
+  ): Promise<void> {
+    const agentConfig = await prepareAgentEnv(agent);
+
+    // The daemon may have shut down while prepareAgentEnv was pending.
+    // Registering now would spawn a child process on a disposed manager
+    // that nothing would ever kill.
+    if (this.disposed) {
+      throw new Error(
+        `ACP session manager is disposed; cannot resume session "${acpSessionId}"`,
+      );
+    }
+
+    const entry = this.registerSession({
+      acpSessionId,
+      agentId: row.agentId,
+      agentConfig,
+      parentConversationId: row.parentConversationId,
+      cwd: row.cwd,
+      startedAt: row.startedAt,
+      sendToVellum,
+    });
+
+    log.info(
+      { acpSessionId, agentId: row.agentId, cwd: row.cwd },
+      "ACP resume from history requested",
+    );
+    const { process: agentProcess, state } = entry;
+
+    // Re-seed the ring buffer from the persisted event log, routed through
+    // appendToBuffer so the count/byte caps still apply. The terminal
+    // upsert then persists the merged (old + new) log.
+    try {
+      const persisted = JSON.parse(row.eventLogJson) as unknown;
+      if (Array.isArray(persisted)) {
+        for (const update of persisted) {
+          this.appendToBuffer(acpSessionId, update as AcpSessionUpdate);
+        }
+      }
+    } catch (err) {
+      log.warn(
+        { acpSessionId, err },
+        "Failed to re-seed ACP event buffer from persisted history",
+      );
+    }
 
     try {
-      log.info({ acpSessionId, agentId }, "ACP spawning child process");
-      agentProcess.spawn(cwd);
       log.info(
-        { acpSessionId, agentId },
-        "ACP initializing protocol connection",
+        { acpSessionId, agentId: row.agentId },
+        "ACP spawning child process for resume",
       );
+      agentProcess.spawn(row.cwd);
       await agentProcess.initialize();
-      log.info({ acpSessionId, agentId }, "ACP creating session");
-      const acpProtocolSessionId = await agentProcess.createSession(cwd);
-      state.acpSessionId = acpProtocolSessionId;
+      if (agentProcess.supportsSessionResume) {
+        // session/resume reattaches without replaying history.
+        await agentProcess.resumeSession(row.acpSessionId, row.cwd);
+      } else if (agentProcess.supportsLoadSession) {
+        // session/load replays the full history as session/update
+        // notifications before resolving; suppress forwarding so the
+        // conversation and ring buffer don't receive duplicates.
+        entry.clientHandler.beginReplaySuppression();
+        try {
+          await agentProcess.loadSession(row.acpSessionId, row.cwd);
+        } finally {
+          entry.clientHandler.endReplaySuppression();
+        }
+      } else {
+        throw new Error(
+          `ACP agent "${row.agentId}" does not support session resume`,
+        );
+      }
+      state.acpSessionId = row.acpSessionId;
       state.status = "running";
       log.info(
-        { acpSessionId, agentId, acpProtocolSessionId },
-        "ACP session running",
+        {
+          acpSessionId,
+          agentId: row.agentId,
+          protocolSessionId: row.acpSessionId,
+        },
+        "ACP session resumed",
       );
     } catch (err) {
-      log.error({ acpSessionId, agentId, err }, "ACP spawn failed");
-      // Kill the orphaned child process and remove the reserved slot.
-      agentProcess.kill();
-      this.sessions.delete(acpSessionId);
-      this.eventBuffers.delete(acpSessionId);
+      log.error(
+        { acpSessionId, agentId: row.agentId, err },
+        "ACP resume failed",
+      );
+      // No prompt has fired yet, so no permissions can be pending.
+      this.teardownSession(acpSessionId, entry);
       throw err;
     }
 
-    wrappedSend({
-      type: "acp_session_spawned",
-      acpSessionId,
-      agent: agentId,
-      parentConversationId,
-    });
-
-    // Fire prompt in the background — don't await
-    entry.currentPrompt = this.firePromptInBackground(
-      acpSessionId,
-      entry,
-      state.acpSessionId,
-      task,
-    );
-
-    return { acpSessionId, protocolSessionId: state.acpSessionId };
+    this.sendSpawnedEvent(acpSessionId, entry);
   }
 
   /**
@@ -225,7 +527,7 @@ export class AcpSessionManager {
   async steer(acpSessionId: string, instruction: string): Promise<void> {
     const entry = this.sessions.get(acpSessionId);
     if (!entry) {
-      throw new Error(`ACP session "${acpSessionId}" not found`);
+      throw new AcpSessionNotFoundError(acpSessionId);
     }
 
     if (entry.state.status !== "running") {
@@ -258,22 +560,123 @@ export class AcpSessionManager {
     );
   }
 
+  /**
+   * Steers a session, transparently resuming it from persisted history
+   * first when it is no longer in memory (it completed, or the daemon
+   * restarted). The resume and the instruction prompt are atomic from the
+   * caller's perspective: a successfully resumed session immediately gets
+   * the instruction fired, so it never sits running-idle with no in-flight
+   * prompt (and therefore no teardown owner). If the post-resume steer
+   * fails, the freshly resumed session is closed (process killed, terminal
+   * row persisted, maps cleared) instead of being leaked.
+   *
+   * When a concurrent caller's resume of the same id is already in flight,
+   * this call awaits that resume and then retries the plain steer, so both
+   * callers' instructions land on the single resumed session.
+   *
+   * Error contract for transport callers (acp_steer tool, steer route):
+   * - `AcpSessionNotFoundError`: no in-memory session AND no history row.
+   * - `AcpResumeError`: the resume (own or a concurrent caller's awaited
+   *   one, or the steer immediately after an own resume) failed; the
+   *   message carries the actionable hint.
+   * - any other error: the plain steer on an in-memory session failed.
+   */
+  async steerOrResume(
+    acpSessionId: string,
+    instruction: string,
+    sendToVellum: (msg: ServerMessage) => void,
+  ): Promise<{ resumed: boolean }> {
+    try {
+      await this.steer(acpSessionId, instruction);
+      return { resumed: false };
+    } catch (err) {
+      // Fall through to the in-flight-resume handling both when the session
+      // is entirely unknown and when a concurrent resume has already
+      // registered its entry but is still initializing: steer rejects with a
+      // plain not-running error in that window, yet the resume reservation
+      // is live and the retry below will land once it settles.
+      if (
+        !(err instanceof AcpSessionNotFoundError) &&
+        !this.pendingResumes.has(acpSessionId)
+      ) {
+        throw err;
+      }
+    }
+
+    // Another caller's resume of this id may already be in flight (the
+    // session is not in memory yet, but its slot is reserved). Await that
+    // resume and retry the plain steer once instead of failing
+    // resumeFromHistory's already-active guard, which would surface a
+    // misleading resume error and drop this instruction.
+    const inFlightResume = this.pendingResumes.get(acpSessionId);
+    if (inFlightResume) {
+      try {
+        await inFlightResume;
+      } catch (err) {
+        throw new AcpResumeError(err);
+      }
+      // The resumed session is owned by the concurrent caller (its own
+      // post-resume steer handles teardown on failure), so a failure here
+      // propagates as a plain steer error without closing the session.
+      await this.steer(acpSessionId, instruction);
+      return { resumed: true };
+    }
+
+    try {
+      await this.resumeFromHistory(acpSessionId, sendToVellum);
+    } catch (err) {
+      // A missing history row keeps its not-found shape; everything else
+      // (legacy row without cwd, resolver failure, capability missing)
+      // is a resume failure with an actionable message.
+      if (err instanceof AcpSessionNotFoundError) throw err;
+      throw new AcpResumeError(err);
+    }
+
+    try {
+      await this.steer(acpSessionId, instruction);
+    } catch (err) {
+      // Tear down the just-resumed session rather than leaving it
+      // running-idle with no prompt handler to own its cleanup.
+      try {
+        this.close(acpSessionId);
+      } catch (closeErr) {
+        log.warn(
+          { acpSessionId, err: closeErr },
+          "Failed to close ACP session after post-resume steer failure",
+        );
+      }
+      throw new AcpResumeError(err);
+    }
+    return { resumed: true };
+  }
+
   /**
    * Cancels an ongoing prompt in the specified session.
    *
-   * The session's in-flight `prompt()` will reject in response, and the
-   * catch handler in `firePromptInBackground` performs the terminal
-   * persistence + teardown. We just flip the status here so that handler
-   * preserves "cancelled" instead of overwriting with "failed".
+   * When a prompt is in flight, its `prompt()` call rejects in response
+   * and the catch handler in `firePromptInBackground` performs the
+   * terminal persistence + teardown; we just flip the status here so that
+   * handler preserves "cancelled" instead of overwriting with "failed".
+   *
+   * When NO prompt is in flight there is no handler to own cleanup, so
+   * cancel persists and tears down the session itself. (Sessions normally
+   * always have a prompt in flight, but a cancel can race the window in
+   * steer() between clearing the old prompt and firing the new one.)
    */
   async cancel(acpSessionId: string): Promise<void> {
     const entry = this.sessions.get(acpSessionId);
     if (!entry) {
-      throw new Error(`ACP session "${acpSessionId}" not found`);
+      throw new AcpSessionNotFoundError(acpSessionId);
     }
     await entry.process.cancel(entry.state.acpSessionId);
     entry.state.status = "cancelled";
     entry.state.completedAt = Date.now();
+    // Re-check the map after the await: the in-flight prompt's handler may
+    // have already torn the session down while process.cancel was pending.
+    if (!entry.currentPrompt && this.sessions.get(acpSessionId) === entry) {
+      this.persistTerminal(acpSessionId, entry);
+      this.teardownSession(acpSessionId, entry);
+    }
   }
 
   /**
@@ -288,7 +691,7 @@ export class AcpSessionManager {
   close(acpSessionId: string): void {
     const entry = this.sessions.get(acpSessionId);
     if (!entry) {
-      throw new Error(`ACP session "${acpSessionId}" not found`);
+      throw new AcpSessionNotFoundError(acpSessionId);
     }
     if (
       entry.state.status === "running" ||
@@ -335,7 +738,7 @@ export class AcpSessionManager {
     if (acpSessionId) {
       const entry = this.sessions.get(acpSessionId);
       if (!entry) {
-        throw new Error(`ACP session "${acpSessionId}" not found`);
+        throw new AcpSessionNotFoundError(acpSessionId);
       }
       return entry.state;
     }
@@ -368,15 +771,18 @@ export class AcpSessionManager {
 
   /**
    * Persists the session's final state + buffered event log to
-   * `acp_session_history`, then frees the buffer entry. Best-effort: a DB
-   * failure is logged but does not propagate, since the session has already
-   * reached a terminal state and clients have been notified.
+   * `acp_session_history`, then frees the buffer entry. Upserts on id:
+   * resumed runs reuse the original vellum session id, so their terminal
+   * write must update the existing row (status, event log, etc.) instead of
+   * being silently skipped. Best-effort: a DB failure is logged but does
+   * not propagate, since the session has already reached a terminal state
+   * and clients have been notified.
    */
   private persistTerminal(acpSessionId: string, entry: SessionEntry): void {
     const buffer = this.eventBuffers.get(acpSessionId) ?? [];
     // Serialize only the wire-shaped updates — drop the byte-size accounting
     // metadata so persisted rows match the protocol shape clients receive.
-    const wireUpdates = buffer.map((buffered) => buffered.update);
+    const eventLogJson = JSON.stringify(buffer.map((b) => b.update));
     try {
       getDb()
         .insert(acpSessionHistory)
@@ -390,9 +796,20 @@ export class AcpSessionManager {
           status: entry.state.status,
           stopReason: entry.state.stopReason ?? null,
           error: entry.state.error ?? null,
-          eventLogJson: JSON.stringify(wireUpdates),
+          eventLogJson,
+          cwd: entry.cwd,
+        })
+        .onConflictDoUpdate({
+          target: acpSessionHistory.id,
+          set: {
+            status: entry.state.status,
+            completedAt: entry.state.completedAt ?? null,
+            stopReason: entry.state.stopReason ?? null,
+            error: entry.state.error ?? null,
+            eventLogJson,
+            cwd: entry.cwd,
+          },
         })
-        .onConflictDoNothing()
         .run();
     } catch (err) {
       log.error(
@@ -451,10 +868,12 @@ export class AcpSessionManager {
           const agentLabel = current.state.agentId;
           const responseText = current.clientHandler.responseText;
           const sessionId = current.state.acpSessionId;
-          const resumeHint =
-            current.command === "claude-agent-acp"
-              ? `\n\nTo resume: cd ${current.cwd} && claude --resume ${sessionId}`
-              : "";
+          const hint = claudeResumeHint(
+            current.command,
+            current.cwd,
+            sessionId,
+          );
+          const resumeHint = hint ? `\n\n${hint}` : "";
           const notifyMessage = `[ACP agent "${agentLabel}" completed]\n\n${responseText}${resumeHint}`;
           const parentConversation = findConversation(
             current.parentConversationId,
@@ -517,9 +936,12 @@ export class AcpSessionManager {
   }
 
   /**
-   * Kills all processes on shutdown.
+   * Kills all processes on shutdown. Also flags the manager as disposed so
+   * resumes that are mid-await when shutdown happens abort before spawning
+   * a child process nothing would ever kill.
    */
   dispose(): void {
+    this.disposed = true;
     this.closeAll();
   }
 }