@skillcap/gdh 0.22.0 → 0.24.0

package/node_modules/@gdh/adapters/dist/self-update-mechanics.js

@@ -1,7 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { resolvePinnedVersion, resolvePinnedVersionOrNull, resolveProjectRoot, writePinnedVersion, } from "@gdh/authoring";
-import { invalidateGdhUpdateCache, resolveEffectiveDevRepoPath } from "@gdh/core";
+import { readProjectConfig, resolvePinnedVersion, resolvePinnedVersionOrNull, resolveProjectRoot, writePinnedVersion, } from "@gdh/authoring";
+import { GDH_AGENT_CONTRACT_VERSION, GDH_PROJECT_CONFIG_VERSION, MIGRATION_REGISTRY_ENTRIES, applyMigrationChain, deleteProcessesSnapshot, invalidateGdhUpdateCache, readMigrationState, readProcessesSnapshot, readRenderInventory, resolveEffectiveDevRepoPath, writeMigrationState, writeProcessesSnapshot, writeRenderInventory, } from "@gdh/core";
+import { detectClass1MarkerDrift, driftResultToPreservationNotes, readBackupManifest, restoreFromDurableBackup, writeDurableBackup, } from "./durable-backup.js";
+import { runInventorySweep } from "./inventory-sweep.js";
+import { captureProcessSnapshot, defaultProcessOrchestrationEnvironment, restartFromSnapshot, stopCapturedProcesses, } from "./process-orchestration.js";
 // Dynamic import breaks the circular dependency with ./index.ts.
 //
 // self-update-mechanics.ts is re-exported from adapters/index.ts (the barrel).
@@ -18,20 +21,91 @@ async function loadInstallSupportedAgentAdapters() {
     const { installSupportedAgentAdapters } = await import("./index.js");
     return installSupportedAgentAdapters;
 }
