@staix/agent-hub 0.12.29 → 0.12.31

package/src/cli/upgrade-restore-state.ts

@@ -0,0 +1,133 @@
+import type { TerminalBinding } from "./terminal-recovery.ts";
+
+export type RestoreReceipt =
+  | { state: "pending" }
+  | { state: "waiting"; origin: "pending" | "failed"; binding: TerminalBinding }
+  | { state: "done"; binding: TerminalBinding }
+  | { state: "failed" };
+export interface RestoreEvidence {
+  target: "running" | "stopped" | "changed";
+  launcher: "live" | "gone" | "unknown" | "no-record-yet" | "replaced" | "older-instance";
+  session: "planned" | "other" | "none";
+  allowOther: boolean;
+  /** The original or verified selected terminal when a bare receipt first acquires a binding. */
+  binding?: TerminalBinding;
+}
+export type RestoreAction = "poll" | "settle" | "revalidate" | "block" | "fail" | "create";
+export interface RestoreTransition { next: RestoreReceipt; action: RestoreAction }
+export type RestoreReceiptStatus = "unstarted" | "pending" | "waiting:pending" | "waiting:failed" | "done" | "failed";
+
+function malformed(): never { throw new Error("invalid restore receipt"); }
+const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+function terminalBinding(value: unknown): TerminalBinding {
+  if (!object(value) || typeof value.peer !== "string" || !["codex", "claude", "pi"].includes(value.peer)) malformed();
+  for (const key of ["handle", "incarnationId", "worktreeId", "projectRoot", "sessionId"]) if (!text(value[key])) malformed();
+  for (const key of ["sessionFile", "backend", "model"]) if (value[key] !== undefined && typeof value[key] !== "string") malformed();
+  const launch = value.launch;
+  const validLaunch = (v: unknown) => object(v) && text(v.packageEntrypoint) && text(v.command)
+    && Array.isArray(v.argv) && v.argv.every(arg => typeof arg === "string")
+    && object(v.env) && Object.values(v.env).every(entry => typeof entry === "string");
+  if (!validLaunch(launch) || value.launchMetadata !== undefined && !validLaunch(value.launchMetadata)) malformed();
+  return { ...value, launchMetadata: value.launchMetadata ?? launch } as unknown as TerminalBinding;
+}
+
+/** Decode legacy representations only here. Absence is unstarted, never pending or failed. */
+export function decodeRestoreReceipt(value: unknown): RestoreReceipt | undefined {
+  if (value === undefined) return undefined;
+  if (value === "pending" || value === "failed") return { state: value };
+  if (!object(value)) malformed();
+  if (Object.hasOwn(value, "state")) {
+    const allowed = value.state === "waiting" ? ["state", "origin", "binding"] : value.state === "done" ? ["state", "binding"] : ["state"];
+    if (Object.keys(value).some(key => !allowed.includes(key))) malformed();
+    switch (value.state) {
+      case "pending": case "failed": return { state: value.state };
+      case "waiting": {
+        if (value.origin !== "pending" && value.origin !== "failed") malformed();
+        return { state: "waiting", origin: value.origin, binding: terminalBinding(value.binding) };
+      }
+      case "done": return { state: "done", binding: terminalBinding(value.binding) };
+      default: return malformed();
+    }
+  }
+  if (Object.hasOwn(value, "attachmentReceipt")) malformed();
+  return { state: "done", binding: terminalBinding(value) };
+}
+
+export function restoreReceiptStatus(value: unknown): RestoreReceiptStatus {
+  const receipt = decodeRestoreReceipt(value);
+  return !receipt ? "unstarted" : receipt.state === "waiting" ? `waiting:${receipt.origin}` : receipt.state;
+}
+export function canChooseFresh(value: unknown): boolean {
+  const receipt = decodeRestoreReceipt(value);
+  return receipt?.state === "failed" || receipt?.state === "waiting" && receipt.origin === "failed";
+}
+
+/** Pure decision only: settlement/revalidation must succeed before the runtime persists its proposed next receipt. */
+export function restoreTransition(receipt: RestoreReceipt, evidence: RestoreEvidence): RestoreTransition {
+  const keep = (action: RestoreAction): RestoreTransition => ({ next: receipt, action });
+  if (evidence.target !== "running") return keep("block");
+  // A chosen waiting terminal cannot be replaced by another identity, even if a session has attached meanwhile.
+  if (receipt.state === "waiting" && ["unknown", "replaced", "older-instance"].includes(evidence.launcher)) return keep("block");
+  if (evidence.session === "other" && (!evidence.allowOther || receipt.state === "done")) return keep("block");
+  if (evidence.session === "planned" || evidence.session === "other" && evidence.allowOther) {
+    if (receipt.state === "done") return keep("revalidate");
+    const binding = receipt.state === "waiting" ? receipt.binding : evidence.binding;
+    return binding ? { next: { state: "done", binding }, action: "settle" } : keep("block");
+  }
+  if (receipt.state === "done") return keep("block");
+  if (evidence.launcher === "unknown" || evidence.launcher === "replaced" || evidence.launcher === "older-instance") return keep("block");
+  if (receipt.state === "waiting" && (evidence.launcher === "live" || evidence.launcher === "no-record-yet")) return keep("poll");
+  const origin = receipt.state === "waiting" ? receipt.origin : receipt.state;
+  if (evidence.launcher === "live") return evidence.binding
+    ? { next: { state: "waiting", origin, binding: evidence.binding }, action: "poll" }
+    : keep("block");
+  // Bare pending/failed have no chosen saved terminal: never infer that an absent record is an outstanding bound wait.
+  return { next: { state: "failed" }, action: origin === "pending" ? "fail" : "create" };
+}
+
+/** Checkable compact documentation, enumerated through the same pure decision function. */
+export function renderRestoreTransitionTable(): string {
+  const launch = { packageEntrypoint: "table", command: "table", argv: [], env: {} };
+  const binding: TerminalBinding = { peer: "codex", handle: "selected", incarnationId: "selected", worktreeId: "selected", projectRoot: "table", sessionId: "planned", launch, launchMetadata: launch };
+  const receipts: RestoreReceipt[] = [{ state: "pending" }, { state: "waiting", origin: "pending", binding }, { state: "waiting", origin: "failed", binding }, { state: "done", binding }, { state: "failed" }];
+  const launchers: RestoreEvidence["launcher"][] = ["live", "gone", "unknown", "no-record-yet", "replaced", "older-instance"];
+  const result = (receipt: RestoreReceipt, evidence: RestoreEvidence, unchanged = false) => {
+    const next = restoreTransition(receipt, evidence);
+    const status = restoreReceiptStatus(next.next);
+    return `${next.action} -> ${unchanged && status === restoreReceiptStatus(receipt) ? "unchanged" : status}${canChooseFresh(next.next) && !(unchanged && status === restoreReceiptStatus(receipt)) ? "; fresh" : ""}`;
+  };
+  const table = (title: string, sessions: readonly { session: RestoreEvidence["session"]; allowOther: boolean }[]) => [
+    title,
+    "",
+    `| Receipt | ${launchers.join(" | ")} |`,
+    `|---|${launchers.map(() => "---").join("|")}|`,
+    ...receipts.map(receipt => `| ${restoreReceiptStatus(receipt)} | ${launchers.map(launcher => {
+      const variants = sessions.map(session => ({ session: session.session, result: result(receipt, { target: "running", launcher, ...session, binding }) }));
+      const outcomes = [...new Set(variants.map(value => value.result))];
+      return outcomes.length === 1 ? outcomes[0]! : [...new Set(variants.map(value => `${value.session}: ${value.result}`))].join("; ");
+    }).join(" | ")} |`),
+  ].join("\n");
+  const priority = (targets: readonly RestoreEvidence["target"][], sessions: readonly { session: RestoreEvidence["session"]; allowOther: boolean }[]) => {
+    const outcomes = new Set<string>();
+    for (const receipt of receipts) for (const target of targets) for (const launcher of launchers) for (const session of sessions) {
+      outcomes.add(result(receipt, { target, launcher, ...session, binding }, true));
+    }
+    return [...outcomes].join(" / ");
+  };
+  const allSessions = (["planned", "other", "none"] as const).flatMap(session => [false, true].map(allowOther => ({ session, allowOther })));
+  return [
+    "Cells show action -> next receipt status. Fresh-session eligibility is marked fresh; peer/operation-specific restrictions still apply. Exact terminal revalidation and settlement must succeed before persisting a proposed done receipt.",
+    "",
+    "| Priority condition | Decision |",
+    "|---|---|",
+    `| Target stopped or changed | ${priority(["stopped", "changed"], allSessions)} |`,
+    `| Running target, other session not allowed | ${priority(["running"], [{ session: "other", allowOther: false }])} |`,
+    "| Absent receipt | unstarted; initial launch is handled by the runtime outside this receipt table |",
+    "",
+    table("Running target, no attached session (either allowOther value):", [{ session: "none", allowOther: false }, { session: "none", allowOther: true }]),
+    "",
+    table("Running target, planned session or explicitly allowed other session (different decisions are labeled):", [{ session: "planned", allowOther: false }, { session: "planned", allowOther: true }, { session: "other", allowOther: true }]),
+  ].join("\n");
+}
+export const RESTORE_TRANSITION_TABLE = renderRestoreTransitionTable();

