@evomap/evolver-proxy 2.0.2 → 2.0.8

package/dist/selfUpdate/migration.js

@@ -9,40 +9,47 @@
 //   RESOLVE  (version / asset name / dest path)
 //   DOWNLOAD (signed manifest + binary staged under tmpdir)
 //   VERIFY   (ed25519 manifest signature + sha256 + real preflight probe)
-//   INSTALL  (atomic copy into <home>/bin; unverified bytes are never written)
-//   REGISTER (spawn `evolver lifecycle bootstrap` with EVOLVER_SELF_UPDATE_TARGET_PATH=dest)
+//   INSTALL  (validate target ownership; publish verified bytes atomically without replacement)
+//   REGISTER (delegate to the lifecycle bootstrap transaction runner with absolute deadlines)
 //
 // Migration is a convenience, never an escalation: it is skipped when disabled
 // (EVOLVER_BOOTSTRAP_MIGRATION=0|off), for root (non-win32), CI, containers, within a
-// bootstrap-failure cooldown window, and on unsupported platforms. Every failure degrades
-// back to the existing 'off + warning' startup and records a bootstrap attempt marker so
-// the cooldown applies. All I/O is injectable for tests.
-import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { chmod as fsChmod, lstat, mkdir as fsMkdir, readFile as fsReadFile, rename as fsRename, rm as fsRm, writeFile as fsWriteFile, } from 'node:fs/promises';
+// bootstrap-failure cooldown window, and on unsupported platforms. Clean failures degrade
+// to the existing 'off + warning' startup; ambiguous child/process-tree ownership requires
+// foreground exit. Clean failures use cooldown; ambiguous ownership writes a durable blocker
+// that keeps later foreground startups fail-closed until signed lifecycle reconciliation
+// proves a committed or cleanly rolled-back terminal outcome.
+import { execFileSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { chmod as fsChmod, link as fsLink, lstat, mkdir as fsMkdir, open as fsOpen, readFile as fsReadFile, realpath as fsRealpath, rename as fsRename, rm as fsRm, rmdir as fsRmdir, unlink as fsUnlink, writeFile as fsWriteFile, } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { ops } from '@evomap/evolver-core';
+import { dirname, isAbsolute, join, parse as parsePath, relative, resolve as resolvePath, win32 } from 'node:path';
+import { ops, util } from '@evomap/evolver-core';
 import { SELF_UPDATE_FAILURE_CODES } from './failureCodes.js';
 import { resolveSelfUpdatePublicKey } from './builtinKey.js';
 import { downloadGithubReleaseArtifact, releaseAssetName, resolveGithubReleaseManifest, } from './releaseBinary.js';
 import { preflightManagedStagedBinary } from './transaction.js';
 import { getCurrentVersion } from './version.js';
-import { looksLikeContainer, recentBootstrapFailure, recordBootstrapAttempt, resolveBootstrapCliInvocation, resolveBootstrapStateDir, } from './bootstrap.js';
-/** Advisory migration state marker written next to the bootstrap attempt marker. */
-export const MIGRATION_STATE_FILE = 'migration.json';
-/**
- * The CLI-side service activation itself spawns up to ~60s (lifecycle powershell/schtasks
- * activation), so a shorter timeout would kill the child mid-activation and leave the
- * installed binary registered as failed. Mirrors the bootstrap timeout rationale.
- */
-export const MIGRATION_REGISTER_TIMEOUT_MS = 90_000;
+import { looksLikeContainer, recentBootstrapFailure, recordBootstrapAttempt, resolveBootstrapStateDir, } from './bootstrap.js';
+/** Canonical migration transaction state written next to the bootstrap attempt marker. */
+const MIGRATION_STATE_FILE = 'migration.json';
+// Keep the child transaction deadline shorter than its parent observation deadline so the
+// child can durably roll back before process-tree containment becomes necessary.
+const MIGRATION_REGISTER_TRANSACTION_BUDGET_MS = 180_000;
+const MIGRATION_REGISTER_TIMEOUT_MS = 210_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const MAX_MIGRATION_DETAIL_LENGTH = 512;
+const MAX_MIGRATION_STATE_BYTES = 16 * 1024;
+const MIGRATION_LOCK_FILE = '.evolver-standalone-migration.lock';
+const BOOTSTRAP_ATTEMPT_FILE = 'bootstrap-attempt.json';
+const HOST_WINDOWS_SYSTEM_ROOT = process.env['SystemRoot']?.trim() || 'C:\\Windows';
 /**
  * Migration install home — mirrors the CLI-side lifecyclePaths home resolution
  * (kept dependency-free across packages): EVOLVER_HOME ?? EVOMAP_HOME ?? ~/.evomap.
  */
 export function resolveMigrationHome(env) {
-    return env['EVOLVER_HOME'] ?? env['EVOMAP_HOME'] ?? join(homedir(), '.evomap');
+    return resolvePath(env['EVOLVER_HOME'] ?? env['EVOMAP_HOME'] ?? join(homedir(), '.evomap'));
 }
 /** Migration install path for this platform: <home>/bin/<releaseAssetName>. Throws on unsupported platforms. */
 export function resolveMigrationDestPath(env, platform = process.platform, arch = process.arch) {
@@ -60,23 +67,480 @@ export function resolveMigrationVersion(env) {
     return ops.normalizeConcreteVersion(getCurrentVersion());
 }
 const defaultReadTextFile = (path) => readFileSync(path, 'utf8');
+function assertTrustedMigrationStateLeafSync(path, options = {}) {
+    const existing = statMigrationStateLeafSync(path);
+    if (options.assertStateFileTrust) {
+        options.assertStateFileTrust(path);
+    }
+    else if (process.platform === 'win32') {
+        assertWindowsMigrationAclTrusted([{ path, parentOnly: false }]);
+    }
+    else {
+        const uid = resolveProcessUid();
+        if ((uid !== undefined && existing.uid !== BigInt(uid)) || (existing.mode & 18n) !== 0n) {
+            throw new Error('untrusted_migration_state_leaf');
+        }
+    }
+    return existing;
+}
+function statMigrationStateLeafSync(path) {
+    const existing = lstatSync(path, { bigint: true });
+    if (existing.isSymbolicLink() || !existing.isFile() || existing.nlink !== 1n) {
+        throw new Error('unsafe_migration_state_leaf');
+    }
+    return existing;
+}
+function sameMigrationStateFileIdentity(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.nlink === 1n
+        && right.nlink === 1n;
+}
+function sameMigrationStateFileSnapshot(left, right) {
+    return sameMigrationStateFileIdentity(left, right)
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs
+        && left.mode === right.mode
+        && left.uid === right.uid
+        && left.gid === right.gid;
+}
+function readBoundedMigrationStateFd(fd) {
+    const bytes = Buffer.allocUnsafe(MAX_MIGRATION_STATE_BYTES + 1);
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+        const read = readSync(fd, bytes, offset, bytes.byteLength - offset, offset);
+        if (read === 0)
+            break;
+        offset += read;
+    }
+    if (offset > MAX_MIGRATION_STATE_BYTES)
+        throw new Error('migration_state_too_large');
+    return bytes.subarray(0, offset);
+}
+function readTrustedMigrationStateText(path, options = {}) {
+    let initial;
+    try {
+        initial = assertTrustedMigrationStateLeafSync(path, options);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+    if (initial.size > BigInt(MAX_MIGRATION_STATE_BYTES)) {
+        throw new Error('migration_state_too_large');
+    }
+    const directory = dirname(resolvePath(path));
+    if (options.assertStateDirectoryTrust) {
+        options.assertStateDirectoryTrust(directory);
+    }
+    else {
+        assertTrustedMigrationDirectoryChainSync(directory);
+    }
+    const beforeOpen = statMigrationStateLeafSync(path);
+    if (!sameMigrationStateFileSnapshot(initial, beforeOpen)) {
+        throw new Error('migration_state_leaf_changed');
+    }
+    const fd = openSync(path, 'r');
+    try {
+        const opened = fstatSync(fd, { bigint: true });
+        if (!sameMigrationStateFileSnapshot(beforeOpen, opened)
+            || opened.size > BigInt(MAX_MIGRATION_STATE_BYTES)) {
+            throw new Error('migration_state_leaf_changed');
+        }
+        const raw = readBoundedMigrationStateFd(fd);
+        const afterRead = statMigrationStateLeafSync(path);
+        const afterFdRead = fstatSync(fd, { bigint: true });
+        const finalPath = assertTrustedMigrationStateLeafSync(path, options);
+        const finalFd = fstatSync(fd, { bigint: true });
+        const confirmedRaw = readBoundedMigrationStateFd(fd);
+        const confirmedPath = statMigrationStateLeafSync(path);
+        const confirmedFd = fstatSync(fd, { bigint: true });
+        if (!sameMigrationStateFileSnapshot(opened, afterRead)
+            || !sameMigrationStateFileSnapshot(opened, afterFdRead)
+            || !sameMigrationStateFileSnapshot(opened, finalPath)
+            || !sameMigrationStateFileSnapshot(opened, finalFd)
+            || !sameMigrationStateFileSnapshot(opened, confirmedPath)
+            || !sameMigrationStateFileSnapshot(opened, confirmedFd)
+            || finalFd.size !== BigInt(raw.byteLength)
+            || confirmedFd.size !== BigInt(confirmedRaw.byteLength)
+            || !raw.equals(confirmedRaw)) {
+            throw new Error('migration_state_leaf_changed');
+        }
+        return raw.toString('utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 const defaultWriteTextFile = (path, content) => {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    writeFileSync(path, content, { encoding: 'utf8', mode: 0o600 });
+    const directory = dirname(resolvePath(path));
+    assertTrustedMigrationDirectoryChainSync(directory);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    assertTrustedMigrationDirectoryChainSync(directory);
+    if (migrationPathKey(realpathSync(directory)) !== migrationPathKey(directory)) {
+        throw new Error('unsafe_migration_state_directory');
+    }
+    try {
+        assertTrustedMigrationStateLeafSync(path);
+    }
+    catch (error) {
+        if (!isErrno(error, 'ENOENT'))
+            throw error;
+    }
+    const temporaryPath = join(directory, `.${parsePath(path).base}.${process.pid}.${randomUUID()}.tmp`);
+    let fd;
+    try {
+        fd = openSync(temporaryPath, 'wx', 0o600);
+        writeFileSync(fd, content, { encoding: 'utf8' });
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameSync(temporaryPath, path);
+        const published = lstatSync(path, { bigint: true });
+        if (published.isSymbolicLink() || !published.isFile() || published.nlink !== 1n) {
+            throw new Error('unsafe_migration_state_publication');
+        }
+        try {
+            const directoryFd = openSync(directory, 'r');
+            try {
+                fsyncSync(directoryFd);
+            }
+            finally {
+                closeSync(directoryFd);
+            }
+        }
+        catch (error) {
+            // Windows does not consistently allow directory handles; POSIX durability requires it.
+            if (process.platform !== 'win32')
+                throw error;
+        }
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Advisory state publication has already failed; cleanup is best effort.
+            }
+        }
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Atomic temp names are owner-only inside a trusted directory; retry on next state write.
+        }
+    }
 };
 function resolveProcessUid() {
     const getuid = process.getuid;
     return typeof getuid === 'function' ? getuid.call(process) : undefined;
 }
-/** Best-effort advisory migration state log; never throws — bookkeeping must not break startup. */
+function sameMigrationInstallAnchor(left, right) {
+    return left.phase === right.phase
+        && left.temporaryPath === right.temporaryPath
+        && left.size === right.size
+        && left.sha256 === right.sha256
+        && left.directoryCreated === right.directoryCreated
+        && (left.phase === 'planned'
+            || (right.phase !== 'planned'
+                && left.device === right.device
+                && left.inode === right.inode));
+}
+const MIGRATION_UUID_RE = /^[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 MIGRATION_DIGEST_RE = /^[0-9a-f]{64}$/;
+const MIGRATION_UNSIGNED_INTEGER_RE = /^[0-9]+$/;
+const MIGRATION_POSITIVE_INTEGER_RE = /^[1-9][0-9]*$/;
+const MIGRATION_SIGNED_INTEGER_RE = /^-?[0-9]+$/;
+function exactMigrationRecordKeys(record, expected) {
+    const actual = Object.keys(record).sort();
+    const sortedExpected = [...expected].sort();
+    return actual.length === sortedExpected.length
+        && actual.every((key, index) => key === sortedExpected[index]);
+}
+function exactMigrationTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+function boundedMigrationStateText(value, maxLength) {
+    return typeof value === 'string'
+        && value.length > 0
+        && value.length <= maxLength
+        && !/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value);
+}
+function parseMigrationInstallAnchor(value, destPath) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const anchor = value;
+    const phase = anchor['phase'];
+    const expectedKeys = phase === 'planned'
+        ? ['phase', 'temporaryPath', 'size', 'sha256', 'directoryCreated']
+        : ['phase', 'temporaryPath', 'device', 'inode', 'size', 'sha256', 'directoryCreated'];
+    if (!exactMigrationRecordKeys(anchor, expectedKeys))
+        return undefined;
+    const temporaryPath = anchor['temporaryPath'];
+    const device = anchor['device'];
+    const inode = anchor['inode'];
+    const size = anchor['size'];
+    const digest = anchor['sha256'];
+    const directoryCreated = anchor['directoryCreated'];
+    if (typeof temporaryPath !== 'string'
+        || !isAbsolute(temporaryPath)
+        || temporaryPath.length > 4_096
+        || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(temporaryPath)
+        || dirname(temporaryPath) !== dirname(destPath)
+        || !parsePath(temporaryPath).base.startsWith(`.${parsePath(destPath).base}.`)
+        || !parsePath(temporaryPath).base.endsWith('.migration')
+        || typeof size !== 'number'
+        || !Number.isSafeInteger(size)
+        || size < 0
+        || typeof digest !== 'string'
+        || !MIGRATION_DIGEST_RE.test(digest)
+        || typeof directoryCreated !== 'boolean') {
+        return undefined;
+    }
+    if (phase === 'planned') {
+        return { phase, temporaryPath, size, sha256: digest, directoryCreated };
+    }
+    if ((phase !== 'materialized' && phase !== 'cleanup')
+        || typeof device !== 'string'
+        || !MIGRATION_POSITIVE_INTEGER_RE.test(device)
+        || typeof inode !== 'string'
+        || !MIGRATION_POSITIVE_INTEGER_RE.test(inode)) {
+        return undefined;
+    }
+    return { phase, temporaryPath, device, inode, size, sha256: digest, directoryCreated };
+}
+function parseMigrationInstallOwnership(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const ownership = value;
+    if (!exactMigrationRecordKeys(ownership, ['disposition', 'preimage', 'directoryCreated'])
+        || (ownership['disposition'] !== 'installed' && ownership['disposition'] !== 'converged')
+        || (ownership['preimage'] !== 'absent' && ownership['preimage'] !== 'matching_target')
+        || typeof ownership['directoryCreated'] !== 'boolean'
+        || (ownership['disposition'] === 'installed' && ownership['preimage'] !== 'absent')
+        || (ownership['disposition'] === 'converged'
+            && (ownership['preimage'] !== 'matching_target' || ownership['directoryCreated']))) {
+        return undefined;
+    }
+    return {
+        disposition: ownership['disposition'],
+        preimage: ownership['preimage'],
+        directoryCreated: ownership['directoryCreated'],
+    };
+}
+function parseMigrationTargetIdentity(value, destPath) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const identity = value;
+    if (!exactMigrationRecordKeys(identity, ['path', 'device', 'inode', 'size', 'linkCount', 'mtimeNs', 'ctimeNs', 'sha256'])) {
+        return undefined;
+    }
+    const path = identity['path'];
+    const device = identity['device'];
+    const inode = identity['inode'];
+    const size = identity['size'];
+    const linkCount = identity['linkCount'];
+    const mtimeNs = identity['mtimeNs'];
+    const ctimeNs = identity['ctimeNs'];
+    const digest = identity['sha256'];
+    if (path !== destPath
+        || typeof device !== 'string'
+        || !MIGRATION_UNSIGNED_INTEGER_RE.test(device)
+        || typeof inode !== 'string'
+        || !MIGRATION_UNSIGNED_INTEGER_RE.test(inode)
+        || typeof size !== 'number'
+        || !Number.isSafeInteger(size)
+        || size < 0
+        || linkCount !== 1
+        || typeof mtimeNs !== 'string'
+        || !MIGRATION_SIGNED_INTEGER_RE.test(mtimeNs)
+        || typeof ctimeNs !== 'string'
+        || !MIGRATION_SIGNED_INTEGER_RE.test(ctimeNs)
+        || typeof digest !== 'string'
+        || !MIGRATION_DIGEST_RE.test(digest)) {
+        return undefined;
+    }
+    return {
+        path: destPath,
+        device,
+        inode,
+        size,
+        linkCount: 1,
+        mtimeNs,
+        ctimeNs,
+        sha256: digest,
+    };
+}
+function parseCanonicalMigrationState(raw) {
+    if (raw.length === 0 || Buffer.byteLength(raw, 'utf8') > MAX_MIGRATION_STATE_BYTES) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    const version = record['version'];
+    const destPath = record['destPath'];
+    const attemptedAt = record['attemptedAt'];
+    if (record['schemaVersion'] !== 1
+        || typeof version !== 'string'
+        || version.length > 128
+        || ops.normalizeConcreteVersion(version) !== version
+        || typeof destPath !== 'string'
+        || !isAbsolute(destPath)
+        || destPath.length > 4_096
+        || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(destPath)
+        || !exactMigrationTimestamp(attemptedAt)) {
+        return undefined;
+    }
+    const base = { schemaVersion: 1, version, destPath, attemptedAt };
+    const baseKeys = ['schemaVersion', 'state', 'version', 'destPath', 'attemptedAt'];
+    if (record['state'] === 'in_progress') {
+        if (record['reason'] === undefined) {
+            return exactMigrationRecordKeys(record, baseKeys) ? { ...base, state: 'in_progress' } : undefined;
+        }
+        return record['reason'] === 'install_recovered'
+            && exactMigrationRecordKeys(record, [...baseKeys, 'reason'])
+            ? { ...base, state: 'in_progress', reason: 'install_recovered' }
+            : undefined;
+    }
+    if (record['state'] === 'failed') {
+        return exactMigrationRecordKeys(record, [...baseKeys, 'reason'])
+            && boundedMigrationStateText(record['reason'], 1_024)
+            ? { ...base, state: 'failed', reason: record['reason'] }
+            : undefined;
+    }
+    if (record['state'] === 'installing') {
+        const installAnchor = parseMigrationInstallAnchor(record['installAnchor'], destPath);
+        return installAnchor && exactMigrationRecordKeys(record, [...baseKeys, 'installAnchor'])
+            ? { ...base, state: 'installing', installAnchor }
+            : undefined;
+    }
+    const intentId = record['intentId'];
+    const targetIdentity = parseMigrationTargetIdentity(record['targetIdentity'], destPath);
+    const installOwnership = parseMigrationInstallOwnership(record['installOwnership']);
+    const hasRegistrationBase = typeof intentId === 'string'
+        && MIGRATION_UUID_RE.test(intentId)
+        && targetIdentity !== undefined
+        && installOwnership !== undefined;
+    if (record['state'] === 'registering' || record['state'] === 'committed') {
+        return hasRegistrationBase
+            && exactMigrationRecordKeys(record, [...baseKeys, 'intentId', 'targetIdentity', 'installOwnership'])
+            ? { ...base, state: record['state'], intentId, targetIdentity, installOwnership }
+            : undefined;
+    }
+    if (record['state'] === 'rollback_pending') {
+        return hasRegistrationBase
+            && boundedMigrationStateText(record['reason'], 1_024)
+            && exactMigrationRecordKeys(record, [...baseKeys, 'intentId', 'targetIdentity', 'installOwnership', 'reason'])
+            ? {
+                ...base,
+                state: 'rollback_pending',
+                intentId,
+                targetIdentity,
+                installOwnership,
+                reason: record['reason'],
+            }
+            : undefined;
+    }
+    if (record['state'] === 'blocked') {
+        return hasRegistrationBase
+            && boundedMigrationStateText(record['reason'], 1_024)
+            && exactMigrationRecordKeys(record, [...baseKeys, 'intentId', 'targetIdentity', 'installOwnership', 'reason'])
+            ? {
+                ...base,
+                state: 'blocked',
+                intentId,
+                targetIdentity,
+                installOwnership,
+                reason: record['reason'],
+            }
+            : undefined;
+    }
+    if (record['state'] !== 'rolled_back'
+        || !boundedMigrationStateText(record['reason'], 1_024)) {
+        return undefined;
+    }
+    const installAnchor = parseMigrationInstallAnchor(record['installAnchor'], destPath);
+    if (installAnchor
+        && exactMigrationRecordKeys(record, [...baseKeys, 'reason', 'installAnchor'])) {
+        return { ...base, state: 'rolled_back', reason: record['reason'], installAnchor };
+    }
+    return hasRegistrationBase
+        && exactMigrationRecordKeys(record, [...baseKeys, 'reason', 'intentId', 'targetIdentity', 'installOwnership'])
+        ? {
+            ...base,
+            state: 'rolled_back',
+            reason: record['reason'],
+            intentId,
+            targetIdentity,
+            installOwnership,
+        }
+        : undefined;
+}
+function inspectMigrationStartupState(env, options) {
+    let raw;
+    try {
+        raw = readTrustedMigrationStateText(join(resolveBootstrapStateDir(env), MIGRATION_STATE_FILE), options);
+    }
+    catch (error) {
+        return { classification: 'unsafe', canonicalPresent: true, detail: errorDetail(error) };
+    }
+    if (raw === undefined)
+        return { classification: 'none', canonicalPresent: false };
+    const record = parseCanonicalMigrationState(raw);
+    if (!record) {
+        return { classification: 'unsafe', canonicalPresent: true, detail: 'migration_state_invalid' };
+    }
+    if (record.state === 'rolled_back' || record.state === 'failed') {
+        return { classification: 'none', canonicalPresent: true };
+    }
+    return { classification: 'retryable', canonicalPresent: true, record, raw };
+}
+function serializeMigrationState(record, options) {
+    const payload = {
+        schemaVersion: 1,
+        ...record,
+        attemptedAt: new Date(options.now ?? Date.now()).toISOString(),
+    };
+    return `${JSON.stringify(payload)}\n`;
+}
+function persistAuthoritativeMigrationState(env, record, options) {
+    const payload = serializeMigrationState(record, options);
+    const path = join(resolveBootstrapStateDir(env), MIGRATION_STATE_FILE);
+    const write = options.writeFile ?? defaultWriteTextFile;
+    write(path, payload);
+    if (readTrustedMigrationStateText(path, options) !== payload) {
+        throw new Error('migration_state_durability_unconfirmed');
+    }
+    return payload;
+}
+function assertAuthoritativeMigrationStateCurrent(env, expectedPayload, options) {
+    if (readTrustedMigrationStateText(join(resolveBootstrapStateDir(env), MIGRATION_STATE_FILE), options)
+        !== expectedPayload) {
+        throw new Error('migration_registration_intent_changed');
+    }
+}
 function writeMigrationState(env, record, options) {
     try {
-        const payload = { ...record, attemptedAt: new Date(options.now ?? Date.now()).toISOString() };
+        const payload = serializeMigrationState(record, options);
         const write = options.writeFile ?? defaultWriteTextFile;
-        write(join(resolveBootstrapStateDir(env), MIGRATION_STATE_FILE), `${JSON.stringify(payload)}\n`);
+        write(join(resolveBootstrapStateDir(env), MIGRATION_STATE_FILE), payload);
     }
     catch {
-        // State log is advisory; startup continues regardless.
+        // Pre-registration diagnostics are advisory; registration intent is persisted separately.
     }
 }
 async function rmSafe(rm, path) {
@@ -88,66 +552,1470 @@ async function rmSafe(rm, path) {
     }
 }
 function errorDetail(err) {
-    if (err instanceof Error)
-        return err.message;
-    return String(err);
-}
-/** Spawn `evolver lifecycle bootstrap` with the migration target bound; bounded timeout. */
-function registerMigratedBinary(env, destPath, options, exists) {
-    const invocation = resolveBootstrapCliInvocation({ execPath: options.execPath, exists });
-    if (!invocation)
-        return Promise.resolve({ ok: false, reason: 'cli_not_found' });
-    // resolveBootstrapCliInvocation already targets `lifecycle bootstrap`; normalize the tail
-    // explicitly while preserving any CLI entry prefix (node <cli.js> ...).
-    const args = [...invocation.args.slice(0, Math.max(0, invocation.args.length - 2)), 'lifecycle', 'bootstrap'];
-    const spawnFn = options.spawnFn ?? spawn;
-    const childEnv = { ...env, EVOLVER_SELF_UPDATE_TARGET_PATH: destPath };
-    const timeoutMs = options.timeoutMs ?? MIGRATION_REGISTER_TIMEOUT_MS;
-    return new Promise((resolvePromise) => {
-        let child;
+    const raw = err instanceof Error ? err.message : String(err);
+    const normalized = raw
+        .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim();
+    return normalized.slice(0, MAX_MIGRATION_DETAIL_LENGTH) || 'unknown';
+}
+function registrationReason(reason) {
+    const normalized = errorDetail(reason);
+    return /^[a-z][a-z0-9_]{0,63}$/.test(normalized) ? normalized : undefined;
+}
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}
+function migrationPathKey(path) {
+    const resolved = resolvePath(path);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+function trustedWindowsSystemExecutable(name) {
+    if (!win32.isAbsolute(HOST_WINDOWS_SYSTEM_ROOT) || /[\r\n\0]/.test(HOST_WINDOWS_SYSTEM_ROOT)) {
+        throw new Error('Windows SystemRoot is not an absolute trusted path');
+    }
+    return win32.join(HOST_WINDOWS_SYSTEM_ROOT, 'System32', name);
+}
+function windowsMigrationAclScript(checks) {
+    const encodedChecks = Buffer.from(JSON.stringify(checks), 'utf8').toString('base64');
+    return [
+        `$ErrorActionPreference = 'Stop'`,
+        'try {',
+        `  $json = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedChecks}'))`,
+        '  $checks = $json | ConvertFrom-Json',
+        ...windowsMigrationAclRules().map((line) => `  ${line}`),
+        '} catch { exit 24 }',
+    ].join('; ');
+}
+function windowsMigrationAclRules() {
+    const d = String.fromCharCode(36);
+    return [
+        `${d}userSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value`,
+        `${d}trustedInstaller = 'S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464'`,
+        ...windowsMigrationAclPermissionRules(d),
+    ];
+}
+function windowsMigrationAclPermissionRules(d) {
+    return [
+        `${d}trustedOwners = @(${d}userSid, 'S-1-5-18', 'S-1-5-32-544', ${d}trustedInstaller)`,
+        `${d}trustedWriters = @(${d}userSid, 'S-1-5-18', 'S-1-5-32-544', ${d}trustedInstaller, 'S-1-3-0', 'S-1-3-4')`,
+        `${d}parentDanger = [System.Security.AccessControl.FileSystemRights]::Delete -bor [System.Security.AccessControl.FileSystemRights]::DeleteSubdirectoriesAndFiles -bor [System.Security.AccessControl.FileSystemRights]::ChangePermissions -bor [System.Security.AccessControl.FileSystemRights]::TakeOwnership`,
+        `${d}contentDanger = [System.Security.AccessControl.FileSystemRights]::WriteData -bor [System.Security.AccessControl.FileSystemRights]::AppendData -bor [System.Security.AccessControl.FileSystemRights]::CreateFiles -bor [System.Security.AccessControl.FileSystemRights]::CreateDirectories`,
+        ...windowsMigrationAclLoopRules(d),
+    ];
+}
+function windowsMigrationAclLoopRules(d) {
+    return [
+        `foreach (${d}check in @(${d}checks)) {`,
+        `  ${d}acl = Get-Acl -LiteralPath ${d}check.path`,
+        `  ${d}owner = ${d}acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value`,
+        `  if (${d}trustedOwners -notcontains ${d}owner) { exit 21 }`,
+        `  ${d}danger = if (${d}check.parentOnly) { ${d}parentDanger } else { ${d}parentDanger -bor ${d}contentDanger }`,
+        `  foreach (${d}rule in @(${d}acl.Access)) {`,
+        `    if (${d}rule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow) { continue }`,
+        `    if ((${d}rule.PropagationFlags -band [System.Security.AccessControl.PropagationFlags]::InheritOnly) -ne 0) { continue }`,
+        `    if ((${d}rule.FileSystemRights -band ${d}danger) -eq 0) { continue }`,
+        `    try { ${d}sid = ${d}rule.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value } catch { exit 22 }`,
+        `    if (${d}trustedWriters -notcontains ${d}sid) { exit 23 }`,
+        '  }',
+        '}',
+    ];
+}
+function assertWindowsMigrationAclTrusted(checks) {
+    if (process.platform !== 'win32' || checks.length === 0)
+        return;
+    try {
+        execFileSync(trustedWindowsSystemExecutable('WindowsPowerShell\\v1.0\\powershell.exe'), ['-NoProfile', '-NonInteractive', '-Command', windowsMigrationAclScript(checks)], { stdio: 'ignore', timeout: 10_000, windowsHide: true });
+    }
+    catch (error) {
+        throw new Error('migration Windows ACL chain is not trusted', { cause: error });
+    }
+}
+function assertTrustedMigrationDirectoryChainSync(directory) {
+    let current = resolvePath(directory);
+    const root = parsePath(current).root;
+    const windowsChecks = [];
+    const uid = resolveProcessUid();
+    let nearestExisting = true;
+    let privateUserAnchor = false;
+    for (;;) {
+        let info;
+        try {
+            info = lstatSync(current);
+        }
+        catch (error) {
+            if (!isErrno(error, 'ENOENT'))
+                throw error;
+            if (current === root)
+                break;
+            current = dirname(current);
+            continue;
+        }
+        if (info.isSymbolicLink() || !info.isDirectory()) {
+            throw new Error('unsafe_migration_state_directory');
+        }
+        if (process.platform === 'win32') {
+            windowsChecks.push({ path: current, parentOnly: windowsChecks.length > 0 });
+        }
+        else {
+            if (uid !== undefined && info.uid !== uid && (nearestExisting || info.uid !== 0)) {
+                throw new Error('migration_state_directory_untrusted_owner');
+            }
+            const writableByOthers = (info.mode & 0o022) !== 0;
+            const trustedStickyAncestor = !nearestExisting
+                && privateUserAnchor
+                && info.uid === 0
+                && (info.mode & 0o1000) !== 0;
+            if (writableByOthers && !trustedStickyAncestor) {
+                throw new Error('migration_state_directory_group_or_world_writable');
+            }
+            if (info.uid === uid && (info.mode & 0o077) === 0)
+                privateUserAnchor = true;
+        }
+        nearestExisting = false;
+        if (current === root)
+            break;
+        current = dirname(current);
+    }
+    assertWindowsMigrationAclTrusted(windowsChecks);
+}
+function unresolvedLegacyMigrationOwnership(env, readFile) {
+    try {
+        const raw = readFile(join(resolveBootstrapStateDir(env), BOOTSTRAP_ATTEMPT_FILE));
+        if (raw.length === 0 || raw.length > 4 * 1024)
+            return false;
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        const outcome = parsed['outcome'];
+        return outcome === 'migration_ambiguous' || outcome === 'migrated' || outcome === 'completed';
+    }
+    catch {
+        return false;
+    }
+}
+async function assertTrustedMigrationDirectoryChain(directory, effectiveUid = resolveProcessUid()) {
+    let current = resolvePath(directory);
+    const root = parsePath(current).root;
+    const windowsChecks = [];
+    const uid = effectiveUid;
+    let nearestExisting = true;
+    let privateUserAnchor = false;
+    for (;;) {
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch (error) {
+            if (!isErrno(error, 'ENOENT'))
+                throw error;
+            if (current === root)
+                break;
+            current = dirname(current);
+            continue;
+        }
+        if (info.isSymbolicLink() || !info.isDirectory()) {
+            throw new Error('unsafe_migration_target_directory');
+        }
+        if (process.platform === 'win32') {
+            windowsChecks.push({ path: current, parentOnly: windowsChecks.length > 0 });
+        }
+        else {
+            if (uid !== undefined && info.uid !== uid && (nearestExisting || info.uid !== 0)) {
+                throw new Error('migration_target_directory_untrusted_owner');
+            }
+            const writableByOthers = (info.mode & 0o022) !== 0;
+            const trustedStickyAncestor = !nearestExisting
+                && privateUserAnchor
+                && info.uid === 0
+                && (info.mode & 0o1000) !== 0;
+            if (writableByOthers && !trustedStickyAncestor) {
+                throw new Error('migration_target_directory_group_or_world_writable');
+            }
+            if (info.uid === uid && (info.mode & 0o077) === 0)
+                privateUserAnchor = true;
+        }
+        nearestExisting = false;
+        if (current === root)
+            break;
+        current = dirname(current);
+    }
+    assertWindowsMigrationAclTrusted(windowsChecks);
+}
+async function assertTrustedMigrationFile(path, effectiveUid = resolveProcessUid()) {
+    const info = await lstat(path);
+    if (info.isSymbolicLink() || !info.isFile()) {
+        throw new Error('destination_exists_unowned_or_invalid');
+    }
+    if (process.platform === 'win32') {
+        assertWindowsMigrationAclTrusted([{ path, parentOnly: false }]);
+        return;
+    }
+    const uid = effectiveUid;
+    if (uid !== undefined && info.uid !== uid) {
+        throw new Error('migration_target_file_untrusted_owner');
+    }
+    if ((info.mode & 0o022) !== 0) {
+        throw new Error('migration_target_file_group_or_world_writable');
+    }
+}
+async function ensureSafeMigrationTargetDirectory(home, directory, mkdir, assertDirectoryTrust) {
+    const absoluteHome = resolvePath(home);
+    const absoluteDirectory = resolvePath(directory);
+    if (relative(absoluteHome, absoluteDirectory) !== 'bin') {
+        throw new Error('migration_target_outside_home');
+    }
+    await ensureSafeMigrationDirectory(absoluteDirectory, mkdir, assertDirectoryTrust);
+}
+async function assertSafeExistingMigrationTargetDirectory(home, directory, assertDirectoryTrust) {
+    const absoluteHome = resolvePath(home);
+    const absoluteDirectory = resolvePath(directory);
+    if (relative(absoluteHome, absoluteDirectory) !== 'bin') {
+        throw new Error('migration_target_outside_home');
+    }
+    await assertDirectoryTrust(absoluteDirectory);
+    let info;
+    try {
+        info = await lstat(absoluteDirectory);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+        throw new Error('unsafe_migration_target_directory');
+    }
+    const canonicalDirectory = await fsRealpath(absoluteDirectory);
+    if (migrationPathKey(canonicalDirectory) !== migrationPathKey(absoluteDirectory)) {
+        throw new Error('unsafe_migration_target_directory');
+    }
+}
+async function ensureSafeMigrationDirectory(directory, mkdir, assertDirectoryTrust) {
+    const absoluteDirectory = resolvePath(directory);
+    // Validate the existing ancestor before mkdir, then validate the complete canonical tree.
+    // This rejects symlinked or non-directory components instead of writing through them.
+    await assertDirectoryTrust(absoluteDirectory);
+    await mkdir(absoluteDirectory, 0o700);
+    await assertDirectoryTrust(absoluteDirectory);
+    const canonicalDirectory = await fsRealpath(absoluteDirectory);
+    if (migrationPathKey(canonicalDirectory) !== migrationPathKey(absoluteDirectory)) {
+        throw new Error('unsafe_migration_target_directory');
+    }
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+async function inspectExistingMigrationTarget(destPath, version, preflight, readBinary, expected, assertDirectoryTrust, assertFileTrust) {
+    let before;
+    try {
+        before = await lstat(destPath, { bigint: true });
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+    if (before.isSymbolicLink() || !before.isFile() || before.dev <= 0n || before.ino <= 0n) {
+        throw new Error('destination_exists_unowned_or_invalid');
+    }
+    await assertDirectoryTrust(dirname(destPath));
+    await assertFileTrust(destPath);
+    if (before.nlink !== 1n)
+        throw new Error('destination_exists_with_external_hardlink');
+    if (before.size !== BigInt(expected.size))
+        throw new Error('destination_exists_with_different_artifact');
+    const existingBytes = await readBinary(destPath);
+    if (existingBytes.byteLength !== expected.size || sha256(existingBytes) !== expected.sha256) {
+        throw new Error('destination_exists_with_different_artifact');
+    }
+    try {
+        await preflight(destPath, version);
+    }
+    catch (error) {
+        throw new Error(`destination_exists_unowned_or_invalid:${errorDetail(error)}`, { cause: error });
+    }
+    await assertFileTrust(destPath);
+    const after = await lstat(destPath, { bigint: true });
+    if (!after.isFile() || after.isSymbolicLink() || after.nlink !== 1n
+        || after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size
+        || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs) {
+        throw new Error('destination_changed_during_validation');
+    }
+    return {
+        path: resolvePath(destPath),
+        device: before.dev.toString(),
+        inode: before.ino.toString(),
+        size: expected.size,
+        linkCount: 1,
+        mtimeNs: before.mtimeNs.toString(),
+        ctimeNs: before.ctimeNs.toString(),
+        sha256: expected.sha256,
+    };
+}
+function sameMigrationTargetIdentity(left, right) {
+    return left.path === right.path
+        && left.device === right.device
+        && left.inode === right.inode
+        && left.size === right.size
+        && left.linkCount === right.linkCount
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs
+        && left.sha256 === right.sha256;
+}
+function assertMigrationTargetIdentityShape(identity) {
+    if (!isAbsolute(identity.path) || migrationPathKey(identity.path) !== migrationPathKey(resolvePath(identity.path))) {
+        throw new Error('migration_target_identity_path_invalid');
+    }
+    if (!Number.isSafeInteger(identity.size) || identity.size < 0
+        || identity.linkCount !== 1
+        || !/^[0-9]+$/.test(identity.device)
+        || !/^[0-9]+$/.test(identity.inode)
+        || !/^-?[0-9]+$/.test(identity.mtimeNs)
+        || !/^-?[0-9]+$/.test(identity.ctimeNs)
+        || !/^[0-9a-f]{64}$/.test(identity.sha256)) {
+        throw new Error('migration_target_identity_invalid');
+    }
+}
+/**
+ * Revalidate the complete signed executable identity immediately before lifecycle bootstrap
+ * spawns it. Callers must not substitute the request's presentation object for this check.
+ */
+async function assertMigrationTargetIdentityCurrent(identity, expectedVersion, options = {}) {
+    assertMigrationTargetIdentityShape(identity);
+    const readBinary = options.readBinary ?? ((path) => fsReadFile(path));
+    const preflight = options.preflightFn
+        ?? ((path, version) => preflightManagedStagedBinary(path, version));
+    const assertDirectoryTrust = options.assertDirectoryTrust ?? assertTrustedMigrationDirectoryChain;
+    const assertFileTrust = options.assertFileTrust ?? assertTrustedMigrationFile;
+    const current = await inspectExistingMigrationTarget(identity.path, expectedVersion, preflight, readBinary, { sha256: identity.sha256, size: identity.size }, assertDirectoryTrust, assertFileTrust);
+    if (!current || !sameMigrationTargetIdentity(current, identity)) {
+        throw new Error('migration_target_identity_changed');
+    }
+}
+const MAX_MIGRATION_LOCK_BYTES = 4_096;
+function assertMigrationLockSnapshotShape(snapshot) {
+    if (snapshot.isSymbolicLink()
+        || !snapshot.isFile()
+        || snapshot.nlink !== 1n
+        || snapshot.size > BigInt(MAX_MIGRATION_LOCK_BYTES)) {
+        throw new Error('migration_lock_ownership_changed');
+    }
+}
+function sameMigrationLockSnapshot(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.nlink === 1n
+        && right.nlink === 1n
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+function readBoundedMigrationLockFd(fd) {
+    const bytes = Buffer.allocUnsafe(MAX_MIGRATION_LOCK_BYTES + 1);
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+        const read = readSync(fd, bytes, offset, bytes.byteLength - offset, offset);
+        if (read === 0)
+            break;
+        offset += read;
+    }
+    if (offset > MAX_MIGRATION_LOCK_BYTES)
+        throw new Error('migration_lock_ownership_changed');
+    return bytes.subarray(0, offset);
+}
+function readMigrationLockAuthority(lockPath) {
+    const beforeOpen = lstatSync(lockPath, { bigint: true });
+    assertMigrationLockSnapshotShape(beforeOpen);
+    const fd = openSync(lockPath, 'r');
+    try {
+        const opened = fstatSync(fd, { bigint: true });
+        assertMigrationLockSnapshotShape(opened);
+        if (!sameMigrationLockSnapshot(beforeOpen, opened)) {
+            throw new Error('migration_lock_ownership_changed');
+        }
+        const firstBytes = readBoundedMigrationLockFd(fd);
+        const afterFirstFd = fstatSync(fd, { bigint: true });
+        const afterFirstPath = lstatSync(lockPath, { bigint: true });
+        const secondBytes = readBoundedMigrationLockFd(fd);
+        const finalFd = fstatSync(fd, { bigint: true });
+        const finalPath = lstatSync(lockPath, { bigint: true });
+        for (const snapshot of [afterFirstFd, afterFirstPath, finalFd, finalPath]) {
+            assertMigrationLockSnapshotShape(snapshot);
+            if (!sameMigrationLockSnapshot(opened, snapshot)) {
+                throw new Error('migration_lock_ownership_changed');
+            }
+        }
+        if (opened.size !== BigInt(firstBytes.byteLength)
+            || finalFd.size !== BigInt(secondBytes.byteLength)
+            || !firstBytes.equals(secondBytes)) {
+            throw new Error('migration_lock_ownership_changed');
+        }
+        return { snapshot: opened, bytes: Buffer.from(firstBytes) };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function assertMigrationLockOwnerRecord(bytes, owner) {
+    let current;
+    try {
+        current = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('migration_lock_ownership_changed');
+    }
+    if (!current || typeof current !== 'object' || Array.isArray(current)) {
+        throw new Error('migration_lock_ownership_changed');
+    }
+    const record = current;
+    if (record['pid'] !== owner.pid
+        || record['token'] !== owner.token
+        || JSON.stringify(record['processStart']) !== JSON.stringify(owner.processStartIdentity)) {
+        throw new Error('migration_lock_ownership_changed');
+    }
+}
+async function withMigrationLock(directory, operation) {
+    const lockPath = join(directory, MIGRATION_LOCK_FILE);
+    let owner;
+    try {
+        owner = util.acquireLock(lockPath, { maxTries: 1, waitMs: 0 });
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null ? error.code : undefined;
+        throw new Error(code === 'LOCK_TIMEOUT' ? 'migration_lock_busy' : `migration_lock_unsafe:${errorDetail(error)}`, {
+            cause: error,
+        });
+    }
+    let acquiredAuthority;
+    try {
+        acquiredAuthority = readMigrationLockAuthority(lockPath);
+        assertMigrationLockOwnerRecord(acquiredAuthority.bytes, owner);
+    }
+    catch (error) {
+        util.releaseLock(lockPath);
+        throw error;
+    }
+    let completed = false;
+    let value;
+    let operationError;
+    const assertOwnershipCurrent = () => {
+        const currentAuthority = readMigrationLockAuthority(lockPath);
+        if (!sameMigrationLockSnapshot(acquiredAuthority.snapshot, currentAuthority.snapshot)
+            || !acquiredAuthority.bytes.equals(currentAuthority.bytes)) {
+            throw new Error('migration_lock_ownership_changed');
+        }
+        assertMigrationLockOwnerRecord(currentAuthority.bytes, owner);
+    };
+    try {
+        assertOwnershipCurrent();
+        value = await operation(assertOwnershipCurrent);
+        assertOwnershipCurrent();
+        completed = true;
+    }
+    catch (error) {
+        operationError = error;
+    }
+    const released = util.releaseLock(lockPath);
+    if (!released.released
+        || (released.reason !== 'released' && released.reason !== 'released_with_cleanup_error')) {
+        throw new Error(`migration_lock_release_failed:${released.reason}`, { cause: operationError });
+    }
+    if (!completed)
+        throw operationError;
+    return value;
+}
+async function installVerifiedMigrationBinary(input) {
+    const directory = dirname(input.destPath);
+    // Read-only validation and convergence detection happen before the durable plan. The plan is
+    // then published before mkdir or O_EXCL temporary-file creation touches the target namespace.
+    await input.assertDirectoryTrust(directory);
+    let directoryCreated = false;
+    try {
+        await lstat(directory);
+    }
+    catch (error) {
+        if (!isErrno(error, 'ENOENT'))
+            throw error;
+        directoryCreated = true;
+    }
+    const existingIdentity = await inspectExistingMigrationTarget(input.destPath, input.version, input.preflight, input.readBinary, { sha256: input.expectedSha256, size: input.bytes.byteLength }, input.assertDirectoryTrust, input.assertFileTrust);
+    if (existingIdentity) {
+        return { disposition: 'converged', targetIdentity: existingIdentity, directoryCreated: false };
+    }
+    const temporaryPath = join(directory, `.${parsePath(input.destPath).base}.${process.pid}.${randomUUID()}.migration`);
+    const plannedAnchor = {
+        phase: 'planned',
+        temporaryPath,
+        size: input.bytes.byteLength,
+        sha256: input.expectedSha256,
+        directoryCreated,
+    };
+    await input.publishInstallIntent(plannedAnchor);
+    let publishedAnchor;
+    let materializedAnchor;
+    let concurrentIdentity;
+    try {
+        await ensureSafeMigrationTargetDirectory(input.home, directory, input.mkdir, input.assertDirectoryTrust);
+        if (directoryCreated) {
+            await input.syncDirectory(dirname(directory));
+        }
+        await input.writeBinary(temporaryPath, input.bytes, 0o755);
+        await input.chmod(temporaryPath, 0o755);
+        await input.syncFile(temporaryPath);
+        const temporaryInfo = await input.stat(temporaryPath);
+        const temporaryIdentity = await lstat(temporaryPath, { bigint: true });
+        if (temporaryInfo.isSymbolicLink() || !temporaryInfo.isFile()
+            || temporaryIdentity.isSymbolicLink() || !temporaryIdentity.isFile()
+            || temporaryIdentity.nlink !== 1n || temporaryIdentity.dev <= 0n || temporaryIdentity.ino <= 0n) {
+            throw new Error('migration_temporary_not_owned_regular_file');
+        }
+        const publishedBytes = await input.readBinary(temporaryPath);
+        if (publishedBytes.byteLength !== input.bytes.byteLength || sha256(publishedBytes) !== input.expectedSha256) {
+            throw new Error('migration_temporary_hash_mismatch');
+        }
+        if (temporaryIdentity.size !== BigInt(input.bytes.byteLength)) {
+            throw new Error('migration_temporary_size_mismatch');
+        }
+        materializedAnchor = {
+            phase: 'materialized',
+            temporaryPath,
+            device: temporaryIdentity.dev.toString(),
+            inode: temporaryIdentity.ino.toString(),
+            size: input.bytes.byteLength,
+            sha256: input.expectedSha256,
+            directoryCreated,
+        };
+        await input.publishInstallIntent(materializedAnchor);
+        try {
+            await input.link(temporaryPath, input.destPath);
+            publishedAnchor = {
+                device: temporaryIdentity.dev,
+                inode: temporaryIdentity.ino,
+                size: temporaryIdentity.size,
+            };
+            await input.syncDirectory(directory);
+        }
+        catch (error) {
+            if (!isErrno(error, 'EEXIST'))
+                throw error;
+            concurrentIdentity = await inspectExistingMigrationTarget(input.destPath, input.version, input.preflight, input.readBinary, { sha256: input.expectedSha256, size: input.bytes.byteLength }, input.assertDirectoryTrust, input.assertFileTrust);
+            if (!concurrentIdentity)
+                throw error;
+        }
+    }
+    catch (error) {
+        if (!materializedAnchor) {
+            throw new Error(`migration_install_rollback_unconfirmed:planned_materialization_unconfirmed:${errorDetail(error)}`, { cause: error });
+        }
+        try {
+            await removeMaterializedMigrationTemporaryFile({
+                anchor: materializedAnchor,
+                readBinary: input.readBinary,
+                rename: input.rename,
+                link: input.link,
+                unlink: input.unlink,
+                syncDirectory: input.syncDirectory,
+                assertFileTrust: input.assertFileTrust,
+            });
+            if (publishedAnchor) {
+                await rollbackPublishedMigrationTarget(input, publishedAnchor, materializedAnchor, directoryCreated);
+            }
+            else if (directoryCreated) {
+                await removeMigrationDirectoryIfEmpty(directory, input.rmdir);
+            }
+        }
+        catch (rollbackError) {
+            throw new Error(`migration_install_rollback_unconfirmed:${errorDetail(rollbackError)}`, { cause: error });
+        }
+        throw error;
+    }
+    try {
+        // Remove our temporary hardlink before enforcing the final target's nlink=1 invariant.
+        if (!materializedAnchor)
+            throw new Error('migration_materialized_anchor_missing');
+        await removeMaterializedMigrationTemporaryFile({
+            anchor: materializedAnchor,
+            readBinary: input.readBinary,
+            rename: input.rename,
+            link: input.link,
+            unlink: input.unlink,
+            syncDirectory: input.syncDirectory,
+            assertFileTrust: input.assertFileTrust,
+        });
+    }
+    catch (error) {
+        throw new Error(`migration_install_rollback_unconfirmed:temporary_cleanup:${errorDetail(error)}`);
+    }
+    if (concurrentIdentity) {
+        return { disposition: 'converged', targetIdentity: concurrentIdentity, directoryCreated: false };
+    }
+    if (!publishedAnchor)
+        throw new Error('published_migration_target_missing');
+    try {
+        const installedIdentity = await inspectExistingMigrationTarget(input.destPath, input.version, input.preflight, input.readBinary, { sha256: input.expectedSha256, size: input.bytes.byteLength }, input.assertDirectoryTrust, input.assertFileTrust);
+        if (!installedIdentity)
+            throw new Error('published_migration_target_missing');
+        return { disposition: 'installed', targetIdentity: installedIdentity, directoryCreated };
+    }
+    catch (error) {
+        try {
+            await rollbackPublishedMigrationTarget(input, publishedAnchor, materializedAnchor, directoryCreated);
+        }
+        catch (rollbackError) {
+            throw new Error(`migration_install_rollback_unconfirmed:${errorDetail(rollbackError)}`, { cause: error });
+        }
+        throw error;
+    }
+}
+function migrationTemporaryCleanupQuarantinePath(temporaryPath) {
+    return `${temporaryPath}.cleanup`;
+}
+function migrationInstallTargetQuarantinePath(anchor) {
+    return `${anchor.temporaryPath}.target-rollback`;
+}
+function migrationRegistrationTargetQuarantinePath(destPath, intentId) {
+    return join(dirname(destPath), `.${parsePath(destPath).base}.${intentId}.rollback`);
+}
+async function migrationPathIdentity(path) {
+    try {
+        return await lstat(path, { bigint: true });
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+function sameMigrationFileId(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+async function inspectExactMigrationCleanupFile(input) {
+    const before = await lstat(input.path, { bigint: true });
+    await input.assertFileTrust(input.path);
+    if (before.isSymbolicLink()
+        || !before.isFile()
+        || !input.allowedLinkCounts.includes(before.nlink)
+        || before.dev.toString() !== input.expected.device
+        || before.ino.toString() !== input.expected.inode
+        || before.size !== BigInt(input.expected.size)) {
+        throw new Error(input.identityError);
+    }
+    const bytes = await input.readBinary(input.path);
+    if (bytes.byteLength !== input.expected.size || sha256(bytes) !== input.expected.sha256) {
+        throw new Error(input.hashError);
+    }
+    const after = await lstat(input.path, { bigint: true });
+    if (after.isSymbolicLink()
+        || !after.isFile()
+        || after.dev !== before.dev
+        || after.ino !== before.ino
+        || after.nlink !== before.nlink
+        || after.size !== before.size
+        || after.mtimeNs !== before.mtimeNs
+        || after.ctimeNs !== before.ctimeNs) {
+        throw new Error(input.identityError);
+    }
+    return after;
+}
+async function restoreMismatchedMigrationQuarantine(input) {
+    const directory = dirname(input.sourcePath);
+    const sourceIdentity = await migrationPathIdentity(input.sourcePath);
+    if (sourceIdentity && !sameMigrationFileId(sourceIdentity, input.quarantineIdentity)) {
+        throw new Error(`${input.errorPrefix}_quarantine_preserved_canonical_occupied`, { cause: input.reason });
+    }
+    if (!sourceIdentity) {
+        try {
+            await input.link(input.quarantinePath, input.sourcePath);
+            await input.syncDirectory(directory);
+        }
+        catch (error) {
+            if (!isErrno(error, 'EEXIST'))
+                throw error;
+            throw new Error(`${input.errorPrefix}_quarantine_preserved_restore_conflict`, { cause: input.reason });
+        }
+    }
+    const restoredIdentity = await migrationPathIdentity(input.sourcePath);
+    const currentQuarantineIdentity = await migrationPathIdentity(input.quarantinePath);
+    if (!restoredIdentity || !currentQuarantineIdentity
+        || !sameMigrationFileId(restoredIdentity, currentQuarantineIdentity)
+        || !sameMigrationFileId(currentQuarantineIdentity, input.quarantineIdentity)) {
+        throw new Error(`${input.errorPrefix}_quarantine_preserved_restore_inconclusive`, { cause: input.reason });
+    }
+    await input.unlink(input.quarantinePath);
+    await input.syncDirectory(directory);
+    throw new Error(`${input.errorPrefix}_moved_object_restored`, { cause: input.reason });
+}
+async function quarantineAndRemoveExactMigrationFile(input) {
+    const directory = dirname(input.sourcePath);
+    let quarantineIdentity = await migrationPathIdentity(input.quarantinePath);
+    if (quarantineIdentity) {
         try {
-            const spawnOptions = { stdio: 'ignore', windowsHide: true, env: childEnv };
-            child = spawnFn(invocation.command, args, spawnOptions);
+            quarantineIdentity = await inspectExactMigrationCleanupFile({
+                path: input.quarantinePath,
+                expected: input.expected,
+                allowedLinkCounts: input.allowedLinkCounts,
+                readBinary: input.readBinary,
+                assertFileTrust: input.assertFileTrust,
+                identityError: input.identityError,
+                hashError: input.hashError,
+            });
         }
         catch (error) {
-            resolvePromise({ ok: false, reason: 'failed', detail: errorDetail(error) });
+            await restoreMismatchedMigrationQuarantine({
+                sourcePath: input.sourcePath,
+                quarantinePath: input.quarantinePath,
+                quarantineIdentity,
+                link: input.link,
+                unlink: input.unlink,
+                syncDirectory: input.syncDirectory,
+                reason: error,
+                errorPrefix: input.errorPrefix,
+            });
+        }
+        const sourceIdentity = await migrationPathIdentity(input.sourcePath);
+        if (sourceIdentity) {
+            if (!sameMigrationFileId(sourceIdentity, quarantineIdentity)) {
+                throw new Error(`${input.errorPrefix}_quarantine_preserved_canonical_occupied`);
+            }
+            await input.unlink(input.quarantinePath);
+            await input.syncDirectory(directory);
+            quarantineIdentity = undefined;
+        }
+        else {
+            await inspectExactMigrationCleanupFile({
+                path: input.quarantinePath,
+                expected: input.expected,
+                allowedLinkCounts: input.allowedLinkCounts,
+                readBinary: input.readBinary,
+                assertFileTrust: input.assertFileTrust,
+                identityError: input.identityError,
+                hashError: input.hashError,
+            });
+            await input.unlink(input.quarantinePath);
+            await input.syncDirectory(directory);
             return;
         }
-        let settled = false;
-        const settle = (outcome) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolvePromise(outcome);
+    }
+    const sourceIdentity = await migrationPathIdentity(input.sourcePath);
+    if (!sourceIdentity)
+        return;
+    await inspectExactMigrationCleanupFile({
+        path: input.sourcePath,
+        expected: input.expected,
+        allowedLinkCounts: input.allowedLinkCounts,
+        readBinary: input.readBinary,
+        assertFileTrust: input.assertFileTrust,
+        identityError: input.identityError,
+        hashError: input.hashError,
+    });
+    if (await migrationPathIdentity(input.quarantinePath)) {
+        throw new Error(`${input.errorPrefix}_quarantine_occupied`);
+    }
+    await input.rename(input.sourcePath, input.quarantinePath);
+    await input.syncDirectory(directory);
+    let movedIdentity = await migrationPathIdentity(input.quarantinePath);
+    if (!movedIdentity)
+        throw new Error(`${input.errorPrefix}_quarantine_missing_after_move`);
+    try {
+        movedIdentity = await inspectExactMigrationCleanupFile({
+            path: input.quarantinePath,
+            expected: input.expected,
+            allowedLinkCounts: input.allowedLinkCounts,
+            readBinary: input.readBinary,
+            assertFileTrust: input.assertFileTrust,
+            identityError: input.identityError,
+            hashError: input.hashError,
+        });
+    }
+    catch (error) {
+        await restoreMismatchedMigrationQuarantine({
+            sourcePath: input.sourcePath,
+            quarantinePath: input.quarantinePath,
+            quarantineIdentity: movedIdentity,
+            link: input.link,
+            unlink: input.unlink,
+            syncDirectory: input.syncDirectory,
+            reason: error,
+            errorPrefix: input.errorPrefix,
+        });
+    }
+    if (await migrationPathIdentity(input.sourcePath)) {
+        throw new Error(`${input.errorPrefix}_quarantine_preserved_canonical_recreated`);
+    }
+    await inspectExactMigrationCleanupFile({
+        path: input.quarantinePath,
+        expected: input.expected,
+        allowedLinkCounts: input.allowedLinkCounts,
+        readBinary: input.readBinary,
+        assertFileTrust: input.assertFileTrust,
+        identityError: input.identityError,
+        hashError: input.hashError,
+    });
+    await input.unlink(input.quarantinePath);
+    await input.syncDirectory(directory);
+}
+async function removeMaterializedMigrationTemporaryFile(input) {
+    await quarantineAndRemoveExactMigrationFile({
+        sourcePath: input.anchor.temporaryPath,
+        quarantinePath: migrationTemporaryCleanupQuarantinePath(input.anchor.temporaryPath),
+        expected: input.anchor,
+        allowedLinkCounts: [1n, 2n],
+        readBinary: input.readBinary,
+        rename: input.rename,
+        link: input.link,
+        unlink: input.unlink,
+        syncDirectory: input.syncDirectory,
+        assertFileTrust: input.assertFileTrust,
+        identityError: 'migration_materialized_temporary_identity_changed',
+        hashError: 'migration_materialized_temporary_hash_changed',
+        errorPrefix: 'migration_materialized_temporary_cleanup',
+    });
+}
+function parsePendingMigrationInstall(raw) {
+    const record = parseCanonicalMigrationState(raw);
+    if (!record)
+        throw new Error('migration_install_journal_invalid');
+    if (record.state !== 'installing')
+        return undefined;
+    return {
+        version: record.version,
+        destPath: record.destPath,
+        anchor: record.installAnchor,
+    };
+}
+async function recoverPendingMigrationInstall(input) {
+    const initialAuthoritativePayload = readTrustedMigrationStateText(join(resolveBootstrapStateDir(input.env), MIGRATION_STATE_FILE), input.stateOptions);
+    if (initialAuthoritativePayload === undefined)
+        return false;
+    let authoritativePayload = initialAuthoritativePayload;
+    const pending = parsePendingMigrationInstall(authoritativePayload);
+    if (!pending)
+        return false;
+    input.markCanonicalStateActive();
+    const directory = dirname(pending.destPath);
+    const storedHome = dirname(directory);
+    const assertPendingCurrent = () => {
+        input.assertOwnerCurrent();
+        assertAuthoritativeMigrationStateCurrent(input.env, authoritativePayload, input.stateOptions);
+    };
+    assertPendingCurrent();
+    await assertSafeExistingMigrationTargetDirectory(storedHome, directory, input.assertDirectoryTrust);
+    const completeRecovery = () => {
+        assertPendingCurrent();
+        persistAuthoritativeMigrationState(input.env, {
+            state: 'rolled_back',
+            version: pending.version,
+            destPath: pending.destPath,
+            reason: 'install_recovered',
+            installAnchor: pending.anchor,
+        }, input.stateOptions);
+    };
+    if (pending.anchor.phase === 'planned') {
+        let before;
+        try {
+            before = await lstat(pending.anchor.temporaryPath, { bigint: true });
+        }
+        catch (error) {
+            if (!isErrno(error, 'ENOENT'))
+                throw error;
+            if (pending.anchor.directoryCreated) {
+                assertPendingCurrent();
+                await removeMigrationDirectoryIfEmpty(directory, input.rmdir);
+                await input.syncDirectory(dirname(directory));
+            }
+            completeRecovery();
+            return true;
+        }
+        await input.assertFileTrust(pending.anchor.temporaryPath);
+        if (before.isSymbolicLink() || !before.isFile() || before.nlink !== 1n
+            || before.dev <= 0n || before.ino <= 0n || before.size > BigInt(pending.anchor.size)) {
+            throw new Error('migration_planned_temporary_unowned');
+        }
+        const bytes = await input.readBinary(pending.anchor.temporaryPath);
+        const after = await lstat(pending.anchor.temporaryPath, { bigint: true });
+        if (after.isSymbolicLink()
+            || !after.isFile()
+            || after.dev !== before.dev
+            || after.ino !== before.ino
+            || after.nlink !== before.nlink
+            || after.size !== before.size
+            || after.mtimeNs !== before.mtimeNs
+            || after.ctimeNs !== before.ctimeNs) {
+            throw new Error('migration_planned_temporary_identity_changed');
+        }
+        if (bytes.byteLength !== Number(after.size)) {
+            throw new Error('migration_planned_temporary_identity_changed');
+        }
+        const cleanupAnchor = {
+            phase: 'cleanup',
+            temporaryPath: pending.anchor.temporaryPath,
+            device: after.dev.toString(),
+            inode: after.ino.toString(),
+            size: bytes.byteLength,
+            sha256: sha256(bytes),
+            directoryCreated: pending.anchor.directoryCreated,
         };
-        const timer = setTimeout(() => {
-            child.kill();
-            settle({ ok: false, reason: 'timeout' });
-        }, timeoutMs);
-        child.once('error', (error) => {
-            settle({ ok: false, reason: 'failed', detail: error.message });
+        assertPendingCurrent();
+        authoritativePayload = persistAuthoritativeMigrationState(input.env, {
+            state: 'installing',
+            version: pending.version,
+            destPath: pending.destPath,
+            installAnchor: cleanupAnchor,
+        }, input.stateOptions);
+        await quarantineAndRemoveExactMigrationFile({
+            sourcePath: cleanupAnchor.temporaryPath,
+            quarantinePath: migrationTemporaryCleanupQuarantinePath(cleanupAnchor.temporaryPath),
+            expected: cleanupAnchor,
+            allowedLinkCounts: [1n],
+            readBinary: input.readBinary,
+            rename: input.rename,
+            link: input.link,
+            unlink: input.unlink,
+            syncDirectory: input.syncDirectory,
+            assertFileTrust: input.assertFileTrust,
+            identityError: 'migration_planned_temporary_identity_changed',
+            hashError: 'migration_planned_temporary_hash_changed',
+            errorPrefix: 'migration_planned_temporary_cleanup',
         });
-        child.once('exit', (code) => {
-            if (code === 0)
-                settle({ ok: true, reason: 'registered' });
-            else
-                settle({ ok: false, reason: 'failed', detail: `exit ${code ?? 'null'}` });
+        if (pending.anchor.directoryCreated) {
+            assertPendingCurrent();
+            await removeMigrationDirectoryIfEmpty(directory, input.rmdir);
+            await input.syncDirectory(dirname(directory));
+        }
+        completeRecovery();
+        return true;
+    }
+    if (pending.anchor.phase === 'cleanup') {
+        await quarantineAndRemoveExactMigrationFile({
+            sourcePath: pending.anchor.temporaryPath,
+            quarantinePath: migrationTemporaryCleanupQuarantinePath(pending.anchor.temporaryPath),
+            expected: pending.anchor,
+            allowedLinkCounts: [1n],
+            readBinary: input.readBinary,
+            rename: input.rename,
+            link: input.link,
+            unlink: input.unlink,
+            syncDirectory: input.syncDirectory,
+            assertFileTrust: input.assertFileTrust,
+            identityError: 'migration_planned_temporary_identity_changed',
+            hashError: 'migration_planned_temporary_hash_changed',
+            errorPrefix: 'migration_planned_temporary_cleanup',
         });
+        if (pending.anchor.directoryCreated) {
+            assertPendingCurrent();
+            await removeMigrationDirectoryIfEmpty(directory, input.rmdir);
+            await input.syncDirectory(dirname(directory));
+        }
+        completeRecovery();
+        return true;
+    }
+    const materializedAnchor = pending.anchor;
+    assertPendingCurrent();
+    await removeMaterializedMigrationTemporaryFile({
+        anchor: materializedAnchor,
+        readBinary: input.readBinary,
+        rename: input.rename,
+        link: input.link,
+        unlink: input.unlink,
+        syncDirectory: input.syncDirectory,
+        assertFileTrust: input.assertFileTrust,
+    });
+    assertPendingCurrent();
+    await rollbackPublishedMigrationTarget({
+        destPath: pending.destPath,
+        expectedSha256: materializedAnchor.sha256,
+        readBinary: input.readBinary,
+        rename: input.rename,
+        link: input.link,
+        unlink: input.unlink,
+        rmdir: input.rmdir,
+        syncDirectory: input.syncDirectory,
+        assertFileTrust: input.assertFileTrust,
+    }, {
+        device: BigInt(materializedAnchor.device),
+        inode: BigInt(materializedAnchor.inode),
+        size: BigInt(materializedAnchor.size),
+    }, materializedAnchor, false);
+    if (materializedAnchor.directoryCreated) {
+        assertPendingCurrent();
+        await removeMigrationDirectoryIfEmpty(directory, input.rmdir);
+        await input.syncDirectory(dirname(directory));
+    }
+    completeRecovery();
+    return true;
+}
+async function removeMigrationDirectoryIfEmpty(directory, rmdir) {
+    try {
+        await rmdir(directory);
+    }
+    catch (error) {
+        if (!isErrno(error, 'ENOENT') && !isErrno(error, 'ENOTEMPTY') && !isErrno(error, 'EEXIST')) {
+            throw error;
+        }
+    }
+}
+async function rollbackPublishedMigrationTarget(input, anchor, materializedAnchor, directoryCreated) {
+    await quarantineAndRemoveExactMigrationFile({
+        sourcePath: input.destPath,
+        quarantinePath: migrationInstallTargetQuarantinePath(materializedAnchor),
+        expected: {
+            device: anchor.device.toString(),
+            inode: anchor.inode.toString(),
+            size: Number(anchor.size),
+            sha256: input.expectedSha256,
+        },
+        allowedLinkCounts: [1n],
+        readBinary: input.readBinary,
+        rename: input.rename,
+        link: input.link,
+        unlink: input.unlink,
+        syncDirectory: input.syncDirectory,
+        assertFileTrust: input.assertFileTrust,
+        identityError: 'migration_install_rollback_identity_changed',
+        hashError: 'migration_install_rollback_hash_changed',
+        errorPrefix: 'migration_install_target_cleanup',
+    });
+    if (directoryCreated) {
+        await removeMigrationDirectoryIfEmpty(dirname(input.destPath), input.rmdir);
+        await input.syncDirectory(dirname(dirname(input.destPath)));
+    }
+}
+async function cleanupInstalledMigrationBinary(input) {
+    if (input.install.disposition !== 'installed')
+        return;
+    const directory = dirname(input.destPath);
+    await input.assertAuthorityCurrent();
+    await input.assertDirectoryTrust(directory);
+    if (await migrationPathIdentity(input.destPath)) {
+        const currentIdentity = await inspectExistingMigrationTarget(input.destPath, input.version, input.preflight, input.readBinary, { sha256: input.expectedSha256, size: input.install.targetIdentity.size }, input.assertDirectoryTrust, input.assertFileTrust);
+        if (!currentIdentity || !sameMigrationTargetIdentity(currentIdentity, input.install.targetIdentity)) {
+            throw new Error('migration_cleanup_target_identity_changed');
+        }
+    }
+    await input.assertAuthorityCurrent();
+    await quarantineAndRemoveExactMigrationFile({
+        sourcePath: input.destPath,
+        quarantinePath: input.quarantinePath,
+        expected: input.install.targetIdentity,
+        allowedLinkCounts: [1n],
+        readBinary: input.readBinary,
+        rename: input.rename,
+        link: input.link,
+        unlink: input.unlink,
+        syncDirectory: input.syncDirectory,
+        assertFileTrust: input.assertFileTrust,
+        identityError: 'migration_cleanup_target_identity_changed',
+        hashError: 'migration_cleanup_target_hash_changed',
+        errorPrefix: 'migration_cleanup_target',
     });
+    if (input.install.directoryCreated) {
+        await removeMigrationDirectoryIfEmpty(directory, input.rmdir);
+        await input.syncDirectory(dirname(directory));
+    }
+}
+function isCanonicalMigrationRegistrationState(record) {
+    return record.state === 'registering' || record.state === 'blocked' || record.state === 'committed';
+}
+async function completeMigrationRollbackPending(input) {
+    const assertCleanupAuthorityCurrent = async () => {
+        await input.assertOwnerCurrent();
+        assertAuthoritativeMigrationStateCurrent(input.env, input.expectedPayload, input.stateOptions);
+    };
+    const directory = dirname(input.record.destPath);
+    const storedHome = dirname(directory);
+    await assertCleanupAuthorityCurrent();
+    await assertSafeExistingMigrationTargetDirectory(storedHome, directory, input.assertDirectoryTrust);
+    if (input.record.installOwnership.disposition === 'installed') {
+        const quarantinePath = migrationRegistrationTargetQuarantinePath(input.record.destPath, input.record.intentId);
+        let targetPresent = true;
+        try {
+            await lstat(input.record.destPath);
+        }
+        catch (error) {
+            if (!isErrno(error, 'ENOENT'))
+                throw error;
+            targetPresent = false;
+        }
+        const quarantinePresent = await migrationPathIdentity(quarantinePath) !== undefined;
+        if (targetPresent || quarantinePresent) {
+            await cleanupInstalledMigrationBinary({
+                install: {
+                    disposition: 'installed',
+                    targetIdentity: input.record.targetIdentity,
+                    directoryCreated: false,
+                },
+                destPath: input.record.destPath,
+                version: input.record.version,
+                expectedSha256: input.record.targetIdentity.sha256,
+                quarantinePath,
+                readBinary: input.readBinary,
+                preflight: input.preflightFn,
+                rename: input.rename,
+                link: input.link,
+                unlink: input.unlink,
+                rmdir: input.rmdir,
+                syncDirectory: input.syncDirectory,
+                assertDirectoryTrust: input.assertDirectoryTrust,
+                assertFileTrust: input.assertFileTrust,
+                assertAuthorityCurrent: assertCleanupAuthorityCurrent,
+            });
+        }
+        else if (!input.record.installOwnership.directoryCreated) {
+            let directoryPresent = true;
+            try {
+                await lstat(directory);
+            }
+            catch (error) {
+                if (!isErrno(error, 'ENOENT'))
+                    throw error;
+                directoryPresent = false;
+            }
+            await assertCleanupAuthorityCurrent();
+            await input.syncDirectory(directoryPresent ? directory : dirname(directory));
+        }
+        if (input.record.installOwnership.directoryCreated) {
+            await assertCleanupAuthorityCurrent();
+            await removeMigrationDirectoryIfEmpty(directory, input.rmdir);
+            await input.syncDirectory(dirname(directory));
+        }
+    }
+    await assertCleanupAuthorityCurrent();
+    persistAuthoritativeMigrationState(input.env, {
+        state: 'rolled_back',
+        version: input.record.version,
+        destPath: input.record.destPath,
+        intentId: input.record.intentId,
+        targetIdentity: input.record.targetIdentity,
+        installOwnership: input.record.installOwnership,
+        reason: input.record.reason,
+    }, input.stateOptions);
+}
+async function reconcileStoredMigrationInstall(input) {
+    const { env, options, record, expectedPayload, stateOptions } = input;
+    const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
+    const failClosed = (reason, detail) => ({
+        action: 'return',
+        result: {
+            outcome: 'failed',
+            reason: `${code}:${reason}`,
+            destPath: record.destPath,
+            message: `one-time standalone migration recovery failed (${code}:${reason}:${errorDetail(detail)})`,
+            requiresForegroundExit: true,
+        },
+    });
+    const readBinary = options.readBinary ?? ((path) => fsReadFile(path));
+    const rename = options.rename ?? ((from, to) => fsRename(from, to));
+    const link = options.link ?? ((from, to) => fsLink(from, to));
+    const unlink = options.unlink ?? ((path) => fsUnlink(path));
+    const rmdir = options.rmdir ?? ((path) => fsRmdir(path));
+    const uid = options.uid ?? resolveProcessUid();
+    const assertDirectoryTrust = options.assertDirectoryTrust
+        ?? ((directory) => assertTrustedMigrationDirectoryChain(directory, uid));
+    const assertFileTrust = options.assertFileTrust
+        ?? ((path) => assertTrustedMigrationFile(path, uid));
+    const syncDirectory = options.syncDirectory ?? (async (path) => {
+        let handle;
+        try {
+            handle = await fsOpen(path, 'r');
+            await handle.sync();
+        }
+        catch (error) {
+            if (process.platform !== 'win32')
+                throw error;
+        }
+        finally {
+            await handle?.close();
+        }
+    });
+    try {
+        return await withMigrationLock(resolveBootstrapStateDir(env), async (assertOwnerLeaseCurrent) => {
+            assertOwnerLeaseCurrent();
+            assertAuthoritativeMigrationStateCurrent(env, expectedPayload, stateOptions);
+            const recovered = await recoverPendingMigrationInstall({
+                env,
+                stateOptions,
+                readBinary,
+                rename,
+                link,
+                unlink,
+                rmdir,
+                syncDirectory,
+                assertDirectoryTrust,
+                assertFileTrust,
+                assertOwnerCurrent: assertOwnerLeaseCurrent,
+                markCanonicalStateActive: () => undefined,
+            });
+            if (!recovered)
+                return failClosed('stored_install_changed', 'stored installing state changed');
+            return { action: 'retry_current' };
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'migration_lock_busy') {
+            return failClosed('migration_in_progress', 'another live process owns migration recovery');
+        }
+        return failClosed('recovery_failed', errorDetail(error));
+    }
+}
+async function reconcileStoredMigrationRollbackPending(input) {
+    const { env, options, record, expectedPayload, stateOptions } = input;
+    const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+    const failClosed = (reason, detail) => ({
+        action: 'return',
+        result: {
+            outcome: 'failed',
+            reason: `${code}:${reason}`,
+            destPath: record.destPath,
+            message: `one-time standalone migration rollback recovery failed (${code}:${reason}:${errorDetail(detail)})`,
+            requiresForegroundExit: true,
+        },
+    });
+    const readBinary = options.readBinary ?? ((path) => fsReadFile(path));
+    const preflightFn = options.preflightFn
+        ?? ((targetPath, expectedVersion) => preflightManagedStagedBinary(targetPath, expectedVersion, options.probe));
+    const rename = options.rename ?? ((from, to) => fsRename(from, to));
+    const link = options.link ?? ((from, to) => fsLink(from, to));
+    const unlink = options.unlink ?? ((path) => fsUnlink(path));
+    const rmdir = options.rmdir ?? ((path) => fsRmdir(path));
+    const uid = options.uid ?? resolveProcessUid();
+    const assertDirectoryTrust = options.assertDirectoryTrust
+        ?? ((directory) => assertTrustedMigrationDirectoryChain(directory, uid));
+    const assertFileTrust = options.assertFileTrust
+        ?? ((path) => assertTrustedMigrationFile(path, uid));
+    const syncDirectory = options.syncDirectory ?? (async (path) => {
+        let handle;
+        try {
+            handle = await fsOpen(path, 'r');
+            await handle.sync();
+        }
+        catch (error) {
+            if (process.platform !== 'win32')
+                throw error;
+        }
+        finally {
+            await handle?.close();
+        }
+    });
+    try {
+        return await withMigrationLock(resolveBootstrapStateDir(env), async (assertOwnerLeaseCurrent) => {
+            await completeMigrationRollbackPending({
+                env,
+                record,
+                expectedPayload,
+                stateOptions,
+                readBinary,
+                preflightFn,
+                rename,
+                link,
+                unlink,
+                rmdir,
+                syncDirectory,
+                assertDirectoryTrust,
+                assertFileTrust,
+                assertOwnerCurrent: assertOwnerLeaseCurrent,
+            });
+            return { action: 'retry_current' };
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'migration_lock_busy') {
+            return failClosed('migration_in_progress', 'another live process owns migration rollback recovery');
+        }
+        return failClosed('rollback_cleanup_failed', errorDetail(error));
+    }
+}
+async function reconcileStoredMigrationRegistration(input) {
+    const { env, platform, options, record, expectedPayload, stateOptions } = input;
+    const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+    const failed = (reason, message, _detail, requiresForegroundExit = false) => ({
+        outcome: 'failed',
+        reason,
+        destPath: record.destPath,
+        message,
+        ...(requiresForegroundExit ? { requiresForegroundExit: true } : {}),
+    });
+    const timedOut = (reason, message, detail, requiresForegroundExit) => failed(reason, message, detail, requiresForegroundExit);
+    const failClosed = (reason, detail) => ({
+        action: 'return',
+        result: {
+            outcome: 'failed',
+            reason: `${code}:${reason}`,
+            destPath: record.destPath,
+            message: `one-time standalone migration recovery failed (${code}:${reason}:${errorDetail(detail)})`,
+            requiresForegroundExit: true,
+        },
+    });
+    const timeoutMs = options.timeoutMs ?? MIGRATION_REGISTER_TIMEOUT_MS;
+    const transactionBudgetMs = options.transactionBudgetMs ?? MIGRATION_REGISTER_TRANSACTION_BUDGET_MS;
+    const readBinary = options.readBinary ?? ((path) => fsReadFile(path));
+    const rename = options.rename ?? ((from, to) => fsRename(from, to));
+    const link = options.link ?? ((from, to) => fsLink(from, to));
+    const unlink = options.unlink ?? ((path) => fsUnlink(path));
+    const rmdir = options.rmdir ?? ((path) => fsRmdir(path));
+    const syncDirectory = options.syncDirectory ?? (async (path) => {
+        let handle;
+        try {
+            handle = await fsOpen(path, 'r');
+            await handle.sync();
+        }
+        catch (error) {
+            if (process.platform !== 'win32')
+                throw error;
+        }
+        finally {
+            await handle?.close();
+        }
+    });
+    const preflightFn = options.preflightFn
+        ?? ((targetPath, expectedVersion) => preflightManagedStagedBinary(targetPath, expectedVersion, options.probe));
+    const uid = options.uid ?? resolveProcessUid();
+    const assertDirectoryTrust = options.assertDirectoryTrust
+        ?? ((directory) => assertTrustedMigrationDirectoryChain(directory, uid));
+    const assertFileTrust = options.assertFileTrust
+        ?? ((path) => assertTrustedMigrationFile(path, uid));
+    try {
+        return await withMigrationLock(resolveBootstrapStateDir(env), async (assertOwnerLeaseCurrent) => {
+            const assertStoredIntentCurrent = async () => {
+                assertOwnerLeaseCurrent();
+                assertAuthoritativeMigrationStateCurrent(env, expectedPayload, stateOptions);
+            };
+            const sealedIdentity = Object.freeze({ ...record.targetIdentity });
+            const revalidateStoredTarget = () => assertMigrationTargetIdentityCurrent(sealedIdentity, record.version, { readBinary, preflightFn, assertDirectoryTrust, assertFileTrust });
+            if (!Number.isSafeInteger(timeoutMs)
+                || !Number.isSafeInteger(transactionBudgetMs)
+                || timeoutMs <= transactionBudgetMs
+                || timeoutMs > MAX_TIMER_DELAY_MS
+                || transactionBudgetMs <= 0) {
+                return failClosed('invalid_registration_timeout_contract', 'invalid registration timeout contract');
+            }
+            if (!options.registrationRunner) {
+                return failClosed('registration_runner_unavailable', 'registration runner unavailable');
+            }
+            try {
+                await assertStoredIntentCurrent();
+                await revalidateStoredTarget();
+            }
+            catch (error) {
+                return failClosed('stored_target_revalidation_failed', errorDetail(error));
+            }
+            const registration = await register(env, platform, record.version, record.destPath, sealedIdentity, revalidateStoredTarget, assertStoredIntentCurrent, options, timeoutMs, transactionBudgetMs, failed, timedOut);
+            try {
+                await assertStoredIntentCurrent();
+            }
+            catch (error) {
+                return failClosed('stored_intent_changed', errorDetail(error));
+            }
+            const intentBase = {
+                version: record.version,
+                destPath: record.destPath,
+                intentId: record.intentId,
+                targetIdentity: sealedIdentity,
+                installOwnership: record.installOwnership,
+            };
+            if (registration.outcome === 'migrated') {
+                persistAuthoritativeMigrationState(env, { state: 'committed', ...intentBase }, stateOptions);
+                recordBootstrapAttempt(env, { ok: true, reason: 'migrated', detail: record.destPath }, stateOptions);
+                return { action: 'return', result: registration };
+            }
+            if (registration.requiresForegroundExit === true) {
+                try {
+                    persistAuthoritativeMigrationState(env, { state: 'blocked', ...intentBase, reason: registration.reason }, stateOptions);
+                }
+                catch {
+                    // Preserve the exact prior active record when blocked-state publication is uncertain.
+                }
+                return { action: 'return', result: registration };
+            }
+            const rollbackPendingRecord = {
+                state: 'rollback_pending',
+                ...intentBase,
+                reason: registration.reason,
+            };
+            let rollbackPendingPayload;
+            try {
+                await assertStoredIntentCurrent();
+                rollbackPendingPayload = persistAuthoritativeMigrationState(env, rollbackPendingRecord, stateOptions);
+            }
+            catch (error) {
+                return failClosed('rollback_intent_persistence_failed', errorDetail(error));
+            }
+            try {
+                await completeMigrationRollbackPending({
+                    env,
+                    record: { ...intentBase, reason: registration.reason },
+                    expectedPayload: rollbackPendingPayload,
+                    stateOptions,
+                    readBinary,
+                    preflightFn,
+                    rename,
+                    link,
+                    unlink,
+                    rmdir,
+                    syncDirectory,
+                    assertDirectoryTrust,
+                    assertFileTrust,
+                    assertOwnerCurrent: assertOwnerLeaseCurrent,
+                });
+            }
+            catch (error) {
+                return failClosed('stored_target_cleanup_failed', errorDetail(error));
+            }
+            return { action: 'retry_current' };
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'migration_lock_busy') {
+            return failClosed('migration_in_progress', 'another live process owns migration recovery');
+        }
+        return failClosed('stored_reconciliation_failed', errorDetail(error));
+    }
 }
 /**
  * One-time migration of the npm/JS install shape to the standalone release binary.
- * Never throws: every failure/skip becomes a structured MigrationResult so degraded
- * startup can keep running with self-update off.
+ * Never throws: every failure/skip becomes a structured MigrationResult. Only a proven clean
+ * failure may continue degraded; ambiguous registration ownership requires foreground exit.
  */
 export async function migrateToStandaloneBinary(env, platform = process.platform, options = {}) {
     const now = options.now ?? Date.now();
     const exists = options.exists ?? existsSync;
     const readText = options.readFile ?? defaultReadTextFile;
     const recordOptions = { now, ...(options.writeFile ? { writeFile: options.writeFile } : {}) };
+    const stateOptions = {
+        ...recordOptions,
+        ...(options.assertStateDirectoryTrust
+            ? { assertStateDirectoryTrust: options.assertStateDirectoryTrust }
+            : {}),
+        ...(options.assertStateFileTrust
+            ? { assertStateFileTrust: options.assertStateFileTrust }
+            : {}),
+    };
+    const startupState = inspectMigrationStartupState(env, stateOptions);
+    if (startupState.classification === 'unsafe') {
+        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+        return {
+            outcome: 'failed',
+            reason: `${code}:migration_state_unsafe`,
+            message: `one-time standalone migration failed (${code}:migration_state_unsafe:${startupState.detail})`,
+            requiresForegroundExit: true,
+        };
+    }
+    const hadPriorAmbiguity = startupState.classification === 'retryable'
+        || (!startupState.canonicalPresent && unresolvedLegacyMigrationOwnership(env, readText));
+    let ownerLeaseHeld = false;
+    // A prior active canonical record remains the recovery authority until this owner publishes
+    // a new authoritative install/registration transition. Advisory progress/failure writes must
+    // never erase the only durable evidence of possible artifact or child ownership.
+    let canonicalMutationStateActive = startupState.classification === 'retryable';
     const skipped = (reason, message) => {
-        writeMigrationState(env, { state: 'skipped', reason }, options);
+        if (hadPriorAmbiguity) {
+            return {
+                outcome: 'failed',
+                reason: `${SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED}:ambiguous_pending:${reason}`,
+                message: 'one-time standalone migration cannot skip while registration ownership is unresolved',
+                requiresForegroundExit: true,
+            };
+        }
         return { outcome: 'skipped', reason, message };
     };
     // Gate order: switch → root → CI → container → cooldown. shouldBootstrap returns
@@ -168,9 +2036,57 @@ export async function migrateToStandaloneBinary(env, platform = process.platform
     if (platform === 'linux' && looksLikeContainer(exists, readText)) {
         return skipped('container_environment', 'one-time standalone migration skipped in a container');
     }
-    if (recentBootstrapFailure(env, readText, now)) {
+    // A prior ambiguous attempt is retried through signed artifact validation and the durable
+    // lifecycle reconciler. Until a registration succeeds, every new failure stays fail-closed.
+    if (!hadPriorAmbiguity && recentBootstrapFailure(env, readText, now)) {
         return skipped('cooldown', 'one-time standalone migration skipped (recent bootstrap failure cooldown)');
     }
+    if (startupState.classification === 'retryable'
+        && startupState.record.state === 'installing') {
+        const reconciliation = await reconcileStoredMigrationInstall({
+            env,
+            options,
+            record: startupState.record,
+            expectedPayload: startupState.raw,
+            stateOptions,
+        });
+        if (reconciliation.action === 'return')
+            return reconciliation.result;
+        // Recovery used the exact stored version/destination transaction and durably terminalized
+        // it. Re-read the environment only after that authority has been released.
+        return migrateToStandaloneBinary(env, platform, options);
+    }
+    if (startupState.classification === 'retryable'
+        && startupState.record.state === 'rollback_pending') {
+        const reconciliation = await reconcileStoredMigrationRollbackPending({
+            env,
+            options,
+            record: startupState.record,
+            expectedPayload: startupState.raw,
+            stateOptions,
+        });
+        if (reconciliation.action === 'return')
+            return reconciliation.result;
+        // Cleanup is idempotently complete and terminal state is durable; only now may the current
+        // version/home request replace the old transaction authority.
+        return migrateToStandaloneBinary(env, platform, options);
+    }
+    if (startupState.classification === 'retryable'
+        && isCanonicalMigrationRegistrationState(startupState.record)) {
+        const reconciliation = await reconcileStoredMigrationRegistration({
+            env,
+            platform,
+            options,
+            record: startupState.record,
+            expectedPayload: startupState.raw,
+            stateOptions,
+        });
+        if (reconciliation.action === 'return')
+            return reconciliation.result;
+        // The exact old transaction is now durably rolled back. Re-read canonical state before
+        // beginning the current version/home request so no stale in-memory authority crosses it.
+        return migrateToStandaloneBinary(env, platform, options);
+    }
     // RESOLVE: version, asset name, dest path.
     const version = resolveMigrationVersion(env);
     if (!version) {
@@ -186,130 +2102,571 @@ export async function migrateToStandaloneBinary(env, platform = process.platform
         // Unsupported platform (e.g. win-arm64): skip without recording a cooldown-worthy attempt.
         return skipped('unsupported_platform', `one-time standalone migration skipped (unsupported platform ${platform}/${options.arch ?? process.arch})`);
     }
-    const destPath = join(resolveMigrationHome(env), 'bin', assetName);
-    writeMigrationState(env, { state: 'in_progress', version, destPath }, options);
-    const fail = (reason, message, attemptDetail) => {
-        recordBootstrapAttempt(env, { ok: false, reason: 'migration_failed', detail: attemptDetail ?? reason }, recordOptions);
-        writeMigrationState(env, { state: 'failed', version, destPath, reason }, options);
-        return { outcome: 'failed', reason, destPath, message };
+    const migrationHome = resolveMigrationHome(env);
+    const destPath = join(migrationHome, 'bin', assetName);
+    const fail = (reason, message, attemptDetail, requiresForegroundExit = false, preserveCanonicalState = false) => {
+        const mustExit = requiresForegroundExit || hadPriorAmbiguity;
+        if (ownerLeaseHeld) {
+            recordBootstrapAttempt(env, {
+                ok: false,
+                reason: mustExit ? 'migration_ambiguous' : 'migration_failed',
+                detail: attemptDetail ?? reason,
+            }, recordOptions);
+            if (!canonicalMutationStateActive && !preserveCanonicalState && !mustExit) {
+                writeMigrationState(env, { state: 'failed', version, destPath, reason }, options);
+            }
+        }
+        return {
+            outcome: 'failed',
+            reason,
+            destPath,
+            message,
+            ...(mustExit ? { requiresForegroundExit: true } : {}),
+        };
     };
-    const failTimeout = (reason, message, attemptDetail) => {
-        recordBootstrapAttempt(env, { ok: false, reason: 'migration_timeout', detail: attemptDetail }, recordOptions);
-        writeMigrationState(env, { state: 'failed', version, destPath, reason }, options);
-        return { outcome: 'failed', reason, destPath, message };
+    const failTimeout = (reason, message, attemptDetail, requiresForegroundExit = true) => {
+        const mustExit = requiresForegroundExit || hadPriorAmbiguity;
+        if (ownerLeaseHeld) {
+            recordBootstrapAttempt(env, {
+                ok: false,
+                reason: mustExit ? 'migration_ambiguous' : 'migration_timeout',
+                detail: attemptDetail,
+            }, recordOptions);
+            if (!canonicalMutationStateActive && !mustExit) {
+                writeMigrationState(env, { state: 'failed', version, destPath, reason }, options);
+            }
+        }
+        return {
+            outcome: 'failed',
+            reason,
+            destPath,
+            message,
+            ...(mustExit ? { requiresForegroundExit: true } : {}),
+        };
     };
+    const timeoutMs = options.timeoutMs ?? MIGRATION_REGISTER_TIMEOUT_MS;
+    const transactionBudgetMs = options.transactionBudgetMs ?? MIGRATION_REGISTER_TRANSACTION_BUDGET_MS;
+    if (!options.registrationRunner) {
+        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+        return fail(`${code}:registration_runner_unavailable`, `one-time standalone migration failed (${code}:registration_runner_unavailable)`, `${code}: registration_runner_unavailable`);
+    }
+    if (!Number.isSafeInteger(timeoutMs)
+        || !Number.isSafeInteger(transactionBudgetMs)
+        || timeoutMs <= transactionBudgetMs
+        || timeoutMs > MAX_TIMER_DELAY_MS
+        || transactionBudgetMs <= 0) {
+        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+        return fail(`${code}:invalid_registration_timeout_contract`, `one-time standalone migration failed (${code}:invalid_registration_timeout_contract)`, `${code}: invalid_registration_timeout_contract`);
+    }
     const readBinary = options.readBinary ?? ((path) => fsReadFile(path));
     const writeBinary = options.writeBinary
-        ?? ((path, content, mode) => fsWriteFile(path, content, { mode }));
+        ?? ((path, content, mode) => fsWriteFile(path, content, { mode, flag: 'wx' }));
     const mkdir = options.mkdir ?? ((path, mode) => fsMkdir(path, { recursive: true, mode }).then(() => undefined));
     const rm = options.rm ?? ((path) => fsRm(path, { recursive: true, force: true }));
-    const rename = options.rename ?? ((from, to) => fsRename(from, to));
+    const unlink = options.unlink ?? ((path) => fsUnlink(path));
+    const rmdir = options.rmdir ?? ((path) => fsRmdir(path));
     const chmod = options.chmod ?? ((path, mode) => fsChmod(path, mode));
+    const syncFile = options.syncFile ?? (async (path) => {
+        const handle = await fsOpen(path, 'r+');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    });
+    const syncDirectory = options.syncDirectory ?? (async (path) => {
+        let handle;
+        try {
+            handle = await fsOpen(path, 'r');
+            await handle.sync();
+        }
+        catch (error) {
+            // Windows does not expose reliable directory fsync handles; the executable is fsynced.
+            if (process.platform !== 'win32')
+                throw error;
+        }
+        finally {
+            await handle?.close();
+        }
+    });
     const stat = options.stat ?? ((path) => lstat(path));
+    const link = options.link ?? ((from, to) => fsLink(from, to));
+    const rename = options.rename ?? ((from, to) => fsRename(from, to));
     const preflightFn = options.preflightFn
         ?? ((targetPath, expectedVersion) => preflightManagedStagedBinary(targetPath, expectedVersion, options.probe));
     const downloadFn = options.downloadFn ?? downloadGithubReleaseArtifact;
     const verifyFn = options.verifyFn
         ?? ((manifest, downloaded, publicKey) => ops.verifySelectedManifestArtifact(manifest, downloaded, publicKey));
-    // Fast path: an existing dest that passes the real preflight only needs registration.
-    if (exists(destPath)) {
-        try {
-            await preflightFn(destPath, version);
-            return register(env, version, destPath, options, exists, recordOptions, fail, failTimeout, writeMigrationState);
-        }
-        catch {
-            // Existing binary is unusable — fall through and download a fresh copy over it.
-        }
-    }
-    // DOWNLOAD: signed manifest + staged binary under tmpdir.
-    const directive = { required_version: version };
-    const releaseOpts = {
-        env,
-        platform,
-        arch: options.arch,
-        fetchFn: options.fetchFn,
-        requireSignedManifest: true,
-    };
-    let manifest;
-    let download;
+    const assertDirectoryTrust = options.assertDirectoryTrust
+        ?? ((directory) => assertTrustedMigrationDirectoryChain(directory, uid));
+    const assertFileTrust = options.assertFileTrust
+        ?? ((path) => assertTrustedMigrationFile(path, uid));
+    // Pure contract and read-only target validation precede even lock-namespace creation.
     try {
-        manifest = await resolveGithubReleaseManifest(directive, releaseOpts);
-        download = await downloadFn(version, directive, releaseOpts);
+        await assertSafeExistingMigrationTargetDirectory(migrationHome, dirname(destPath), assertDirectoryTrust);
     }
     catch (err) {
-        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_DOWNLOAD_FAILED;
+        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
         return fail(`${code}:${errorDetail(err)}`, `one-time standalone migration failed (${code})`, `${code}: ${errorDetail(err)}`);
     }
-    const stagedDir = dirname(download.stagedPath);
-    // VERIFY: ed25519 signature over the complete manifest + sha256 of the staged bytes.
-    // Fail closed: unverified bytes are NEVER written into the user's home.
-    const verification = verifyFn(manifest, download.artifacts, resolveSelfUpdatePublicKey(env));
-    if (!verification.ok) {
-        await rmSafe(rm, stagedDir);
-        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_VERIFY_FAILED;
-        return fail(`${code}:${verification.reason}`, `one-time standalone migration failed (${code})`, `${code}: ${verification.reason}`);
-    }
-    // Preflight the staged binary for real (`--version` + `proxy --help`) before install.
+    const migrationLockDirectory = resolveBootstrapStateDir(env);
     try {
-        await preflightFn(download.stagedPath, version);
+        await ensureSafeMigrationDirectory(migrationLockDirectory, mkdir, assertDirectoryTrust);
     }
     catch (err) {
-        await rmSafe(rm, stagedDir);
-        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_VERIFY_FAILED;
-        const detail = `preflight:${errorDetail(err)}`;
-        return fail(`${code}:${detail}`, `one-time standalone migration failed (${code})`, `${code}: ${detail}`);
-    }
-    // INSTALL: atomic copy into <home>/bin (verified bytes only).
-    try {
-        await mkdir(dirname(destPath), 0o700);
-        const stagedStat = await stat(download.stagedPath);
-        if (stagedStat.isSymbolicLink() || !stagedStat.isFile()) {
-            throw new Error('staged_artifact_not_regular_file');
-        }
-        const bytes = await readBinary(download.stagedPath);
-        const tmpDest = `${destPath}.tmp`;
-        try {
-            await writeBinary(tmpDest, bytes, 0o755);
-            await chmod(tmpDest, 0o755);
-            await rename(tmpDest, destPath);
-        }
-        catch (err) {
-            await rmSafe(rm, tmpDest);
-            throw err;
-        }
-    }
-    catch (err) {
-        await rmSafe(rm, stagedDir);
         const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
         return fail(`${code}:${errorDetail(err)}`, `one-time standalone migration failed (${code})`, `${code}: ${errorDetail(err)}`);
     }
-    finally {
-        await rmSafe(rm, stagedDir);
+    try {
+        return await withMigrationLock(migrationLockDirectory, async (assertOwnerLeaseCurrent) => {
+            ownerLeaseHeld = true;
+            try {
+                const recoveredInstall = await recoverPendingMigrationInstall({
+                    env,
+                    stateOptions,
+                    readBinary,
+                    rename,
+                    link,
+                    unlink,
+                    rmdir,
+                    syncDirectory,
+                    assertDirectoryTrust,
+                    assertFileTrust,
+                    assertOwnerCurrent: assertOwnerLeaseCurrent,
+                    markCanonicalStateActive: () => {
+                        canonicalMutationStateActive = true;
+                    },
+                });
+                if (recoveredInstall)
+                    canonicalMutationStateActive = true;
+            }
+            catch (error) {
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
+                return fail(`${code}:recovery_failed`, `one-time standalone migration failed (${code}:recovery_failed)`, `${code}: recovery_failed:${errorDetail(error)}`, true);
+            }
+            // Revalidate after acquiring ownership so the read-before-mutation check cannot go stale.
+            try {
+                await assertSafeExistingMigrationTargetDirectory(migrationHome, dirname(destPath), assertDirectoryTrust);
+            }
+            catch (err) {
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
+                return fail(`${code}:${errorDetail(err)}`, `one-time standalone migration failed (${code})`, `${code}: ${errorDetail(err)}`);
+            }
+            if (!canonicalMutationStateActive) {
+                writeMigrationState(env, { state: 'in_progress', version, destPath }, options);
+            }
+            // DOWNLOAD: signed manifest + staged binary under tmpdir.
+            const directive = { required_version: version };
+            const releaseOpts = {
+                env,
+                platform,
+                arch: options.arch,
+                fetchFn: options.fetchFn,
+                requireSignedManifest: true,
+            };
+            let manifest;
+            let download;
+            try {
+                manifest = await resolveGithubReleaseManifest(directive, releaseOpts);
+                download = await downloadFn(version, directive, releaseOpts);
+            }
+            catch (err) {
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_DOWNLOAD_FAILED;
+                return fail(`${code}:${errorDetail(err)}`, `one-time standalone migration failed (${code})`, `${code}: ${errorDetail(err)}`);
+            }
+            const stagedDir = dirname(download.stagedPath);
+            // VERIFY: ed25519 signature over the complete manifest + sha256 of the staged bytes.
+            // Fail closed: unverified bytes are NEVER written into the user's home.
+            const verification = verifyFn(manifest, download.artifacts, resolveSelfUpdatePublicKey(env));
+            if (!verification.ok) {
+                await rmSafe(rm, stagedDir);
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_VERIFY_FAILED;
+                const detail = errorDetail(verification.reason);
+                return fail(`${code}:${detail}`, `one-time standalone migration failed (${code})`, `${code}: ${detail}`);
+            }
+            let stagedBytes;
+            let expectedSha256;
+            try {
+                const stagedStat = await stat(download.stagedPath);
+                if (stagedStat.isSymbolicLink() || !stagedStat.isFile()) {
+                    throw new Error('staged_artifact_not_regular_file');
+                }
+                stagedBytes = await readBinary(download.stagedPath);
+                const selected = download.artifacts.length === 1 && download.artifacts[0]?.path === assetName
+                    ? download.artifacts[0]
+                    : undefined;
+                expectedSha256 = selected?.sha256 ?? (selected?.bytes ? sha256(selected.bytes) : '');
+                if (!/^[0-9a-f]{64}$/.test(expectedSha256) || sha256(stagedBytes) !== expectedSha256) {
+                    throw new Error('staged_artifact_hash_mismatch');
+                }
+                // Preflight the staged binary for real (`--version` + `proxy --help`) before install.
+                await preflightFn(download.stagedPath, version);
+            }
+            catch (err) {
+                await rmSafe(rm, stagedDir);
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_VERIFY_FAILED;
+                const detail = `preflight:${errorDetail(err)}`;
+                return fail(`${code}:${detail}`, `one-time standalone migration failed (${code})`, `${code}: ${detail}`);
+            }
+            await rmSafe(rm, stagedDir);
+            // The same lease spans INSTALL -> identity revalidation -> REGISTER -> conditional cleanup.
+            // A second process must never register the target while this owner can still roll it back.
+            let installResult;
+            let installAnchor;
+            try {
+                installResult = await installVerifiedMigrationBinary({
+                    home: migrationHome,
+                    destPath,
+                    version,
+                    bytes: stagedBytes,
+                    expectedSha256,
+                    mkdir,
+                    writeBinary,
+                    readBinary,
+                    chmod,
+                    syncFile,
+                    syncDirectory,
+                    stat,
+                    link,
+                    rename,
+                    unlink,
+                    rmdir,
+                    preflight: preflightFn,
+                    assertDirectoryTrust,
+                    assertFileTrust,
+                    publishInstallIntent: async (anchor) => {
+                        const previousAnchor = installAnchor;
+                        const installingRecord = {
+                            state: 'installing',
+                            version,
+                            destPath,
+                            installAnchor: anchor,
+                        };
+                        const expectedPayload = serializeMigrationState(installingRecord, recordOptions);
+                        assertOwnerLeaseCurrent();
+                        try {
+                            persistAuthoritativeMigrationState(env, installingRecord, stateOptions);
+                            installAnchor = anchor;
+                            canonicalMutationStateActive = true;
+                        }
+                        catch (error) {
+                            try {
+                                const expectedPublished = readTrustedMigrationStateText(join(resolveBootstrapStateDir(env), MIGRATION_STATE_FILE), stateOptions) === expectedPayload;
+                                if (expectedPublished) {
+                                    canonicalMutationStateActive = true;
+                                    installAnchor = anchor;
+                                }
+                                else if (previousAnchor) {
+                                    canonicalMutationStateActive = true;
+                                    installAnchor = previousAnchor;
+                                }
+                                else {
+                                    canonicalMutationStateActive = false;
+                                }
+                            }
+                            catch {
+                                canonicalMutationStateActive = true;
+                                installAnchor = previousAnchor ?? anchor;
+                            }
+                            throw error;
+                        }
+                    },
+                });
+            }
+            catch (err) {
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
+                const detail = errorDetail(err);
+                let ambiguous = detail.startsWith('migration_install_rollback_unconfirmed:');
+                let rollbackTerminalized = false;
+                if (canonicalMutationStateActive && installAnchor && !ambiguous) {
+                    try {
+                        assertOwnerLeaseCurrent();
+                        persistAuthoritativeMigrationState(env, { state: 'rolled_back', version, destPath, installAnchor, reason: detail }, stateOptions);
+                        rollbackTerminalized = true;
+                    }
+                    catch {
+                        ambiguous = true;
+                    }
+                }
+                return fail(`${code}:${detail}`, `one-time standalone migration failed (${code})`, `${code}: ${detail}`, ambiguous || (canonicalMutationStateActive && !rollbackTerminalized));
+            }
+            let registrationIdentity;
+            try {
+                const currentIdentity = await inspectExistingMigrationTarget(destPath, version, preflightFn, readBinary, { sha256: expectedSha256, size: stagedBytes.byteLength }, assertDirectoryTrust, assertFileTrust);
+                if (!currentIdentity || !sameMigrationTargetIdentity(currentIdentity, installResult.targetIdentity)) {
+                    throw new Error('migration_target_identity_changed_before_registration');
+                }
+                registrationIdentity = currentIdentity;
+            }
+            catch (error) {
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+                return fail(`${code}:target_identity_changed`, `one-time standalone migration failed (${code}:target_identity_changed)`, `${code}: target_identity_changed:${errorDetail(error)}`, true);
+            }
+            // REGISTER: delegate to the ordinary lifecycle bootstrap transaction runner.
+            const sealedRegistrationIdentity = Object.freeze({ ...registrationIdentity });
+            const revalidateTarget = () => assertMigrationTargetIdentityCurrent(sealedRegistrationIdentity, version, { readBinary, preflightFn, assertDirectoryTrust, assertFileTrust });
+            const intentId = randomUUID();
+            const intentBase = {
+                version,
+                destPath,
+                intentId,
+                targetIdentity: sealedRegistrationIdentity,
+                installOwnership: {
+                    disposition: installResult.disposition,
+                    preimage: installResult.disposition === 'installed' ? 'absent' : 'matching_target',
+                    directoryCreated: installResult.directoryCreated,
+                },
+            };
+            const registeringRecord = { state: 'registering', ...intentBase };
+            const expectedIntentPayload = serializeMigrationState(registeringRecord, recordOptions);
+            let registrationIntentPayload;
+            try {
+                assertOwnerLeaseCurrent();
+                registrationIntentPayload = persistAuthoritativeMigrationState(env, registeringRecord, stateOptions);
+                canonicalMutationStateActive = true;
+            }
+            catch (error) {
+                let intentRollbackTerminalized = false;
+                let intentAuthorityAmbiguous = false;
+                let currentAuthoritativePayload;
+                try {
+                    currentAuthoritativePayload = readTrustedMigrationStateText(join(resolveBootstrapStateDir(env), MIGRATION_STATE_FILE), stateOptions);
+                }
+                catch {
+                    canonicalMutationStateActive = true;
+                    intentAuthorityAmbiguous = true;
+                }
+                if (!intentAuthorityAmbiguous && currentAuthoritativePayload === expectedIntentPayload) {
+                    canonicalMutationStateActive = true;
+                    try {
+                        assertOwnerLeaseCurrent();
+                        const rollbackPendingPayload = persistAuthoritativeMigrationState(env, { state: 'rollback_pending', ...intentBase, reason: 'intent_persistence_failed' }, stateOptions);
+                        await completeMigrationRollbackPending({
+                            env,
+                            record: { ...intentBase, reason: 'intent_persistence_failed' },
+                            expectedPayload: rollbackPendingPayload,
+                            stateOptions,
+                            readBinary,
+                            preflightFn,
+                            rename,
+                            link,
+                            unlink,
+                            rmdir,
+                            syncDirectory,
+                            assertDirectoryTrust,
+                            assertFileTrust,
+                            assertOwnerCurrent: assertOwnerLeaseCurrent,
+                        });
+                        intentRollbackTerminalized = true;
+                    }
+                    catch (cleanupError) {
+                        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
+                        return fail(`${code}:cleanup_failed`, `one-time standalone migration failed (${code}:cleanup_failed)`, `${code}: cleanup_failed:${errorDetail(cleanupError)}`, true, true);
+                    }
+                }
+                else if (!intentAuthorityAmbiguous && currentAuthoritativePayload !== undefined) {
+                    const currentRecord = parseCanonicalMigrationState(currentAuthoritativePayload);
+                    if (currentRecord?.state !== 'installing'
+                        || currentRecord.version !== version
+                        || currentRecord.destPath !== destPath
+                        || !installAnchor
+                        || !sameMigrationInstallAnchor(currentRecord.installAnchor, installAnchor)) {
+                        canonicalMutationStateActive = true;
+                        intentAuthorityAmbiguous = true;
+                    }
+                    else {
+                        canonicalMutationStateActive = true;
+                        try {
+                            const recovered = await recoverPendingMigrationInstall({
+                                env,
+                                stateOptions,
+                                readBinary,
+                                rename,
+                                link,
+                                unlink,
+                                rmdir,
+                                syncDirectory,
+                                assertDirectoryTrust,
+                                assertFileTrust,
+                                assertOwnerCurrent: assertOwnerLeaseCurrent,
+                                markCanonicalStateActive: () => {
+                                    canonicalMutationStateActive = true;
+                                },
+                            });
+                            if (!recovered)
+                                throw new Error('migration_install_journal_changed');
+                            intentRollbackTerminalized = true;
+                        }
+                        catch (cleanupError) {
+                            const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
+                            return fail(`${code}:cleanup_failed`, `one-time standalone migration failed (${code}:cleanup_failed)`, `${code}: cleanup_failed:${errorDetail(cleanupError)}`, true, true);
+                        }
+                    }
+                }
+                else if (!intentAuthorityAmbiguous) {
+                    // The installed artifact cannot be deleted without a durable transaction record.
+                    canonicalMutationStateActive = true;
+                    intentAuthorityAmbiguous = true;
+                }
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+                return fail(`${code}:intent_persistence_failed`, `one-time standalone migration failed (${code}:intent_persistence_failed)`, `${code}: intent_persistence_failed:${errorDetail(error)}`, intentAuthorityAmbiguous || !intentRollbackTerminalized, true);
+            }
+            const assertRegistrationIntentCurrent = async () => {
+                assertOwnerLeaseCurrent();
+                assertAuthoritativeMigrationStateCurrent(env, registrationIntentPayload, stateOptions);
+            };
+            const registration = await register(env, platform, version, destPath, sealedRegistrationIdentity, revalidateTarget, assertRegistrationIntentCurrent, options, timeoutMs, transactionBudgetMs, fail, failTimeout);
+            if (registration.outcome === 'failed' && registration.requiresForegroundExit === true) {
+                try {
+                    assertOwnerLeaseCurrent();
+                    persistAuthoritativeMigrationState(env, { state: 'blocked', ...intentBase, reason: registration.reason }, stateOptions);
+                }
+                catch {
+                    // Preserve the already durable registering intent if blocked-state publication fails.
+                }
+                return registration;
+            }
+            if (registration.outcome === 'failed') {
+                try {
+                    await assertRegistrationIntentCurrent();
+                    const rollbackPendingPayload = persistAuthoritativeMigrationState(env, { state: 'rollback_pending', ...intentBase, reason: registration.reason }, stateOptions);
+                    canonicalMutationStateActive = true;
+                    await completeMigrationRollbackPending({
+                        env,
+                        record: { ...intentBase, reason: registration.reason },
+                        expectedPayload: rollbackPendingPayload,
+                        stateOptions,
+                        readBinary,
+                        preflightFn,
+                        rename,
+                        link,
+                        unlink,
+                        rmdir,
+                        syncDirectory,
+                        assertDirectoryTrust,
+                        assertFileTrust,
+                        assertOwnerCurrent: assertOwnerLeaseCurrent,
+                    });
+                    canonicalMutationStateActive = false;
+                }
+                catch (error) {
+                    const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_INSTALL_FAILED;
+                    return fail(`${code}:cleanup_failed`, `one-time standalone migration failed (${code}:cleanup_failed)`, `${code}: cleanup_failed:${errorDetail(error)}`, true);
+                }
+                return registration;
+            }
+            try {
+                assertOwnerLeaseCurrent();
+                persistAuthoritativeMigrationState(env, { state: 'committed', ...intentBase }, stateOptions);
+                canonicalMutationStateActive = false;
+            }
+            catch (error) {
+                const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+                return fail(`${code}:commit_persistence_failed`, `one-time standalone migration failed (${code}:commit_persistence_failed)`, `${code}: commit_persistence_failed:${errorDetail(error)}`, true);
+            }
+            recordBootstrapAttempt(env, { ok: true, reason: 'migrated', detail: destPath }, recordOptions);
+            return registration;
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'migration_lock_busy') {
+            return {
+                outcome: 'failed',
+                reason: `${SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED}:migration_in_progress`,
+                destPath,
+                message: 'one-time standalone migration is already owned by another live process',
+                requiresForegroundExit: true,
+            };
+        }
+        const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
+        return fail(`${code}:owner_lease_failed`, `one-time standalone migration failed (${code}:owner_lease_failed)`, `${code}: owner_lease_failed:${errorDetail(error)}`, true, true);
     }
-    // REGISTER: hand the installed binary to `evolver lifecycle bootstrap`.
-    return register(env, version, destPath, options, exists, recordOptions, fail, failTimeout, writeMigrationState);
 }
-async function register(env, version, destPath, options, exists, recordOptions, fail, failTimeout, writeState) {
+async function register(env, platform, version, destPath, targetIdentity, revalidateTarget, assertRegistrationIntentCurrent, options, timeoutMs, transactionBudgetMs, fail, failTimeout) {
     const code = SELF_UPDATE_FAILURE_CODES.MIGRATION_REGISTER_FAILED;
-    const registration = await registerMigratedBinary(env, destPath, options, exists);
-    if (registration.reason === 'cli_not_found') {
-        return fail(`${code}:cli_not_found`, `one-time standalone migration failed (${code}:cli_not_found)`, `${code}: cli_not_found`);
+    const runner = options.registrationRunner;
+    if (!runner) {
+        return fail(`${code}:registration_runner_unavailable`, `one-time standalone migration failed (${code}:registration_runner_unavailable)`, `${code}: registration_runner_unavailable`);
+    }
+    let startedAtMs;
+    try {
+        startedAtMs = (options.clock ?? Date.now)();
+    }
+    catch (error) {
+        return fail(`${code}:registration_clock_failed`, `one-time standalone migration failed (${code}:registration_clock_failed)`, `${code}: registration_clock_failed:${errorDetail(error)}`);
     }
-    if (registration.reason === 'timeout') {
-        return failTimeout('migration_register_timeout', `one-time standalone migration failed (${code}:timeout)`, `${code}: timeout`);
+    const transactionDeadlineMs = startedAtMs + transactionBudgetMs;
+    const parentDeadlineMs = startedAtMs + timeoutMs;
+    if (!Number.isSafeInteger(startedAtMs)
+        || startedAtMs < 0
+        || !Number.isSafeInteger(transactionDeadlineMs)
+        || !Number.isSafeInteger(parentDeadlineMs)) {
+        return fail(`${code}:invalid_registration_deadline`, `one-time standalone migration failed (${code}:invalid_registration_deadline)`, `${code}: invalid_registration_deadline`);
     }
+    const request = Object.freeze({
+        env: Object.freeze({ ...env, EVOLVER_SELF_UPDATE_TARGET_PATH: destPath }),
+        platform,
+        version,
+        startedAtMs,
+        transactionDeadlineMs,
+        parentDeadlineMs,
+        transactionBudgetMs,
+        timeoutMs,
+        targetIdentity,
+        revalidateTarget,
+        assertRegistrationIntentCurrent,
+        // Registration must execute the verified standalone binary, never the npm/JS Node entry.
+        execPath: destPath,
+        ...(options.exists !== undefined ? { exists: options.exists } : {}),
+        ...(options.readFile !== undefined ? { readFile: options.readFile } : {}),
+        ...(options.writeFile !== undefined ? { writeFile: options.writeFile } : {}),
+        ...(options.spawnFn !== undefined ? { spawnFn: options.spawnFn } : {}),
+    });
+    let registration;
+    try {
+        registration = await runner(request);
+    }
+    catch (error) {
+        return fail(`${code}:runner_threw`, `one-time standalone migration failed (${code}:runner_threw)`, errorDetail(`${code}: runner_threw:${errorDetail(error)}`), true);
+    }
+    if (!registration
+        || typeof registration.ok !== 'boolean'
+        || typeof registration.reason !== 'string'
+        || registrationReason(registration.reason) === undefined
+        || (registration.detail !== undefined && typeof registration.detail !== 'string')
+        || (registration.requiresForegroundExit !== undefined && registration.requiresForegroundExit !== true)) {
+        return fail(`${code}:invalid_reconciliation_result`, `one-time standalone migration failed (${code}:invalid_reconciliation_result)`, `${code}: invalid_reconciliation_result`, true);
+    }
+    const safeReason = registrationReason(registration.reason);
+    if (!safeReason) {
+        return fail(`${code}:invalid_reconciliation_result`, `one-time standalone migration failed (${code}:invalid_reconciliation_result)`, `${code}: invalid_reconciliation_result`, true);
+    }
+    const safeDetail = registration.detail === undefined ? undefined : errorDetail(registration.detail);
     if (!registration.ok) {
-        const detail = registration.detail ?? 'unknown';
-        return fail(`${code}:${detail}`, `one-time standalone migration failed (${code})`, `${code}: ${detail}`);
+        const ownershipAmbiguous = registration.requiresForegroundExit === true
+            || ['ambiguous', 'blocked', 'signal', 'termination_unconfirmed', 'timeout'].includes(safeReason);
+        const detail = safeDetail ? `:${safeDetail}` : '';
+        if (safeReason === 'timeout') {
+            return failTimeout('migration_register_timeout', `one-time standalone migration failed (${code}:timeout)`, errorDetail(`${code}: timeout${detail}`), true);
+        }
+        return fail(`${code}:${safeReason}`, `one-time standalone migration failed (${code}:${safeReason})`, errorDetail(`${code}: ${safeReason}${detail}`), ownershipAmbiguous);
+    }
+    const lockReleaseUnconfirmed = safeReason === 'bootstrapped_lock_release_unconfirmed';
+    if ((safeReason !== 'bootstrapped' && !lockReleaseUnconfirmed)
+        || (lockReleaseUnconfirmed && !safeDetail)
+        || registration.requiresForegroundExit === true) {
+        return fail(`${code}:invalid_success_reconciliation`, `one-time standalone migration failed (${code}:invalid_success_reconciliation)`, `${code}: invalid_success_reconciliation:${safeReason}`, true);
     }
-    recordBootstrapAttempt(env, { ok: true, reason: 'migrated', detail: destPath }, recordOptions);
-    writeState(env, { state: 'migrated', version, destPath }, options);
     return {
         outcome: 'migrated',
         reason: 'migrated',
         destPath,
         message: `[evolver-proxy] self-update: installed standalone binary ${version} at ${destPath} and registered `
             + 'durable service supervision via `evolver lifecycle bootstrap`; handing over to the service manager '
-            + 'and exiting so it can take the IPC port.',
+            + 'and exiting so it can take the IPC port.'
+            + (lockReleaseUnconfirmed
+                ? ` The service commit is durable, but lifecycle lock release remains unconfirmed (${safeDetail}).`
+                : ''),
     };
 }