@wrongstack/webui 0.9.7 → 0.9.20

package/dist/server/entry.js

@@ -10,10 +10,15 @@ import {
   DefaultMemoryStore as DefaultMemoryStore2,
   DefaultModeStore as DefaultModeStore2,
   DefaultModelsRegistry,
+  DefaultSessionReader,
   DefaultSessionStore as DefaultSessionStore2,
   DefaultSkillLoader as DefaultSkillLoader2,
   DefaultSystemPromptBuilder as DefaultSystemPromptBuilder2,
   DefaultTokenCounter as DefaultTokenCounter2,
+  AnnotationsStore,
+  CollaborationBus,
+  collabPauseMiddleware,
+  collabInjectMiddleware,
   estimateRequestTokens,
   EventBus,
   HybridCompactor as HybridCompactor2,
@@ -62,16 +67,30 @@ function createDefaultContainer(opts) {
   container.bind(TOKENS.RetryPolicy, () => new DefaultRetryPolicy());
   container.bind(TOKENS.ErrorHandler, () => new DefaultErrorHandler());
   container.bind(TOKENS.ModelsRegistry, () => modelsRegistry);
-  container.bind(TOKENS.TokenCounter, () => new DefaultTokenCounter({ registry: modelsRegistry, providerId: config.provider }));
+  container.bind(
+    TOKENS.TokenCounter,
+    () => new DefaultTokenCounter({ registry: modelsRegistry, providerId: config.provider })
+  );
   const modeStore = new DefaultModeStore({ directory: wpaths.configDir });
   container.bind(TOKENS.ModeStore, () => modeStore);
-  container.bind(TOKENS.SessionStore, () => new DefaultSessionStore({ dir: wpaths.projectSessions }));
+  container.bind(
+    TOKENS.SessionStore,
+    () => new DefaultSessionStore({
+      dir: wpaths.projectSessions,
+      // Scrub secrets out of persisted user/model turns (F-06). Tool output
+      // is already scrubbed by the executor.
+      secretScrubber: container.resolve(TOKENS.SecretScrubber)
+    })
+  );
   const memoryStore = new DefaultMemoryStore({ paths: wpaths });
   container.bind(TOKENS.MemoryStore, () => memoryStore);
   const skillLoader = new DefaultSkillLoader({ paths: wpaths, bundledDir: opts.bundledSkillsDir });
   container.bind(TOKENS.SkillLoader, () => skillLoader);
   if (opts.systemPrompt) {
-    container.bind(TOKENS.SystemPromptBuilder, () => new DefaultSystemPromptBuilder(opts.systemPrompt));
+    container.bind(
+      TOKENS.SystemPromptBuilder,
+      () => new DefaultSystemPromptBuilder(opts.systemPrompt)
+    );
   }
   container.bind(
     TOKENS.PermissionPolicy,
@@ -464,6 +483,664 @@ Type: ${task.type}`;
   }
 };
 
+// src/server/collaboration-ws-handler.ts
+import { randomUUID } from "crypto";
+var REPLAY_LIMIT = 50;
+var PAUSE_TIMEOUT_MS = 6e4;
+var CollaborationWebSocketHandler = class {
+  constructor(events, logger, reader, annotations, bus) {
+    this.events = events;
+    this.logger = logger;
+    this.reader = reader;
+    this.annotations = annotations;
+    this.bus = bus;
+    this.subscribe();
+  }
+  events;
+  logger;
+  reader;
+  annotations;
+  bus;
+  clients = /* @__PURE__ */ new Set();
+  /** sessionId → participants currently watching it. */
+  bySession = /* @__PURE__ */ new Map();
+  broadcastInterval = null;
+  offs = [];
+  // ── Public API (called by server/index.ts per WS connection) ───────────
+  addClient(ws) {
+    this.clients.add(ws);
+    this.ensureBroadcast();
+    ws.on("close", () => this.handleDisconnect(ws));
+    ws.on("error", () => this.handleDisconnect(ws));
+  }
+  dispose() {
+    for (const off of this.offs) off();
+    this.offs.length = 0;
+    this.stopBroadcast();
+  }
+  // ── Inbound client messages ────────────────────────────────────────────
+  /**
+   * Dispatch a parsed client message. Returns true when the message was
+   * recognized and handled; false when the caller should ignore / log.
+   * Phase 1 only knows `collab.join` and `collab.leave`; unknown types
+   * return false so the upstream router can decide.
+   */
+  handleMessage(ws, msg) {
+    if (msg.type === "collab.join") {
+      const payload = msg.payload;
+      if (!payload?.sessionId) {
+        this.send(ws, this.errorMessage("collab.join requires sessionId"));
+        return true;
+      }
+      this.join(ws, payload.sessionId, payload.role ?? "observer");
+      return true;
+    }
+    if (msg.type === "collab.leave") {
+      this.leave(ws);
+      return true;
+    }
+    if (msg.type === "collab.annotate") {
+      void this.handleAnnotate(ws, msg.payload);
+      return true;
+    }
+    if (msg.type === "collab.resolve") {
+      void this.handleResolve(ws, msg.payload);
+      return true;
+    }
+    if (msg.type === "collab.request_pause") {
+      void this.handleRequestPause(ws, msg.payload);
+      return true;
+    }
+    if (msg.type === "collab.resume") {
+      void this.handleResume(ws, msg.payload);
+      return true;
+    }
+    if (msg.type === "collab.grant_control") {
+      void this.handleGrantControl(ws, msg.payload);
+      return true;
+    }
+    if (msg.type === "collab.inject_tool") {
+      void this.handleInjectTool(ws, msg.payload);
+      return true;
+    }
+    return false;
+  }
+  // ── Join / leave flow ──────────────────────────────────────────────────
+  join(ws, sessionId, role) {
+    if (role === "controller" && !this.bus) {
+      this.send(
+        ws,
+        this.errorMessage(
+          `role 'controller' is not available: server has no CollaborationBus`
+        )
+      );
+      return;
+    }
+    if (role === "annotator" && !this.annotations) {
+      this.send(
+        ws,
+        this.errorMessage(
+          `role 'annotator' is not available: server has no annotations store`
+        )
+      );
+      return;
+    }
+    const participant = {
+      participantId: randomUUID(),
+      ws,
+      sessionId,
+      role,
+      joinedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    let bucket = this.bySession.get(sessionId);
+    if (!bucket) {
+      bucket = /* @__PURE__ */ new Set();
+      this.bySession.set(sessionId, bucket);
+    }
+    bucket.add(participant);
+    this.send(ws, this.stateMessage(sessionId));
+    this.broadcast(sessionId, {
+      type: "collab.participant.joined",
+      payload: {
+        participantId: participant.participantId,
+        sessionId,
+        role,
+        joinedAt: participant.joinedAt
+      }
+    });
+    this.broadcast(sessionId, this.stateMessage(sessionId));
+    if (this.reader) {
+      this.replayHistory(ws, sessionId).catch((err) => {
+        this.logger.debug?.(
+          `collab: replay failed for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      });
+    }
+    this.logger.debug?.(
+      `collab: participant ${participant.participantId} joined ${sessionId}`
+    );
+  }
+  leave(ws) {
+    this.handleDisconnect(ws);
+  }
+  handleDisconnect(ws) {
+    this.clients.delete(ws);
+    for (const [sessionId, bucket] of this.bySession) {
+      for (const p of bucket) {
+        if (p.ws === ws) {
+          const leftEvent = {
+            type: "collab.participant.left",
+            payload: { participantId: p.participantId, sessionId }
+          };
+          this.send(ws, leftEvent);
+          bucket.delete(p);
+          if (bucket.size === 0) {
+            this.bySession.delete(sessionId);
+          } else {
+            this.broadcast(sessionId, leftEvent);
+            this.broadcast(sessionId, this.stateMessage(sessionId));
+          }
+          break;
+        }
+      }
+    }
+    if (this.bySession.size === 0) this.stopBroadcast();
+  }
+  // ── Annotation flow (Phase 2) ───────────────────────────────────────────
+  /**
+   * Look up the participant record for a given WS across all sessions.
+   * Returns null when the WS hasn't joined (e.g. the client sent a
+   * `collab.annotate` before `collab.join`).
+   */
+  findParticipant(ws) {
+    for (const bucket of this.bySession.values()) {
+      for (const p of bucket) {
+        if (p.ws === ws) return p;
+      }
+    }
+    return null;
+  }
+  async handleAnnotate(ws, raw) {
+    if (!this.annotations) {
+      this.send(ws, this.errorMessage("annotations store is not configured"));
+      return;
+    }
+    const participant = this.findParticipant(ws);
+    if (!participant) {
+      this.send(ws, this.errorMessage("annotate requires an active join"));
+      return;
+    }
+    if (participant.role !== "annotator") {
+      this.send(
+        ws,
+        this.errorMessage(
+          `annotate requires the 'annotator' role (current: '${participant.role}')`
+        )
+      );
+      return;
+    }
+    const payload = raw;
+    if (!payload?.sessionId || typeof payload.atEventIndex !== "number" || typeof payload.text !== "string") {
+      this.send(
+        ws,
+        this.errorMessage("annotate requires { sessionId, atEventIndex, text }")
+      );
+      return;
+    }
+    if (payload.sessionId !== participant.sessionId) {
+      this.send(
+        ws,
+        this.errorMessage(
+          `annotate sessionId mismatch (joined: ${participant.sessionId})`
+        )
+      );
+      return;
+    }
+    try {
+      const annotation = await this.annotations.add({
+        sessionId: payload.sessionId,
+        atEventIndex: payload.atEventIndex,
+        authorId: participant.participantId,
+        text: payload.text
+      });
+      this.broadcast(payload.sessionId, {
+        type: "collab.annotation.added",
+        payload: {
+          sessionId: payload.sessionId,
+          annotation: {
+            id: annotation.id,
+            atEventIndex: annotation.atEventIndex,
+            authorId: annotation.authorId,
+            authorRole: annotation.authorRole,
+            text: annotation.text,
+            createdAt: annotation.createdAt,
+            resolved: annotation.resolved
+          }
+        }
+      });
+    } catch (err) {
+      this.send(
+        ws,
+        this.errorMessage(
+          `annotation rejected: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+    }
+  }
+  async handleResolve(ws, raw) {
+    if (!this.annotations) {
+      this.send(ws, this.errorMessage("annotations store is not configured"));
+      return;
+    }
+    const participant = this.findParticipant(ws);
+    if (!participant) {
+      this.send(ws, this.errorMessage("resolve requires an active join"));
+      return;
+    }
+    if (participant.role !== "annotator") {
+      this.send(
+        ws,
+        this.errorMessage(
+          `resolve requires the 'annotator' role (current: '${participant.role}')`
+        )
+      );
+      return;
+    }
+    const payload = raw;
+    if (!payload?.sessionId || !payload.annotationId) {
+      this.send(
+        ws,
+        this.errorMessage("resolve requires { sessionId, annotationId }")
+      );
+      return;
+    }
+    if (payload.sessionId !== participant.sessionId) {
+      this.send(
+        ws,
+        this.errorMessage(
+          `resolve sessionId mismatch (joined: ${participant.sessionId})`
+        )
+      );
+      return;
+    }
+    try {
+      const updated = await this.annotations.resolve({
+        sessionId: payload.sessionId,
+        annotationId: payload.annotationId,
+        resolvedBy: participant.participantId
+      });
+      if (!updated) {
+        this.send(
+          ws,
+          this.errorMessage(`annotation not found: ${payload.annotationId}`)
+        );
+        return;
+      }
+      this.broadcast(payload.sessionId, {
+        type: "collab.annotation.resolved",
+        payload: {
+          sessionId: payload.sessionId,
+          annotationId: updated.id,
+          resolvedBy: updated.resolvedBy ?? participant.participantId,
+          resolvedAt: updated.resolvedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+    } catch (err) {
+      this.send(
+        ws,
+        this.errorMessage(
+          `resolve failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+    }
+  }
+  // ── Event subscription (live mirror) ───────────────────────────────────
+  subscribe() {
+    const on = this.events.on.bind(this.events);
+    const forwarded = [
+      ["iteration.started", "iteration.started"],
+      ["iteration.completed", "iteration.completed"],
+      ["tool.started", "tool.started"],
+      ["tool.progress", "tool.progress"],
+      ["tool.executed", "tool.executed"],
+      ["tool.confirm_needed", "tool.confirm_needed"],
+      ["subagent.spawned", "subagent.spawned"],
+      ["subagent.task_started", "subagent.task_started"],
+      ["subagent.iteration_summary", "subagent.iteration_summary"],
+      ["subagent.task_completed", "subagent.task_completed"],
+      ["subagent.done", "subagent.done"]
+    ];
+    for (const [kernelEvent, kind] of forwarded) {
+      this.offs.push(
+        on(kernelEvent, (raw) => {
+          let payload = raw;
+          try {
+            payload = JSON.parse(JSON.stringify(raw));
+          } catch {
+            return;
+          }
+          this.broadcastEvent(kind, payload);
+        })
+      );
+    }
+  }
+  broadcastEvent(kind, payload) {
+    if (this.bySession.size === 0) return;
+    const msg = {
+      type: "collab.event",
+      payload: { kind, payload, at: (/* @__PURE__ */ new Date()).toISOString() }
+    };
+    const data = JSON.stringify(msg);
+    for (const bucket of this.bySession.values()) {
+      for (const p of bucket) {
+        try {
+          if (p.ws.readyState === 1) p.ws.send(data);
+        } catch (err) {
+          this.logger.debug?.(
+            `collab broadcast failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Replay the last `REPLAY_LIMIT` events from the on-disk session log
+   * to a single observer (the late joiner). Each event is forwarded as
+   * a `collab.event` with `replay: true` so the client can distinguish
+   * history from the live stream.
+   *
+   * The session log stores typed `SessionEvent`s (`user_input`,
+   * `llm_response`, `tool_result`, etc.) — different from the kernel's
+   * bus events. We translate the most useful subset (`tool.*` and
+   * `iteration.*`-shaped ones) into the same `kind` namespace the live
+   * mirror uses, so the client can render a single activity strip.
+   */
+  async replayHistory(ws, sessionId) {
+    if (!this.reader) return;
+    const all = [];
+    try {
+      for await (const ev of this.reader.replay(sessionId)) {
+        all.push(ev);
+      }
+    } catch (err) {
+      this.logger.debug?.(
+        `collab: session reader rejected ${sessionId}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return;
+    }
+    const tail = all.slice(-REPLAY_LIMIT);
+    if (tail.length === 0) return;
+    for (const raw of tail) {
+      const ev = raw;
+      const kind = this.historyEventToKind(ev);
+      if (!kind) continue;
+      this.send(ws, {
+        type: "collab.event",
+        payload: {
+          kind,
+          payload: ev,
+          at: ev.ts ?? (/* @__PURE__ */ new Date()).toISOString(),
+          replay: true
+        }
+      });
+    }
+  }
+  /**
+   * Map a stored `SessionEvent` to a `collab.event.kind` so the live
+   * strip and the history strip can share a single rendering path.
+   * Returns null for events that don't have a meaningful live analog
+   * (e.g. `session_start`, file-snapshot bookkeeping, rewind markers).
+   */
+  historyEventToKind(ev) {
+    switch (ev.type) {
+      case "user_input":
+        return "user_input";
+      case "llm_response":
+        return "llm_response";
+      case "tool_result":
+        return "tool.executed";
+      case "compaction":
+        return "compaction";
+      case "error":
+        return "error";
+      default:
+        return null;
+    }
+  }
+  // ── State snapshot + periodic broadcast ────────────────────────────────
+  stateMessage(sessionId) {
+    const bucket = this.bySession.get(sessionId);
+    return {
+      type: "collab.state",
+      payload: {
+        sessionId,
+        participants: bucket ? [...bucket].map((p) => ({
+          participantId: p.participantId,
+          role: p.role,
+          joinedAt: p.joinedAt
+        })) : []
+      }
+    };
+  }
+  ensureBroadcast() {
+    if (this.broadcastInterval) return;
+    this.broadcastInterval = setInterval(() => {
+      for (const sessionId of this.bySession.keys()) {
+        this.broadcast(sessionId, this.stateMessage(sessionId));
+      }
+    }, 2e3);
+  }
+  stopBroadcast() {
+    if (this.broadcastInterval) {
+      clearInterval(this.broadcastInterval);
+      this.broadcastInterval = null;
+    }
+  }
+  broadcast(sessionId, msg) {
+    const data = JSON.stringify(msg);
+    const bucket = this.bySession.get(sessionId);
+    if (!bucket) return;
+    for (const p of bucket) {
+      try {
+        if (p.ws.readyState === 1) p.ws.send(data);
+      } catch (err) {
+        this.logger.debug?.(
+          `collab broadcast failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  send(ws, msg) {
+    try {
+      if (ws.readyState === 1) ws.send(JSON.stringify(msg));
+    } catch {
+    }
+  }
+  errorMessage(detail) {
+    return { type: "error", payload: { phase: "collab", message: detail } };
+  }
+  // ── Controller flow (Phase 3) ───────────────────────────────────────────
+  async handleRequestPause(ws, raw) {
+    if (!this.bus) {
+      this.send(ws, this.errorMessage("pause requires a CollaborationBus"));
+      return;
+    }
+    const participant = this.findParticipant(ws);
+    if (!participant) {
+      this.send(ws, this.errorMessage("pause requires an active join"));
+      return;
+    }
+    if (participant.role !== "controller") {
+      this.send(
+        ws,
+        this.errorMessage(
+          `pause requires the 'controller' role (current: '${participant.role}')`
+        )
+      );
+      return;
+    }
+    const payload = raw;
+    if (!payload?.sessionId || payload.sessionId !== participant.sessionId) {
+      this.send(ws, this.errorMessage("pause sessionId mismatch"));
+      return;
+    }
+    const transitioned = this.bus.requestPause(participant.participantId);
+    if (!transitioned) {
+      const s2 = this.bus.getState();
+      this.send(ws, {
+        type: "error",
+        payload: {
+          phase: "collab",
+          message: `bus already paused by ${s2.pausedBy ?? "?"} at ${s2.pausedAt ?? "?"}`
+        }
+      });
+      return;
+    }
+    const s = this.bus.getState();
+    this.broadcast(payload.sessionId, {
+      type: "collab.pause.granted",
+      payload: {
+        sessionId: payload.sessionId,
+        pausedBy: s.pausedBy ?? participant.participantId,
+        pausedAt: s.pausedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+        autoResumeInMs: PAUSE_TIMEOUT_MS
+      }
+    });
+  }
+  async handleResume(ws, raw) {
+    if (!this.bus) {
+      this.send(ws, this.errorMessage("resume requires a CollaborationBus"));
+      return;
+    }
+    const participant = this.findParticipant(ws);
+    if (!participant) {
+      this.send(ws, this.errorMessage("resume requires an active join"));
+      return;
+    }
+    if (participant.role !== "controller") {
+      this.send(
+        ws,
+        this.errorMessage(
+          `resume requires the 'controller' role (current: '${participant.role}')`
+        )
+      );
+      return;
+    }
+    const payload = raw;
+    if (!payload?.sessionId || payload.sessionId !== participant.sessionId) {
+      this.send(ws, this.errorMessage("resume sessionId mismatch"));
+      return;
+    }
+    const transitioned = this.bus.resume();
+    if (!transitioned) {
+      this.send(ws, this.errorMessage("bus is not currently paused"));
+      return;
+    }
+    this.broadcast(payload.sessionId, {
+      type: "collab.pause.released",
+      payload: {
+        sessionId: payload.sessionId,
+        reason: "controller",
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    });
+  }
+  async handleGrantControl(ws, raw) {
+    const participant = this.findParticipant(ws);
+    if (!participant) {
+      this.send(ws, this.errorMessage("grant_control requires an active join"));
+      return;
+    }
+    const payload = raw;
+    if (!payload?.sessionId || !payload.toParticipant || payload.sessionId !== participant.sessionId) {
+      this.send(ws, this.errorMessage("grant_control requires { sessionId, toParticipant }"));
+      return;
+    }
+    this.logger.debug?.(
+      `collab: control granted from ${participant.participantId} to ${payload.toParticipant} in ${payload.sessionId}`
+    );
+  }
+  /**
+   * Phase 4 — handle a controller's manual tool-call injection.
+   * Validates the payload, queues it on the bus, and broadcasts
+   * the grant so observers see what just happened. The actual
+   * splice into the agent's pipeline is performed by the
+   * `collabInjectMiddleware` on the next tool call.
+   */
+  async handleInjectTool(ws, raw) {
+    if (!this.bus) {
+      this.send(ws, this.errorMessage("inject_tool requires a CollaborationBus"));
+      return;
+    }
+    const participant = this.findParticipant(ws);
+    if (!participant) {
+      this.send(ws, this.errorMessage("inject_tool requires an active join"));
+      return;
+    }
+    if (participant.role !== "controller") {
+      this.send(
+        ws,
+        this.errorMessage(
+          `inject_tool requires the 'controller' role (current: '${participant.role}')`
+        )
+      );
+      return;
+    }
+    const payload = raw;
+    if (!payload?.sessionId || !payload.toolUseId || typeof payload.isError !== "boolean" || typeof payload.reason !== "string" || payload.content === void 0) {
+      this.send(
+        ws,
+        this.errorMessage(
+          "inject_tool requires { sessionId, toolUseId, content, isError, reason }"
+        )
+      );
+      return;
+    }
+    if (payload.sessionId !== participant.sessionId) {
+      this.send(
+        ws,
+        this.errorMessage(
+          `inject_tool sessionId mismatch (joined: ${participant.sessionId})`
+        )
+      );
+      return;
+    }
+    const queued = this.bus.injectToolResult({
+      toolUseId: payload.toolUseId,
+      content: payload.content,
+      isError: payload.isError,
+      reason: payload.reason,
+      authorId: participant.participantId
+    });
+    if (!queued) {
+      this.send(
+        ws,
+        this.errorMessage(
+          `an injection for toolUseId ${payload.toolUseId} is already queued`
+        )
+      );
+      return;
+    }
+    this.broadcast(payload.sessionId, {
+      type: "collab.injection.granted",
+      payload: {
+        sessionId: payload.sessionId,
+        toolUseId: payload.toolUseId,
+        // The tool name is unknown here (the injection is queued
+        // before the model produces the tool call). We surface a
+        // placeholder; the middleware will emit a `consumed` event
+        // with the real name on match.
+        toolName: "(pending match)",
+        authorId: participant.participantId,
+        reason: payload.reason,
+        isError: payload.isError,
+        phase: "queued",
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    });
+  }
+};
+
 // src/server/worktree-ws-handler.ts
 var MAX_ACTIVITY = 6;
 var WorktreeWebSocketHandler = class {
@@ -646,6 +1323,8 @@ async function startWebUI(opts = {}) {
   const events = new EventBus();
   events.setLogger(logger);
   const sessionStore = new DefaultSessionStore2({ dir: wpaths.projectSessions });
+  const sessionReader = new DefaultSessionReader({ store: sessionStore });
+  const annotationsStore = new AnnotationsStore({ dir: wpaths.projectSessions });
   let session = await sessionStore.create({
     id: "",
     title: "",
@@ -740,6 +1419,13 @@ async function startWebUI(opts = {}) {
   context.meta["contextWindowMode"] = initialContextPolicy.id;
   context.meta["contextWindowPolicy"] = initialContextPolicy;
   const pipelines = createDefaultPipelines();
+  const collabBus = new CollaborationBus();
+  const collabPause = collabPauseMiddleware(collabBus, { logger });
+  Object.defineProperty(collabPause, "name", { value: "collab-pause" });
+  pipelines.toolCall.prepend(collabPause);
+  const collabInject = collabInjectMiddleware(collabBus, { logger });
+  Object.defineProperty(collabInject, "name", { value: "collab-inject" });
+  pipelines.toolCall.prepend(collabInject);
   const compactor = new HybridCompactor2({
     preserveK: config.context?.preserveK ?? 20,
     eliseThreshold: config.context?.eliseThreshold ?? 0.7
@@ -813,6 +1499,13 @@ async function startWebUI(opts = {}) {
     projectRoot
   );
   const worktreeHandler = new WorktreeWebSocketHandler(events, logger);
+  const collabHandler = new CollaborationWebSocketHandler(
+    events,
+    logger,
+    sessionReader,
+    annotationsStore,
+    collabBus
+  );
   async function sessionStartPayload() {
     let maxContext = 0;
     let inputCost = 0;
@@ -1036,6 +1729,7 @@ async function startWebUI(opts = {}) {
     });
     autoPhaseHandler.addClient(ws);
     worktreeHandler.addClient(ws);
+    collabHandler.addClient(ws);
     ws.on("message", async (data) => {
       if (!checkRateLimit(ws, client)) {
         send(ws, {
@@ -1101,8 +1795,18 @@ async function startWebUI(opts = {}) {
       }
     });
   }
-  async function handleMessage(ws, client, msg) {
+  async function handleMessage(ws, _client, msg) {
     switch (msg.type) {
+      // Collaboration messages short-circuit the user/agent flow.
+      // They don't touch runLock, the agent loop, or the message queue —
+      // they're pure transport for the live observer mirror.
+      case "collab.join":
+      case "collab.leave":
+      case "collab.annotate":
+      case "collab.resolve": {
+        collabHandler.handleMessage(ws, msg);
+        return;
+      }
       case "user_message": {
         const content = msg.payload.content;
         if (runLock) {
@@ -1702,7 +2406,7 @@ async function startWebUI(opts = {}) {
           break;
         }
         try {
-          const { getPlanTemplate, loadPlan, savePlan, emptyPlan, addPlanItem, formatPlan } = await import("@wrongstack/core");
+          const { getPlanTemplate, loadPlan, savePlan, emptyPlan, addPlanItem } = await import("@wrongstack/core");
           const tpl = getPlanTemplate(template);
           if (!tpl) {
             sendResult(ws, false, `Unknown template "${template}".`);