@staix/agent-hub 0.6.3 → 0.7.0

package/src/adapters/codex-appserver.ts

@@ -51,13 +51,15 @@ export class CodexPeer extends BasePeer {
   private threadId = "";
   private readonly activeTurns = new Set<string>();
   private nextId = -1;
-  private readonly pending = new Map<number, { resolve: (result?: any) => void; reject: (e: Error) => void }>();
+  private readonly pending = new Map<number, { resolve: (result?: any) => void; reject: (e: Error) => void; deliveryId?: string; kind?: "deliver" | "steer" }>();
   private usageTimer: ReturnType<typeof setInterval> | undefined;
   private injected: Envelope | undefined; // the hub envelope that started the current turn, if any
   private lastAnswer = "";
   private readonly deltas = new Map<string, string[]>();
   private primed = false;
   private readonly steers = new Set<number>(); // request ids of turn/steer calls app-server has not answered yet
+  private readonly turnDeliveries = new Map<string, Set<string>>();
+  private readonly unboundDeliveries = new Set<string>();
 
   constructor(
     id: PeerId,
@@ -129,9 +131,10 @@ export class CodexPeer extends BasePeer {
   }
 
   /** Resolves when app-server accepts the turn. Only called while idle, i.e. a thread exists and no turn runs. */
-  deliver(envs: Envelope[]): Promise<void> {
+  deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
     const link = this.link;
     if (this.state !== "idle" || !link || link.up.readyState !== WebSocket.OPEN) {
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is not injectable` });
       return Promise.reject(new Error(`${this.id} is not injectable`));
     }
     const text = this.render(envs);
@@ -139,13 +142,21 @@ export class CodexPeer extends BasePeer {
     this.setState("busy"); // claim the turn now so the bus stops draining
     return new Promise<void>((resolve, reject) => {
       this.pending.set(id, {
-        resolve: () => {
+        deliveryId, kind: "deliver",
+        resolve: (result) => {
           this.primed = true;
           this.injected = replyParent(envs);
+          const nativeTurn = typeof result?.turn?.id === "string" ? result.turn.id : undefined;
+          if (deliveryId) {
+            if (nativeTurn) this.addTurnDelivery(nativeTurn, deliveryId);
+            else this.unboundDeliveries.add(deliveryId);
+            this.delivery({ id: deliveryId, state: "accepted" });
+          }
           resolve();
         },
         reject: (e) => {
           if (!this.activeTurns.size) this.setState("idle");
+          if (deliveryId) this.delivery({ id: deliveryId, state: this.knownRejection(e) ? "failed_safe" : "needs_review", reason: e.message });
           reject(e);
         },
       });
@@ -160,25 +171,32 @@ export class CodexPeer extends BasePeer {
   }
 
   /** `important` while a turn runs: feed it into that turn. Rejects when there is no steerable turn or app-server refuses. */
-  steer(envs: Envelope[]): Promise<void> {
+  steer(envs: Envelope[], deliveryId?: string): Promise<void> {
     const link = this.link;
     const expectedTurnId = [...this.activeTurns].reverse().find((t) => !t.startsWith("unknown:"));
     if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId) {
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} has no steerable turn` });
       return Promise.reject(new Error(`${this.id} has no steerable turn`));
     }
     const id = this.nextId--;
     this.steers.add(id);
     return new Promise<void>((resolve, reject) => {
       this.pending.set(id, {
+        deliveryId, kind: "steer",
         resolve: () => {
           this.steers.delete(id);
           this.primed = true;
           // The turn now answers these too; the highest hop wins so a steer cannot reset the hop cap.
           this.injected = replyParent(this.injected ? [this.injected, ...envs] : envs);
+          if (deliveryId) {
+            this.addTurnDelivery(expectedTurnId, deliveryId);
+            this.delivery({ id: deliveryId, state: "accepted" });
+          }
           resolve();
         },
         reject: (e) => {
           this.steers.delete(id);
+          if (deliveryId) this.delivery({ id: deliveryId, state: this.knownRejection(e) ? "failed_safe" : "needs_review", reason: e.message });
           reject(e);
         },
       });
@@ -194,6 +212,9 @@ export class CodexPeer extends BasePeer {
       this.link?.up.send(JSON.stringify({ method: "turn/interrupt", id: this.nextId--, params: { threadId: this.threadId, turnId } }));
     }
     this.activeTurns.clear();
+    for (const ids of this.turnDeliveries.values()) for (const id of ids) this.delivery({ id, state: "needs_review", reason: "Codex turn watchdog timeout" });
+    for (const id of this.unboundDeliveries) this.delivery({ id, state: "needs_review", reason: "Codex turn watchdog timeout" });
+    this.turnDeliveries.clear(); this.unboundDeliveries.clear();
     this.injected = undefined;
     this.lastAnswer = "";
     this.abandonSteers("turn went silent");
@@ -209,6 +230,15 @@ export class CodexPeer extends BasePeer {
     }
   }
 
+  private addTurnDelivery(turnId: string, deliveryId: string): void {
+    const ids = this.turnDeliveries.get(turnId) ?? new Set<string>();
+    ids.add(deliveryId); this.turnDeliveries.set(turnId, ids); this.unboundDeliveries.delete(deliveryId);
+  }
+
+  private knownRejection(error: Error): boolean {
+    return /turn in progress|no active turn|not injectable|rejected|usage limit/i.test(error.message);
+  }
+
   private async spawnAppServer(): Promise<string> {
     const port = this.opts.appPort;
     const probe = () => fetch(`http://127.0.0.1:${port}/healthz`).then((r) => r.ok, () => false);
@@ -259,8 +289,14 @@ export class CodexPeer extends BasePeer {
     this.link = undefined;
     this.threadId = "";
     this.activeTurns.clear();
-    for (const p of this.pending.values()) p.reject(new Error("codex TUI detached"));
+    for (const p of this.pending.values()) {
+      if (p.deliveryId) this.delivery({ id: p.deliveryId, state: "needs_review", reason: "Codex TUI detached" });
+      p.reject(new Error("codex TUI detached"));
+    }
     this.pending.clear();
+    for (const ids of this.turnDeliveries.values()) for (const id of ids) this.delivery({ id, state: "needs_review", reason: "Codex TUI detached" });
+    for (const id of this.unboundDeliveries) this.delivery({ id, state: "needs_review", reason: "Codex TUI detached" });
+    this.turnDeliveries.clear(); this.unboundDeliveries.clear();
     this.setState("offline");
   }
 
@@ -319,7 +355,9 @@ export class CodexPeer extends BasePeer {
     }
     if (link !== this.link || params.threadId !== this.threadId) return;
     if (method === "turn/started") {
-      this.activeTurns.add(params.turn?.id ?? `unknown:${Date.now()}`);
+      const nativeTurn = params.turn?.id ?? `unknown:${Date.now()}`;
+      this.activeTurns.add(nativeTurn);
+      for (const id of [...this.unboundDeliveries]) this.addTurnDelivery(nativeTurn, id);
       this.lastAnswer = "";
       this.setState("busy");
     } else if (method === "item/agentMessage/delta") {
@@ -334,13 +372,18 @@ export class CodexPeer extends BasePeer {
       // Conclusions only: skip commentary, keep the last answer of the turn (phase may be absent).
       if (item.phase !== "commentary" && text.trim()) this.lastAnswer = text.trim();
     } else if (method === "turn/completed") {
-      this.activeTurns.delete(params.turn?.id);
+      const nativeTurn = params.turn?.id;
+      this.activeTurns.delete(nativeTurn);
       for (const id of this.activeTurns) if (id.startsWith("unknown:")) this.activeTurns.delete(id);
       if (params.turn?.status === "failed") {
         this.opts.log?.(`[${this.id}] turn failed: ${params.turn.error?.message ?? "unknown error"}`);
       }
       if (this.activeTurns.size) return;
       this.abandonSteers("turn completed");
+      if (typeof nativeTurn === "string") {
+        for (const id of this.turnDeliveries.get(nativeTurn) ?? []) this.delivery({ id, state: params.turn?.status === "failed" ? "needs_review" : "completed", ...(params.turn?.status === "failed" ? { reason: params.turn?.error?.message ?? "Codex turn failed" } : {}) });
+        this.turnDeliveries.delete(nativeTurn);
+      }
       const inReplyTo = this.injected;
       this.injected = undefined;
       this.deltas.clear();

package/src/adapters/local-worker.ts

@@ -57,6 +57,7 @@ export class LocalPeer extends BasePeer {
   private readonly sessionId = `agent-hub-local-${randomUUID()}`;
   private turn = 0; // generation guard, as in acp.ts: a turn aborted by the watchdog must not touch the next one
   private abort: AbortController | undefined;
+  private activeDeliveryId: string | undefined;
   private readonly sandboxProfile: string; // built once: profile() spawns git and must stay off the per-call path
   /** What served the last call, for `ahub status`. */
   lastServedBy = "";
@@ -79,6 +80,8 @@ export class LocalPeer extends BasePeer {
   }
 
   async stop(): Promise<void> {
+    if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "turn stopped before settlement" });
+    this.activeDeliveryId = undefined;
     this.turn++;
     this.abort?.abort();
     await this.opts.capture?.end();
@@ -86,10 +89,15 @@ export class LocalPeer extends BasePeer {
   }
 
   /** Resolves once the turn is claimed; a turn that cannot reach any model hands the envelopes back through onFailed. */
-  async deliver(envs: Envelope[]): Promise<void> {
-    if (this.state !== "idle") throw new Error(`${this.id} is ${this.state}`);
+  async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
+    if (this.state !== "idle") {
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is ${this.state}` });
+      throw new Error(`${this.id} is ${this.state}`);
+    }
     const turn = ++this.turn;
+    this.activeDeliveryId = deliveryId;
     this.setState("busy");
+    if (deliveryId) this.delivery({ id: deliveryId, state: "accepted" });
     // The turn works on its own message list and joins the history only as a whole, so a failed or aborted turn can
     // never leave a tool call without its result (strict servers reject that history forever after).
     const msgs: ChatMessage[] = [{ role: "user", content: renderDigest(envs, true) }];
@@ -103,24 +111,33 @@ export class LocalPeer extends BasePeer {
         if (turn !== this.turn) return;
         if (!policy?.pii) this.commit(msgs); // a PII turn leaves nothing in the history later turns send along
         if (answer) this.onMessage?.(answer, reply);
+        if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed" });
       })
       .catch((e: Error) => {
         if (turn !== this.turn) return; // aborted by the watchdog or stop(): nothing to report, nothing was committed
         this.opts.log?.(`[${this.id}] turn failed: ${e.message}`);
-        if (!progress.sideEffects) return this.onFailed?.(envs); // nothing happened yet: safe to redeliver
+        if (!progress.sideEffects) {
+          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: e.message });
+          else this.onFailed?.(envs); // legacy delivery: safe to redeliver
+          return;
+        }
         // Tools already changed things. Redelivering would redo approved writes and commits, so report instead.
         // A model call is the only thing that throws here, and every tool call before it has its result: msgs is consistent.
         const note = `(turn failed after ${progress.sideEffects} tool call(s) with side effects: ${e.message.slice(0, 200)}. The work may be partial; check before repeating it.) ${progress.last}`.trim();
         msgs.push({ role: "assistant", content: note });
         if (!policy?.pii) this.commit(msgs);
         this.onMessage?.(note, reply);
+        if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
       })
       .finally(() => {
         if (turn === this.turn && this.state === "busy") this.setState("idle");
+        if (turn === this.turn && this.activeDeliveryId === deliveryId) this.activeDeliveryId = undefined;
       });
   }
 
   protected override onWatchdog(): void {
+    if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "turn watchdog timeout" });
+    this.activeDeliveryId = undefined;
     this.turn++;
     this.abort?.abort();
     super.onWatchdog();

package/src/adapters/pi.ts

@@ -51,6 +51,7 @@ export class PiPeer extends BasePeer {
   private persistedOnce = false;
   private activeEnvs: Envelope[] = [];
   private activeTools = 0;
+  private readonly activeDeliveryIds = new Set<string>();
   private agentRunning = false;
   private owner = randomUUID();
   private _tuiLaunch?: PiTuiLaunch;
@@ -206,6 +207,8 @@ export class PiPeer extends BasePeer {
   }
 
   async stop(): Promise<void> {
+    for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: "Pi session stopped before settlement" });
+    this.activeDeliveryIds.clear();
     this.stopping = true;
     this.clearOwnerMonitor();
     if (this.opts.mode === "tui") {
@@ -240,8 +243,11 @@ export class PiPeer extends BasePeer {
     this.server?.stop(true); this.server = undefined; this.setState("offline");
   }
 
-  async deliver(envs: Envelope[]): Promise<void> {
-    if (this.state !== "idle" || this.stopping) throw new Error(`${this.id} is not ready`);
+  async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
+    if (this.state !== "idle" || this.stopping) {
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is not ready` });
+      throw new Error(`${this.id} is not ready`);
+    }
     this.setState("busy"); this.activeEnvs = envs; this.currentReply = replyParent(envs); this.settledText = "";
     let attempted = false;
     try {
@@ -249,23 +255,39 @@ export class PiPeer extends BasePeer {
       if (requested) await this.setRequestedModel(requested);
       this.noteActivity();
       attempted = true;
+      if (deliveryId) this.activeDeliveryIds.add(deliveryId);
       if (this.opts.mode === "tui") await this.sendTui({ type: "prompt", message: renderDigest(envs, true) });
       else await this.sendRpc({ type: "prompt", message: renderDigest(envs, true) });
+      if (deliveryId && this.activeDeliveryIds.has(deliveryId)) this.delivery({ id: deliveryId, state: "accepted" });
     } catch (error) {
-      if (!attempted) { this.activeEnvs = []; this.setState("idle"); throw error; }
+      if (!attempted) {
+        this.activeEnvs = []; this.setState("idle");
+        if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: error instanceof Error ? error.message : String(error) });
+        throw error;
+      }
       // The prompt may have reached Pi even if its acknowledgement was lost.
       // Fence the owner before reporting failure; never return it to the bus for replay.
-      await this.terminateFailedTurn(error instanceof Error ? error : new Error(String(error)));
+      const reason = error instanceof Error ? error.message : String(error);
+      if (deliveryId && /process is not running/i.test(reason)) {
+        this.activeDeliveryIds.delete(deliveryId);
+        this.delivery({ id: deliveryId, state: "failed_safe", reason });
+      }
+      await this.terminateFailedTurn(error instanceof Error ? error : new Error(reason));
     }
   }
 
-  async steer(envs: Envelope[]): Promise<void> {
-    if (this.state !== "busy" || this.stopping || envs.some((e) => e.kind !== "chat" || e.private || e.priority !== "important")) throw new Error("Pi workflow/private messages must queue");
+  async steer(envs: Envelope[], deliveryId?: string): Promise<void> {
+    if (this.state !== "busy" || this.stopping || envs.some((e) => e.kind !== "chat" || e.private || e.priority !== "important")) {
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: "Pi workflow/private messages must queue" });
+      throw new Error("Pi workflow/private messages must queue");
+    }
     const reply = replyParent([...this.activeEnvs, ...envs]);
     this.activeEnvs.push(...envs); this.currentReply = reply;
     try {
+      if (deliveryId) this.activeDeliveryIds.add(deliveryId);
       if (this.opts.mode === "tui") await this.sendTui({ type: "steer", message: renderDigest(envs, true) });
       else await this.sendRpc({ type: "steer", message: renderDigest(envs, true) });
+      if (deliveryId && this.activeDeliveryIds.has(deliveryId)) this.delivery({ id: deliveryId, state: "accepted" });
     } catch (error) {
       await this.terminateFailedTurn(error instanceof Error ? error : new Error(String(error)));
     }
@@ -288,7 +310,7 @@ export class PiPeer extends BasePeer {
       if ((this.opts.sessionId && this.sessionId !== this.opts.sessionId) || (this.opts.sessionFile && this.sessionFile !== this.opts.sessionFile)) { this.opts.log?.(`[${this.id}] Pi session identity mismatch`); return; }
       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 === "session_shutdown") { this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor(); this.resolveTuiExit?.(); this.resolveTuiExit = undefined; this.fail(new Error("Pi session shut down before settlement")); }
     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") {
@@ -307,6 +329,8 @@ export class PiPeer extends BasePeer {
       if (cancelled) this.onMessage?.("Pi turn cancelled; inspect any partial effects before continuing.", reply);
       else if (error) void this.opts.onTurnFailure?.(this.activeEnvs, error);
       else if (text) this.onMessage?.(text, reply);
+      for (const id of this.activeDeliveryIds) this.delivery({ id, state: error || cancelled ? "needs_review" : "completed", ...(error || cancelled ? { reason: error || "Pi turn cancelled; partial effects are possible" } : {}) });
+      this.activeDeliveryIds.clear();
       this.currentReply = undefined; this.activeEnvs = []; if (this.state === "busy" && !this.activeTools) this.setState("idle");
     }
   }
@@ -346,6 +370,8 @@ export class PiPeer extends BasePeer {
     for (const pending of this.pending.values()) pending.reject(error);
     this.pending.clear();
     const envs = this.activeEnvs; this.activeEnvs = [];
+    for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: error.message });
+    this.activeDeliveryIds.clear();
     if (envs.length) {
       this.onMessage?.("Pi turn failed; inspect its session and any partial effects before continuing.", { inReplyTo: this.currentReply });
       void this.opts.onTurnFailure?.(envs, error.message).catch(() => this.opts.log?.("Pi failure handoff could not be completed"));

package/src/cli/free-text.ts

@@ -0,0 +1,8 @@
+/** Validate option-like tokens without discarding message text before the separator. */
+export function freeText(words: string[], usage: string): string {
+  const end = words.indexOf("--");
+  const before = end === -1 ? words : words.slice(0, end);
+  const flag = before.find((a) => a.startsWith("--"));
+  if (flag) throw new Error(`the message would absorb the flag "${flag}"; put it after "--" to send it as text; usage: ${usage}`);
+  return (end === -1 ? words : [...before, ...words.slice(end + 1)]).join(" ");
+}

package/src/cli/main.ts

@@ -17,6 +17,7 @@ import { buildLaunch, UNATTENDED_WARNING } from "./launch.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
 import { VERSION } from "../version.ts";
+import { freeText } from "./free-text.ts";
 import { createInterface } from "node:readline/promises";
 import { assertLifecycleAvailable, readOperation } from "../hub/recovery-store.ts";
 import { childEnv } from "../hub/child-process.ts";
@@ -66,6 +67,9 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub ui [--no-open]           open the local dashboard (or print its one-time link)
   ahub tail                     live stream of messages, states and permission requests
   ahub permit <id> <option>     answer a permission request shown by tail ("deny" cancels)
+  ahub queue list [--peer <id>] [--json]       inspect durable deliveries
+  ahub queue show <delivery-id>               inspect one delivery and revision
+  ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text>
   ahub status | logs [-f] | doctor | kill`;
 
 const argv = process.argv.slice(2);
@@ -446,7 +450,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   say: async () => {
     const lead = args.findIndex((a) => !/^@[a-z][a-z0-9-]*$/.test(a)); // only leading @tokens are recipients
     const to = args.slice(0, lead === -1 ? args.length : lead).map((a) => a.slice(1));
-    const body = lead === -1 ? "" : args.slice(lead).join(" ");
+    const body = lead === -1 ? "" : freeText(args.slice(lead), "ahub say [@peer ...] <text>");
     const hub = await connect();
     const res = await hub.request({ t: "send", body, to });
     hub.close();
@@ -455,6 +459,36 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log(res.targets.length ? `queued for: ${res.targets.join(", ")}` : "no peers attached; nothing delivered");
   },
 
+  queue: async () => {
+    const [operation = "list", ...rest] = args;
+    const hub = await connect();
+    try {
+      if (operation === "list") {
+        const { one, rest: flags } = takeFlags(rest, ["--peer"], []);
+        if (flags.some((flag) => flag !== "--json")) fail("usage: ahub queue list [--peer <id>] [--json]");
+        const result = await hub.request({ t: "queue", op: "list", ...(one["--peer"] ? { peer: one["--peer"] } : {}) });
+        if (!result.ok) fail(result.error);
+        if (flags.includes("--json")) return console.log(JSON.stringify(result.deliveries, null, 2));
+        for (const row of result.deliveries) console.log(`${row.id}  ${row.peer}  ${row.state}  revision ${row.revision}${row.important ? "  important" : ""}`);
+        if (!result.deliveries.length) console.log("no retained deliveries");
+        return;
+      }
+      const [id, ...flags] = rest;
+      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text>");
+      const shown = await hub.request({ t: "queue", op: "show", id });
+      if (!shown.ok) fail(shown.error);
+      if (operation === "show") {
+        if (flags.length) fail("usage: ahub queue show <id>");
+        return console.log(JSON.stringify(shown.delivery, null, 2));
+      }
+      const { one, rest: extra } = takeFlags(flags, ["--action", "--reason"], []);
+      if (extra.length || !["completed", "retry", "discard"].includes(one["--action"] ?? "") || !one["--reason"]?.trim()) fail("usage: ahub queue resolve <id> --action completed|retry|discard --reason <text>");
+      const result = await hub.request({ t: "queue", op: "resolve", id, revision: shown.delivery.revision, action: one["--action"], reason: one["--reason"] });
+      if (!result.ok) fail(result.error);
+      console.log(JSON.stringify(result.delivery, null, 2));
+    } finally { hub.close(); }
+  },
+
   tail: async () => {
     const hub = await connect();
     hub.onPush = (msg) => {
@@ -528,7 +562,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log(await taskOp("hub_review", { id: Number(id), verdict, note: note.join(" ") }));
   },
 
-  remember: async () => console.log(await taskOp("hub_remember", { text: args.join(" ") })),
+  remember: async () => console.log(await taskOp("hub_remember", { text: freeText(args, "ahub remember <text>") })),
 
   ask: async () => {
     const remember = args.includes("--remember");
@@ -571,7 +605,9 @@ const commands: Record<string, () => Promise<void> | void> = {
     const hub = await connect();
     const { status } = await hub.request({ t: "status" });
     hub.close();
+    if (args.includes("--json")) return console.log(JSON.stringify(status, null, 2));
     console.log(`hub pid ${status.pid}, control 127.0.0.1:${status.controlPort}, ${status.cwd}`);
+    if (status.deliveryError) console.log(`  delivery storage: ${status.deliveryError}; dispatch is stopped`);
     const peers = Object.entries(status.peers as Record<string, PeerRow>);
     for (const [id, p] of peers) console.log(peerLine(id, p));
     const models = (status as any).models?.backends as BackendRow[] | undefined;
@@ -611,6 +647,20 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     const up = await healthy();
     row(up, "ahub daemon", up ? readControl(stateDir)!.url : "not running (ahub up)");
+    if (up) {
+      const hub = await connect();
+      try {
+        const { status } = await hub.request({ t: "status" });
+        const pending = Object.values(status.peers as Record<string, PeerRow>).reduce((n, peer) => n + (peer.needsReview ?? 0), 0);
+        row(!status.deliveryError && pending === 0, "delivery recovery", status.deliveryError ?? (pending ? `${pending} deliveries need review; run ahub queue list` : "journal healthy; no deliveries need review"));
+        const observed = await hub.request({ t: "recovery", op: "inspect", expectedInstanceId: status.instanceId });
+        for (const peer of Object.values(observed.recovery?.peers ?? {}) as { id: string; state: string; sessionId?: string; threadId?: string }[]) {
+          if (!["claude", "codex"].includes(peer.id) || peer.state === "offline") continue;
+          const identity = peer.id === "claude" ? peer.sessionId : peer.threadId;
+          row(!!identity, `${peer.id} recovery ID`, identity ? "recorded" : `missing; verify the current conversation and reconnect with ahub ${peer.id} before upgrading`);
+        }
+      } finally { hub.close(); }
+    }
     const plugin = pluginState(parseList<InstalledPlugin>(spawnSync("claude", ["plugin", "list", "--json"], { encoding: "utf8" }).stdout ?? ""), join(import.meta.dir, "..", ".."));
     row(plugin.state === "current", "claude plugin", plugin.state === "missing" ? "missing: run ahub setup" : plugin.state === "current" ? `agent-hub@agent-hub ${plugin.version}` : `agent-hub@agent-hub is stale (${plugin.why}): run ahub setup`);
 

package/src/cli/status-lines.ts

@@ -1,6 +1,6 @@
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { state?: string; queued?: number; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { state?: string; queued?: number; queuedImportant?: number; needsReview?: number; oldestQueuedAt?: number; attached?: boolean; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */
@@ -12,6 +12,11 @@ export function backendLabel(backend: BackendRow): string {
 
 export function peerLine(id: string, p: PeerRow): string {
   return `  ${id.padEnd(8)} ${(p.state ?? "unknown").padEnd(8)} queued ${p.queued ?? 0}` +
+    // Which queued messages the peer will not wait out the batch window for (issue #41).
+    (p.queuedImportant ? ` (${p.queuedImportant} important)` : "") +
+    (p.needsReview ? `  needs review ${p.needsReview}` : "") +
+    (p.oldestQueuedAt !== undefined ? `  oldest ${Math.max(0, Math.floor((Date.now() - p.oldestQueuedAt) / 1000))}s` : "") +
+    (p.attached === false ? "  disconnected" : "") +
     (p.paused ? `  (${p.paused})` : "") +
     (p.servedBy ? `  last call: ${p.servedBy}` : "") +
     // Which backend the peer asked for on its last turn: without it, telling a Pi DGX turn from an MLX one

package/src/cli/terminal-recovery.ts

@@ -66,6 +66,10 @@ export interface RecoveryBlocker {
   message: string;
   peer?: TerminalPeer;
   handle?: string;
+  /** Stable terminal reference when Orca supplied one, for operator reconciliation. */
+  terminalReference?: string;
+  /** Human action that can resolve the blocker without guessing or retrying an effect. */
+  nextAction?: string;
 }
 
 export interface TerminalInspection {
@@ -399,7 +403,13 @@ function launchFor(peer: TerminalPeer, projectRoot: string, sessionId: string, o
 }
 
 function blocker(code: RecoveryBlocker["code"], message: string, peer?: TerminalPeer, handle?: string): RecoveryBlocker {
-  return { code, message, ...(peer ? { peer } : {}), ...(handle ? { handle } : {}) };
+  const nextAction = code === "missing-session" ? "reconnect the original native session and rerun recovery" :
+    code === "ownership-unknown" ? "confirm the terminal owner in Orca, then resume recovery" :
+    code === "ambiguous-terminal" ? "close or identify the duplicate terminal, then resume recovery" :
+    code === "ambiguous-create" ? "inspect the existing terminal and attach the original session before resuming" :
+    code === "terminal-unready" ? "finish or cancel the active terminal turn, then resume recovery" :
+    "inspect the named terminal and resume recovery after the identity is verified";
+  return { code, message, ...(peer ? { peer } : {}), ...(handle ? { handle, terminalReference: handle } : {}), nextAction };
 }
 
 function verifyBindingData(actual: Record<string, unknown>, binding: TerminalBinding): RecoveryBlocker | undefined {
@@ -547,6 +557,36 @@ export async function createTerminal(binding: TerminalBinding, options?: Command
   const config = normalizeOptions(options);
   try {
     const worktreeSelector = binding.worktreeId.startsWith("id:") ? binding.worktreeId : `id:${binding.worktreeId}`;
+    // A lost create reply is an uncertain effect. Before issuing another create,
+    // reconcile terminals already present in the captured worktree. An exact
+    // session match is safe to adopt; any other occupant requires an operator
+    // decision rather than risking a duplicate native session.
+    const existing = listTerminals(await run(config.runner, ["terminal", "list", "--json"])).filter((terminal) =>
+      rootMatches(terminal.worktreePath ?? terminal.projectRoot, binding.projectRoot) &&
+      nestedString(terminal, ["worktreeId"]) === binding.worktreeId,
+    );
+    if (existing.length > 0) {
+      const matches: TerminalBinding[] = [];
+      for (const listed of existing) {
+        const handle = nestedString(listed, ["handle"]);
+        if (!handle) continue;
+        try {
+          const shown = terminalObject(await run(config.runner, ["terminal", "show", "--terminal", handle, "--json"]));
+          if (identityFrom(shown) === binding.peer && sessionFrom(shown) === binding.sessionId) {
+            const incarnationId = nestedString(shown, ["incarnationId"]);
+            const worktreeId = nestedString(shown, ["worktreeId"]);
+            if (incarnationId && worktreeId) matches.push({ ...binding, handle, incarnationId, worktreeId });
+          }
+        } catch { /* An unreadable candidate remains an ambiguity below. */ }
+      }
+      if (matches.length === 1) {
+        const recovered = matches[0]!;
+        const idle = await waitForIdle(recovered, timeoutMs, config);
+        if (!idle.satisfied) return { created: false, ready: false, manualRequired: true, blockers: idle.blockers };
+        return { created: true, ready: true, manualRequired: false, binding: recovered, newBinding: recovered, blockers: [] };
+      }
+      return { created: false, ready: false, manualRequired: true, blockers: [blocker("ambiguous-create", `an existing terminal in worktree ${binding.worktreeId} may be the result of an earlier create; refusing another create`, binding.peer)] };
+    }
     const value = await run(config.runner, ["terminal", "create", "--worktree", worktreeSelector, "--command", binding.launch.command, "--title", `${binding.peer} recovery`, "--json"]);
     let created = terminalObject(value);
     const createdHandle = nestedString(created, ["handle"]);

package/src/cli/upgrade-runtime.ts

@@ -1,7 +1,7 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { ControlClient, PROTOCOL, readControl } from "../hub/control-client.ts";
+import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS, readControl } from "../hub/control-client.ts";
 import { inspectProject } from "../hub/lifecycle.ts";
 import type { Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.ts";
@@ -41,7 +41,7 @@ export async function inspectRecovery(project: Project): Promise<Inspection> {
   const base = await inspectProject(project);
   const control = readControl(project.stateDir);
   const sourceProtocol = control?.protocol;
-  const legacySupported = sourceProtocol === 8;
+  const legacySupported = sourceProtocol !== undefined && RECOVERY_SOURCE_PROTOCOLS.includes(sourceProtocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]);
   if (base.state !== "running" && !legacySupported) return {
     state: base.state, peers: [], blockers: base.state === "stopped" ? [] : [base.state === "incompatible" ? "manual-bootstrap-required: source lacks the recovery contract; use its matching CLI" : base.error ?? base.state],
     ...(control?.instanceId ? { instanceId: control.instanceId } : {}), ...(control?.protocol ? { protocol: control.protocol } : {}),
@@ -84,7 +84,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
   if (existsSync(managerFile)) {
     try {
       const manager = JSON.parse(readFileSync(managerFile, "utf8"));
-      if (![8, PROTOCOL].includes(manager.protocol)) body.blockers.push("manager requires manual bootstrap with its matching CLI before protocol-9 recovery");
+      if (!RECOVERY_SOURCE_PROTOCOLS.includes(manager.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number])) body.blockers.push("manager requires manual bootstrap with its matching CLI before protocol-10 recovery");
     } catch { body.blockers.push("manager ownership manifest is unreadable"); }
   }
   for (const project of projects) {
@@ -94,24 +94,24 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     catch { source = { state: "unavailable", peers: [], blockers: ["source recovery metadata could not be authenticated"] }; }
     if (source.state === "stopped" || source.state === "missing") continue;
     const blockers = [...source.blockers];
-    if (![8, PROTOCOL].includes(source.protocol ?? 0) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated recovery-capable source is required");
+    if (!RECOVERY_SOURCE_PROTOCOLS.includes(source.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated protocol-9 or protocol-10 source is required");
     if (source.recovery?.operationId && source.recovery.phase !== "released") blockers.push(`existing recovery operation ${source.recovery.operationId} must be resolved first`);
     const sessions: { codex?: string; claude?: string; pi?: SessionRef } = {};
     for (const peer of source.peers) {
       if (peer.state === "offline") continue;
       if (peer.id === "codex" || peer.id === "claude") {
         const session = peer.id === "codex" ? peer.threadId : peer.sessionId;
-        if (!session) blockers.push(`${peer.id}: original conversation ID is unknown; manual-required`);
+        if (!session) blockers.push(`${peer.id}: original conversation ID is unknown; manual-required; next action: reconnect the original native session and make a new recovery plan`);
         else sessions[peer.id] = session;
       } else if (peer.id === "pi" && peer.args?.mode === "tui") {
-        if (!peer.sessionId) blockers.push("pi: original session ID is unknown; manual-required");
+        if (!peer.sessionId) blockers.push("pi: original session ID is unknown; manual-required; next action: reconnect the original Pi session and make a new recovery plan");
         else sessions.pi = { sessionId: peer.sessionId, ...(peer.sessionFile ? { sessionFile: peer.sessionFile } : {}), ...(peer.args.backend ? { backend: peer.args.backend } : {}), ...(peer.args.model ? { model: peer.args.model } : {}) };
       } else if (peer.id !== "kimi" && peer.id !== "local" && peer.id !== "pi") blockers.push(`${peer.id}: no automatic recovery adapter`);
     }
     const terminals = await inspectTerminals(project.root, sessions, {
       ...terminalOptions(run), stateDir: project.stateDir, instanceId: source.instanceId,
     });
-    blockers.push(...terminals.blockers.map((b) => b.message));
+    blockers.push(...terminals.blockers.map((b) => `${b.message}${b.terminalReference ? ` (terminal ${b.terminalReference})` : ""}${b.nextAction ? `; next action: ${b.nextAction}` : ""}`));
     body.projects.push({ project, source, terminals: terminals.bindings, blockers });
   }
   if (!body.projects.length) body.blockers.push("no running registered projects in scope");
@@ -169,7 +169,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
   };
   const control = (project: Project, op: string, id: string, instance: string) => {
     const sourceProtocol = readControl(project.stateDir)?.protocol;
-    const protocol = sourceProtocol === 8 ? 8 : PROTOCOL;
+    const protocol = sourceProtocol !== undefined && RECOVERY_SOURCE_PROTOCOLS.includes(sourceProtocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) ? sourceProtocol : PROTOCOL;
     return rpc(project, { t: "recovery", op, operationId: id, expectedInstanceId: instance }, protocol).then(() => {});
   };
   const revalidateTerminal = async (planned: PlannedProject, progress: ProjectProgress, saved: TerminalBinding, exact: boolean): Promise<TerminalBinding> => {