pipeline-moe 0.1.0

package/src/server.ts

@@ -0,0 +1,1846 @@
+// Pipeline-MoE backend entry point.
+//
+// REST + SSE over Express. Manages a roster of stateful pi AgentSession
+// instances (one per participant) sharing a workspace, routes @mentions to
+// them via a serial queue, and streams everything to the UI over SSE.
+
+import { createHash } from "node:crypto"
+import { access, mkdir, readdir, readFile, stat, unlink, writeFile } from "node:fs/promises"
+import { readFileSync } from "node:fs"
+import { dirname, extname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import cors from "cors"
+import rateLimit from "express-rate-limit"
+import express, { Router } from "express"
+import { config } from "./config.js"
+
+/** Package root (this file lives in <root>/src) — anchors paths that must
+ *  work when installed as a dependency and run from an arbitrary cwd. */
+const packageRoot = () => resolve(dirname(fileURLToPath(import.meta.url)), "..")
+import { downgradeUnavailableModels, isAllowedModel, listModels, resolveModel, type ResolvedModel } from "./model.js"
+import { listWorkspace } from "./receipts.js"
+import { BASE_PROMPT, BUILDER_OVERLAY, PLANNER_OVERLAY, SEED_PERSONAS } from "./personas.js"
+import { Room } from "./room.js"
+import { RoomManager, type RoomDetails } from "./room-manager.js"
+import type { RoomOrchestrator } from "./orchestrator.js"
+import { SseHub } from "./sse.js"
+import { cleanupStaleMounts, isSshTarget, mountSshfs, unmountSshfs, type RoomMount } from "./sshfs.js"
+import type { Persona, PersonaState, RouteDecision } from "./types.js"
+import { parsePersona, VALID_TOOLS } from "./validation.js"
+
+/** Directory for saved user images (relative to workspace). */
+function mediaDir(): string {
+  return join(config.workspaceDir, "media")
+}
+
+/** Resolve a base64 data URI to a saved file path, returning the workspace-relative path. */
+async function saveImage(uri: string): Promise<string> {
+  // Parse "data:image/png;base64,ABCD" → { ext: "png", data: "ABCD" }
+  const match = uri.match(/^data:image\/(png|jpeg|webp|gif);base64,([A-Za-z0-9+\/=]+)$/)
+  if (!match) throw new Error(`unsupported image format: ${uri.slice(0, 30)}...`);
+  const [, ext, b64] = match
+  const hash = createHash("md5").update(b64).digest("hex").slice(0, 12)
+  const fileName = `${hash}.${ext}`
+  const filePath = join(mediaDir(), fileName)
+  await writeFile(filePath, Buffer.from(b64, "base64"))
+  return `media/${fileName}`
+}
+
+async function saveIncomingImages(images: unknown): Promise<string[]> {
+  if (!Array.isArray(images)) return []
+  const results: string[] = []
+  for (const uri of images) {
+    if (typeof uri !== "string") continue
+    try {
+      results.push(await saveImage(uri))
+    } catch (err) {
+      // Skip images that fail to save; the message still goes through.
+      console.warn(`[server] image save failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+  return results
+}
+
+
+// ── Preset I/O ──────────────────────────────────────────────────────────────
+
+/** A persona as persisted in a preset file — systemPrompt is optional since
+ *  seed personas rehydrate from SEED_PERSONAS at load time. */
+interface PresetPersona extends Omit<PersonaState, "systemPrompt"> {
+  systemPrompt?: string
+}
+
+/** A saved preset: roster configuration + metadata. */
+interface PresetFile {
+  name: string
+  personas: PresetPersona[]
+}
+
+function presetsDir(): string {
+  return join(config.workspaceDir, "presets")
+}
+
+function presetPath(name: string): string {
+  return join(presetsDir(), `${name}.json`)
+}
+
+async function listPresets(): Promise<PresetFile[]> {
+  await mkdir(presetsDir(), { recursive: true })
+  const files = await readdir(presetsDir())
+  const results: PresetFile[] = []
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue
+    try {
+      const content = await readFile(presetPath(f.replace(".json", "")), "utf-8")
+      const parsed = JSON.parse(content) as PresetFile
+      results.push(parsed)
+    } catch {
+      // Skip corrupt files
+    }
+  }
+  return results.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+async function readPreset(name: string): Promise<PresetFile | null> {
+  const path = presetPath(name)
+  try {
+    const content = await readFile(path, "utf-8")
+    return JSON.parse(content) as PresetFile
+  } catch {
+    return null
+  }
+}
+
+async function writePreset(preset: PresetFile): Promise<void> {
+  await mkdir(presetsDir(), { recursive: true })
+  const content = JSON.stringify(preset, null, 2)
+  await writeFile(presetPath(preset.name), content, "utf-8")
+}
+
+async function deletePreset(name: string): Promise<boolean> {
+  const path = presetPath(name)
+  try {
+    await unlink(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Strip systemPrompt from seed persona IDs so presets don't carry stale prompts. */
+function stripSeedPrompts(personas: (PersonaState | PresetPersona)[]): PresetPersona[] {
+  const seedIds = new Set(SEED_PERSONAS.map(p => p.id))
+  return personas.map(p => {
+    if (seedIds.has(p.id)) {
+      const { systemPrompt: _, ...rest } = p
+      return rest
+    }
+    return p as PresetPersona
+  })
+}
+
+/** Rehydrate systemPrompt from current SEED_PERSONAS for matching IDs. */
+function rehydratePrompts(personas: PresetPersona[]): PersonaState[] {
+  const seedMap = new Map(SEED_PERSONAS.map(p => [p.id, p]))
+  return personas.map(p => {
+    const seed = seedMap.get(p.id)
+    if (seed && !p.systemPrompt) {
+      return { ...p, systemPrompt: seed.systemPrompt }
+    }
+    return p as PersonaState
+  })
+}
+
+/** Re-seed any missing default presets (allows user deletion, restored on restart). */
+async function seedDefaultPresets(): Promise<void> {
+  const existing = await listPresets()
+  const existingNames = new Set(existing.map(p => p.name))
+
+  const localDefault: PresetFile = {
+    name: "local-default",
+    personas: stripSeedPrompts(SEED_PERSONAS.map(p => ({ ...p, active: true, parallel: false }))),
+  }
+
+  // Cloud-sprint: builder2 (Haiku), auditor (Sonnet), planner (Opus), tester (Sonnet)
+  const cloudSprint: PresetFile = {
+    name: "cloud-sprint",
+    personas: stripSeedPrompts([
+      {
+        id: "builder2",
+        name: "Builder2",
+        color: "#EF9F27",
+        icon: "🔨",
+        tools: ["read", "bash", "edit", "write", "grep", "find", "ls"],
+        systemPrompt: BASE_PROMPT + BUILDER_OVERLAY,
+        model: "anthropic/claude-haiku-4-20250719",
+        active: true,
+        parallel: true,
+      },
+      {
+        id: "auditor",
+        name: "Auditor",
+        color: "#AFA9EC",
+        icon: "🛡️",
+        tools: ["read", "grep", "find", "ls"],
+        model: "anthropic/claude-sonnet-4-20250514",
+        active: true,
+        parallel: true,
+      },
+      {
+        id: "planner",
+        name: "Planner",
+        color: "#4A90D9",
+        icon: "📋",
+        tools: ["read", "grep", "find", "ls"],
+        systemPrompt: BASE_PROMPT + PLANNER_OVERLAY,
+        model: "anthropic/claude-opus-4-6-20250603",
+        active: true,
+        parallel: true,
+      },
+      {
+        id: "tester",
+        name: "Tester",
+        color: "#97C459",
+        icon: "🧪",
+        tools: ["read", "bash", "grep", "find", "ls"],
+        model: "anthropic/claude-sonnet-4-20250514",
+        active: true,
+        parallel: true,
+      },
+    ]),
+  }
+
+  let seeded = 0
+  if (!existingNames.has("local-default")) {
+    await writePreset(localDefault)
+    seeded++
+  }
+  if (!existingNames.has("cloud-sprint")) {
+    await writePreset(cloudSprint)
+    seeded++
+  }
+  if (seeded > 0) {
+    console.log(`[presets] seeded ${seeded} default preset(s)`)
+  }
+}
+
+/** Build the provider list for SSE broadcast and API responses. */
+async function getProviderList(resolved: ResolvedModel, explicitlyEnabled: Set<string>) {
+  const allModels = resolved.modelRegistry.getAll()
+  const providerSet = new Set(allModels.map((m) => m.provider))
+  // Pre-compute which providers support OAuth login
+  const oauthProviderIds = new Set(
+    resolved.authStorage.getOAuthProviders().map((p) => p.id),
+  )
+  return Array.from(providerSet).map((name) => {
+    const authStatus = resolved.modelRegistry.getProviderAuthStatus(name)
+    const models = allModels
+      .filter((m) => m.provider === name)
+      .map((m) => ({ id: m.id, name: (m as { name?: string }).name ?? m.id }))
+    return {
+      name,
+      displayName: resolved.modelRegistry.getProviderDisplayName(name),
+      ...authStatus,
+      explicitlyEnabled: explicitlyEnabled.has(name),
+      supportsOAuth: oauthProviderIds.has(name),
+      models,
+    }
+  })
+}
+
+/** Error carrying an HTTP-style status so a route can map it to a response and
+ *  a tool can map it to error text. Thrown by provisionRoom(). */
+class RoomProvisionError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly details?: unknown,
+  ) {
+    super(message)
+    this.name = "RoomProvisionError"
+  }
+}
+
+async function main(): Promise<void> {
+  await mkdir(config.workspaceDir, { recursive: true })
+  await mkdir(mediaDir(), { recursive: true })
+
+  const resolved = await resolveModel()
+  const hub = new SseHub()
+
+  // Track providers the user has explicitly added via the API — their models
+  // appear in listModels() even when PIPELINE_ALLOW_CLOUD is false.
+  const explicitlyEnabledProviders = new Set<string>()
+
+  const roomManager = new RoomManager(resolved, hub, explicitlyEnabledProviders, SEED_PERSONAS)
+
+  // Preset loads downgrade unavailable models (stale cloud id, swapped local
+  // quant…) to the process default instead of blocking the whole load.
+  const downgradeModels = (personas: Array<{ name: string; model?: string }>) =>
+    downgradeUnavailableModels(personas, (m) => registry.isAllowedModel(m))
+
+  // Shared room-provisioning path used by both the POST /api/rooms route and the
+  // sub-room orchestrator (spawn_room tool). Single source of truth so the two
+  // entry points cannot drift on validation, mounting, preset resolution, or
+  // rollback. Throws RoomProvisionError(status, msg) on any failure.
+  async function provisionRoom(opts: {
+    roomId?: string
+    name: string
+    preset?: string
+    goal?: string
+    workspaceDir?: string
+    goalMode?: "auto" | "eval"
+    goalEvaluator?: string
+    maxGoalIterations?: number
+  }): Promise<RoomDetails> {
+    const name = opts.name.trim()
+    if (!name) throw new RoomProvisionError(400, "`name` is required")
+
+    const rawId = (opts.roomId ?? "").trim().replace(/[^a-zA-Z0-9_-]/g, "")
+    const roomId = rawId || `room-${Date.now().toString(36)}`
+    // Reject a duplicate roomId *before* any sshfs mount. The mountpoint is
+    // derived from roomId, so mounting for a duplicate would collide with the
+    // existing room's mountpoint and leak. Fail fast here instead.
+    if (roomManager.getRoom(roomId)) {
+      throw new RoomProvisionError(409, `Room "${roomId}" already exists`)
+    }
+
+    // Global concurrency cap. Counts ALL rooms (default included). Both entry
+    // points — POST /api/rooms and the spawn_room tool — flow through here, so
+    // the cap can't be bypassed. Reject before any sshfs mount so a refused
+    // spawn leaks no resources, and give the planner an actionable message.
+    if (roomManager.listRooms().length >= config.maxRooms) {
+      throw new RoomProvisionError(
+        429,
+        `room limit reached (${config.maxRooms}) — stop or destroy a room before creating another`,
+      )
+    }
+
+    const presetName = opts.preset?.trim() || undefined
+    const goal = opts.goal?.trim() || undefined
+    const workspaceDir = opts.workspaceDir?.trim() || undefined
+
+    // Per-room scope: local path or sshfs target. Empty = pipeline workspace.
+    let effectiveWorkspaceDir = workspaceDir
+    let mount: RoomMount | undefined
+    if (workspaceDir && isSshTarget(workspaceDir)) {
+      // Remote scope: mount now. Mounting can fail (auth, unreachable, bad path,
+      // sshfs missing) — surface a 400 before the room exists.
+      try {
+        const mountpoint = await mountSshfs(roomId, workspaceDir)
+        effectiveWorkspaceDir = mountpoint
+        mount = { mountpoint, sshTarget: workspaceDir }
+      } catch (err) {
+        throw new RoomProvisionError(400, err instanceof Error ? err.message : String(err))
+      }
+    } else if (workspaceDir) {
+      // Local scope: require an existing directory. A typo would silently make a
+      // broken room (empty listing, nonexistent bash cwd).
+      const scope = resolve(workspaceDir)
+      try {
+        const st = await stat(scope)
+        if (!st.isDirectory()) {
+          throw new RoomProvisionError(400, `workspaceDir "${scope}" is not a directory`)
+        }
+      } catch (err) {
+        if (err instanceof RoomProvisionError) throw err
+        throw new RoomProvisionError(400, `workspaceDir "${scope}" does not exist`)
+      }
+    }
+
+    try {
+      // Resolve preset roster if requested.
+      let overridePersonas: PersonaState[] | undefined
+      if (presetName) {
+        const presetFile = await readPreset(presetName)
+        if (!presetFile) throw new RoomProvisionError(404, `preset "${presetName}" not found`)
+        const personas = rehydratePrompts(presetFile.personas)
+        if (personas.length === 0) {
+          throw new RoomProvisionError(400, `preset "${presetName}" has no personas`)
+        }
+        // Unavailable models fall back to the default rather than failing room creation.
+        downgradeModels(personas)
+        overridePersonas = personas
+      }
+
+      const newRoom = roomManager.createRoom(roomId, name, overridePersonas, effectiveWorkspaceDir, mount)
+      await newRoom.init()
+
+      // Fire the goal BEFORE broadcasting "created": submitGoal sets the status to
+      // "running" synchronously, so the broadcast below carries an accurate
+      // goalStatus and the room tab shows the right badge from the start (a
+      // goal-less room stays "idle" instead of being mislabeled "running").
+      if (goal) {
+        newRoom.submitGoal(goal, {
+          mode: opts.goalMode,
+          evaluator: opts.goalEvaluator,
+          maxIterations: opts.maxGoalIterations,
+        })
+      }
+
+      hub.broadcast("room", {
+        type: "created",
+        roomId,
+        name,
+        participantCount: newRoom.rosterLength(),
+        goalStatus: newRoom.getGoalStatus(),
+      })
+
+      return roomManager.getRoomDetails(roomId)!
+    } catch (err) {
+      // Roll back after a successful mount. If the room reached the map (init
+      // threw), destroyRoom unmounts + removes it; otherwise unmount directly.
+      if (roomManager.getRoom(roomId)) {
+        await roomManager.destroyRoom(roomId).catch(() => {})
+      } else if (mount) {
+        await unmountSshfs(mount.mountpoint).catch(() => {})
+      }
+      if (err instanceof RoomProvisionError) throw err
+      const msg = err instanceof Error ? err.message : String(err)
+      throw new RoomProvisionError(msg.includes("already exists") ? 409 : 500, msg)
+    }
+  }
+
+  /** Clone a built-in seed persona into a room as a NEW participant with a unique
+   *  id ("builder" → "builder-2" → "builder-3") and a matching display name. Keeps
+   *  the template's tools, prompt, icon, color, and model — unless that model is
+   *  unavailable (e.g. cloud disabled), in which case it falls back to the room
+   *  default instead of failing the add. Returns the new roster item. */
+  async function addFromTemplate(room: Room, templateId: string) {
+    const tpl = SEED_PERSONAS.find((p) => p.id === templateId)
+    if (!tpl) throw new Error(`no persona template "${templateId}"`)
+    const reg = room.getRegistry()
+
+    let id = tpl.id
+    let n = 1
+    while (reg.has(id)) {
+      n++
+      id = `${tpl.id}-${n}`
+    }
+    const name = n === 1 ? tpl.name : `${tpl.name} ${n}`
+
+    const clone: Persona = { ...tpl, id, name }
+    if (clone.model && !reg.isAllowedModel(clone.model)) {
+      clone.model = undefined
+    }
+    await reg.create(clone)
+    return reg.roster().find((r) => r.id === id)
+  }
+
+  // Wire the sub-room orchestrator BEFORE any room is created, so participants
+  // built during room.init() receive spawn/check/destroy_room tools. The
+  // orchestrator closes over provisionRoom (preset + mount logic lives here).
+  const orchestrator: RoomOrchestrator = {
+    async spawnRoom(o) {
+      const d = await provisionRoom({
+        name: o.name,
+        goal: o.goal,
+        preset: o.preset,
+        workspaceDir: o.workspaceDir,
+        goalMode: o.goalMode,
+        goalEvaluator: o.goalEvaluator,
+        maxGoalIterations: o.maxGoalIterations,
+      })
+      return { roomId: d.roomId, name: d.name, goalStatus: d.goalStatus }
+    },
+    checkRoom(roomId) {
+      const r = roomManager.getRoom(roomId)
+      if (!r) return { found: false, roomId }
+      const details = roomManager.getRoomDetails(roomId)
+      const lastMessages = r.getTranscript().slice(-5).map((e) => `${e.authorName}: ${e.text}`)
+      return {
+        found: true,
+        roomId,
+        name: details?.name,
+        goalStatus: r.getGoalStatus(),
+        goalText: r.getGoalText(),
+        lastMessages,
+      }
+    },
+    async stopRoom(roomId) {
+      // The default room is the planner's OWN room — stopping it would abort the
+      // planner mid-turn. Protect it; stop_room is for sub-rooms only.
+      if (roomId === "default") return false
+      const r = roomManager.getRoom(roomId)
+      if (!r) return false
+      await r.abortCurrent()
+      hub.broadcast("room", { type: "stopped", roomId })
+      return true
+    },
+    async destroyRoom(roomId) {
+      if (roomId === "default") return false
+      const removed = await roomManager.destroyRoom(roomId)
+      if (removed) hub.broadcast("room", { type: "destroyed", roomId })
+      return removed
+    },
+  }
+  roomManager.setOrchestrator(orchestrator)
+
+  const room = roomManager.createDefaultRoom()
+  const registry = room.getRegistry()
+
+  // Load the most recent saved discussion, or seed a fresh one.
+  await room.init()
+  await seedDefaultPresets()
+  console.log(`[room] roster: ${registry.roster().length} participants`)
+
+  // Re-create rooms that were created in a previous run. The Map is in-memory;
+  // the manifest (sessions/rooms.json) is the durable record. Default room is
+  // already created above — restoreRooms only adds the others (and restores a
+  // renamed default name). sshfs rooms are re-mounted here.
+  //
+  // First clear any mounts leaked by a prior process that was killed before
+  // teardown — otherwise a resume/restore that re-mounts the same deterministic
+  // path fails with "fusermount3: … Permission denied". restoreRooms re-mounts
+  // the rooms that are still valid right after.
+  await cleanupStaleMounts()
+  await roomManager.restoreRooms()
+
+  const app = express()
+  app.use(cors({ origin: config.corsOrigins }))
+  app.use(express.json({ limit: "5mb" }))
+
+  app.get("/api/health", (_req, res) => {
+    res.json({ ok: true, workspace: config.workspaceDir, clients: hub.clientCount })
+  })
+
+  // ── Presets ────────────────────────────────────────────────────────────────
+
+  // Preset save/load/apply shared by the default-room (/api) and room-scoped
+  // (/api/rooms/:id) routes, so an action targets the room you're viewing
+  // — not always the default room.
+  const doSavePreset = async (r: Room, name: string, res: express.Response): Promise<void> => {
+    if (!name) {
+      res.status(400).json({ error: "`name` is required (alphanumeric, dash, underscore)" })
+      return
+    }
+    if (r.isBusy()) {
+      res.status(409).json({ error: "a turn is running — press Stop before saving a preset" })
+      return
+    }
+    try {
+      const personas = stripSeedPrompts(r.getRegistry().personaStates())
+      const preset: PresetFile = { name, personas }
+      await writePreset(preset)
+      res.status(201).json(preset)
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  }
+
+  const doLoadPreset = async (r: Room, name: string, res: express.Response): Promise<void> => {
+    if (r.isBusy()) {
+      res.status(409).json({ error: "a turn is running — press Stop before loading a preset" })
+      return
+    }
+    try {
+      const preset = await readPreset(name)
+      if (!preset) {
+        res.status(404).json({ error: `preset "${name}" not found` })
+        return
+      }
+      const personas = rehydratePrompts(preset.personas)
+      if (personas.length === 0) {
+        res.status(400).json({ error: `preset "${name}" has no personas — would brick the session` })
+        return
+      }
+      // Unavailable models (stale cloud id, swapped local quant…) fall back to the
+      // default instead of blocking the whole preset — the human is told which.
+      const downgraded = downgradeModels(personas)
+      const meta = await r.loadPreset(personas, `${name} — ${new Date().toLocaleTimeString()}`)
+      res.json({ ok: true, conversation: meta, downgraded })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      res.status(msg.includes("unknown") ? 404 : 409).json({ error: msg })
+    }
+  }
+
+  const doApplyPreset = async (r: Room, name: string, res: express.Response): Promise<void> => {
+    if (r.isBusy()) {
+      res.status(409).json({ error: "a turn is running — press Stop before applying a preset" })
+      return
+    }
+    try {
+      const preset = await readPreset(name)
+      if (!preset) {
+        res.status(404).json({ error: `preset "${name}" not found` })
+        return
+      }
+      const personas = rehydratePrompts(preset.personas)
+      if (personas.length === 0) {
+        res.status(400).json({ error: `preset "${name}" has no personas — would brick the session` })
+        return
+      }
+      const downgraded = downgradeModels(personas)
+      const meta = await r.applyPreset(personas)
+      res.json({ ok: true, conversation: meta, downgraded })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      res.status(msg.includes("unknown") ? 404 : 409).json({ error: msg })
+    }
+  }
+
+  app.get("/api/presets", async (_req, res) => {
+    try {
+      const presets = await listPresets()
+      res.json(presets)
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  app.post("/api/presets", async (req, res) => {
+    const name = String(req.body?.name ?? "").trim().replace(/[^a-zA-Z0-9_-]/g, "")
+    await doSavePreset(room, name, res)
+  })
+
+  app.delete("/api/presets/:name", async (req, res) => {
+    const name = req.params.name
+    const deleted = await deletePreset(name)
+    if (!deleted) {
+      res.status(404).json({ error: `preset "${name}" not found` })
+      return
+    }
+    res.status(204).end()
+  })
+
+  app.post("/api/presets/:name/load", (req, res) => doLoadPreset(room, req.params.name, res))
+
+  // ── Apply preset roster to current room (in-place, no new conversation) ──
+
+  app.post("/api/presets/:name/apply", (req, res) => doApplyPreset(room, req.params.name, res))
+
+  // Serve saved images from the media directory.
+  app.get("/api/media/:filename", async (req, res) => {
+    const filename = req.params.filename
+    const ext = extname(filename).toLowerCase()
+    const allowed = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"])
+    if (!allowed.has(ext)) {
+      res.status(400).json({ error: "unsupported file type" })
+      return
+    }
+    const filePath = join(mediaDir(), filename)
+    try {
+      await access(filePath)
+      res.sendFile(filePath)
+    } catch {
+      res.status(404).json({ error: "image not found" })
+    }
+  })
+
+  // SSE stream of all room events.
+  // Global (unfiltered) SSE stream. Consumed by App.tsx for process-wide `room`
+  // lifecycle events (created/destroyed/renamed/goal-*), which are broadcast
+  // without a roomId and so must reach a non-room-filtered subscriber. Per-room
+  // UI state uses /api/rooms/:roomId/events instead.
+  app.get("/api/events", (_req, res) => {
+    hub.addClient(res)
+    // Write the current roster directly to *this* connecting client. Using
+    // hub.broadcast() here would push the default room's roster to every
+    // room-filtered client, clobbering their roster on any new connection.
+    res.write(`event: roster\ndata: ${JSON.stringify(registry.roster())}\n\n`)
+  })
+
+  app.get("/api/participants", (_req, res) => {
+    res.json(registry.roster())
+  })
+
+  // Built-in persona templates for the "Add agent" picker — clone one into a room
+  // (e.g. a second builder) without rebuilding it or loading a whole preset.
+  app.get("/api/persona-templates", (_req, res) => {
+    res.json(
+      SEED_PERSONAS.map((p) => ({
+        id: p.id, name: p.name, color: p.color, icon: p.icon, tools: p.tools, model: p.model,
+      })),
+    )
+  })
+
+  // Models offered for per-agent selection (local-only unless PIPELINE_ALLOW_CLOUD,
+  // or the provider has been explicitly enabled by the user via /api/providers).
+  app.get("/api/models", (_req, res) => {
+    const models = listModels(resolved, room.getAllowCloud(), explicitlyEnabledProviders)
+    res.json({ models, allowCloud: room.getAllowCloud() })
+  })
+
+  // ── Providers ──────────────────────────────────────────────────────────────
+
+  // List all known providers with their auth status (no secrets exposed).
+  app.get("/api/providers", (_req, res) => {
+    const allModels = resolved.modelRegistry.getAll()
+    const providerSet = new Set(allModels.map((m) => m.provider))
+    const providers = Array.from(providerSet).map((name) => {
+      const authStatus = resolved.modelRegistry.getProviderAuthStatus(name)
+      const models = allModels
+        .filter((m) => m.provider === name)
+        .map((m) => ({ id: m.id, name: (m as { name?: string }).name ?? m.id }))
+      return {
+        name,
+        displayName: resolved.modelRegistry.getProviderDisplayName(name),
+        ...authStatus,
+        explicitlyEnabled: explicitlyEnabledProviders.has(name),
+        models,
+      }
+    })
+    res.json({ providers, explicitlyEnabled: Array.from(explicitlyEnabledProviders) })
+  })
+
+  // Set an API key for a provider (persisted to auth.json).
+  app.post("/api/providers/:name", async (req, res) => {
+    const name = req.params.name
+    const body = req.body ?? {}
+
+    if (!body.key || typeof body.key !== "string") {
+      res.status(400).json({ error: "`key` is required (string)" })
+      return
+    }
+    if (room.isBusy()) {
+      res.status(409).json({ error: "a turn is running — press Stop before changing provider credentials" })
+      return
+    }
+
+    // Verify the provider exists in the registry
+    const allModels = resolved.modelRegistry.getAll()
+    const providerExists = allModels.some((m) => m.provider === name)
+    if (!providerExists && !body.baseUrl) {
+      res.status(404).json({ error: `provider "${name}" not found in model registry` })
+      return
+    }
+
+    try {
+      resolved.authStorage.set(name, { type: "api_key", key: body.key })
+      explicitlyEnabledProviders.add(name)
+      // Refresh so getAvailable() picks up the new models immediately
+      resolved.modelRegistry.refresh()
+
+      // Broadcast updated provider list to SSE clients
+      hub.broadcast("providers", {
+        providers: await getProviderList(resolved, explicitlyEnabledProviders),
+        explicitlyEnabled: Array.from(explicitlyEnabledProviders),
+      })
+
+      // Return only the auth status — never the key
+      const status = resolved.modelRegistry.getProviderAuthStatus(name)
+      res.status(200).json({ name, ...status })
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  // Start OAuth login flow for a provider (device-code or auth URL).
+  app.post("/api/providers/:name/login", async (req, res) => {
+    const name = req.params.name
+    const oauthProviders = resolved.authStorage.getOAuthProviders()
+    const oauthProvider = oauthProviders.find((p) => p.id === name)
+    if (!oauthProvider) {
+      res.status(404).json({ error: `provider "${name}" does not support OAuth login` })
+      return
+    }
+    if (room.isBusy()) {
+      res.status(409).json({ error: "a turn is running — press Stop before starting OAuth login" })
+      return
+    }
+
+    // Start the login flow in the background — communicate progress via SSE.
+    // Return 202 immediately so the client can wait for SSE events.
+    const providerName = name // capture for closure
+    setImmediate(async () => {
+      try {
+        await resolved.authStorage.login(name, {
+          onDeviceCode: (info) => {
+            hub.broadcast("oauth_progress", {
+              provider: providerName,
+              type: "device_code",
+              userCode: info.userCode,
+              verificationUri: info.verificationUri,
+            })
+          },
+          onAuth: (info) => {
+            hub.broadcast("oauth_progress", {
+              provider: providerName,
+              type: "auth_url",
+              url: info.url,
+              instructions: info.instructions,
+            })
+          },
+          onProgress: (message) => {
+            hub.broadcast("oauth_progress", {
+              provider: providerName,
+              type: "progress",
+              message,
+            })
+          },
+          onPrompt: async (prompt) => {
+            // For headless: reject prompts that require user input
+            hub.broadcast("oauth_progress", {
+              provider: providerName,
+              type: "error",
+              message: `OAuth requires interactive prompt: "${prompt.message}" — use the pi CLI for this provider.`,
+            })
+            throw new Error("interactive prompt not supported in headless mode")
+          },
+          onSelect: async () => {
+            hub.broadcast("oauth_progress", {
+              provider: providerName,
+              type: "error",
+              message: "OAuth requires a selection — use the pi CLI for this provider.",
+            })
+            throw new Error("interactive selection not supported in headless mode")
+          },
+        })
+
+        // Success — broadcast updated provider list
+        resolved.modelRegistry.refresh()
+        hub.broadcast("providers", {
+          providers: await getProviderList(resolved, explicitlyEnabledProviders),
+          explicitlyEnabled: Array.from(explicitlyEnabledProviders),
+        })
+        hub.broadcast("oauth_progress", {
+          provider: providerName,
+          type: "success",
+          message: `Authenticated with ${providerName}.`,
+        })
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        hub.broadcast("oauth_progress", {
+          provider: providerName,
+          type: "error",
+          message: msg,
+        })
+      }
+    })
+
+    res.status(202).json({ accepted: true, provider: name })
+  })
+
+  // Remove credentials for a provider.
+  app.delete("/api/providers/:name", async (req, res) => {
+    const name = req.params.name
+    if (name === "local") {
+      res.status(400).json({ error: "cannot remove the local provider" })
+      return
+    }
+    if (room.isBusy()) {
+      res.status(409).json({ error: "a turn is running — press Stop before changing provider credentials" })
+      return
+    }
+
+    // Check if any active participant uses this provider
+    const roster = registry.roster()
+    const agentsUsing = roster.filter((p) => {
+      const model = p.model
+      return model && model.startsWith(`${name}/`)
+    }).map((p) => p.name)
+
+    try {
+      resolved.authStorage.remove(name)
+      explicitlyEnabledProviders.delete(name)
+      resolved.modelRegistry.refresh()
+
+      hub.broadcast("providers", {
+        providers: await getProviderList(resolved, explicitlyEnabledProviders),
+        explicitlyEnabled: Array.from(explicitlyEnabledProviders),
+      })
+
+      const status = resolved.modelRegistry.getProviderAuthStatus(name)
+      res.status(200).json({ name, ...status, agentsUsing })
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  app.post("/api/participants", async (req, res) => {
+    try {
+      const persona = parsePersona(req.body ?? {})
+      if (registry.has(persona.id)) {
+        res.status(409).json({ error: `participant "${persona.id}" already exists` })
+        return
+      }
+      await registry.create(persona)
+      res.status(201).json(registry.roster().find((r) => r.id === persona.id))
+    } catch (err) {
+      res.status(400).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  app.post("/api/participants/from-template", async (req, res) => {
+    try {
+      const item = await addFromTemplate(room, String(req.body?.templateId ?? ""))
+      res.status(201).json(item)
+    } catch (err) {
+      res.status(400).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  // Reorder the roster (first-turn / @all execution order). Registered before
+  // the "/:id" routes so "reorder" is never parsed as an id.
+  app.post("/api/participants/reorder", (req, res) => {
+    const order = req.body?.order
+    if (!Array.isArray(order) || !order.every((x: unknown) => typeof x === "string")) {
+      res.status(400).json({ error: "`order` must be an array of participant ids" })
+      return
+    }
+    registry.reorder(order as string[])
+    res.json(registry.roster())
+  })
+
+  // Full persona (incl. systemPrompt) for the edit form.
+  app.get("/api/participants/:id", (req, res) => {
+    const p = registry.get(req.params.id)
+    if (!p) {
+      res.status(404).json({ error: `unknown participant "${req.params.id}"` })
+      return
+    }
+    res.json({ ...p.persona, availableThinkingLevels: p.getAvailableThinkingLevels() })
+  })
+
+  // Activate / deactivate AND edit persona (name, prompt, tools, color, icon).
+  app.patch("/api/participants/:id", async (req, res) => {
+    const { id } = req.params
+    if (!registry.has(id)) {
+      res.status(404).json({ error: `unknown participant "${id}"` })
+      return
+    }
+    const body = req.body ?? {}
+
+    // Build a persona patch from any editable fields present in the body.
+    const patch: Record<string, unknown> = {}
+    if (typeof body.name === "string" && body.name.trim()) patch.name = body.name.trim()
+    if (typeof body.systemPrompt === "string" && body.systemPrompt.trim())
+      patch.systemPrompt = body.systemPrompt.trim()
+    if (typeof body.color === "string") patch.color = body.color
+    if (typeof body.icon === "string") patch.icon = body.icon
+    if (Array.isArray(body.tools))
+      patch.tools = body.tools.map(String).filter((t: string) => VALID_TOOLS.has(t))
+    const VALID_THINKING = new Set(["off", "minimal", "low", "medium", "high", "xhigh"])
+    if ("thinkingLevel" in body) {
+      const tv = body.thinkingLevel
+      if (tv === null || tv === "") {
+        patch.thinkingLevel = undefined // reset to the global default
+      } else if (typeof tv === "string" && VALID_THINKING.has(tv)) {
+        patch.thinkingLevel = tv
+      } else {
+        res.status(400).json({ error: `invalid thinkingLevel "${String(tv)}" — must be one of: off, minimal, low, medium, high, xhigh` })
+        return
+      }
+    }
+    if ("model" in body) {
+      const mv = body.model
+      if (mv === null || mv === "") {
+        patch.model = undefined // reset to the process default model
+      } else if (typeof mv === "string" && registry.isAllowedModel(mv)) {
+        patch.model = mv
+      } else {
+        res.status(400).json({
+          error: room.getAllowCloud()
+            ? `unknown model "${String(mv)}"`
+            : `model "${String(mv)}" unavailable — cloud is disabled (toggle in Settings)`,
+        })
+        return
+      }
+    }
+    if ("compactionInstructions" in body) {
+      const ci = body.compactionInstructions
+      if (ci === null || ci === "") {
+        patch.compactionInstructions = undefined
+      } else if (typeof ci === "string" && ci.length <= 500) {
+        patch.compactionInstructions = ci
+      } else if (typeof ci === "string") {
+        res.status(400).json({ error: `compactionInstructions too long (${ci.length} chars, max 500)` })
+        return
+      } else {
+        res.status(400).json({ error: "compactionInstructions must be a string" })
+        return
+      }
+    }
+
+    try {
+      if (typeof body.active === "boolean") registry.setActive(id, body.active)
+      if (typeof body.parallel === "boolean") registry.setParallel(id, body.parallel)
+      if (Object.keys(patch).length > 0) {
+        // Fast path: thinkingLevel-only change → in-place, no session recreation.
+        if (Object.keys(patch).length === 1 && "thinkingLevel" in patch && patch.thinkingLevel !== undefined) {
+          const level = patch.thinkingLevel as "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
+          await registry.setThinkingLevel(id, level)
+        } else {
+          // Heavy path: dispose + recreate session.
+          if (room.isBusy()) {
+            res.status(409).json({ error: "a turn is running — press Stop before editing an agent" })
+            return
+          }
+          await registry.update(id, patch)
+        }
+      }
+      res.json(registry.roster().find((r) => r.id === id))
+    } catch (err) {
+      res.status(400).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  app.delete("/api/participants/:id", (req, res) => {
+    const { id } = req.params
+    if (!registry.has(id)) {
+      res.status(404).json({ error: `unknown participant "${id}"` })
+      return
+    }
+    registry.kick(id)
+    res.status(204).end()
+  })
+
+  app.get("/api/transcript", (_req, res) => {
+    res.json(room.getTranscript())
+  })
+
+  app.get("/api/workspace", async (_req, res) => {
+    res.json(await listWorkspace(config.workspaceDir))
+  })
+
+  // ── Conversations (saved group discussions) ───────────────────────────────
+  app.get("/api/conversations", async (_req, res) => {
+    res.json(await room.getConversations())
+  })
+
+  app.post("/api/conversations", async (req, res) => {
+    try {
+      const title = req.body?.title ? String(req.body.title) : undefined
+      res.status(201).json(await room.newConversation(title))
+    } catch (err) {
+      res.status(409).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  app.post("/api/conversations/:id/load", async (req, res) => {
+    try {
+      await room.switchConversation(req.params.id)
+      res.json({ ok: true })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      res.status(msg.includes("unknown") ? 404 : 409).json({ error: msg })
+    }
+  })
+
+  app.patch("/api/conversations/:id", async (req, res) => {
+    const title = String(req.body?.title ?? "").trim()
+    if (!title) {
+      res.status(400).json({ error: "`title` is required" })
+      return
+    }
+    try {
+      await room.renameConversation(req.params.id, title)
+      res.json({ ok: true })
+    } catch (err) {
+      res.status(404).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  app.delete("/api/conversations/:id", async (req, res) => {
+    try {
+      await room.deleteConversation(req.params.id)
+      res.status(204).end()
+    } catch (err) {
+      res.status(409).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  const settingsPayload = (r: Room) => ({
+    chaining: r.getChaining(),
+    routingMode: r.getRoutingMode(),
+    defaultAgent: r.getDefaultAgent(),
+    fallbackAgent: r.getFallbackAgent(),
+    maxChainHops: r.getMaxChainHops(),
+    circuitBreaker: r.getCircuitBreaker(),
+    defaultThinkingLevel: r.getDefaultThinkingLevel(),
+    allowCloud: r.getAllowCloud(),
+    compactionReserveTokens: r.getCompactionReserveTokens(),
+    maxRooms: config.maxRooms,
+    pendingRoute: r.getPendingRoute(),
+  })
+
+  const parseRouteDecision = (body: Record<string, unknown>): RouteDecision | null => {
+    const action = body?.action
+    if (action !== "approve" && action !== "redirect" && action !== "drop") return null
+    const targetIds = Array.isArray(body?.targetIds) ? body.targetIds.map(String) : undefined
+    return { action, targetIds }
+  }
+
+  app.get("/api/settings", (_req, res) => {
+    res.json(settingsPayload(room))
+  })
+
+  app.patch("/api/settings", (req, res) => {
+    const body = req.body ?? {}
+    if ("chaining" in body) {
+      if (typeof body.chaining !== "boolean") {
+        res.status(400).json({ error: "`chaining` must be a boolean" })
+        return
+      }
+      room.setChaining(body.chaining)
+    }
+    if ("defaultAgent" in body) {
+      const da = body.defaultAgent
+      if (da !== null && typeof da !== "string") {
+        res.status(400).json({ error: "`defaultAgent` must be a string id or null" })
+        return
+      }
+      try {
+        room.setDefaultAgent(da)
+      } catch (err) {
+        res.status(404).json({ error: err instanceof Error ? err.message : String(err) })
+        return
+      }
+    }
+    if ("fallbackAgent" in body) {
+      const fa = body.fallbackAgent
+      if (fa !== null && typeof fa !== "string") {
+        res.status(400).json({ error: "`fallbackAgent` must be a string id or null" })
+        return
+      }
+      try {
+        room.setFallbackAgent(fa)
+      } catch (err) {
+        res.status(404).json({ error: err instanceof Error ? err.message : String(err) })
+        return
+      }
+    }
+    if ("maxChainHops" in body) {
+      const n = body.maxChainHops
+      if (typeof n !== "number" || n < 1 || n > 100) {
+        res.status(400).json({ error: "`maxChainHops` must be a number between 1 and 100" })
+        return
+      }
+      room.setMaxChainHops(n)
+    }
+    if ("routingMode" in body) {
+      const m = body.routingMode
+      if (m !== "auto" && m !== "semi" && m !== "manual") {
+        res.status(400).json({ error: "`routingMode` must be 'auto', 'semi', or 'manual'" })
+        return
+      }
+      room.setRoutingMode(m)
+    }
+    if ("circuitBreaker" in body) {
+      if (typeof body.circuitBreaker !== "boolean") {
+        res.status(400).json({ error: "`circuitBreaker` must be a boolean" })
+        return
+      }
+      room.setCircuitBreaker(body.circuitBreaker)
+    }
+    if ("defaultThinkingLevel" in body) {
+      const validLevels = ["off", "minimal", "low", "medium", "high", "xhigh"]
+      if (!validLevels.includes(body.defaultThinkingLevel)) {
+        res.status(400).json({ error: "`defaultThinkingLevel` must be one of: " + validLevels.join(", ") })
+        return
+      }
+      room.setDefaultThinkingLevel(body.defaultThinkingLevel)
+    }
+    if ("allowCloud" in body) {
+      if (typeof body.allowCloud !== "boolean") {
+        res.status(400).json({ error: "`allowCloud` must be a boolean" })
+        return
+      }
+      room.setAllowCloud(body.allowCloud)
+    }
+    if ("compactionReserveTokens" in body) {
+      const v = Number(body.compactionReserveTokens)
+      if (!Number.isFinite(v) || v < 5000 || v > 100000) {
+        res.status(400).json({ error: "`compactionReserveTokens` must be an integer between 5000 and 100000" })
+        return
+      }
+      room.setCompactionReserveTokens(v)
+    }
+    res.json(settingsPayload(room))
+  })
+
+  app.post("/api/route", (req, res) => {
+    const decision = parseRouteDecision(req.body ?? {})
+    if (!decision) {
+      res.status(400).json({ error: "`action` must be 'approve', 'redirect', or 'drop'" })
+      return
+    }
+    room.resolveRoute(decision)
+    res.status(202).json({ accepted: true })
+  })
+
+  // Post a message to the room. Returns immediately; results stream over SSE.
+  // Rate limited to prevent agent loops from flooding the queue.
+  app.post("/api/messages", rateLimit({ windowMs: 60_000, max: 60, standardHeaders: true, legacyHeaders: false }), async (req, res) => {
+    const text = String(req.body?.text ?? "").trim()
+    if (!text) {
+      res.status(400).json({ error: "`text` is required" })
+      return
+    }
+    // Save images and resolve to workspace-relative paths.
+    const images = await saveIncomingImages(req.body?.images)
+    room.submit(text, images.length > 0 ? images : undefined)
+    res.status(202).json({ accepted: true })
+  })
+
+  // Compact a specific agent's session context.
+  app.post("/api/participants/:id/compact", async (req, res) => {
+    const { id } = req.params
+    const p = registry.get(id)
+    if (!p) {
+      res.status(404).json({ error: `unknown participant "${id}"` })
+      return
+    }
+    if (room.isBusy()) {
+      res.status(409).json({ error: "a turn is running — press Stop before compacting" })
+      return
+    }
+    try {
+      const result = await p.compact()
+      res.json(result)
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  // Export agent's session as self-contained HTML.
+  app.get("/api/participants/:id/export", async (req, res) => {
+    const { id } = req.params
+    const p = registry.get(id)
+    if (!p) {
+      res.status(404).json({ error: `unknown participant "${id}"` })
+      return
+    }
+    try {
+      const filePath = await p.exportToHtml()
+      const html = readFileSync(filePath, "utf-8")
+      const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, -5)
+      const filename = `${id}-${timestamp}.html`
+      res.setHeader("Content-Type", "text/html; charset=utf-8")
+      res.setHeader("Content-Disposition", `attachment; filename="${filename}"`)
+      res.send(html)
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  // Export agent's session as JSONL (one JSON object per line).
+  app.get("/api/participants/:id/export-jsonl", (req, res) => {
+    const { id } = req.params
+    const p = registry.get(id)
+    if (!p) {
+      res.status(404).json({ error: `unknown participant "${id}"` })
+      return
+    }
+    try {
+      const filePath = p.exportToJsonl()
+      const jsonl = readFileSync(filePath, "utf-8")
+      const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, -5)
+      const filename = `${id}-${timestamp}.jsonl`
+      res.setHeader("Content-Type", "application/x-ndjson; charset=utf-8")
+      res.setHeader("Content-Disposition", `attachment; filename="${filename}"`)
+      res.send(jsonl)
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  app.post("/api/abort", async (_req, res) => {
+    const aborted = await room.abortCurrent()
+    res.json({ aborted })
+  })
+
+  // Steer a running agent mid-turn.
+  app.post("/api/messages/steer", async (req, res) => {
+    const { text, target } = req.body
+    if (!text || !target) {
+      res.status(400).json({ error: "`text` and `target` are required" })
+      return
+    }
+    try {
+      await room.steer(target, String(text).trim())
+      res.json({ ok: true, target, text: String(text).trim() })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      if (msg.includes("not running") || msg.includes("cannot steer")) {
+        res.status(409).json({ error: msg })
+      } else if (msg.includes("unknown participant")) {
+        res.status(404).json({ error: msg })
+      } else {
+        res.status(500).json({ error: msg })
+      }
+    }
+  })
+
+  // ── Room management API ─────────────────────────────────────────────────
+
+  /** Resolve the room for this request — falls back to "default" if roomId absent. */
+  function roomOf(req: any): Room {
+    const id = (req.params?.roomId as string | undefined) ?? "default"
+    const r = roomManager.getRoom(id)
+    if (!r) throw new Error(`room "${id}" not found`)
+    return r
+  }
+
+  /** Middleware: verify room exists before handing off to a route handler. */
+  function requireRoom(req: any, res: any, next: any): void {
+    try { roomOf(req); next() } catch { res.status(404).json({ error: `room "${req.params?.roomId}" not found` }) }
+  }
+
+  // Room CRUD — process-global (not room-scoped)
+  app.get("/api/rooms", (_req, res) => {
+    res.json(roomManager.listRooms())
+  })
+
+  // MUST precede "/api/rooms/:roomId" — otherwise Express binds "resumable" as a
+  // roomId. Lists rooms with on-disk data that aren't currently open (resume
+  // candidates), including legacy orphans created before meta.json existed.
+  app.get("/api/rooms/resumable", async (_req, res) => {
+    res.json(await roomManager.listResumableRooms())
+  })
+
+  app.get("/api/rooms/:roomId", (req, res) => {
+    const details = roomManager.getRoomDetails(req.params.roomId)
+    if (!details) {
+      res.status(404).json({ error: `room "${req.params.roomId}" not found` })
+      return
+    }
+    res.json(details)
+  })
+
+  app.patch("/api/rooms/:roomId", (req, res) => {
+    const { roomId } = req.params
+    const name = String(req.body?.name ?? "").trim()
+    if (!name) {
+      res.status(400).json({ error: "`name` is required" })
+      return
+    }
+    const renamed = roomManager.renameRoom(roomId, name)
+    if (!renamed) {
+      res.status(404).json({ error: `room "${roomId}" not found` })
+      return
+    }
+    hub.broadcast("room", { type: "renamed", roomId, name })
+    res.json({ roomId, name })
+  })
+
+  app.post("/api/rooms", async (req, res) => {
+    try {
+      const summary = await provisionRoom({
+        roomId: req.body?.roomId ? String(req.body.roomId) : undefined,
+        name: String(req.body?.name ?? "").trim(),
+        preset: req.body?.preset ? String(req.body.preset).trim() : undefined,
+        goal: req.body?.goal ? String(req.body.goal).trim() : undefined,
+        workspaceDir: req.body?.workspaceDir ? String(req.body.workspaceDir).trim() : undefined,
+        goalMode: req.body?.goalMode === "eval" ? "eval" : undefined,
+        goalEvaluator: req.body?.goalEvaluator ? String(req.body.goalEvaluator).trim() : undefined,
+        maxGoalIterations: typeof req.body?.maxGoalIterations === "number" ? req.body.maxGoalIterations : undefined,
+      })
+      res.status(201).json(summary)
+    } catch (err) {
+      if (err instanceof RoomProvisionError) {
+        const body: { error: string; details?: unknown } = { error: err.message }
+        if (err.details !== undefined) body.details = err.details
+        res.status(err.status).json(body)
+        return
+      }
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  app.delete("/api/rooms/:roomId", async (req, res) => {
+    const { roomId } = req.params
+    if (roomId === "default") {
+      res.status(400).json({ error: "cannot delete the default room" })
+      return
+    }
+    // destroyRoom unmounts the room's sshfs mount (if any) before removal.
+    const removed = await roomManager.destroyRoom(roomId)
+    if (!removed) {
+      res.status(404).json({ error: `room "${roomId}" not found` })
+      return
+    }
+    hub.broadcast("room", { type: "destroyed", roomId })
+    res.status(204).end()
+  })
+
+  // Resume a room that exists on disk but isn't live (destroyed/closed). Reuses
+  // provisionRoom with the durable name/scope from meta.json; the room's init()
+  // reloads its saved transcript + roster. Registered as a top-level route (not
+  // via the room-scoped router, whose requireRoom guard would 404 a non-live room).
+  app.post("/api/rooms/:roomId/resume", async (req, res) => {
+    const { roomId } = req.params
+    if (roomId === "default") {
+      res.status(400).json({ error: "the default room is always open" })
+      return
+    }
+    if (roomManager.getRoom(roomId)) {
+      res.status(409).json({ error: `room "${roomId}" is already open` })
+      return
+    }
+    const target = (await roomManager.listResumableRooms()).find((r) => r.roomId === roomId)
+    if (!target) {
+      res.status(404).json({ error: `no resumable data for room "${roomId}"` })
+      return
+    }
+    try {
+      const summary = await provisionRoom({
+        roomId,
+        name: target.name,
+        workspaceDir: target.workspaceDir,
+      })
+      res.status(200).json(summary)
+    } catch (err) {
+      if (err instanceof RoomProvisionError) {
+        const body: { error: string; details?: unknown } = { error: err.message }
+        if (err.details !== undefined) body.details = err.details
+        res.status(err.status).json(body)
+        return
+      }
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  // ── Room-scoped router (/api/rooms/:roomId/*) ─────────────────────────────
+  // Mirrors the legacy /api/* routes but resolves room dynamically via roomOf().
+  // Existing /api/* routes are unchanged — backward compat is preserved.
+
+  const roomRouter = Router({ mergeParams: true })
+
+  roomRouter.get("/participants", (req, res) => {
+    res.json(roomOf(req).getRegistry().roster())
+  })
+
+  roomRouter.post("/participants", async (req, res) => {
+    const reg = roomOf(req).getRegistry()
+    try {
+      const persona = parsePersona(req.body ?? {})
+      if (reg.has(persona.id)) {
+        res.status(409).json({ error: `participant "${persona.id}" already exists` })
+        return
+      }
+      await reg.create(persona)
+      res.status(201).json(reg.roster().find((r) => r.id === persona.id))
+    } catch (err) {
+      res.status(400).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  roomRouter.post("/participants/from-template", async (req, res) => {
+    try {
+      const item = await addFromTemplate(roomOf(req), String(req.body?.templateId ?? ""))
+      res.status(201).json(item)
+    } catch (err) {
+      res.status(400).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  roomRouter.post("/participants/reorder", (req, res) => {
+    const order = req.body?.order
+    if (!Array.isArray(order) || !order.every((x: unknown) => typeof x === "string")) {
+      res.status(400).json({ error: "`order` must be an array of participant ids" })
+      return
+    }
+    const reg = roomOf(req).getRegistry()
+    reg.reorder(order as string[])
+    res.json(reg.roster())
+  })
+
+  roomRouter.get("/participants/:id", (req, res) => {
+    const p = roomOf(req).getRegistry().get(req.params.id)
+    if (!p) {
+      res.status(404).json({ error: `unknown participant "${req.params.id}"` })
+      return
+    }
+    res.json({ ...p.persona, availableThinkingLevels: p.getAvailableThinkingLevels() })
+  })
+
+  roomRouter.patch("/participants/:id", async (req, res) => {
+    const r = roomOf(req)
+    const reg = r.getRegistry()
+    const { id } = req.params
+    if (!reg.has(id)) {
+      res.status(404).json({ error: `unknown participant "${id}"` })
+      return
+    }
+    const body = req.body ?? {}
+    const patch: Record<string, unknown> = {}
+    if (typeof body.name === "string" && body.name.trim()) patch.name = body.name.trim()
+    if (typeof body.systemPrompt === "string" && body.systemPrompt.trim())
+      patch.systemPrompt = body.systemPrompt.trim()
+    if (typeof body.color === "string") patch.color = body.color
+    if (typeof body.icon === "string") patch.icon = body.icon
+    if (Array.isArray(body.tools))
+      patch.tools = body.tools.map(String).filter((t: string) => VALID_TOOLS.has(t))
+    const VALID_THINKING = new Set(["off", "minimal", "low", "medium", "high", "xhigh"])
+    if ("thinkingLevel" in body) {
+      const tv = body.thinkingLevel
+      if (tv === null || tv === "") {
+        patch.thinkingLevel = undefined
+      } else if (typeof tv === "string" && VALID_THINKING.has(tv)) {
+        patch.thinkingLevel = tv
+      } else {
+        res.status(400).json({ error: `invalid thinkingLevel "${String(tv)}" — must be one of: off, minimal, low, medium, high, xhigh` })
+        return
+      }
+    }
+    if ("model" in body) {
+      const mv = body.model
+      if (mv === null || mv === "") {
+        patch.model = undefined
+      } else if (typeof mv === "string" && reg.isAllowedModel(mv)) {
+        patch.model = mv
+      } else {
+        res.status(400).json({
+          error: r.getAllowCloud()
+            ? `unknown model "${String(mv)}"`
+            : `model "${String(mv)}" unavailable — cloud is disabled (toggle in Settings)`,
+        })
+        return
+      }
+    }
+    if ("compactionInstructions" in body) {
+      const ci = body.compactionInstructions
+      if (ci === null || ci === "") {
+        patch.compactionInstructions = undefined
+      } else if (typeof ci === "string" && ci.length <= 500) {
+        patch.compactionInstructions = ci
+      } else if (typeof ci === "string") {
+        res.status(400).json({ error: `compactionInstructions too long (${ci.length} chars, max 500)` })
+        return
+      } else {
+        res.status(400).json({ error: "compactionInstructions must be a string" })
+        return
+      }
+    }
+    try {
+      if (typeof body.active === "boolean") reg.setActive(id, body.active)
+      if (typeof body.parallel === "boolean") reg.setParallel(id, body.parallel)
+      if (Object.keys(patch).length > 0) {
+        if (Object.keys(patch).length === 1 && "thinkingLevel" in patch && patch.thinkingLevel !== undefined) {
+          await reg.setThinkingLevel(id, patch.thinkingLevel as "off" | "minimal" | "low" | "medium" | "high" | "xhigh")
+        } else {
+          if (r.isBusy()) {
+            res.status(409).json({ error: "a turn is running — press Stop before editing an agent" })
+            return
+          }
+          await reg.update(id, patch)
+        }
+      }
+      res.json(reg.roster().find((ri) => ri.id === id))
+    } catch (err) {
+      res.status(400).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  roomRouter.delete("/participants/:id", (req, res) => {
+    const reg = roomOf(req).getRegistry()
+    const { id } = req.params
+    if (!reg.has(id)) {
+      res.status(404).json({ error: `unknown participant "${id}"` })
+      return
+    }
+    reg.kick(id)
+    res.status(204).end()
+  })
+
+  roomRouter.get("/transcript", (req, res) => {
+    res.json(roomOf(req).getTranscript())
+  })
+
+  // Room-scoped workspace listing: initial snapshot for the WorkspacePanel.
+  // Live updates arrive over SSE; this serves the first paint per room.
+  roomRouter.get("/workspace", async (req, res) => {
+    res.json(await roomOf(req).getWorkspaceListing())
+  })
+
+  roomRouter.get("/settings", (req, res) => {
+    const r = roomOf(req)
+    res.json(settingsPayload(r))
+  })
+
+  roomRouter.patch("/settings", (req, res) => {
+    const r = roomOf(req)
+    const body = req.body ?? {}
+    if ("chaining" in body) {
+      if (typeof body.chaining !== "boolean") {
+        res.status(400).json({ error: "`chaining` must be a boolean" })
+        return
+      }
+      r.setChaining(body.chaining)
+    }
+    if ("defaultAgent" in body) {
+      const da = body.defaultAgent
+      if (da !== null && typeof da !== "string") {
+        res.status(400).json({ error: "`defaultAgent` must be a string id or null" })
+        return
+      }
+      try { r.setDefaultAgent(da) } catch (err) {
+        res.status(404).json({ error: err instanceof Error ? err.message : String(err) })
+        return
+      }
+    }
+    if ("fallbackAgent" in body) {
+      const fa = body.fallbackAgent
+      if (fa !== null && typeof fa !== "string") {
+        res.status(400).json({ error: "`fallbackAgent` must be a string id or null" })
+        return
+      }
+      try { r.setFallbackAgent(fa) } catch (err) {
+        res.status(404).json({ error: err instanceof Error ? err.message : String(err) })
+        return
+      }
+    }
+    if ("maxChainHops" in body) {
+      const n = body.maxChainHops
+      if (typeof n !== "number" || n < 1 || n > 100) {
+        res.status(400).json({ error: "`maxChainHops` must be a number between 1 and 100" })
+        return
+      }
+      r.setMaxChainHops(n)
+    }
+    if ("routingMode" in body) {
+      const m = body.routingMode
+      if (m !== "auto" && m !== "semi" && m !== "manual") {
+        res.status(400).json({ error: "`routingMode` must be 'auto', 'semi', or 'manual'" })
+        return
+      }
+      r.setRoutingMode(m)
+    }
+    if ("circuitBreaker" in body) {
+      if (typeof body.circuitBreaker !== "boolean") {
+        res.status(400).json({ error: "`circuitBreaker` must be a boolean" })
+        return
+      }
+      r.setCircuitBreaker(body.circuitBreaker)
+    }
+    if ("defaultThinkingLevel" in body) {
+      const validLevels = ["off", "minimal", "low", "medium", "high", "xhigh"]
+      if (!validLevels.includes(body.defaultThinkingLevel)) {
+        res.status(400).json({ error: "`defaultThinkingLevel` must be one of: " + validLevels.join(", ") })
+        return
+      }
+      r.setDefaultThinkingLevel(body.defaultThinkingLevel)
+    }
+    if ("allowCloud" in body) {
+      if (typeof body.allowCloud !== "boolean") {
+        res.status(400).json({ error: "`allowCloud` must be a boolean" })
+        return
+      }
+      r.setAllowCloud(body.allowCloud)
+    }
+    if ("compactionReserveTokens" in body) {
+      const v = Number(body.compactionReserveTokens)
+      if (!Number.isFinite(v) || v < 5000 || v > 100000) {
+        res.status(400).json({ error: "`compactionReserveTokens` must be an integer between 5000 and 100000" })
+        return
+      }
+      r.setCompactionReserveTokens(v)
+    }
+    res.json(settingsPayload(r))
+  })
+
+  roomRouter.post("/route", (req, res) => {
+    const decision = parseRouteDecision(req.body ?? {})
+    if (!decision) {
+      res.status(400).json({ error: "`action` must be 'approve', 'redirect', or 'drop'" })
+      return
+    }
+    roomOf(req).resolveRoute(decision)
+    res.status(202).json({ accepted: true })
+  })
+
+  // Room-scoped preset actions — target the room in the URL, not the default.
+  roomRouter.post("/presets", async (req, res) => {
+    const name = String(req.body?.name ?? "").trim().replace(/[^a-zA-Z0-9_-]/g, "")
+    await doSavePreset(roomOf(req), name, res)
+  })
+  roomRouter.post("/presets/:name/load", (req, res) => doLoadPreset(roomOf(req), req.params.name, res))
+  roomRouter.post("/presets/:name/apply", (req, res) => doApplyPreset(roomOf(req), req.params.name, res))
+
+  roomRouter.post("/messages", rateLimit({ windowMs: 60_000, max: 60, standardHeaders: true, legacyHeaders: false }), async (req, res) => {
+    const text = String(req.body?.text ?? "").trim()
+    if (!text) {
+      res.status(400).json({ error: "`text` is required" })
+      return
+    }
+    const images = await saveIncomingImages(req.body?.images)
+    roomOf(req).submit(text, images.length > 0 ? images : undefined)
+    res.status(202).json({ accepted: true })
+  })
+
+  roomRouter.post("/messages/steer", async (req, res) => {
+    const { text, target } = req.body
+    if (!text || !target) {
+      res.status(400).json({ error: "`text` and `target` are required" })
+      return
+    }
+    try {
+      await roomOf(req).steer(target, String(text).trim())
+      res.json({ ok: true, target, text: String(text).trim() })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      if (msg.includes("not running") || msg.includes("cannot steer")) {
+        res.status(409).json({ error: msg })
+      } else if (msg.includes("unknown participant")) {
+        res.status(404).json({ error: msg })
+      } else {
+        res.status(500).json({ error: msg })
+      }
+    }
+  })
+
+  roomRouter.post("/abort", async (req, res) => {
+    const aborted = await roomOf(req).abortCurrent()
+    res.json({ aborted })
+  })
+
+  roomRouter.post("/participants/:id/compact", async (req, res) => {
+    const r = roomOf(req)
+    const p = r.getRegistry().get(req.params.id)
+    if (!p) {
+      res.status(404).json({ error: `unknown participant "${req.params.id}"` })
+      return
+    }
+    if (r.isBusy()) {
+      res.status(409).json({ error: "a turn is running — press Stop before compacting" })
+      return
+    }
+    try {
+      const result = await p.compact()
+      res.json(result)
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  roomRouter.get("/participants/:id/export", async (req, res) => {
+    const p = roomOf(req).getRegistry().get(req.params.id)
+    if (!p) {
+      res.status(404).json({ error: `unknown participant "${req.params.id}"` })
+      return
+    }
+    try {
+      const filePath = await p.exportToHtml()
+      const html = readFileSync(filePath, "utf-8")
+      const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, -5)
+      const filename = `${req.params.id}-${timestamp}.html`
+      res.setHeader("Content-Type", "text/html; charset=utf-8")
+      res.setHeader("Content-Disposition", `attachment; filename="${filename}"`)
+      res.send(html)
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  roomRouter.get("/participants/:id/export-jsonl", (req, res) => {
+    const p = roomOf(req).getRegistry().get(req.params.id)
+    if (!p) {
+      res.status(404).json({ error: `unknown participant "${req.params.id}"` })
+      return
+    }
+    try {
+      const filePath = p.exportToJsonl()
+      const jsonl = readFileSync(filePath, "utf-8")
+      const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, -5)
+      const filename = `${req.params.id}-${timestamp}.jsonl`
+      res.setHeader("Content-Type", "application/x-ndjson; charset=utf-8")
+      res.setHeader("Content-Disposition", `attachment; filename="${filename}"`)
+      res.send(jsonl)
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  // Per-room SSE stream — filtered to only this room's events via the roomId
+  // passed to addClient(). Every room-scoped broadcast carries its roomId param
+  // (object and array payloads alike), so the hub delivers only this room's
+  // events here, plus global events that carry no roomId (room lifecycle, etc.).
+  // The initial roster/transcript snapshot is written directly to this response.
+  roomRouter.get("/events", (req, res) => {
+    const r = roomOf(req)
+    hub.addClient(res, r.roomId) // register with room filter
+    // Deliver initial state directly to this client (bypasses broadcast filter)
+    const roster = r.getRegistry().roster()
+    res.write(`event: roster\ndata: ${JSON.stringify(roster)}\n\n`)
+    res.write(`event: transcript\ndata: ${JSON.stringify(r.getTranscript())}\n\n`)
+  })
+
+  roomRouter.get("/conversations", async (req, res) => {
+    res.json(await roomOf(req).getConversations())
+  })
+
+  roomRouter.post("/conversations", async (req, res) => {
+    try {
+      const title = req.body?.title ? String(req.body.title) : undefined
+      res.status(201).json(await roomOf(req).newConversation(title))
+    } catch (err) {
+      res.status(409).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  roomRouter.post("/conversations/:id/load", async (req, res) => {
+    try {
+      await roomOf(req).switchConversation(req.params.id)
+      res.json({ ok: true })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      res.status(msg.includes("unknown") ? 404 : 409).json({ error: msg })
+    }
+  })
+
+  roomRouter.patch("/conversations/:id", async (req, res) => {
+    const title = String(req.body?.title ?? "").trim()
+    if (!title) {
+      res.status(400).json({ error: "`title` is required" })
+      return
+    }
+    try {
+      await roomOf(req).renameConversation(req.params.id, title)
+      res.json({ ok: true })
+    } catch (err) {
+      res.status(404).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  roomRouter.delete("/conversations/:id", async (req, res) => {
+    try {
+      await roomOf(req).deleteConversation(req.params.id)
+      res.status(204).end()
+    } catch (err) {
+      res.status(409).json({ error: err instanceof Error ? err.message : String(err) })
+    }
+  })
+
+  // Mount the room-scoped router. CRUD routes above must come before this.
+  app.use("/api/rooms/:roomId", requireRoom, roomRouter)
+
+  // Serve the built web UI when present (web/dist relative to the package
+  // root, not the cwd — `npx pipeline-moe serve` runs from anywhere). In dev
+  // the Vite server on :5310 is used instead and this directory is absent.
+  const webDist = resolve(packageRoot(), "web", "dist")
+  try {
+    readFileSync(join(webDist, "index.html"))
+    app.use(express.static(webDist))
+    // SPA fallback: any non-API GET serves the app shell.
+    app.get(/^\/(?!api\/).*/, (_req, res) => {
+      res.sendFile(join(webDist, "index.html"))
+    })
+    console.log(`[server] serving web UI from ${webDist}`)
+  } catch {
+    // no built web UI — API only
+  }
+
+  const server = app.listen(config.port, "127.0.0.1", () => {
+    console.log(`[server] Pipeline-MoE listening on http://localhost:${config.port}`)
+    console.log(`[server] workspace: ${config.workspaceDir}`)
+  })
+
+  const shutdown = async () => {
+    console.log("\n[server] shutting down…")
+    registry.disposeAll()
+    // Unmount any sshfs-scoped rooms so a normal shutdown leaves no orphaned
+    // FUSE mounts. Best-effort — never block shutdown on a failed unmount.
+    await roomManager.cleanupAllMounts().catch(() => {})
+    server.close(() => process.exit(0))
+    setTimeout(() => process.exit(0), 2000).unref()
+  }
+  process.on("SIGINT", shutdown)
+  process.on("SIGTERM", shutdown)
+}
+
+main().catch((err) => {
+  console.error("[fatal]", err)
+  process.exit(1)
+})