@staix/agent-hub 0.12.30 → 0.12.32

package/src/cli/upgrade-runtime.ts

@@ -1,23 +1,34 @@
+import { checkedSessionPath, recordedFileState } from "./recovery-session-file.ts";
+import { resolveAcceptedBinding } from "./recovery-guidance.ts";
+import { definitionOf } from "../adapters/registry.ts";
 import { qwenSessionId } from "../hub/crash.ts";
 import { isDatabaseBusy, isDatabaseBusyReply, RecoveryDatabaseBusy } from "../hub/recovery-error.ts";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
-import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS, readControl } from "../hub/control-client.ts";
 import { awaitStopped, inspectProject } from "../hub/lifecycle.ts";
 import type { Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.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 { inspectSavedTerminal, inspectTerminals, closeTerminal, createTerminal, launcherOf, recordPath, waitForIdle, shellQuote, type SessionRef, type TerminalBinding, type TerminalRecoveryOptions } from "./terminal-recovery.ts";
+import { ReattachmentRequired, MissingRecordedSession, 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 { readRecoveryContinuity, retireRecoveryContinuity, writeRecoveryContinuity } from "../hub/recovery-continuity.ts";
 import { recoveryLock } from "../hub/recovery-store.ts";
+import { decodeRestoreReceipt, restoreTransition, type RestoreReceipt, type RestoreEvidence, type RestoreTransition } from "./upgrade-restore-state.ts";
+import { RecoveryPreservationError, RecoveryPresentationError, type RecoveryNativeCause } from "./upgrade-presentation-data.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");
@@ -27,11 +38,10 @@ const orcaExecutable = () => process.env.ORCA_CLI_COMMAND || (process.env.ORCA_D
  * dir, creating the project directory only with the first persisted turn; the slug replaces
  * every non-alphanumeric character of the project root with '-'.
  */
-function claudeTranscriptExists(binding: TerminalBinding): boolean {
-  const config = binding.launch.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
-  const slug = binding.projectRoot.replace(/[^a-zA-Z0-9]/g, "-");
-  return existsSync(join(config, "projects", slug, `${binding.sessionId}.jsonl`));
+function claudeTranscriptState(binding: TerminalBinding): "found" | "missing" | "unknown" {
+  return recordedFileState(checkedSessionPath(binding, "transcript"));
 }
+function claudeTranscriptExists(binding: TerminalBinding): boolean { return claudeTranscriptState(binding) === "found"; }
 
 /**
  * #215: `codex resume <id>` reads the thread's rollout from the store its launcher uses (the captured CODEX_HOME, else
@@ -39,7 +49,7 @@ function claudeTranscriptExists(binding: TerminalBinding): boolean {
  * ponytail: a `.jsonl` under sessions/ whose name carries the thread id is the evidence; ask Codex itself once it offers
  * a supported resumability query, or when its store layout changes.
  */
-const codexSessions = (binding: TerminalBinding) => join(binding.launch.env.CODEX_HOME ?? join(homedir(), ".codex"), "sessions");
+const codexSessions = (binding: TerminalBinding) => checkedSessionPath(binding, "rollout");
 function codexTranscript(binding: TerminalBinding): "found" | "missing" | "unknown" {
   try { return readdirSync(codexSessions(binding), { recursive: true }).some((name) => String(name).endsWith(".jsonl") && basename(String(name)).includes(binding.sessionId)) ? "found" : "missing"; }
   catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unknown"; } // no store has no rollout; an unreadable one says nothing
@@ -151,7 +161,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 +199,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,
@@ -239,6 +249,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     const reconnectOnly: string[] = [];
     for (const peer of source.peers) {
       if (peer.state === "offline") continue;
+      const adapter = definitionOf(peer.id);
       if (peer.id === "kimi" && peer.args?.mode === "tui") {
         blockers.push("kimi: its pull-only terminal has no automatic restore; end it in that terminal, then make a new recovery plan (its session is not resumed by the hub)");
         continue;
@@ -275,12 +286,13 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
         const session = peer.id === "codex" ? peer.threadId : peer.sessionId;
         if (!session) blockers.push(`${peer.id}: original conversation ID is unknown; manual-required; next action: reconnect the original native session and make a new recovery plan`);
         else sessions[peer.id] = session;
-      } else if (peer.id === "qwen" || peer.id === "jcode") {
-        if (!qwenSessionId(peer.sessionId)) blockers.push(`${peer.id}: saved ACP session identity unavailable; end the peer and make a new recovery plan`);
+      } else if (adapter?.session.restoreOnStart || peer.id === "jcode") {
+        const session = adapter?.session.crashIdentity ? adapter.session.crashIdentity(peer).sessionId : qwenSessionId(peer.sessionId);
+        if (!session) blockers.push(`${peer.id}: saved ACP session identity unavailable; end the peer and make a new recovery plan`);
       } else if (peer.id === "pi" && peer.args?.mode === "tui") {
         if (!peer.sessionId) blockers.push("pi: original session ID is unknown; manual-required; next action: reconnect the original Pi session and make a new recovery plan");
         else sessions.pi = { sessionId: peer.sessionId, ...(peer.sessionFile ? { sessionFile: peer.sessionFile } : {}), ...(peer.args.backend ? { backend: peer.args.backend } : {}), ...(peer.args.model ? { model: peer.args.model } : {}) };
-      } else if (peer.id !== "kimi" && peer.id !== "qwen" && peer.id !== "local" && peer.id !== "pi") blockers.push(`${peer.id}: no automatic recovery adapter`);
+      } else if (peer.id !== "kimi" && peer.id !== "local" && peer.id !== "pi") blockers.push(`${peer.id}: no automatic recovery adapter`);
     }
     const terminals = await inspectTerminals(project.root, sessions, {
       ...terminalOptions(run), stateDir: project.stateDir, instanceId: source.instanceId,
@@ -352,25 +364,28 @@ 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 nativeFailure = (planned: PlannedProject, peer: string, reason: RecoveryNativeCause["reason"], message: string,
+    details: Omit<RecoveryNativeCause, "kind" | "reason" | "projectId" | "peer"> = {}) =>
+    new RecoveryPresentationError(message, { kind: "native_recovery", reason, projectId: planned.project.id, peer, ...details });
   const revalidateTerminal = async (planned: PlannedProject, progress: ProjectProgress, saved: TerminalBinding, exact: boolean): Promise<TerminalBinding> => {
     const options = { ...terminalOptions(run), stateDir: planned.project.stateDir, instanceId: progress.instanceId };
-    const found = await inspectTerminals(planned.project.root, { [saved.peer]: saved.sessionId }, options);
+    const found = await inspectTerminals(planned.project.root, { [saved.peer]: { sessionId: saved.sessionId, sessionFile: saved.sessionFile, backend: saved.backend, model: saved.model } }, options);
     const current = found.byPeer[saved.peer];
     if (found.manualRequired || !current || (exact && (current.handle !== saved.handle || current.incarnationId !== saved.incarnationId || current.worktreeId !== saved.worktreeId || current.projectRoot !== saved.projectRoot))) {
-      throw new Error(`${saved.peer}: saved terminal identity changed or is not verified; manual-required`);
+      throw nativeFailure(planned, saved.peer, "terminal_unverified", `${saved.peer}: saved terminal identity changed or is not verified; manual-required`, { handle: saved.handle });
     }
     const idle = await waitForIdle(exact ? saved : current, 120_000, options);
-    if (!idle.satisfied) throw new Error(`${saved.peer}: terminal is not idle; manual-required`);
+    if (!idle.satisfied) throw nativeFailure(planned, saved.peer, "terminal_unverified", `${saved.peer}: terminal is not idle; manual-required`, { handle: saved.handle });
     const observed = await inspectRecovery(planned.project);
-    if (observed.instanceId !== progress.instanceId) throw new Error(`${saved.peer}: daemon instance changed during terminal revalidation`);
+    if (observed.instanceId !== progress.instanceId) throw nativeFailure(planned, saved.peer, "target_unavailable", `${saved.peer}: daemon instance changed during terminal revalidation`, { handle: saved.handle, targetState: observed.state });
     const peer = observed.peers.find((item) => item.id === saved.peer);
     const session = saved.peer === "codex" ? peer?.threadId : peer?.sessionId;
-    if (session !== saved.sessionId) throw new Error(`${saved.peer}: daemon session changed during terminal revalidation; manual-required`);
+    if (session !== saved.sessionId || saved.peer === "pi" && progress.reattachments?.pi && saved.sessionFile && peer?.sessionFile !== saved.sessionFile) throw nativeFailure(planned, saved.peer, "session_changed", `${saved.peer}: daemon session changed during terminal revalidation; manual-required`, { handle: saved.handle, expectedSession: saved.sessionId, ...(session === undefined ? {} : { observedSession: session }) });
     return current;
   };
   /** Whether Orca's inventory lists the terminal; a failed, not-ok, truncated or non-JSON answer shows nothing. */
@@ -387,7 +402,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.
@@ -397,22 +412,56 @@ 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 } : {}) };
+  };
+  /** Only independently confirmed terminal loss plus absent sessions and launchers can arm a repair. */
+  const detached = async (planned: PlannedProject, progress: ProjectProgress, op: RecoveryOperation,
+    binding: TerminalBinding, save?: () => void): Promise<void> => {
+    const evidence = await peerEvidence(planned, progress, binding.peer);
+    if (evidence.state !== "gone") return;
+    const terminal = await inspectSavedTerminal(binding, terminalOptions(run));
+    const decision = restoreTransition({ state: "done", binding }, {
+      target: "running", launcher: "gone", session: "none", allowOther: false,
+      terminal: terminal.state === "missing" || terminal.state === "orphaned" ? "gone" : terminal.state === "present" ? "present" : terminal.state === "changed" ? "changed" : "unknown",
+    });
+    if (decision.action !== "reattach") return;
+    const current = await inspectRecovery(planned.project);
+    if (current.state !== "running" || current.instanceId !== progress.instanceId || current.version !== op.plan.version || current.recovery?.operationId !== op.id ||
+      (await peerEvidence(planned, progress, binding.peer)).state !== "gone") return;
+    const existing = progress.reattachments?.[binding.peer];
+    const why = `${binding.peer}: detached after restore; saved terminal ${binding.handle} is ${terminal.state}; recorded session ${binding.sessionId}${binding.sessionFile ? ` (${binding.sessionFile})` : ""}`;
+    if (existing) throw new ReattachmentRequired(planned.project.id, binding.peer, `${why}; the one reattachment was already attempted; no second terminal will be created`);
+    if (!save) throw new Error(`${why}; a durable coordinator save is required before reattachment`);
+    (progress.reattachments ??= {})[binding.peer] = { state: "ready", at: now(), cause: "detached after restore", binding };
+    (progress.repairedSessions ??= {})[binding.peer] = true;
+    progress.terminals[`restored:${binding.peer}`] = decision.next;
+    progress.phase = "started";
+    save();
+    throw new ReattachmentRequired(planned.project.id, binding.peer, `${why}; resume or use the operation's person-only reattach command`);
   };
   /**
    * #225: the terminal of a done restoration of a target instance that died is closed under the close receipt rules
@@ -436,24 +485,66 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     progress.terminals[key] = true; save();
   };
   /** #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, binding: TerminalBinding, save: () => void, expectedSession: string | null = binding.sessionId): Promise<string> => {
-    const deadline = now() + RECONNECT_WAIT_MS;
+  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 saveTiming = () => {
+      try { save(); }
+      catch { console.warn("Recovery timing observation could not be saved; recovery continues"); }
+    };
+    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 startedAt = now(), deadline = startedAt + RECONNECT_WAIT_MS;
+    const waitStep = op.step;
+    if (waitStep) {
+      (op.waits ??= {})[waitStep] = { waitStartedAt: new Date(startedAt).toISOString(), deadlineAt: new Date(deadline).toISOString() };
+      saveTiming();
+    }
+    let waitFailed = false;
+    try {
     let live: Inspection;
     for (;;) {
       live = await inspectRecovery(planned.project);
-      if (live.state === "running" && (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);
+      if (live.state !== "running") throw nativeFailure(planned, binding.peer, "target_unavailable", `${binding.peer}: target hub reads as ${live.state} while awaiting attachment; saved terminal retained`, { handle: binding.handle, targetState: live.state });
+      if (live.instanceId !== progress.instanceId || live.version !== op.plan.version || live.recovery?.operationId !== op.id) throw nativeFailure(planned, binding.peer, "target_unavailable", `${binding.peer}: target identity changed while awaiting attachment`, { handle: binding.handle, targetState: live.state });
+      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}`);
+      const zeroTurn = changed && !progress.reattachments?.[binding.peer] && !progress.repairedSessions?.[binding.peer] && binding.peer === "claude" && (planned.terminals as TerminalBinding[]).some((p) => p.peer === "claude" && p.sessionId === binding.sessionId) && !claudeTranscriptExists(binding);
+      if (changed && !zeroTurn) throw nativeFailure(planned, binding.peer, "session_changed", `${binding.peer}: a different conversation attached while awaiting ${binding.sessionId}`, { handle: binding.handle, expectedSession: expectedSession!, observedSession: session! });
       if (now() > deadline) break;
-      if (live.state === "running" && peer && ["idle", "busy", "paused"].includes(peer.state) && session) {
+      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 nativeFailure(planned, binding.peer, "launcher_unverified", `${binding.peer}: saved terminal identity changed while awaiting attachment`, { handle: binding.handle, launcherState: launchState });
+        if (launchState === "older-instance") throw nativeFailure(planned, binding.peer, "launcher_unverified", `${binding.peer}: an older target's launcher in terminal ${olderHandle ?? "unknown"} may still run; saved terminal retained; no terminal was created`, { ...(olderHandle ? { handle: olderHandle } : {}), launcherState: launchState });
+        throw nativeFailure(planned, binding.peer, "launcher_unverified", `${binding.peer}: the chosen restoration launcher's identity cannot be verified (${launchState}); saved terminal retained; no terminal was created`, { handle: binding.handle, launcherState: launchState });
+      }
       if (now() >= deadline) break;
       await sleep(Math.min(1000, deadline - now()));
     }
@@ -468,15 +559,28 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       }
     } catch { /* unavailable metadata stays unknown; raw output/errors never enter the receipt */ }
     const peer = live.peers.find((p) => p.id === binding.peer);
