@openrig/cli 0.5.0 → 0.5.2

package/node_modules/@openrig/daemon/dist/domain/restore-orchestrator.js

@@ -0,0 +1,1318 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolvePermissionPolicyAttachment } from "./permission-policy/policy-ref.js";
+import { assessNativeResumeProbe } from "./native-resume-probe.js";
+import { AppliedLaunchObservationStore } from "./applied-launch-observation-store.js";
+// Only these edge kinds constrain launch order
+const LAUNCH_DEPENDENCY_KINDS = new Set(["delegates_to", "spawned_by"]);
+export function rollupRestoreRigResult(nodes) {
+    if (nodes.length === 0)
+        return "failed";
+    // L3: `attention_required` is non-terminal failure (alive but blocked on
+    // operator action). It rolls up as `partially_restored`. `operator_recovered`
+    // is a clean post-reconciliation outcome and rolls up like `resumed`.
+    const allFailed = nodes.every((node) => node.status === "failed");
+    if (allFailed)
+        return "failed";
+    if (nodes.some((node) => node.status === "fresh" || node.status === "fresh-primed" || node.status === "awaiting-decision" || node.status === "failed" || node.status === "attention_required")) {
+        return "partially_restored";
+    }
+    return "fully_restored";
+}
+/** OPR.0.4.3.20 FR-7 — restore/launch statuses that mean NO session is running and
+ *  the operator must act. The launch API + CLI must NOT report these as a successful
+ *  launch (a subset/single launch that lands `awaiting-decision` is not "Launched"). */
+export const NON_RUNNING_LAUNCH_STATUSES = new Set([
+    "awaiting-decision",
+    "attention_required",
+    "failed",
+]);
+/** True when a restore/launch status means a session is actually running (a real
+ *  successful launch): resumed / rebuilt / fresh / fresh-primed / operator_recovered. */
+export function launchStatusIsRunning(status) {
+    return !NON_RUNNING_LAUNCH_STATUSES.has(status);
+}
+export class RestoreOrchestrator {
+    db;
+    activeRestores = new Set();
+    rigRepo;
+    sessionRegistry;
+    eventBus;
+    snapshotRepo;
+    snapshotCapture;
+    nodeLauncher;
+    tmuxAdapter;
+    claudeResume;
+    codexResume;
+    piResume;
+    transcriptStore;
+    serviceOrchestrator;
+    appliedLaunchStore;
+    constructor(deps) {
+        if (deps.db !== deps.rigRepo.db) {
+            throw new Error("RestoreOrchestrator: rigRepo must share the same db handle");
+        }
+        if (deps.db !== deps.sessionRegistry.db) {
+            throw new Error("RestoreOrchestrator: sessionRegistry must share the same db handle");
+        }
+        if (deps.db !== deps.eventBus.db) {
+            throw new Error("RestoreOrchestrator: eventBus must share the same db handle");
+        }
+        if (deps.db !== deps.snapshotRepo.db) {
+            throw new Error("RestoreOrchestrator: snapshotRepo must share the same db handle");
+        }
+        if (deps.db !== deps.checkpointStore.db) {
+            throw new Error("RestoreOrchestrator: checkpointStore must share the same db handle");
+        }
+        if (deps.db !== deps.snapshotCapture.db) {
+            throw new Error("RestoreOrchestrator: snapshotCapture must share the same db handle");
+        }
+        if (deps.db !== deps.nodeLauncher.db) {
+            throw new Error("RestoreOrchestrator: nodeLauncher must share the same db handle");
+        }
+        this.db = deps.db;
+        this.rigRepo = deps.rigRepo;
+        this.sessionRegistry = deps.sessionRegistry;
+        this.eventBus = deps.eventBus;
+        this.snapshotRepo = deps.snapshotRepo;
+        this.snapshotCapture = deps.snapshotCapture;
+        this.nodeLauncher = deps.nodeLauncher;
+        this.tmuxAdapter = deps.tmuxAdapter;
+        this.claudeResume = deps.claudeResume;
+        this.codexResume = deps.codexResume;
+        this.piResume = deps.piResume ?? null;
+        this.transcriptStore = deps.transcriptStore ?? null;
+        this.serviceOrchestrator = deps.serviceOrchestrator ?? null;
+        this.appliedLaunchStore = new AppliedLaunchObservationStore(deps.db);
+    }
+    async restore(snapshotId, opts) {
+        // 1. Load snapshot
+        const snapshot = this.snapshotRepo.getSnapshot(snapshotId);
+        if (!snapshot) {
+            return { ok: false, code: "snapshot_not_found", message: `Snapshot ${snapshotId} not found` };
+        }
+        const rigId = snapshot.rigId;
+        const rig = this.rigRepo.getRig(rigId);
+        if (!rig) {
+            return { ok: false, code: "rig_not_found", message: `Rig ${rigId} not found` };
+        }
+        // Classify DB-running sessions against tmux reality WITHOUT mutating DB.
+        // This determines whether the rig is safe to restore before any state
+        // changes occur — critical for pre_restore snapshot ordering (snapshot
+        // must capture original DB state, not post-reconciliation state).
+        const classification = await this.classifyRunningSessions(rigId);
+        if (classification.live.length > 0 || classification.unknown.length > 0) {
+            return { ok: false, code: "rig_not_stopped", message: `Rig ${rigId} has live sessions. Stop the rig with 'rig down' before restoring, or use the latest auto-pre-down snapshot.` };
+        }
+        // Per-rig concurrency lock
+        if (this.activeRestores.has(rigId)) {
+            return { ok: false, code: "restore_in_progress", message: `Restore already in progress for rig ${rigId}` };
+        }
+        this.activeRestores.add(rigId);
+        try {
+            const validation = this.validatePreRestore(snapshot.data, {
+                fsOps: opts?.fsOps,
+                servicesRecord: this.rigRepo.getServicesRecord(rigId),
+            });
+            if (validation.blockers.length > 0) {
+                const result = {
+                    snapshotId,
+                    preRestoreSnapshotId: null,
+                    rigResult: "not_attempted",
+                    nodes: [],
+                    warnings: validation.warnings,
+                    blockers: validation.blockers,
+                };
+                return {
+                    ok: false,
+                    code: "pre_restore_validation_failed",
+                    message: "Restore pre-validation failed; no restore mutation was attempted.",
+                    result,
+                };
+            }
+            // 2. Capture pre-restore snapshot BEFORE any DB mutations —
+            // DB still reflects original session state (running for stale sessions)
+            const preRestoreSnapshot = this.snapshotCapture.captureSnapshot(rigId, "pre_restore");
+            // 2b. NOW mark stale sessions as detached (safe: we've captured the
+            // pre-restore snapshot and confirmed no live/unknown sessions remain)
+            for (const sessionId of classification.stale) {
+                this.sessionRegistry.markDetached(sessionId);
+            }
+            // 3. Emit restore.started — the persisted event seq IS the attempt id
+            //    (Decision 1: no separate restore_attempts table).
+            const restoreStartedEvent = this.eventBus.emit({ type: "restore.started", rigId, snapshotId });
+            const attemptId = restoreStartedEvent.seq;
+            try {
+                opts?.onAttemptStarted?.(attemptId);
+            }
+            catch {
+                // onAttemptStarted is fire-and-forget; never let a route's response
+                // logic crash the restore pipeline.
+            }
+            // 3b. Service gate: boot services before agent restore if this rig has services
+            if (this.serviceOrchestrator) {
+                const svcRecord = this.rigRepo.getServicesRecord(rigId);
+                if (svcRecord) {
+                    const bootResult = await this.serviceOrchestrator.boot(rigId);
+                    if (!bootResult.ok) {
+                        this.eventBus.emit({ type: "restore.completed", rigId, snapshotId, result: { snapshotId, preRestoreSnapshotId: preRestoreSnapshot.id, rigResult: "failed", nodes: [], warnings: [`Service boot failed: ${bootResult.error}`] } });
+                        return { ok: false, code: "service_boot_failed", message: `Service boot failed before agent restore: ${bootResult.error}` };
+                    }
+                }
+            }
+            // 4. Compute restore plan
+            const plan = this.computeRestorePlan(snapshot.data);
+            // 5. Execute restore with compensating pattern per node
+            const nodeResults = [];
+            const restoreWarnings = [...validation.warnings];
+            for (const entry of plan) {
+                const result = await this.restoreNodeWithCompensation(entry, rigId, snapshotId, snapshot.data, opts, restoreWarnings);
+                nodeResults.push(result);
+            }
+            const restoreResult = {
+                snapshotId,
+                preRestoreSnapshotId: preRestoreSnapshot.id,
+                rigResult: rollupRestoreRigResult(nodeResults),
+                nodes: nodeResults,
+                warnings: restoreWarnings,
+            };
+            // 7. Emit restore.completed
+            this.eventBus.emit({ type: "restore.completed", rigId, snapshotId, result: restoreResult });
+            return { ok: true, result: restoreResult };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                code: "restore_error",
+                message: err instanceof Error ? err.message : String(err),
+            };
+        }
+        finally {
+            this.activeRestores.delete(rigId);
+        }
+    }
+    async launchNodeSubset(rigId, logicalIds, opts) {
+        const rig = this.rigRepo.getRig(rigId);
+        if (!rig)
+            return { ok: false, code: "rig_not_found", message: `Rig ${rigId} not found` };
+        const snapshot = this.snapshotRepo.findLatestRestoreUsable(rigId);
+        if (!snapshot)
+            return { ok: false, code: "no_usable_snapshot", message: `No usable snapshot for rig ${rigId}` };
+        const allNodes = rig.nodes;
+        const targetNodes = allNodes.filter((n) => logicalIds.includes(n.logicalId));
+        const matchedIds = new Set(targetNodes.map((n) => n.logicalId));
+        const unmatchedIds = logicalIds.filter((id) => !matchedIds.has(id));
+        if (targetNodes.length === 0)
+            return { ok: false, code: "no_matching_nodes", message: `No nodes match logical ids: ${logicalIds.join(", ")}` };
+        const nonTargetNodes = allNodes.filter((n) => !logicalIds.includes(n.logicalId));
+        // Per-target tmux-liveness classification (runtime truth, fail-closed)
+        const launched = [];
+        const alreadyRunning = [];
+        const failedTargets = [];
+        // Subset-level aggregate of per-node warnings (incl. FR-5 derived-name
+        // fallback observability). Previously created per-node inside the loop and
+        // discarded, so restore.subset_completed carried warnings: [].
+        const subsetWarnings = [];
+        for (const node of targetNodes) {
+            const sessions = this.sessionRegistry.getSessionsForRig(rigId)
+                .filter((s) => s.nodeId === node.id && s.status === "running");
+            let isLive = false;
+            let isUnknown = false;
+            for (const session of sessions) {
+                try {
+                    const alive = await this.tmuxAdapter.hasSession(session.sessionName);
+                    if (alive) {
+                        isLive = true;
+                        break;
+                    }
+                }
+                catch {
+                    isUnknown = true;
+                }
+            }
+            if (isLive) {
+                alreadyRunning.push({ nodeId: node.id, logicalId: node.logicalId });
+                continue;
+            }
+            if (isUnknown) {
+                // OPR.0.4.3.28 correction — INVERT the fail-closed-on-unknown launch default. A failed tmux
+                // liveness probe is NOT positive evidence of a live seat (only isLive, above, is). Deny-by-
+                // default here hard-503'd all restore/launch on a transient tmux blip. Instead PROCEED to
+                // launch this node (same path as stale/no-session below) and surface the uncertainty as a
+                // NON-blocking warning so an operator/agent can verify no live seat was squatted. isLive stays
+                // the no-squat guard.
+                subsetWarnings.push(`liveness_probe_unknown: launched '${node.logicalId}' despite a failed tmux liveness probe — verify no live seat was squatted`);
+            }
+            // Stale or no session (or probe-unknown, per the inversion above) — launchable. Accumulate this
+            // node's warnings into
+            // the subset-level array so they survive to restore.subset_completed + the
+            // API result (FR-5 fallback observability must not be discarded here).
+            const planEntry = { node };
+            const result = await this.restoreNodeWithCompensation(planEntry, rigId, snapshot.id, snapshot.data, { adapters: opts?.adapters, fsOps: opts?.fsOps }, subsetWarnings);
+            launched.push(result);
+        }
+        // Emit restore.subset_completed for launched targets only
+        if (launched.length > 0) {
+            const subsetResult = {
+                snapshotId: snapshot.id,
+                preRestoreSnapshotId: null,
+                rigResult: rollupRestoreRigResult(launched),
+                nodes: launched,
+                warnings: subsetWarnings,
+            };
+            this.eventBus.emit({ type: "restore.subset_completed", rigId, snapshotId: snapshot.id, result: subsetResult });
+        }
+        // Emit node.held for non-running held non-targets (tri-state: running/unknown/held)
+        const held = [];
+        const holdReasonText = opts?.holdReason ?? "excluded_from_subset";
+        for (const node of nonTargetNodes) {
+            const sessions = this.sessionRegistry.getSessionsForRig(rigId)
+                .filter((s) => s.nodeId === node.id && s.status === "running");
+            let running = false;
+            let unknown = false;
+            for (const session of sessions) {
+                try {
+                    if (await this.tmuxAdapter.hasSession(session.sessionName)) {
+                        running = true;
+                        break;
+                    }
+                }
+                catch {
+                    unknown = true;
+                }
+            }
+            if (running || unknown)
+                continue;
+            // Clear stale DB-running rows for non-targets proven tmux-dead so
+            // inventory projects heldReason honestly (not masked by stale running status).
+            for (const session of sessions) {
+                this.sessionRegistry.markDetached(session.id);
+            }
+            this.eventBus.emit({
+                type: "node.held",
+                rigId,
+                nodeId: node.id,
+                logicalId: node.logicalId,
+                reason: holdReasonText,
+            });
+            held.push({ nodeId: node.id, logicalId: node.logicalId, reason: holdReasonText });
+        }
+        return { ok: true, launched, held, alreadyRunning, failedTargets, unmatchedIds: unmatchedIds.length > 0 ? unmatchedIds : undefined, warnings: subsetWarnings.length > 0 ? subsetWarnings : undefined };
+    }
+    validatePreRestore(data, opts) {
+        const blockers = [];
+        const warnings = [];
+        const exists = opts.fsOps?.exists ?? (() => true);
+        const add = (blocker) => blockers.push(blocker);
+        const nodes = Array.isArray(data.nodes) ? data.nodes : null;
+        const sessions = Array.isArray(data.sessions) ? data.sessions : null;
+        const edges = Array.isArray(data.edges) ? data.edges : null;
+        const checkpoints = data.checkpoints && typeof data.checkpoints === "object" ? data.checkpoints : null;
+        if (!data.rig || typeof data.rig.id !== "string") {
+            add({
+                code: "invalid_snapshot_data",
+                severity: "critical",
+                target: "snapshot.rig",
+                message: "Snapshot is missing the rig record needed for restore.",
+                remediation: "Capture a new snapshot or restore from a structurally valid snapshot.",
+            });
+        }
+        if (!nodes) {
+            add({
+                code: "invalid_snapshot_data",
+                severity: "critical",
+                target: "snapshot.nodes",
+                message: "Snapshot is missing the node list needed for restore.",
+                remediation: "Capture a new snapshot or restore from a structurally valid snapshot.",
+            });
+        }
+        if (!sessions) {
+            add({
+                code: "invalid_snapshot_data",
+                severity: "critical",
+                target: "snapshot.sessions",
+                message: "Snapshot is missing session records needed for restore.",
+                remediation: "Capture a new snapshot or restore from a structurally valid snapshot.",
+            });
+        }
+        if (!edges) {
+            add({
+                code: "invalid_snapshot_data",
+                severity: "critical",
+                target: "snapshot.edges",
+                message: "Snapshot is missing topology edges needed for restore planning.",
+                remediation: "Capture a new snapshot or restore from a structurally valid snapshot.",
+            });
+        }
+        if (!checkpoints) {
+            add({
+                code: "invalid_snapshot_data",
+                severity: "critical",
+                target: "snapshot.checkpoints",
+                message: "Snapshot is missing the checkpoint map needed for restore.",
+                remediation: "Capture a new snapshot or restore from a structurally valid snapshot.",
+            });
+        }
+        if (!nodes || !checkpoints) {
+            return { blockers, warnings };
+        }
+        for (const node of nodes) {
+            const checkpoint = checkpoints[node.id] ?? null;
+            if (checkpoint && !node.cwd) {
+                add({
+                    code: "checkpoint_missing_node_cwd",
+                    severity: "critical",
+                    nodeId: node.id,
+                    logicalId: node.logicalId,
+                    target: "checkpoint",
+                    message: `Checkpoint exists for ${node.logicalId}, but the node has no cwd to receive it.`,
+                    remediation: "Update the rig spec to include a cwd for this node, then capture a new snapshot or restore manually.",
+                });
+            }
+            const startupCtx = data.nodeStartupContext?.[node.id] ?? null;
+            if (!startupCtx)
+                continue;
+            for (const file of startupCtx.resolvedStartupFiles ?? []) {
+                if (!file.required) {
+                    if (this.pathLike(file.absolutePath) && !exists(file.absolutePath)) {
+                        warnings.push(`Restore pre-validation: optional startup file missing for ${node.logicalId}: ${file.absolutePath}`);
+                    }
+                    continue;
+                }
+                if (this.pathLike(file.ownerRoot) && !exists(file.ownerRoot)) {
+                    add({
+                        code: "startup_owner_root_missing",
+                        severity: "critical",
+                        nodeId: node.id,
+                        logicalId: node.logicalId,
+                        target: file.path,
+                        path: file.ownerRoot,
+                        message: `Required startup file owner root is missing for ${node.logicalId}: ${file.ownerRoot}`,
+                        remediation: "Restore the agent/source root or capture a new snapshot with reachable startup context.",
+                    });
+                }
+                if (this.pathLike(file.absolutePath) && !exists(file.absolutePath)) {
+                    add({
+                        code: "required_startup_file_missing",
+                        severity: "critical",
+                        nodeId: node.id,
+                        logicalId: node.logicalId,
+                        target: file.path,
+                        path: file.absolutePath,
+                        message: `Required startup file is missing for ${node.logicalId}: ${file.absolutePath}`,
+                        remediation: "Restore the missing startup file or capture a new snapshot before retrying restore.",
+                    });
+                }
+            }
+            // OPR.0.3.4.5 (behavior 09): projection-validity != session continuity.
+            // A stale/missing projected skill/artifact must NOT abort a restore that
+            // has a valid native resume. Demoted from critical blockers to warnings
+            // flagged as projection_drift (compose slice-03's drift reporting shape).
+            // The existing post-launch filter (:855-885) already skips missing
+            // entries with a "(skipped)" warning; here we prevent the pre-restore
+            // gate from blocking the attempt entirely. Missing REQUIRED startup
+            // files and genuinely-fatal blockers (malformed snapshot, missing nodes)
+            // stay critical above.
+            for (const entry of startupCtx.projectionEntries ?? []) {
+                if (this.pathLike(entry.sourcePath) && !exists(entry.sourcePath)) {
+                    warnings.push(`projection_drift: source root missing for ${node.logicalId}: ${entry.sourcePath} (projection will be skipped at startup; session continuity is unaffected)`);
+                }
+                if (this.pathLike(entry.absolutePath) && !exists(entry.absolutePath)) {
+                    warnings.push(`projection_drift: entry missing for ${node.logicalId}: ${entry.absolutePath} (projection will be skipped at startup; session continuity is unaffected)`);
+                }
+            }
+        }
+        const servicesRecord = opts.servicesRecord ?? null;
+        if (servicesRecord) {
+            if (this.pathLike(servicesRecord.rigRoot) && !exists(servicesRecord.rigRoot)) {
+                add({
+                    code: "service_rig_root_missing",
+                    severity: "critical",
+                    target: "services.rigRoot",
+                    path: servicesRecord.rigRoot,
+                    message: `Service rig root is missing: ${servicesRecord.rigRoot}`,
+                    remediation: "Restore the service rig root or update the services record before retrying restore.",
+                });
+            }
+            if (this.pathLike(servicesRecord.composeFile) && !exists(servicesRecord.composeFile)) {
+                add({
+                    code: "service_compose_file_missing",
+                    severity: "critical",
+                    target: "services.composeFile",
+                    path: servicesRecord.composeFile,
+                    message: `Service compose file is missing: ${servicesRecord.composeFile}`,
+                    remediation: "Restore the compose file or update the services record before retrying restore.",
+                });
+            }
+        }
+        return { blockers, warnings };
+    }
+    pathLike(value) {
+        return typeof value === "string" && value.trim().length > 0 && (value.startsWith("/")
+            || value.startsWith("./")
+            || value.startsWith("../")
+            || value.startsWith("~"));
+    }
+    captureNodeState(nodeId, rigId) {
+        const binding = this.sessionRegistry.getBindingForNode(nodeId);
+        const sessions = this.sessionRegistry.getSessionsForRig(rigId)
+            .filter((s) => s.nodeId === nodeId && s.status !== "superseded" && s.status !== "exited")
+            .map((s) => ({ id: s.id, status: s.status }));
+        return { binding, sessions };
+    }
+    /**
+     * Classify ALL DB-running sessions against tmux reality without mutating DB.
+     * Scans every session (not just latest-per-node) to catch older live sessions
+     * behind newer detached rows. Returns structured classification for the caller
+     * to act on: live sessions block restore, stale sessions get marked detached
+     * AFTER the pre_restore snapshot is captured, unknown sessions fail closed.
+     */
+    async classifyRunningSessions(rigId) {
+        const live = [];
+        const stale = [];
+        const unknown = [];
+        for (const session of this.sessionRegistry.getSessionsForRig(rigId)) {
+            if (session.status !== "running")
+                continue;
+            try {
+                const alive = await this.tmuxAdapter.hasSession(session.sessionName);
+                if (alive) {
+                    live.push(session.id);
+                }
+                else {
+                    stale.push(session.id);
+                }
+            }
+            catch {
+                // tmux check failed — fail closed: classify as unknown so restore blocks
+                unknown.push(session.id);
+            }
+        }
+        return { live, stale, unknown };
+    }
+    clearStaleState(nodeId, rigId) {
+        this.sessionRegistry.clearBinding(nodeId);
+        const sessions = this.sessionRegistry.getSessionsForRig(rigId);
+        for (const sess of sessions) {
+            if (sess.nodeId === nodeId && sess.status !== "superseded" && sess.status !== "exited") {
+                this.sessionRegistry.markSuperseded(sess.id);
+            }
+        }
+    }
+    restoreNodeState(nodeId, priorState) {
+        // Restore prior binding EXACTLY, not as a partial merge. The launch path
+        // may have created a binding for this node (NodeLauncher), and
+        // updateBinding alone is an upsert MERGE: a null prior binding would
+        // leave the launched binding pointing at a killed session, and null
+        // prior fields would silently preserve launched-row values. Clear first,
+        // then recreate from the prior fields — or leave absent when no prior
+        // binding existed. Shared by launch-failure compensation and
+        // rollbackToZeroSession so both carry the same exact semantics.
+        this.sessionRegistry.clearBinding(nodeId);
+        if (priorState.binding) {
+            this.sessionRegistry.updateBinding(nodeId, {
+                attachmentType: priorState.binding.attachmentType ?? undefined,
+                tmuxSession: priorState.binding.tmuxSession ?? undefined,
+                tmuxWindow: priorState.binding.tmuxWindow ?? undefined,
+                tmuxPane: priorState.binding.tmuxPane ?? undefined,
+                externalSessionName: priorState.binding.externalSessionName ?? undefined,
+                cmuxWorkspace: priorState.binding.cmuxWorkspace ?? undefined,
+                cmuxSurface: priorState.binding.cmuxSurface ?? undefined,
+            });
+        }
+        // Restore prior session statuses
+        for (const sess of priorState.sessions) {
+            this.sessionRegistry.updateStatus(sess.id, sess.status);
+        }
+    }
+    computeRestorePlan(data) {
+        const nodes = data.nodes;
+        const edges = data.edges;
+        // Build adjacency for launch-dependency edges only
+        // For delegates_to: source must launch before target
+        // For spawned_by: target must launch before source
+        const nodeIds = nodes.map((n) => n.id);
+        const inDegree = {};
+        const adjacency = {};
+        for (const id of nodeIds) {
+            inDegree[id] = 0;
+            adjacency[id] = [];
+        }
+        for (const edge of edges) {
+            if (!LAUNCH_DEPENDENCY_KINDS.has(edge.kind))
+                continue;
+            let from;
+            let to;
+            if (edge.kind === "delegates_to") {
+                from = edge.sourceId;
+                to = edge.targetId;
+            }
+            else {
+                // spawned_by: target (parent) must launch before source (child)
+                from = edge.targetId;
+                to = edge.sourceId;
+            }
+            if (adjacency[from] && inDegree[to] !== undefined) {
+                adjacency[from].push(to);
+                inDegree[to] = (inDegree[to] ?? 0) + 1;
+            }
+        }
+        // Topological sort with alphabetical tiebreaker by logical_id
+        const nodeById = new Map(nodes.map((n) => [n.id, n]));
+        const queue = nodeIds
+            .filter((id) => (inDegree[id] ?? 0) === 0)
+            .sort((a, b) => {
+            const na = nodeById.get(a).logicalId;
+            const nb = nodeById.get(b).logicalId;
+            return na.localeCompare(nb);
+        });
+        const order = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            order.push(current);
+            const neighbors = (adjacency[current] ?? []).slice().sort((a, b) => {
+                const na = nodeById.get(a).logicalId;
+                const nb = nodeById.get(b).logicalId;
+                return na.localeCompare(nb);
+            });
+            for (const neighbor of neighbors) {
+                inDegree[neighbor] = (inDegree[neighbor] ?? 1) - 1;
+                if ((inDegree[neighbor] ?? 0) === 0) {
+                    // Insert in sorted position
+                    const logicalId = nodeById.get(neighbor).logicalId;
+                    let inserted = false;
+                    for (let i = 0; i < queue.length; i++) {
+                        if (nodeById.get(queue[i]).logicalId.localeCompare(logicalId) > 0) {
+                            queue.splice(i, 0, neighbor);
+                            inserted = true;
+                            break;
+                        }
+                    }
+                    if (!inserted)
+                        queue.push(neighbor);
+                }
+            }
+        }
+        return order.map((id) => ({
+            node: nodeById.get(id),
+        }));
+    }
+    async restoreNodeWithCompensation(entry, rigId, snapshotId, data, opts, warnings) {
+        const node = entry.node;
+        const nodeId = node.id;
+        // Consult live continuity state BEFORE clearing stale state
+        if (node.podId) {
+            const continuityRow = this.db.prepare("SELECT status FROM continuity_state WHERE pod_id = ? AND node_id = ?").get(node.podId, nodeId);
+            if (continuityRow) {
+                if (continuityRow.status === "restoring") {
+                    warnings?.push(`Node ${node.logicalId}: continuity state is 'restoring', skipping`);
+                    return { nodeId, logicalId: node.logicalId, status: "fresh" };
+                }
+                if (continuityRow.status === "degraded") {
+                    warnings?.push(`Node ${node.logicalId}: continuity state is 'degraded', proceeding with caution`);
+                }
+            }
+        }
+        // OPR.0.3.4.2 (A) + OPR.0.4.3.20 FR-7 — PRE-LAUNCH stop-and-ask classification,
+        // BEFORE clearStaleState / launchNode, so `awaiting-decision` means ZERO session
+        // started and prior state is untouched.
+        //
+        // FR-7 (Gap 1): a `resume_if_possible` seat that HAD a session (a snapshot
+        // session row exists) but has NO usable token stops here — whether or not a
+        // resume SOURCE was recorded. The old scope required a recorded source, so a
+        // crashed seat with a session row but no captured token silently fresh-primed
+        // (identity-replaced while looking healthy). A node with NO session row at all
+        // never ran / has nothing to resume → it legitimately fresh-primes (falls
+        // through). The ONLY default fresh-prime is now: no prior session, a genuinely
+        // non-resume policy (relaunch_fresh / checkpoint_only), or explicit `--fresh`.
+        {
+            const snapSessions = data.sessions.filter((s) => s.nodeId === nodeId);
+            const snapSession = snapSessions.length > 0
+                ? snapSessions.reduce((latest, s) => s.id > latest.id ? s : latest)
+                : null;
+            const policy = snapSession?.restorePolicy ?? "resume_if_possible";
+            const freshRequested = opts?.freshLogicalIds?.includes(node.logicalId) ?? false;
+            const resumeSourceRecorded = !!snapSession?.resumeType && snapSession.resumeType !== "none";
+            if (policy === "resume_if_possible" && snapSession && !snapSession.resumeToken && !freshRequested) {
+                const sourceNote = resumeSourceRecorded
+                    ? `resume source '${snapSession?.resumeType}' recorded but no token available`
+                    : `no resume token was captured for this seat`;
+                return {
+                    nodeId,
+                    logicalId: node.logicalId,
+                    status: "awaiting-decision",
+                    error: `Original session unresumable: ${sourceNote}. No session was started. Re-run with --fresh ${node.logicalId} to deliberately start a fresh-primed seat, or restore the original session manually.`,
+                };
+            }
+        }
+        // Capture prior state for compensation
+        const priorState = this.captureNodeState(nodeId, rigId);
+        // Clear stale state so NodeLauncher doesn't see already_bound
+        this.clearStaleState(nodeId, rigId);
+        // Derive canonical session name for pod-aware nodes
+        const rig = this.rigRepo.getRig(rigId);
+        let launchOpts = node.cwd
+            ? { cwd: node.cwd }
+            : undefined;
+        let expectedSessionName;
+        // OPR.0.4.3.20 FR-5 — pin the resume target to the DURABLY-BOUND session.
+        // priorState.binding was captured (above) BEFORE clearStaleState deleted the
+        // binding row, so it is the ONLY surviving copy of the name the seat was
+        // ACTUALLY bound to. Pinning it means a rename/reshape between the binding
+        // and the crash does not silently retarget resume to a re-derived
+        // (wrong/nonexistent) pane — the Class-1 fragility. Setting
+        // launchOpts.sessionName (not just expectedSessionName) is required:
+        // otherwise the launcher re-derives (node-launcher.ts) and writes the
+        // derived name back to the binding, defeating the pin. Selection-only — no
+        // identity re-key, no schema/derive-helper change. Fallback to the existing
+        // derive (below) is observable, never a silent divergence.
+        const pinnedTarget = priorState.binding?.tmuxSession ?? null;
+        let pinnedTargetUsed = false;
+        if (pinnedTarget) {
+            const { validateSessionName } = await import("./session-name.js");
+            if (validateSessionName(pinnedTarget)) {
+                expectedSessionName = pinnedTarget;
+                launchOpts = { ...launchOpts, sessionName: expectedSessionName };
+                pinnedTargetUsed = true;
+            }
+            else {
+                // Binding present but the bound name is malformed → observable fallback.
+                warnings?.push(`FR-5: durably-bound session name "${pinnedTarget}" for ${node.logicalId} is invalid; falling back to a derived name.`);
+            }
+        }
+        else {
+            // No durably-bound session name (old data / null binding or empty
+            // tmux_session) → observable derived-name fallback (PRD back-compat AC).
+            warnings?.push(`FR-5: no durably-bound session name for ${node.logicalId}; falling back to a derived session name.`);
+        }
+        // Derived-name FALLBACK — only when no usable pin. The existing derive,
+        // unchanged (pod-aware then legacy); preserves back-compat for partial-data rigs.
+        if (!pinnedTargetUsed) {
+            if (node.podId && rig) {
+                // Pod-aware: derive {pod}-{member}@{rigName} from node identity
+                const parts = node.logicalId.split(".");
+                if (parts.length >= 2) {
+                    const podPart = parts[0];
+                    const memberPart = parts.slice(1).join(".");
+                    const { deriveCanonicalSessionName, deriveSessionName } = await import("./session-name.js");
+                    expectedSessionName = deriveCanonicalSessionName(podPart, memberPart, rig.rig.name);
+                    launchOpts = { ...launchOpts, sessionName: expectedSessionName };
+                }
+            }
+            if (!expectedSessionName && rig) {
+                const { deriveSessionName } = await import("./session-name.js");
+                expectedSessionName = deriveSessionName(rig.rig.name, node.logicalId);
+            }
+        }
+        // Write transcript boundary marker BEFORE launch (before pipe-pane attaches)
+        // so the marker appears before any post-restore terminal output.
+        // Uses "restore attempt" language — honest even if launch subsequently fails.
+        if (this.transcriptStore?.enabled && rig && expectedSessionName) {
+            const markerOk = this.transcriptStore.writeBoundaryMarker(rig.rig.name, expectedSessionName, `restore attempt from snapshot ${snapshotId}`);
+            if (!markerOk) {
+                warnings?.push(`Transcript boundary marker failed for ${expectedSessionName}`);
+            }
+        }
+        // Attempt launch — compensate ONLY if launch itself fails
+        const launchResult = await this.nodeLauncher.launchNode(rigId, node.logicalId, launchOpts);
+        if (!launchResult.ok) {
+            // Launch failed — restore prior state (compensating action)
+            this.restoreNodeState(nodeId, priorState);
+            return {
+                nodeId,
+                logicalId: node.logicalId,
+                status: "failed",
+                error: launchResult.message,
+            };
+        }
+        // Launch succeeded — do NOT compensate on post-launch failures
+        // (the new session/binding are now the current state)
+        // Propagate launch warnings (includes transcript attach failures)
+        if (launchResult.warnings?.length) {
+            warnings?.push(...launchResult.warnings);
+        }
+        return this.postLaunchRestore(entry, rigId, data, launchResult.sessionName, launchResult, opts, warnings, priorState);
+    }
+    /** OPR.0.3.4.2 (B) — roll a just-launched session back to ZERO sessions for
+     *  the awaiting-decision outcome: kill the live blank session, mark its row
+     *  superseded, and restore the prior binding/session state (the existing
+     *  launch-failure compensating action). The caller fires this ONLY on a
+     *  POSITIVE determination the session is fresh/blank — never for
+     *  unknown-but-possibly-valid continuity. */
+    async rollbackToZeroSession(nodeId, sessionName, launchedSessionId, priorState) {
+        try {
+            await this.tmuxAdapter.killSession(sessionName);
+        }
+        catch { /* best-effort — the row + projection rollback below is the source of truth */ }
+        if (launchedSessionId) {
+            try {
+                this.sessionRegistry.updateStatus(launchedSessionId, "superseded");
+            }
+            catch { /* best-effort */ }
+        }
+        if (priorState) {
+            this.restoreNodeState(nodeId, priorState);
+        }
+    }
+    async postLaunchRestore(entry, rigId, data, sessionName, launchResult, opts, warnings, priorState) {
+        const node = entry.node;
+        // Find the NEWEST session for this node. ULIDs are monotonic, so latest = max id.
+        const nodeSessions = data.sessions.filter((s) => s.nodeId === node.id);
+        const session = nodeSessions.length > 0
+            ? nodeSessions.reduce((latest, s) => s.id > latest.id ? s : latest)
+            : null;
+        const checkpoint = data.checkpoints[node.id] ?? null;
+        // Check restore policy. OPR.0.3.4.2: a --fresh-listed seat (operation B)
+        // deliberately skips the resume attempt; its launch reports `fresh-primed`.
+        const restorePolicy = session?.restorePolicy ?? "resume_if_possible";
+        const resumeType = session?.resumeType ?? null;
+        const resumeToken = session?.resumeToken ?? null;
+        const freshRequested = opts?.freshLogicalIds?.includes(node.logicalId) ?? false;
+        const resumeRequested = restorePolicy === "resume_if_possible" && !!resumeType && resumeType !== "none" && !freshRequested;
+        // OPR.0.3.4.2 — non-resume launches are DELIBERATE blank-slate launches
+        // (policy- or --fresh-driven): named `fresh-primed`, the old conflated
+        // `fresh` no longer flows from this pipeline.
+        let baseStatus = "fresh-primed";
+        // Pod-aware nodes: resume via launchHarness (handled in startup orchestrator with skipHarnessLaunch: false)
+        // Legacy nodes: resume via old claude-resume/codex-resume helpers
+        const isPodAware = !!node.podId;
+        if (resumeRequested && !isPodAware) {
+            // Legacy resume path
+            if (!resumeToken) {
+                // Defense in depth: the pre-launch classification catches this case
+                // before any session exists. If it is somehow reached post-launch, the
+                // just-created session is a confirmed blank (no resume was possible) —
+                // roll back to zero sessions and present the decision honestly.
+                await this.rollbackToZeroSession(node.id, sessionName, launchResult?.session.id, priorState);
+                return { nodeId: node.id, logicalId: node.logicalId, status: "awaiting-decision", error: `Original session unresumable: resume requested but no token available. No session is running. Re-run with --fresh ${node.logicalId} for a deliberate fresh-primed seat, or restore the original session manually.` };
+            }
+            else {
+                const resumeOutcome = await this.attemptResume(node.id, sessionName, resumeType, resumeToken, node.cwd ?? "/", node.codexConfigProfile, node.model, this.resolveRestorePosture(node.id, rigId));
+                if (resumeOutcome.kind === "resumed") {
+                    baseStatus = "resumed";
+                }
+                else if (resumeOutcome.kind === "attention_required") {
+                    // L3 Decision 2: Claude resume-selection prompt -> attention_required.
+                    // Do NOT auto-answer. Reconcile later via reconcileNodeRuntimeTruth
+                    // when the operator reaches a usable pane state. (Boundary: a LIVE
+                    // parked session is attention_required, NEVER awaiting-decision.)
+                    return {
+                        nodeId: node.id,
+                        logicalId: node.logicalId,
+                        status: "attention_required",
+                        error: resumeOutcome.message,
+                        attentionEvidence: resumeOutcome.evidence ?? null,
+                    };
+                }
+                else {
+                    // OPR.0.3.4.2 (B): resume CONCLUDED failed — the launched session is
+                    // a confirmed blank agent (precision guard trigger (i)). Roll back to
+                    // zero sessions; the stop-and-ask is realized as awaiting-decision.
+                    await this.rollbackToZeroSession(node.id, sessionName, launchResult?.session.id, priorState);
+                    return { nodeId: node.id, logicalId: node.logicalId, status: "awaiting-decision", error: `Original session unresumable: resume attempted but failed. The blank session was rolled back; no session is running. Re-run with --fresh ${node.logicalId} for a deliberate fresh-primed seat, or check the harness state manually.` };
+                }
+            }
+        }
+        else if (resumeRequested && isPodAware) {
+            // Pod-aware restore must preserve the same honesty contract as legacy restore:
+            // if resume was requested but continuity state is unavailable, stop loudly
+            // instead of silently downgrading to a fresh launch with amnesia.
+            if (!resumeToken) {
+                // Defense in depth (pre-launch classification catches this first).
+                await this.rollbackToZeroSession(node.id, sessionName, launchResult?.session.id, priorState);
+                return {
+                    nodeId: node.id,
+                    logicalId: node.logicalId,
+                    status: "awaiting-decision",
+                    error: `Original session unresumable: resume requested but no token available. No session is running. Re-run with --fresh ${node.logicalId} for a deliberate fresh-primed seat, or restore the original session manually.`,
+                };
+            }
+            // OPR.0.4.3.20 FR-7 (Gap 2b) — a pod-aware resume needs the runtime adapter
+            // to verify continuity + relaunch the harness (the startup replay below is
+            // gated on opts.adapters). If the adapter for this seat's runtime is absent
+            // (e.g. a node-subset launch that did not thread adapters), we CANNOT resume
+            // and MUST NOT silently fresh-prime — fail closed to awaiting-decision.
+            // Explicit --fresh and non-resume policies stay the only fresh-prime paths.
+            const resumeAdapter = node.runtime ? opts?.adapters?.[node.runtime] : undefined;
+            if (!resumeAdapter) {
+                await this.rollbackToZeroSession(node.id, sessionName, launchResult?.session.id, priorState);
+                return {
+                    nodeId: node.id,
+                    logicalId: node.logicalId,
+                    status: "awaiting-decision",
+                    error: `Original session unresumable: resume requested but runtime continuity could not be verified (no ${node.runtime ?? "runtime"} adapter available). No session is running. Re-run with --fresh ${node.logicalId} for a deliberate fresh-primed seat, or retry restore with runtime adapters.`,
+                };
+            }
+        }
+        // Checkpoint delivery (if not already resumed)
+        if (baseStatus !== "resumed" && checkpoint) {
+            if (!node.cwd) {
+                return { nodeId: node.id, logicalId: node.logicalId, status: "failed", error: "Checkpoint available but node has no cwd" };
+            }
+            const written = this.writeCheckpointFile(node.cwd, checkpoint);
+            if (written) {
+                baseStatus = "rebuilt";
+            }
+            else {
+                return { nodeId: node.id, logicalId: node.logicalId, status: "failed", error: "Checkpoint file write failed" };
+            }
+        }
+        // Attempt restore-safe startup replay if context available
+        if (data.nodeStartupContext && opts?.adapters && launchResult) {
+            const startupCtx = data.nodeStartupContext[node.id];
+            if (startupCtx) {
+                const adapter = opts.adapters[startupCtx.runtime];
+                if (adapter) {
+                    // Prefilter: check which files/entries still exist
+                    const existsFn = opts.fsOps?.exists ?? (() => true);
+                    const filteredEntries = startupCtx.projectionEntries.filter((e) => {
+                        if (!existsFn(e.absolutePath)) {
+                            warnings?.push(`Restore: missing projection entry ${e.absolutePath} (skipped)`);
+                            return false;
+                        }
+                        return true;
+                    });
+                    const filteredFiles = startupCtx.resolvedStartupFiles.filter((f) => {
+                        if (!existsFn(f.absolutePath)) {
+                            if (f.required) {
+                                warnings?.push(`Restore: missing REQUIRED startup file ${f.absolutePath}`);
+                                return false; // will cause failure below
+                            }
+                            warnings?.push(`Restore: missing optional startup file ${f.absolutePath} (skipped)`);
+                            return false;
+                        }
+                        return true;
+                    });
+                    // Check if any required files were dropped
+                    const missingRequired = startupCtx.resolvedStartupFiles.filter((f) => f.required && !existsFn(f.absolutePath));
+                    if (missingRequired.length > 0) {
+                        return { nodeId: node.id, logicalId: node.logicalId, status: "failed", error: `Missing required startup files: ${missingRequired.map((f) => f.path).join(", ")}` };
+                    }
+                    // Build fresh projection plan (all safe_projection)
+                    const plan = {
+                        runtime: startupCtx.runtime,
+                        cwd: node.cwd ?? ".",
+                        entries: filteredEntries.map((e) => ({
+                            ...e,
+                            classification: "safe_projection",
+                            category: e.category,
+                            mergeStrategy: e.mergeStrategy,
+                        })),
+                        startup: { files: filteredFiles, actions: startupCtx.startupActions },
+                        conflicts: [],
+                        noOps: [],
+                        diagnostics: [],
+                    };
+                    const binding = {
+                        ...launchResult.binding,
+                        cwd: node.cwd ?? ".",
+                        codexConfigProfile: node.codexConfigProfile ?? undefined,
+                        // OPR.0.4.8.3 Seam B: the pod-aware restore path binds the restored posture too
+                        // (both restore paths consume persisted provenance — preflight surface 3).
+                        launchPosture: this.resolveRestorePosture(node.id, rigId),
+                        // OPR.0.4.6.PI1 VM leg finding: the restore binding dropped the
+                        // node's model declaration, so a resumed Pi seat relaunched with
+                        // no --model — and the runner's provider-key allowlist (keyed off
+                        // the declared provider) passed nothing through ("No API key
+                        // found" on every resumed Pi seat). Claude/Codex silently lost
+                        // their -m/--model on restore the same way.
+                        model: node.model ?? undefined,
+                    };
+                    try {
+                        const { StartupOrchestrator } = await import("./startup-orchestrator.js");
+                        const startupOrch = new StartupOrchestrator({ db: this.db, sessionRegistry: this.sessionRegistry, eventBus: this.eventBus, tmuxAdapter: this.tmuxAdapter });
+                        const replayAsRestore = baseStatus !== "fresh-primed";
+                        const shouldLaunchHarness = isPodAware;
+                        const startupResult = await startupOrch.startNode({
+                            rigId,
+                            nodeId: node.id,
+                            sessionId: launchResult.session.id,
+                            binding: binding,
+                            adapter,
+                            plan,
+                            resolvedStartupFiles: filteredFiles,
+                            startupActions: startupCtx.startupActions,
+                            isRestore: replayAsRestore,
+                            skipHarnessLaunch: !shouldLaunchHarness,
+                            resumeToken: (isPodAware && resumeRequested) ? resumeToken ?? undefined : undefined,
+                            sessionName: sessionName,
+                            allowFreshFallback: !(isPodAware && resumeRequested),
+                        });
+                        if (startupResult.ok) {
+                            const nativeContinuityProved = isPodAware
+                                && resumeRequested
+                                && this.launchedSessionMatchesSnapshotResume(launchResult.session.id, resumeType, resumeToken);
+                            if (isPodAware && resumeRequested && startupResult.continuityOutcome === "fresh" && !nativeContinuityProved) {
+                                // OPR.0.3.4.2 (B): the runtime POSITIVELY reported fresh
+                                // continuity and native continuity is unproven — a confirmed
+                                // blank agent (precision guard trigger (ii)). Roll back to
+                                // zero sessions and present the decision. NOTE: this fires
+                                // ONLY on the concluded-fresh determination; a genuinely
+                                // unknown-but-possibly-valid continuity never reaches here
+                                // (continuityOutcome would not be "fresh").
+                                await this.rollbackToZeroSession(node.id, sessionName, launchResult.session.id, priorState);
+                                return {
+                                    nodeId: node.id,
+                                    logicalId: node.logicalId,
+                                    status: "awaiting-decision",
+                                    error: `Original session unresumable: resume attempted but the runtime reported fresh continuity. The blank session was rolled back; no session is running. Re-run with --fresh ${node.logicalId} if that degradation is acceptable.`,
+                                };
+                            }
+                            const finalStatus = (isPodAware && resumeRequested)
+                                ? ((startupResult.continuityOutcome === "resumed" || nativeContinuityProved) ? "resumed" : baseStatus)
+                                : baseStatus;
+                            return { nodeId: node.id, logicalId: node.logicalId, status: finalStatus };
+                        }
+                        // Pod-aware attention_required: hoisted above both the
+                        // resume-requested and non-resume-requested failed branches so
+                        // that pod-aware Codex auth-refusal (verifyResumeLaunch →
+                        // recovery: "attention_required") surfaces honestly regardless
+                        // of whether resume was requested. Mirrors the runtime-agnostic
+                        // legacy mapping at lines 725-735. This MUST come before the
+                        // line 859 / 867 failed branches; otherwise the production
+                        // pod-aware-resume path (most common) returns `status: "failed"`
+                        // and the slice's "attention_required end-to-end" claim breaks.
+                        if (isPodAware && startupResult.startupStatus === "attention_required") {
+                            return {
+                                nodeId: node.id,
+                                logicalId: node.logicalId,
+                                status: "attention_required",
+                                error: `Restore startup requires attention: ${startupResult.errors.join("; ")}`,
+                                attentionEvidence: startupResult.evidence ?? null,
+                            };
+                        }
+                        if (isPodAware && resumeRequested) {
+                            return {
+                                nodeId: node.id,
+                                logicalId: node.logicalId,
+                                status: "failed",
+                                error: startupResult.errors.join("; "),
+                            };
+                        }
+                        if (isPodAware) {
+                            const prefix = startupResult.startupStatus === "attention_required"
+                                ? "Restore startup requires attention"
+                                : "Restore startup failed";
+                            return {
+                                nodeId: node.id,
+                                logicalId: node.logicalId,
+                                status: "failed",
+                                error: `${prefix}: ${startupResult.errors.join("; ")}`,
+                            };
+                        }
+                        warnings?.push(`Restore startup failed for ${node.logicalId}: ${startupResult.errors.join("; ")}`);
+                    }
+                    catch (err) {
+                        if (isPodAware && resumeRequested) {
+                            return {
+                                nodeId: node.id,
+                                logicalId: node.logicalId,
+                                status: "failed",
+                                error: `Restore startup error: ${err.message}`,
+                            };
+                        }
+                        if (isPodAware) {
+                            return {
+                                nodeId: node.id,
+                                logicalId: node.logicalId,
+                                status: "failed",
+                                error: `Restore startup error: ${err.message}`,
+                            };
+                        }
+                        warnings?.push(`Restore startup error for ${node.logicalId}: ${err.message}`);
+                    }
+                }
+            }
+        }
+        return { nodeId: node.id, logicalId: node.logicalId, status: baseStatus };
+    }
+    launchedSessionMatchesSnapshotResume(sessionId, resumeType, resumeToken) {
+        if (!resumeType || !resumeToken)
+            return false;
+        const row = this.db.prepare("SELECT resume_type, resume_token FROM sessions WHERE id = ?").get(sessionId);
+        if (!row?.resume_type || !row.resume_token)
+            return false;
+        return row.resume_type === resumeType && row.resume_token === resumeToken;
+    }
+    /**
+     * OPR.0.4.8.3 Seam B — a restored seat's launch posture WITHOUT the in-memory RigSpec
+     * (dev-guard restart-provenance ruling):
+     *   1. Persisted node provenance (migration 057) is the primary source. For a CUSTOM
+     *      attachment with readable provenance (declaringDir + the node's raw ref) the policy
+     *      is REOPENED + re-derived (a custom surface:flag policy restores to full_bypass);
+     *      an unreadable file degrades to the PERSISTED posture (still restart-stable).
+     *   2. No provenance (e.g. organic claim/self-attach seats): the persisted RIG-level ref
+     *      resolves — builtin refs resolve dirlessly; a custom rig ref without provenance
+     *      degrades to the resolver's advisory floor (honest absence of a declaring dir).
+     *   3. Nothing attached (or a resolution error) → EXPLICIT "floor" — the locked
+     *      minimum-floor absence contract; never undefined/env-delegation for managed seats.
+     */
+    resolveRestorePosture(nodeId, rigId) {
+        try {
+            const prov = this.rigRepo.getNodePolicyProvenance(nodeId);
+            if (prov) {
+                // Guard-F3: the resolver swallows read errors internally (advisory floor), so the
+                // fallback must be decided BEFORE re-resolution: probe readability of the persisted
+                // resolvedTarget first — readable → REOPEN + re-derive (the ruling); unreadable /
+                // invalid → the PERSISTED posture carries (restart-stable), never a silent floor.
+                if (prov.origin === "custom" && prov.declaringDir && prov.resolvedTarget) {
+                    const ref = prov.nodeRef ?? this.rigRepo.getRigPermissionPolicy(rigId);
+                    if (ref) {
+                        let content = null;
+                        try {
+                            content = readFileSync(prov.resolvedTarget, "utf-8");
+                        }
+                        catch {
+                            content = null;
+                        }
+                        if (content !== null) {
+                            const body = content;
+                            const rederived = resolvePermissionPolicyAttachment(ref, prov.declaringDir, {
+                                readFile: () => body,
+                            });
+                            // Guard round-2: trust the re-derivation ONLY when content resolution
+                            // genuinely succeeded with usable semantics (parse OK + valid flag
+                            // contract) — readable-but-malformed/unusable carries the PERSISTED
+                            // posture, exactly like unreadable. Advisory only; no enforcement.
+                            if (rederived.contentResolved)
+                                return rederived.launchPosture;
+                        }
+                    }
+                }
+                return prov.launchPosture;
+            }
+            // Guard-F1: no node provenance (organic claim/self-attach seats) → the PERSISTED
+            // rig-level attachment is authoritative — same readable-probe discipline; NEVER
+            // resolve the raw relative rig ref against this process's cwd.
+            const rigProv = this.rigRepo.getRigPolicyProvenance(rigId);
+            if (rigProv) {
+                if (rigProv.origin === "custom" && rigProv.declaringDir && rigProv.resolvedTarget && rigProv.rigRef) {
+                    let content = null;
+                    try {
+                        content = readFileSync(rigProv.resolvedTarget, "utf-8");
+                    }
+                    catch {
+                        content = null;
+                    }
+                    if (content !== null) {
+                        const body = content;
+                        const rederived = resolvePermissionPolicyAttachment(rigProv.rigRef, rigProv.declaringDir, {
+                            readFile: () => body,
+                        });
+                        if (rederived.contentResolved)
+                            return rederived.launchPosture; // same rule as node-level
+                    }
+                }
+                return rigProv.launchPosture;
+            }
+        }
+        catch { /* posture resolution must never block a restore */ }
+        // R2 terminal (954d97a0): NO provenance anywhere (and the error path) = the locked
+        // minimum floor, explicitly — never undefined (which would delegate to ambient YOLO).
+        return "floor";
+    }
+    async attemptResume(nodeId, sessionName, resumeType, resumeToken, cwd, codexConfigProfile, model, 
+    // OPR.0.4.8.3 Seam B: the seat's restored launch posture (persisted provenance,
+    // custom policies re-validated when readable). Absent = env decision.
+    resolvedPosture) {
+        const launchGeneration = this.sessionRegistry.currentOccupantTenure(nodeId)?.generationUuid;
+        if (this.claudeResume.canResume(resumeType, resumeToken)) {
+            const result = await this.claudeResume.resume(sessionName, resumeType, resumeToken, cwd, resolvedPosture, model);
+            if (result.ok) {
+                if (result.appliedLaunch && launchGeneration)
+                    this.appliedLaunchStore.recordGeneration(launchGeneration, result.appliedLaunch);
+                return { kind: "resumed" };
+            }
+            if (result.code === "retry_fresh")
+                return { kind: "retry_fresh" };
+            // L3: surface attention_required from the Claude probe (resume-selection prompt).
+            if (result.code === "attention_required") {
+                return {
+                    kind: "attention_required",
+                    message: result.message,
+                    evidence: result.evidence,
+                };
+            }
+            return { kind: "failed", message: result.message };
+        }
+        if (this.codexResume.canResume(resumeType, resumeToken)) {
+            const result = await this.codexResume.resume(sessionName, resumeType, resumeToken, cwd, codexConfigProfile, resolvedPosture, model);
+            if (result.ok) {
+                if (result.appliedLaunch && launchGeneration)
+                    this.appliedLaunchStore.recordGeneration(launchGeneration, result.appliedLaunch);
+                return { kind: "resumed" };
+            }
+            if (result.code === "retry_fresh")
+                return { kind: "retry_fresh" };
+            // Codex auth-refusal: stored OAuth token can no longer be refreshed.
+            // Recoverable — operator runs `codex login` and the seat continues.
+            // Per-node mapping at lines 725-735 emits `status: "attention_required"`
+            // with `attentionEvidence` for both runtimes; no further wiring needed.
+            if (result.code === "attention_required") {
+                return {
+                    kind: "attention_required",
+                    message: result.message,
+                    evidence: result.evidence,
+                };
+            }
+            return { kind: "failed", message: result.message };
+        }
+        // OPR.0.4.6.PI1 FR-6 — honest session-file continuation. A missing
+        // session file returns retry_fresh, which the caller maps to the
+        // awaiting-decision stop-and-ask — never a silent fresh start (BR-6).
+        if (this.piResume?.canResume(resumeType, resumeToken)) {
+            const result = await this.piResume.resume(sessionName, resumeType, resumeToken, cwd, model, resolvedPosture);
+            if (result.ok) {
+                if (result.appliedLaunch && launchGeneration)
+                    this.appliedLaunchStore.recordGeneration(launchGeneration, result.appliedLaunch);
+                return { kind: "resumed" };
+            }
+            if (result.code === "retry_fresh")
+                return { kind: "retry_fresh" };
+            if (result.code === "attention_required") {
+                return {
+                    kind: "attention_required",
+                    message: result.message,
+                    evidence: result.evidence,
+                };
+            }
+            return { kind: "failed", message: result.message };
+        }
+        return { kind: "failed", message: "No resume adapter available for this runtime/token combination." };
+    }
+    /**
+     * L3 Decision 3: runtime-truth reconciliation. Given a node whose original
+     * `restoreOutcome` was `failed` or `attention_required`, examine current
+     * runtime state. If ALL four visible-evidence preconditions hold, append
+     * `restore.outcome_reconciled` so the node's effective post-reconciliation
+     * outcome becomes `operator_recovered`. Never mutates or deletes the
+     * original failure event; never produces `ready`.
+     *
+     * Returns `{ ok: true, attemptId, from, to, evidence }` on upgrade, or
+     * `{ ok: false, code, detail }` describing exactly which precondition
+     * failed (or "no_attempt" / "outcome_not_upgradable" when there is nothing
+     * to reconcile).
+     */
+    async reconcileNodeRuntimeTruth(rigId, nodeId) {
+        // Locate the latest restore attempt for this rig.
+        const startedRow = this.db.prepare("SELECT seq, payload FROM events WHERE rig_id = ? AND type = 'restore.started' ORDER BY seq DESC LIMIT 1").get(rigId);
+        if (!startedRow) {
+            return { ok: false, code: "no_attempt", detail: "No restore.started event recorded for this rig." };
+        }
+        const attemptId = startedRow.seq;
+        // Find the node's most recent post-attempt outcome from the most-recent
+        // restore.completed event for this rig. If the latest outcome is not
+        // failed or attention_required, the reconciler has nothing to upgrade.
+        const completedRow = this.db.prepare("SELECT payload FROM events WHERE rig_id = ? AND type = 'restore.completed' AND seq > ? ORDER BY seq DESC LIMIT 1").get(rigId, attemptId);
+        let nodeStatus = null;
+        let nodeLogicalId = null;
+        if (completedRow) {
+            try {
+                const parsed = JSON.parse(completedRow.payload);
+                const found = parsed.result?.nodes?.find((n) => n.nodeId === nodeId);
+                if (found) {
+                    nodeStatus = found.status;
+                    nodeLogicalId = found.logicalId;
+                }
+            }
+            catch {
+                // payload corruption — treat as no node record found
+            }
+        }
+        if (!nodeStatus) {
+            return { ok: false, code: "node_not_found", detail: `Node ${nodeId} has no record in the latest restore.completed event for rig ${rigId}.` };
+        }
+        if (nodeStatus !== "failed" && nodeStatus !== "attention_required") {
+            return { ok: false, code: "outcome_not_upgradable", detail: `Reconciliation only upgrades failed or attention_required; current outcome is ${nodeStatus}.` };
+        }
+        const fromStatus = nodeStatus;
+        // Resolve canonical session name for this node so we can probe tmux/pane.
+        const bindingRow = this.db.prepare("SELECT tmux_session FROM bindings WHERE node_id = ?").get(nodeId);
+        const sessionName = bindingRow?.tmux_session ?? null;
+        if (!sessionName) {
+            return { ok: false, code: "tmux_session_missing", detail: "No tmux session bound for this node." };
+        }
+        // Precondition #1: tmux session exists.
+        let alive = false;
+        try {
+            alive = await this.tmuxAdapter.hasSession(sessionName);
+        }
+        catch {
+            // L1 fail-closed: ambiguous probe failure stays as not-alive for the
+            // reconciler. Original failure event remains untouched.
+            alive = false;
+        }
+        if (!alive) {
+            return { ok: false, code: "tmux_session_missing", detail: `Tmux session ${sessionName} is not currently alive.` };
+        }
+        // Resolve runtime + capture pane state for preconditions #2 and #4.
+        const nodeRow = this.db.prepare("SELECT runtime FROM nodes WHERE id = ?").get(nodeId);
+        const runtime = nodeRow?.runtime ?? null;
+        const paneCommand = await this.tmuxAdapter.getPaneCommand(sessionName);
+        const paneContent = (await this.tmuxAdapter.capturePaneContent(sessionName, 40)) ?? "";
+        // Precondition #2: foreground process is the runtime (claude or codex).
+        const probe = assessNativeResumeProbe({ runtime, paneCommand, paneContent });
+        const fgProcess = paneCommand && (paneCommand === "claude" || paneCommand.startsWith("codex"))
+            ? (paneCommand === "claude" ? "claude" : "codex")
+            : null;
+        if (!fgProcess) {
+            return { ok: false, code: "fg_process_not_runtime", detail: `Foreground process is "${paneCommand ?? "(unknown)"}", not claude/codex.` };
+        }
+        // Precondition #3: the resume token was actually used at launch.
+        // Stored on the latest session row; null/empty means resume was not
+        // exercised so a "recovered" claim has no basis.
+        const sessRow = this.db.prepare("SELECT resume_token FROM sessions WHERE node_id = ? ORDER BY id DESC LIMIT 1").get(nodeId);
+        const resumeTokenUsed = typeof sessRow?.resume_token === "string" && sessRow.resume_token.length > 0;
+        if (!resumeTokenUsed) {
+            return { ok: false, code: "resume_token_not_used", detail: "No resume token recorded on the latest session row." };
+        }
+        // Precondition #4: pane is at a usable/idle state — explicitly NOT a
+        // resume-selection prompt and not the "returned to shell" failure mode.
+        if (probe.status !== "resumed") {
+            return { ok: false, code: "pane_not_usable", detail: `Pane state is ${probe.status} (${probe.code}); reconciliation requires resumed.` };
+        }
+        // All four preconditions hold. Append (never mutate) the audit event.
+        this.eventBus.emit({
+            type: "restore.outcome_reconciled",
+            rigId,
+            nodeId,
+            attemptId,
+            from: fromStatus,
+            to: "operator_recovered",
+            evidence: { tmux: true, fgProcess, resumeTokenUsed: true, paneState: "usable" },
+        });
+        return {
+            ok: true,
+            attemptId,
+            from: fromStatus,
+            to: "operator_recovered",
+            evidence: { tmux: true, fgProcess, resumeTokenUsed: true, paneState: "usable" },
+        };
+    }
+    writeCheckpointFile(cwd, checkpoint) {
+        try {
+            const filePath = join(cwd, ".rigged-checkpoint.md");
+            const content = [
+                "# OpenRig Checkpoint",
+                "",
+                `## Summary`,
+                checkpoint.summary,
+                "",
+                checkpoint.currentTask ? `## Current Task\n${checkpoint.currentTask}\n` : "",
+                checkpoint.nextStep ? `## Next Step\n${checkpoint.nextStep}\n` : "",
+                checkpoint.blockedOn ? `## Blocked On\n${checkpoint.blockedOn}\n` : "",
+                checkpoint.keyArtifacts.length > 0
+                    ? `## Key Artifacts\n${checkpoint.keyArtifacts.map((a) => `- ${a}`).join("\n")}\n`
+                    : "",
+            ]
+                .filter(Boolean)
+                .join("\n");
+            writeFileSync(filePath, content, "utf-8");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=restore-orchestrator.js.map