@staix/agent-hub 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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).

package/README.md

@@ -4,9 +4,16 @@ Native multi-agent hub for one developer's machine: Claude Code, Codex, Kimi Cod
 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.4.0. 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.4.0 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.5.0 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.4.0",
+  "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.4.0",
+  "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

@@ -15615,7 +15615,7 @@ function projectContext(cwd, env = process.env) {
 function stateDirFor(cwd) {
   return projectContext(cwd).stateDir;
 }
-var PROTOCOL = 7;
+var PROTOCOL = 8;
 function readControl(stateDir) {
   try {
     const status = JSON.parse(readFileSync2(join2(stateDir, "status.json"), "utf8"));
@@ -15724,7 +15724,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.4.0",
+  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/src/adapters/acp.ts

@@ -2,7 +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";
+import { childEnv, stopOwnedProcess } from "../hub/child-process.ts";
 
 export interface PermissionOption {
   optionId: string;
@@ -18,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 }[] }[];
@@ -52,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}`));

package/src/adapters/codex-appserver.ts

@@ -2,7 +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";
+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>`. */
@@ -21,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;
 }
@@ -64,6 +66,13 @@ 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}`;
   }
@@ -209,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()}`));

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");

package/src/cli/main.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { ControlClient, readControl } from "../hub/control-client.ts";
@@ -17,6 +17,11 @@ 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
 
@@ -29,6 +34,9 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   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
@@ -65,13 +73,13 @@ const [cmd = "help", ...args] = argv;
 let selected: { root: string; stateDir: string };
 try {
   if (selector) {
-    const registry = new Registry();
-    try {
-      const known = registry.get(selector);
+    const projects = registeredProjects();
+    {
+      const known = projects.find((p) => p.id === selector);
       const context = known ?? projectContext(selector, {});
-      const registered = known ?? registry.list().find((p) => p.root === context.root);
+      const registered = known ?? projects.find((p) => p.root === context.root);
       selected = registered ?? context;
-    } finally { registry.close(); }
+    }
   } else selected = projectContext(process.cwd());
 } catch (error) { fail((error as Error).message); }
 const cwd = selected.root;
@@ -95,7 +103,7 @@ async function healthy(): Promise<boolean> {
 }
 
 function exec(bin: string, argv: string[]): never {
-  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...process.env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+  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);
 }
@@ -166,7 +174,56 @@ 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),
@@ -214,6 +271,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   setup: async () => {
+    assertLifecycleAvailable();
     const root = join(import.meta.dir, "..", "..");
     const state = () => {
       const out = (argv: string[]) => spawnSync("claude", argv, { encoding: "utf8" }).stdout ?? "";
@@ -239,6 +297,7 @@ 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");
@@ -258,7 +317,13 @@ const commands: Record<string, () => Promise<void> | void> = {
     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;
@@ -275,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);
@@ -289,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 "..."');
@@ -298,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 "..."`);

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
 }