@evomap/evolver-proxy 2.0.0-beta.9 → 2.0.1

package/dist/selfUpdate/bootstrap.d.ts

@@ -0,0 +1,69 @@
+import { spawn } from 'node:child_process';
+import { type MigrationOptions } from './migration.js';
+export declare const BOOTSTRAP_SUCCESS_FILE = "bootstrap.json";
+export type BootstrapSkipReason = 'already_supervised' | 'already_bootstrapped' | 'unsupported_install_shape' | 'policy_not_auto' | 'bootstrap_disabled' | 'ci_environment' | 'container_environment' | 'recent_failure';
+export interface BootstrapDecision {
+    proceed: boolean;
+    reason?: BootstrapSkipReason;
+}
+export interface BootstrapOutcome {
+    ok: boolean;
+    /**
+     * 'bootstrapped' / 'migrated' on success; failure/skip reason otherwise. Migration
+     * failures record 'migration_failed' / 'migration_timeout' (both cooldown-worthy).
+     */
+    reason: string;
+    detail?: string;
+}
+export interface BootstrapRunOptions {
+    env: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    execPath?: string;
+    argv1?: string;
+    timeoutMs?: number;
+    now?: number;
+    exists?: (path: string) => boolean;
+    readFile?: (path: string) => string;
+    writeFile?: (path: string, content: string) => void;
+    spawnFn?: typeof spawn;
+    /**
+     * Extra seams forwarded to the one-time npm/JS → standalone migration (migration.ts).
+     * Bootstrap-level seams (exists/readFile/writeFile/spawnFn/now/execPath) win when both
+     * are supplied, so the decision and the migration observe the same injected world.
+     */
+    migration?: MigrationOptions;
+}
+/** Lifecycle state dir mirror of evolver-cli lifecyclePaths (kept dependency-free across packages). */
+export declare function resolveBootstrapStateDir(env: NodeJS.ProcessEnv): string;
+export declare function looksLikeContainer(exists: (path: string) => boolean, readFile: (path: string) => string): boolean;
+/** True when a recent bootstrap/migration attempt failed within the cooldown window. */
+export declare function recentBootstrapFailure(env: NodeJS.ProcessEnv, readFile: (path: string) => string, now: number): boolean;
+/**
+ * Decide whether an unsupervised (degraded) startup should attempt first-run bootstrap.
+ * Pure — filesystem access is injectable for tests.
+ */
+export declare function shouldBootstrap(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, options?: Pick<BootstrapRunOptions, 'exists' | 'readFile' | 'now' | 'execPath'>): BootstrapDecision;
+/**
+ * Resolve the `lifecycle bootstrap` invocation for the current install shape: standalone binary,
+ * CLI entry through node, or the npm-installed @evomap/evolver-cli sibling. Returns undefined when
+ * no CLI can be located (degrade to the existing warning instead of failing startup).
+ */
+export declare function resolveBootstrapCliInvocation(options?: Pick<BootstrapRunOptions, 'execPath' | 'argv1' | 'exists'>): {
+    command: string;
+    args: string[];
+} | undefined;
+/** Best-effort attempt marker; never throws — bootstrap bookkeeping must not break startup. */
+export declare function recordBootstrapAttempt(env: NodeJS.ProcessEnv, outcome: BootstrapOutcome, options?: Pick<BootstrapRunOptions, 'writeFile' | 'now'>): void;
+/** Spawn `evolver lifecycle bootstrap` and await its result within a bounded timeout. */
+export declare function runBootstrap(options: BootstrapRunOptions): Promise<BootstrapOutcome>;
+export interface DegradedStartupBootstrapResult {
+    /** True when bootstrap succeeded and startup should exit so the new service takes over. */
+    handedOver: boolean;
+    /** Operator-facing single-line message (stdout when handed over, stderr otherwise). */
+    message: string;
+}
+/**
+ * Orchestrate bootstrap for a degraded (default-auto, unsupervised) startup: decide, attempt,
+ * record, and produce the operator message. Never throws.
+ */
+export declare function bootstrapDegradedSelfUpdateStartup(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, options?: Omit<BootstrapRunOptions, 'env' | 'platform'>): Promise<DegradedStartupBootstrapResult>;

package/dist/selfUpdate/bootstrap.js

