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

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

@@ -5,6 +5,7 @@ exports.fleetSliceRunnerRequiresCleanup = fleetSliceRunnerRequiresCleanup;
 exports.validateFleetSliceRunnerRequest = validateFleetSliceRunnerRequest;
 exports.validateFleetSliceRunnerState = validateFleetSliceRunnerState;
 exports.fleetSliceRunnerPaths = fleetSliceRunnerPaths;
+exports.validateFleetSliceRunnerRestartRequest = validateFleetSliceRunnerRestartRequest;
 exports.requestFleetSliceRunnerRestart = requestFleetSliceRunnerRestart;
 exports.writeFleetSliceRunnerState = writeFleetSliceRunnerState;
 exports.readFleetSliceRunnerState = readFleetSliceRunnerState;
@@ -24,6 +25,7 @@ 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_state_js_1 = require("./fleet-state.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");
@@ -31,6 +33,7 @@ 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");
+const fleet_web_start_js_1 = require("./fleet-web-start.js");
 exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION = 1;
 exports.FLEET_SLICE_RUNNER_RESTART_SCHEMA_VERSION = 1;
 exports.DEFAULT_RUNNER_PARENT_GRACE_MS = 15_000;
@@ -266,7 +269,7 @@ function launchFleetSliceRunner(input, effects = {}) {
                 EBK_FLEET_SLICE_RUNNER_REQUEST: paths.request,
             }),
             shell: false,
-            stdio: 'pipe',
+            stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
             windowsHide: true,
         });
         return {
@@ -289,16 +292,49 @@ function childExit(child) {
         child.once('exit', (code) => resolvePromise(code));
     });
 }
