@evomap/evolver-proxy 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/selfUpdate/executor.js

@@ -12,7 +12,7 @@
 // Concurrency: a process-level mutex guarantees that concurrent force_update messages execute the update EXACTLY
 // once. The second caller short-circuits with `already_in_progress` and performs no I/O.
 import { ops } from '@evomap/evolver-core';
-import { SELF_UPDATE_FAILURE_CODES, classifySelfUpdateError, codeForDecisionReject, } from './failureCodes.js';
+import { SELF_UPDATE_FAILURE_CODES, classifySelfUpdateError, codeForDecisionReject, selfUpdateFailure, } from './failureCodes.js';
 const { decideUpdate, verifySelectedManifestArtifact } = ops;
 // Process-level mutex. Module scope is correct: there is one daemon per process, and v1's _forceUpdateInFlight had
 // the same lifetime. Guards against two force_update envelopes (or a heartbeat-driven + mailbox-driven trigger)
@@ -32,22 +32,28 @@ function report(deps, result) {
     return result;
 }
 /**
- * Execute a force_update directive end to end: decide → (mutex) → download → VERIFY → atomic replace → restart.
+ * Execute a force_update directive end to end: fast exits → lease → resolve/decide → download → VERIFY → replace → restart.
  *
  * Order is load-bearing:
- *  1. policy off → do nothing (the default-off risk gate; a half-built channel must not auto-apply).
- *  2. decideUpdate (pure): reject bad manifests, NOOP when already satisfied (no download, no restart).
- *  3. mutex: exactly one execution; concurrent callers get `already_in_progress` and touch no disk.
- *  4. download the staged release.
- *  5. verifySelectedManifestArtifact (pure) — THE GATE. Fail → no write, no restart.
- *  6. atomicReplace, then restart(). Only reached after verification passed.
+ *  1. policy off → do nothing (explicit opt-out; auto is hard-gated upstream by supervisor + public key).
+ *  2. reject malformed/already-satisfied required versions without acquiring the lifecycle owner lease.
+ *  3. mutex + lifecycle owner lease: exactly one executor may resolve or mutate release state.
+ *  4. resolve and decideUpdate (pure): reject bad manifests or NOOP under the held lease.
+ *  5. download the staged release.
+ *  6. verifySelectedManifestArtifact (pure) — THE GATE. Fail → no write, no restart.
+ *  7. atomicReplace, then restart(). Only reached after verification passed.
  *
  * Never throws: every failure becomes a structured SelfUpdateResult so the daemon can report it and keep running
  * on the old (intact) version.
  */
 export async function executeForceUpdate(directive, deps) {
+    let selectedResult;
+    const finish = (result) => {
+        selectedResult = result;
+        return report(deps, result);
+    };
     if (deps.policy !== 'auto') {
-        return report(deps, {
+        return finish({
             outcome: 'disabled',
             reason: deps.policy === 'prompt' ? 'self_update_policy_prompt_requires_approval' : 'self_update_policy_off',
         });
@@ -56,63 +62,105 @@ export async function executeForceUpdate(directive, deps) {
         ? ops.normalizeRequiredVersion(directive.required_version)
         : undefined;
     if (directive.required_version !== undefined && !requiredFloor) {
-        return report(deps, {
+        return finish({
             outcome: 'rejected_decision',
             reason: 'required_version_invalid',
             failureCode: SELF_UPDATE_FAILURE_CODES.BAD_REQUIRED_VERSION,
         });
     }
     if (requiredFloor && ops.currentSatisfiesRequiredVersion(deps.currentVersion, requiredFloor)) {
-        return report(deps, { outcome: 'noop', reason: 'already_satisfied', targetVersion: requiredFloor });
+        return finish({ outcome: 'noop', reason: 'already_satisfied', targetVersion: requiredFloor });
     }
-    let manifest = directive.manifest;
-    if (deps.resolveManifest && shouldResolveManifest(directive, manifest, Boolean(deps.publicKey))) {
-        try {
-            manifest = await deps.resolveManifest(directive, deps.currentVersion);
-        }
-        catch (err) {
-            const targetVersion = ops.normalizeRequiredVersion(directive.required_version);
-            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
-            return report(deps, {
-                outcome: 'download_failed',
-                reason: `manifest_resolve_failed: ${classified.detail}`,
-                failureCode: classified.failureCode,
-                ...(targetVersion ? { targetVersion } : {}),
-            });
-        }
-    }
-    const effectiveDirective = { ...directive, manifest };
-    const decision = decideUpdate({
-        current: deps.currentVersion,
-        ...(requiredFloor ? { required: requiredFloor } : {}),
-        manifest,
-    });
-    if (decision.action === 'reject') {
-        return report(deps, {
-            outcome: 'rejected_decision',
-            reason: decision.reason,
-            failureCode: codeForDecisionReject(decision.reason),
-            ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}),
-        });
-    }
-    if (decision.action === 'noop') {
-        return report(deps, { outcome: 'noop', reason: decision.reason, ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}) });
-    }
-    // action === 'proceed'. Take the mutex; a concurrent force_update short-circuits here with NO I/O.
+    // The mutex and lifecycle lease precede manifest resolution, which is release I/O too.
+    // Policy, malformed required-version, and already-satisfied fast exits remain lock-free.
     if (inFlight) {
-        return report(deps, { outcome: 'already_in_progress', reason: 'another_update_in_flight' });
+        return finish({ outcome: 'already_in_progress', reason: 'another_update_in_flight' });
     }
     inFlight = true;
-    const targetVersion = decision.targetVersion ?? manifest?.version ?? '';
+    let targetVersion = requiredFloor ?? '';
+    let lifecycleLease;
     let transaction;
+    const assertLifecycleLease = async () => {
+        try {
+            await lifecycleLease?.assertOwned();
+        }
+        catch (error) {
+            const classified = classifySelfUpdateError(error, SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED);
+            throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED, `self_update_lifecycle_owner_lease_lost:${classified.detail}`, { cause: error });
+        }
+    };
     try {
+        if (deps.acquireLifecycleLease) {
+            try {
+                lifecycleLease = await deps.acquireLifecycleLease();
+                await assertLifecycleLease();
+            }
+            catch (err) {
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED);
+                return finish({
+                    outcome: classified.failureCode === SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED
+                        ? 'already_in_progress'
+                        : 'replace_failed',
+                    reason: classified.detail,
+                    failureCode: classified.failureCode,
+                    ...(targetVersion ? { targetVersion } : {}),
+                });
+            }
+        }
+        let manifest = directive.manifest;
+        if (deps.resolveManifest && shouldResolveManifest(directive, manifest, Boolean(deps.publicKey))) {
+            try {
+                await assertLifecycleLease();
+                manifest = await deps.resolveManifest(directive, deps.currentVersion);
+            }
+            catch (err) {
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
+                if (classified.failureCode === SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED) {
+                    return finish({
+                        outcome: 'replace_failed',
+                        reason: classified.detail,
+                        failureCode: classified.failureCode,
+                        ...(targetVersion ? { targetVersion } : {}),
+                    });
+                }
+                return finish({
+                    outcome: 'download_failed',
+                    reason: `manifest_resolve_failed: ${classified.detail}`,
+                    failureCode: classified.failureCode,
+                    ...(targetVersion ? { targetVersion } : {}),
+                });
+            }
+        }
+        const effectiveDirective = { ...directive, manifest };
+        const decision = decideUpdate({
+            current: deps.currentVersion,
+            ...(requiredFloor ? { required: requiredFloor } : {}),
+            manifest,
+        });
+        if (decision.action === 'reject') {
+            return finish({
+                outcome: 'rejected_decision',
+                reason: decision.reason,
+                failureCode: codeForDecisionReject(decision.reason),
+                ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}),
+            });
+        }
+        if (decision.action === 'noop') {
+            return finish({
+                outcome: 'noop',
+                reason: decision.reason,
+                ...(decision.targetVersion ? { targetVersion: decision.targetVersion } : {}),
+            });
+        }
+        targetVersion = decision.targetVersion ?? manifest?.version ?? '';
         if (deps.beginTransaction) {
             try {
+                await assertLifecycleLease();
                 transaction = await deps.beginTransaction(targetVersion);
             }
             catch (err) {
                 const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED);
-                return report(deps, {
+                return finish({
                     outcome: classified.failureCode === SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED ? 'already_in_progress' : 'replace_failed',
                     reason: classified.detail,
                     failureCode: classified.failureCode,
@@ -123,12 +171,21 @@ export async function executeForceUpdate(directive, deps) {
         // 4. Download the staged release.
         let dl;
         try {
+            await assertLifecycleLease();
             dl = await deps.download(targetVersion, effectiveDirective);
         }
         catch (err) {
-            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED).catch(() => { });
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
-            return report(deps, {
+            await transaction?.abort(classified.failureCode).catch(() => { });
+            if (classified.failureCode === SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED) {
+                return finish({
+                    outcome: 'replace_failed',
+                    reason: classified.detail,
+                    failureCode: classified.failureCode,
+                    targetVersion,
+                });
+            }
+            return finish({
                 outcome: 'download_failed',
                 reason: classified.detail,
                 failureCode: classified.failureCode,
@@ -137,12 +194,13 @@ export async function executeForceUpdate(directive, deps) {
         }
         if (transaction) {
             try {
+                await assertLifecycleLease();
                 dl = await transaction.adoptDownloaded(dl);
             }
             catch (err) {
                 await transaction.abort(SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED).catch(() => { });
                 const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED);
-                return report(deps, {
+                return finish({
                     outcome: 'replace_failed',
                     reason: classified.detail,
                     failureCode: classified.failureCode,
@@ -151,11 +209,24 @@ export async function executeForceUpdate(directive, deps) {
             }
         }
         // 5. THE GATE: verify the downloaded bytes against the (optionally signed) manifest BEFORE any write.
+        try {
+            await assertLifecycleLease();
+        }
+        catch (err) {
+            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED).catch(() => { });
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.RECOVERY_REQUIRED);
+            return finish({
+                outcome: 'replace_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
         const verification = verifySelectedManifestArtifact(manifest, dl.artifacts, ...(deps.publicKey ? [deps.publicKey] : []));
         if (!verification.ok) {
             await transaction?.abort(SELF_UPDATE_FAILURE_CODES.REJECTED_VERIFICATION).catch(() => { });
             // Verification failed → write NOTHING, restart NOTHING. Old version stays intact and runnable.
-            return report(deps, {
+            return finish({
                 outcome: 'rejected_verification',
                 reason: verification.reason,
                 failureCode: SELF_UPDATE_FAILURE_CODES.REJECTED_VERIFICATION,
@@ -163,12 +234,13 @@ export async function executeForceUpdate(directive, deps) {
             });
         }
         try {
+            await assertLifecycleLease();
             await transaction?.markVerified(dl.artifacts);
         }
         catch (err) {
             await transaction?.abort(SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED).catch(() => { });
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED);
-            return report(deps, {
+            return finish({
                 outcome: 'replace_failed',
                 reason: classified.detail,
                 failureCode: classified.failureCode,
@@ -177,6 +249,7 @@ export async function executeForceUpdate(directive, deps) {
         }
         // 6. Verified. Atomic replace, then signal restart. A replace failure leaves the old version intact.
         try {
+            await assertLifecycleLease();
             if (transaction)
                 await transaction.install();
             else
@@ -184,7 +257,7 @@ export async function executeForceUpdate(directive, deps) {
         }
         catch (err) {
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.COPY_FAILED);
-            return report(deps, {
+            return finish({
                 outcome: 'replace_failed',
                 reason: classified.detail,
                 failureCode: classified.failureCode,
@@ -198,9 +271,11 @@ export async function executeForceUpdate(directive, deps) {
             appliedVia: dl.appliedVia ?? 'binary',
             ...(transaction ? { confirmationPending: true } : {}),
         };
-        report(deps, result);
+        finish(result);
         try {
+            await assertLifecycleLease();
             await transaction?.markRestartRequested();
+            await assertLifecycleLease();
             await deps.restart(); // v1 convention: exit(78) → supervisor relaunches the new version.
         }
         catch (err) {
@@ -210,14 +285,14 @@ export async function executeForceUpdate(directive, deps) {
             }
             catch (rollbackError) {
                 const rollback = classifySelfUpdateError(rollbackError, SELF_UPDATE_FAILURE_CODES.ROLLBACK_FAILED);
-                return report(deps, {
+                return finish({
                     outcome: 'rollback_failed',
                     reason: rollback.detail,
                     failureCode: rollback.failureCode,
                     targetVersion,
                 });
             }
-            return report(deps, {
+            return finish({
                 outcome: 'restart_failed',
                 reason: classified.detail,
                 failureCode: classified.failureCode,
@@ -228,11 +303,36 @@ export async function executeForceUpdate(directive, deps) {
     }
     finally {
         await transaction?.release().catch(() => { });
-        // Released so a later legitimate update (after a failed attempt) can proceed. On the success path the process
-        // is exiting anyway; releasing is harmless and keeps the mutex honest if restart() is a test fake that returns.
+        if (lifecycleLease) {
+            try {
+                await lifecycleLease.release();
+            }
+            catch (error) {
+                if (selectedResult) {
+                    selectedResult.cleanupWarning = boundedCleanupWarning(error);
+                    if (selectedResult.outcome === 'applied') {
+                        selectedResult.reason = 'verified_and_replaced_lifecycle_lease_release_unconfirmed';
+                    }
+                    try {
+                        deps.onCleanupWarning?.(selectedResult.cleanupWarning, selectedResult);
+                    }
+                    catch {
+                        // Cleanup reporting must not replace the primary update outcome.
+                    }
+                }
+            }
+        }
         inFlight = false;
     }
 }
+function boundedCleanupWarning(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const normalized = raw
+        .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return (normalized || 'self_update_lifecycle_owner_lease_release_failed').slice(0, 512);
+}
 function shouldResolveManifest(directive, manifest, signatureRequired) {
     if (manifest === undefined)
         return true;

package/dist/selfUpdate/failureCodes.d.ts

@@ -23,6 +23,10 @@ export declare const SELF_UPDATE_FAILURE_CODES: Readonly<{
     readonly RESTART_FAILED: "restart_failed";
     readonly READ_BACK_FAILED: "read_back_failed";
     readonly ROLLBACK_FAILED: "rollback_failed";
+    readonly MIGRATION_DOWNLOAD_FAILED: "migration_download_failed";
+    readonly MIGRATION_VERIFY_FAILED: "migration_verify_failed";
+    readonly MIGRATION_INSTALL_FAILED: "migration_install_failed";
+    readonly MIGRATION_REGISTER_FAILED: "migration_register_failed";
 }>;
 export type SelfUpdateFailureCode = typeof SELF_UPDATE_FAILURE_CODES[keyof typeof SELF_UPDATE_FAILURE_CODES];
 export interface ClassifiedSelfUpdateError {

package/dist/selfUpdate/failureCodes.js

@@ -28,6 +28,13 @@ export const SELF_UPDATE_FAILURE_CODES = Object.freeze({
     RESTART_FAILED: 'restart_failed',
     READ_BACK_FAILED: 'read_back_failed',
     ROLLBACK_FAILED: 'rollback_failed',
+    // One-time npm/JS → standalone binary migration (migration.ts). Append-only:
+    // these surface in attempt-marker detail strings and operator messages so
+    // telemetry can attribute first-run migration failures by phase.
+    MIGRATION_DOWNLOAD_FAILED: 'migration_download_failed',
+    MIGRATION_VERIFY_FAILED: 'migration_verify_failed',
+    MIGRATION_INSTALL_FAILED: 'migration_install_failed',
+    MIGRATION_REGISTER_FAILED: 'migration_register_failed',
 });
 export class SelfUpdateFailureError extends Error {
     failureCode;

package/dist/selfUpdate/index.d.ts

@@ -5,4 +5,5 @@ export * from './releaseBinary.js';
 export * from './transaction.js';
 export * from './failureCodes.js';
 export * from './unixController.js';
-export * from './windowsController.js';
+export * from './windowsController.js';
+export * from './bootstrapReadiness.js';

package/dist/selfUpdate/index.js

@@ -5,4 +5,5 @@ export * from './releaseBinary.js';
 export * from './transaction.js';
 export * from './failureCodes.js';
 export * from './unixController.js';
-export * from './windowsController.js';
+export * from './windowsController.js';
+export * from './bootstrapReadiness.js';

package/dist/selfUpdate/migration.d.ts

@@ -0,0 +1,158 @@
+import { type spawn } from 'node:child_process';
+import { ops } from '@evomap/evolver-core';
+import type { DownloadResult, ForceUpdateDirective } from './executor.js';
+import { type ReleaseBinaryOptions } from './releaseBinary.js';
+import { type StagedBinaryProbe } from './transaction.js';
+type DownloadedArtifact = ops.DownloadedArtifact;
+type VerifyResult = ops.VerifyResult;
+type FetchFn = (input: string | URL, init?: RequestInit) => Promise<Response>;
+/** Minimal stat shape migration needs (symlink guard + regular-file check). */
+interface MigrationFileStat {
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+    isDirectory?(): boolean;
+    size?: number;
+}
+interface MigrationTargetIdentity {
+    path: string;
+    device: string;
+    inode: string;
+    size: number;
+    linkCount: 1;
+    mtimeNs: string;
+    ctimeNs: string;
+    sha256: string;
+}
+/**
+ * Registration is delegated to the same transaction runner used by ordinary first-run
+ * bootstrap. The absolute deadlines are part of this request so an adapter cannot silently
+ * restart either observation budget during registration and reconciliation.
+ */
+export interface MigrationRegistrationRequest {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    version: string;
+    startedAtMs: number;
+    transactionDeadlineMs: number;
+    parentDeadlineMs: number;
+    transactionBudgetMs: number;
+    timeoutMs: number;
+    /** Exact signed target identity the runner must revalidate before spawning the child. */
+    targetIdentity: Readonly<MigrationTargetIdentity>;
+    /** Sealed verifier over the original identity/dependencies; call immediately before spawn. */
+    revalidateTarget: () => Promise<void>;
+    /** Sealed durable-intent verifier; call immediately before target revalidation and spawn. */
+    assertRegistrationIntentCurrent: () => Promise<void>;
+    execPath: string;
+    exists?: (path: string) => boolean;
+    readFile?: (path: string) => string;
+    writeFile?: (path: string, content: string) => void;
+    spawnFn?: typeof spawn;
+}
+interface MigrationRegistrationOutcome {
+    ok: boolean;
+    reason: string;
+    detail?: string;
+    /** The runner could not prove child/process-tree ownership or a clean rollback. */
+    requiresForegroundExit?: true;
+}
+export type MigrationRegistrationRunner = (request: MigrationRegistrationRequest) => Promise<MigrationRegistrationOutcome>;
+export interface MigrationOptions {
+    /** Arch override for release asset resolution (defaults to process.arch). */
+    arch?: NodeJS.Architecture;
+    exists?: (path: string) => boolean;
+    /** Sync text read (bootstrap.ts mirror); used for container detection. */
+    readFile?: (path: string) => string;
+    /** Sync text write seam for attempt markers and canonical migration state. */
+    writeFile?: (path: string, content: string) => void;
+    /** Async binary read of the staged artifact (install copy). */
+    readBinary?: (path: string) => Promise<Buffer>;
+    /** Async binary write with mode (install tmp copy). */
+    writeBinary?: (path: string, content: Buffer, mode: number) => Promise<void>;
+    /** Recursive mkdir with mode (install dest dir). */
+    mkdir?: (path: string, mode: number) => Promise<void>;
+    /** Force/recursive removal (staged tmp dir, leftover tmp copies). */
+    rm?: (path: string) => Promise<void>;
+    /** Owner-verified installed target removal after a proven clean registration rollback. */
+    unlink?: (path: string) => Promise<void>;
+    /** Remove a transaction-created empty bin directory after clean rollback. */
+    rmdir?: (path: string) => Promise<void>;
+    chmod?: (path: string, mode: number) => Promise<void>;
+    /** Flush staged executable data/metadata before namespace publication. */
+    syncFile?: (path: string) => Promise<void>;
+    /** Flush target namespace mutations; Windows may use a documented no-op fallback. */
+    syncDirectory?: (path: string) => Promise<void>;
+    /** lstat-shaped stat for the staged-artifact symlink guard. */
+    stat?: (path: string) => Promise<MigrationFileStat>;
+    /** Atomic no-replace publication seam. */
+    link?: (from: string, to: string) => Promise<void>;
+    /** Atomic same-directory move used by exact rollback quarantine. */
+    rename?: (from: string, to: string) => Promise<void>;
+    fetchFn?: FetchFn;
+    /** Probe used by the default preflight (real execution of `--version` / `proxy --help`). */
+    probe?: StagedBinaryProbe;
+    spawnFn?: typeof spawn;
+    now?: number;
+    /** Clock used to bind the registration runner to absolute deadlines. */
+    clock?: () => number;
+    execPath?: string;
+    /** Effective uid (tests / platforms without process.getuid). */
+    uid?: number | undefined;
+    /** Parent register timeout; must exceed transactionBudgetMs. */
+    timeoutMs?: number;
+    /** Child transaction budget; defaults to MIGRATION_REGISTER_TRANSACTION_BUDGET_MS. */
+    transactionBudgetMs?: number;
+    /** Durable reconciliation + process-tree-contained registration runner. */
+    registrationRunner?: MigrationRegistrationRunner;
+    /** Test seam for platform ownership/ACL validation; production uses strict host checks. */
+    assertDirectoryTrust?: (directory: string) => void | Promise<void>;
+    /** Test seam for executable ownership/ACL validation; production uses strict host checks. */
+    assertFileTrust?: (path: string) => void | Promise<void>;
+    /** Sync test seam for canonical state-directory ownership/ACL validation. */
+    assertStateDirectoryTrust?: (directory: string) => void;
+    /** Sync test seam for canonical state-file ownership/ACL validation. */
+    assertStateFileTrust?: (path: string) => void;
+    /** High-level seam: download leg (defaults to downloadGithubReleaseArtifact). */
+    downloadFn?: (targetVersion: string, directive: ForceUpdateDirective, opts: ReleaseBinaryOptions) => Promise<DownloadResult>;
+    /** High-level seam: manifest verification (defaults to ops.verifySelectedManifestArtifact). */
+    verifyFn?: (manifest: unknown, downloaded: readonly DownloadedArtifact[], publicKey: string) => VerifyResult;
+    /** High-level seam: preflight (defaults to preflightManagedStagedBinary with options.probe). */
+    preflightFn?: (targetPath: string, expectedVersion: string) => Promise<void>;
+}
+export interface MigrationResult {
+    outcome: 'migrated' | 'skipped' | 'failed';
+    /**
+     * Structured reason: 'migrated' / 'disabled' / 'root_user' / 'ci_environment' /
+     * 'container_environment' / 'cooldown' / 'unsupported_platform' /
+     * 'invalid_version_override' / 'version_unresolvable' /
+     * 'migration_download_failed:<detail>' / 'migration_verify_failed:<reason>' /
+     * 'migration_install_failed:<detail>' / 'migration_register_failed:<detail>' /
+     * 'migration_register_timeout'.
+     */
+    reason: string;
+    destPath?: string;
+    /** Registration ownership is ambiguous, so the foreground proxy must not continue. */
+    requiresForegroundExit?: true;
+    /** Operator-facing message (short phrase for skipped/failed; full line for migrated). */
+    message: string;
+}
+/**
+ * Migration install home — mirrors the CLI-side lifecyclePaths home resolution
+ * (kept dependency-free across packages): EVOLVER_HOME ?? EVOMAP_HOME ?? ~/.evomap.
+ */
+export declare function resolveMigrationHome(env: NodeJS.ProcessEnv): string;
+/** Migration install path for this platform: <home>/bin/<releaseAssetName>. Throws on unsupported platforms. */
+export declare function resolveMigrationDestPath(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, arch?: NodeJS.Architecture): string;
+/**
+ * Resolve the migration target version: EVOLVER_BOOTSTRAP_MIGRATION_VERSION override
+ * (normalized through the self-update version contract) wins, else the current package
+ * version. Returns undefined when nothing normalizes to a concrete semver.
+ */
+export declare function resolveMigrationVersion(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * One-time migration of the npm/JS install shape to the standalone release binary.
+ * Never throws: every failure/skip becomes a structured MigrationResult. Only a proven clean
+ * failure may continue degraded; ambiguous registration ownership requires foreground exit.
+ */
+export declare function migrateToStandaloneBinary(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, options?: MigrationOptions): Promise<MigrationResult>;
+export {};