@empire-builder-kit/nx 1.0.0-beta.9 → 1.0.0-rc.2

package/src/local-dev/slice-runner.js

@@ -0,0 +1,715 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RUNNER_PARENT_GRACE_MS = exports.FLEET_SLICE_RUNNER_RESTART_SCHEMA_VERSION = exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION = void 0;
+exports.fleetSliceRunnerRequiresCleanup = fleetSliceRunnerRequiresCleanup;
+exports.validateFleetSliceRunnerRequest = validateFleetSliceRunnerRequest;
+exports.validateFleetSliceRunnerState = validateFleetSliceRunnerState;
+exports.fleetSliceRunnerPaths = fleetSliceRunnerPaths;
+exports.requestFleetSliceRunnerRestart = requestFleetSliceRunnerRestart;
+exports.writeFleetSliceRunnerState = writeFleetSliceRunnerState;
+exports.readFleetSliceRunnerState = readFleetSliceRunnerState;
+exports.writeFleetSliceRunnerRequest = writeFleetSliceRunnerRequest;
+exports.readFleetSliceRunnerRequest = readFleetSliceRunnerRequest;
+exports.launchFleetSliceRunner = launchFleetSliceRunner;
+exports.runnerParentStatus = runnerParentStatus;
+exports.runFleetSliceRunner = runFleetSliceRunner;
+exports.assertFleetSliceRunnerCleanup = assertFleetSliceRunnerCleanup;
+exports.retryFleetSliceRunnerCleanup = retryFleetSliceRunnerCleanup;
+exports.recoverFleetSliceRunnerCleanups = recoverFleetSliceRunnerCleanups;
+exports.recoverFleetSliceRunnerCleanupsForSlices = recoverFleetSliceRunnerCleanupsForSlices;
+exports.inspectFleetRunnersAbsent = inspectFleetRunnersAbsent;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const contract_validation_js_1 = require("./contract-validation.js");
+const errors_js_1 = require("./errors.js");
+const fleet_process_js_1 = require("./fleet-process.js");
+const fleet_startup_js_1 = require("./fleet-startup.js");
+const nx_workspace_js_1 = require("./nx-workspace.js");
+const private_state_js_1 = require("./private-state.js");
+const process_identity_js_1 = require("./process-identity.js");
+const personal_secret_ledger_js_1 = require("./personal-secret-ledger.js");
+const personal_stage_js_1 = require("./personal-stage.js");
+const fleet_lock_js_1 = require("./fleet-lock.js");
+exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION = 1;
+exports.FLEET_SLICE_RUNNER_RESTART_SCHEMA_VERSION = 1;
+exports.DEFAULT_RUNNER_PARENT_GRACE_MS = 15_000;
+function fleetSliceRunnerRequiresCleanup(reason) {
+    return reason === 'parent-lost' || reason === 'termination';
+}
+function runnerError(message) {
+    throw new errors_js_1.LocalDevContractError('invalid-state', message);
+}
+function absolutePath(value, label) {
+    const path = (0, contract_validation_js_1.requireBoundedString)(value, label, { maximumLength: 4_096 });
+    if (!(0, node_path_1.isAbsolute)(path))
+        return runnerError(`${label} must be absolute.`);
+    return path;
+}
+function generation(value, label) {
+    return (0, contract_validation_js_1.requireBoundedString)(value, label, {
+        maximumLength: 128,
+        pattern: contract_validation_js_1.LOCAL_DEV_TOKEN_PATTERN,
+    });
+}
+function processIdentity(value, label) {
+    (0, contract_validation_js_1.assertRecord)(value, label);
+    (0, contract_validation_js_1.assertExactProperties)(value, ['pid', 'processIdentity', 'startedAt'], [], label);
+    return {
+        pid: (0, contract_validation_js_1.requireInteger)(value.pid, `${label} pid`, 1, 2_147_483_647),
+        processIdentity: (0, contract_validation_js_1.requireBoundedString)(value.processIdentity, `${label} processIdentity`, { maximumLength: 128, pattern: contract_validation_js_1.LOCAL_DEV_TOKEN_PATTERN }),
+        startedAt: (0, contract_validation_js_1.requireIsoTimestamp)(value.startedAt, `${label} startedAt`),
+    };
+}
+function exactOrigin(value) {
+    const raw = (0, contract_validation_js_1.requireBoundedString)(value, 'Fleet Slice runner origin', {
+        maximumLength: 2_048,
+    });
+    const url = new URL(raw);
+    if (url.protocol !== 'https:' ||
+        url.origin !== raw ||
+        url.username ||
+        url.password) {
+        return runnerError('Fleet Slice runner origin must be an exact credential-free HTTPS origin.');
+    }
+    return raw;
+}
+function validateFleetSliceRunnerRequest(value) {
+    (0, contract_validation_js_1.assertRecord)(value, 'Fleet Slice runner request');
+    (0, contract_validation_js_1.assertExactProperties)(value, [
+        'createdAt',
+        'fleetId',
+        'heartbeatPath',
+        'origin',
+        'parent',
+        'port',
+        'runnerGeneration',
+        'schemaVersion',
+        'sessionGeneration',
+        'slice',
+        'startupPath',
+        'workspaceRealpath',
+    ], [], 'Fleet Slice runner request');
+    if (value.schemaVersion !== exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION) {
+        return runnerError(`Fleet Slice runner schemaVersion must be ${exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION}.`);
+    }
+    return {
+        createdAt: (0, contract_validation_js_1.requireIsoTimestamp)(value.createdAt, 'Fleet Slice runner createdAt'),
+        fleetId: (0, fleet_lock_js_1.validateFleetIdentitySlug)(value.fleetId, 'Fleet Slice runner fleetId'),
+        heartbeatPath: absolutePath(value.heartbeatPath, 'Fleet Slice runner heartbeatPath'),
+        origin: exactOrigin(value.origin),
+        parent: processIdentity(value.parent, 'Fleet Slice runner parent'),
+        port: (0, contract_validation_js_1.requireInteger)(value.port, 'Fleet Slice runner port', 1, 65_535),
+        runnerGeneration: generation(value.runnerGeneration, 'Fleet Slice runner generation'),
+        schemaVersion: exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION,
+        sessionGeneration: generation(value.sessionGeneration, 'Fleet Slice runner sessionGeneration'),
+        slice: (0, fleet_lock_js_1.validateFleetIdentitySlug)(value.slice, 'Fleet Slice runner Slice'),
+        startupPath: absolutePath(value.startupPath, 'Fleet Slice runner startupPath'),
+        workspaceRealpath: absolutePath(value.workspaceRealpath, 'Fleet Slice runner workspaceRealpath'),
+    };
+}
+function validateFleetSliceRunnerState(value) {
+    (0, contract_validation_js_1.assertRecord)(value, 'Fleet Slice runner state');
+    (0, contract_validation_js_1.assertExactProperties)(value, [
+        'cleanup',
+        'fleetId',
+        'runner',
+        'runnerGeneration',
+        'schemaVersion',
+        'sessionGeneration',
+        'slice',
+        'updatedAt',
+    ], ['child', 'failure'], 'Fleet Slice runner state');
+    if (value.schemaVersion !== exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION ||
+        !['failed', 'pending', 'running', 'succeeded'].includes(String(value.cleanup))) {
+        return runnerError('Fleet Slice runner state is invalid.');
+    }
+    const state = {
+        cleanup: value.cleanup,
+        fleetId: (0, fleet_lock_js_1.validateFleetIdentitySlug)(value.fleetId, 'Fleet Slice runner state fleetId'),
+        runner: processIdentity(value.runner, 'Fleet Slice runner state runner'),
+        runnerGeneration: generation(value.runnerGeneration, 'Fleet Slice runner state runnerGeneration'),
+        schemaVersion: exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION,
+        sessionGeneration: generation(value.sessionGeneration, 'Fleet Slice runner state sessionGeneration'),
+        slice: (0, fleet_lock_js_1.validateFleetIdentitySlug)(value.slice, 'Fleet Slice runner state Slice'),
+        updatedAt: (0, contract_validation_js_1.requireIsoTimestamp)(value.updatedAt, 'Fleet Slice runner state updatedAt'),
+    };
+    if (value.child !== undefined) {
+        state.child = processIdentity(value.child, 'Fleet Slice runner state child');
+    }
+    if (value.failure !== undefined) {
+        state.failure = (0, contract_validation_js_1.requireBoundedString)(value.failure, 'Fleet Slice runner state failure', { maximumLength: 1_024 });
+    }
+    return state;
+}
+function runnerStem(slice, runnerGeneration) {
+    return `${(0, fleet_lock_js_1.validateFleetIdentitySlug)(slice, 'Fleet Slice runner Slice')}-${(0, contract_validation_js_1.sha256Digest)({ runnerGeneration: generation(runnerGeneration, 'runner generation') }).slice(0, 20)}`;
+}
+function fleetSliceRunnerPaths(runnersDirectory, slice, runnerGeneration) {
+    if (!(0, node_path_1.isAbsolute)(runnersDirectory)) {
+        return runnerError('Fleet Slice runners directory must be absolute.');
+    }
+    const stem = runnerStem(slice, runnerGeneration);
+    return {
+        request: (0, node_path_1.join)(runnersDirectory, `${stem}.request.json`),
+        restart: (0, node_path_1.join)(runnersDirectory, `${stem}.restart.json`),
+        state: (0, node_path_1.join)(runnersDirectory, `${stem}.state.json`),
+    };
+}
+function validateFleetSliceRunnerRestartRequest(value) {
+    (0, contract_validation_js_1.assertRecord)(value, 'Fleet Slice runner restart request');
+    (0, contract_validation_js_1.assertExactProperties)(value, [
+        'action',
+        'createdAt',
+        'fleetId',
+        'runnerGeneration',
+        'schemaVersion',
+        'sessionGeneration',
+        'slice',
+    ], [], 'Fleet Slice runner restart request');
+    if (value.action !== 'restart-without-cleanup' ||
+        value.schemaVersion !== exports.FLEET_SLICE_RUNNER_RESTART_SCHEMA_VERSION) {
+        return runnerError('Fleet Slice runner restart request is invalid.');
+    }
+    return {
+        action: 'restart-without-cleanup',
+        createdAt: (0, contract_validation_js_1.requireIsoTimestamp)(value.createdAt, 'Fleet Slice runner restart createdAt'),
+        fleetId: (0, fleet_lock_js_1.validateFleetIdentitySlug)(value.fleetId, 'Fleet Slice runner restart fleetId'),
+        runnerGeneration: generation(value.runnerGeneration, 'Fleet Slice runner restart runnerGeneration'),
+        schemaVersion: exports.FLEET_SLICE_RUNNER_RESTART_SCHEMA_VERSION,
+        sessionGeneration: generation(value.sessionGeneration, 'Fleet Slice runner restart sessionGeneration'),
+        slice: (0, fleet_lock_js_1.validateFleetIdentitySlug)(value.slice, 'Fleet Slice runner restart Slice'),
+    };
+}
+function requestFleetSliceRunnerRestart(launched, effects = {}) {
+    const state = readFleetSliceRunnerState(launched.statePath, effects.security ?? {});
+    if (state.fleetId !== launched.request.fleetId ||
+        state.runnerGeneration !== launched.request.runnerGeneration ||
+        state.sessionGeneration !== launched.request.sessionGeneration ||
+        state.slice !== launched.request.slice ||
+        state.cleanup !== 'pending') {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet Slice restart requires the exact active runner generation with pending cleanup authority.');
+    }
+    const request = validateFleetSliceRunnerRestartRequest({
+        action: 'restart-without-cleanup',
+        createdAt: (effects.now ?? (() => new Date()))().toISOString(),
+        fleetId: launched.request.fleetId,
+        runnerGeneration: launched.request.runnerGeneration,
+        schemaVersion: exports.FLEET_SLICE_RUNNER_RESTART_SCHEMA_VERSION,
+        sessionGeneration: launched.request.sessionGeneration,
+        slice: launched.request.slice,
+    });
+    if (!(0, private_state_js_1.createPrivateFileExclusive)(launched.restartPath, `${JSON.stringify(request, null, 2)}\n`, effects.security)) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet Slice restart intent already exists; refusing ambiguous process replacement.');
+    }
+}
+function consumeFleetSliceRunnerRestart(path, request, security) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return false;
+    try {
+        const restart = validateFleetSliceRunnerRestartRequest(JSON.parse((0, private_state_js_1.readPrivateFile)(path, security).toString('utf8')));
+        if (restart.fleetId !== request.fleetId ||
+            restart.runnerGeneration !== request.runnerGeneration ||
+            restart.sessionGeneration !== request.sessionGeneration ||
+            restart.slice !== request.slice) {
+            return false;
+        }
+        (0, node_fs_1.unlinkSync)(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function writeFleetSliceRunnerState(path, state, security = {}) {
+    const validated = validateFleetSliceRunnerState(state);
+    (0, private_state_js_1.atomicWritePrivateFile)(path, `${JSON.stringify(validated, null, 2)}\n`, security);
+    return validated;
+}
+function readFleetSliceRunnerState(path, security = {}) {
+    return validateFleetSliceRunnerState(JSON.parse((0, private_state_js_1.readPrivateFile)(path, security).toString('utf8')));
+}
+function writeFleetSliceRunnerRequest(path, value, security = {}) {
+    const request = validateFleetSliceRunnerRequest(value);
+    if (!(0, private_state_js_1.createPrivateFileExclusive)(path, `${JSON.stringify(request, null, 2)}\n`, security)) {
+        return runnerError('Fleet Slice runner request already exists.');
+    }
+    return request;
+}
+function readFleetSliceRunnerRequest(path, security = {}) {
+    return validateFleetSliceRunnerRequest(JSON.parse((0, private_state_js_1.readPrivateFile)(path, security).toString('utf8')));
+}
+function launchFleetSliceRunner(input, effects = {}) {
+    (0, private_state_js_1.ensurePrivateDirectory)(input.runtimePaths.runnersDirectory, effects.security);
+    const paths = fleetSliceRunnerPaths(input.runtimePaths.runnersDirectory, input.slice, input.runnerGeneration);
+    const request = writeFleetSliceRunnerRequest(paths.request, {
+        createdAt: (effects.now ?? (() => new Date()))().toISOString(),
+        fleetId: (0, node_path_1.basename)(input.runtimePaths.sessionDirectory),
+        heartbeatPath: input.runtimePaths.heartbeat,
+        origin: input.origin.origin,
+        parent: input.parent,
+        port: input.port,
+        runnerGeneration: input.runnerGeneration,
+        schemaVersion: exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION,
+        sessionGeneration: input.sessionGeneration,
+        slice: input.slice,
+        startupPath: input.startupPath,
+        workspaceRealpath: input.workspaceRealpath,
+    }, effects.security);
+    const daemonPath = effects.daemonPath ?? require.resolve('./fleet-slice-runner-daemon.js');
+    try {
+        const child = (effects.spawn ?? node_child_process_1.spawn)(process.execPath, [daemonPath], {
+            cwd: request.workspaceRealpath,
+            detached: process.platform !== 'win32',
+            env: (0, personal_stage_js_1.createPersonalDevelopmentEnvironment)((0, fleet_startup_js_1.readFleetStartupRequest)(request.startupPath).identity.stage, {
+                ...process.env,
+                EBK_FLEET_SLICE_RUNNER_REQUEST: paths.request,
+            }),
+            shell: false,
+            stdio: 'pipe',
+            windowsHide: true,
+        });
+        return {
+            child,
+            request,
+            requestPath: paths.request,
+            restartPath: paths.restart,
+            statePath: paths.state,
+        };
+    }
+    catch (error) {
+        if ((0, node_fs_1.existsSync)(paths.request))
+            (0, node_fs_1.unlinkSync)(paths.request);
+        throw error;
+    }
+}
+function childExit(child) {
+    return new Promise((resolvePromise, reject) => {
+        child.once('error', reject);
+        child.once('exit', (code) => resolvePromise(code));
+    });
+}
+async function runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, stage, workspaceRealpath, spawnTarget) {
+    if (!cleanupTarget)
+        return;
+    const cleanup = spawnTarget(runtime, cleanupTarget, {
+        additionalEnvironment: childEnvironment,
+        stage,
+        stdio: 'inherit',
+        workspaceRoot: workspaceRealpath,
+    });
+    const code = await childExit(cleanup);
+    if (code !== 0) {
+        throw new Error(`${cleanupTarget.project}:${cleanupTarget.target} exited with status ${code ?? 'unknown'}.`);
+    }
+}
+function readParentHeartbeat(path, security) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return undefined;
+    try {
+        const value = JSON.parse((0, private_state_js_1.readPrivateFile)(path, security).toString('utf8'));
+        return {
+            heartbeatAt: (0, contract_validation_js_1.requireIsoTimestamp)(value.heartbeatAt, 'Fleet supervisor heartbeatAt'),
+            processIdentity: (0, contract_validation_js_1.requireBoundedString)(value.processIdentity, 'Fleet supervisor heartbeat processIdentity', { maximumLength: 128, pattern: contract_validation_js_1.LOCAL_DEV_TOKEN_PATTERN }),
+            sessionGeneration: generation(value.sessionGeneration, 'Fleet supervisor heartbeat sessionGeneration'),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function runnerParentStatus(request, options = {}) {
+    const processProbe = options.processProbe ?? (0, process_identity_js_1.probeProcessIdentity)(request.parent);
+    if (processProbe === 'matching')
+        return 'present';
+    if (processProbe === 'ambiguous')
+        return 'ambiguous';
+    const heartbeat = readParentHeartbeat(request.heartbeatPath, options.security ?? {});
+    const authorityTimestamp = heartbeat?.sessionGeneration === request.sessionGeneration &&
+        heartbeat.processIdentity === request.parent.processIdentity
+        ? heartbeat.heartbeatAt
+        : request.createdAt;
+    const grace = options.graceMs ?? exports.DEFAULT_RUNNER_PARENT_GRACE_MS;
+    return (options.now ?? new Date()).getTime() -
+        Date.parse(authorityTimestamp) >
+        grace
+        ? 'lost'
+        : 'ambiguous';
+}
+async function runFleetSliceRunner(requestPath, options = {}) {
+    const security = options.security ?? {};
+    const now = options.now ?? (() => new Date());
+    const request = readFleetSliceRunnerRequest(requestPath, security);
+    const startup = (0, fleet_startup_js_1.readFleetStartupRequest)(request.startupPath, security);
+    if (startup.fleetId !== request.fleetId ||
+        startup.sessionGeneration !== request.sessionGeneration ||
+        startup.workspaceRealpath !== request.workspaceRealpath) {
+        return runnerError('Fleet Slice runner request does not match its startup authority.');
+    }
+    const plan = await (options.loadPlan ?? nx_workspace_js_1.loadWorkspaceFleetPlan)();
+    const adapter = plan.adapters.get(request.slice);
+    if (!adapter) {
+        return runnerError('Fleet Slice runner Slice is absent from the Nx plan.');
+    }
+    const startTarget = (0, nx_workspace_js_1.declaredStartTarget)(plan, request.slice);
+    const cleanupTarget = (0, nx_workspace_js_1.declaredCleanupTarget)(plan, request.slice);
+    const runtime = (options.resolveRuntime ?? nx_workspace_js_1.resolveWorkspaceNxRuntime)(request.workspaceRealpath);
+    const paths = fleetSliceRunnerPaths((0, node_path_1.join)((0, node_path_1.dirname)(request.startupPath), 'runners'), request.slice, request.runnerGeneration);
+    const runner = (options.processIdentity ?? process_identity_js_1.captureProcessIdentity)();
+    const origin = new URL(request.origin);
+    const childEnvironment = (0, personal_stage_js_1.createPersonalDevelopmentEnvironment)(startup.identity.stage, {
+        ...process.env,
+        AWS_DEFAULT_REGION: startup.context.region,
+        AWS_PROFILE: startup.context.profile,
+        AWS_REGION: startup.context.region,
+        EBK_AUTH_CALLBACK_URLS: JSON.stringify(adapter.auth?.callbackPaths?.map((path) => new URL(path, origin).toString()) ?? []),
+        EBK_AUTH_LOGOUT_URLS: JSON.stringify(adapter.auth?.logoutPaths?.map((path) => new URL(path, origin).toString()) ?? []),
+        EBK_FLEET_ORIGIN: origin.origin,
+        EBK_LOCAL_DEV_APP_DATA: startup.appData,
+        EBK_PERSONAL_SECRET_LEDGER_PATH: (0, personal_secret_ledger_js_1.personalSecretLedgerPath)(startup.appData, request.slice, startup.identity.stage),
+        EBK_SECURE_COOKIES: 'true',
+        EBK_SST_DEV_MODE: startup.sstMode,
+    });
+    const spawnTarget = options.spawnTarget ?? nx_workspace_js_1.spawnDeclaredNxTarget;
+    const terminate = options.terminate ?? fleet_process_js_1.terminateOwnedChild;
+    if ((0, node_fs_1.existsSync)(paths.state)) {
+        let previous = readFleetSliceRunnerState(paths.state, security);
+        if (previous.fleetId !== request.fleetId ||
+            previous.runnerGeneration !== request.runnerGeneration ||
+            previous.sessionGeneration !== request.sessionGeneration ||
+            previous.slice !== request.slice) {
+            return runnerError('Fleet Slice cleanup retry does not match the retained runner authority.');
+        }
+        const processProbe = options.processProbe ?? process_identity_js_1.probeProcessIdentity;
+        if (processProbe(previous.runner) !== 'absent' ||
+            (previous.child && processProbe(previous.child) !== 'absent')) {
+            return runnerError('Fleet Slice cleanup retry requires exact prior runner and child absence.');
+        }
+        if (previous.cleanup === 'succeeded') {
+            if ((0, node_fs_1.existsSync)(requestPath))
+                (0, node_fs_1.unlinkSync)(requestPath);
+            if ((0, node_fs_1.existsSync)(paths.restart))
+                (0, node_fs_1.unlinkSync)(paths.restart);
+            return 0;
+        }
+        previous = writeFleetSliceRunnerState(paths.state, {
+            cleanup: 'running',
+            fleetId: request.fleetId,
+            runner,
+            runnerGeneration: request.runnerGeneration,
+            schemaVersion: exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION,
+            sessionGeneration: request.sessionGeneration,
+            slice: request.slice,
+            updatedAt: now().toISOString(),
+        }, security);
+        try {
+            await runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, startup.identity.stage, request.workspaceRealpath, spawnTarget);
+            writeFleetSliceRunnerState(paths.state, {
+                ...previous,
+                cleanup: 'succeeded',
+                updatedAt: now().toISOString(),
+            }, security);
+            if ((0, node_fs_1.existsSync)(requestPath))
+                (0, node_fs_1.unlinkSync)(requestPath);
+            if ((0, node_fs_1.existsSync)(paths.restart))
+                (0, node_fs_1.unlinkSync)(paths.restart);
+            return 0;
+        }
+        catch (error) {
+            writeFleetSliceRunnerState(paths.state, {
+                ...previous,
+                cleanup: 'failed',
+                failure: error instanceof Error ? error.message : String(error),
+                updatedAt: now().toISOString(),
+            }, security);
+            return 1;
+        }
+    }
+    let state = writeFleetSliceRunnerState(paths.state, {
+        cleanup: 'pending',
+        fleetId: request.fleetId,
+        runner,
+        runnerGeneration: request.runnerGeneration,
+        schemaVersion: exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION,
+        sessionGeneration: request.sessionGeneration,
+        slice: request.slice,
+        updatedAt: now().toISOString(),
+    }, security);
+    const child = spawnTarget(runtime, startTarget, {
+        additionalEnvironment: childEnvironment,
+        port: request.port,
+        stage: startup.identity.stage,
+        stdio: 'inherit',
+        workspaceRoot: request.workspaceRealpath,
+    });
+    try {
+        if (!child.pid)
+            throw new Error('Slice child did not expose a PID.');
+        state = writeFleetSliceRunnerState(paths.state, {
+            ...state,
+            child: (options.processIdentity ?? process_identity_js_1.captureProcessIdentity)(child.pid),
+            updatedAt: now().toISOString(),
+        }, security);
+    }
+    catch (error) {
+        await terminate(child).catch(() => undefined);
+        state = writeFleetSliceRunnerState(paths.state, {
+            ...state,
+            cleanup: 'failed',
+            failure: error instanceof Error ? error.message : String(error),
+            updatedAt: now().toISOString(),
+        }, security);
+        return 1;
+    }
+    let finalizing;
+    let interval;
+    const finalize = (terminateChild, cleanup) => {
+        if (finalizing)
+            return finalizing;
+        finalizing = (async () => {
+            if (interval)
+                clearInterval(interval);
+            if (!cleanup) {
+                try {
+                    if (terminateChild)
+                        await terminate(child);
+                    state = writeFleetSliceRunnerState(paths.state, {
+                        ...state,
+                        cleanup: 'pending',
+                        updatedAt: now().toISOString(),
+                    }, security);
+                    return 0;
+                }
+                catch (error) {
+                    state = writeFleetSliceRunnerState(paths.state, {
+                        ...state,
+                        cleanup: 'failed',
+                        failure: error instanceof Error ? error.message : String(error),
+                        updatedAt: now().toISOString(),
+                    }, security);
+                    return 1;
+                }
+            }
+            state = writeFleetSliceRunnerState(paths.state, { ...state, cleanup: 'running', updatedAt: now().toISOString() }, security);
+            try {
+                if (terminateChild)
+                    await terminate(child);
+                await runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, startup.identity.stage, request.workspaceRealpath, spawnTarget);
+                state = writeFleetSliceRunnerState(paths.state, {
+                    ...state,
+                    cleanup: 'succeeded',
+                    updatedAt: now().toISOString(),
+                }, security);
+                if ((0, node_fs_1.existsSync)(requestPath))
+                    (0, node_fs_1.unlinkSync)(requestPath);
+                if ((0, node_fs_1.existsSync)(paths.restart))
+                    (0, node_fs_1.unlinkSync)(paths.restart);
+                return 0;
+            }
+            catch (error) {
+                state = writeFleetSliceRunnerState(paths.state, {
+                    ...state,
+                    cleanup: 'failed',
+                    failure: error instanceof Error ? error.message : String(error),
+                    updatedAt: now().toISOString(),
+                }, security);
+                return 1;
+            }
+        })();
+        return finalizing;
+    };
+    const interrupt = () => void finalize(true, fleetSliceRunnerRequiresCleanup('termination'));
+    const terminateSignal = () => {
+        const reason = consumeFleetSliceRunnerRestart(paths.restart, request, security)
+            ? 'explicit-restart'
+            : 'termination';
+        void finalize(true, fleetSliceRunnerRequiresCleanup(reason));
+    };
+    process.once('SIGINT', interrupt);
+    process.once('SIGTERM', terminateSignal);
+    // A child exit is restartable process failure, not consent to destroy local
+    // prerequisites. The exact runner request and pending cleanup evidence stay
+    // behind so a later explicit down or proved-stale recovery can clean them.
+    const childFinished = childExit(child).then(() => finalize(false, fleetSliceRunnerRequiresCleanup('child-exit')));
+    const parentLost = new Promise((resolvePromise) => {
+        interval = setInterval(() => {
+            if (runnerParentStatus(request, {
+                graceMs: options.parentGraceMs,
+                now: now(),
+                processProbe: options.processProbe?.(request.parent),
+                security,
+            }) === 'lost') {
+                void finalize(true, fleetSliceRunnerRequiresCleanup('parent-lost')).then(resolvePromise);
+            }
+        }, options.monitorIntervalMs ?? 1_000);
+        interval.unref();
+    });
+    const result = await Promise.race([childFinished, parentLost]);
+    process.removeListener('SIGINT', interrupt);
+    process.removeListener('SIGTERM', terminateSignal);
+    return (result ??
+        (await finalize(true, fleetSliceRunnerRequiresCleanup('termination'))));
+}
+function assertFleetSliceRunnerCleanup(statePath, expected, security = {}) {
+    const state = readFleetSliceRunnerState(statePath, security);
+    if (state.cleanup !== 'succeeded' ||
+        state.fleetId !== expected.fleetId ||
+        state.runnerGeneration !== expected.runnerGeneration ||
+        state.sessionGeneration !== expected.sessionGeneration ||
+        state.slice !== expected.slice) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice runner cleanup is ${state.cleanup}; its claim remains retained.`);
+    }
+}
+async function retryFleetSliceRunnerCleanup(launched, effects = {}) {
+    const security = effects.security ?? {};
+    let state;
+    try {
+        state = readFleetSliceRunnerState(launched.statePath, security);
+    }
+    catch (error) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice cleanup retry lacks validated runner state: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (state.fleetId !== launched.request.fleetId ||
+        state.runnerGeneration !== launched.request.runnerGeneration ||
+        state.sessionGeneration !== launched.request.sessionGeneration ||
+        state.slice !== launched.request.slice) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet Slice cleanup retry authority does not match the retained runner.');
+    }
+    const probe = effects.processProbe ?? process_identity_js_1.probeProcessIdentity;
+    if (probe(state.runner) !== 'absent' ||
+        (state.child && probe(state.child) !== 'absent')) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet Slice cleanup retry cannot prove the prior runner and child absent.');
+    }
+    if (state.cleanup === 'succeeded') {
+        if ((0, node_fs_1.existsSync)(launched.requestPath))
+            (0, node_fs_1.unlinkSync)(launched.requestPath);
+        const restartPath = launched.statePath.replace(/\.state\.json$/, '.restart.json');
+        if ((0, node_fs_1.existsSync)(restartPath))
+            (0, node_fs_1.unlinkSync)(restartPath);
+        return;
+    }
+    if (!(0, node_fs_1.existsSync)(launched.requestPath)) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet Slice cleanup retry request is missing; its claim remains retained.');
+    }
+    const request = readFleetSliceRunnerRequest(launched.requestPath, security);
+    if (request.fleetId !== launched.request.fleetId ||
+        request.runnerGeneration !== launched.request.runnerGeneration ||
+        request.sessionGeneration !== launched.request.sessionGeneration ||
+        request.slice !== launched.request.slice) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet Slice cleanup retry request changed after retained-state inspection.');
+    }
+    const startup = (0, fleet_startup_js_1.readFleetStartupRequest)(request.startupPath, security);
+    const daemonPath = effects.daemonPath ?? require.resolve('./fleet-slice-runner-daemon.js');
+    const child = (effects.spawn ?? node_child_process_1.spawn)(process.execPath, [daemonPath], {
+        cwd: request.workspaceRealpath,
+        detached: process.platform !== 'win32',
+        env: (0, personal_stage_js_1.createPersonalDevelopmentEnvironment)(startup.identity.stage, {
+            ...process.env,
+            EBK_FLEET_SLICE_RUNNER_REQUEST: launched.requestPath,
+        }),
+        shell: false,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    const timeoutMs = effects.timeoutMs ?? 120_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000) {
+        await (0, fleet_process_js_1.terminateOwnedChild)(child);
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet Slice cleanup retry timeout is invalid.');
+    }
+    let timeout;
+    const result = await Promise.race([
+        childExit(child).then((code) => ({ code, timedOut: false })),
+        new Promise((resolvePromise) => {
+            timeout = setTimeout(() => resolvePromise({ timedOut: true }), timeoutMs);
+        }),
+    ]);
+    if (timeout)
+        clearTimeout(timeout);
+    if (!('code' in result)) {
+        await (0, fleet_process_js_1.terminateOwnedChild)(child);
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice cleanup retry exceeded ${timeoutMs}ms; its claim remains retained.`);
+    }
+    const code = result.code;
+    if (code !== 0) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice cleanup retry exited with status ${code ?? 'unknown'}; its claim remains retained.`);
+    }
+    assertFleetSliceRunnerCleanup(launched.statePath, launched.request, security);
+    const restartPath = launched.statePath.replace(/\.state\.json$/, '.restart.json');
+    if ((0, node_fs_1.existsSync)(restartPath))
+        (0, node_fs_1.unlinkSync)(restartPath);
+}
+async function recoverFleetSliceRunnerCleanups(state, paths, effects = {}) {
+    const selected = new Set(state.slices
+        .filter(({ selected: isSelected }) => isSelected)
+        .map(({ name }) => name));
+    return recoverFleetSliceRunnerCleanupsForSlices({
+        fleetId: state.fleetId,
+        sessionGeneration: state.sessionGeneration,
+    }, selected, paths, effects);
+}
+async function recoverFleetSliceRunnerCleanupsForSlices(authority, selectedSlices, paths, effects = {}) {
+    const selected = new Set([...selectedSlices].map((slice) => (0, fleet_lock_js_1.validateFleetIdentitySlug)(slice, 'Fleet cleanup Slice')));
+    if (selected.size === 0)
+        return;
+    if (!(0, node_fs_1.existsSync)(paths.runnersDirectory)) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet Slice runner directory is missing; retained claims cannot be cleaned.');
+    }
+    for (const name of (0, node_fs_1.readdirSync)(paths.runnersDirectory).sort()) {
+        if (!name.endsWith('.state.json'))
+            continue;
+        const statePath = (0, node_path_1.join)(paths.runnersDirectory, name);
+        const runnerState = readFleetSliceRunnerState(statePath, effects.security ?? {});
+        if (runnerState.fleetId !== authority.fleetId ||
+            runnerState.sessionGeneration !== authority.sessionGeneration ||
+            !selected.has(runnerState.slice)) {
+            continue;
+        }
+        const requestPath = statePath.replace(/\.state\.json$/, '.request.json');
+        if (runnerState.cleanup === 'succeeded' && !(0, node_fs_1.existsSync)(requestPath)) {
+            continue;
+        }
+        if (!(0, node_fs_1.existsSync)(requestPath)) {
+            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice ${runnerState.slice} retained cleanup lacks its exact request.`);
+        }
+        const request = readFleetSliceRunnerRequest(requestPath, effects.security ?? {});
+        await retryFleetSliceRunnerCleanup({ request, requestPath, statePath }, effects);
+    }
+}
+function inspectFleetRunnersAbsent(state, paths, effects = {}) {
+    const selected = state.slices
+        .filter(({ selected: isSelected }) => isSelected)
+        .map(({ name }) => name);
+    if (selected.length === 0)
+        return true;
+    if (!(0, node_fs_1.existsSync)(paths.runnersDirectory))
+        return 'ambiguous';
+    let runnerStates;
+    try {
+        const entries = (0, node_fs_1.readdirSync)(paths.runnersDirectory);
+        if (entries.some((name) => !/^[a-z0-9][a-z0-9-]{0,62}-[a-f0-9]{20}\.state\.json$/.test(name))) {
+            return 'ambiguous';
+        }
+        runnerStates = entries
+            .map((name) => readFleetSliceRunnerState((0, node_path_1.join)(paths.runnersDirectory, name), effects.security ?? {}))
+            .filter((runner) => runner.fleetId === state.fleetId &&
+            runner.sessionGeneration === state.sessionGeneration);
+    }
+    catch {
+        return 'ambiguous';
+    }
+    const probe = effects.processProbe ?? process_identity_js_1.probeProcessIdentity;
+    for (const slice of selected) {
+        const matching = runnerStates.filter((runner) => runner.slice === slice);
+        if (matching.length === 0)
+            return 'ambiguous';
+        for (const runner of matching) {
+            if (runner.cleanup !== 'succeeded' ||
+                probe(runner.runner) !== 'absent' ||
+                (runner.child && probe(runner.child) !== 'absent')) {
+                return 'ambiguous';
+            }
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=slice-runner.js.map