stageflow 0.25.0 → 0.27.0

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,16 +1,36 @@
-import { resolveSkillByName } from "../config/listSkills.js";
+import { bindingKindForOrigin, catalogOrSeededOrigin, decideWorkspaceConfigTrust, } from "../config/configOrigin.js";
+import { resolveSkillByName, } from "../config/listSkills.js";
+import { loadHostConfig } from "../config/hostConfig.js";
+import { defaultSeededRoots } from "../config/seededCatalog.js";
+import { readFileSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
-import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError, resolveStageMcpServers, stampStagePromptArtifactsDir, } from "../config/resolveStageMcpServers.js";
+import { runSkillsDir } from "./runSkills.js";
+import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError, mcpCatalogExists, mcpCatalogPath, resolveStageMcpServers, stampStagePromptArtifactsDir, } from "../config/resolveStageMcpServers.js";
 import { attemptArtifactsDir, attemptStreamLogPath } from "../runstore/workspaceLayout.js";
 import { createStageStreamLogWriter, } from "./stageStreamLog.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
+import { collectMcpEnvNamedSecrets, patchRunManifest, redactMcpServers, sha256Digest, withSkillEntry, withStageMcpServers, withStageResolvedModel, } from "../runstore/runManifest.js";
+import { getNamedSecrets, registerNamedSecrets, } from "../logging/namedSecrets.js";
 import { assertPriorInputPayload, payloadInstanceMismatch, } from "../envelope/payloadSchema.js";
 import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
 import { assignment } from "./cloneSchedule.js";
 import { resumeSessionFilePath } from "./stageAttemptContext.js";
