@openrig/cli 0.6.14 → 0.7.1

package/daemon/dist/domain/restore-orchestrator.js

@@ -1,15 +1,23 @@
+import { observeSolePane } from "./pane-binding-observation.js";
+import { automaticRestoreOverrides } from "./existing-rig-restore.js";
 import { restoreRuntimeCompatibilityError } from "./restore-runtime-compatibility.js";
+import { leftAttachedReason } from "./restore-plan-preview.js";
+import { assessSnapshotCurrentOccupants, stoppedSnapshotReason } from "./rehydrate-eligibility.js";
 import { nonInterruptiveNotice, nonInterruptiveSummary } from "../adapters/non-interruptive.js";
 import { effortPrecedence, readSeatEffort } from "./seat-effort.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { ensureSeatSkillPlugin, hasSeatSkillRecords, rehydrateSeatSkills, seatSkillPaths, seatSkillPathsForNode, seatCatalogKeptNote, seatSkillReplay, writeSeatSkillCatalog, writeSeatSkillRouter, seatRouterKeptNote } from "./seat-skill-storage.js";
 import { NativePermissionStore } from "./native-permission-store.js";
 import { resolvePermissionPolicyAttachment } from "./permission-policy/policy-ref.js";
 import { claudeResumeRotation } from "./session-registry.js";
 import { assessNativeResumeProbe } from "./native-resume-probe.js";
+import { resumeProbeEvidence } from "./native-resume-probe-evidence.js";
 import { observeClaudeDelivery, observeClaudeResumeLaunch, verifyClaudePaneProcess, verifyPaneIdleShell } from "./native-process-lineage.js";
 import { reanchorBuiltinStartupFile, reanchorShippedProjectionEntry } from "./builtin-startup-files.js";
-import { seatGuidance, restoreMissingGuidance, missingGuidanceBlocks } from "./restore-guidance.js";
+import { applySeatSkillsLineRule, seatGuidance, restoreMissingGuidance, missingGuidanceBlocks } from "./restore-guidance.js";
+import { readFootprintAnswer } from "./footprint-choice.js";
+import { SettingsStore } from "./user-settings/settings-store.js";
 import { AppliedLaunchObservationStore } from "./applied-launch-observation-store.js";
 import { classifyPaneRuntimeMatch } from "./seat-identity-reconciler.js";
 import { isShellForeground } from "./shell-classifier.js";
@@ -23,12 +31,16 @@ const LAUNCH_DEPENDENCY_KINDS = new Set(["delegates_to", "spawned_by"]);
 // in the pure leaf module active-occupant.ts, shared with preview, snapshot
 // usability, and lifecycle projection. Imported and re-exported here so the
 // existing export surface and the execution call sites below are unchanged.
-import { resolveActiveSnapshotSession, activeOccupantAmbiguityError, absentSeatResumeHistory, absentSeatResumeHistoryError } from "./active-occupant.js";
-import { effectiveRestorePolicy } from "./restore-policy.js";
+import { resolveActiveSnapshotSession, activeOccupantAmbiguityError, absentSeatResumeHistory, absentSeatResumeHistoryError, freshSeatLaunchCommand } from "./active-occupant.js";
+import { effectiveRestorePolicy, communityLaunchOnlyRestoreReason } from "./restore-policy.js";
 import { communityHarnessOf } from "./built-in-runtimes.js";
+import { communityHarnessStopsRestore } from "./community-harness-presets.js";
 import { seatAdapter } from "../adapters/community-harness-runtime-adapter.js";
 import { pluginPathsOf } from "./claude-core-plugin-env.js";
+import { seatLaunchAdditionsForLaunch, systemPromptPendingNoteForNode } from "./seat-launch-additions.js";
 export { resolveActiveSnapshotSession } from "./active-occupant.js";
+/** Pre-restore blockers that concern one seat's own startup content; see restore(). */
+const SEAT_STARTUP_BLOCKERS = new Set(["required_startup_file_missing", "startup_owner_root_missing"]);
 export function rollupRestoreRigResult(nodes) {
     if (nodes.length === 0)
         return "failed";
@@ -47,12 +59,14 @@ export function rollupRestoreRigResult(nodes) {
     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
+ *  the operator must act, or (`left_attached`) that nothing was launched in an external seat's place.
+ *  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",
+    "left_attached",
 ]);
 /** True when a restore/launch status means a session is actually running (a real
  *  successful launch): resumed / rebuilt / fresh / fresh-primed / operator_recovered. */
