@staix/agent-hub 0.12.30 → 0.12.32

package/src/cli/recovery-guidance.ts

@@ -0,0 +1,137 @@
+import { recordedFileState } from "./recovery-session-file.ts";
+import { decodeRestoreReceipt } from "./upgrade-restore-state.ts";
+import { shellQuote } from "./terminal-recovery.ts";
+import type { TerminalBinding } from "./terminal-recovery.ts";
+import type { Inspection, PlannedProject, ProjectProgress, RecoveryOperation, RecoveryPeer } from "./upgrade.ts";
+
+export type RecoveryNativePeer = "codex" | "pi" | "claude";
+export type RecordedSessionOverride = Pick<TerminalBinding, "sessionId" | "sessionFile">;
+export interface RecordedPeerGuidance {
+  peer: RecoveryNativePeer;
+  sessionId?: string;
+  sessionFile?: string;
+  command?: string;
+  reattachCommand?: string;
+  note: string;
+}
+export interface RecoveryGuidanceOptions {
+  /** Person-only blocked guidance; no lifecycle action is taken by this projection. */
+  stopAndArchiveCommand?: string;
+  /** Caller-validated retained repair bindings, including accepted sessions no longer in a done/waiting receipt. */
+  recorded?: Partial<Record<RecoveryNativePeer, RecordedSessionOverride>>;
+  /** The caller's fixed formatter for this operation's own coordinator, never model-supplied code. */
+  reattachCommand?: (peer: RecoveryNativePeer) => string | undefined;
+}
+
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+const argv = (...words: string[]): string => words.map(shellQuote).join(" ");
+const peers: readonly RecoveryNativePeer[] = ["codex", "pi", "claude"];
+
+function sourceSession(peer: RecoveryNativePeer, source: RecoveryPeer | undefined): { sessionId?: string; sessionFile?: string } {
+  const sessionId = peer === "codex" ? source?.threadId : source?.sessionId;
+  const sessionFile = peer === "pi" ? source?.sessionFile ?? source?.args?.sessionFile : undefined;
+  return { ...(text(sessionId) ? { sessionId } : {}), ...(text(sessionFile) ? { sessionFile } : {}) };
+}
+
+/** Fixed person commands for the existing Pi archive exit; this helper performs no lifecycle action. */
+export function piArchiveExit(planned: PlannedProject, stopAndArchiveCommand: string): string {
+  return `Run ${stopAndArchiveCommand}; after stop-and-archive, run ${argv("ahub", "--project", planned.project.root, "pi")}. A proven missing archived bookmark is retired by the normal Pi start without a fresh fallback in that same call; repeat the normal start as its notice directs.`;
+}
+
+/** Accepted identity outlives an incarnation's repair fence. Malformed evidence never means absence. */
+export function resolveAcceptedBinding(planned: PlannedProject, progress: ProjectProgress, peer: RecoveryNativePeer): TerminalBinding | undefined {
+  if (progress.id !== planned.project.id) throw new Error("recorded binding project mismatch");
+  const binding = (value: unknown): TerminalBinding => {
+    const receipt = decodeRestoreReceipt({ state: "done", binding: value });
+    if (receipt?.state !== "done" || receipt.binding.peer !== peer || receipt.binding.projectRoot !== planned.project.root) throw new Error("recorded binding does not match its peer and project");
+    return receipt.binding;
+  };
+  const restored = decodeRestoreReceipt(progress.terminals[`restored:${peer}`]);
+  if (restored?.state === "done" || restored?.state === "waiting") return binding(restored.binding);
+  if (progress.reattachments !== undefined) {
+    if (!progress.reattachments || typeof progress.reattachments !== "object" || Array.isArray(progress.reattachments)) throw new Error("invalid recorded reattachment markers");
+    if (Object.hasOwn(progress.reattachments, peer)) {
+      const marker = progress.reattachments[peer];
+      if (!marker || typeof marker !== "object" || Array.isArray(marker) || Object.keys(marker).some(key => !["state", "at", "cause", "binding"].includes(key)) ||
+          !["ready", "attempted"].includes(marker.state) || marker.cause !== "detached after restore" || !Number.isFinite(marker.at) || marker.at < 0) throw new Error("invalid recorded reattachment marker");
+      return binding(marker.binding);
+    }
+  }
+  const retiredKey = `retired:${peer}`;
+  if (Object.hasOwn(progress.terminals, retiredKey)) return binding(progress.terminals[retiredKey]);
+  const original = planned.terminals.filter(value => !!value && typeof value === "object" && (value as { peer?: unknown }).peer === peer);
+  if (original.length > 1) throw new Error("ambiguous planned recorded bindings");
+  return original.length ? binding(original[0]) : undefined;
+}
+
+/**
+ * Person-only projection of recorded identities, never a peer/tool result or evidence of live attachment.
+ * A supplied override must already be validated by the recovery coordinator. It deliberately wins over both
+ * current receipts and the original plan. A malformed current receipt otherwise stays unavailable.
+ */
+export function recordedPeerGuidance(planned: PlannedProject, progress: ProjectProgress, options: RecoveryGuidanceOptions = {}): RecordedPeerGuidance[] {
+  return peers.map(peer => {
+    let session: { sessionId?: string; sessionFile?: string } | undefined;
+    let unavailable = false;
+    const override = options.recorded && Object.hasOwn(options.recorded, peer) ? options.recorded[peer] : undefined;
+    if (override !== undefined) session = override;
+    else {
+      try {
+        session = resolveAcceptedBinding(planned, progress, peer)
+          ?? sourceSession(peer, planned.source.peers.find(row => row.id === peer));
+      } catch { unavailable = true; }
+    }
+    const sessionId = text(session?.sessionId) ? session.sessionId : undefined;
+    const sessionFile = peer === "pi" && text(session?.sessionFile) ? session.sessionFile : undefined;
+    if (unavailable || (!sessionId && !sessionFile)) return { peer, note: `${peer}: recorded session identity unavailable; inspect the retained recovery receipt before choosing a conversation` };
+    const prefix = ["ahub", "--project", planned.project.root];
+    const command = peer === "codex"
+      ? sessionId ? argv(...prefix, "codex", "resume", sessionId) : undefined
+      : peer === "pi"
+        ? sessionFile ? argv(...prefix, "pi", "--session-file", sessionFile) : sessionId ? argv(...prefix, "pi", "--session-id", sessionId) : undefined
+        : sessionId ? argv(...prefix, "claude", "--resume", sessionId) : undefined;
+    let note = peer === "claude"
+      ? "The existing Claude channel may reconnect while its native session remains open. Transcript availability is unknown; the recorded resume command is guidance, not proof that the transcript can be resumed."
+      : peer === "codex" ? "Recorded Codex thread; leave the old native client before resuming this conversation."
+        : "Recorded Pi conversation; preserve this session when starting Pi again.";
+    if (sessionFile && options.stopAndArchiveCommand && recordedFileState(sessionFile) === "missing") {
+      note = `Recorded Pi session file is positively missing. Fresh-session is not supported for Pi. ${piArchiveExit(planned, options.stopAndArchiveCommand)}`;
+    }
+    const reattachCommand = command ? options.reattachCommand?.(peer) : undefined;
+    return { peer, ...(sessionId ? { sessionId } : {}), ...(sessionFile ? { sessionFile } : {}), ...(command ? { command } : {}), ...(reattachCommand ? { reattachCommand } : {}), note };
+  });
+}
+
+/** Historical receipt facts only. A stopped/archived target is never described as still running. */
+export function stopAndArchiveSummary(op: RecoveryOperation, live: Readonly<Record<string, Inspection | undefined>> = {}): string[] {
+  const lines = [op.disposition
+    ? `${op.plan.kind} abandoned, not completed; committed transitions were not rolled back.`
+    : "Stop-and-archive is not recorded; no abandonment outcome is claimed."];
+  for (const progress of op.projects) {
+    if (["started", "peers-restored", "verified"].includes(progress.phase) || progress.restarts?.length) lines.push(`${progress.id}: target ${op.plan.version} had started; this is a recorded historical step.`);
+    const outcome = op.disposition?.projects[progress.id];
+    if (outcome) lines.push(`${progress.id}: ${outcome}`);
+    const continuity = op.disposition?.continuity?.[progress.id];
+    if (continuity === "not-archived") lines.push(`${progress.id}: no Pi continuity bookmark because the snapshot was not archived by this operation; use the manual recorded-session commands below.`);
+    else if (continuity === "unavailable") lines.push(`${progress.id}: Pi continuity bookmark unavailable; automatic session continuity is unconfirmed, so use the manual recorded-session commands below.`);
+    const observed = live[progress.id];
+    if (observed) lines.push(`${progress.id}: supplied inspection reported ${observed.state}${observed.version ? ` on ${observed.version}` : ""}; it does not change the recorded disposition.`);
+    const planned = op.plan.projects.find(project => project.project.id === progress.id);
+    if (planned) for (const row of recordedPeerGuidance(planned, progress)) {
+      if (row.command) lines.push(`${progress.id} ${row.peer}: ${row.command}`);
+      lines.push(`${progress.id} ${row.peer}: ${row.note}`);
+    }
+  }
+  if (op.freshOverride) {
+    const { peer, evidence, checked, at } = op.freshOverride;
+    lines.push(`Explicit fresh override: ${peer} in ${evidence.projectId}; accepted session ${shellQuote(evidence.sessionId)}, ${evidence.kind}${evidence.checkedPath ? ` at ${shellQuote(evidence.checkedPath)}` : ""} checked ${checked} at ${at}; missing-history replacement was person-authorized.`);
+  }
+  lines.push(op.pluginInstalled ? "Claude plugin installation recorded." : "Claude plugin installation not recorded.");
+  if (op.globalInstalled) lines.push("global CLI installation recorded.");
+  else if (op.plan.kind === "upgrade") {
+    lines.push("global CLI installation remains; it was not recorded as completed.");
+    const exact = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/.test(op.plan.version);
+    lines.push(exact ? argv("bun", "add", "-g", `@staix/agent-hub@${op.plan.version}`, "--ignore-scripts") : "Exact target version unavailable; review the retained receipt before installing the global CLI.");
+  } else lines.push("global CLI installation not recorded; a restart does not install a new CLI.");
+  return lines;
+}

