the-campfire 0.1.0

package/server/routes/recording-routes.ts

@@ -0,0 +1,101 @@
+import type { Hono } from "hono";
+import type { RouteDeps } from "./route-deps.js";
+import { join } from "node:path";
+import { loadRecording, filterEntries } from "../replay.js";
+
+export function registerRecordingRoutes(api: Hono, deps: RouteDeps): void {
+  const { recorder, sessionStore } = deps;
+
+  api.post("/sessions/:id/recording/start", (c) => {
+    const id = c.req.param("id");
+    if (!recorder) return c.json({ error: "Recording not available" }, 501);
+    recorder.enableForSession(id);
+    return c.json({ ok: true, recording: true });
+  });
+
+  api.post("/sessions/:id/recording/stop", (c) => {
+    const id = c.req.param("id");
+    if (!recorder) return c.json({ error: "Recording not available" }, 501);
+    recorder.disableForSession(id);
+    return c.json({ ok: true, recording: false });
+  });
+
+  api.get("/sessions/:id/recording/status", (c) => {
+    const id = c.req.param("id");
+    if (!recorder) return c.json({ recording: false, available: false });
+    return c.json({
+      recording: recorder.isRecording(id),
+      available: true,
+      ...recorder.getRecordingStatus(id),
+    });
+  });
+
+  api.get("/recordings", (c) => {
+    if (!recorder) return c.json({ recordings: [] });
+    return c.json({ recordings: recorder.listRecordings() });
+  });
+
+  api.get("/recordings/:filename", (c) => {
+    if (!recorder) return c.json({ error: "Recording not available" }, 501);
+    const filename = c.req.param("filename");
+    if (filename.includes("/") || filename.includes("..")) {
+      return c.json({ error: "Invalid filename" }, 400);
+    }
+    const filePath = join(recorder.getRecordingsDir(), filename);
+    try {
+      const recording = loadRecording(filePath);
+
+      // Playable message types for the replay UI (expanded to cover all backends)
+      const PLAYABLE_TYPES = new Set([
+        "assistant", "result", "user_message", "stream_event",
+        "permission_request", "permission_cancelled", "status_change",
+        "session_init", "session_update", "cli_connected", "cli_disconnected",
+        "tool_progress", "tool_use_summary", "error",
+        "session_name_update", "mcp_status",
+      ]);
+
+      // Collect outgoing browser messages (server→browser)
+      const outEntries = filterEntries(recording.entries, "out", "browser");
+      // Collect incoming browser messages (browser→server) for user_message
+      const inEntries = filterEntries(recording.entries, "in", "browser");
+
+      // Merge both channels chronologically, filtering to playable types
+      const merged: { ts: number; parsed: unknown }[] = [];
+      for (const e of outEntries) {
+        try {
+          const parsed = JSON.parse(e.raw);
+          if (PLAYABLE_TYPES.has(parsed.type)) {
+            merged.push({ ts: e.ts, parsed });
+          }
+        } catch { /* skip malformed */ }
+      }
+      for (const e of inEntries) {
+        try {
+          const parsed = JSON.parse(e.raw);
+          if (parsed.type === "user_message") {
+            merged.push({ ts: e.ts, parsed });
+          }
+        } catch { /* skip malformed */ }
+      }
+
+      // Sort by timestamp
+      merged.sort((a, b) => a.ts - b.ts);
+
+      const messages = merged.map((m) => m.parsed);
+      const timestamps = merged.map((m) => m.ts);
+      return c.json({ header: recording.header, messages, timestamps });
+    } catch (err: any) {
+      return c.json({ error: err?.message || "Failed to load recording" }, 404);
+    }
+  });
+
+  api.get("/sessions/:id/history", (c) => {
+    const id = c.req.param("id");
+    const persisted = sessionStore.load(id);
+    if (!persisted) return c.json({ error: "Session not found" }, 404);
+    return c.json({
+      messages: persisted.messageHistory || [],
+      state: persisted.state || null,
+    });
+  });
+}

package/server/routes/route-deps.ts

