@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/server/src/browser-handlers/session-action-handler.ts

@@ -0,0 +1,271 @@
+/**
+ * Session action handlers: send_prompt, abort, resume, spawn, shutdown, flow_control.
+ */
+import type { BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
+import type { BrowserHandlerContext } from "./handler-context.js";
+import { spawnPiSession } from "../process-manager.js";
+import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { createBranchedSessionFile } from "../session-file-reader.js";
+import { execSync } from "node:child_process";
+
+function killHeadlessBySessionId(sessionId: string): boolean {
+  if (process.platform === "win32") return false;
+  try {
+    const output = execSync(
+      `ps -eo pid,command | grep "${sessionId}" | grep "sleep 2147483647" | grep -v grep`,
+      { encoding: "utf8", timeout: 3000 },
+    ).trim();
+    if (!output) return false;
+    for (const line of output.split("\n")) {
+      const pid = parseInt(line.trim(), 10);
+      if (pid > 0) {
+        try { process.kill(-pid, "SIGTERM"); } catch {
+          try { process.kill(pid, "SIGTERM"); } catch { /* ignore */ }
+        }
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function handleSendPrompt(
+  msg: Extract<BrowserToServerMessage, { type: "send_prompt" }>,
+  ctx: BrowserHandlerContext,
+): Promise<void> {
+  const { sessionManager, piGateway, headlessPidRegistry, pendingResumeRegistry, pendingDashboardSpawns, broadcast } = ctx;
+  const promptSession = sessionManager.get(msg.sessionId);
+
+  if (promptSession?.status === "ended") {
+    if (!promptSession.sessionFile) {
+      console.error(`[dashboard] auto-resume failed: no session file for session ${msg.sessionId}`);
+      return;
+    }
+    const alreadyResuming = promptSession.resuming;
+    pendingResumeRegistry.record(promptSession.cwd, {
+      text: msg.text,
+      images: msg.images,
+      oldSessionId: msg.sessionId,
+      sessionFile: promptSession.sessionFile,
+    });
+    if (alreadyResuming) return;
+    sessionManager.update(msg.sessionId, { resuming: true });
+    broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { resuming: true } });
+    const autoResumeConfig = loadConfig();
+    const spawnResult = await spawnPiSession(promptSession.cwd, {
+      sessionFile: promptSession.sessionFile,
+      mode: "continue",
+      strategy: autoResumeConfig.spawnStrategy,
+    });
+    if (!spawnResult.success) {
+      console.error(`[dashboard] auto-resume spawn failed: ${spawnResult.message}`);
+      pendingResumeRegistry.consume(promptSession.cwd);
+      sessionManager.update(msg.sessionId, { resuming: false });
+      broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { resuming: false } });
+    }
+    if (spawnResult.dashboardSpawned && spawnResult.success) {
+      pendingDashboardSpawns?.set(promptSession.cwd, (pendingDashboardSpawns?.get(promptSession.cwd) ?? 0) + 1);
+    }
+    if (spawnResult.process && spawnResult.pid) {
+      headlessPidRegistry.register(spawnResult.pid, promptSession.cwd, spawnResult.process);
+    }
+  } else {
+    const sent = piGateway.sendToSession(msg.sessionId, {
+      type: "send_prompt",
+      sessionId: msg.sessionId,
+      text: msg.text,
+      images: msg.images,
+    });
+    if (!sent) {
+      console.error(`[dashboard] send_prompt failed: no bridge connection for session ${msg.sessionId}`);
+    }
+  }
+}
+
+export async function handleResumeSession(
+  msg: Extract<BrowserToServerMessage, { type: "resume_session" }>,
+  ctx: BrowserHandlerContext,
+): Promise<void> {
+  const { ws, sessionManager, pendingForkRegistry, headlessPidRegistry, pendingDashboardSpawns, sendTo } = ctx;
+  const session = sessionManager.get(msg.sessionId);
+  if (!session) {
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session not found" });
+    return;
+  }
+  if (!session.sessionFile) {
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session file is unknown (pre-migration session)" });
+    return;
+  }
+  if (msg.mode === "continue" && session.status !== "ended") {
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already active" });
+    return;
+  }
+  if (session.resuming) {
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already being resumed" });
+    return;
+  }
+  if (msg.mode === "fork" && pendingForkRegistry) {
+    pendingForkRegistry.recordFork(session.cwd, msg.sessionId);
+  }
+
+  // For fork-from-message: create a pruned session file first
+  let forkSessionFile = session.sessionFile;
+  if (msg.mode === "fork" && msg.entryId) {
+    try {
+      forkSessionFile = createBranchedSessionFile(session.sessionFile, msg.entryId);
+    } catch (err: any) {
+      sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: `Fork from entry failed: ${err.message}` });
+      return;
+    }
+  }
+
+  const resumeConfig = loadConfig();
+  const result = await spawnPiSession(session.cwd, {
+    sessionFile: forkSessionFile,
+    mode: msg.mode,
+    strategy: resumeConfig.spawnStrategy,
+  });
+  if (result.dashboardSpawned && result.success) {
+    pendingDashboardSpawns?.set(session.cwd, (pendingDashboardSpawns?.get(session.cwd) ?? 0) + 1);
+  }
+  if (result.process && result.pid) {
+    headlessPidRegistry.register(result.pid, session.cwd, result.process);
+  }
+  sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: result.success, message: result.message });
+}
+
+export async function handleSpawnSession(
+  msg: Extract<BrowserToServerMessage, { type: "spawn_session" }>,
+  ctx: BrowserHandlerContext,
+): Promise<void> {
+  const { ws, headlessPidRegistry, pendingDashboardSpawns, sendTo } = ctx;
+  const config = loadConfig();
+  const spawnResult = await spawnPiSession(msg.cwd, { strategy: config.spawnStrategy });
+  if (spawnResult.process && spawnResult.pid) {
+    headlessPidRegistry.register(spawnResult.pid, msg.cwd, spawnResult.process);
+  }
+  if (spawnResult.dashboardSpawned && spawnResult.success) {
+    pendingDashboardSpawns?.set(msg.cwd, (pendingDashboardSpawns?.get(msg.cwd) ?? 0) + 1);
+  }
+  sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: spawnResult.success, message: spawnResult.message });
+}
+
+export function handleShutdown(
+  msg: Extract<BrowserToServerMessage, { type: "shutdown" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const { sessionManager, piGateway, headlessPidRegistry, broadcast } = ctx;
+  piGateway.sendToSession(msg.sessionId, { type: "shutdown", sessionId: msg.sessionId });
+  headlessPidRegistry.killBySessionId(msg.sessionId);
+  killHeadlessBySessionId(msg.sessionId);
+  sessionManager.unregister(msg.sessionId);
+  broadcast({ type: "session_removed", sessionId: msg.sessionId });
+}
+
+export function handleAbort(
+  msg: Extract<BrowserToServerMessage, { type: "abort" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  ctx.piGateway.sendToSession(msg.sessionId, { type: "abort", sessionId: msg.sessionId });
+}
+
+export function handleFlowControl(
+  msg: Extract<BrowserToServerMessage, { type: "flow_control" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  ctx.piGateway.sendToSession(msg.sessionId, { type: "flow_control", sessionId: msg.sessionId, action: msg.action });
+}
+
+export function handleKillProcess(
+  msg: Extract<BrowserToServerMessage, { type: "kill_process" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  ctx.piGateway.sendToSession(msg.sessionId, { type: "kill_process", sessionId: msg.sessionId, pgid: msg.pgid });
+}
+
+/**
+ * Check if a PID belongs to a pi/node process (safety check before SIGKILL).
+ * Returns true if the process looks like a pi-related process, false otherwise.
+ */
+function isPiProcess(pid: number): boolean {
+  try {
+    const cmd = process.platform === "darwin"
+      ? `ps -p ${pid} -o command=`
+      : `cat /proc/${pid}/cmdline 2>/dev/null || ps -p ${pid} -o command=`;
+    const output = execSync(cmd, { encoding: "utf8", timeout: 2000 }).trim();
+    return /\bpi\b|\bnode\b/.test(output);
+  } catch {
+    // Process already exited — treat as dead
+    return false;
+  }
+}
+
+/**
+ * Check if a process is still alive.
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function handleForceKill(
+  msg: Extract<BrowserToServerMessage, { type: "force_kill" }>,
+  ctx: BrowserHandlerContext,
+): Promise<void> {
+  const { sessionManager, piGateway, headlessPidRegistry, broadcast, sendTo, ws } = ctx;
+  const session = sessionManager.get(msg.sessionId);
+  if (!session) {
+    sendTo(ws, { type: "force_kill_result", sessionId: msg.sessionId, success: false, message: "Session not found" });
+    return;
+  }
+
+  // Force-close the bridge WebSocket regardless of PID availability
+  piGateway.closeSession(msg.sessionId);
+
+  const pid = session?.pid;
+  if (!pid) {
+    // No PID — we can only close the WebSocket
+    sessionManager.update(msg.sessionId, { status: "ended", endedAt: Date.now() });
+    broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { status: "ended", endedAt: Date.now() } });
+    sendTo(ws, { type: "force_kill_result", sessionId: msg.sessionId, success: true, message: "WebSocket closed (no PID available)" });
+    return;
+  }
+
+  // Step 1: SIGTERM
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // Process already dead
+    sessionManager.update(msg.sessionId, { status: "ended", endedAt: Date.now() });
+    broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { status: "ended", endedAt: Date.now() } });
+    sendTo(ws, { type: "force_kill_result", sessionId: msg.sessionId, success: true, message: "Process already exited" });
+    return;
+  }
+
+  // Also kill via headless registry if applicable
+  headlessPidRegistry.killBySessionId(msg.sessionId);
+
+  // Step 2: Wait 2s, then SIGKILL if still alive
+  await new Promise<void>((resolve) => {
+    setTimeout(() => {
+      if (isProcessAlive(pid)) {
+        // Safety check: verify PID still belongs to a pi process
+        if (isPiProcess(pid)) {
+          try {
+            process.kill(pid, "SIGKILL");
+          } catch { /* already dead */ }
+        }
+      }
+      resolve();
+    }, 2000);
+  });
+
+  sessionManager.update(msg.sessionId, { status: "ended", endedAt: Date.now() });
+  broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { status: "ended", endedAt: Date.now() } });
+  sendTo(ws, { type: "force_kill_result", sessionId: msg.sessionId, success: true });
+}