package/src/cli/recovery-presentation-options.ts

@@ -0,0 +1,8 @@
+/** Pure shared recognition; the console still validates colour values and precedence. */
+export function recoveryPresentationFlag(arg: string): { kind: "json" | "verbose" } | { kind: "color"; value: string } | undefined {
+  if (arg === "--json") return { kind: "json" };
+  if (arg === "--verbose") return { kind: "verbose" };
+  const prefix = "--color=";
+  if (arg.startsWith(prefix)) return { kind: "color", value: arg.slice(prefix.length) };
+  return undefined;
+}

package/src/cli/recovery-session-file.ts

@@ -0,0 +1,18 @@
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { TerminalBinding } from "./terminal-recovery.ts";
+
+/** The exact transcript file, or the exact sessions directory recursively searched for a rollout. */
+export function checkedSessionPath(binding: TerminalBinding, kind: "rollout" | "transcript"): string {
+  if (kind === "rollout") return join(binding.launch.env.CODEX_HOME ?? join(homedir(), ".codex"), "sessions");
+  const config = binding.launch.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+  const slug = binding.projectRoot.replace(/[^a-zA-Z0-9]/g, "-");
+  return join(config, "projects", slug, `${binding.sessionId}.jsonl`);
+}
+
+/** Only an absent path is positive missing evidence. Unreadable or non-file evidence stays unknown. */
+export function recordedFileState(file: string): "found" | "missing" | "unknown" {
+  try { return statSync(file).isFile() ? "found" : "unknown"; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unknown"; }
+}

package/src/cli/terminal-recovery.ts

@@ -76,6 +76,12 @@ export interface RecoveryBlocker {
   nextAction?: string;
 }
 
+/** Read-only evidence for one already recorded terminal, never a session-selection result. */
+export interface SavedTerminalInspection {
+  state: "present" | "orphaned" | "missing" | "changed" | "unknown";
+  blocker?: RecoveryBlocker;
+}
+
 export interface TerminalInspection {
   bindings: TerminalBinding[];
   /** A map is convenient for callers recovering both peers at once. */
@@ -539,6 +545,48 @@ async function showBinding(binding: TerminalBinding, options: Required<TerminalR
   return actual;
 }
 
+/**
+ * Judge only the saved terminal identity. The caller separately fences the peer's current/restarted launchers.
+ * A failed read is unknown; only a typed stale handle plus a complete inventory can prove absence.
+ */
+export async function inspectSavedTerminal(binding: TerminalBinding, options?: CommandRunner | TerminalRecoveryOptions): Promise<SavedTerminalInspection> {
+  const config = normalizeOptions(options);
+  const unknown = (): SavedTerminalInspection => ({ state: "unknown", blocker: blocker("command-error", "saved terminal evidence is unavailable or inconsistent", binding.peer, binding.handle) });
+  const completeIdentity = (value: Record<string, unknown>) =>
+    [nestedString(value, ["handle"]), nestedString(value, ["incarnationId"]), nestedString(value, ["worktreeId"]), nestedString(value, ["worktreePath", "projectRoot"])].every(Boolean);
+  try {
+    const shown = terminalObject(await run(config.runner, ["terminal", "show", "--terminal", binding.handle, "--json"]));
+    if (!completeIdentity(shown)) return unknown();
+    const issue = verifyBindingData(shown, binding);
+    if (issue) return { state: "changed", blocker: issue };
+    if (shown.orphaned === true) return { state: "orphaned", blocker: blocker("terminal-gone", "the saved terminal is orphaned", binding.peer, binding.handle) };
+    if (shown.connected === false) return unknown();
+    return { state: "present" };
+  } catch (error) {
+    if (!(error instanceof OrcaCommandError) || error.blocker.code !== "terminal-gone") return unknown();
+  }
+  try {
+    const result = responseResult(await run(config.runner, ["terminal", "list", "--json"]));
+    const rows = result.terminals ?? result.items;
+    if (result.truncated === true || !Array.isArray(rows)) return unknown();
+    const handles = new Set<string>(), incarnations = new Set<string>();
+    for (const raw of rows) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) return unknown();
+      const row = raw as Record<string, unknown>;
+      if (!completeIdentity(row)) return unknown();
+      const handle = nestedString(row, ["handle"])!, incarnation = nestedString(row, ["incarnationId"])!;
+      if (handles.has(handle) || incarnations.has(incarnation)) return unknown();
+      handles.add(handle); incarnations.add(incarnation);
+    }
+    const retained = (rows as Record<string, unknown>[]).find(row => row.handle === binding.handle || row.incarnationId === binding.incarnationId);
+    if (retained) {
+      const issue = verifyBindingData(retained, binding);
+      return issue ? { state: "changed", blocker: issue } : unknown();
+    }
+    return { state: "missing", blocker: blocker("terminal-gone", "the saved terminal handle and incarnation are absent from the complete inventory", binding.peer, binding.handle) };
+  } catch { return unknown(); }
+}
+
 /**
  * Read Orca's authoritative terminal inventory and bind only exact agent/session identities.
  * Titles, previews, pty ids and process names are deliberately never used as identity.

package/src/cli/upgrade-interactive.ts

@@ -1,3 +1,7 @@
+import { renderPlan, renderOperation, renderBlocked, renderSummary, renderStep, renderWait, renderMenu, choiceInstruction, type RecoveryPresentationOptions, type MenuPresentationItem } from "./upgrade-presentation.ts";
+import { quoted, wrap } from "./console-state.ts";
+import { operationLines, stepLabel } from "./upgrade-labels.ts";
+export { operationLines, stepLabel } from "./upgrade-labels.ts";
 import { recoveryArgv } from "../hub/recovery-store.ts";
 import { cancellableWait, nextChoices, publicOperation, type Inspection, type PlannedProject, type RecoveryOperation, type RecoveryPeer, type UpgradePlan } from "./upgrade.ts";
 
@@ -10,6 +14,8 @@ import { cancellableWait, nextChoices, publicOperation, type Inspection, type Pl
 
 /** The terminal a screen talks to; tests script it. */
 export interface ScreenIO {
+  /** Optional terminal presentation; raw JSON always bypasses this layer. */
+  presentation?: RecoveryPresentationOptions;
   /** One trimmed line from the person; null when the input ended or they pressed Ctrl+C, which no prompt takes for text. */
   ask(question: string): Promise<string | null>;
   out(line: string): void;
@@ -34,6 +40,8 @@ export interface UpgradeHost {
   read(id: string): RecoveryOperation;
   runner(id: string): number | "unknown" | undefined;
   live(op: RecoveryOperation): Promise<Record<string, Inspection | undefined>>;
+  /** Read-only current state after completion/disposal; failure remains unknown. */
+  endInspection?(op: RecoveryOperation): Promise<Record<string, Inspection | undefined>>;
   /** Whether the runner's claim carries a process signature that still matches: the only kind a screen may stop. */
   runnerStoppable(id: string): boolean;
   /** Stop that verified runner and wait until it is gone; false when one still holds the operation. */
@@ -44,9 +52,28 @@ export interface UpgradeHost {
   version: string;
 }
 
-const yes = async (io: ScreenIO, question: string): Promise<boolean> => /^y(es)?$/i.test((await io.ask(question)) ?? "");
+function emit(io: ScreenIO, lines: readonly string[]): void { for (const line of lines) io.out(line); }
+function human(io: ScreenIO, line: string): void {
+  if (!io.presentation) return io.out(line);
+  emit(io, wrap(/\p{Cc}/u.test(line) ? quoted(line) : line, io.presentation.columns));
+}
+function ask(io: ScreenIO, question: string): Promise<string | null> {
+  if (!io.presentation) return io.ask(question);
+  const lines = wrap(/\p{Cc}/u.test(question) ? quoted(question) : question, io.presentation.columns);
+  emit(io, lines.slice(0, -1));
+  return io.ask(lines.at(-1) ?? "> ");
+}
+async function summary(host: UpgradeHost, io: ScreenIO, op: RecoveryOperation): Promise<void> {
+  if (!io.presentation) return;
+  const live = await host.endInspection?.(op).catch(() => ({} as Record<string, Inspection | undefined>));
+  emit(io, renderSummary(op, live ?? {}, io.presentation));
+}
+const clock = (io: ScreenIO) => io.presentation?.now() ?? Date.now();
+
+const yes = async (io: ScreenIO, question: string): Promise<boolean> => /^y(es)?$/i.test((await ask(io, question)) ?? "");
 /** The way back after Ctrl+C: the operation's own coordinator, since the installed `ahub` may still be the older release (#215). */
-const left = (op: { id: string; sourceRoot?: string }): string => `left: the runner keeps working; \`bun ${recoveryArgv(op, "status")[0]} recovery\` shows the operation and what can be done`;
+const left = (op: { id: string; sourceRoot?: string }, io: ScreenIO): string => io.presentation && !io.presentation.verbose
+  ? `left: the runner keeps working; ahub recovery status ${op.id} shows the operation (use --verbose for its retained coordinator path)` : `left: the runner keeps working; \`bun ${recoveryArgv(op, "status")[0]} recovery\` shows the operation and what can be done`;
 
 /**
  * How an attached peer runs, which decides how it can be ended: a TUI agent in a terminal the plan could bind, a
@@ -60,19 +87,6 @@ export function peerKind(planned: PlannedProject, peer: RecoveryPeer): "tui" | "
   return "headless";
 }
 
-const STEPS: Record<string, string> = {
-  stage: "staging the release", prepare: "holding deliveries and waiting until the hub is quiet", reprepare: "preparing the source again after an expired hold",
-  commit: "closing terminals and stopping the old hub", restart: "restarting a target that stopped", start: "starting the new hub", restore: "restoring Codex and Pi sessions",
-  "install-plugin": "installing the Claude plugin", "restore-claude": "restoring the Claude session and verifying the hub", release: "releasing held deliveries",
-  "refresh-manager": "refreshing the dashboard manager", "install-global": "installing the global CLI", completed: "completed", cancelled: "cancelled",
-};
-
-/** A receipt step (`commit:<project>`) in a person's words; a step this release does not know is shown as it is. */
-export function stepLabel(step: string): string {
-  const at = step.indexOf(":"), name = at < 0 ? step : step.slice(0, at);
-  return STEPS[name] ? `${at < 0 ? "" : `${step.slice(at + 1)}: `}${STEPS[name]}` : step;
-}
-
 function peerAction(planned: PlannedProject, peer: RecoveryPeer): string {
   if (peer.state === "offline") return "offline, left as it is";
   if (planned.reconnectOnly?.includes(peer.id)) return "reconnects by itself (unmanaged session; its terminal is left alone)";
@@ -102,20 +116,6 @@ export function planLines(plan: UpgradePlan, current: string): string[] {
   return lines;
 }
 
-const ago = (ms: number): string => ms < 90_000 ? `${Math.max(0, Math.round(ms / 1000))}s` : ms < 5_400_000 ? `${Math.round(ms / 60_000)}m` : `${Math.round(ms / 3_600_000)}h`;
-
-export function operationLines(op: RecoveryOperation, runner: number | "unknown" | undefined, now: number): string[] {
-  const held = runner === "unknown" ? "; whether a runner holds it cannot be read" : runner ? `; runner ${runner} is working` : op.phase === "running" ? "; no runner holds it (the last one stopped mid-step)" : "";
-  const lines = [`${op.plan.kind} to ${op.plan.version}: operation ${op.id}`, `  ${op.phase} at "${stepLabel(op.step)}", updated ${ago(now - op.updatedAt)} ago${held}`];
-  for (const p of op.projects) {
-    const effects = Object.entries(p.terminals).map(([key, value]) => value === "pending" || value === "failed" ? `${key} ${value}` : key);
-    lines.push(`  ${p.id}  ${p.phase}${effects.length ? `  (${effects.join(", ")})` : ""}${p.restarts?.length ? `  restarts ${p.restarts.length}` : ""}`);
-  }
-  // The error ends with the commands status would print; the menu below offers them instead.
-  if (op.error) lines.push(`  error: ${op.error.split("; next actions: ")[0]}`);
-  return lines;
-}
-
 /**
  * Print steps and readiness waits until the operation completes, blocks or loses its runner ("open"), the person
  * enters a line (also "open": the menu), or presses Ctrl+C ("left"). `scheduled` is the receipt's `updatedAt` from
@@ -123,15 +123,27 @@ export function operationLines(op: RecoveryOperation, runner: number | "unknown"
  * it was scheduled from, which is not the outcome.
  */
 export async function follow(host: UpgradeHost, io: ScreenIO, id: string, scheduled?: number): Promise<"completed" | "open" | "left"> {
-  let step = "", waiting = "", unowned = 0, tick = 0;
+  let step = "", waiting = "", unowned = 0, tick = 0, started = clock(io), lastWaitAt = -Infinity;
+  const resuming = scheduled !== undefined;
+  let resumeAnnounced = false;
   for (;; tick++) {
     const op = host.read(id);
-    if (io.interrupted()) { io.out(left(op)); return "left"; }
+    if (io.interrupted()) { human(io, left(op, io)); return "left"; }
     if (io.typed()) return "open";
     const unwritten = scheduled !== undefined && op.updatedAt === scheduled;
     if (!unwritten) {
       scheduled = undefined;
-      if (op.step !== step) { step = op.step; waiting = ""; tick = 0; io.out(`  ${stepLabel(step)}`); }
+      if (op.step !== step) {
+        const now = clock(io);
+        if (io.presentation && step) emit(io, renderStep(resuming && step === "stage" ? "checking retained release" : stepLabel(step), "done", Math.max(0, now - started), io.presentation));
+        step = op.step; waiting = ""; tick = 0; started = now; lastWaitAt = -Infinity;
+        if (io.presentation) {
+          if (resuming && !resumeAnnounced) { human(io, `resuming from ${step === "stage" ? "checking retained release" : stepLabel(step)}`); resumeAnnounced = true; }
+          if (op.phase === "blocked") emit(io, renderStep(stepLabel(step), "blocked", undefined, io.presentation));
+          else if (op.phase === "completed") emit(io, renderStep(stepLabel(step), "done", undefined, io.presentation));
+          else emit(io, renderStep(resuming && step === "stage" ? "checking retained release" : stepLabel(step), "running", undefined, io.presentation));
+        } else human(io, `  ${stepLabel(step)}`);
+      }
       if (op.phase === "completed") return "completed";
       if (op.phase === "cancelled" || op.phase === "blocked") return "open";
     }
@@ -143,9 +155,20 @@ export async function follow(host: UpgradeHost, io: ScreenIO, id: string, schedu
       // A hub that is not ready and names no cause (one older than #272 lists only busy peers and approvals) still waits.
       const held = Object.values(live).some((i) => i?.recovery?.operationId === id && i.recovery.ready === false);
       const now = [...new Set(Object.values(live).flatMap((i) => i?.recovery?.waiting ?? []))].join(", ") || (held ? "the hub is not quiet yet (it names no cause: a completion check, a task command or a Pi call may be in flight)" : "");
-      if (now && now !== waiting) io.out(`    waiting for: ${now}`);
+      if (now && (now !== waiting || io.presentation && clock(io) - lastWaitAt >= 60_000)) {
+        lastWaitAt = clock(io);
+        if (io.presentation) emit(io, renderWait(op, step, Object.values(live).flatMap(value => value?.recovery?.waiting ?? []).length ? Object.values(live).flatMap(value => value?.recovery?.waiting ?? []) : [now], io.presentation));
+        else human(io, `    waiting for: ${now}`);
+      }
       waiting = now;
     }
+    if (io.presentation && !unwritten && !/^(re)?prepare:/.test(step) && op.waits?.[step] && !op.waits[step]!.waitEndedAt && tick % 8 === 0) {
+      const reason = "waiting for the recorded native session to attach";
+      if (waiting !== reason || clock(io) - lastWaitAt >= 60_000) {
+        emit(io, renderWait(op, step, [reason], io.presentation));
+        waiting = reason; lastWaitAt = clock(io);
+      }
+    }
     await io.sleep(250);
   }
 }
@@ -162,22 +185,22 @@ export async function endAgents(host: UpgradeHost, io: ScreenIO, endable: { plan
   const of = (kind: string) => endable.filter((e) => peerKind(e.planned, e.peer) === kind);
   const tui = of("tui"), headless = of("headless");
   const choices = [...(tui.length ? [`[t] the TUI agents (${tui.map(label).join(", ")})`] : []), ...(headless.length ? [`[h] the headless agents (${headless.map(label).join(", ")})`] : []), "or names separated by spaces", "[Enter] none"];
-  const words = new Set(((await io.ask(`End which agents? ${choices.join("  ")}: `)) ?? "").toLowerCase().split(/\s+/).filter(Boolean));
+  const words = new Set(((await ask(io, `End which agents? ${choices.join("  ")}: `)) ?? "").toLowerCase().split(/\s+/).filter(Boolean));
   const picked = new Set<Agent>(), unknown: string[] = [], ambiguous: string[] = [];
   for (const word of words) {
     const named = word === "t" ? tui : word === "h" ? headless : endable.filter((e) => word === full(e) || word === e.peer.id);
     if (word === "t" || word === "h" || named.length === 1) for (const e of named) picked.add(e);
     else (named.length ? ambiguous : unknown).push(word);
   }
-  if (unknown.length) io.out(`not an agent that can be ended here: ${unknown.join(", ")}`);
-  if (ambiguous.length) io.out(`${ambiguous.join(", ")}: attached in several projects; name the one to end with its project (${endable.filter((e) => ambiguous.includes(e.peer.id)).map(full).join(", ")})`);
+  if (unknown.length) human(io, `not an agent that can be ended here: ${unknown.join(", ")}`);
+  if (ambiguous.length) human(io, `${ambiguous.join(", ")}: attached in several projects; name the one to end with its project (${endable.filter((e) => ambiguous.includes(e.peer.id)).map(full).join(", ")})`);
   const chosen = endable.filter((e) => picked.has(e));
-  if (!chosen.length) { io.out("no agent was ended"); return false; }
-  if (!(await yes(io, `End ${chosen.map(label).join(", ")} now? A TUI agent's terminal is closed, a turn in progress is cut, and none of them is restored by the upgrade. [y/N] `))) { io.out("no agent was ended"); return false; }
+  if (!chosen.length) { human(io, "no agent was ended"); return false; }
+  if (!(await yes(io, `End ${chosen.map(label).join(", ")} now? A TUI agent's terminal is closed, a turn in progress is cut, and none of them is restored by the upgrade. [y/N] `))) { human(io, "no agent was ended"); return false; }
   let asked = 0;
   for (const e of chosen) {
-    if (io.interrupted()) { io.out(`interrupted: ${chosen.length - asked} of ${chosen.length} left alone (${chosen.slice(asked).map(label).join(", ")})`); break; }
-    io.out(`  ${await host.endPeer(e.planned, e.peer)}`);
+    if (io.interrupted()) { human(io, `interrupted: ${chosen.length - asked} of ${chosen.length} left alone (${chosen.slice(asked).map(label).join(", ")})`); break; }
+    human(io, `  ${await host.endPeer(e.planned, e.peer)}`);
     asked++;
   }
   return asked > 0;
@@ -185,18 +208,19 @@ export async function endAgents(host: UpgradeHost, io: ScreenIO, endable: { plan
 
 /** `ahub reset` for one project: the scope, its dry run, a confirmation, then the reset itself. */
 export async function resetFlow(host: UpgradeHost, io: ScreenIO, projects: { id: string; root: string }[]): Promise<void> {
-  if (host.lock()) return io.out("an operation holds the recovery lock; cancel or end it before a reset");
+  if (host.lock()) return human(io, "an operation holds the recovery lock; cancel or end it before a reset");
   let project = projects[0];
   if (projects.length > 1) {
-    projects.forEach((p, i) => io.out(`  ${i + 1}  ${p.id}  ${p.root}`));
-    project = projects[Number(await io.ask("Reset which project? [number, Enter: none] ")) - 1];
+    projects.forEach((p, i) => human(io, `  ${i + 1}  ${p.id}  ${p.root}`));
+    project = projects[Number(await ask(io, "Reset which project? [number, Enter: none] ")) - 1];
   }
-  if (!project) return io.out("nothing was reset");
-  const scope = ((await io.ask("[r] runtime reset (deliveries, holds, pauses, session pointers)  [a] full reset (archive the state directory)  [Enter] none: ")) ?? "").toLowerCase();
-  if (scope !== "r" && scope !== "a") return io.out("nothing was reset");
+  if (!project) return human(io, "nothing was reset");
+  const scope = ((await ask(io, "[r] runtime reset (deliveries, holds, pauses, session pointers)  [a] full reset (archive the state directory)  [Enter] none: ")) ?? "").toLowerCase();
+  if (scope !== "r" && scope !== "a") return human(io, "nothing was reset");
   const reset = [host.entry, "--project", project.root, "reset", ...(scope === "a" ? ["--all"] : [])];
   if ((await io.run(reset)) !== 0) return; // the dry run: it lists and changes nothing
-  if (!(await yes(io, `Apply this reset of ${project.id}? [y/N] `))) return io.out("nothing was reset");
+  const consequence = scope === "a" ? "archive this project's hub state" : "reset delivery holds, pauses and session pointers";
+  if (!(await yes(io, io.presentation ? `Reset ${project.id}: ${consequence}? [y/N] ` : `Apply this reset of ${project.id}? [y/N] `))) return human(io, "nothing was reset");
   await io.run([...reset, "--yes"]);
 }
 
@@ -205,44 +229,54 @@ export async function operationScreen(host: UpgradeHost, io: ScreenIO, id: strin
   for (let acted = false, reset = false; ;) {
     if (io.interrupted()) return "quit";
     const op = host.read(id), runner = host.runner(id);
-    if (op.phase === "completed") { io.out(`${op.plan.kind} to ${op.plan.version} completed`); return "completed"; }
+    if (op.phase === "completed") { if (io.presentation) await summary(host, io, op); else human(io, `${op.plan.kind} to ${op.plan.version} completed`); return "completed"; }
     if (op.phase === "cancelled") {
-      io.out(`operation ${id} is ${op.disposition ? "ended (abandoned, not completed)" : "cancelled"}; the recovery lock is free`);
+      if (io.presentation) await summary(host, io, op);
+      else human(io, `operation ${id} is ${op.disposition ? "ended (abandoned, not completed)" : "cancelled"}; the recovery lock is free`);
       // Ended from this screen: the reset the person may have come for is one key away.
       if (acted && !reset && await yes(io, "Reset a project's hub now? [y/N] ")) await resetFlow(host, io, op.plan.projects.map((p) => p.project));
       return "ended";
     }
     const live = runner ? {} : await host.live(op);
-    io.out("");
-    for (const line of operationLines(op, runner, Date.now())) io.out(line);
-    const run = async (action: "resume" | "abort" | "dispose", flags: string[] = []) => { acted = true; return (await io.run(recoveryArgv(op, action, flags))) === 0; };
+    human(io, "");
+    if (io.presentation) emit(io, renderOperation(op, runner, io.presentation));
+    else for (const line of operationLines(op, runner, Date.now())) human(io, line);
+    const run = async (action: "resume" | "abort" | "dispose" | "reattach", flags: string[] = []) => { acted = true; return (await io.run(recoveryArgv(op, action, flags))) === 0; };
     // A runner scheduled by a command has not written yet: follow from the receipt as that command left it (resume
     // writes nothing, a fresh-session choice records itself first).
     const followed = async (): Promise<boolean> => (await follow(host, io, id, host.read(id).updatedAt)) === "left";
     const end = async (): Promise<boolean> => {
-      if (!(await yes(io, "End this operation? Its own targets are stopped and the upgrade is abandoned, not completed. [y/N] "))) return false;
-      const reason = await io.ask("Reason for the audit [Enter: ended from the upgrade screen]: ");
+      if (!(await yes(io, io.presentation ? `Stop this operation's ${op.plan.version} targets? The upgrade is abandoned, not completed; sessions remain recorded. [y/N] ` : "End this operation? Its own targets are stopped and the upgrade is abandoned, not completed. [y/N] "))) return false;
+      const reason = await ask(io, "Reason for the audit [Enter: ended from the upgrade screen]: ");
       if (reason === null) return false; // Ctrl+C or the end of input is never a reason
       return run("dispose", ["--stop-and-archive", "--reason", reason.slice(0, 500) || "ended from the upgrade screen"]);
     };
     // An act returns true when the person left (Ctrl+C in a follow).
-    const menu = new Map<string, { label: string; act: () => Promise<boolean | void> }>();
+    const menu = new Map<string, { label: string; disabledReason?: string; act: () => Promise<boolean | void> }>();
     if (typeof runner === "number") {
       menu.set("w", { label: "follow its progress", act: async () => (await follow(host, io, id)) === "left" });
       if (cancellableWait(op) && host.runnerStoppable(id)) menu.set("c", { label: "cancel: stop the waiting runner and cancel (nothing was closed or stopped)", act: async () => {
         // Decided again on the receipt as it is now: the runner may have moved on while the menu was read.
-        if (!cancellableWait(host.read(id)) || !host.runnerStoppable(id)) return io.out("the runner moved on; nothing was stopped or cancelled");
+        if (!cancellableWait(host.read(id)) || !host.runnerStoppable(id)) return human(io, "the runner moved on; nothing was stopped or cancelled");
         if (await host.stopRunner(id)) await run("abort");
-        else io.out("the runner could not be stopped; nothing was cancelled");
+        else human(io, "the runner could not be stopped; nothing was cancelled");
       } });
-      else if (cancellableWait(op)) io.out("  cancel is not offered: this runner's claim cannot be verified (an older coordinator's, or unreadable); a live runner gives up its wait after 10 minutes");
+      else if (cancellableWait(op)) human(io, "  cancel is not offered: this runner's claim cannot be verified (an older coordinator's, or unreadable); a live runner gives up its wait after 10 minutes");
     }
-    for (const choice of nextChoices(op, runner, live)) {
-      if (choice.kind === "wait") { if (typeof runner !== "number") io.out(`  ${choice.text}`); }
-      else if (choice.kind === "resume") menu.set("r", { label: `resume${op.error ? " (after the step the error names)" : ""}`, act: async () => (await run("resume")) && followed() });
+    const choices = nextChoices(op, runner, live);
+    if (io.presentation && op.phase === "blocked") emit(io, renderBlocked(op, choices, io.presentation));
+    for (const choice of choices) {
+      if (choice.kind === "wait") { if (typeof runner !== "number") {
+        if (io.presentation && op.phase !== "blocked") human(io, choiceInstruction(op, choice, io.presentation));
+        if (io.presentation) menu.set("w", { label: "wait for the current recovery condition", disabledReason: runner === "unknown" ? "runner ownership is unknown; refresh to read its claim" : "no verified runner is working; refresh after the reported condition changes", act: async () => {} });
+        else human(io, `  ${choice.text}`);
+      } }
+      else if (choice.kind === "resume") menu.set("r", { label: io.presentation ? op.error ? "resume after reviewing the recorded failure" : "resume from the recorded step" : `resume${op.error ? " (after the step the error names)" : ""}`, act: async () => (await run("resume")) && followed() });
       else if (choice.kind === "abort") menu.set("c", { label: "cancel (no runtime was stopped; nothing to roll back)", act: async () => { await run("abort"); } });
+      else if (choice.kind === "reattach") menu.set("a", { label: `reattach ${choice.peer} with its recorded session only (then resume to finish)`, act: async () => { await run("reattach", [choice.peer!]); } });
       else if (choice.kind === "fresh") menu.set(menu.has("f") ? `f-${choice.peer}` : "f", { label: `start ${choice.peer} as a new session (its conversation is recorded as lost)`, act: async () => {
-        const reason = await io.ask(`Reason for losing ${choice.peer}'s conversation [Enter: go back]: `);
+        if (io.presentation && !(await yes(io, `Start ${choice.peer} fresh? Its recorded conversation is marked lost. [y/N] `))) return;
+        const reason = await ask(io, `Reason for losing ${choice.peer}'s conversation [Enter: go back]: `);
         return !!reason && (await run("dispose", ["--fresh-session", choice.peer!, "--reason", reason.slice(0, 500)])) && followed();
       } });
       else {
@@ -252,11 +286,17 @@ export async function operationScreen(host: UpgradeHost, io: ScreenIO, id: strin
     }
     menu.set("s", { label: "refresh", act: async () => {} });
     menu.set("j", { label: "receipt as JSON", act: async () => io.out(JSON.stringify(publicOperation(op, runner, live), null, 2)) });
-    for (const [key, item] of menu) io.out(`  [${key}] ${item.label}`);
-    io.out("  [q] quit (the operation stays as it is)");
-    const answer = await io.ask("> ");
+    const preferred = [typeof runner === "number" ? "w" : runner === "unknown" ? "s" : "j", "s"].find(key => menu.has(key) && !menu.get(key)!.disabledReason);
+    if (io.presentation) {
+      const items: MenuPresentationItem[] = [...menu].map(([key, item]) => ({ key, label: item.label, ...(item.disabledReason ? { disabledReason: item.disabledReason } : {}), ...(key === preferred ? { recommended: true } : {}), ...(["e", "x"].includes(key) || key === "f" || key.startsWith("f-") ? { destructive: true } : {}) }));
+      emit(io, renderMenu(items, io.presentation));
+    } else for (const [key, item] of menu) human(io, `  [${key}] ${item.label}`);
+    human(io, "  [q] quit (the operation stays as it is)");
+    const answer = await ask(io, "> ");
     if (answer === null || answer.toLowerCase() === "q") return "quit";
-    if ((await menu.get(answer.toLowerCase())?.act()) === true) return "quit";
+    const selected = menu.get(io.presentation && answer === "" ? preferred ?? "s" : answer.toLowerCase());
+    if (selected?.disabledReason) { human(io, `disabled: ${selected.disabledReason}`); continue; }
+    if ((await selected?.act()) === true) return "quit";
   }
 }
 
@@ -272,24 +312,39 @@ export async function planScreen(host: UpgradeHost, io: ScreenIO): Promise<void>
     }
     const plan = await host.plan();
     if (io.interrupted()) return;
-    io.out("");
-    for (const line of planLines(plan, host.version)) io.out(line);
+    human(io, "");
+    if (io.presentation) emit(io, renderPlan(plan, host.version, io.presentation, planLines(plan, host.version)));
+    else for (const line of planLines(plan, host.version)) human(io, line);
     const blocked = plan.blockers.length > 0 || plan.projects.some((p) => p.blockers.length > 0);
-    if (!plan.projects.length) io.out(plan.kind === "upgrade" ? `no hub is running, so nothing is carried over: install with \`bun add -g @staix/agent-hub@${plan.version}\`, then \`ahub setup\`` : "this project's hub is not running: `ahub up` starts it");
+    if (!plan.projects.length) human(io, plan.kind === "upgrade" ? `no hub is running, so nothing is carried over: install with \`bun add -g @staix/agent-hub@${plan.version}\`, then \`ahub setup\`` : "this project's hub is not running: `ahub up` starts it");
     const endable = plan.projects.flatMap((p) => p.source.peers.filter((peer) => ["tui", "headless"].includes(peerKind(p, peer))).map((peer) => ({ planned: p, peer })));
     const keys = [...(blocked ? [] : ["[a] apply"]), "[r] refresh", ...(endable.length ? ["[k] end agents"] : []), "[j] plan as JSON", ...(plan.projects.length ? ["[x] reset a project's hub"] : []), "[q] quit"];
-    const answer = (await io.ask(`${blocked ? "Blocked: take the next action each blocker names, then refresh.\n" : ""}${keys.join("  ")}: `))?.toLowerCase() ?? "q";
-    if (answer === "q") return touched ? undefined : io.out("nothing was changed");
+    const preferred = "r"; // Enter never closes terminals, stops a hub, resumes or reattaches implicitly.
+    if (io.presentation) {
+      if (blocked) human(io, "Blocked: take the next action each blocker names, then refresh.");
+      const items: MenuPresentationItem[] = [
+        ...(!blocked ? [{ key: "a", label: "apply this reviewed plan" }] : []),
+        { key: "r", label: "refresh the plan", recommended: preferred === "r" },
+        ...(endable.length ? [{ key: "k", label: "end selected agents before upgrading", destructive: true }] : []),
+        { key: "j", label: "plan as JSON" },
+        ...(plan.projects.length ? [{ key: "x", label: "reset a project's hub", destructive: true }] : []),
+        { key: "q", label: "quit" },
+      ];
+      emit(io, renderMenu(items, io.presentation));
+    }
+    const entered = (await ask(io, io.presentation ? "> " : `${blocked ? "Blocked: take the next action each blocker names, then refresh.\n" : ""}${keys.join("  ")}: `))?.toLowerCase();
+    const answer = entered === undefined ? "q" : io.presentation && entered === "" ? preferred : entered;
+    if (answer === "q") return touched ? undefined : human(io, "nothing was changed");
     if (answer === "j") io.out(JSON.stringify(plan, null, 2));
     else if (answer === "x" && plan.projects.length) { touched = true; await resetFlow(host, io, plan.projects.map((p) => p.project)); }
     else if (answer === "k" && endable.length) touched = (await endAgents(host, io, endable)) || touched;
     else if (answer === "a" && !blocked) {
       touched = true;
       let op: RecoveryOperation;
-      try { op = await host.apply(plan, () => io.interrupted()); } catch (error) { io.out(`ahub: ${(error as Error).message}`); continue; }
-      io.out(`operation ${op.id} started; Enter opens its menu, Ctrl+C leaves, and neither stops the ${plan.kind}`);
+      try { op = await host.apply(plan, () => io.interrupted()); } catch (error) { human(io, `ahub: ${(error as Error).message}`); continue; }
+      human(io, `operation ${op.id} started; Enter opens its menu, Ctrl+C leaves, and neither stops the ${plan.kind}`);
       const end = await follow(host, io, op.id);
-      if (end === "completed") return io.out(`${plan.kind} to ${plan.version} completed`);
+      if (end === "completed") { if (io.presentation) await summary(host, io, host.read(op.id)); else human(io, `${plan.kind} to ${plan.version} completed`); return; }
       if (end === "left") return;
       // Blocked, cancelled or left to its runner: the lock check above opens its screen, or plans again once it is free.
     }

package/src/cli/upgrade-labels.ts

@@ -0,0 +1,30 @@
+import { restoreReceiptStatus } from "./upgrade-restore-state.ts";
+import type { RecoveryOperation } from "./upgrade.ts";
+
+const STEPS: Record<string, string> = {
+  stage: "staging the release", prepare: "holding deliveries and waiting until the hub is quiet", reprepare: "preparing the source again after an expired hold",
+  commit: "closing terminals and stopping the old hub", restart: "restarting a target that stopped", start: "starting the new hub", restore: "restoring Codex and Pi sessions",
+  "install-plugin": "installing the Claude plugin", "restore-claude": "restoring the Claude session and verifying the hub", release: "releasing held deliveries",
+  "refresh-manager": "refreshing the dashboard manager", "install-global": "installing the global CLI", completed: "completed", cancelled: "cancelled",
+};
+
+/** A receipt step (`commit:<project>`) in a person's words; a step this release does not know is shown as it is. */
+export function stepLabel(step: string): string {
+  const at = step.indexOf(":"), name = at < 0 ? step : step.slice(0, at);
+  return STEPS[name] ? `${at < 0 ? "" : `${step.slice(at + 1)}: `}${STEPS[name]}` : step;
+}
+
+const ago = (ms: number): string => ms < 90_000 ? `${Math.max(0, Math.round(ms / 1000))}s` : ms < 5_400_000 ? `${Math.round(ms / 60_000)}m` : `${Math.round(ms / 3_600_000)}h`;
+
+export function operationLines(op: RecoveryOperation, runner: number | "unknown" | undefined, now: number): string[] {
+  const held = runner === "unknown" ? "; whether a runner holds it cannot be read" : runner ? `; runner ${runner} is working` : op.phase === "running" ? "; no runner holds it (the last one stopped mid-step)" : "";
+  const lines = [`${op.plan.kind} to ${op.plan.version}: operation ${op.id}`, `  ${op.phase} at "${stepLabel(op.step)}", updated ${ago(now - op.updatedAt)} ago${held}`];
+  for (const p of op.projects) {
+    const effects = Object.entries(p.terminals).map(([key, value]) => key.startsWith("restored:") ? `${key} ${restoreReceiptStatus(value)}` : value === "pending" || value === "failed" ? `${key} ${value}` : key);
+    lines.push(`  ${p.id}  ${p.phase}${effects.length ? `  (${effects.join(", ")})` : ""}${p.restarts?.length ? `  restarts ${p.restarts.length}` : ""}`);
+  }
+  // The error ends with the commands status would print; the menu below offers them instead.
+  if (op.error) lines.push(`  error: ${op.error.split("; next actions: ")[0]}`);
+  return lines;
+}
+