@staix/agent-hub 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.6.1
+
+- Preserve Pi session identity when handing an empty native session between headless and TUI modes (#27).
+- Keep recovery metadata and native terminal restoration bound to the verified project session.
+
 ## 0.6.0
 
 - Pi peer with managed local model routing, RPC and native terminal integration (#25).

package/README.md

@@ -4,7 +4,7 @@ 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.6.0. All six milestones of the design spec are implemented; the [smoke checklist](docs/smoke.md)
+Status: 0.6.1. 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).
@@ -29,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.6.0 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.6.1 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.
@@ -99,7 +99,9 @@ does not stop MLX. The relay can fall back from MLX to DGX before streaming
 starts. Inspect `ahub status` for requested routes and reported backend models.
 
 A project has one managed Pi session owner. Mode changes require the agent to
-settle and preserve the session file. Protocol 9 adds Pi recovery metadata;
+settle and preserve the session file. Before the first generation, a live source
+verified to be empty can instead retain its exact session ID without a file.
+Missing history from a nonempty session blocks handover. Protocol 9 adds Pi recovery metadata;
 protocol-8 hubs can use controlled upgrade, while protocols 5-7 still require
 their matching CLI and an attended bootstrap.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference 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.6.0",
+  "version": "0.6.1",
   "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

@@ -15726,7 +15726,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.6.0",
+  version: "0.6.1",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",

package/src/adapters/pi.ts

@@ -20,6 +20,7 @@ export interface PiOptions {
 }
 export interface PiTuiLaunch { cmd: string; args: string[]; env: NodeJS.ProcessEnv; }
 type RpcMessage = { type?: string; id?: string | number; command?: string; success?: boolean; data?: any; [key: string]: any };
+type VerifiedEmptyResume = { sessionId: string };
 function processSignature(pid: number): string | undefined { try { const result = Bun.spawnSync(["ps", "-p", String(pid), "-o", "lstart=,comm="], { stdout: "pipe", stderr: "pipe" }); if (result.exitCode !== 0) return undefined; const text = result.stdout.toString().trim(); return text ? new Bun.CryptoHasher("sha256").update(text).digest("hex") : undefined; } catch { return undefined; } }
 function ownerStillAlive(pid: number, signature: string | undefined): boolean { const current = processSignature(pid); if (current !== undefined) return current === signature; try { process.kill(pid, 0); return true; } catch { return false; } }
 
@@ -43,6 +44,10 @@ export class PiPeer extends BasePeer {
   private currentReply?: Envelope;
   private sessionId = "";
   private sessionFile = "";
+  private emptyResumeVerified = false;
+  private verifiedEmptyResume?: VerifiedEmptyResume;
+  private activityObserved = false;
+  private persistedOnce = false;
   private activeEnvs: Envelope[] = [];
   private activeTools = 0;
   private agentRunning = false;
@@ -64,15 +69,60 @@ export class PiPeer extends BasePeer {
 
   constructor(id: PeerId, private readonly opts: PiOptions) { super(id, opts.watchdogMs); }
   get tuiLaunch(): PiTuiLaunch | undefined { return this._tuiLaunch; }
+  get pendingResume(): { sessionId?: string; sessionFile?: string } {
+    if (this.canReuseVerifiedEmptyResume()) return { sessionId: this.verifiedEmptyResume!.sessionId };
+    return { sessionId: this.opts.sessionId, sessionFile: this.opts.sessionFile };
+  }
   get acceptingTools(): boolean { return !this.stopping; }
   /** Idle verified owners can be stopped; uncertain live owners and pending launches stay fenced. */
   get recoveryReady(): boolean {
     if (this.state === "busy" || this.starting || this.activeTools) return false;
-    if (this.opts.mode === "headless") return this.state === "idle" || !this.proc || this.proc.exitCode !== null;
+    if (this.sessionFile && !existsSync(this.sessionFile) && (this.activityObserved || this.persistedOnce)) return false;
+    if (this.opts.mode === "headless") return this.state === "idle" || !this.proc || this.proc.exitCode !== null || this.proc.signalCode !== null;
     if (this.state === "idle") return this.ownerClaimed && !!this.ownerPid && processSignature(this.ownerPid) === this.ownerSignature;
     return this.stopping && !this.ownerClaimed && (!this.ownerPid || !ownerStillAlive(this.ownerPid, this.ownerSignature));
   }
-  recoveryMetadata(): Record<string, unknown> { return { launch: { kind: "pi", cwd: this.opts.cwd, mode: this.opts.mode, backend: this.opts.backend, ...(this.opts.model ? { model: this.opts.model } : {}), ...(this.sessionFile ? { sessionFile: this.sessionFile } : {}) }, ...(this.sessionId ? { sessionId: this.sessionId } : {}), ...(this.sessionFile ? { sessionFile: this.sessionFile } : {}) }; }
+  recoveryMetadata(): Record<string, unknown> {
+    const exists = !!this.sessionFile && existsSync(this.sessionFile);
+    if (exists) { this.persistedOnce = true; this.verifiedEmptyResume = undefined; }
+    const empty = this.emptyResumeVerified && !this.activityObserved && !this.persistedOnce;
+    const file = this.sessionFile && (exists || !empty) ? this.sessionFile : undefined;
+    return { launch: { kind: "pi", cwd: this.opts.cwd, mode: this.opts.mode, backend: this.opts.backend, ...(this.opts.model ? { model: this.opts.model } : {}), ...(file ? { sessionFile: file } : {}) }, ...(this.sessionId ? { sessionId: this.sessionId } : {}), ...(file ? { sessionFile: file } : {}) };
+  }
+
+  /** Verify the live source before choosing ID-only restoration. Never infer emptiness from a missing file. */
+  async captureResume(): Promise<Record<string, unknown>> {
+    if (this.state === "offline") {
+      if (this.canReuseVerifiedEmptyResume()) return this.recoveryMetadata();
+      if (this.recoveryReady && this.sessionFile && existsSync(this.sessionFile)) return this.recoveryMetadata();
+      throw new Error("Pi source session is offline and has no verified persisted resume state");
+    }
+    this.emptyResumeVerified = false;
+    if (this.state !== "idle" || this.stopping || this.activeTools) throw new Error("Pi must settle before session capture");
+    if (this.sessionFile && existsSync(this.sessionFile)) return this.recoveryMetadata();
+    const snapshot = this.opts.mode === "headless"
+      ? (await this.waitRpc("get_state", 15_000)).data
+      : await this.sendTui({ type: "get_session_state" });
+    if (this.state !== "idle" || this.activeTools || snapshot?.sessionId !== this.sessionId || snapshot?.sessionFile !== this.sessionFile) throw new Error("Pi source session changed during capture");
+    const empty = this.opts.mode === "headless"
+      ? snapshot.messageCount === 0 && snapshot.pendingMessageCount === 0 && snapshot.isStreaming === false && snapshot.isCompacting !== true && !snapshot.sessionName
+      : snapshot.empty === true && snapshot.idle === true;
+    if (!empty || this.activityObserved || this.persistedOnce) throw new Error("Pi session history is not persisted; refusing to recreate it");
+    this.emptyResumeVerified = true;
+    const captured = this.recoveryMetadata();
+    if (typeof captured.sessionId === "string" && !captured.sessionFile) this.verifiedEmptyResume = { sessionId: captured.sessionId };
+    return captured;
+  }
+
+  private canReuseVerifiedEmptyResume(): boolean {
+    return !!this.verifiedEmptyResume && this.recoveryReady && !this.activityObserved && !this.persistedOnce && this.sessionId === this.verifiedEmptyResume.sessionId && (!this.sessionFile || !existsSync(this.sessionFile));
+  }
+
+  private noteActivity(): void {
+    this.activityObserved = true;
+    this.emptyResumeVerified = false;
+    this.verifiedEmptyResume = undefined;
+  }
 
   async start(): Promise<void> {
     if (this.starting) return this.starting;
@@ -112,6 +162,7 @@ export class PiPeer extends BasePeer {
       }
       if (url.pathname === "/tool") {
         if (this.stopping || this.state === "offline") return Response.json({ text: "error: Pi owner is stopped" }, { status: 409 });
+        this.noteActivity();
         this.activeTools++;
         if (this.state === "idle") this.setState("busy");
         if (this.state === "busy") this.touch();
@@ -148,6 +199,7 @@ export class PiPeer extends BasePeer {
       throw new Error("Pi get_state session identity does not match the requested recovery session");
     }
     this.sessionId = state.data.sessionId; this.sessionFile = state.data.sessionFile;
+    this.persistedOnce = existsSync(this.sessionFile);
     if ((this.opts.sessionId && this.sessionId !== this.opts.sessionId) || (this.opts.sessionFile && this.sessionFile !== this.opts.sessionFile)) throw new Error("Pi startup session identity mismatch");
     this.setState("idle");
   }
@@ -194,6 +246,7 @@ export class PiPeer extends BasePeer {
     try {
       const requested = await this.opts.selectModel?.(envs);
       if (requested) await this.setRequestedModel(requested);
+      this.noteActivity();
       attempted = true;
       if (this.opts.mode === "tui") await this.sendTui({ type: "prompt", message: renderDigest(envs, true) });
       else await this.sendRpc({ type: "prompt", message: renderDigest(envs, true) });
@@ -235,7 +288,7 @@ export class PiPeer extends BasePeer {
       this.startOwnerMonitor(); if (this.opts.mode === "tui") this.setState("idle");
     }
     if (event.type === "session_shutdown") { this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor(); this.resolveTuiExit?.(); this.resolveTuiExit = undefined; this.setState("offline"); }
-    if (event.type === "agent_start") { this.agentRunning = true; this.setState("busy"); }
+    if (event.type === "agent_start") { this.noteActivity(); this.agentRunning = true; this.setState("busy"); }
     if (event.type === "activity" && this.state === "busy") this.touch();
     if (event.type === "agent_end") {
       this.settledText = typeof event.text === "string" ? event.text : "";

package/src/hub/daemon.ts

@@ -558,7 +558,7 @@ export async function startDaemon(opts: DaemonOptions) {
     }
     const existing = bus.peers.get(peer);
     if (peer === "pi" && existing instanceof PiPeer) {
-      const saved = existing.recoveryMetadata();
+      let saved = existing.recoveryMetadata();
       const launch = saved.launch as Record<string, unknown>;
       if ((args.sessionId && saved.sessionId && args.sessionId !== saved.sessionId) || (args.sessionFile && saved.sessionFile && args.sessionFile !== saved.sessionFile)) return { ok: false, error: "Pi already owns a different session; refusing to replace its identity" };
       const mode = args.mode ?? "headless";
@@ -566,17 +566,20 @@ export async function startDaemon(opts: DaemonOptions) {
       const unclaimed = existing.state === "offline" && !saved.sessionId && !saved.sessionFile;
       if (changesOwner && (existing.state === "busy" || (existing.state !== "offline" && !existing.recoveryReady))) return { ok: false, error: "Pi is busy; wait for agent_settled before changing mode/backend" };
       if (unclaimed) {
+        if (!args.sessionId && !args.sessionFile) args = { ...args, ...existing.pendingResume };
         // Revoke the previous launch bridge before issuing another launch. A late
         // process from the abandoned CLI cannot claim the replacement owner.
         await existing.stop();
       } else if (changesOwner) {
-        if (!saved.sessionId || !saved.sessionFile) return { ok: false, error: "Pi session identity is not ready for handover" };
-        args = { ...args, backend: args.backend ?? launch.backend as "auto" | "dgx" | "mlx", model: args.model ?? (args.backend === undefined && typeof launch.model === "string" ? launch.model : undefined), sessionId: String(saved.sessionId), sessionFile: String(saved.sessionFile) };
+        saved = await existing.captureResume();
+        if (!saved.sessionId) return { ok: false, error: "Pi session identity is not ready for handover" };
+        args = { ...args, backend: args.backend ?? launch.backend as "auto" | "dgx" | "mlx", model: args.model ?? (args.backend === undefined && typeof launch.model === "string" ? launch.model : undefined), sessionId: String(saved.sessionId), sessionFile: typeof saved.sessionFile === "string" ? saved.sessionFile : undefined };
         await existing.stop();
       } else if (existing.state !== "offline") {
         return mode === "tui" ? { ok: false, error: "Pi already owns a native terminal; use that terminal or switch to headless first" } : { ok: true, already: true };
-      } else if (saved.sessionId && saved.sessionFile) {
-        args = { ...args, backend: args.backend ?? launch.backend as "auto" | "dgx" | "mlx", model: args.model ?? (args.backend === undefined && typeof launch.model === "string" ? launch.model : undefined), sessionId: String(saved.sessionId), sessionFile: String(saved.sessionFile) };
+      } else if (saved.sessionId) {
+        saved = await existing.captureResume();
+        args = { ...args, backend: args.backend ?? launch.backend as "auto" | "dgx" | "mlx", model: args.model ?? (args.backend === undefined && typeof launch.model === "string" ? launch.model : undefined), sessionId: String(saved.sessionId), sessionFile: typeof saved.sessionFile === "string" ? saved.sessionFile : undefined };
       }
     }
     if (existing && existing.state !== "offline") {
@@ -847,6 +850,12 @@ export async function startDaemon(opts: DaemonOptions) {
   async function recoveryOp(msg: any): Promise<Record<string, unknown>> {
     if (typeof msg.op !== "string" || !["inspect", "prepare", "commit", "abort", "release"].includes(msg.op)) return recoveryError("unknown recovery operation");
     if (typeof msg.expectedInstanceId !== "string" || msg.expectedInstanceId !== instanceId) return recoveryError("expected daemon instance does not match");
+    if (msg.op === "inspect" || msg.op === "prepare" || msg.op === "commit") {
+      const pi = bus.peers.get("pi");
+      if (pi instanceof PiPeer && pi.state === "idle") {
+        try { await pi.captureResume(); } catch (error) { return recoveryError((error as Error).message); }
+      }
+    }
     if (msg.op === "inspect" && msg.operationId === undefined) return { t: "recovery", ok: true, recovery: recoveryView() };
     if (typeof msg.operationId !== "string" || msg.operationId.length < 1 || msg.operationId.length > 128) return recoveryError("operationId is required");
     const op = msg.operationId as string;

package/src/pi/extension.ts

@@ -39,6 +39,15 @@ async function poll(pi: ExtensionAPI): Promise<void> {
       try {
         if (command.type === "prompt" || command.type === "steer") {
           pi.sendMessage({ customType: "agent-hub", content: String(command.message ?? ""), display: true }, { triggerTurn: command.type === "prompt", deliverAs: command.type === "steer" ? "steer" : "followUp" });
+        } else if (command.type === "get_session_state") {
+          const entries = runtimeCtx.sessionManager.getEntries();
+          await post("/ack", { id: command.id, ok: true, result: {
+            sessionId: runtimeCtx.sessionManager.getHeader()?.id,
+            sessionFile: runtimeCtx.sessionManager.getSessionFile(),
+            idle: runtimeCtx.isIdle() === true,
+            empty: entries.every((entry: any) => ["model_change", "thinking_level_change"].includes(entry.type)),
+          } });
+          continue;
         } else if (command.type === "set_model") {
           const model = modelRegistry?.find(String(command.provider), String(command.modelId));
           if (!model || !(await (pi as any).setModel?.(model))) throw new Error("Pi model is not available");