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

package/dist/private/nodeCredentialStore.js

@@ -0,0 +1,210 @@
+import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const NODE_SECRET_RE = /^[a-f0-9]{64}$/i;
+const WINDOWS_PROTECTED_VALUE_RE = /^[a-z0-9+/]+={0,2}$/i;
+const MAX_PROTECTED_VALUE_LENGTH = 16_384;
+export class PrivateNodeCredentialReadError extends Error {
+    constructor() {
+        super('stored private node credential is unreadable');
+        this.name = 'PrivateNodeCredentialReadError';
+    }
+}
+export class PrivateNodeCredentialStore {
+    directory;
+    path;
+    platform;
+    windowsProtector;
+    constructor(proxyStorePath, options = {}) {
+        this.platform = options.platform ?? process.platform;
+        this.windowsProtector = this.platform === 'win32'
+            ? options.windowsProtector ?? createWindowsDpapiProtector()
+            : undefined;
+        if (this.windowsProtector)
+            verifyWindowsProtector(this.windowsProtector);
+        this.directory = join(dirname(resolve(proxyStorePath)), '.private-credentials');
+        this.path = join(this.directory, this.platform === 'win32' ? 'node-secret.dpapi' : 'node-secret');
+        this.prepareDirectory();
+    }
+    read() {
+        if (!existsSync(this.path))
+            return undefined;
+        this.assertRegularFile(this.path);
+        if (this.platform !== 'win32')
+            chmodSync(this.path, FILE_MODE);
+        const storedValue = readFileSync(this.path, 'utf8').trim();
+        try {
+            const value = this.windowsProtector
+                ? this.windowsProtector.unprotect(assertWindowsProtectedValue(storedValue))
+                : storedValue;
+            if (!NODE_SECRET_RE.test(value))
+                throw new PrivateNodeCredentialReadError();
+            return value;
+        }
+        catch {
+            throw new PrivateNodeCredentialReadError();
+        }
+    }
+    write(nodeSecret) {
+        if (!NODE_SECRET_RE.test(nodeSecret))
+            throw new Error('private node credential is invalid');
+        const storedValue = this.windowsProtector
+            ? assertWindowsProtectedValue(this.windowsProtector.protect(nodeSecret))
+            : nodeSecret;
+        this.prepareDirectory();
+        if (existsSync(this.path))
+            this.assertRegularFile(this.path);
+        const temporaryPath = join(this.directory, `.node-secret.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+        let descriptor;
+        try {
+            descriptor = openSync(temporaryPath, 'wx', FILE_MODE);
+            writeFileSync(descriptor, storedValue, 'utf8');
+            fsyncSync(descriptor);
+            closeSync(descriptor);
+            descriptor = undefined;
+            renameSync(temporaryPath, this.path);
+            if (this.platform !== 'win32')
+                chmodSync(this.path, FILE_MODE);
+            if (this.platform !== 'win32')
+                syncDirectory(this.directory);
+        }
+        catch (error) {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+            if (existsSync(temporaryPath))
+                unlinkSync(temporaryPath);
+            throw error;
+        }
+    }
+    prepareDirectory() {
+        const parent = dirname(this.directory);
+        const parentStat = lstatSync(parent);
+        if (!parentStat.isDirectory() || parentStat.isSymbolicLink()) {
+            throw new Error(`private credential parent must be a real directory: ${parent}`);
+        }
+        if (this.platform !== 'win32' && (parentStat.mode & 0o022) !== 0) {
+            throw new Error(`private credential parent must not be group/world-writable: ${parent}`);
+        }
+        const directoryExisted = existsSync(this.directory);
+        mkdirSync(this.directory, { recursive: true, mode: DIRECTORY_MODE });
+        const stat = lstatSync(this.directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error(`private credential path must be a real directory: ${this.directory}`);
+        }
+        if (this.platform !== 'win32')
+            chmodSync(this.directory, DIRECTORY_MODE);
+        if (!directoryExisted && this.platform !== 'win32')
+            syncDirectory(parent);
+    }
+    assertRegularFile(path) {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`private credential must be a regular file: ${path}`);
+        }
+    }
+}
+function assertWindowsProtectedValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > MAX_PROTECTED_VALUE_LENGTH || !WINDOWS_PROTECTED_VALUE_RE.test(trimmed)) {
+        throw new Error('stored private node credential ciphertext is invalid');
+    }
+    return trimmed;
+}
+function createWindowsDpapiProtector() {
+    const systemRoot = process.env['SystemRoot']?.trim();
+    if (!systemRoot || !isAbsolute(systemRoot)) {
+        throw new Error('Windows private credential persistence requires an absolute SystemRoot');
+    }
+    const executable = join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    let executableIsSafe = false;
+    try {
+        const executableStat = lstatSync(executable);
+        executableIsSafe = executableStat.isFile() && !executableStat.isSymbolicLink();
+    }
+    catch {
+        // Normalize filesystem errors so local paths are not included in startup logs.
+    }
+    if (!executableIsSafe) {
+        throw new Error('Windows private credential persistence requires Windows PowerShell');
+    }
+    return {
+        preflight: () => {
+            const canary = randomBytes(32).toString('hex');
+            if (runWindowsPowerShell(executable, WINDOWS_DPAPI_PREFLIGHT_SCRIPT, canary) !== canary) {
+                throw new Error('Windows private credential protection preflight failed');
+            }
+        },
+        protect: (secret) => runWindowsPowerShell(executable, WINDOWS_DPAPI_PROTECT_SCRIPT, secret),
+        unprotect: (protectedValue) => runWindowsPowerShell(executable, WINDOWS_DPAPI_UNPROTECT_SCRIPT, protectedValue),
+    };
+}
+function verifyWindowsProtector(protector) {
+    try {
+        if (protector.preflight) {
+            protector.preflight();
+            return;
+        }
+        const canary = randomBytes(32).toString('hex');
+        const protectedCanary = assertWindowsProtectedValue(protector.protect(canary));
+        if (protector.unprotect(protectedCanary) !== canary) {
+            throw new Error('round trip mismatch');
+        }
+    }
+    catch {
+        throw new Error('Windows private credential protection preflight failed');
+    }
+}
+function runWindowsPowerShell(executable, script, input) {
+    try {
+        return execFileSync(executable, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script], {
+            encoding: 'utf8',
+            input,
+            maxBuffer: 64 * 1024,
+            stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 15_000,
+            windowsHide: true,
+        }).trim();
+    }
+    catch {
+        throw new Error('Windows private credential protection failed');
+    }
+}
+const WINDOWS_DPAPI_PREFLIGHT_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    'Add-Type -AssemblyName System.Security',
+    '$plain = [Console]::In.ReadToEnd()',
+    '$bytes = [Text.Encoding]::UTF8.GetBytes($plain)',
+    '$scope = [Security.Cryptography.DataProtectionScope]::CurrentUser',
+    '$protected = [Security.Cryptography.ProtectedData]::Protect($bytes, $null, $scope)',
+    '$restored = [Security.Cryptography.ProtectedData]::Unprotect($protected, $null, $scope)',
+    '[Console]::Out.Write([Text.Encoding]::UTF8.GetString($restored))',
+].join('; ');
+const WINDOWS_DPAPI_PROTECT_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    'Add-Type -AssemblyName System.Security',
+    '$plain = [Console]::In.ReadToEnd()',
+    '$bytes = [Text.Encoding]::UTF8.GetBytes($plain)',
+    '$scope = [Security.Cryptography.DataProtectionScope]::CurrentUser',
+    '$protected = [Security.Cryptography.ProtectedData]::Protect($bytes, $null, $scope)',
+    '[Console]::Out.Write([Convert]::ToBase64String($protected))',
+].join('; ');
+const WINDOWS_DPAPI_UNPROTECT_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    'Add-Type -AssemblyName System.Security',
+    '$protected = [Convert]::FromBase64String([Console]::In.ReadToEnd())',
+    '$scope = [Security.Cryptography.DataProtectionScope]::CurrentUser',
+    '$bytes = [Security.Cryptography.ProtectedData]::Unprotect($protected, $null, $scope)',
+    '[Console]::Out.Write([Text.Encoding]::UTF8.GetString($bytes))',
+].join('; ');
+function syncDirectory(path) {
+    const descriptor = openSync(path, 'r');
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

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;