@@ -0,0 +1,32 @@
+import type { Hono } from "hono";
+import type { CliLauncher } from "../cli-launcher.js";
+import type { WsBridge } from "../ws-bridge.js";
+import type { SessionStore } from "../session-store.js";
+import type { WorktreeTracker } from "../worktree-tracker.js";
+import type { TerminalManager } from "../terminal-manager.js";
+import type { PRPoller } from "../pr-poller.js";
+import type { RecorderManager } from "../recorder.js";
+import type { CronScheduler } from "../cron-scheduler.js";
+import type { WebhookManager } from "../webhook-manager.js";
+import type { AdapterRegistry } from "../adapter-registry.js";
+import type { AgentExecutor } from "../agent-executor.js";
+import type { ProtocolMonitor } from "../protocol-monitor.js";
+import type { AgentMcpBridge } from "../agent-mcp-bridge.js";
+
+export interface RouteDeps {
+  launcher: CliLauncher;
+  wsBridge: WsBridge;
+  sessionStore: SessionStore;
+  worktreeTracker: WorktreeTracker;
+  terminalManager: TerminalManager;
+  prPoller?: PRPoller;
+  recorder?: RecorderManager;
+  cronScheduler?: CronScheduler;
+  webhookManager?: WebhookManager;
+  adapterRegistry?: AdapterRegistry;
+  agentExecutor?: AgentExecutor;
+  protocolMonitor?: ProtocolMonitor;
+  agentMcpBridge?: AgentMcpBridge;
+}
+
+export type RegisterRoutes = (api: Hono, deps: RouteDeps) => void;

package/server/routes/session-routes.ts

