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

package/src/local-dev/native-completion.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readNativeDevelopmentCompletion = readNativeDevelopmentCompletion;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const errors_js_1 = require("./errors.js");
+/** Read only SST 4.17.1's current native completion. Never retain its body:
+ * links, outputs and resources can contain private application material.
+ * This observes deployment, not preview/state authority or application health. */
+async function readNativeDevelopmentCompletion(input, signal) {
+    const startedAt = Date.parse(input.startedAt);
+    if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(input.stage) ||
+        !Number.isFinite(startedAt))
+        throw new errors_js_1.LocalDevContractError('invalid-state', 'Native completion owner is invalid.');
+    const root = (0, node_fs_1.realpathSync)(input.projectRoot);
+    const directory = (0, node_path_1.join)(root, '.sst');
+    const path = (0, node_path_1.join)(directory, `${input.stage}.server`);
+    let fd;
+    let origin;
+    try {
+        if ((0, node_fs_1.lstatSync)(directory).isSymbolicLink() ||
+            (0, node_fs_1.realpathSync)(directory) !== directory)
+            throw new Error('Invalid native server directory.');
+        if ((0, node_fs_1.lstatSync)(path).isSymbolicLink())
+            throw new Error('Invalid native server file.');
+        fd = (0, node_fs_1.openSync)(path, node_fs_1.constants.O_RDONLY | (node_fs_1.constants.O_NOFOLLOW ?? 0));
+        const stat = (0, node_fs_1.fstatSync)(fd);
+        if (!stat.isFile() ||
+            stat.size > 512 ||
+            stat.nlink !== 1 ||
+            (process.platform !== 'win32' &&
+                ((stat.mode & 0o022) !== 0 || stat.uid !== process.getuid?.())))
+            throw new Error('Invalid native server file.');
+        // Native os.WriteFile is not an atomic rename. Its short empty-file
+        // creation/truncation window is not a failed deployment or ready state.
+        if (stat.size === 0)
+            return 'pending';
+        // The exact runner launch must have created this server record. A previous
+        // watcher (even one with a successful completion) cannot satisfy readiness.
+        if (stat.mtimeMs < startedAt)
+            return 'pending';
+        origin = new URL((0, node_fs_1.readFileSync)(fd, 'utf8'));
+        if (origin.protocol !== 'http:' ||
+            !['0.0.0.0', '127.0.0.1', 'localhost', '[::1]'].includes(origin.hostname) ||
+            !origin.port ||
+            origin.username ||
+            origin.password ||
+            origin.pathname !== '/' ||
+            origin.search ||
+            origin.hash)
+            throw new Error('Invalid native server origin.');
+        // Native SST records its wildcard listener address. Connect only to the
+        // loopback interface; never send an HTTP request to a wildcard address.
+        if (origin.hostname === '0.0.0.0')
+            origin.hostname = '127.0.0.1';
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT')
+            return 'pending';
+        throw new errors_js_1.LocalDevContractError('invalid-state', 'The task native SST server record is invalid. Inspect ebk dev logs before retrying.');
+    }
+    finally {
+        if (fd !== undefined)
+            (0, node_fs_1.closeSync)(fd);
+    }
+    let response;
+    try {
+        response = await fetch(new URL('/api/completed', origin), {
+            method: 'GET',
+            redirect: 'error',
+            signal: AbortSignal.any([signal, AbortSignal.timeout(2_000)]),
+        });
+    }
+    catch {
+        return 'pending';
+    }
+    if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        return 'pending';
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.length;
+            if (bytes > 8 * 1024 * 1024)
+                return 'failed';
+            chunks.push(value);
+        }
+        const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (value === null)
+            return 'pending';
+        if (typeof value !== 'object' || Array.isArray(value))
+            return 'failed';
+        const event = value;
+        if (typeof event['Old'] !== 'boolean' ||
+            typeof event['Finished'] !== 'boolean' ||
+            !(event['Errors'] === null || Array.isArray(event['Errors'])) ||
+            !(event['ImportDiffs'] === null ||
+                (typeof event['ImportDiffs'] === 'object' &&
+                    !Array.isArray(event['ImportDiffs']))))
+            return 'failed';
+        if (event['Old'])
+            return 'pending';
+        if (event['Errors']?.length ||
+            Object.keys(event['ImportDiffs'] ?? {}).length)
+            return 'failed';
+        if (!event['Finished'])
+            return 'pending';
+        if (typeof event['UpdateID'] !== 'string' ||
+            !/^[a-zA-Z0-9-]{1,128}$/.test(event['UpdateID']))
+            return 'failed';
+        return 'succeeded';
+    }
+    catch {
+        return signal.aborted ? 'pending' : 'failed';
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=native-completion.js.map

package/src/local-dev/nx-workspace.d.ts

@@ -1,10 +1,12 @@
-import { type ProjectConfiguration } from '@nx/devkit';
+import { type ProjectConfiguration, type ProjectGraph } from '@nx/devkit';
 import { type ChildProcess } from 'node:child_process';
 import { type LocalDevAdapter } from './contracts.js';
 export declare const SUPPORTED_WORKSPACE_NX_RANGE: ">=23.1.0 <24";
 export type WorkspaceProjectConfiguration = Pick<ProjectConfiguration, 'metadata' | 'root' | 'tags' | 'targets'>;
 export interface WorkspaceFleetPlan {
     adapters: ReadonlyMap<string, LocalDevAdapter>;
+    /** The authoritative Nx graph, including inferred cross-project edges. */
+    projectGraph?: ProjectGraph;
     projects: Readonly<Record<string, WorkspaceProjectConfiguration>>;
 }
 export interface WorkspaceNxRuntime {
@@ -32,7 +34,7 @@ export interface DeclaredNxTargetInvocation {
     cwd: string;
     env: NodeJS.ProcessEnv;
 }
-export declare function discoverWorkspaceFleetPlan(projects: Readonly<Record<string, WorkspaceProjectConfiguration>>): WorkspaceFleetPlan;
+export declare function discoverWorkspaceFleetPlan(projects: Readonly<Record<string, WorkspaceProjectConfiguration>>, projectGraph?: ProjectGraph): WorkspaceFleetPlan;
 export declare function selectWorkspaceSlices(plan: WorkspaceFleetPlan, selector: {
     all: boolean;
     slices: readonly string[];

package/src/local-dev/nx-workspace.js

@@ -86,7 +86,7 @@ function assertSafeCleanupClosure(projectName, cleanupTarget, projects) {
         }
     }
 }
-function discoverWorkspaceFleetPlan(projects) {
+function discoverWorkspaceFleetPlan(projects, projectGraph) {
     const entries = Object.entries(projects)
         .filter(([, project]) => projectIsSlice(project))
         .filter(([, project]) => adapterValue(project) !== undefined)
@@ -100,11 +100,11 @@ function discoverWorkspaceFleetPlan(projects) {
         if (!project?.targets?.[adapter.target]) {
             return workspaceError('invalid-adapter', `Local-dev target ${name}:${adapter.target} is not declared.`);
         }
-        if (adapter.adapterVersion === 2 && adapter.lifecycle) {
+        if (adapter.adapterVersion !== 1 && adapter.lifecycle) {
             assertSafeCleanupClosure(name, adapter.lifecycle.cleanupTarget, projects);
         }
     }
-    return { adapters, projects };
+    return { adapters, ...(projectGraph ? { projectGraph } : {}), projects };
 }
 function selectWorkspaceSlices(plan, selector) {
     const selected = selector.all
@@ -124,12 +124,12 @@ function selectWorkspaceSlices(plan, selector) {
             return workspaceError('invalid-adapter', `Selected Product Slice ${name} has no valid local-dev adapter.`);
         }
     }
-    return selected;
+    return (0, contracts_js_1.resolveFleetSliceDependencies)(plan.adapters, selected);
 }
 async function loadWorkspaceFleetPlan() {
     const graph = await (0, devkit_1.createProjectGraphAsync)();
     const configuration = (0, devkit_1.readProjectsConfigurationFromProjectGraph)(graph);
-    return discoverWorkspaceFleetPlan(configuration.projects);
+    return discoverWorkspaceFleetPlan(configuration.projects, graph);
 }
 function resolveWorkspaceNxRuntime(workspaceRoot, compatibilityRange = exports.SUPPORTED_WORKSPACE_NX_RANGE) {
     if (!(0, node_path_1.isAbsolute)(workspaceRoot)) {
@@ -180,7 +180,7 @@ function declaredCleanupTarget(plan, project) {
     if (!adapter) {
         return workspaceError('invalid-adapter', `Product Slice ${project} has no local-dev adapter.`);
     }
-    if (adapter.adapterVersion !== 2 || !adapter.lifecycle)
+    if (adapter.adapterVersion === 1 || !adapter.lifecycle)
         return undefined;
     assertSafeCleanupClosure(project, adapter.lifecycle.cleanupTarget, plan.projects);
     return {
@@ -197,6 +197,11 @@ function buildDeclaredNxTargetInvocation(runtime, declared, options) {
     const environment = {
         ...(0, personal_stage_js_1.createPersonalDevelopmentEnvironment)(options.stage, options.additionalEnvironment),
         EBK_FOUNDATION_STAGE: options.foundationStage ?? 'development',
+        // spawnDeclaredNxTarget owns the POSIX group. Native descendants must join
+        // it so shutdown proves the entire writer group absent, not just Nx.
+        ...(process.platform !== 'win32'
+            ? { EBK_GOVERNED_PROCESS_GROUP: '1' }
+            : {}),
     };
     if (options.port !== undefined) {
         if (!Number.isInteger(options.port) ||

package/src/local-dev/personal-stage.d.ts

@@ -1,17 +1,16 @@
-export declare const PERSONAL_STAGE_RESOLVER_VERSION: 1;
+export declare const PERSONAL_STAGE_RESOLVER_VERSION: 2;
 export declare const PERSONAL_STAGE_MAX_LENGTH: 36;
-export declare const PERSONAL_STAGE_IDENTITY_SOURCE: "os-account";
+export declare const PERSONAL_STAGE_IDENTITY_SOURCE: "worktree-task";
 export interface PersonalStageResolution {
     identitySource: typeof PERSONAL_STAGE_IDENTITY_SOURCE;
     resolverVersion: typeof PERSONAL_STAGE_RESOLVER_VERSION;
     stage: string;
 }
 export interface PersonalStageResolver {
-    resolve(): PersonalStageResolution;
+    resolve(workspaceRoot?: string): PersonalStageResolution;
 }
 export declare function isFrameworkPersonalStage(stage: string): boolean;
-export declare function derivePersonalStage(accountName: string): string;
-export declare function createPersonalStageResolver(readAccountName?: () => string): PersonalStageResolver;
+export declare function createPersonalStageResolver(readTaskId?: (workspaceRoot: string) => string): PersonalStageResolver;
 export declare function rejectExplicitStageArguments(arguments_: readonly string[]): void;
 export declare function createPersonalStageEnvironment(stage: string, ambient?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function stripAmbientStageAuthority(ambient: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/src/local-dev/personal-stage.js

@@ -2,21 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PERSONAL_STAGE_IDENTITY_SOURCE = exports.PERSONAL_STAGE_MAX_LENGTH = exports.PERSONAL_STAGE_RESOLVER_VERSION = void 0;
 exports.isFrameworkPersonalStage = isFrameworkPersonalStage;
-exports.derivePersonalStage = derivePersonalStage;
 exports.createPersonalStageResolver = createPersonalStageResolver;
 exports.rejectExplicitStageArguments = rejectExplicitStageArguments;
 exports.createPersonalStageEnvironment = createPersonalStageEnvironment;
 exports.stripAmbientStageAuthority = stripAmbientStageAuthority;
 exports.createPersonalDevelopmentEnvironment = createPersonalDevelopmentEnvironment;
-const node_crypto_1 = require("node:crypto");
-const node_os_1 = require("node:os");
 const stages_js_1 = require("../foundation/stages.js");
 const errors_js_1 = require("./errors.js");
-exports.PERSONAL_STAGE_RESOLVER_VERSION = 1;
+const task_identity_js_1 = require("./task-identity.js");
+exports.PERSONAL_STAGE_RESOLVER_VERSION = 2;
 exports.PERSONAL_STAGE_MAX_LENGTH = 36;
-exports.PERSONAL_STAGE_IDENTITY_SOURCE = 'os-account';
-const PREFIX = 'personal-';
-const LOSSY_DIGEST_LENGTH = 8;
+exports.PERSONAL_STAGE_IDENTITY_SOURCE = 'worktree-task';
 const COMPETING_STAGE_VARIABLES = [
     'EBK_STAGE',
     'EBK_CONSUMER_STAGE',
@@ -40,57 +36,13 @@ const AMBIENT_AWS_AUTHORITY_VARIABLES = [
 function isFrameworkPersonalStage(stage) {
     return (0, stages_js_1.isPersonalStage)(stage);
 }
-function normalizeAccountName(value) {
-    return value
-        .normalize('NFKD')
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .replace(/-+/g, '-');
-}
-function shortIdentityDigest(value) {
-    return (0, node_crypto_1.createHash)('sha256')
-        .update(value, 'utf8')
-        .digest('hex')
-        .slice(0, LOSSY_DIGEST_LENGTH);
-}
-function derivePersonalStage(accountName) {
-    if (typeof accountName !== 'string' ||
-        accountName.length === 0 ||
-        accountName !== accountName.trim()) {
-        throw new errors_js_1.LocalDevContractError('personal-identity-unavailable', 'The operating-system account name is unavailable or unsafe.');
-    }
-    const normalized = normalizeAccountName(accountName);
-    if (!normalized) {
-        throw new errors_js_1.LocalDevContractError('personal-identity-unavailable', 'The operating-system account name cannot form a personal stage.');
-    }
-    const maximumBodyLength = exports.PERSONAL_STAGE_MAX_LENGTH - PREFIX.length;
-    const lossless = normalized === accountName && normalized.length <= maximumBodyLength;
-    const body = lossless
-        ? normalized
-        : `${normalized
-            .slice(0, maximumBodyLength - LOSSY_DIGEST_LENGTH - 1)
-            .replace(/-+$/g, '')}-${shortIdentityDigest(accountName)}`;
-    const stage = `${PREFIX}${body}`;
-    if (!isFrameworkPersonalStage(stage)) {
-        throw new errors_js_1.LocalDevContractError('personal-identity-unavailable', 'The operating-system account name cannot form a bounded personal stage.');
-    }
-    return stage;
-}
-function createPersonalStageResolver(readAccountName = () => (0, node_os_1.userInfo)().username) {
+function createPersonalStageResolver(readTaskId = (workspaceRoot) => (0, task_identity_js_1.resolveTaskIdentity)(workspaceRoot).taskId) {
     return {
-        resolve() {
-            let accountName;
-            try {
-                accountName = readAccountName();
-            }
-            catch {
-                throw new errors_js_1.LocalDevContractError('personal-identity-unavailable', 'The operating-system account identity could not be read.');
-            }
+        resolve(workspaceRoot = process.cwd()) {
             return {
                 identitySource: exports.PERSONAL_STAGE_IDENTITY_SOURCE,
                 resolverVersion: exports.PERSONAL_STAGE_RESOLVER_VERSION,
-                stage: derivePersonalStage(accountName),
+                stage: (0, task_identity_js_1.taskStage)(readTaskId(workspaceRoot)),
             };
         },
     };

package/src/local-dev/port-claims.d.ts

@@ -0,0 +1,13 @@
+import { type PrivateStateSecurity } from './private-state.js';
+import { type FleetProcessIdentity } from './fleet-lock.js';
+/** Process-lifetime exclusion between local Fleet supervisors. A claim does
+ * not attest HTTP health and is not permission to terminate any other process.
+ * Unknown or hard-kill remnants stay reserved, never reclaimed speculatively. */
+export declare function createFleetPortClaims(directory: string, owner: {
+    fleetId: string;
+    sessionGeneration: string;
+    process: FleetProcessIdentity;
+}, security?: PrivateStateSecurity): {
+    claim(port: number): boolean;
+    release(): void;
+};

package/src/local-dev/port-claims.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFleetPortClaims = createFleetPortClaims;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const errors_js_1 = require("./errors.js");
+const private_state_js_1 = require("./private-state.js");
+const fleet_lock_js_1 = require("./fleet-lock.js");
+/** Process-lifetime exclusion between local Fleet supervisors. A claim does
+ * not attest HTTP health and is not permission to terminate any other process.
+ * Unknown or hard-kill remnants stay reserved, never reclaimed speculatively. */
+function createFleetPortClaims(directory, owner, security = {}) {
+    (0, fleet_lock_js_1.validateFleetProcessIdentity)(owner.process);
+    const claimed = new Map();
+    return {
+        claim(port) {
+            if (!Number.isInteger(port) || port < 1 || port > 65_535)
+                throw new errors_js_1.LocalDevContractError('invalid-input', 'Invalid Fleet port claim.');
+            if (claimed.has(port))
+                return false;
+            const contents = `${JSON.stringify({ schemaVersion: 1, ...owner, port })}\n`;
+            if (!(0, private_state_js_1.publishPrivateFileExclusive)((0, node_path_1.join)(directory, `${port}.json`), contents, security))
+                return false;
+            claimed.set(port, contents);
+            return true;
+        },
+        release() {
+            const failed = [];
+            for (const [port, expected] of [...claimed].reverse()) {
+                try {
+                    const path = (0, node_path_1.join)(directory, `${port}.json`);
+                    if ((0, private_state_js_1.readPrivateFile)(path, security).toString('utf8') !== expected)
+                        throw new Error('Port claim changed');
+                    (0, node_fs_1.unlinkSync)(path);
+                    claimed.delete(port);
+                }
+                catch {
+                    failed.push(port);
+                }
+            }
+            if (failed.length)
+                throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet port ownership changed or could not be released for ${failed.join(', ')}. Retained claims require inspection; no foreign claim was removed.`);
+        },
+    };
+}
+//# sourceMappingURL=port-claims.js.map

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

@@ -1,10 +1,22 @@
 export declare const FLEET_PORT_RANGE: {
-    readonly first: 41000;
-    readonly last: 51999;
+    readonly first: 16000;
+    readonly last: 29999;
 };
+export interface TcpPortRange {
+    first: number;
+    last: number;
+}
+/** Read only. Never change sysctl/netsh or assume a custom range is default. */
+export declare function readAutomaticTcpPortRange(effects?: {
+    platform?: NodeJS.Platform;
+    read?: (path: string) => string;
+    execute?: (command: string, args: string[]) => string;
+}): TcpPortRange;
 export declare function preferredFleetPort(key: string): number;
 export declare function canBindLoopbackPort(port: number): Promise<boolean>;
 export declare function allocateFleetPort(key: string, options?: {
+    ephemeralRange?: TcpPortRange;
     isAvailable?: (port: number) => Promise<boolean>;
+    claim?: (port: number) => boolean;
     reserved?: ReadonlySet<number>;
 }): Promise<number>;

package/src/local-dev/ports.js

@@ -1,12 +1,80 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FLEET_PORT_RANGE = void 0;
+exports.readAutomaticTcpPortRange = readAutomaticTcpPortRange;
 exports.preferredFleetPort = preferredFleetPort;
 exports.canBindLoopbackPort = canBindLoopbackPort;
 exports.allocateFleetPort = allocateFleetPort;
 const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
 const node_net_1 = require("node:net");
-exports.FLEET_PORT_RANGE = { first: 41000, last: 51999 };
+const errors_js_1 = require("./errors.js");
+// Leave the usual automatic TCP client ranges to the OS. Still inspect the
+// actual host range: probing alone cannot protect a delayed native web bind
+// from an outbound connection opened during SST provisioning.
+exports.FLEET_PORT_RANGE = { first: 16000, last: 29999 };
+function validRange(range) {
+    return (Number.isInteger(range.first) &&
+        Number.isInteger(range.last) &&
+        range.first > 0 &&
+        range.first <= range.last &&
+        range.last <= 65_535);
+}
+/** Read only. Never change sysctl/netsh or assume a custom range is default. */
+function readAutomaticTcpPortRange(effects = {}) {
+    const platform = effects.platform ?? process.platform;
+    const execute = effects.execute ??
+        ((command, args) => (0, node_child_process_1.execFileSync)(command, args, {
+            encoding: 'utf8',
+            timeout: 5_000,
+            maxBuffer: 8_192,
+            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);
+        }
+        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;
+    }
+    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.');
+    }
+}
 function preferredFleetPort(key) {
     const digest = (0, node_crypto_1.createHash)('sha256').update(key).digest();
     const size = exports.FLEET_PORT_RANGE.last - exports.FLEET_PORT_RANGE.first + 1;
@@ -26,14 +94,21 @@ async function canBindLoopbackPort(port) {
 }
 async function allocateFleetPort(key, options = {}) {
     const isAvailable = options.isAvailable ?? canBindLoopbackPort;
+    const ephemeral = options.ephemeralRange ?? readAutomaticTcpPortRange();
+    if (!validRange(ephemeral))
+        throw new errors_js_1.LocalDevContractError('invalid-input', 'Invalid automatic TCP port range.');
     const first = preferredFleetPort(key);
     const size = exports.FLEET_PORT_RANGE.last - exports.FLEET_PORT_RANGE.first + 1;
     for (let offset = 0; offset < size; offset += 1) {
         const port = exports.FLEET_PORT_RANGE.first +
             ((first - exports.FLEET_PORT_RANGE.first + offset) % size);
-        if (!options.reserved?.has(port) && (await isAvailable(port)))
+        if (port >= ephemeral.first && port <= ephemeral.last)
+            continue;
+        if (!options.reserved?.has(port) &&
+            (await isAvailable(port)) &&
+            (!options.claim || options.claim(port)))
             return port;
     }
-    throw new Error(`No loopback port is available in ${exports.FLEET_PORT_RANGE.first}-${exports.FLEET_PORT_RANGE.last}.`);
+    throw new Error(`No unclaimed loopback port outside the automatic TCP client range is available in ${exports.FLEET_PORT_RANGE.first}-${exports.FLEET_PORT_RANGE.last}. Inspect owned Fleet sessions before retrying; no foreign listener or claim was removed.`);
 }
 //# sourceMappingURL=ports.js.map

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

@@ -5,13 +5,24 @@ export type PrivatePathKind = 'directory' | 'file';
 export interface WindowsPrivateAcl {
     assert(path: string, kind: PrivatePathKind): void;
     harden(path: string, kind: PrivatePathKind): void;
+    /** Harden several paths in one platform invocation; falls back to
+     * `harden` per path when absent. */
+    hardenAll?(paths: readonly string[], kind: PrivatePathKind): void;
 }
 export interface PrivateStateSecurity {
     platform?: NodeJS.Platform;
     windowsAcl?: WindowsPrivateAcl;
 }
+/** @internal */
+export declare function hardenPrivatePath(path: string, kind: PrivatePathKind, security?: PrivateStateSecurity): void;
 export declare function assertPrivatePath(path: string, kind: PrivatePathKind, security?: PrivateStateSecurity): void;
 export declare function ensurePrivateDirectory(path: string, security?: PrivateStateSecurity): void;
 export declare function createPrivateFileExclusive(path: string, contents: string | Buffer, security?: PrivateStateSecurity): boolean;
+/** Publish complete private bytes without replacing a concurrent winner.
+ * Unlike a lock file, a persistent data record must never be readable empty. */
+export declare function publishPrivateFileExclusive(path: string, contents: string | Buffer, security?: PrivateStateSecurity): boolean;
 export declare function atomicWritePrivateFile(path: string, contents: string | Buffer, security?: PrivateStateSecurity): void;
+/** Write a caller-bounded private artifact without relaxing the default
+ * private-state limit for any existing authority or control file. */
+export declare function atomicWritePrivateFileWithMaximumBytes(path: string, contents: string | Buffer, maximumBytes: number, security?: PrivateStateSecurity): void;
 export declare function readPrivateFile(path: string, security?: PrivateStateSecurity): Buffer;