@@ -0,0 +1,282 @@
+// First-run supervision bootstrap for the DEFAULT self-update policy.
+//
+// Default auto self-update degrades to 'off' without a durable supervisor attestation (policy.ts).
+// To make `npm install` a complete zero-config path, an unsupervised foreground startup may ONCE
+// register its own user-level durable launcher (`evolver lifecycle bootstrap`) and hand over to it:
+// the generated launcher carries the EVOLVER_SELF_UPDATE_SUPERVISOR attestation, so the next
+// supervised startup runs auto self-update with the unchanged signature/health-check/rollback gates.
+//
+// Bootstrap is a convenience, never an escalation: it is skipped for attested runs, explicit
+// non-auto policies, the EVOLVER_SELF_BOOTSTRAP kill switch, CI, containers, and within a
+// cooldown window after a failed attempt. The npm/JS install shape has no bindable
+// self-update target, so instead of launcher bootstrap it attempts a one-time migration to
+// the standalone release binary (migration.ts). Any failure degrades back to the existing
+// 'off + warning' startup.
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isSelfUpdateExplicit, resolveSelfUpdatePolicy, selfUpdateSupervisorAttested, } from './policy.js';
+import { expandHomePath } from '../bin/envFile.js';
+import { resolveSelfUpdateTarget } from './releaseBinary.js';
+import { migrateToStandaloneBinary } from './migration.js';
+const requireFromHere = createRequire(import.meta.url);
+export const BOOTSTRAP_SUCCESS_FILE = 'bootstrap.json';
+const BOOTSTRAP_ATTEMPT_FILE = 'bootstrap-attempt.json';
+const BOOTSTRAP_FAILURE_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+// 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
+// half-installed state: the service registered but bootstrap judged failed.
+const BOOTSTRAP_TIMEOUT_MS = 90_000;
+const BOOTSTRAP_ENV_FILE_HANDOFF = 'EVOLVER_INTERNAL_BOOTSTRAP_ENV_FILE';
+/** Lifecycle state dir mirror of evolver-cli lifecyclePaths (kept dependency-free across packages). */
+export function resolveBootstrapStateDir(env) {
+    const explicit = env['EVOLVER_LIFECYCLE_STATE_DIR']?.trim();
+    const home = env['EVOLVER_HOME'] ?? env['EVOMAP_HOME'] ?? join(homedir(), '.evomap');
+    return resolvePath(explicit || join(home, 'lifecycle'));
+}
+function bootstrapChildEnv(env) {
+    const childEnv = { ...env };
+    const envFile = env['EVOLVER_ENV_FILE']?.trim();
+    delete childEnv['EVOLVER_ENV_FILE'];
+    delete childEnv[BOOTSTRAP_ENV_FILE_HANDOFF];
+    if (envFile)
+        childEnv[BOOTSTRAP_ENV_FILE_HANDOFF] = resolvePath(expandHomePath(envFile));
+    // Resolve while the foreground proxy still owns cwd, then carry that identity through the
+    // bootstrap child and generated service launcher. Service managers do not share one cwd.
+    childEnv['EVOLVER_LIFECYCLE_STATE_DIR'] = resolveBootstrapStateDir(env);
+    return childEnv;
+}
+const defaultReadTextFile = (path) => readFileSync(path, 'utf8');
+export function looksLikeContainer(exists, readFile) {
+    if (exists('/.dockerenv'))
+        return true;
+    try {
+        return /docker|containerd|kubepods|podman|lxc/.test(readFile('/proc/1/cgroup'));
+    }
+    catch {
+        return false;
+    }
+}
+function readBootstrapAttempt(env, readFile) {
+    try {
+        const parsed = JSON.parse(readFile(join(resolveBootstrapStateDir(env), BOOTSTRAP_ATTEMPT_FILE)));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Cooldown-worthy attempt outcomes. Migration adds its own failure/timeout outcomes so a
+// broken release (download/verify/install/register) does not get retried on every startup.
+const BOOTSTRAP_FAILURE_OUTCOMES = new Set([
+    'failed', 'timeout', 'cli_not_found', 'migration_failed', 'migration_timeout',
+]);
+/** True when a recent bootstrap/migration attempt failed within the cooldown window. */
+export function recentBootstrapFailure(env, readFile, now) {
+    const attempt = readBootstrapAttempt(env, readFile);
+    if (!attempt)
+        return false;
+    if (typeof attempt['outcome'] !== 'string' || !BOOTSTRAP_FAILURE_OUTCOMES.has(attempt['outcome']))
+        return false;
+    if (typeof attempt['attemptedAt'] !== 'string')
+        return false;
+    const attemptedAt = Date.parse(attempt['attemptedAt']);
+    if (Number.isNaN(attemptedAt))
+        return false;
+    return now - attemptedAt < BOOTSTRAP_FAILURE_COOLDOWN_MS;
+}
+/**
+ * Decide whether an unsupervised (degraded) startup should attempt first-run bootstrap.
+ * Pure — filesystem access is injectable for tests.
+ */
+export function shouldBootstrap(env, platform = process.platform, options = {}) {
+    if (selfUpdateSupervisorAttested(env))
+        return { proceed: false, reason: 'already_supervised' };
+    const bootstrapSwitch = env['EVOLVER_SELF_BOOTSTRAP']?.trim();
+    if (bootstrapSwitch === '0' || bootstrapSwitch === 'off')
+        return { proceed: false, reason: 'bootstrap_disabled' };
+    if (isSelfUpdateExplicit(env) && resolveSelfUpdatePolicy(env) !== 'auto') {
+        return { proceed: false, reason: 'policy_not_auto' };
+    }
+    const exists = options.exists ?? existsSync;
+    if (exists(join(resolveBootstrapStateDir(env), BOOTSTRAP_SUCCESS_FILE))) {
+        return { proceed: false, reason: 'already_bootstrapped' };
+    }
+    // The npm/JS install shape has no replaceable standalone binary target, so the launcher
+    // bootstrap would register a supervised instance that crashes at self-update target
+    // resolution on every startup (crash-loop under the service manager). Skip it; an explicit
+    // EVOLVER_SELF_UPDATE_TARGET_PATH keeps the target bindable and bypasses this guard.
+    try {
+        resolveSelfUpdateTarget({ env, processExecPath: options.execPath });
+    }
+    catch {
+        return { proceed: false, reason: 'unsupported_install_shape' };
+    }
+    const ci = env['CI']?.trim();
+    if (ci && ci.toLowerCase() !== 'false' && ci !== '0')
+        return { proceed: false, reason: 'ci_environment' };
+    if (platform === 'linux' && looksLikeContainer(exists, options.readFile ?? defaultReadTextFile)) {
+        return { proceed: false, reason: 'container_environment' };
+    }
+    if (recentBootstrapFailure(env, options.readFile ?? defaultReadTextFile, options.now ?? Date.now())) {
+        return { proceed: false, reason: 'recent_failure' };
+    }
+    return { proceed: true };
+}
+/**
+ * Resolve the `lifecycle bootstrap` invocation for the current install shape: standalone binary,
+ * CLI entry through node, or the npm-installed @evomap/evolver-cli sibling. Returns undefined when
+ * no CLI can be located (degrade to the existing warning instead of failing startup).
+ */
+export function resolveBootstrapCliInvocation(options = {}) {
+    const execPath = options.execPath ?? process.execPath;
+    const argv1 = options.argv1 ?? process.argv[1];
+    const exists = options.exists ?? existsSync;
+    const executableName = basename(execPath).toLowerCase();
+    if (/^evolver(?:\.exe|-(?:darwin-(?:arm64|x64)|linux-(?:arm64|x64)|windows-x64\.exe))?$/.test(executableName)) {
+        return { command: execPath, args: ['lifecycle', 'bootstrap'] };
+    }
+    if (argv1 && basename(argv1).toLowerCase() === 'cli.js') {
+        return { command: execPath, args: [argv1, 'lifecycle', 'bootstrap'] };
+    }
+    try {
+        const entry = requireFromHere.resolve('@evomap/evolver-cli');
+        const cliPath = join(dirname(entry), 'cli.js');
+        if (exists(cliPath))
+            return { command: execPath, args: [cliPath, 'lifecycle', 'bootstrap'] };
+    }
+    catch {
+        // Not resolvable from the installed proxy package — fall through to the monorepo layout.
+    }
+    const local = fileURLToPath(new URL('../../../evolver-cli/dist/cli.js', import.meta.url));
+    if (exists(local))
+        return { command: execPath, args: [local, 'lifecycle', 'bootstrap'] };
+    return undefined;
+}
+/** Best-effort attempt marker; never throws — bootstrap bookkeeping must not break startup. */
+export function recordBootstrapAttempt(env, outcome, options = {}) {
+    const path = join(resolveBootstrapStateDir(env), BOOTSTRAP_ATTEMPT_FILE);
+    const record = {
+        attemptedAt: new Date(options.now ?? Date.now()).toISOString(),
+        outcome: outcome.reason,
+        ...(outcome.detail ? { detail: outcome.detail } : {}),
+    };
+    try {
+        const writeFile = options.writeFile ?? ((target, content) => {
+            mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+            writeFileSync(target, content, { encoding: 'utf8', mode: 0o600 });
+        });
+        writeFile(path, `${JSON.stringify(record)}\n`);
+    }
+    catch {
+        // Marker is advisory; startup continues regardless.
+    }
+}
+/** Spawn `evolver lifecycle bootstrap` and await its result within a bounded timeout. */
+export async function runBootstrap(options) {
+    const invocation = resolveBootstrapCliInvocation(options);
+    if (!invocation)
+        return { ok: false, reason: 'cli_not_found' };
+    const spawnFn = options.spawnFn ?? spawn;
+    const timeoutMs = options.timeoutMs ?? BOOTSTRAP_TIMEOUT_MS;
+    return new Promise((resolvePromise) => {
+        let child;
+        try {
+            child = spawnFn(invocation.command, invocation.args, {
+                stdio: 'ignore',
+                windowsHide: true,
+                env: bootstrapChildEnv(options.env),
+            });
+        }
+        catch (error) {
+            resolvePromise({ ok: false, reason: 'failed', detail: error instanceof Error ? error.message : String(error) });
+            return;
+        }
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolvePromise(outcome);
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            settle({ ok: false, reason: 'timeout' });
+        }, timeoutMs);
+        child.once('error', (error) => {
+            settle({ ok: false, reason: 'failed', detail: error.message });
+        });
+        child.once('exit', (code) => {
+            if (code === 0)
+                settle({ ok: true, reason: 'bootstrapped' });
+            else
+                settle({ ok: false, reason: 'failed', detail: `exit ${code ?? 'null'}` });
+        });
+    });
+}
+/**
+ * Orchestrate bootstrap for a degraded (default-auto, unsupervised) startup: decide, attempt,
+ * record, and produce the operator message. Never throws.
+ */
+export async function bootstrapDegradedSelfUpdateStartup(env, platform = process.platform, options = {}) {
+    const bootstrapEnv = {
+        ...env,
+        EVOLVER_LIFECYCLE_STATE_DIR: resolveBootstrapStateDir(env),
+    };
+    const decision = shouldBootstrap(bootstrapEnv, platform, options);
+    if (!decision.proceed) {
+        const reason = decision.reason ?? 'skipped';
+        recordBootstrapAttempt(bootstrapEnv, { ok: false, reason }, options);
+        if (reason === 'unsupported_install_shape') {
+            // Do not suggest `evolver lifecycle bootstrap` here: under the npm/JS install shape it
+            // would register a supervised service that crashes at self-update target resolution on
+            // every startup (crash-loop). Only a standalone release binary can host self-update —
+            // so attempt the one-time migration to it; any skip/failure keeps the degraded startup.
+            const migration = await migrateToStandaloneBinary(env, platform, {
+                ...options.migration,
+                ...(options.execPath !== undefined ? { execPath: options.execPath } : {}),
+                ...(options.exists !== undefined ? { exists: options.exists } : {}),
+                ...(options.readFile !== undefined ? { readFile: options.readFile } : {}),
+                ...(options.writeFile !== undefined ? { writeFile: options.writeFile } : {}),
+                ...(options.spawnFn !== undefined ? { spawnFn: options.spawnFn } : {}),
+                ...(options.now !== undefined ? { now: options.now } : {}),
+            });
+            if (migration.outcome === 'migrated') {
+                return { handedOver: true, message: migration.message };
+            }
+            return {
+                handedOver: false,
+                message: '[evolver-proxy] self-update: running from the npm/JS install shape, which has no standalone '
+                    + 'binary target for self-update; bootstrap skipped, continuing with self-update off. '
+                    + 'Install the standalone binary from GitHub Releases and start it to enable self-update. '
+                    + `(${migration.message})`,
+            };
+        }
+        return {
+            handedOver: false,
+            message: '[evolver-proxy] self-update: default auto requires a durable supervisor attestation; '
+                + `running with self-update off (bootstrap skipped: ${reason}). `
+                + 'Run `evolver lifecycle bootstrap` or `evolver lifecycle install-service` to enable.',
+        };
+    }
+    const outcome = await runBootstrap({ env: bootstrapEnv, platform, ...options });
+    recordBootstrapAttempt(bootstrapEnv, outcome, options);
+    if (outcome.ok) {
+        return {
+            handedOver: true,
+            message: '[evolver-proxy] self-update: registered durable service supervision via `evolver lifecycle bootstrap`; '
+                + 'handing over to the service manager and exiting so it can take the IPC port.',
+        };
+    }
+    return {
+        handedOver: false,
+        message: `[evolver-proxy] self-update: first-run bootstrap failed (${outcome.reason}); `
+            + 'running with self-update off. Run `evolver lifecycle install-service` manually to enable.',
+    };
+}

