@terminus-ai/cli 0.0.1

package/bin/devserver.mjs

@@ -0,0 +1,2127 @@
+/**
+ * The `terminus dev` web server for a kind:"agent" package.
+ *
+ * One local HTTP server on 127.0.0.1 between the browser and the dev
+ * machinery. It serves the static chat UI (`bin/dev-ui/`), bridges the
+ * engine's frames to SSE, owns the SQLite session mirror
+ * (`.terminus/dev/agent/dev.db`), watches the package for hot
+ * reloads, and is the only place credentials live — the user JWT never
+ * reaches the page. Because every /api door proxies user-authed cloud
+ * doors, each request must carry the per-run token embedded in the served
+ * page (plus an Origin check) — otherwise any tab on localhost could spend
+ * the developer's authority.
+ *
+ * Substrates (interface constant, substrate swapped):
+ *  - local (default): `LocalDev` — agentd on this machine, native exec,
+ *    brokered web/skills/connectors.
+ *  - `--remote`: `AgentDevSession` — the tree pushed as the Studio draft,
+ *    turns on the production engine. Same UI.
+ *
+ * An agent has ONE conversation here, start to finish: the engine's session
+ * is resumed on every start, and there is no door to list, switch or begin
+ * another. The SQLite row survives so a reload keeps the transcript.
+ *
+ * terminus.json is ground truth: the inspector's edits land in the manifest
+ * (indent-preserving re-render of the strict-JSON file), then the engine
+ * recompiles. The one thing that is NOT written there is a reader's model
+ * pick, because it is not the developer's configuration — it is what one
+ * visitor chose, and only an agent that offers a choice has one.
+ */
+
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { watch } from "node:fs";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { DEV_DIRECTORY, ensureDevDirectory, TERMINUS_DIRECTORY } from "./files.mjs";
+
+import {
+  AgentDevSession,
+  LocalDev,
+  compatWarningsForToolCall,
+} from "./agentdev.mjs";
+import {
+  MAX_ICON_BYTES,
+  STAGED_ICON_NAMES,
+  readStagedIcon,
+  sniffImage,
+} from "./agent-icon.mjs";
+import { MODEL_MODES, readModelSection, writeModelSection } from "./agent-models.mjs";
+import { readDiscovery, writeDiscovery } from "./agent-discovery.mjs";
+import { readAgentType, writeAgentType } from "./agent-type.mjs";
+import {
+  buildTriggerInput,
+  effectiveWorkloads,
+  listDevTriggers,
+  loadWatchState,
+  runTriggerFiring,
+} from "./devtriggers.mjs";
+import { readAppPackage, resolveCreation } from "./apps.mjs";
+import { parseAgentTriggers, validUtcCron } from "./schedules.mjs";
+import { CliError } from "./client.mjs";
+import { normalizeBase } from "./http.mjs";
+import {
+  answerDevAbout,
+  assertDevPortRangeAvailable,
+  DEV_ABOUT_PATH,
+  devPortUnavailableError,
+  isLoopbackHost,
+  isLoopbackOrigin,
+  listenDevServer,
+  refuseForeignHost,
+  resolveDevPortRange,
+} from "./dev-ports.mjs";
+
+const BODY_LIMIT_BYTES = 40 * 1024 * 1024;
+const MAX_IMAGE_ATTACHMENTS = 4;
+const MAX_IMAGE_ATTACHMENT_BYTES = 5 * 1024 * 1024;
+const MAX_FILE_ATTACHMENTS = 4;
+const MAX_FILE_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+const IMAGE_MEDIA_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
+const PORT_ATTEMPTS = 50;
+const WATCH_DEBOUNCE_MS = 500;
+const TOOL_INPUT_MIRROR_CAP = 4_096;
+
+const uiDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "dev-ui");
+
+const CONTENT_TYPES = {
+  ".css": "text/css; charset=utf-8",
+  ".csv": "text/csv; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webp": "image/webp",
+  ".woff2": "font/woff2",
+};
+
+export function contentTypeFor(filePath) {
+  return CONTENT_TYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+
+// ---------------------------------------------------------------------------
+// SQLite session mirror
+// ---------------------------------------------------------------------------
+
+/** Open (creating on first use) the local SQLite mirror. Prod parity
+ * decides storage: sessions are Postgres rows in prod, so locally they are
+ * SQLite rows; outputs stay real files in the workspace lanes. */
+export async function openDevDb(dbPath) {
+  let DatabaseSync;
+  try {
+    ({ DatabaseSync } = await import("node:sqlite"));
+  } catch {
+    throw new CliError(
+      "the dev needs node:sqlite (Node ≥ 22.16) — update Node to run the web dev",
+    );
+  }
+  await mkdir(path.dirname(dbPath), { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL DEFAULT '',
+      model TEXT NOT NULL DEFAULT '',
+      substrate TEXT NOT NULL DEFAULT 'local',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      tokens INTEGER NOT NULL DEFAULT 0,
+      cost_usd REAL NOT NULL DEFAULT 0
+    );
+    CREATE TABLE IF NOT EXISTS messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      content TEXT NOT NULL,
+      extra TEXT,
+      created_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS messages_session ON messages (session_id, id);
+    CREATE TABLE IF NOT EXISTS prefs (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `);
+  return {
+    ensureSession(id, model, substrate) {
+      db.prepare(
+        `INSERT INTO sessions (id, model, substrate, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET model = excluded.model`,
+      ).run(id, model ?? "", substrate, Date.now(), Date.now());
+    },
+    touchSession(id, { title, tokens = 0, costUsd = 0 } = {}) {
+      db.prepare(
+        `UPDATE sessions SET
+           updated_at = ?,
+           tokens = tokens + ?,
+           cost_usd = cost_usd + ?,
+           title = CASE WHEN title = '' THEN ? ELSE title END
+         WHERE id = ?`,
+      ).run(Date.now(), tokens, costUsd, (title ?? "").slice(0, 80), id);
+    },
+    insertMessage(sessionId, role, content, extra) {
+      db.prepare(
+        "INSERT INTO messages (session_id, role, content, extra, created_at) VALUES (?, ?, ?, ?, ?)",
+      ).run(sessionId, role, content, extra ? JSON.stringify(extra) : null, Date.now());
+    },
+    listSessions() {
+      return db
+        .prepare(
+          `SELECT s.id, s.title, s.model, s.substrate, s.created_at, s.updated_at,
+                  s.tokens, s.cost_usd,
+                  (SELECT COUNT(*) FROM messages m
+                    WHERE m.session_id = s.id AND m.role = 'user') AS turns
+           FROM sessions s ORDER BY s.updated_at DESC`,
+        )
+        .all();
+    },
+    listMessages(sessionId) {
+      return db
+        .prepare(
+          "SELECT id, role, content, extra, created_at FROM messages WHERE session_id = ? ORDER BY id ASC",
+        )
+        .all(sessionId)
+        .map((row) => ({
+          ...row,
+          extra: row.extra ? JSON.parse(row.extra) : null,
+        }));
+    },
+    close() {
+      try {
+        db.close();
+      } catch {
+        // Best effort; process exit reclaims it anyway.
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// terminus.json is ground truth
+// ---------------------------------------------------------------------------
+
+/** Apply one mutation to the package manifest, re-rendering the strict-JSON
+ * file with its own indentation (detected, defaulting to two spaces) and a
+ * trailing newline. terminus.json is scaffolded strict JSON — there are no
+ * comments to preserve. */
+export async function editManifestFile(dir, mutate) {
+  const manifestPath = path.join(dir, "terminus.json");
+  const raw = await readFile(manifestPath, "utf8");
+  const indent = /\n([ \t]+)"/.exec(raw)?.[1] ?? "  ";
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch {
+    throw new CliError("terminus.json is not valid JSON — fix it before editing from the dev");
+  }
+  mutate(manifest);
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, indent)}\n`);
+  return manifest;
+}
+
+function toolIdentity(entry) {
+  return typeof entry === "string" ? entry : entry?.id;
+}
+
+/** A sanity bound mirroring the backend's, not a product limit. The old cap
+ * was 16 — below the size of the live catalog, so "any model" could not be
+ * published at all. */
+export const MAX_AGENT_MODELS = 512;
+
+/** The declarable platform lanes that are not connector profiles — the core
+ * half of GET /api/tool-catalog. Connector tools join at request time from
+ * the live `/connectors` catalog, so this list never has to chase them. */
+export const CORE_TOOL_CATALOG = [
+  { id: "internet", name: "Internet", desc: "Search the web and read public pages through the gateway", kind: "core" },
+  { id: "compute", name: "Compute", desc: "Run shell, Python, and Node programs in the workspace", kind: "core" },
+  { id: "automation", name: "Automation", desc: "Manage its own schedules and page watches", kind: "core" },
+  { id: "bash", name: "Bash", desc: "Run shell commands in the workspace", kind: "core" },
+  { id: "python", name: "Python", desc: "Compute with Python", kind: "core" },
+  { id: "node", name: "Node.js", desc: "Run Node.js", kind: "core" },
+  { id: "web.search", name: "Web search", desc: "Search the public web through the gateway", kind: "core" },
+  { id: "web.fetch", name: "Web fetch", desc: "Fetch a public page through the gateway", kind: "core" },
+  { id: "schedules.manage", name: "Schedules", desc: "Manage its own scheduled runs in conversation", kind: "core" },
+  { id: "watches.manage", name: "Watches", desc: "Track pages and sources in conversation", kind: "core" },
+];
+
+/**
+ * The lanes above, said the way a developer says them: three bundles, each
+ * standing for the tools it expands to. This is the registry's own grouping
+ * (`bin/horizontal-capabilities/v1/contract.json` → `bundles`) carried into
+ * the manifest's vocabulary, where a member is `web.search` rather than the
+ * registry's `web-search`; `registryToolId` and its test hold the two
+ * together, so a member added upstream cannot go missing here in silence.
+ *
+ * Granting every member of a bundle IS the bundle — that is what the
+ * compiler's sugar means — which is why the picker offers the bundle first
+ * and its members as the thing you narrow it to.
+ */
+export const TOOL_BUNDLES = [
+  { id: "internet", members: ["web.search", "web.fetch"] },
+  { id: "compute", members: ["bash", "python", "node"] },
+  { id: "automation", members: ["schedules.manage", "watches.manage"] },
+].map((bundle) => {
+  const core = CORE_TOOL_CATALOG.find((tool) => tool.id === bundle.id);
+  return {
+    ...bundle,
+    name: core?.name ?? bundle.id,
+    desc: core?.desc ?? "",
+    tools: bundle.members.map((id) => {
+      const member = CORE_TOOL_CATALOG.find((tool) => tool.id === id);
+      return { id, name: member?.name ?? id, desc: member?.desc ?? "" };
+    }),
+  };
+});
+
+/** A horizontal-registry capability id as the manifest spells it. The two
+ *  vocabularies differ in exactly this handful of names. */
+export function registryToolId(id) {
+  return { "web-search": "web.search", "web-fetch": "web.fetch", schedules: "schedules.manage", watches: "watches.manage" }[id]
+    ?? id;
+}
+
+/** The manifest operations the Settings panel performs. */
+export function applyManifestOps(manifest, ops) {
+  // Who reads the agent's conversations: the default, or its maintainers.
+  if (ops.type !== undefined) {
+    writeAgentType(manifest, String(ops.type ?? "").trim());
+  }
+  // Model configuration is ONE section, read and written whole: a default, a
+  // mode, and a list that only exists under `selective`. Editing the parts
+  // separately is how the flat shape ended up able to hold two answers.
+  if (ops.model !== undefined || ops.model_mode !== undefined || ops.models !== undefined) {
+    const section = readModelSection(manifest);
+
+    if (typeof ops.model === "string" && ops.model.trim()) {
+      section.default = ops.model.trim();
+    }
+
+    if (ops.model_mode !== undefined) {
+      const mode = String(ops.model_mode ?? "default").trim();
+      if (!MODEL_MODES.includes(mode)) {
+        throw new CliError(`models.mode is one of ${MODEL_MODES.join(", ")}`);
+      }
+      section.mode = mode;
+      // A list only means something under `selective`; leaving one behind
+      // under another mode would be a second, contradicting answer.
+      if (mode !== "selective") section.available = [];
+    }
+
+    if (ops.models !== undefined) {
+      const list = Array.isArray(ops.models)
+        ? ops.models.map((entry) => String(entry ?? "").trim()).filter(Boolean)
+        : [];
+      // The platform offers the default PLUS this list (agent_host.rs
+      // allowed_models), so naming the default again buys nothing and makes a
+      // default-only agent look like it offers a choice of one.
+      const unique = [...new Set(list)].filter((id) => id !== section.default);
+      if (unique.length > MAX_AGENT_MODELS) {
+        throw new CliError(`at most ${MAX_AGENT_MODELS} selectable models`);
+      }
+      section.available = unique;
+      section.mode = unique.length ? "selective" : "default";
+    }
+
+    writeModelSection(manifest, section);
+  }
+  // Whether the agent may look in the Store for a kind of thing, or keep to
+  // what its tools name.
+  if (ops.discovery !== undefined) {
+    writeDiscovery(manifest, ops.discovery?.kind, ops.discovery?.mode);
+  }
+  // One tool or several: a service is one token per operation, so adding or
+  // dropping it is a set of tokens that has to land in ONE write.
+  const adding = ops.add_tools ?? (ops.add_tool !== undefined ? [ops.add_tool] : []);
+  if (adding.length) {
+    const tools = Array.isArray(manifest.tools) ? manifest.tools : [];
+    for (const token of adding) {
+      const id = toolIdentity(token);
+      if (!id) throw new CliError("add_tool needs a tool token (string or {id, when})");
+      if (!tools.some((entry) => toolIdentity(entry) === id)) tools.push(token);
+    }
+    manifest.tools = tools;
+  }
+  const dropping = new Set(
+    (ops.remove_tools ?? (ops.remove_tool ? [ops.remove_tool] : []))
+      .filter((id) => typeof id === "string" && id),
+  );
+  if (dropping.size) {
+    manifest.tools = (Array.isArray(manifest.tools) ? manifest.tools : []).filter(
+      (entry) => !dropping.has(toolIdentity(entry)),
+    );
+  }
+  const agentTriggerOps = manifest.kind === "agent"
+    && ["schedule", "schedule_create", "schedule_delete", "watch", "watch_create", "watch_delete"]
+      .some((op) => ops[op] !== undefined);
+  if (agentTriggerOps) {
+    applyAgentTriggerOps(manifest, ops, AGENT_TRIGGER_KINDS.schedule);
+    applyAgentTriggerOps(manifest, ops, AGENT_TRIGGER_KINDS.watch);
+  } else if (ops.schedule !== undefined) {
+    const { name, cron, timezone, enabled } = ops.schedule ?? {};
+    if (!name) throw new CliError("schedule op needs the schedule's name");
+    const schedules = manifest.workloads?.schedules;
+    const target = Array.isArray(schedules)
+      ? schedules.find((entry) => entry?.name === name)
+      : null;
+    if (!target) throw new CliError(`no schedule named '${name}' in workloads.schedules`);
+    if (cron !== undefined) {
+      if (!validUtcCron(cron)) {
+        throw new CliError(
+          "cron fields are *, */N, or one number (minute hour day month weekday)",
+        );
+      }
+      target.cron = String(cron).trim();
+    }
+    if (timezone !== undefined) {
+      try {
+        new Intl.DateTimeFormat("en", { timeZone: timezone });
+      } catch {
+        throw new CliError(`unknown timezone '${timezone}'`);
+      }
+      target.timezone = timezone;
+    }
+    // `enabled: true` is the default, so writing it out would only add noise
+    // to the manifest; delete the key instead of stating the default.
+    if (enabled !== undefined) {
+      if (enabled) delete target.enabled;
+      else target.enabled = false;
+    }
+  }
+  return manifest;
+}
+
+const CADENCE_FIELDS = ["every", "at", "on_day", "cron"];
+
+/** The two conversationally-editable trigger kinds, one grammar each. */
+const AGENT_TRIGGER_KINDS = {
+  schedule: {
+    op: "schedule",
+    section: "schedules",
+    fields: ["name", "every", "at", "on_day", "cron", "timezone", "prompt", "enabled"],
+    // A cadence update replaces the whole cadence atomically.
+    exclusive: CADENCE_FIELDS,
+    defaults: (draft) => {
+      if (draft.cron === undefined && draft.every === undefined) {
+        draft.every = "day";
+        draft.at = draft.at ?? "09:00";
+      }
+    },
+    generatedName: (entry) => (entry.cron !== undefined
+      ? "custom"
+      : entry.every === "day"
+        ? "daily"
+        : entry.every === "month"
+          ? "monthly"
+          : /^\d+[mh]$/.test(entry.every ?? "")
+            ? `every-${entry.every}`
+            : String(entry.every ?? "schedule")),
+  },
+  watch: {
+    op: "watch",
+    section: "watches",
+    fields: ["name", "url", "pattern", "interval_minutes", "prompt", "condition", "enabled"],
+    exclusive: [],
+    defaults: (draft) => {
+      draft.url = draft.url ?? "https://example.com";
+    },
+    generatedName: () => "watch",
+  },
+};
+
+/** Strip defaults so the authored file never states them: enabled true,
+ * nulls, and undefined fields stay out of terminus.json. */
+function cleanAgentTrigger(entry, fields) {
+  const cleaned = {};
+  for (const field of fields) {
+    if (entry[field] !== undefined && entry[field] !== null) cleaned[field] = entry[field];
+  }
+  if (cleaned.enabled === true) delete cleaned.enabled;
+  return cleaned;
+}
+
+/**
+ * Agent triggers live at the manifest top level in prompt form. Per kind:
+ * `<kind>_create` appends (auto-naming once there is more than one),
+ * `<kind>_delete` removes by name ("default" addresses a single unnamed
+ * entry), `<kind>` updates fields — `null` clears a field back to its
+ * default. The result is validated whole before it is written, so a refused
+ * edit leaves the manifest untouched.
+ */
+function applyAgentTriggerOps(manifest, ops, kind) {
+  const create = ops[`${kind.op}_create`];
+  const remove = ops[`${kind.op}_delete`];
+  const update = ops[kind.op];
+  if (create === undefined && remove === undefined && update === undefined) return;
+  let entries = Array.isArray(manifest[kind.section])
+    ? manifest[kind.section].map((entry) => ({ ...entry }))
+    : [];
+  const keyOf = (entry) => entry.name ?? "default";
+  if (create !== undefined) {
+    const draft = { ...(create ?? {}) };
+    kind.defaults(draft);
+    if (entries.length === 1 && entries[0].name === undefined) {
+      // The single entry's key was implicitly "default"; naming it keeps the
+      // key (and its platform state) stable as the list grows.
+      entries[0].name = "default";
+    }
+    if (draft.name === undefined && entries.length) {
+      const taken = new Set(entries.map(keyOf));
+      const base = kind.generatedName(draft);
+      let name = base;
+      for (let counter = 2; taken.has(name); counter += 1) name = `${base}-${counter}`;
+      draft.name = name;
+    }
+    entries.push(cleanAgentTrigger(draft, kind.fields));
+  }
+  if (remove !== undefined) {
+    const name = remove?.name;
+    if (!name) throw new CliError(`${kind.op}_delete needs the ${kind.op}'s name`);
+    const remaining = entries.filter((entry) => keyOf(entry) !== name);
+    if (remaining.length === entries.length) {
+      throw new CliError(`no ${kind.op} named '${name}'`);
+    }
+    entries = remaining;
+    if (entries.length === 1 && entries[0].name === "default") {
+      delete entries[0].name;
+    }
+  }
+  if (update !== undefined) {
+    const updates = update ?? {};
+    if (!updates.name) throw new CliError(`${kind.op} op needs the ${kind.op}'s name`);
+    const index = entries.findIndex((entry) => keyOf(entry) === updates.name);
+    if (index < 0) throw new CliError(`no ${kind.op} named '${updates.name}'`);
+    const target = { ...entries[index] };
+    if (kind.exclusive.some((field) => updates[field] !== undefined)) {
+      for (const field of kind.exclusive) delete target[field];
+    }
+    for (const field of kind.fields) {
+      if (field === "name" || updates[field] === undefined) continue;
+      target[field] = updates[field];
+    }
+    entries[index] = cleanAgentTrigger(target, kind.fields);
+  }
+  // One atomic gate for whatever the ops produced — the same validation
+  // publish runs, so the file can never be edited into an unpublishable
+  // state.
+  const candidate = { ...manifest };
+  if (entries.length) candidate[kind.section] = entries;
+  else delete candidate[kind.section];
+  parseAgentTriggers(candidate, { agentName: "agent" });
+  if (entries.length) manifest[kind.section] = entries;
+  else delete manifest[kind.section];
+}
+
+// ---------------------------------------------------------------------------
+// Attachments (the ratified contract, local half)
+// ---------------------------------------------------------------------------
+
+function sanitizeAttachmentName(name) {
+  const base = String(name ?? "")
+    .split(/[\\/]/)
+    .pop();
+  const cleaned = base
+    .replace(/[^A-Za-z0-9._-]/g, "-")
+    .replace(/^[.-]+|[.-]+$/g, "")
+    .slice(0, 80);
+  return cleaned || "file";
+}
+
+/** Validate and split a message's attachments: images become engine content
+ * parts, files materialize into the workspace's attachments/ folder with
+ * reference notes appended to the text — mirroring the hosted door exactly.
+ *
+ * `mediaDir` is the harness's own store, OUTSIDE the agent's lanes: image bytes
+ * are kept there only so the transcript can still show the photo after a
+ * reload. The agent never sees them as files, because the hosted agent does
+ * not either — images reach a model as content parts and nothing else. */
+const IMAGE_EXTENSIONS = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+};
+
+export async function prepareAttachments(attachments, workspaceDir, mediaDir = null) {
+  const images = [];
+  const notes = [];
+  const fileMeta = [];
+  const imageMeta = [];
+  const list = Array.isArray(attachments) ? attachments : [];
+  const imageCount = list.filter((entry) => (entry?.kind ?? "image") === "image").length;
+  const fileCount = list.filter((entry) => entry?.kind === "file").length;
+  if (imageCount > MAX_IMAGE_ATTACHMENTS) {
+    throw new CliError(`at most ${MAX_IMAGE_ATTACHMENTS} image attachments per message`);
+  }
+  if (fileCount > MAX_FILE_ATTACHMENTS) {
+    throw new CliError(`at most ${MAX_FILE_ATTACHMENTS} file attachments per message`);
+  }
+  for (const entry of list) {
+    const kind = entry?.kind ?? "image";
+    const data = typeof entry?.data === "string" ? entry.data : "";
+    let bytes;
+    try {
+      bytes = Buffer.from(data, "base64");
+    } catch {
+      bytes = Buffer.alloc(0);
+    }
+    if (!bytes.length) throw new CliError("attachment data must be non-empty base64");
+    if (kind === "image") {
+      const mediaType = entry?.media_type ?? "";
+      if (!IMAGE_MEDIA_TYPES.has(mediaType)) {
+        throw new CliError(
+          `unsupported image media_type '${mediaType}' (png, jpeg, webp, or gif)`,
+        );
+      }
+      if (bytes.length > MAX_IMAGE_ATTACHMENT_BYTES) {
+        throw new CliError(
+          `image attachments are limited to ${MAX_IMAGE_ATTACHMENT_BYTES / (1024 * 1024)} MB each`,
+        );
+      }
+      images.push({ media_type: mediaType, data });
+      const meta = { media_type: mediaType };
+      if (mediaDir) {
+        meta.id = `${randomBytes(8).toString("hex")}.${IMAGE_EXTENSIONS[mediaType]}`;
+        await mkdir(mediaDir, { recursive: true });
+        await writeFile(path.join(mediaDir, meta.id), bytes);
+      }
+      imageMeta.push(meta);
+    } else if (kind === "file") {
+      if (!workspaceDir) {
+        throw new CliError(
+          "file attachments need a local workspace — the remote dev draft has none; send images instead",
+        );
+      }
+      if (bytes.length > MAX_FILE_ATTACHMENT_BYTES) {
+        throw new CliError(
+          `file attachments are limited to ${MAX_FILE_ATTACHMENT_BYTES / (1024 * 1024)} MB each`,
+        );
+      }
+      const storedName = `${randomBytes(4).toString("hex")}-${sanitizeAttachmentName(entry?.name)}`;
+      const target = path.join(workspaceDir, "attachments", storedName);
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, bytes);
+      notes.push(`[attached file: attachments/${storedName}]`);
+      fileMeta.push({ name: entry?.name ?? storedName, path: `attachments/${storedName}` });
+    } else {
+      throw new CliError("attachment kind must be 'image' or 'file'");
+    }
+  }
+  return { images, notes, fileMeta, imageMeta };
+}
+
+// ---------------------------------------------------------------------------
+// Workspace lanes (files stay files)
+// ---------------------------------------------------------------------------
+
+/**
+ * Two lanes, two roots.
+ *
+ * `source` is the PACKAGE — the tree the developer authors, terminus.json and
+ * AGENT.md included, and the only lane they may write. It is deliberately not
+ * the staged copy: editing a copy that is rebuilt on every reload would throw
+ * the edit away.
+ *
+ * `workspace` is the AGENT's own state: its files at the root, output/
+ * deliverables, attachments/ from chat, and memory/ notes. Read-only here,
+ * because it is the result of a run, not its input. (Session history is
+ * not a workspace concern — it lives in dev.db, behind the History
+ * button.) The package stages read-only IN PLACE at the same root, but
+ * those staged paths are deliberately NOT listed — they are runtime
+ * plumbing, byte-identical to the Source lane (still readable file-by-file
+ * so a path the agent mentions resolves when clicked).
+ */
+const LANES = ["source", "workspace"];
+const WRITABLE_LANES = new Set(["source"]);
+
+/**
+ * Never listed under source: the harness's own staging, VCS internals,
+ * dependency trees, OS litter. Everything the developer authored is theirs.
+ *
+ * The same segments `apps.mjs` refuses to upload (IGNORED_SEGMENTS) — the
+ * lane and the package have to agree about what is the developer's work,
+ * or the explorer shows folders that can never be pushed. `.terminus-dev`
+ * and `.workspace` are where a dev's state lived before `.terminus/dev`:
+ * nothing writes them any more, but a folder that ran an older build still
+ * has one sitting there, and it is no more the package than `.terminus` is.
+ */
+const SOURCE_SKIP = new Set([
+  TERMINUS_DIRECTORY, ".terminus-dev", ".workspace", ".git", "node_modules", ".DS_Store",
+]);
+
+/** The staged package paths (the reserved names), from the live local dev;
+ * empty when the dev has not started or runs remote. */
+function stagedPackagePaths(hub) {
+  return hub.local?.reservedPaths ?? [];
+}
+
+function laneRoot(hub, lane) {
+  if (lane === "source") return hub.dir;
+  if (lane === "workspace") return hub.workspace;
+  throw new CliError(`unknown lane '${lane}'`);
+}
+
+function laneFilePath(hub, lane, raw) {
+  const root = laneRoot(hub, lane);
+  const virtual = String(raw ?? "").replace(/^\/+/, "");
+  const parts = virtual.split("/");
+  if (
+    !virtual
+    || virtual.includes("\\")
+    || parts.some((part) => part === "" || part === "." || part === "..")
+  ) {
+    throw new CliError("path must be a safe file inside the lane");
+  }
+  const target = path.join(root, ...parts);
+  // Belt and braces over the segment check: whatever the parts were, the
+  // resolved path has to land under the lane it claims.
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new CliError("path escapes its lane");
+  }
+  return target;
+}
+
+async function listLane(root, skip) {
+  const entries = [];
+  const walk = async (dir, prefix) => {
+    let children;
+    try {
+      children = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const child of children) {
+      if (skip?.has(child.name)) continue;
+      const virtual = prefix ? `${prefix}/${child.name}` : child.name;
+      const full = path.join(dir, child.name);
+      if (child.isDirectory()) {
+        await walk(full, virtual);
+      } else if (entries.length < 2_000) {
+        const info = await stat(full).catch(() => null);
+        entries.push({ path: virtual, size: info?.size ?? 0, mtime: info?.mtimeMs ?? 0 });
+      }
+    }
+  };
+  await walk(root, "");
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+  return entries;
+}
+
+export async function openWithPlatform(target) {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", target] : [target];
+  return new Promise((resolve) => {
+    try {
+      const child = execFile(command, args, { detached: true, stdio: "ignore" }, (error) => {
+        resolve(!error);
+      });
+      child.unref();
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// The server
+// ---------------------------------------------------------------------------
+
+function sseStart(response) {
+  response.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache, no-transform",
+    // SSE dies behind buffering; nothing here compresses, and this header
+    // keeps any local proxy honest too.
+    "x-accel-buffering": "no",
+    connection: "keep-alive",
+  });
+  response.write(":ok\n\n");
+  return {
+    send(frame) {
+      response.write(`data: ${JSON.stringify(frame)}\n\n`);
+    },
+    end() {
+      response.end();
+    },
+  };
+}
+
+async function readJsonBody(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > BODY_LIMIT_BYTES) {
+      throw new CliError("request body is too large");
+    }
+    chunks.push(chunk);
+  }
+  if (!size) return {};
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new CliError("the request body is not valid JSON");
+  }
+}
+
+export function timingSafeTokenMatch(expected, presented) {
+  if (typeof presented !== "string" || presented.length !== expected.length) return false;
+  let mismatch = 0;
+  for (let index = 0; index < expected.length; index += 1) {
+    mismatch |= expected.charCodeAt(index) ^ presented.charCodeAt(index);
+  }
+  return mismatch === 0;
+}
+
+let webhookTokenWrites = Promise.resolve();
+
+/** Each declared webhook's local delivery token, made on first sight.
+ *
+ * The local ingress mirrors the platform's `POST /v1/hooks/{token}`: 32
+ * random bytes that are the whole capability, so a tunnel can deliver under
+ * its own Host, while a web page, which cannot read the token, cannot fire
+ * the hook. The tokens live beside the dev state, per folder, so a provider
+ * pointed at one keeps working across restarts; deleting the file rotates
+ * them. Writes are queued so two first sights cannot mint two tokens. */
+export function webhookTokens(devRoot, names) {
+  const pending = webhookTokenWrites.then(async () => {
+    const file = path.join(devRoot, "webhook-tokens.json");
+    let tokens = {};
+    try {
+      const saved = JSON.parse(await readFile(file, "utf8"));
+      if (saved && typeof saved === "object" && !Array.isArray(saved)) tokens = saved;
+    } catch {
+      // Not made yet, or unreadable: start again, which rotates every token.
+    }
+    let minted = false;
+    for (const name of names) {
+      if (typeof tokens[name] === "string" && /^[0-9a-f]{64}$/.test(tokens[name])) continue;
+      tokens[name] = randomBytes(32).toString("hex");
+      minted = true;
+    }
+    if (minted) await writeFile(file, `${JSON.stringify(tokens, null, 2)}\n`, { mode: 0o600 });
+    return tokens;
+  });
+  webhookTokenWrites = pending.catch(() => {});
+  return pending;
+}
+
+class DevHub {
+  constructor({ dir, flags, api }) {
+    this.dir = dir;
+    this.flags = flags;
+    this.api = api;
+    this.remote = Boolean(flags.remote);
+    this.devRoot = path.join(dir, DEV_DIRECTORY, "agent");
+    this.workspace = path.join(this.devRoot, "workspace");
+    this.mediaDir = path.join(this.devRoot, "media");
+    this.db = null;
+    this.local = null;
+    this.remoteDev = null;
+    this.remoteInfo = null;
+    this.compiled = null;
+    this.manifest = null;
+    this.model = null;
+    /** The reader's model pick for this dev run, distinct from the
+     * developer's `--model` flag. Never written to terminus.json. */
+    this.readerModel = null;
+    /** The reload in flight, so the next one waits rather than racing it. */
+    this.reloading = null;
+    /** Set by stop(); a stopped hub never starts another engine. */
+    this.stopped = false;
+    /** The live model catalog, fetched once when a manifest says "*". */
+    this.catalog = null;
+    /** Where the agent's mark comes from: "remote" (the linked artifact's own
+     * icon), "staged" (icon.png beside terminus.json, pre-first-push), or
+     * "default" (the house robot). Resolved on every reload. */
+    this.icon = { source: "default", appId: null };
+    /** The PUBLISHED version, or null while the agent has never shipped. The
+     * dev always runs the local package; this says what its users have. */
+    this.publishedVersion = null;
+    this.busy = false;
+    this.pendingReload = false;
+    this.eventSubscribers = new Set();
+    this.turn = null;
+    /** Re-mints the local engine's runtime token before it expires. */
+    this.credentialTimer = null;
+  }
+
+  broadcast(frame) {
+    for (const subscriber of this.eventSubscribers) {
+      try {
+        subscriber.send(frame);
+      } catch {
+        this.eventSubscribers.delete(subscriber);
+      }
+    }
+  }
+
+  activeSessionId() {
+    return this.remote ? this.remoteDev?.sessionId ?? null : this.local?.sessionId ?? null;
+  }
+
+  /** The local engine announces its session id on its first stdout frame,
+   * just after spawn — wait briefly rather than racing it. */
+  async waitForEngineSession(timeoutMs = 5_000) {
+    const startedAt = Date.now();
+    while (!this.activeSessionId() && Date.now() - startedAt < timeoutMs) {
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    return this.activeSessionId();
+  }
+
+  spend() {
+    const spend = this.remote ? this.remoteDev?.spend : this.local?.spend;
+    return spend ?? { tokens: 0, costUsd: 0 };
+  }
+
+  /** Compile info is served by the compile door on both substrates — the
+   * remote gear still shows the same toolset panels. */
+  async compileInfo() {
+    const pkg = await readAppPackage(this.dir, { includeSource: false });
+    if (pkg.manifest.kind !== "agent") {
+      throw new CliError(
+        `terminus dev chat is for kind 'agent' packages (found '${pkg.manifest.kind}')`,
+      );
+    }
+    this.manifest = pkg.manifest;
+    this.compiled = await this.api.json("POST /v1/agent-dev/compile", { body: pkg.manifest });
+    // A pick only stands while the agent still offers a choice that
+    // includes it — pinning the agent, or dropping the model from the
+    // allowlist, returns every reader to the default.
+    if (this.readerModel) {
+      const offered = await this.selectableModels();
+      if (offered.length < 2 || !offered.includes(this.readerModel)) this.readerModel = null;
+    }
+    this.model = this.readerModel ?? this.flags.model ?? this.compiled.model;
+    return this.compiled;
+  }
+
+  /** What the linked artifact says about itself: its mark and its published
+   * version. One listing answers both, so they are resolved together.
+   *
+   * The mark: the linked artifact wins, because Studio and the dev then look
+   * at ONE object and a change in either shows in both; a staged file only
+   * speaks for a package with no remote yet. Never fatal — an agent with
+   * neither still runs, wearing the robot.
+   */
+  /** The `id` the developer wrote in terminus.json — the link to a published
+   * artifact — read from the file itself. */
+  async linkedAddress() {
+    try {
+      const raw = await readFile(path.join(this.dir, "terminus.json"), "utf8");
+      return String(JSON.parse(raw).id ?? "").trim();
+    } catch {
+      return "";
+    }
+  }
+
+  async resolveIdentity() {
+    const next = { source: "default", appId: null };
+    let published = null;
+    // From the RAW manifest, not this.manifest: readAppPackage normalizes, and
+    // normalization moves the address off the manifest onto pkg.id — so the
+    // link is invisible to anything reading the compiled shape.
+    const address = (await this.linkedAddress()).toLowerCase();
+    if (address) {
+      try {
+        // The platform's one address door: the creation, yours or shared
+        // with you, drafts included — null when there is none.
+        const app = await resolveCreation(this.api, address);
+        if (app?.id) {
+          next.appId = app.id;
+          if (app.icon_url) next.source = "remote";
+          if (app.status === "published") {
+            // The platform's own display rule (routes/apps/releases.rs
+            // version_display): the manifest's semver label when a release
+            // carries one, else the integer release counter.
+            const label = String(app.release_label ?? "").trim();
+            published = label
+              || (app.release_version == null ? null : String(app.release_version));
+          }
+        }
+      } catch {
+        // Offline, or not logged in: a package we cannot ask about is a draft
+        // wearing whatever it carries locally.
+      }
+    }
+    if (next.source === "default" && await readStagedIcon(this.dir)) next.source = "staged";
+    this.icon = next;
+    this.publishedVersion = published;
+  }
+
+  /** The bytes to paint, or null for "draw the robot". */
+  async iconBytes() {
+    if (this.icon.source === "remote" && this.icon.appId) {
+      try {
+        const bytes = await this.api.bytes("GET /v1/apps/{app_id}/icon", { params: { app_id: this.icon.appId } });
+        // The platform stores only PNG, JPEG, and WebP marks, sniffed on upload.
+        const sniffed = sniffImage(bytes);
+        if (sniffed) return { bytes, mediaType: sniffed.mediaType };
+      } catch {
+        // Fall through: a mark we cannot fetch is a mark we do not have.
+      }
+    }
+    const staged = await readStagedIcon(this.dir);
+    return staged ? { bytes: staged.bytes, mediaType: staged.mediaType } : null;
+  }
+
+  /** A mark chosen in the dev. Linked packages write STRAIGHT to the
+   * artifact — icons are never release-pinned, so it is live at once and needs
+   * no republish. An unlinked package stages the file instead, and the first
+   * push carries it up. */
+  async setIcon(bytes) {
+    if (bytes.length > MAX_ICON_BYTES) {
+      throw new CliError("the icon must be 512KB or smaller");
+    }
+    const sniffed = sniffImage(bytes);
+    if (!sniffed) throw new CliError("the icon must be a PNG, JPEG, or WebP image");
+    if (this.icon.appId) {
+      try {
+        await this.api.request("PUT /v1/apps/{app_id}/icon", {
+          params: { app_id: this.icon.appId },
+          raw: { data: bytes, type: sniffed.mediaType },
+          as: "none",
+        });
+      } catch (error) {
+        throw new CliError(
+          `the platform refused the icon (${error.status ?? error.message}) — it stays as it was`,
+        );
+      }
+      this.icon = { ...this.icon, source: "remote" };
+      return { source: "remote" };
+    }
+    // No remote to hold it yet: stage beside terminus.json, replacing whatever
+    // extension was there so a package never carries two marks.
+    for (const name of STAGED_ICON_NAMES) {
+      if (name === `icon.${sniffed.extension}`) continue;
+      await rm(path.join(this.dir, name), { force: true }).catch(() => {});
+    }
+    await writeFile(path.join(this.dir, `icon.${sniffed.extension}`), bytes);
+    this.icon = { ...this.icon, source: "staged" };
+    return { source: "staged" };
+  }
+
+  async start() {
+    // The dev folder ignores itself before anything is written into it.
+    await ensureDevDirectory(this.dir);
+    this.db = await openDevDb(path.join(this.devRoot, "dev.db"));
+    if (this.remote) {
+      await this.compileInfo();
+      this.remoteDev = new AgentDevSession(this.api);
+      this.remoteInfo = await this.remoteDev.start(this.dir, this.flags.model);
+      this.model = this.remoteInfo.model || this.model;
+      this.db.ensureSession(this.remoteDev.sessionId, this.model, "remote");
+    } else {
+      this.local = new LocalDev(this.dir, this.flags, this.api, {
+        onFrame: (frame) => this.onEngineFrame(frame),
+      });
+      const started = await this.local.start();
+      this.compiled = started.compiled;
+      this.manifest = this.local.manifest;
+      this.model = this.local.model;
+      if (this.local.sessionId) this.db.ensureSession(this.local.sessionId, this.model, "local");
+    }
+    // AFTER the substrate branch, for the same reason reload() does it here:
+    // compileInfo() is a REMOTE-only path, so anything hung off it never runs
+    // for the default substrate.
+    await this.resolveIdentity();
+    this.armCredentialRefresh();
+  }
+
+  /**
+   * The local engine's runtime token is minted per start with a ~2h life,
+   * and agentd cannot refresh it by design — the host owns reauthentication.
+   * A dev left open past the expiry therefore watched every brokered tool
+   * fail with "the backend rejected the runtime token". So the hub reloads
+   * the engine (which re-mints, and resumes the conversation by session id)
+   * comfortably before the deadline; the busy guard inside reload() defers
+   * it past a running turn.
+   */
+  armCredentialRefresh() {
+    clearTimeout(this.credentialTimer);
+    if (this.remote) return;
+    const expiresAt = this.local?.runtimeExpiresAt;
+    if (!expiresAt) return;
+    const lead = 10 * 60 * 1000;
+    // Clamp above Node's 2^31-1ms setTimeout ceiling: a longer delay would
+    // overflow and fire IMMEDIATELY, turning a distant expiry into a reload
+    // loop. A token further out than the ceiling simply never needs the timer.
+    const wait = Math.min(Math.max(expiresAt - Date.now() - lead, 30_000), 2_147_483_647);
+    this.credentialTimer = setTimeout(() => {
+      this.reload().catch((error) => {
+        this.broadcast({ type: "engine_log", text: `credential refresh failed: ${error.message}` });
+      });
+    }, wait);
+    this.credentialTimer.unref?.();
+  }
+
+  /** Recompile + restart the engine. Local keeps the conversation (resume by
+   * session id); remote re-pushes the draft and starts a fresh one — the
+   * draft session's semantics, unchanged from v1. */
+  /**
+   * Reloads run ONE at a time. Settings write per change, so two edits a
+   * moment apart would otherwise assemble the dev workspace twice at once —
+   * one run deleting the files the other is still chmod-ing (ENOENT).
+   */
+  async reload() {
+    const queued = (this.reloading ?? Promise.resolve()).catch(() => {}).then(() => this.reloadOnce());
+    this.reloading = queued.catch(() => {});
+    return queued;
+  }
+
+  async reloadOnce() {
+    if (this.stopped) return { stopped: true };
+    if (this.busy) {
+      this.pendingReload = true;
+      return { deferred: true };
+    }
+    if (this.remote) {
+      await this.remoteDev?.stop();
+      await this.compileInfo();
+      this.remoteDev = new AgentDevSession(this.api);
+      this.remoteInfo = await this.remoteDev.start(this.dir, this.flags.model);
+      this.model = this.remoteInfo.model || this.model;
+      this.db.ensureSession(this.remoteDev.sessionId, this.model, "remote");
+    } else {
+      await this.local.stop();
+      // A pick only stands while the agent still offers a choice that
+      // includes it, and the engine restarts ON it — the same rule
+      // compileInfo() applies for the remote substrate.
+      if (this.readerModel) {
+        const offered = await this.selectableModels();
+        if (offered.length < 2 || !offered.includes(this.readerModel)) this.readerModel = null;
+      }
+      this.local.modelOverride = this.readerModel;
+      const started = await this.local.start();
+      this.compiled = started.compiled;
+      this.manifest = this.local.manifest;
+      this.model = this.local.model;
+    }
+    // The mark can change between reloads — a staged file added or deleted, or
+    // an icon set in Studio — so it is re-resolved every time, not cached from
+    // the first compile.
+    await this.resolveIdentity();
+    this.armCredentialRefresh();
+    this.broadcast({ type: "reload", model: this.model, session_id: this.activeSessionId() });
+    this.broadcast({ type: "icon", source: this.icon.source });
+    return { deferred: false };
+  }
+
+  onEngineFrame(frame) {
+    if (frame.type === "session_started") {
+      if (typeof frame.session_id === "string") {
+        this.db?.ensureSession(frame.session_id, this.model, "local");
+      }
+      return;
+    }
+    // The reactive half of the credential contract: if a rejection slipped
+    // through anyway (clock skew, a laptop asleep past the timer), re-mint
+    // via reload so the NEXT call works without a manual restart. While a
+    // turn runs this defers through pendingReload, so it fires once the
+    // failing turn settles.
+    if (
+      frame.type === "tool_result"
+      && String(frame.output ?? frame.content ?? "").includes("rejected the runtime token")
+    ) {
+      this.broadcast({
+        type: "engine_log",
+        text: "runtime credential expired — re-minting and reloading the engine",
+      });
+      this.reload().catch(() => {});
+    }
+    this.turn?.onFrame(frame);
+  }
+
+  /** Run one turn: mirror the user message, stream frames to the response,
+   * aggregate for the mirror, settle the session row. */
+  async sendMessage({ text, attachments }, stream) {
+    if (this.busy) throw new CliError("a turn is already running — interrupt it first");
+    this.busy = true;
+    const substrate = this.remote ? "remote" : "local";
+    try {
+      const prepared = await prepareAttachments(
+        attachments,
+        this.remote ? null : this.workspace,
+        this.mediaDir,
+      );
+      let fullText = String(text ?? "").trim();
+      for (const note of prepared.notes) {
+        fullText = fullText ? `${fullText}\n\n${note}` : note;
+      }
+      if (!fullText && !prepared.images.length) {
+        throw new CliError("say something (or attach something)");
+      }
+      const sessionId = await this.waitForEngineSession();
+      if (!sessionId) throw new CliError("the dev engine is not running");
+      this.db.ensureSession(sessionId, this.model, substrate);
+      this.db.insertMessage(sessionId, "user", fullText, {
+        images: prepared.imageMeta,
+        files: prepared.fileMeta,
+      });
+      this.db.touchSession(sessionId, { title: fullText || "(attachment)" });
+
+      const aggregate = {
+        text: "", tools: [], plan: null, cards: [], error: null, tokens: 0, costUsd: 0,
+      };
+      this.turn = {
+        onFrame: (frame) => {
+          let followUp = null;
+          switch (frame.type) {
+            case "delta":
+              if (typeof frame.text === "string") aggregate.text += frame.text;
+              break;
+            case "tool_call": {
+              const warnings = this.remote ? [] : compatWarningsForToolCall(frame);
+              let input = "";
+              try {
+                input = JSON.stringify(frame.input ?? {});
+              } catch {
+                input = "";
+              }
+              aggregate.tools.push({
+                name: frame.name ?? "?",
+                // ToolCall frames carry `id`; ToolResult echoes it back as
+                // `tool_use_id`.
+                tool_use_id: frame.id,
+                input: input.slice(0, TOOL_INPUT_MIRROR_CAP),
+                startedAt: Date.now(),
+                warnings,
+              });
+              if (warnings.length) {
+                // After the tool_call frame itself, so the UI can attach the
+                // warnings to the row it just rendered.
+                followUp = { type: "compat_warning", tool: frame.name, warnings };
+              }
+              break;
+            }
+            case "tool_result": {
+              const target =
+                aggregate.tools.find((tool) => tool.tool_use_id === frame.tool_use_id)
+                ?? aggregate.tools.findLast((tool) => tool.name === frame.name);
+              if (target) {
+                // The engine reports duration_ms itself; the wall-clock diff
+                // only covers older agentd builds that don't.
+                const ms = Number(frame.duration_ms);
+                if (Number.isFinite(ms) && ms > 0) target.ms = ms;
+                else if (target.startedAt) target.ms = Date.now() - target.startedAt;
+                delete target.startedAt;
+                if (frame.is_error === true) {
+                  target.is_error = true;
+                  const detail = String(frame.output ?? frame.content ?? "");
+                  target.error = detail.split("\n")[0].slice(0, 300);
+                }
+              }
+              break;
+            }
+            case "plan_update":
+              aggregate.plan = Array.isArray(frame.steps) ? frame.steps : null;
+              break;
+            case "host_event":
+              // send_file's card: keep it in the durable transcript so a
+              // reload still shows what was delivered.
+              if (frame.event?.type === "file_card") aggregate.cards.push(frame.event);
+              break;
+            case "usage": {
+              aggregate.tokens += (frame.input_tokens ?? 0) + (frame.output_tokens ?? 0);
+              const billed = Number.parseFloat(frame.billed_amount_usd);
+              const cost = Number.parseFloat(
+                Number.isFinite(billed) && billed > 0
+                  ? frame.billed_amount_usd
+                  : frame.est_provider_cost_usd,
+              );
+              if (Number.isFinite(cost)) aggregate.costUsd += cost;
+              break;
+            }
+            case "error":
+              aggregate.error = frame.message ?? "the turn failed";
+              break;
+            default:
+              break;
+          }
+          stream.send(frame);
+          if (followUp) stream.send(followUp);
+        },
+      };
+      try {
+        if (this.remote) {
+          await this.remoteDev.send(fullText, prepared.images, (frame) =>
+            this.turn.onFrame(frame),
+          );
+        } else {
+          await this.local.send(fullText, prepared.images);
+        }
+      } catch (error) {
+        if (!aggregate.error) aggregate.error = error?.message ?? "the turn failed";
+        stream.send({ type: "error", message: aggregate.error });
+      }
+      if (aggregate.text || aggregate.tools.length) {
+        this.db.insertMessage(sessionId, "assistant", aggregate.text, {
+          tools: aggregate.tools,
+          plan: aggregate.plan ?? undefined,
+          cards: aggregate.cards.length ? aggregate.cards : undefined,
+        });
+      }
+      if (aggregate.error) {
+        this.db.insertMessage(sessionId, "error", aggregate.error, null);
+      }
+      this.db.touchSession(sessionId, {
+        tokens: aggregate.tokens,
+        costUsd: aggregate.costUsd,
+      });
+      stream.send({
+        type: "done",
+        session_id: sessionId,
+        tokens: this.spend().tokens,
+        cost_usd: this.spend().costUsd,
+      });
+      // Trigger simulation chains turns on the step results
+      // (`steps.N.result.text`), so the aggregate text is the return value.
+      return aggregate.text;
+    } finally {
+      this.turn = null;
+      this.busy = false;
+      if (this.pendingReload) {
+        this.pendingReload = false;
+        this.reload().catch((error) => {
+          this.broadcast({ type: "engine_log", text: `reload failed: ${error.message}` });
+        });
+      }
+    }
+  }
+
+  interrupt() {
+    if (this.remote) this.remoteDev?.interrupt();
+    else this.local?.interrupt();
+  }
+
+  async connectorStatuses() {
+    const slugs = this.compiled?.grants?.connectors ?? [];
+    if (!slugs.length) return [];
+    try {
+      const status = await this.api.json("POST /v1/connectors/status", { body: { slugs } });
+      return status.connectors ?? [];
+    } catch {
+      return slugs.map((slug) => ({ slug, status: "unknown" }));
+    }
+  }
+
+  /** What a reader of this agent may pick between: the pinned default plus
+   * the manifest's allowlist. A pinned agent offers exactly one. Mirrors the
+   * platform's `allowed_models()`. */
+  /**
+   * The mode a `models` list declares: "all" | "selective" | "default".
+   *
+   * Takes the list rather than reading `this.manifest`, which is only
+   * refreshed on reload — so right after a manifest write it still holds the
+   * PREVIOUS value, and the panel would report the mode one edit behind.
+   */
+  /** The raw manifest as AUTHORED. readAppPackage normalizes, which moves and
+   * renames things; the model policy has to be read from the file. */
+  async authoredManifest() {
+    try {
+      return JSON.parse(await readFile(path.join(this.dir, "terminus.json"), "utf8"));
+    } catch {
+      return {};
+    }
+  }
+
+  async selectableModels() {
+    const section = readModelSection(await this.authoredManifest());
+    const seen = [];
+    const add = (model) => {
+      const trimmed = String(model ?? "").trim();
+      if (trimmed && !seen.includes(trimmed)) seen.push(trimmed);
+    };
+    add(this.compiled?.model);
+    if (section.mode === "all") {
+      // The same resolution the platform performs, so the reader's picker here
+      // offers exactly what a visitor would be offered.
+      for (const model of await this.platformModels()) add(model);
+      return seen;
+    }
+    for (const model of section.available) add(model);
+    return seen;
+  }
+
+  /** The live catalog, cached for the run: resolving "all" should not cost a
+   * round trip on every turn. */
+  async platformModels() {
+    if (this.catalog) return this.catalog;
+    try {
+      const data = await this.api.json("GET /v1/terminus/models");
+      const list = Array.isArray(data) ? data : data.models ?? data.data ?? [];
+      this.catalog = list
+        .map((model) => String(model.slug ?? model.id ?? model.model ?? "").trim())
+        .filter(Boolean);
+    } catch {
+      this.catalog = [];
+    }
+    return this.catalog;
+  }
+
+  async devInfo() {
+    const manifest = this.manifest ?? {};
+    // The Setup panel edits the AUTHORED tools list. readAppPackage
+    // normalizes the sugar into `capabilities`, so read the raw ground
+    // truth back from terminus.json.
+    const authored = await this.authoredManifest();
+    const manifestTools = Array.isArray(authored.tools) ? authored.tools : [];
+    const modelSection = readModelSection(authored);
+    const manifestModels = modelSection.available;
+    return {
+      substrate: this.remote ? "remote" : "local",
+      agent: {
+        name: manifest.name ?? path.basename(this.dir),
+        slug: manifest.slug ?? "",
+        description: manifest.description ?? "",
+        // "default" means the page draws the robot; anything else means it can
+        // GET /api/agent-icon. icon_linked decides whether a new mark goes live
+        // at once or waits for the first push.
+        icon: this.icon.source,
+        icon_linked: Boolean(this.icon.appId),
+        // null until the agent has shipped; the dev always runs the LOCAL
+        // package, which is why both versions are reported.
+        published_version: this.publishedVersion,
+        local_version: manifest.version ?? null,
+        // "default" | "observed", as the file says it — the Type switch.
+        type: readAgentType(authored),
+      },
+      model: this.model,
+      // What the FILE says, which a reader's pick above does not change — the
+      // Settings panel configures terminus.json, not this run.
+      model_default: modelSection.default || this.compiled?.model || null,
+      session_id: this.activeSessionId(),
+      tools: (this.compiled?.tools ?? []).map((tool) => ({
+        name: tool.name,
+        description: (tool.description ?? "").slice(0, 400),
+      })),
+      manifest_tools: manifestTools,
+      // The list only matters under `selective`; the mode is the setting.
+      manifest_models: manifestModels,
+      model_policy: modelSection.mode,
+      discovery: readDiscovery(authored),
+      grants: this.compiled?.grants ?? {},
+      budgets: this.compiled?.budgets ?? {},
+      connectors: await this.connectorStatuses(),
+      spend: this.spend(),
+      remote: this.remote
+        ? { address: this.remoteInfo?.address, revision: this.remoteInfo?.revision }
+        : null,
+    };
+  }
+
+  /** One simulated trigger firing (standing-agents P4): input built the way
+   * the platform builds it, templates resolved the same way, agent.run steps
+   * as real turns on this dev with the platform's untrusted-event fence.
+   * A manual fire is a test, so an unchanged watch still fires — with a
+   * notice saying so. */
+  async fireTrigger({ name, payload }, stream) {
+    if (this.remote) {
+      throw new CliError("trigger simulation runs on the local dev — restart without --remote");
+    }
+    const raw = JSON.parse(await readFile(path.join(this.dir, "terminus.json"), "utf8"));
+    const trigger = listDevTriggers(raw).find((candidate) => candidate.name === name);
+    if (!trigger) throw new CliError(`no declared trigger named '${name}'`);
+    const built = await buildTriggerInput(trigger, { payload, devRoot: this.devRoot });
+    stream.send({
+      type: "trigger_fired",
+      trigger: trigger.name,
+      kind: trigger.kind,
+      ...(built.baseline ? { baseline: true } : {}),
+      ...(built.unchanged ? { unchanged: true } : {}),
+    });
+    if (built.baseline) {
+      stream.send({
+        type: "notice",
+        message: `watch '${trigger.name}': first poll recorded the baseline — this firing tests the loop with the current content`,
+      });
+    } else if (built.unchanged) {
+      stream.send({
+        type: "notice",
+        message: `watch '${trigger.name}': the source is unchanged — on the platform this would not fire`,
+      });
+    }
+    await runTriggerFiring({
+      manifest: raw,
+      trigger,
+      input: built.input,
+      runTurn: (prompt) => {
+        // Turn boundary for the transcript: the composed prompt (fence and
+        // all) IS what the agent receives — seeing it is the point of a
+        // dev.
+        stream.send({ type: "trigger_turn", text: prompt });
+        return this.sendMessage({ text: prompt, attachments: [] }, stream);
+      },
+      emit: (frame) => stream.send(frame),
+    });
+  }
+
+  async stop() {
+    // A reload in flight has stopped the old engine and is starting a new
+    // one; stopping now would find nothing to stop, and the new engine would
+    // outlive the dev, keeping the process alive. So it lands first, and its
+    // engine and credential timer are the ones stopped here.
+    this.stopped = true;
+    await this.reloading;
+    clearTimeout(this.credentialTimer);
+    if (this.remote) await this.remoteDev?.stop();
+    else await this.local?.stop();
+    // Null after close so a second stop (shutdown races, tests) is a no-op
+    // instead of a double-close throw.
+    this.db?.close();
+    this.db = null;
+  }
+}
+
+/** Start the dev web server; resolves when it is listening. Exported for
+ * tests (which drive it against a fake agentd and a mock API). */
+export async function startDevServer({ commandArgs, dir, flags, api }) {
+  // A busy --port is reported before the engine starts, so it costs no
+  // compile and no agentd, and says who holds the port.
+  const basePort = resolveDevPortRange(flags.port, 1, 4720);
+  if (flags.port !== undefined) {
+    await assertDevPortRangeAvailable({ basePort, commandArgs, count: 1, directory: dir });
+  }
+  const hub = new DevHub({ dir, flags, api });
+  await hub.start();
+  const token = randomBytes(16).toString("hex");
+  const webBase = normalizeBase(
+    flags.web_base ?? process.env.TERMINUS_WEB_BASE ?? "https://www.terminus.build",
+  );
+
+  const authorized = (request, url) => {
+    const presented = request.headers["x-dev-token"] ?? url.searchParams.get("token");
+    return timingSafeTokenMatch(token, presented) && isLoopbackOrigin(request);
+  };
+
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, "http://127.0.0.1");
+    const route = `${request.method} ${url.pathname}`;
+    try {
+      // Local webhook ingress (`POST /hooks/{token}`), the platform's shape:
+      // outside the dev-token gate and the Host check, so curl or a
+      // provider's redeliver button through a tunnel can exercise the whole
+      // loop. The token (see webhookTokens) is the capability. The firing
+      // runs in the background and its frames land on the dev event stream.
+      const hook = request.method === "POST" && /^\/hooks\/([0-9a-f]{64})$/.exec(url.pathname);
+      if (hook) {
+        const raw = JSON.parse(await readFile(path.join(dir, "terminus.json"), "utf8"));
+        const webhooks = listDevTriggers(raw).filter((candidate) => candidate.kind === "webhook");
+        const tokens = await webhookTokens(hub.devRoot, webhooks.map(({ name }) => name));
+        const trigger = webhooks.find((candidate) => timingSafeTokenMatch(tokens[candidate.name], hook[1]));
+        if (!trigger) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "no declared webhook has this token" }));
+          return;
+        }
+        const body = await readJsonBody(request).catch(() => ({}));
+        if (hub.busy) {
+          response.writeHead(429, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "a turn is already running" }));
+          return;
+        }
+        const broadcastStream = { send: (frame) => hub.broadcast(frame), end: () => {} };
+        void hub
+          .fireTrigger({ name: trigger.name, payload: body }, broadcastStream)
+          .catch((error) => hub.broadcast({ type: "error", message: error.message }));
+        response.writeHead(202, { "content-type": "application/json" });
+        response.end(JSON.stringify({ ok: true }));
+        return;
+      }
+      // Everything else, the page with the dev token first, answers only
+      // requests addressed to localhost (see isLoopbackHost).
+      if (!isLoopbackHost(request)) return refuseForeignHost(request, response);
+      if (url.pathname === DEV_ABOUT_PATH) {
+        answerDevAbout(request, response, {
+          kind: "agent",
+          app: (await hub.linkedAddress()) || path.basename(path.resolve(dir)),
+          directory: path.resolve(dir),
+          remote: hub.remote,
+        });
+        return;
+      }
+      if (route === "GET /" || route === "GET /index.html") {
+        const html = await readFile(path.join(uiDir, "index.html"), "utf8");
+        response.writeHead(200, {
+          "content-type": "text/html; charset=utf-8",
+          "cache-control": "no-store",
+        });
+        response.end(
+          html.replace(
+            "__DEV_BOOT__",
+            JSON.stringify({ token, webBase }).replaceAll("</", "<\\/"),
+          ),
+        );
+        return;
+      }
+      if (request.method === "GET" && url.pathname.startsWith("/assets/")) {
+        const name = url.pathname.slice("/assets/".length);
+        if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+          response.writeHead(404).end();
+          return;
+        }
+        try {
+          const bytes = await readFile(path.join(uiDir, name));
+          // The page's own code must never be served stale. Without a header
+          // the browser caches heuristically, and a dev running an old
+          // bundle silently disagrees with the server it is talking to — the
+          // hardest kind of bug to see, because everything LOOKS current.
+          // Fonts and artwork are content-addressed by name and can cache.
+          const code = /\.(js|mjs|css|html)$/i.test(name);
+          response.writeHead(200, {
+            "content-type": contentTypeFor(name),
+            "cache-control": code ? "no-store" : "public, max-age=86400",
+          });
+          response.end(bytes);
+        } catch {
+          response.writeHead(404).end();
+        }
+        return;
+      }
+      if (!url.pathname.startsWith("/api/")) {
+        response.writeHead(404).end();
+        return;
+      }
+      if (!authorized(request, url)) {
+        response.writeHead(401, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: "dev token required" }));
+        return;
+      }
+      const json = (status, body) => {
+        response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+        response.end(JSON.stringify(body));
+      };
+      switch (route) {
+        case "GET /api/dev":
+          return json(200, await hub.devInfo());
+        // The reader's pick. `model` policy decides whether the page may
+        // offer this at all; the server still refuses anything outside the
+        // agent's own allowlist, because the door is the authority.
+        case "POST /api/model": {
+          const body = await readJsonBody(request);
+          const wanted = String(body.model ?? "").trim();
+          const allowed = await hub.selectableModels();
+          if (!wanted) {
+            hub.readerModel = null;
+          } else if (allowed.includes(wanted)) {
+            hub.readerModel = wanted;
+          } else {
+            throw new CliError("that model is not one this agent offers");
+          }
+          const result = await hub.reload();
+          return json(200, { ok: true, ...result, dev: await hub.devInfo() });
+        }
+        case "POST /api/reload": {
+          const result = await hub.reload();
+          return json(200, { ok: true, ...result, model: hub.model });
+        }
+        case "POST /api/interrupt":
+          hub.interrupt();
+          return json(200, { ok: true });
+        case "GET /api/events": {
+          const stream = sseStart(response);
+          hub.eventSubscribers.add(stream);
+          request.on("close", () => hub.eventSubscribers.delete(stream));
+          return undefined;
+        }
+        case "POST /api/messages": {
+          const body = await readJsonBody(request);
+          const stream = sseStart(response);
+          try {
+            await hub.sendMessage(body, stream);
+          } catch (error) {
+            stream.send({ type: "error", message: error.message });
+            stream.send({ type: "done" });
+          }
+          stream.end();
+          return undefined;
+        }
+        case "GET /api/triggers": {
+          const raw = JSON.parse(await readFile(path.join(dir, "terminus.json"), "utf8"));
+          const state = await loadWatchState(hub.devRoot);
+          const port = server.address()?.port;
+          const triggers = listDevTriggers(raw);
+          const hookTokens = await webhookTokens(
+            hub.devRoot,
+            triggers.filter(({ kind }) => kind === "webhook").map(({ name }) => name),
+          );
+          // The Schedules tab shows what a firing DOES, so each trigger
+          // carries a step summary from the automation it names.
+          const automations = new Map(
+            (effectiveWorkloads(raw).automations ?? []).map((automation) => [automation.name, automation]),
+          );
+          const stepSummary = (step) => ({
+            action: step?.action ?? "?",
+            summary: String(
+              step?.action === "agent.run"
+                ? step?.params?.prompt ?? ""
+                : step?.params?.title ?? step?.params?.connector ?? "",
+            ).slice(0, 200),
+          });
+          return json(200, {
+            triggers: triggers.map((trigger) => ({
+              ...trigger,
+              steps: (automations.get(trigger.automation)?.steps ?? []).map(stepSummary),
+              ...(trigger.kind === "webhook" && port
+                ? { local_url: `http://127.0.0.1:${port}/hooks/${hookTokens[trigger.name]}` }
+                : {}),
+              ...(trigger.kind === "watch"
+                ? { baseline: Boolean(state[trigger.name]) }
+                : {}),
+            })),
+          });
+        }
+        case "POST /api/triggers/fire": {
+          const body = await readJsonBody(request);
+          const stream = sseStart(response);
+          try {
+            await hub.fireTrigger(body, stream);
+          } catch (error) {
+            stream.send({ type: "error", message: error.message });
+          }
+          stream.send({ type: "done" });
+          stream.end();
+          return undefined;
+        }
+        // Images the developer attached, served back to the transcript from
+        // the harness's own store. Ids are minted here, so an id that is not
+        // one of ours can never address a path.
+        case "GET /api/media": {
+          const id = url.searchParams.get("id") ?? "";
+          if (!/^[0-9a-f]{16}\.(png|jpg|webp|gif)$/.test(id)) {
+            return json(400, { error: "bad media id" });
+          }
+          let bytes;
+          try {
+            bytes = await readFile(path.join(hub.mediaDir, id));
+          } catch {
+            return json(404, { error: "no such attachment" });
+          }
+          response.writeHead(200, {
+            "content-type": contentTypeFor(id),
+            "cache-control": "private, max-age=86400",
+          });
+          response.end(bytes);
+          return undefined;
+        }
+        case "GET /api/agent-icon": {
+          const art = await hub.iconBytes();
+          if (!art) return json(404, { error: "this agent has no icon of its own" });
+          response.writeHead(200, {
+            "content-type": art.mediaType,
+            // The mark can change under us (Studio, or an upload here), so
+            // never let a stale one stick.
+            "cache-control": "no-store",
+          });
+          response.end(art.bytes);
+          return undefined;
+        }
+        case "PUT /api/agent-icon": {
+          const chunks = [];
+          let size = 0;
+          for await (const chunk of request) {
+            size += chunk.length;
+            if (size > MAX_ICON_BYTES) return json(400, { error: "the icon must be 512KB or smaller" });
+            chunks.push(chunk);
+          }
+          const placed = await hub.setIcon(Buffer.concat(chunks));
+          hub.broadcast({ type: "icon", source: placed.source });
+          return json(200, { ok: true, ...placed, dev: await hub.devInfo() });
+        }
+        case "GET /api/workspace": {
+          const lane = url.searchParams.get("lane") ?? "source";
+          if (!LANES.includes(lane)) return json(400, { error: `unknown lane '${lane}'` });
+          let files = await listLane(
+            laneRoot(hub, lane),
+            lane === "source" ? SOURCE_SKIP : null,
+          );
+          if (lane === "workspace") {
+            // The staged package is plumbing, not agent state (see LANES
+            // doc) — the Source lane is where humans read those files.
+            const staged = new Set(stagedPackagePaths(hub));
+            files = files.filter((file) => !staged.has(file.path));
+          }
+          return json(200, { lane, files, writable: WRITABLE_LANES.has(lane) });
+        }
+        case "PUT /api/workspace/file": {
+          const lane = url.searchParams.get("lane") ?? "source";
+          if (!WRITABLE_LANES.has(lane)) {
+            return json(403, { error: `${lane}/ belongs to the agent — it is read-only here` });
+          }
+          const target = laneFilePath(hub, lane, url.searchParams.get("path"));
+          await stat(target).catch(() => {
+            throw new CliError("no such file — the dev edits files that exist");
+          });
+          const chunks = [];
+          let size = 0;
+          for await (const chunk of request) {
+            size += chunk.length;
+            if (size > BODY_LIMIT_BYTES) throw new CliError("that file is too large to save");
+            chunks.push(chunk);
+          }
+          await writeFile(target, Buffer.concat(chunks));
+          // The package watcher picks this up and hot-reloads the agent, which
+          // is the point: editing AGENT.md should change the next turn.
+          return json(200, { ok: true });
+        }
+        case "GET /api/workspace/file": {
+          const target = laneFilePath(hub, url.searchParams.get("lane") ?? "source", url.searchParams.get("path"));
+          let bytes;
+          try {
+            bytes = await readFile(target);
+          } catch {
+            return json(404, { error: "no such workspace file" });
+          }
+          const headers = { "content-type": contentTypeFor(target) };
+          if (url.searchParams.get("download") === "1") {
+            headers["content-disposition"] =
+              `attachment; filename="${path.basename(target).replace(/["\\]/g, "")}"`;
+          }
+          response.writeHead(200, headers);
+          response.end(bytes);
+          return undefined;
+        }
+        case "POST /api/workspace/open": {
+          const body = await readJsonBody(request);
+          const target = laneFilePath(hub, body.lane ?? "source", body.path);
+          await stat(target).catch(() => {
+            throw new CliError("no such workspace file");
+          });
+          return json(200, { ok: await openWithPlatform(target) });
+        }
+        case "GET /api/history": {
+          return json(200, { sessions: hub.db.listSessions() });
+        }
+        case "GET /api/models": {
+          const models = await api.json("GET /v1/terminus/models");
+          return json(200, models);
+        }
+        // One Store, three kinds. The public search takes the kind, so the
+        // skills, services and agents places are the same door with a
+        // different word — and a service also needs its operations, which
+        // only its own record carries.
+        //
+        // No words is a BROWSE, not an empty answer: the picker opens onto
+        // the Store's own ranking for that kind, the way the Store window
+        // does, and typing narrows it. `track=false` on every request —
+        // the door records a committed search when it is left out, and a
+        // developer filling in a manifest is not a person searching the
+        // Store.
+        case "GET /api/store": {
+          const query = (url.searchParams.get("q") ?? "").trim();
+          const kind = { skills: "skill", services: "service", agents: "agent" }[
+            url.searchParams.get("kind") ?? "skills"
+          ];
+          if (!kind) throw new CliError("store search takes kind=skills|services|agents");
+          // A service costs one detail request per row before it can even be
+          // offered, so its page is shorter than the other two.
+          const limit = kind === "service" ? 12 : 24;
+          const found = await api.json("GET /v1/skills/search", {
+            query: { q: query, limit, kinds: kind, scope: "store", track: "false" },
+          });
+          const rows = (Array.isArray(found) ? found : found.results ?? found.skills ?? found.items ?? [])
+            .map((row) => ({
+              address: row.address ?? row.uid ?? "",
+              name: row.name ?? row.title ?? row.address ?? "",
+              description: row.description ?? row.short_description ?? "",
+              kind,
+              official: Boolean(row.is_official),
+              icon_url: row.illustration_url ?? null,
+              likes: row.like_count ?? 0,
+              rating: row.rating_average ?? null,
+              ratings: row.rating_count ?? 0,
+              price: row.price_usd ?? null,
+              pricing: row.pricing ?? "",
+              version: row.release_version ?? null,
+            }))
+            .filter((row) => row.address);
+          if (kind !== "service") return json(200, { results: rows });
+          // A service is granted per operation, so the picker has to know
+          // them — and what each one does and costs — before it can add one.
+          const detailed = await Promise.all(rows.map(async (row) => {
+            const [publisher, slug] = row.address.replace(/^@/, "").split("/");
+            try {
+              const record = await api.json("GET /v1/services/by-address/{publisher}/{slug}", {
+                params: { publisher, slug },
+              });
+              return {
+                ...row,
+                operations: (record.operations ?? [])
+                  .filter((operation) => operation?.id)
+                  .map((operation) => ({
+                    id: operation.id,
+                    description: operation.description ?? "",
+                    price: operation.price_credits ?? null,
+                  })),
+              };
+            } catch {
+              return { ...row, operations: [] };
+            }
+          }));
+          return json(200, { results: detailed.filter((row) => row.operations.length) });
+        }
+        case "GET /api/connectors":
+          return json(200, {
+            connectors: await hub.connectorStatuses(),
+            connect_url: `${webBase}/os?settings=connections`,
+          });
+        case "GET /api/tool-catalog": {
+          // What the picker browses, in the two shapes a developer names out
+          // loud: the platform's own lanes as BUNDLES, and one record per
+          // CONNECTOR holding the profiles it offers. `tools` is the flat
+          // list of every declarable id, kept because search filters over it
+          // and the window's hover lines read from it. The catalog degrades
+          // to the core lanes when the platform is unreachable — search
+          // should never be the reason the picker errors.
+          const tools = [...CORE_TOOL_CATALOG];
+          const connectors = [];
+          try {
+            const data = await api.json("GET /v1/connectors");
+            for (const connector of data.connectors ?? []) {
+              const profiles = (connector.profiles ?? []).filter((profile) => profile?.id);
+              for (const profile of profiles) {
+                tools.push({
+                  id: profile.id,
+                  name: profile.name ?? profile.id,
+                  desc: profile.description ?? "",
+                  kind: "connector",
+                  connector: connector.slug ?? "",
+                  connector_name: connector.name ?? connector.slug ?? "",
+                });
+              }
+              // A connector with no agent profiles grants nothing, so it is
+              // not a thing this picker can offer.
+              if (!profiles.length) continue;
+              connectors.push({
+                slug: connector.slug ?? "",
+                name: connector.name ?? connector.slug ?? "",
+                description: connector.description ?? "",
+                category: connector.category ?? "other",
+                // The developer's OWN link to the product, which is what
+                // makes a grant testable in this chat — not the visitor's.
+                status: connector.connection?.status ?? "not_connected",
+                account: connector.connection?.account_label ?? null,
+                profiles: profiles.map((profile) => ({
+                  id: profile.id,
+                  profile: profile.profile ?? String(profile.id).split(".").pop(),
+                  name: profile.name ?? profile.id,
+                  description: profile.description ?? "",
+                  operations: profile.operations ?? [],
+                })),
+              });
+            }
+          } catch { /* offline: the core lanes still list */ }
+          return json(200, { tools, bundles: TOOL_BUNDLES, connectors });
+        }
+        case "POST /api/spend-approvals": {
+          // The spend card's answer: proxy the approval to the account door
+          // with the developer's own credential. Local turns never bill, so
+          // this only matters on --remote (the draft lane runs the hosted
+          // gate).
+          const body = await readJsonBody(request);
+          if (typeof body.session_id !== "string" || !body.session_id) {
+            throw new CliError("a spend approval names its session_id");
+          }
+          const approved = await api.json("POST /v1/terminus/sessions/{session_id}/spend-approvals", {
+            params: { session_id: body.session_id },
+            body: { scope: body.scope ?? "" },
+          });
+          return json(200, approved);
+        }
+        case "PUT /api/manifest": {
+          const ops = await readJsonBody(request);
+          await editManifestFile(dir, (manifest) => applyManifestOps(manifest, ops));
+          if (ops.model !== undefined) hub.readerModel = null;
+          const result = await hub.reload();
+          return json(200, { ok: true, ...result, dev: await hub.devInfo() });
+        }
+        default: {
+          const messages = /^GET \/api\/sessions\/([0-9a-f-]{36})\/messages$/.exec(route);
+          if (messages) {
+            return json(200, { messages: hub.db.listMessages(messages[1]) });
+          }
+          return json(404, { error: "no such dev door" });
+        }
+      }
+    } catch (error) {
+      if (!response.headersSent) {
+        response.writeHead(error instanceof CliError ? 400 : 500, {
+          "content-type": "application/json",
+        });
+        response.end(JSON.stringify({ error: error.message ?? "dev server error" }));
+      } else {
+        response.end();
+      }
+      if (!(error instanceof CliError)) {
+        console.error(`[dev] ${route}: ${error.stack ?? error}`);
+      }
+    }
+  });
+
+  let port = basePort;
+  let lastError = null;
+  for (let attempt = 0; attempt < (flags.port !== undefined ? 1 : PORT_ATTEMPTS); attempt += 1) {
+    try {
+      await listenDevServer(server, port);
+      lastError = null;
+      port = server.address().port;
+      break;
+    } catch (error) {
+      lastError = error;
+      if (error?.code !== "EADDRINUSE") throw error;
+      port += 1;
+    }
+  }
+  if (lastError) {
+    // The engine is already up; it goes down with the failed start.
+    await hub.stop().catch(() => {});
+    if (flags.port !== undefined) {
+      // Taken while the engine started, after the check above said it was free.
+      throw await devPortUnavailableError({
+        basePort,
+        commandArgs,
+        count: 1,
+        directory: dir,
+        failures: [{ port: basePort, error: lastError }],
+      });
+    }
+    throw new CliError(`no free port between ${basePort} and ${port - 1}; pick one with --port`);
+  }
+
+  // Watch the package for edits — from any editor or coding agent — and hot
+  // reload; terminus.json stays the single ground truth.
+  /**
+   * Reloads are paced, not just debounced.
+   *
+   * The compile door is rate-limited per user, and the editor autosaves on
+   * every pause in typing — so a plain debounce still asks the server to
+   * recompile once every couple of seconds for as long as someone is writing.
+   * A floor between reloads coalesces a writing session into a handful, and
+   * the trailing call guarantees the LAST edit is always the one that lands.
+   */
+  const MIN_RELOAD_GAP_MS = 3_000;
+  let debounce = null;
+  let lastReloadAt = 0;
+
+  const scheduleReload = () => {
+    clearTimeout(debounce);
+    const since = Date.now() - lastReloadAt;
+    const wait = Math.max(WATCH_DEBOUNCE_MS, MIN_RELOAD_GAP_MS - since);
+    debounce = setTimeout(() => {
+      lastReloadAt = Date.now();
+      hub
+        .reload()
+        .catch((error) => hub.broadcast({ type: "engine_log", text: `reload failed: ${error.message}` }));
+    }, wait);
+  };
+
+  const watcher = watch(dir, { recursive: true }, (_event, file) => {
+    if (!file || file.includes(TERMINUS_DIRECTORY) || file.includes(".git")) return;
+    // The tree is told at once; the recompile waits for the typing to settle.
+    hub.broadcast({ type: "files", lane: "source" });
+    scheduleReload();
+  });
+
+  // The agent's own lanes change while a turn runs, and nothing was watching
+  // them — the explorer only saw new output when something else forced a
+  // reload. No debounce and no recompile: a file appearing is not a reason to
+  // rebuild the agent.
+  let lanesWatcher = null;
+  try {
+    lanesWatcher = watch(hub.workspace, { recursive: true }, (_event, file) => {
+      if (!file) return;
+      // The staged package is restaged on reload (which broadcasts its own
+      // refresh) and hidden from the tree anyway, so only the agent's live
+      // half of the tree pings the explorer.
+      const relative = String(file).split(path.sep).join("/");
+      if (stagedPackagePaths(hub).includes(relative)) return;
+      hub.broadcast({ type: "files", lane: "workspace" });
+    });
+  } catch {
+    // A platform without recursive watch still works; the tree just waits for
+    // the next explicit load.
+  }
+
+  const close = async () => {
+    watcher.close();
+    lanesWatcher?.close();
+    clearTimeout(debounce);
+    // End every open event stream first: an SSE response never finishes on
+    // its own, and `server.close()` waits for it forever otherwise.
+    for (const subscriber of hub.eventSubscribers) {
+      try {
+        subscriber.end();
+      } catch {
+        // The socket is already gone; nothing to end.
+      }
+    }
+    hub.eventSubscribers.clear();
+    const closed = new Promise((resolve) => server.close(resolve));
+    // The browser also parks idle keep-alive sockets; reclaim them now
+    // rather than waiting out the keep-alive timeout.
+    server.closeAllConnections();
+    await closed;
+    await hub.stop();
+  };
+  const address = `http://127.0.0.1:${port}`;
+  return { server, hub, port, token, url: `${address}/`, close };
+}
+
+/** The interactive `terminus dev` entry: start the server, open the browser,
+ * run until Ctrl-C. */
+export async function runDevServer({ commandArgs, dir, flags, api }) {
+  const started = await startDevServer({ commandArgs, dir, flags, api });
+  const substrate = flags.remote ? "remote (draft on the production engine)" : "local";
+  console.log(`terminus dev (${substrate})`);
+  console.log(`${started.url}`);
+  console.log(
+    "Chat, attachments, files, and settings live in the browser. Edits to "
+    + "this package hot-reload. Headless lane: terminus dev --prompt \"…\" "
+    + "--json. Ctrl-C stops the server.",
+  );
+  if (!flags.no_open) {
+    await openWithPlatform(started.url);
+  }
+  await new Promise((resolve) => {
+    process.once("SIGINT", resolve);
+    process.once("SIGTERM", resolve);
+  });
+  console.log("\nClosing…");
+  // A second Ctrl-C while we drain is an order, not a request.
+  process.once("SIGINT", () => process.exit(130));
+  // Read the goodbye numbers before close() shuts the SQLite mirror.
+  const spend = started.hub.spend();
+  let conversations = 0;
+  try {
+    // Only conversations someone actually had — the auto-created empty
+    // session is not worth a goodbye line.
+    conversations = started.hub.db?.listSessions().filter((s) => s.turns > 0).length ?? 0;
+  } catch {
+    // The mirror is best-effort at exit; missing numbers are not an error.
+  }
+  await started.close();
+  const spent = spend.tokens > 0
+    ? ` — ${spend.tokens} tok${spend.costUsd > 0 ? ` · $${spend.costUsd.toFixed(4)}` : ""} this run`
+    : "";
+  console.log(`Stopped${spent}.`);
+  if (conversations > 0) {
+    const noun = conversations === 1 ? "conversation" : "conversations";
+    console.log(
+      `${conversations} ${noun} saved in .terminus/dev/agent/dev.db — \`terminus dev .\` picks them up.`,
+    );
+  }
+}