package/packages/server/src/browser-handlers/session-meta-handler.ts

@@ -0,0 +1,95 @@
+/**
+ * Session metadata handlers: rename, hide, unhide, attach/detach proposal, fetch_content, list_sessions.
+ */
+import type { BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
+import type { BrowserHandlerContext } from "./handler-context.js";
+
+export function handleRenameSession(
+  msg: Extract<BrowserToServerMessage, { type: "rename_session" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const { sessionManager, piGateway, broadcast } = ctx;
+  const nameUpdates = { name: msg.name || undefined };
+  sessionManager.update(msg.sessionId, nameUpdates);
+  broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: nameUpdates });
+  piGateway.sendToSession(msg.sessionId, { type: "rename_session", sessionId: msg.sessionId, name: msg.name });
+}
+
+export function handleHideSession(
+  msg: Extract<BrowserToServerMessage, { type: "hide_session" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const updates = { hidden: true };
+  ctx.sessionManager.update(msg.sessionId, updates);
+  ctx.broadcast({ type: "session_updated", sessionId: msg.sessionId, updates });
+}
+
+export function handleUnhideSession(
+  msg: Extract<BrowserToServerMessage, { type: "unhide_session" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const updates = { hidden: false };
+  ctx.sessionManager.update(msg.sessionId, updates);
+  ctx.broadcast({ type: "session_updated", sessionId: msg.sessionId, updates });
+}
+
+export function handleAttachProposal(
+  msg: Extract<BrowserToServerMessage, { type: "attach_proposal" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const { sessionManager, piGateway, broadcast } = ctx;
+  const updates: Record<string, unknown> = { attachedProposal: msg.changeName };
+  const session = sessionManager.get(msg.sessionId);
+  if (session && !session.name?.trim()) {
+    updates.name = msg.changeName;
+    piGateway.sendToSession(msg.sessionId, { type: "rename_session", sessionId: msg.sessionId, name: msg.changeName });
+  }
+  sessionManager.update(msg.sessionId, updates);
+  broadcast({ type: "session_updated", sessionId: msg.sessionId, updates });
+}
+
+export function handleDetachProposal(
+  msg: Extract<BrowserToServerMessage, { type: "detach_proposal" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const updates = { attachedProposal: null, openspecPhase: null, openspecChange: null };
+  ctx.sessionManager.update(msg.sessionId, updates);
+  ctx.broadcast({ type: "session_updated", sessionId: msg.sessionId, updates });
+}
+
+export function handleFetchContent(
+  msg: Extract<BrowserToServerMessage, { type: "fetch_content" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const event = ctx.eventStore.getEvent(msg.sessionId, msg.seq);
+  if (event) {
+    ctx.sendTo(ctx.ws, { type: "event", sessionId: msg.sessionId, seq: msg.seq, event });
+  }
+}
+
+export function handleListSessions(
+  msg: Extract<BrowserToServerMessage, { type: "list_sessions" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const { ws, sessionManager, piGateway, sendTo } = ctx;
+  const cwd = msg.cwd;
+  const bridgeSessionId = piGateway.findSessionByCwd(cwd);
+  if (bridgeSessionId) {
+    piGateway.sendToSession(bridgeSessionId, { type: "list_sessions", sessionId: bridgeSessionId, cwd });
+  } else {
+    const allSessions = sessionManager.listAll();
+    const filtered = allSessions
+      .filter((s) => s.cwd === cwd || s.cwd.startsWith(cwd + "/") || cwd.startsWith(s.cwd + "/"))
+      .map((s) => ({
+        id: s.id,
+        path: s.sessionFile || "",
+        cwd: s.cwd,
+        name: s.name,
+        created: new Date(s.startedAt).toISOString(),
+        modified: new Date(s.endedAt || s.startedAt).toISOString(),
+        messageCount: 0,
+        firstMessage: s.firstMessage,
+      }));
+    sendTo(ws, { type: "sessions_list", sessionId: "", cwd, sessions: filtered });
+  }
+}

package/packages/server/src/browser-handlers/subscription-handler.ts

@@ -0,0 +1,154 @@
+/**
+ * Subscription message handlers: subscribe, unsubscribe.
+ */
+import type { WebSocket } from "ws";
+import type { ServerToBrowserMessage, BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
+import type { BrowserHandlerContext } from "./handler-context.js";
+import { extractStatsFromEvents } from "../event-status-extraction.js";
+import type { StoredEvent } from "../memory-event-store.js";
+
+const REPLAY_BATCH_SIZE = 50;
+/** Max events to replay per session subscription (0 = unlimited) */
+const MAX_REPLAY_EVENTS = 0;
+/** Max buffered bytes before pausing replay sends (1MB) */
+const BACKPRESSURE_THRESHOLD = 1_024 * 1_024;
+
+/**
+ * Send stored events to a WebSocket in batches with backpressure handling.
+ * Yields between batches to let the event loop flush data and avoid OOM.
+ */
+/**
+ * Send stored events to a WebSocket in batches with backpressure handling.
+ * Returns the highest seq sent, or 0 if no events were sent.
+ */
+async function sendEventBatches(
+  ws: WebSocket,
+  sessionId: string,
+  stored: StoredEvent[],
+  sendTo: (ws: WebSocket, msg: ServerToBrowserMessage) => void,
+): Promise<number> {
+  for (let i = 0; i < stored.length; i += REPLAY_BATCH_SIZE) {
+    if (ws.readyState !== ws.OPEN) return 0;
+    const batch = stored.slice(i, i + REPLAY_BATCH_SIZE);
+    sendTo(ws, {
+      type: "event_replay",
+      sessionId,
+      events: batch.map((e) => ({ seq: e.seq, event: e.event })),
+      isLast: i + REPLAY_BATCH_SIZE >= stored.length,
+    });
+    // Yield to event loop between batches to allow GC and buffer flushing
+    if (ws.bufferedAmount > BACKPRESSURE_THRESHOLD) {
+      await new Promise<void>((resolve) => {
+        const check = () => {
+          if (ws.readyState !== ws.OPEN || ws.bufferedAmount < BACKPRESSURE_THRESHOLD) {
+            resolve();
+          } else {
+            setTimeout(check, 50);
+          }
+        };
+        setTimeout(check, 10);
+      });
+    } else {
+      await new Promise<void>((r) => setImmediate(r));
+    }
+  }
+  return stored.length > 0 ? stored[stored.length - 1].seq : 0;
+}
+
+export function handleSubscribe(
+  msg: Extract<BrowserToServerMessage, { type: "subscribe" }>,
+  subs: Set<string>,
+  ctx: BrowserHandlerContext,
+): void {
+  const { ws, sessionManager, eventStore, directoryService, piGateway, sendTo, broadcast, getSubscribers, replayPendingUiRequests, markReplaying, clearReplaying } = ctx;
+  subs.add(msg.sessionId);
+
+  // Request metadata from the extension so commands/flows/models/roles arrive
+  // while the browser is actually subscribed (responses use sendToSubscribers).
+  piGateway.sendToSession(msg.sessionId, { type: "request_commands", sessionId: msg.sessionId });
+  piGateway.sendToSession(msg.sessionId, { type: "request_models", sessionId: msg.sessionId });
+  piGateway.sendToSession(msg.sessionId, { type: "request_roles", sessionId: msg.sessionId });
+
+  if (eventStore.hasEvents(msg.sessionId)) {
+    const lastSeq = msg.lastSeq ?? 0;
+    const maxSeq = eventStore.getMaxSeq(msg.sessionId);
+
+    // Stale lastSeq: client has higher seq than server (e.g. server restarted)
+    if (lastSeq > 0 && lastSeq > maxSeq) {
+      sendTo(ws, { type: "session_state_reset", sessionId: msg.sessionId });
+      // Full replay from seq 1
+      let events = eventStore.getEvents(msg.sessionId, 1);
+      if (MAX_REPLAY_EVENTS > 0 && events.length > MAX_REPLAY_EVENTS) {
+        events = events.slice(events.length - MAX_REPLAY_EVENTS);
+      }
+      markReplaying(ws, msg.sessionId);
+      sendEventBatches(ws, msg.sessionId, events, sendTo).then((lastSent) => {
+        clearReplaying(ws, msg.sessionId, lastSent);
+        replayPendingUiRequests(ws, msg.sessionId);
+      });
+    } else {
+      let events = eventStore.getEvents(msg.sessionId, lastSeq + 1);
+      if (MAX_REPLAY_EVENTS > 0 && events.length > MAX_REPLAY_EVENTS) {
+        events = events.slice(events.length - MAX_REPLAY_EVENTS);
+      }
+      // Suppress live events during delta replay to prevent out-of-order delivery
+      if (lastSeq > 0 && events.length > 0) {
+        markReplaying(ws, msg.sessionId);
+        sendEventBatches(ws, msg.sessionId, events, sendTo).then((lastSent) => {
+          clearReplaying(ws, msg.sessionId, lastSent);
+          replayPendingUiRequests(ws, msg.sessionId);
+        });
+      } else {
+        sendEventBatches(ws, msg.sessionId, events, sendTo).then(() => {
+          replayPendingUiRequests(ws, msg.sessionId);
+        });
+      }
+    }
+  } else if (directoryService) {
+    const session = sessionManager.get(msg.sessionId);
+    if (session?.sessionFile) {
+      sendTo(ws, {
+        type: "event_replay",
+        sessionId: msg.sessionId,
+        events: [],
+        isLast: false,
+      });
+      directoryService.loadSessionEvents(msg.sessionId, session.sessionFile).then(async (result) => {
+        if (result.success) {
+          for (const evt of result.events) {
+            eventStore.insertEvent(msg.sessionId, evt);
+          }
+          const statsUpdates = extractStatsFromEvents(result.events);
+          const metaUpdates: Record<string, unknown> = { dataUnavailable: false, ...statsUpdates };
+          sessionManager.update(msg.sessionId, metaUpdates);
+          broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: metaUpdates });
+          let stored = eventStore.getEvents(msg.sessionId, 1);
+          if (MAX_REPLAY_EVENTS > 0 && stored.length > MAX_REPLAY_EVENTS) {
+            stored = stored.slice(stored.length - MAX_REPLAY_EVENTS);
+          }
+          const subscribers = getSubscribers(msg.sessionId);
+          for (const sub of subscribers) {
+            await sendEventBatches(sub, msg.sessionId, stored, sendTo);
+            replayPendingUiRequests(sub, msg.sessionId);
+          }
+        } else {
+          sendTo(ws, { type: "event_replay", sessionId: msg.sessionId, events: [], isLast: true });
+          sessionManager.update(msg.sessionId, { dataUnavailable: true });
+          broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { dataUnavailable: true } });
+        }
+      }).catch(() => {
+        sendTo(ws, { type: "event_replay", sessionId: msg.sessionId, events: [], isLast: true });
+        sessionManager.update(msg.sessionId, { dataUnavailable: true });
+        broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { dataUnavailable: true } });
+      });
+    } else {
+      sendTo(ws, { type: "event_replay", sessionId: msg.sessionId, events: [], isLast: true });
+      if (session) {
+        sessionManager.update(msg.sessionId, { dataUnavailable: true });
+        broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { dataUnavailable: true } });
+      }
+    }
+  } else {
+    sendTo(ws, { type: "event_replay", sessionId: msg.sessionId, events: [], isLast: true });
+  }
+}

