@staix/agent-hub 0.12.31 → 0.12.33

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/reset.ts

@@ -4,6 +4,7 @@ import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync,
 import { join } from "node:path";
 import { Bus } from "../hub/bus.ts";
 import { DeliveryJournal } from "../hub/delivery-journal.ts";
+import { validateDeferredHub } from "../hub/deferred-hub.ts";
 import type { Project } from "../hub/registry.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "../hub/db-timeout.ts";
 
@@ -73,7 +74,14 @@ export function planReset(stateDir: string, projectId: string): ResetPlan {
     const bus: unknown = JSON.parse(meta?.bus_snapshot || "{}"), manual: unknown = JSON.parse(meta?.manual_paused || "[]");
     shaped(isList(manual, isText), "manual_paused");
     shaped(isObject(bus) && (bus.manualPaused === undefined || isList(bus.manualPaused, isText)) && (bus.queues === undefined || (isObject(bus.queues) && Object.values(bus.queues).every((queue) => isList(queue, isEnvelope)))), "bus_snapshot");
-    const { queues = {}, manualPaused = [] } = bus as { queues?: Record<string, { id: string }[]>; manualPaused?: string[] };
+    const { queues = {}, manualPaused = [], seen = [], deferredHub } = bus as {
+      queues?: Record<string, { id: string }[]>; manualPaused?: string[]; seen?: { id: string }[]; deferredHub?: unknown;
+    };
+    shaped(isList(seen, isEnvelope), "bus_snapshot.seen");
+    // Deferred notices are pending delivery too, but must not be published just to preview or reset them.
+    const deferred = validateDeferredHub(deferredHub, undefined, new Set([
+      ...seen.map(env => env.id), ...Object.values(queues).flat().map(env => env.id),
+    ]));
     plan.manualHolds = [...new Set([...manual as string[], ...manualPaused])].sort();
     // As Bus.queueList: a queued envelope that no open row stands for is listed as q:<peer>:<envelope id>.
     // ponytail: the rule is copied so the dry run never opens the journal for writing; the reset tests compare the
@@ -84,6 +92,9 @@ export function planReset(stateDir: string, projectId: string): ResetPlan {
       return (originals as { id: string }[]).map((env) => `${row.peer}:${env.id}`);
     }));
     for (const [peer, queue] of Object.entries(queues)) for (const env of queue) if (!recorded.has(`${peer}:${env.id}`)) plan.queued.push(`q:${peer}:${env.id}`);
+    for (const env of deferred) for (const peer of new Set(env.to)) {
+      if (!recorded.has(`${peer}:${env.id}`)) plan.queued.push(`q:${peer}:${env.id}`);
+    }
   } finally { db.close(); }
   return plan;
 }
@@ -114,6 +125,7 @@ export function resetRuntime(stateDir: string, project: Project): { settled: str
     const journal = new DeliveryJournal({ file, projectRoot: project.root, projectId: project.id, instanceId: randomUUID() });
     const bus = new Bus({ journal });
     try {
+      settled.push(...bus.discardDeferredHub("reset"));
       for (const { id } of bus.queueList().filter((row) => row.state === "queued" || row.state === "needs_review")) {
         // Read again each time: a queue entry's revision is the journal's, and every resolution moves it on.
         bus.resolveDelivery(id, bus.queueShow(id)!.revision, "discard", "reset");

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.