@staix/agent-hub 0.3.2 → 0.5.0

package/src/hub/recovery-store.ts

@@ -0,0 +1,89 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { Database } from "bun:sqlite";
+import { hubHome } from "./project.ts";
+
+export const operationIdPattern = /^[a-f0-9-]{36}$/;
+export function operationPath(id: string, home = hubHome()): string {
+  if (!operationIdPattern.test(id)) throw new Error("invalid recovery operation ID");
+  return join(home, "recovery", `${id}.json`);
+}
+
+/** Private state only. Never put tokens or transcript/message bodies in an operation receipt. */
+export function atomicPrivateJSON(file: string, value: unknown): void {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, file);
+  } finally { rmSync(temporary, { force: true }); }
+}
+
+export function readOperation<T>(id: string, home = hubHome()): T {
+  return JSON.parse(readFileSync(operationPath(id, home), "utf8")) as T;
+}
+
+export function writeOperation(id: string, value: unknown, home = hubHome()): void {
+  mkdirSync(join(home, "recovery"), { recursive: true, mode: 0o700 });
+  atomicPrivateJSON(operationPath(id, home), value);
+}
+
+export function recoveryLock(home = hubHome()): string | undefined {
+  const file = join(home, "recovery.lock");
+  try {
+    const data = JSON.parse(readFileSync(file, "utf8"));
+    if (!operationIdPattern.test(data.operationId)) throw new Error("invalid recovery lock");
+    return data.operationId;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new Error("recovery lock is unreadable; inspect it before changing runtimes", { cause: error });
+  }
+}
+
+export function acquireRecoveryLock(id: string, home = hubHome()): void {
+  operationPath(id, home);
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  const existing = recoveryLock(home);
+  if (existing === id) return;
+  try { writeFileSync(join(home, "recovery.lock"), JSON.stringify({ operationId: id }), { mode: 0o600, flag: "wx" }); }
+  catch { throw new Error(`another recovery operation owns this machine: ${recoveryLock(home) ?? "unknown"}`); }
+}
+
+export function releaseRecoveryLock(id: string, home = hubHome()): void {
+  if (recoveryLock(home) !== id) throw new Error("recovery lock ownership changed");
+  rmSync(join(home, "recovery.lock"));
+}
+
+/** Used by CLI and manager lifecycle paths. A detached operation carries its own ID. */
+export function assertLifecycleAvailable(): void {
+  const owner = recoveryLock();
+  if (owner && process.env.AGENTHUB_RECOVERY_OPERATION !== owner) {
+    throw new Error(`recovery operation ${owner} is active; use ahub recovery status|resume ${owner}`);
+  }
+}
+
+/** An exclusive runner claim. Never steal a live or uncertain owner on resume. */
+export function claimRunner(id: string, home = hubHome()): () => void {
+  const path = `${operationPath(id, home)}.runner.db`;
+  const db = new Database(path, { create: true });
+  chmodSync(path, 0o600);
+  const nonce = randomUUID();
+  try {
+    db.run("PRAGMA busy_timeout = 3000");
+    db.run("CREATE TABLE IF NOT EXISTS runner (slot INTEGER PRIMARY KEY, pid INTEGER NOT NULL, nonce TEXT NOT NULL)");
+    db.transaction(() => {
+      const row = db.query("SELECT pid FROM runner WHERE slot = 1").get() as { pid: number } | null;
+      if (row) {
+        if (!Number.isSafeInteger(row.pid) || row.pid < 1) throw new Error("invalid recovery runner ownership");
+        try { process.kill(row.pid, 0); throw new Error(`recovery runner ${row.pid} is still alive`); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+      }
+      db.query("INSERT OR REPLACE INTO runner (slot, pid, nonce) VALUES (1, ?, ?)").run(process.pid, nonce);
+    }).immediate();
+  } catch (error) { db.close(); throw error; }
+  return () => {
+    db.query("DELETE FROM runner WHERE slot = 1 AND nonce = ?").run(nonce);
+    db.close();
+  };
+}

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

@@ -0,0 +1,97 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { BusSnapshot } from "./bus.ts";
+import type { PeerId, PeerState } from "./envelope.ts";
+import { MAX_HOP } from "./envelope.ts";
+
+export const RESTART_SCHEMA_VERSION = 1;
+
+export type RecoveryPhase = "preparing" | "prepared" | "restored" | "released";
+
+export interface RestartPeerSnapshot {
+  id: PeerId;
+  state: PeerState;
+  queueIds: string[];
+  launch?: Record<string, unknown>;
+  /** Safe native correlation metadata. Never include prompt/message text here. */
+  threadId?: string;
+  sessionId?: string;
+}
+
+export interface RestartSnapshot {
+  schemaVersion: 1;
+  projectRoot: string;
+  projectId: string;
+  sourceInstanceId: string;
+  operationId: string;
+  committedAt: number;
+  bus: BusSnapshot;
+  manualPaused: PeerId[];
+  peers: RestartPeerSnapshot[];
+  integrity?: {
+    queues: Record<string, string[]>;
+    manualPaused: PeerId[];
+    boardDigest: string;
+    budgetDigest: string;
+  };
+}
+
+export interface RestartReadExpectation {
+  projectRoot: string;
+  projectId: string;
+  operationId?: string;
+}
+
+export function restartPath(stateDir: string): string {
+  return join(stateDir, "restart.json");
+}
+
+export function releasedRestartPath(stateDir: string, operationId: string): string {
+  const safe = createHash("sha256").update(operationId).digest("hex");
+  return join(stateDir, `restart.released.${safe}.json`);
+}
+
+/** Read only a matching controlled-restart snapshot. Unknown or malformed state is ignored and must block recovery upstream. */
+export function readRestartSnapshot(stateDir: string, expected: RestartReadExpectation): RestartSnapshot | undefined {
+  let parsed: unknown;
+  try { parsed = JSON.parse(readFileSync(restartPath(stateDir), "utf8")); } catch { return undefined; }
+  if (!parsed || typeof parsed !== "object") return undefined;
+  const s = parsed as Partial<RestartSnapshot>;
+  if (s.schemaVersion !== RESTART_SCHEMA_VERSION || s.projectRoot !== expected.projectRoot || s.projectId !== expected.projectId || typeof s.operationId !== "string" || !s.operationId || typeof s.sourceInstanceId !== "string" || !s.sourceInstanceId || !s.bus) return undefined;
+  if (expected.operationId !== undefined && s.operationId !== expected.operationId) return undefined;
+  const peerId = (value: unknown): value is string => typeof value === "string" && /^(?:hub|user|[a-z][a-z0-9-]{0,31})$/.test(value);
+  const isEnvelope = (value: unknown, seen = false): boolean => {
+    if (!value || typeof value !== "object") return false;
+    const e = value as Record<string, unknown>;
+    return typeof e.id === "string" && e.id.length > 0 && e.id.length <= 256 && typeof e.trace === "string" && e.trace.length > 0 && e.trace.length <= 256 && peerId(e.from) && typeof e.body === "string" && Number.isSafeInteger(e.hop) && (e.hop as number) >= 0 && (seen || (e.hop as number) <= MAX_HOP) && Number.isFinite(e.ts) && ["chat", "task", "review", "status", "budget", "presence"].includes(e.kind as string) && ["important", "status", "fyi"].includes(e.priority as string) && (e.to === undefined || (Array.isArray(e.to) && e.to.every(peerId)));
+  };
+  const bus = s.bus as Partial<BusSnapshot>;
+  if (bus.schemaVersion !== 1 || !bus.queues || typeof bus.queues !== "object" || !bus.prefaces || typeof bus.prefaces !== "object" || !Array.isArray(bus.seen) || !bus.attempts || typeof bus.attempts !== "object" || !Array.isArray(bus.withdrawn)) return undefined;
+  if (!Object.keys(bus.queues).every(peerId) || !Object.keys(bus.prefaces).every(peerId) || !Object.values(bus.queues).every((queue) => Array.isArray(queue) && queue.every((e) => isEnvelope(e))) || !Object.values(bus.prefaces).every((e) => isEnvelope(e)) || !bus.seen.every((e) => isEnvelope(e, true)) || !bus.withdrawn.every((id) => typeof id === "string" && id.length > 0) || !Object.values(bus.attempts).every((n) => Number.isSafeInteger(n) && n > 0)) return undefined;
+  if (!Array.isArray(s.manualPaused) || !s.manualPaused.every((id) => typeof id === "string") || !Array.isArray(s.peers) || !s.peers.every((peer) => peer && typeof peer === "object" && typeof peer.id === "string" && ["idle", "busy", "paused", "offline"].includes(peer.state as string) && Array.isArray(peer.queueIds) && peer.queueIds.every((id) => typeof id === "string"))) return undefined;
+  if (s.integrity !== undefined && (!s.integrity || typeof s.integrity !== "object" || typeof s.integrity.boardDigest !== "string" || typeof s.integrity.budgetDigest !== "string" || !Array.isArray(s.integrity.manualPaused) || !s.integrity.manualPaused.every((id) => typeof id === "string") || !s.integrity.queues || typeof s.integrity.queues !== "object" || !Object.values(s.integrity.queues).every((ids) => Array.isArray(ids) && ids.every((id) => typeof id === "string")))) return undefined;
+  return s as RestartSnapshot;
+}
+
+/** Atomic, owner-readable recovery state. The file never carries delivery bodies outside this 0600 path. */
+export function writeRestartSnapshot(stateDir: string, snapshot: RestartSnapshot): void {
+  mkdirSync(stateDir, { recursive: true });
+  const file = restartPath(stateDir);
+  const tmp = `${file}.${snapshot.sourceInstanceId}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(snapshot)}\n`, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, file);
+  chmodSync(file, 0o600);
+}
+
+export function removeRestartSnapshot(stateDir: string): void {
+  try { unlinkSync(restartPath(stateDir)); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+}
+
+/** Preserve an uncertain release outcome for manual reconciliation without making it authoritative on startup. */
+export function archiveRestartSnapshot(stateDir: string, operationId: string): void {
+  renameSync(restartPath(stateDir), releasedRestartPath(stateDir, operationId));
+  chmodSync(releasedRestartPath(stateDir, operationId), 0o600);
+}

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));

