chainlesschain 0.162.198 → 0.162.200

package/src/lib/packer/native-update-state.js

@@ -1,13 +1,28 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
+import os from "node:os";
+import { spawn } from "node:child_process";
+import {
+  sameFileStatIdentity,
+  samePathHandleFileIdentity,
+  samePathHandleStableFileIdentity,
+  withTrustedFileParentSync,
+} from "../secure-file-identity.js";
 
 export const NATIVE_UPDATE_LINEAGE_SCHEMA =
   "chainlesschain.native-update-lineage.v1";
 export const NATIVE_UPDATE_RESULT_SCHEMA =
   "chainlesschain.native-update-result.v1";
+export const NATIVE_GENERATION_TRANSACTION_SCHEMA =
+  "chainlesschain.native-install-transaction.v1";
 export const SHA256_HEX = /^[0-9a-f]{64}$/;
 const UUID =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const NATIVE_LOCK_TOKEN = new RegExp(
+  `^([1-9][0-9]*):(?:[0-9a-f]{32}|${UUID.source.slice(1, -1)})$`,
+  "i",
+);
 const RESULT_STATUS = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 export class NativeUpdateStateError extends Error {
@@ -43,6 +58,7 @@ export function assertSafePathAncestors(filePath, options = {}) {
     platform = process.platform,
     leaf = "any",
     allowMissingLeaf = true,
+    allowPathAliases = false,
   } = options;
   const resolved = path.resolve(filePath);
   const parsed = path.parse(resolved);
@@ -73,7 +89,7 @@ export function assertSafePathAncestors(filePath, options = {}) {
         `${label} ancestor is not a directory: ${current}`,
       );
     }
