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

package/src/local-dev/slice-runner.d.ts

@@ -23,8 +23,16 @@ export interface FleetSliceRunnerRequest {
     startupPath: string;
     workspaceRealpath: string;
 }
+/** The Slice start target's own exit when it ended without owned
+ * termination: the cause behind a runner that then exits cleanly. */
+export interface FleetSliceRunnerChildExit {
+    at: string;
+    code: number | null;
+    signal: string | null;
+}
 export interface FleetSliceRunnerState {
     child?: FleetProcessIdentity;
+    childExit?: FleetSliceRunnerChildExit;
     cleanup: 'failed' | 'pending' | 'running' | 'succeeded';
     failure?: string;
     fleetId: string;
@@ -91,6 +99,13 @@ export declare function runnerParentStatus(request: FleetSliceRunnerRequest, opt
     processProbe?: ProcessIdentityProbe;
     security?: PrivateStateSecurity;
 }): 'ambiguous' | 'lost' | 'present';
+interface FleetSliceRunnerControl {
+    acknowledgeQuiesce(): void;
+    /** Registers the quiesce handler and replays a request that arrived while
+     * the runner was still reading its request. */
+    onQuiesce(handler: () => void): void;
+    stopSignal: AbortSignal;
+}
 declare function runFleetSliceRunnerCore(requestPath: string, options: {
     loadPlan?: typeof loadWorkspaceFleetPlan;
     monitorIntervalMs?: number;
@@ -102,11 +117,14 @@ declare function runFleetSliceRunnerCore(requestPath: string, options: {
     security?: PrivateStateSecurity;
     spawnTarget?: typeof spawnDeclaredNxTarget;
     terminate?: typeof terminateOwnedChild;
-}, stopSignal: AbortSignal): Promise<0 | 1>;
+}, control: FleetSliceRunnerControl): Promise<0 | 1>;
 export declare function runFleetSliceRunner(requestPath: string, options?: Parameters<typeof runFleetSliceRunnerCore>[1]): Promise<0 | 1>;
 export declare function assertFleetSliceRunnerCleanup(statePath: string, expected: Pick<FleetSliceRunnerRequest, 'fleetId' | 'runnerGeneration' | 'sessionGeneration' | 'slice'>, security?: PrivateStateSecurity): void;
 export declare function retryFleetSliceRunnerCleanup(launched: Pick<LaunchedFleetSliceRunner, 'request' | 'requestPath' | 'statePath'>, effects?: {
     daemonPath?: string;
+    /** Receives the retry runner's output, including its declared cleanup
+     * target's, for the Slice log store. Without it the output is inherited. */
+    output?: (stream: 'stderr' | 'stdout', chunk: Buffer | string) => void;
     processProbe?: (identity: FleetProcessIdentity) => ProcessIdentityProbe;
     security?: PrivateStateSecurity;
     spawn?: typeof spawn;

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

@@ -122,7 +122,7 @@ function validateFleetSliceRunnerState(value) {
         'sessionGeneration',
         'slice',
         'updatedAt',
-    ], ['child', 'failure'], 'Fleet Slice runner state');
+    ], ['child', 'childExit', 'failure'], 'Fleet Slice runner state');
     if (value.schemaVersion !== exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION ||
         !['failed', 'pending', 'running', 'succeeded'].includes(String(value.cleanup))) {
         return runnerError('Fleet Slice runner state is invalid.');
@@ -140,11 +140,35 @@ function validateFleetSliceRunnerState(value) {
     if (value.child !== undefined) {
         state.child = processIdentity(value.child, 'Fleet Slice runner state child');
     }
+    if (value.childExit !== undefined) {
+        state.childExit = validateRunnerChildExit(value.childExit);
+    }
     if (value.failure !== undefined) {
         state.failure = (0, contract_validation_js_1.requireBoundedString)(value.failure, 'Fleet Slice runner state failure', { maximumLength: 1_024 });
     }
     return state;
 }
+function validateRunnerChildExit(value) {
+    (0, contract_validation_js_1.assertRecord)(value, 'Fleet Slice runner child exit');
+    (0, contract_validation_js_1.assertExactProperties)(value, ['at', 'code', 'signal'], [], 'Fleet Slice runner child exit');
+    const code = value.code === null
+        ? null
+        : (0, contract_validation_js_1.requireInteger)(value.code, 'Fleet Slice runner child exit code', -2_147_483_648, 4_294_967_295);
+    const signal = value.signal === null
+        ? null
+        : (0, contract_validation_js_1.requireBoundedString)(value.signal, 'Fleet Slice runner child signal', {
+            maximumLength: 32,
+            pattern: /^SIG[A-Z0-9]+$/,
+        });
+    if ((code === null) === (signal === null)) {
+        return runnerError('Fleet Slice runner child exit must carry exactly one of status or signal.');
+    }
+    return {
+        at: (0, contract_validation_js_1.requireIsoTimestamp)(value.at, 'Fleet Slice runner child exit at'),
+        code,
+        signal,
+    };
+}
 function runnerStem(slice, runnerGeneration) {
     return `${(0, fleet_lock_js_1.validateFleetIdentitySlug)(slice, 'Fleet Slice runner Slice')}-${(0, contract_validation_js_1.sha256Digest)({ runnerGeneration: generation(runnerGeneration, 'runner generation') }).slice(0, 20)}`;
 }
@@ -184,8 +208,17 @@ function validateFleetSliceRunnerRestartRequest(value) {
         slice: (0, fleet_lock_js_1.validateFleetIdentitySlug)(value.slice, 'Fleet Slice runner restart Slice'),
     };
 }