package/dist/selfUpdate/builtinKey.d.ts

@@ -0,0 +1,4 @@
+/** Ed25519 SPKI public key (base64 DER) matching the v2-beta release environment signing key. */
+export declare const BUILTIN_SELF_UPDATE_PUBLIC_KEY = "MCowBQYDK2VwAyEAAgoV6aWwJd5zlxOcPqWuxkDB+isQnKydFStV8X3DxMk=";
+/** Resolve the self-update verification public key: env override wins, else the built-in key. */
+export declare function resolveSelfUpdatePublicKey(env?: NodeJS.ProcessEnv): string;

package/dist/selfUpdate/builtinKey.js

@@ -0,0 +1,16 @@
+// Built-in Ed25519 verification public key for the official v2-beta self-update channel.
+//
+// A public key is not secret: embedding it lets nodes installed through a trusted
+// distribution channel (npm tarball or prebuilt release binary) verify signed update
+// manifests with zero per-node configuration. Trust bootstraps from the install
+// channel itself (npm registry integrity / release artifact provenance), and every
+// later self-update stays signature-gated.
+//
+// EVOLVER_SELF_UPDATE_PUBLIC_KEY overrides this when set (rotation / private fleets).
+/** Ed25519 SPKI public key (base64 DER) matching the v2-beta release environment signing key. */
+export const BUILTIN_SELF_UPDATE_PUBLIC_KEY = 'MCowBQYDK2VwAyEAAgoV6aWwJd5zlxOcPqWuxkDB+isQnKydFStV8X3DxMk=';
+/** Resolve the self-update verification public key: env override wins, else the built-in key. */
+export function resolveSelfUpdatePublicKey(env = process.env) {
+    const configured = env['EVOLVER_SELF_UPDATE_PUBLIC_KEY']?.trim();
+    return configured || BUILTIN_SELF_UPDATE_PUBLIC_KEY;
+}