-    const session = binding.peer === "codex" ? peer?.threadId : peer?.sessionId;
+    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)`);
+    throw nativeFailure(planned, binding.peer, "attachment_timeout", `${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)`, { handle: binding.handle, timeoutMs: RECONNECT_WAIT_MS });
+    } catch (error) { waitFailed = true; throw error; }
+    finally {
+      const finish = () => {
+        if (!waitStep) return;
+        op.waits![waitStep] = { ...op.waits![waitStep]!, waitEndedAt: new Date(now()).toISOString() };
+        saveTiming();
+      };
+      // Metadata storage must not hide the attachment failure or change its recovery outcome.
+      if (waitFailed) { try { finish(); } catch { /* original attachment failure remains authoritative */ } }
+      else finish();
+    }
   };
   return {
+    ...(liveTestPeer === undefined ? {} : { liveTestPeer }),
     now, sleep, inspect: inspectRecovery,
+    recordedSessionState: async (binding, kind) => kind === "rollout" ? codexTranscript(binding) : claudeTranscriptState(binding),
     stage: async (op) => {
       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 }) }
@@ -485,16 +589,24 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       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");
-      if (op.plan.projects.some(p => p.source.peers.some(peer => peer.id === "qwen" && peer.state !== "offline"))) {
+      // 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 => definitionOf(peer.id)?.session.restoreOnStart && 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;
         if (!peers || !/["']qwen["']/.test(peers)) throw new FinalRefusal("target does not support Qwen; end Qwen and make a new plan, or choose a supporting target; runtimes unchanged");
@@ -508,12 +620,20 @@ 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),
-    release: (p, id, instance) => control(p, "release", id, instance),
+    commit: (p, id, instance, features) => control(p, "commit", id, instance, features),
+    release: async (p, id, instance) => {
+      // Snapshot before the request: a later writer must never be retired by this older release completion.
+      const previous = readRecoveryContinuity(p.stateDir, { projectId: p.id, projectRoot: p.root });
+      await control(p, "release", id, instance);
+      if (previous.state === "ready" && previous.bookmark.operationId !== id) {
+        try { retireRecoveryContinuity(p.stateDir, { projectId: p.id, projectRoot: p.root, operationId: previous.bookmark.operationId, digest: previous.digest }, "recovery_released"); }
+        catch { console.error("Pi continuity retirement is unconfirmed after successful recovery release; inspect the retained bookmark before another automatic start"); }
+      }
+    },
     closeTerminals: async (planned, progress, op, save) => {
       for (const binding of planned.terminals as TerminalBinding[]) {
         const key = `closed:${binding.peer}`;
@@ -563,10 +683,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       if (reconnect.length) waiveRecoveryPeers(p.stateDir, op.id, Object.fromEntries(reconnect.map((peer) => [peer, "reconnect-only"])));
       await command(op, ["up"], p);
     },
-    restore: async (planned, progress, op, group, save) => {
+    restore: async (planned, progress, op, group, save, onlyPeer) => {
       const live = await inspectRecovery(planned.project);
       if (live.instanceId !== progress.instanceId) throw new Error("target daemon changed before peer restore");
-      if (group === "native") {
+      if (group === "native" && !onlyPeer) {
         for (const peer of planned.source.peers.filter((p) => ["kimi", "qwen", "jcode", "local", "pi"].includes(p.id) && p.state !== "offline" && !(p.id === "pi" && p.args?.mode === "tui"))) {
           const current = live.peers.find((p) => p.id === peer.id);
           if (current && current.state !== "offline") continue;
@@ -583,7 +703,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           // #269: `ahub pi` without a mode now takes Pi's start mode (tui by default). This Pi ran headless (a terminal
           // one is filtered out above), so a snapshot that recorded no mode still restores it headless.
           if (peer.id === "pi" && typeof peer.args?.mode !== "string") args.push("--mode", "headless");
-          if (peer.id === "qwen" && peer.sessionId) args.push("--session-id", peer.sessionId);
+          if (definitionOf(peer.id)?.session.restoreOnStart && peer.sessionId) args.push("--session-id", peer.sessionId);
           if (peer.id === "jcode" && peer.sessionId) args.push("--session-id", peer.sessionId);
           if (peer.id === "jcode" && peer.args?.providerProfile) args.push("--provider-profile", peer.args.providerProfile);
           if (peer.id === "pi") {
@@ -594,130 +714,221 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           await command(op, args, planned.project);
         }
       }
+      let claudeGroup = false;
       for (const plannedBinding of planned.terminals as TerminalBinding[]) {
-        if ((plannedBinding.peer === "claude") !== (group === "claude")) continue;
+        if ((plannedBinding.peer === "claude") !== (claudeGroup = group === "claude") || onlyPeer && plannedBinding.peer !== onlyPeer) continue;
         const key = `restored:${plannedBinding.peer}`;
-        // #225: after a restart, the stopped target's terminal for this peer goes first; a session it had accepted
-        // instead of the planned one (fresh choice, fresh start, zero-turn Claude) is relaunched by that id, which the
-        // operation-fenced waiver already covers.
-        await closeRetired(progress, plannedBinding.peer, save);
-        const retired = progress.terminals[`retired:${plannedBinding.peer}`] as TerminalBinding | undefined;
-        const accepted = retired && typeof retired === "object" && retired.sessionId !== plannedBinding.sessionId ? retired.sessionId : undefined;
-        const original = accepted ? { ...plannedBinding, sessionId: accepted } : plannedBinding;
-        // A new session is accepted only by the operator's choice (#215 dispose --fresh-session) or a planned fresh
-        // start of a Codex thread with nothing to lose that still has no rollout; an unreadable store is neither.
-        const chosen = !!progress.fresh?.[original.peer];
-        let read: ReturnType<typeof codexTranscript> | undefined;
-        const transcript = () => original.peer !== "codex" || (chosen && !accepted) ? "found" : (read ??= codexTranscript(original));
-        // An accepted session starts new again only when it has nothing to resume: a Codex thread that never got a
-        // rollout, or a Claude session with no transcript (`--resume` could never succeed, #21).
-        const fresh = () => accepted
-          ? (original.peer === "codex" ? (chosen || !!planned.freshStart?.includes("codex")) && transcript() === "missing" : original.peer === "claude" && !claudeTranscriptExists(original))
-          : chosen || (!!planned.freshStart?.includes(original.peer) && transcript() === "missing");
-        // The runner ends this with the choices `status` shows (nextActions); resume comes first and launches a failed
-        // peer again, which helps once its cause (a transient Orca create failure, a fixed store) is gone.
-        // The waiver's audit label: the operator's choice, a Claude with nothing to resume, or the plan's Codex fresh start.
-        const waiver = () => progress.fresh?.[original.peer] ? "fresh-session" : original.peer === "claude" ? "zero-turn" : "fresh-start";
-        const notRestored = (why: string) => new Error(fresh()
-          ? `${original.peer}: ${why}; read that terminal in Orca for the launcher's error and fix its cause`
-          : `${original.peer}: ${why}; session ${original.sessionId} was not restored; resume launches it again once the cause is fixed`);
-        // Anything live or unknown blocks a create and keeps the receipt: never decide on evidence that could not be read.
-        const blocked = (evidence: Exclude<Awaited<ReturnType<typeof peerEvidence>>, { state: "gone" }>) => new Error(evidence.state === "unknown"
-          ? `${original.peer}: whether a ${original.peer} session or launcher is live cannot be told (${evidence.why}); nothing was recorded or created${evidence.step ? `; ${evidence.step} first` : ""}`
-          : 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") {
-          const binding = receipt as TerminalBinding;
-          const sessionId = await awaitAttachment(planned, progress, op, binding, save, fresh() && binding.sessionId === original.sessionId ? null : binding.sessionId);
-          progress.terminals[key] = { ...binding, sessionId }; save();
-          progress.terminals[key] = await revalidateTerminal(planned, progress, progress.terminals[key] as TerminalBinding, true); save();
-          continue;
-        }
-        // #215: the pending row of the receipt table, used wherever a pending launch meets an attached session.
-        const settle = async (attached: string) => {
-          // #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`);
+        try {
+          // #225: after a restart, the stopped target's terminal for this peer goes first; a session it had accepted
+          // instead of the planned one (fresh choice, fresh start, zero-turn Claude) is relaunched by that id, which the
+          // operation-fenced waiver already covers.
+          await closeRetired(progress, plannedBinding.peer, save);
+          const retired = progress.terminals[`retired:${plannedBinding.peer}`] as TerminalBinding | undefined;
+          const accepted = retired && typeof retired === "object" && retired.sessionId !== plannedBinding.sessionId ? retired.sessionId : undefined;
+          const repair = progress.reattachments?.[plannedBinding.peer];
+          const recordedOnly = !!repair || progress.repairedSessions?.[plannedBinding.peer] === true && !progress.fresh?.[plannedBinding.peer]?.repaired;
+          const retiredReceipt = recordedOnly && retired !== undefined ? decodeRestoreReceipt({ state: "done", binding: retired }) : undefined;
+          const recordedBinding = retiredReceipt?.state === "done" && retiredReceipt.binding.peer === plannedBinding.peer && retiredReceipt.binding.projectRoot === planned.project.root ? retiredReceipt.binding : undefined;
+          const original = repair?.binding ?? recordedBinding ?? (accepted ? { ...plannedBinding, sessionId: accepted } : plannedBinding);
+          // A new session is accepted only by the operator's choice (#215 dispose --fresh-session) or a planned fresh
+          // start of a Codex thread with nothing to lose that still has no rollout; an unreadable store is neither.
+          const chosen = !recordedOnly && !!progress.fresh?.[original.peer];
+          let read: ReturnType<typeof codexTranscript> | undefined;
+          const transcript = () => original.peer !== "codex" || (chosen && !accepted) ? "found" : (read ??= codexTranscript(original));
+          // An accepted session starts new again only when it has nothing to resume: a Codex thread that never got a
+          // rollout, or a Claude session with no transcript (`--resume` could never succeed, #21).
+          const fresh = () => recordedOnly ? false : accepted
+            ? (original.peer === "codex" ? (chosen || !!planned.freshStart?.includes("codex")) && transcript() === "missing" : original.peer === "claude" && !claudeTranscriptExists(original))
+            : chosen || (!!planned.freshStart?.includes(original.peer) && transcript() === "missing");
+          // The runner ends this with the choices `status` shows (nextActions); resume comes first and launches a failed
+          // peer again, which helps once its cause (a transient Orca create failure, a fixed store) is gone.
+          // The waiver's audit label: the operator's choice, a Claude with nothing to resume, or the plan's Codex fresh start.
+          const waiver = () => progress.fresh?.[original.peer] ? "fresh-session" : original.peer === "claude" ? "zero-turn" : "fresh-start";
+          const notRestored = (why: string) => new Error(fresh()
+            ? `${original.peer}: ${why}; read that terminal in Orca for the launcher's error and fix its cause`
+            : `${original.peer}: ${why}; session ${original.sessionId} was not restored; resume launches it again once the cause is fixed`);
+          // Anything live or unknown blocks a create and keeps the receipt: never decide on evidence that could not be read.
+          const blocked = (evidence: Exclude<Awaited<ReturnType<typeof peerEvidence>>, { state: "gone" }>) => evidence.state === "unknown"
+            ? new Error(`${original.peer}: whether a ${original.peer} session or launcher is live cannot be told (${evidence.why}); nothing was recorded or created${evidence.step ? `; ${evidence.step} first` : ""}`)
+            : nativeFailure(planned, original.peer, evidence.session ? "session_changed" : "launcher_unverified", 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`,
+            evidence.session
+              ? { expectedSession: original.sessionId, observedSession: evidence.session }
+              : { ...(evidence.handle ? { handle: evidence.handle } : {}), launcherState: evidence.terminal ? "live" : "older-instance" });
+          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() || (!recordedOnly && 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, 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() && !(!recordedOnly && 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]?.lost === plannedBinding.sessionId) {
+              delete progress.fresh[original.peer];
+              if (!Object.keys(progress.fresh).length) delete progress.fresh;
+            }
+            // Any other accepted session needs the target to waive the saved id, or release would wait for it forever;
+            // 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() });
+            if (repair) repair.state = "attempted"; // a verified spontaneous reattachment also closes this repair allowance
+            // The person accepted one loss, not a permanent exemption for later repairs of the replacement.
+            if (progress.fresh?.[original.peer]?.repaired) delete progress.fresh[original.peer]!.repaired;
+            progress.terminals[key] = { state: "done", binding: verified } satisfies RestoreReceipt; save();
+          };
+          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).
+            await detached(planned, progress, op, receipt.binding, save);
+            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;
           }
-          // 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]) {
-            delete progress.fresh[original.peer];
-            if (!Object.keys(progress.fresh).length) delete progress.fresh;
+          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; }
           }
-          // Any other accepted session needs the target to waive the saved id, or release would wait for it forever;
-          // 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();
-        };
-        // #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 === "pending" || receipt?.state === "failed") {
+            const evidence = await peerEvidence(planned, progress, original.peer);
+            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`);
+            }
+          }
+          // 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) { await settle(evidence.session); continue; }
+          if (evidence.state === "live" && evidence.session === original.sessionId) {
+            if (repair) await settle(evidence.session);
+            else { progress.terminals[key] = { state: "done", binding: await revalidateTerminal(planned, progress, original, false) } satisfies RestoreReceipt; save(); }
+            continue;
+          }
           if (evidence.state !== "gone") throw blocked(evidence);