@@ -0,0 +1,560 @@
+import type { Hono } from "hono";
+import type { RouteDeps } from "./route-deps.js";
+import * as envManager from "../env-manager.js";
+import { getSettings } from "../settings-manager.js";
+import * as gitUtils from "../git-utils.js";
+import * as sessionNames from "../session-names.js";
+import { containerManager, type ContainerConfig, type ContainerInfo } from "../container-manager.js";
+import { seedClaudeAuth } from "../claude-container-auth.js";
+import { seedCodexAuth } from "../codex-container-auth.js";
+import { pullImage, imageExistsLocally } from "../image-pull-manager.js";
+
+/**
+ * Resolve environment variables from an envSlug and inject global provider tokens.
+ * Returns the merged env vars (or undefined if none).
+ */
+function resolveEnvVars(
+  envSlug: string | undefined,
+  bodyEnv: Record<string, string> | undefined,
+  backend: string,
+): Record<string, string> | undefined {
+  let envVars: Record<string, string> | undefined = bodyEnv;
+
+  if (envSlug) {
+    const campfireEnv = envManager.getEnv(envSlug);
+    if (campfireEnv) {
+      console.log(
+        `[routes] Injecting env "${campfireEnv.name}" (${Object.keys(campfireEnv.variables).length} vars):`,
+        Object.keys(campfireEnv.variables).join(", "),
+      );
+      envVars = { ...campfireEnv.variables, ...bodyEnv };
+    } else {
+      console.warn(
+        `[routes] Environment "${envSlug}" not found, ignoring`,
+      );
+    }
+  }
+
+  const globalSettings = getSettings();
+  if (backend === "claude" && globalSettings.claudeOAuthToken && !envVars?.["CLAUDE_CODE_OAUTH_TOKEN"]) {
+    envVars = { ...envVars, CLAUDE_CODE_OAUTH_TOKEN: globalSettings.claudeOAuthToken };
+  }
+  if (backend === "codex" && globalSettings.openaiApiKey && !envVars?.["OPENAI_API_KEY"]) {
+    envVars = { ...envVars, OPENAI_API_KEY: globalSettings.openaiApiKey };
+  }
+  if (globalSettings.anthropicApiKey && !envVars?.["ANTHROPIC_API_KEY"]) {
+    envVars = { ...envVars, ANTHROPIC_API_KEY: globalSettings.anthropicApiKey };
+  }
+
+  return envVars;
+}
+
+interface WorktreeResult {
+  cwd: string;
+  worktreeInfo?: {
+    isWorktree: boolean;
+    repoRoot: string;
+    branch: string;
+    actualBranch: string;
+    worktreePath: string;
+  };
+}
+
+/**
+ * Set up a git worktree (or checkout a branch in-place) for a session.
+ * Returns the resolved cwd and optional worktreeInfo.
+ */
+function setupWorktree(
+  cwd: string,
+  branch: string | undefined,
+  useWorktree: boolean | undefined,
+  createBranch: boolean | undefined,
+): WorktreeResult {
+  if (!branch) return { cwd };
+
+  if (useWorktree) {
+    return createWorktreeForBranch(cwd, branch, createBranch);
+  }
+
+  checkoutBranchInPlace(cwd, branch);
+  return { cwd };
+}
+
+/** Create a git worktree for the given branch, returning updated cwd and worktreeInfo. */
+function createWorktreeForBranch(
+  cwd: string,
+  branch: string,
+  createBranch: boolean | undefined,
+): WorktreeResult {
+  const repoInfo = gitUtils.getRepoInfo(cwd);
+  if (!repoInfo) return { cwd };
+
+  const result = gitUtils.ensureWorktree(
+    repoInfo.repoRoot,
+    branch,
+    {
+      baseBranch: repoInfo.defaultBranch,
+      createBranch,
+      forceNew: true,
+    },
+  );
+  return {
+    cwd: result.worktreePath,
+    worktreeInfo: {
+      isWorktree: true,
+      repoRoot: repoInfo.repoRoot,
+      branch,
+      actualBranch: result.actualBranch,
+      worktreePath: result.worktreePath,
+    },
+  };
+}
+
+/** Checkout a branch in-place (fetch, checkout, pull). */
+function checkoutBranchInPlace(cwd: string, branch: string): void {
+  const repoInfo = gitUtils.getRepoInfo(cwd);
+  if (!repoInfo) return;
+
+  const fetchResult = gitUtils.gitFetch(repoInfo.repoRoot);
+  if (!fetchResult.success) {
+    throw new Error(`git fetch failed before session create: ${fetchResult.output}`);
+  }
+  if (repoInfo.currentBranch !== branch) {
+    gitUtils.checkoutBranch(repoInfo.repoRoot, branch);
+  }
+  const pullResult = gitUtils.gitPull(repoInfo.repoRoot);
+  if (!pullResult.success) {
+    console.warn(`[routes] git pull warning (non-fatal): ${pullResult.output}`);
+  }
+}
+
+/**
+ * Create a container and seed authentication credentials.
+ * Returns the ContainerInfo if a container was requested, undefined otherwise.
+ */
+function setupContainer(
+  containerOpts: { image?: string; ports?: unknown[]; volumes?: string[]; env?: Record<string, string> } | undefined,
+  cwd: string,
+  backend: string,
+): ContainerInfo | undefined {
+  if (!containerOpts) return undefined;
+
+  const cConfig: ContainerConfig = {
+    image: containerOpts.image || "campfire-dev:latest",
+    ports: Array.isArray(containerOpts.ports)
+      ? containerOpts.ports.map(Number).filter((n: number) => n > 0)
+      : [],
+    volumes: containerOpts.volumes,
+    env: containerOpts.env,
+  };
+  const containerId = crypto.randomUUID().slice(0, 8);
+  const containerInfo = containerManager.createContainer(containerId, cwd, cConfig);
+
+  if (backend === "claude") {
+    seedClaudeAuth(containerInfo.containerId);
+  } else if (backend === "codex") {
+    seedCodexAuth(containerInfo.containerId);
+  }
+
+  return containerInfo;
+}
+
+export function registerSessionRoutes(api: Hono, deps: RouteDeps): void {
+  const { launcher, wsBridge, sessionStore, worktreeTracker, prPoller } = deps;
+
+  api.post("/sessions/create", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      const backend = body.backend ?? "claude";
+      const validBackends = ["claude", "codex", "goose", "aider", "openhands", "openclaw", "opencode"];
+      if (!validBackends.includes(backend)) {
+        return c.json({ error: `Invalid backend: ${String(backend)}` }, 400);
+      }
+
+      const envVars = resolveEnvVars(body.envSlug, body.env, backend);
+
+      const worktreeResult: WorktreeResult = body.cwd
+        ? setupWorktree(body.cwd, body.branch, body.useWorktree, body.createBranch)
+        : { cwd: body.cwd };
+      const cwd = worktreeResult.cwd;
+      const worktreeInfo = worktreeResult.worktreeInfo;
+
+      const containerInfo = setupContainer(body.container, cwd, backend);
+
+      const session = launcher.launch({
+        model: body.model,
+        permissionMode: body.permissionMode,
+        cwd,
+        claudeBinary: body.claudeBinary,
+        codexBinary: body.codexBinary,
+        codexInternetAccess: backend === "codex" && body.codexInternetAccess === true,
+        codexSandbox: backend === "codex" && body.codexInternetAccess === true
+          ? "danger-full-access"
+          : "workspace-write",
+        codexReasoningEffort: backend === "codex" ? body.codexReasoningEffort : undefined,
+        allowedTools: body.allowedTools,
+        env: envVars,
+        backendType: backend,
+        worktreeInfo,
+        containerId: containerInfo?.containerId,
+      });
+
+      wsBridge.markSessionOrchestration(session.sessionId, {
+        role: session.orchestrationRole,
+        parentSessionId: session.parentSessionId,
+        detectedEnvironment: session.detectedEnvironment,
+      });
+
+      // Re-track container with real session ID
+      if (containerInfo) {
+        containerManager.retrack(containerInfo.containerId, session.sessionId);
+      }
+
+      // Track the worktree mapping
+      if (worktreeInfo) {
+        worktreeTracker.addMapping({
+          sessionId: session.sessionId,
+          repoRoot: worktreeInfo.repoRoot,
+          branch: worktreeInfo.branch,
+          actualBranch: worktreeInfo.actualBranch,
+          worktreePath: worktreeInfo.worktreePath,
+          createdAt: Date.now(),
+        });
+      }
+
+      return c.json(session);
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : "Unknown error";
+      console.error("[routes] Failed to create session:", msg);
+      return c.json({ error: msg }, 500);
+    }
+  });
+
+  api.get("/sessions", (c) => {
+    const sessions = launcher.listSessions();
+    const names = sessionNames.getAllNames();
+    const bridgeStates = wsBridge.getAllSessions();
+    const bridgeMap = new Map(bridgeStates.map((s) => [s.session_id, s]));
+    const enriched = sessions.map((s) => {
+      const bridge = bridgeMap.get(s.sessionId);
+      return {
+        ...s,
+        name: names[s.sessionId] ?? s.name,
+        gitBranch: bridge?.git_branch || "",
+        gitAhead: bridge?.git_ahead || 0,
+        gitBehind: bridge?.git_behind || 0,
+        totalLinesAdded: bridge?.total_lines_added || 0,
+        totalLinesRemoved: bridge?.total_lines_removed || 0,
+      };
+    });
+    return c.json(enriched);
+  });
+
+  api.get("/sessions/:id", (c) => {
+    const id = c.req.param("id");
+    const session = launcher.getSession(id);
+    if (!session) return c.json({ error: "Session not found" }, 404);
+    return c.json(session);
+  });
+
+  api.patch("/sessions/:id/name", async (c) => {
+    const id = c.req.param("id");
+    const body = await c.req.json().catch(() => ({}));
+    if (typeof body.name !== "string" || !body.name.trim()) {
+      return c.json({ error: "name is required" }, 400);
+    }
+    const session = launcher.getSession(id);
+    if (!session) return c.json({ error: "Session not found" }, 404);
+    sessionNames.setName(id, body.name.trim());
+    return c.json({ ok: true, name: body.name.trim() });
+  });
+
+  api.post("/sessions/:id/kill", async (c) => {
+    const id = c.req.param("id");
+    const killed = await launcher.kill(id);
+    if (!killed)
+      return c.json({ error: "Session not found or already exited" }, 404);
+    containerManager.removeContainer(id);
+    return c.json({ ok: true });
+  });
+
+  api.post("/sessions/:id/relaunch", async (c) => {
+    const id = c.req.param("id");
+    const ok = await launcher.relaunch(id);
+    if (!ok) return c.json({ error: "Session not found" }, 404);
+    return c.json({ ok: true });
+  });
+
+  api.delete("/sessions/:id", async (c) => {
+    const id = c.req.param("id");
+    await launcher.kill(id);
+    containerManager.removeContainer(id);
+    const worktreeResult = cleanupWorktree(worktreeTracker, id, true);
+    prPoller?.unwatch(id);
+    launcher.removeSession(id);
+    wsBridge.closeSession(id);
+    return c.json({ ok: true, worktree: worktreeResult });
+  });
+
+  api.post("/sessions/:id/archive", async (c) => {
+    const id = c.req.param("id");
+    const body = await c.req.json().catch(() => ({}));
+    await launcher.kill(id);
+    containerManager.removeContainer(id);
+    prPoller?.unwatch(id);
+    const worktreeResult = cleanupWorktree(worktreeTracker, id, body.force);
+    launcher.setArchived(id, true);
+    sessionStore.setArchived(id, true);
+    return c.json({ ok: true, worktree: worktreeResult });
+  });
+
+  api.post("/sessions/:id/unarchive", (c) => {
+    const id = c.req.param("id");
+    launcher.setArchived(id, false);
+    sessionStore.setArchived(id, false);
+    return c.json({ ok: true });
+  });
+
+  // ─── Fork ──────────────────────────────────────────────────────
+  api.post("/sessions/:id/fork", async (c) => {
+    const sourceId = c.req.param("id");
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      const liveSession = wsBridge.getSession(sourceId);
+      const persisted = sessionStore.load(sourceId);
+      const sourceHistory = liveSession?.messageHistory ?? persisted?.messageHistory ?? [];
+      const sourceState = liveSession?.state ?? persisted?.state ?? null;
+      if (!sourceState) {
+        return c.json({ error: "Source session not found" }, 404);
+      }
+
+      const messageIndex = typeof body.messageIndex === "number" ? body.messageIndex : sourceHistory.length;
+      const forkedHistory = sourceHistory.slice(0, messageIndex);
+
+      const backend = sourceState.backend_type || "claude";
+      const model = body.model || sourceState.model;
+      const permissionMode = body.permissionMode || sourceState.permissionMode;
+      const cwd = sourceState.cwd || process.cwd();
+
+      let worktreeInfo: { isWorktree: boolean; repoRoot: string; branch: string; actualBranch: string; worktreePath: string } | undefined;
+      let forkCwd = cwd;
+      const repoInfo = gitUtils.getRepoInfo(cwd);
+      if (repoInfo) {
+        const branchName = body.branch || repoInfo.currentBranch || "main";
+        const result = gitUtils.ensureWorktree(repoInfo.repoRoot, branchName, {
+          baseBranch: repoInfo.defaultBranch,
+          createBranch: true,
+          forceNew: true,
+        });
+        forkCwd = result.worktreePath;
+        worktreeInfo = {
+          isWorktree: true,
+          repoRoot: repoInfo.repoRoot,
+          branch: branchName,
+          actualBranch: result.actualBranch,
+          worktreePath: result.worktreePath,
+        };
+      }
+
+      const session = launcher.launch({
+        model,
+        permissionMode,
+        cwd: forkCwd,
+        backendType: backend,
+        worktreeInfo,
+      });
+
+      if (worktreeInfo) {
+        worktreeTracker.addMapping({
+          sessionId: session.sessionId,
+          repoRoot: worktreeInfo.repoRoot,
+          branch: worktreeInfo.branch,
+          actualBranch: worktreeInfo.actualBranch,
+          worktreePath: worktreeInfo.worktreePath,
+          createdAt: Date.now(),
+        });
+      }
+
+      wsBridge.seedMessageHistory(session.sessionId, forkedHistory);
+      return c.json({ ...session, forkedFrom: sourceId });
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : "Unknown error";
+      console.error("[routes] Failed to fork session:", msg);
+      return c.json({ error: msg }, 500);
+    }
+  });
+
+  // ─── Invite links ─────────────────────────────────────────────
+  api.post("/sessions/:id/invite", async (c) => {
+    const id = c.req.param("id");
+    let role: "owner" | "collaborator" | "spectator" = "collaborator";
+    try {
+      const body = await c.req.json();
+      if (body.role === "spectator" || body.role === "collaborator" || body.role === "owner") {
+        role = body.role;
+      }
+    } catch { /* no body, use default */ }
+    const token = wsBridge.createInviteToken(id, role);
+    if (!token) return c.json({ error: "Session not found" }, 404);
+
+    const protocol = c.req.header("x-forwarded-proto") || "http";
+    const host = c.req.header("host") || "localhost:4567";
+    const url = `${protocol}://${host}/#/join/${token}`;
+    return c.json({ token, url, role });
+  });
+
+  api.get("/sessions/join/:token", (c) => {
+    const token = c.req.param("token");
+    const sessionId = wsBridge.resolveInviteToken(token);
+    if (!sessionId) return c.json({ error: "Invalid or expired invite token" }, 404);
+    const role = wsBridge.resolveInviteTokenRole(token) || "collaborator";
+    return c.json({ session_id: sessionId, token, role });
+  });
+
+  // ─── Voting policy ──────────────────────────────────────────
+  api.get("/voting-policy", (c) => {
+    return c.json({ policy: wsBridge.getVotingPolicy() });
+  });
+
+  api.put("/voting-policy", async (c) => {
+    const body = await c.req.json();
+    const policy = body.policy;
+    if (policy !== "majority-rules" && policy !== "any-deny-blocks" && policy !== "owner-decides") {
+      return c.json({ error: "Invalid policy. Must be: majority-rules, any-deny-blocks, or owner-decides" }, 400);
+    }
+    wsBridge.setVotingPolicy(policy);
+    return c.json({ policy });
+  });
+
+  // ─── SSE session creation with progress ─────────────────────────────
+  api.post("/sessions/create-with-progress", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const backend = body.backend ?? "claude";
+    const image = body.container?.image || "campfire-dev:latest";
+
+    // Set up SSE stream
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+      async start(controller) {
+        function sendEvent(type: string, data: Record<string, unknown>) {
+          const msg = `event: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+          controller.enqueue(encoder.encode(msg));
+        }
+
+        try {
+          // Step 1: Check image
+          sendEvent("step", { step: "checking_image", message: `Checking image ${image}...` });
+          const exists = await imageExistsLocally(image);
+
+          // Step 2: Pull image if needed
+          if (!exists) {
+            sendEvent("step", { step: "pulling_image", message: `Pulling ${image}...` });
+            const pulled = await pullImage(image, (progress) => {
+              sendEvent("step", {
+                step: "pulling_image",
+                message: progress.message || progress.status,
+                percent: progress.percent,
+                layer: progress.layer,
+              });
+            });
+            if (!pulled) {
+              sendEvent("error", { error: `Failed to pull image ${image}` });
+              controller.close();
+              return;
+            }
+          }
+
+          // Step 3: Create container and seed auth
+          sendEvent("step", { step: "creating_container", message: "Creating container..." });
+          const cwd = body.cwd || process.cwd();
+          const containerInfo = setupContainer(body.container, cwd, backend);
+
+          if (containerInfo) {
+            sendEvent("step", { step: "seeding_auth", message: "Seeding authentication..." });
+          }
+
+          // Step 4: Launch agent
+          sendEvent("step", { step: "launching_agent", message: "Launching agent..." });
+
+          const envVars = resolveEnvVars(body.envSlug, body.env, backend);
+
+          const session = launcher.launch({
+            model: body.model,
+            permissionMode: body.permissionMode,
+            cwd,
+            claudeBinary: body.claudeBinary,
+            codexBinary: body.codexBinary,
+            codexInternetAccess: backend === "codex" && body.codexInternetAccess === true,
+            codexSandbox: backend === "codex" && body.codexInternetAccess === true
+              ? "danger-full-access"
+              : "workspace-write",
+            codexReasoningEffort: backend === "codex" ? body.codexReasoningEffort : undefined,
+            allowedTools: body.allowedTools,
+            env: envVars,
+            backendType: backend,
+            containerId: containerInfo?.containerId,
+          });
+
+          if (containerInfo) {
+            containerManager.retrack(containerInfo.containerId, session.sessionId);
+          }
+
+          sendEvent("done", { sessionId: session.sessionId, session });
+        } catch (err: unknown) {
+          const msg = err instanceof Error ? err.message : "Unknown error";
+          sendEvent("error", { error: msg });
+        } finally {
+          controller.close();
+        }
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+      },
+    });
+  });
+}
+
+// ─── Helper ─────────────────────────────────────────────────────────
+export function cleanupWorktree(
+  worktreeTracker: RouteDeps["worktreeTracker"],
+  sessionId: string,
+  force?: boolean,
+): { cleaned?: boolean; dirty?: boolean; path?: string } | undefined {
+  const mapping = worktreeTracker.getBySession(sessionId);
+  if (!mapping) return undefined;
+
+  if (worktreeTracker.isWorktreeInUse(mapping.worktreePath, sessionId)) {
+    worktreeTracker.removeBySession(sessionId);
+    return { cleaned: false, path: mapping.worktreePath };
+  }
+
+  const dirty = gitUtils.isWorktreeDirty(mapping.worktreePath);
+  if (dirty && !force) {
+    console.log(
+      `[routes] Worktree ${mapping.worktreePath} is dirty, not auto-removing`,
+    );
+    return { cleaned: false, dirty: true, path: mapping.worktreePath };
+  }
+
+  const branchToDelete =
+    mapping.actualBranch && mapping.actualBranch !== mapping.branch
+      ? mapping.actualBranch
+      : undefined;
+  const result = gitUtils.removeWorktree(
+    mapping.repoRoot,
+    mapping.worktreePath,
+    { force: dirty, branchToDelete },
+  );
+  if (result.removed) {
+    worktreeTracker.removeBySession(sessionId);
+    console.log(
+      `[routes] ${dirty ? "Force-removed dirty" : "Auto-removed clean"} worktree ${mapping.worktreePath}`,
+    );
+  }
+  return { cleaned: result.removed, path: mapping.worktreePath };
+}