+// ---------------------------------------------------------------------------
+// Plan 72-08 — pair resolution helpers (D-10 step 2)
+// ---------------------------------------------------------------------------
 /**
- * Phase 12 MIG-01 + MIG-02 orchestrator. Atomically bumps the .gdh/project.yaml
- * `gdh_version` pin and re-bakes every managed surface at the new pin.
+ * Resolve the {schema, agentContract} pair for an onboarded target.
  *
- * Sequencing invariant (MIG-02): writePinnedVersion is called BEFORE
- * installSupportedAgentAdapters. Because installSupportedAgentAdapters reads
- * the pin from disk once per top-level call (adapters/index.ts:173), pinning
- * first guarantees every renderer bakes the new value.
+ * Returns:
+ *   - `null` when `.gdh/project.yaml` is absent or unparseable (project not
+ *     onboarded; bumpAndRebakePin treats this as `blocked` with reason
+ *     `current_pair_unresolvable`)
+ *   - the supported-range floor pair `{schema: 2, agentContract: 2}` for any
+ *     readable target
  *
- * Transactional invariant (MIG-02): on re-bake failure, every captured original
- * is restored. Partial state is not acceptable.
+ * Why a constant floor instead of the on-disk version? The supported floor
+ * pair gates the s2c2_to_s2c3 registry entry's range filter
+ * (entry.from = {2,2} must be ≥ fromPair). Per Plan 72-02 audit, every entry
+ * in the supported range is idempotent — running it on a target that's
+ * already past the entry's `to` pair is a verify-true no-op. Using the
+ * constant floor means the chain considers every entry on every run; the
+ * entry transforms self-detect "already at HEAD" and skip work, and the
+ * entry verify probes self-confirm "rules.yaml at version: 3" regardless of
+ * whether the entry just rewrote it or it was already there.
  *
- * SELF-03 leak barrier: dev-mode check gates at the mechanics layer, not only at
- * Phase 13 entry points. Single source of truth.
+ * The on-disk schema version (`version:` field of `.gdh/project.yaml`) is
+ * read defensively to confirm the config is parseable, but is not used to
+ * narrow the pair: per the audit, project.yaml `version: 3` has been
+ * forward-compatible since v0.18 and does not gate registry entries.
+ */
+export async function resolveCurrentMigrationPairOrNull(targetPath) {
+    const configPath = path.join(targetPath, ".gdh/project.yaml");
+    const content = await fs.readFile(configPath, "utf8").catch(() => null);
+    if (content === null)
+        return null;
+    // Defensive parse: ensure the file has at minimum a recognizable schema
+    // header. If parse fails, treat as unresolvable.
+    const firstLine = content.split("\n", 1)[0] ?? "";
+    if (!/^version:\s*\d+/.test(firstLine))
+        return null;
+    return { schema: 2, agentContract: 2 };
+}
+/**
+ * Resolve the {schema, agentContract} pair for the running GDH version.
+ *
+ * Always the package's compile-time pair: `GDH_PROJECT_CONFIG_VERSION` and
+ * `GDH_AGENT_CONTRACT_VERSION` from `@gdh/core`. This is the chain's `to`
+ * pair ceiling — applyMigrationChain runs every entry whose `to` ≤ this pair.
+ */
+export function resolveTargetMigrationPair() {
+    return {
+        schema: GDH_PROJECT_CONFIG_VERSION,
+        agentContract: GDH_AGENT_CONTRACT_VERSION,
+    };
+}
+/**
+ * Phase 12 MIG-01 + MIG-02 + Plan 72-08 D-10 orchestrator. Atomically bumps the
+ * `.gdh/project.yaml` `gdh_version` pin, re-bakes every managed surface at the
+ * new pin (class-1), runs the migration registry chain (class-2/3 transforms +
+ * verify probes), sweeps orphan files, and orchestrates managed-process
+ * stop/restart with a deferred-action recovery path on restart failure.
+ *
+ * The full 12-step ordering (D-10):
+ *   1. SELF-03 dev-mode short-circuit (preserved unchanged)
+ *   2. Plan: dry-run installSupportedAgentAdapters + resolve from/to pair
+ *   3. Capture process snapshot (writeProcessesSnapshot)
+ *   4. Stop processes (broker → pruneBroker; mcp → graceful → hard kill)
+ *   5. Write durable backup (.gdh-state/backup/) with WFL-02 marker drift detection
+ *   6. Write pin (writePinnedVersion) — MIG-02 sequencing precedes final re-bake
+ *   7. Re-bake adapters (installSupportedAgentAdapters apply)
+ *   8. Apply migration chain (registry entries class-2/3); failure → 8a rollback
+ *   9. Inventory set-diff sweep (orphan deletion)
+ *   10. Write new render-inventory.json + migration.json
+ *   11. Restart processes from snapshot; on all_restarted delete snapshot,
+ *       on some_failed write process_restart deferred action (D-19)
+ *   12. Emit structured BumpAndRebakePinResult
+ *
+ * On step-8 chain failure: restoreFromDurableBackup re-creates files byte-equal
+ * pre-update (writePinnedVersion is rolled back automatically because
+ * `.gdh/project.yaml` is in the captured paths). Processes stay stopped per
+ * WFL-01 D-18 step 6. Inventory is NOT updated (the new render set was never
+ * reached coherently). Result: `rolled_back_from_durable_backup`.
+ *
+ * Sequencing invariant (MIG-02 + validate-docs Check 43): writePinnedVersion
+ * is called textually BEFORE the FINAL installSupportedAgentAdapters call in
+ * this file. The dry-run plan call at step 2 reads the current pin; the apply
+ * call at step 7 reads the new pin from disk after writePinnedVersion.
  */
 export async function bumpAndRebakePin(targetPath, options) {
     const rawTargetPath = path.resolve(targetPath);
@@ -46,23 +120,74 @@ export async function bumpAndRebakePin(targetPath, options) {
             currentVersion: await resolvePinnedVersionOrNull(effectiveTargetPath),
         };
     }
-    // Step 2: Read current pin (throws with gdh-migrate-apply hint if unonboarded).
+    // Step 2 (plan + pair resolution).
+    const fromPair = await resolveCurrentMigrationPairOrNull(effectiveTargetPath);
+    if (fromPair === null) {
+        return {
+            state: "blocked",
+            reason: "current_pair_unresolvable: .gdh/project.yaml is missing or unparseable",
+        };
+    }
+    const toPair = resolveTargetMigrationPair();
+    // resolvePinnedVersion throws with the gdh-migrate-apply hint if the pin
+    // line is missing — but resolveCurrentMigrationPairOrNull already gated
+    // the absence-of-config case. Pin-line absence after that is genuine.
     const fromVersion = await resolvePinnedVersion(effectiveTargetPath);