-          if (receipt === "pending") {
-            progress.terminals[key] = "failed"; save();
-            throw notRestored(`its launcher no longer runs and no ${original.peer} session attached`);
+          if (transcript() === "unknown") throw new Error(`${unresumable(original)}; no terminal was created; make that store readable first`);
+          if (transcript() === "missing" && !fresh()) {
+            progress.terminals[key] = { state: "failed" } satisfies RestoreReceipt; save();
+            if (recordedOnly) throw new MissingRecordedSession({ projectId: planned.project.id, peer: original.peer, sessionId: original.sessionId, kind: "rollout", checkedPath: checkedSessionPath(original, "rollout") });
+            throw notRestored(unresumable(original).slice("codex: ".length));
           }
-          // 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();
-          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();
-          throw notRestored(unresumable(original).slice("codex: ".length));
-        }
-        if (fresh()) {
-          if (!targetReadsWaivers(op)) throw new Error(`${original.peer}: target ${op.plan.version} predates recovery waivers, so it cannot accept a new session`);
-          // The restored daemon must accept the new session instead of the recorded one.
-          waiveRecoveryPeers(planned.project.stateDir, op.id, { [original.peer]: waiver() });
-        }
-        const entrypoint = join(op.targetRoot!, "src/cli/main.js");
-        const argv = restoredTerminalArgv(entrypoint, planned.project.root, original, fresh());
-        const assignments = { ...original.launch.env, AGENTHUB_HOME: hubHome(), AGENTHUB_RECOVERY_OPERATION: op.id };
-        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();
-        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) {
-          // #215: the launcher's exit alone is not the peer's state (a target that died or flapped also ends it): only
-          // 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; }
-          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`);
+          if (fresh()) {
+            if (!targetReadsWaivers(op)) throw new Error(`${original.peer}: target ${op.plan.version} predates recovery waivers, so it cannot accept a new session`);
+            // The restored daemon must accept the new session instead of the recorded one.
+            waiveRecoveryPeers(planned.project.stateDir, op.id, { [original.peer]: waiver() });
+          }
+          if (repair) {
+            if (repair.state === "attempted") throw new ReattachmentRequired(planned.project.id, original.peer, `${original.peer}: recorded-session reattachment already attempted; no second terminal will be created`);
+            repair.state = "attempted"; save(); // durable before any terminal creation, including an uncertain failure
+          }
+          const entrypoint = join(op.targetRoot!, "src/cli/main.js");
+          const argv = restoredTerminalArgv(entrypoint, planned.project.root, original, fresh());
+          const assignments = { ...original.launch.env, AGENTHUB_HOME: hubHome(), AGENTHUB_RECOVERY_OPERATION: op.id };
+          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] = { 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) {
+            // #215: the launcher's exit alone is not the peer's state (a target that died or flapped also ends it): only
+            // 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);
+            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);
+          }
+          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.
+          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);
+        } catch (error) {
+          if (error instanceof MissingRecordedSession || isDatabaseBusy(error)) throw error;
+          // A failed recorded-only Claude launch may prove that its transcript is gone. No error text is evidence.
+          if (claudeGroup && progress.repairedSessions?.[plannedBinding.peer] && !progress.fresh?.[plannedBinding.peer]?.repaired) {
+            const chosenReceipt = decodeRestoreReceipt(progress.terminals[key]);
+            // A bare pending/failed row can hide an uncertain create. Only a durable exact chosen binding
+            // can become the terminal that an explicit fresh choice must close before another create.
+            const binding = chosenReceipt?.state === "waiting" ? chosenReceipt.binding : undefined;
+            if (binding && claudeTranscriptState(binding) === "missing" && (await peerEvidence(planned, progress, plannedBinding.peer)).state === "gone") {
+              // Retain the exact chosen terminal so an explicit later fresh choice closes it before creating again.
+              progress.terminals[`retired:${plannedBinding.peer}`] = binding;
+              delete progress.terminals[`closedRetired:${plannedBinding.peer}`];
+              const marker = progress.reattachments?.[plannedBinding.peer];
+              if (marker) marker.binding = binding;
+              progress.terminals[key] = { state: "failed" } satisfies RestoreReceipt; save();
+              throw new MissingRecordedSession({ projectId: planned.project.id, peer: plannedBinding.peer, sessionId: binding.sessionId, kind: "transcript", checkedPath: checkedSessionPath(binding, "transcript") });
+            }
+          }
+          if (error instanceof ReattachmentRequired || isDatabaseBusy(error)) throw error;
+          if (progress.reattachments?.[plannedBinding.peer]) throw new ReattachmentRequired(planned.project.id, plannedBinding.peer,
+            error instanceof Error ? error.message : `${plannedBinding.peer}: recorded-session reattachment is unconfirmed`, error instanceof RecoveryPresentationError ? error : undefined);
+          throw error;
         }
-        // The daemon's id is authoritative: a fresh session is recorded under the id it reports once attached.
-        progress.terminals[key] = restored.newBinding; save();
-        const sessionId = await awaitAttachment(planned, progress, op, restored.newBinding, save, fresh() ? null : restored.newBinding.sessionId);
-        progress.terminals[key] = { ...restored.newBinding, sessionId }; save();
       }
-      if (group === "claude") for (const id of planned.reconnectOnly ?? []) {
+      if (group === "claude" && !onlyPeer) 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 nativeFailure(planned, id, "attachment_timeout", `${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`, { timeoutMs: UNMANAGED_RECONNECT_WAIT_MS });
           await sleep(1000);
         }
       }
@@ -751,34 +962,78 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         await awaitStopped(project, instance);
       }
       abandonRestartSnapshot(project.stateDir, op.id);
+      const planned = op.plan.projects?.find(item => item.project.id === project.id);
+      const progress = op.projects?.find(item => item.id === project.id);
+      const source = planned?.source.peers.find(peer => peer.id === "pi" && peer.state !== "offline");
+      if (source && progress) {
+        // abandonRestartSnapshot is deliberately a no-op for another operation or an unreadable snapshot.
+        // A continuity bookmark needs positive archival evidence, including when disposal resumes after a crash.
+        const archive = join(project.stateDir, `restart.abandoned.${createHash("sha256").update(op.id).digest("hex")}.json`);
+        let archived: unknown;
+        try { archived = JSON.parse(readFileSync(archive, "utf8")); } catch { return { continuity: "not-archived" }; }
+        if (!archived || typeof archived !== "object" || (archived as { operationId?: unknown }).operationId !== op.id) return { continuity: "not-archived" };
+        try {
+          const binding = planned ? resolveAcceptedBinding(planned, progress, "pi") : undefined;
+          const sessionId = binding?.sessionId ?? source.sessionId;
+          if (!sessionId) throw new Error("Pi recorded session unavailable; archive continuity bookmark was not written");
+          const backend = binding?.backend ?? source.args?.backend;
+          writeRecoveryContinuity(project.stateDir, { schema: 1, operationId: op.id, projectId: project.id, projectRoot: project.root, at: now(),
+            pi: { sessionId, sessionFile: binding?.sessionFile ?? source.sessionFile ?? source.args?.sessionFile,
+              ...(backend === "auto" || backend === "dgx" || backend === "mlx" ? { backend } : {}), model: binding?.model ?? source.args?.model } });
+        } catch { return { continuity: "unavailable" }; } // optional metadata must not wedge stop-and-archive
+      }
     },
     refreshManager: async (op) => { await refreshManager({ home: hubHome(), cli: join(op.targetRoot!, "src/cli/main.ts") }); },
-    verify: async (planned, progress, op) => {
+    verify: async (planned, progress, op, save) => {
       const live = await inspectRecovery(planned.project);
       if (live.instanceId !== progress.instanceId || live.version !== op.plan.version || live.recovery?.operationId !== op.id) throw new Error("target identity verification failed");
       for (const old of planned.source.peers.filter((p) => p.state !== "offline")) {
         const peer = live.peers.find((p) => p.id === old.id);
-        if (!peer || !["idle", "busy", "paused"].includes(peer.state)) throw new Error(`${old.id}: peer reattachment not verified`);
-        if (progress.fresh?.[old.id] || planned.freshStart?.includes(old.id)) continue; // #215: a new session was accepted (recorded)
-        if (old.id === "codex" && peer.threadId !== old.threadId) throw new Error("Codex resumed a different conversation");
+        if (!peer || !["idle", "busy", "paused"].includes(peer.state)) {
+          const receipt = decodeRestoreReceipt(progress.terminals[`restored:${old.id}`]);
+          if (receipt?.state === "done") await detached(planned, progress, op, receipt.binding, save);
+          throw new Error(`${old.id}: peer reattachment not verified`);
+        }
+        const accepted = decodeRestoreReceipt(progress.terminals[`restored:${old.id}`]);
+        const repair = progress.reattachments?.[old.id as "codex" | "pi" | "claude"];
+        const recordedOnly = !!repair || progress.repairedSessions?.[old.id as keyof NonNullable<ProjectProgress["repairedSessions"]>] === true && !progress.fresh?.[old.id]?.repaired;
+        const retiredValue = progress.terminals[`retired:${old.id}`];
+        const retired = retiredValue === undefined ? undefined : decodeRestoreReceipt({ state: "done", binding: retiredValue });
+        // A #225 restart clears the old target's repair fence, never its accepted conversation.
+        const retained = retired?.state === "done" && accepted?.state === "done" && retired.binding.peer === old.id && retired.binding.projectRoot === planned.project.root && retired.binding.sessionId === accepted.binding.sessionId;
+        if ((recordedOnly || retained) && accepted?.state === "done") {
+          const session = old.id === "codex" ? peer.threadId : peer.sessionId;
+          if (session !== accepted.binding.sessionId || repair && accepted.binding.sessionId !== repair.binding.sessionId ||
+              old.id === "pi" && (recordedOnly || old.sessionFile) && accepted.binding.sessionFile && peer.sessionFile !== accepted.binding.sessionFile) throw nativeFailure(planned, old.id, "session_changed", `${old.id}: reattached a different recorded conversation`, { handle: accepted.binding.handle, expectedSession: accepted.binding.sessionId, ...(session === undefined ? {} : { observedSession: session }) });
+          continue;
+        }
+        if (!recordedOnly && (progress.fresh?.[old.id] || planned.freshStart?.includes(old.id))) continue; // #215: a new session was accepted (recorded)
+        if (old.id === "codex" && peer.threadId !== old.threadId) throw nativeFailure(planned, old.id, "session_changed", "Codex resumed a different conversation", { ...(old.threadId ? { expectedSession: old.threadId } : {}), ...(peer.threadId ? { observedSession: peer.threadId } : {}) });
         if (old.id === "claude" && peer.sessionId !== old.sessionId) {
           // #64: the restore gate already accepted a fresh session when the original never
           // persisted a transcript. Re-derive persistence from the binding exactly like that
           // gate did, so a first turn landing after the plan was made keeps the check strict.
           const binding = (planned.terminals as TerminalBinding[]).find((t) => t.peer === "claude");
-          if (!binding || binding.sessionId !== old.sessionId || claudeTranscriptExists(binding)) throw new Error("Claude resumed a different conversation");
+          if (recordedOnly || !binding || binding.sessionId !== old.sessionId || claudeTranscriptExists(binding)) throw nativeFailure(planned, old.id, "session_changed", "Claude resumed a different conversation", { ...(old.sessionId ? { expectedSession: old.sessionId } : {}), ...(peer.sessionId ? { observedSession: peer.sessionId } : {}) });
         }
-        if (old.id === "pi" && (peer.sessionId !== old.sessionId || (old.sessionFile && peer.sessionFile !== old.sessionFile))) throw new Error("Pi resumed a different conversation");
+        if (old.id === "pi" && (peer.sessionId !== old.sessionId || (old.sessionFile && peer.sessionFile !== old.sessionFile))) throw nativeFailure(planned, old.id, "session_changed", "Pi resumed a different conversation", { ...(old.sessionId ? { expectedSession: old.sessionId } : {}), ...(peer.sessionId ? { observedSession: peer.sessionId } : {}) });
       }
       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");
       const recovery = await rpc(planned.project, { t: "recovery", op: "inspect", expectedInstanceId: progress.instanceId });
       const integrity = recovery.recovery?.integrity;
+      if (integrity?.expected && integrity.current) {
+        for (const check of ["queues", "manualPaused", "boardDigest", "budgetDigest"] as const) {
+          if (JSON.stringify(integrity.current[check]) !== JSON.stringify(integrity.expected[check])) {
+            throw new RecoveryPreservationError(check, planned.project.id);
+          }
+        }
+      }
       if (!integrity?.expected || JSON.stringify(integrity.current) !== JSON.stringify(integrity.expected)) {
         throw new Error("queue, manual pause, task board or budget preservation was not verified");
       }