package/dist/selfUpdate/executor.d.ts

@@ -81,7 +81,7 @@ export declare function _resetSelfUpdateMutex(): void;
  * Execute a force_update directive end to end: decide → (mutex) → download → VERIFY → atomic replace → restart.
  *
  * Order is load-bearing:
- *  1. policy off → do nothing (the default-off risk gate; a half-built channel must not auto-apply).
+ *  1. policy off → do nothing (explicit opt-out; auto is hard-gated upstream by supervisor + public key).
  *  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.

package/dist/selfUpdate/executor.js

@@ -35,7 +35,7 @@ function report(deps, result) {
  * Execute a force_update directive end to end: decide → (mutex) → download → VERIFY → atomic replace → restart.
  *
  * Order is load-bearing:
- *  1. policy off → do nothing (the default-off risk gate; a half-built channel must not auto-apply).
+ *  1. policy off → do nothing (explicit opt-out; auto is hard-gated upstream by supervisor + public key).
  *  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.

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/migration.d.ts

@@ -0,0 +1,93 @@
+import { 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>;
+/** Advisory migration state marker written next to the bootstrap attempt marker. */
+export declare 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 declare const MIGRATION_REGISTER_TIMEOUT_MS = 90000;
+/** Minimal stat shape migration needs (symlink guard + regular-file check). */
+export interface MigrationFileStat {
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+}
+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 for advisory state markers (attempt marker + migration.json). */
+    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>;
+    rename?: (from: string, to: string) => Promise<void>;
+    chmod?: (path: string, mode: number) => Promise<void>;
+    /** lstat-shaped stat for the staged-artifact symlink guard. */
+    stat?: (path: string) => Promise<MigrationFileStat>;
+    fetchFn?: FetchFn;
+    /** Probe used by the default preflight (real execution of `--version` / `proxy --help`). */
+    probe?: StagedBinaryProbe;
+    spawnFn?: typeof spawn;
+    now?: number;
+    execPath?: string;
+    /** Effective uid (tests / platforms without process.getuid). */
+    uid?: number | undefined;
+    /** Register-step timeout override (defaults to MIGRATION_REGISTER_TIMEOUT_MS). */
+    timeoutMs?: number;
+    /** 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;
+    /** 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 so degraded
+ * startup can keep running with self-update off.
+ */
+export declare function migrateToStandaloneBinary(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, options?: MigrationOptions): Promise<MigrationResult>;
+export {};