-    if (fromVersion === options.targetVersion) {
+    // ── Phase 73 D-11 — resume detection ──
+    // Read migration.json once for the resume marker. If a marker exists and
+    // its `to_pin` matches options.targetVersion, treat this run as a resume of
+    // a previously-paused chain: skip the noop early-return AND skip steps 3-7
+    // (snapshot capture, stop, durable backup, pin write, re-bake) since they
+    // already ran in the original attempt. Re-running steps 5-7 would either be
+    // a no-op (idempotent pin write, idempotent re-bake of already-baked
+    // surfaces) OR destructive (overwriting the durable backup with post-pause
+    // content, which would defeat the all-or-nothing rollback contract). The
+    // marker check MUST run BEFORE the `fromVersion === options.targetVersion`
+    // early-return below, because on resume the pin has already been written
+    // (step 6 of the original attempt) and would otherwise short-circuit as
+    // noop.
+    const priorState = await readMigrationState(effectiveTargetPath);
+    const resumeMarker = priorState?.pending_envelope_resume ?? null;
+    const wasResume = resumeMarker !== null && resumeMarker.to_pin === options.targetVersion;
+    // Defensive: marker present but for a different target (e.g., manual
+    // downgrade or hand-edited migration.json with mismatched to_pin). Clear
+    // the stale marker and fall through to the standard pin-equality check —
+    // the run continues as a fresh self-update attempt. Mitigates T-73-04-01.
+    if (resumeMarker !== null && !wasResume) {
+        // exactOptionalPropertyTypes: cannot assign undefined; rebuild without
+        // the marker field. envelopes carries forward as-is (recorded-result
+        // evidence is independent of the in-flight marker).
+        const cleared = {
+            migration_version: 1,
+            last_applied_at: priorState.last_applied_at,
+            deferred_actions: priorState.deferred_actions,
+            ...(priorState.envelopes !== undefined
+                ? { envelopes: priorState.envelopes }
+                : {}),
+        };
+        await writeMigrationState(effectiveTargetPath, cleared);
+    }
+    if (!wasResume && fromVersion === options.targetVersion) {
         return { state: "noop", currentVersion: fromVersion };
     }
-    // Step 3: Plan — dry-run to collect actions. File SET is determined by adapter
-    // status + guidance readiness, not by pin value; planning against current pin
-    // tells us which files to capture. Per research recommendation (c).
     const installSupportedAgentAdapters = await loadInstallSupportedAgentAdapters();
     const plan = await installSupportedAgentAdapters(effectiveTargetPath, {
         dryRun: true,
         allowBootstrap: true,
     });
-    // Step 4: Capture originals (including .gdh/project.yaml) before any mutation.
-    const configPath = path.join(effectiveTargetPath, ".gdh/project.yaml");
-    const originals = await captureOriginals(plan.actions, configPath);
     if (options.dryRun === true) {
+        // WR-04: when the chain is paused on an envelope (resumeMarker is set and
+        // wasResume is true), a dry-run cannot truthfully report `updated`:
+        // pending_envelope_resume is still on disk and gdh status will continue to
+        // emit the envelope-pending advisory. Surface as `blocked` so the agent
+        // sees the real next action — record the envelope result and re-run
+        // without --dry-run.
+        if (wasResume && resumeMarker !== null) {
+            return {
+                state: "blocked",
+                reason: `dry_run_during_envelope_pause: chain is paused on envelope_ref="${resumeMarker.envelope_ref}"; record the result and re-run without --dry-run`,
+            };
+        }
         return {
             state: "updated",
             fromVersion,
@@ -70,95 +195,451 @@ export async function bumpAndRebakePin(targetPath, options) {
             actions: plan.actions,
         };
     }
-    // Step 5: COMMIT POINT — write new pin first (MIG-02 sequencing).
-    //   Phase 12 Check 43 asserts writePinnedVersion call textually precedes the
-    //   final installSupportedAgentAdapters call in this source file. Both calls
-    //   are inside bumpAndRebakePin; the grep/awk check targets the function body.
-    try {
-        await writePinnedVersion(effectiveTargetPath, options.targetVersion);
+    const env = options.processOrchestrationEnvironment ?? defaultProcessOrchestrationEnvironment();
+    // Hoisted across the wasResume branch so step 11 (restart) and step 12
+    // (emit report) can read them on both fresh and resume paths.
+    let preservationNotes = [];
+    let rebakeActions = [];
+    // captureResult/stopResult are intentionally null on resume; step 11 reads
+    // the snapshot via readProcessesSnapshot(effectiveTargetPath) instead.
+    let captureResult = null;
+    let stopResult = null;
+    // Computed inside the !wasResume branch (steps 5/9/10 reference it). On
+    // resume, step 9 has already run in the original attempt — but we still
+    // re-derive renderedRelativePaths from the planned actions before writing
+    // render-inventory.json and migration.json so success-write parity is
+    // preserved.
+    let allPlannedRelativePaths = [];
+    if (wasResume) {
+        // Steps 3-7 already ran in the original attempt:
+        //   - Step 3 (capture snapshot) — processes-snapshot.json persists on disk
+        //   - Step 4 (stop) — stop_method-per-row recorded in that snapshot
+        //   - Step 5 (drift detect + durable backup) — backup persists; manifest
+        //     carries `preservation_notes` from the original drift detection
+        //   - Step 6 (pin write) — pin already at options.targetVersion (so the
+        //     noop early-return above had to be guarded by !wasResume). Even if
+        //     re-invoked, writePinnedVersion is idempotent for the same target.
+        //   - Step 7 (re-bake) — surfaces are already re-baked
+        // Re-taking the durable backup here would clobber the pre-update content
+        // captured originally — defeating the rollback substrate (T-73-04-02).
+        //
+        // Load preservation_notes from the durable backup manifest written in the
+        // original step 5. If the manifest is unreadable (missing or schema-
+        // mismatched), fall back to empty notes — the agent already saw the
+        // original report when the chain paused, so this is informational only.
+        const manifest = await readBackupManifest(effectiveTargetPath);
+        preservationNotes = manifest?.preservation_notes ?? [];
+        // Also re-derive the planned action paths so steps 9 and 10 (inventory
+        // sweep + render-inventory write) see the same surfaces the original
+        // attempt computed.
+        allPlannedRelativePaths = computePlannedRelativePaths(plan.actions, effectiveTargetPath);
     }
-    catch (error) {
-        // Nothing else mutated yet — no rollback needed.
-        return { state: "blocked", reason: `Pin write failed: ${formatError(error)}` };
-    }
-    // Step 6: Re-bake — installSupportedAgentAdapters reads the new pin from disk.
-    try {
-        const rebake = await installSupportedAgentAdapters(effectiveTargetPath, {
-            allowBootstrap: true,
+    else {
+        // Step 3: Capture process snapshot.
+        captureResult = await captureProcessSnapshot({
+            targetPath: effectiveTargetPath,
+            env,
         });
-        const blocked = rebake.actions.filter((a) => a.state === "blocked");
-        if (blocked.length > 0) {
-            throw new Error(`Re-bake had ${blocked.length} blocked action(s): ${blocked
-                .map((a) => a.summary)
-                .join("; ")}`);
+        // WR-01: Snapshot write is the recovery anchor for the stop step. If we
+        // cannot persist the captured snapshot, do NOT proceed to stop processes —
+        // a SIGTERM with no recorded snapshot leaves the operator with stopped
+        // processes and no rows to drive restart. Convert to blocked so the
+        // structured BumpAndRebakePinResult shape is preserved through the CLI.
+        try {
+            await writeProcessesSnapshot(effectiveTargetPath, captureResult.snapshot);
         }
-        // Phase 16 UPD-05 Fix B: invalidate the shared update-check cache so the
-        // Claude statusline (which reads cache.updateAvailable directly, bypassing
-        // readGdhUpdateMetaOrNull) clears its update indicator in the same session
-        // and every other reader gets a clean-slate re-probe on the next
-        // SessionStart hook. Structurally gated to the "updated" return only:
-        // rolled_back / blocked / noop / skipped_dev_mode all return earlier.
-        // Kept inside the try so any future throw here routes through rollback.
-        await invalidateGdhUpdateCache();
+        catch (error) {
+            return {
+                state: "blocked",
+                reason: `processes_snapshot_write_failed: ${formatError(error)}`,
+            };
+        }
+        // Step 4: Stop processes; persist updated snapshot (with stop_method per row).
+        stopResult = await stopCapturedProcesses({
+            snapshot: captureResult.snapshot,
+            env,
+            targetPath: effectiveTargetPath,
+        });
+        // WR-01: Stop has already happened — by the time we get here processes are
+        // SIGTERM'd. A failed snapshot write at this point is still recoverable
+        // contractually (the captured snapshot from step 3 is on disk) but we
+        // surface the failure as blocked so downstream consumers (D-15/D-18) see
+        // the structured shape rather than a thrown exception.
+        try {
+            await writeProcessesSnapshot(effectiveTargetPath, stopResult.updatedSnapshot);
+        }
+        catch (error) {
+            return {
+                state: "blocked",
+                reason: `processes_snapshot_write_failed: ${formatError(error)}`,
+            };
+        }
+        // Step 5: WFL-02 drift detection + durable backup.
+        allPlannedRelativePaths = computePlannedRelativePaths(plan.actions, effectiveTargetPath);
+        // Approximate class-1 set: the plan's actions include skill rendering
+        // (per-target paths under .claude/.codex/.cursor + .gdh/runtime-knowledge)
+        // which are deterministic class-1 surfaces. We feed every plan-derived
+        // relative path through detectClass1MarkerDrift; KNOWN_GDH_MARKERS only
+        // matches files that GDH actually rendered (those carry the marker), so
+        // false positives degrade to manifest entries — never silent loss.
+        const driftResult = await detectClass1MarkerDrift({
+            targetPath: effectiveTargetPath,
+            plannedClass1Paths: allPlannedRelativePaths,
+        });
+        preservationNotes = driftResultToPreservationNotes(driftResult);
+        const allPlannedPaths = uniquePaths([
+            ".gdh/project.yaml",
+            ...allPlannedRelativePaths,
+        ]);
+        const fromPin = (await resolvePinnedVersionOrNull(effectiveTargetPath)) ?? "";
+        // WR-03: defensive cross-check before clobbering the durable backup. If we
+        // are on the fresh-run path (!wasResume), no resume marker is set, but a
+        // backup manifest already exists, the most likely explanation is that
+        // migration.json was deleted (or hand-edited) between a paused chain and
+        // this run. Overwriting the existing backup with post-pause content would
+        // destroy the rollback substrate (T-73-04-02). Surface as blocked so the
+        // operator can run `gdh migration clear-backups` after confirming state.
+        const existingManifest = await readBackupManifest(effectiveTargetPath);
+        if (existingManifest !== null) {
+            return {
+                state: "blocked",
+                reason: "stale_durable_backup_no_marker: a durable backup exists but migration.json has no pending_envelope_resume marker; run `gdh migration clear-backups` after confirming the workspace state",
+            };
+        }
+        await writeDurableBackup({
+            targetPath: effectiveTargetPath,
+            fromPair,
+            toPair,
+            fromPin,
+            toPin: options.targetVersion,
+            plannedPaths: allPlannedPaths,
+            preservationNotes,
+        });
+        // Step 6: COMMIT POINT — write new pin first (MIG-02 sequencing; Check 43).
+        try {
+            await writePinnedVersion(effectiveTargetPath, options.targetVersion);
+        }
+        catch (error) {
+            // Pin write failed before the chain ran. Backup is intact; restore so
+            // .gdh/project.yaml is unchanged and the operator can re-run.
+            await restoreFromDurableBackup({ targetPath: effectiveTargetPath });
+            return {
+                state: "blocked",
+                reason: `Pin write failed: ${formatError(error)}`,
+            };
+        }
+        // Step 7: Re-bake adapters (installSupportedAgentAdapters reads the new pin).
+        try {
+            const rebake = await installSupportedAgentAdapters(effectiveTargetPath, {
+                allowBootstrap: true,
+            });
+            rebakeActions = rebake.actions;
+            const blocked = rebake.actions.filter((a) => a.state === "blocked");
+            if (blocked.length > 0) {
+                throw new Error(`Re-bake had ${blocked.length} blocked action(s): ${blocked
+                    .map((a) => a.summary)
+                    .join("; ")}`);
+            }
+            // Step 7b: Repair the runtime bridge surface. Without this, self-update
+            // re-bakes the managed adapters and addon files but leaves project.godot
+            // missing the GDHBridge autoload, which `inspectProjectLifecycleCompatibility`
+            // surfaces as `compatibility_degraded` with reasons
+            // `runtime_bridge_plugin_enable_required` /
+            // `runtime_bridge_autoload_missing_or_drifted`. The repair pass runs the
+            // v1.18 register_autoload class-3 op deterministically (see
+            // GDH_MANAGED_SURFACE_CLASSES `project_godot.allowedOps`), so the chain
+            // matrix can prove "every supported version reaches HEAD via gdh
+            // self-update without manual intervention".
+            const projectConfigForBridge = await readProjectConfig(effectiveTargetPath);
+            if (projectConfigForBridge !== null) {
+                const { repairRuntimeBridgeSurface } = await import("@gdh/runtime");
+                await repairRuntimeBridgeSurface({
+                    targetPath: effectiveTargetPath,
+                    projectConfig: projectConfigForBridge,
+                    dryRun: false,
+                });
+            }
+            // Phase 16 UPD-05 Fix B: invalidate the shared update-check cache so the
+            // Claude statusline clears its update indicator in the same session.
+            await invalidateGdhUpdateCache();
+        }
+        catch (error) {
+            // Re-bake failure is treated as a chain-equivalent rollback path: restore
+            // from durable backup so pin + class-1 surfaces revert atomically.
+            const restore = await restoreFromDurableBackup({
+                targetPath: effectiveTargetPath,
+            });
+            return {
+                state: "rolled_back_from_durable_backup",
+                // WR-03: surface the resolved fromVersion (line 266) — never `fromPin`,
+                // which uses the OrNull `?? ""` fallback and would silently coerce a
+                // contractually-impossible null into "" and violate the typed
+                // `BumpAndRebakePinResult.fromVersion: string` semver invariant.
+                fromVersion,
+                attemptedToVersion: options.targetVersion,
+                failureReason: {
+                    kind: "transform_threw",
+                    entryId: "rebake_pre_chain",
+                    error: formatError(error),
+                },
+                preservationNotes,
+                restoredPaths: restore.state === "restored" ? restore.restored : [],
+                removedPaths: restore.state === "restored" ? restore.removed : [],
+                // WR-06: surface aggregate restore-failure count so callers don't
+                // mistake a totally-failed restore for a clean rollback.
+                restoreFailedCount: restore.state === "restored" ? restore.failedCount : 0,
+            };
+        }
+    }
+    // Step 8: Apply migration chain. Pause on needs_envelope (Phase 73 D-09).
+    // Verify/transform failure → 8a rollback.
+    const chainResult = await applyMigrationChain(effectiveTargetPath, fromPair, toPair, undefined, // entries — default to MIGRATION_REGISTRY_ENTRIES
+    // Plan 73-03 envelopePinContext: pin the chain's D-10 staleness check to
+    // this bump's pair. Production callers always pass this so the gate
+    // doesn't fail closed unconditionally.
+    { fromPin: fromVersion, toPin: options.targetVersion });
+    // Phase 73 D-11 — chain paused on an unresolved envelope_ref. Atomically
+    // write the in-flight resume marker (mirrors WR-02 receipt-before-cleanup:
+    // the marker is the resume substrate, distinct from the migration.json
+    // success receipt). Read fresh state to preserve any existing envelopes
+    // slot history (D-08) and deferred actions across the marker write.
+    if (chainResult.state === "needs_envelope") {
+        const currentState = await readMigrationState(effectiveTargetPath);
+        const pauseState = {
+            migration_version: 1,
+            last_applied_at: currentState?.last_applied_at ?? {
+                package: fromVersion,
+                schema: fromPair.schema,
+                agentContract: fromPair.agentContract,
+            },
+            deferred_actions: currentState?.deferred_actions ?? [],
+            ...(currentState?.envelopes !== undefined
+                ? { envelopes: currentState.envelopes }
+                : {}),
+            pending_envelope_resume: {
+                envelope_ref: chainResult.envelopeRef,
+                from_pin: fromVersion,
+                to_pin: options.targetVersion,
+            },
+        };
+        await writeMigrationState(effectiveTargetPath, pauseState);
+        // Durable backup persists; processes-snapshot persists; we do NOT call
+        // deleteProcessesSnapshot or restoreFromDurableBackup here. The agent
+        // runs the envelope, calls `gdh migration record-envelope-result` (Plan
+        // 73-05), then re-runs `gdh self-update` which resumes from step 8 with
+        // wasResume === true.
         return {
-            state: "updated",
+            state: "needs_envelope",
             fromVersion,
-            toVersion: options.targetVersion,
-            actions: rebake.actions,
+            attemptedToVersion: options.targetVersion,
+            envelopeRef: chainResult.envelopeRef,
+            envelope: chainResult.envelope,
+            preservationNotes,
+            priorlyApplied: chainResult.applied,
         };
     }
-    catch (error) {
-        const restoreFailures = await rollbackOriginals(originals);
+    if (chainResult.state === "verify_failed" ||
+        chainResult.state === "transform_threw") {
+        const restore = await restoreFromDurableBackup({
+            targetPath: effectiveTargetPath,
+        });
+        const failureReason = chainResult.state === "verify_failed"
+            ? ({
+                kind: "verify_failed",
+                entryId: chainResult.failedEntryId,
+                reason: chainResult.reason,
+            })
+            : ({
+                kind: "transform_threw",
+                entryId: chainResult.failedEntryId,
+                error: chainResult.error,
+            });
         return {
-            state: "rolled_back",
+            state: "rolled_back_from_durable_backup",
+            // WR-03: see WR-03 comment above — use the resolved fromVersion from
+            // line 266 (typed `string` semver), not `fromPin` which falls back to "".
             fromVersion,
             attemptedToVersion: options.targetVersion,
-            failureReason: formatError(error),
-            restoreFailures,
+            failureReason,
+            preservationNotes,
+            restoredPaths: restore.state === "restored" ? restore.restored : [],
+            removedPaths: restore.state === "restored" ? restore.removed : [],
+            // WR-06: same as above — surface aggregate restore-failure count.
+            restoreFailedCount: restore.state === "restored" ? restore.failedCount : 0,
+        };
+    }
+    // Step 9: Inventory set-diff sweep.
+    const oldInventory = await readRenderInventory(effectiveTargetPath);
+    const supplementaryDeletions = chainResult.state === "applied"
+        ? chainResult.applied.flatMap((id) => {
+            const entry = MIGRATION_REGISTRY_ENTRIES.find((e) => e.id === id);
+            return entry?.supplementaryDeletions ?? [];
+        })
+        : [];
+    await runInventorySweep({
+        targetPath: effectiveTargetPath,
+        oldInventory,
+        supplementaryDeletions,
+    });
+    // Step 10: Write new render-inventory.json + bootstrap migration.json.
+    const renderedRelativePaths = uniquePaths(allPlannedRelativePaths);
+    await writeRenderInventory(effectiveTargetPath, {
+        inventory_version: 1,
+        rendered_at: {
+            package: options.targetVersion,
+            schema: toPair.schema,
+            agentContract: toPair.agentContract,
+        },
+        paths: renderedRelativePaths,
+    });
+    const baseMigrationState = {
+        migration_version: 1,
+        last_applied_at: {
+            package: options.targetVersion,
+            schema: toPair.schema,
+            agentContract: toPair.agentContract,
+        },
+        deferred_actions: [],
+    };
+    // Step 11: Restart processes from snapshot.
+    //
+    // On the fresh-run path, stopResult.updatedSnapshot is the in-memory
+    // snapshot whose stop_method-per-row was set by the step-4 stop loop. On
+    // resume, stopResult is null — step 4 ran in the original attempt, and the
+    // on-disk processes-snapshot.json carries the stop_method state we need.
+    // Read it fresh from disk in that case (Phase 73 D-11 LOCKED resume-path
+    // refactor — captureResult.snapshot.captured_at is undefined on resume, so
+    // any deferred-action id below MUST derive from the resume-read snapshot).
+    const restartSnapshot = wasResume
+        ? await readProcessesSnapshot(effectiveTargetPath)
+        : stopResult.updatedSnapshot;
+    if (wasResume && restartSnapshot === null) {
+        // Defensive degraded-state path: the marker said we were mid-resume but
+        // processes-snapshot.json is gone. Cannot restart processes blindly;
+        // surface as blocked so the agent re-runs a fresh self-update. Mitigates
+        // T-73-04-06.
+        return {
+            state: "blocked",
+            reason: "resume_snapshot_missing: processes-snapshot.json was deleted between pause and resume",
+        };
+    }
+    const restartResult = await restartFromSnapshot({
+        snapshot: restartSnapshot,
+        env,
+        targetPath: effectiveTargetPath,
+    });
+    if (restartResult.state === "all_restarted") {
+        // WR-02: Receipt-before-cleanup ordering. migration.json is the durable
+        // success marker (Plan 72-08 D-10 step 12); processes-snapshot.json is the
+        // work artifact. If writeMigrationState throws BETWEEN deleteProcessesSnapshot
+        // and the migration-state write, the operator is left with snapshot deleted
+        // AND migration.json missing — the very state-corruption scenario the
+        // staged-write strategy in this phase is designed to prevent. Land the
+        // receipt first, then delete the work artifact.
+        //
+        // Phase 73 D-11: on resume, the success-write must ALSO clear
+        // pending_envelope_resume (chain advanced past the envelope). Preserve
+        // any existing `envelopes` slot history (D-08) — that is recorded-result
+        // evidence and is independent of the in-flight marker.
+        const priorAtSuccess = await readMigrationState(effectiveTargetPath);
+        const successState = {
+            ...baseMigrationState,
+            ...(priorAtSuccess?.envelopes !== undefined
+                ? { envelopes: priorAtSuccess.envelopes }
+                : {}),
+            // pending_envelope_resume omitted → cleared. Mitigates T-73-04-03.
+        };
+        await writeMigrationState(effectiveTargetPath, successState);
+        await deleteProcessesSnapshot(effectiveTargetPath);
+        // Step 12: Emit report (success).
+        return {
+            state: "updated",
+            fromVersion,
+            toVersion: options.targetVersion,
+            actions: rebakeActions,
         };
     }
+    // some_failed → D-19: create a process_restart deferred action; snapshot persists.
+    // Phase 73: on resume, captureResult is null, so the deferred-action id
+    // MUST derive from restartSnapshot.captured_at — the resume-read snapshot
+    // we just used to drive restart, which carries the original step-3 capture
+    // timestamp. On the fresh-run path the two values are identical.
+    const failedRows = restartResult.failed;
+    const snapshotCapturedAt = wasResume
+        ? restartSnapshot.captured_at
+        : captureResult.snapshot.captured_at;
+    const deferredAction = {
+        id: `process_restart_${snapshotCapturedAt}`,
+        description: "One or more managed processes failed to restart after self-update; the runtime probe will re-attempt on the next gdh status invocation.",
+        verify: {
+            kind: "process_restart",
+            payload: {
+                failed_rows: failedRows.map((row) => ({
+                    kind: row.kind,
+                    pid: row.pid,
+                    cmd: row.cmd,
+                })),
+            },
+        },
+        status: "pending",
+    };
+    // Phase 73: clear pending_envelope_resume on the some_failed path too —
+    // the chain advanced past the envelope; only the restart was partial.
+    // Preserve envelopes slot history (D-08).
+    const priorAtPartial = await readMigrationState(effectiveTargetPath);
+    const updatedMigrationState = {
+        ...baseMigrationState,
+        deferred_actions: [deferredAction],
+        ...(priorAtPartial?.envelopes !== undefined
+            ? { envelopes: priorAtPartial.envelopes }
+            : {}),
+        // pending_envelope_resume omitted → cleared.
+    };
+    await writeMigrationState(effectiveTargetPath, updatedMigrationState);
+    return {
+        state: "updated_with_deferred_actions",
+        fromVersion,
+        toVersion: options.targetVersion,
+        actions: rebakeActions,
+        migrationChainResult: chainResult,
+        deferredActions: [{ id: deferredAction.id, kind: deferredAction.verify.kind }],
+        restartFailedRows: failedRows,
+        preservationNotes,
+    };
 }
 /**
- * Capture current content of every file the planned actions will touch, plus the
- * pin config. A `null` value means the file did not exist — rollback is `fs.rm`.
- * Skips actions with null absolutePath (run_command, write_local_hints abstract actions).
+ * Compute workspace-relative POSIX paths for every plan action that has a
+ * concrete absolutePath. Skips abstract actions (run_command,
+ * write_local_hints) whose absolutePath is null.
+ *
+ * WR-08: When an action's `absolutePath` is non-null but resolves OUTSIDE
+ * `effectiveTargetPath`, this is a defensive invariant violation — adapter
+ * outputs are GDH-controlled, so a violation indicates a real upstream bug
+ * (e.g., wrong targetPath resolution upstream) that would silently leave the
+ * surface uncaptured by the durable backup and defeat the rollback contract
+ * for that surface. Fail loud rather than silently dropping the action.
  */
-async function captureOriginals(plannedActions, pinConfigPath) {
-    const originals = new Map();
-    originals.set(pinConfigPath, await fs.readFile(pinConfigPath, "utf8"));
+function computePlannedRelativePaths(plannedActions, effectiveTargetPath) {
+    const relativePaths = [];
     for (const action of plannedActions) {
         if (action.absolutePath === null)
             continue;
-        if (originals.has(action.absolutePath))
-            continue;
-        const existing = await fs
-            .readFile(action.absolutePath, "utf8")
-            .catch(() => null);
-        originals.set(action.absolutePath, existing);
-    }
-    return originals;
-}
-/**
- * Best-effort restore. Iterates captured originals; restores content or rm's
- * previously-absent files. Collects failure messages but continues (rollback-soldier
- * pattern: partial recovery > aborting mid-rollback).
- */
-async function rollbackOriginals(originals) {
-    const failures = [];
-    for (const [absolutePath, content] of originals) {
-        try {
-            if (content === null) {
-                await fs.rm(absolutePath, { force: true });
-            }
-            else {
-                await fs.writeFile(absolutePath, content, "utf8");
-            }
-        }
-        catch (error) {
-            failures.push(`${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+        const rel = path.relative(effectiveTargetPath, action.absolutePath);
+        // WR-08: defensive invariant — adapter outputs are GDH-controlled.
+        // Out-of-workspace absolutePath signals an upstream bug; throw rather
+        // than silently dropping the action (which would defeat the durable-
+        // backup rollback contract for that surface).
+        if (rel.startsWith("..") || path.isAbsolute(rel)) {
+            throw new Error(`assertion: action ${action.agent}/${action.kind}/${action.scope}` +
+                ` (relativePath=${action.relativePath ?? "<null>"}) has absolutePath` +
+                ` outside target ${effectiveTargetPath}: ${action.absolutePath}`);
         }
+        relativePaths.push(rel.split(path.sep).join("/"));
     }
-    return failures;
+    return relativePaths;
+}
+function uniquePaths(paths) {
+    return [...new Set(paths)].sort();
 }
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);