@staix/agent-hub 0.3.2 → 0.5.0

package/src/cli/main.ts

@@ -1,11 +1,14 @@
 #!/usr/bin/env bun
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { ControlClient, readControl } from "../hub/control-client.ts";
-import { loadConfig, startDaemon, stateDirFor } from "../hub/daemon.ts";
+import { loadConfig } from "../hub/daemon.ts";
+import { projectContext } from "../hub/project.ts";
+import { Registry, type Project } from "../hub/registry.ts";
+import { inspectProject, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
+import { openManager, startManager, stopManager } from "../hub/manager.ts";
 import type { BusEvent } from "../hub/bus.ts";
-import { allocatePorts, CODEX_APP, CODEX_PROXY, CONTROL, SWITCHYARD } from "../hub/ports.ts";
 import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
 import { init } from "./init.ts";
@@ -14,12 +17,26 @@ import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplac
 import { CLASSES } from "../hub/board.ts";
 import { VERSION } from "../version.ts";
 import { createInterface } from "node:readline/promises";
+import { assertLifecycleAvailable, readOperation } from "../hub/recovery-store.ts";
+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";
 
 const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one project directory
 
+  ahub --project <path|id> <command>  select a repository or worktree explicitly
+  ahub projects [--json]         list registered projects and live status
+  ahub projects remove <id>      forget a stopped registration (keeps project files)
+  ahub status --all              show every registered project
+  ahub ui --all [--no-open]      open the unified project dashboard
+  ahub ui --all --stop           stop only the dashboard manager
   ahub setup [--yes]            install or update the Claude Code channel plugin from this package, then run doctor
   ahub init                     write .agenthub/config.json and the CLAUDE.md / AGENTS.md marker blocks
   ahub up [--unattended]        start the daemon for this directory
+  ahub upgrade --to <version> [--dry-run] [--yes]   review and upgrade running projects
+  ahub restart [--dry-run] [--yes]                 recover this project's runtime
+  ahub recovery status|resume|abort <operation-id> inspect, resume or cancel a preflight
   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
@@ -45,25 +62,69 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub permit <id> <option>     answer a permission request shown by tail ("deny" cancels)
   ahub status | logs [-f] | doctor | kill`;
 
-const cwd = process.cwd();
-const stateDir = stateDirFor(cwd);
+const argv = process.argv.slice(2);
+let selector: string | undefined;
+if (argv[0] === "--project") {
+  argv.shift();
+  selector = argv.shift();
+  if (!selector || selector.startsWith("--")) fail("--project needs a path or project ID");
+}
+const [cmd = "help", ...args] = argv;
+let selected: { root: string; stateDir: string };
+try {
+  if (selector) {
+    const projects = registeredProjects();
+    {
+      const known = projects.find((p) => p.id === selector);
+      const context = known ?? projectContext(selector, {});
+      const registered = known ?? projects.find((p) => p.root === context.root);
+      selected = registered ?? context;
+    }
+  } else selected = projectContext(process.cwd());
+} catch (error) { fail((error as Error).message); }
+const cwd = selected.root;
+const stateDir = selected.stateDir;
+try { process.chdir(cwd); } catch { fail(`project directory is unavailable: ${cwd}`); }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
-const [cmd = "help", ...args] = process.argv.slice(2);
+const lifecycle = { inspectProject, startProject, stopProject };
+const connect = () => ControlClient.connect(stateDir, { role: "console", projectRoot: cwd });
 
-const connect = () => ControlClient.connect(stateDir, { role: "console" });
+function registeredProject(): Project {
+  const registry = new Registry();
+  try { return registry.register(cwd, stateDir); }
+  finally { registry.close(); }
+}
 
 async function healthy(): Promise<boolean> {
-  const control = readControl(stateDir);
-  if (!control) return false;
-  return fetch(control.url.replace("ws:", "http:") + "/healthz").then((r) => r.ok, () => false);
+  let hub: ControlClient | undefined;
+  try { hub = await connect(); const reply = await hub.request({ t: "status" }, 3000); return reply.status?.cwd === cwd; }
+  catch { return false; }
+  finally { hub?.close(); }
 }
 
 function exec(bin: string, argv: string[]): never {
-  const res = spawnSync(bin, argv, { stdio: "inherit", env: { ...process.env, AGENTHUB_STATE_DIR: stateDir } });
+  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...childEnv(), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
   if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 
+async function projectRows() {
+  const registry = new Registry();
+  try { return await Promise.all(registry.list().map(async (project) => ({ ...project, ...await inspectProject(project) }))); }
+  finally { registry.close(); }
+}
+
+async function printProjects(json = false) {
+  const rows = await projectRows();
+  if (json) return console.log(JSON.stringify(rows, null, 2));
+  for (const row of rows) {
+    console.log(`${row.id}  ${row.state.padEnd(12)} ${row.root}`);
+    if (row.status) console.log(`  peers ${Object.keys(row.status.peers ?? {}).length}, control ${row.status.controlPort}, tasks ${JSON.stringify(row.status.tasks ?? {})}`);
+    if (row.error) console.log(`  ${row.error}`);
+  }
+  if (!rows.length) console.log("No registered projects. Run ahub init in a project directory.");
+}
+
 function fail(message: string): never {
   console.error(`ahub: ${message}`);
   process.exit(1);
@@ -113,25 +174,104 @@ async function hold(t: "pause" | "resume"): Promise<void> {
   console.log(`${args[0]} is ${res.state}`);
 }
 
+function spawnRecovery(operation: RecoveryOperation): void {
+  const child = spawn(process.execPath, [join(operation.sourceRoot, "src/cli/main.js"), "recovery-run", operation.id], {
+    cwd, detached: true, stdio: "ignore", env: { ...process.env, AGENTHUB_RECOVERY_OPERATION: operation.id },
+  });
+  child.on("error", () => console.error(`runner launch failed; use ahub recovery resume ${operation.id}`));
+  child.unref();
+  console.log(`Recovery operation ${operation.id} scheduled.\nahub recovery status ${operation.id}`);
+}
+
+async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
+  const { one, rest } = takeFlags(args, ["--to"], []);
+  if (rest.some((a) => !["--dry-run", "--yes"].includes(a)) || (kind === "restart" && one["--to"])) fail("usage: ahub upgrade --to <version> [--dry-run] [--yes] | ahub restart [--dry-run] [--yes]");
+  if (kind === "upgrade" && !one["--to"]) fail("upgrade requires --to <exact-version>");
+  if (kind === "upgrade" && selector) fail("upgrade changes the shared package/plugin; omit --project to review all affected running projects");
+  const plan = await makeUpgradePlan(kind, one["--to"] ?? VERSION, kind === "restart" ? cwd : undefined);
+  console.log(JSON.stringify(plan, null, 2));
+  if (args.includes("--dry-run")) return;
+  if (plan.blockers.length || plan.projects.some((p) => p.blockers.length)) fail("plan has blockers; no runtime was changed");
+  assertLifecycleAvailable();
+  if (!args.includes("--yes")) {
+    if (!process.stdin.isTTY) fail("review --dry-run and use --yes in non-interactive sessions");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      if (!/^(y|yes)$/i.test((await rl.question("Apply this project list and restore its sessions? [y/N] ")).trim())) return;
+    } finally { rl.close(); }
+  }
+  const current = await makeUpgradePlan(kind, plan.version, kind === "restart" ? cwd : undefined);
+  if (current.fingerprint !== plan.fingerprint) fail("plan changed during review; run the command again");
+  const sourceRoot = preserveSource(plan);
+  const operation = createOperation(plan, sourceRoot);
+  spawnRecovery(operation);
+}
+
 const commands: Record<string, () => Promise<void> | void> = {
+  upgrade: () => upgrade("upgrade"),
+  restart: () => upgrade("restart"),
+  recovery: async () => {
+    const [action, id] = args;
+    if (args.length !== 2 || !id || !["status", "resume", "abort"].includes(action ?? "")) fail("usage: ahub recovery status|resume|abort <operation-id>");
+    const operation = readOperation<RecoveryOperation>(id);
+    if (action === "status") console.log(JSON.stringify(publicOperation(operation), null, 2));
+    else if (action === "abort") { await abortRecovery(id, makeRecoveryDriver()); console.log("preflight cancelled; no committed transition was rolled back"); }
+    else if (["completed", "cancelled"].includes(operation.phase)) console.log(`recovery is already ${operation.phase}`);
+    else spawnRecovery(operation);
+  },
+  "recovery-run": async () => {
+    if (args.length !== 1 || process.env.AGENTHUB_RECOVERY_OPERATION !== args[0]) fail("recovery-run is an internal command");
+    const result = await runRecovery(args[0]!, makeRecoveryDriver());
+    if (result.phase !== "completed") process.exitCode = 1;
+  },
   help: () => console.log(USAGE),
   "--version": () => console.log(VERSION),
   version: () => console.log(VERSION),
 
+  projects: async () => {
+    if (args[0] === "remove") {
+      if (args.length !== 2) fail("usage: ahub projects remove <id>");
+      const registry = new Registry();
+      try { registry.remove(args[1]!); } finally { registry.close(); }
+      console.log("registration removed; project files were kept");
+      return;
+    }
+    if (args.some((arg) => arg !== "--json")) fail("usage: ahub projects [--json]");
+    await printProjects(args.includes("--json"));
+  },
+
   ui: async () => {
-    if (args.some((arg) => arg !== "--no-open")) fail("usage: ahub ui [--no-open]");
-    const hub = await connect();
-    const res = await hub.request({ t: "ui" }, 10_000);
-    hub.close();
-    if (!res.ok) fail(res.error);
-    if (args.includes("--no-open")) return console.log(res.url);
+    if (args.some((arg) => !["--no-open", "--all", "--stop"].includes(arg))) fail("usage: ahub ui [--all] [--no-open] | --all --stop");
+    if (args.includes("--stop")) {
+      if (!args.includes("--all") || args.includes("--no-open")) fail("usage: ahub ui --all --stop");
+      await stopManager();
+      return console.log("dashboard manager stopped; project hubs were kept running");
+    }
+    let url: string;
+    if (args.includes("--all")) url = await openManager();
+    else {
+      const hub = await connect();
+      try {
+        const res = await hub.request({ t: "ui" }, 10_000);
+        if (!res.ok) fail(res.error);
+        url = res.url;
+      } finally { hub.close(); }
+    }
+    if (args.includes("--no-open")) return console.log(url);
     const opener = process.platform === "darwin" ? "open" : "xdg-open";
-    const opened = spawnSync(opener, [res.url], { stdio: "ignore", timeout: 10_000 });
-    if (opened.error || opened.status !== 0) console.log(`Open this one-time link within 60 seconds:\n${res.url}`);
+    const opened = spawnSync(opener, [url], { stdio: "ignore", timeout: 10_000 });
+    if (opened.error || opened.status !== 0) console.log(`Open this one-time link within 60 seconds:\n${url}`);
     else console.log("Dashboard opened. The session expires in one hour; run ahub ui to reopen it.");
   },
 
+  manager: async () => {
+    const manager = await startManager({ lifecycle });
+    for (const signal of ["SIGINT", "SIGTERM"] as const) process.on(signal, () => void manager.stop());
+    await manager.stopped;
+  },
+
   setup: async () => {
+    assertLifecycleAvailable();
     const root = join(import.meta.dir, "..", "..");
     const state = () => {
       const out = (argv: string[]) => spawnSync("claude", argv, { encoding: "utf8" }).stdout ?? "";
@@ -157,50 +297,33 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   init: () => {
+    assertLifecycleAvailable();
     const changed = init(cwd);
+    registeredProject();
     console.log(changed.length ? changed.map((p) => `wrote ${p}`).join("\n") : "already up to date");
   },
 
-  // Internal: the detached daemon process started by `ahub up`.
+  // Internal: the detached daemon process started by ahub up or the manager.
   daemon: async () => {
-    // Long-lived process: one bad adapter callback must not take every peer down. stderr is hub.log.
     process.on("unhandledRejection", (e) => console.error(`${new Date().toISOString()} unhandled rejection:`, e));
     process.on("uncaughtException", (e) => console.error(`${new Date().toISOString()} uncaught exception:`, e));
-    const base = allocatePorts(cwd);
-    const daemon = await startDaemon({
-      cwd,
-      stateDir,
-      controlPort: base + CONTROL,
-      codexAppPort: base + CODEX_APP,
-      codexProxyPort: base + CODEX_PROXY,
-      switchyardPort: base + SWITCHYARD,
-      unattended: unattendedEnv || args.includes("--unattended"),
-    });
-    for (const sig of ["SIGINT", "SIGTERM"] as const) process.on(sig, () => void daemon.stop());
-    await daemon.stopped;
-    process.exit(0);
+    await runProjectDaemon(registeredProject(), unattendedEnv || args.includes("--unattended"));
   },
 
   up: async () => {
-    if (await healthy()) return console.log("hub is already running");
     const unattended = unattendedEnv || args.includes("--unattended");
     if (unattended) console.error(UNATTENDED_WARNING);
-    mkdirSync(stateDir, { recursive: true });
-    const log = openSync(join(stateDir, "hub.log"), "a");
-    spawn(process.execPath, [import.meta.path, "daemon", ...(unattended ? ["--unattended"] : [])], {
-      cwd,
-      detached: true,
-      stdio: ["ignore", log, log],
-      env: { ...process.env, AGENTHUB_STATE_DIR: stateDir },
-    }).unref();
-    for (let i = 0; i < 50; i++) {
-      if (await healthy()) return console.log(`ahub up (${readControl(stateDir)!.url}), state in ${stateDir}`);
-      await Bun.sleep(100);
-    }
-    fail(`daemon did not start; see ${join(stateDir, "hub.log")}`);
+    const status = await startProject(registeredProject(), { unattended });
+    console.log(`ahub up (ws://127.0.0.1:${status.controlPort}), state in ${stateDir}`);
   },
 
-  claude: () => {
+  claude: async () => {
+    assertLifecycleAvailable();
+    const control = readControl(stateDir);
+    if (control?.instanceId) {
+      process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
+      await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
+    }
     // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
     // project local, then project, then user.
     let original: { command?: string; refreshInterval?: number; padding?: number } | undefined;
@@ -217,11 +340,14 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   codex: async () => {
+    assertLifecycleAvailable();
     const launch0 = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: "pending" }); // refuse bad flags before starting anything
     const hub = await connect();
-    const res = await hub.request({ t: "start", peer: "codex" });
+    const res = await hub.request({ t: "start", peer: "codex", operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
     hub.close();
     if (!res.ok) fail(res.error);
+    const control = readControl(stateDir);
+    if (control?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, control.instanceId);
     const launch = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: res.proxyUrl, codexBin: loadConfig(cwd).codex_bin });
     if (launch0.warning) console.error(launch0.warning);
     exec(launch.cmd, launch.args);
@@ -231,7 +357,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const i = args.indexOf("--model");
     const model = i === -1 ? undefined : args[i + 1] ?? fail("--model needs an alias");
     const hub = await connect();
-    const res = await hub.request({ t: "start", peer: "kimi", args: { model } });
+    const res = await hub.request({ t: "start", peer: "kimi", args: { model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
     hub.close();
     if (!res.ok) fail(res.error);
     console.log(res.already ? "kimi is already attached" : 'kimi attached (headless). Talk to it with: ahub say @kimi "..."');
@@ -240,7 +366,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   local: async () => {
     const opt = (flag: string) => (args.includes(flag) ? args[args.indexOf(flag) + 1] ?? fail(`${flag} needs a value`) : undefined);
     const hub = await connect();
-    const res = await hub.request({ t: "start", peer: "local", args: { route: opt("--route"), model: opt("--model") } });
+    const res = await hub.request({ t: "start", peer: "local", args: { route: opt("--route"), model: opt("--model") }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
     hub.close();
     if (!res.ok) fail(res.error);
     console.log(res.already ? "local is already attached" : `local attached on ${res.model}. Give it work with: ahub say @local "..."`);
@@ -370,6 +496,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   status: async () => {
+    if (args.includes("--all")) return printProjects(args.includes("--json"));
     const hub = await connect();
     const { status } = await hub.request({ t: "status" });
     hub.close();
@@ -385,23 +512,16 @@ const commands: Record<string, () => Promise<void> | void> = {
   logs: () => exec("tail", [args.includes("-f") ? "-f" : "-n100", join(stateDir, "hub.log")]),
 
   kill: async () => {
-    const hub = await connect().catch(() => undefined);
-    if (hub) {
-      hub.send({ t: "kill" });
-      await new Promise<void>((r) => (hub.onClose = () => r()));
-      return console.log("hub stopped");
-    }
-    const pidFile = join(stateDir, "hub.pid");
-    if (!existsSync(pidFile)) return console.log("hub is not running");
-    // The pid file may be stale and the pid reused: signal it only if it still is a hub daemon.
-    const pid = Number(readFileSync(pidFile, "utf8"));
-    const owner = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" }).stdout ?? "";
-    if (/main\.ts daemon|ahub daemon/.test(owner)) {
-      process.kill(pid, "SIGTERM");
-      return console.log("hub signalled");
+    const registry = new Registry();
+    let project: Project | undefined;
+    try { project = registry.list().find((p) => p.root === cwd && p.stateDir === stateDir); }
+    finally { registry.close(); }
+    if (!project) {
+      if (!readControl(stateDir) && !existsSync(join(stateDir, "hub.pid"))) return console.log("hub is not running");
+      fail("hub has no matching registration; use its matching CLI to stop it before upgrading");
     }
-    for (const f of ["hub.pid", "status.json", "control-token"]) rmSync(join(stateDir, f), { force: true });
-    console.log("hub is not running (removed stale state files)");
+    await stopProject(project);
+    console.log("hub stopped");
   },
 
   doctor: async () => {

package/src/cli/recovery-package.ts

@@ -0,0 +1,99 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hubHome } from "../hub/project.ts";
+
+export type CommandResult = { code: number; stdout: string; stderr: string };
+export type RunCommand = (args: string[], options?: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }) => Promise<CommandResult>;
+export const runCommand: RunCommand = (args, options = {}) => new Promise((resolve, reject) => {
+  const child = spawn(args[0]!, args.slice(1), { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"] });
+  let stdout = "", stderr = "", exceeded = false;
+  const append = (old: string, value: unknown) => {
+    const next = old + String(value);
+    if (next.length > 2_000_000) { exceeded = true; child.kill("SIGTERM"); }
+    return next.slice(-2_000_000);
+  };
+  child.stdout.on("data", (v) => { stdout = append(stdout, v); });
+  child.stderr.on("data", (v) => { stderr = append(stderr, v); });
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); }, options.timeoutMs ?? 60_000);
+  const hardTimer = setTimeout(() => child.kill("SIGKILL"), (options.timeoutMs ?? 60_000) + 3000);
+  child.on("error", (e) => { clearTimeout(timer); clearTimeout(hardTimer); reject(e); });
+  child.on("close", (code) => {
+    clearTimeout(timer); clearTimeout(hardTimer);
+    if (timedOut || exceeded) reject(new Error(`command ${args[0]} ${timedOut ? "timed out" : "exceeded output limit"}; inspect state before retrying`));
+    else resolve({ code: code ?? 1, stdout, stderr });
+  });
+});
+
+export function exactVersion(version: string): string {
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) throw new Error("--to requires an exact package version");
+  return version;
+}
+
+export function packageDigest(root: string): string {
+  const hash = createHash("sha256");
+  const visit = (directory: string, prefix = "") => {
+    for (const item of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (item.isSymbolicLink()) throw new Error("runtime package must not contain symlinks");
+      const name = `${prefix}${item.name}`;
+      if (item.isDirectory()) visit(join(directory, item.name), `${name}/`);
+      else { hash.update(name); hash.update("\0"); hash.update(readFileSync(join(directory, item.name))); hash.update("\0"); }
+    }
+  };
+  // Only runtime assets; never copy or hash a checkout's private state or dependencies.
+  for (const name of ["src", "plugins", "templates", ".claude-plugin"]) visit(join(root, name), `${name}/`);
+  hash.update(readFileSync(join(root, "package.json")));
+  return hash.digest("hex");
+}
+
+export function verifyPackage(root: string, version: string): string {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const plugin = JSON.parse(readFileSync(join(root, "plugins/agent-hub/.claude-plugin/plugin.json"), "utf8"));
+  if (pkg.name !== "@staix/agent-hub" || pkg.version !== version || plugin.version !== version ||
+      !existsSync(join(root, "src/cli/main.js"))) throw new Error("staged package identity/version mismatch");
+  return packageDigest(root);
+}
+
+export async function registryRelease(version: string, run: RunCommand = runCommand): Promise<{ version: string; integrity: string }> {
+  exactVersion(version);
+  const result = await run(["npm", "view", `@staix/agent-hub@${version}`, "version", "dist.integrity", "--json"], { timeoutMs: 30_000 });
+  if (result.code !== 0) throw new Error(`registry metadata unavailable for @staix/agent-hub@${version}`);
+  const data = JSON.parse(result.stdout);
+  if (data.version !== version || typeof data["dist.integrity"] !== "string" || !data["dist.integrity"].startsWith("sha512-")) {
+    throw new Error("registry returned an unexpected release identity");
+  }
+  return { version, integrity: data["dist.integrity"] };
+}
+
+/** Stage outside the mutable global install; retain successful versions for recovery. */
+export async function stageRelease(version: string, integrity: string, run: RunCommand = runCommand, home = hubHome()): Promise<{ root: string; digest: string }> {
+  exactVersion(version);
+  const base = join(home, "releases");
+  const destination = join(base, version);
+  const root = join(destination, "node_modules/@staix/agent-hub");
+  if (existsSync(destination)) {
+    const saved = JSON.parse(readFileSync(join(destination, "verified.json"), "utf8"));
+    const digest = verifyPackage(root, version);
+    if (saved.integrity !== integrity || saved.digest !== digest) throw new Error("cached release changed; refusing it");
+    return { root, digest };
+  }
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  const temporary = join(base, `.stage-${randomUUID()}`);
+  mkdirSync(temporary, { mode: 0o700 });
+  try {
+    writeFileSync(join(temporary, "package.json"), JSON.stringify({ private: true, dependencies: { "@staix/agent-hub": version } }));
+    const install = await run([process.execPath, "install", "--ignore-scripts", "--cwd", temporary], { timeoutMs: 180_000 });
+    if (install.code !== 0) throw new Error("package staging failed; installed runtime was not changed");
+    const staged = join(temporary, "node_modules/@staix/agent-hub");
+    const digest = verifyPackage(staged, version);
+    // Bun's lock records the registry integrity actually used, not a later metadata query.
+    const lock = JSON.parse(readFileSync(join(temporary, "bun.lock"), "utf8").replace(/,\s*([}\]])/g, "$1"));
+    const row = lock.packages?.["@staix/agent-hub"];
+    if (!Array.isArray(row) || !row.includes(integrity)) throw new Error("staged package integrity differs from the reviewed release");
+    writeFileSync(join(temporary, "verified.json"), JSON.stringify({ integrity, digest }), { mode: 0o600 });
+    renameSync(temporary, destination);
+    return { root, digest };
+  } finally { rmSync(temporary, { recursive: true, force: true }); }
+}

package/src/cli/statusline-tee.ts

@@ -4,13 +4,14 @@
 // user's own status line command: it records the limits for the hub's budget coordinator and then runs the original
 // command with the same input, so the status line looks exactly as before. It must never fail the render.
 import { spawnSync } from "node:child_process";
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const input = await Bun.stdin.text();
 let own = "";
 try {
-  const limits = JSON.parse(input).rate_limits;
+  const parsed = JSON.parse(input);
+  const limits = parsed.rate_limits;
   const pct = (w: any) => (typeof w?.used_percentage === "number" ? `${Math.round(w.used_percentage)}%` : "-");
   if (limits) own = `agent-hub  5h ${pct(limits.five_hour)}  wk ${pct(limits.seven_day)}`;
   const dir = process.env.AGENTHUB_STATE_DIR;
@@ -20,6 +21,14 @@ try {
     writeFileSync(`${file}.tmp`, JSON.stringify({ at: Date.now(), rate_limits: limits }));
     renameSync(`${file}.tmp`, file);
   }
+  const sessionId = typeof parsed.session_id === "string" ? parsed.session_id : typeof parsed.sessionId === "string" ? parsed.sessionId : "";
+  if (sessionId && dir) {
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "claude-session.json");
+    writeFileSync(`${file}.tmp`, JSON.stringify({ at: Date.now(), sessionId, ...(process.env.AGENTHUB_INSTANCE_ID ? { instanceId: process.env.AGENTHUB_INSTANCE_ID } : {}), ...(process.env.AGENTHUB_LAUNCH_ID ? { launchId: process.env.AGENTHUB_LAUNCH_ID } : {}) }), { mode: 0o600 });
+    chmodSync(`${file}.tmp`, 0o600);
+    renameSync(`${file}.tmp`, file);
+  }
 } catch {
   // not JSON, or the state dir is gone: the status line still has to render
 }