-    if (!isLeaf && stat.isDirectory()) {
+    if (!allowPathAliases && !isLeaf && stat.isDirectory()) {
       let real;
       try {
         real = fs.realpathSync.native(current);
@@ -139,6 +155,8 @@ export function nativeUpdatePaths(canonicalPath) {
     backupPath: `${canonicalPath}.previous`,
     lockPath: `${canonicalPath}.update.lock`,
     lineagePath: `${canonicalPath}.update-lineage.json`,
+    journalPath: `${canonicalPath}.update-transaction.json`,
+    lastJournalPath: `${canonicalPath}.update-transaction.json.last`,
     resultPath: `${canonicalPath}.update-result.json`,
     lastResultPath: `${canonicalPath}.update-result.last.json`,
   };
@@ -229,6 +247,966 @@ export function nativeResultRequiresRecovery(value) {
   );
 }
 
+const GENERATION_PHASES = new Set([
+  "prepared",
+  "target-committed",
+  "backup-committed",
+  "alias-committed",
+  "verified",
+  "lineage-committed",
+  "committed",
+]);
+
+function readStableRegular(filePath, options = {}) {
+  assertSafeRegularFile(filePath, {
+    label: options.label || "native generation state",
+    allowMissingLeaf: false,
+    platform: options.platform || process.platform,
+  });
+  return withTrustedFileParentSync(
+    fs,
+    filePath,
+    ({ canonicalPath, parentDevice }) =>
+      readStableRegularAtPath(canonicalPath, parentDevice, options),
+  );
+}
+
+function readStableRegularAtPath(filePath, parentDevice, options) {
+  const { capture = false, maxBytes = 1024 * 1024 } = options;
+  const fd = fs.openSync(filePath, "r");
+  try {
+    const before = fs.fstatSync(fd, { bigint: true });
+    const pathBefore = fs.lstatSync(filePath, { bigint: true });
+    const hash = crypto.createHash("sha256");
+    const chunks = [];
+    let capturedBytes = 0;
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let offset = 0;
+    for (;;) {
+      const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, offset);
+      if (bytesRead === 0) break;
+      const chunk = buffer.subarray(0, bytesRead);
+      hash.update(chunk);
+      offset += bytesRead;
+      if (capture) {
+        capturedBytes += bytesRead;
+        if (capturedBytes > maxBytes) {
+          throw new NativeUpdateStateError(
+            `${options.label || "native generation state"} is oversized`,
+            "TRANSACTION_INVALID",
+          );
+        }
+        chunks.push(Buffer.from(chunk));
+      }
+    }
+    const after = fs.fstatSync(fd, { bigint: true });
+    const pathAfter = fs.lstatSync(filePath, { bigint: true });
+    const stable =
+      before.isFile() &&
+      pathBefore.isFile() &&
+      after.isFile() &&
+      pathAfter.isFile() &&
+      before.nlink > 0n &&
+      samePathHandleFileIdentity(pathBefore, before, parentDevice) &&
+      sameFileStatIdentity(before, after) &&
+      samePathHandleFileIdentity(pathAfter, after, parentDevice);
+    if (!stable) {
+      throw new NativeUpdateStateError(
+        `${options.label || "native generation state"} changed while read`,
+        "TRANSACTION_CHANGED",
+      );
+    }
+    return {
+      bytes: capture ? Buffer.concat(chunks) : null,
+      sha256: hash.digest("hex"),
+      parentDevice,
+      stat: after,
+    };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function fsyncNativeDirectory(directoryPath) {
+  let fd;
+  try {
+    fd = fs.openSync(directoryPath, "r");
+    fs.fsyncSync(fd);
+  } catch (error) {
+    if (
+      !["EACCES", "EBADF", "EINVAL", "EISDIR", "ENOTSUP", "EPERM"].includes(
+        error?.code,
+      )
+    ) {
+      throw error;
+    }
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function fsyncNativeFileDescriptor(fd) {
+  try {
+    fs.fsyncSync(fd);
+  } catch (error) {
+    if (!["EBADF", "EINVAL", "ENOTSUP", "EPERM"].includes(error?.code)) {
+      throw error;
+    }
+  }
+}
+
+function parseGenerationJournal(journalPath, platform) {
+  const { bytes } = readStableRegular(journalPath, {
+    capture: true,
+    label: "native generation transaction journal",
+    platform,
+  });
+  let value;
+  try {
+    value = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    throw new NativeUpdateStateError(
+      `native generation transaction journal is corrupt: ${error.message}`,
+      "TRANSACTION_INVALID",
+    );
+  }
+  const validBefore = (present, digest) =>
+    typeof present === "boolean" &&
+    (present ? SHA256_HEX.test(digest || "") : digest === null);
+  const valid =
+    value?.schema === NATIVE_GENERATION_TRANSACTION_SCHEMA &&
+    UUID.test(value.transactionId || "") &&
+    ["install", "update", "rescue"].includes(value.operation) &&
+    (platform !== "win32" ||
+      (Number.isSafeInteger(value.ownerPid) && value.ownerPid > 0)) &&
+    GENERATION_PHASES.has(value.phase) &&
+    ["rollback", "commit"].includes(value.decision) &&
+    (value.phase === "committed") === (value.decision === "commit") &&
+    SHA256_HEX.test(value.expectedSha256 || "") &&
+    validBefore(value.hadTarget, value.targetBeforeSha256) &&
+    validBefore(value.hadBackup, value.backupBeforeSha256) &&
+    validBefore(value.hadAlias, value.aliasBeforeSha256) &&
+    validBefore(value.hadLineage, value.lineageBeforeSha256);
+  if (!valid) {
+    throw new NativeUpdateStateError(
+      "native generation transaction journal failed schema validation",
+      "TRANSACTION_INVALID",
+    );
+  }
+  return value;
+}
+
+function stableRegularShaOrNull(filePath, platform, label) {
+  const stat = lstatOrNull(filePath);
+  if (!stat) return null;
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new NativeUpdateStateError(`${label} has an unsafe file type`);
+  }
+  return readStableRegular(filePath, { label, platform }).sha256;
+}
+
+function stableAliasShaOrNull(aliasPath) {
+  if (!lstatOrNull(aliasPath)) return null;
+  const before = fs.lstatSync(aliasPath, { bigint: true });
+  if (!before.isSymbolicLink()) {
+    throw new NativeUpdateStateError(
+      "native generation alias has an unsafe file type",
+    );
+  }
+  const rawTarget = fs.readlinkSync(aliasPath);
+  const after = fs.lstatSync(aliasPath, { bigint: true });
+  if (
+    !after.isSymbolicLink() ||
+    before.dev !== after.dev ||
+    before.ino !== after.ino ||
+    before.size !== after.size ||
+    before.mtimeNs !== after.mtimeNs ||
+    before.ctimeNs !== after.ctimeNs
+  ) {
+    throw new NativeUpdateStateError(
+      "native generation alias changed while read",
+      "TRANSACTION_CHANGED",
+    );
+  }
+  return crypto
+    .createHash("sha256")
+    .update(Buffer.from(rawTarget))
+    .digest("hex");
+}
+
+function restoreRegularGeneration(
+  sourcePath,
+  destinationPath,
+  expectedSha,
+  transactionId,
+  platform,
+  label,
+) {
+  if (
+    stableRegularShaOrNull(sourcePath, platform, `${label} snapshot`) !==
+    expectedSha
+  ) {
+    throw new NativeUpdateStateError(
+      `${label} recovery snapshot is missing or changed`,
+      "RECOVERY_FAILED",
+    );
+  }
+  const stagingPath = `${destinationPath}.restart-recovery-${transactionId}`;
+  if (lstatOrNull(stagingPath)) {
+    throw new NativeUpdateStateError(
+      `${label} recovery staging path already exists`,
+      "RECOVERY_FAILED",
+    );
+  }
+  try {
+    fs.copyFileSync(sourcePath, stagingPath, fs.constants.COPYFILE_EXCL);
+    try {
+      fs.chmodSync(stagingPath, fs.statSync(sourcePath).mode);
+    } catch {
+      /* mode preservation is best effort on filesystems without POSIX modes */
+    }
+    const fd = fs.openSync(stagingPath, "r");
+    try {
+      fsyncNativeFileDescriptor(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    if (
+      stableRegularShaOrNull(
+        stagingPath,
+        platform,
+        `${label} recovery staging`,
+      ) !== expectedSha
+    ) {
+      throw new NativeUpdateStateError(
+        `${label} recovery staging changed`,
+        "RECOVERY_FAILED",
+      );
+    }
+    fs.renameSync(stagingPath, destinationPath);
+    fsyncNativeDirectory(path.dirname(destinationPath));
+    if (
+      stableRegularShaOrNull(destinationPath, platform, label) !== expectedSha
+    ) {
+      throw new NativeUpdateStateError(
+        `${label} recovery verification failed`,
+        "RECOVERY_FAILED",
+      );
+    }
+  } finally {
+    try {
+      const stat = fs.lstatSync(stagingPath);
+      if (stat.isFile() && !stat.isSymbolicLink()) fs.unlinkSync(stagingPath);
+    } catch {
+      /* absent or unsafe staging is retained */
+    }
+  }
+}
+
+function retireKnownRegular(
+  filePath,
+  allowedHashes,
+  transactionId,
+  platform,
+  label,
+) {
+  const current = stableRegularShaOrNull(filePath, platform, label);
+  if (current === null) return;
+  if (!allowedHashes.filter(Boolean).includes(current)) {
+    throw new NativeUpdateStateError(
+      `${label} has an unknown generation`,
+      "RECOVERY_FAILED",
+    );
+  }
+  const retiredPath = `${filePath}.restart-retired-${transactionId}`;
+  if (lstatOrNull(retiredPath)) {
+    throw new NativeUpdateStateError(
+      `${label} retirement path already exists`,
+      "RECOVERY_FAILED",
+    );
+  }
+  fs.renameSync(filePath, retiredPath);
+  fsyncNativeDirectory(path.dirname(filePath));
+}
+
+function lineageMatchesGeneration(
+  lineagePath,
+  transactionId,
+  expectedSha,
+  platform,
+) {
+  if (
+    stableRegularShaOrNull(lineagePath, platform, "native update lineage") ===
+    null
+  ) {
+    return false;
+  }
+  let value;
+  try {
+    value = JSON.parse(
+      readStableRegular(lineagePath, {
+        capture: true,
+        label: "native update lineage",
+        platform,
+      }).bytes.toString("utf8"),
+    );
+  } catch {
+    return false;
+  }
+  return (
+    value?.schema === NATIVE_UPDATE_LINEAGE_SCHEMA &&
+    value.transactionId === transactionId &&
+    value.currentSha256 === expectedSha
+  );
+}
+
+function acquireGenerationRecoveryLock(lockPath, platform) {
+  const current = lstatOrNull(lockPath);
+  if (current) {
+    const { bytes, parentDevice, stat } = readStableRegular(lockPath, {
+      capture: true,
+      maxBytes: 128,
+      label: "stale native update lock",
+      platform,
+    });
+    const token = bytes.toString("utf8");
+    const match = NATIVE_LOCK_TOKEN.exec(token);
+    if (!match) {
+      throw new NativeUpdateStateError(
+        "stale native update lock token is invalid",
+        "RECOVERY_LOCK_INVALID",
+      );
+    }
+    try {
+      process.kill(Number(match[1]), 0);
+      throw new NativeUpdateStateError(
+        `native update lock owner PID ${match[1]} is still live`,
+        "RECOVERY_LOCK_LIVE",
+      );
+    } catch (error) {
+      if (error instanceof NativeUpdateStateError) throw error;
+      if (error?.code !== "ESRCH") {
+        throw new NativeUpdateStateError(
+          `could not prove stale native update lock ownership: ${error.message}`,
+          "RECOVERY_LOCK_LIVE",
+        );
+      }
+    }
+    const orphanPath = `${lockPath}.orphaned-${crypto.randomUUID()}`;
+    fs.renameSync(lockPath, orphanPath);
+    const orphan = fs.lstatSync(orphanPath, { bigint: true });
+    if (!samePathHandleStableFileIdentity(orphan, stat, parentDevice)) {
+      throw new NativeUpdateStateError(
+        "stale native update lock changed during quarantine",
+        "RECOVERY_LOCK_CHANGED",
+      );
+    }
+    fsyncNativeDirectory(path.dirname(lockPath));
+  }
+  const token = `${process.pid}:${crypto.randomUUID()}`;
+  const fd = fs.openSync(lockPath, "wx+", 0o600);
+  try {
+    fs.writeFileSync(fd, token, "utf8");
+    fsyncNativeFileDescriptor(fd);
+    return { fd, lockPath, token };
+  } catch (error) {
+    try {
+      const owned = fs.fstatSync(fd, { bigint: true });
+      const currentLock = fs.lstatSync(lockPath, { bigint: true });
+      if (
+        currentLock.isFile() &&
+        !currentLock.isSymbolicLink() &&
+        owned.dev === currentLock.dev &&
+        owned.ino === currentLock.ino
+      ) {
+        fs.unlinkSync(lockPath);
+        fsyncNativeDirectory(path.dirname(lockPath));
+      }
+    } catch {
+      /* retain ambiguous ownership evidence and fail closed */
+    }
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* the original persistence error is authoritative */
+    }
+    throw error;
+  }
+}
+
+function releaseGenerationRecoveryLock(lock, success) {
+  fs.closeSync(lock.fd);
+  if (!success) return;
+  const stat = lstatOrNull(lock.lockPath);
+  if (
+    stat?.isFile() &&
+    !stat.isSymbolicLink() &&
+    fs.readFileSync(lock.lockPath, "utf8") === lock.token
+  ) {
+    fs.unlinkSync(lock.lockPath);
+    fsyncNativeDirectory(path.dirname(lock.lockPath));
+  }
+}
+
+function windowsRecoveryWrapperSource() {
+  return [
+    "@echo off",
+    "setlocal EnableExtensions DisableDelayedExpansion",
+    'set "CC_RECOVERY_EXIT=1"',
+    '> "%CC_RECOVERY_READY_TEMP%" echo %CC_RECOVERY_TRANSACTION_ID%',
+    "if errorlevel 1 goto cleanup",
+    'move /Y "%CC_RECOVERY_READY_TEMP%" "%CC_RECOVERY_READY%" >NUL 2>&1',
+    "if errorlevel 1 goto cleanup",
+    "set /a CC_RECOVERY_ATTEMPTS=0",
+    ":waitloop",
+    '"%CC_RECOVERY_SYSTEM_ROOT%\\System32\\tasklist.exe" /FI "PID eq %CC_RECOVERY_PARENT_PID%" /FO CSV /NH > "%CC_RECOVERY_PARENT_PROBE%" 2>NUL',
+    "if errorlevel 1 goto cleanup",
+    '"%CC_RECOVERY_SYSTEM_ROOT%\\System32\\findstr.exe" /L /C:"%CC_RECOVERY_PARENT_PID%" "%CC_RECOVERY_PARENT_PROBE%" >NUL 2>&1',
+    "if errorlevel 1 goto runrecovery",
+    "set /a CC_RECOVERY_ATTEMPTS=%CC_RECOVERY_ATTEMPTS%+1",
+    "if %CC_RECOVERY_ATTEMPTS% GEQ 120 goto cleanup",
+    '"%CC_RECOVERY_SYSTEM_ROOT%\\System32\\ping.exe" -n 2 -w 1000 127.0.0.1 >NUL',
+    "if errorlevel 1 goto cleanup",
+    "goto waitloop",
+    ":runrecovery",
+    'set "CC_CLI_INSTALL_DIR=%CC_RECOVERY_INSTALL_DIR%"',
+    'set "CC_CLI_INSTALL_RECOVERY_ONLY=1"',
+    '"%CC_RECOVERY_POWERSHELL%" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "%CC_RECOVERY_INSTALLER%"',
+    'set "CC_RECOVERY_EXIT=%ERRORLEVEL%"',
+    ":cleanup",
+    'del /F /Q "%CC_RECOVERY_READY_TEMP%" >NUL 2>&1',
+    'del /F /Q "%CC_RECOVERY_READY%" >NUL 2>&1',
+    'del /F /Q "%CC_RECOVERY_PARENT_PROBE%" >NUL 2>&1',
+    'del /F /Q "%CC_RECOVERY_INSTALLER%" >NUL 2>&1',
+    '(goto) 2>NUL & del /F /Q "%~f0" & exit /b %CC_RECOVERY_EXIT%',
+  ].join("\r\n");
+}
+
+function waitForWindowsRecoveryReady(readyPath, transactionId, timeoutMs) {
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const value = fs.readFileSync(readyPath, "utf8").trim();
+      if (value === transactionId) return true;
+      if (value) return false;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    Atomics.wait(sleeper, 0, 0, 25);
+  }
+  return false;
+}
+
+function resolveTrustedWindowsPowerShell() {
+  if (process.platform !== "win32") {
+    return {
+      powershellPath: String.raw`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`,
+      systemRoot: String.raw`C:\Windows`,
+    };
+  }
+  let systemRoot;
+  try {
+    systemRoot = path.win32.resolve(
+      fs.realpathSync.native(String.raw`\\?\GLOBALROOT\SystemRoot`),
+    );
+  } catch (error) {
+    throw new NativeUpdateStateError(
+      `could not resolve the trusted Windows system root: ${error.message}`,
+      "WINDOWS_SYSTEM_ROOT_UNAVAILABLE",
+    );
+  }
+  if (!/^[A-Za-z]:\\/.test(systemRoot) || systemRoot.includes("\0")) {
+    throw new NativeUpdateStateError(
+      "the trusted Windows system root resolved to an invalid path",
+      "WINDOWS_SYSTEM_ROOT_UNAVAILABLE",
+    );
+  }
+  return {
+    powershellPath: path.win32.join(
+      systemRoot,
+      "System32",
+      "WindowsPowerShell",
+      "v1.0",
+      "powershell.exe",
+    ),
+    systemRoot,
+  };
+}
+
+function scheduleWindowsGenerationRecovery(options) {
+  const {
+    canonicalPath,
+    statePaths,
+    journal,
+    stderr,
+    spawnImpl = spawn,
+    tmpRoot = os.tmpdir(),
+    installerBytes,
+    powershellPath,
+    cmdPath,
+    readyTimeoutMs = 10_000,
+    waitForReadyImpl = waitForWindowsRecoveryReady,
+  } = options;
+  try {
+    process.kill(journal.ownerPid, 0);
+    throw new NativeUpdateStateError(
+      `native generation owner PID ${journal.ownerPid} is still live`,
+      "RECOVERY_OWNER_LIVE",
+    );
+  } catch (error) {
+    if (error instanceof NativeUpdateStateError) throw error;
+    if (error?.code !== "ESRCH") {
+      throw new NativeUpdateStateError(
+        `could not prove native generation owner retirement: ${error.message}`,
+        "RECOVERY_OWNER_LIVE",
+      );
+    }
+  }
+
+  const lock = acquireGenerationRecoveryLock(statePaths.lockPath, "win32");
+  let child = null;
+  let scheduled = false;
+  let wrapperPath = null;
+  let installerPath = null;
+  let readyPath = null;
+  let readyTempPath = null;
+  let parentProbePath = null;
+  try {
+    const suffix = journal.transactionId.replaceAll("-", "");
+    const rawTmpRoot = path.resolve(tmpRoot);
+    assertSafePathAncestors(rawTmpRoot, {
+      label: "raw Windows recovery temporary root",
+      allowMissingLeaf: false,
+      allowPathAliases: true,
+      leaf: "directory",
+      platform: "win32",
+    });
+    const canonicalTmpRoot = fs.realpathSync.native(rawTmpRoot);
+    assertSafePathAncestors(canonicalTmpRoot, {
+      label: "canonical Windows recovery temporary root",
+      allowMissingLeaf: false,
+      leaf: "directory",
+      platform: "win32",
+    });
+    wrapperPath = path.join(
+      canonicalTmpRoot,
+      `cc-native-recovery-${suffix}.cmd`,
+    );
+    installerPath = path.join(
+      canonicalTmpRoot,
+      `cc-native-recovery-installer-${suffix}.ps1`,
+    );
+    readyPath = `${wrapperPath}.ready`;
+    readyTempPath = `${readyPath}.tmp-${journal.transactionId}`;
+    parentProbePath = `${wrapperPath}.parent`;
+    const trustedPowerShell = resolveTrustedWindowsPowerShell();
+    const resolvedPowerShell =
+      powershellPath || trustedPowerShell.powershellPath;
+    const resolvedCmd =
+      cmdPath ||
+      path.win32.join(trustedPowerShell.systemRoot, "System32", "cmd.exe");
+    for (const [label, filePath] of Object.entries({
+      "Windows recovery wrapper": wrapperPath,
+      "Windows recovery installer": installerPath,
+      "Windows recovery readiness marker": readyPath,
+      "Windows recovery readiness staging": readyTempPath,
+      "Windows recovery parent probe": parentProbePath,
+    })) {
+      assertSafeRegularFile(filePath, {
+        label,
+        allowMissingLeaf: true,
+        platform: "win32",
+      });
+      if (lstatOrNull(filePath)) {
+        throw new NativeUpdateStateError(
+          `${label} already exists`,
+          "RECOVERY_SCHEDULE_FAILED",
+        );
+      }
+    }
+    assertSafeRegularFile(resolvedPowerShell, {
+      label: "trusted Windows PowerShell",
+      allowMissingLeaf: false,
+      platform: "win32",
+    });
+    assertSafeRegularFile(resolvedCmd, {
+      label: "trusted Windows command processor",
+      allowMissingLeaf: false,
+      platform: "win32",
+    });
+    const recoveryInstallerBytes =
+      installerBytes ||
+      fs.readFileSync(new URL("../../../install/install.ps1", import.meta.url));
+    fs.writeFileSync(installerPath, recoveryInstallerBytes, {
+      flag: "wx",
+      mode: 0o600,
+    });
+    const installerFd = fs.openSync(installerPath, "r+");
+    try {
+      fsyncNativeFileDescriptor(installerFd);
+    } finally {
+      fs.closeSync(installerFd);
+    }
+    fs.writeFileSync(wrapperPath, windowsRecoveryWrapperSource(), {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    const wrapperFd = fs.openSync(wrapperPath, "r+");
+    try {
+      fsyncNativeFileDescriptor(wrapperFd);
+    } finally {
+      fs.closeSync(wrapperFd);
+    }
+    fsyncNativeDirectory(canonicalTmpRoot);
+    child = spawnImpl(resolvedCmd, ["/d", "/c", wrapperPath], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      shell: false,
+      env: {
+        ...process.env,
+        SystemRoot: trustedPowerShell.systemRoot,
+        windir: trustedPowerShell.systemRoot,
+        CC_RECOVERY_SYSTEM_ROOT: trustedPowerShell.systemRoot,
+        CC_RECOVERY_POWERSHELL: resolvedPowerShell,
+        CC_RECOVERY_PARENT_PID: String(process.pid),
+        CC_RECOVERY_INSTALL_DIR: path.dirname(canonicalPath),
+        CC_RECOVERY_INSTALLER: installerPath,
+        CC_RECOVERY_READY: readyPath,
+        CC_RECOVERY_READY_TEMP: readyTempPath,
+        CC_RECOVERY_PARENT_PROBE: parentProbePath,
+        CC_RECOVERY_TRANSACTION_ID: journal.transactionId,
+      },
+    });
+    child.on?.("error", () => {});
+    if (!waitForReadyImpl(readyPath, journal.transactionId, readyTimeoutMs)) {
+      child.kill?.();
+      child.unref?.();
+      throw new NativeUpdateStateError(
+        "Windows recovery sidecar did not publish readiness",
+        "RECOVERY_SCHEDULE_FAILED",
+      );
+    }
+    child.unref?.();
+    scheduled = true;
+    stderr.write(
+      `Scheduled Windows native generation recovery; rerun the CLI after transaction=${journal.transactionId}\n`,
+    );
+    return {
+      outcome: "scheduled",
+      transactionId: journal.transactionId,
+      requiresRestart: true,
+    };
+  } finally {
+    releaseGenerationRecoveryLock(lock, false);
+    if (!scheduled) {
+      for (const filePath of [readyPath, readyTempPath, parentProbePath].filter(
+        Boolean,
+      )) {
+        try {
+          if (lstatOrNull(filePath)?.isFile()) fs.unlinkSync(filePath);
+        } catch {
+          /* retain ambiguous transient evidence */
+        }
+      }
+      for (const filePath of [wrapperPath, installerPath].filter(Boolean)) {
+        try {
+          if (lstatOrNull(filePath)?.isFile()) fs.unlinkSync(filePath);
+        } catch {
+          /* retain ambiguous recovery evidence */
+        }
+      }
+    }
+  }
+}
+
+/** Resolve a durable installer/OTA generation decision before normal startup. */
+export function recoverPendingNativeGeneration(options = {}) {
+  const {
+    targetExePath = process.execPath,
+    platform = process.platform,
+    packed = Boolean(process.pkg),
+    force = false,
+    stderr = process.stderr,
+  } = options;
+  if (!force && !packed) return null;
+  const normalizedPlatform = platform === "win32" ? "win32" : "posix";
+  const { canonicalPath } = resolveNativeLayout(
+    targetExePath,
+    normalizedPlatform,
+  );
+  const statePaths = nativeUpdatePaths(canonicalPath);
+  if (!lstatOrNull(statePaths.journalPath)) return null;
+  const journal = parseGenerationJournal(
+    statePaths.journalPath,
+    normalizedPlatform,
+  );
+  if (normalizedPlatform === "win32") {
+    return scheduleWindowsGenerationRecovery({
+      ...options,
+      canonicalPath,
+      statePaths,
+      journal,
+      stderr,
+    });
+  }
+  const directory = path.dirname(canonicalPath);
+  const aliasPath = path.join(directory, "cc");
+  const transactionId = journal.transactionId;
+  const priorTarget = path.join(
+    directory,
+    `.chainlesschain.target-prior-${transactionId}`,
+  );
+  const priorBackup = path.join(
+    directory,
+    `.chainlesschain.backup-prior-${transactionId}`,
+  );
+  const priorAlias = path.join(directory, `.cc.prior-${transactionId}`);
+  const priorLineage = path.join(
+    directory,
+    `.chainlesschain.lineage-prior-${transactionId}`,
+  );
+  const canonicalAliasSha = crypto
+    .createHash("sha256")
+    .update(Buffer.from("chainlesschain"))
+    .digest("hex");
+  const lock = acquireGenerationRecoveryLock(
+    statePaths.lockPath,
+    normalizedPlatform,
+  );
+  let success = false;
+  try {
+    const targetSha = stableRegularShaOrNull(
+      canonicalPath,
+      normalizedPlatform,
+      "native target",
+    );
+    if (journal.decision === "commit") {
+      if (targetSha !== journal.expectedSha256) {
+        throw new NativeUpdateStateError(
+          "committed native target does not match its durable decision",
+          "RECOVERY_FAILED",
+        );
+      }
+      const expectedBackup =
+        journal.operation === "rescue"
+          ? journal.hadBackup
+            ? journal.backupBeforeSha256
+            : null
+          : journal.hadTarget
+            ? journal.targetBeforeSha256
+            : null;
+      if (
+        stableRegularShaOrNull(
+          statePaths.backupPath,
+          normalizedPlatform,
+          "native backup",
+        ) !== expectedBackup
+      ) {
+        throw new NativeUpdateStateError(
+          "committed native backup does not match its durable decision",
+          "RECOVERY_FAILED",
+        );
+      }
+      if (
+        journal.operation === "install" &&
+        stableAliasShaOrNull(aliasPath) !== canonicalAliasSha
+      ) {
+        throw new NativeUpdateStateError(
+          "committed native alias does not match its durable decision",
+          "RECOVERY_FAILED",
+        );
+      }
+      if (
+        !lineageMatchesGeneration(
+          statePaths.lineagePath,
+          transactionId,
+          journal.expectedSha256,
+          normalizedPlatform,
+        )
+      ) {
+        throw new NativeUpdateStateError(
+          "committed native lineage does not match its durable decision",
+          "RECOVERY_FAILED",
+        );
+      }
+    } else {
+      if (journal.hadTarget) {
+        if (
+          ![journal.targetBeforeSha256, journal.expectedSha256, null].includes(
+            targetSha,
+          )
+        ) {
+          throw new NativeUpdateStateError(
+            "interrupted native target has an unknown generation",
+            "RECOVERY_FAILED",
+          );
+        }
+        if (targetSha !== journal.targetBeforeSha256) {
+          restoreRegularGeneration(
+            priorTarget,
+            canonicalPath,
+            journal.targetBeforeSha256,
+            transactionId,
+            normalizedPlatform,
+            "native target",
+          );
+        }
+      } else {
+        retireKnownRegular(
+          canonicalPath,
+          [journal.expectedSha256],
+          transactionId,
+          normalizedPlatform,
+          "fresh native target",
+        );
+      }
+
+      const backupSha = stableRegularShaOrNull(
+        statePaths.backupPath,
+        normalizedPlatform,
+        "native backup",
+      );
+      if (journal.hadBackup) {
+        if (
+          ![
+            journal.backupBeforeSha256,
+            journal.targetBeforeSha256,
+            null,
+          ].includes(backupSha)
+        ) {
+          throw new NativeUpdateStateError(
+            "interrupted native backup has an unknown generation",
+            "RECOVERY_FAILED",
+          );
+        }
+        if (backupSha !== journal.backupBeforeSha256) {
+          restoreRegularGeneration(
+            priorBackup,
+            statePaths.backupPath,
+            journal.backupBeforeSha256,
+            transactionId,
+            normalizedPlatform,
+            "native backup",
+          );
+        }
+      } else {
+        retireKnownRegular(
+          statePaths.backupPath,
+          [journal.targetBeforeSha256],
+          transactionId,
+          normalizedPlatform,
+          "fresh native backup",
+        );
+      }
+
+      if (journal.operation === "install") {
+        const aliasSha = stableAliasShaOrNull(aliasPath);
+        if (journal.hadAlias) {
+          if (
+            ![journal.aliasBeforeSha256, canonicalAliasSha, null].includes(
+              aliasSha,
+            )
+          ) {
+            throw new NativeUpdateStateError(
+              "interrupted native alias has an unknown generation",
+              "RECOVERY_FAILED",
+            );
+          }
+          if (aliasSha !== journal.aliasBeforeSha256) {
+            const rawTarget = fs.readlinkSync(priorAlias);
+            const stagingAlias = `${aliasPath}.restart-recovery-${transactionId}`;
+            fs.symlinkSync(rawTarget, stagingAlias);
+            fs.renameSync(stagingAlias, aliasPath);
+            fsyncNativeDirectory(directory);
+          }
+        } else if (aliasSha !== null) {
+          if (aliasSha !== canonicalAliasSha) {
+            throw new NativeUpdateStateError(
+              "fresh native alias has an unknown generation",
+              "RECOVERY_FAILED",
+            );
+          }
+          const retiredAlias = `${aliasPath}.restart-retired-${transactionId}`;
+          fs.renameSync(aliasPath, retiredAlias);
+          fsyncNativeDirectory(directory);
+        }
+      }
+
+      const lineageSha = stableRegularShaOrNull(
+        statePaths.lineagePath,
+        normalizedPlatform,
+        "native lineage",
+      );
+      if (journal.hadLineage) {
+        if (lineageSha !== journal.lineageBeforeSha256) {
+          if (
+            lineageSha !== null &&
+            !lineageMatchesGeneration(
+              statePaths.lineagePath,
+              transactionId,
+              journal.expectedSha256,
+              normalizedPlatform,
+            )
+          ) {
+            throw new NativeUpdateStateError(
+              "interrupted native lineage has an unknown generation",
+              "RECOVERY_FAILED",
+            );
+          }
+          restoreRegularGeneration(
+            priorLineage,
+            statePaths.lineagePath,
+            journal.lineageBeforeSha256,
+            transactionId,
+            normalizedPlatform,
+            "native lineage",
+          );
+        }
+      } else if (lineageSha !== null) {
+        if (
+          !lineageMatchesGeneration(
+            statePaths.lineagePath,
+            transactionId,
+            journal.expectedSha256,
+            normalizedPlatform,
+          )
+        ) {
+          throw new NativeUpdateStateError(
+            "fresh native lineage has an unknown generation",
+            "RECOVERY_FAILED",
+          );
+        }
+        retireKnownRegular(
+          statePaths.lineagePath,
+          [lineageSha],
+          transactionId,
+          normalizedPlatform,
+          "fresh native lineage",
+        );
+      }
+    }
+
+    assertSafeRegularFile(statePaths.lastJournalPath, {
+      label: "retired native generation journal",
+      allowMissingLeaf: true,
+      platform: normalizedPlatform,
+    });
+    fs.renameSync(statePaths.journalPath, statePaths.lastJournalPath);
+    fsyncNativeDirectory(directory);
+    success = true;
+    const outcome = journal.decision === "commit" ? "committed" : "rolled-back";
+    stderr.write(
+      `Recovered interrupted native generation: ${outcome}, transaction=${transactionId}\n`,
+    );
+    return { outcome, transactionId, journal };
+  } finally {
+    releaseGenerationRecoveryLock(lock, success);
+  }
+}
+
 /**
  * Consume the detached Windows sidecar result on the next packed invocation.
  * The consumed record is atomically retained as `.last.json` for diagnostics.