@staix/agent-hub 0.3.2 → 0.5.0

package/src/hub/lifecycle.ts

@@ -0,0 +1,189 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createServer, type Server } from "node:net";
+import { ControlClient, PROTOCOL, readControl } from "./control-client.ts";
+import { startDaemon } from "./daemon.ts";
+import { Registry, type Project } from "./registry.ts";
+import { CODEX_APP, CODEX_PROXY, CONTROL, SWITCHYARD } from "./ports.ts";
+import { assertLifecycleAvailable, recoveryLock } from "./recovery-store.ts";
+
+export type ProjectInspection = {
+  state: "running" | "stopped" | "stopping" | "unavailable" | "incompatible" | "missing" | "starting";
+  status?: any;
+  error?: string;
+};
+
+function processAlive(pid: unknown): boolean | undefined {
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return undefined;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH" ? false : undefined; }
+}
+
+/** A port or PID alone is never evidence that the selected project's hub is alive. */
+export async function inspectProject(project: Project): Promise<ProjectInspection> {
+  if (!existsSync(project.root)) return { state: "missing", error: "project directory is missing" };
+  const control = readControl(project.stateDir);
+  if (control) {
+    if (processAlive(control.pid) === false) return { state: "stopped" };
+    if (control.protocol !== undefined && control.protocol !== PROTOCOL) {
+      return { state: "incompatible", error: `hub protocol ${control.protocol}; stop with its matching CLI before upgrading` };
+    }
+    if ((control.projectId && control.projectId !== project.id) || control.cwd !== project.root) {
+      return { state: "unavailable", error: "state directory belongs to a different project" };
+    }
+    let client: ControlClient | undefined;
+    try {
+      // Older manifests omit identity. Authenticate first, then require the full current contract.
+      client = await ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root,
+        ...(control.projectId ? { projectId: project.id } : {}), ...(control.instanceId ? { instanceId: control.instanceId } : {}) });
+      const response = await client.request({ t: "status" }, 3000);
+      if (!response.status || response.status.projectId !== project.id || !response.status.instanceId || response.status.cwd !== project.root) {
+        return { state: "unavailable", error: "authenticated hub identity does not match registration" };
+      }
+      if (project.instanceId && project.instanceId !== response.status.instanceId && processAlive(project.pid) !== false) {
+        return { state: "unavailable", error: "daemon instance differs from the registry claim" };
+      }
+      return response.status.stopping
+        ? { state: "stopping", status: response.status, error: "hub shutdown is pending; wait before starting it again" }
+        : { state: "running", status: response.status };
+    } catch (error) {
+      return { state: (error as { code?: number }).code === 4426 ? "incompatible" : "unavailable", error: (error as Error).message };
+    } finally { client?.close(); }
+  }
+  if (project.instanceId && processAlive(project.pid) !== false) return { state: "starting", error: "daemon owns a startup or shutdown claim" };
+  try {
+    const pid = Number(readFileSync(join(project.stateDir, "hub.pid"), "utf8").trim());
+    if (processAlive(pid) !== false) return { state: "unavailable", error: "state has a live or uncertain owner but no usable control connection" };
+  } catch { /* no legacy PID file */ }
+  return { state: "stopped" };
+}
+
+/** Probe the full stride's used ports before publishing a daemon; close only our own probes. */
+async function available(base: number): Promise<boolean> {
+  const servers: Server[] = [];
+  try {
+    for (const offset of [CONTROL, CODEX_APP, CODEX_PROXY, SWITCHYARD]) {
+      const server = createServer();
+      servers.push(server);
+      await new Promise<void>((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(base + offset, "127.0.0.1", () => resolve());
+      });
+    }
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EADDRINUSE") return false;
+    throw error;
+  } finally {
+    await Promise.all(servers.map((server) => new Promise<void>((resolve) => {
+      if (!server.listening) return resolve();
+      server.close(() => resolve());
+    })));
+  }
+}
+
+/** Called only in the detached daemon process. A competing starter exits without touching state. */
+export async function runProjectDaemon(project: Project, unattended = false): Promise<void> {
+  assertLifecycleAvailable();
+  const registry = new Registry();
+  const instanceId = randomUUID();
+  let claimed = false;
+  let daemon: Awaited<ReturnType<typeof startDaemon>> | undefined;
+  try {
+    const before = await inspectProject(registry.get(project.id) ?? project);
+    if (before.state === "running" || before.state === "starting") return;
+    if (before.state !== "stopped") throw new Error(before.error ?? before.state);
+    claimed = registry.claim(project.id, instanceId, process.pid);
+    if (!claimed) return;
+    let base = registry.get(project.id)!.basePort;
+    for (let attempt = 0; attempt < 100; attempt++) {
+      if (await available(base)) {
+        try {
+          daemon = await startDaemon({ cwd: project.root, stateDir: project.stateDir, projectId: project.id, instanceId,
+            controlPort: base + CONTROL, codexAppPort: base + CODEX_APP, codexProxyPort: base + CODEX_PROXY,
+            switchyardPort: base + SWITCHYARD, unattended });
+          break;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error;
+        }
+      }
+      base = registry.reallocate(project.id, instanceId);
+    }
+    if (!daemon) throw new Error("no free hub port range after 100 attempts");
+    const stop = () => { void daemon!.stop().catch((error) => console.error(`shutdown incomplete: ${(error as Error).message}`)); };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    try { await daemon.stopped; }
+    finally { process.off("SIGINT", stop); process.off("SIGTERM", stop); }
+  } finally {
+    if (claimed) registry.release(project.id, instanceId);
+    registry.close();
+  }
+}
+
+export async function startProject(project: Project, options: { unattended?: boolean; env?: NodeJS.ProcessEnv } = {}): Promise<any> {
+  assertLifecycleAvailable();
+  const registry = new Registry();
+  try {
+    const current = registry.get(project.id);
+    if (!current || current.root !== project.root || current.stateDir !== project.stateDir) throw new Error("project registration changed; refresh before starting");
+    const before = await inspectProject(current);
+    if (before.state === "running") return before.status;
+    if (before.state !== "stopped" && before.state !== "starting") throw new Error(before.error ?? before.state);
+    if (!existsSync(join(project.root, ".agenthub", "config.json"))) throw new Error("project is not initialized; run ahub init there first");
+    if (before.state === "stopped") {
+      mkdirSync(project.stateDir, { recursive: true });
+      const marker = join(project.stateDir, "project.json");
+      const temporary = `${marker}.${randomUUID()}.tmp`;
+      writeFileSync(temporary, JSON.stringify({ root: project.root, projectId: project.id }), { mode: 0o600 });
+      renameSync(temporary, marker);
+      const log = openSync(join(project.stateDir, "hub.log"), "a");
+      try {
+        const launchEnv = { ...(options.env ?? process.env) };
+        // Native sessions can outlive the operation which launched them. An expired
+        // operation ID must not make a later ordinary startup load a retired snapshot.
+        if (launchEnv.AGENTHUB_RECOVERY_OPERATION !== recoveryLock()) delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
+        const child = spawn(process.execPath, [join(import.meta.dir, "../cli/main.ts"), "--project", project.root, "daemon",
+          ...(options.unattended ? ["--unattended"] : [])], {
+          cwd: project.root, detached: true, stdio: ["ignore", log, log],
+          env: { ...launchEnv, AGENTHUB_STATE_DIR: project.stateDir, AGENTHUB_PROJECT_DIR: project.root,
+            AGENTHUB_UNATTENDED: options.unattended ? "1" : "0" },
+        });
+        child.on("error", () => {}); // bounded readiness below reports failure with the project's log path
+        child.unref();
+      } finally { closeSync(log); }
+    }
+    const deadline = Date.now() + 12_000;
+    while (Date.now() < deadline) {
+      const observed = await inspectProject(registry.get(project.id) ?? project);
+      if (observed.state === "running") return observed.status;
+      if (observed.state === "incompatible" || observed.state === "missing") throw new Error(observed.error ?? observed.state);
+      await Bun.sleep(100);
+    }
+    throw new Error(`hub readiness not confirmed; inspect ${join(project.stateDir, "hub.log")} before retrying`);
+  } finally { registry.close(); }
+}
+
+export async function stopProject(project: Project, expectedInstance?: string): Promise<void> {
+  assertLifecycleAvailable();
+  const inspection = await inspectProject(project);
+  if (inspection.state === "stopped") return;
+  if (inspection.state !== "running" && inspection.state !== "stopping") throw new Error(inspection.error ?? "hub ownership is not verified; not stopping it");
+  const instanceId = inspection.status.instanceId as string;
+  if (expectedInstance && expectedInstance !== instanceId) throw new Error("hub restarted; refresh before stopping");
+  const client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId });
+  try {
+    const result = await client.request({ t: "kill", instanceId }, 3000);
+    if (!result.ok) throw new Error(result.error ?? "hub did not acknowledge shutdown");
+  } finally { client.close(); }
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    const current = readControl(project.stateDir);
+    if (!current) return; // daemon removes its manifest only after owned children stop
+    if (current.instanceId !== instanceId) throw new Error("a new hub instance started; it was not stopped");
+    await Bun.sleep(100);
+  }
+  throw new Error("shutdown is still pending; state and ownership were retained");
+}

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/peers.ts

@@ -15,6 +15,8 @@ export interface PeerAdapter {
   onState?: (state: PeerState) => void;
   /** Set by the bus. A delivery that had resolved turned out not to reach the agent: put it back. */
   onFailed?: (envs: Envelope[]) => void;
+  /** Safe restart metadata only: ids and launch parameters, never prompt/message text. */
+  recoveryMetadata?(): Record<string, unknown>;
 }
 
 export const DEFAULT_WATCHDOG_MS = 300_000;

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"));
+}