-import { buildStageRoots, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
-async function resolveStageSkillForRun(stage, catalog) {
+import { bindingKindFromMeta, buildStageRoots, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
+function resolveTrustWorkspaceConfig(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    try {
+        return loadHostConfig().trustWorkspaceConfig;
+    }
+    catch {
+        return [];
+    }
+}
+function seededRootPaths() {
+    return defaultSeededRoots().map((root) => root.path);
+}
+async function resolveStageSkillForRun(stage, catalog, options) {
     const name = stage.skill;
     if (name === undefined)
         return { ok: true };
@@ -20,44 +40,173 @@ async function resolveStageSkillForRun(stage, catalog) {
     const resolved = await resolveSkillByName(name, {
         cwd: catalog.cwd ?? process.cwd(),
         agentDir: catalog.agentDir,
+        runSkillsDir: runSkillsDir(options.workspaceDir),
+        ...(options.checkoutRoot !== undefined
+            ? { checkoutRoot: options.checkoutRoot }
+            : {}),
     });
     if (!resolved) {
         return { ok: false, reason: `Skill "${name}" is not installed` };
     }
-    return { ok: true, skillFilePath: resolved.filePath };
+    if (resolved.origin === "checkout") {
+        const decision = decideWorkspaceConfigTrust({
+            bindingKind: bindingKindForOrigin(options.bindingKind),
+            projectRoot: options.factoryCwd ?? options.checkoutRoot ?? "",
+            trustWorkspaceConfig: options.trustWorkspaceConfig,
+            source: "workspace",
+        });
+        if (!decision.allow) {
+            return {
+                ok: false,
+                reason: decision.code ?? "untrusted_config_origin",
+            };
+        }
+    }
+    return {
+        ok: true,
+        skillFilePath: resolved.filePath,
+        skillOrigin: resolved.origin,
+    };
 }
-async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir) {
+async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir, options) {
     const names = allowlist ?? [];
     if (names.length === 0)
-        return undefined;
-    if (factoryCwd === undefined) {
-        throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "missing_catalog");
+        return { servers: undefined, origins: [] };
+    const env = {
+        ...(options.stageEnv ?? {}),
+        [STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV]: artifactsDir,
+    };
+    const stageIdOpt = options.stageId !== undefined ? { stageId: options.stageId } : {};
+    const bindingKind = bindingKindForOrigin(options.bindingKind);
+    if (factoryCwd !== undefined && (await mcpCatalogExists(factoryCwd))) {
+        await mkdir(artifactsDir, { recursive: true });
+        const resolved = await resolveStageMcpServers({
+            projectRoot: factoryCwd,
+            allowlist: names,
+            env,
+            bindingKind,
+            trustWorkspaceConfig: options.trustWorkspaceConfig,
+            ...stageIdOpt,
+        });
+        const origin = catalogOrSeededOrigin(factoryCwd, seededRootPaths());
+        const catalogPath = mcpCatalogPath(factoryCwd);
+        return {
+            servers: Object.keys(resolved).length > 0 ? resolved : undefined,
+            origins: names.map((name) => ({
+                name,
+                origin,
+                path: catalogPath,
+            })),
+        };
     }
-    await mkdir(artifactsDir, { recursive: true });
-    const resolved = await resolveStageMcpServers({
-        projectRoot: factoryCwd,
-        allowlist: names,
-        env: {
-            ...process.env,
-            [STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV]: artifactsDir,
-        },
-    });
-    return Object.keys(resolved).length > 0 ? resolved : undefined;
+    const checkoutRoot = options.checkoutRoot;
+    if (checkoutRoot !== undefined &&
+        checkoutRoot !== factoryCwd &&
+        (await mcpCatalogExists(checkoutRoot))) {
+        await mkdir(artifactsDir, { recursive: true });
+        const resolved = await resolveStageMcpServers({
+            projectRoot: checkoutRoot,
+            allowlist: names,
+            env,
+            bindingKind,
+            trustWorkspaceConfig: options.trustWorkspaceConfig,
+            trustProjectRoot: factoryCwd ?? checkoutRoot,
+            workspaceSourced: true,
+            ...stageIdOpt,
+        });
+        const catalogPath = mcpCatalogPath(checkoutRoot);
+        return {
+            servers: Object.keys(resolved).length > 0 ? resolved : undefined,
+            origins: names.map((name) => ({
+                name,
+                origin: "workspace",
+                path: catalogPath,
+            })),
+        };
+    }
+    throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "missing_catalog");
 }
-async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, artifactsDir) {
-    const skill = await resolveStageSkillForRun(input.stage, catalog);
+function verifyCommandOrigins(dag, stageId, pipelinePath, factoryCwd) {
+    const completion = dag.nodes.find((node) => node.id === stageId)?.completion;
+    const origin = catalogOrSeededOrigin(factoryCwd, seededRootPaths());
+    const records = [];
+    for (const check of completion?.checks ?? []) {
+        if (check.type !== "command")
+            continue;
+        records.push({
+            name: check.id,
+            origin,
+            ...(pipelinePath !== undefined ? { path: pipelinePath } : {}),
+        });
+    }
+    return records;
+}
+async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, artifactsDir, resolveOptions) {
+    const skill = await resolveStageSkillForRun(input.stage, catalog, {
+        bindingKind: resolveOptions.bindingKind,
+        checkoutRoot: resolveOptions.checkoutRoot,
+        factoryCwd,
+        trustWorkspaceConfig: resolveOptions.trustWorkspaceConfig,
+        workspaceDir: resolveOptions.workspaceDir,
+    });
     if (!skill.ok)
         return skill;
     let resolvedMcpServers;
+    const origins = [];
     try {
-        resolvedMcpServers = await resolveAttemptMcpServers(input.stage.mcp, factoryCwd, artifactsDir);
+        const mcp = await resolveAttemptMcpServers(input.stage.mcp, factoryCwd, artifactsDir, {
+            checkoutRoot: resolveOptions.checkoutRoot,
+            bindingKind: resolveOptions.bindingKind,
+            trustWorkspaceConfig: resolveOptions.trustWorkspaceConfig,
+            stageEnv: resolveOptions.stageEnv,
+            stageId: input.stageId,
+        });
+        resolvedMcpServers = mcp.servers;
+        origins.push(...mcp.origins);
     }
     catch (err) {
         if (err instanceof StageMcpError) {
-            return { ok: false, reason: err.message };
+            return {
+                ok: false,
+                reason: err.code === "untrusted_config_origin" ? err.code : err.message,
+            };
         }
         throw err;
     }
+    origins.push(...verifyCommandOrigins(resolveOptions.dag, input.stageId ?? input.stage.id, resolveOptions.pipelinePath, factoryCwd));
+    if (origins.length > 0) {
+        await resolveOptions.store.appendConfigOrigins(resolveOptions.runId, origins);
+    }
+    const stageIdForManifest = input.stageId ?? input.stage.id;
+    if (resolvedMcpServers !== undefined) {
+        const mcpSecrets = collectMcpEnvNamedSecrets(resolvedMcpServers);
+        if (mcpSecrets.length > 0) {
+            registerNamedSecrets(mcpSecrets);
+        }
+        const originMap = new Map(origins
+            .filter((o) => o.name.length > 0)
+            .map((o) => [o.name, o.origin]));
+        const mcpServers = redactMcpServers(resolvedMcpServers, [...getNamedSecrets(), ...mcpSecrets], originMap);
+        await patchRunManifest(resolveOptions.store, resolveOptions.runId, (m) => withStageMcpServers(m, stageIdForManifest, mcpServers), [...getNamedSecrets(), ...mcpSecrets]).catch(() => null);
+    }
+    if (skill.skillOrigin !== undefined && skill.skillFilePath !== undefined) {
+        const skillName = input.stage.skill;
+        if (skillName !== undefined) {
+            let digest;
+            try {
+                digest = sha256Digest(readFileSync(skill.skillFilePath));
+            }
+            catch {
+                digest = sha256Digest(skill.skillFilePath);
+            }
+            await patchRunManifest(resolveOptions.store, resolveOptions.runId, (m) => withSkillEntry(m, {
+                name: skillName,
+                origin: skill.skillOrigin,
+                digest,
+                files: ["SKILL.md"],
+            })).catch(() => null);
+        }
+    }
     try {
         const handle = agent.openStage({
             ...input,
@@ -69,6 +218,14 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
                 ? { skillFilePath: skill.skillFilePath }
                 : {}),
             ...(resolvedMcpServers !== undefined ? { resolvedMcpServers } : {}),
+            onResolvedModel: async (info) => {
+                await patchRunManifest(resolveOptions.store, resolveOptions.runId, (m) => withStageResolvedModel(m, info.stageId, {
+                    model: info.model,
+                    ...(info.thinkingLevel !== undefined
+                        ? { thinkingLevel: info.thinkingLevel }
+                        : {}),
+                })).catch(() => null);
+            },
         });
         return { ok: true, handle };
     }
@@ -219,6 +376,9 @@ export async function openStageAttempt(input) {
         : runtimeNode?.feedback_loop;
     const repairContext = await repairContextForAttempt(input, stageId, attempt);
     const readQaTrail = createAttemptQaTrailReader(input.store, input.runId, stageId, attempt);
+    const meta = await input.store.readRunMeta(input.runId);
+    const bindingKind = input.bindingKind ?? bindingKindFromMeta(meta);
+    const trustWorkspaceConfig = resolveTrustWorkspaceConfig(input.trustWorkspaceConfig);
     const opened = await openStageWithOperatorCatalog(input.agent, {
         roots,
         stage: input.stage,
@@ -250,7 +410,17 @@ export async function openStageAttempt(input) {
         ...(input.stage.timeout_ms !== undefined
             ? { timeoutMs: input.stage.timeout_ms }
             : {}),
-    }, input.operatorCatalog, input.factoryCwd, attemptArtifactsDir(input.workspaceDir, stageId, attempt));
+    }, input.operatorCatalog, input.factoryCwd, attemptArtifactsDir(input.workspaceDir, stageId, attempt), {
+        checkoutRoot: input.checkoutRoot ?? meta.checkout_root,
+        bindingKind,
+        trustWorkspaceConfig,
+        stageEnv: input.stageEnv,
+        store: input.store,
+        runId: input.runId,
+        pipelinePath: meta.pipeline_path,
+        dag: input.dag,
+        workspaceDir: input.workspaceDir,
+    });
     if (!opened.ok)
         return opened;
     return {
@@ -258,5 +428,6 @@ export async function openStageAttempt(input) {
         handle: opened.handle,
         roots,
         prior: priorResult.prior,
+        ...(input.stageEnv !== undefined ? { stageEnv: input.stageEnv } : {}),
     };
 }

package/dist/runtime/stageCacheEnv.d.ts

@@ -0,0 +1,6 @@
+export declare function stageflowCacheRoot(home?: string): string;
+/** Compute cache env vars without creating directories (lazy create is separate). */
+export declare function computeCacheEnvVars(home?: string): Record<string, string>;
+/** Lazily create shared cache directories at first stage launch. */
+export declare function ensureStageCacheDirs(home?: string): Record<string, string>;
+export declare function resetStageCacheDirsForTests(): void;

package/dist/runtime/stageCacheEnv.js

@@ -0,0 +1,34 @@
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+export function stageflowCacheRoot(home = globalStageflowHome()) {
+    return path.join(home, "cache");
+}
+/** Compute cache env vars without creating directories (lazy create is separate). */
+export function computeCacheEnvVars(home = globalStageflowHome()) {
+    const cache = stageflowCacheRoot(home);
+    return {
+        STAGEFLOW_CACHE: cache,
+        npm_config_cache: path.join(cache, "npm"),
+        PNPM_STORE_DIR: path.join(cache, "pnpm"),
+        YARN_CACHE_FOLDER: path.join(cache, "yarn"),
+        UV_CACHE_DIR: path.join(cache, "uv"),
+        GOMODCACHE: path.join(cache, "go", "mod"),
+        CARGO_HOME: path.join(cache, "cargo"),
+    };
+}
+let cacheEnsured = false;
+/** Lazily create shared cache directories at first stage launch. */
+export function ensureStageCacheDirs(home = globalStageflowHome()) {
+    const vars = computeCacheEnvVars(home);
+    if (!cacheEnsured) {
+        for (const value of Object.values(vars)) {
+            mkdirSync(value, { recursive: true });
+        }
+        cacheEnsured = true;
+    }
+    return vars;
+}
+export function resetStageCacheDirsForTests() {
+    cacheEnsured = false;
+}

package/dist/runtime/stageConcurrency.d.ts

@@ -1,7 +1,8 @@
 export declare const UNLIMITED_CONCURRENCY: number;
 export declare const DEFAULT_MAX_ACTIVE_STAGES_PER_RUN: number;
 export declare const MAX_ACTIVE_STAGES_PER_RUN_ENV = "STAGEFLOW_MAX_ACTIVE_STAGES_PER_RUN";
-export declare const DEFAULT_MAX_ACTIVE_STAGE_PROCESSES: number;
+/** Fallback when cgroup is absent; finite so waitForCapacity is exercised. */
+export declare const DEFAULT_MAX_ACTIVE_STAGE_PROCESSES = 4;
 export declare const MAX_ACTIVE_STAGE_PROCESSES_ENV = "STAGEFLOW_MAX_ACTIVE_STAGE_PROCESSES";
 export declare const STAGE_EXECUTION_ENV = "STAGEFLOW_STAGE_EXECUTION";
 export type StageExecutionMode = "process" | "inprocess";

package/dist/runtime/stageConcurrency.js

@@ -1,7 +1,9 @@
+import { getContainerLimits } from "./containerLimits.js";
 export const UNLIMITED_CONCURRENCY = Number.POSITIVE_INFINITY;
 export const DEFAULT_MAX_ACTIVE_STAGES_PER_RUN = UNLIMITED_CONCURRENCY;
 export const MAX_ACTIVE_STAGES_PER_RUN_ENV = "STAGEFLOW_MAX_ACTIVE_STAGES_PER_RUN";
-export const DEFAULT_MAX_ACTIVE_STAGE_PROCESSES = UNLIMITED_CONCURRENCY;
+/** Fallback when cgroup is absent; finite so waitForCapacity is exercised. */
+export const DEFAULT_MAX_ACTIVE_STAGE_PROCESSES = 4;
 export const MAX_ACTIVE_STAGE_PROCESSES_ENV = "STAGEFLOW_MAX_ACTIVE_STAGE_PROCESSES";
 export const STAGE_EXECUTION_ENV = "STAGEFLOW_STAGE_EXECUTION";
 export function readStageExecutionMode(env = process.env, override) {
@@ -41,7 +43,7 @@ export function readMaxActiveStageProcesses(env = process.env, override) {
     }
     const raw = env[MAX_ACTIVE_STAGE_PROCESSES_ENV];
     if (raw === undefined || raw.trim() === "") {
-        return DEFAULT_MAX_ACTIVE_STAGE_PROCESSES;
+        return getContainerLimits().maxActiveStageProcesses;
     }
     const n = Number.parseInt(raw, 10);
     if (!Number.isFinite(n) || n < 1) {

package/dist/runtime/stageEnvironment.d.ts

@@ -0,0 +1,38 @@
+export declare const STAGE_ENV_PASSTHROUGH = "STAGEFLOW_STAGE_ENV_PASSTHROUGH";
+export declare const STAGE_ENV_ALLOW = "STAGEFLOW_STAGE_ENV_ALLOW";
+/** Names copied from Host when present (exact-name allowlist; no prefix wildcards). */
+export declare const STAGE_ENV_ALLOWLIST: readonly string[];
+/** Never grantable — even via secrets `as: env`. */
+export declare const FOREVER_DENIED_SECRET_NAMES: ReadonlySet<string>;
+/** Blocked from ambient / ALLOW / PASSTHROUGH; `as: env` grants may still inject. */
+export declare const AMBIENT_BLOCKED_ENV_NAMES: ReadonlySet<string>;
+/** Full denylist surface for docs and health (union of forever + ambient-blocked). */
+export declare const STAGE_ENV_DENYLIST: readonly string[];
+export type ResolvedStageGrants = {
+    env: Record<string, string>;
+    registeredSecretNames: readonly string[];
+    declaredSecretNames: readonly string[];
+};
+export type BuildStageEnvironmentInput = {
+    hostEnv: NodeJS.ProcessEnv;
+    runVars?: Record<string, string>;
+    cacheVars?: Record<string, string>;
+    grants?: ResolvedStageGrants;
+    /** Per-attempt empty HOME (KTD7). When set, overrides Host HOME. */
+    attemptHome?: string;
+    /** Package version for PASSTHROUGH deprecation text. */
+    packageVersion?: string;
+};
+export type BuildStageEnvironmentResult = {
+    env: Record<string, string>;
+    warnings: string[];
+    passthroughActive: boolean;
+};
+export declare function isForeverDeniedSecret(name: string): boolean;
+export declare function isAmbientBlockedEnv(name: string): boolean;
+/**
+ * Construct the stage child environment. Exact-name allowlist only — never a
+ * raw spread of Host env, and never a STAGEFLOW_* prefix passthrough.
+ */
+export declare function buildStageEnvironment(input: BuildStageEnvironmentInput): BuildStageEnvironmentResult;
+export declare function envNameSet(env: Record<string, string>): Set<string>;

package/dist/runtime/stageEnvironment.js

@@ -0,0 +1,193 @@
+import { SF_STAGE_WORKER } from "./stageWorkerProtocol.js";
+export const STAGE_ENV_PASSTHROUGH = "STAGEFLOW_STAGE_ENV_PASSTHROUGH";
+export const STAGE_ENV_ALLOW = "STAGEFLOW_STAGE_ENV_ALLOW";
+/** Names copied from Host when present (exact-name allowlist; no prefix wildcards). */
+export const STAGE_ENV_ALLOWLIST = [
+    "PATH",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "TERM",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "NODE_EXTRA_CA_CERTS",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+    "STAGEFLOW_HOME",
+];
+const PROVIDER_AND_CLOUD_NAMES = [
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENAI_API_KEY_FILE",
+    "GOOGLE_API_KEY",
+    "GEMINI_API_KEY",
+    "GROQ_API_KEY",
+    "MISTRAL_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "TOGETHER_API_KEY",
+    "FIREWORKS_API_KEY",
+    "PERPLEXITY_API_KEY",
+    "XAI_API_KEY",
+    "COHERE_API_KEY",
+    "OPENROUTER_API_KEY",
+    "AZURE_OPENAI_API_KEY",
+    "AWS_ACCESS_KEY_ID",
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "AWS_SECURITY_TOKEN",
+    "AWS_PROFILE",
+    "AWS_DEFAULT_REGION",
+    "AWS_REGION",
+    "GOOGLE_APPLICATION_CREDENTIALS",
+    "GCLOUD_PROJECT",
+    "AZURE_CLIENT_SECRET",
+    "AZURE_TENANT_ID",
+    "AZURE_CLIENT_ID",
+    "NPM_TOKEN",
+    "NODE_AUTH_TOKEN",
+    "SSH_AUTH_SOCK",
+    "SSH_AGENT_PID",
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+    "GITHUB_TOKEN_FILE",
+    "GH_TOKEN_FILE",
+];
+/** Never grantable — even via secrets `as: env`. */
+export const FOREVER_DENIED_SECRET_NAMES = new Set([
+    "STAGEFLOW_CONTROL_TOKEN",
+    "STAGEFLOW_CONTROL_TOKEN_FILE",
+    "STAGEFLOW_READ_TOKEN",
+    "STAGEFLOW_READ_TOKEN_FILE",
+]);
+/** Blocked from ambient / ALLOW / PASSTHROUGH; `as: env` grants may still inject. */
+export const AMBIENT_BLOCKED_ENV_NAMES = new Set([
+    ...FOREVER_DENIED_SECRET_NAMES,
+    ...PROVIDER_AND_CLOUD_NAMES,
+]);
+/** Full denylist surface for docs and health (union of forever + ambient-blocked). */
+export const STAGE_ENV_DENYLIST = [
+    ...FOREVER_DENIED_SECRET_NAMES,
+    ...PROVIDER_AND_CLOUD_NAMES,
+];
+function copyDefined(out, hostEnv, names) {
+    for (const name of names) {
+        const value = hostEnv[name];
+        if (value !== undefined && value !== "") {
+            out[name] = value;
+        }
+    }
+}
+export function isForeverDeniedSecret(name) {
+    if (FOREVER_DENIED_SECRET_NAMES.has(name))
+        return true;
+    return name.startsWith("STAGEFLOW_CONTROL_TOKEN_");
+}
+export function isAmbientBlockedEnv(name) {
+    return isForeverDeniedSecret(name) || AMBIENT_BLOCKED_ENV_NAMES.has(name);
+}
+function stripForeverDenied(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        if (isForeverDeniedSecret(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+function parseAllowList(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function passthroughDeprecationTarget(version) {
+    const parts = version.split(".").map((p) => Number.parseInt(p, 10));
+    const major = Number.isFinite(parts[0]) ? parts[0] : 0;
+    const minor = Number.isFinite(parts[1]) ? parts[1] : 0;
+    return `${major}.${minor + 2}.0`;
+}
+/**
+ * Construct the stage child environment. Exact-name allowlist only — never a
+ * raw spread of Host env, and never a STAGEFLOW_* prefix passthrough.
+ */
+export function buildStageEnvironment(input) {
+    const hostEnv = input.hostEnv;
+    const warnings = [];
+    const grants = input.grants ?? {
+        env: {},
+        registeredSecretNames: [],
+        declaredSecretNames: [],
+    };
+    const declared = new Set(grants.declaredSecretNames);
+    const registered = new Set(grants.registeredSecretNames);
+    const env = {};
+    copyDefined(env, hostEnv, STAGE_ENV_ALLOWLIST);
+    if (input.cacheVars) {
+        Object.assign(env, input.cacheVars);
+    }
+    if (input.runVars) {
+        Object.assign(env, input.runVars);
+    }
+    const allowNames = parseAllowList(hostEnv[STAGE_ENV_ALLOW]);
+    for (const name of allowNames) {
+        if (AMBIENT_BLOCKED_ENV_NAMES.has(name))
+            continue;
+        const value = hostEnv[name];
+        if (value !== undefined) {
+            env[name] = value;
+        }
+    }
+    const passthroughRaw = hostEnv[STAGE_ENV_PASSTHROUGH]?.trim();
+    const passthroughActive = passthroughRaw === "all";
+    if (passthroughActive) {
+        const version = input.packageVersion ?? "0.24.0";
+        const removeBy = passthroughDeprecationTarget(version);
+        warnings.push(`${STAGE_ENV_PASSTHROUGH}=all is deprecated and will be removed in ${removeBy}; prefer ${STAGE_ENV_ALLOW} or stage secrets:`);
+        for (const [key, value] of Object.entries(hostEnv)) {
+            if (value === undefined)
+                continue;
+            if (AMBIENT_BLOCKED_ENV_NAMES.has(key))
+                continue;
+            if (registered.has(key) && !declared.has(key))
+                continue;
+            if (key.endsWith("_FILE") &&
+                registered.has(key.slice(0, -"_FILE".length)) &&
+                !declared.has(key.slice(0, -"_FILE".length))) {
+                continue;
+            }
+            if (Object.hasOwn(env, key))
+                continue;
+            env[key] = value;
+        }
+    }
+    // Grants after ambient so explicit `as: env` can inject ambient-blocked names
+    // (e.g. GITHUB_TOKEN). Forever-denied names are stripped below.
+    Object.assign(env, grants.env);
+    if (input.attemptHome !== undefined) {
+        env.HOME = input.attemptHome;
+    }
+    env[SF_STAGE_WORKER] = "1";
+    return {
+        env: stripForeverDenied(env),
+        warnings,
+        passthroughActive,
+    };
+}
+export function envNameSet(env) {
+    return new Set(Object.keys(env));
+}

package/dist/runtime/stageProcessLauncher.d.ts

@@ -1,4 +1,8 @@
+import * as childProcess from "node:child_process";
+import { type Logger } from "../logging/logger.js";
+import { type ResolvedStageGrants } from "./stageEnvironment.js";
 import type { OperatorCatalog } from "./stageAttemptBootstrap.js";
+import { type DerivedBindingKind } from "./stageRoots.js";
 export type StageLaunchInput = {
     runId: string;
     stageId: string;
@@ -9,6 +13,10 @@ export type StageLaunchInput = {
     sessionFilePath?: string;
     operatorCatalog?: OperatorCatalog;
     skipGates?: boolean;
+    env?: Record<string, string>;
+    bindingKind?: DerivedBindingKind;
+    grants?: ResolvedStageGrants;
+    attemptHome?: string;
 };
 export type StageLaunchResult = {
     type: "succeeded";
@@ -27,17 +35,27 @@ export type StageProcessLauncherOptions = {
     maxActiveStageProcesses?: number;
     env?: Record<string, string | undefined>;
     cliEntry?: string;
+    logger?: Logger;
+    /** Test seam: override child_process.fork. */
+    forkFn?: typeof childProcess.fork;
 };
+export declare function signalProcessGroup(pid: number | undefined, signal: NodeJS.Signals): void;
 export declare class StageProcessLauncher {
     private readonly maxActive;
     private readonly env;
+    private readonly explicitChildExtras;
     private readonly cliEntry;
+    private readonly logger;
+    private readonly forkFn;
     private readonly active;
     private readonly waitQueue;
+    private readonly cancelledRuns;
     private slotsHeld;
+    private readonly heapMb;
     constructor(options?: StageProcessLauncherOptions);
     activeCount(): number;
     getActiveStageProcesses(): ActiveStageProcess[];
+    signalAllActive(signal: NodeJS.Signals): void;
     launch(input: StageLaunchInput): Promise<StageLaunchResult>;
     cancelRun(runId: string, killAfterMs?: number): Promise<void>;
     private waitForCapacity;