@staix/agent-hub 0.3.1 → 0.4.0

package/src/hub/manager.ts

@@ -0,0 +1,232 @@
+import { Database } from "bun:sqlite";
+import { randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { ControlClient, PROTOCOL } from "./control-client.ts";
+import { Registry, type Project } from "./registry.ts";
+import { hubHome } from "./project.ts";
+import { startDashboard } from "./ui.ts";
+import { projectChain } from "../memory/recall.ts";
+import type { ProjectInspection } from "./lifecycle.ts";
+
+export type ProjectRecord = Project;
+export type Lifecycle = {
+  inspectProject(project: Project): Promise<ProjectInspection>;
+  startProject(project: Project, options?: { unattended?: boolean; env?: NodeJS.ProcessEnv }): Promise<any>;
+  stopProject(project: Project, expectedInstance?: string): Promise<void>;
+};
+export type ManagerOptions = { registry?: Registry; lifecycle?: Lifecycle; home?: string; cli?: string };
+type ManagerHandle = { stop(): Promise<void>; stopped: Promise<void> };
+type Manifest = { port: number; protocol: number; instanceId: string; pid: number };
+const active = new Map<string, { handle: ManagerHandle; issue(): string }>();
+const CONTROL_TIMEOUT = 3000;
+const safeError = (error: unknown) => error instanceof Error ? error.message.slice(0, 300) : "operation failed";
+
+function files(home: string) {
+  const dir = join(home, "manager");
+  return { dir, token: join(dir, "control-token"), status: join(dir, "status.json"), owner: join(dir, "owner.db") };
+}
+function scrubEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const out = { ...env };
+  for (const key of ["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR", "AGENTHUB_UNATTENDED", "AGENTHUB_OMNIROUTE_URL", "OMNIROUTE_API_KEY"]) delete out[key];
+  return out;
+}
+async function bounded<T>(promise: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try { return await Promise.race([promise, new Promise<T>((_, reject) => {
+    timer = setTimeout(() => reject(new Error("completion was not confirmed; refresh before retrying")), ms);
+  })]); } finally { clearTimeout(timer); }
+}
+function alive(pid: number): boolean | undefined {
+  if (!Number.isSafeInteger(pid) || pid < 1) return undefined;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH" ? false : undefined; }
+}
+function claimOwner(path: string, instanceId: string): Database {
+  const db = new Database(path, { create: true });
+  try {
+    db.run("PRAGMA busy_timeout = 5000");
+    db.run("CREATE TABLE IF NOT EXISTS owner (slot INTEGER PRIMARY KEY CHECK (slot = 1), instance_id TEXT NOT NULL, pid INTEGER NOT NULL)");
+    db.transaction(() => {
+      const row = db.query("SELECT pid FROM owner WHERE slot = 1").get() as { pid: number } | null;
+      if (row && alive(row.pid) !== false) throw new Error("manager has a live or uncertain owner");
+      db.query("INSERT OR REPLACE INTO owner (slot, instance_id, pid) VALUES (1, ?, ?)").run(instanceId, process.pid);
+    }).immediate();
+    return db;
+  } catch (error) { db.close(); throw error; }
+}
+function readManifest(home: string): Manifest | undefined {
+  try {
+    const status = JSON.parse(readFileSync(files(home).status, "utf8"));
+    if (!Number.isInteger(status.port) || status.port < 1 || status.port > 65535 || typeof status.instanceId !== "string") return undefined;
+    return status;
+  } catch { return undefined; }
+}
+function removeManifest(home: string, instanceId: string) {
+  if (readManifest(home)?.instanceId !== instanceId) return;
+  rmSync(files(home).status, { force: true });
+  rmSync(files(home).token, { force: true });
+}
+
+export async function startManager(options: ManagerOptions = {}): Promise<ManagerHandle> {
+  const home = options.home ?? hubHome();
+  const existing = active.get(home);
+  if (existing) return existing.handle;
+  if (!options.lifecycle) throw new Error("manager lifecycle is not configured");
+  const lifecycle = options.lifecycle;
+  const registry = options.registry ?? new Registry(join(home, "registry.db"));
+  const ownsRegistry = !options.registry;
+  const f = files(home);
+  mkdirSync(f.dir, { recursive: true, mode: 0o700 });
+  const token = randomBytes(32).toString("hex"), instanceId = randomUUID();
+  let owner: Database | undefined;
+  let server: ReturnType<typeof Bun.serve> | undefined;
+  let dashboard: ReturnType<typeof startDashboard> | undefined;
+  let stopping = false;
+  let resolveStopped!: () => void;
+  const stopped = new Promise<void>((resolve) => { resolveStopped = resolve; });
+  const cleanup = () => {
+    dashboard?.stop(); server?.stop(true);
+    active.delete(home);
+    removeManifest(home, instanceId);
+    if (owner) {
+      owner.query("DELETE FROM owner WHERE slot = 1 AND instance_id = ? AND pid = ?").run(instanceId, process.pid);
+      owner.close(); owner = undefined;
+    }
+    if (ownsRegistry) registry.close();
+  };
+  const stop = async () => {
+    if (stopping) return;
+    stopping = true;
+    cleanup(); resolveStopped();
+  };
+  try {
+    owner = claimOwner(f.owner, instanceId);
+    const aliases = new Map<string, { at: number; names: string[] }>();
+    const list = async () => {
+      const projects = registry.list();
+      for (const p of projects) if (!aliases.has(p.id) || Date.now() - aliases.get(p.id)!.at > 60_000) {
+        aliases.set(p.id, { at: Date.now(), names: existsSync(p.root) ? projectChain(p.root) : [] });
+      }
+      const rows = await Promise.all(projects.map(async (project) => {
+        let result: ProjectInspection;
+        try { result = await bounded(lifecycle.inspectProject(project), 7000); }
+        catch (error) { result = { state: "unavailable", error: safeError(error) }; }
+        const names = aliases.get(project.id)!.names;
+        const shared = projects.some((other) => other.id !== project.id && aliases.get(other.id)!.names.some((name) => names.includes(name)));
+        return { id: project.id, root: project.root, state: result.state,
+          instanceId: result.state === "running" ? result.status?.instanceId ?? null : null,
+          peers: result.status?.peers ?? {}, tasks: result.status?.tasks ?? {},
+          ...(shared ? { warning: "Native memory aliases are shared with another registered project." } : {}),
+          ...(result.error ? { error: result.error } : {}) };
+      }));
+      return { ok: true, mode: "all", projects: rows };
+    };
+    const act = async (input: Record<string, unknown>) => {
+      if (stopping) return { ok: false, error: "manager is stopping" };
+      const project = typeof input.projectId === "string" ? registry.get(input.projectId) : undefined;
+      if (!project) return { ok: false, error: "unknown project" };
+      let client: ControlClient | undefined;
+      try {
+        if (input.action === "start") {
+          const status = await bounded(lifecycle.startProject(project, { unattended: false, env: { ...scrubEnv(process.env), AGENTHUB_HOME: home } }), 20_000);
+          return { ok: true, projectId: project.id, instanceId: status.instanceId };
+        }
+        if (typeof input.instanceId !== "string" || !input.instanceId) return { ok: false, error: "expected daemon instance is required" };
+        if (input.action === "stop") {
+          await bounded(lifecycle.stopProject(project, input.instanceId), 20_000);
+          return { ok: true };
+        }
+        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
+        client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
+        return await client.request(input.action === "snapshot"
+          ? { t: "ui_snapshot", after: input.after ?? 0 }
+          : { t: "ui_action", action: input, instanceId: input.instanceId }, 10_000);
+      } catch (error) { return { ok: false, error: safeError(error) }; }
+      finally { client?.close(); }
+    };
+    dashboard = startDashboard({ projects: list, snapshot: (after, input = {}) => act({ ...input, action: "snapshot", after }), action: act });
+    server = Bun.serve({ hostname: "127.0.0.1", port: 0, maxRequestBodySize: 1024,
+      fetch(req) {
+        if (req.headers.has("origin")) return new Response("forbidden", { status: 403 });
+        if (req.headers.get("authorization") !== `Bearer ${token}`) return new Response("unauthorized", { status: 401 });
+        if (req.method !== "POST") return new Response("POST required", { status: 405 });
+        const expected = req.headers.get("x-agenthub-instance");
+        if (expected && expected !== instanceId) return Response.json({ ok: false, error: "manager instance changed" }, { status: 409 });
+        if (stopping) return Response.json({ ok: false, error: "manager is stopping" }, { status: 409 });
+        const path = new URL(req.url).pathname;
+        if (path === "/open") return Response.json({ ok: true, instanceId, protocol: PROTOCOL, url: dashboard!.issue() });
+        if (path === "/stop") { setTimeout(() => void stop(), 0); return Response.json({ ok: true, instanceId }); }
+        return new Response("not found", { status: 404 });
+      },
+    });
+    writeFileSync(f.token, token, { mode: 0o600 });
+    chmodSync(f.token, 0o600);
+    const temp = `${f.status}.${instanceId}.tmp`;
+    writeFileSync(temp, JSON.stringify({ port: server.port, protocol: PROTOCOL, instanceId, pid: process.pid }));
+    renameSync(temp, f.status);
+    const handle = { stop, stopped };
+    active.set(home, { handle, issue: () => dashboard!.issue() });
+    return handle;
+  } catch (error) { cleanup(); throw error; }
+}
+
+async function managerRequest(home: string, path: "/open" | "/stop"): Promise<{ status: Manifest; body: any }> {
+  const status = readManifest(home);
+  if (!status) throw new Error("manager manifest is unavailable");
+  if (status.protocol !== PROTOCOL) throw new Error("manager protocol is incompatible; use its matching CLI to stop it");
+  const token = readFileSync(files(home).token, "utf8").trim();
+  if (!token) throw new Error("manager token is unavailable");
+  const response = await fetch(`http://127.0.0.1:${status.port}${path}`, {
+    method: "POST", headers: { authorization: `Bearer ${token}`, "x-agenthub-instance": status.instanceId }, signal: AbortSignal.timeout(CONTROL_TIMEOUT),
+  });
+  if (!response.ok) throw new Error(`manager refused request (${response.status}); ownership was not verified`);
+  const body = await response.json() as { ok?: boolean; instanceId?: string; url?: string };
+  if (!body.ok || body.instanceId !== status.instanceId) throw new Error("manager identity changed; refresh before retrying");
+  return { status, body };
+}
+
+export async function openManager(options: ManagerOptions = {}): Promise<string> {
+  const home = options.home ?? hubHome();
+  const local = active.get(home);
+  if (local) return local.issue();
+  try { return (await managerRequest(home, "/open")).body.url; }
+  catch (error) {
+    const old = readManifest(home);
+    if (old && alive(old.pid) !== false) throw error;
+    // A definitely dead manager can be recovered by its ownership claim.
+  }
+  const f = files(home);
+  mkdirSync(f.dir, { recursive: true, mode: 0o700 });
+  const log = openSync(join(f.dir, "manager.log"), "a");
+  try {
+    const proc = spawn(process.execPath, [options.cli ?? join(import.meta.dir, "../cli/main.ts"), "manager"], {
+      cwd: home, detached: true, stdio: ["ignore", log, log], env: { ...scrubEnv(process.env), AGENTHUB_HOME: home },
+    });
+    proc.on("error", () => {}); proc.unref();
+  } finally { closeSync(log); }
+  const deadline = Date.now() + 8000;
+  let error: unknown;
+  while (Date.now() < deadline) {
+    try { return (await managerRequest(home, "/open")).body.url; }
+    catch (caught) { error = caught; await Bun.sleep(100); }
+  }
+  throw new Error(`manager readiness not confirmed: ${safeError(error)}; see ${join(f.dir, "manager.log")}`);
+}
+
+export async function stopManager(options: ManagerOptions = {}): Promise<void> {
+  const home = options.home ?? hubHome();
+  const local = active.get(home);
+  if (local) return local.handle.stop();
+  if (!existsSync(files(home).status)) return;
+  const { status } = await managerRequest(home, "/stop");
+  const deadline = Date.now() + CONTROL_TIMEOUT;
+  while (Date.now() < deadline) {
+    const current = readManifest(home);
+    if (!current) return;
+    if (current.instanceId !== status.instanceId) throw new Error("a new manager instance started; it was not stopped");
+    await Bun.sleep(25);
+  }
+  throw new Error("manager shutdown is still pending; project hubs were not changed");
+}