package/src/cli/upgrade-runtime.ts

@@ -8,16 +8,23 @@ import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS, readControl } from
 import { awaitStopped, inspectProject } from "../hub/lifecycle.ts";
 import type { Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.ts";
-import { packageDigest, registryRelease, runCommand, stageRelease, verifyPackage, type RunCommand } from "./recovery-package.ts";
+import { packageDigest, preserveRuntimeDependencies, registryRelease, runCommand, stageRelease, verifyPackage, type RunCommand } from "./recovery-package.ts";
 import { inspectTerminals, closeTerminal, createTerminal, launcherOf, recordPath, waitForIdle, shellQuote, type SessionRef, type TerminalBinding, type TerminalRecoveryOptions } from "./terminal-recovery.ts";
 import { FinalRefusal, planFingerprint, registeredProjects, targetReadsWaivers, type Inspection, type PlannedProject, type ProjectProgress, type RecoveryDriver, type RecoveryOperation, type RecoveryPeer, type UpgradePlan } from "./upgrade.ts";
 import { readEvents } from "../hub/events.ts";
 import { refreshManager } from "../hub/manager.ts";
 import { abandonRestartSnapshot, readRestartSnapshot, waiveRecoveryPeers } from "../hub/restart.ts";
 import { recoveryLock } from "../hub/recovery-store.ts";
+import { decodeRestoreReceipt, restoreTransition, type RestoreReceipt, type RestoreEvidence, type RestoreTransition } from "./upgrade-restore-state.ts";
 
 /** An unmanaged Claude's plugin retries with a backoff of at most 30 s; three of those bound the reconnect wait (#206). */
-const RECONNECT_WAIT_MS = 90_000;
+const UNMANAGED_RECONNECT_WAIT_MS = 90_000;
+/** Managed TUI startup can include resume and MCP handshakes; match createTerminal's ten-minute readiness ceiling. */
+const RECONNECT_WAIT_MS = 600_000;
+class AttachmentLauncherGone extends Error {
+  constructor(readonly transition: RestoreTransition) { super("chosen attachment launcher exited"); }
+}
+const attachedBinding = (binding: TerminalBinding, sessionId: string): TerminalBinding => ({ ...binding, sessionId });
 
 export const PACKAGE_ROOT = resolve(import.meta.dir, "../..");
 const orcaExecutable = () => process.env.ORCA_CLI_COMMAND || (process.env.ORCA_DEV_REPO_ROOT ? "orca-dev" : process.platform === "linux" && !process.env.ORCA_TERMINAL_HANDLE ? "orca-ide" : "orca");
@@ -151,7 +158,7 @@ export async function endPlannedPeer(planned: PlannedProject, peer: RecoveryPeer
   }
 }
 