package/src/memory/recall.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { basename } from "node:path";
+import { basename, dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
 import type { PeerId } from "../hub/envelope.ts";
 import type { MemoryClient } from "./client.ts";
 
@@ -11,11 +12,33 @@ const HEADER =
   "Shared project memory (claude-mem): recent work by the agents in this project. Reference only, not a request. " +
   "Fetch details by id with your memory tools if you need them.";
 
-/** Project names from the outermost superproject down to this repo: claude-mem treats the last one as primary. */
+/** Project names from the outermost superproject down to this repo. */
 export function projectChain(cwd: string): string[] {
   const git = (dir: string, arg: string) => spawnSync("git", ["-C", dir, "rev-parse", arg], { encoding: "utf8" }).stdout?.trim() ?? "";
+  const top = git(cwd, "--show-toplevel");
+  if (!top) return [basename(cwd)];
+
+  // claude-mem's native identity for a worktree is [parent, parent/worktree].
+  // The worktree's .git file points into <parent>/.git/worktrees/<name>; the
+  // ordinary superproject walk below remains unchanged for repos and submodules.
+  const gitFile = resolve(top, ".git");
+  try {
+    const match = readFileSync(gitFile, "utf8").trim().match(/^gitdir:\s*(.+)$/i);
+    if (match) {
+      const gitDir = resolve(top, match[1]!);
+      if (/[/\\]\.git[/\\]worktrees[/\\][^/\\]+$/.test(gitDir)) {
+        const parentRoot = dirname(dirname(dirname(gitDir)));
+        const parent = projectChain(parentRoot);
+        const parentName = basename(parentRoot);
+        return [...parent, `${parentName}/${basename(top)}`];
+      }
+    }
+  } catch {
+    // A missing or unreadable .git file falls through to git's normal chain.
+  }
+
   const chain: string[] = [];
-  for (let dir = git(cwd, "--show-toplevel"); dir && chain.length < 8; dir = git(dir, "--show-superproject-working-tree")) {
+  for (let dir = top; dir && chain.length < 8; dir = git(dir, "--show-superproject-working-tree")) {
     chain.unshift(basename(dir));
   }
   return chain.length ? chain : [basename(cwd)];

package/src/switchyard/sidecar.ts

@@ -4,9 +4,11 @@ import { join } from "node:path";
 import type { Routing } from "../hub/routing.ts";
 import type { OmniRoute } from "../omniroute/client.ts";
 import { KEY_ENV, switchyardToml } from "./config.ts";
+import { stopOwnedProcess } from "../hub/child-process.ts";
 
 class GatewayDown extends Error {}
 
+
 export interface SidecarOptions {
   routing: Routing;
   omni: OmniRoute;
@@ -25,6 +27,9 @@ export interface SidecarOptions {
 export class Sidecar {
   private proc: ChildProcess | undefined;
   private starting: Promise<string | undefined> | undefined;
+  private generation = 0;
+  private stopped = false;
+  private stopping: Promise<void> | undefined;
   private off = "";
   /** The gateway URL the running sidecar was generated with; calls through it go there whatever the client probes later. */
   upstream: string | undefined;
@@ -37,7 +42,7 @@ export class Sidecar {
 
   /** Base URL to send chat calls to, or undefined when the hub should call OmniRoute directly. */
   endpoint(): Promise<string | undefined> {
-    if (this.off) return Promise.resolve(undefined);
+    if (this.off || this.stopped) return Promise.resolve(undefined);
     return (this.starting ??= this.start().catch((e: Error) => {
       // An unreachable gateway says nothing about Switchyard: this call goes direct, the next one tries the sidecar again.
       if (e instanceof GatewayDown) this.starting = undefined;
@@ -51,22 +56,34 @@ export class Sidecar {
     if (this.off) return;
     this.off = reason;
     this.opts.log(`switchyard: off, falling back to fixed_model on OmniRoute (${reason})`);
-    this.stop();
+    void this.stop().catch((e: Error) => this.opts.log(`switchyard: shutdown incomplete (${e.message})`));
   }
 
-  stop(): void {
-    this.proc?.kill();
-    this.proc = undefined;
+  async stop(): Promise<void> {
+    if (this.stopping) return this.stopping;
+    this.stopped = true;
+    ++this.generation;
+    const proc = this.proc;
+    // Preserve the historical synchronous file cleanup; the returned promise
+    // still represents the child process shutdown and must be awaited by the hub.
     rmSync(join(this.opts.stateDir, "switchyard.toml"), { force: true });
+    this.stopping = (async () => {
+      if (proc) await stopOwnedProcess(proc);
+      if (this.proc === proc) this.proc = undefined;
+    })();
+    return this.stopping;
   }
 
   private async start(): Promise<string | undefined> {
+    const generation = this.generation;
+    if (this.stopped) return undefined;
     const { routing, omni, stateDir, port, log } = this.opts;
     if (!Object.keys(routing.routes).length) throw new Error("routing.toml defines no routes");
     const bin = this.opts.bin ?? process.env.AGENTHUB_SWITCHYARD_BIN ?? "switchyard-server";
     const baseUrl = await omni.base();
     const key = omni.apiKey();
     if (!baseUrl || !key) throw new GatewayDown("no OmniRoute endpoint or key");
+    if (this.stopped || generation !== this.generation) return undefined;
     this.upstream = baseUrl;
 
     const file = join(stateDir, "switchyard.toml");
@@ -79,6 +96,11 @@ export class Sidecar {
 
     // Switchyard's default host is 0.0.0.0; the hub binds loopback only.
     const proc = spawn(bin, ["--config", file, "--host", "127.0.0.1", "--port", String(port)], { env, stdio: ["ignore", "ignore", "pipe"] });
+    if (this.stopped || generation !== this.generation) {
+      proc.kill("SIGTERM");
+      await stopOwnedProcess(proc);
+      return undefined;
+    }
     this.proc = proc;
     let exited = false;
     // Switchyard logs every request at INFO on stderr; only problems belong in hub.log.
@@ -91,12 +113,24 @@ export class Sidecar {
       if (this.proc === proc) this.disable(`exited with code ${code}`);
     });
     for (let i = 0; i < 100 && !exited; i++) {
+      if (this.stopped || generation !== this.generation) {
+        await stopOwnedProcess(proc);
+        if (this.proc === proc) this.proc = undefined;
+        return undefined;
+      }
       if (await fetch(`http://127.0.0.1:${port}/health`).then((r) => r.ok, () => false)) {
+        if (this.stopped || generation !== this.generation) {
+          await stopOwnedProcess(proc);
+          if (this.proc === proc) this.proc = undefined;
+          return undefined;
+        }
         log(`switchyard: up on 127.0.0.1:${port}, routes ${Object.keys(routing.routes).join(", ")}`);
         return `http://127.0.0.1:${port}/v1`;
       }
       await Bun.sleep(100);
     }
+    await stopOwnedProcess(proc);
+    if (this.proc === proc) this.proc = undefined;
     throw new Error(exited ? "exited during startup" : "not healthy within 10 s");
   }
 }