@documentation-robotics/cli 0.3.0 → 0.4.0

package/dist/server/server.js

@@ -1,11 +1,13 @@
 import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
 import { cors } from "hono/cors";
 import { swaggerUI } from "@hono/swagger-ui";
-import { serve } from "@hono/node-server";
+import { createAdaptorServer } from "@hono/node-server";
 import { createNodeWebSocket } from "@hono/node-ws";
 import { spawn, spawnSync } from "child_process";
 import chokidar from "chokidar";
-import { randomBytes } from "crypto";
+import { randomBytes, randomUUID } from "crypto";
+import { existsSync, realpathSync } from "fs";
+import { homedir } from "os";
 import { createRequire } from "module";
 import { fileURLToPath } from "url";
 import path from "path";
@@ -14,13 +16,13 @@ import { Model } from "../core/model.js";
 import { StagedChangesetStorage } from "../core/staged-changeset-storage.js";
 import { StagingAreaManager } from "../core/staging-area.js";
 import { CANONICAL_LAYER_NAMES } from "../core/layers.js";
+import { AnnotationStore } from "../core/annotation-store.js";
 import { telemetryMiddleware } from "./telemetry-middleware.js";
 import { ClaudeCodeClient } from "../coding-agents/claude-code-client.js";
 import { CopilotClient } from "../coding-agents/copilot-client.js";
 import { detectAvailableClients, selectChatClient } from "../coding-agents/chat-utils.js";
 import { formatForClaudeCode, formatForClaudeCodeWithChangesets, applyCopilotPermissions, CHANGESET_ONLY_ENV } from "../coding-agents/default-permissions.js";
