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

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,14 +12,28 @@ 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 task_identity_js_1 = require("../../local-dev/task-identity.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("../../workspace-deployment/index.js");
+const index_js_4 = require("../../work-markers/index.js");
 const secret_preflight_js_1 = require("./secret-preflight.js");
-const PROTECTED_STAGES = new Set(['staging', 'production']);
+const task_native_writer_js_1 = require("../../local-dev/task-native-writer.js");
+const local_deploy_js_1 = require("../local-deploy/local-deploy.js");
+const task_stack_absence_js_1 = require("../dev-task-cleanup/task-stack-absence.js");
+const process_group_js_1 = require("../../local-dev/process-group.js");
+const secret_initialize_js_1 = require("../secret-initialize/secret-initialize.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']);
 const RESERVED_FORWARDED_OPTIONS = new Set([
     '--config',
     '--profile',
@@ -27,17 +43,349 @@ 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$/;
-function requiresInfrastructureBinding(command, stage) {
-    return (PROTECTED_STAGES.has(stage) &&
+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 = process_group_js_1.OWNED_PROCESS_SIGNAL_GRACE_MS;
+const SST_SIGNAL_KILL_WAIT_MS = process_group_js_1.OWNED_PROCESS_KILL_WAIT_MS;
+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 task Fleet is not validated in this prerelease either.');
+    }
+}
+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;
+    return (0, process_group_js_1.exactOwnedProcessGroupExists)(pid);
+}
+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 cancellationSignal;
+        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 {
+                // A child may acknowledge cancellation with exit zero. Preserve the
+                // observed parent signal before callers reconcile a successful close.
+                result.signal ??= cancellationSignal ?? null;
+                await input.afterClose?.(result);
+            }
+            catch (error) {
+                result.error =
+                    error instanceof Error
+                        ? error
+                        : new Error('Governed child close reconciliation failed.');
+            }
+            result.signal ??= cancellationSignal ?? null;
+            settled = true;
+            unregisterSignalCleanup();
+            resolveChildSettled();
+            resolveChildRun(result);
+        };
+        unregisterSignalCleanup = (0, federated_credential_transport_js_1.registerGovernedSignalCleanup)((signal) => {
+            if (settled)
+                return;
+            cancellationSignal ??= signal;
+            return 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
+        ? context.projectsConfigurations?.projects[projectName]?.root
+        : undefined;
+    if (!projectName || !configured) {
+        throw new Error('SST lifecycle tool-owned source requires one exact Nx project root.');
+    }
+    return (0, sst_environment_source_js_1.captureSstEnvironmentSourceTree)({
+        projectRoot: (0, node_path_1.isAbsolute)(configured)
+            ? configured
+            : (0, node_path_1.join)(context.root, configured),
+        workspaceRoot: context.root,
+    });
+}
+function requiresSourceReconciliation(command, stage) {
+    return ((GOVERNED_STAGES.has(stage) ||
+        (command === 'remove' && /^personal-[a-f0-9]{24}$/.test(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 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);
+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,
+    });
+    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) {
@@ -52,11 +400,31 @@ 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;
-    return { ...sanitized, ...invocation };
+    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;
+    delete sanitized.EBK_NX_TASK_CLEANUP;
+    delete sanitized.EBK_NX_TASK_UNLOCK;
+    // Nx injects task identity, target, hash, terminal, cache, and invocation
+    // 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];
+        }
+    }
+    const childEnvironment = { ...sanitized, ...invocation };
+    delete childEnvironment.EBK_NX_TASK_UNLOCK;
+    return childEnvironment;
 }
 function assertSafeSstForwardedArguments(args) {
     const reserved = args.find((argument) => {
@@ -80,21 +448,39 @@ function resolveSstDevMode(environment, forwardedArguments = []) {
     }
     return requested;
 }
-function assertSstLifecyclePolicy(command, stage, environment = process.env) {
-    if (!PROTECTED_STAGES.has(stage))
+function assertSstLifecyclePolicy(command, stage, environment = process.env, deploymentProfile = 'fully-isolated') {
+    if (!GOVERNED_STAGES.has(stage))
         return;
     if (command === 'dev') {
         throw new Error(`SST dev is not permitted for protected stage ${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
@@ -104,14 +490,10 @@ function assertSstLifecyclePolicy(command, stage, environment = process.env) {
         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) {
@@ -165,7 +547,7 @@ function buildSstCommandInvocation(command, options, context, environment = proc
             }
             return {
                 consumerStage: (dependencies.personalStageResolver ??
-                    (0, personal_stage_js_1.createPersonalStageResolver)()).resolve().stage,
+                    (0, personal_stage_js_1.createPersonalStageResolver)()).resolve(context.root).stage,
                 foundationStage: 'development',
                 mapped: true,
             };
@@ -180,15 +562,138 @@ 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.`);
     }
-    assertSstLifecyclePolicy(command, stages.consumerStage, environment);
-    if (PROTECTED_STAGES.has(stages.consumerStage) &&
+    const taskCleanup = environment.EBK_NX_TASK_CLEANUP !== undefined;
+    const taskUnlock = environment.EBK_NX_TASK_UNLOCK !== undefined;
+    if (taskUnlock) {
+        if (taskCleanup ||
+            command !== 'unlock' ||
+            kind !== 'slice' ||
+            environment.GITHUB_ACTIONS === 'true' ||
+            options.args !== undefined ||
+            options.cwd !== undefined ||
+            options.target !== undefined ||
+            !stages.mapped ||
+            stages.foundationStage !== 'development') {
+            throw new Error('Task unlock is restricted to the current local Slice task.');
+        }
+        const task = (0, task_identity_js_1.resolveTaskIdentity)(context.root);
+        if (environment.EBK_NX_TASK_UNLOCK !== task.taskId ||
+            stages.consumerStage !== `personal-${task.taskId}`) {
+            throw new Error('Task unlock cannot select another task or stage.');
+        }
+        const source = (0, local_deploy_js_1.localWorkingTreeDigest)(context.root);
+        if (source.commit !== environment.EBK_SOURCE_COMMIT ||
+            source.digest !== environment.EBK_LOCAL_SOURCE_TREE) {
+            throw new Error('Task unlock requires the exact authorized source tree.');
+        }
+        (0, task_stack_absence_js_1.resolveStaticTaskApp)({
+            workspaceRoot: context.root,
+            projectRoot: cwd,
+            projectName: context.projectName ?? '',
+        });
+    }
+    else if (command === 'unlock' && stages.mapped) {
+        throw new Error('Personal task unlock requires the current-task governed adapter.');
+    }
+    if (taskCleanup) {
+        if (command !== 'remove' ||
+            kind !== 'slice' ||
+            environment.GITHUB_ACTIONS === 'true' ||
+            options.args !== undefined ||
+            options.cwd !== undefined ||
+            options.target !== undefined ||
+            !stages.mapped ||
+            stages.foundationStage !== 'development')
+            throw new Error('Task cleanup is restricted to the current local Slice task and native removal.');
+        const task = (0, task_identity_js_1.resolveTaskIdentity)(context.root);
+        if (environment.EBK_NX_TASK_CLEANUP !== task.taskId ||
+            stages.consumerStage !== `personal-${task.taskId}`) {
+            throw new Error('Task cleanup cannot select another task or stage.');
+        }
+    }
+    else if (command === 'remove' && stages.mapped) {
+        throw new Error('Personal task removal is owned by ebk dev down; canonical remove cannot select a task.');
+    }
+    const operatingPolicy = command === 'dev' ||
+        taskCleanup ||
+        taskUnlock ||
+        (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 authorityStage = command === 'dev' || taskCleanup || taskUnlock
+        ? 'development'
+        : stages.consumerStage;
+    const deploymentAccount = operatingPolicy
+        ? (0, index_js_2.configuredDeploymentAccountForStage)(operatingPolicy.deploymentProfile, operatingPolicy.deploymentAccounts, authorityStage)
+        : undefined;
+    const deploymentRegion = operatingPolicy
+        ? (0, index_js_2.configuredDeploymentRegion)(operatingPolicy.deploymentRegion)
+        : undefined;
+    if ((taskCleanup || taskUnlock) && deploymentAccount && deploymentRegion) {
+        // This read cannot create or reassign the binding. The executor separately
+        // verifies the current caller and Foundation owner before constructing SST.
+        const owner = (0, index_js_2.readRepositoryOperatingPolicy)(context.root);
+        (0, task_identity_js_1.assertCurrentTaskEnvironment)(context.root, {
+            accountId: deploymentAccount,
+            region: deploymentRegion,
+            workspaceDeploymentId: owner.workspaceDeploymentId,
+        });
+    }
+    if (deploymentRegion &&
+        options.region?.trim() &&
+        options.region.trim() !== deploymentRegion) {
+        throw new Error(`SST lifecycle Region ${options.region.trim()} differs from committed deployment Region ${deploymentRegion}.`);
+    }
+    if (options.expectedRoleArn !== undefined &&
+        !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)) {
+        throw new Error('SST lifecycle profile must be one non-empty exact AWS profile name up to 128 characters.');
+    }
+    if (operatingPolicy &&
+        environment.GITHUB_ACTIONS !== 'true' &&
+        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_4.assertWorkMarkerReport)((0, index_js_4.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: [
                 {
@@ -200,9 +705,8 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         })
         : undefined;
     const args = [command, '--stage', stages.consumerStage];
-    if (options.profile) {
-        args.push('--profile', options.profile);
-    }
+    if (command === 'refresh')
+        args.push('--yes');
     if (options.target) {
         args.push('--target', options.target);
     }
@@ -222,8 +726,29 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         ],
         cwd,
         environment: {
-            ...(options.region?.trim() ? { AWS_REGION: options.region.trim() } : {}),
+            ...(deploymentAccount
+                ? {
+                    AWS_EXPECTED_ACCOUNT_ID: deploymentAccount,
+                }
+                : {}),
+            ...(profile ? { AWS_PROFILE: profile } : {}),
+            ...(deploymentRegion
+                ? { AWS_REGION: deploymentRegion }
+                : options.region?.trim()
+                    ? { AWS_REGION: options.region.trim() }
+                    : {}),
             EBK_CONSUMER_STAGE: stages.consumerStage,
+            ...(taskCleanup
+                ? { EBK_NX_TASK_CLEANUP: environment.EBK_NX_TASK_CLEANUP }
+                : {}),
+            ...(taskUnlock
+                ? { EBK_NX_TASK_UNLOCK: environment.EBK_NX_TASK_UNLOCK }
+                : {}),
+            ...((committedRoleArn ?? options.expectedRoleArn?.trim())
+                ? {
+                    EBK_EXPECTED_DEPLOYMENT_ROLE_ARN: committedRoleArn ?? options.expectedRoleArn?.trim(),
+                }
+                : {}),
             EBK_FOUNDATION_STAGE: stages.foundationStage,
             ...(policyDecision?.effectiveProductionProfile
                 ? {
@@ -234,77 +759,261 @@ 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) {
+    // Standard Slices contain a Python infrastructure provisioner even when
+    // their application handlers are TypeScript. Fail before SST can partially
+    // create resources; recovery operations must remain available without build
+    // tooling. This is a local prerequisite, not a provider-plan gate.
+    if ((command === 'dev' || command === 'deploy') &&
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(invocation.cwd, 'pyproject.toml'))) {
+        const manifest = (0, node_fs_1.lstatSync)((0, node_path_1.join)(invocation.cwd, 'pyproject.toml'));
+        if (!manifest.isFile() || manifest.isSymbolicLink()) {
+            throw new Error('Python tooling manifest must be a regular project file.');
+        }
+        const childEnvironment = {};
+        for (const key of ['PATH', 'Path', 'PATHEXT', 'SystemRoot', 'SYSTEMROOT']) {
+            if (environment[key] !== undefined)
+                childEnvironment[key] = environment[key];
+        }
+        const result = (0, node_child_process_1.spawnSync)('uv', ['--version'], {
+            cwd: invocation.cwd,
+            env: childEnvironment,
+            encoding: 'utf8',
+            timeout: 5_000,
+            maxBuffer: 4_096,
+            windowsHide: true,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.error ||
+            result.status !== 0 ||
+            !/^uv \d+\.\d+\.\d+\b/.test(result.stdout ?? '')) {
+            // Do not surface arbitrary tool stderr or inherited credential material.
+            throw new Error(`Python tooling for ${context.projectName ?? 'the selected project'} requires uv on PATH. Install the workspace-documented uv version and retry the same EBK command. No SST child started.`);
+        }
     }
+    const stage = command === 'dev' ||
+        (command === 'remove' && invocation.environment.EBK_NX_TASK_CLEANUP) ||
+        (command === 'unlock' && invocation.environment.EBK_NX_TASK_UNLOCK)
+        ? 'development'
+        : invocation.environment.EBK_CONSUMER_STAGE;
+    await (dependencies.ownership ?? index_js_3.assertWorkspaceStageOwnershipForWorkspace)(context.root, stage, {
+        ...(environment.AWS_CONFIG_FILE
+            ? { configFilepath: environment.AWS_CONFIG_FILE }
+            : {}),
+        ...(environment.AWS_SHARED_CREDENTIALS_FILE
+            ? { credentialsFilepath: environment.AWS_SHARED_CREDENTIALS_FILE }
+            : {}),
+        ...(invocation.environment.AWS_PROFILE
+            ? { profile: invocation.environment.AWS_PROFILE }
+            : {}),
+    });
     if (command === 'deploy') {
+        if (environment.GITHUB_ACTIONS === 'true') {
+            await (dependencies.initializeSecrets ?? secret_initialize_js_1.initializeProtectedDeploymentSecrets)(stage, context, environment);
+        }
         await (dependencies.secrets ?? secret_preflight_js_1.preflightSliceSecretMetadata)(options, context, invocation);
     }
-    if (requiresInfrastructureBinding(command, invocation.environment.EBK_CONSUMER_STAGE)) {
-        await (dependencies.infrastructureAuthorization ??
-            authorizeInfrastructureMutation)(command, options, context, invocation);
+    if (command === 'unlock' &&
+        invocation.environment.EBK_EXPECTED_DEPLOYMENT_ROLE_ARN) {
+        await (dependencies.unlockAuthorization ?? authorizeLocalUnlock)(options, invocation, environment);
     }
 }
 async function runSstCommand(command, options, context, dependencies = {}) {
+    const environment = dependencies.environment ?? process.env;
+    if (command !== 'dev' &&
+        !(command === 'remove' && environment.EBK_NX_TASK_CLEANUP !== undefined) &&
+        !(command === 'unlock' && environment.EBK_NX_TASK_UNLOCK !== undefined)) {
+        assertGovernedAwsLifecyclePlatform(dependencies.platform);
+    }
+    const joinsGovernedProcessGroup = process.platform !== 'win32' &&
+        environment[GOVERNED_PROCESS_GROUP_ENV] === '1';
     let invocation;
+    let environmentSource;
+    let taskWriter;
     try {
-        invocation = buildSstCommandInvocation(command, options, context);
-        await runSstLifecyclePreflights(command, options, context, invocation, dependencies);
+        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, environment);
+        if (environmentSource)
+            (0, sst_environment_source_js_1.reconcileSstEnvironmentSourceTree)(environmentSource);
+        if (command === 'dev' ||
+            invocation.environment.EBK_NX_TASK_CLEANUP ||
+            invocation.environment.EBK_NX_TASK_UNLOCK) {
+            // Rebuild after asynchronous authorization: source, task owner, and
+            // committed account/Region must still agree immediately before spawn.
+            const current = buildSstCommandInvocation(command, options, context, environment);
+            if (JSON.stringify(current) !== JSON.stringify(invocation))
+                throw new Error('Task native invocation changed during preflight.');
+            taskWriter = (dependencies.acquireTaskWriter ?? task_native_writer_js_1.acquireTaskNativeWriterLease)(context, invocation.environment.EBK_CONSUMER_STAGE.slice('personal-'.length), command === 'unlock', dependencies.taskNativeWriterEffects);
+            taskWriter.assertCurrent();
+        }
     }
     catch (error) {
+        let restorationError;
+        try {
+            // No native child has been spawned during this preflight phase.
+            taskWriter?.release();
+        }
+        catch (releaseError) {
+            devkit_1.logger.error(`Task native writer preflight evidence retained: ${releaseError instanceof Error ? releaseError.message : String(releaseError)}`);
+        }
+        if (environmentSource) {
+            try {
+                (0, sst_environment_source_js_1.reconcileSstEnvironmentSourceTree)(environmentSource);
+            }
+            catch (candidate) {
+                restorationError = candidate;
+            }
+        }
         devkit_1.logger.error(error instanceof Error ? error.message : String(error));
+        if (restorationError !== undefined) {
+            devkit_1.logger.error(`Failed to restore SST tool-owned source after preflight: ${restorationError instanceof Error
+                ? restorationError.message
+                : String(restorationError)}`);
+        }
         return { success: false };
     }
     devkit_1.logger.info(`Running workspace SST: ${command} --stage ${invocation.environment.EBK_CONSUMER_STAGE} foundationStage=${invocation.environment.EBK_FOUNDATION_STAGE} (${invocation.cwd})`);
     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),
-            shell: false,
-            stdio: 'inherit',
-        });
+        let child;
+        try {
+            taskWriter?.assertCurrent();
+            child = (dependencies.spawnChild ?? node_child_process_1.spawn)(invocation.executable, invocation.args, {
+                cwd: invocation.cwd,
+                detached: process.platform !== 'win32' && !joinsGovernedProcessGroup,
+                env: createSstChildEnvironment(environment, invocation.environment),
+                shell: false,
+                stdio: 'inherit',
+            });
+        }
+        catch (error) {
+            try {
+                taskWriter?.release();
+            }
+            catch {
+                /* Keep ambiguous lease evidence. */
+            }
+            devkit_1.logger.error(error instanceof Error ? error.message : String(error));
+            resolve({ success: false });
+            return;
+        }
         let settled = false;
+        let cancellationSignal;
+        let writerRegistrationFailed = false;
+        let unregisterSignalCleanup = () => undefined;
+        let resolveChildSettled = () => undefined;
+        const childSettled = new Promise((resolveChild) => {
+            resolveChildSettled = resolveChild;
+        });
         const settle = (success) => {
             if (settled)
                 return;
             settled = true;
-            resolve({ success });
+            unregisterSignalCleanup();
+            resolveChildSettled();
+            try {
+                if (writerRegistrationFailed)
+                    throw new Error('Native child registration failed.');
+                taskWriter?.release();
+            }
+            catch (error) {
+                success = false;
+                devkit_1.logger.error(`Task native writer evidence retained: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            resolve({ success: success && !cancellationSignal });
         };
+        unregisterSignalCleanup = (0, federated_credential_transport_js_1.registerGovernedSignalCleanup)((signal) => {
+            if (settled)
+                return;
+            cancellationSignal ??= signal;
+            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 (code !== 0) {
-                devkit_1.logger.error(signal
-                    ? `SST ${command} terminated with signal ${signal}.`
-                    : `SST ${command} exited with status ${code ?? 'unknown'}.`);
+            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) {
+                    // The leader's exit is not evidence that its native writers ended.
+                    // Keep task lease receipts for explicit, owner-proven recovery.
+                    if (taskWriter)
+                        writerRegistrationFailed = true;
+                    devkit_1.logger.error('SST exited before its exact descendant process tree stopped.');
+                }
+            }
+            if (code !== 0 || cancellationSignal) {
+                devkit_1.logger.error(cancellationSignal
+                    ? `SST ${command} cancelled by ${cancellationSignal}.`
+                    : signal
+                        ? `SST ${command} terminated with signal ${signal}.`
+                        : `SST ${command} exited with status ${code ?? 'unknown'}.`);
                 if (command === 'deploy' || command === 'remove') {
                     devkit_1.logger.error(`If the stack is locked, run pnpm nx run ${context.projectName ?? '<project>'}:unlock --stage=${options.stage}.`);
                 }
             }
-            const applySucceeded = code === 0;
-            if (requiresInfrastructureBinding(command, invocation.environment.EBK_CONSUMER_STAGE)) {
+            let sourceRestored = true;
+            if (environmentSource) {
                 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.
-                    settle(applySucceeded && mutationEvidenceRetained);
+                    (0, sst_environment_source_js_1.reconcileSstEnvironmentSourceTree)(environmentSource);
                 }
                 catch (error) {
-                    devkit_1.logger.error(`Failed to retain infrastructure convergence: ${error instanceof Error ? error.message : String(error)}`);
-                    settle(false);
+                    sourceRestored = false;
+                    devkit_1.logger.error(`Failed to restore SST tool-owned source: ${error instanceof Error ? error.message : String(error)}`);
                 }
-                return;
             }
-            settle(applySucceeded);
+            const applySucceeded = code === 0 &&
+                !cancellationSignal &&
+                sourceRestored &&
+                !retainedProcessTree;
+            let generatedSecretRetirementSucceeded = true;
+            if (applySucceeded &&
+                command === 'remove' &&
+                !invocation.environment.EBK_NX_TASK_CLEANUP &&
+                projectKind(context) === 'slice') {
+                try {
+                    await (dependencies.generatedSecretRetirement ??
+                        generated_secret_retirement_js_1.retireGeneratedSecretsAfterSliceRemove)(options, context, invocation, { environment });
+                }
+                catch (error) {
+                    generatedSecretRetirementSucceeded = false;
+                    devkit_1.logger.error(`Generated stage-secret retirement failed after native Slice removal: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            settle(applySucceeded && generatedSecretRetirementSucceeded);
         });
+        if (taskWriter && child.pid) {
+            try {
+                taskWriter.recordChild(child.pid, !joinsGovernedProcessGroup);
+            }
+            catch (error) {
+                writerRegistrationFailed = true;
+                devkit_1.logger.error(`Task native child identity was not retained: ${error instanceof Error ? error.message : String(error)}`);
+                // Never leave an unrecorded writer running after a failed registration.
+                void stopExactGovernedProcessTree(child, 'SIGTERM', childSettled, () => settled, !joinsGovernedProcessGroup).catch((stopError) => {
+                    writerRegistrationFailed = true;
+                    devkit_1.logger.error(`Unregistered native child termination failed; writer evidence retained: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+                });
+            }
+        }
     });
 }
 //# sourceMappingURL=run-sst-command.js.map