package/packages/server/src/browser-handlers/terminal-handler.ts

@@ -0,0 +1,37 @@
+/**
+ * Terminal message handlers: create, kill, rename.
+ */
+import type { BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
+import type { BrowserHandlerContext } from "./handler-context.js";
+
+export function handleCreateTerminal(
+  msg: Extract<BrowserToServerMessage, { type: "create_terminal" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  const { terminalManager, sessionOrderManager, broadcast } = ctx;
+  if (terminalManager && sessionOrderManager) {
+    const terminal = terminalManager.spawn(msg.cwd);
+    sessionOrderManager.insert(msg.cwd, terminal.id);
+    broadcast({ type: "terminal_added", terminal });
+    broadcast({ type: "sessions_reordered", cwd: msg.cwd, sessionIds: sessionOrderManager.getOrder(msg.cwd) });
+  }
+}
+
+export function handleKillTerminal(
+  msg: Extract<BrowserToServerMessage, { type: "kill_terminal" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  if (ctx.terminalManager) {
+    try { ctx.terminalManager.kill(msg.terminalId); } catch { /* ignore */ }
+  }
+}
+
+export function handleRenameTerminal(
+  msg: Extract<BrowserToServerMessage, { type: "rename_terminal" }>,
+  ctx: BrowserHandlerContext,
+): void {
+  if (ctx.terminalManager) {
+    ctx.terminalManager.updateTitle(msg.terminalId, msg.title);
+    ctx.broadcast({ type: "terminal_updated", terminalId: msg.terminalId, updates: { title: msg.title } });
+  }
+}