-import { DR_ARCHITECT_AGENT, checkInstalledAgentMcpTools, drBotMcpPrompt, drMcpAllowedTools, prepareDrMcpLaunch } from "../coding-agents/drbot-mcp.js";
-import { ApiKeyManager } from "../mcp/api-key-manager.js";
+import { DR_ARCHITECT_AGENT, drBotMcpPrompt, drMcpAllowedTools, prepareDrMcpLaunch, prepareDrBotAgent } from "../coding-agents/drbot-mcp.js";
 import { getErrorMessage } from "../utils/errors.js";
 import { AnnotationCreateSchema, AnnotationUpdateSchema, AnnotationReplyCreateSchema, LayerNameSchema, IdSchema, AnnotationFilterSchema, ErrorResponseSchema, HealthResponseSchema, AnnotationSchema, AnnotationReplySchema, AnnotationsListSchema, ChangesetsListSchema, ChangesetDetailSchema, ChangesetActionResultSchema, ModelResponseSchema, LayerResponseSchema, SpecResponseSchema, AnnotationRepliesSchema, WSMessageSchema } from "./schemas.js";
 const JSONRPC_ERRORS = {
@@ -35,21 +37,37 @@ const JSONRPC_ERRORS = {
   NO_CLIENT_AVAILABLE: -32001
   // No chat client available
 };
+function annotationFingerprint(annotation) {
+  return {
+    elementId: annotation.elementId,
+    state: JSON.stringify([annotation.content, annotation.tags, annotation.resolved, annotation.updatedAt ?? null]),
+    replyIds: annotation.replies.map((reply) => reply.id)
+  };
+}
+function toolResultText(content) {
+  return typeof content == "string" ? content : Array.isArray(content) ? content.map((part) => part && typeof part == "object" && typeof part.text == "string" ? part.text : "").filter(Boolean).join(`
+`) : "";
+}
 class VisualizationServer {
   app;
   model;
-  _server;
-  // Node HTTP server returned by @hono/node-server
+  _servers = [];
+  // One per loopback address the viewer listens on
   upgradeWebSocket;
   injectWebSocket;
   clients = /* @__PURE__ */ new Set();
   watcher;
-  annotations = /* @__PURE__ */ new Map();
-  // annotationId -> annotation
-  annotationsByElement = /* @__PURE__ */ new Map();
-  // elementId -> Set<annotationId>
-  replies = /* @__PURE__ */ new Map();
-  // annotationId -> replies[]
+  /**
+   * Annotations live on disk (documentation-robotics/annotations/), shared with the MCP
+   * annotation_* tools, which run in other processes.
+   */
+  annotationStore;
+  /** What this server last saw of each annotation, to tell which changes to broadcast. */
+  annotationSnapshot = /* @__PURE__ */ new Map();
+  /** Serializes annotation writes and snapshot syncs, so a sync never sees half of a write. */
+  annotationQueue = Promise.resolve();
+  /** Pending debounced annotation sync from the file watcher. */
+  annotationsBroadcastTimer;
   changesets = /* @__PURE__ */ new Map();
   // changesetId -> changeset
   changesetStorage;
@@ -64,17 +82,35 @@ class VisualizationServer {
   activeChatProcesses = /* @__PURE__ */ new Map();
   // conversationId -> spawned chat process
   chatConversationCounter = 0;
+  /**
+   * Viewer conversation id -> Claude Code session id. The first send in a conversation starts the
+   * session with --session-id; `started` is set once Claude Code has created it, and later sends
+   * pass --resume. A new conversation id starts a new session.
+   */
+  chatSessions = /* @__PURE__ */ new Map();
+  /**
+   * Conversation id -> the running turn's token. A conversation runs one turn at a time: it is
+   * reserved when chat.send arrives and released only after that turn's process has exited.
+   */
+  busyChatConversations = /* @__PURE__ */ new Map();
+  /** Chat processes stopped by chat.cancel: nothing more from them reaches the client. */
+  cancelledChatProcesses = /* @__PURE__ */ new WeakSet();
+  /** Test hook: Claude Code's config directory (default ~/.claude or CLAUDE_CONFIG_DIR). */
+  _testClaudeConfigDir;
+  /** Pending debounced `changesets.updated` broadcast from the file watcher. */
+  changesetsBroadcastTimer;
+  /** Debounce for changeset-directory events: one write is several file events. */
+  changesetsDebounceMs = 150;
   selectedChatClient;
   // Selected chat client for server
   chatInitializationError;
   // Store initialization error for status endpoint
   _testClaudeCmdOverride;
   _testCopilotCmdOverride;
-  /** Test hook: prepare DrBot's MCP launch with these (fake key, scratch dirs) even under _testClaudeCmdOverride. */
+  /** Test hook: prepare DrBot's MCP launch with these (scratch dirs) even under _testClaudeCmdOverride. */
   _testDrMcpOptions;
   /** Test hook: the claude arguments the last chat launch built, before any _testClaudeCmdOverride. */
   _testLastClaudeChatArgs;
-  drMcpKey;
   drBotWarnings = /* @__PURE__ */ new Set();
   /**
    * Valid spec node IDs per layer
@@ -127,7 +163,7 @@ class VisualizationServer {
     }), ids;
   })();
   constructor(model, options) {
-    this.app = new OpenAPIHono(), this.model = model, this.loadWebSocketAdapter(), this.authEnabled = options?.authEnabled ?? process.env.DR_AUTH_ENABLED !== "false", this.authToken = options?.authToken || process.env.DR_AUTH_TOKEN || this.generateAuthToken(), this.withDanger = options?.withDanger || !1, this.withChangesets = options?.withChangesets || !1, this.viewerPath = options?.viewerPath || new URL("../viewer", import.meta.url).pathname, !this.authEnabled && options?.authToken && console.warn("[VisualizationServer] Warning: authToken provided but authEnabled is false. The token will be generated but not used for authentication. Set authEnabled: true to enable authentication."), this.app.use("/*", cors()), this.app.use("/*", telemetryMiddleware), this.app.use("/api/*", async (c, next) => {
+    this.app = new OpenAPIHono(), this.model = model, this.annotationStore = new AnnotationStore(model.rootPath), this.loadWebSocketAdapter(), this.authEnabled = options?.authEnabled ?? process.env.DR_AUTH_ENABLED !== "false", this.authToken = options?.authToken || process.env.DR_AUTH_TOKEN || this.generateAuthToken(), this.withDanger = options?.withDanger || !1, this.withChangesets = options?.withChangesets || !1, this.viewerPath = options?.viewerPath || new URL("../viewer", import.meta.url).pathname, !this.authEnabled && options?.authToken && console.warn("[VisualizationServer] Warning: authToken provided but authEnabled is false. The token will be generated but not used for authentication. Set authEnabled: true to enable authentication."), this.app.use("/*", cors()), this.app.use("/*", telemetryMiddleware), this.app.use("/api/*", async (c, next) => {
       if (!this.authEnabled)
         return next();
       const authHeader = c.req.header("Authorization"), queryToken = c.req.query("token");
@@ -172,21 +208,79 @@ class VisualizationServer {
    * Performs partial updates with atomic operations
    */
   async updateAnnotation(annotationId, body) {
-    const annotation = this.annotations.get(annotationId);
-    if (!annotation)
-      return null;
-    const updatedAnnotation = {
-      ...annotation,
-      content: body.content ?? annotation.content,
-      tags: body.tags ?? annotation.tags,
-      resolved: body.resolved ?? annotation.resolved,
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    return this.annotations.set(annotationId, updatedAnnotation), await this.broadcastMessage({
+    const { updated, messages } = await this.withAnnotations(async () => {
+      const updated2 = await this.annotationStore.update(annotationId, body);
+      return { updated: updated2, messages: updated2 ? this.diffAnnotation(updated2) : [] };
+    });
+    return updated ? (await this.broadcastAll(messages), updated) : null;
+  }
+  /** Broadcasts each message, in order. */
+  async broadcastAll(messages) {
+    for (const message of messages)
+      await this.broadcastMessage(message);
+  }
+  /** Runs an annotation write or sync after the ones queued before it. */
+  withAnnotations(fn) {
+    const run = this.annotationQueue.then(fn, fn);
+    return this.annotationQueue = run.catch(() => {
+    }), run;
+  }
+  /**
+   * Records an annotation as seen and returns a broadcast for each difference from what this
+   * server last saw of it: the change a route just made, and any change another process made
+   * that the watcher has not synced yet (so recording it as seen doesn't swallow that change).
+   * Call it inside withAnnotations.
+   */
+  diffAnnotation(annotation) {
+    const before = this.annotationSnapshot.get(annotation.id), after = annotationFingerprint(annotation);
+    if (this.annotationSnapshot.set(annotation.id, after), !before)
+      return [
+        {
+          type: "annotation.added",
+          annotationId: annotation.id,
+          elementId: annotation.elementId,
+          timestamp: annotation.createdAt
+        }
+      ];
+    const out = [];
+    before.state !== after.state && out.push({
       type: "annotation.updated",
-      annotationId: updatedAnnotation.id,
-      timestamp: updatedAnnotation.updatedAt
-    }), updatedAnnotation;
+      annotationId: annotation.id,
+      timestamp: annotation.updatedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+    for (const reply of annotation.replies)
+      before.replyIds.includes(reply.id) || out.push({
+        type: "annotation.reply.added",
+        annotationId: annotation.id,
+        replyId: reply.id,
+        timestamp: reply.createdAt
+      });
+    return out;
+  }
+  /**
+   * Compares the annotation files with what this server last saw, and broadcasts each change
+   * another process made (the MCP annotation tools, a hand edit) with the same messages the
+   * REST routes send: annotation.added, annotation.updated, annotation.reply.added and
+   * annotation.deleted.
+   */
+  async syncAnnotations(options) {
+    const messages = await this.withAnnotations(async () => {
+      const current = await this.annotationStore.list(), now = (/* @__PURE__ */ new Date()).toISOString(), out = [], seen = /* @__PURE__ */ new Set();
+      for (const annotation of current)
+        seen.add(annotation.id), out.push(...this.diffAnnotation(annotation));
+      for (const id of [...this.annotationSnapshot.keys()])
+        seen.has(id) || (this.annotationSnapshot.delete(id), out.push({ type: "annotation.deleted", annotationId: id, timestamp: now }));
+      return out;
+    });
+    options.broadcast && await this.broadcastAll(messages);
+  }
+  /** Syncs the annotations once their files have been quiet for a moment. */
+  scheduleAnnotationsSync() {
+    this.annotationsBroadcastTimer && clearTimeout(this.annotationsBroadcastTimer), this.annotationsBroadcastTimer = setTimeout(() => {
+      this.annotationsBroadcastTimer = void 0, this.syncAnnotations({ broadcast: !0 }).catch((error) => {
+        console.error(`[Watcher] Failed to broadcast annotations: ${getErrorMessage(error)}`);
+      });
+    }, this.changesetsDebounceMs);
   }
   /**
    * Setup HTTP routes and WebSocket handler
@@ -379,14 +473,12 @@ class VisualizationServer {
         }
       }
     });
-    this.app.openapi(getAnnotationsRoute, (c) => {
-      const elementId = c.req.valid("query").elementId;
-      if (elementId) {
-        const annotationIds = this.annotationsByElement.get(elementId) || /* @__PURE__ */ new Set(), annotations = Array.from(annotationIds).map((id) => this.annotations.get(id)).filter((a) => a !== void 0);
-        return c.json({ annotations });
-      } else {
-        const annotations = Array.from(this.annotations.values());
+    this.app.openapi(getAnnotationsRoute, async (c) => {
+      try {
+        const query = c.req.valid("query"), annotations = await this.annotationStore.list(query.elementId);
         return c.json({ annotations });
+      } catch (error) {
+        return c.json({ error: getErrorMessage(error) }, 500);
       }
     });
     const createAnnotationRoute = createRoute({
@@ -443,24 +535,18 @@ class VisualizationServer {
     this.app.openapi(createAnnotationRoute, async (c) => {
       try {
         const body = c.req.valid("json");
-        if (!await this.findElement(body.elementId))
+        if (!await this.elementExists(body.elementId))
           return c.json({ error: "Element not found" }, 404);
-        const annotation = {
-          id: this.generateAnnotationId(),
-          elementId: body.elementId,
-          author: body.author,
-          content: body.content,
-          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-          tags: body.tags,
-          resolved: !1
-          // Default to unresolved
-        };
-        return this.annotations.set(annotation.id, annotation), this.annotationsByElement.has(annotation.elementId) || this.annotationsByElement.set(annotation.elementId, /* @__PURE__ */ new Set()), this.annotationsByElement.get(annotation.elementId).add(annotation.id), await this.broadcastMessage({
-          type: "annotation.added",
-          annotationId: annotation.id,
-          elementId: annotation.elementId,
-          timestamp: annotation.createdAt
-        }), c.json(annotation, 201);
+        const { annotation, messages } = await this.withAnnotations(async () => {
+          const created = await this.annotationStore.create({
+            elementId: body.elementId,
+            author: body.author,
+            content: body.content,
+            tags: body.tags
+          });
+          return { annotation: created, messages: this.diffAnnotation(created) };
+        });
+        return await this.broadcastAll(messages), c.json(annotation, 201);
       } catch (error) {
         const message = getErrorMessage(error);
         return c.json({ error: message }, 500);
@@ -505,7 +591,7 @@ class VisualizationServer {
     });
     this.app.openapi(getAnnotationRoute, async (c) => {
       try {
-        const { annotationId } = c.req.valid("param"), annotation = this.annotations.get(annotationId);
+        const { annotationId } = c.req.valid("param"), annotation = await this.annotationStore.get(annotationId);
         return annotation ? c.json(annotation) : c.json({ error: "Annotation not found" }, 404);
       } catch (error) {
         const message = getErrorMessage(error);
@@ -652,16 +738,15 @@ class VisualizationServer {
     });
     this.app.openapi(deleteAnnotationRoute, async (c) => {
       try {
-        const { annotationId } = c.req.valid("param"), annotation = this.annotations.get(annotationId);
-        if (!annotation)
-          return c.json({ error: "Annotation not found" }, 404);
-        this.annotations.delete(annotationId), this.replies.delete(annotationId);
-        const elementAnnotations = this.annotationsByElement.get(annotation.elementId);
-        return elementAnnotations && elementAnnotations.delete(annotationId), await this.broadcastMessage({
+        const { annotationId } = c.req.valid("param");
+        return await this.withAnnotations(async () => {
+          const existed = await this.annotationStore.delete(annotationId);
+          return this.annotationSnapshot.delete(annotationId), existed;
+        }) ? (await this.broadcastMessage({
           type: "annotation.deleted",
           annotationId,
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
-        }), c.body(null, 204);
+        }), c.body(null, 204)) : c.json({ error: "Annotation not found" }, 404);
       } catch (error) {
         const message = getErrorMessage(error);
         return c.json({ error: message }, 500);
@@ -696,12 +781,13 @@ class VisualizationServer {
         }
       }
     });
-    this.app.openapi(getAnnotationRepliesRoute, (c) => {
-      const { annotationId } = c.req.valid("param");
-      if (!this.annotations.get(annotationId))
-        return c.json({ error: "Annotation not found" }, 404);
-      const replies = this.replies.get(annotationId) || [];
-      return c.json({ replies });
+    this.app.openapi(getAnnotationRepliesRoute, async (c) => {
+      try {
+        const { annotationId } = c.req.valid("param"), annotation = await this.annotationStore.get(annotationId);
+        return annotation ? c.json({ replies: annotation.replies }) : c.json({ error: "Annotation not found" }, 404);
+      } catch (error) {
+        return c.json({ error: getErrorMessage(error) }, 500);
+      }
     });
     const createAnnotationReplyRoute = createRoute({
       method: "post",
@@ -749,21 +835,22 @@ class VisualizationServer {
     });
     this.app.openapi(createAnnotationReplyRoute, async (c) => {
       try {
-        const { annotationId } = c.req.valid("param");
-        if (!this.annotations.get(annotationId))
-          return c.json({ error: "Annotation not found" }, 404);
-        const body = c.req.valid("json"), reply = {
-          id: this.generateReplyId(),
-          author: body.author,
-          content: body.content,
-          createdAt: (/* @__PURE__ */ new Date()).toISOString()
-        };
-        return this.replies.has(annotationId) || this.replies.set(annotationId, []), this.replies.get(annotationId).push(reply), await this.broadcastMessage({
-          type: "annotation.reply.added",
-          annotationId,
-          replyId: reply.id,
-          timestamp: reply.createdAt
-        }), c.json(reply, 201);
+        const { annotationId } = c.req.valid("param"), body = c.req.valid("json"), { reply, messages } = await this.withAnnotations(async () => {
+          const added = await this.annotationStore.addReply(annotationId, {
+            author: body.author,
+            content: body.content
+          });
+          if (!added)
+            return { reply: null, messages: [] };
+          const annotation = await this.annotationStore.get(annotationId), own = {
+            type: "annotation.reply.added",
+            annotationId,
+            replyId: added.id,
+            timestamp: added.createdAt
+          };
+          return { reply: added, messages: annotation ? this.diffAnnotation(annotation) : [own] };
+        });
+        return reply ? (await this.broadcastAll(messages), c.json(reply, 201)) : c.json({ error: "Annotation not found" }, 404);
       } catch (error) {
         const message = getErrorMessage(error);
         return c.json({ error: message }, 500);
@@ -1126,20 +1213,6 @@ class VisualizationServer {
     }
     return layer in VisualizationServer.LAYER_FALLBACK ? VisualizationServer.LAYER_FALLBACK[layer] : "data-store.database";
   }
-  /**
-   * Generate unique annotation ID
-   * Uses cryptographically secure random bytes for collision-resistant IDs
-   */
-  generateAnnotationId() {
-    return `ann-${Date.now()}-${randomBytes(4).toString("hex")}`;
-  }
-  /**
-   * Generate unique reply ID
-   * Uses cryptographically secure random bytes for collision-resistant IDs
-   */
-  generateReplyId() {
-    return `reply-${Date.now()}-${randomBytes(4).toString("hex")}`;
-  }
   /**
    * Broadcast message to all connected WebSocket clients
    */
@@ -1195,6 +1268,20 @@ class VisualizationServer {
     }
     return null;
   }
+  /**
+   * Whether an element can be annotated: it is in the model, or a changeset that is still open
+   * (staged, not committed or discarded) adds it. A reviewer comments mostly on what the plan
+   * adds, so those count too.
+   */
+  async elementExists(id) {
+    if (await this.findElement(id))
+      return !0;
+    await this.loadChangesetsFromDisk();
+    for (const changeset of this.changesets.values())
+      if (changeset.status === "staged" && changeset.changes.some((change) => change.type === "add" && change.elementId === id))
+        return !0;
+    return !1;
+  }
   /**
    * Handle WebSocket messages
    */
@@ -1276,14 +1363,32 @@ class VisualizationServer {
             sendError(JSONRPC_ERRORS.NO_CLIENT_AVAILABLE, "No chat client available. Install Claude Code or GitHub Copilot to enable chat.");
             return;
           }
-          const conversationId = `conv-${++this.chatConversationCounter}-${Date.now()}`;
-          await this.launchChat(ws, conversationId, params.message, id);
+          const clientConversationId = params.conversation_id;
+          if (clientConversationId !== void 0 && (typeof clientConversationId != "string" || clientConversationId.trim() === "" || clientConversationId.length > 200)) {
+            sendError(JSONRPC_ERRORS.INVALID_PARAMS, "conversation_id must be a non-empty string of at most 200 characters");
+            return;
+          }
+          const conversationId = clientConversationId ?? `conv-${++this.chatConversationCounter}-${Date.now()}`;
+          if (this.busyChatConversations.has(conversationId)) {
+            sendError(JSONRPC_ERRORS.INVALID_PARAMS, "A reply is still running in this conversation; wait for it or cancel it first");
+            return;
+          }
+          const turn = this.reserveChatConversation(conversationId);
+          try {
+            await this.launchChat(ws, conversationId, params.message, id, {
+              resumable: clientConversationId !== void 0,
+              turn
+            });
+          } catch (error) {
+            throw this.releaseChatConversation(conversationId, turn), error;
+          }
           break;
         case "chat.cancel":
           let cancelled = !1, cancelledConvId = null;
-          for (const [convId, process2] of this.activeChatProcesses)
+          const cancelConvId = params?.conversation_id, cancelCandidates = [...this.activeChatProcesses].filter(([convId, proc]) => !this.cancelledChatProcesses.has(proc) && (typeof cancelConvId != "string" || convId === cancelConvId));
+          for (const [convId, process2] of cancelCandidates)
             try {
-              process2.kill(), this.activeChatProcesses.delete(convId), cancelled = !0, cancelledConvId = convId;
+              this.cancelledChatProcesses.add(process2), process2.kill(), cancelled = !0, cancelledConvId = convId;
               break;
             } catch (error) {
               console.warn(`[Chat] Failed to cancel process for conversation ${convId}: ${getErrorMessage(error)}`);
@@ -1304,9 +1409,9 @@ class VisualizationServer {
   /**
    * Launch chat with selected client and stream responses via WebSocket
    */
-  async launchChat(ws, conversationId, message, requestId) {
+  async launchChat(ws, conversationId, message, requestId, options = {}) {
     if (!this.selectedChatClient) {
-      ws.send(JSON.stringify({
+      options.turn && this.releaseChatConversation(conversationId, options.turn), ws.send(JSON.stringify({
         jsonrpc: "2.0",
         error: {
           code: JSONRPC_ERRORS.NO_CLIENT_AVAILABLE,
@@ -1316,50 +1421,103 @@ class VisualizationServer {
       }));
       return;
     }
-    this.selectedChatClient instanceof ClaudeCodeClient ? await this.launchClaudeCodeChat(ws, conversationId, message, requestId) : this.selectedChatClient instanceof CopilotClient ? await this.launchCopilotChat(ws, conversationId, message, requestId) : ws.send(JSON.stringify({
+    this.selectedChatClient instanceof ClaudeCodeClient ? await this.launchClaudeCodeChat(ws, conversationId, message, requestId, options) : this.selectedChatClient instanceof CopilotClient ? await this.launchCopilotChat(ws, conversationId, message, requestId, options) : (options.turn && this.releaseChatConversation(conversationId, options.turn), ws.send(JSON.stringify({
       jsonrpc: "2.0",
       error: {
         code: JSONRPC_ERRORS.NO_CLIENT_AVAILABLE,
         message: "Unknown chat client type"
       },
       id: requestId
-    }));
+    })));
   }
   /**
    * Build command arguments for Claude Code launch
    */
-  buildClaudeChatArgs(mcpConfigPath) {
-    const cmd = ["claude", "--agent", "dr-architect", "--print"], mode = this.drBotMode(), mcpRules = mcpConfigPath ? drMcpAllowedTools(mode) : [];
+  buildClaudeChatArgs(mcpConfigPath, session, agentArgs = []) {
+    const cmd = ["claude", "--agent", DR_ARCHITECT_AGENT, ...agentArgs, "--print"], mode = this.drBotMode(), mcpRules = mcpConfigPath ? drMcpAllowedTools(mode) : [];
     if (mode === "danger")
       cmd.push("--dangerously-skip-permissions");
     else {
       const bashRules = mode === "changesets" ? formatForClaudeCodeWithChangesets() : formatForClaudeCode();
       cmd.push("--allowedTools", [bashRules, ...mcpRules].join(","));
     }
-    return mcpConfigPath && cmd.push("--mcp-config", mcpConfigPath, "--append-system-prompt", drBotMcpPrompt(mode)), cmd.push("--verbose", "--output-format", "stream-json"), cmd;
+    return mcpConfigPath && cmd.push("--mcp-config", mcpConfigPath, "--append-system-prompt", drBotMcpPrompt(mode)), session && cmd.push(session.started ? "--resume" : "--session-id", session.sessionId), cmd.push("--verbose", "--output-format", "stream-json"), cmd;
+  }
+  /**
+   * The Claude Code session for a viewer conversation, created on its first send. A send
+   * without a conversation id gets none, so it runs in a fresh session as before.
+   */
+  chatSessionFor(conversationId, resumable) {
+    if (!resumable)
+      return;
+    let session = this.chatSessions.get(conversationId);
+    return session || (session = { sessionId: randomUUID(), started: !1 }, this.chatSessions.set(conversationId, session)), session;
+  }
+  /** Marks a conversation busy for one turn; the token releases it. */
+  reserveChatConversation(conversationId) {
+    const turn = Symbol(conversationId);
+    return this.busyChatConversations.set(conversationId, turn), turn;
+  }
+  /** Ends a turn's hold on its conversation. A stale token (an older turn) releases nothing. */
+  releaseChatConversation(conversationId, turn) {
+    this.busyChatConversations.get(conversationId) === turn && this.busyChatConversations.delete(conversationId);
+  }
+  /** Drops a turn's process from activeChatProcesses, unless a newer turn's has replaced it. */
+  forgetChatProcess(conversationId, proc) {
+    this.activeChatProcesses.get(conversationId) === proc && this.activeChatProcesses.delete(conversationId);
+  }
+  /**
+   * Whether Claude Code already has this session on disk
+   * (`<config dir>/projects/<cwd with non-alphanumerics as "-">/<id>.jsonl`). A first send that
+   * died before the server saw it start can still have created it, and --session-id would then
+   * fail with "already in use".
+   */
+  claudeSessionExists(sessionId) {
+    const configDir = this._testClaudeConfigDir ?? process.env.CLAUDE_CONFIG_DIR ?? path.join(homedir(), ".claude"), roots = /* @__PURE__ */ new Set([this.model.rootPath]);
+    try {
+      roots.add(realpathSync(this.model.rootPath));
+    } catch {
+    }
+    for (const root of roots) {
+      const projectDir = root.replace(/[^a-zA-Z0-9]/g, "-");
+      if (existsSync(path.join(configDir, "projects", projectDir, `${sessionId}.jsonl`)))
+        return !0;
+    }
+    return !1;
   }
   /** DrBot's permission mode; danger wins over changeset-only. */
   drBotMode() {
     return this.withDanger ? "danger" : this.withChangesets ? "changesets" : "read-safe";
   }
   /**
-   * Writes the MCP config that connects DrBot to `dr mcp` for this model. Returns null when it
-   * can't (logged): DrBot then launches without MCP and uses its Bash rules.
+   * Resolves the dr-architect DrBot runs, once: the extra launch arguments (--agents for the
+   * bundled copy) and the check of its tools both come from this lookup.
    */
-  async prepareDrBotMcp() {
-    const mode = this.drBotMode(), overrides = this._testDrMcpOptions ?? {};
+  async resolveDrBotAgentLaunch() {
+    const overrides = this._testDrMcpOptions ?? {};
     try {
-      const check = await checkInstalledAgentMcpTools(this.model.rootPath, mode, overrides.homeDir);
-      if (check && (this.warnDrBotOnce(check.noneVisible ? `[Claude Code] The installed ${DR_ARCHITECT_AGENT} agent (${check.path}) predates the dr MCP tools, so the chat can't use them and falls back to Bash dr commands. Run \`dr claude upgrade\` to update it.` : `[Claude Code] The installed ${DR_ARCHITECT_AGENT} agent (${check.path}) doesn't list ${check.missing.join(", ")}, so the chat can't use those dr MCP tools. Run \`dr claude upgrade\` to update it.`), check.noneVisible))
-        return null;
+      return await prepareDrBotAgent(this.model.rootPath, this.drBotMode(), {
+        homeDir: overrides.homeDir,
+        env: overrides.env,
+        bundledPath: overrides.bundledPath
+      });
     } catch (error) {
-      this.warnDrBotOnce(`[Claude Code] Could not check the installed ${DR_ARCHITECT_AGENT} agent's tools (${getErrorMessage(error)}); connecting the dr MCP server anyway.`);
+      return this.warnDrBotOnce(`[Claude Code] Could not check the installed ${DR_ARCHITECT_AGENT} agent's tools (${getErrorMessage(error)}); connecting the dr MCP server anyway.`), { agent: null, args: [], check: null };
     }
+  }
+  /**
+   * Writes the MCP config that connects DrBot to `dr mcp` for this model. Returns null when it
+   * can't (logged), or when the agent DrBot runs can't see the dr tools: DrBot then launches
+   * without MCP and uses its Bash rules.
+   */
+  async prepareDrBotMcp(check) {
+    const mode = this.drBotMode(), overrides = this._testDrMcpOptions ?? {};
+    if (check && (this.warnDrBotOnce(check.error ? `[Claude Code] Could not pass the bundled ${DR_ARCHITECT_AGENT} agent (${check.path}: ${check.error}), so the chat may run one that can't see the dr MCP tools; it falls back to Bash dr commands.` : check.noneVisible ? `[Claude Code] The installed ${DR_ARCHITECT_AGENT} agent (${check.path}) predates the dr MCP tools, so the chat can't use them and falls back to Bash dr commands. Run \`dr claude upgrade\` to update it.` : `[Claude Code] The installed ${DR_ARCHITECT_AGENT} agent (${check.path}) doesn't list ${check.missing.join(", ")}, so the chat can't use those dr MCP tools. Run \`dr claude upgrade\` to update it.`), check.noneVisible))
+      return null;
     try {
       return await prepareDrMcpLaunch({
         rootPath: this.model.rootPath,
         changesetOnly: mode === "changesets",
-        keyManager: { ensureKey: () => this.ensureDrMcpKey() },
         drCommand: overrides.drCommand,
         tempRoot: overrides.tempRoot
       });
@@ -1367,23 +1525,6 @@ class VisualizationServer {
       return console.warn(`[Claude Code] dr MCP server unavailable for chat, falling back to Bash dr commands: ${getErrorMessage(error)}`), null;
     }
   }
-  /**
-   * The installation's MCP API key. Concurrent chat launches share one in-flight ensureKey call,
-   * so a first-time key is created once rather than raced and overwritten (which would leave an
-   * earlier launch's MCP server holding a key that no longer matches). Once it settles the next
-   * launch reads the key afresh, so a key rotated with `dr mcp --regenerate-key` is picked up.
-   */
-  ensureDrMcpKey() {
-    if (!this.drMcpKey) {
-      const pending = (this._testDrMcpOptions?.keyManager ?? new ApiKeyManager()).ensureKey();
-      this.drMcpKey = pending;
-      const clear = () => {
-        this.drMcpKey === pending && (this.drMcpKey = void 0);
-      };
-      pending.then(clear, clear);
-    }
-    return this.drMcpKey;
-  }
   /** Logs a DrBot setup warning once per server rather than on every chat message. */
   warnDrBotOnce(message) {
     this.drBotWarnings.has(message) || (this.drBotWarnings.add(message), console.warn(message));
@@ -1410,11 +1551,15 @@ class VisualizationServer {
   /**
    * Launch Claude Code CLI with dr-architect agent and stream responses
    */
-  async launchClaudeCodeChat(ws, conversationId, message, requestId) {
+  async launchClaudeCodeChat(ws, conversationId, message, requestId, options = {}) {
     let drMcp = null;
+    const session = this.chatSessionFor(conversationId, options.resumable === !0), turnToken = options.turn ?? this.reserveChatConversation(conversationId), release = () => this.releaseChatConversation(conversationId, turnToken);
     try {
-      drMcp = this._testClaudeCmdOverride !== void 0 && this._testDrMcpOptions === void 0 ? null : await this.prepareDrBotMcp();
-      const cmd = this.buildClaudeChatArgs(drMcp?.configPath);
+      const agent = this._testClaudeCmdOverride !== void 0 && this._testDrMcpOptions === void 0 ? null : await this.resolveDrBotAgentLaunch();
+      drMcp = agent ? await this.prepareDrBotMcp(agent.check) : null, session && !session.started && session.attempted && this.claudeSessionExists(session.sessionId) && (session.started = !0);
+      const usedSessionIdFlag = session !== void 0 && !session.started;
+      session && usedSessionIdFlag && (session.attempted = !0);
+      const cmd = this.buildClaudeChatArgs(drMcp?.configPath, session, agent?.args ?? []);
       this._testLastClaudeChatArgs = [...cmd], this._testClaudeCmdOverride && cmd.splice(0, cmd.length, ...this._testClaudeCmdOverride);
       const proc = spawn(cmd[0], cmd.slice(1), {
         cwd: this.model.rootPath,
@@ -1427,7 +1572,7 @@ class VisualizationServer {
       }
       proc.on("error", (err) => {
         const errorMsg = getErrorMessage(err);
-        console.error(`[Claude Code] Failed to spawn subprocess for conversation ${conversationId}: ${errorMsg}`), this.activeChatProcesses.delete(conversationId);
+        console.error(`[Claude Code] Failed to spawn subprocess for conversation ${conversationId}: ${errorMsg}`), this.forgetChatProcess(conversationId, proc), release();
         try {
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
@@ -1441,10 +1586,35 @@ class VisualizationServer {
           console.error(`[Claude Code] Failed to send spawn-error notification: ${getErrorMessage(sendError)}`);
         }
       }), proc.stdin?.on("error", () => {
-      }), this.activeChatProcesses.set(conversationId, proc), proc.stdin?.write(message), proc.stdin?.end();
+      });
+      let stderrTail = "";
+      proc.stderr?.on("data", (data) => {
+        stderrTail = (stderrTail + data.toString()).slice(-4096);
+      }), this.activeChatProcesses.set(conversationId, proc);
+      const isCancelled = () => this.cancelledChatProcesses.has(proc);
+      proc.stdin?.write(message), proc.stdin?.end();
       const decoder = new TextDecoder();
       (async () => {
-        let accumulatedText = "", buffer = "";
+        const turn = { accumulatedText: "", pendingTools: /* @__PURE__ */ new Map(), session, sawEvent: !1 };
+        let buffer = "";
+        const handleLine = (line, isLast) => {
+          if (isCancelled())
+            return;
+          let event;
+          try {
+            event = JSON.parse(line);
+          } catch (parseError) {
+            process.env.DEBUG && console.debug(`[Chat] Failed to parse JSON chunk: ${getErrorMessage(parseError)}`), this.sendChatNotification(ws, "chat.response.chunk", {
+              conversation_id: conversationId,
+              content: isLast ? line : line + `
+`,
+              is_final: isLast,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            });
+            return;
+          }
+          turn.sawEvent = !0, this.handleClaudeStreamEvent(ws, conversationId, event, turn);
+        };
         try {
           for await (const chunkBuf of proc.stdout) {
             const chunk = decoder.decode(chunkBuf, { stream: !0 });
@@ -1453,79 +1623,34 @@ class VisualizationServer {
 `);
             buffer = lines.pop() || "";
             for (const line of lines)
-              if (line.trim())
-                try {
-                  const event = JSON.parse(line);
-                  if (event.type === "assistant") {
-                    const content = event.message?.content || [];
-                    for (const block of content)
-                      block.type === "text" ? (accumulatedText += block.text, ws.send(JSON.stringify({
-                        jsonrpc: "2.0",
-                        method: "chat.response.chunk",
-                        params: {
-                          conversation_id: conversationId,
-                          content: block.text,
-                          is_final: !1,
-                          timestamp: (/* @__PURE__ */ new Date()).toISOString()
-                        }
-                      }))) : block.type === "tool_use" && ws.send(JSON.stringify({
-                        jsonrpc: "2.0",
-                        method: "chat.tool.invoke",
-                        params: {
-                          conversation_id: conversationId,
-                          tool_name: block.name,
-                          tool_input: block.input,
-                          timestamp: (/* @__PURE__ */ new Date()).toISOString()
-                        }
-                      }));
-                  } else event.type === "result" && ws.send(JSON.stringify({
-                    jsonrpc: "2.0",
-                    method: "chat.tool.result",
-                    params: {
-                      conversation_id: conversationId,
-                      result: event.result,
-                      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-                    }
-                  }));
-                } catch (parseError) {
-                  process.env.DEBUG && console.debug(`[Chat] Failed to parse JSON chunk: ${getErrorMessage(parseError)}`), ws.send(JSON.stringify({
-                    jsonrpc: "2.0",
-                    method: "chat.response.chunk",
-                    params: {
-                      conversation_id: conversationId,
-                      content: line + `
-`,
-                      is_final: !1,
-                      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-                    }
-                  }));
-                }
+              line.trim() && handleLine(line, !1);
           }
-          buffer.trim() && ws.send(JSON.stringify({
-            jsonrpc: "2.0",
-            method: "chat.response.chunk",
-            params: {
-              conversation_id: conversationId,
-              content: buffer,
-              is_final: !0,
-              timestamp: (/* @__PURE__ */ new Date()).toISOString()
-            }
-          }));
+          buffer.trim() && handleLine(buffer, !0);
           const exitCode = await this.waitForExit(proc);
-          this.activeChatProcesses.delete(conversationId), ws.send(JSON.stringify({
+          if (this.forgetChatProcess(conversationId, proc), session && exitCode === 0 && (session.started = !0), session && usedSessionIdFlag && !options.retried && !isCancelled() && exitCode !== 0 && !turn.sawEvent && /already in use/i.test(stderrTail)) {
+            session.started = !0, await this.launchClaudeCodeChat(ws, conversationId, message, requestId, {
+              ...options,
+              turn: turnToken,
+              retried: !0
+            });
+            return;
+          }
+          isCancelled() || this.failPendingTools(ws, conversationId, turn, "The tool reported no result before the reply ended"), release(), ws.send(JSON.stringify({
             jsonrpc: "2.0",
             result: {
               conversation_id: conversationId,
               status: exitCode === 0 ? "complete" : "error",
               exit_code: exitCode,
-              full_response: accumulatedText,
+              full_response: turn.accumulatedText,
               timestamp: (/* @__PURE__ */ new Date()).toISOString()
             },
             id: requestId
           }));
         } catch (error) {
-          if (!proc.pid)
+          if (!proc.pid) {
+            release();
             return;
+          }
           const errorMsg = getErrorMessage(error);
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
@@ -1534,16 +1659,18 @@ class VisualizationServer {
               message: `Chat failed: ${errorMsg}`
             },
             id: requestId
-          })), this.activeChatProcesses.delete(conversationId);
+          })), this.forgetChatProcess(conversationId, proc);
           try {
             await this.killProcessWithRetry(proc, conversationId, "Claude Code");
           } catch (error2) {
             console.error(`[Claude Code] Failed to kill process for conversation ${conversationId}: ${getErrorMessage(error2)}`);
+          } finally {
+            release();
           }
         }
       })().catch((err) => {
         const errorMsg = getErrorMessage(err);
-        console.error(`[Claude Code] Stream error: ${errorMsg}`);
+        console.error(`[Claude Code] Stream error: ${errorMsg}`), release();
         try {
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
@@ -1558,7 +1685,7 @@ class VisualizationServer {
         }
       });
     } catch (error) {
-      drMcp?.cleanup();
+      drMcp?.cleanup(), release();
       const errorMsg = getErrorMessage(error);
       ws.send(JSON.stringify({
         jsonrpc: "2.0",
@@ -1570,10 +1697,77 @@ class VisualizationServer {
       }));
     }
   }
+  /** Sends a JSON-RPC notification to one chat client. */
+  sendChatNotification(ws, method, params) {
+    ws.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
+  }
+  /**
+   * Turns one Claude Code stream-json event into the chat notifications the viewer reads:
+   * - assistant text -> `chat.response.chunk`
+   * - assistant tool_use -> `chat.tool.invoke` with `status: "executing"`
+   * - user tool_result -> `chat.tool.invoke` again, same `tool_use_id`, `completed` or `failed`
+   * - result (end of the turn) -> `chat.response.complete`
+   */
+  handleClaudeStreamEvent(ws, conversationId, event, turn) {
+    if (turn.session && typeof event?.session_id == "string" && (turn.session.started = !0), event?.type === "assistant") {
+      const content = Array.isArray(event.message?.content) ? event.message.content : [];
+      for (const block of content)
+        block?.type === "text" ? (turn.accumulatedText += block.text, this.sendChatNotification(ws, "chat.response.chunk", {
+          conversation_id: conversationId,
+          content: block.text,
+          is_final: !1,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })) : block?.type === "tool_use" && (typeof block.id == "string" && turn.pendingTools.set(block.id, { name: block.name, input: block.input }), this.sendChatNotification(ws, "chat.tool.invoke", {
+          conversation_id: conversationId,
+          tool_use_id: block.id,
+          tool_name: block.name,
+          tool_input: block.input,
+          status: "executing",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
+    } else if (event?.type === "user") {
+      const content = Array.isArray(event.message?.content) ? event.message.content : [];
+      for (const block of content)
+        block?.type !== "tool_result" || typeof block.tool_use_id != "string" || this.sendToolOutcome(ws, conversationId, turn, block.tool_use_id, block.is_error === !0, block.content);
+    } else if (event?.type === "result") {
+      const denials = Array.isArray(event.permission_denials) ? event.permission_denials : [];
+      for (const denial of denials) {
+        const id = denial?.tool_use_id;
+        typeof id == "string" && turn.pendingTools.has(id) && this.sendToolOutcome(ws, conversationId, turn, id, !0, `Permission denied: ${denial.tool_name ?? "tool"}`);
+      }
+      this.sendChatNotification(ws, "chat.response.complete", {
+        conversation_id: conversationId,
+        result: event.result,
+        is_error: event.is_error === !0,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+  }
+  /** Sends a tool's final `chat.tool.invoke` (completed or failed) and stops tracking it. */
+  sendToolOutcome(ws, conversationId, turn, toolUseId, isError, result) {
+    const tool = turn.pendingTools.get(toolUseId);
+    turn.pendingTools.delete(toolUseId), this.sendChatNotification(ws, "chat.tool.invoke", {
+      conversation_id: conversationId,
+      tool_use_id: toolUseId,
+      tool_name: tool?.name,
+      tool_input: tool?.input,
+      status: isError ? "failed" : "completed",
+      is_error: isError,
+      result,
+      ...isError ? { error: toolResultText(result) || "Tool call failed" } : {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  /** Reports every tool still waiting for a result as failed. */
+  failPendingTools(ws, conversationId, turn, reason) {
+    for (const toolUseId of [...turn.pendingTools.keys()])
+      this.sendToolOutcome(ws, conversationId, turn, toolUseId, !0, reason);
+  }
   /**
    * Launch GitHub Copilot CLI and stream responses via WebSocket
    */
-  async launchCopilotChat(ws, conversationId, message, requestId) {
+  async launchCopilotChat(ws, conversationId, message, requestId, options = {}) {
+    const turnToken = options.turn ?? this.reserveChatConversation(conversationId), release = () => this.releaseChatConversation(conversationId, turnToken);
     try {
       let cmd;
       if (this._testCopilotCmdOverride)
@@ -1590,7 +1784,7 @@ class VisualizationServer {
       });
       proc.on("error", (err) => {
         const errorMsg = getErrorMessage(err);
-        console.error(`[Copilot] Failed to spawn subprocess for conversation ${conversationId}: ${errorMsg}`), this.activeChatProcesses.delete(conversationId);
+        console.error(`[Copilot] Failed to spawn subprocess for conversation ${conversationId}: ${errorMsg}`), this.forgetChatProcess(conversationId, proc), release();
         try {
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
@@ -1611,7 +1805,7 @@ class VisualizationServer {
         try {
           for await (const chunkBuf of proc.stdout) {
             const chunk = decoder.decode(chunkBuf, { stream: !0 });
-            accumulatedText += chunk, ws.send(JSON.stringify({
+            accumulatedText += chunk, !this.cancelledChatProcesses.has(proc) && ws.send(JSON.stringify({
               jsonrpc: "2.0",
               method: "chat.response.chunk",
               params: {
@@ -1623,7 +1817,7 @@ class VisualizationServer {
             }));
           }
           const exitCode = await this.waitForExit(proc);
-          this.activeChatProcesses.delete(conversationId), ws.send(JSON.stringify({
+          this.forgetChatProcess(conversationId, proc), release(), ws.send(JSON.stringify({
             jsonrpc: "2.0",
             result: {
               conversation_id: conversationId,
@@ -1635,8 +1829,10 @@ class VisualizationServer {
             id: requestId
           }));
         } catch (error) {
-          if (!proc.pid)
+          if (!proc.pid) {
+            release();
             return;
+          }
           const errorMsg = getErrorMessage(error);
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
@@ -1645,16 +1841,18 @@ class VisualizationServer {
               message: `Chat failed: ${errorMsg}`
             },
             id: requestId
-          })), this.activeChatProcesses.delete(conversationId);
+          })), this.forgetChatProcess(conversationId, proc);
           try {
             await this.killProcessWithRetry(proc, conversationId, "Copilot");
           } catch (error2) {
             console.error(`[Copilot] Failed to kill process for conversation ${conversationId}: ${getErrorMessage(error2)}`);
+          } finally {
+            release();
           }
         }
       })().catch((err) => {
         const errorMsg = getErrorMessage(err);
-        console.error(`[Copilot] Stream error: ${errorMsg}`);
+        console.error(`[Copilot] Stream error: ${errorMsg}`), release();
         try {
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
@@ -1669,6 +1867,7 @@ class VisualizationServer {
         }
       });
     } catch (error) {
+      release();
       const errorMsg = getErrorMessage(error);
       ws.send(JSON.stringify({
         jsonrpc: "2.0",
@@ -1681,28 +1880,67 @@ class VisualizationServer {
     }
   }
   /**
-   * Setup file watcher for model changes
+   * Watch the model and the changesets for changes made outside the server (the CLI, DrBot).
+   * A model change reloads and broadcasts `model.updated`. A changeset change, including the
+   * `.active` marker, broadcasts a debounced `changesets.updated`. An annotation change (the
+   * MCP annotation_* tools write the same files) broadcasts what changed, debounced.
    */
   setupFileWatcher() {
-    const modelPath = `${this.model.rootPath}/documentation-robotics/model`;
+    const drRoot = path.join(this.model.rootPath, "documentation-robotics"), modelPath = path.join(drRoot, "model"), changesetsPath = path.join(drRoot, "changesets"), annotationsPath = path.join(drRoot, "annotations"), isWithin = (filePath, dir) => filePath === dir || filePath.startsWith(dir + path.sep);
     try {
-      this.watcher = chokidar.watch(modelPath, {
+      this.watcher = chokidar.watch(drRoot, {
         persistent: !0,
-        ignoreInitial: !0
-      }), this.watcher.on("all", async (_event, path2) => {
-        process.env.VERBOSE && console.log(`[Watcher] File changed: ${path2}`);
-        try {
-          await this.reloadAndBroadcast();
-        } catch (error) {
-          const message = getErrorMessage(error);
-          console.error(`[Watcher] Failed to reload model: ${message}`);
+        ignoreInitial: !0,
+        ignored: (filePath) => !(filePath === drRoot || isWithin(filePath, modelPath) || isWithin(filePath, changesetsPath) || isWithin(filePath, annotationsPath))
+      }), this.watcher.on("all", async (_event, filePath) => {
+        if (process.env.VERBOSE && console.log(`[Watcher] File changed: ${filePath}`), isWithin(filePath, annotationsPath)) {
+          this.scheduleAnnotationsSync();
+          return;
+        }
+        if (isWithin(filePath, changesetsPath)) {
+          this.scheduleChangesetsBroadcast();
+          return;
         }
+        if (isWithin(filePath, modelPath))
+          try {
+            await this.reloadAndBroadcast();
+          } catch (error) {
+            const message = getErrorMessage(error);
+            console.error(`[Watcher] Failed to reload model: ${message}`);
+          }
       }), this.watcher.on("error", (err) => {
-        console.warn(`[Watcher] Could not watch ${modelPath}: ${getErrorMessage(err)}`);
+        console.warn(`[Watcher] Could not watch ${drRoot}: ${getErrorMessage(err)}`);
       });
     } catch (err) {
-      console.warn(`[Watcher] Could not watch ${modelPath}: ${err}`);
+      console.warn(`[Watcher] Could not watch ${drRoot}: ${err}`);
+    }
+  }
+  /** Broadcasts `changesets.updated` once the changeset files have been quiet for a moment. */
+  scheduleChangesetsBroadcast() {
+    this.changesetsBroadcastTimer && clearTimeout(this.changesetsBroadcastTimer), this.changesetsBroadcastTimer = setTimeout(() => {
+      this.changesetsBroadcastTimer = void 0, this.broadcastChangesetsUpdated().catch((error) => {
+        console.error(`[Watcher] Failed to broadcast changesets: ${getErrorMessage(error)}`);
+      });
+    }, this.changesetsDebounceMs);
+  }
+  /**
+   * Reload the changesets from disk and send every client `changesets.updated` with their ids
+   * and the active one. Clients fetch `GET /api/changesets` for the details.
+   */
+  async broadcastChangesetsUpdated() {
+    await this.loadChangesetsFromDisk();
+    let active = null;
+    try {
+      active = await new StagingAreaManager(this.model.rootPath).getActiveId();
+    } catch (error) {
+      console.warn(`[Changesets] Could not read the active changeset: ${getErrorMessage(error)}`);
     }
+    await this.broadcastMessage({
+      type: "changesets.updated",
+      ids: [...this.changesets.keys()],
+      active,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
   }
   /**
    * Load all JSON schemas from bundled directory (recursive)
@@ -2403,8 +2641,8 @@ class VisualizationServer {
    * Commit or discard a staged changeset for POST /api/changesets/:id/{commit,discard}.
    *
    * Works on a freshly loaded model rather than the server's in-memory copy, so a CLI
-   * change since the last reload can't be overwritten. Afterwards the server reloads
-   * (the watcher only sees model files, and a discard touches none) and broadcasts.
+   * change since the last reload can't be overwritten. Afterwards the server reloads and
+   * broadcasts `model.updated` and `changesets.updated` at once, rather than wait for the watcher.
    */
   async runChangesetAction(c, changesetId, action) {
     const model = await Model.load(this.model.rootPath, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(changesetId);
@@ -2438,6 +2676,11 @@ class VisualizationServer {
     } catch (error) {
       console.error(`[Changesets] Reload after ${action} failed: ${getErrorMessage(error)}`);
     }
+    try {
+      await this.broadcastChangesetsUpdated();
+    } catch (error) {
+      console.error(`[Changesets] Broadcast after ${action} failed: ${getErrorMessage(error)}`);
+    }
     const updated = this.changesets.get(changesetId) ?? await manager.load(changesetId);
     return c.json({
       id: changesetId,
@@ -2465,14 +2708,44 @@ class VisualizationServer {
    * Start the server
    */
   async start(port = 8080) {
-    this.changesetStorage = new StagedChangesetStorage(this.model.rootPath), await this.loadChangesetsFromDisk(), this.setupFileWatcher(), this._server = serve({
-      port,
-      fetch: this.app.fetch
-    }), await new Promise((resolve, reject) => {
-      this._server.once("listening", resolve), this._server.once("error", (err) => {
-        err.code === "EADDRINUSE" ? reject(new Error(`Port ${port} is already in use. Try a different port with --port <port>.`)) : reject(err);
+    this.changesetStorage = new StagedChangesetStorage(this.model.rootPath), await this.loadChangesetsFromDisk(), await this.syncAnnotations({ broadcast: !1 }).catch((error) => {
+      console.warn(`[Annotations] Could not read the annotations: ${getErrorMessage(error)}`);
+    });
+    try {
+      this._servers.push(await this.listenOn(port, "127.0.0.1"));
+      try {
+        this._servers.push(await this.listenOn(port, "::1"));
+      } catch (error) {
+        const code = error.code;
+        if (code !== "EADDRNOTAVAIL" && code !== "EAFNOSUPPORT")
+          throw error;
+      }
+    } catch (error) {
+      throw this.closeServers(), error.code === "EADDRINUSE" ? new Error(`Port ${port} is already in use. Try a different port with --port <port>.`) : error;
+    }
+    for (const server of this._servers)
+      this.injectWebSocket?.(server);
+    this.setupFileWatcher(), console.log(`\u2713 Visualization server running at http://localhost:${port}`);
+  }
+  /**
+   * One HTTP server for the app, listening on host:port. Node reports bind failures (e.g.
+   * EADDRINUSE) through an 'error' event, not a throw; this turns that into a rejection
+   * instead of an unhandled 'error' that would crash the process via server-entry.ts's
+   * uncaughtException handler.
+   */
+  async listenOn(port, host) {
+    const server = createAdaptorServer({ fetch: this.app.fetch });
+    return await new Promise((resolve, reject) => {
+      server.once("listening", resolve), server.once("error", reject), server.listen(port, host);
+    }), server;
+  }
+  /** Closes every HTTP server this instance listens on. */
+  closeServers() {
+    for (const server of this._servers)
+      server.close((error) => {
+        error && process.env.VERBOSE && console.warn(`[SERVER] Error while closing HTTP server: ${getErrorMessage(error)}`);
       });
-    }), this.injectWebSocket?.(this._server), console.log(`\u2713 Visualization server running at http://localhost:${port}`);
+    this._servers = [];
   }
   /**
    * Get the current auth token
@@ -2494,11 +2767,11 @@ class VisualizationServer {
    */
   waitForExit(proc) {
     return new Promise((resolve) => {
-      if (proc.exitCode !== null) {
-        resolve(proc.exitCode);
+      if (this.hasExited(proc)) {
+        resolve(proc.exitCode ?? 1);
         return;
       }
-      proc.once("exit", (code) => resolve(code ?? 0));
+      proc.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
     });
   }
   /**
@@ -2549,9 +2822,7 @@ class VisualizationServer {
         const errorMessage = error instanceof Error ? error.message : String(error);
         errorMessage.includes("already closed") || console.warn(`[SERVER] Unexpected error closing WebSocket client: ${errorMessage}`);
       }
-    this.clients.clear(), this.watcher && this.watcher.close?.(), this._server && this._server.close((error) => {
-      error && process.env.VERBOSE && console.warn(`[SERVER] Error while closing HTTP server: ${getErrorMessage(error)}`);
-    });
+    this.clients.clear(), this.watcher && this.watcher.close?.(), this.changesetsBroadcastTimer && (clearTimeout(this.changesetsBroadcastTimer), this.changesetsBroadcastTimer = void 0), this.annotationsBroadcastTimer && (clearTimeout(this.annotationsBroadcastTimer), this.annotationsBroadcastTimer = void 0), this.closeServers();
   }
 }
 export {