@staix/agent-hub 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.5.0
+
+- Controlled protocol-8 restart with private queue/session snapshots, manual-pause preservation, instance fencing and verified release (#21).
+- Exact-version upgrade planning, immutable package staging, detached resumable operation receipts and machine lifecycle locking.
+- Orca-first native terminal recovery: original Codex/Claude conversations, new Kimi/local sessions with task context, and explicit manual blockers for unsupported sessions.
+- Running projects transition sequentially; the shared Claude plugin and Claude sessions have a final common phase. Global CLI promotion follows verification.
+- Protocols 5–7 require a manual bootstrap using their matching CLI. No automatic legacy shutdown, uncertain side-effect replay or rollback.
+
+## 0.4.1 (included in 0.5.0)
+
+- Synchronize the daemon digest integration fixture without changing batching semantics or weakening digest/FYI assertions (#15).
+- Reconcile completed live smoke and npm publication evidence; infrastructure-dependent checks remain tracked in #12.
+
+## 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).

package/README.md

@@ -1,12 +1,19 @@
 # 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.2. All six milestones of the design spec are implemented; the [smoke checklist](docs/smoke.md)
+Status: 0.5.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.
 
+Version 0.5.0 adds [controlled upgrade and session recovery](docs/specs/2026-09-20-upgrade-recovery-design.md).
+After bootstrapping a protocol-8 hub, use `ahub restart --dry-run` to inspect one
+project or `ahub upgrade --to <exact-version> --dry-run` to inspect an upgrade of
+the running projects. Remove `--dry-run` to review and schedule the operation;
+`ahub recovery status <operation-id>` reports progress. Existing protocol-5–7
+hubs require their matching CLI and an attended maintenance bootstrap.
+
 ## Start here
 
 Requires [Bun](https://bun.sh) >=1.3.0 on PATH; Node alone cannot run the CLI.
@@ -22,7 +29,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.2 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.5.0 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.
@@ -69,3 +76,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.2",
+  "version": "0.5.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.2",
+  "version": "0.5.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 = 8;
 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,15 +15645,33 @@ 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}`));
+      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" });
@@ -15574,21 +15679,38 @@ class ControlClient {
         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.2",
+  version: "0.5.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,12 +15824,13 @@ ${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;
   }
@@ -15716,6 +15839,7 @@ 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"
@@ -15772,7 +15896,11 @@ 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;

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 { childEnv, stopOwnedProcess } from "../hub/child-process.ts";
 
 export interface PermissionOption {
   optionId: string;
@@ -17,7 +18,11 @@ export interface PermissionRequest {
 export interface AcpOptions {
   /** e.g. ["kimi", "acp"]. `opencode acp` fits the same adapter. */
   cmd: string[];
+  /** Coordinator-visible selected model only; contains no prompts or command arguments. */
+  launchModel?: string;
   cwd: string;
+  /** Optional launch environment; recovery authority is always removed before spawn. */
+  env?: NodeJS.ProcessEnv;
   watchdogMs?: number;
   /** ACP stdio MCP servers for the session (the hub's task tools). */
   mcpServers?: { name: string; command: string; args: string[]; env: { name: string; value: string }[] }[];
@@ -51,9 +56,13 @@ export class AcpPeer extends BasePeer {
     super(id, opts.watchdogMs);
   }
 
+  recoveryMetadata(): Record<string, unknown> {
+    return { launch: { kind: "acp", ...(this.opts.launchModel ? { model: this.opts.launchModel } : {}) }, ...(this.sessionId ? { sessionId: this.sessionId } : {}) };
+  }
+
   async start(): Promise<void> {
     const [bin, ...args] = this.opts.cmd;
-    const proc = spawn(bin!, args, { cwd: this.opts.cwd, stdio: ["pipe", "pipe", "pipe"] });
+    const proc = spawn(bin!, args, { cwd: this.opts.cwd, env: childEnv({ ...process.env, ...(this.opts.env ?? {}) }), stdio: ["pipe", "pipe", "pipe"] });
     this.proc = proc;
     proc.on("error", (e) => this.down(`spawn failed: ${e.message}`));
     proc.on("exit", (code) => this.down(`exited with code ${code}`));
@@ -74,14 +83,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,14 +11,18 @@ 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;
   }
@@ -28,6 +32,7 @@ const MAX_RECONNECT_DELAY_MS = 30_000;
 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",
@@ -87,7 +92,8 @@ 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;

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 { childEnv, 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>`. */
@@ -20,6 +21,8 @@ export interface CodexOptions {
   /** How often to ask app-server for the rate limits while a TUI is attached. */
   usagePollMs?: number;
   cwd: string;
+  /** Optional launch environment; recovery authority is always removed before spawn. */
+  env?: NodeJS.ProcessEnv;
   watchdogMs?: number;
   log?: (line: string) => void;
 }
@@ -43,6 +46,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;
@@ -61,13 +66,21 @@ export class CodexPeer extends BasePeer {
     super(id, opts.watchdogMs);
   }
 
+  recoveryMetadata(): Record<string, unknown> {
+    return {
+      launch: { kind: "codex", bin: this.opts.bin ?? "codex", cwd: this.opts.cwd, appPort: this.opts.appPort, proxyPort: this.opts.proxyPort },
+      ...(this.threadId ? { threadId: this.threadId } : {}),
+    };
+  }
+
   get proxyUrl(): string {
     return `ws://127.0.0.1:${this.server?.port ?? this.opts.proxyPort}`;
   }
 
   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 +90,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");
   }
@@ -186,6 +218,7 @@ export class CodexPeer extends BasePeer {
     let gone = "";
     this.proc = spawn(this.opts.bin ?? "codex", ["app-server", "--listen", `ws://127.0.0.1:${port}`, ...(this.opts.extraArgs ?? [])], {
       cwd: this.opts.cwd,
+      env: childEnv({ ...process.env, ...(this.opts.env ?? {}) }),
       stdio: ["ignore", "ignore", "pipe"],
     });
     this.proc.stderr?.on("data", (d) => this.opts.log?.(`[${this.id}] ${String(d).trimEnd()}`));
@@ -200,13 +233,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 +253,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 +351,7 @@ export class CodexPeer extends BasePeer {
   }
 }
 
+
 function parse(raw: string): any {
   try {
     return JSON.parse(raw);

package/src/adapters/local-worker.ts

@@ -68,6 +68,10 @@ export class LocalPeer extends BasePeer {
     this.sandboxProfile = profile(opts.cwd, opts.tools.bashNetwork ?? false, opts.tools.readAllow, opts.tools.deny);
   }
 
+  recoveryMetadata(): Record<string, unknown> {
+    return { launch: { kind: "local", cwd: this.opts.cwd, model: this.opts.fixedModel, ...(this.opts.route ? { route: this.opts.route } : {}) }, sessionId: this.sessionId };
+  }
+
   async start(): Promise<void> {
     this.opts.capture?.init(this.sessionId, "agent-hub local worker session");
     this.setState("idle");