@empire-builder-kit/nx 1.0.0-rc.43 → 1.0.0-rc.45

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveDevelopmentRouter = resolveDevelopmentRouter;
+exports.createFleetSliceRunnerEffects = createFleetSliceRunnerEffects;
 exports.startFleetRuntime = startFleetRuntime;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
@@ -71,6 +72,111 @@ async function resolveDevelopmentRouter(request) {
         throw new errors_js_1.LocalDevContractError('foundation-unavailable', `Development Foundation discovery failed: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/** One Slice's Fleet process effects: a coordinating runner per launch,
+ * generation-bound restart and quiescence, and cleanup whose retry output
+ * joins the Slice log store. startFleetRuntime and the real-runner
+ * quiescence specs share this wiring, so a dropped effect fails those specs. */
+function createFleetSliceRunnerEffects(input, daemon = {}) {
+    const { logStore, name } = input;
+    let activeRunner;
+    let activeAttempt = 0;
+    const runnersByChild = new WeakMap();
+    const project = input.projects[name];
+    const nativeProjectRoot = project?.targets?.[input.adapter.target]?.executor ===
+        '@empire-builder-kit/nx:dev'
+        ? (0, node_path_1.join)(input.workspaceRealpath, project.root)
+        : undefined;
+    const effects = {
+        ...(nativeProjectRoot
+            ? {
+                nativeDeployment: async (signal) => activeRunner
+                    ? (0, native_completion_js_1.readNativeDevelopmentCompletion)({
+                        projectRoot: nativeProjectRoot,
+                        stage: input.stage,
+                        startedAt: activeRunner.request.createdAt,
+                    }, signal)
+                    : 'pending',
+                applicationStarted: () => Boolean(activeRunner &&
+                    (0, fleet_web_start_js_1.hasFleetWebStarted)(activeRunner.requestPath, activeRunner.request)),
+            }
+            : {}),
+        cleanup: async () => {
+            if (!activeRunner) {
+                throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice runner state for ${name} is missing.`);
+            }
+            try {
+                (0, slice_runner_js_1.assertFleetSliceRunnerCleanup)(activeRunner.statePath, activeRunner.request);
+            }
+            catch {
+                // A runner that already exited (or whose own cleanup failed)
+                // is retried by a separate runner; keep its output in the
+                // same Slice log as the in-runner cleanup.
+                const attempt = activeAttempt;
+                try {
+                    await (0, slice_runner_js_1.retryFleetSliceRunnerCleanup)(activeRunner, {
+                        ...daemon,
+                        output: (stream, chunk) => {
+                            logStore.writeChunk(name, stream, attempt, chunk);
+                        },
+                    });
+                }
+                finally {
+                    logStore.flush(name, undefined, attempt);
+                }
+                (0, slice_runner_js_1.assertFleetSliceRunnerCleanup)(activeRunner.statePath, activeRunner.request);
+            }
+            await (0, slice_runner_js_1.recoverFleetSliceRunnerCleanupsForSlices)({
+                fleetId: activeRunner.request.fleetId,
+                sessionGeneration: activeRunner.request.sessionGeneration,
+            }, [name], input.runtimePaths, daemon);
+        },
+        launch: (attempt) => {
+            activeAttempt = attempt;
+            activeRunner = (0, slice_runner_js_1.launchFleetSliceRunner)({
+                origin: input.origin,
+                parent: input.parent,
+                port: input.port,
+                runnerGeneration: `${input.sessionGeneration}:${name}:${attempt}:${(0, node_crypto_1.randomUUID)()}`,
+                runtimePaths: input.runtimePaths,
+                sessionGeneration: input.sessionGeneration,
+                slice: name,
+                startupPath: input.startupPath,
+                workspaceRealpath: input.workspaceRealpath,
+            }, daemon);
+            runnersByChild.set(activeRunner.child, activeRunner);
+            return { attempt, child: activeRunner.child };
+        },
+        prepareRestart: async () => {
+            if (!activeRunner) {
+                throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice runner state for ${name} is missing.`);
+            }
+            (0, slice_runner_js_1.requestFleetSliceRunnerRestart)(activeRunner);
+        },
+        // The runner stops its writer and stays alive with pending
+        // cleanup authority; a later stop runs declared cleanup in that
+        // runner, so its output reaches this Slice's log store.
+        quiesce: async (child) => {
+            if (!activeRunner || activeRunner.child !== child) {
+                throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet runner ownership changed before quiescence.');
+            }
+            await (0, fleet_process_js_1.quiesceCoordinatingFleetRunner)(child, activeRunner.request.runnerGeneration);
+        },
+        runnerGeneration: () => activeRunner?.request.runnerGeneration,
+        startTargetExit: (child) => {
+            const runner = runnersByChild.get(child);
+            return runner
+                ? (0, slice_runner_js_1.readFleetSliceRunnerState)(runner.statePath).childExit
+                : undefined;
+        },
+        terminate: async (child) => {
+            if (!activeRunner || activeRunner.child !== child) {
+                throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet runner ownership changed before shutdown.');
+            }
+            await (0, fleet_process_js_1.terminateCoordinatingFleetRunner)(child, activeRunner.request.runnerGeneration);
+        },
+    };
+    return { activeRunner: () => activeRunner, effects };
+}
 async function startFleetRuntime(startupPath, dependencies = {}) {
     const request = (0, fleet_startup_js_1.readFleetStartupRequest)(startupPath);
     if ((0, node_fs_1.realpathSync)(request.workspaceRealpath) !== request.workspaceRealpath) {
@@ -220,75 +326,27 @@ async function startFleetRuntime(startupPath, dependencies = {}) {
             adapters: plan.adapters,
             allocatePort: async (name) => ports.get(name),
             fleetId,
-            processFactory: ({ adapter, name, onStateChange, upstream }) => {
-                let activeRunner;
-                return new fleet_process_js_1.FleetProcessController({
-                    adapter,
-                    logStore,
-                    maxRestartAttempts: request.context.maxRestartAttempts,
-                    name,
-                    onStateChange,
-                    upstream,
-                }, {
-                    ...(plan.projects[name]?.targets?.[adapter.target]?.executor ===
-                        '@empire-builder-kit/nx:dev'
-                        ? {
-                            nativeDeployment: async (signal) => activeRunner
-                                ? (0, native_completion_js_1.readNativeDevelopmentCompletion)({
-                                    projectRoot: (0, node_path_1.join)(request.workspaceRealpath, plan.projects[name].root),
-                                    stage: request.identity.stage,
-                                    startedAt: activeRunner.request.createdAt,
-                                }, signal)
-                                : 'pending',
-                            applicationStarted: () => Boolean(activeRunner &&
-                                (0, fleet_web_start_js_1.hasFleetWebStarted)(activeRunner.requestPath, activeRunner.request)),
-                        }
-                        : {}),
-                    cleanup: async () => {
-                        if (!activeRunner) {
-                            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice runner state for ${name} is missing.`);
-                        }
-                        try {
-                            (0, slice_runner_js_1.assertFleetSliceRunnerCleanup)(activeRunner.statePath, activeRunner.request);
-                        }
-                        catch {
-                            await (0, slice_runner_js_1.retryFleetSliceRunnerCleanup)(activeRunner);
-                            (0, slice_runner_js_1.assertFleetSliceRunnerCleanup)(activeRunner.statePath, activeRunner.request);
-                        }
-                        await (0, slice_runner_js_1.recoverFleetSliceRunnerCleanupsForSlices)({
-                            fleetId: activeRunner.request.fleetId,
-                            sessionGeneration: activeRunner.request.sessionGeneration,
-                        }, [name], runtimePaths);
-                    },
-                    launch: (attempt) => {
-                        activeRunner = (0, slice_runner_js_1.launchFleetSliceRunner)({
-                            origin,
-                            parent: processOwner,
-                            port: ports.get(name),
-                            runnerGeneration: `${request.sessionGeneration}:${name}:${attempt}:${(0, node_crypto_1.randomUUID)()}`,
-                            runtimePaths,
-                            sessionGeneration: request.sessionGeneration,
-                            slice: name,
-                            startupPath,
-                            workspaceRealpath: request.workspaceRealpath,
-                        });
-                        return { attempt, child: activeRunner.child };
-                    },
-                    prepareRestart: async () => {
-                        if (!activeRunner) {
-                            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice runner state for ${name} is missing.`);
-                        }
-                        (0, slice_runner_js_1.requestFleetSliceRunnerRestart)(activeRunner);
-                    },
-                    runnerGeneration: () => activeRunner?.request.runnerGeneration,
-                    terminate: async (child) => {
-                        if (!activeRunner || activeRunner.child !== child) {
-                            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Fleet runner ownership changed before shutdown.');
-                        }
-                        await (0, fleet_process_js_1.terminateCoordinatingFleetRunner)(child, activeRunner.request.runnerGeneration);
-                    },
-                });
-            },
+            processFactory: ({ adapter, name, onStateChange, upstream }) => new fleet_process_js_1.FleetProcessController({
+                adapter,
+                logStore,
+                maxRestartAttempts: request.context.maxRestartAttempts,
+                name,
+                onStateChange,
+                upstream,
+            }, createFleetSliceRunnerEffects({
+                adapter,
+                logStore,
+                name,
+                origin,
+                parent: processOwner,
+                port: ports.get(name),
+                projects: plan.projects,
+                runtimePaths,
+                sessionGeneration: request.sessionGeneration,
+                stage: request.identity.stage,
+                startupPath,
+                workspaceRealpath: request.workspaceRealpath,
+            }).effects),
             proxy: proxyHost,
             proxyPort,
             routes,

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

@@ -8,6 +8,7 @@ export interface FleetSliceProcess {
     readonly runnerGeneration?: string;
     readonly state: FleetProcessRouteState;
     interruptStartup?(): void;
+    quiesce(): Promise<void>;
     restart(): Promise<void>;
     start(): Promise<void>;
     stop(options: {

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

@@ -8,6 +8,12 @@ const slice_claim_js_1 = require("./slice-claim.js");
 function sessionError(classification, message) {
     throw new errors_js_1.LocalDevContractError(classification, message);
 }
+function startupFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return error instanceof errors_js_1.LocalDevContractError
+        ? `${error.classification}: ${message}`
+        : message;
+}
 class FleetSession {
     routes;
     #allocatePort;
@@ -79,6 +85,29 @@ class FleetSession {
         this.#operation = result.then(() => undefined, () => undefined);
         return result;
     }
+    async #quiesce(names) {
+        const failures = [];
+        // The complete selection was dependency-validated before this phase.
+        // Keep every claim selected until all writers stop, even if one fails.
+        for (const name of names) {
+            const process = this.#processes.get(name);
+            if (!process)
+                continue;
+            const route = this.#route(name);
+            try {
+                await process.quiesce();
+            }
+            catch (error) {
+                this.#cleanupStates.set(name, 'failed');
+                failures.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            finally {
+                route.selected = true;
+                route.state = 'unavailable';
+            }
+        }
+        return failures;
+    }
     up(names) {
         return this.#serialized(async () => {
             const requested = (0, contracts_js_1.resolveFleetSliceOperation)(this.#adapters, 'up', names, this.selectedSlices());
@@ -119,11 +148,14 @@ class FleetSession {
                 }
             }
             catch (error) {
-                const cleanupFailures = [];
+                const quiesceFailures = await this.#quiesce([...changed].reverse());
+                const cleanupFailures = [...quiesceFailures];
                 const releasable = [];
                 for (const name of [...changed].reverse()) {
                     const process = this.#processes.get(name);
                     if (process) {
+                        if (quiesceFailures.length > 0)
+                            continue;
                         try {
                             (0, contracts_js_1.resolveFleetSliceOperation)(this.#adapters, 'down', [name], this.selectedSlices());
                             await process.stop({ cleanup: true });
@@ -161,7 +193,9 @@ class FleetSession {
                     }
                 }
                 if (cleanupFailures.length > 0) {
-                    return sessionError('cleanup-incomplete', `Fleet startup failed and generation-owned rollback was incomplete: ${cleanupFailures.join('; ')}`);
+                    // The start failure leads: the persisted failure message is
+                    // bounded, and the cause must survive the rollback report.
+                    return sessionError('cleanup-incomplete', `Fleet startup failed (${startupFailure(error)}) and generation-owned rollback was incomplete: ${cleanupFailures.join('; ')}`);
                 }
                 throw error;
             }
@@ -214,10 +248,15 @@ class FleetSession {
             const results = [];
             const cleanupFailures = [];
             const ordered = (0, contracts_js_1.resolveFleetSliceOperation)(this.#adapters, 'down', names, this.selectedSlices());
+            const previousStates = new Map(ordered.map((name) => [name, this.#route(name).state]));
+            const quiesceFailures = await this.#quiesce(ordered);
+            if (quiesceFailures.length > 0) {
+                return sessionError('cleanup-incomplete', `Fleet writers did not quiesce; no cloud cleanup ran and all claims were retained: ${quiesceFailures.join('; ')}`);
+            }
             for (const name of ordered) {
                 const route = this.#route(name);
                 const process = this.#processes.get(name);
-                const previousState = route.state;
+                const previousState = previousStates.get(name);
                 if (!route.selected || !process) {
                     results.push({
                         changed: false,

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

@@ -5,6 +5,9 @@ import { type PrivateStateSecurity } from './private-state.js';
 import type { FleetRouterSource } from './fleet-configuration.js';
 export declare const FLEET_STATE_SCHEMA_VERSION: 1;
 export declare const FLEET_STATE_FILE: "control-state.json";
+/** A persisted operation failure cause stays one bounded line, so the full
+ * state (up to 128 operations) remains inside the CLI result bound. */
+export declare const FLEET_OPERATION_FAILURE_MESSAGE_MAX_LENGTH = 1024;
 export declare const FLEET_ROUTE_STATES: readonly ["remote", "starting", "ready", "unavailable"];
 export declare const FLEET_CLEANUP_STATES: readonly ["not-declared", "pending", "succeeded", "failed"];
 export declare const FLEET_OPERATION_STATES: readonly ["accepted", "running", "succeeded", "failed"];
@@ -28,6 +31,8 @@ export interface FleetOperationStateRecord {
     command: FleetMutationCommand;
     completedAt?: string;
     failureClassification?: LocalDevFailureClassification;
+    /** Bounded, redacted, single-line cause of a failed operation. */
+    failureMessage?: string;
     id: string;
     idempotencyKey: string;
     slices: string[];

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FLEET_OPERATION_STATES = exports.FLEET_CLEANUP_STATES = exports.FLEET_ROUTE_STATES = exports.FLEET_STATE_FILE = exports.FLEET_STATE_SCHEMA_VERSION = void 0;
+exports.FLEET_OPERATION_STATES = exports.FLEET_CLEANUP_STATES = exports.FLEET_ROUTE_STATES = exports.FLEET_OPERATION_FAILURE_MESSAGE_MAX_LENGTH = exports.FLEET_STATE_FILE = exports.FLEET_STATE_SCHEMA_VERSION = void 0;
 exports.fleetOwnedSliceNames = fleetOwnedSliceNames;
 exports.fleetOwnsStartingSlice = fleetOwnsStartingSlice;
 exports.validateFleetStateRecord = validateFleetStateRecord;
@@ -18,6 +18,9 @@ const private_state_js_1 = require("./private-state.js");
 const personal_stage_js_1 = require("./personal-stage.js");
 exports.FLEET_STATE_SCHEMA_VERSION = 1;
 exports.FLEET_STATE_FILE = 'control-state.json';
+/** A persisted operation failure cause stays one bounded line, so the full
+ * state (up to 128 operations) remains inside the CLI result bound. */
+exports.FLEET_OPERATION_FAILURE_MESSAGE_MAX_LENGTH = 1_024;
 exports.FLEET_ROUTE_STATES = [
     'remote',
     'starting',
@@ -120,7 +123,7 @@ function validateSliceState(value) {
 }
 function validateOperation(value) {
     (0, contract_validation_js_1.assertRecord)(value, 'Fleet operation state');
-    (0, contract_validation_js_1.assertExactProperties)(value, ['acceptedAt', 'command', 'id', 'idempotencyKey', 'slices', 'state'], ['completedAt', 'failureClassification'], 'Fleet operation state');
+    (0, contract_validation_js_1.assertExactProperties)(value, ['acceptedAt', 'command', 'id', 'idempotencyKey', 'slices', 'state'], ['completedAt', 'failureClassification', 'failureMessage'], 'Fleet operation state');
     if (value.command !== 'up' &&
         value.command !== 'down' &&
         value.command !== 'restart') {
@@ -157,6 +160,12 @@ function validateOperation(value) {
         }
         result.failureClassification = classification;
     }
+    if (value.failureMessage !== undefined) {
+        if (result.state !== 'failed') {
+            return stateError('Fleet operation failureMessage is valid only for a failed operation.');
+        }
+        result.failureMessage = (0, contract_validation_js_1.requireBoundedString)(value.failureMessage, 'Fleet operation failureMessage', { maximumLength: exports.FLEET_OPERATION_FAILURE_MESSAGE_MAX_LENGTH });
+    }
     const terminal = result.state === 'succeeded' || result.state === 'failed';
     if (terminal !== (result.completedAt !== undefined)) {
         return stateError('Fleet operation terminal state and completedAt must agree.');

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

@@ -42,6 +42,12 @@ export interface FleetSupervisorOptions {
     security?: PrivateStateSecurity;
     shutdownGraceMs?: number;
 }
+/** Failed operations beyond this many keep their classification only. */
+export declare const FLEET_RETAINED_FAILURE_MESSAGES = 8;
+/** The persisted cause is one redacted, bounded line. Whitespace collapses
+ * before redaction because the terminal-safety strip deletes line breaks and
+ * the state validator refuses every control character. */
+export declare function fleetOperationFailureMessage(error: unknown): string | undefined;
 export declare class FleetSupervisor {
     #private;
     constructor(options: FleetSupervisorOptions, effects?: FleetSupervisorEffects);

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FleetSupervisor = void 0;
+exports.FleetSupervisor = exports.FLEET_RETAINED_FAILURE_MESSAGES = void 0;
+exports.fleetOperationFailureMessage = fleetOperationFailureMessage;
 const node_crypto_1 = require("node:crypto");
 const contracts_js_1 = require("./contracts.js");
 const node_fs_1 = require("node:fs");
@@ -8,6 +9,7 @@ const control_contract_js_1 = require("./control-contract.js");
 const errors_js_1 = require("./errors.js");
 const fleet_ipc_js_1 = require("./fleet-ipc.js");
 const fleet_lock_js_1 = require("./fleet-lock.js");
+const fleet_logs_js_1 = require("./fleet-logs.js");
 const fleet_state_js_1 = require("./fleet-state.js");
 const private_state_js_1 = require("./private-state.js");
 const process_identity_js_1 = require("./process-identity.js");
@@ -33,6 +35,49 @@ function failureClassification(error) {
         ? error.classification
         : 'internal-error';
 }
+/** Failed operations beyond this many keep their classification only. */
+exports.FLEET_RETAINED_FAILURE_MESSAGES = 8;
+/** The persisted cause is one redacted, bounded line. Whitespace collapses
+ * before redaction because the terminal-safety strip deletes line breaks and
+ * the state validator refuses every control character. */
+function fleetOperationFailureMessage(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const line = (0, fleet_logs_js_1.redactLocalLogText)(raw.replace(/\s+/gu, ' '))
+        // The persisted line must carry no control character of any kind.
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/gu, ' ')
+        .replace(/ {2,}/gu, ' ')
+        .trim();
+    if (line.length === 0)
+        return undefined;
+    if (line.length <= fleet_state_js_1.FLEET_OPERATION_FAILURE_MESSAGE_MAX_LENGTH)
+        return line;
+    let bounded = '';
+    for (const character of line) {
+        if (bounded.length + character.length >
+            fleet_state_js_1.FLEET_OPERATION_FAILURE_MESSAGE_MAX_LENGTH - 1)
+            break;
+        bounded += character;
+    }
+    return `${bounded.trimEnd()}\u2026`;
+}
+function retainRecentFailureMessages(operations) {
+    let retained = 0;
+    return operations
+        .slice()
+        .reverse()
+        .map((operation) => {
+        if (operation.failureMessage === undefined)
+            return operation;
+        retained += 1;
+        if (retained <= exports.FLEET_RETAINED_FAILURE_MESSAGES)
+            return operation;
+        const classificationOnly = { ...operation };
+        delete classificationOnly.failureMessage;
+        return classificationOnly;
+    })
+        .reverse();
+}
 class FleetSupervisor {
     #closed = false;
     #adapters;
@@ -316,12 +361,15 @@ class FleetSupervisor {
         }
         catch (error) {
             this.#shutdownAfterOperations.delete(operation.id);
+            const failureMessage = fleetOperationFailureMessage(error);
             this.#state.operations[index] = {
                 ...this.#state.operations[index],
                 completedAt: this.#effects.now().toISOString(),
                 failureClassification: failureClassification(error),
+                ...(failureMessage === undefined ? {} : { failureMessage }),
                 state: 'failed',
             };
+            this.#state.operations = retainRecentFailureMessages(this.#state.operations);
             this.#persistState();
         }
     }

package/src/local-dev/ports.d.ts

@@ -6,11 +6,21 @@ export interface TcpPortRange {
     first: number;
     last: number;
 }
-/** Read only. Never change sysctl/netsh or assume a custom range is default. */
+/**
+ * Read only. Never change sysctl/netsh or assume a custom range is default.
+ *
+ * A supported platform is read at most three times, pausing 250 ms x attempt
+ * between reads (250 ms, then 500 ms). Each native command read is bounded by a
+ * 5 s timeout, so the worst-case failure on Windows or macOS takes about
+ * 3 x 5 s + 250 ms + 500 ms = 15.75 s before the
+ * `prerequisite-unavailable` error. An unsupported platform fails at once,
+ * without a read or a pause, and the error names it as unsupported.
+ */
 export declare function readAutomaticTcpPortRange(effects?: {
     platform?: NodeJS.Platform;
     read?: (path: string) => string;
     execute?: (command: string, args: string[]) => string;
+    pause?: (milliseconds: number) => void;
 }): TcpPortRange;
 export declare function preferredFleetPort(key: string): number;
 export declare function canBindLoopbackPort(port: number): Promise<boolean>;

package/src/local-dev/ports.js

@@ -21,7 +21,33 @@ function validRange(range) {
         range.first <= range.last &&
         range.last <= 65_535);
 }
-/** Read only. Never change sysctl/netsh or assume a custom range is default. */
+/**
+ * Bounded attempts for the host range read. A loaded Windows host can fail a
+ * single netsh read transiently; three attempts with a short pause absorb that
+ * without hiding a persistent failure. Module-private: the specs observe the
+ * bound through the injected effects, and the public ./local-dev subpath does
+ * not export it.
+ */
+const AUTOMATIC_TCP_PORT_RANGE_READ_ATTEMPTS = 3;
+const AUTOMATIC_TCP_PORT_RANGE_RETRY_PAUSE_MS = 250;
+const SUPPORTED_RANGE_PLATFORMS = [
+    'linux',
+    'darwin',
+    'win32',
+];
+function pauseSynchronously(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+/**
+ * Read only. Never change sysctl/netsh or assume a custom range is default.
+ *
+ * A supported platform is read at most three times, pausing 250 ms x attempt
+ * between reads (250 ms, then 500 ms). Each native command read is bounded by a
+ * 5 s timeout, so the worst-case failure on Windows or macOS takes about
+ * 3 x 5 s + 250 ms + 500 ms = 15.75 s before the
+ * `prerequisite-unavailable` error. An unsupported platform fails at once,
+ * without a read or a pause, and the error names it as unsupported.
+ */
 function readAutomaticTcpPortRange(effects = {}) {
     const platform = effects.platform ?? process.platform;
     const execute = effects.execute ??
@@ -32,48 +58,62 @@ function readAutomaticTcpPortRange(effects = {}) {
             windowsHide: true,
             stdio: ['ignore', 'pipe', 'pipe'],
         }));
-    try {
-        let values;
-        if (platform === 'linux') {
-            const text = (effects.read ?? ((path) => (0, node_fs_1.readFileSync)(path, 'utf8')))('/proc/sys/net/ipv4/ip_local_port_range');
-            if (!/^\s*\d+\s+\d+\s*$/.test(text))
-                throw new Error('Invalid range');
-            values = text.trim().split(/\s+/).map(Number);
-        }
-        else if (platform === 'darwin') {
-            const text = execute('/usr/sbin/sysctl', [
-                '-n',
-                'net.inet.ip.portrange.first',
-                'net.inet.ip.portrange.last',
-            ]);
-            if (!/^\s*\d+\s+\d+\s*$/.test(text))
-                throw new Error('Invalid range');
-            values = text.trim().split(/\s+/).map(Number);
+    const read = effects.read ?? ((path) => (0, node_fs_1.readFileSync)(path, 'utf8'));
+    const pause = effects.pause ?? pauseSynchronously;
+    // An unsupported platform is not transient: fail before any read.
+    if (!SUPPORTED_RANGE_PLATFORMS.includes(platform)) {
+        throw new errors_js_1.LocalDevContractError('prerequisite-unavailable', `The host platform ${platform} is not supported for the automatic TCP client-port range read; ebk dev up supports Linux, macOS and Windows. No network setting was changed.`);
+    }
+    const attempts = AUTOMATIC_TCP_PORT_RANGE_READ_ATTEMPTS;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            return readAutomaticTcpPortRangeOnce(platform, read, execute);
         }
-        else if (platform === 'win32') {
-            const text = execute('netsh.exe', [
-                'int',
-                'ipv4',
-                'show',
-                'dynamicport',
-                'tcp',
-            ]);
-            // Labels are localized; the two numeric colon-delimited values are not.
-            values = [...text.matchAll(/:\s*(\d+)\s*$/gm)].map((match) => Number(match[1]));
-            if (values.length !== 2 || values[1] < 1)
-                throw new Error('Invalid range');
-            values[1] = values[0] + values[1] - 1;
+        catch {
+            if (attempt < attempts)
+                pause(AUTOMATIC_TCP_PORT_RANGE_RETRY_PAUSE_MS * attempt);
         }
-        else
-            throw new Error('Unsupported platform');
-        const range = { first: values[0], last: values[1] };
-        if (!validRange(range))
+    }
+    throw new errors_js_1.LocalDevContractError('prerequisite-unavailable', `Cannot read the host automatic TCP client-port range after ${attempts} ${attempts === 1 ? 'attempt' : 'attempts'}. Verify the native network configuration is readable before retrying ebk dev up; no network setting was changed.`);
+}
+function readAutomaticTcpPortRangeOnce(platform, read, execute) {
+    let values;
+    if (platform === 'linux') {
+        const text = read('/proc/sys/net/ipv4/ip_local_port_range');
+        if (!/^\s*\d+\s+\d+\s*$/.test(text))
+            throw new Error('Invalid range');
+        values = text.trim().split(/\s+/).map(Number);
+    }
+    else if (platform === 'darwin') {
+        const text = execute('/usr/sbin/sysctl', [
+            '-n',
+            'net.inet.ip.portrange.first',
+            'net.inet.ip.portrange.last',
+        ]);
+        if (!/^\s*\d+\s+\d+\s*$/.test(text))
             throw new Error('Invalid range');
-        return range;
+        values = text.trim().split(/\s+/).map(Number);
     }
-    catch {
-        throw new errors_js_1.LocalDevContractError('prerequisite-unavailable', 'Cannot read the host automatic TCP client-port range. Verify the native network configuration is readable before retrying ebk dev up; no network setting was changed.');
+    else if (platform === 'win32') {
+        const text = execute('netsh.exe', [
+            'int',
+            'ipv4',
+            'show',
+            'dynamicport',
+            'tcp',
+        ]);
+        // Labels are localized; the two numeric colon-delimited values are not.
+        values = [...text.matchAll(/:\s*(\d+)\s*$/gm)].map((match) => Number(match[1]));
+        if (values.length !== 2 || values[1] < 1)
+            throw new Error('Invalid range');
+        values[1] = values[0] + values[1] - 1;
     }
+    else
+        throw new Error('Unsupported platform');
+    const range = { first: values[0], last: values[1] };
+    if (!validRange(range))
+        throw new Error('Invalid range');
+    return range;
 }
 function preferredFleetPort(key) {
     const digest = (0, node_crypto_1.createHash)('sha256').update(key).digest();