@@ -84,8 +98,9 @@ function snapshotLaunchOutcome(data, nodeId, runtime, savedRuntime) {
     const policy = effectiveRestorePolicy(seatFacts(data, nodeId, savedRuntime, runtime), session.restorePolicy);
     if (policy !== "resume_if_possible")
         return { kind: "fresh", why: `saves this seat with restore policy '${policy}'` };
-    if (communityHarnessOf(session.communityHarness, runtime))
-        return { kind: "decision", why: "is a community harness whose preset is launch-only (resume unsupported)" };
+    if (communityHarnessOf(session.communityHarness, runtime) && communityHarnessStopsRestore(runtime, session.resumeType, session.resumeToken)) {
+        return { kind: "decision", why: "is a community harness whose preset can't resume this seat's saved conversation (launch-only, or the id isn't this harness's own)" };
+    }
     if (!session.resumeToken)
         return { kind: "decision", why: "has no resume token for this seat" };
     if (!session.resumeType || session.resumeType === "none")
@@ -109,6 +124,7 @@ export class RestoreOrchestrator {
     transcriptStore;
     serviceOrchestrator;
     listProcesses;
+    routerLineSettings;
     appliedLaunchStore;
     constructor(deps) {
         if (deps.db !== deps.rigRepo.db) {
@@ -147,6 +163,7 @@ export class RestoreOrchestrator {
         this.transcriptStore = deps.transcriptStore ?? null;
         this.serviceOrchestrator = deps.serviceOrchestrator ?? null;
         this.listProcesses = deps.listProcesses;
+        this.routerLineSettings = deps.routerLineSettings;
         this.appliedLaunchStore = new AppliedLaunchObservationStore(deps.db);
     }
     async restore(snapshotId, opts) {
@@ -160,8 +177,28 @@ export class RestoreOrchestrator {
         if (!rig) {
             return { ok: false, code: "rig_not_found", message: `Rig ${rigId} not found` };
         }
+        if (!opts?.automatic && !opts?.automaticReplacements) {
+            const overrides = await automaticRestoreOverrides({ rigRepo: this.rigRepo, snapshotRepo: this.snapshotRepo }, rigId, opts);
+            if (overrides.refusal)
+                return { ok: false, code: "rig_not_stopped", message: overrides.refusal };
+            opts = { ...opts, automaticReplacements: overrides.replacements };
+        }
+        const replacements = opts?.automaticReplacements ?? [];
+        const selectedIds = new Set(replacements.map(target => target.nodeId));
+        // Only this invocation's resume input changes; historical snapshots remain immutable.
+        if (replacements.length) {
+            snapshot.data = structuredClone(snapshot.data);
+            snapshot.data.topologyRoster = { version: 1, source: "operator_explicit", intendedNodeIds: [...selectedIds] };
+            for (const target of replacements.filter(target => target.corrected)) {
+                const active = resolveActiveSnapshotSession(snapshot.data, target.nodeId);
+                if (active.kind !== "resolved")
+                    return { ok: false, code: "restore_error", message: "Corrected seat has no unambiguous snapshot occupant; nothing replaced." };
+                active.session.resumeType = target.resumeType;
+                active.session.resumeToken = target.resumeToken;
+            }
+        }
         const guard = this.tmuxAdapter.deliveryGuard;
-        const guardedIds = rig.nodes.map(node => node.id);
+        const guardedIds = rig.nodes.filter(node => !replacements.length || selectedIds.has(node.id)).map(node => node.id);
         if (guard && guardedIds.some(id => !guard.ownsLifecycle(id))) {
             return guard.lifecycle(guardedIds, () => this.restore(snapshotId, opts));
         }
@@ -173,8 +210,8 @@ export class RestoreOrchestrator {
         // 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) {
+        const classification = await this.classifyRunningSessions(rigId, replacements.length ? selectedIds : undefined);
+        if (classification.unknown.length > 0 || classification.live.some(id => !replacements.some(target => target.sessionId === id))) {
             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
@@ -190,7 +227,22 @@ export class RestoreOrchestrator {
                 currentRuntimes: Object.fromEntries((this.rigRepo.getRig(rigId)?.nodes ?? []).map((current) => [current.logicalId, current.runtime])),
             });
             const topology = resolveSnapshotRestoreTopology(snapshot.data);
-            if (validation.blockers.length > 0) {
+            // A required startup file that is missing holds only its own seat. That seat isn't launched, because it would start
+            // without its startup content; it's reported failed with the reason, and the rest of the rig restores. Any other
+            // blocker, or holds on every seat this restore would launch, still stops the whole restore before any mutation.
+            const heldForStartup = new Map();
+            for (const blocker of validation.blockers) {
+                if (!SEAT_STARTUP_BLOCKERS.has(blocker.code) || !blocker.nodeId)
+                    continue;
+                // A seat joined with `rig attach` as an external CLI isn't launched, so its startup files don't hold it.
+                if (this.sessionRegistry.getBindingForNode(blocker.nodeId)?.attachmentType === "external_cli")
+                    continue;
+                const reason = `${blocker.message} ${blocker.remediation}`;
+                heldForStartup.set(blocker.nodeId, heldForStartup.has(blocker.nodeId) ? `${heldForStartup.get(blocker.nodeId)} ${reason}` : reason);
+            }
+            const planIds = this.computeRestorePlan(snapshot.data).filter(entry => !replacements.length || selectedIds.has(entry.node.id)).map(entry => entry.node.id);
+            const rigWide = validation.blockers.some((blocker) => !SEAT_STARTUP_BLOCKERS.has(blocker.code) || !blocker.nodeId);
+            if (rigWide || planIds.every((id) => heldForStartup.has(id))) {
                 const result = {
                     snapshotId,
                     preRestoreSnapshotId: null,
@@ -238,7 +290,7 @@ export class RestoreOrchestrator {
                 // logic crash the restore pipeline.
             }
             // 3b. Service gate: boot services before agent restore if this rig has services
-            if (this.serviceOrchestrator) {
+            if (this.serviceOrchestrator && replacements.length === 0) {
                 const svcRecord = this.rigRepo.getServicesRecord(rigId);
                 if (svcRecord) {
                     const bootResult = await this.serviceOrchestrator.boot(rigId);
@@ -263,7 +315,8 @@ export class RestoreOrchestrator {
                 }
             }
             // 4. Compute restore plan
-            const plan = this.computeRestorePlan(snapshot.data);
+            const plan = this.computeRestorePlan(snapshot.data).filter(entry => !replacements.length || selectedIds.has(entry.node.id));
+            const { stoppedNodeIds } = assessSnapshotCurrentOccupants(this.db, rig, snapshot, opts?.preserveStoppedInitial);
             // 5. Execute restore with compensating pattern per node
             const nodeResults = [];
             const restoreWarnings = [...validation.warnings];
@@ -272,8 +325,17 @@ export class RestoreOrchestrator {
             else if (opts?.nonInterruptive === false)
                 restoreWarnings.push(nonInterruptiveSummary(false));
             for (const entry of plan) {
-                const result = await this.restoreNodeWithCompensation(entry, rigId, snapshotId, snapshot.data, opts, restoreWarnings);
+                const held = heldForStartup.get(entry.node.id);
+                if (held) {
+                    nodeResults.push({ nodeId: entry.node.id, logicalId: entry.node.logicalId, status: "failed", error: `Not launched: ${held}` });
+                    continue;
+                }
+                const replacement = replacements.find(target => target.nodeId === entry.node.id);
+                const result = await this.restoreNodeWithCompensation(entry, rigId, snapshotId, snapshot.data, opts, restoreWarnings, stoppedNodeIds.has(entry.node.id));
                 nodeResults.push(result);
+                if (replacement && this.db.prepare("SELECT status FROM sessions WHERE id = ?").get(replacement.sessionId)?.status === "exited") {
+                    restoreWarnings.push(`Stopped ${entry.node.logicalId}'s startup occupant for explicit replacement; replacement outcome: ${result.status}.`);
+                }
             }
             const restoreResult = {
                 snapshotId,
@@ -375,7 +437,9 @@ export class RestoreOrchestrator {
         // discarded, so restore.subset_completed carried warnings: [].
         const subsetWarnings = [];
         for (const node of targetNodes) {
-            const sessions = this.sessionRegistry.getSessionsForRig(rigId)
+            // An external CLI's claim has no tmux session to probe; restoreNodeWithCompensation leaves it attached.
+            const external = this.sessionRegistry.getBindingForNode(node.id)?.attachmentType === "external_cli";
+            const sessions = external ? [] : this.sessionRegistry.getSessionsForRig(rigId)
                 .filter((s) => s.nodeId === node.id && s.status === "running");
             let isLive = false;
             let isUnknown = false;
@@ -466,6 +530,9 @@ export class RestoreOrchestrator {
         const held = [];
         const holdReasonText = opts?.holdReason ?? "excluded_from_subset";
         for (const node of nonTargetNodes) {
+            // A seat joined with `rig attach` as an external CLI has no tmux session to check, and restore leaves it attached.
+            if (this.sessionRegistry.getBindingForNode(node.id)?.attachmentType === "external_cli")
+                continue;
             const sessions = this.sessionRegistry.getSessionsForRig(rigId)
                 .filter((s) => s.nodeId === node.id && s.status === "running");
             let running = false;
@@ -527,14 +594,28 @@ export class RestoreOrchestrator {
      * 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) {
+    async classifyRunningSessions(rigId, selectedIds) {
         const live = [];
         const stale = [];
         const unknown = [];
         for (const session of this.sessionRegistry.getSessionsForRig(rigId)) {
-            if (session.status !== "running")
+            if (session.status !== "running" || (selectedIds && !selectedIds.has(session.nodeId)))
+                continue;
+            // An external CLI's claim has no tmux session; restore leaves it attached (restoreNodeWithCompensation).
+            if (this.sessionRegistry.getBindingForNode(session.nodeId)?.attachmentType === "external_cli")
                 continue;
             try {
+                // Replacement must preserve unknown transport state before any reconciliation write.
+                if (selectedIds) {
+                    const probe = await this.tmuxAdapter.probeSession(session.sessionName);
+                    if (probe.state === "present")
+                        live.push(session.id);
+                    else if (probe.state === "absent")
+                        stale.push(session.id);
+                    else
+                        unknown.push(session.id);
+                    continue;
+                }
                 const alive = await this.tmuxAdapter.hasSession(session.sessionName);
                 if (alive) {
                     live.push(session.id);
@@ -550,6 +631,48 @@ export class RestoreOrchestrator {
         }
         return { live, stale, unknown };
     }
+    /** Called under a new lifecycle lease, after startup has released its own leases. */
+    async stopAutomaticOccupant(target) {
+        const current = (stopped = false) => {
+            const row = this.db.prepare(`SELECT s.id, s.status, s.session_name AS name, s.resume_type AS resumeType,
+        s.resume_token AS resumeToken, s.resume_provenance AS provenance, s.origin, b.tmux_session AS bound, b.tmux_pane AS pane
+        FROM sessions s LEFT JOIN bindings b ON b.node_id = s.node_id
+        WHERE s.node_id = ? AND s.status != 'superseded' ORDER BY s.created_at DESC, s.id DESC LIMIT 1`)
+                .get(target.nodeId);
+            return row?.id === target.sessionId && row.status === (stopped ? "exited" : "running") && row.origin !== "claimed" && row.bound === row.name
+                && row.resumeType === target.resumeType && row.resumeToken === target.resumeToken
+                && (!target.corrected || row.provenance === "operator") ? row : null;
+        };
+        const row = current();
+        if (!row)
+            return "Startup occupant or correction changed; no replacement attempted.";
+        const probe = await this.tmuxAdapter.probeSession(row.name);
+        if (probe.state !== "present")
+            return "Startup terminal is absent or unknown; no replacement attempted.";
+        const observedPane = await observeSolePane(this.tmuxAdapter, row.name);
+        if (!observedPane.ok || observedPane.pane !== row.pane)
+            return "Startup terminal pane no longer matches its managed binding; nothing replaced.";
+        const afterProbe = current();
+        if (!afterProbe || afterProbe.name !== row.name || afterProbe.pane !== row.pane)
+            return "Startup occupant or correction changed during the terminal probe; no replacement attempted.";
+        this.tmuxAdapter.deliveryGuard?.checkInput(row.name);
+        const killed = await this.tmuxAdapter.killSession(row.name);
+        if (!killed.ok)
+            return "Could not stop the startup occupant; no replacement attempted.";
+        if (!current())
+            return "Startup occupant changed during stop; no replacement launched.";
+        this.sessionRegistry.updateStatus(target.sessionId, "exited");
+        this.tmuxAdapter.deliveryGuard?.rebindLifecycle(target.nodeId);
+        // Killing the last session ends tmux's server. Reopen an empty server before proving absence.
+        await this.tmuxAdapter.startServer();
+        const absent = await this.tmuxAdapter.probeSession(row.name);
+        if (absent.state !== "absent")
+            return "Startup terminal absence is unconfirmed; no replacement launched.";
+        if (!current(true))
+            return "Startup occupant changed during stop; no replacement launched.";
+        // Retain the name pin; ordinary restore clears it. Compensation sees an exited predecessor.
+        return null;
+    }
     clearStaleState(nodeId, rigId) {
         this.sessionRegistry.clearBinding(nodeId);
         const sessions = this.sessionRegistry.getSessionsForRig(rigId);
@@ -661,11 +784,16 @@ export class RestoreOrchestrator {
      * Restore one planned seat, checking continuity before launching its occupant.
      * Preserve prior state so a failed launch or resume can be compensated.
      */
-    async restoreNodeWithCompensation(entry, rigId, snapshotId, data, opts, warnings) {
+    async restoreNodeWithCompensation(entry, rigId, snapshotId, data, opts, warnings, preserveStoppedCurrent = false) {
         // Compare against the live logical target without changing saved post-launch inputs.
         const node = entry.node;
         const liveNode = this.rigRepo.getRig(rigId)?.nodes.find(current => current.logicalId === node.logicalId);
         const nodeId = node.id;
+        // A seat joined with `rig attach` as an external CLI keeps its attachment: launching here would replace it.
+        const external = this.sessionRegistry.getBindingForNode(nodeId);
+        if (external?.attachmentType === "external_cli") {
+            return { nodeId, logicalId: node.logicalId, status: "left_attached", error: leftAttachedReason(external.externalSessionName ?? node.logicalId) };
+        }
         // OPR.0.5.7.1 (bought ordering blocker, baton 0efd154d): D1 present-map
         // ambiguity must be DETECTED before any continuity_state short-circuit —
         // a pod node in 'restoring' otherwise returns a silent status "fresh"
@@ -682,6 +810,9 @@ export class RestoreOrchestrator {
             };
         }
         const freshRequested = opts?.freshLogicalIds?.includes(node.logicalId) ?? false;
+        if (occupantResolution.kind === "none" && preserveStoppedCurrent && !freshRequested) {
+            return { nodeId, logicalId: node.logicalId, status: "awaiting-decision", error: stoppedSnapshotReason(node.logicalId, data.rig.name) };
+        }
         const runtimeError = restoreRuntimeCompatibilityError(liveNode ? liveNode.runtime : node.runtime, data.nodeStartupContext?.[nodeId]?.runtime);
         if (runtimeError) {
             return { nodeId, logicalId: node.logicalId, status: "awaiting-decision", error: runtimeError };
@@ -699,6 +830,9 @@ export class RestoreOrchestrator {
             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") {
+                    if (opts?.automaticReplacements?.some(target => target.nodeId === nodeId)) {
+                        return { nodeId, logicalId: node.logicalId, status: "awaiting-decision", error: "Continuity recovery owns this seat; its startup occupant was left unchanged." };
+                    }
                     warnings?.push(`Node ${node.logicalId}: continuity state is 'restoring', skipping`);
                     return { nodeId, logicalId: node.logicalId, status: "fresh" };
                 }
@@ -726,13 +860,15 @@ export class RestoreOrchestrator {
             const snapSession = occupantResolution.kind === "resolved" ? occupantResolution.session : null;
             const policy = effectiveRestorePolicy(seatFacts(data, nodeId, node.runtime, liveNode ? liveNode.runtime : node.runtime), snapSession?.restorePolicy);
             const resumeSourceRecorded = !!snapSession?.resumeType && snapSession.resumeType !== "none";
-            // A community harness is launch-only: nothing resumes it, so even a saved token (say, from a former runtime) stops here.
-            if (policy === "resume_if_possible" && snapSession && !freshRequested && communityHarnessOf(snapSession.communityHarness, node.runtime)) {
+            // A community harness that can't resume this seat's token (launch-only, or a former runtime's id) stops here; a seat
+            // with no token goes on to the "no resume token" stop below.
+            if (policy === "resume_if_possible" && snapSession && !freshRequested && communityHarnessOf(snapSession.communityHarness, node.runtime)
+                && communityHarnessStopsRestore(node.runtime, snapSession.resumeType, snapSession.resumeToken)) {
                 return {
                     nodeId,
                     logicalId: node.logicalId,
                     status: "awaiting-decision",
-                    error: `Resume is unsupported for community harness "${node.runtime}": its preset is launch-only. No session was started, and the earlier conversation is left as it is. Re-run with --fresh ${node.logicalId} only if you want a new conversation.`,
+                    error: communityLaunchOnlyRestoreReason(node.runtime, node.logicalId, this.rigRepo.getRig(rigId)?.rig.name ?? data.rig.name),
                 };
             }
             if (policy === "resume_if_possible" && snapSession && !snapSession.resumeToken && !freshRequested) {
@@ -743,11 +879,18 @@ export class RestoreOrchestrator {
                     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.`,
+                    error: `Original session unresumable: ${sourceNote}. No session was started. Restore the original session manually, or deliberately start only this seat fresh: ${this.freshSeatCommand(rigId, data, node.logicalId)}.`,
                 };
             }
         }
-        // Capture prior state for compensation
+        // All ordinary per-seat preflight decisions precede the destructive effect.
+        const replacement = opts?.automaticReplacements?.find(target => target.nodeId === nodeId);
+        if (replacement) {
+            const error = await this.stopAutomaticOccupant(replacement);
+            if (error)
+                return { nodeId, logicalId: node.logicalId, status: "failed", error };
+        }
+        // Capture prior state for compensation, including an exited replacement predecessor.
         const priorState = this.captureNodeState(nodeId, rigId);
         // Clear stale state so NodeLauncher doesn't see already_bound
         this.clearStaleState(nodeId, rigId);
@@ -816,13 +959,58 @@ export class RestoreOrchestrator {
                 warnings?.push(`Transcript boundary marker failed for ${expectedSessionName}`);
             }
         }
+        // OPR.0.7.0.13: a Claude seat's team skills come back before its session starts, because the session's plugin list
+        // is set then. `rig down` removed the unchanged files OpenRig wrote but kept the records, so they are put back from
+        // their recorded sources (only where those still match) and the seat's plugin is written again. An edited or
+        // unprovable file is named, never substituted. Nothing is replayed into a resumed conversation; this is the seat's
+        // storage on disk.
+        // The rehydration's decisions are carried into the fresh relaunch's replay below, so no later writer undoes them.
+        let seatRehydration;
+        if (node.runtime === "claude-code" || node.runtime === "codex") {
+            const seatSkills = seatSkillPaths({ rigId, logicalId: node.logicalId, runtime: node.runtime });
+            if (hasSeatSkillRecords(seatSkills)) {
+                if (node.runtime === "claude-code")
+                    warnings?.push(...ensureSeatSkillPlugin(seatSkills).map((w) => `Restore: ${w}`));
+                const rehydrated = rehydrateSeatSkills(seatSkills);
+                seatRehydration = rehydrated;
+                if (rehydrated.restored.length > 0)
+                    warnings?.push(`Restore: put back ${rehydrated.restored.length} skill file(s) for ${node.logicalId} from their recorded sources`);
+                for (const file of rehydrated.kept)
+                    warnings?.push(`Restore: kept ${file}: it differs from what OpenRig wrote there (an edit is never overwritten)`);
+                for (const file of rehydrated.missing)
+                    warnings?.push(`Restore: ${file} is missing and its recorded source is gone or has changed; not substituted`);
+                for (const file of rehydrated.refused)
+                    warnings?.push(`Restore: ${file} is not inside this seat's storage (a link on the way); nothing written there`);
+                // The seat's generated router is rebuilt from what is now in its storage, for either runtime.
+                try {
+                    const router = writeSeatSkillRouter(seatSkills);
+                    if (router.kept)
+                        warnings?.push(`Restore: ${seatRouterKeptNote(router)}`);
+                }
+                catch (error) {
+                    warnings?.push(`Restore: seat_router_not_written: ${error.message}`);
+                }
+                // A Codex seat's catalog is rebuilt from what is now in its storage (its startup text sends it on a fresh start).
+                if (node.runtime === "codex") {
+                    try {
+                        const catalog = writeSeatSkillCatalog(seatSkills);
+                        if (catalog.kept)
+                            warnings?.push(`Restore: ${seatCatalogKeptNote(catalog)}`);
+                    }
+                    catch (error) {
+                        warnings?.push(`Restore: seat_catalog_not_written: ${seatSkills.catalogPath}: ${error.message}`);
+                    }
+                }
+            }
+        }
         // Attempt launch — compensate ONLY if launch itself fails
-        // The snapshot's saved startup context says which plugins the seat selected; without one the launcher reads the
-        // node's own saved context.
+        // Preserve the snapshot's selected plugins and record the committed session before launch continues.
         const savedStartup = data.nodeStartupContext?.[nodeId];
+        const onSessionLaunched = opts?.onSessionLaunched;
         const launchResult = await this.nodeLauncher.launchNode(rigId, node.logicalId, {
             ...launchOpts,
             ...(savedStartup ? { pluginPaths: pluginPathsOf(savedStartup.projectionEntries) } : {}),
+            ...(onSessionLaunched ? { onSessionRegistered: (sessionId) => onSessionLaunched(nodeId, sessionId) } : {}),
         });
         if (!launchResult.ok) {
             // Launch failed — restore prior state (compensating action)
@@ -840,13 +1028,22 @@ export class RestoreOrchestrator {
         if (launchResult.warnings?.length) {
             warnings?.push(...launchResult.warnings);
         }
-        const restored = await this.postLaunchRestore(entry, rigId, data, launchResult.sessionName, launchResult, opts, warnings, priorState);
+        const restored = await this.postLaunchRestore(entry, rigId, data, launchResult.sessionName, launchResult, opts, warnings, priorState, seatRehydration);
         return this.checkRestoredGuidance(restored, entry.node, rigId, data, warnings);
     }
     /** A seat that came back running should also have its role, culture and SOP guidance. If its
      *  guidance file still lacks a managed block it should hold, the seat keeps its true status (a
      *  live resumed session is still running) and the gap is disclosed on the node and in the
      *  warnings, so the rig is reported partially_restored, not fully_restored. */
+    /** Whether the person answered yes to the seat-skills line; an unreadable answer isn't a yes. */
+    routerLineAnsweredYes() {
+        try {
+            return readFootprintAnswer(this.routerLineSettings ?? new SettingsStore()).state === "yes";
+        }
+        catch {
+            return false;
+        }
+    }
     checkRestoredGuidance(result, node, rigId, data, warnings) {
         // Every status with a live session; attention_required keeps its status and gains the disclosure.
         if (!["resumed", "fresh-primed", "fresh", "rebuilt", "attention_required"].includes(result.status))
@@ -859,6 +1056,8 @@ export class RestoreOrchestrator {
             warnings?.push(`Restore: ${node.logicalId}: could not check its guidance: ${err.message}`);
             return { ...result, guidanceGaps: ["(guidance check failed)"] };
         }
+        if (guidance)
+            guidance = applySeatSkillsLineRule(guidance, this.routerLineAnsweredYes()).guidance;
         if (!guidance || guidance.items.length === 0)
             return result;
         let missing;
@@ -895,7 +1094,11 @@ export class RestoreOrchestrator {
             this.restoreNodeState(nodeId, priorState);
         }
     }
-    async postLaunchRestore(entry, rigId, data, sessionName, launchResult, opts, warnings, priorState) {
+    /** The one-seat command a restore reason names for a seat left awaiting a decision. */
+    freshSeatCommand(rigId, data, logicalId) {
+        return freshSeatLaunchCommand(logicalId, this.rigRepo.getRig(rigId)?.rig.name ?? data.rig.name);
+    }
+    async postLaunchRestore(entry, rigId, data, sessionName, launchResult, opts, warnings, priorState, seatRehydration) {
         const node = entry.node;
         // OPR.0.7.0.7: what this restore launches with when the seat has a saved effort choice is decided by the one
         // precedence seam (latest wins), which also says so when the snapshot held another value.
@@ -987,6 +1190,12 @@ export class RestoreOrchestrator {
                 // Guidance never blocks the exact resume; the post-launch check discloses the gap.
                 warnings?.push(`Restore guidance: ${node.logicalId}: could not read its saved guidance selection: ${err.message}`);
             }
+            if (guidance) {
+                const rule = applySeatSkillsLineRule(guidance, this.routerLineAnsweredYes());
+                guidance = rule.guidance;
+                if (rule.excluded === "linked")
+                    warnings?.push(`Restore guidance: ${node.logicalId}: the seat-skills line wasn't put back, because ${guidance.targetPath} is a link.`);
+            }
             if (guidance && guidance.items.length > 0) {
                 const repair = restoreMissingGuidance(guidance, {
                     exists: existsSync,
@@ -1009,7 +1218,7 @@ export class RestoreOrchestrator {
                 // 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.` };
+                return { nodeId: node.id, logicalId: node.logicalId, status: "awaiting-decision", error: `Original session unresumable: resume requested but no token available. No session is running. Restore the original session manually, or deliberately start only this seat fresh: ${this.freshSeatCommand(rigId, data, node.logicalId)}.` };
             }
             else {
                 const launchedSessionId = launchResult?.session.id;
@@ -1020,7 +1229,7 @@ export class RestoreOrchestrator {
                     }
                     catch { /* best-effort: without it a rotation stays unproved, as before */ }
                 }
-                const resumeOutcome = await this.attemptResume(node.id, sessionName, resumeType, resumeToken, node.cwd ?? "/", node.codexConfigProfile, node.model, this.resolveRestorePosture(node.id, rigId), effortForRestore(), warnings);
+                const resumeOutcome = await this.attemptResume(node.id, sessionName, resumeType, resumeToken, node.cwd ?? "/", node.codexConfigProfile, node.model, this.resolveRestorePosture(node.id, rigId), effortForRestore(), warnings, node.advisor);
                 if (resumeOutcome.kind === "resumed") {
                     baseStatus = "resumed";
                     if (launchedSessionId && this.claudeResume.canResume(resumeType, resumeToken)) {
@@ -1053,7 +1262,7 @@ export class RestoreOrchestrator {
                     // 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.` };
+                    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. Check the harness state manually, or deliberately start only this seat fresh: ${this.freshSeatCommand(rigId, data, node.logicalId)}.` };
                 }
             }
         }
@@ -1068,7 +1277,7 @@ export class RestoreOrchestrator {
                     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.`,
+                    error: `Original session unresumable: resume requested but no token available. No session is running. Restore the original session manually, or deliberately start only this seat fresh: ${this.freshSeatCommand(rigId, data, node.logicalId)}.`,
                 };
             }
             // OPR.0.4.3.20 FR-7 (Gap 2b) — a pod-aware resume needs the runtime adapter
@@ -1084,7 +1293,7 @@ export class RestoreOrchestrator {
                     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.`,
+                    error: `Original session unresumable: resume requested but runtime continuity could not be verified (no ${node.runtime ?? "runtime"} adapter available). No session is running. Retry the restore with runtime adapters, or deliberately start only this seat fresh: ${this.freshSeatCommand(rigId, data, node.logicalId)}.`,
                 };
             }
         }
@@ -1166,7 +1375,20 @@ export class RestoreOrchestrator {
                     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)
+                    // OPR.0.7.0.13: a fresh relaunch of a seat with its own storage keeps the saved selection, through every later
+                    // writer: a skill or startup skill file already in its storage (put back above, before the launch) is left as
+                    // it is, an edited one is named, and a missing one whose recorded source is gone or has changed is not put back
+                    // with today's bytes. Only the rest is projected or installed. Nothing is re-resolved from today's spec. Native
+                    // resume replays nothing (sourceEntries is empty). The whole selection stays in the saved startup context.
+                    const seatSkills = (startupCtx.runtime === "claude-code" || startupCtx.runtime === "codex") && !replayContained ? seatSkillPathsForNode(this.db, node.id) : undefined;
+                    let replaySkip;
+                    if (seatSkills) {
+                        const replay = seatSkillReplay({ entries: filteredEntries, files: filteredFiles, paths: seatSkills,
+                            rehydration: seatRehydration ?? { missing: [], refused: [] } });
+                        replaySkip = { entryIds: replay.skipEntryIds, files: replay.skipFiles };
+                        warnings?.push(...replay.warnings);
+                    }
+                    // Build fresh projection plan (all safe_projection; replaySkip says which seat skills are left alone)
                     const plan = {
                         runtime: startupCtx.runtime,
                         cwd: node.cwd ?? ".",
@@ -1196,6 +1418,7 @@ export class RestoreOrchestrator {
                         // their -m/--model on restore the same way.
                         model: node.model ?? undefined,
                         effort: effortForRestore() ?? undefined,
+                        advisor: node.advisor ?? undefined,
                     };
                     try {
                         const { StartupOrchestrator } = await import("./startup-orchestrator.js");
@@ -1213,6 +1436,7 @@ export class RestoreOrchestrator {
                             resolvedStartupFiles: filteredFiles,
                             startupActions: sourceActions,
                             isRestore: replayAsRestore,
+                            ...(replaySkip ? { replaySkip } : {}),
                             preserveStartupContext: replayContained,
                             skipHarnessLaunch: !shouldLaunchHarness,
                             resumeToken: (isPodAware && resumeRequested) ? resumeToken ?? undefined : undefined,
@@ -1238,14 +1462,14 @@ export class RestoreOrchestrator {
                                     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.`,
+                                    error: `Original session unresumable: resume attempted but the runtime reported fresh continuity. The blank session was rolled back; no session is running. If that degradation is acceptable, start only this seat fresh: ${this.freshSeatCommand(rigId, data, node.logicalId)}.`,
                                 };
                             }
                             const finalStatus = (isPodAware && resumeRequested)
                                 ? ((startupResult.continuityOutcome === "resumed" || nativeContinuityProved) ? "resumed" : baseStatus)
                                 : baseStatus;
                             if (finalStatus === "resumed") {
-                                return this.finishJoinedResume(node, sessionName, resumeToken, launchResult?.session.id, isPodAware && node.runtime === "claude-code");
+                                return this.finishJoinedResume(node, sessionName, resumeToken, launchResult?.session.id, isPodAware && node.runtime === "claude-code", startupResult.resumedProcess);
                             }
                             return { nodeId: node.id, logicalId: node.logicalId, status: finalStatus };
                         }
@@ -1271,13 +1495,13 @@ export class RestoreOrchestrator {
                             // Only the runtime's own report that the conversation doesn't exist rolls the seat back
                             // as unresumable. A pane that went back to its shell for another reason stays failed,
                             // with its pane and binding kept, so its output can still be read.
-                            if (startupResult.recovery === "retry_fresh" && startupResult.missingConversation) {
+                            if (startupResult.missingConversation) {
                                 await this.rollbackToZeroSession(node.id, sessionName, launchResult?.session.id, priorState);
                                 return {
                                     nodeId: node.id,
                                     logicalId: node.logicalId,
                                     status: "awaiting-decision",
-                                    error: `Original session unresumable: ${startupResult.errors.join("; ")}. The blank session was rolled back; no session is running. Re-run with --fresh ${node.logicalId} to deliberately start a fresh-primed seat, or restore the original session manually.`,
+                                    error: `Original session unresumable: ${startupResult.errors.join("; ")}. The blank session was rolled back; no session is running. Restore the original session manually, or deliberately start only this seat fresh: ${this.freshSeatCommand(rigId, data, node.logicalId)}.`,
                                 };
                             }
                             return {
@@ -1329,7 +1553,9 @@ export class RestoreOrchestrator {
     }
     /** A native resume is only a full success after the restored terminal is
      * rebound and its process identity agrees with the declared seat runtime. */
-    async finishJoinedResume(node, sessionName, resumeToken, sessionId, managedClaudeResume = false) {
+    async finishJoinedResume(node, sessionName, resumeToken, sessionId, managedClaudeResume = false, 
+    /** Codex (#1524): the process the adapter proved the resume on. The join must verify that same process. */
+    provenCodexProcess) {
         const identity = await rebindAndVerifyPaneIdentity({
             db: this.db,
             sessionRegistry: this.sessionRegistry,
@@ -1360,6 +1586,19 @@ export class RestoreOrchestrator {
                 error: `Exact native session resumed, but joined restore proof is incomplete: ${identity.detail}. The resumed session was preserved; no replacement was started.`,
             };
         }
+        // #1524 (b): the adapter proved the resume on one Codex process. The join observed later, after startup's awaits;
+        // a different process (or none matched) there is not certified by that proof. No new read, wait or relaunch.
+        if (node.runtime === "codex" && provenCodexProcess) {
+            const joined = identity.nativeProcess;
+            if (!joined || joined.pid !== provenCodexProcess.pid || joined.startedAt !== provenCodexProcess.startedAt) {
+                const store = new SeatIdentityStore(this.db);
+                const proof = store.getForNode(node.id);
+                if (proof)
+                    store.upsert({ ...proof, verdict: "mismatch", reason: "process_identity_mismatch" });
+                return { nodeId: node.id, logicalId: node.logicalId, status: "attention_required",
+                    error: `Codex resume was proven on process ${provenCodexProcess.pid} (started ${provenCodexProcess.startedAt}), but the restore join verified ${joined ? `process ${joined.pid} (started ${joined.startedAt ?? "unknown"})` : "no matching Codex process"}. The session was preserved; nothing was restarted.` };
+            }
+        }
         // Legacy resume adapters do not write native metadata. Fill only the
         // launched row's empty token after proof; never overwrite a hook/operator.
         const provedClaudeWrapper = node.runtime === "claude-code"
@@ -1477,7 +1716,7 @@ export class RestoreOrchestrator {
     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, effort, warnings) {
+    resolvedPosture, effort, warnings, advisor) {
         const launchGeneration = this.sessionRegistry.currentOccupantTenure(nodeId)?.generationUuid;
         const node = this.db.prepare("SELECT rig_id FROM nodes WHERE id = ?").get(nodeId);
         const nonInterruptive = node ? this.rigRepo.getRigNonInterruptive(node.rig_id) : false;
@@ -1500,8 +1739,22 @@ export class RestoreOrchestrator {
             ? [effort, nonInterruptive, false, true] : kernelAuthority
             ? [effort, nonInterruptive, true] : nonInterruptive ? [effort, true] : effort !== undefined ? [effort] : [];
         if (this.claudeResume.canResume(resumeType, resumeToken)) {
-            const result = await this.claudeResume.resume(sessionName, resumeType, resumeToken, cwd, resolvedPosture, model, permissionMode, nodeId, ...launchTail);
+            // Advisor is Claude-specific; preserve the existing tail for other runtimes and unconfigured seats.
+            const claudeTail = advisor
+                ? [effort, nonInterruptive, kernelAuthority, teamPermissionDefault, advisor] : launchTail;
+            // OPR.0.7.0.9: the seat's own launch additions follow the Advisor.
+            const launch = nodeId ? seatLaunchAdditionsForLaunch(this.db, nodeId) : { missing: [], refused: [] };
+            for (const file of launch.missing)
+                warnings?.push(`${sessionName}: seat_launch_addition_missing: ${file} is not in this seat's storage; launched without it`);
+            for (const reason of launch.refused)
+                warnings?.push(`${sessionName}: seat_launch_addition_refused: ${reason}; launched without it`);
+            const tail = launch.additions ? [...claudeTail, ...Array(5 - claudeTail.length).fill(undefined), launch.additions] : claudeTail;
+            const result = await this.claudeResume.resume(sessionName, resumeType, resumeToken, cwd, resolvedPosture, model, permissionMode, nodeId, ...tail);
             if (result.ok) {
+                // OPR.0.7.0.9: the resumed conversation's own start, as on the pod-aware path.
+                const promptNote = launch.additions?.appendSystemPromptFile && nodeId && resumeToken ? systemPromptPendingNoteForNode(this.db, nodeId, resumeToken) : undefined;
+                if (promptNote)
+                    warnings?.push(`${sessionName}: ${promptNote}`);
                 const notice = nonInterruptiveNotice("claude-code", { nonInterruptive, launchPosture: resolvedPosture, permissionMode });
                 if (notice)
                     warnings?.push(`${sessionName}: ${notice}`);
@@ -1717,12 +1970,13 @@ export class RestoreOrchestrator {
         // 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") {
+            const evidence = await resumeProbeEvidence(probe, paneContent, this.tmuxAdapter, identity.pane);
             // The label reads as a shell, but the runtime's lineage was just proven in this pane: name a shell only for a proven idle one.
             if (probe.code === "returned_to_shell" && !await verifyPaneIdleShell({ target: identity.pane, tmux: this.tmuxAdapter,
                 ...(this.listProcesses ? { listProcesses: this.listProcesses } : {}) })) {
-                return { ok: false, code: "pane_not_usable", detail: "Pane is not shown to be resumed: its command reads as a shell, but it is not a proven idle shell (the runtime may be starting or showing a dialog); reconciliation requires resumed." };
+                return { ok: false, code: "pane_not_usable", probe: evidence, attemptId, detail: "Pane is not shown to be resumed: its command reads as a shell, but it is not a proven idle shell (the runtime may be starting or showing a dialog); reconciliation requires resumed." };
             }
-            return { ok: false, code: "pane_not_usable", detail: `Pane state is ${probe.status} (${probe.code}); reconciliation requires resumed.` };
+            return { ok: false, code: "pane_not_usable", probe: evidence, attemptId, detail: `Pane state is ${probe.status} (${probe.code}); reconciliation requires resumed.` };
         }
         // All four preconditions hold. Append (never mutate) the audit event.
         this.eventBus.emit({