@staix/agent-hub 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.0
+
+- Independent repository and worktree hubs with canonical project selection, `--project <path|id>`, `projects`, and `status --all` (#19).
+- Transactional machine-wide project/port registration, concurrent startup claims, authenticated instance checks and owned shutdown; legacy port allocations are imported without resetting them.
+- `ahub ui --all` opens a separate local manager for project selection, hub start/stop and existing dashboard actions. `ahub ui --all --stop` leaves project hubs running.
+- Native memory aliases stay compatible with claude-mem, including worktree parent/composite names. Shared aliases are indicated in the manager.
+- A second Codex TUI cannot take over an existing hub connection. Owned child shutdown is awaited before runtime ownership is released.
+- Control protocol 7: stop old hubs with their matching CLI before upgrading; refresh the channel bundle with `ahub setup`, then restart hubs and agent sessions. No automatic restarts or account configuration changes.
+
+## 0.3.2
+
+- The channel plugin no longer fights a second session attached as the same peer: the replaced one stays detached and its tools say so, instead of taking the peer back every second (#16).
+- The plugin MCP server exits when its host goes away, and stops retrying a hub that refused it (wire version, token, peer id), reporting the hub's reason (#17).
+- After upgrading, run `ahub setup` to refresh the Claude plugin and restart agent sessions; stale `server.js` processes from earlier versions have to be ended by hand once.
+
 ## 0.3.1
 
 - Hub task, review and budget events are distinguished from reference-only presence/recall in agent instructions and rendered message kinds, including mixed Claude digests.

package/README.md

@@ -1,10 +1,10 @@
 # agent-hub
 
 Native multi-agent hub for one developer's machine: Claude Code, Codex, Kimi Code and a
-hub-owned local-LLM worker collaborate as peers in one project directory, with
+hub-owned local-LLM worker collaborate as peers in independent project directories, with
 task-aware model routing (Switchyard) in front of a self-hosted gateway (OmniRoute).
 
-Status: 0.3.1. All six milestones of the design spec are implemented; the [smoke checklist](docs/smoke.md)
+Status: 0.4.0. All six milestones of the design spec are implemented; the [smoke checklist](docs/smoke.md)
 says what has and has not been verified against real agents.
 
 ## Start here
@@ -22,7 +22,7 @@ cd <your project> && ahub init && ahub up && ahub tail
 Or install the same version from GitHub:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.3.1 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.4.0 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.
@@ -69,3 +69,51 @@ peers, and answer approvals. Budget pauses still require the terminal override.
 Private envelopes and PII tasks stay redacted. Local-worker tool details and
 allow decisions stay in `ahub tail` / `ahub permit`; the page can deny them.
 No dashboard port is opened until requested. See [the session security model](docs/security.md#local-dashboard-sessions-issue-6).
+
+
+## Multiple projects and worktrees
+
+Version 0.4.0 adds one independent hub per repository or Git worktree.
+Subdirectory commands resolve to that project; symlink aliases resolve to the same
+hub. Explicit selection works from any directory:
+
+```bash
+ahub --project /path/to/project-a init
+ahub --project /path/to/project-b init
+ahub --project /path/to/project-a up
+ahub --project /path/to/project-b up
+ahub projects
+ahub status --all
+ahub --project /path/to/project-a codex
+ahub ui --all
+```
+
+The unified dashboard lists registered roots and opens their boards, streams,
+messages, approvals and budgets. It can start hubs and stop a selected hub after
+confirmation. Launch Claude/Codex TUIs from a terminal. The manager stays available
+when a project stops; `ahub ui --all --stop` stops only the manager. Existing
+`ahub ui` still opens the current project's dashboard.
+
+`ahub projects --json` returns machine-readable live status. Use a listed ID or a
+path with `--project`; the selector must precede the command. `ahub projects remove
+<id>` forgets a stopped registration without deleting project data. A moved root
+gets a new registration. Missing roots remain visible until removed.
+
+Runtime state stays in each project's `.agenthub/state/`. The machine registry is
+`~/.agenthub/registry.db`; existing `ports.json` allocations are imported once.
+`AGENTHUB_HOME` selects an isolated machine registry (also used by tests). An
+inherited state directory from a different project cannot redirect a new CLI
+invocation. Explicit custom state requires a matching project marker or the
+initialization pair `AGENTHUB_PROJECT_DIR` / `AGENTHUB_STATE_DIR`.
+
+Manager-started hubs use attended mode and project configuration, including
+credential-file references. They do not inherit the launching project's gateway
+URL/key overrides. Native memory remains shared according to claude-mem aliases;
+worktrees recall their parent and composite identity. A shared-alias notice does
+not mean that task boards or agent sessions are shared. Provider quota readings
+may describe the same account and should not be added across projects.
+
+Before upgrading to protocol 7, stop existing hubs with their matching CLI, then
+update the package/plugin and restart the desired projects and agent sessions.
+Incompatible or unverified processes are shown explicitly and are never killed by
+PID-name matching. See the [multi-project specification](docs/specs/2026-09-19-multi-project-design.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code and a local worker as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -15529,21 +15529,108 @@ class StdioServerTransport {
 }
 
 // src/adapters/claude-channel.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
+
+// src/hub/control-client.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
 
+// src/hub/project.ts
+import { existsSync, lstatSync, readFileSync, realpathSync } from "fs";
+import { basename, dirname, isAbsolute, join, resolve } from "path";
+import { spawnSync } from "child_process";
+var canonical = (path) => {
+  const absolute = resolve(path);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    const parent = dirname(absolute);
+    return parent === absolute ? absolute : join(canonical(parent), basename(absolute));
+  }
+};
+function gitRoot(dir) {
+  const result = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  if (result.status !== 0)
+    return;
+  const root = result.stdout.trim();
+  return root ? canonical(root) : undefined;
+}
+function hasConfig(dir) {
+  return existsSync(join(dir, ".agenthub", "config.json"));
+}
+function projectRoot(cwd) {
+  const input = isAbsolute(cwd) ? cwd : resolve(cwd);
+  let dir;
+  try {
+    dir = canonical(input);
+    if (!lstatSync(dir).isDirectory())
+      throw new Error(`${cwd} is not a directory`);
+  } catch (error2) {
+    throw new Error(`cannot resolve project directory ${cwd}: ${error2.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) {
+  let current = dir;
+  while (dirname(current) !== current)
+    current = dirname(current);
+  return current;
+}
+function stateMarker(stateDir) {
+  for (const file of [join(stateDir, "project.json"), join(stateDir, "status.json")]) {
+    try {
+      const value = JSON.parse(readFileSync(file, "utf8"));
+      const root = value.root ?? value.cwd;
+      if (typeof root === "string")
+        return canonical(root);
+    } catch {}
+  }
+  return;
+}
+function projectContext(cwd, env = process.env) {
+  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 };
+  if (!recorded && declared && canonical(declared) === root)
+    return { root, stateDir };
+  return { root, stateDir: canonical(join(root, ".agenthub", "state")) };
+}
+
 // src/hub/control-client.ts
-import { readFileSync } from "fs";
-import { join } from "path";
 function stateDirFor(cwd) {
-  return process.env.AGENTHUB_STATE_DIR ?? join(cwd, ".agenthub", "state");
+  return projectContext(cwd).stateDir;
 }
-var PROTOCOL = 6;
+var PROTOCOL = 7;
 function readControl(stateDir) {
   try {
-    const status = JSON.parse(readFileSync(join(stateDir, "status.json"), "utf8"));
-    const token = readFileSync(join(stateDir, "control-token"), "utf8").trim();
-    return { url: `ws://127.0.0.1:${status.controlPort}`, token };
+    const status = JSON.parse(readFileSync2(join2(stateDir, "status.json"), "utf8"));
+    const token = readFileSync2(join2(stateDir, "control-token"), "utf8").trim();
+    if (!Number.isInteger(status.controlPort) || status.controlPort < 1 || status.controlPort > 65535 || !token)
+      return;
+    return {
+      url: `ws://127.0.0.1:${status.controlPort}`,
+      token,
+      projectId: status.projectId,
+      instanceId: status.instanceId,
+      cwd: status.cwd,
+      protocol: status.protocol,
+      pid: status.pid
+    };
   } catch {
     return;
   }
@@ -15558,37 +15645,72 @@ class ControlClient {
   constructor(ws) {
     this.ws = ws;
   }
-  static connect(stateDir, hello) {
+  static connect(stateDir, hello, timeoutMs = 3000) {
     const control = readControl(stateDir);
     if (!control)
       return Promise.reject(new Error(`no hub running for ${stateDir} (run: ahub up)`));
-    return new Promise((resolve, reject) => {
+    if (control.protocol !== undefined && control.protocol !== PROTOCOL) {
+      return Promise.reject(Object.assign(new Error(`wire version mismatch: hub speaks ${control.protocol}, CLI speaks ${PROTOCOL}; stop it with its matching CLI, then upgrade and restart`), { code: 4426 }));
+    }
+    if (hello.projectId && hello.projectId !== control.projectId || hello.instanceId && hello.instanceId !== control.instanceId || hello.projectRoot && hello.projectRoot !== control.cwd) {
+      return Promise.reject(Object.assign(new Error("hub project or instance does not match the selected project"), { code: 4404 }));
+    }
+    const expected = {
+      projectId: hello.projectId ?? control.projectId,
+      instanceId: hello.instanceId ?? control.instanceId,
+      projectRoot: hello.projectRoot ?? control.cwd
+    };
+    return new Promise((resolve2, reject) => {
       const ws = new WebSocket(control.url);
       const client = new ControlClient(ws);
-      ws.onerror = () => reject(new Error(`cannot reach hub at ${control.url}`));
-      ws.onclose = () => {
-        reject(new Error("hub closed the connection (stale token?)"));
+      const timer = setTimeout(() => refuse(new Error(`hub connection timed out at ${control.url}`)), timeoutMs);
+      const refuse = (error2) => {
+        clearTimeout(timer);
+        reject(error2);
+        ws.close();
+      };
+      ws.onerror = () => refuse(new Error(`cannot reach hub at ${control.url}`));
+      ws.onclose = (ev) => {
+        clearTimeout(timer);
+        reject(Object.assign(new Error(`hub closed the connection: ${ev.reason || "stale token?"}`), { code: ev.code }));
         for (const done of client.pending.values())
           done({ ok: false, error: "hub connection closed" });
         client.pending.clear();
-        client.onClose();
+        client.onClose(ev.code, ev.reason);
       };
       ws.onmessage = (ev) => {
-        const msg = JSON.parse(String(ev.data));
+        let msg;
+        try {
+          msg = JSON.parse(String(ev.data));
+        } catch {
+          return refuse(new Error("invalid hub response"));
+        }
+        if (!msg || typeof msg !== "object" || Array.isArray(msg))
+          return refuse(new Error("invalid hub response"));
         const done = msg.rid !== undefined ? client.pending.get(msg.rid) : undefined;
         if (!done)
           return client.onPush(msg);
         client.pending.delete(msg.rid);
         done(msg);
       };
-      ws.onopen = () => void client.request({ t: "hello", v: PROTOCOL, token: control.token, ...hello }).then(() => resolve(client));
+      ws.onopen = () => void client.request({ t: "hello", v: PROTOCOL, token: control.token, ...hello, ...expected }, timeoutMs).then((reply) => {
+        if (reply.t !== "welcome" || reply.ok === false)
+          return refuse(new Error(reply.error ?? "hub refused handshake"));
+        if (expected.projectId && reply.projectId !== expected.projectId || expected.instanceId && reply.instanceId !== expected.instanceId || expected.projectRoot && reply.cwd !== expected.projectRoot) {
+          return refuse(Object.assign(new Error("connected hub has a different project or instance"), { code: 4404 }));
+        }
+        clearTimeout(timer);
+        resolve2(client);
+      });
     });
   }
-  request(msg, timeoutMs) {
+  request(msg, timeoutMs = 30000) {
+    if (this.ws.readyState !== WebSocket.OPEN)
+      return Promise.resolve({ ok: false, error: "hub connection is not open" });
     const rid = this.nextRid++;
-    return new Promise((resolve) => {
-      const timer = timeoutMs ? setTimeout(() => (this.pending.delete(rid), resolve({ ok: false, error: `no answer from the hub within ${Math.round(timeoutMs / 1000)} s` })), timeoutMs) : undefined;
-      this.pending.set(rid, (reply) => (clearTimeout(timer), resolve(reply)));
+    return new Promise((resolve2) => {
+      const timer = timeoutMs ? setTimeout(() => (this.pending.delete(rid), resolve2({ ok: false, error: `no answer from the hub within ${Math.round(timeoutMs / 1000)} s` })), timeoutMs) : undefined;
+      this.pending.set(rid, (reply) => (clearTimeout(timer), resolve2(reply)));
       this.ws.send(JSON.stringify({ ...msg, rid }));
     });
   }
@@ -15602,7 +15724,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.3.1",
+  version: "0.4.0",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code and a local worker as peers in one project",
   license: "MIT",
   type: "module",
@@ -15702,17 +15824,26 @@ ${sanitize(env.body)}`;
 }
 
 // src/adapters/claude-channel.ts
-var stateDir = stateDirFor(process.cwd());
+var stateDir = process.env.AGENTHUB_STATE_DIR ?? stateDirFor(process.cwd());
+var projectRoot2 = process.env.AGENTHUB_PROJECT_DIR ?? process.cwd();
 var peerId = process.env.AGENTHUB_PEER_ID ?? "claude";
 var toolsOnly = process.env.AGENTHUB_MODE === "tools";
 function roles() {
   try {
-    return { ...DEFAULT_ROLES, ...JSON.parse(readFileSync2(join2(process.cwd(), ".agenthub", "config.json"), "utf8")).roles };
+    return { ...DEFAULT_ROLES, ...JSON.parse(readFileSync3(join3(projectRoot2, ".agenthub", "config.json"), "utf8")).roles };
   } catch {
     return DEFAULT_ROLES;
   }
 }
 var MAX_RECONNECT_DELAY_MS = 30000;
+var TERMINAL_CLOSES = {
+  4000: `another session attached to the hub as "${peerId}"; this one is detached (restart it to take the peer back)`,
+  4401: "the hub refused the control token",
+  4404: "the hub belongs to a different project or instance; restart this session from the intended project",
+  4403: `the hub refused the peer id "${peerId}" (reserved or malformed)`,
+  4409: `the peer id "${peerId}" is taken by a hub-managed adapter`,
+  4426: "wire version mismatch with the running hub: update the agent-hub plugin (ahub setup) and restart this session"
+};
 var INBOX_CAP = 200;
 var INSTRUCTIONS = [
   "agent-hub connects you to other coding agents working in this project (for example codex, kimi, local) and to the hub console user.",
@@ -15734,6 +15865,8 @@ var text = (s) => ({ content: [{ type: "text", text: s }] });
 var server = new Server({ name: "agent-hub", version: VERSION }, toolsOnly ? { capabilities: { tools: {} }, instructions: TOOLS_INSTRUCTIONS } : { capabilities: { experimental: { "claude/channel": {} }, tools: {} }, instructions: INSTRUCTIONS });
 var inbox = [];
 var hub;
+var detached;
+var offline = () => detached ?? "hub is not running for this project (start it with: ahub up).";
 async function push(envs) {
   const parent = replyParent(envs);
   const single = envs.length === 1;
@@ -15761,19 +15894,29 @@ ${sanitize(e.body)}`).join(`
 }
 async function connectLoop() {
   for (let attempt = 0;; attempt++) {
+    let code;
     try {
-      const client = await ControlClient.connect(stateDir, { role: toolsOnly ? "tools" : "peer", peer: peerId });
+      const client = await ControlClient.connect(stateDir, {
+        role: toolsOnly ? "tools" : "peer",
+        peer: peerId,
+        ...process.env.AGENTHUB_PROJECT_DIR ? { projectRoot: projectRoot2 } : {}
+      });
       client.onPush = (msg) => msg.t === "deliver" && void push(msg.envs ?? [msg.env]);
       hub = client;
       attempt = -1;
       log(`connected to hub as "${peerId}"`);
-      await new Promise((r) => client.onClose = r);
+      code = await new Promise((r) => client.onClose = r);
       hub = undefined;
       log("hub connection lost");
     } catch (e) {
+      code = e.code;
       if (attempt === 0)
         log(e.message);
     }
+    if (code !== undefined && TERMINAL_CLOSES[code]) {
+      detached = TERMINAL_CLOSES[code];
+      return log(`stopped reconnecting: ${detached}`);
+    }
     await new Promise((r) => setTimeout(r, Math.min(1000 * 2 ** Math.max(attempt, 0), MAX_RECONNECT_DELAY_MS)));
   }
 }
@@ -15814,7 +15957,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   if (name === "hub_send") {
     const { text: body, to, reply_to } = args ?? {};
     if (!hub)
-      return text("hub is not running for this project (start it with: ahub up). Message not sent.");
+      return text(`${offline()} Message not sent.`);
     const res = await hub.request({ t: "send", body, to, reply_to });
     if (!res.ok)
       return text(`not sent: ${res.error}`);
@@ -15824,11 +15967,13 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   }
   if (TASK_TOOL_NAMES.has(name)) {
     if (!hub)
-      return text("hub is not running for this project (start it with: ahub up).");
+      return text(offline());
     const res = await hub.request({ t: "task", op: name, args: args ?? {} });
     return text(res.ok ? res.text : `error: ${res.error}`);
   }
   return text(`unknown tool ${name}`);
 });
 await server.connect(new StdioServerTransport);
+process.stdin.on("end", () => process.exit(0));
+process.stdin.on("close", () => process.exit(0));
 connectLoop();

package/src/adapters/acp.ts

@@ -2,6 +2,7 @@ import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { createInterface } from "node:readline";
 import { renderDigest, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
+import { stopOwnedProcess } from "../hub/child-process.ts";
 
 export interface PermissionOption {
   optionId: string;
@@ -74,14 +75,17 @@ export class AcpPeer extends BasePeer {
     try {
       this.sessionId = (await Promise.race([handshake(), timeout])).sessionId;
     } catch (e) {
-      proc.kill();
+      await stopOwnedProcess(proc);
       throw e;
     }
     this.setState("idle");
   }
 
   async stop(): Promise<void> {
-    this.proc?.kill();
+    const proc = this.proc;
+    if (!proc || proc.exitCode !== null) return;
+    await stopOwnedProcess(proc);
+    if (this.proc === proc) this.proc = undefined;
   }
 
   /** Resolves once the prompt is in flight; the turn result arrives on its own. */

package/src/adapters/claude-channel.ts

@@ -11,19 +11,32 @@ import { VERSION } from "../version.ts";
 import { DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS } from "../hub/hub-tools.ts";
 import { frame, replyParent, sanitize, HUB_MESSAGE_INSTRUCTION, type Envelope } from "../hub/envelope.ts";
 
-const stateDir = stateDirFor(process.cwd());
+// A native session is pinned at launch. Unlike a new CLI invocation after `cd`,
+// its MCP server must not silently move to another hub (including while offline).
+// ControlClient verifies the manifest identity on every connection.
+const stateDir = process.env.AGENTHUB_STATE_DIR ?? stateDirFor(process.cwd());
+const projectRoot = process.env.AGENTHUB_PROJECT_DIR ?? process.cwd();
 const peerId = process.env.AGENTHUB_PEER_ID ?? "claude";
 /** tools mode: the same server, run by Kimi (ACP mcpServers) or Codex (mcp_servers override). Their messages arrive through their own adapters, so no channel here. */
 const toolsOnly = process.env.AGENTHUB_MODE === "tools";
 
 function roles(): Record<string, string[]> {
   try {
-    return { ...DEFAULT_ROLES, ...JSON.parse(readFileSync(join(process.cwd(), ".agenthub", "config.json"), "utf8")).roles };
+    return { ...DEFAULT_ROLES, ...JSON.parse(readFileSync(join(projectRoot, ".agenthub", "config.json"), "utf8")).roles };
   } catch {
     return DEFAULT_ROLES;
   }
 }
 const MAX_RECONNECT_DELAY_MS = 30_000;
+/** Close codes a retry cannot fix: another session took this peer id (4000), bad token, reserved or taken id, wire version. */
+const TERMINAL_CLOSES: Record<number, string> = {
+  4000: `another session attached to the hub as "${peerId}"; this one is detached (restart it to take the peer back)`,
+  4401: "the hub refused the control token",
+  4404: "the hub belongs to a different project or instance; restart this session from the intended project",
+  4403: `the hub refused the peer id "${peerId}" (reserved or malformed)`,
+  4409: `the peer id "${peerId}" is taken by a hub-managed adapter`,
+  4426: "wire version mismatch with the running hub: update the agent-hub plugin (ahub setup) and restart this session",
+};
 const INBOX_CAP = 200;
 
 const INSTRUCTIONS = [
@@ -50,6 +63,8 @@ const server = new Server(
 
 const inbox: string[] = []; // pushes that failed; drained by hub_inbox
 let hub: ControlClient | undefined;
+let detached: string | undefined; // why this server stopped reconnecting; tool calls report it
+const offline = () => detached ?? "hub is not running for this project (start it with: ahub up).";
 
 /** One delivery = one notification, because every notification can cost Claude a turn. */
 async function push(envs: Envelope[]): Promise<void> {
@@ -75,18 +90,26 @@ async function push(envs: Envelope[]): Promise<void> {
 
 async function connectLoop(): Promise<void> {
   for (let attempt = 0; ; attempt++) {
+    let code: number | undefined;
     try {
-      const client = await ControlClient.connect(stateDir, { role: toolsOnly ? "tools" : "peer", peer: peerId });
+      const client = await ControlClient.connect(stateDir, { role: toolsOnly ? "tools" : "peer", peer: peerId,
+        ...(process.env.AGENTHUB_PROJECT_DIR ? { projectRoot } : {}) });
       client.onPush = (msg) => msg.t === "deliver" && void push(msg.envs ?? [msg.env]); // `env`: a daemon older than wire version 2
       hub = client;
       attempt = -1;
       log(`connected to hub as "${peerId}"`);
-      await new Promise<void>((r) => (client.onClose = r));
+      code = await new Promise<number>((r) => (client.onClose = r));
       hub = undefined;
       log("hub connection lost");
     } catch (e) {
+      code = (e as { code?: number }).code;
       if (attempt === 0) log((e as Error).message);
     }
+    // Retrying these only fights another session or hammers a hub that will refuse again.
+    if (code !== undefined && TERMINAL_CLOSES[code]) {
+      detached = TERMINAL_CLOSES[code];
+      return log(`stopped reconnecting: ${detached}`);
+    }
     await new Promise((r) => setTimeout(r, Math.min(1000 * 2 ** Math.max(attempt, 0), MAX_RECONNECT_DELAY_MS)));
   }
 }
@@ -129,14 +152,14 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   }
   if (name === "hub_send") {
     const { text: body, to, reply_to } = (args ?? {}) as { text?: string; to?: string[]; reply_to?: string };
-    if (!hub) return text("hub is not running for this project (start it with: ahub up). Message not sent.");
+    if (!hub) return text(`${offline()} Message not sent.`);
     const res = await hub.request({ t: "send", body, to, reply_to });
     if (!res.ok) return text(`not sent: ${res.error}`);
     if (res.recorded) return text("recorded only ([FYI]): it is on the hub console and log, and no peer spent a turn on it");
     return text(`sent to: ${res.targets.join(", ") || "(no other peers attached)"}`);
   }
   if (TASK_TOOL_NAMES.has(name)) {
-    if (!hub) return text("hub is not running for this project (start it with: ahub up).");
+    if (!hub) return text(offline());
     const res = await hub.request({ t: "task", op: name, args: args ?? {} });
     return text(res.ok ? res.text : `error: ${res.error}`);
   }
@@ -144,4 +167,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 
 await server.connect(new StdioServerTransport());
+// The host (Claude Code, Codex, Kimi) talks over stdin; once it is gone nothing can use this server, and a leftover would keep reconnecting.
+process.stdin.on("end", () => process.exit(0));
+process.stdin.on("close", () => process.exit(0));
 void connectLoop();

package/src/adapters/codex-appserver.ts

@@ -2,6 +2,7 @@ import { spawn, type ChildProcess } from "node:child_process";
 import type { Server, ServerWebSocket } from "bun";
 import { renderDigest, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
+import { stopOwnedProcess } from "../hub/child-process.ts";
 
 export interface CodexOptions {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
@@ -43,6 +44,8 @@ export class CodexPeer extends BasePeer {
   private proc: ChildProcess | undefined;
   private server: Server<Link> | undefined;
   private link: Link | undefined; // the connection that owns the current thread
+  /** Claimed as soon as a TUI WebSocket opens, before it can start a thread. */
+  private claimedTui: Link | undefined;
   private threadId = "";
   private readonly activeTurns = new Set<string>();
   private nextId = -1;
@@ -67,7 +70,8 @@ export class CodexPeer extends BasePeer {
 
   async start(): Promise<void> {
     const upstream = this.opts.upstreamUrl ?? (await this.spawnAppServer());
-    this.server = Bun.serve<Link>({
+    try {
+      this.server = Bun.serve<Link>({
       hostname: "127.0.0.1",
       port: this.opts.proxyPort,
       fetch: (req, server) => {
@@ -77,21 +81,40 @@ export class CodexPeer extends BasePeer {
         return new Response("agent-hub codex proxy");
       },
       websocket: {
-        open: (tui) => this.attach(tui, upstream),
-        message: (tui, data) => this.fromTui(tui.data, String(data)),
-        close: (tui) => this.detach(tui.data),
+        open: (tui) => {
+          if (this.claimedTui) {
+            tui.close(1013, "codex TUI already attached to this hub");
+            return;
+          }
+          this.attach(tui, upstream);
+        },
+        message: (tui, data) => {
+          if (tui.data?.up) this.fromTui(tui.data, String(data));
+        },
+        close: (tui) => {
+          // A rejected second attachment never passed through attach(), so it has no Link.
+          if (tui.data?.up) this.detach(tui.data);
+        },
       },
-    });
+      });
+    } catch (error) {
+      const proc = this.proc;
+      if (proc) {
+        await stopOwnedProcess(proc);
+        if (this.proc === proc) this.proc = undefined;
+      }
+      throw error;
+    }
   }
 
   async stop(): Promise<void> {
     this.server?.stop(true);
+    this.claimedTui?.tui.close(1001, "hub shutting down");
     const proc = this.proc;
     if (proc && proc.exitCode === null) {
       // Wait for the port to be released: `ahub codex` may restart the adapter right away.
-      const exited = new Promise((r) => proc.once("exit", r));
-      proc.kill();
-      await Promise.race([exited, Bun.sleep(3000)]);
+      await stopOwnedProcess(proc);
+      if (this.proc === proc) this.proc = undefined;
     }
     this.setState("offline");
   }
@@ -200,13 +223,16 @@ export class CodexPeer extends BasePeer {
       await Bun.sleep(100);
     }
     if (gone) throw new Error(gone);
-    this.proc.kill();
+    const proc = this.proc;
+    await stopOwnedProcess(proc);
+    if (this.proc === proc) this.proc = undefined;
     throw new Error("codex app-server did not become healthy within 10 s");
   }
 
   private attach(tui: ServerWebSocket<Link>, upstream: string): void {
     const up = new WebSocket(upstream);
     const link: Link = { tui, up, backlog: [], tracked: new Map() };
+    this.claimedTui = link;
     tui.data = link;
     up.onopen = () => {
       for (const frame of link.backlog.splice(0)) up.send(frame);
@@ -217,6 +243,7 @@ export class CodexPeer extends BasePeer {
 
   private detach(link: Link): void {
     link.up.close();
+    if (this.claimedTui === link) this.claimedTui = undefined;
     if (this.link !== link) return;
     clearInterval(this.usageTimer);
     this.link = undefined;
@@ -314,6 +341,7 @@ export class CodexPeer extends BasePeer {
   }
 }
 
+
 function parse(raw: string): any {
   try {
     return JSON.parse(raw);