-export async function inspectRecovery(project: Project): Promise<Inspection> {
+export async function inspectRecovery(project: Project, targetFeatures?: readonly string[]): Promise<Inspection> {
   // #226: the claim is judged by the registry as it is now, never by the plan's frozen copy, which holds the source's
   // pid from planning time (after a reboot another process may hold it). A registry that cannot be read throws: the
   // caller reads that as not inspected, never as stopped.
@@ -189,9 +196,9 @@ export async function inspectRecovery(project: Project): Promise<Inspection> {
   }
   if (!status || !control) return { state: "unavailable", peers: [], blockers: ["authenticated source status unavailable"] };
   let response: any;
-  try { response = await rpc(project, { t: "recovery", op: "inspect", expectedInstanceId: status.instanceId }, sourceProtocol ?? PROTOCOL); }
+  try { response = await rpc(project, { t: "recovery", op: "inspect", expectedInstanceId: status.instanceId, ...(targetFeatures === undefined ? {} : { targetFeatures }) }, sourceProtocol ?? PROTOCOL); }
   catch (error) {
-    if (isDatabaseBusy(error)) throw error;
+    if (isDatabaseBusy(error) || targetFeatures !== undefined) throw error;
     // A stop can complete between authenticated status and the second read. Never infer stopped
     // from a connection failure: the coordinator will inspect the ownership manifest again.
     return { state: "unavailable", instanceId: status.instanceId, version: status.version, protocol: status.protocol,
@@ -307,7 +314,7 @@ export function preserveSource(plan: UpgradePlan, home = hubHome()): string {
   const base = join(home, "releases");
   const dest = join(base, `source-${plan.sourceDigest}`);
   if (existsSync(dest)) {
-    if (packageDigest(dest) !== plan.sourceDigest) throw new Error("preserved source package changed");
+    if (packageDigest(dest, { ownDependencies: true }) !== plan.sourceDigest) throw new Error("preserved source package changed");
     return dest;
   }
   mkdirSync(base, { recursive: true, mode: 0o700 });
@@ -317,15 +324,16 @@ export function preserveSource(plan: UpgradePlan, home = hubHome()): string {
     for (const name of ["src", "plugins", "templates", ".claude-plugin", "package.json", "README.md", "LICENSE", "CHANGELOG.md"]) {
       cpSync(join(plan.sourceRoot, name), join(temporary, name), { recursive: true, dereference: false });
     }
-    if (packageDigest(temporary) !== plan.sourceDigest) throw new Error("source changed while being preserved");
+    preserveRuntimeDependencies(plan.sourceRoot, temporary);
+    if (packageDigest(temporary, { ownDependencies: true }) !== plan.sourceDigest) throw new Error("source changed while being preserved");
     renameSync(temporary, dest);
   } finally { rmSync(temporary, { recursive: true, force: true }); }
   return dest;
 }
 
-export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?: string): RecoveryDriver {
-  const now = () => Date.now();
-  const sleep = (ms: number) => Bun.sleep(ms);
+export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?: string, clock?: Pick<RecoveryDriver, "now" | "sleep">): RecoveryDriver {
+  const now = clock?.now ?? (() => Date.now());
+  const sleep = clock?.sleep ?? ((ms: number) => Bun.sleep(ms));
   const env = (op: RecoveryOperation, project?: Project): NodeJS.ProcessEnv => {
     const value = { ...process.env };
     // Do not carry one project's gateway, auth overrides or unattended mode into another.
@@ -351,10 +359,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     if (result.code !== 0) throw new Error(`target command ${args[0]} failed; inspect recovery state before retrying`);
     return result;
   };
-  const control = (project: Project, op: string, id: string, instance: string) => {
+  const control = (project: Project, op: string, id: string, instance: string, targetFeatures?: readonly string[]) => {
     const sourceProtocol = readControl(project.stateDir)?.protocol;
     const protocol = sourceProtocol !== undefined && RECOVERY_SOURCE_PROTOCOLS.includes(sourceProtocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) ? sourceProtocol : PROTOCOL;
-    return rpc(project, { t: "recovery", op, operationId: id, expectedInstanceId: instance }, protocol).then(() => {});
+    return rpc(project, { t: "recovery", op, operationId: id, expectedInstanceId: instance, ...(targetFeatures === undefined ? {} : { targetFeatures }) }, protocol).then(() => {});
   };
   const revalidateTerminal = async (planned: PlannedProject, progress: ProjectProgress, saved: TerminalBinding, exact: boolean): Promise<TerminalBinding> => {
     const options = { ...terminalOptions(run), stateDir: planned.project.stateDir, instanceId: progress.instanceId };
@@ -386,7 +394,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
    * expected instance can report "gone"; an unreadable target or launcher is unknown and blocks, never gone.
    */
   const peerEvidence = async (planned: PlannedProject, progress: ProjectProgress, peer: TerminalBinding["peer"]):
-      Promise<{ state: "live"; session?: string; handle?: string; attached?: true } | { state: "gone" } | { state: "unknown"; why: string; step?: string }> => {
+      Promise<{ state: "live"; session?: string; handle?: string; attached?: true; terminal?: Pick<TerminalBinding, "handle" | "incarnationId" | "worktreeId"> } | { state: "gone"; terminal?: Pick<TerminalBinding, "handle" | "incarnationId" | "worktreeId"> } | { state: "unknown"; why: string; step?: string; idless?: true }> => {
     const target = await inspectRecovery(planned.project);
     if (target.state !== "running" || target.instanceId !== progress.instanceId) {
       // Only a hub that may still answer is waited for; a stopped, missing or other one is settled by the runner's list.
@@ -396,22 +404,31 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     const attached = target.peers.find((p) => p.id === peer && p.state !== "offline");
     const session = peer === "codex" ? attached?.threadId : attached?.sessionId;
     if (session) return { state: "live", session };
+    let endedTerminal: Pick<TerminalBinding, "handle" | "incarnationId" | "worktreeId"> | undefined;
     // #225: the launch records of every instance this operation started for the project, the current one first: a
     // launcher a dead instance recorded may still run (read before the check below, so a block names its terminal).
     for (const instanceId of [progress.instanceId, ...(progress.restarts ?? []).map((r) => r.instanceId)]) {
       if (!instanceId) continue;
       const launch = await launcherOf(peer, planned.project.root, { ...terminalOptions(run), stateDir: planned.project.stateDir, instanceId });
-      if (launch?.state === "live") return { state: "live", handle: launch.record!.handle, ...(attached ? { attached: true as const } : {}) };
+      if (launch?.state === "live") {
+        const record = launch.record!;
+        return { state: "live", handle: record.handle, ...(attached ? { attached: true as const } : {}),
+          ...(instanceId === progress.instanceId ? { terminal: { handle: record.handle, incarnationId: record.incarnationId, worktreeId: record.worktreeId } } : {}) };
+      }
       if (launch?.state === "unknown") {
         return launch.record ? { state: "unknown", why: `its launcher in terminal ${launch.record.handle} cannot be read`, step: `wait until it attaches, or end it and close terminal ${launch.record.handle}` }
           : launch.invalidRow ? { state: "unknown", why: "a launch record that may be its launcher's cannot be evaluated", step: `inspect ${recordPath(planned.project.stateDir)} and fix that row, or end that launcher and remove its row` }
           : { state: "unknown", why: "the launcher records cannot be read", step: `inspect ${recordPath(planned.project.stateDir)} and move it aside (sessions it recorded then count as unmanaged)` };
       }
+      if (instanceId === progress.instanceId && launch?.state === "gone" && launch.record) {
+        const record = launch.record;
+        endedTerminal = { handle: record.handle, incarnationId: record.incarnationId, worktreeId: record.worktreeId };
+      }
     }
     // #225: attached with no provable session id (a Claude of a dead instance whose plugin reconnected, or one that has
     // not reported its id yet) is a session of unknown identity, never "nothing attached".
-    if (attached) return { state: "unknown", why: `a ${peer} session is attached to the target without a session id`, step: `wait until it reports one, or end that ${peer} session` };
-    return { state: "gone" };
+    if (attached) return { state: "unknown", idless: true, why: `a ${peer} session is attached to the target without a session id`, step: `wait until it reports one, or end that ${peer} session` };
+    return { state: "gone", ...(endedTerminal ? { terminal: endedTerminal } : {}) };
   };
   /**
    * #225: the terminal of a done restoration of a target instance that died is closed under the close receipt rules
@@ -434,34 +451,104 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     if (result.manualRequired) throw new Error(`${peer}: closing terminal ${retired.handle} of the stopped target's session was not verified; manual-required`);
     progress.terminals[key] = true; save();
   };
-  const attachedId = async (planned: PlannedProject, peer: string, op: RecoveryOperation): Promise<string> => {
-    for (const deadline = now() + RECONNECT_WAIT_MS; ;) {
-      const current = (await inspectRecovery(planned.project)).peers.find((p) => p.id === peer && p.state !== "offline");
-      const id = peer === "codex" ? current?.threadId : current?.sessionId;
-      if (id) return id;
-      if (now() >= deadline) throw new Error(`${peer}: the new session reported no id within ${RECONNECT_WAIT_MS / 1000} s; wait until it attaches first`);
-      await sleep(1000);
+  /** #414: an idle terminal is not an authenticated peer. Keep its receipt while waiting, including on resume. */
+  const awaitAttachment = async (planned: PlannedProject, progress: ProjectProgress, op: RecoveryOperation, waiting: Extract<RestoreReceipt, { state: "waiting" }>, save: () => void, expectedSession: string | null = waiting.binding.sessionId): Promise<string> => {
+    const binding = waiting.binding;
+    const matchesTerminal = (terminal: Pick<TerminalBinding, "handle" | "incarnationId" | "worktreeId">) => terminal.handle === binding.handle && terminal.incarnationId === binding.incarnationId && terminal.worktreeId === binding.worktreeId;
+    const deadline = now() + RECONNECT_WAIT_MS;
+    let live: Inspection;
+    for (;;) {
+      live = await inspectRecovery(planned.project);
+      if (live.state !== "running") throw new Error(`${binding.peer}: target hub reads as ${live.state} while awaiting attachment; saved terminal retained`);
+      if (live.instanceId !== progress.instanceId || live.version !== op.plan.version || live.recovery?.operationId !== op.id) throw new Error(`${binding.peer}: target identity changed while awaiting attachment`);
+      const peer = live.peers.find((p) => p.id === binding.peer && p.state !== "offline");
+      const session = binding.peer === "codex" ? peer?.threadId : peer?.sessionId;
+      const changed = !!session && expectedSession !== null && session !== expectedSession;
+      // #64: only the original zero-turn Claude may change identity without an operator choice. Re-read persistence
+      // at attachment, not at the plan or wait start; an already accepted replacement is bound to its own id.
+      const zeroTurn = changed && binding.peer === "claude" && (planned.terminals as TerminalBinding[]).some((p) => p.peer === "claude" && p.sessionId === binding.sessionId) && !claudeTranscriptExists(binding);
+      if (changed && !zeroTurn) throw new Error(`${binding.peer}: a different conversation attached while awaiting ${binding.sessionId}`);
+      if (now() > deadline) break;
+      const launcher = await launcherOf(binding.peer, planned.project.root, { ...terminalOptions(run), stateDir: planned.project.stateDir, instanceId: progress.instanceId });
+      const sameTerminal = launcher?.record && matchesTerminal(launcher.record);
+      let launchState: RestoreEvidence["launcher"] = !launcher ? "no-record-yet" : launcher.state === "unknown" || !launcher.record ? "unknown"
+        : sameTerminal ? launcher.state : launcher.state === "gone" ? "no-record-yet" : "replaced";
+      let olderHandle: string | undefined;
+      if ((launchState === "gone" || launchState === "no-record-yet") && !session) {
+        // An exact exit is not proof while an older launcher or an id-less session may still run.
+        const evidence = await peerEvidence(planned, progress, binding.peer);
+        if (evidence.state === "gone" && evidence.terminal && matchesTerminal(evidence.terminal)) launchState = "gone";
+        else if (evidence.state === "unknown") {
+          if (!(launchState === "no-record-yet" && evidence.idless)) launchState = "unknown";
+        } else if (evidence.state === "live" && !evidence.session) {
+          if (evidence.terminal) launchState = matchesTerminal(evidence.terminal) ? "live" : "replaced";
+          else { launchState = "older-instance"; olderHandle = evidence.handle; }
+        } else if (evidence.state === "live" && evidence.session) {
+          if (now() >= deadline) break;
+          await sleep(Math.min(1000, deadline - now()));
+          continue;
+        }
+      }
+      const decision = restoreTransition(waiting, { target: "running", launcher: launchState,
+        session: session && peer && ["idle", "busy", "paused"].includes(peer.state) ? changed ? "other" : "planned" : "none", allowOther: zeroTurn || expectedSession === null, binding });
+      if (decision.action === "settle" && session) {
+        if (zeroTurn) waiveRecoveryPeers(planned.project.stateDir, op.id, { claude: "zero-turn" });
+        return session;
+      }
+      if (decision.action === "fail" || decision.action === "create") throw new AttachmentLauncherGone(decision);
+      if (decision.action === "block") {
+        if (launchState === "replaced") throw new Error(`${binding.peer}: saved terminal identity changed while awaiting attachment`);
+        if (launchState === "older-instance") throw new Error(`${binding.peer}: an older target's launcher in terminal ${olderHandle ?? "unknown"} may still run; saved terminal retained; no terminal was created`);
+        throw new Error(`${binding.peer}: the chosen restoration launcher's identity cannot be verified (${launchState}); saved terminal retained; no terminal was created`);
+      }
+      if (now() >= deadline) break;
+      await sleep(Math.min(1000, deadline - now()));
     }
+    const terminal: NonNullable<ProjectProgress["attachmentTimeouts"]>[string]["terminal"] = { handle: binding.handle, incarnationId: binding.incarnationId, state: "unknown" };
+    try {
+      const result = await run([orcaExecutable(), "terminal", "show", "--terminal", binding.handle, "--json"], { timeoutMs: 3000 });
+      const value = JSON.parse(result.stdout), shown = value.result?.terminal;
+      if (result.code === 0 && value.ok === true && shown?.handle === binding.handle && shown.incarnationId === binding.incarnationId) {
+        if (["idle", "busy", "exited"].includes(shown.state)) terminal.state = shown.state;
+        if (typeof shown.connected === "boolean") terminal.connected = shown.connected;
+        if (typeof shown.orphaned === "boolean") terminal.orphaned = shown.orphaned;
+      }
+    } catch { /* unavailable metadata stays unknown; raw output/errors never enter the receipt */ }
+    const peer = live.peers.find((p) => p.id === binding.peer);
+    const session = peer?.state === "offline" ? undefined : binding.peer === "codex" ? peer?.threadId : peer?.sessionId;
+    (progress.attachmentTimeouts ??= {})[binding.peer] = { at: now(), terminal,
+      hub: { state: live.state, ...(live.instanceId ? { instanceId: live.instanceId } : {}), ...(peer ? { peerState: peer.state } : {}), ...(session ? { sessionId: session } : {}) },
+      lastHubConnectAttempt: "unknown" };
+    save();
+    throw new Error(`${binding.peer}: attachment not verified within ${RECONNECT_WAIT_MS / 1000} s; terminal ${binding.handle} retained; resume after it attaches (native-start diagnostic recorded; last hub connect attempt unknown)`);
   };
   return {
     now, sleep, inspect: inspectRecovery,
     stage: async (op) => {
-      if (packageDigest(op.sourceRoot) !== op.plan.sourceDigest) throw new FinalRefusal("preserved source changed");
-      const target = op.plan.kind === "restart" ? { root: op.sourceRoot, digest: verifyPackage(op.sourceRoot, op.plan.version) }
+      if (packageDigest(op.sourceRoot, { ownDependencies: true }) !== op.plan.sourceDigest) throw new FinalRefusal("preserved source changed");
+      const target = op.plan.kind === "restart" ? { root: op.sourceRoot, digest: verifyPackage(op.sourceRoot, op.plan.version, { ownDependencies: true }) }
         : await stageRelease(op.plan.version, op.plan.integrity!, run);
       const identityPath = join(target.root, "src/cli/identity.ts");
       if (liveTestPeer && (!existsSync(identityPath) || !readFileSync(identityPath, "utf8").includes("export const LIVE_TEST_SUPPORTED = true;"))) {
         throw new FinalRefusal("target does not support live-test delegation; choose a supporting target before retrying; runtimes unchanged");
       }
-      // #215: the protocol and waiver checks are properties of these bytes. Once they passed (the runner recorded the
-      // digest), a resume does not check again, so a transient probe failure cannot refuse an operation for good;
-      // changed bytes are the runner's final "staged target changed".
-      if (op.targetDigest && op.targetDigest === target.digest && op.targetRoot === target.root) return target;
-      const protocol = await run([process.execPath, "-e", `import { PROTOCOL } from ${JSON.stringify(join(target.root, "src/hub/control-client.ts"))}; console.log(PROTOCOL)`]);
-      const read = protocol.code === 0 ? Number.parseInt(protocol.stdout.trim(), 10) : NaN;
-      // A probe that did not answer (killed, a null exit code maps to 1) says nothing about the target: retry.
-      if (!Number.isInteger(read)) throw new Error(`the staged target's control protocol could not be read (probe exit ${protocol.code}); staged package retained, runtimes unchanged; resume again once it can run`);
-      if (read !== PROTOCOL) throw new FinalRefusal("target protocol requires a newer coordinator; staged package retained, runtimes unchanged");
+      // Reuse capability proof only after verifying the cached root and digest still identify these exact bytes.
+      const cached = op.targetDigest === target.digest && op.targetRoot === target.root;
+      if (cached && op.targetFeatures !== undefined) return { ...target, targetFeatures: [...op.targetFeatures] };
+      // A legacy cached operation already past commit needs no capability proof to finish restoration (#215).
+      // A prepared commitSent receipt remains uncertain and must still obtain proof before a possible commit.
+      if (cached && op.projects?.every(project => ["stopped", "started", "peers-restored", "verified"].includes(project.phase))) return target;
+      // Legacy uncommitted receipts acquire verified feature evidence before source compatibility checks.
+      const probe = await run([process.execPath, "-e", `import * as target from ${JSON.stringify(join(target.root, "src/hub/control-client.ts"))}; console.log(JSON.stringify({protocol: target.PROTOCOL, features: target.DAEMON_FEATURES ?? []}))`]);
+      let metadata: { protocol?: unknown; features?: unknown } | undefined;
+      try { if (probe.code === 0) metadata = JSON.parse(probe.stdout); } catch { /* Unknown metadata refuses before effects. */ }
+      if (!metadata || typeof metadata !== "object" || !Number.isInteger(metadata.protocol)) throw new Error(`the staged target's control protocol could not be read (probe exit ${probe.code}); staged package retained, runtimes unchanged; resume again once it can run`);
+      if (!Array.isArray(metadata.features) || !metadata.features.every((feature: unknown) => typeof feature === "string" && feature.length > 0)) throw new Error("the staged target features could not be read; staged package retained, runtimes unchanged");
+      const targetFeatures: readonly string[] = [...metadata.features];
+      if (metadata.protocol !== PROTOCOL) throw new FinalRefusal("target protocol requires a newer coordinator; staged package retained, runtimes unchanged");
+      const verified = { ...target, targetFeatures };
+      // Existing peer/waiver compatibility checks remain properties of the already verified bytes.
+      if (op.targetDigest && op.targetDigest === target.digest && op.targetRoot === target.root) return verified;
       if (op.plan.projects.some(p => p.source.peers.some(peer => peer.id === "qwen" && peer.state !== "offline"))) {
         const catalog = join(target.root, "src/hub/peer-catalog.ts");
         const peers = existsSync(catalog) ? /export const OPTIONAL_PEERS\s*=\s*\[([^\]]*)\]/.exec(readFileSync(catalog, "utf8"))?.[1] : undefined;
@@ -476,11 +563,11 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       if (op.plan.projects.some((p) => p.reconnectOnly?.length || p.freshStart?.length) && !targetReadsWaivers({ targetRoot: target.root })) {
         throw new FinalRefusal(`target ${op.plan.version} predates recovery waivers, so its hub could never accept a reconnect-only Claude or a fresh Codex start; staged package retained, runtimes unchanged; choose a newer target once this operation is cancelled or ended`);
       }
-      return target;
+      return verified;
     },
-    prepare: (p, id, instance) => control(p, "prepare", id, instance),
+    prepare: (p, id, instance, features) => control(p, "prepare", id, instance, features),
     abort: (p, id, instance) => control(p, "abort", id, instance),
-    commit: (p, id, instance) => control(p, "commit", id, instance),
+    commit: (p, id, instance, features) => control(p, "commit", id, instance, features),
     release: (p, id, instance) => control(p, "release", id, instance),
     closeTerminals: async (planned, progress, op, save) => {
       for (const binding of planned.terminals as TerminalBinding[]) {
@@ -595,19 +682,35 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           : evidence.session
             ? `${original.peer}: session ${evidence.session} is attached instead of ${original.sessionId}; no terminal was created; end that ${original.peer} session and close its terminal first`
             : `${original.peer}: its launcher in terminal ${evidence.handle} is running but no ${original.peer} session ${evidence.attached ? "with an id " : ""}attached yet; no terminal was created; wait until it attaches, or end it and close terminal ${evidence.handle} first`);
-        const receipt = progress.terminals[key];
-        if (receipt && receipt !== "pending" && receipt !== "failed") {
-          progress.terminals[key] = await revalidateTerminal(planned, progress, receipt as TerminalBinding, true); save();
-          continue;
+        const decide = (receipt: RestoreReceipt, evidence: Awaited<ReturnType<typeof peerEvidence>>) => restoreTransition(receipt, {
+          target: "running", launcher: evidence.state === "unknown" ? "unknown" : evidence.state === "gone" ? "gone" : evidence.terminal ? "live" : "older-instance",
+          session: evidence.state === "live" && evidence.session ? evidence.session === original.sessionId ? "planned" : "other" : "none",
+          allowOther: fresh() || (original.peer === "claude" && !claudeTranscriptExists(original)),
+          binding: evidence.state === "live" && evidence.terminal ? { ...original, ...evidence.terminal } : original,
+        });
+        const receipt = decodeRestoreReceipt(progress.terminals[key]);
+        function awaitBound(waiting: Extract<RestoreReceipt, { state: "waiting" }> & { origin: "pending" }, expected: string | null): Promise<string>;
+        function awaitBound(waiting: Extract<RestoreReceipt, { state: "waiting" }>, expected: string | null): Promise<string | undefined>;
+        async function awaitBound(waiting: Extract<RestoreReceipt, { state: "waiting" }>, expected: string | null): Promise<string | undefined> {
+          try { return await awaitAttachment(planned, progress, op, waiting, save, expected); }
+          catch (error) {
+            if (!(error instanceof AttachmentLauncherGone)) throw error;
+            progress.terminals[key] = error.transition.next; save();
+            // The table decides whether this failed wait blocks or is eligible for a new launch.
+            if (error.transition.action === "create") return undefined;
+            throw notRestored(`its launcher no longer runs and no ${original.peer} session attached`);
+          }
         }
         // #215: the pending row of the receipt table, used wherever a pending launch meets an attached session.
-        const settle = async (attached: string) => {
+        const settle = async (attached: string, recovered?: TerminalBinding) => {
           // #21: a Claude session that never got a first turn has no transcript, so `claude --resume S` can never
           // succeed and accepting its fresh attach loses nothing. Otherwise only the planned id, or a new session
           // the operator or the plan accepted, counts as restored.
           if (attached !== original.sessionId && !fresh() && !(original.peer === "claude" && !claudeTranscriptExists(original))) {
             throw new Error(`${original.peer}: terminal creation outcome is uncertain: session ${attached} is attached instead of ${original.sessionId}; end that ${original.peer} session and close its terminal first`);
           }
+          // Validate the proposed transition before committing continuity/waiver effects or a done receipt.
+          const verified = await revalidateTerminal(planned, progress, attachedBinding(recovered ?? original, attached), !!recovered);
           // The planned session came back after all: a fresh session chosen for it lost nothing. Compared with the plan,
           // never with a session accepted after a restart (#225), whose choice must stay on record.
           if (attached === plannedBinding.sessionId && progress.fresh?.[original.peer]) {
@@ -618,31 +721,58 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           // a launch writes the waiver first, but this must not rely on that.
           // The planned session needs no waiver: the target's snapshot already expects it.
           if (attached !== original.sessionId && attached !== plannedBinding.sessionId) waiveRecoveryPeers(planned.project.stateDir, op.id, { [original.peer]: waiver() });
-          progress.terminals[key] = await revalidateTerminal(planned, progress, { ...original, sessionId: attached }, false); save();
+          progress.terminals[key] = { state: "done", binding: verified } satisfies RestoreReceipt; save();
         };
-        // #215: a pending or failed receipt is settled by what is live now (the receipt table in the recovery spec).
-        if (receipt === "pending" || receipt === "failed") {
+        if (receipt?.state === "done") {
+          // A completed restoration is never a waiting launch. A closed terminal blocks exact revalidation;
+          // it cannot erase continuity or create a fresh-session choice (PROBE-B).
+          const observed = await peerEvidence(planned, progress, original.peer);
+          const decision = restoreTransition(receipt, { target: "running", launcher: "no-record-yet", session: observed.state === "live" && observed.session === receipt.binding.sessionId ? "planned" : observed.state === "live" && observed.session ? "other" : "none", allowOther: false });
+          if (decision.action === "block") {
+            const condition = observed.state === "unknown" ? `cannot be verified (${observed.why})`
+              : observed.state === "live" && observed.session ? `session ${observed.session} is attached instead of ${receipt.binding.sessionId}`
+              : observed.state === "live" ? `is not attached; its launcher in terminal ${observed.handle ?? "unknown"} may still run` : "is not attached";
+            throw new Error(`${original.peer}: completed restoration ${condition}; saved done receipt retained; resume its recorded conversation`);
+          }
+          progress.terminals[key] = { state: "done", binding: await revalidateTerminal(planned, progress, receipt.binding, true) } satisfies RestoreReceipt; save();
+          continue;
+        }
+        if (receipt?.state === "waiting") {
+          const binding = receipt.binding;
+          const sessionId = await awaitBound(receipt, fresh() && binding.sessionId === original.sessionId ? null : binding.sessionId);
+          if (sessionId !== undefined) { await settle(sessionId, binding); continue; }
+        }
+        if (receipt?.state === "pending" || receipt?.state === "failed") {
           const evidence = await peerEvidence(planned, progress, original.peer);
-          if (evidence.state === "live" && evidence.session) { await settle(evidence.session); continue; }
-          if (evidence.state !== "gone") throw blocked(evidence);
-          if (receipt === "pending") {
-            progress.terminals[key] = "failed"; save();
+          const decision = decide(receipt, evidence);
+          if (decision.action === "settle" && evidence.state === "live" && evidence.session) { await settle(evidence.session); continue; }
+          if (decision.action === "poll" && decision.next.state === "waiting") {
+            const waiting = decision.next;
+            progress.terminals[key] = waiting; save();
+            const session = await awaitBound(waiting, fresh() ? null : original.sessionId);
+            if (session !== undefined) { await settle(session, waiting.binding); continue; }
+          } else if (decision.action === "fail") {
+            progress.terminals[key] = decision.next; save();
             throw notRestored(`its launcher no longer runs and no ${original.peer} session attached`);
+          } else if (decision.action === "block") {
+            if (evidence.state === "live" && evidence.session) {
+              throw new Error(`${original.peer}: terminal creation outcome is uncertain: session ${evidence.session} is attached instead of ${original.sessionId}; end that ${original.peer} session and close its terminal first`);
+            }
+            if (evidence.state !== "gone") throw blocked(evidence);
+            throw new Error(`${original.peer}: restoration evidence is not actionable`);
           }
-          // failed, nothing live: launched again below; the receipt stays `failed` until `pending` replaces it, so a
-          // refusal on the way keeps the failed-restoration choices
         }
         // Never create beside a live launch, nor on evidence that could not be read: read now, not at restore start.
         // The planned session already attached is the restoration (the table's row for it), not a reason to block.
         const evidence = await peerEvidence(planned, progress, original.peer);
         if (evidence.state === "live" && evidence.session === original.sessionId) {
-          progress.terminals[key] = await revalidateTerminal(planned, progress, original, false); save();
+          progress.terminals[key] = { state: "done", binding: await revalidateTerminal(planned, progress, original, false) } satisfies RestoreReceipt; save();
           continue;
         }
         if (evidence.state !== "gone") throw blocked(evidence);
         if (transcript() === "unknown") throw new Error(`${unresumable(original)}; no terminal was created; make that store readable first`);
         if (transcript() === "missing" && !fresh()) {
-          progress.terminals[key] = "failed"; save();
+          progress.terminals[key] = { state: "failed" } satisfies RestoreReceipt; save();
           throw notRestored(unresumable(original).slice("codex: ".length));
         }
         if (fresh()) {
@@ -656,7 +786,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         const launch = { ...original.launch, packageEntrypoint: entrypoint, argv,
           command: ["env", ...Object.entries(assignments).map(([k, v]) => `${k}=${v}`), ...argv].map(shellQuote).join(" ") };
         const binding = { ...original, launch, launchMetadata: launch };
-        progress.terminals[key] = "pending"; save();
+        progress.terminals[key] = { state: "pending" } satisfies RestoreReceipt; save();
         const restored = await createTerminal(binding, { ...terminalOptions(run), stateDir: planned.project.stateDir, instanceId: progress.instanceId }, undefined, fresh());
         const exited = restored.blockers.find((b) => b.code === "launcher-exited");
         if (exited) {
@@ -664,23 +794,34 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           // nothing live makes it failed; an attached session is settled as the pending row settles it; anything else
           // stays pending.
           const after = await peerEvidence(planned, progress, original.peer);
-          if (after.state === "live" && after.session) { await settle(after.session); continue; }
+          const decision = decide({ state: "pending" }, after);
+          if (decision.action === "settle" && after.state === "live" && after.session) { await settle(after.session); continue; }
+          if (decision.action === "poll" && decision.next.state === "waiting") {
+            progress.terminals[key] = decision.next; save();
+            const session = await awaitBound(decision.next, fresh() ? null : original.sessionId);
+            if (session !== undefined) { await settle(session, decision.next.binding); continue; }
+          }
+          if (decision.action === "fail") {
+            progress.terminals[key] = decision.next; save();
+            throw notRestored(exited.message);
+          }
           if (after.state !== "gone") throw blocked(after);
-          progress.terminals[key] = "failed"; save();
-          throw notRestored(exited.message);
         }
         if (restored.manualRequired || !restored.newBinding) {
           const handle = restored.binding?.handle ?? restored.blockers[0]?.handle;
           throw new Error(`${original.peer}: original session restoration needs manual verification${restored.blockers[0] ? ` (${restored.blockers[0].message})` : ""}; wait until it attaches, or end that launch and close its terminal${handle ? ` ${handle}` : ""} first`);
         }
         // The daemon's id is authoritative: a fresh session is recorded under the id it reports once attached.
-        progress.terminals[key] = fresh() ? { ...restored.newBinding, sessionId: await attachedId(planned, original.peer, op) } : restored.newBinding; save();
+        const awaiting = { state: "waiting", origin: "pending", binding: restored.newBinding } satisfies RestoreReceipt;
+        progress.terminals[key] = awaiting; save();
+        const sessionId = await awaitBound(awaiting, fresh() ? null : restored.newBinding.sessionId);
+        await settle(sessionId, awaiting.binding);
       }
       if (group === "claude") for (const id of planned.reconnectOnly ?? []) {
         // #206: nothing is launched for an unmanaged session; its plugin reconnects by itself, within a bound.
-        const deadline = now() + RECONNECT_WAIT_MS;
+        const deadline = now() + UNMANAGED_RECONNECT_WAIT_MS;
         while (!(await inspectRecovery(planned.project)).peers.some((p) => p.id === id && p.state !== "offline")) {
-          if (now() >= deadline) throw new Error(`${id}: the unmanaged session did not reconnect within ${RECONNECT_WAIT_MS / 1000} s; if that Claude session was closed, start Claude in the project again (its plugin reconnects) first`);
+          if (now() >= deadline) throw new Error(`${id}: the unmanaged session did not reconnect within ${UNMANAGED_RECONNECT_WAIT_MS / 1000} s; if that Claude session was closed, start Claude in the project again (its plugin reconnects) first`);
           await sleep(1000);
         }
       }
@@ -734,9 +875,9 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         if (old.id === "pi" && (peer.sessionId !== old.sessionId || (old.sessionFile && peer.sessionFile !== old.sessionFile))) throw new Error("Pi resumed a different conversation");
       }
       for (const original of planned.terminals as TerminalBinding[]) {
-        const saved = progress.terminals[`restored:${original.peer}`];
-        if (!saved || typeof saved === "string") throw new Error(`${original.peer}: restored terminal outcome is not recorded; manual-required`);
-        await revalidateTerminal(planned, progress, saved as TerminalBinding, true);
+        const saved = decodeRestoreReceipt(progress.terminals[`restored:${original.peer}`]);
+        if (saved?.state !== "done") throw new Error(`${original.peer}: restored terminal outcome is not recorded; manual-required`);
+        await revalidateTerminal(planned, progress, saved.binding, true);
       }
       const snapshot = await rpc(planned.project, { t: "ui_snapshot", after: 0 });
       if (snapshot.ok === false) throw new Error("dashboard snapshot readback failed");