+/** A runner publishes its state once its Nx plan is loaded, or earlier when
+ * quiescence reaches it during the load. Name that condition instead of
+ * surfacing the private-file check's missing-file error. */
+function readPublishedFleetSliceRunnerState(statePath, security, consequence) {
+    if (!(0, node_fs_1.existsSync)(statePath)) {
+        throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice runner has not published its state; it is still loading its Nx plan or exited before starting. ${consequence}`);
+    }
+    return readFleetSliceRunnerState(statePath, security);
+}
 function requestFleetSliceRunnerRestart(launched, effects = {}) {
-    const state = readFleetSliceRunnerState(launched.statePath, effects.security ?? {});
+    const state = readPublishedFleetSliceRunnerState(launched.statePath, effects.security ?? {}, 'Restart is refused until the Slice reports starting.');
     if (state.fleetId !== launched.request.fleetId ||
         state.runnerGeneration !== launched.request.runnerGeneration ||
         state.sessionGeneration !== launched.request.sessionGeneration ||
@@ -372,7 +405,8 @@ function runnerParentStatus(request, options = {}) {
         ? 'lost'
         : 'ambiguous';
 }
-async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
+async function runFleetSliceRunnerCore(requestPath, options = {}, control) {
+    const { stopSignal } = control;
     const security = options.security ?? {};
     const now = options.now ?? (() => new Date());
     const request = readFleetSliceRunnerRequest(requestPath, security);
@@ -382,6 +416,47 @@ async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
         startup.workspaceRealpath !== request.workspaceRealpath) {
         return runnerError('Fleet Slice runner request does not match its startup authority.');
     }
+    const paths = fleetSliceRunnerPaths((0, node_path_1.join)((0, node_path_1.dirname)(request.startupPath), 'runners'), request.slice, request.runnerGeneration);
+    // A runner launched over retained state is a cleanup retry and never
+    // starts a writer. Decide that before quiescence can publish fresh state.
+    const retry = (0, node_fs_1.existsSync)(paths.state);
+    const runner = (options.processIdentity ?? process_identity_js_1.captureProcessIdentity)();
+    const pendingState = () => ({
+        cleanup: 'pending',
+        fleetId: request.fleetId,
+        runner,
+        runnerGeneration: request.runnerGeneration,
+        schemaVersion: exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION,
+        sessionGeneration: request.sessionGeneration,
+        slice: request.slice,
+        updatedAt: now().toISOString(),
+    });
+    let phase = 'loading';
+    let published;
+    let quiesceFailure;
+    let quiesceRunning = () => undefined;
+    if (!retry) {
+        control.onQuiesce(() => {
+            if (phase === 'loading') {
+                // Quiescence reached this runner while it loads its Nx plan. No
+                // writer has started and none will: publish pending cleanup
+                // authority first, so a later stop runs the declared cleanup here
+                // and a restart intent can bind to this exact generation.
+                try {
+                    published = writeFleetSliceRunnerState(paths.state, pendingState(), security);
+                    phase = 'quiesced';
+                    control.acknowledgeQuiesce();
+                }
+                catch (error) {
+                    quiesceFailure = error;
+                }
+            }
+            else if (phase === 'running')
+                quiesceRunning();
+            else if (phase === 'quiesced')
+                control.acknowledgeQuiesce();
+        });
+    }
     const plan = await (options.loadPlan ?? nx_workspace_js_1.loadWorkspaceFleetPlan)();
     const adapter = plan.adapters.get(request.slice);
     if (!adapter) {
@@ -390,8 +465,6 @@ async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
     const startTarget = (0, nx_workspace_js_1.declaredStartTarget)(plan, request.slice);
     const cleanupTarget = (0, nx_workspace_js_1.declaredCleanupTarget)(plan, request.slice);
     const runtime = (options.resolveRuntime ?? nx_workspace_js_1.resolveWorkspaceNxRuntime)(request.workspaceRealpath);
-    const paths = fleetSliceRunnerPaths((0, node_path_1.join)((0, node_path_1.dirname)(request.startupPath), 'runners'), request.slice, request.runnerGeneration);
-    const runner = (options.processIdentity ?? process_identity_js_1.captureProcessIdentity)();
     const origin = new URL(request.origin);
     const childEnvironment = (0, personal_stage_js_1.createPersonalDevelopmentEnvironment)(startup.identity.stage, {
         ...process.env,
@@ -417,9 +490,9 @@ async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
     };
     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)) {
+    if (retry) {
+        if (stopSignal.aborted)
+            throw new Error('Fleet Slice runner stopped before child execution.');
         let previous = readFleetSliceRunnerState(paths.state, security);
         if (previous.fleetId !== request.fleetId ||
             previous.runnerGeneration !== request.runnerGeneration ||
@@ -488,57 +561,92 @@ async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
             return 1;
         }
     }
-    let state = writeFleetSliceRunnerState(paths.state, {
-        cleanup: 'pending',
-        fleetId: request.fleetId,
-        runner,
-        runnerGeneration: request.runnerGeneration,
-        schemaVersion: exports.FLEET_SLICE_RUNNER_SCHEMA_VERSION,
-        sessionGeneration: request.sessionGeneration,
-        slice: request.slice,
-        updatedAt: now().toISOString(),
-    }, security);
-    const child = spawnTarget(runtime, startTarget, {
-        additionalEnvironment: childEnvironment,
-        port: request.port,
-        stage: startup.identity.stage,
-        stdio: 'inherit',
-        workspaceRoot: request.workspaceRealpath,
-    });
-    try {
-        if (!child.pid)
-            throw new Error('Slice child did not expose a PID.');
-        state = writeFleetSliceRunnerState(paths.state, {
-            ...state,
-            child: identifyChild(child),
-            updatedAt: now().toISOString(),
-        }, security);
+    if (quiesceFailure !== undefined) {
+        // Quiescence was requested but its pending authority could not be
+        // published: refuse to start a writer and report the failed runner.
+        throw quiesceFailure instanceof Error
+            ? quiesceFailure
+            : new Error(String(quiesceFailure));
     }
-    catch (error) {
-        await terminate(child).catch(() => undefined);
+    let child;
+    let state;
+    if (phase === 'quiesced' || stopSignal.aborted) {
+        // Quiescence or a stop reached this runner while it loaded its plan, so
+        // its writer never starts. The stop handled below then runs declared
+        // cleanup here, or a restart intent leaves cleanup pending.
+        state =
+            published ??
+                writeFleetSliceRunnerState(paths.state, pendingState(), security);
+        phase = 'quiesced';
+    }
+    else {
+        state = writeFleetSliceRunnerState(paths.state, pendingState(), security);
+        const started = spawnTarget(runtime, startTarget, {
+            additionalEnvironment: childEnvironment,
+            port: request.port,
+            stage: startup.identity.stage,
+            stdio: 'inherit',
+            workspaceRoot: request.workspaceRealpath,
+        });
+        try {
+            if (!started.pid)
+                throw new Error('Slice child did not expose a PID.');
+            state = writeFleetSliceRunnerState(paths.state, {
+                ...state,
+                child: identifyChild(started),
+                updatedAt: now().toISOString(),
+            }, security);
+        }
+        catch (error) {
+            await terminate(started).catch(() => undefined);
+            state = writeFleetSliceRunnerState(paths.state, {
+                ...state,
+                cleanup: 'failed',
+                failure: error instanceof Error ? error.message : String(error),
+                updatedAt: now().toISOString(),
+            }, security);
+            return 1;
+        }
+        child = started;
+        phase = 'running';
+    }
+    let finalizing;
+    let quiescing;
+    let interval;
+    let settle = () => undefined;
+    let abandon = () => undefined;
+    const done = new Promise((resolvePromise, reject) => {
+        settle = resolvePromise;
+        abandon = reject;
+    });
+    const recordFailure = (error) => {
         state = writeFleetSliceRunnerState(paths.state, {
             ...state,
             cleanup: 'failed',
             failure: error instanceof Error ? error.message : String(error),
             updatedAt: now().toISOString(),
         }, security);
-        return 1;
-    }
-    let finalizing;
-    let interval;
+    };
+    // The writer is gone only when its whole owned group is absent.
+    const settleChild = async (terminateChild) => {
+        if (!child)
+            return;
+        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);
+    };
     const finalize = (terminateChild, cleanup) => {
         if (finalizing)
             return finalizing;
+        phase = 'finalizing';
+        if (interval)
+            clearInterval(interval);
         finalizing = (async () => {
-            if (interval)
-                clearInterval(interval);
             if (!cleanup) {
                 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);
+                    await settleChild(terminateChild);
                     state = writeFleetSliceRunnerState(paths.state, {
                         ...state,
                         cleanup: 'pending',
@@ -547,22 +655,15 @@ async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
                     return 0;
                 }
                 catch (error) {
-                    state = writeFleetSliceRunnerState(paths.state, {
-                        ...state,
-                        cleanup: 'failed',
-                        failure: error instanceof Error ? error.message : String(error),
-                        updatedAt: now().toISOString(),
-                    }, security);
+                    recordFailure(error);
                     return 1;
                 }
             }
             state = writeFleetSliceRunnerState(paths.state, { ...state, cleanup: 'running', updatedAt: now().toISOString() }, security);
             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);
+                await settleChild(terminateChild);
+                // The cleanup child inherits this runner's stdio, which the Fleet
+                // supervisor captures into the Slice log store.
                 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.');
@@ -585,31 +686,94 @@ async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
                 return 0;
             }
             catch (error) {
-                state = writeFleetSliceRunnerState(paths.state, {
-                    ...state,
-                    cleanup: 'failed',
-                    failure: error instanceof Error ? error.message : String(error),
-                    updatedAt: now().toISOString(),
-                }, security);
+                recordFailure(error);
                 return 1;
             }
         })();
+        void finalizing.then(settle);
         return finalizing;
     };
-    const terminateSignal = () => {
+    // Every exit request funnels here. A quiescence in progress finishes
+    // first, so finalization never races the writer it is still stopping.
+    const finish = (cleanup) => {
+        if (phase === 'finalizing')
+            return;
+        if (phase === 'quiescing') {
+            void quiescing?.then(() => finish(cleanup), () => undefined);
+            return;
+        }
+        void finalize(phase === 'running', cleanup);
+    };
+    quiesceRunning = () => {
+        if (phase !== 'running')
+            return;
+        phase = 'quiescing';
+        // Stop the writer but keep this runner and its pending cleanup
+        // authority: peer writers may still be live, so cleanup waits for an
+        // explicit stop after every selected Slice has quiesced.
+        quiescing = (async () => {
+            await settleChild(true);
+            state = writeFleetSliceRunnerState(paths.state, { ...state, cleanup: 'pending', updatedAt: now().toISOString() }, security);
+        })();
+        quiescing.then(() => {
+            if (phase !== 'quiescing')
+                return;
+            phase = 'quiesced';
+            control.acknowledgeQuiesce();
+        }, (error) => {
+            if (phase !== 'quiescing')
+                return;
+            phase = 'finalizing';
+            if (interval)
+                clearInterval(interval);
+            try {
+                recordFailure(error);
+            }
+            catch {
+                // The failed exit status below still reports the refusal.
+            }
+            finalizing = Promise.resolve(1);
+            settle(1);
+        });
+    };
+    const onStop = () => {
         const reason = consumeFleetSliceRunnerRestart(paths.restart, request, security)
             ? 'explicit-restart'
             : 'termination';
-        void finalize(true, fleetSliceRunnerRequiresCleanup(reason));
+        finish(fleetSliceRunnerRequiresCleanup(reason));
     };
-    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.
-    const childFinished = childExit(child).then(() => finalize(false, fleetSliceRunnerRequiresCleanup('child-exit')));
-    const parentLost = new Promise((resolvePromise) => {
+    if (child) {
+        const started = child;
+        started.once('error', abandon);
+        // 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.
+        started.once('exit', (code, signal) => {
+            // Owned termination (quiescence, restart, stop, lost parent) changes
+            // the phase first; only an exit the runner did not cause is the
+            // Slice's own failure cause.
+            if (phase !== 'running')
+                return;
+            if (code !== null || signal !== null) {
+                try {
+                    state = writeFleetSliceRunnerState(paths.state, {
+                        ...state,
+                        childExit: { at: now().toISOString(), code, signal },
+                        updatedAt: now().toISOString(),
+                    }, security);
+                }
+                catch {
+                    // The diagnostic is best effort; finalization below owns cleanup.
+                }
+            }
+            void finalize(false, fleetSliceRunnerRequiresCleanup('child-exit'));
+        });
+    }
+    stopSignal.addEventListener('abort', onStop, { once: true });
+    try {
+        // Referenced: a quiesced runner without a child must stay alive to
+        // observe its parent until an explicit stop arrives.
         interval = setInterval(() => {
             if (runnerParentStatus(request, {
                 graceMs: options.parentGraceMs,
@@ -617,35 +781,63 @@ async function runFleetSliceRunnerCore(requestPath, options = {}, stopSignal) {
                 processProbe: options.processProbe?.(request.parent),
                 security,
             }) === 'lost') {
-                void finalize(true, fleetSliceRunnerRequiresCleanup('parent-lost')).then(resolvePromise);
+                finish(fleetSliceRunnerRequiresCleanup('parent-lost'));
             }
         }, options.monitorIntervalMs ?? 1_000);
-        interval.unref();
-    });
-    const result = await Promise.race([childFinished, parentLost]);
-    stopSignal.removeEventListener('abort', terminateSignal);
-    return (result ??
-        (await finalize(true, fleetSliceRunnerRequiresCleanup('termination'))));
+        if (stopSignal.aborted)
+            onStop();
+        return await done;
+    }
+    finally {
+        stopSignal.removeEventListener('abort', onStop);
+        if (interval)
+            clearInterval(interval);
+    }
 }
 async function runFleetSliceRunner(requestPath, options = {}) {
     const request = readFleetSliceRunnerRequest(requestPath, options.security);
     const stop = new AbortController();
+    let quiesce;
+    let quiesceRequested = false;
     const interrupt = () => stop.abort();
+    const control = (value, type) => Boolean(value &&
+        typeof value === 'object' &&
+        Object.keys(value).sort().join(',') === 'runnerGeneration,type' &&
+        'type' in value &&
+        value.type === type &&
+        'runnerGeneration' in value &&
+        value.runnerGeneration === request.runnerGeneration);
     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)
+        if (control(value, fleet_process_js_1.FLEET_RUNNER_STOP_MESSAGE))
             interrupt();
+        else if (control(value, fleet_process_js_1.FLEET_RUNNER_QUIESCE_MESSAGE)) {
+            if (quiesce)
+                quiesce();
+            else
+                quiesceRequested = true;
+        }
     };
     process.once('SIGINT', interrupt);
     process.once('SIGTERM', interrupt);
     process.on('message', message);
     try {
-        return await runFleetSliceRunnerCore(requestPath, options, stop.signal);
+        return await runFleetSliceRunnerCore(requestPath, options, {
+            acknowledgeQuiesce: () => {
+                if (process.connected)
+                    process.send?.({
+                        runnerGeneration: request.runnerGeneration,
+                        type: fleet_process_js_1.FLEET_RUNNER_QUIESCED_MESSAGE,
+                    }, () => undefined);
+            },
+            onQuiesce: (handler) => {
+                quiesce = handler;
+                if (!quiesceRequested)
+                    return;
+                quiesceRequested = false;
+                handler();
+            },
+            stopSignal: stop.signal,
+        });
     }
     finally {
         process.removeListener('SIGINT', interrupt);
@@ -654,7 +846,7 @@ async function runFleetSliceRunner(requestPath, options = {}) {
     }
 }
 function assertFleetSliceRunnerCleanup(statePath, expected, security = {}) {
-    const state = readFleetSliceRunnerState(statePath, security);
+    const state = readPublishedFleetSliceRunnerState(statePath, security, 'Its claim remains retained.');
     if (state.cleanup !== 'succeeded' ||
         state.fleetId !== expected.fleetId ||
         state.runnerGeneration !== expected.runnerGeneration ||
@@ -667,7 +859,7 @@ async function retryFleetSliceRunnerCleanup(launched, effects = {}) {
     const security = effects.security ?? {};
     let state;
     try {
-        state = readFleetSliceRunnerState(launched.statePath, security);
+        state = readPublishedFleetSliceRunnerState(launched.statePath, security, 'Its claim remains retained.');
     }
     catch (error) {
         throw new errors_js_1.LocalDevContractError('cleanup-incomplete', `Fleet Slice cleanup retry lacks validated runner state: ${error instanceof Error ? error.message : String(error)}`);
@@ -713,9 +905,16 @@ async function retryFleetSliceRunnerCleanup(launched, effects = {}) {
             EBK_FLEET_SLICE_RUNNER_REQUEST: launched.requestPath,
         }),
         shell: false,
-        stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+        stdio: effects.output
+            ? ['ignore', 'pipe', 'pipe', 'ipc']
+            : ['ignore', 'inherit', 'inherit', 'ipc'],
         windowsHide: true,
     });
+    const output = effects.output;
+    if (output) {
+        child.stdout?.on('data', (chunk) => output('stdout', chunk));
+        child.stderr?.on('data', (chunk) => output('stderr', chunk));
+    }
     // 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.

package/src/repository-policy/deployment-plan.d.ts

@@ -1,6 +1,6 @@
 import type { ConfiguredDeploymentAccounts, DeploymentProfile, ProductionApprovalMode, ProductionFoundationProfile, RepositoryOperatingPolicy } from './policy.js';
 export declare const PROTECTED_DEPLOYMENT_ACTIONS: readonly ["deploy", "refresh", "remove", "unlock"];
-export declare const PROTECTED_DEPLOYMENT_STAGES: readonly ["staging", "production"];
+export declare const PROTECTED_DEPLOYMENT_STAGES: readonly ["development", "staging", "production"];
 export type ProtectedDeploymentAction = (typeof PROTECTED_DEPLOYMENT_ACTIONS)[number];
 export type ProtectedDeploymentStage = (typeof PROTECTED_DEPLOYMENT_STAGES)[number];
 export interface DeploymentPlanProject {

package/src/repository-policy/deployment-plan.js

@@ -9,7 +9,11 @@ exports.PROTECTED_DEPLOYMENT_ACTIONS = [
     'remove',
     'unlock',
 ];
-exports.PROTECTED_DEPLOYMENT_STAGES = ['staging', 'production'];
+exports.PROTECTED_DEPLOYMENT_STAGES = [
+    'development',
+    'staging',
+    'production',
+];
 function supportsAction(project, action) {
     return Object.prototype.hasOwnProperty.call(project.targets ?? {}, action);
 }
@@ -20,6 +24,17 @@ function compareCodePoints(left, right) {
     return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
 }
 function createProtectedDeploymentPlan(policy, options) {
+    // Only the starter protected pair deploys development through the protected
+    // workflow, from protected develop. Isolated profiles rehearse staging there,
+    // and the trunk lane protects main alone.
+    if (options.stage === 'development') {
+        if (policy.deploymentProfile !== 'starter') {
+            throw new Error(`Protected development deployment is unavailable for the ${policy.deploymentProfile} deployment profile; its protected develop lifecycle deploys staging.`);
+        }
+        if ((0, policy_js_1.deliveryLaneOf)(policy) === 'trunk') {
+            throw new Error('Protected development deployment is unavailable in the trunk delivery lane; development deploys locally and the protected lifecycle runs from main.');
+        }
+    }
     (0, policy_js_1.configuredDeploymentAccountForStage)(policy.deploymentProfile, policy.deploymentAccounts, options.stage);
     const deploymentAccounts = { ...policy.deploymentAccounts };
     const deploymentRegion = (0, policy_js_1.configuredDeploymentRegion)(policy.deploymentRegion);

package/src/secrets/generated-aws-control-plane.d.ts

@@ -4,9 +4,18 @@ export type AwsGeneratedSecretCommand = CreateSecretCommand | DescribeSecretComm
 export interface AwsGeneratedSecretClient {
     send(command: AwsGeneratedSecretCommand): Promise<unknown>;
 }
+declare const observationPhases: readonly ["inspect", "pre-create", "post-create"];
+declare const observationPredicates: readonly ["response-record", "arn-type", "arn-name", "name", "description", "deleted-date", "rotation-enabled", "tags-shape", "tags-count", "tag-entry", "tag-duplicate", "tag-value", "version-state", "not-found"];
+export interface GeneratedSecretObservationDiagnostic {
+    readonly phase: (typeof observationPhases)[number];
+    readonly predicate: (typeof observationPredicates)[number];
+}
+/** Copy only static labels; never invoke getters or retain provider detail. */
+export declare function safeGeneratedSecretObservationDiagnostic(value: unknown): GeneratedSecretObservationDiagnostic | undefined;
 export declare class AwsGeneratedSecretInitializationError extends Error {
     readonly code: 'generated-secret-input-invalid' | 'generated-secret-observation-invalid' | 'generated-secret-read-failed' | 'generated-secret-state-conflicting' | 'generated-secret-write-failed';
-    constructor(code: AwsGeneratedSecretInitializationError['code']);
+    readonly observationDiagnostic?: GeneratedSecretObservationDiagnostic;
+    constructor(code: AwsGeneratedSecretInitializationError['code'], observationDiagnostic?: GeneratedSecretObservationDiagnostic);
 }
 /**
  * Generates one declared machine value inside the AWS adapter and atomically
@@ -21,3 +30,4 @@ export declare function createAwsGeneratedSecretInitializationControlPlane(optio
     randomBytes?: (size: number) => Buffer;
     wait?: (milliseconds: number) => Promise<void>;
 }): GeneratedSecretInitializationControlPlane;
+export {};