package/src/hub/ports.ts

@@ -1,6 +1,7 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { Registry } from "./registry.ts";
+import { hubHome } from "./project.ts";
 
 export const BASE_PORT = 4600;
 export const STRIDE = 10;
@@ -10,20 +11,48 @@ export const CODEX_APP = 1;
 export const CODEX_PROXY = 2;
 export const SWITCHYARD = 3;
 
-/** One stride of loopback ports per project directory, remembered in ~/.agenthub/ports.json. */
-export function allocatePorts(projectDir: string, registry = join(homedir(), ".agenthub", "ports.json")): number {
-  let map: Record<string, number> = {};
+/** SQLite-backed project allocation; an explicit JSON path retains the legacy utility API under a lock. */
+export function allocatePorts(projectDir: string, registry?: string): number {
+  if (registry === undefined) {
+    const db = new Registry(join(hubHome(), "registry.db"));
+    try {
+      return db.allocate(projectDir);
+    } finally {
+      db.close();
+    }
+  }
+  mkdirSync(dirname(registry), { recursive: true });
+  const lock = `${registry}.lock`;
+  for (let attempt = 0; ; attempt++) {
+    try { mkdirSync(lock); break; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST" || attempt >= 500) throw new Error(`cannot lock legacy port registry ${registry}`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
   try {
-    map = JSON.parse(readFileSync(registry, "utf8"));
-  } catch {
-    // first use
+  let map: Record<string, number> = {};
+  if (existsSync(registry)) {
+    try {
+      map = JSON.parse(readFileSync(registry, "utf8"));
+    } catch (error) {
+      throw new Error(`cannot read legacy port registry ${registry}: ${(error as Error).message}`);
+    }
+  }
+  if (!map || Array.isArray(map) || typeof map !== "object") throw new Error(`cannot read legacy port registry ${registry}: expected an object`);
+  const seen = new Set<number>();
+  for (const [root, port] of Object.entries(map)) {
+    if (typeof port !== "number" || !Number.isInteger(port) || port < BASE_PORT || port % STRIDE !== 0) throw new Error(`cannot read legacy port registry ${registry}: invalid port for ${root}`);
+    if (seen.has(port)) throw new Error(`cannot read legacy port registry ${registry}: conflicting port ${port}`);
+    seen.add(port);
   }
   const known = map[projectDir];
   if (known) return known;
   const base = Math.max(BASE_PORT - STRIDE, ...Object.values(map)) + STRIDE;
   map[projectDir] = base;
-  mkdirSync(dirname(registry), { recursive: true });
-  // ponytail: no file lock; two first-time `ahub up` in different projects at the same instant could collide.
-  writeFileSync(registry, `${JSON.stringify(map, null, 2)}\n`);
+  const temp = `${registry}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(temp, `${JSON.stringify(map, null, 2)}\n`);
+  renameSync(temp, registry);
   return base;
+  } finally { rmSync(lock, { recursive: true, force: true }); }
 }

package/src/hub/project.ts

@@ -0,0 +1,93 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const canonical = (path: string): string => {
+  const absolute = resolve(path);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    const parent = dirname(absolute);
+    return parent === absolute ? absolute : join(canonical(parent), basename(absolute));
+  }
+};
+
+export function canonicalPath(path: string): string {
+  return canonical(path);
+}
+
+function gitRoot(dir: string): string | undefined {
+  const result = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  if (result.status !== 0) return undefined;
+  const root = result.stdout.trim();
+  return root ? canonical(root) : undefined;
+}
+
+function hasConfig(dir: string): boolean {
+  return existsSync(join(dir, ".agenthub", "config.json"));
+}
+
+/** Resolve the project root without crossing the nearest Git working-tree boundary. */
+export function projectRoot(cwd: string): string {
+  const input = isAbsolute(cwd) ? cwd : resolve(cwd);
+  let dir: string;
+  try {
+    dir = canonical(input);
+    if (!lstatSync(dir).isDirectory()) throw new Error(`${cwd} is not a directory`);
+  } catch (error) {
+    throw new Error(`cannot resolve project directory ${cwd}: ${(error as Error).message}`);
+  }
+
+  const boundary = gitRoot(dir);
+  const stop = boundary ?? parseRoot(dir);
+  for (let current = dir; ; current = dirname(current)) {
+    if (hasConfig(current)) return canonical(current);
+    if (current === stop || current === dirname(current)) break;
+  }
+  return boundary ?? dir;
+}
+
+function parseRoot(dir: string): string {
+  let current = dir;
+  while (dirname(current) !== current) current = dirname(current);
+  return current;
+}
+
+function stateMarker(stateDir: string): string | undefined {
+  for (const file of [join(stateDir, "project.json"), join(stateDir, "status.json")]) {
+    try {
+      const value = JSON.parse(readFileSync(file, "utf8")) as { root?: string; cwd?: string };
+      const root = value.root ?? value.cwd;
+      if (typeof root === "string") return canonical(root);
+    } catch {
+      // A missing or incomplete marker is not a valid proof of ownership.
+    }
+  }
+  return undefined;
+}
+
+export interface ProjectContext {
+  root: string;
+  stateDir: string;
+}
+
+/** Resolve a project and accept an inherited state directory only with an ownership proof. */
+export function projectContext(cwd: string, env: NodeJS.ProcessEnv = process.env): ProjectContext {
+  const root = projectRoot(cwd);
+  const override = env.AGENTHUB_STATE_DIR?.trim();
+  if (!override) return { root, stateDir: canonical(join(root, ".agenthub", "state")) };
+
+  const declared = env.AGENTHUB_PROJECT_DIR?.trim();
+  const stateDir = canonical(override);
+  const recorded = stateMarker(stateDir);
+  if (recorded === root) return { root, stateDir };
+  // A marker for another project is authoritative; an inherited mismatch must not
+  // redirect this cwd. The explicit pair is only for a freshly initialized state.
+  if (!recorded && declared && canonical(declared) === root) return { root, stateDir };
+  return { root, stateDir: canonical(join(root, ".agenthub", "state")) };
+}
+
+export function hubHome(env: NodeJS.ProcessEnv = process.env): string {
+  return canonical(env.AGENTHUB_HOME?.trim() || join(homedir(), ".agenthub"));
+}

package/src/hub/registry.ts

@@ -0,0 +1,204 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { canonicalPath, hubHome, projectRoot } from "./project.ts";
+
+const BASE_PORT = 4600;
+const STRIDE = 10;
+const MAX_PORT = 65535 - 3;
+const LEGACY_DONE = "legacy_ports_imported";
+type Tx = { immediate(): void };
+// SQLite's busy_timeout bounds contention; never multiply it through unbounded retries.
+const runTx = (tx: Tx): void => { tx.immediate(); };
+
+export interface Project {
+  id: string;
+  root: string;
+  stateDir: string;
+  basePort: number;
+  instanceId: string | null;
+  pid: number | null;
+}
+
+const idFor = (root: string) => `p_${createHash("sha256").update(root).digest("hex").slice(0, 24)}`;
+// Preserve the original identifier of missing legacy checkouts as a reservation.
+const legacyRoot = (path: string) => { try { return realpathSync(path); } catch { return resolve(path); } };
+const canonicalState = canonicalPath;
+const alive = (pid: number): boolean | undefined => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ESRCH") return false;
+    return undefined;
+  }
+};
+
+export class Registry {
+  readonly path: string;
+  private readonly db: Database;
+
+  constructor(path = join(hubHome(), "registry.db")) {
+    this.path = path;
+    mkdirSync(dirname(path), { recursive: true });
+    this.db = new Database(path, { create: true });
+    this.db.run("PRAGMA busy_timeout = 5000");
+    try {
+      this.db.run("PRAGMA journal_mode = WAL");
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "SQLITE_BUSY" && code !== "SQLITE_LOCKED") throw error;
+    }
+    this.db.run(`CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY, root TEXT NOT NULL UNIQUE, state_dir TEXT NOT NULL UNIQUE,
+      base_port INTEGER NOT NULL UNIQUE, instance_id TEXT, pid INTEGER, claimed_at INTEGER
+    )`);
+    this.db.run("CREATE TABLE IF NOT EXISTS registry_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+    this.importLegacy();
+  }
+
+  register(root: string, stateDir?: string): Project {
+    const canonicalRoot = projectRoot(root);
+    const explicitState = stateDir !== undefined;
+    const stateInput = stateDir ? (stateDir.startsWith("/") ? stateDir : join(canonicalRoot, stateDir)) : join(canonicalRoot, ".agenthub", "state");
+    const state = canonicalState(stateInput);
+    const id = idFor(canonicalRoot);
+    const tx = this.db.transaction(() => {
+      const existing = this.row(id);
+      if (existing) {
+        if (existing.root !== canonicalRoot) throw new Error(`registry id collision for ${canonicalRoot}`);
+        if (explicitState && existing.stateDir !== state) {
+          if (existing.instanceId && (existing.pid === null || alive(existing.pid) !== false)) throw new Error(`cannot relocate live or uncertain project ${id}`);
+          this.db.query("UPDATE projects SET state_dir = ? WHERE id = ?").run(state, id);
+        }
+        return;
+      }
+      const basePort = this.nextBase();
+      try {
+        this.db.query("INSERT INTO projects (id, root, state_dir, base_port) VALUES (?, ?, ?, ?)").run(id, canonicalRoot, state, basePort);
+      } catch (error) {
+        throw new Error(`cannot register ${canonicalRoot}: ${(error as Error).message}`);
+      }
+    });
+    runTx(tx as Tx);
+    return this.get(id)!;
+  }
+
+  get(id: string): Project | undefined {
+    return this.row(id) ?? undefined;
+  }
+
+  list(): Project[] {
+    return this.db.query("SELECT id, root, state_dir as stateDir, base_port as basePort, instance_id as instanceId, pid FROM projects ORDER BY root").all() as Project[];
+  }
+
+  allocate(root: string): number {
+    return this.register(root).basePort;
+  }
+
+  reallocate(id: string, instanceId: string): number {
+    let base = 0;
+    const tx = this.db.transaction(() => {
+      const project = this.row(id);
+      if (!project || project.instanceId !== instanceId) throw new Error(`project ${id} is not owned by instance ${instanceId}`);
+      base = this.nextBase(project.basePort);
+      this.db.query("UPDATE projects SET base_port = ? WHERE id = ?").run(base, id);
+    });
+    runTx(tx as Tx);
+    return base;
+  }
+
+  claim(id: string, instanceId: string, pid: number): boolean {
+    let claimed = false;
+    const tx = this.db.transaction(() => {
+      const project = this.row(id);
+      if (!project) return;
+      if (project.instanceId && project.instanceId !== instanceId) {
+        if (project.pid === null) return;
+        const state = alive(project.pid);
+        if (state !== false) return;
+      }
+      this.db.query("UPDATE projects SET instance_id = ?, pid = ?, claimed_at = ? WHERE id = ?").run(instanceId, pid, Date.now(), id);
+      claimed = true;
+    });
+    runTx(tx as Tx);
+    return claimed;
+  }
+
+  release(id: string, instanceId: string): void {
+    this.db.query("UPDATE projects SET instance_id = NULL, pid = NULL, claimed_at = NULL WHERE id = ? AND instance_id = ?").run(id, instanceId);
+  }
+
+  remove(id: string): void {
+    const tx = this.db.transaction(() => {
+      const project = this.row(id);
+      if (!project) return;
+      if (project.instanceId) {
+        if (project.pid === null || alive(project.pid) !== false) throw new Error(`project ${id} has a live or uncertain claim`);
+      } else if (existsSync(join(project.stateDir, "status.json")) || existsSync(join(project.stateDir, "control-token"))) {
+        let pid: number | undefined;
+        try {
+          const status = JSON.parse(readFileSync(join(project.stateDir, "status.json"), "utf8")) as { pid?: number };
+          pid = typeof status.pid === "number" ? status.pid : undefined;
+        } catch {
+          // A state directory without a readable owner marker is uncertain.
+        }
+        if (pid === undefined || alive(pid) !== false) throw new Error(`project ${id} has a live or uncertain legacy state`);
+      }
+      this.db.query("DELETE FROM projects WHERE id = ?").run(id);
+    });
+    runTx(tx as Tx);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  private row(id: string): Project | null {
+    return this.db.query("SELECT id, root, state_dir as stateDir, base_port as basePort, instance_id as instanceId, pid FROM projects WHERE id = ?").get(id) as Project | null;
+  }
+
+  private nextBase(after = BASE_PORT - STRIDE): number {
+    const used = new Set((this.db.query("SELECT base_port as basePort FROM projects").all() as { basePort: number }[]).map((r) => r.basePort));
+    let base = Math.max(BASE_PORT - STRIDE, after);
+    do {
+      base += STRIDE;
+      if (base > MAX_PORT) throw new Error(`no available project port range below ${MAX_PORT}`);
+    } while (used.has(base));
+    return base;
+  }
+
+  private importLegacy(): void {
+    const legacy = join(dirname(this.path), "ports.json");
+    const tx = this.db.transaction(() => {
+      if (this.db.query("SELECT 1 FROM registry_meta WHERE key = ?").get(LEGACY_DONE)) return;
+      if (existsSync(legacy)) {
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(readFileSync(legacy, "utf8"));
+        } catch (error) {
+          throw new Error(`cannot import legacy port registry ${legacy}: ${(error as Error).message}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`cannot import legacy port registry ${legacy}: expected an object`);
+        const seen = new Map<string, number>();
+        for (const [rawRoot, rawPort] of Object.entries(parsed as Record<string, unknown>)) {
+          if (typeof rawPort !== "number" || !Number.isInteger(rawPort) || rawPort < BASE_PORT || rawPort > MAX_PORT || rawPort % STRIDE !== 0) throw new Error(`cannot import legacy port registry ${legacy}: invalid port for ${rawRoot}`);
+          const root = legacyRoot(rawRoot);
+          const alias = seen.get(root);
+          if (alias !== undefined && alias !== rawPort) throw new Error(`cannot import legacy port registry ${legacy}: aliases for ${root} have conflicting ports`);
+          if (alias !== undefined) continue;
+          if ([...seen.values()].includes(rawPort)) throw new Error(`cannot import legacy port registry ${legacy}: conflicting port ${rawPort}`);
+          seen.set(root, rawPort);
+          const id = idFor(root);
+          const existing = this.row(id);
+          if (existing && existing.basePort !== rawPort) throw new Error(`legacy port for ${root} conflicts with registry`);
+          if (!existing) this.db.query("INSERT INTO projects (id, root, state_dir, base_port) VALUES (?, ?, ?, ?)").run(id, root, join(root, ".agenthub", "state"), rawPort);
+        }
+      }
+      this.db.query("INSERT INTO registry_meta (key, value) VALUES (?, ?)").run(LEGACY_DONE, String(Date.now()));
+    });
+    runTx(tx as Tx);
+  }
+}

