@empire-builder-kit/nx 1.0.0-rc.30 → 1.0.0-rc.31

package/src/executors/sst-lifecycle/run-sst-command.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertGovernedAwsLifecyclePlatform = assertGovernedAwsLifecyclePlatform;
+exports.runGovernedChildProcess = runGovernedChildProcess;
 exports.createSstChildEnvironment = createSstChildEnvironment;
 exports.assertSafeSstForwardedArguments = assertSafeSstForwardedArguments;
 exports.resolveSstDevMode = resolveSstDevMode;
@@ -10,13 +12,18 @@ exports.runSstLifecyclePreflights = runSstLifecyclePreflights;
 exports.runSstCommand = runSstCommand;
 const devkit_1 = require("@nx/devkit");
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const index_js_1 = require("../../aws-authority/index.js");
+const child_environment_js_1 = require("../../aws/child-environment.js");
+const identity_js_1 = require("../../aws/identity.js");
 const stages_js_1 = require("../../foundation/stages.js");
 const personal_stage_js_1 = require("../../local-dev/personal-stage.js");
-const index_js_1 = require("../../repository-policy/index.js");
-const index_js_2 = require("../../work-markers/index.js");
-const logging_preflight_js_1 = require("./logging-preflight.js");
+const federated_credential_transport_js_1 = require("../local-deploy/federated-credential-transport.js");
+const index_js_2 = require("../../repository-policy/index.js");
+const index_js_3 = require("../../work-markers/index.js");
 const secret_preflight_js_1 = require("./secret-preflight.js");
+const generated_secret_retirement_js_1 = require("./generated-secret-retirement.js");
 const sst_environment_source_js_1 = require("./sst-environment-source.js");
 const GOVERNED_STAGES = new Set(['development', 'staging', 'production']);
 const DEPLOYMENT_STAGES = new Set(['development', 'staging', 'production']);