-async function runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, stage, workspaceRealpath, spawnTarget) {
+async function runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, stage, workspaceRealpath, spawnTarget, observeChild, stopSignal, terminate = fleet_process_js_1.terminateOwnedChild) {
     if (!cleanupTarget)
         return;
+    if (stopSignal?.aborted)
+        throw new Error('Fleet Slice cleanup was interrupted before execution.');
     const cleanup = spawnTarget(runtime, cleanupTarget, {
         additionalEnvironment: childEnvironment,
         stage,
         stdio: 'inherit',
         workspaceRoot: workspaceRealpath,
     });
-    const code = await childExit(cleanup);
+    const finished = childExit(cleanup);
+    let interruption;
+    let rejectInterruption = () => undefined;
+    const interruptionFailed = new Promise((_resolve, reject) => {
+        rejectInterruption = reject;
+    });
+    void interruptionFailed.catch(() => undefined);
+    const interrupt = () => {
+        interruption ??= terminate(cleanup);
+        // Observe rejection immediately while the child may still be running;
+        // the awaited promise below still makes the eventual cleanup fail.
+        void interruption.catch(rejectInterruption);
+    };
+    stopSignal?.addEventListener('abort', interrupt, { once: true });
+    let code;
+    try {
+        observeChild(cleanup);
+        code = await Promise.race([finished, interruptionFailed]);
+        await interruption;
+        if (!cleanup.pid)
+            throw new Error('Cleanup child PID is unavailable.');
+        await (0, fleet_process_js_1.assertOwnedGroupAbsent)(cleanup.pid);
+    }
+    catch (error) {
+        await terminate(cleanup);
+        throw error;
+    }
+    finally {
+        stopSignal?.removeEventListener('abort', interrupt);
+    }
+    if (stopSignal?.aborted)
+        throw new Error('Fleet Slice cleanup was interrupted; ownership remains retained.');
     if (code !== 0) {
         throw new Error(`${cleanupTarget.project}:${cleanupTarget.target} exited with status ${code ?? 'unknown'}.`);
     }
@@ -336,7 +372,7 @@ function runnerParentStatus(request, options = {}) {
         ? 'lost'
         : 'ambiguous';
 }
-async function runFleetSliceRunner(requestPath, options = {}) {
+async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
     const security = options.security ?? {};
     const now = options.now ?? (() => new Date());
     const request = readFleetSliceRunnerRequest(requestPath, security);
@@ -371,7 +407,18 @@ async function runFleetSliceRunner(requestPath, options = {}) {
         EBK_SST_DEV_MODE: startup.sstMode,
     });
     const spawnTarget = options.spawnTarget ?? nx_workspace_js_1.spawnDeclaredNxTarget;
-    const terminate = options.terminate ?? fleet_process_js_1.terminateOwnedChild;
+    const ownedChildren = new Map();
+    const identifyChild = (child) => {
+        if (!child.pid)
+            throw new Error('Slice child PID is unavailable.');
+        const identity = (options.processIdentity ?? process_identity_js_1.captureProcessIdentity)(child.pid);
+        ownedChildren.set(child, identity);
+        return identity;
+    };
+    const terminate = options.terminate ??
+        ((child) => (0, fleet_process_js_1.terminateOwnedChild)(child, ownedChildren.get(child)));
+    if (stopSignal.aborted)
+        throw new Error('Fleet Slice runner stopped before child execution.');
     if ((0, node_fs_1.existsSync)(paths.state)) {
         let previous = readFleetSliceRunnerState(paths.state, security);
         if (previous.fleetId !== request.fleetId ||
@@ -386,12 +433,19 @@ async function runFleetSliceRunner(requestPath, options = {}) {
             return runnerError('Fleet Slice cleanup retry requires exact prior runner and child absence.');
         }
         if (previous.cleanup === 'succeeded') {
+            (0, fleet_web_start_js_1.retireFleetWebStarted)(requestPath, request, security);
+            if (previous.child)
+                await (0, fleet_process_js_1.assertOwnedGroupAbsent)(previous.child.pid);
             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;
         }
+        // The old Nx group must be gone before its only retained child identity
+        // can be replaced by this retry's cleanup child.
+        if (previous.child)
+            await (0, fleet_process_js_1.assertOwnedGroupAbsent)(previous.child.pid);
         previous = writeFleetSliceRunnerState(paths.state, {
             cleanup: 'running',
             fleetId: request.fleetId,
@@ -403,7 +457,16 @@ async function runFleetSliceRunner(requestPath, options = {}) {
             updatedAt: now().toISOString(),
         }, security);
         try {
-            await runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, startup.identity.stage, request.workspaceRealpath, spawnTarget);
+            await runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, startup.identity.stage, request.workspaceRealpath, spawnTarget, (cleanup) => {
+                if (!cleanup.pid)
+                    throw new Error('Cleanup child did not expose a PID.');
+                previous = writeFleetSliceRunnerState(paths.state, {
+                    ...previous,
+                    child: identifyChild(cleanup),
+                    updatedAt: now().toISOString(),
+                }, security);
+            }, stopSignal, terminate);
+            (0, fleet_web_start_js_1.retireFleetWebStarted)(requestPath, request, security);
             writeFleetSliceRunnerState(paths.state, {
                 ...previous,
                 cleanup: 'succeeded',
@@ -447,7 +510,7 @@ async function runFleetSliceRunner(requestPath, options = {}) {
             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),
+            child: identifyChild(child),
             updatedAt: now().toISOString(),
         }, security);
     }
@@ -473,6 +536,9 @@ async function runFleetSliceRunner(requestPath, options = {}) {
                 try {
                     if (terminateChild)
                         await terminate(child);
+                    if (!child.pid)
+                        throw new Error('Slice child PID is unavailable.');
+                    await (0, fleet_process_js_1.assertOwnedGroupAbsent)(child.pid);
                     state = writeFleetSliceRunnerState(paths.state, {
                         ...state,
                         cleanup: 'pending',
@@ -494,7 +560,19 @@ async function runFleetSliceRunner(requestPath, options = {}) {
             try {
                 if (terminateChild)
                     await terminate(child);
-                await runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, startup.identity.stage, request.workspaceRealpath, spawnTarget);
+                if (!child.pid)
+                    throw new Error('Slice child PID is unavailable.');
+                await (0, fleet_process_js_1.assertOwnedGroupAbsent)(child.pid);
+                await runDeclaredCleanupTarget(cleanupTarget, runtime, childEnvironment, startup.identity.stage, request.workspaceRealpath, spawnTarget, (cleanup) => {
+                    if (!cleanup.pid)
+                        throw new Error('Cleanup child did not expose a PID.');
+                    state = writeFleetSliceRunnerState(paths.state, {
+                        ...state,
+                        child: identifyChild(cleanup),
+                        updatedAt: now().toISOString(),
+                    }, security);
+                }, undefined, terminate);
+                (0, fleet_web_start_js_1.retireFleetWebStarted)(requestPath, request, security);
                 state = writeFleetSliceRunnerState(paths.state, {
                     ...state,
                     cleanup: 'succeeded',
@@ -518,15 +596,15 @@ async function runFleetSliceRunner(requestPath, options = {}) {
         })();
         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);
+    stopSignal.addEventListener('abort', terminateSignal, { once: true });
+    if (stopSignal.aborted)
+        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.
@@ -545,11 +623,36 @@ async function runFleetSliceRunner(requestPath, options = {}) {
         interval.unref();
     });
     const result = await Promise.race([childFinished, parentLost]);
-    process.removeListener('SIGINT', interrupt);
-    process.removeListener('SIGTERM', terminateSignal);
+    stopSignal.removeEventListener('abort', terminateSignal);
     return (result ??
         (await finalize(true, fleetSliceRunnerRequiresCleanup('termination'))));
 }
+async function runFleetSliceRunner(requestPath, options = {}) {
+    const request = readFleetSliceRunnerRequest(requestPath, options.security);
+    const stop = new AbortController();
+    const interrupt = () => stop.abort();
+    const message = (value) => {
+        if (value &&
+            typeof value === 'object' &&
+            Object.keys(value).sort().join(',') === 'runnerGeneration,type' &&
+            'type' in value &&
+            value.type === fleet_process_js_1.FLEET_RUNNER_STOP_MESSAGE &&
+            'runnerGeneration' in value &&
+            value.runnerGeneration === request.runnerGeneration)
+            interrupt();
+    };
+    process.once('SIGINT', interrupt);
+    process.once('SIGTERM', interrupt);
+    process.on('message', message);
+    try {
+        return await runFleetSliceRunnerCore(requestPath, options, stop.signal);
+    }
+    finally {
+        process.removeListener('SIGINT', interrupt);
+        process.removeListener('SIGTERM', interrupt);
+        process.removeListener('message', message);
+    }
+}
 function assertFleetSliceRunnerCleanup(statePath, expected, security = {}) {
     const state = readFleetSliceRunnerState(statePath, security);
     if (state.cleanup !== 'succeeded' ||
@@ -580,6 +683,8 @@ async function retryFleetSliceRunnerCleanup(launched, effects = {}) {
         (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.child)
+        await (0, fleet_process_js_1.assertOwnedGroupAbsent)(state.child.pid);
     if (state.cleanup === 'succeeded') {
         if ((0, node_fs_1.existsSync)(launched.requestPath))
             (0, node_fs_1.unlinkSync)(launched.requestPath);
@@ -608,28 +713,13 @@ async function retryFleetSliceRunnerCleanup(launched, effects = {}) {
             EBK_FLEET_SLICE_RUNNER_REQUEST: launched.requestPath,
         }),
         shell: false,
-        stdio: 'ignore',
+        stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
         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;
+    // Client observation deadlines do not cancel a native cleanup operation.
+    // Explicit signals and generation-bound IPC still stop the coordinator;
+    // only its terminal exit and validated receipt can complete this retry.
+    const code = await childExit(child);
     if (code !== 0) {
         throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice cleanup retry exited with status ${code ?? 'unknown'}; its claim remains retained.`);
     }
@@ -639,14 +729,68 @@ async function retryFleetSliceRunnerCleanup(launched, effects = {}) {
         (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));
+    // Inspect the complete retained namespace before starting any cleanup. A
+    // supervisor can die after acquisition but before persisting route selection.
+    inspectRetainedFleetRunners(state, paths, effects.security ?? {});
+    const selected = new Set((0, fleet_state_js_1.fleetOwnedSliceNames)(state));
+    if (!(0, node_fs_1.existsSync)(paths.runnersDirectory) &&
+        !state.slices.some((slice) => slice.selected))
+        return;
     return recoverFleetSliceRunnerCleanupsForSlices({
         fleetId: state.fleetId,
         sessionGeneration: state.sessionGeneration,
     }, selected, paths, effects);
 }
+function inspectRetainedFleetRunners(state, paths, security) {
+    const owned = new Set((0, fleet_state_js_1.fleetOwnedSliceNames)(state));
+    if (!(0, node_fs_1.existsSync)(paths.runnersDirectory))
+        return [];
+    const entries = (0, node_fs_1.readdirSync)(paths.runnersDirectory).sort();
+    const states = [];
+    for (const name of entries) {
+        if (!/^[a-z0-9][a-z0-9-]{0,62}-[a-f0-9]{20}\.(state|request|restart|web-start)\.json$/.test(name)) {
+            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Unsupported retained runner entry; no cleanup authority can be inferred.');
+        }
+        const statePath = (0, node_path_1.join)(paths.runnersDirectory, name.replace(/\.(request|restart|web-start)\.json$/, '.state.json'));
+        const runner = readFleetSliceRunnerState(statePath, security);
+        const slice = state.slices.find((candidate) => candidate.name === runner.slice);
+        const settled = slice?.cleanup === 'succeeded' && runner.cleanup === 'succeeded';
+        if (runner.fleetId !== state.fleetId ||
+            runner.sessionGeneration !== state.sessionGeneration ||
+            (!owned.has(runner.slice) && !settled) ||
+            fleetSliceRunnerPaths(paths.runnersDirectory, runner.slice, runner.runnerGeneration).state !== statePath ||
+            (!settled &&
+                !state.slices.some((slice) => slice.name === runner.slice && slice.selected) &&
+                !(0, fleet_state_js_1.fleetOwnsStartingSlice)(state, runner.slice, runner.updatedAt))) {
+            throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Retained runner does not belong to selected or starting state of this exact Fleet generation.');
+        }
+        if (name.endsWith('.request.json')) {
+            const request = readFleetSliceRunnerRequest((0, node_path_1.join)(paths.runnersDirectory, name), security);
+            if (request.fleetId !== state.fleetId ||
+                request.sessionGeneration !== state.sessionGeneration ||
+                request.slice !== runner.slice ||
+                request.runnerGeneration !== runner.runnerGeneration ||
+                request.parent.pid !== state.supervisor.pid ||
+                request.parent.processIdentity !== state.supervisor.processIdentity ||
+                request.parent.startedAt !== state.supervisor.startedAt ||
+                request.workspaceRealpath !== state.workspaceRealpath ||
+                request.startupPath !== paths.startup ||
+                request.heartbeatPath !== paths.heartbeat ||
+                (!state.slices.some((slice) => slice.name === runner.slice && slice.selected) &&
+                    !(0, fleet_state_js_1.fleetOwnsStartingSlice)(state, runner.slice, request.createdAt))) {
+                throw new errors_js_1.LocalDevContractError('cleanup-incomplete', 'Retained runner request does not prove exact supervisor and workspace ownership.');
+            }
+        }
+        if (name.endsWith('.state.json'))
+            states.push(runner);
+        if (name.endsWith('.web-start.json')) {
+            const requestPath = statePath.replace(/\.state\.json$/, '.request.json');
+            const request = readFleetSliceRunnerRequest(requestPath, security);
+            (0, fleet_web_start_js_1.hasFleetWebStarted)(requestPath, request, security);
+        }
+    }
+    return states;
+}
 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)
@@ -679,36 +823,27 @@ 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))) {
+        runnerStates = inspectRetainedFleetRunners(state, paths, effects.security ?? {});
+        if ((0, node_fs_1.existsSync)(paths.runnersDirectory) &&
+            (0, node_fs_1.readdirSync)(paths.runnersDirectory).some((name) => !name.endsWith('.state.json')))
             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 runner of runnerStates) {
+        if (runner.cleanup !== 'succeeded' ||
+            probe(runner.runner) !== 'absent' ||
+            (runner.child && probe(runner.child) !== 'absent'))
+            return 'ambiguous';
+    }
     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;
 }

package/src/local-dev/task-attachment.d.ts

@@ -0,0 +1,17 @@
+import { inventoryFleets, inventorySliceClaims } from './fleet-inventory.js';
+import type { LocalDevContext } from './local-context.js';
+import { verifyTaskEnvironment } from './task-authority.js';
+import { type TaskIdentity } from './task-identity.js';
+export interface TaskAttachmentInput {
+    appData: string;
+    context: LocalDevContext;
+    taskId: string;
+    workspaceName: string;
+    workspaceRoot: string;
+}
+export interface TaskAttachmentEffects {
+    inventory?: typeof inventoryFleets;
+    inventoryClaims?: typeof inventorySliceClaims;
+    verify?: typeof verifyTaskEnvironment;
+}
+export declare function attachStoppedTask(input: TaskAttachmentInput, effects?: TaskAttachmentEffects): Promise<TaskIdentity>;

package/src/local-dev/task-attachment.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachStoppedTask = attachStoppedTask;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const errors_js_1 = require("./errors.js");
+const fleet_inventory_js_1 = require("./fleet-inventory.js");
+const fleet_lock_js_1 = require("./fleet-lock.js");
+const identity_js_1 = require("./identity.js");
+const process_identity_js_1 = require("./process-identity.js");
+const runtime_paths_js_1 = require("./runtime-paths.js");
+const task_authority_js_1 = require("./task-authority.js");
+const task_identity_js_1 = require("./task-identity.js");
+async function attachStoppedTask(input, effects = {}) {
+    const workspaceRoot = (0, node_fs_1.realpathSync)(input.workspaceRoot);
+    const stage = (0, task_identity_js_1.taskStage)((0, task_identity_js_1.requireTaskId)(input.taskId));
+    const fleetId = (0, identity_js_1.createFleetId)({
+        checkoutPath: workspaceRoot,
+        stage,
+        workspaceName: input.workspaceName,
+    });
+    const environment = await (effects.verify ?? task_authority_js_1.verifyTaskEnvironment)(workspaceRoot, input.context);
+    const currentTask = (0, task_identity_js_1.resolveTaskIdentityForAttachment)(workspaceRoot, input.taskId);
+    const currentFleetId = (0, identity_js_1.createFleetId)({
+        checkoutPath: workspaceRoot,
+        stage: (0, task_identity_js_1.taskStage)(currentTask.taskId),
+        workspaceName: input.workspaceName,
+    });
+    const inventory = await (effects.inventory ?? fleet_inventory_js_1.inventoryFleets)({
+        appData: input.appData,
+    });
+    const blocked = inventory.filter((record) => record.fleetId === fleetId ||
+        record.fleetId === currentFleetId ||
+        record.checkout === workspaceRoot);
+    if (blocked.length > 0) {
+        throw new errors_js_1.LocalDevContractError('fleet-in-use', 'Task reattachment requires stopped, fully cleaned fleet ownership in both worktrees. Run ebk dev down --all, then inspect ebk dev ps and use ebk dev prune for its exact stale fleet before attaching.');
+    }
+    // Lock both task identities: a target-worktree startup must not race the
+    // pointer transfer after inventory, even when it is starting a different task.
+    const leases = [];
+    try {
+        for (const lockedId of [...new Set([fleetId, currentFleetId])].sort()) {
+            const lockedPaths = (0, runtime_paths_js_1.fleetRuntimePaths)(lockedId, input.appData);
+            const lease = (0, fleet_lock_js_1.acquireFleetLock)(lockedPaths.lock, {
+                fleetId: lockedId,
+                owner: (0, process_identity_js_1.captureProcessIdentity)(),
+                sessionGeneration: (0, node_crypto_1.randomUUID)(),
+            });
+            if (lease.kind !== 'acquired') {
+                throw new errors_js_1.LocalDevContractError('fleet-in-use', 'Another process owns this task. Stop its fleet and retry explicit attachment.');
+            }
+            leases.push({ paths: lockedPaths, record: lease.record });
+            if ((0, node_fs_1.existsSync)(lockedPaths.state) || (0, node_fs_1.existsSync)(lockedPaths.capability)) {
+                throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Residual fleet state prevents reattachment. Inspect ebk dev ps and recover its exact stale fleet first.');
+            }
+        }
+        const claims = await (effects.inventoryClaims ?? fleet_inventory_js_1.inventorySliceClaims)({
+            appData: input.appData,
+        });
+        if (claims.some((claim) => claim.fleetId === fleetId ||
+            claim.fleetId === currentFleetId ||
+            !claim.fleetId)) {
+            throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Retained Slice claims prevent task reattachment. Inspect ebk dev ps and recover their exact Fleet before transferring ownership.');
+        }
+        return (0, task_identity_js_1.attachTaskIdentity)(workspaceRoot, input.taskId, environment);
+    }
+    finally {
+        for (const lease of leases.reverse()) {
+            (0, fleet_lock_js_1.releaseFleetLock)(lease.paths.lock, lease.record);
+        }
+    }
+}
+//# sourceMappingURL=task-attachment.js.map

package/src/local-dev/task-authority.d.ts

@@ -0,0 +1,10 @@
+import { assertWorkspaceStageOwnershipForWorkspace } from '../workspace-deployment/ownership.js';
+import { resolveCurrentAwsAccountId } from './environment-inspector.js';
+import type { LocalDevContext } from './local-context.js';
+import { type TaskEnvironment } from './task-identity.js';
+export interface TaskAuthorityEffects {
+    account?: typeof resolveCurrentAwsAccountId;
+    ownership?: typeof assertWorkspaceStageOwnershipForWorkspace;
+}
+export declare function verifyTaskEnvironment(workspaceRoot: string, context: LocalDevContext, effects?: TaskAuthorityEffects): Promise<TaskEnvironment>;
+export declare function bindCurrentTaskEnvironment(workspaceRoot: string, context: LocalDevContext): Promise<void>;

package/src/local-dev/task-authority.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyTaskEnvironment = verifyTaskEnvironment;
+exports.bindCurrentTaskEnvironment = bindCurrentTaskEnvironment;
+const ownership_js_1 = require("../workspace-deployment/ownership.js");
+const environment_inspector_js_1 = require("./environment-inspector.js");
+const errors_js_1 = require("./errors.js");
+const task_identity_js_1 = require("./task-identity.js");
+async function verifyTaskEnvironment(workspaceRoot, context, effects = {}) {
+    const [accountId, ownership] = await Promise.all([
+        (effects.account ?? environment_inspector_js_1.resolveCurrentAwsAccountId)(context, AbortSignal.timeout(15_000)),
+        (effects.ownership ?? ownership_js_1.assertWorkspaceStageOwnershipForWorkspace)(workspaceRoot, 'development', { profile: context.profile }),
+    ]);
+    if (accountId !== ownership.accountId ||
+        context.region !== ownership.region) {
+        throw new errors_js_1.LocalDevContractError('configuration-mismatch', 'Task development caller must match the workspace-owned development account and Region. Run ebk dev configure with its development profile and Region.');
+    }
+    return {
+        accountId,
+        region: ownership.region,
+        workspaceDeploymentId: ownership.expectedOwner.workspaceDeploymentId,
+    };
+}
+async function bindCurrentTaskEnvironment(workspaceRoot, context) {
+    (0, task_identity_js_1.bindTaskEnvironment)(workspaceRoot, await verifyTaskEnvironment(workspaceRoot, context));
+}
+//# sourceMappingURL=task-authority.js.map

package/src/local-dev/task-identity.d.ts

@@ -0,0 +1,33 @@
+import { type PrivateStateSecurity } from './private-state.js';
+export declare const TASK_ID_PATTERN: RegExp;
+export declare const TASK_IDENTITY_SCHEMA_VERSION: 1;
+export interface TaskIdentity {
+    schemaVersion: typeof TASK_IDENTITY_SCHEMA_VERSION;
+    taskId: string;
+    workspaceRealpath: string;
+}
+export interface TaskEnvironment {
+    accountId: string;
+    region: string;
+    workspaceDeploymentId: string;
+}
+/** Only explicit attachment may inspect a moved pointer without changing it. */
+export declare function resolveTaskIdentityForAttachment(workspaceRoot: string, requestedTaskId: string, security?: PrivateStateSecurity): TaskIdentity;
+/** Cleanup requires an already-bound task; it may not establish new authority. */
+export declare function assertCurrentTaskEnvironment(workspaceRoot: string, environment: TaskEnvironment, security?: PrivateStateSecurity): TaskIdentity;
+/** The caller must establish this tuple through current STS and workspace ownership checks. */
+export declare function bindTaskEnvironment(workspaceRoot: string, environment: TaskEnvironment, security?: PrivateStateSecurity): void;
+/** Called while holding the existing task fleet lock, after proving no runner or cleanup remains. */
+export declare function attachTaskIdentity(workspaceRoot: string, taskId: string, environment: TaskEnvironment, security?: PrivateStateSecurity): TaskIdentity;
+export declare function requireTaskId(value: unknown): string;
+export declare function taskStage(taskId: string): string;
+/** Git query budget: hosted Windows runners answer slowly under child contention
+ * (eight simultaneous resolvers exceeded 5 s in PR #113 diagnostic 34737069666). */
+export declare const WORKTREE_GIT_QUERY_TIMEOUT_MS: Readonly<{
+    default: 5000;
+    win32: 30000;
+}>;
+export declare function resolveWorktreeGitDirectory(workspaceRoot: string): string;
+export declare function taskIdentityPath(workspaceRoot: string): string;
+export declare function validateTaskIdentity(value: unknown): TaskIdentity;
+export declare function resolveTaskIdentity(workspaceRoot: string, security?: PrivateStateSecurity): TaskIdentity;