package/src/hub/ui.ts

@@ -2,8 +2,10 @@ import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 
 export interface DashboardOptions {
-  snapshot: (after: number) => unknown;
-  action: (input: Record<string, unknown>) => Promise<unknown>;
+  snapshot: (after: number, input?: Record<string, unknown>) => unknown | Promise<unknown>;
+  action: (input: Record<string, unknown>) => unknown | Promise<unknown>;
+  projects?: () => unknown | Promise<unknown>;
+  selectedProjectId?: string;
   /** Injectable clock for expiry tests; production uses wall time. */
   now?: () => number;
 }
@@ -49,7 +51,7 @@ export function startDashboard(options: DashboardOptions) {
       if (req.method !== "POST") return reject(405, "POST required");
       if (requestOrigin !== origin) return reject(403, "origin required");
       if (req.headers.get("content-type")?.split(";")[0]?.trim() !== "application/json") return reject(415, "JSON required");
-      if (!["/session", "/snapshot", "/action"].includes(path)) return reject(404, "not found");
+      if (!["/session", "/projects", "/snapshot", "/action"].includes(path)) return reject(404, "not found");
       prune(tickets);
       prune(sessions);
       let cookie: string | undefined;
@@ -76,10 +78,33 @@ export function startDashboard(options: DashboardOptions) {
         sessions.set(session, now() + SESSION_MS);
         return json({ ok: true }, 200, { "Set-Cookie": `${cookieName}=${session}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${SESSION_MS / 1000}` });
       }
+      if (path === "/projects") {
+        if (!options.projects) {
+          const result: Record<string, unknown> = { ok: true, mode: "project" };
+          if (options.selectedProjectId) result.selectedProjectId = options.selectedProjectId;
+          return json(result);
+        }
+        try {
+          return json(await options.projects());
+        } catch {
+          return reject(400, "project listing failed; check its inputs and the terminal");
+        }
+      }
       if (path === "/snapshot") {
         const after = input.after ?? 0;
         if (typeof after !== "number" || !Number.isSafeInteger(after) || after < 0) return reject(400, "invalid cursor");
-        return json(options.snapshot(after));
+        try {
+          const result = await options.snapshot(after, input);
+          if (!result || typeof result !== "object" || Array.isArray(result)) return json(result);
+          const response = { ...(result as Record<string, unknown>) };
+          if (typeof response.projectId === "string" && typeof input.projectId === "string" && response.projectId !== input.projectId) return reject(409, "snapshot project changed; refresh the dashboard");
+          if (typeof response.instanceId === "string" && typeof input.instanceId === "string" && response.instanceId !== input.instanceId) return reject(409, "snapshot instance changed; refresh the dashboard");
+          if (typeof input.projectId === "string" && response.projectId === undefined) response.projectId = input.projectId;
+          if (typeof input.instanceId === "string" && response.instanceId === undefined) response.instanceId = input.instanceId;
+          return json(response);
+        } catch {
+          return reject(400, "snapshot failed; check its inputs and the terminal");
+        }
       }
       try {
         return json(await options.action(input));