@staix/agent-hub 0.7.3 → 0.7.5

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.7.5
+
+- A zero-turn Claude session no longer wedges an upgrade after restore either: the commit snapshot records whether the session ever persisted a transcript, coordinator verification re-derives persistence from the terminal binding exactly like the restore gate did, and daemon readiness tolerates a fresh session while the original transcript is absent (snapshots from older sources are re-derived from disk). A session with a transcript keeps the strict identity check in all three places. The status line tee now records the transcript path Claude reports (#64).
+
+## 0.7.4
+
+- A Claude session that never persisted a transcript (zero turns) no longer wedges an upgrade at restore: when the original transcript is absent, the coordinator accepts the fresh session the operator attached, because nothing was preserved and nothing is lost. Sessions with a transcript keep the strict identity check; Codex stays strict in all cases (#21).
+
 ## 0.7.3
 
 - A peer that detaches mid-upgrade no longer wedges the recovery: readiness ignores a now-offline peer's stale identity (a reattach with a different thread still blocks), an already-exited terminal is closed as a no-op instead of being waited on, and resume can drive the operation to release once the peer returns (#21).

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.7.3, control protocol 10. Durable delivery records distinguish queued
+Status: 0.7.5, control protocol 10. Durable delivery records distinguish queued
 work from uncertain execution. The [smoke checklist](docs/smoke.md) records
 verified paths and remaining prerequisites.
 
@@ -28,7 +28,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.7.3 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.7.5 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.7.3 and control protocol 10. Live verification
+This guide describes ahub 0.7.5 and control protocol 10. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Install and start
@@ -182,27 +182,27 @@ For an upgrade from 0.6.4 (protocol 9) or 0.7.0, use the patched coordinator wit
 replacing the global CLI prematurely. Run from the project directory:
 
 ```bash
-bunx --package @staix/agent-hub@0.7.3 ahub upgrade --to 0.7.3 --dry-run
-bunx --package @staix/agent-hub@0.7.3 ahub upgrade --to 0.7.3 --yes
+bunx --package @staix/agent-hub@0.7.5 ahub upgrade --to 0.7.5 --dry-run
+bunx --package @staix/agent-hub@0.7.5 ahub upgrade --to 0.7.5 --yes
 ```
 
 The coordinator verifies and retains the exact target package, preserves its
 own source, and promotes the global CLI only after restored projects pass
 readback. Do not use the old protocol-9 coordinator to target protocol 10.
 
-Once the installed CLI is 0.7.3, review the current project or all registered
+Once the installed CLI is 0.7.5, review the current project or all registered
 projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.7.3 --dry-run
+ahub upgrade --to 0.7.5 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.7.3 --yes
+ahub upgrade --to 0.7.5 --yes
 ahub recovery status <operation-id>
 ahub recovery resume <operation-id>
 ahub recovery abort <operation-id>
@@ -219,6 +219,9 @@ package digest, terminal binding, and phase receipt. An uncertain terminal
 creation is never repeated blindly. If Claude shows its development-channel confirmation screen, confirm it in
 the captured terminal, then run `ahub recovery resume <operation-id>`; resume must not open a duplicate terminal.
 Kimi and local sessions may start fresh with preserved routing and task context.
+A Claude session that never persisted a transcript (zero turns) also starts fresh:
+there is nothing to resume, so the upgrade accepts the new session id; a session
+with a transcript must come back with its original id.
 Previously stopped projects stay stopped; only the reviewed running projects
 are upgraded.
 

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the Claude Code channel plu
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.7.3
+bun add -g github:STAIxBWLB/agent-hub#v0.7.5
 ahub setup
 ```
 

package/docs/smoke.md

@@ -629,3 +629,67 @@ A source-build smoke on Apple silicon/macOS 27.0 with Ollama 0.34.2 verified:
 The live harness is opt-in and is not called by the hermetic repository
 check. `AHUB_SMOKE_PROJECT` selects a project configuration without starting
 its daemon or replaying its queue. It deliberately forbids remote inference.
+
+
+## 0.7.2-0.7.4 attended upgrade smoke (issue #21, 2026-09-27)
+
+Attended registry package/plugin upgrade on a scratch project
+(`~/ahub-smoke`, Orca-managed worktree) with claude, codex and kimi attached
+to a 0.7.1 hub installed from npm. Pre-upgrade state: task #1 in_progress
+(owner codex, reviewer claude), kimi manually paused with one important
+envelope queued, live Claude session and live Codex thread captured by the
+dry-run plan. This run closes the attended leg left open by the 0.7.1
+cutover; it also exposed three recovery defects that became 0.7.3 and 0.7.4.
+
+### What the runs proved
+
+- The coordinator blocked safely, twice, when the Codex TUI detached
+  mid-prepare: "no terminal was closed", the 0.7.1 source kept running, and
+  the board, pause and queue were verified unchanged afterwards. Blocked
+  operations were resumable or cleanly resolvable once their cause was
+  removed.
+- The fifth attempt (0.7.3 coordinator, codex offline at plan time) drove
+  prepare, commit, source stop, staged-target start and native peer restore
+  without operator intervention; the new daemon reported version 0.7.3 with
+  a new instanceId, kimi still paused with its queued envelope intact, and
+  the task board unchanged. Claude restoration paused at the documented
+  attended step (development-channel confirmation in the captured terminal),
+  then resumed.
+- Final state after completion: daemon, CLI and plugin all 0.7.4
+  (pid 12483, new instanceId, protocol 10), claude idle, kimi idle with
+  queued 0. The important envelope queued at 03:16 on 0.7.1 was delivered
+  after resume and answered by kimi at 04:53 ("Received the upgrade
+  preservation check envelope"). Task #1 remains in_progress on the board.
+
+### Defects found and fixed by this smoke
+
+- A peer detaching between prepare and commit wedged the operation:
+  readiness never recovered, resume refused, abort refused. Fixed in 0.7.3
+  (PR #60): an offline peer no longer fails the identity comparison, and an
+  already-exited terminal closes as a no-op.
+- A zero-turn Claude session (no transcript on disk) made restore fail with
+  "No conversation found" and wedged the pending-restore identity gate.
+  Fixed in 0.7.4 (PR #62): with the original transcript absent, a fresh
+  operator-attached session is accepted.
+- The same zero-turn case still cannot pass the coordinator's verify step
+  or the daemon's release gate; tracked as issue #64. This operation was
+  completed manually (restart snapshot removed, daemon restarted), which is
+  an operator action, not a designed path.
+
+### Environmental limits recorded
+
+- An active native Codex TUI could not be kept alive on this machine: the
+  Orca runtime closed three `ahub codex` terminals in-process
+  (`origin: in-process`, `ptyKilled: true`) 35-90 seconds after each attach,
+  while the Claude terminal survived. The Codex leg therefore ran with
+  codex offline at plan time, as in the 0.7.1 cutover; this run does not
+  claim an active native Codex TUI restoration either.
+- The recovery runner for an existing operation always executes the
+  operation's preserved source, so a coordinator fix released after an
+  operation was created does not reach that operation's resume. The
+  sourceRoot digest guard correctly refused a hand-patched receipt.
+- `ahub setup` is interactive (one confirmation gates all steps); piping an
+  answer works, running it detached does not.
+
+Issue [#12](https://github.com/STAIxBWLB/agent-hub/issues/12) remains open
+for off-campus Access credentials and a natural near-limit budget pause.

package/package.json

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

@@ -15727,7 +15727,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.7.3",
+  version: "0.7.5",
   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/cli/statusline-tee.ts

@@ -25,7 +25,10 @@ try {
   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 });
+    // The transcript path lets the hub tell a zero-turn session (file not yet created, so
+    // `claude --resume` can never work) from one whose conversation must be preserved (#64).
+    const transcriptPath = typeof parsed.transcript_path === "string" && parsed.transcript_path ? parsed.transcript_path : undefined;
+    writeFileSync(`${file}.tmp`, JSON.stringify({ at: Date.now(), sessionId, ...(transcriptPath ? { transcriptPath } : {}), ...(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);
   }

package/src/cli/upgrade-runtime.ts

@@ -1,4 +1,5 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS, readControl } from "../hub/control-client.ts";
@@ -13,6 +14,17 @@ 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");
 
+/**
+ * Claude Code persists a transcript at projects/<slug>/<sessionId>.jsonl under its config
+ * dir, creating the project directory only with the first persisted turn; the slug replaces
+ * every non-alphanumeric character of the project root with '-'.
+ */
+function claudeTranscriptExists(binding: TerminalBinding): boolean {
+  const config = binding.launch.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+  const slug = binding.projectRoot.replace(/[^a-zA-Z0-9]/g, "-");
+  return existsSync(join(config, "projects", slug, `${binding.sessionId}.jsonl`));
+}
+
 function terminalOptions(run: RunCommand = runCommand): TerminalRecoveryOptions {
   return { orcaExecutable: orcaExecutable(), runner: async (args) => {
     const result = await run([orcaExecutable(), ...args], { timeoutMs: 610_000 });
@@ -286,10 +298,20 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
         if (progress.terminals[key] === "pending") {
           const observed = await inspectRecovery(planned.project);
           const peer = observed.peers.find((p) => p.id === original.peer);
-          if ((original.peer === "codex" ? peer?.threadId : peer?.sessionId) !== original.sessionId) {
-            throw new Error(`${original.peer}: terminal creation outcome is uncertain; attach the original session manually, then resume`);
+          const attached = original.peer === "codex" ? peer?.threadId : peer?.sessionId;
+          let expected = original;
+          if (attached !== original.sessionId) {
+            // #21: a Claude session that never got a first turn has no transcript on disk,
+            // so `claude --resume S` can never succeed and nothing it stood for is lost by
+            // accepting the fresh attach. A session WITH a transcript keeps the strict
+            // identity check. Codex stays strict too: its rollout jsonl is written when the
+            // thread starts, so an unrestorable thread should not exist.
+            if (original.peer !== "claude" || !peer || peer.state === "offline" || !attached || claudeTranscriptExists(original)) {
+              throw new Error(`${original.peer}: terminal creation outcome is uncertain; attach the original session manually, then resume`);
+            }
+            expected = { ...original, sessionId: attached };
           }
-          const existing = await revalidateTerminal(planned, progress, original, false);
+          const existing = await revalidateTerminal(planned, progress, expected, false);
           progress.terminals[key] = existing; save(); continue;
         }
         const entrypoint = join(op.targetRoot!, "src/cli/main.js");
@@ -330,7 +352,13 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
         const peer = live.peers.find((p) => p.id === old.id);
         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 === "claude" && peer.sessionId !== old.sessionId) {
+          // #64: the restore gate already accepted a fresh session when the original never
+          // persisted a transcript. Re-derive persistence from the binding exactly like that
+          // gate did, so a first turn landing after the plan was made keeps the check strict.
+          const binding = (planned.terminals as TerminalBinding[]).find((t) => t.peer === "claude");
+          if (!binding || binding.sessionId !== old.sessionId || claudeTranscriptExists(binding)) 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[]) {

package/src/hub/daemon.ts

@@ -1,6 +1,7 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { homedir } from "node:os";
 import type { ServerWebSocket } from "bun";
 import { AcpPeer, type PermissionRequest } from "../adapters/acp.ts";
 import { CodexPeer } from "../adapters/codex-appserver.ts";
@@ -480,27 +481,44 @@ export async function startDaemon(opts: DaemonOptions) {
       // Kimi/local rebuild a fresh worker with task context on the target; native
       // Claude and Pi sessions must keep their exact identities across restoration.
       const freshWorker = recoveryPhase === "restored" && (saved.id === "kimi" || saved.id === "local");
-      if (!freshWorker && saved.sessionId && saved.sessionId !== now.sessionId) return false;
+      if (!freshWorker && saved.sessionId && saved.sessionId !== now.sessionId) {
+        // #64: a Claude session that never persisted a transcript cannot be resumed, so the
+        // restore gate accepted a fresh session and nothing it stood for is lost. Snapshots
+        // written before this flag existed are re-derived from disk.
+        const unpersistedClaude = saved.id === "claude" && (saved.sessionPersisted === false || (saved.sessionPersisted === undefined && !claudeTranscriptPersisted(saved.sessionId)));
+        if (!unpersistedClaude) return false;
+      }
       return true;
     });
   };
-  const claudeSessionId = () => {
+  const claudeSession = (): { sessionId?: string; transcriptPath?: string } => {
     try {
       const value = JSON.parse(readFileSync(join(opts.stateDir, "claude-session.json"), "utf8"));
-      if (value.instanceId !== instanceId) return undefined;
+      if (value.instanceId !== instanceId) return {};
       try {
         const records = JSON.parse(readFileSync(join(opts.stateDir, "terminal-recovery.json"), "utf8"));
         const current = Array.isArray(records) ? records.find((row) => row?.peer === "claude" && row?.projectRoot === opts.cwd && row?.instanceId === instanceId) : undefined;
-        if (current?.launchId && value.launchId !== current.launchId) return undefined;
+        if (current?.launchId && value.launchId !== current.launchId) return {};
       } catch { /* no managed terminal record: the instance fence is still enforced */ }
-      return typeof value.sessionId === "string" && value.sessionId ? value.sessionId : undefined;
-    } catch { return undefined; }
+      return {
+        ...(typeof value.sessionId === "string" && value.sessionId ? { sessionId: value.sessionId } : {}),
+        ...(typeof value.transcriptPath === "string" && value.transcriptPath ? { transcriptPath: value.transcriptPath } : {}),
+      };
+    } catch { return {}; }
+  };
+  /** Claude persists projects/<slug>/<sessionId>.jsonl only with the first turn. Prefer the
+   * path Claude itself reported through the status line; fall back to the slug computation. */
+  const claudeTranscriptPersisted = (sessionId: string): boolean => {
+    const reported = claudeSession();
+    if (reported.sessionId === sessionId && reported.transcriptPath) return existsSync(reported.transcriptPath);
+    const config = process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+    return existsSync(join(config, "projects", opts.cwd.replace(/[^a-zA-Z0-9]/g, "-"), `${sessionId}.jsonl`));
   };
   const recoveryPeers = (): Record<string, RestartPeerSnapshot> => Object.fromEntries([...bus.peers].map(([id, peer]) => {
     const metadata = peer.recoveryMetadata?.() ?? {};
     const row: RestartPeerSnapshot = { id, state: peer.state, queueIds: bus.queueIds(id), ...(metadata.launch ? { launch: metadata.launch as Record<string, unknown> } : {}) };
     if (typeof metadata.threadId === "string") row.threadId = metadata.threadId;
-    const sessionId = id === "claude" ? claudeSessionId() : metadata.sessionId;
+    const sessionId = id === "claude" ? claudeSession().sessionId : metadata.sessionId;
     if (typeof sessionId === "string" && sessionId) row.sessionId = sessionId;
     return [id, row];
   }));
@@ -991,6 +1009,8 @@ export async function startDaemon(opts: DaemonOptions) {
       const peers = (recoveryPeerSnapshot ?? Object.values(currentPeers)).map((saved) => ({
         ...saved,
         queueIds: bus.queueIds(saved.id),
+        // Recorded at commit, not prepare: a first turn landing in between flips it (#64).
+        ...(saved.id === "claude" && saved.sessionId ? { sessionPersisted: claudeTranscriptPersisted(saved.sessionId) } : {}),
       }));
       const snapshot: RestartSnapshot = {
         schemaVersion: 1,

package/src/hub/restart.ts

@@ -18,6 +18,10 @@ export interface RestartPeerSnapshot {
   /** Safe native correlation metadata. Never include prompt/message text here. */
   threadId?: string;
   sessionId?: string;
+  /** Claude only: false when the session never persisted a transcript (zero turns), so it
+   * cannot be resumed and a fresh session is accepted instead. Absent in snapshots written
+   * before this flag; those are re-derived from disk (#64). */
+  sessionPersisted?: boolean;
 }
 
 export interface RestartSnapshot {