@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.40

package/src/local-dev/fleet-logs.js

@@ -63,15 +63,35 @@ function isSensitiveRecordKey(key) {
 function logError(message) {
     throw new errors_js_1.LocalDevContractError('log-query-invalid', message);
 }
+function safeLogCharacter(character) {
+    const codePoint = character.codePointAt(0);
+    return (codePoint === 0x09 ||
+        (codePoint >= 0x20 &&
+            !(codePoint >= 0x7f && codePoint <= 0x9f) &&
+            codePoint !== 0x2028 &&
+            codePoint !== 0x2029));
+}
+/** Log text is not an identity token: indentation and tabs are meaningful. */
+function requireLogMessage(value) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        Buffer.byteLength(value, 'utf8') > exports.LOCAL_LOG_MAX_LINE_BYTES ||
+        [...value].some((character) => !safeLogCharacter(character))) {
+        return logError('Local log message must be bounded UTF-8 text without unsafe controls.');
+    }
+    return value;
+}
+function truncateUtf8(value, maximumBytes) {
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.length <= maximumBytes)
+        return value;
+    let end = maximumBytes;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return bytes.subarray(0, end).toString('utf8');
+}
 function stripUnsafeTerminalText(value) {
-    return [...value.replace(ANSI_ESCAPE, '')]
-        .filter((character) => {
-        const codePoint = character.codePointAt(0);
-        return (codePoint === 0x09 ||
-            (codePoint >= 0x20 && codePoint !== 0x7f) ||
-            codePoint > 0x9f);
-    })
-        .join('');
+    return [...value.replace(ANSI_ESCAPE, '')].filter(safeLogCharacter).join('');
 }
 function replaceCredentialUrl(value) {
     return value.replace(sharedCredentialPattern('credential-url'), (credentialUrl) => {
@@ -94,7 +114,7 @@ function boundedRecordValue(value, exactValues, depth = 0) {
     if (depth > 4)
         return '[TRUNCATED_DEPTH]';
     if (typeof value === 'string') {
-        return redactLocalLogText(value, exactValues).slice(0, 2_048);
+        return truncateUtf8(redactLocalLogText(value, exactValues), 2_048);
     }
     if (value === null ||
         typeof value === 'boolean' ||
@@ -166,9 +186,7 @@ function validateLocalLogEnvelope(value) {
         fleetId: (0, fleet_lock_js_1.validateFleetIdentitySlug)(value.fleetId, 'Local log fleetId'),
         kind: value.kind,
         level: value.level,
-        message: (0, contract_validation_js_1.requireBoundedString)(value.message, 'Local log message', {
-            maximumLength: exports.LOCAL_LOG_MAX_LINE_BYTES,
-        }),
+        message: requireLogMessage(value.message),
         schemaVersion: exports.LOCAL_LOG_SCHEMA_VERSION,
         sequence: (0, contract_validation_js_1.requireInteger)(value.sequence, 'Local log sequence', 0, Number.MAX_SAFE_INTEGER),
         sessionGeneration: (0, contract_validation_js_1.requireBoundedString)(value.sessionGeneration, 'Local log sessionGeneration', {
@@ -338,6 +356,9 @@ class FleetLogStore {
         this.#maxAgeMs = options.maxAgeMs ?? exports.LOCAL_LOG_MAX_AGE_MS;
         this.#maxGenerations = options.maxGenerations ?? exports.LOCAL_LOG_MAX_GENERATIONS;
         this.#maxLineBytes = options.maxLineBytes ?? exports.LOCAL_LOG_MAX_LINE_BYTES;
+        if (this.#maxLineBytes > exports.LOCAL_LOG_MAX_LINE_BYTES) {
+            return logError('Local log line bound cannot exceed the public protocol byte limit.');
+        }
         this.#now = options.now ?? (() => new Date());
         this.#security = options.security ?? {};
         for (const [value, label] of [
@@ -392,11 +413,8 @@ class FleetLogStore {
     writeLine(slice, stream, attempt, line) {
         const terminalSafe = stripUnsafeTerminalText(line);
         const bytes = Buffer.byteLength(terminalSafe);
-        const truncated = bytes > this.#maxLineBytes;
+        let truncated = bytes > this.#maxLineBytes;
         const redacted = redactLocalLogText(terminalSafe, this.#exactValues);
-        const boundedPlain = truncated
-            ? Buffer.from(redacted).subarray(0, this.#maxLineBytes).toString('utf8')
-            : redacted;
         let parsed;
         if (!truncated) {
             try {
@@ -406,22 +424,32 @@ class FleetLogStore {
                 parsed = undefined;
             }
         }
-        const structured = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);
-        const bounded = structured ? terminalSafe : boundedPlain;
-        const record = structured
+        let structured = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);
+        let record = structured
             ? boundedRecordValue(parsed, this.#exactValues)
             : undefined;
-        const rawMessage = record && typeof record.message === 'string'
+        let rawMessage = record && typeof record.message === 'string'
             ? record.message
             : structured
                 ? 'Structured log record'
-                : bounded || '[empty line]';
+                : redacted || '[empty line]';
+        // Redaction can expand short inputs. Bound the sanitized payload, not its
+        // pre-redaction length, and never split a multi-byte UTF-8 character.
+        if (record &&
+            Buffer.byteLength(JSON.stringify(record)) > this.#maxLineBytes) {
+            rawMessage = JSON.stringify(record);
+            record = undefined;
+            structured = false;
+            truncated = true;
+        }
+        truncated ||= Buffer.byteLength(rawMessage) > this.#maxLineBytes;
+        const message = truncateUtf8(rawMessage, this.#maxLineBytes) || '.';
         const envelope = {
             attempt,
             fleetId: this.#fleetId,
             kind: structured ? 'structured' : 'plain',
             level: normalizeLevel(record?.level, stream),
-            message: rawMessage,
+            message,
             ...(record ? { record } : {}),
             schemaVersion: exports.LOCAL_LOG_SCHEMA_VERSION,
             sequence: this.#sequence,

package/src/local-dev/fleet-process.d.ts

@@ -1,6 +1,8 @@
 import { type ChildProcess } from 'node:child_process';
 import type { LocalDevAdapter } from './contracts.js';
 import type { FleetLogStore } from './fleet-logs.js';
+import type { FleetProcessIdentity } from './fleet-lock.js';
+import type { NativeDevelopmentCompletion } from './native-completion.js';
 export type FleetProcessRouteState = 'remote' | 'starting' | 'ready' | 'unavailable';
 export type FleetProcessCleanupState = 'failed' | 'not-declared' | 'pending' | 'succeeded';
 export interface FleetProcessLaunch {
@@ -8,6 +10,10 @@ export interface FleetProcessLaunch {
     child: ChildProcess;
 }
 export interface FleetProcessEffects {
+    /** Native provisioning may outlast HTTP readiness. This is an owned launch
+     * notification, not an HTTP-health result. Non-native adapters omit it. */
+    applicationStarted?: () => boolean;
+    nativeDeployment?: (signal: AbortSignal) => Promise<NativeDevelopmentCompletion>;
     cleanup?: () => Promise<void>;
     delay?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
     launch: (attempt: number) => FleetProcessLaunch;
@@ -19,6 +25,7 @@ export interface FleetProcessEffects {
 export interface FleetProcessControllerOptions {
     adapter: LocalDevAdapter;
     healthTimeoutMs?: number;
+    provisioningTimeoutMs?: number;
     logStore?: FleetLogStore;
     maxRestartAttempts: number;
     name: string;
@@ -33,7 +40,15 @@ export declare function planFleetRestart(completedRestartAttempts: number, maxRe
     nextAttempt: number;
     restart: true;
 };
-export declare function terminateOwnedChild(child: ChildProcess): Promise<void>;
+export declare function assertOwnedGroupAbsent(pid: number, deadline?: number): Promise<void>;
+export declare function terminateOwnedChild(child: ChildProcess, ownedIdentity?: FleetProcessIdentity): Promise<void>;
+export declare const FLEET_RUNNER_STOP_MESSAGE = "ebk-fleet-runner-stop";
+/** A runner coordinates detached children and native cleanup. Never force-kill
+ * that coordinator on a client observation deadline. An explicit diagnostic
+ * deadline retains live ownership and reports failure instead of orphaning a
+ * writer (and falsely permitting stale-process recovery).
+ */
+export declare function terminateCoordinatingFleetRunner(child: ChildProcess, runnerGeneration: string, timeoutMs?: number): Promise<void>;
 export declare class FleetProcessController {
     #private;
     constructor(options: FleetProcessControllerOptions, effects: FleetProcessEffects);
@@ -42,6 +57,10 @@ export declare class FleetProcessController {
     get runnerGeneration(): string | undefined;
     get state(): FleetProcessRouteState;
     start(): Promise<void>;
+    /** Cancel readiness and pending automatic retries, not controller lifetime.
+     * The serialized startup rollback retains
+     * responsibility for native termination and exact cleanup before down runs. */
+    interruptStartup(): void;
     restart(): Promise<void>;
     stop(options: {
         cleanup: boolean;

package/src/local-dev/fleet-process.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FleetProcessController = void 0;
+exports.FleetProcessController = exports.FLEET_RUNNER_STOP_MESSAGE = void 0;
 exports.fleetRestartDelay = fleetRestartDelay;
 exports.planFleetRestart = planFleetRestart;
+exports.assertOwnedGroupAbsent = assertOwnedGroupAbsent;
 exports.terminateOwnedChild = terminateOwnedChild;
+exports.terminateCoordinatingFleetRunner = terminateCoordinatingFleetRunner;
 const node_child_process_1 = require("node:child_process");
 const errors_js_1 = require("./errors.js");
+const process_group_js_1 = require("./process-group.js");
+const process_identity_js_1 = require("./process-identity.js");
 function fleetRestartDelay(attempt) {
     if (!Number.isInteger(attempt) || attempt < 0) {
         throw new errors_js_1.LocalDevContractError('invalid-input', 'Fleet restart attempt must be a non-negative integer.');
@@ -27,9 +31,40 @@ function planFleetRestart(completedRestartAttempts, maxRestartAttempts) {
         restart: true,
     };
 }
-async function terminateOwnedChild(child) {
-    if (child.exitCode !== null || child.signalCode !== null)
+async function waitForOwnedExit(exited, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            exited.then(() => true),
+            new Promise((resolvePromise) => {
+                timer = setTimeout(() => resolvePromise(false), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function assertOwnedGroupAbsent(pid, deadline = Date.now() + 1_000) {
+    // Native Windows retains its existing taskkill contract. This POSIX proof
+    // is not a claim that Windows orphan trees can be inspected after exit.
+    if (process.platform === 'win32')
+        return;
+    while ((0, process_group_js_1.exactOwnedProcessGroupExists)(pid)) {
+        if (Date.now() >= deadline)
+            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Owned child group remains after leader exit; child ownership is retained.');
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+}
+async function terminateOwnedChild(child, ownedIdentity) {
+    if (!child.pid)
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Owned child PID is unavailable.');
+    if (child.exitCode !== null || child.signalCode !== null) {
+        await assertOwnedGroupAbsent(child.pid);
         return;
+    }
+    const deadline = Date.now() + process_group_js_1.OWNED_PROCESS_SIGNAL_GRACE_MS + process_group_js_1.OWNED_PROCESS_KILL_WAIT_MS;
     const exited = new Promise((resolvePromise) => child.once('exit', () => resolvePromise()));
     if (process.platform === 'win32' && child.pid) {
         const killer = (0, node_child_process_1.spawn)('taskkill', ['/pid', String(child.pid), '/t', '/f'], {
@@ -37,36 +72,84 @@ async function terminateOwnedChild(child) {
             windowsHide: true,
         });
         await new Promise((resolvePromise) => killer.once('exit', () => resolvePromise()));
-        await Promise.race([
-            exited,
-            new Promise((resolvePromise) => setTimeout(resolvePromise, 2_000)),
-        ]);
+        await waitForOwnedExit(exited, 2_000);
         return;
     }
-    if (child.pid) {
+    const identity = ownedIdentity ?? (0, process_identity_js_1.captureProcessIdentity)(child.pid);
+    const signalOwned = (signal) => {
+        if (identity.pid !== child.pid ||
+            (0, process_identity_js_1.probeProcessIdentity)(identity) !== 'matching')
+            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Owned child identity changed; no process group was signaled.');
         try {
-            process.kill(-child.pid, 'SIGTERM');
+            process.kill(-identity.pid, signal);
         }
-        catch {
-            child.kill('SIGTERM');
+        catch (error) {
+            if (typeof error !== 'object' ||
+                error === null ||
+                !('code' in error) ||
+                error.code !== 'ESRCH')
+                throw error;
+            if ((0, process_identity_js_1.probeProcessIdentity)(identity) !== 'matching')
+                throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Owned child identity changed before direct signal.');
+            child.kill(signal);
         }
-    }
-    const stopped = await Promise.race([
-        exited.then(() => true),
-        new Promise((resolvePromise) => setTimeout(() => resolvePromise(false), 5_000)),
-    ]);
+    };
+    signalOwned('SIGTERM');
+    const stopped = await waitForOwnedExit(exited, process_group_js_1.OWNED_PROCESS_SIGNAL_GRACE_MS);
     if (!stopped && child.pid) {
+        signalOwned('SIGKILL');
+        if (!(await waitForOwnedExit(exited, Math.max(0, deadline - Date.now()))))
+            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Owned child did not exit; ownership is retained.');
+    }
+    await assertOwnedGroupAbsent(child.pid, deadline);
+}
+exports.FLEET_RUNNER_STOP_MESSAGE = 'ebk-fleet-runner-stop';
+/** A runner coordinates detached children and native cleanup. Never force-kill
+ * that coordinator on a client observation deadline. An explicit diagnostic
+ * deadline retains live ownership and reports failure instead of orphaning a
+ * writer (and falsely permitting stale-process recovery).
+ */
+async function terminateCoordinatingFleetRunner(child, runnerGeneration, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    if (!child.connected || !child.send) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet runner control channel is unavailable; live ownership is retained.');
+    }
+    if (timeoutMs !== undefined &&
+        (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000)) {
+        throw new errors_js_1.LocalDevContractError('invalid-input', 'Invalid runner stop deadline.');
+    }
+    await new Promise((resolvePromise, reject) => {
+        const settle = (error) => {
+            if (timer)
+                clearTimeout(timer);
+            child.removeListener('exit', exited);
+            child.removeListener('error', failed);
+            if (error)
+                reject(error);
+            else
+                resolvePromise();
+        };
+        const exited = () => settle();
+        const failed = (error) => settle(error);
+        child.once('exit', exited);
+        child.once('error', failed);
+        // Native SST removal may legitimately outlive a client's observation
+        // deadline. The ordinary stop retains ownership until the exact runner
+        // exits; an explicit deadline is only for bounded diagnostics/tests.
+        const timer = timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => settle(new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet runner has not completed coordinated shutdown within ${timeoutMs}ms; its process and claim remain retained.`)), timeoutMs);
         try {
-            process.kill(-child.pid, 'SIGKILL');
+            child.send?.({ type: exports.FLEET_RUNNER_STOP_MESSAGE, runnerGeneration }, (error) => {
+                if (error)
+                    settle(error);
+            });
         }
-        catch {
-            child.kill('SIGKILL');
+        catch (error) {
+            settle(error instanceof Error ? error : new Error(String(error)));
         }
-        await Promise.race([
-            exited,
-            new Promise((resolvePromise) => setTimeout(resolvePromise, 1_000)),
-        ]);
-    }
+    });
 }
 async function defaultProbe(url, signal) {
     try {
@@ -86,11 +169,13 @@ function defaultDelay(milliseconds, signal) {
             resolvePromise();
             return;
         }
-        const timer = setTimeout(resolvePromise, milliseconds);
-        signal.addEventListener('abort', () => {
+        const settle = () => {
             clearTimeout(timer);
+            signal.removeEventListener('abort', settle);
             resolvePromise();
-        }, { once: true });
+        };
+        const timer = setTimeout(settle, milliseconds);
+        signal.addEventListener('abort', settle, { once: true });
     });
 }
 class FleetProcessController {
@@ -100,7 +185,9 @@ class FleetProcessController {
     #cleanup;
     #effects;
     #healthTimeoutMs;
+    #provisioningTimeoutMs;
     #lifetime = new AbortController();
+    #startup = new AbortController();
     #logStore;
     #maxRestartAttempts;
     #name;
@@ -118,16 +205,28 @@ class FleetProcessController {
         }
         this.#adapter = options.adapter;
         this.#cleanup =
-            options.adapter.adapterVersion === 2 && options.adapter.lifecycle
+            options.adapter.adapterVersion !== 1 && options.adapter.lifecycle
                 ? 'pending'
                 : 'not-declared';
         this.#healthTimeoutMs = options.healthTimeoutMs ?? 120_000;
+        this.#provisioningTimeoutMs = options.provisioningTimeoutMs ?? 30 * 60_000;
+        for (const timeout of [
+            this.#healthTimeoutMs,
+            this.#provisioningTimeoutMs,
+        ]) {
+            if (!Number.isSafeInteger(timeout) ||
+                timeout < 1 ||
+                timeout > 2_147_483_647)
+                throw new errors_js_1.LocalDevContractError('invalid-input', 'Fleet readiness deadline is invalid.');
+        }
         this.#logStore = options.logStore;
         this.#maxRestartAttempts = options.maxRestartAttempts;
         this.#name = options.name;
         this.#onStateChange = options.onStateChange;
         this.#upstream = options.upstream;
         this.#effects = {
+            applicationStarted: effects.applicationStarted,
+            nativeDeployment: effects.nativeDeployment,
             cleanup: effects.cleanup,
             delay: effects.delay ?? defaultDelay,
             launch: effects.launch,
@@ -158,8 +257,9 @@ class FleetProcessController {
         child.stderr?.on('data', (chunk) => this.#logStore?.writeChunk(this.#name, 'stderr', attempt, chunk));
     }
     #launch() {
+        this.#startup = new AbortController();
         this.#cleanup =
-            this.#adapter.adapterVersion === 2 && this.#adapter.lifecycle
+            this.#adapter.adapterVersion !== 1 && this.#adapter.lifecycle
                 ? 'pending'
                 : 'not-declared';
         const launched = this.#effects.launch(this.#activeAttempt);
@@ -177,41 +277,80 @@ class FleetProcessController {
             this.#logStore?.writeLine(this.#name, 'stderr', launched.attempt, `Local process exited with ${signal ? `signal ${signal}` : `status ${code ?? 'unknown'}`}.`);
             if (signal || code !== 0) {
                 this.#cleanup =
-                    this.#adapter.adapterVersion === 2 && this.#adapter.lifecycle
+                    this.#adapter.adapterVersion !== 1 && this.#adapter.lifecycle
                         ? 'failed'
                         : 'not-declared';
                 this.#logStore?.writeLine(this.#name, 'stderr', launched.attempt, 'Runner cleanup did not complete cleanly; automatic restart is blocked until declared cleanup succeeds.');
                 return;
             }
-            this.#restartTask = this.#autoRestart();
+            if (!this.#startup.signal.aborted) {
+                this.#restartTask = this.#autoRestart();
+            }
         });
     }
     async #waitForReadiness() {
-        const deadline = Date.now() + this.#healthTimeoutMs;
+        const child = this.#child;
+        const signal = AbortSignal.any([
+            this.#lifetime.signal,
+            this.#startup.signal,
+        ]);
+        const provisioningDeadline = Date.now() + this.#provisioningTimeoutMs;
+        let deadline;
         const target = new URL(this.#adapter.healthPath, this.#upstream);
-        while (!this.#lifetime.signal.aborted && Date.now() < deadline) {
-            if (!this.#child) {
+        while (!signal.aborted && !this.#stopping) {
+            if (!child || this.#child !== child) {
                 throw new errors_js_1.LocalDevContractError('readiness-timeout', `${this.#name} exited before readiness.`);
             }
-            if (await this.#effects.probe(target, this.#lifetime.signal)) {
+            if (deadline === undefined) {
+                const native = await this.#effects.nativeDeployment?.(signal);
+                if (native === 'failed') {
+                    this.#transition('unavailable');
+                    throw new errors_js_1.LocalDevContractError('prerequisite-unavailable', `${this.#name} native SST deployment failed; web health cannot accept this task. Inspect ebk dev logs ${this.#name}, resolve the native diagnostic, then run ebk dev restart ${this.#name} after owned cleanup settles.`);
+                }
+                if (native === 'pending' ||
+                    (this.#effects.applicationStarted &&
+                        !this.#effects.applicationStarted())) {
+                    if (Date.now() >= provisioningDeadline) {
+                        this.#transition('unavailable');
+                        throw new errors_js_1.LocalDevContractError('provisioning-timeout', `${this.#name} native provisioning did not complete and launch the web application within ${this.#provisioningTimeoutMs}ms. Inspect ebk dev logs before retrying; owned cleanup must settle first.`);
+                    }
+                    await this.#effects.delay(500, signal);
+                    continue;
+                }
+                deadline = Date.now() + this.#healthTimeoutMs;
+            }
+            if (Date.now() >= deadline)
+                break;
+            if (await this.#effects.probe(target, signal)) {
+                if (this.#child !== child || this.#stopping || signal.aborted)
+                    continue;
                 this.#restartAttempts = 0;
                 this.#transition('ready');
                 return;
             }
-            await this.#effects.delay(500, this.#lifetime.signal);
+            await this.#effects.delay(500, signal);
         }
         this.#transition('unavailable');
+        if (signal.aborted || this.#stopping) {
+            throw new errors_js_1.LocalDevContractError('startup-interrupted', `${this.#name} startup was interrupted; owned cleanup must settle before retrying.`);
+        }
         throw new errors_js_1.LocalDevContractError('readiness-timeout', `${this.#name} did not become ready within ${this.#healthTimeoutMs}ms.`);
     }
     async #autoRestart() {
+        const signal = AbortSignal.any([
+            this.#lifetime.signal,
+            this.#startup.signal,
+        ]);
+        if (this.#stopping || signal.aborted)
+            return;
         const restart = planFleetRestart(this.#restartAttempts, this.#maxRestartAttempts);
         if (!restart.restart) {
             this.#logStore?.writeLine(this.#name, 'stderr', this.#activeAttempt, `Automatic restart stopped after ${this.#maxRestartAttempts} attempt(s).`);
             return;
         }
         this.#restartAttempts = restart.nextAttempt;
-        await this.#effects.delay(restart.delayMs, this.#lifetime.signal);
-        if (this.#stopping || this.#lifetime.signal.aborted)
+        await this.#effects.delay(restart.delayMs, signal);
+        if (this.#stopping || signal.aborted)
             return;
         this.#activeAttempt = restart.nextAttempt;
         this.#launch();
@@ -222,7 +361,10 @@ class FleetProcessController {
             if (this.#child) {
                 await this.#effects.terminate(this.#child);
             }
-            if (!this.#restartTask && !this.#lifetime.signal.aborted) {
+            if (!this.#restartTask &&
+                !this.#stopping &&
+                !this.#lifetime.signal.aborted &&
+                !this.#startup.signal.aborted) {
                 this.#restartTask = this.#autoRestart();
             }
             this.#logStore?.writeLine(this.#name, 'stderr', this.#activeAttempt, error instanceof Error ? error.message : String(error));
@@ -236,6 +378,14 @@ class FleetProcessController {
         this.#launch();
         await this.#waitForReadiness();
     }
+    /** Cancel readiness and pending automatic retries, not controller lifetime.
+     * The serialized startup rollback retains
+     * responsibility for native termination and exact cleanup before down runs. */
+    interruptStartup() {
+        if (this.#state === 'starting' ||
+            (this.#state === 'unavailable' && this.#restartTask))
+            this.#startup.abort();
+    }
     async restart() {
         if (this.#state === 'remote') {
             throw new errors_js_1.LocalDevContractError('not-running', `${this.#name} is not selected.`);
@@ -243,8 +393,13 @@ class FleetProcessController {
         this.#stopping = true;
         try {
             if (this.#child) {
-                await this.#effects.prepareRestart?.(this.#child);
-                await this.#effects.terminate(this.#child);
+                const stoppedChild = this.#child;
+                await this.#effects.prepareRestart?.(stoppedChild);
+                await this.#effects.terminate(stoppedChild);
+                if (stoppedChild.exitCode !== 0 || stoppedChild.signalCode !== null) {
+                    this.#cleanup = 'failed';
+                    throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `${this.#name} runner did not settle successfully for restart; its claim remains retained.`);
+                }
             }
             await this.#restartTask;
             this.#restartTask = undefined;
@@ -263,6 +418,7 @@ class FleetProcessController {
         if (this.#state === 'remote')
             return;
         this.#stopping = true;
+        this.#startup.abort();
         if (this.#child)
             await this.#effects.terminate(this.#child);
         await this.#restartTask;

package/src/local-dev/fleet-runner-evidence.d.ts

@@ -0,0 +1,5 @@
+import type { FleetStateRecord } from './fleet-state.js';
+import type { FleetRuntimePaths } from './runtime-paths.js';
+import { inspectFleetRunnersAbsent } from './slice-runner.js';
+/** Retire terminal diagnostics only while the supervisor still owns its state. */
+export declare function retireFleetRunnerEvidence(state: FleetStateRecord, paths: FleetRuntimePaths, effects?: Parameters<typeof inspectFleetRunnersAbsent>[2]): void;

package/src/local-dev/fleet-runner-evidence.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retireFleetRunnerEvidence = retireFleetRunnerEvidence;
+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 private_state_js_1 = require("./private-state.js");
+const slice_runner_js_1 = require("./slice-runner.js");
+/** Retire terminal diagnostics only while the supervisor still owns its state. */
+function retireFleetRunnerEvidence(state, paths, effects = {}) {
+    const security = effects.security ?? {};
+    const refuse = () => {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Fleet runner evidence cannot be retired without exact terminal ownership and process absence.');
+    };
+    if (state.slices.some(({ selected }) => selected))
+        refuse();
+    if ((0, slice_runner_js_1.inspectFleetRunnersAbsent)(state, paths, effects) !== true)
+        refuse();
+    if (!(0, node_fs_1.existsSync)(paths.runnersDirectory))
+        return;
+    (0, private_state_js_1.assertPrivatePath)(paths.runnersDirectory, 'directory', security);
+    const archive = (0, node_path_1.join)(paths.logDirectory, 'runner-evidence', (0, contract_validation_js_1.sha256Digest)(state.sessionGeneration));
+    (0, private_state_js_1.ensurePrivateDirectory)(paths.logDirectory, security);
+    (0, private_state_js_1.ensurePrivateDirectory)((0, node_path_1.join)(paths.logDirectory, 'runner-evidence'), security);
+    (0, private_state_js_1.ensurePrivateDirectory)(archive, security);
+    // A retry may encounter copies from an interrupted retirement. They must
+    // independently belong to this exact terminal generation, never be replaced.
+    if ((0, slice_runner_js_1.inspectFleetRunnersAbsent)(state, { ...paths, runnersDirectory: archive }, effects) !== true)
+        refuse();
+    const entries = (0, node_fs_1.readdirSync)(paths.runnersDirectory).sort();
+    const copies = entries.map((name) => ({
+        name,
+        contents: (0, private_state_js_1.readPrivateFile)((0, node_path_1.join)(paths.runnersDirectory, name), security),
+    }));
+    for (const { name, contents } of copies) {
+        const destination = (0, node_path_1.join)(archive, name);
+        (0, private_state_js_1.publishPrivateFileExclusive)(destination, contents, security);
+        if (!(0, private_state_js_1.readPrivateFile)(destination, security).equals(contents))
+            refuse();
+    }
+    // No authority is removed until every byte has a verified durable copy.
+    if ((0, slice_runner_js_1.inspectFleetRunnersAbsent)(state, paths, effects) !== true)
+        refuse();
+    if (JSON.stringify((0, node_fs_1.readdirSync)(paths.runnersDirectory).sort()) !==
+        JSON.stringify(entries))
+        refuse();
+    for (const { name, contents } of copies) {
+        const source = (0, node_path_1.join)(paths.runnersDirectory, name);
+        if (!(0, private_state_js_1.readPrivateFile)(source, security).equals(contents))
+            refuse();
+        (0, node_fs_1.unlinkSync)(source);
+    }
+    (0, node_fs_1.rmdirSync)(paths.runnersDirectory);
+}
+//# sourceMappingURL=fleet-runner-evidence.js.map