@@ -30,6 +37,274 @@ const RESERVED_FORWARDED_OPTIONS = new Set([
 const SST_DEV_MODES = new Set(['basic', 'mono']);
 const AWS_REGION_PATTERN = /^[a-z]{2}(?:-gov)?-[a-z]+-\d$/;
 const AWS_ROLE_ARN_PATTERN = /^arn:(aws|aws-us-gov|aws-cn):iam::\d{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
+const MAX_CALLER_IDENTITY_BYTES = 1024 * 1024;
+const SST_SIGNAL_GRACE_PERIOD_MS = 10_000;
+const SST_SIGNAL_KILL_WAIT_MS = 5_000;
+const SST_PROCESS_GROUP_POLL_MS = 25;
+const GOVERNED_PROCESS_GROUP_ENV = 'EBK_GOVERNED_PROCESS_GROUP';
+function assertGovernedAwsLifecyclePlatform(platform = process.platform) {
+    if (platform === 'win32') {
+        throw new Error('Governed AWS infrastructure lifecycle is unavailable on native Windows; use macOS, Linux, or WSL2. Native Windows remains supported for local development and verification.');
+    }
+}
+function isMissingProcessError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ESRCH');
+}
+function exactWindowsSystemRoot() {
+    const values = new Set(Object.entries(process.env)
+        .filter(([name, value]) => name.toLowerCase() === 'systemroot' &&
+        typeof value === 'string' &&
+        value.length > 0)
+        .map(([, value]) => value));
+    if (values.size !== 1) {
+        throw new Error('Workspace SST tree cleanup requires exact SystemRoot.');
+    }
+    const systemRoot = values.values().next().value;
+    if (typeof systemRoot !== 'string' ||
+        !(0, node_path_1.isAbsolute)(systemRoot) ||
+        /[\0\r\n"]/u.test(systemRoot)) {
+        throw new Error('Workspace SST tree cleanup has an unsafe SystemRoot.');
+    }
+    return systemRoot;
+}
+function exactWindowsTaskkill() {
+    const systemRoot = exactWindowsSystemRoot();
+    const requested = (0, node_path_1.join)(systemRoot, 'System32', 'taskkill.exe');
+    const metadata = (0, node_fs_1.lstatSync)(requested);
+    const canonical = (0, node_fs_1.realpathSync)(requested);
+    if (metadata.isSymbolicLink() ||
+        !metadata.isFile() ||
+        canonical.toLowerCase() !== requested.toLowerCase()) {
+        throw new Error('Workspace SST taskkill authority is not exact.');
+    }
+    return { executable: canonical, systemRoot };
+}
+function signalExactGovernedProcessTree(child, signal) {
+    const pid = child.pid;
+    if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0) {
+        throw new Error('Workspace SST child has no exact process identity.');
+    }
+    if (process.platform === 'win32') {
+        const taskkill = exactWindowsTaskkill();
+        const terminated = (0, node_child_process_1.spawnSync)(taskkill.executable, ['/pid', String(pid), '/t', '/f'], {
+            env: { SystemRoot: taskkill.systemRoot },
+            shell: false,
+            stdio: 'ignore',
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        if ((terminated.error || terminated.signal || terminated.status !== 0) &&
+            child.exitCode === null &&
+            child.signalCode === null) {
+            throw new Error('Workspace SST process-tree termination failed.');
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (!isMissingProcessError(error))
+            throw error;
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill(signal);
+        }
+    }
+}
+function exactGovernedProcessTreeExists(pid) {
+    if (process.platform === 'win32')
+        return false;
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (isMissingProcessError(error))
+            return false;
+        throw error;
+    }
+}
+async function waitForExactGovernedProcessTreeExit(pid, deadline = Date.now() + SST_SIGNAL_GRACE_PERIOD_MS + SST_SIGNAL_KILL_WAIT_MS) {
+    while (exactGovernedProcessTreeExists(pid)) {
+        if (Date.now() >= deadline) {
+            throw new Error('Workspace SST process tree did not stop within the bounded deadline.');
+        }
+        await new Promise((resolveWait) => setTimeout(resolveWait, SST_PROCESS_GROUP_POLL_MS));
+    }
+}
+async function waitForGovernedChildSettlement(childSettled, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+        throw new Error('Workspace SST child did not stop within the bounded deadline.');
+    }
+    let timeout;
+    try {
+        await Promise.race([
+            childSettled,
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => reject(new Error('Workspace SST child did not stop within the bounded deadline.')), remaining);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+async function terminateRetainedGovernedProcessGroup(pid) {
+    if (process.platform === 'win32' || !exactGovernedProcessTreeExists(pid)) {
+        return false;
+    }
+    const deadline = Date.now() + SST_SIGNAL_GRACE_PERIOD_MS + SST_SIGNAL_KILL_WAIT_MS;
+    try {
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch (error) {
+        if (!isMissingProcessError(error))
+            throw error;
+        return false;
+    }
+    const escalation = setTimeout(() => {
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch (error) {
+            if (!isMissingProcessError(error)) {
+                process.stderr.write('Governed descendant process-tree escalation failed.\n');
+            }
+        }
+    }, SST_SIGNAL_GRACE_PERIOD_MS);
+    try {
+        await waitForExactGovernedProcessTreeExit(pid, deadline);
+    }
+    finally {
+        clearTimeout(escalation);
+    }
+    return true;
+}
+async function stopExactGovernedProcessTree(child, signal, childSettled, isSettled, ownsProcessGroup = true) {
+    const pid = child.pid;
+    const deadline = Date.now() + SST_SIGNAL_GRACE_PERIOD_MS + SST_SIGNAL_KILL_WAIT_MS;
+    if (process.platform === 'win32' || ownsProcessGroup) {
+        signalExactGovernedProcessTree(child, signal);
+    }
+    else {
+        child.kill(signal);
+    }
+    let escalationError;
+    const escalation = setTimeout(() => {
+        try {
+            if (!isSettled() ||
+                (ownsProcessGroup && pid && exactGovernedProcessTreeExists(pid))) {
+                if (process.platform === 'win32' || ownsProcessGroup) {
+                    signalExactGovernedProcessTree(child, 'SIGKILL');
+                }
+                else {
+                    child.kill('SIGKILL');
+                }
+            }
+        }
+        catch (error) {
+            escalationError = error;
+        }
+    }, SST_SIGNAL_GRACE_PERIOD_MS);
+    try {
+        await waitForGovernedChildSettlement(childSettled, deadline);
+        if (ownsProcessGroup && pid && process.platform !== 'win32') {
+            await waitForExactGovernedProcessTreeExit(pid, deadline);
+        }
+        if (escalationError)
+            throw escalationError;
+    }
+    finally {
+        clearTimeout(escalation);
+    }
+}
+/** Run one exact shell-free child as an owned process tree. The returned
+ * promise settles only after child teardown and the bounded caller-supplied
+ * close reconciliation complete. */
+function runGovernedChildProcess(input) {
+    return new Promise((resolveChildRun) => {
+        const environment = { ...input.environment };
+        for (const name of Object.keys(environment)) {
+            if (name.toUpperCase() === GOVERNED_PROCESS_GROUP_ENV) {
+                delete environment[name];
+            }
+        }
+        if (process.platform !== 'win32') {
+            environment[GOVERNED_PROCESS_GROUP_ENV] = '1';
+        }
+        const child = (input.spawnChild ?? node_child_process_1.spawn)(input.executable, [...input.args], {
+            cwd: input.cwd,
+            detached: process.platform !== 'win32',
+            env: environment,
+            shell: false,
+            stdio: 'inherit',
+        });
+        let finishing = false;
+        let settled = false;
+        let spawnError;
+        let unregisterSignalCleanup = () => undefined;
+        let resolveChildSettled = () => undefined;
+        const childSettled = new Promise((resolveChild) => {
+            resolveChildSettled = resolveChild;
+        });
+        const finish = async (status, signal) => {
+            if (finishing)
+                return;
+            finishing = true;
+            const result = {
+                ...(spawnError ? { error: spawnError } : {}),
+                signal,
+                status,
+            };
+            if (!(0, federated_credential_transport_js_1.governedSignalCleanupInProgress)() && child.pid) {
+                try {
+                    if (await terminateRetainedGovernedProcessGroup(child.pid)) {
+                        result.error ??= new Error('Governed child exited before its exact descendant process tree stopped.');
+                    }
+                }
+                catch (error) {
+                    result.error =
+                        error instanceof Error
+                            ? error
+                            : new Error('Governed child descendant process-tree reconciliation failed.');
+                }
+            }
+            try {
+                await input.afterClose?.(result);
+            }
+            catch (error) {
+                result.error =
+                    error instanceof Error
+                        ? error
+                        : new Error('Governed child close reconciliation failed.');
+            }
+            settled = true;
+            unregisterSignalCleanup();
+            resolveChildSettled();
+            resolveChildRun(result);
+        };
+        unregisterSignalCleanup = (0, federated_credential_transport_js_1.registerGovernedSignalCleanup)((signal) => stopExactGovernedProcessTree(child, signal, childSettled, () => settled), 100);
+        child.once('error', (error) => {
+            spawnError = error;
+            void finish(null, null);
+        });
+        child.once('close', (status, signal) => {
+            void finish(status, signal);
+        });
+    });
+}
+function partitionForRegion(region) {
+    if (region.startsWith('cn-'))
+        return 'aws-cn';
+    if (region.startsWith('us-gov-'))
+        return 'aws-us-gov';
+    return 'aws';
+}
 function captureSstEnvironmentSource(context) {
     const projectName = context.projectName;
     const configured = projectName
@@ -45,24 +320,62 @@ function captureSstEnvironmentSource(context) {
         workspaceRoot: context.root,
     });
 }
-function requiresInfrastructureBinding(command, stage) {
+function requiresSourceReconciliation(command, stage) {
     return (GOVERNED_STAGES.has(stage) &&
         (command === 'deploy' || command === 'refresh' || command === 'remove'));
 }
-async function authorizeInfrastructureMutation(command, options, context, invocation) {
-    const { revalidateInfrastructureMutationAuthorization } = await Promise.resolve().then(() => require('../infrastructure-plan/infrastructure-plan.js'));
-    await revalidateInfrastructureMutationAuthorization(command, options, context, invocation);
+function isGovernedLocalCommand(command) {
+    return (command === 'deploy' ||
+        command === 'refresh' ||
+        command === 'remove' ||
+        command === 'unlock');
 }
-async function authorizeLocalUnlock(options, invocation) {
-    const { revalidateLocalUnlockCallerAuthority } = await Promise.resolve().then(() => require('../infrastructure-plan/infrastructure-plan.js'));
-    revalidateLocalUnlockCallerAuthority({
-        invocation,
-        profile: options.profile,
+async function authorizeLocalUnlock(options, invocation, environment = process.env) {
+    const expectedAccount = invocation.environment.AWS_EXPECTED_ACCOUNT_ID?.trim() ?? '';
+    const expectedRoleArn = invocation.environment.EBK_EXPECTED_DEPLOYMENT_ROLE_ARN?.trim() ?? '';
+    if (!/^\d{12}$/.test(expectedAccount) || !expectedRoleArn) {
+        throw new Error('Local unlock requires one exact committed account and temporary assumed role.');
+    }
+    const ambientExpectedAccount = environment.AWS_EXPECTED_ACCOUNT_ID?.trim();
+    if (ambientExpectedAccount && ambientExpectedAccount !== expectedAccount) {
+        throw new Error('Ambient AWS_EXPECTED_ACCOUNT_ID does not match committed deployment topology.');
+    }
+    const result = (0, node_child_process_1.spawnSync)('aws', [
+        'sts',
+        'get-caller-identity',
+        '--endpoint-url',
+        (0, identity_js_1.canonicalStsEndpoint)(invocation.environment.AWS_REGION?.trim() ?? ''),
+        '--output',
+        'json',
+        ...(options.profile ? ['--profile', options.profile] : []),
+    ], {
+        cwd: invocation.cwd,
+        encoding: 'utf8',
+        env: createSstChildEnvironment(environment, invocation.environment),
+        maxBuffer: MAX_CALLER_IDENTITY_BYTES,
+        shell: false,
+        windowsHide: true,
     });
-}
-async function retainInfrastructureConvergence(command, options, context, invocation, applySucceeded) {
-    const { recordInfrastructureMutationConvergence } = await Promise.resolve().then(() => require('../infrastructure-plan/infrastructure-plan.js'));
-    return recordInfrastructureMutationConvergence(command, options, context, invocation, applySucceeded);
+    if (result.error || result.status !== 0 || result.signal) {
+        throw new Error('Local unlock AWS caller identity could not be verified.');
+    }
+    let caller;
+    try {
+        caller = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new Error('Local unlock AWS caller identity is not valid JSON.');
+    }
+    if (!caller ||
+        typeof caller !== 'object' ||
+        Array.isArray(caller) ||
+        !('Account' in caller) ||
+        !('Arn' in caller) ||
+        caller.Account !== expectedAccount ||
+        typeof caller.Arn !== 'string' ||
+        !(0, identity_js_1.matchesExpectedAssumedRoleArn)(expectedAccount, caller.Arn, expectedRoleArn)) {
+        throw new Error('Local unlock AWS caller does not match the committed account and exact temporary assumed role.');
+    }
 }
 function projectKind(context) {
     if (!context.projectName) {
@@ -77,18 +390,21 @@ function projectKind(context) {
     return foundation ? 'foundation' : 'slice';
 }
 function createSstChildEnvironment(ambient, invocation) {
-    const sanitized = (0, personal_stage_js_1.isFrameworkPersonalStage)(invocation.EBK_CONSUMER_STAGE)
+    const stageSanitized = (0, personal_stage_js_1.isFrameworkPersonalStage)(invocation.EBK_CONSUMER_STAGE)
         ? (0, personal_stage_js_1.createPersonalDevelopmentEnvironment)(invocation.EBK_CONSUMER_STAGE, ambient)
         : (0, personal_stage_js_1.stripAmbientStageAuthority)(ambient);
+    const sanitized = (0, child_environment_js_1.sanitizeGovernedAwsChildEnvironment)(stageSanitized, {
+        preserveVerifiedGithubCredentials: stageSanitized.GITHUB_ACTIONS === 'true',
+    });
     delete sanitized.EBK_PRODUCTION_FOUNDATION_PROFILE;
     delete sanitized.EBK_LOCAL_MUTATION_CAPABILITY_NONCE;
     delete sanitized.EBK_LOCAL_MUTATION_CAPABILITY_PATH;
+    delete sanitized.EBK_GITHUB_JOB_WORKFLOW_REF;
+    delete sanitized.EBK_NX_STAGE_LIFECYCLE;
     // Nx injects task identity, target, hash, terminal, cache, and invocation
-    // metadata into every executor process. A reviewed infrastructure-plan and
-    // its mutation-time revalidation intentionally run under different Nx
-    // targets, so those values are orchestration context rather than desired
-    // infrastructure inputs. Never let them reach SST, where build tools can
-    // persist ambient environment values into deployment archives.
+    // metadata into every executor process. Those values describe orchestration,
+    // not desired infrastructure. Never let them reach SST, where build tools
+    // can persist ambient environment values into deployment archives.
     for (const name of Object.keys(sanitized)) {
         if (name.startsWith('NX_') || name === 'LERNA_PACKAGE_NAME') {
             delete sanitized[name];
@@ -124,19 +440,33 @@ function assertSstLifecyclePolicy(command, stage, environment = process.env, dep
     if (command === 'dev') {
         throw new Error(`SST dev is not permitted for protected stage ${stage}.`);
     }
-    if (!(0, index_js_1.requiresGithubDeployment)(deploymentProfile, stage) &&
+    if (command === 'remove' &&
+        stage === 'production' &&
+        environment.EBK_ALLOW_PRODUCTION_REMOVE !== 'true') {
+        throw new Error('Production removal requires EBK_ALLOW_PRODUCTION_REMOVE=true in the governed production environment.');
+    }
+    if (!(0, index_js_2.requiresGithubDeployment)(deploymentProfile, stage) &&
         environment.GITHUB_ACTIONS !== 'true') {
         return;
     }
     const repository = environment.GITHUB_REPOSITORY;
-    const expectedBranch = stage === 'staging' ? 'develop' : 'main';
+    const expectedBranch = stage === 'production' ? 'main' : 'develop';
     const expectedRef = `refs/heads/${expectedBranch}`;
-    const expectedWorkflowRef = repository
+    const expectedCalledWorkflowRef = repository
         ? `${repository}/.github/workflows/deploy.yml@${expectedRef}`
         : undefined;
     const eventName = environment.GITHUB_EVENT_NAME;
     const allowedEvent = eventName === 'workflow_dispatch' ||
-        (eventName === 'push' && command === 'deploy');
+        (eventName === 'push' &&
+            command === 'deploy' &&
+            deploymentProfile !== 'starter');
+    const expectedCallerWorkflowRef = eventName === 'push'
+        ? repository
+            ? `${repository}/.github/workflows/ci.yml@${expectedRef}`
+            : undefined
+        : eventName === 'workflow_dispatch'
+            ? expectedCalledWorkflowRef
+            : undefined;
     // These GitHub-provided values are a fail-closed provenance consistency
     // check, not a credential boundary: a local process can spoof them. Actual
     // protected-stage authority comes from environment-scoped OIDC role access
@@ -146,14 +476,10 @@ function assertSstLifecyclePolicy(command, stage, environment = process.env, dep
         environment.GITHUB_ACTIONS === 'true' &&
         allowedEvent &&
         environment.GITHUB_REF === expectedRef &&
-        environment.GITHUB_WORKFLOW_REF === expectedWorkflowRef;
+        environment.GITHUB_WORKFLOW_REF === expectedCallerWorkflowRef &&
+        environment.EBK_GITHUB_JOB_WORKFLOW_REF === expectedCalledWorkflowRef;
     if (!workflowProvenanceMatches) {
-        throw new Error(`SST ${command} for protected stage ${stage} must run from the ${expectedBranch}-branch deploy workflow; pushes may run only deploy and other lifecycle actions require workflow_dispatch.`);
-    }
-    if (command === 'remove' &&
-        stage === 'production' &&
-        environment.EBK_ALLOW_PRODUCTION_REMOVE !== 'true') {
-        throw new Error('Production removal requires EBK_ALLOW_PRODUCTION_REMOVE=true in the protected production environment.');
+        throw new Error(`SST ${command} for protected stage ${stage} must run from the exact ${expectedBranch}-branch caller and reusable deploy workflows; isolated-profile pushes may run only deploy and other lifecycle actions require workflow_dispatch.`);
     }
 }
 function resolveSstLifecycleStages(options, environment = process.env) {
@@ -222,19 +548,23 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         stages.mapped) {
         throw new Error(`Full deploy is not permitted for mapped personal stage ${stages.consumerStage}. Use ebk dev against the ${stages.foundationStage} Foundation.`);
     }
-    const operatingPolicy = DEPLOYMENT_STAGES.has(stages.consumerStage) &&
-        (command === 'deploy' ||
-            command === 'refresh' ||
-            command === 'remove' ||
-            command === 'unlock')
-        ? (0, index_js_1.readRepositoryOperatingPolicy)(context.root)
+    const operatingPolicy = command === 'dev' ||
+        (DEPLOYMENT_STAGES.has(stages.consumerStage) &&
+            (command === 'deploy' ||
+                command === 'refresh' ||
+                command === 'remove' ||
+                command === 'unlock'))
+        ? (0, index_js_2.readRepositoryOperatingPolicy)(context.root)
         : undefined;
     assertSstLifecyclePolicy(command, stages.consumerStage, environment, operatingPolicy?.deploymentProfile);
-    const deploymentAccounts = operatingPolicy
-        ? (0, index_js_1.configuredDeploymentAccountTopology)(operatingPolicy.deploymentProfile, operatingPolicy.deploymentAccounts)
+    const authorityStage = command === 'dev'
+        ? 'development'
+        : stages.consumerStage;
+    const deploymentAccount = operatingPolicy
+        ? (0, index_js_2.configuredDeploymentAccountForStage)(operatingPolicy.deploymentProfile, operatingPolicy.deploymentAccounts, authorityStage)
         : undefined;
     const deploymentRegion = operatingPolicy
-        ? (0, index_js_1.configuredDeploymentRegion)(operatingPolicy.deploymentRegion)
+        ? (0, index_js_2.configuredDeploymentRegion)(operatingPolicy.deploymentRegion)
         : undefined;
     if (deploymentRegion &&
         options.region?.trim() &&
@@ -245,6 +575,22 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         !AWS_ROLE_ARN_PATTERN.test(options.expectedRoleArn.trim())) {
         throw new Error('SST lifecycle expectedRoleArn must be one exact IAM role ARN.');
     }
+    const committedRoleArn = operatingPolicy &&
+        deploymentAccount &&
+        deploymentRegion &&
+        isGovernedLocalCommand(command)
+        ? (0, index_js_1.createStageAuthorityIdentity)({
+            accountId: deploymentAccount,
+            partition: partitionForRegion(deploymentRegion),
+            region: deploymentRegion,
+            stage: authorityStage,
+        }).deploymentRoleArn
+        : undefined;
+    if (committedRoleArn &&
+        options.expectedRoleArn?.trim() &&
+        options.expectedRoleArn.trim() !== committedRoleArn) {
+        throw new Error(`SST ${command} requires the exact committed ${authorityStage} stage authority role ${committedRoleArn}.`);
+    }
     const profile = options.profile?.trim();
     if (options.profile !== undefined &&
         (!profile || profile !== options.profile || profile.length > 128)) {
@@ -252,21 +598,24 @@ function buildSstCommandInvocation(command, options, context, environment = proc
     }
     if (operatingPolicy &&
         environment.GITHUB_ACTIONS !== 'true' &&
-        (command === 'deploy' ||
-            command === 'refresh' ||
-            command === 'remove' ||
-            command === 'unlock') &&
+        command === 'deploy' &&
+        environment.EBK_NX_STAGE_LIFECYCLE !== 'local') {
+        throw new Error(`Local deploy for ${stages.consumerStage} must be invoked by the governed root stage lifecycle (EBK_NX_STAGE_LIFECYCLE=local).`);
+    }
+    if (operatingPolicy &&
+        environment.GITHUB_ACTIONS !== 'true' &&
+        isGovernedLocalCommand(command) &&
         !options.expectedRoleArn?.trim()) {
         throw new Error(`Local ${command} for ${stages.consumerStage} requires --expectedRoleArn for one temporary assumed-role session.`);
     }
     if (GOVERNED_STAGES.has(stages.consumerStage) &&
         (command === 'deploy' || command === 'refresh')) {
-        (0, index_js_2.assertWorkMarkerReport)((0, index_js_2.scanWorkMarkers)(context.root), {
-            protectedPromotion: true,
+        (0, index_js_3.assertWorkMarkerReport)((0, index_js_3.scanWorkMarkers)(context.root), {
+            protectedPromotion: stages.consumerStage !== 'development',
         });
     }
     const policyDecision = stages.consumerStage === 'production'
-        ? (0, index_js_1.assertRepositoryPolicyRequest)(context.root, {
+        ? (0, index_js_2.assertRepositoryPolicyRequest)(context.root, {
             action: command,
             projects: [
                 {
@@ -278,6 +627,8 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         })
         : undefined;
     const args = [command, '--stage', stages.consumerStage];
+    if (command === 'refresh')
+        args.push('--yes');
     if (options.target) {
         args.push('--target', options.target);
     }
@@ -297,9 +648,9 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         ],
         cwd,
         environment: {
-            ...(deploymentAccounts
+            ...(deploymentAccount
                 ? {
-                    AWS_EXPECTED_ACCOUNT_ID: deploymentAccounts[stages.consumerStage],
+                    AWS_EXPECTED_ACCOUNT_ID: deploymentAccount,
                 }
                 : {}),
             ...(profile ? { AWS_PROFILE: profile } : {}),
@@ -309,9 +660,9 @@ function buildSstCommandInvocation(command, options, context, environment = proc
                     ? { AWS_REGION: options.region.trim() }
                     : {}),
             EBK_CONSUMER_STAGE: stages.consumerStage,
-            ...(options.expectedRoleArn?.trim()
+            ...((committedRoleArn ?? options.expectedRoleArn?.trim())
                 ? {
-                    EBK_EXPECTED_DEPLOYMENT_ROLE_ARN: options.expectedRoleArn.trim(),
+                    EBK_EXPECTED_DEPLOYMENT_ROLE_ARN: committedRoleArn ?? options.expectedRoleArn?.trim(),
                 }
                 : {}),
             EBK_FOUNDATION_STAGE: stages.foundationStage,
@@ -324,35 +675,33 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         executable: process.execPath,
     };
 }
-async function runSstLifecyclePreflights(command, options, context, invocation, dependencies = {}) {
-    if (command === 'deploy' || command === 'dev') {
-        await (dependencies.logging ?? logging_preflight_js_1.preflightManagedLogGroups)(command, options, context, invocation);
-    }
+async function runSstLifecyclePreflights(command, options, context, invocation, dependencies = {}, environment = process.env) {
     if (command === 'deploy') {
         await (dependencies.secrets ?? secret_preflight_js_1.preflightSliceSecretMetadata)(options, context, invocation);
     }
     if (command === 'unlock' &&
         invocation.environment.EBK_EXPECTED_DEPLOYMENT_ROLE_ARN) {
-        await (dependencies.unlockAuthorization ?? authorizeLocalUnlock)(options, invocation);
-    }
-    if (requiresInfrastructureBinding(command, invocation.environment.EBK_CONSUMER_STAGE)) {
-        await (dependencies.infrastructureAuthorization ??
-            authorizeInfrastructureMutation)(command, options, context, invocation);
+        await (dependencies.unlockAuthorization ?? authorizeLocalUnlock)(options, invocation, environment);
     }
 }
 async function runSstCommand(command, options, context, dependencies = {}) {
+    if (command !== 'dev') {
+        assertGovernedAwsLifecyclePlatform(dependencies.platform);
+    }
+    const environment = dependencies.environment ?? process.env;
+    const joinsGovernedProcessGroup = process.platform !== 'win32' &&
+        environment[GOVERNED_PROCESS_GROUP_ENV] === '1';
     let invocation;
     let environmentSource;
     try {
-        invocation = buildSstCommandInvocation(command, options, context);
-        if (requiresInfrastructureBinding(command, invocation.environment.EBK_CONSUMER_STAGE)) {
-            // Infrastructure authorization runs an SST plan and SST can rewrite its
-            // generated environment declaration during that preflight. Capture the
-            // committed source before any SST-bearing operation so neither the plan
-            // nor the mutation child can become the restoration baseline.
+        invocation = buildSstCommandInvocation(command, options, context, environment);
+        if (requiresSourceReconciliation(command, invocation.environment.EBK_CONSUMER_STAGE)) {
+            // Native SST can rewrite its generated environment declaration. Capture
+            // committed tool-owned source before the child so successful and failed
+            // lifecycle commands restore the repository exactly.
             environmentSource = captureSstEnvironmentSource(context);
         }
-        await runSstLifecyclePreflights(command, options, context, invocation, dependencies);
+        await runSstLifecyclePreflights(command, options, context, invocation, dependencies, environment);
         if (environmentSource)
             (0, sst_environment_source_js_1.reconcileSstEnvironmentSourceTree)(environmentSource);
     }
@@ -378,22 +727,52 @@ async function runSstCommand(command, options, context, dependencies = {}) {
     return new Promise((resolve) => {
         const child = (dependencies.spawnChild ?? node_child_process_1.spawn)(invocation.executable, invocation.args, {
             cwd: invocation.cwd,
-            env: createSstChildEnvironment(process.env, invocation.environment),
+            detached: process.platform !== 'win32' && !joinsGovernedProcessGroup,
+            env: createSstChildEnvironment(environment, invocation.environment),
             shell: false,
             stdio: 'inherit',
         });
         let settled = false;
+        let unregisterSignalCleanup = () => undefined;
+        let resolveChildSettled = () => undefined;
+        const childSettled = new Promise((resolveChild) => {
+            resolveChildSettled = resolveChild;
+        });
         const settle = (success) => {
             if (settled)
                 return;
             settled = true;
+            unregisterSignalCleanup();
+            resolveChildSettled();
             resolve({ success });
         };
+        unregisterSignalCleanup = (0, federated_credential_transport_js_1.registerGovernedSignalCleanup)((signal) => {
+            if (settled)
+                return;
+            return stopExactGovernedProcessTree(child, signal, childSettled, () => settled, !joinsGovernedProcessGroup);
+        }, 100);
         child.on('error', (error) => {
             devkit_1.logger.error(`Failed to start workspace SST: ${error.message}`);
             settle(false);
         });
         child.on('close', async (code, signal) => {
+            if (settled)
+                return;
+            let retainedProcessTree = false;
+            if (!(0, federated_credential_transport_js_1.governedSignalCleanupInProgress)() &&
+                !joinsGovernedProcessGroup &&
+                child.pid) {
+                try {
+                    retainedProcessTree = await terminateRetainedGovernedProcessGroup(child.pid);
+                }
+                catch (error) {
+                    retainedProcessTree = true;
+                    devkit_1.logger.error(`Failed to stop retained SST descendant process tree: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                if (retainedProcessTree) {
+                    devkit_1.logger.error('SST exited before its exact descendant process tree stopped.');
+                }
+            }
             if (code !== 0) {
                 devkit_1.logger.error(signal
                     ? `SST ${command} terminated with signal ${signal}.`
@@ -412,30 +791,21 @@ async function runSstCommand(command, options, context, dependencies = {}) {
                     devkit_1.logger.error(`Failed to restore SST tool-owned source: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
-            const applySucceeded = code === 0 && sourceRestored;
-            if (requiresInfrastructureBinding(command, invocation.environment.EBK_CONSUMER_STAGE)) {
+            const applySucceeded = code === 0 && sourceRestored && !retainedProcessTree;
+            let generatedSecretRetirementSucceeded = true;
+            if (applySucceeded &&
+                command === 'remove' &&
+                projectKind(context) === 'slice') {
                 try {
-                    const mutationEvidenceRetained = await (dependencies.infrastructureConvergence ??
-                        retainInfrastructureConvergence)(command, options, context, invocation, applySucceeded);
-                    if (!mutationEvidenceRetained) {
-                        devkit_1.logger.error(`SST ${command} did not retain valid infrastructure mutation evidence.`);
-                    }
-                    // A deploy retains apply-complete-unverified as a successful handoff
-                    // to deployed smoke. It is not terminal convergence; the protected
-                    // finalizer consumes the exact alarm, data, and journey evidence.
-                    // Convergence remains the fail-closed authority for governed
-                    // mutations. A child failure remains failed even if refresh wrote a
-                    // newer state snapshot; that condition is retained as recovery
-                    // evidence and cannot be upgraded into accepted success.
-                    settle(sourceRestored && mutationEvidenceRetained && applySucceeded);
+                    await (dependencies.generatedSecretRetirement ??
+                        generated_secret_retirement_js_1.retireGeneratedSecretsAfterSliceRemove)(options, context, invocation, { environment });
                 }
                 catch (error) {
-                    devkit_1.logger.error(`Failed to retain infrastructure convergence: ${error instanceof Error ? error.message : String(error)}`);
-                    settle(false);
+                    generatedSecretRetirementSucceeded = false;
+                    devkit_1.logger.error(`Generated stage-secret retirement failed after native Slice removal: ${error instanceof Error ? error.message : String(error)}`);
                 }
-                return;
             }
-            settle(applySucceeded);
+            settle(applySucceeded && generatedSecretRetirementSucceeded);
         });
     });
 }