@staix/agent-hub 0.12.31 → 0.12.33

package/src/cli/upgrade-interactive.ts

@@ -1,4 +1,7 @@
-import { restoreReceiptStatus } from "./upgrade-restore-state.ts";
+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";
 
@@ -11,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;
@@ -35,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. */
@@ -45,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
@@ -61,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)";
@@ -103,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]) => 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;
-}
-
 /**
  * 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
@@ -124,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";
     }
@@ -144,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);
   }
 }
@@ -163,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;
@@ -186,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"]);
 }
 
@@ -206,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 {
@@ -253,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";
   }
 }
 
@@ -273,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;
+}
+

package/src/cli/upgrade-presentation-data.ts

@@ -0,0 +1,41 @@
+/** Read-only observations of a coordinator wait, never input to its deadline or decisions. */
+export interface RecoveryWaitTiming {
+  readonly waitStartedAt: string;
+  readonly deadlineAt: string;
+  readonly waitEndedAt?: string;
+}
+
+export type RecoveryPreservationCheck = "queues" | "manualPaused" | "boardDigest" | "budgetDigest";
+
+export interface RecoveryPreservationCause {
+  readonly kind: "preservation";
+  readonly check: RecoveryPreservationCheck;
+  readonly projectId?: string;
+}
+
+export interface RecoveryNativeCause {
+  readonly kind: "native_recovery";
+  readonly reason: "terminal_unverified" | "session_changed" | "launcher_unverified" | "target_unavailable" | "attachment_timeout";
+  readonly projectId: string;
+  readonly peer: string;
+  readonly handle?: string;
+  readonly expectedSession?: string;
+  readonly observedSession?: string;
+  readonly targetState?: string;
+  readonly launcherState?: string;
+  readonly timeoutMs?: number;
+}
+
+export type RecoveryPresentationCause = RecoveryPreservationCause | RecoveryNativeCause;
+
+/** Only a guard with observed evidence constructs this error; messages are never classification input. */
+export class RecoveryPresentationError extends Error {
+  constructor(message: string, readonly presentationCause: RecoveryPresentationCause) { super(message); }
+}
+
+/** The failing integrity comparison supplies the cause; presentation never parses the error text. */
+export class RecoveryPreservationError extends RecoveryPresentationError {
+  constructor(check: RecoveryPreservationCheck, projectId?: string) {
+    super("queue, manual pause, task board or budget preservation was not verified", { kind: "preservation", check, ...(projectId === undefined ? {} : { projectId }) });
+  }
+}

package/src/cli/upgrade-presentation-flags.ts

@@ -0,0 +1,31 @@
+import { recoveryPresentationFlag } from "./recovery-presentation-options.ts";
+import { resolveColor } from "./console-state.ts";
+import type { RecoveryPresentationOptions } from "./upgrade-presentation.ts";
+
+/** Presentation flags never consume another option's audit, version or peer value. */
+export function readRecoveryPresentationFlags(
+  argv: readonly string[],
+  terminal: { isTTY: boolean; columns?: number; TERM?: string; NO_COLOR?: string },
+  now: () => number = Date.now,
+): { args: string[]; flags: string[]; json: boolean; options: RecoveryPresentationOptions } {
+  const args: string[] = [], flags: string[] = [];
+  let color: string | undefined, json = false, verbose = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!, flag = recoveryPresentationFlag(arg);
+    if (["--reason", "--fresh-session", "--to"].includes(arg)) {
+      args.push(arg);
+      if (i + 1 < argv.length) args.push(argv[++i]!);
+    } else if (arg === "--color") {
+      throw new Error("usage: ahub <command> [--color=auto|always|never]");
+    } else if (flag?.kind === "color") {
+      if (color !== undefined) throw new Error("usage: ahub <command> [--color=auto|always|never]");
+      color = flag.value; flags.push(arg);
+    } else if (flag?.kind === "json") { json = true; flags.push(arg); }
+    else if (flag?.kind === "verbose") { verbose = true; flags.push(arg); }
+    else args.push(arg);
+  }
+  const resolved = resolveColor(color, terminal);
+  if (resolved instanceof Error) throw resolved;
+  const columns = terminal.columns !== undefined && Number.isFinite(terminal.columns) && terminal.columns > 0 ? Math.floor(terminal.columns) : 80;
+  return { args, flags, json, options: { columns, color: resolved, verbose, now } };
+}