muse-crew 0.6.5 → 0.6.7

package/lib/crew-api.js

@@ -0,0 +1,1101 @@
+#!/usr/bin/env node
+// crew-api.js — the Muse Crew's own task-service API.
+//
+// The crew owns its state. This CLI implements the Crew API contract
+// (API.md) against a SQLite database at $CREW_HOME/crew-state.db. Workflows
+// call it through their agents' shell; the dashboard delegates to it.
+// Nobody calls the dashboard for crew state anymore.
+//
+// Usage:
+//   crew-api.js --crew-home <path> <command> [--json '<json>' | --flag value ...]
+//   crew-api.js --crew-home <path> <command> < /tmp/args.json
+//
+// Commands (kebab-case) map to API.md actions:
+//   get-dispatch-state, get-state, create-task, update-task, claim-task,
+//   park-task, recover-task, upsert-session, log-event, get-events,
+//   create-project, update-project, delete-project, list-projects,
+//   get-project, kill-switch, get-config, update-config,
+//   set-provenance, get-provenance, acknowledge-poll,
+//   record-phase (composite), migrate (one-time import)
+//
+// Output is JSON on stdout. Errors are JSON on stderr.
+// Exit codes: 0 ok · 2 usage/validation · 3 not found · 4 conflict/guard.
+
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { homedir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+class CrewError extends Error {
+  constructor(code, message, exitCode) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+const usageError = (m) => new CrewError("usage", m, 2);
+const notFound = (m) => new CrewError("not_found", m, 3);
+const conflict = (m) => new CrewError("conflict", m, 4);
+
+// Tri-state visual_protocol validation: true | false | null. undefined means
+// "not provided" (create: defaults to null; update: leaves the field alone).
+// null is the explicit clear operation — it returns the project to inherit.
+// Anything else ("yes", 1, 0, {}, "") is a usage error.
+function validateVisualProtocol(value) {
+  if (value === undefined || value === null) return null;
+  if (value === true || value === false) return value;
+  throw usageError("visual_protocol must be true, false, or null.");
+}
+
+// ---------------------------------------------------------------------------
+// Crew home resolution (fail closed)
+// ---------------------------------------------------------------------------
+
+function resolveCrewHome(flagValue) {
+  const raw = flagValue || process.env.CREW_HOME;
+  if (!raw) throw usageError("crew home not set: pass --crew-home or set CREW_HOME.");
+  const abs = resolve(raw);
+  // Gate 0: the crew only lives under $HOME/workspace (workflow_launch
+  // confinement). Refuse anything else rather than writing state elsewhere.
+  const allowed = homedir() + sep + "workspace" + sep;
+  if (!abs.startsWith(allowed)) {
+    throw usageError(`crew home must be under ${allowed}; got ${abs}.`);
+  }
+  return abs;
+}
+
+// ---------------------------------------------------------------------------
+// Database
+// ---------------------------------------------------------------------------
+
+const SCHEMA_PATH = join(import.meta.dirname, "schema.sql");
+
+function openDb(crewHome) {
+  const dbPath = join(crewHome, "crew-state.db");
+  const fresh = !existsSync(dbPath);
+  const db = new DatabaseSync(dbPath);
+  db.exec("PRAGMA journal_mode = WAL;");
+  db.exec("PRAGMA foreign_keys = ON;");
+  if (fresh) {
+    const schema = readFileSync(SCHEMA_PATH, "utf8");
+    db.exec(schema);
+  } else {
+    // Idempotent: CREATE TABLE IF NOT EXISTS covers upgrades that only add.
+    const schema = readFileSync(SCHEMA_PATH, "utf8");
+    db.exec(schema);
+    // Migration: add last_heartbeat column if missing (duplicate-resume fix, 2026-09-11).
+    // SQLite has no IF NOT EXISTS for ADD COLUMN, so check first. The try/catch
+    // handles the theoretical race where two processes both pass the check.
+    const cols = db.prepare("PRAGMA table_info(agent_sessions)").all();
+    if (!cols.some((c) => c.name === "last_heartbeat")) {
+      try {
+        db.exec("ALTER TABLE agent_sessions ADD COLUMN last_heartbeat TEXT");
+      } catch (e) {
+        // Another process may have added it concurrently; ignore duplicate-column errors.
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
+    // Migration: add visual_protocol column if missing (per-project visual
+    // protocol toggle, 2026-09-12). Same idempotent PRAGMA-check pattern;
+    // ADD COLUMN without a default leaves existing rows NULL, which is the
+    // inherit state by design (no backfill step).
+    const projectCols = db.prepare("PRAGMA table_info(projects)").all();
+    if (!projectCols.some((c) => c.name === "visual_protocol")) {
+      try {
+        db.exec("ALTER TABLE projects ADD COLUMN visual_protocol INTEGER CHECK (visual_protocol IN (0, 1))");
+      } catch (e) {
+        // Another process may have added it concurrently; ignore duplicate-column errors.
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
+  }
+  return db;
+}
+
+// ---------------------------------------------------------------------------
+// Small helpers (ported from the dashboard's actions.ts — same shapes)
+// ---------------------------------------------------------------------------
+
+const now = () => new Date().toISOString();
+const uuid = () => randomUUID();
+
+function parseDeps(value) {
+  try {
+    const parsed = JSON.parse(value ?? "[]");
+    return Array.isArray(parsed) ? parsed.filter((i) => typeof i === "string") : [];
+  } catch { return []; }
+}
+
+function parseCaveats(value) {
+  try {
+    const parsed = JSON.parse(value ?? "[]");
+    return Array.isArray(parsed) ? parsed : [];
+  } catch { return []; }
+}
+
+function mapProject(row) {
+  return {
+    id: row.id,
+    display_name: row.display_name,
+    repo_path: row.repo_path,
+    deploy_type: row.deploy_type,
+    deploy_slug: row.deploy_slug,
+    description: row.description,
+    simultaneity: row.simultaneity,
+    quiesced: !!row.quiesced,
+    // Tri-state: null (inherit) stays null, never coerced to false.
+    visual_protocol: row.visual_protocol == null ? null : !!row.visual_protocol,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+function mapTask(row, taskStates = new Map()) {
+  const deps = parseDeps(row.deps);
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description,
+    state: row.state,
+    priority: row.priority,
+    project: row.project,
+    workflow: row.workflow,
+    next_phase: row.next_phase,
+    deps,
+    filed_by: row.filed_by,
+    retry_reset_at: row.retry_reset_at,
+    blocked: deps.some((id) => taskStates.get(id) !== "done"),
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+function mapSession(row) {
+  return {
+    id: row.id,
+    task_id: row.task_id,
+    identity: row.identity,
+    step: row.step,
+    status: row.status,
+    started_at: row.started_at,
+    ended_at: row.ended_at,
+    notes: row.notes,
+    caveats: parseCaveats(row.caveats),
+    failure_reason: row.failure_reason,
+    last_heartbeat: row.last_heartbeat ?? null,
+  };
+}
+
+function mapEvent(row) {
+  return {
+    id: row.id,
+    type: row.type,
+    task_id: row.task_id,
+    identity: row.identity,
+    message: row.message,
+    timestamp: row.timestamp,
+  };
+}
+
+// Retry counting, ported verbatim from the dashboard's retry.ts.
+function countConsecutiveFailures(sessions, retryResetAt) {
+  const latest = sessions[0];
+  if (!latest) return 0;
+  let n = 0;
+  for (const s of sessions) {
+    if (retryResetAt && s.started_at <= retryResetAt) break;
+    if (s.step !== latest.step) break;
+    if (s.status !== "failed" && s.status !== "timed_out" && s.status !== "stalled") break;
+    n += 1;
+  }
+  return n;
+}
+
+function countRejectionsSinceReset(sessions, retryResetAt) {
+  return sessions.filter((s) =>
+    s.status === "rejected" && (!retryResetAt || s.started_at > retryResetAt)).length;
+}
+
+function setRetryResetAtForTransition(patch, currentState, requestedState, timestamp) {
+  if (currentState === "parked" && requestedState === "todo") {
+    patch.retry_reset_at = timestamp;
+  }
+}
+
+// Active runs: status=running AND started within the last hour.
+function findActiveRuns(db, taskIds) {
+  if (taskIds.length === 0) return [];
+  const placeholders = taskIds.map(() => "?").join(",");
+  return db.prepare(
+    `SELECT id, task_id, identity, step, started_at FROM agent_sessions
+     WHERE task_id IN (${placeholders}) AND status = 'running'
+       AND datetime(started_at) > datetime('now', '-1 hour')
+     ORDER BY started_at DESC`
+  ).all(...taskIds);
+}
+
+function requireTask(db, id) {
+  const row = db.prepare("SELECT * FROM tasks WHERE id = ?").get(id);
+  if (!row) throw notFound("Task not found.");
+  return row;
+}
+
+function requireProject(db, id) {
+  const row = db.prepare("SELECT * FROM projects WHERE id = ?").get(id);
+  if (!row) throw notFound("Project not found.");
+  return row;
+}
+
+function workflowExists(crewHome, slug) {
+  if (!slug) return false;
+  return (
+    existsSync(join(crewHome, "current", "workflows", `${slug}.js`)) ||
+    existsSync(join(crewHome, "workflows", `${slug}.js`))
+  );
+}
+
+// Minimal git-repo validation (ported from the dashboard's validateRepoPath):
+// accepts a repo root (.git dir) or a linked worktree (.git file).
+function isGitRepoPath(p) {
+  try {
+    const git = join(p, ".git");
+    if (!existsSync(git)) return false;
+    const st = statSync(git);
+    return st.isDirectory() || st.isFile();
+  } catch { return false; }
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+const commands = {};
+
+commands["get-dispatch-state"] = (db) => {
+  // Sweep zombie sessions: running with no heartbeat for over an hour is timed out.
+  // Uses last_heartbeat (updated on every record-phase) falling back to started_at
+  // for old sessions. A live workflow heartbeats via record-phase at each phase
+  // boundary, so the sweep no longer kills sessions for slow-but-alive workflows
+  // (duplicate-resume fix, 2026-09-11).
+  db.prepare(
+    `UPDATE agent_sessions SET status = 'timed_out', ended_at = datetime('now')
+     WHERE status = 'running' AND datetime(COALESCE(last_heartbeat, started_at)) < datetime('now', '-1 hour')`
+  ).run();
+
+  const taskRows = db.prepare("SELECT * FROM tasks").all();
+  const projectRows = db.prepare("SELECT * FROM projects ORDER BY display_name").all();
+  const configRows = db.prepare("SELECT key, value FROM config WHERE key <> 'simultaneity'").all();
+  const sessionCount = db.prepare("SELECT COUNT(*) AS n FROM agent_sessions").get().n;
+  const eventCount = db.prepare("SELECT COUNT(*) AS n FROM events").get().n;
+
+  const taskStates = new Map(taskRows.map((t) => [t.id, t.state]));
+  const projectConfigs = new Map(projectRows.map((p) => [p.id, p]));
+  const priorityOrder = { high: 0, normal: 1, low: 2 };
+  const readyTaskRows = taskRows
+    .filter((task) => {
+      const project = projectConfigs.get(task.project);
+      if (!project || project.quiesced) return false;
+      if (task.state === "in_progress") return true;
+      if (task.state !== "todo") return false;
+      return !parseDeps(task.deps).some((id) => taskStates.get(id) !== "done");
+    })
+    .sort((a, b) => {
+      const d = priorityOrder[a.priority] - priorityOrder[b.priority];
+      return d !== 0 ? d : a.created_at.localeCompare(b.created_at);
+    });
+
+  const readyIds = readyTaskRows.map((t) => t.id);
+  let sessionsByTask = new Map();
+  if (readyIds.length > 0) {
+    const ph = readyIds.map(() => "?").join(",");
+    const rows = db.prepare(
+      `SELECT * FROM agent_sessions WHERE task_id IN (${ph})
+       ORDER BY task_id, started_at DESC`
+    ).all(...readyIds);
+    for (const s of rows) {
+      const list = sessionsByTask.get(s.task_id) ?? [];
+      list.push(s);
+      sessionsByTask.set(s.task_id, list);
+    }
+  }
+
+  return {
+    ready_tasks: readyTaskRows.map((task) => {
+      const deps = parseDeps(task.deps);
+      const taskSessions = sessionsByTask.get(task.id) ?? [];
+      const latest = taskSessions[0] ?? null;
+      const project = projectConfigs.get(task.project);
+      return {
+        id: task.id,
+        title: task.title,
+        description: task.description,
+        state: task.state,
+        project: task.project,
+        project_config: {
+          simultaneity: project?.simultaneity ?? 0,
+          quiesced: !!project?.quiesced,
+        },
+        workflow: task.workflow,
+        blocked: deps.some((id) => taskStates.get(id) !== "done"),
+        deps,
+        priority: task.priority,
+        latest_session: latest ? {
+          id: latest.id,
+          identity: latest.identity,
+          step: latest.step,
+          status: latest.status,
+          notes: latest.notes,
+          started_at: latest.started_at,
+          ended_at: latest.ended_at,
+          caveats: parseCaveats(latest.caveats),
+        } : null,
+        retry: {
+          consecutive_failures: countConsecutiveFailures(
+            taskSessions.map(mapSession), task.retry_reset_at),
+          rejections_since_reset: countRejectionsSinceReset(
+            taskSessions.map(mapSession), task.retry_reset_at),
+        },
+      };
+    }),
+    projects: projectRows.map(mapProject),
+    config: Object.fromEntries(configRows.map((r) => [r.key, r.value])),
+    counts: {
+      total_tasks: taskRows.length,
+      active_tasks: taskRows.filter((t) => t.state === "todo" || t.state === "in_progress").length,
+      done_tasks: taskRows.filter((t) => t.state === "done").length,
+      total_sessions: sessionCount,
+      total_events: eventCount,
+    },
+  };
+};
+
+commands["get-state"] = (db, args) => {
+  const dayStart = args.day_start ?? new Date(new Date().setUTCHours(0, 0, 0, 0)).toISOString();
+  const dayEnd = args.day_end ?? new Date(new Date().setUTCHours(24, 0, 0, 0)).toISOString();
+  const limit = Math.min(Math.max(args.events_limit ?? 20, 1), 100);
+  const offset = Math.max(args.events_offset ?? 0, 0);
+  const projectRows = db.prepare("SELECT * FROM projects ORDER BY display_name").all();
+  const taskRows = db.prepare("SELECT * FROM tasks ORDER BY updated_at DESC").all();
+  const sessionRows = db.prepare("SELECT * FROM agent_sessions ORDER BY started_at DESC").all();
+  const recentEvents = db.prepare(
+    "SELECT * FROM events ORDER BY timestamp DESC LIMIT ? OFFSET ?").all(limit, offset);
+  const todayEvents = db.prepare(
+    "SELECT id FROM events WHERE timestamp >= ? AND timestamp < ?").all(dayStart, dayEnd);
+  const eventCount = db.prepare("SELECT COUNT(*) AS n FROM events").get().n;
+  const pollRow = db.prepare("SELECT last_poll_at FROM poll_state WHERE id = 1").get();
+  const configRows = db.prepare("SELECT key, value FROM config WHERE key <> 'simultaneity'").all();
+  const taskStates = new Map(taskRows.map((t) => [t.id, t.state]));
+  return {
+    projects: projectRows.map(mapProject),
+    tasks: taskRows.map((t) => mapTask(t, taskStates)),
+    sessions: sessionRows.map(mapSession),
+    events: recentEvents.map(mapEvent),
+    events_total: eventCount,
+    events_offset: offset,
+    events_limit: limit,
+    events_has_more: offset + recentEvents.length < eventCount,
+    config: Object.fromEntries(configRows.map((r) => [r.key, r.value])),
+    summary: {
+      active: sessionRows.filter((s) => s.status === "running").length,
+      total_tasks: taskRows.length,
+      events_today: todayEvents.length,
+      total_events: eventCount,
+    },
+    observed_at: now(),
+    last_poll_at: pollRow?.last_poll_at ?? null,
+  };
+};
+
+commands["create-task"] = (db, args, ctx) => {
+  const title = (args.title ?? "").trim();
+  if (title.length < 1 || title.length > 160) throw usageError("title must be 1-160 chars.");
+  const description = (args.description ?? "").trim();
+  if (description.length > 5000) throw usageError("description must be <= 5000 chars.");
+  const state = args.state ?? "todo";
+  if (!["todo", "in_progress", "parked", "done"].includes(state)) throw usageError("bad state.");
+  const priority = args.priority ?? "normal";
+  if (!["high", "normal", "low"].includes(priority)) throw usageError("bad priority.");
+  const filedBy = (args.filed_by ?? "").trim();
+  if (filedBy.length < 1 || filedBy.length > 80) throw usageError("filed_by is required (1-80 chars).");
+  if (args.workflow && !workflowExists(ctx.crewHome, args.workflow)) throw notFound("Workflow not found.");
+  const projectId = args.project || "orchestra-dashboard";
+  requireProject(db, projectId);
+  const deps = [...new Set(args.deps ?? [])];
+  const existingIds = new Set(db.prepare("SELECT id FROM tasks").all().map((r) => r.id));
+  const missing = deps.find((id) => !existingIds.has(id));
+  if (missing) throw usageError(`Unknown task dependency: ${missing}.`);
+
+  const timestamp = now();
+  const task = {
+    id: uuid(), title, description, state, priority, project: projectId,
+    workflow: args.workflow ?? null, next_phase: null, deps: JSON.stringify(deps),
+    filed_by: filedBy, retry_reset_at: null, created_at: timestamp, updated_at: timestamp,
+  };
+  const event = {
+    id: uuid(), type: "created", task_id: task.id, identity: null,
+    message: `Created \u201c${title}\u201d${task.workflow ? ` with the ${task.workflow} workflow` : " for triage"}.`,
+    timestamp,
+  };
+  const insertTask = db.prepare(
+    `INSERT INTO tasks (id, title, description, state, priority, project, workflow,
+      next_phase, deps, filed_by, retry_reset_at, created_at, updated_at)
+     VALUES (@id, @title, @description, @state, @priority, @project, @workflow,
+      @next_phase, @deps, @filed_by, @retry_reset_at, @created_at, @updated_at)`);
+  const insertEvent = db.prepare(
+    `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+     VALUES (@id, @type, @task_id, @identity, @message, @timestamp)`);
+  db.exec("BEGIN");
+  try {
+    insertTask.run(task);
+    insertEvent.run(event);
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  const taskStates = new Map(db.prepare("SELECT id, state FROM tasks").all().map((r) => [r.id, r.state]));
+  return { task: mapTask({ ...task }, taskStates) };
+};
+
+commands["update-task"] = (db, args, ctx) => {
+  if (!args.id) throw usageError("id is required.");
+  const current = requireTask(db, args.id);
+  if (args.workflow && !workflowExists(ctx.crewHome, args.workflow)) throw notFound("Workflow not found.");
+  if (args.project !== undefined) requireProject(db, args.project);
+  if (args.project !== undefined && args.project !== current.project) {
+    const active = findActiveRuns(db, [args.id]);
+    if (active[0]) {
+      throw conflict(
+        `Cannot move task "${current.title}" from project "${current.project}" to "${args.project}": ` +
+        `an active run is in progress (${active[0].identity} ${active[0].step ?? "unknown step"}). ` +
+        `Wait for the run to finish, or recover/park the task first.`);
+    }
+  }
+  const deps = args.deps === undefined ? undefined : [...new Set(args.deps)];
+  if (deps !== undefined) {
+    const existingIds = new Set(db.prepare("SELECT id FROM tasks").all().map((r) => r.id));
+    const missing = deps.find((id) => !existingIds.has(id));
+    if (missing) throw usageError(`Unknown task dependency: ${missing}.`);
+  }
+  const timestamp = now();
+  const patch = {};
+  setRetryResetAtForTransition(patch, current.state, args.state, timestamp);
+  if (args.title !== undefined) {
+    const t = args.title.trim();
+    if (t.length < 1 || t.length > 200) throw usageError("title must be 1-200 chars.");
+    patch.title = t;
+  }
+  if (args.description !== undefined) patch.description = args.description.trim().slice(0, 3000);
+  if (args.state !== undefined) {
+    if (!["todo", "in_progress", "parked", "done"].includes(args.state)) throw usageError("bad state.");
+    patch.state = args.state;
+  }
+  if (args.priority !== undefined) {
+    if (!["high", "normal", "low"].includes(args.priority)) throw usageError("bad priority.");
+    patch.priority = args.priority;
+  }
+  if (args.project !== undefined) patch.project = args.project;
+  if (args.workflow !== undefined) patch.workflow = args.workflow;
+  if (deps !== undefined) patch.deps = JSON.stringify(deps);
+
+  db.exec("BEGIN");
+  try {
+    if (Object.keys(patch).length > 0) {
+      patch.updated_at = timestamp;
+      const sets = Object.keys(patch).map((k) => `${k} = @${k}`).join(", ");
+      db.prepare(`UPDATE tasks SET ${sets} WHERE id = @id`).run({ ...patch, id: args.id });
+    }
+    if (args.state && args.state !== current.state) {
+      const type = args.state === "done" ? "completed"
+        : args.state === "in_progress" ? "dispatched" : "note";
+      db.prepare(
+        `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+         VALUES (?, ?, ?, NULL, ?, ?)`
+      ).run(uuid(), type, args.id, `Moved \u201c${patch.title ?? current.title}\u201d to ${args.state.replace("_", " ")}.`, timestamp);
+    }
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  const updated = { ...current, ...patch };
+  const taskStates = new Map(db.prepare("SELECT id, state FROM tasks").all().map((r) => [r.id, r.state]));
+  return { task: mapTask(updated, taskStates) };
+};
+
+commands["claim-task"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  const identity = (args.identity ?? "").trim();
+  if (identity.length < 1 || identity.length > 80) throw usageError("identity is required (1-80 chars).");
+  const task = requireTask(db, args.task_id);
+  const project = requireProject(db, task.project);
+  if (project.quiesced) throw conflict("This project is paused. Resume it before claiming tasks.");
+
+  const row = {
+    id: uuid(), task_id: args.task_id, identity,
+    step: args.step ?? null, status: "running",
+    started_at: now(), ended_at: null,
+    notes: (args.notes ?? "").trim().slice(0, 3000), caveats: "[]",
+    last_heartbeat: now(),
+  };
+  // Atomic: the partial unique index on (task_id) WHERE status='running'
+  // turns a duplicate claim into a no-op insert.
+  const info = db.prepare(
+    `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
+      ended_at, notes, caveats, last_heartbeat)
+     VALUES (@id, @task_id, @identity, @step, @status, @started_at,
+      @ended_at, @notes, @caveats, @last_heartbeat)
+     ON CONFLICT DO NOTHING`).run(row);
+  if (info.changes > 0) {
+    return { ok: true, claimed: true, session_id: row.id, session: mapSession({ ...row, failure_reason: null }) };
+  }
+  const existing = db.prepare(
+    `SELECT id FROM agent_sessions
+     WHERE task_id = ? AND status = 'running'
+     ORDER BY started_at DESC LIMIT 1`).get(args.task_id);
+  if (!existing) throw new CrewError("claim_unresolved", "Task claim could not be resolved. Please retry.", 4);
+  return { ok: true, claimed: false, reason: "already_claimed", existing_session_id: existing.id };
+};
+
+commands["park-task"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  const message = (args.message ?? "").trim();
+  if (message.length < 1 || message.length > 1000) throw usageError("message is required (1-1000 chars).");
+  const task = requireTask(db, args.task_id);
+  const timestamp = now();
+  db.exec("BEGIN");
+  try {
+    db.prepare("UPDATE tasks SET state = 'parked', updated_at = ? WHERE id = ?").run(timestamp, task.id);
+    db.prepare(
+      `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+       VALUES (?, 'note', ?, NULL, ?, ?)`
+    ).run(uuid(), task.id, message, timestamp);
+    // Settle every running session: a parked task never keeps a ghost run.
+    // Settled sessions move to 'failed' so recover-task accepts them.
+    const settled = db.prepare(
+      `UPDATE agent_sessions
+       SET status = 'failed', ended_at = ?,
+           notes = notes || ' Parked: ' || ?
+       WHERE task_id = ? AND status = 'running'`
+    ).run(timestamp, message.slice(0, 500), task.id);
+    db.exec("COMMIT");
+    const taskStates = new Map(db.prepare("SELECT id, state FROM tasks").all().map((r) => [r.id, r.state]));
+    return {
+      ok: true,
+      task: mapTask({ ...task, state: "parked", updated_at: timestamp }, taskStates),
+      settled_sessions: Number(settled.changes),
+    };
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+};
+
+commands["recover-task"] = (db, args, ctx) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  if (args.action !== "send_to") throw usageError('action must be "send_to".');
+  const targetPhase = (args.target_phase ?? "").trim();
+  if (targetPhase.length < 1 || targetPhase.length > 120) throw usageError("target_phase is required (1-120 chars).");
+  const task = requireTask(db, args.task_id);
+  const latest = db.prepare(
+    `SELECT * FROM agent_sessions WHERE task_id = ? ORDER BY started_at DESC LIMIT 1`
+  ).get(args.task_id);
+  if (!latest || !["failed", "timed_out"].includes(latest.status)) {
+    throw conflict("The latest session is not failed or timed out.");
+  }
+  if (!task.workflow) throw conflict("This task does not have a workflow with selectable phases.");
+  if (!workflowExists(ctx.crewHome, task.workflow)) throw notFound("Workflow not found.");
+  const timestamp = now();
+  const queued = {
+    id: uuid(), task_id: task.id,
+    identity: latest.identity, step: targetPhase, status: "failed",
+    started_at: timestamp, ended_at: timestamp,
+    notes: (args.updated_description ?? "").trim().slice(0, 5000),
+    caveats: "[]", failure_reason: null, last_heartbeat: timestamp,
+  };
+  db.exec("BEGIN");
+  try {
+    db.prepare("UPDATE tasks SET next_phase = ?, updated_at = ? WHERE id = ?")
+      .run(targetPhase, timestamp, task.id);
+    db.prepare("UPDATE agent_sessions SET ended_at = ? WHERE id = ?").run(timestamp, latest.id);
+    db.prepare(
+      `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
+        ended_at, notes, caveats, failure_reason, last_heartbeat)
+       VALUES (@id, @task_id, @identity, @step, @status, @started_at,
+        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat)`).run(queued);
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  const taskStates = new Map(db.prepare("SELECT id, state FROM tasks").all().map((r) => [r.id, r.state]));
+  return {
+    task: mapTask({ ...task, next_phase: targetPhase, updated_at: timestamp }, taskStates),
+    session: mapSession(queued),
+  };
+};
+
+commands["upsert-session"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  requireTask(db, args.task_id);
+  const identity = (args.identity ?? "").trim();
+  if (identity.length < 1) throw usageError("identity is required.");
+  const status = args.status;
+  const valid = ["running", "completed", "failed", "rejected", "timed_out", "stalled", "passed", "superseded"];
+  if (!valid.includes(status)) throw usageError(`bad status: ${status}.`);
+  const id = args.id ?? uuid();
+  const current = db.prepare("SELECT * FROM agent_sessions WHERE id = ?").get(id);
+  const row = {
+    id,
+    task_id: args.task_id,
+    identity,
+    step: args.step === undefined ? (current?.step ?? null) : args.step,
+    status,
+    started_at: args.started_at ?? current?.started_at ?? now(),
+    ended_at: args.ended_at ?? (status === "running" ? null : now()),
+    notes: (args.notes ?? "").trim().slice(0, 3000),
+    caveats: args.caveats === undefined ? (current?.caveats ?? "[]") : JSON.stringify(args.caveats),
+    failure_reason: args.failure_reason === undefined ? (current?.failure_reason ?? null) : args.failure_reason,
+    last_heartbeat: now(),
+  };
+  if (current) {
+    db.prepare(
+      `UPDATE agent_sessions SET task_id=@task_id, identity=@identity, step=@step,
+       status=@status, started_at=@started_at, ended_at=@ended_at, notes=@notes,
+       caveats=@caveats, failure_reason=@failure_reason, last_heartbeat=@last_heartbeat WHERE id=@id`).run(row);
+  } else {
+    db.prepare(
+      `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
+        ended_at, notes, caveats, failure_reason, last_heartbeat)
+       VALUES (@id, @task_id, @identity, @step, @status, @started_at,
+        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat)
+       ON CONFLICT DO NOTHING`).run(row);
+  }
+  return { session: mapSession(row) };
+};
+
+commands["heartbeat-session"] = (db, args) => {
+  // Update the last_heartbeat for a running session. Workflows call this
+  // periodically during long phases to prevent the zombie sweep from
+  // marking a live session as timed_out (duplicate-resume fix, 2026-09-11).
+  if (!args.id) throw usageError("id is required.");
+  const session = db.prepare("SELECT * FROM agent_sessions WHERE id = ?").get(args.id);
+  if (!session) throw notFound("Session not found.");
+  if (session.status !== "running") throw conflict("Only running sessions can heartbeat.");
+  const timestamp = now();
+  db.prepare("UPDATE agent_sessions SET last_heartbeat = ? WHERE id = ?").run(timestamp, args.id);
+  return { session: mapSession({ ...session, last_heartbeat: timestamp }) };
+};
+
+commands["log-event"] = (db, args) => {
+  const valid = ["dispatched", "completed", "failed", "blocked", "created",
+    "note", "release_activated", "deployed", "rejected"];
+  if (!valid.includes(args.type)) throw usageError(`bad event type: ${args.type}.`);
+  const message = (args.message ?? "").trim();
+  if (message.length < 1 || message.length > 1000) throw usageError("message is required (1-1000 chars).");
+  if (args.task_id) requireTask(db, args.task_id);
+  const event = {
+    id: uuid(), type: args.type, task_id: args.task_id ?? null,
+    identity: args.identity ?? null, message,
+    timestamp: args.timestamp ?? now(),
+  };
+  db.prepare(
+    `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+     VALUES (@id, @type, @task_id, @identity, @message, @timestamp)`).run(event);
+  return { event: mapEvent(event) };
+};
+
+commands["get-events"] = (db, args) => {
+  const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);
+  const rows = args.task_id
+    ? db.prepare("SELECT * FROM events WHERE task_id = ? ORDER BY timestamp DESC LIMIT ?").all(args.task_id, limit)
+    : db.prepare("SELECT * FROM events ORDER BY timestamp DESC LIMIT ?").all(limit);
+  return { events: rows.map(mapEvent) };
+};
+
+// Composite: record a phase's session verdict AND its event in one
+// transaction. This is the operation that used to crash the workflow when the
+// two writes went to different contracts: the session stored, the event
+// rejected, the run dead. One transaction, one vocabulary, no partial state.
+commands["record-phase"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  requireTask(db, args.task_id);
+  const session = args.session ?? {};
+  const event = args.event ?? {};
+  const status = session.status;
+  const validStatuses = ["running", "completed", "failed", "rejected", "timed_out", "stalled", "passed", "superseded"];
+  if (!validStatuses.includes(status)) throw usageError(`bad session status: ${status}.`);
+  const validTypes = ["dispatched", "completed", "failed", "blocked", "created",
+    "note", "release_activated", "deployed", "rejected"];
+  if (!validTypes.includes(event.type)) throw usageError(`bad event type: ${event.type}.`);
+  const message = (event.message ?? "").trim();
+  if (message.length < 1 || message.length > 1000) throw usageError("event message is required (1-1000 chars).");
+  const timestamp = now();
+  const sessionRow = {
+    id: session.id ?? uuid(),
+    task_id: args.task_id,
+    identity: (session.identity ?? "").trim() || "crew",
+    step: session.step ?? null,
+    status,
+    started_at: session.started_at ?? timestamp,
+    ended_at: session.ended_at ?? (status === "running" ? null : timestamp),
+    notes: (session.notes ?? "").trim().slice(0, 3000),
+    caveats: session.caveats === undefined ? "[]" : JSON.stringify(session.caveats),
+    failure_reason: session.failure_reason ?? null,
+    last_heartbeat: timestamp,
+  };
+  const eventRow = {
+    id: uuid(), type: event.type, task_id: args.task_id,
+    identity: event.identity ?? sessionRow.identity, message, timestamp,
+  };
+  db.exec("BEGIN");
+  try {
+    db.prepare(
+      `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
+        ended_at, notes, caveats, failure_reason, last_heartbeat)
+       VALUES (@id, @task_id, @identity, @step, @status, @started_at,
+        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat)
+       ON CONFLICT(id) DO UPDATE SET status=@status, ended_at=@ended_at,
+        notes=@notes, caveats=@caveats, failure_reason=@failure_reason,
+        last_heartbeat=@last_heartbeat`).run(sessionRow);
+    db.prepare(
+      `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+       VALUES (@id, @type, @task_id, @identity, @message, @timestamp)`).run(eventRow);
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  return { session: mapSession(sessionRow), event: mapEvent(eventRow) };
+};
+
+commands["create-project"] = (db, args) => {
+  const id = (args.id ?? "").trim();
+  if (!/^[a-z0-9-]+$/.test(id)) throw usageError("id must be a slug.");
+  const displayName = (args.display_name ?? "").trim();
+  if (displayName.length < 1 || displayName.length > 120) throw usageError("display_name must be 1-120 chars.");
+  const repoPath = (args.repo_path ?? "").trim();
+  if (!repoPath) throw usageError("repo_path is required.");
+  if (!isGitRepoPath(repoPath)) throw usageError("repo_path must be a valid Git repository path.");
+  const deployType = args.deploy_type ?? "";
+  if (!["npm", "artifact", "vercel", ""].includes(deployType)) throw usageError("bad deploy_type.");
+  if (db.prepare("SELECT id FROM projects WHERE id = ?").get(id)) {
+    throw conflict("A project with this ID already exists.");
+  }
+  const timestamp = now();
+  const visualProtocol = validateVisualProtocol(args.visual_protocol);
+  const row = {
+    id, display_name: displayName, repo_path: repoPath, deploy_type: deployType,
+    deploy_slug: args.deploy_slug ?? null,
+    description: (args.description ?? "").trim().slice(0, 3000),
+    simultaneity: args.simultaneity ?? 2,
+    quiesced: args.quiesced ? 1 : 0,
+    visual_protocol: visualProtocol == null ? null : (visualProtocol ? 1 : 0),
+    created_at: timestamp, updated_at: timestamp,
+  };
+  if (!Number.isInteger(row.simultaneity) || row.simultaneity < 1 || row.simultaneity > 100) {
+    throw usageError("simultaneity must be 1-100.");
+  }
+  db.prepare(
+    `INSERT INTO projects (id, display_name, repo_path, deploy_type, deploy_slug,
+      description, simultaneity, quiesced, visual_protocol, created_at, updated_at)
+     VALUES (@id, @display_name, @repo_path, @deploy_type, @deploy_slug,
+      @description, @simultaneity, @quiesced, @visual_protocol, @created_at, @updated_at)`).run(row);
+  return { project: mapProject(row) };
+};
+
+commands["get-project"] = (db, args) => {
+  if (!args.id) throw usageError("id is required.");
+  return { project: mapProject(requireProject(db, args.id)) };
+};
+
+commands["list-projects"] = (db) => {
+  const rows = db.prepare("SELECT * FROM projects ORDER BY display_name").all();
+  return { projects: rows.map(mapProject) };
+};
+
+commands["update-project"] = (db, args) => {
+  if (!args.id) throw usageError("id is required.");
+  const current = requireProject(db, args.id);
+  if (args.repo_path !== undefined && !isGitRepoPath(args.repo_path)) {
+    throw usageError("repo_path must be a valid Git repository path.");
+  }
+  const patch = { updated_at: now() };
+  if (args.display_name !== undefined) patch.display_name = args.display_name.trim();
+  if (args.repo_path !== undefined) patch.repo_path = args.repo_path;
+  if (args.deploy_type !== undefined) {
+    if (!["npm", "artifact", "vercel", ""].includes(args.deploy_type)) throw usageError("bad deploy_type.");
+    patch.deploy_type = args.deploy_type;
+  }
+  if (args.deploy_slug !== undefined) patch.deploy_slug = args.deploy_slug;
+  if (args.description !== undefined) patch.description = args.description.trim().slice(0, 3000);
+  if (args.simultaneity !== undefined) {
+    if (!Number.isInteger(args.simultaneity) || args.simultaneity < 0 || args.simultaneity > 100) {
+      throw usageError("simultaneity must be 0-100.");
+    }
+    const changesDispatchState = (current.simultaneity === 0) !== (args.simultaneity === 0);
+    if (changesDispatchState) throw usageError("Use kill-switch to pause or resume dispatch.");
+    patch.simultaneity = args.simultaneity;
+  }
+  if (args.quiesced !== undefined) patch.quiesced = args.quiesced ? 1 : 0;
+  // NOT covered by the context-change guard below: visual_protocol is read
+  // once from launch args at dispatch time, so a mid-run change only affects
+  // future launches.
+  if (args.visual_protocol !== undefined) {
+    const vp = validateVisualProtocol(args.visual_protocol);
+    patch.visual_protocol = vp == null ? null : (vp ? 1 : 0);
+  }
+
+  const contextChanged =
+    (args.repo_path !== undefined && args.repo_path !== current.repo_path) ||
+    (args.deploy_type !== undefined && args.deploy_type !== current.deploy_type) ||
+    (args.deploy_slug !== undefined && args.deploy_slug !== current.deploy_slug);
+  if (contextChanged) {
+    const taskIds = db.prepare("SELECT id FROM tasks WHERE project = ?").all(args.id).map((r) => r.id);
+    const active = findActiveRuns(db, taskIds);
+    if (active.length > 0) {
+      throw conflict(
+        `Cannot change repo_path/deploy_type/deploy_slug for project "${current.display_name}": ` +
+        `${active.length} active run(s) in progress. Wait for the runs to finish, or recover/park those tasks first.`);
+    }
+  }
+  const sets = Object.keys(patch).map((k) => `${k} = @${k}`).join(", ");
+  db.prepare(`UPDATE projects SET ${sets} WHERE id = @id`).run({ ...patch, id: args.id });
+  return { project: mapProject({ ...current, ...patch }) };
+};
+
+commands["delete-project"] = (db, args) => {
+  if (!args.id) throw usageError("id is required.");
+  requireProject(db, args.id);
+  const taskIds = db.prepare("SELECT id FROM tasks WHERE project = ?").all(args.id).map((r) => r.id);
+  db.exec("BEGIN");
+  try {
+    if (taskIds.length > 0) {
+      const ph = taskIds.map(() => "?").join(",");
+      db.prepare(`DELETE FROM events WHERE task_id IN (${ph})`).run(...taskIds);
+      db.prepare(`DELETE FROM agent_sessions WHERE task_id IN (${ph})`).run(...taskIds);
+    }
+    db.prepare("DELETE FROM tasks WHERE project = ?").run(args.id);
+    db.prepare("DELETE FROM config WHERE key = ?").run(`prev_simultaneity_${args.id}`);
+    db.prepare("DELETE FROM projects WHERE id = ?").run(args.id);
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  return { ok: true };
+};
+
+commands["kill-switch"] = (db, args) => {
+  if (!args.project_id) throw usageError("project_id is required.");
+  if (!["pause", "resume"].includes(args.action)) throw usageError('action must be "pause" or "resume".');
+  const reason = (args.reason ?? "").trim();
+  if (reason.length < 1 || reason.length > 1000) throw usageError("reason is required (1-1000 chars).");
+  const actor = (args.actor ?? "agent").trim().slice(0, 120) || "agent";
+  const project = requireProject(db, args.project_id);
+  const isPaused = project.simultaneity === 0;
+  if (args.action === "pause" && isPaused) throw conflict("This project is already paused.");
+  if (args.action === "resume" && !isPaused) throw conflict("This project is already running.");
+  const timestamp = now();
+  const storedKey = `prev_simultaneity_${project.id}`;
+  let newSimultaneity;
+  db.exec("BEGIN");
+  try {
+    if (args.action === "pause") {
+      newSimultaneity = 0;
+      db.prepare("INSERT INTO config (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value")
+        .run(storedKey, String(project.simultaneity));
+      db.prepare("UPDATE projects SET simultaneity = 0, updated_at = ? WHERE id = ?").run(timestamp, project.id);
+    } else {
+      const stored = db.prepare("SELECT value FROM config WHERE key = ?").get(storedKey);
+      const parsed = Number.parseInt(stored?.value ?? "2", 10);
+      newSimultaneity = Number.isInteger(parsed) && parsed > 0 ? Math.min(parsed, 100) : 2;
+      db.prepare("UPDATE projects SET simultaneity = ?, updated_at = ? WHERE id = ?")
+        .run(newSimultaneity, timestamp, project.id);
+      db.prepare("DELETE FROM config WHERE key = ?").run(storedKey);
+    }
+    const verb = args.action === "pause" ? "Paused" : "Resumed";
+    db.prepare(
+      `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+       VALUES (?, 'note', NULL, NULL, ?, ?)`
+    ).run(uuid(),
+      `[KILL SWITCH] ${verb} project "${project.display_name}" — reason: ${reason} | previous_sim=${project.simultaneity} new_sim=${newSimultaneity} actor=${actor}`,
+      timestamp);
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  return {
+    ok: true, project_id: project.id,
+    previous_simultaneity: project.simultaneity, new_simultaneity: newSimultaneity,
+  };
+};
+
+commands["get-config"] = (db) => {
+  const rows = db.prepare("SELECT key, value FROM config").all();
+  return { config: Object.fromEntries(rows.map((r) => [r.key, r.value])) };
+};
+
+commands["update-config"] = (db, args) => {
+  const key = (args.key ?? "").trim();
+  if (key.length < 1 || key.length > 80) throw usageError("key must be 1-80 chars.");
+  if (key === "simultaneity") throw usageError("Simultaneity is configured per project.");
+  const value = String(args.value ?? "").slice(0, 10000);
+  db.prepare("INSERT INTO config (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value")
+    .run(key, value);
+  return { ok: true };
+};
+
+commands["set-provenance"] = (db, args) => {
+  if (!/^[0-9a-f]{40}$/.test(args.source_commit ?? "")) throw usageError("source_commit must be 40-char hex.");
+  if (!/^([0-9a-f]{40}|pkg-\d+\.\d+\.\d+)$/.test(args.crew_release ?? "")) {
+    throw usageError("crew_release must be 40-char hex or pkg-<semver>.");
+  }
+  // task_id is optional; when present it must be 1-80 chars (matches dashboard contract).
+  const taskId = args.task_id ?? null;
+  if (taskId !== null && (typeof taskId !== "string" || taskId.trim().length < 1 || taskId.length > 80)) {
+    throw usageError("task_id must be 1-80 chars when provided.");
+  }
+  const upsert = db.prepare(
+    "INSERT INTO config (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value");
+  upsert.run("provenance.source_commit", args.source_commit);
+  upsert.run("provenance.crew_release", args.crew_release);
+  upsert.run("provenance.published_at", args.published_at ?? now());
+  if (taskId !== null) upsert.run("provenance.task_id", taskId);
+  return { ok: true };
+};
+
+commands["get-provenance"] = (db) => {
+  const rows = db.prepare("SELECT key, value FROM config WHERE key LIKE 'provenance.%'").all();
+  const byKey = Object.fromEntries(rows.map((r) => [r.key, r.value]));
+  const sc = byKey["provenance.source_commit"];
+  const cr = byKey["provenance.crew_release"];
+  const pa = byKey["provenance.published_at"];
+  if (!sc || !cr || !pa) return { provenance: null };
+  return { provenance: {
+    source_commit: sc, crew_release: cr, published_at: pa,
+    task_id: byKey["provenance.task_id"] ?? null,
+  } };
+};
+
+commands["acknowledge-poll"] = (db) => {
+  const timestamp = now();
+  const existing = db.prepare("SELECT min_poll_interval_seconds FROM poll_state WHERE id = 1").get();
+  if (existing) {
+    db.prepare("UPDATE poll_state SET poll_requested = 0, last_poll_at = ? WHERE id = 1").run(timestamp);
+  } else {
+    db.prepare("INSERT INTO poll_state (id, last_poll_at, poll_requested, min_poll_interval_seconds) VALUES (1, ?, 0, 300)")
+      .run(timestamp);
+  }
+  return {
+    last_poll_at: timestamp, poll_requested: false,
+    min_poll_interval_seconds: existing?.min_poll_interval_seconds ?? 300,
+  };
+};
+
+// One-time import from a dashboard app.db. Copies the six crew tables
+// verbatim (same column names). The dashboard DB is never modified.
+commands["migrate"] = (db, args) => {
+  const dashboardDb = args.dashboard_db;
+  if (!dashboardDb || !existsSync(dashboardDb)) throw usageError("dashboard_db must be an existing SQLite file.");
+  const src = new DatabaseSync(dashboardDb, { readOnly: true });
+  try {
+    const tables = ["projects", "tasks", "poll_state", "config", "agent_sessions", "events"];
+    const counts = {};
+    db.exec("BEGIN");
+    try {
+      for (const table of tables) {
+        const hasTable = src.prepare(
+          "SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(table);
+        if (!hasTable) { counts[table] = 0; continue; }
+        const rows = src.prepare(`SELECT * FROM "${table}"`).all();
+        if (rows.length === 0) { counts[table] = 0; continue; }
+        const cols = Object.keys(rows[0]);
+        const placeholders = cols.map((c) => `@${c}`).join(", ");
+        const stmt = db.prepare(
+          `INSERT OR REPLACE INTO "${table}" (${cols.map((c) => `"${c}"`).join(", ")}) VALUES (${placeholders})`);
+        for (const row of rows) stmt.run(row);
+        counts[table] = rows.length;
+      }
+      db.exec("COMMIT");
+    } catch (e) { db.exec("ROLLBACK"); throw e; }
+    return { ok: true, counts };
+  } finally {
+    src.close();
+  }
+};
+
+// import-json: one-time import from a dashboard exportCrewState JSON payload.
+// Used for the live migration (the artifact's app.db is never opened directly).
+// Args: { data: { projects: [...], tasks: [...], agent_sessions: [...], events: [...], config: [...], poll_state: [...] } }
+// Or pipe the JSON via stdin.
+commands["import-json"] = (db, args) => {
+  const data = args.data;
+  if (!data || typeof data !== "object") throw usageError("data must be the exportCrewState JSON object.");
+  const tables = ["projects", "tasks", "poll_state", "config", "agent_sessions", "events"];
+  const counts = {};
+  db.exec("BEGIN");
+  try {
+    for (const table of tables) {
+      const rows = data[table];
+      if (!Array.isArray(rows) || rows.length === 0) { counts[table] = 0; continue; }
+      const cols = Object.keys(rows[0]);
+      const placeholders = cols.map((c) => `@${c}`).join(", ");
+      const stmt = db.prepare(
+        `INSERT OR REPLACE INTO "${table}" (${cols.map((c) => `"${c}"`).join(", ")}) VALUES (${placeholders})`);
+      for (const row of rows) stmt.run(row);
+      counts[table] = rows.length;
+    }
+    db.exec("COMMIT");
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
+  return { ok: true, counts };
+};
+
+// ---------------------------------------------------------------------------
+// CLI plumbing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = { flags: {}, json: null, command: null, crewHome: null };
+  let i = 0;
+  const rest = [];
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === "--crew-home") { out.crewHome = argv[++i]; }
+    else if (a === "--json") { out.json = argv[++i]; }
+    else if (a.startsWith("--")) {
+      const key = a.slice(2).replace(/-/g, "_");
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) { out.flags[key] = true; }
+      else { out.flags[key] = next; i++; }
+    } else rest.push(a);
+    i++;
+  }
+  if (rest.length > 0) out.command = rest[0].replace(/_/g, "-");
+  return out;
+}
+
+function readStdin() {
+  if (process.stdin.isTTY) return null;
+  try {
+    const data = readFileSync(0, "utf8").trim();
+    return data ? data : null;
+  } catch { return null; }
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  const cmd = commands[parsed.command];
+  if (!cmd) {
+    const names = Object.keys(commands).sort().join(", ");
+    throw usageError(`unknown command: ${parsed.command ?? "(none)"}. Known: ${names}.`);
+  }
+  let args = { ...parsed.flags };
+  const raw = parsed.json ?? readStdin();
+  if (raw) {
+    try { args = { ...args, ...JSON.parse(raw) }; }
+    catch { throw usageError("--json must be valid JSON."); }
+  }
+  const crewHome = resolveCrewHome(parsed.crewHome);
+  const db = openDb(crewHome);
+  try {
+    const result = cmd(db, args, { crewHome });
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } finally {
+    db.close();
+  }
+}
+
+try {
+  main();
+} catch (e) {
+  const code = e instanceof CrewError ? e.code : "internal";
+  const exitCode = e instanceof CrewError ? e.exitCode : 1;
+  process.stderr.write(JSON.stringify({ ok: false, error: code, message: e.message }) + "\n");
+  process.exit(exitCode);
+}