@staix/agent-hub 0.5.0 → 0.6.1

package/src/cli/main.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 import { ControlClient, readControl } from "../hub/control-client.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { projectContext } from "../hub/project.ts";
@@ -22,6 +23,7 @@ import { childEnv } from "../hub/child-process.ts";
 import { abortRecovery, createOperation, publicOperation, registeredProjects, runRecovery, type RecoveryOperation } from "./upgrade.ts";
 import { makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.ts";
 import { recordTerminalLaunch } from "./terminal-recovery.ts";
+import { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
 
 const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one project directory
 
@@ -40,6 +42,8 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub claude [args...]         launch Claude Code with the hub channel   [--unattended]
   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 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,
@@ -108,6 +112,34 @@ function exec(bin: string, argv: string[]): never {
   process.exit(res.status ?? 1);
 }
 
+function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never {
+  const env: NodeJS.ProcessEnv = { ...extra, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+  delete env.AGENTHUB_RECOVERY_OPERATION;
+  delete env.AGENTHUB_UNATTENDED;
+  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env });
+  if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
+  process.exit(res.status ?? 1);
+}
+
+function piFlags(): { mode: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; model?: string; sessionId?: string; sessionFile?: string } {
+  for (const flag of ["--mode", "--backend", "--model", "--session-id", "--session-file"]) {
+    const index = args.indexOf(flag);
+    if (index >= 0 && (!args[index + 1] || args[index + 1]!.startsWith("--"))) fail(`${flag} needs a value`);
+  }
+  const mode = (args.includes("--mode") ? args[args.indexOf("--mode") + 1] : "headless") as string;
+  const backend = (args.includes("--backend") ? args[args.indexOf("--backend") + 1] : undefined) as string | undefined;
+  const model = args.includes("--model") ? args[args.indexOf("--model") + 1] : undefined;
+  const sessionId = args.includes("--session-id") ? args[args.indexOf("--session-id") + 1] : undefined;
+  const sessionFile = args.includes("--session-file") ? args[args.indexOf("--session-file") + 1] : undefined;
+  const valueFlags = new Set(["--mode", "--backend", "--model", "--session-id", "--session-file"]);
+  for (let i = 0; i < args.length; i++) {
+    if (!valueFlags.has(args[i]!)) fail(`unknown Pi option: ${args[i]}`);
+    i++;
+  }
+  if (!["headless", "tui"].includes(mode) || (backend !== undefined && !["auto", "dgx", "mlx"].includes(backend)) || (sessionId && sessionFile)) fail("usage: ahub pi [--mode headless|tui] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id> | --session-file <path>]");
+  return { mode: mode as "headless" | "tui", ...(backend ? { backend: backend as "auto" | "dgx" | "mlx" } : {}), ...(model ? { model } : {}), ...(sessionId ? { sessionId } : {}), ...(sessionFile ? { sessionFile } : {}) };
+}
+
 async function projectRows() {
   const registry = new Registry();
   try { return await Promise.all(registry.list().map(async (project) => ({ ...project, ...await inspectProject(project) }))); }
@@ -363,6 +395,25 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log(res.already ? "kimi is already attached" : 'kimi attached (headless). Talk to it with: ahub say @kimi "..."');
   },
 
+  pi: async () => {
+    const options = piFlags();
+    const hub = await connect();
+    const res = await hub.request({ t: "start", peer: "pi", args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+    hub.close();
+    if (!res.ok) fail(res.error);
+    if (options.mode === "tui") {
+      const launch = res.launch;
+      if (!launch || typeof launch.cmd !== "string" || !Array.isArray(launch.args) || !launch.args.every((a: unknown) => typeof a === "string") || !launch.env || typeof launch.env !== "object") fail("Pi TUI launch metadata was not verified");
+      const launchEnv = { ...(launch.env as NodeJS.ProcessEnv) };
+      delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
+      delete launchEnv.AGENTHUB_UNATTENDED;
+      const control = readControl(stateDir);
+      if (control?.instanceId) await recordTerminalLaunch("pi", cwd, stateDir, control.instanceId);
+      return execWithEnv(launch.cmd, launch.args, launchEnv);
+    }
+    console.log(res.already ? "pi is already attached" : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
+  },
+
   local: async () => {
     const opt = (flag: string) => (args.includes(flag) ? args[args.indexOf(flag) + 1] ?? fail(`${flag} needs a value`) : undefined);
     const hub = await connect();
@@ -372,6 +423,24 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log(res.already ? "local is already attached" : `local attached on ${res.model}. Give it work with: ahub say @local "..."`);
   },
 
+  models: async () => {
+    const action = args[0] ?? "status";
+    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 };
+    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");
+    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]);
+    run(["uv", "pip", "install", "--python", python, "mlx-lm==0.31.3"]);
+    run([python, "-c", `from huggingface_hub import snapshot_download; snapshot_download(repo_id='Qwen/Qwen3-8B-MLX-4bit', revision='383413e909f3bc5303ce195ebbdf0339c5a1a2a3', local_dir=${JSON.stringify(modelPath)}, token=False)`]);
+    console.log(`MLX runtime and pinned model prepared at ${runtimeDir}`);
+  },
+
   say: async () => {
     const lead = args.findIndex((a) => !/^@[a-z][a-z0-9-]*$/.test(a)); // only leading @tokens are recipients
     const to = args.slice(0, lead === -1 ? args.length : lead).map((a) => a.slice(1));
@@ -503,6 +572,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log(`hub pid ${status.pid}, control 127.0.0.1:${status.controlPort}, ${status.cwd}`);
     const peers = Object.entries(status.peers as Record<string, { state: string; queued: number }>);
     for (const [id, p] of peers) console.log(`  ${id.padEnd(8)} ${p.state.padEnd(8)} queued ${p.queued}${(p as any).paused ? `  (${(p as any).paused})` : ""}${(p as any).servedBy ? `  last call: ${(p as any).servedBy}` : ""}`);
+    const models = (status as any).models?.backends as any[] | undefined;
+    if (models?.length) for (const backend of models) console.log(`  model    ${backend.kind ?? "unknown"}/${backend.alias ?? "unknown"} ${backend.state ?? "unknown"} active ${backend.active ?? 0}${backend.requestedModel ? ` requested ${backend.requestedModel}` : ""}${backend.actualModel ? ` actual ${backend.actualModel}` : ""}${backend.provider ? ` provider ${backend.provider}` : ""}`);
     if (status.switchyard) console.log(`  switchyard: ${status.switchyard}`);
     const counts = Object.entries(status.tasks ?? {}).map(([s, n]) => `${n} ${s}`).join(", ");
     if (counts) console.log(`  tasks: ${counts} (ahub board)`);
@@ -548,6 +619,9 @@ const commands: Record<string, () => Promise<void> | void> = {
     row(!!omni.apiKey(), "omniroute key", omni.apiKey() ? "present" : "missing: set OMNIROUTE_API_KEY or omniroute.api_key_file in .agenthub/config.json");
     const sy = spawnSync(process.env.AGENTHUB_SWITCHYARD_BIN ?? "switchyard-server", ["--version"], { encoding: "utf8" });
     row(sy.status === 0 ? true : undefined, "switchyard", sy.status === 0 ? sy.stdout.trim() : "not installed: ahub local uses fixed_model on OmniRoute (cargo install --locked switchyard-server)");
+    const mlxConfig = loadConfig(cwd).mlx;
+    const mlx = await inspectMlx({ ...mlxConfig, runtimeDir: mlxConfig.runtimeDir ? resolve(cwd, mlxConfig.runtimeDir) : undefined, modelPath: mlxConfig.modelPath ? resolve(cwd, mlxConfig.modelPath) : undefined });
+    row(mlx.state === "ready" || mlx.state === "stopped", "pi mlx", `${mlx.state}${mlx.model ? ` (${mlx.model})` : ""}${mlx.lastError ? `: ${mlx.lastError}` : ""}`);
 
     const memory = new MemoryClient();
     const mem = await memory.health();

package/src/cli/terminal-recovery.ts

@@ -23,7 +23,8 @@ export type CommandRunner = (argv: readonly string[]) => Promise<CommandResult>;
 /** Stable process identity hook. It returns a digest, never raw process metadata. */
 export type ProcessIdentity = (pid: number) => string | undefined | Promise<string | undefined>;
 
-export type TerminalPeer = "codex" | "claude";
+export type TerminalPeer = "codex" | "claude" | "pi";
+export interface SessionRef { sessionId: string; sessionFile?: string; backend?: string; model?: string; }
 
 export interface LaunchMetadata {
   /** Absolute entrypoint of the package which owns the resumed session. */
@@ -43,6 +44,9 @@ export interface TerminalBinding {
   worktreeId: string;
   projectRoot: string;
   sessionId: string;
+  sessionFile?: string;
+  backend?: string;
+  model?: string;
   launch: LaunchMetadata;
   /** Alias retained for callers that use the wire name. */
   launchMetadata: LaunchMetadata;
@@ -353,7 +357,7 @@ function identityFrom(terminal: Record<string, unknown>): TerminalPeer | undefin
   const session = object(terminal.session);
   const candidates = [terminal.agentIdentity, terminal.agent, wait.agentIdentity, wait.agent, session.agentIdentity, session.agent];
   for (const candidate of candidates) {
-    if (candidate === "codex" || candidate === "claude") return candidate;
+    if (candidate === "codex" || candidate === "claude" || candidate === "pi") return candidate;
   }
   return undefined;
 }
@@ -381,11 +385,13 @@ function requireAbsoluteEntrypoint(value: string): string {
   return value;
 }
 
-function launchFor(peer: TerminalPeer, projectRoot: string, sessionId: string, options: Required<TerminalRecoveryOptions>, source: Record<string, unknown>, recorded?: RecordedTerminalLaunch): LaunchMetadata {
+function launchFor(peer: TerminalPeer, projectRoot: string, sessionId: string, options: Required<TerminalRecoveryOptions>, source: Record<string, unknown>, recorded?: RecordedTerminalLaunch, ref?: SessionRef): LaunchMetadata {
   const packageEntrypoint = requireAbsoluteEntrypoint(options.packageEntrypoint);
   const argv = peer === "codex"
     ? ["bun", packageEntrypoint, "--project", projectRoot, "codex", "resume", sessionId]
-    : ["bun", packageEntrypoint, "--project", projectRoot, "claude", "--resume", sessionId];
+    : peer === "claude"
+      ? ["bun", packageEntrypoint, "--project", projectRoot, "claude", "--resume", sessionId]
+      : ["bun", packageEntrypoint, "--project", projectRoot, "pi", "--mode", "tui", ...(ref?.backend ? ["--backend", ref.backend] : []), ...(ref?.model ? ["--model", ref.model] : []), ...(ref?.sessionFile ? ["--session-file", ref.sessionFile] : ["--session-id", sessionId])];
   const env = { ...allowedEnv(source), ...(recorded?.env ?? {}) };
   const prefix = ALLOWED_ENV.filter((name) => env[name] !== undefined).map((name) => `${name}=${shellQuote(env[name]!)}`);
   const command = [...prefix, ...argv.map(shellQuote)].join(" ");
@@ -418,13 +424,13 @@ async function showBinding(binding: TerminalBinding, options: Required<TerminalR
  * Read Orca's authoritative terminal inventory and bind only exact agent/session identities.
  * Titles, previews, pty ids and process names are deliberately never used as identity.
  */
-export async function inspectTerminals(projectRoot: string, sessions: Partial<Record<TerminalPeer, string>>, options?: CommandRunner | TerminalRecoveryOptions): Promise<TerminalInspection> {
+export async function inspectTerminals(projectRoot: string, sessions: Partial<Record<TerminalPeer, string | SessionRef>>, options?: CommandRunner | TerminalRecoveryOptions): Promise<TerminalInspection> {
   const config = normalizeOptions(options);
   const records = await liveRecords(config.stateDir, projectRoot, config.instanceId, config.processIdentity);
   const blockers: RecoveryBlocker[] = [];
   const bindings: TerminalBinding[] = [];
   const byPeer: Partial<Record<TerminalPeer, TerminalBinding>> = {};
-  const requested = (Object.entries(sessions) as [TerminalPeer, string | undefined][]).filter((entry): entry is [TerminalPeer, string] => typeof entry[1] === "string" && entry[1].length > 0);
+  const requested = (Object.entries(sessions) as [TerminalPeer, string | SessionRef | undefined][]).map(([peer, value]) => [peer, typeof value === "string" ? { sessionId: value } : value] as const).filter((entry): entry is [TerminalPeer, SessionRef] => !!entry[1]?.sessionId);
   if (!requested.length) return { bindings, byPeer, blockers, manualRequired: false };
 
   let listed: Record<string, unknown>[];
@@ -435,7 +441,8 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
     return { bindings, byPeer, blockers: [commandBlocker], manualRequired: true };
   }
 
-  for (const [peer, sessionId] of requested) {
+  for (const [peer, ref] of requested) {
+    const sessionId = ref.sessionId;
     const candidates = listed.filter((terminal) => rootMatches(terminal.worktreePath ?? terminal.projectRoot, projectRoot));
     const peerCandidates: Record<string, unknown>[] = [];
     for (const listedTerminal of candidates) {
@@ -481,8 +488,9 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
       continue;
     }
     const recorded = records.find((item) => item.peer === peer && item.handle === handle && item.worktreeId === terminal.worktreeId && item.incarnationId === terminal.incarnationId);
-    const launch = launchFor(peer, projectRoot, sessionId, config, terminal, recorded);
-    const binding: TerminalBinding = { peer, handle, incarnationId, worktreeId, projectRoot, sessionId, launch, launchMetadata: launch };
+    const sessionFile = peer === "pi" ? nestedString(terminal, ["sessionFile", "sessionPath"]) ?? nestedString(object(terminal.session), ["file", "path"]) : undefined;
+    const launch = launchFor(peer, projectRoot, sessionId, config, terminal, recorded, { ...ref, ...(sessionFile ? { sessionFile } : {}) });
+    const binding: TerminalBinding = { peer, handle, incarnationId, worktreeId, projectRoot, sessionId, ...(sessionFile ? { sessionFile } : {}), ...(ref.backend ? { backend: ref.backend } : {}), ...(ref.model ? { model: ref.model } : {}), launch, launchMetadata: launch };
     bindings.push(binding);
     byPeer[peer] = binding;
   }

package/src/cli/upgrade-runtime.ts

@@ -6,8 +6,9 @@ import { inspectProject } from "../hub/lifecycle.ts";
 import type { Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.ts";
 import { packageDigest, registryRelease, runCommand, stageRelease, verifyPackage, type RunCommand } from "./recovery-package.ts";
-import { inspectTerminals, closeTerminal, createTerminal, waitForIdle, shellQuote, type TerminalBinding, type TerminalRecoveryOptions } from "./terminal-recovery.ts";
+import { inspectTerminals, closeTerminal, createTerminal, waitForIdle, shellQuote, type SessionRef, type TerminalBinding, type TerminalRecoveryOptions } from "./terminal-recovery.ts";
 import { planFingerprint, registeredProjects, type Inspection, type PlannedProject, type ProjectProgress, type RecoveryDriver, type RecoveryOperation, type UpgradePlan } from "./upgrade.ts";
+import { refreshManager } from "../hub/manager.ts";
 
 export const PACKAGE_ROOT = resolve(import.meta.dir, "../..");
 const orcaExecutable = () => process.env.ORCA_CLI_COMMAND || (process.env.ORCA_DEV_REPO_ROOT ? "orca-dev" : process.platform === "linux" && !process.env.ORCA_TERMINAL_HANDLE ? "orca-ide" : "orca");
@@ -19,8 +20,16 @@ function terminalOptions(run: RunCommand = runCommand): TerminalRecoveryOptions
   } };
 }
 
-async function rpc(project: Project, message: Record<string, unknown>): Promise<any> {
-  const client = await ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root, projectId: project.id });
+export function restoredTerminalArgv(entrypoint: string, projectRoot: string, binding: TerminalBinding): string[] {
+  if (binding.peer === "codex") return [process.execPath, entrypoint, "--project", projectRoot, "codex", "resume", binding.sessionId];
+  if (binding.peer === "claude") return [process.execPath, entrypoint, "--project", projectRoot, "claude", "--resume", binding.sessionId];
+  return [process.execPath, entrypoint, "--project", projectRoot, "pi", "--mode", "tui",
+    ...(binding.backend ? ["--backend", binding.backend] : []), ...(binding.model ? ["--model", binding.model] : []),
+    ...(binding.sessionFile ? ["--session-file", binding.sessionFile] : ["--session-id", binding.sessionId])];
+}
+
+async function rpc(project: Project, message: Record<string, unknown>, protocol = PROTOCOL): Promise<any> {
+  const client = await ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root, projectId: project.id }, 30_000, protocol);
   try {
     const reply = await client.request(message, 30_000);
     if (reply.ok === false) throw new Error(reply.error ?? "recovery control request failed");
@@ -31,13 +40,20 @@ async function rpc(project: Project, message: Record<string, unknown>): Promise<
 export async function inspectRecovery(project: Project): Promise<Inspection> {
   const base = await inspectProject(project);
   const control = readControl(project.stateDir);
-  if (base.state !== "running") return {
+  const sourceProtocol = control?.protocol;
+  const legacySupported = sourceProtocol === 8;
+  if (base.state !== "running" && !legacySupported) return {
     state: base.state, peers: [], blockers: base.state === "stopped" ? [] : [base.state === "incompatible" ? "manual-bootstrap-required: source lacks the recovery contract; use its matching CLI" : base.error ?? base.state],
     ...(control?.instanceId ? { instanceId: control.instanceId } : {}), ...(control?.protocol ? { protocol: control.protocol } : {}),
   };
-  const status = base.status;
+  let status = base.status;
+  if (!status && legacySupported) {
+    const readback = await rpc(project, { t: "status" }, sourceProtocol);
+    status = readback.status;
+  }
+  if (!status || !control) return { state: "unavailable", peers: [], blockers: ["authenticated source status unavailable"] };
   let response: any;
-  try { response = await rpc(project, { t: "recovery", op: "inspect", expectedInstanceId: status.instanceId }); }
+  try { response = await rpc(project, { t: "recovery", op: "inspect", expectedInstanceId: status.instanceId }, sourceProtocol ?? PROTOCOL); }
   catch {
     // A stop can complete between authenticated status and the second read. Never infer stopped
     // from a connection failure: the coordinator will inspect the ownership manifest again.
@@ -48,7 +64,8 @@ export async function inspectRecovery(project: Project): Promise<Inspection> {
   return { state: "running", instanceId: status.instanceId, version: status.version, protocol: status.protocol,
     recovery: { operationId: response.recovery?.operationId, phase: response.recovery?.phase, ready: response.recovery?.ready }, peers: peers.map((peer) => ({ id: peer.id, state: peer.state,
       ...(peer.threadId ? { threadId: peer.threadId } : {}), ...(peer.sessionId ? { sessionId: peer.sessionId } : {}),
-      ...(peer.launch ? { args: Object.fromEntries(Object.entries(peer.launch).filter(([k, v]) => ["model", "route"].includes(k) && typeof v === "string")) as Record<string, string> } : {}) })), blockers: [] };
+      ...(typeof (peer.sessionFile ?? peer.launch?.sessionFile) === "string" ? { sessionFile: peer.sessionFile ?? peer.launch.sessionFile } : {}),
+      ...(peer.launch ? { args: Object.fromEntries(Object.entries(peer.launch).filter(([k, v]) => ["model", "route", "sessionFile", "mode", "backend"].includes(k) && typeof v === "string")) as Record<string, string> } : {}) })), blockers: [] };
 }
 
 export async function makeUpgradePlan(kind: "restart" | "upgrade", version: string, selectedRoot?: string, run: RunCommand = runCommand): Promise<UpgradePlan> {
@@ -67,7 +84,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
   if (existsSync(managerFile)) {
     try {
       const manager = JSON.parse(readFileSync(managerFile, "utf8"));
-      if (manager.protocol !== PROTOCOL) body.blockers.push("manager requires manual bootstrap with its matching CLI before protocol-8 recovery");
+      if (![8, PROTOCOL].includes(manager.protocol)) body.blockers.push("manager requires manual bootstrap with its matching CLI before protocol-9 recovery");
     } catch { body.blockers.push("manager ownership manifest is unreadable"); }
   }
   for (const project of projects) {
@@ -77,16 +94,19 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     catch { source = { state: "unavailable", peers: [], blockers: ["source recovery metadata could not be authenticated"] }; }
     if (source.state === "stopped" || source.state === "missing") continue;
     const blockers = [...source.blockers];
-    if (source.protocol !== PROTOCOL || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated recovery-capable source is required");
+    if (![8, PROTOCOL].includes(source.protocol ?? 0) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated recovery-capable source is required");
     if (source.recovery?.operationId && source.recovery.phase !== "released") blockers.push(`existing recovery operation ${source.recovery.operationId} must be resolved first`);
-    const sessions: { codex?: string; claude?: string } = {};
+    const sessions: { codex?: string; claude?: string; pi?: SessionRef } = {};
     for (const peer of source.peers) {
       if (peer.state === "offline") continue;
       if (peer.id === "codex" || peer.id === "claude") {
         const session = peer.id === "codex" ? peer.threadId : peer.sessionId;
         if (!session) blockers.push(`${peer.id}: original conversation ID is unknown; manual-required`);
         else sessions[peer.id] = session;
-      } else if (peer.id !== "kimi" && peer.id !== "local") blockers.push(`${peer.id}: no automatic recovery adapter`);
+      } else if (peer.id === "pi" && peer.args?.mode === "tui") {
+        if (!peer.sessionId) blockers.push("pi: original session ID is unknown; manual-required");
+        else sessions.pi = { sessionId: peer.sessionId, ...(peer.sessionFile ? { sessionFile: peer.sessionFile } : {}), ...(peer.args.backend ? { backend: peer.args.backend } : {}), ...(peer.args.model ? { model: peer.args.model } : {}) };
+      } else if (peer.id !== "kimi" && peer.id !== "local" && peer.id !== "pi") blockers.push(`${peer.id}: no automatic recovery adapter`);
     }
     const terminals = await inspectTerminals(project.root, sessions, {
       ...terminalOptions(run), stateDir: project.stateDir, instanceId: source.instanceId,
@@ -147,7 +167,11 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
     if (result.code !== 0) throw new Error(`target command ${args[0]} failed; inspect recovery state before retrying`);
     return result;
   };
-  const control = (project: Project, op: string, id: string, instance: string) => rpc(project, { t: "recovery", op, operationId: id, expectedInstanceId: instance }).then(() => {});
+  const control = (project: Project, op: string, id: string, instance: string) => {
+    const sourceProtocol = readControl(project.stateDir)?.protocol;
+    const protocol = sourceProtocol === 8 ? 8 : PROTOCOL;
+    return rpc(project, { t: "recovery", op, operationId: id, expectedInstanceId: instance }, protocol).then(() => {});
+  };
   const revalidateTerminal = async (planned: PlannedProject, progress: ProjectProgress, saved: TerminalBinding, exact: boolean): Promise<TerminalBinding> => {
     const options = { ...terminalOptions(run), stateDir: planned.project.stateDir, instanceId: progress.instanceId };
     const found = await inspectTerminals(planned.project.root, { [saved.peer]: saved.sessionId }, options);
@@ -218,11 +242,16 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
       const live = await inspectRecovery(planned.project);
       if (live.instanceId !== progress.instanceId) throw new Error("target daemon changed before peer restore");
       if (group === "native") {
-        for (const peer of planned.source.peers.filter((p) => ["kimi", "local"].includes(p.id) && p.state !== "offline")) {
+        for (const peer of planned.source.peers.filter((p) => ["kimi", "local", "pi"].includes(p.id) && p.state !== "offline" && !(p.id === "pi" && p.args?.mode === "tui"))) {
           const current = live.peers.find((p) => p.id === peer.id);
           if (current && current.state !== "offline") continue;
           const args = [peer.id];
-          for (const key of ["model", "route"]) if (typeof peer.args?.[key] === "string") args.push(`--${key}`, peer.args[key]!);
+          for (const key of ["mode", "backend", "model", "route"]) if (typeof peer.args?.[key] === "string") args.push(`--${key}`, peer.args[key]!);
+          if (peer.id === "pi") {
+            const sessionFile = peer.sessionFile ?? peer.args?.sessionFile;
+            if (typeof sessionFile === "string") args.push("--session-file", sessionFile);
+            else if (peer.sessionId) args.push("--session-id", peer.sessionId);
+          }
           await command(op, args, planned.project);
         }
       }
@@ -243,8 +272,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
           progress.terminals[key] = existing; save(); continue;
         }
         const entrypoint = join(op.targetRoot!, "src/cli/main.js");
-        const argv = [process.execPath, entrypoint, "--project", planned.project.root, original.peer,
-          ...(original.peer === "codex" ? ["resume", original.sessionId] : ["--resume", original.sessionId])];
+        const argv = restoredTerminalArgv(entrypoint, planned.project.root, original);
         const assignments = { ...original.launch.env, AGENTHUB_HOME: hubHome(), AGENTHUB_RECOVERY_OPERATION: op.id };
         const launch = { ...original.launch, packageEntrypoint: entrypoint, argv,
           command: ["env", ...Object.entries(assignments).map(([k, v]) => `${k}=${v}`), ...argv].map(shellQuote).join(" ") };
@@ -273,6 +301,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
       const readback = await run(["ahub", "--version"], { env: env(op) });
       if (readback.code !== 0 || readback.stdout.trim() !== op.plan.version) throw new Error("global CLI version was not verified");
     },
+    refreshManager: async (op) => { await refreshManager({ home: hubHome(), cli: join(op.targetRoot!, "src/cli/main.ts") }); },
     verify: async (planned, progress, op) => {
       const live = await inspectRecovery(planned.project);
       if (live.instanceId !== progress.instanceId || live.version !== op.plan.version || live.recovery?.operationId !== op.id) throw new Error("target identity verification failed");
@@ -281,6 +310,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
         if (!peer || !["idle", "busy", "paused"].includes(peer.state)) throw new Error(`${old.id}: peer reattachment not verified`);
         if (old.id === "codex" && peer.threadId !== old.threadId) throw new Error("Codex resumed a different conversation");
         if (old.id === "claude" && peer.sessionId !== old.sessionId) throw new Error("Claude resumed a different conversation");
+        if (old.id === "pi" && (peer.sessionId !== old.sessionId || (old.sessionFile && peer.sessionFile !== old.sessionFile))) throw new Error("Pi resumed a different conversation");
       }
       for (const original of planned.terminals as TerminalBinding[]) {
         const saved = progress.terminals[`restored:${original.peer}`];

package/src/cli/upgrade.ts

@@ -11,6 +11,7 @@ export interface RecoveryPeer {
   state: string;
   threadId?: string;
   sessionId?: string;
+  sessionFile?: string;
   args?: Record<string, string>;
 }
 export interface Inspection {
@@ -112,6 +113,7 @@ export interface RecoveryDriver {
   restore(planned: PlannedProject, progress: ProjectProgress, op: RecoveryOperation, group: "native" | "claude", save: () => void): Promise<void>;
   installPlugin(op: RecoveryOperation): Promise<void>;
   installGlobal(op: RecoveryOperation): Promise<void>;
+  refreshManager?(op: RecoveryOperation): Promise<void>;
   release(project: Project, operation: string, instance: string): Promise<void>;
   verify(planned: PlannedProject, progress: ProjectProgress, op: RecoveryOperation): Promise<void>;
   sleep(ms: number): Promise<void>;
@@ -245,6 +247,7 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
       await driver.release(planned.project, id, progress.instanceId!);
       progress.phase = "verified"; save();
     }
+    if (driver.refreshManager) { step("refresh-manager"); await driver.refreshManager(op); }
     if (op.plan.kind === "upgrade" && !op.globalInstalled) {
       step("install-global"); await driver.installGlobal(op); op.globalInstalled = true; save();
     }

package/src/hub/control-client.ts

@@ -6,8 +6,8 @@ export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
 }
 
-/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap. The plugin is installed apart from the daemon, so they can drift. */
-export const PROTOCOL = 8; // controlled daemon restart/recovery RPC and project/instance identity
+/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata. The plugin is installed apart from the daemon, so they can drift. */
+export const PROTOCOL = 9; // controlled restart/recovery plus the Pi bridge contract
 
 export interface Hello {
   /** `tools`: acts for `peer` (task tools, hub_send) without being a delivery target: the MCP server Kimi and Codex run. */
@@ -51,11 +51,13 @@ export class ControlClient {
 
   private constructor(private readonly ws: WebSocket) {}
 
-  static connect(stateDir: string, hello: Hello, timeoutMs = 3000): Promise<ControlClient> {
+  /** `protocol` is used only by the upgrade coordinator for an authenticated, explicitly supported source contract. */
+  static connect(stateDir: string, hello: Hello, timeoutMs = 3000, protocol = PROTOCOL): Promise<ControlClient> {
+    if (protocol !== 8 && protocol !== PROTOCOL) return Promise.reject(new Error(`unsupported recovery source protocol ${protocol}`));
     const control = readControl(stateDir);
     if (!control) return Promise.reject(new Error(`no hub running for ${stateDir} (run: ahub up)`));
-    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 (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) ||
@@ -87,7 +89,7 @@ export class ControlClient {
         client.pending.delete(msg.rid);
         done(msg);
       };
-      ws.onopen = () => void client.request({ t: "hello", v: PROTOCOL, token: control.token, ...hello, ...expected }, timeoutMs).then((reply) => {
+      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) ||