@staix/agent-hub 0.7.1 → 0.7.2

package/src/cli/main.ts

@@ -25,6 +25,7 @@ import { abortRecovery, createOperation, publicOperation, registeredProjects, ru
 import { makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.ts";
 import { recordTerminalLaunch } from "./terminal-recovery.ts";
 import { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
+import { setupOllamaModel } from "./models-setup.ts";
 
 import { backendLine, peerLine, type BackendRow, type PeerRow } from "./status-lines.ts";
 
@@ -37,7 +38,7 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub ui --all [--no-open]      open the unified project dashboard
   ahub ui --all --stop           stop only the dashboard manager
   ahub setup [--yes]            install or update the Claude Code channel plugin from this package, then run doctor
-  ahub init                     write .agenthub/config.json and the CLAUDE.md / AGENTS.md marker blocks
+  ahub init                     write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)
   ahub up [--unattended]        start the daemon for this directory
   ahub upgrade --to <version> [--dry-run] [--yes]   review and upgrade running projects
   ahub restart [--dry-run] [--yes]                 recover this project's runtime
@@ -46,7 +47,7 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub codex [args...]          start the Codex adapter and attach the TUI [--unattended]
   ahub kimi [--model <alias>]   start Kimi headless under ACP
   ahub pi [--mode headless|tui] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>]  start Pi
-  ahub models setup|status|start|stop  manage the pinned local MLX runtime
+  ahub models setup|status|start|stop  prepare or inspect local Ollama MLX (legacy stop is explicit)
   ahub local [--route <id> | --model <id>]
                                start the hub-native worker on the self-hosted models (routing.toml)
   ahub say [@peer ...] <text>   send as the console user (no @peer = broadcast); delivered at once,
@@ -70,7 +71,9 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub queue list [--peer <id>] [--json]       inspect durable deliveries
   ahub queue show <delivery-id>               inspect one delivery and revision
   ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text>
-  ahub status | logs [-f] | doctor | kill`;
+  ahub status | logs [-f] | doctor | kill
+  ahub doctor --orphans [--kill]  list registrations whose project root is gone; --kill stops their
+                               daemons (SIGTERM, then SIGKILL) only after the process identity checks out`;
 
 const argv = process.argv.slice(2);
 let selector: string | undefined;
@@ -163,6 +166,87 @@ async function printProjects(json = false) {
   if (!rows.length) console.log("No registered projects. Run ahub init in a project directory.");
 }
 
+/** Full command line of a live process, undefined once it is gone. */
+function processCommandLine(pid: number): string | undefined {
+  const res = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
+  if (res.status !== 0) return undefined;
+  return res.stdout.trim() || undefined;
+}
+
+/**
+ * A bare PID is never enough to kill on: it must belong to this project's hub daemon.
+ * The daemon argv is `<bun> .../cli/main.ts --project <root> daemon [--unattended]`, built by
+ * startProject from the registry row. ps joins argv with spaces and drops quoting, so the
+ * token after `--project` must equal the root exactly: a substring check would let an orphan
+ * rooted at /tmp/foo match a healthy hub launched with --project /tmp/foo2, and a root whose
+ * path contains a space simply can never be verified this way and is refused (issue #56).
+ */
+function hubDaemonCommand(pid: number, root: string): string | undefined {
+  const command = processCommandLine(pid);
+  if (!command) return undefined;
+  const tokens = command.split(/\s+/);
+  const project = tokens.indexOf("--project");
+  if (project < 1 || tokens[project + 1] !== root || tokens[project + 2] !== "daemon") return undefined;
+  return command;
+}
+
+/** Live PID candidates for a registration whose project root is gone: the claim, the manifest, the legacy pid file. */
+function orphanPids(project: Project): number[] {
+  const candidates = new Set<number>();
+  if (typeof project.pid === "number") candidates.add(project.pid);
+  const control = readControl(project.stateDir);
+  if (control && Number.isSafeInteger(control.pid)) candidates.add(control.pid!);
+  try {
+    const pid = Number(readFileSync(join(project.stateDir, "hub.pid"), "utf8").trim());
+    if (Number.isSafeInteger(pid) && pid > 0) candidates.add(pid);
+  } catch { /* no legacy pid file */ }
+  return [...candidates].filter((pid) => {
+    try { process.kill(pid, 0); return true; } catch { return false; }
+  });
+}
+
+const processGone = (pid: number): boolean => !processCommandLine(pid);
+
+async function killOrphan(pid: number, root: string): Promise<boolean> {
+  if (!hubDaemonCommand(pid, root)) {
+    console.log(`    pid ${pid}: command line is not this project's hub daemon; refusing to kill`);
+    return false;
+  }
+  try { process.kill(pid, "SIGTERM"); } catch { return true; } // exited meanwhile
+  const graceful = Date.now() + 3_000;
+  while (Date.now() < graceful && !processGone(pid)) await Bun.sleep(100);
+  if (processGone(pid)) { console.log(`    pid ${pid}: stopped with SIGTERM`); return true; }
+  // The PID may have been reused since SIGTERM; verify identity again before escalating.
+  if (!hubDaemonCommand(pid, root)) {
+    console.log(`    pid ${pid}: identity changed after SIGTERM; refusing SIGKILL`);
+    return false;
+  }
+  try { process.kill(pid, "SIGKILL"); } catch { return true; }
+  const hard = Date.now() + 2_000;
+  while (Date.now() < hard && !processGone(pid)) await Bun.sleep(100);
+  if (!processGone(pid)) {
+    console.log(`    pid ${pid}: still alive after SIGKILL`);
+    return false;
+  }
+  console.log(`    pid ${pid}: killed with SIGKILL`);
+  return true;
+}
+
+async function orphanDoctor(kill: boolean): Promise<void> {
+  const orphans = registeredProjects().filter((project) => !existsSync(project.root));
+  if (!orphans.length) return console.log("no orphaned hub registrations");
+  console.log("orphaned hub registrations (the project root is gone):");
+  let failed = 0;
+  for (const project of orphans) {
+    const pids = orphanPids(project);
+    console.log(`  ${project.id}  ${project.root}${pids.length ? `  live pid ${pids.join(", ")}` : "  no live process"}`);
+    if (!kill) continue;
+    for (const pid of pids) if (!(await killOrphan(pid, project.root))) failed++;
+  }
+  if (!kill) console.log("kill live orphans with `ahub doctor --orphans --kill`, then forget each row with `ahub projects remove <id>`");
+  if (failed) fail(`${failed} orphaned hub process(es) could not be stopped`);
+}
+
 function fail(message: string): never {
   console.error(`ahub: ${message}`);
   process.exit(1);
@@ -338,7 +422,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     assertLifecycleAvailable();
     const changed = init(cwd);
     registeredProject();
-    console.log(changed.length ? changed.map((p) => `wrote ${p}`).join("\n") : "already up to date");
+    console.log(changed.length ? changed.map((p) => `${existsSync(p) ? "wrote" : "removed"} ${p}`).join("\n") : "already up to date");
   },
 
   // Internal: the detached daemon process started by ahub up or the manager.
@@ -434,11 +518,16 @@ const commands: Record<string, () => Promise<void> | void> = {
     const configured = loadConfig(cwd).mlx;
     const runtimeDir = configured.runtimeDir ? resolve(cwd, configured.runtimeDir) : join(homedir(), ".agenthub", "runtimes", "mlx");
     const modelPath = configured.modelPath ? resolve(cwd, configured.modelPath) : join(homedir(), ".agenthub", "models", "qwen3-8b-mlx");
-    const mlxOptions = { ...configured, runtimeDir, modelPath };
+    const mlxOptions = configured.provider === "ollama" ? configured : { ...configured, runtimeDir, modelPath };
     if (action === "status") return console.log(JSON.stringify(await inspectMlx(mlxOptions), null, 2));
     if (action === "start") { const handle = await ensureMlx(mlxOptions); return console.log(JSON.stringify(handle.status(), null, 2)); }
     if (action === "stop") { await stopMlx(mlxOptions); return console.log("MLX stopped"); }
     if (action !== "setup") fail("usage: ahub models setup|status|start|stop");
+    if (configured.provider === "ollama") {
+      await setupOllamaModel(configured);
+      const handle = await ensureMlx(configured);
+      return console.log(JSON.stringify(handle.status(), null, 2));
+    }
     const python = join(runtimeDir, "bin", "python");
     const run = (argv: string[]) => { const result = spawnSync(argv[0]!, argv.slice(1), { cwd, stdio: "inherit" }); if (result.status !== 0) fail(`models setup failed: ${argv.join(" ")}`); };
     if (!existsSync(python)) run(["uv", "venv", "--python", "3.12", runtimeDir]);
@@ -634,6 +723,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   doctor: async () => {
+    if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"));
     const version = (bin: string) => {
       const res = spawnSync(bin, ["--version"], { encoding: "utf8" });
       return res.status === 0 ? res.stdout.trim().split("\n")[0]! : undefined;

package/src/cli/models-setup.ts

@@ -0,0 +1,39 @@
+import type { MlxOptions } from "../models/mlx.ts";
+import { validateOllamaOptions } from "../models/ollama.ts";
+
+/** Explicit setup only: inference never downloads models or starts a service. */
+export async function setupOllamaModel(options: MlxOptions): Promise<void> {
+  const config = validateOllamaOptions(options);
+  const source = options.sourceModel ?? "qwen3.5:4b-mlx";
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/.test(source) || !source.endsWith("-mlx") || source.includes("cloud") || source.includes("..") || source.includes("://")) {
+    throw new Error("Ollama sourceModel must be an explicit local MLX model tag");
+  }
+  if (source === config.model) throw new Error("sourceModel and the dedicated AgentHub model must differ");
+  const base = `http://${config.host === "::1" ? "[::1]" : config.host}:${config.port}`;
+  const post = async (path: string, body: unknown) => {
+    const response = await fetch(`${base}${path}`, {
+      method: "POST", redirect: "error", headers: { "content-type": "application/json" },
+      body: JSON.stringify(body), signal: AbortSignal.timeout(30 * 60_000),
+    });
+    if (!response.ok) throw new Error(`Ollama ${path} failed: HTTP ${response.status}`);
+    const result = await response.json() as { error?: string };
+    if (result.error) throw new Error(`Ollama ${path} failed: ${result.error.slice(0, 200)}`);
+    return result;
+  };
+  await post("/api/pull", { model: source, stream: false });
+  const sourceMetadata = await post("/api/show", { model: source }) as { remote_host?: unknown; remote_model?: unknown };
+  if (sourceMetadata.remote_host != null || sourceMetadata.remote_model != null) {
+    throw new Error("Ollama source model resolves to a remote/cloud model");
+  }
+  // Idempotent setup must never silently overwrite an existing model's recipe.
+  const existing = await fetch(`${base}/api/show`, {
+    method: "POST", redirect: "error", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ model: config.model }), signal: AbortSignal.timeout(10_000),
+  });
+  if (existing.ok) return; // The caller's inspect operation validates its context.
+  if (existing.status !== 404) throw new Error(`Ollama model inspection failed: HTTP ${existing.status}`);
+  await post("/api/create", {
+    model: config.model, from: source, stream: false,
+    parameters: { num_ctx: config.contextWindow, num_predict: config.maxTokens, temperature: 0.2 },
+  });
+}

package/src/cli/upgrade-runtime.ts

@@ -48,8 +48,16 @@ export async function inspectRecovery(project: Project): Promise<Inspection> {
   };
   let status = base.status;
   if (!status && legacySupported) {
-    const readback = await rpc(project, { t: "status" }, sourceProtocol);
-    status = readback.status;
+    try {
+      const readback = await rpc(project, { t: "status" }, sourceProtocol);
+      status = readback.status;
+    } catch {
+      // server.stop() runs before state-file removal, so a stopping hub briefly refuses
+      // connections with its manifest still on disk. Never infer stopped from a connect
+      // failure: callers poll again and see "stopped" once the manifest is gone.
+      return { state: "unavailable", peers: [], blockers: ["runtime changed during recovery inspection"],
+        ...(control?.instanceId ? { instanceId: control.instanceId } : {}), ...(control?.protocol ? { protocol: control.protocol } : {}) };
+    }
   }
   if (!status || !control) return { state: "unavailable", peers: [], blockers: ["authenticated source status unavailable"] };
   let response: any;

package/src/hub/bus.ts

@@ -194,10 +194,25 @@ export class Bus {
     return this.recoveryHeld;
   }
 
-  /** Wait until a hold has fenced condensation, steering and queue drains already in flight. */
-  async fenceRecovery(): Promise<void> {
+  /**
+   * Wait until a hold has fenced condensation, steering and queue drains already in flight.
+   * A drain stuck on a peer that never settles must not spin a core forever (issue #56):
+   * the wait backs off and gives up, leaving queues, in-flight deliveries and a hold the
+   * caller did not set exactly as they were.
+   */
+  async fenceRecovery(timeoutMs = 5_000): Promise<void> {
+    const heldBefore = this.recoveryHeld;
     this.recoveryHeld = true;
-    while (this.draining.size || this.steering || this.condensing) await Bun.sleep(0);
+    const deadline = Date.now() + timeoutMs;
+    let delay = 1;
+    while (this.draining.size || this.steering || this.condensing) {
+      if (Date.now() >= deadline) {
+        this.recoveryHeld = heldBefore;
+        throw new Error(`recovery fence timed out after ${timeoutMs} ms with ${this.draining.size + this.steering + this.condensing} deliveries still in flight; retry the operation`);
+      }
+      await Bun.sleep(delay);
+      delay = Math.min(delay * 2, 50);
+    }
   }
 
   /** A bounded, JSON-safe representation of queued work and retry/dedupe state. */

package/src/hub/daemon.ts

@@ -50,7 +50,7 @@ export interface HubConfig {
   inference: InferenceConfig;
   omniroute: OmniRouteConfig;
   pi: { enabled: boolean; auto_start: boolean; cmd: string[]; backend: "auto" | "dgx" | "mlx"; dgx_coding: string; dgx_fast: string; max_steps: number };
-  mlx: Pick<MlxOptions, "runtimeDir" | "modelPath" | "port" | "maxInputTokens" | "maxTokens">;
+  mlx: Pick<MlxOptions, "provider" | "host" | "runtimeDir" | "modelPath" | "port" | "model" | "sourceModel" | "contextWindow" | "maxInputTokens" | "maxTokens" | "maxConcurrency">;
   local: { deny: string[]; bash_network: boolean; max_steps: number; read_allow: string[] };
 }
 export const DEFAULT_CONFIG: HubConfig = {
@@ -66,7 +66,7 @@ export const DEFAULT_CONFIG: HubConfig = {
   inference: DEFAULT_INFERENCE,
   omniroute: DEFAULT_OMNIROUTE,
   pi: { enabled: false, auto_start: false, cmd: ["pi"], backend: "auto", dgx_coding: "coding", dgx_fast: "fast", max_steps: 30 },
-  mlx: { maxInputTokens: 16_000, maxTokens: 2048 },
+  mlx: { provider: "ollama", model: "agenthub-fast-mlx:4b-8k", sourceModel: "qwen3.5:4b-mlx", contextWindow: 8192, maxInputTokens: 6000, maxTokens: 2048, maxConcurrency: 1 },
   local: { deny: [], bash_network: false, max_steps: 30, read_allow: [] },
 };
 
@@ -79,7 +79,12 @@ const PEER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 export function loadConfig(cwd: string): HubConfig {
   try {
     const file = JSON.parse(readFileSync(join(cwd, ".agenthub", "config.json"), "utf8"));
-    const mlx = { ...DEFAULT_CONFIG.mlx, ...file.mlx };
+    if (file.mlx != null && (typeof file.mlx !== "object" || Array.isArray(file.mlx))) throw new Error("mlx configuration must be an object");
+    if (file.mlx?.provider !== undefined && !["ollama", "legacy"].includes(file.mlx.provider)) throw new Error("mlx.provider must be ollama or legacy");
+    if (file.mlx?.provider === undefined && (file.mlx?.modelPath || file.mlx?.runtimeDir || file.mlx?.bin || file.mlx?.port)) {
+      throw new Error("legacy MLX configuration requires explicit mlx.provider=legacy; migrate to provider=ollama to avoid Python serving");
+    }
+    const mlx = { ...(file.mlx?.provider === "legacy" ? { provider: "legacy" as const, maxInputTokens: 16_000, maxTokens: 2048 } : DEFAULT_CONFIG.mlx), ...file.mlx };
     if (typeof mlx.runtimeDir === "string") mlx.runtimeDir = resolve(cwd, mlx.runtimeDir);
     if (typeof mlx.modelPath === "string") mlx.modelPath = resolve(cwd, mlx.modelPath);
     return {
@@ -94,8 +99,9 @@ export function loadConfig(cwd: string): HubConfig {
       pi: { ...DEFAULT_CONFIG.pi, ...file.pi },
       mlx,
     };
-  } catch {
-    return DEFAULT_CONFIG;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return DEFAULT_CONFIG;
+    throw error;
   }
 }
 
@@ -114,6 +120,10 @@ export interface DaemonOptions {
   /** Auto-approve ACP permission requests with the agent's allow_once option. */
   unattended?: boolean;
   permissionTimeoutMs?: number;
+  /** Called once when shutdown begins, however it was triggered; the lifecycle uses it to arm a hard deadline. */
+  onShutdownStart?: () => void;
+  /** How often the daemon checks that its project root and state dir still exist. Tests shrink this. */
+  orphanWatchMs?: number;
 }
 
 interface Client {
@@ -172,7 +182,8 @@ export async function startDaemon(opts: DaemonOptions) {
   const config = opts.config ?? loadConfig(opts.cwd);
   mkdirSync(opts.stateDir, { recursive: true });
   const logFile = join(opts.stateDir, "hub.log");
-  const log = (line: string) => appendFileSync(logFile, `${new Date().toISOString()} ${line}\n`);
+  // The state dir can vanish under a running hub (issue #56): a log line must never take a handler down with it.
+  const log = (line: string) => { try { appendFileSync(logFile, `${new Date().toISOString()} ${line}\n`); } catch { /* the state dir is gone; the watchdog is stopping the hub */ } };
 
   // Any local web page can open a WebSocket to a loopback port, so the control link needs a secret.
   // The file is written only after the port is bound: a second daemon that loses the bind must not clobber it.
@@ -516,9 +527,11 @@ export async function startDaemon(opts: DaemonOptions) {
     ...(recoveryOperationId ? { recovery: { operationId: recoveryOperationId, phase: recoveryPhase, ready: recoveryReady() } } : {}),
   });
   const writeStatus = () => {
-    const file = join(opts.stateDir, "status.json"); // clients parse this on every connect: replace it atomically
-    writeFileSync(`${file}.${instanceId}.tmp`, `${JSON.stringify(status(), null, 2)}\n`);
-    renameSync(`${file}.${instanceId}.tmp`, file);
+    try {
+      const file = join(opts.stateDir, "status.json"); // clients parse this on every connect: replace it atomically
+      writeFileSync(`${file}.${instanceId}.tmp`, `${JSON.stringify(status(), null, 2)}\n`);
+      renameSync(`${file}.${instanceId}.tmp`, file);
+    } catch { /* the state dir is gone; the watchdog is stopping the hub (issue #56) */ }
   };
 
   // A queue change is not a bus event: without this, status.json reports the queue as it was before the last
@@ -702,7 +715,7 @@ export async function startDaemon(opts: DaemonOptions) {
         cwd: opts.cwd, stateDir: opts.stateDir, cmd: config.pi.cmd, mode, backend,
         model: args.model,
         sessionId: args.sessionId, sessionFile: args.sessionFile,
-        relay: { url: modelRelay.url, token: modelRelay.token, models: modelRelay.models.map((id) => ({ id, contextWindow: id.startsWith("mlx/") ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens, maxTokens: id.startsWith("mlx/") ? (config.mlx.maxTokens ?? 2048) : 8192 })) },
+        relay: { url: modelRelay.url, token: modelRelay.token, models: modelRelay.models.map((id) => ({ id, contextWindow: id.startsWith("mlx/") ? Math.min(routing.pi.mlx_max_context_tokens, config.mlx.provider === "ollama" ? (config.mlx.contextWindow ?? 8192) : routing.pi.mlx_max_context_tokens) : routing.pi.dgx_max_context_tokens, maxTokens: id.startsWith("mlx/") ? (config.mlx.maxTokens ?? 2048) : 8192 })) },
         tools: [...TOOL_SCHEMAS.map((t) => t.function), ...TASK_TOOLS.map((t) => ({ name: t.name, description: t.description, parameters: t.inputSchema }))],
         executeTool: async (name, raw, callId, sessionId) => {
           if (stopping || (recoveryActive() && recoveryPhase !== "preparing")) return "error: recovery is holding tool effects";
@@ -1082,7 +1095,7 @@ export async function startDaemon(opts: DaemonOptions) {
       }
       case "recovery":
         if (c.role !== "console") return void reply(recoveryError("recovery is a console command"));
-        void recoveryOp(msg).then(reply, () => reply(recoveryError("recovery operation failed")));
+        void recoveryOp(msg).then(reply, (error) => reply(recoveryError((error as Error)?.message ?? "recovery operation failed")));
         return;
       case "send": {
         if (recoveryActive()) return void reply({ t: "sent", ok: false, error: "recovery is holding new deliveries" });
@@ -1214,6 +1227,7 @@ export async function startDaemon(opts: DaemonOptions) {
   let shutdown: Promise<void> | undefined;
   function stop(): Promise<void> {
     if (shutdown) return shutdown;
+    opts.onShutdownStart?.();
     shutdown = stopOnce().catch((error) => { shutdown = undefined; throw error; });
     return shutdown;
   }
@@ -1225,26 +1239,44 @@ export async function startDaemon(opts: DaemonOptions) {
     for (const i of intervals) clearInterval(i);
     for (const done of checkpointWaits.values()) done(undefined);
     for (const p of permissions.values()) p.done(undefined);
-    // A peer can still be inside memory recall or its native handshake when kill arrives.
-    // Drain those starts before taking the final owned-process snapshot.
-    await Promise.allSettled([...starting.values()]);
-    const exits = await Promise.allSettled([...bus.peers.values()].map((p) => p.stop()).concat(sidecar ? [sidecar.stop()] : []));
-    const failed = exits.find((r) => r.status === "rejected");
-    if (failed?.status === "rejected") throw failed.reason;
-    await modelRelay?.close();
-    await piReceipts?.close();
-    budget.close();
-    board.close();
-    server.stop(true);
-    bus.closeJournal();
     try {
-      const current = JSON.parse(readFileSync(join(opts.stateDir, "status.json"), "utf8"));
-      if (current.instanceId === instanceId) for (const f of ["hub.pid", "status.json", "control-token"]) rmSync(join(opts.stateDir, f), { force: true });
-    } catch { /* another owner or no published state: never remove it */ }
-    onStop?.();
+      // A peer can still be inside memory recall or its native handshake when kill arrives.
+      // Drain those starts before taking the final owned-process snapshot.
+      await Promise.allSettled([...starting.values()]);
+      const exits = await Promise.allSettled([...bus.peers.values()].map((p) => p.stop()).concat(sidecar ? [sidecar.stop()] : []));
+      // A peer whose stop rejects must not strand the daemon (issue #56): its failure is
+      // logged and shutdown finishes anyway, or the process ignores SIGTERM forever.
+      for (const exit of exits) if (exit.status === "rejected") log(`peer stop failed during shutdown: ${(exit.reason as Error)?.message ?? exit.reason}`);
+      await modelRelay?.close();
+      await piReceipts?.close();
+      budget.close();
+      board.close();
+      server.stop(true);
+      try { bus.closeJournal(); } catch { /* the state dir is gone; the journal went with it */ }
+    } finally {
+      // State removal and the stopped notification run no matter what failed above,
+      // or daemon.stopped never resolves and the daemon outlives its project.
+      try {
+        const current = JSON.parse(readFileSync(join(opts.stateDir, "status.json"), "utf8"));
+        if (current.instanceId === instanceId) for (const f of ["hub.pid", "status.json", "control-token"]) rmSync(join(opts.stateDir, f), { force: true });
+      } catch { /* another owner or no published state: never remove it */ }
+      onStop?.();
+    }
   }
   let onStop: (() => void) | undefined;
 
+  // A hub whose project root or state dir vanished has nothing left to serve: the test suite
+  // rmSync's the temp dir of a leaked daemon, and operators delete projects (issue #56).
+  // The check is slow and unref'd, so it never keeps a daemon alive on its own.
+  const orphanWatch = setInterval(() => {
+    if (stopping) return;
+    if (existsSync(opts.cwd) && existsSync(opts.stateDir)) return;
+    log("project root or state directory is gone; shutting down");
+    void stop().catch((error) => console.error(`shutdown incomplete: ${(error as Error).message}`));
+  }, opts.orphanWatchMs ?? 10_000);
+  orphanWatch.unref?.();
+  intervals.push(orphanWatch);
+
   const tokenFile = join(opts.stateDir, "control-token");
   writeFileSync(tokenFile, token, { mode: 0o600 });
   chmodSync(tokenFile, 0o600);

package/src/hub/lifecycle.ts

@@ -91,6 +91,19 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
   const instanceId = randomUUID();
   let claimed = false;
   let daemon: Awaited<ReturnType<typeof startDaemon>> | undefined;
+  // ponytail: shutdown is bounded as a whole, not per peer; a peer whose stop never settles
+  // escapes only through this process-level deadline (issue #56). 15 s leaves the claude-mem
+  // session-end work awaited in stop() its chance. Upgrade path: per-peer stop deadlines.
+  const SHUTDOWN_DEADLINE_MS = 15_000;
+  let forcedExit: ReturnType<typeof setTimeout> | undefined;
+  const onShutdownStart = () => {
+    if (forcedExit) return;
+    forcedExit = setTimeout(() => {
+      console.error(`hub shutdown did not finish within ${SHUTDOWN_DEADLINE_MS / 1000} s; exiting anyway`);
+      process.exit(1);
+    }, SHUTDOWN_DEADLINE_MS);
+    forcedExit.unref();
+  };
   try {
     const before = await inspectProject(registry.get(project.id) ?? project);
     if (before.state === "running" || before.state === "starting") return;
@@ -103,7 +116,7 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
         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 });
+            switchyardPort: base + SWITCHYARD, unattended, onShutdownStart });
           break;
         } catch (error) {
           if ((error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error;
@@ -116,7 +129,7 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
     try { await daemon.stopped; }
-    finally { process.off("SIGINT", stop); process.off("SIGTERM", stop); }
+    finally { if (forcedExit) clearTimeout(forcedExit); process.off("SIGINT", stop); process.off("SIGTERM", stop); }
   } finally {
     if (claimed) registry.release(project.id, instanceId);
     registry.close();

package/src/hub/manager.ts

@@ -16,7 +16,7 @@ export type Lifecycle = {
   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 };
+export type ManagerOptions = { registry?: Registry; lifecycle?: Lifecycle; home?: string; cli?: string; orphanWatchMs?: number };
 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 }>();
@@ -87,15 +87,20 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
   let server: ReturnType<typeof Bun.serve> | undefined;
   let dashboard: ReturnType<typeof startDashboard> | undefined;
   let stopping = false;
+  let orphanWatch: ReturnType<typeof setInterval> | undefined;
   let resolveStopped!: () => void;
   const stopped = new Promise<void>((resolve) => { resolveStopped = resolve; });
   const cleanup = () => {
+    if (orphanWatch) clearInterval(orphanWatch);
     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;
+      // The state dir may already be gone (the orphan watchdog path, issue #56): a DELETE on an
+      // unlinked database fails with SQLITE_IOERR_VNODE on macOS, and the claim went with the file.
+      try { owner.query("DELETE FROM owner WHERE slot = 1 AND instance_id = ? AND pid = ?").run(instanceId, process.pid); } catch { /* claim file already gone */ }
+      try { owner.close(); } catch { /* already unlinked */ }
+      owner = undefined;
     }
     if (ownsRegistry) registry.close();
   };
@@ -169,6 +174,13 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
     const temp = `${f.status}.${instanceId}.tmp`;
     writeFileSync(temp, JSON.stringify({ port: server.port, protocol: PROTOCOL, instanceId, pid: process.pid }));
     renameSync(temp, f.status);
+    // The manager outlives whoever opened it; a deleted AGENTHUB_HOME (a test suite's temp
+    // home, issue #56) must not leave it serving a registry that no longer exists.
+    orphanWatch = setInterval(() => {
+      if (stopping || existsSync(f.dir)) return;
+      void stop();
+    }, options.orphanWatchMs ?? 10_000);
+    orphanWatch.unref?.();
     const handle = { stop, stopped };
     active.set(home, { handle, issue: () => dashboard!.issue() });
     return handle;

package/src/models/mlx.ts

@@ -9,8 +9,11 @@ import { Database } from "bun:sqlite";
 export type MlxState = "disabled" | "starting" | "ready" | "stopped" | "foreign" | "error";
 
 export interface MlxOptions {
+  provider?: "legacy" | "ollama";
   runtimeDir?: string;
   modelPath?: string;
+  model?: string;
+  sourceModel?: string;
   bin?: string;
   host?: string;
   port?: number;
@@ -21,6 +24,7 @@ export interface MlxOptions {
   spawn?: typeof spawn;
   health?: (url: string, signal: AbortSignal) => Promise<boolean>;
   processInfo?: (pid: number) => ProcessSignature | undefined;
+  contextWindow?: number;
 }
 
 export interface MlxStatus {
@@ -32,6 +36,12 @@ export interface MlxStatus {
   maxConcurrency: number;
   active: number;
   lastError?: string;
+  provider?: "legacy" | "ollama";
+  modelAvailable?: boolean;
+  modelResident?: boolean;
+  expiresAt?: string | null;
+  contextWindow?: number;
+  maxTokens?: number;
 }
 
 export interface MlxHandle {
@@ -54,7 +64,7 @@ interface OwnerRecord {
   processStart: string;
 }
 
-interface ProcessSignature {
+export interface ProcessSignature {
   command: string;
   start: string;
 }
@@ -227,7 +237,7 @@ function claimGenerationSlot(db: Database, slot: number, readInfo: (pid: number)
   };
 }
 
-async function acquireGeneration(runtimeDir: string, maxConcurrency: number, signal?: AbortSignal, readInfo: (pid: number) => ProcessSignature | undefined = processInfo): Promise<() => void> {
+export async function acquireGeneration(runtimeDir: string, maxConcurrency: number, signal?: AbortSignal, readInfo: (pid: number) => ProcessSignature | undefined = processInfo): Promise<() => void> {
   if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1) throw new Error("MLX maxConcurrency must be a positive integer");
   if (signal?.aborted) throw new Error("MLX generation acquisition cancelled");
   const deadline = Date.now() + 120_000;
@@ -304,6 +314,10 @@ function argsFor(options: Required<Pick<MlxOptions, "modelPath" | "host" | "port
 }
 
 export async function inspectMlx(options: MlxOptions = {}): Promise<MlxStatus> {
+  if (options.provider === "ollama") {
+    const { inspectOllama } = await import("./ollama.ts");
+    return inspectOllama(options);
+  }
   const runtimeDir = options.runtimeDir ?? DEFAULT_RUNTIME_DIR;
   const modelPath = options.modelPath ?? DEFAULT_MODEL_PATH;
   const host = options.host ?? "127.0.0.1";
@@ -323,6 +337,10 @@ export async function inspectMlx(options: MlxOptions = {}): Promise<MlxStatus> {
 }
 
 export async function ensureMlx(options: MlxOptions = {}): Promise<MlxHandle> {
+  if (options.provider === "ollama") {
+    const { ensureOllama } = await import("./ollama.ts");
+    return ensureOllama(options);
+  }
   const runtimeDir = options.runtimeDir ?? DEFAULT_RUNTIME_DIR;
   const modelPath = options.modelPath ?? DEFAULT_MODEL_PATH;
   const bin = options.bin ?? join(runtimeDir, "bin", "mlx_lm.server");
@@ -405,6 +423,10 @@ export async function ensureMlx(options: MlxOptions = {}): Promise<MlxHandle> {
 }
 
 export async function stopMlx(options: MlxOptions = {}): Promise<void> {
+  if (options.provider === "ollama") {
+    const { stopOllama } = await import("./ollama.ts");
+    return stopOllama(options);
+  }
   const runtimeDir = options.runtimeDir ?? DEFAULT_RUNTIME_DIR;
   const owner = readOwner(runtimeDir);
   if (!owner) return;