stageflow 0.25.0 → 0.27.0

package/dist/mcp/getStartedTool.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { PACKAGE_VERSION } from "../package-meta.js";
+import { listPipelinesMultiProject, listTasksMultiProject } from "../config/multiProjectCatalog.js";
+import { resolveCatalogRoots } from "../config/resolveCatalogRoots.js";
+import { textResult } from "./toolResults.js";
+import { toolchainHealthMap } from "../preflight/toolchain.js";
+export function registerGetStartedTool(server, deps) {
+    server.registerTool("get_started", {
+        description: "First-run orientation for remote harnesses: host version, providers, toolchain hints, catalog roots with counts, and a three-call next_steps list. No arguments.",
+        inputSchema: z.object({}),
+    }, async () => {
+        const roots = await resolveCatalogRoots({
+            store: deps.store,
+            bootCwd: deps.cwd,
+        });
+        const pipelines = await listPipelinesMultiProject({
+            store: deps.store,
+            bootCwd: deps.cwd,
+        });
+        const tasks = await listTasksMultiProject({
+            store: deps.store,
+            bootCwd: deps.cwd,
+        });
+        const catalog_roots = roots.map((root) => ({
+            project_root: root.project_root,
+            kind: root.kind,
+            read_only: root.read_only,
+            pipeline_count: pipelines.items.filter((p) => p.project_root === root.project_root).length,
+            task_count: tasks.items.filter((t) => t.project_root === root.project_root)
+                .length,
+        }));
+        const firstRoot = catalog_roots.find((r) => r.kind === "seeded") ?? catalog_roots[0];
+        const samplePipeline = pipelines.items.find((p) => p.project_root === firstRoot?.project_root);
+        const sampleTask = tasks.items.find((t) => t.project_root === firstRoot?.project_root);
+        return textResult({
+            host: { version: PACKAGE_VERSION },
+            providers: deps.providerAuthContext
+                ? { note: "Use list_providers for status" }
+                : { configured: [] },
+            toolchain: toolchainHealthMap(),
+            catalog_roots,
+            next_steps: [
+                {
+                    tool: "list_pipelines",
+                    args: firstRoot ? { project_root: firstRoot.project_root } : {},
+                },
+                {
+                    tool: "list_tasks",
+                    args: firstRoot ? { project_root: firstRoot.project_root } : {},
+                },
+                {
+                    tool: "start_run",
+                    args: {
+                        ...(firstRoot ? { project_root: firstRoot.project_root } : {}),
+                        pipeline: samplePipeline?.path ?? "pipelines/demo.pipeline.yaml",
+                        task_path: sampleTask?.path ?? "tasks/demo.task.yaml",
+                    },
+                },
+            ],
+        });
+    });
+}

package/dist/mcp/readArtifact.d.ts

@@ -1,4 +1,15 @@
 import type { RunStore } from "../runstore/port.js";
+export declare function assertSafeRunId(runId: string): void;
+export declare const PATH_DENIED_MESSAGE = "Artifact path denied";
+export type ContainedPathMessages = {
+    relativeRequired: string;
+    escapes: string;
+    notFound: (relativePath: string) => string;
+    denied?: string;
+};
+export declare const CHECKOUT_PATH_MESSAGES: ContainedPathMessages;
+export declare function assertSafeRelativePath(relativePath: string, messages: ContainedPathMessages): string[];
+export declare function resolveContainedRelativePath(containerDir: string, relativePath: string, messages: ContainedPathMessages): Promise<string>;
 export declare function artifactMediaType(relativePath: string): string | undefined;
 export type ClassifiedArtifactContent = {
     kind: "image";

package/dist/mcp/readArtifact.js

@@ -1,8 +1,8 @@
 import { isUtf8 } from "node:buffer";
-import { readFile, realpath } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { isInsideDir } from "../runstore/workspaceLayout.js";
-function assertSafeRunId(runId) {
+import { classifyRealPathContainment } from "../runstore/workspaceLayout.js";
+export function assertSafeRunId(runId) {
     if (typeof runId !== "string" || runId.trim().length === 0) {
         throw new Error("runId must be a non-empty string");
     }
@@ -13,6 +13,48 @@ function assertSafeRunId(runId) {
         throw new Error("runId must not contain path separators or ..");
     }
 }
+export const PATH_DENIED_MESSAGE = "Artifact path denied";
+const ARTIFACT_MESSAGES = {
+    relativeRequired: "path must be relative to the run workspace",
+    escapes: "path escapes the run workspace",
+    notFound: (relativePath) => `Artifact not found: ${relativePath}`,
+    denied: PATH_DENIED_MESSAGE,
+};
+export const CHECKOUT_PATH_MESSAGES = {
+    relativeRequired: "path must be relative to the checkout",
+    escapes: "path escapes the checkout",
+    notFound: (relativePath) => `Checkout file not found: ${relativePath}`,
+    denied: PATH_DENIED_MESSAGE,
+};
+export function assertSafeRelativePath(relativePath, messages) {
+    if (typeof relativePath !== "string" || relativePath.trim().length === 0) {
+        throw new Error("path must be a non-empty string");
+    }
+    if (path.isAbsolute(relativePath)) {
+        throw new Error(messages.relativeRequired);
+    }
+    const segments = relativePath.split(/[/\\]/);
+    if (segments.some((segment) => segment === "..")) {
+        throw new Error("path must not contain .. segments");
+    }
+    if (segments.some((segment) => segment === ".pi-agent") ||
+        path.basename(relativePath) === "auth.json") {
+        throw new Error(messages.denied ?? PATH_DENIED_MESSAGE);
+    }
+    return segments;
+}
+export async function resolveContainedRelativePath(containerDir, relativePath, messages) {
+    assertSafeRelativePath(relativePath, messages);
+    const candidate = path.resolve(containerDir, relativePath);
+    const containment = await classifyRealPathContainment(candidate, containerDir);
+    if (containment.status === "missing") {
+        throw new Error(messages.notFound(relativePath));
+    }
+    if (containment.status === "outside") {
+        throw new Error(messages.escapes);
+    }
+    return containment.realPath;
+}
 export function artifactMediaType(relativePath) {
     const ext = path.extname(relativePath).toLowerCase();
     switch (ext) {
@@ -41,35 +83,9 @@ export function classifyArtifactContent(relativePath, bytes) {
 }
 async function resolveRunArtifactFile(store, runId, relativePath) {
     assertSafeRunId(runId);
-    if (typeof relativePath !== "string" || relativePath.trim().length === 0) {
-        throw new Error("path must be a non-empty string");
-    }
-    if (path.isAbsolute(relativePath)) {
-        throw new Error("path must be relative to the run workspace");
-    }
-    const segments = relativePath.split(/[/\\]/);
-    if (segments.some((segment) => segment === "..")) {
-        throw new Error("path must not contain .. segments");
-    }
-    if (segments.some((segment) => segment === ".pi-agent") ||
-        path.basename(relativePath) === "auth.json") {
-        throw new Error("Artifact path denied");
-    }
     await store.readRunMeta(runId);
     const workspaceDir = store.getWorkspaceDir(runId);
-    const workspaceReal = await realpath(workspaceDir);
-    const candidate = path.resolve(workspaceDir, relativePath);
-    let fileReal;
-    try {
-        fileReal = await realpath(candidate);
-    }
-    catch {
-        throw new Error(`Artifact not found: ${relativePath}`);
-    }
-    if (!isInsideDir(fileReal, workspaceReal)) {
-        throw new Error("path escapes the run workspace");
-    }
-    return fileReal;
+    return resolveContainedRelativePath(workspaceDir, relativePath, ARTIFACT_MESSAGES);
 }
 export async function readRunArtifact(store, runId, relativePath) {
     const fileReal = await resolveRunArtifactFile(store, runId, relativePath);

package/dist/mcp/server.js

@@ -38,6 +38,7 @@ function toolDepsFrom(deps) {
         manager: deps.manager,
         store: deps.store,
         cwd: deps.cwd,
+        ...(deps.agentDir !== undefined ? { agentDir: deps.agentDir } : {}),
         ...(deps.providerAuthContext !== undefined
             ? { providerAuthContext: deps.providerAuthContext }
             : {}),

package/dist/mcp/tools.js

@@ -1,14 +1,18 @@
 import { z } from "zod";
 import { registerCatalogTools } from "./catalogTools.js";
+import { registerCheckoutTools } from "./checkoutTools.js";
 import { registerControlTools } from "./controlTools.js";
 import { registerProjectMcpTools } from "./projectMcpTools.js";
 import { registerProviderTools } from "./providerTools.js";
 import { textResult } from "./toolResults.js";
 import { DEFAULT_TIMEOUT_MS, waitRun } from "./waitRun.js";
+import { registerGetStartedTool } from "./getStartedTool.js";
 export function registerMcpTools(server, deps) {
     const { store } = deps;
+    registerGetStartedTool(server, deps);
     registerCatalogTools(server, deps);
     registerControlTools(server, deps);
+    registerCheckoutTools(server, deps);
     registerProviderTools(server, deps);
     registerProjectMcpTools(server, deps);
     server.registerTool("wait_run", {

package/dist/net/proxy.d.ts

@@ -0,0 +1,14 @@
+export type ProxyInstallResult = {
+    installed: boolean;
+    httpProxyHost?: string;
+    httpsProxyHost?: string;
+    noProxy: string;
+};
+export declare function effectiveNoProxy(env: NodeJS.ProcessEnv, bindHosts?: readonly string[]): string;
+export declare function installProxyDispatcher(env?: NodeJS.ProcessEnv, options?: {
+    bindHosts?: readonly string[];
+    log?: (msg: string) => void;
+}): ProxyInstallResult;
+export declare function resetProxyDispatcherForTests(): void;
+export declare function buildEgressHealth(env?: NodeJS.ProcessEnv): Record<string, unknown>;
+export declare function proxyHealthFields(env?: NodeJS.ProcessEnv): Record<string, unknown>;

package/dist/net/proxy.js

@@ -0,0 +1,78 @@
+import { EnvHttpProxyAgent, setGlobalDispatcher } from "undici";
+import { stripUrlUserinfo } from "../logging/redact.js";
+let installed = false;
+function firstProxy(env) {
+    return (env.HTTPS_PROXY ||
+        env.https_proxy ||
+        env.HTTP_PROXY ||
+        env.http_proxy ||
+        undefined);
+}
+function parseProxyHost(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const u = new URL(raw);
+        return u.host;
+    }
+    catch {
+        return stripUrlUserinfo(raw);
+    }
+}
+export function effectiveNoProxy(env, bindHosts = ["127.0.0.1", "::1", "localhost"]) {
+    const existing = env.NO_PROXY ?? env.no_proxy ?? "";
+    const parts = existing
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const set = new Set(parts.map((p) => p.toLowerCase()));
+    for (const host of bindHosts) {
+        if (!set.has(host.toLowerCase())) {
+            parts.push(host);
+            set.add(host.toLowerCase());
+        }
+    }
+    return parts.join(",");
+}
+export function installProxyDispatcher(env = process.env, options = {}) {
+    const proxy = firstProxy(env);
+    if (!proxy) {
+        return { installed: false, noProxy: env.NO_PROXY ?? env.no_proxy ?? "" };
+    }
+    const noProxy = effectiveNoProxy(env, options.bindHosts);
+    process.env.NO_PROXY = noProxy;
+    if (!installed) {
+        setGlobalDispatcher(new EnvHttpProxyAgent({ noProxy }));
+        installed = true;
+        options.log?.(`Installed EnvHttpProxyAgent; appended loopback to NO_PROXY (${noProxy})`);
+    }
+    return {
+        installed: true,
+        httpProxyHost: parseProxyHost(env.HTTP_PROXY ?? env.http_proxy),
+        httpsProxyHost: parseProxyHost(env.HTTPS_PROXY ?? env.https_proxy),
+        noProxy,
+    };
+}
+export function resetProxyDispatcherForTests() {
+    installed = false;
+}
+export function buildEgressHealth(env = process.env) {
+    const httpSet = Boolean(env.HTTP_PROXY || env.http_proxy);
+    const httpsSet = Boolean(env.HTTPS_PROXY || env.https_proxy);
+    const noProxySet = Boolean(env.NO_PROXY || env.no_proxy);
+    const caSet = Boolean(env.NODE_EXTRA_CA_CERTS || env.SSL_CERT_FILE || env.REQUESTS_CA_BUNDLE);
+    const proxyHost = parseProxyHost(env.HTTPS_PROXY ?? env.https_proxy) ??
+        parseProxyHost(env.HTTP_PROXY ?? env.http_proxy) ??
+        null;
+    return {
+        http_proxy: httpSet ? "set" : "unset",
+        https_proxy: httpsSet ? "set" : "unset",
+        no_proxy: noProxySet ? "set" : "unset",
+        proxy_host: proxyHost,
+        extra_ca_certs: caSet ? "set" : "unset",
+        dispatcher_installed: installed,
+    };
+}
+export function proxyHealthFields(env = process.env) {
+    return buildEgressHealth(env);
+}

package/dist/package-meta.d.ts

@@ -1,2 +1,3 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.25.0";
+export declare const PACKAGE_VERSION = "0.27.0";
+export declare const BUILD_SHA: string;

package/dist/package-meta.js

@@ -1,2 +1,3 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.25.0";
+export const PACKAGE_VERSION = "0.27.0";
+export const BUILD_SHA = process.env.STAGEFLOW_BUILD_SHA ?? "unknown";

package/dist/preflight/bash.d.ts

@@ -0,0 +1,8 @@
+export type BashPreflightErrorCode = "bash_not_found";
+export declare class BashPreflightError extends Error {
+    readonly code: BashPreflightErrorCode;
+    constructor(message: string, code?: BashPreflightErrorCode);
+}
+/** Resolve `bash` on PATH (never hardcode /bin/bash). */
+export declare function resolveBashPath(env?: NodeJS.ProcessEnv): string;
+export declare function assertBashAvailable(env?: NodeJS.ProcessEnv): string;

package/dist/preflight/bash.js

@@ -0,0 +1,34 @@
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+export class BashPreflightError extends Error {
+    code;
+    constructor(message, code = "bash_not_found") {
+        super(message);
+        this.name = "BashPreflightError";
+        this.code = code;
+    }
+}
+function isExecutable(filePath) {
+    try {
+        accessSync(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve `bash` on PATH (never hardcode /bin/bash). */
+export function resolveBashPath(env = process.env) {
+    const pathValue = env.PATH ?? "";
+    const parts = pathValue.split(path.delimiter).filter((p) => p.length > 0);
+    for (const dir of parts) {
+        const candidate = path.join(dir, "bash");
+        if (isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    throw new BashPreflightError('bash was not found on PATH; Stageflow verify requires bash (install bash or fix PATH)', "bash_not_found");
+}
+export function assertBashAvailable(env = process.env) {
+    return resolveBashPath(env);
+}

package/dist/preflight/claudeRoot.d.ts

@@ -0,0 +1,11 @@
+export type ClaudeRootErrorCode = "claude_as_root";
+export declare class ClaudeRootError extends Error {
+    readonly code: ClaudeRootErrorCode;
+    readonly euid: number;
+    constructor(euid: number);
+}
+export declare function isEffectiveRoot(geteuid?: (() => number) | undefined): boolean;
+export declare function assertClaudeNotRoot(options: {
+    backendId: string | undefined;
+    geteuid?: (() => number) | undefined;
+}): void;

package/dist/preflight/claudeRoot.js

@@ -0,0 +1,23 @@
+export class ClaudeRootError extends Error {
+    code = "claude_as_root";
+    euid;
+    constructor(euid) {
+        super(`Claude backend cannot run as root (euid=${euid}). Use a non-root USER or docker --user.`);
+        this.name = "ClaudeRootError";
+        this.euid = euid;
+    }
+}
+export function isEffectiveRoot(geteuid = process.geteuid) {
+    if (typeof geteuid !== "function")
+        return false;
+    return geteuid() === 0;
+}
+export function assertClaudeNotRoot(options) {
+    if (options.backendId !== "claude")
+        return;
+    const geteuid = options.geteuid ?? process.geteuid;
+    if (isEffectiveRoot(geteuid)) {
+        const euid = typeof geteuid === "function" ? geteuid() : 0;
+        throw new ClaudeRootError(euid);
+    }
+}

package/dist/preflight/mcpCommands.d.ts

@@ -0,0 +1,8 @@
+export type McpCommandMissing = {
+    command: string;
+    serverName: string;
+};
+export declare function resolveCommandOnPath(command: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function findMissingMcpCommands(servers: Record<string, {
+    command?: string;
+}>, env?: NodeJS.ProcessEnv): McpCommandMissing[];

package/dist/preflight/mcpCommands.js

@@ -0,0 +1,36 @@
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+export function resolveCommandOnPath(command, env = process.env) {
+    if (command.includes("/") || command.includes("\\")) {
+        try {
+            accessSync(command, constants.X_OK);
+            return command;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const pathValue = env.PATH ?? "";
+    for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+        const candidate = path.join(dir, command);
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // continue
+        }
+    }
+    return undefined;
+}
+export function findMissingMcpCommands(servers, env = process.env) {
+    const missing = [];
+    for (const [serverName, server] of Object.entries(servers)) {
+        if (!server.command)
+            continue;
+        if (resolveCommandOnPath(server.command, env) === undefined) {
+            missing.push({ command: server.command, serverName });
+        }
+    }
+    return missing;
+}

package/dist/preflight/pipelinePreflight.d.ts

@@ -0,0 +1,40 @@
+import type { LoadedPipeline } from "../types/pipeline.js";
+import { type ToolRequirement } from "../config/toolRequires.js";
+import { type CheckToolchainOptions, type ToolchainCheckResult } from "./toolchain.js";
+export type PreflightCheckKind = "toolchain" | "secret" | "mcp";
+export type PreflightItem = {
+    kind: PreflightCheckKind;
+    status: "ok" | "missing_tool" | "tool_version_mismatch" | "unknown_version" | "secret_unavailable" | "stage.unknown_secret" | "stage.denied_secret" | "unresolved_var" | "missing_catalog" | "unknown_server" | "invalid_config" | "untrusted_config_origin";
+    tool?: string;
+    required?: string;
+    found?: string;
+    path?: string;
+    secret?: string;
+    stageId?: string;
+    server?: string;
+    message?: string;
+};
+export type PipelinePreflightResult = {
+    ok: boolean;
+    checks: PreflightItem[];
+    requirements: ToolRequirement[];
+    toolchain: ToolchainCheckResult;
+};
+export declare function checkStageSecretsPresence(loaded: LoadedPipeline, hostEnv?: NodeJS.ProcessEnv): PreflightItem[];
+export declare function checkStageMcpResolution(loaded: LoadedPipeline, options: {
+    projectRoot: string;
+    hostEnv?: NodeJS.ProcessEnv;
+}): Promise<PreflightItem[]>;
+export declare function runPipelinePreflight(loaded: LoadedPipeline, options: {
+    projectRoot: string;
+    hostEnv?: NodeJS.ProcessEnv;
+    toolchain?: CheckToolchainOptions;
+    /** When true (doctor --strict / explicit), unknown_version fails. */
+    strict?: boolean;
+    /** start_run: unknown_version passes; missing/mismatch fail. */
+    forStart?: boolean;
+}): Promise<PipelinePreflightResult>;
+export declare function preflightFailureCode(result: PipelinePreflightResult, options?: {
+    strict?: boolean;
+    forStart?: boolean;
+}): string | undefined;

package/dist/preflight/pipelinePreflight.js

@@ -0,0 +1,192 @@
+import { collectEffectiveRequires, } from "../config/toolRequires.js";
+import { resolveStageMcpServers, StageMcpError, } from "../config/resolveStageMcpServers.js";
+import { assertSecretPresent, loadSecretRegistry, SecretUnavailableError, } from "../runtime/stageSecrets.js";
+import { isForeverDeniedSecret } from "../runtime/stageEnvironment.js";
+import { checkToolchainRequirements, curatedStageEnv, } from "./toolchain.js";
+function toolchainItems(checks) {
+    return checks.map((c) => ({
+        kind: "toolchain",
+        status: c.status,
+        tool: c.tool,
+        required: c.required,
+        found: c.found,
+        path: c.path,
+    }));
+}
+export function checkStageSecretsPresence(loaded, hostEnv = process.env) {
+    const registry = loadSecretRegistry(hostEnv);
+    const items = [];
+    for (const stage of loaded.stages) {
+        for (const decl of stage.secrets ?? []) {
+            if (isForeverDeniedSecret(decl.name)) {
+                items.push({
+                    kind: "secret",
+                    status: "stage.denied_secret",
+                    secret: decl.name,
+                    stageId: stage.id,
+                    message: `secret "${decl.name}" is permanently denied`,
+                });
+                continue;
+            }
+            try {
+                assertSecretPresent(decl.name, registry, hostEnv);
+                items.push({
+                    kind: "secret",
+                    status: "ok",
+                    secret: decl.name,
+                    stageId: stage.id,
+                });
+            }
+            catch (err) {
+                if (err instanceof SecretUnavailableError) {
+                    items.push({
+                        kind: "secret",
+                        status: "secret_unavailable",
+                        secret: decl.name,
+                        stageId: stage.id,
+                        message: err.message,
+                    });
+                    continue;
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                if (message.startsWith("stage.unknown_secret")) {
+                    items.push({
+                        kind: "secret",
+                        status: "stage.unknown_secret",
+                        secret: decl.name,
+                        stageId: stage.id,
+                        message: `unknown secret "${decl.name}" is not in the Host secret registry`,
+                    });
+                    continue;
+                }
+                items.push({
+                    kind: "secret",
+                    status: "secret_unavailable",
+                    secret: decl.name,
+                    stageId: stage.id,
+                    message,
+                });
+            }
+        }
+    }
+    return items;
+}
+export async function checkStageMcpResolution(loaded, options) {
+    const hostEnv = options.hostEnv ?? process.env;
+    const stageEnv = { ...curatedStageEnv(hostEnv) };
+    const registry = loadSecretRegistry(hostEnv);
+    for (const stage of loaded.stages) {
+        for (const decl of stage.secrets ?? []) {
+            try {
+                assertSecretPresent(decl.name, registry, hostEnv);
+                const entry = registry.get(decl.name);
+                if (entry?.kind === "env") {
+                    const plain = hostEnv[decl.name];
+                    const fileKey = `${decl.name}_FILE`;
+                    const filePath = hostEnv[fileKey];
+                    if (plain !== undefined && plain.length > 0) {
+                        stageEnv[decl.name] = plain;
+                    }
+                    else if (filePath !== undefined && filePath.length > 0) {
+                        try {
+                            const { readFileSync } = await import("node:fs");
+                            stageEnv[decl.name] = readFileSync(filePath, "utf8").replace(/\r?\n$/, "");
+                        }
+                        catch {
+                            /* presence already checked */
+                        }
+                    }
+                }
+            }
+            catch {
+                /* secret presence reported separately */
+            }
+        }
+    }
+    const items = [];
+    for (const stage of loaded.stages) {
+        const allowlist = stage.mcp ?? [];
+        if (allowlist.length === 0)
+            continue;
+        try {
+            await resolveStageMcpServers({
+                projectRoot: options.projectRoot,
+                allowlist,
+                env: stageEnv,
+                stageId: stage.id,
+            });
+            for (const server of allowlist) {
+                items.push({
+                    kind: "mcp",
+                    status: "ok",
+                    server,
+                    stageId: stage.id,
+                });
+            }
+        }
+        catch (err) {
+            if (err instanceof StageMcpError) {
+                items.push({
+                    kind: "mcp",
+                    status: err.code,
+                    stageId: stage.id,
+                    message: err.message,
+                });
+                continue;
+            }
+            items.push({
+                kind: "mcp",
+                status: "invalid_config",
+                stageId: stage.id,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return items;
+}
+export async function runPipelinePreflight(loaded, options) {
+    const hostEnv = options.hostEnv ?? process.env;
+    const strict = options.strict === true;
+    const forStart = options.forStart === true;
+    const reqOutcome = collectEffectiveRequires({
+        pipelineRequires: loaded.pipeline.requires,
+        stageRequires: loaded.stages.map((s) => s.requires),
+        pipelineId: loaded.pipeline.id,
+    });
+    const requirements = reqOutcome.ok ? reqOutcome.value : [];
+    const toolchain = checkToolchainRequirements(requirements, {
+        ...options.toolchain,
+        env: hostEnv,
+        strict: forStart ? false : strict,
+        failOnUnknownVersion: forStart ? false : strict,
+    });
+    const secretChecks = checkStageSecretsPresence(loaded, hostEnv);
+    const mcpChecks = await checkStageMcpResolution(loaded, {
+        projectRoot: options.projectRoot,
+        hostEnv,
+    });
+    const checks = [
+        ...toolchainItems(toolchain.checks),
+        ...secretChecks,
+        ...mcpChecks,
+    ];
+    const ok = toolchain.ok &&
+        !secretChecks.some((c) => c.status !== "ok") &&
+        !mcpChecks.some((c) => c.status !== "ok");
+    return { ok, checks, requirements, toolchain };
+}
+export function preflightFailureCode(result, options = {}) {
+    for (const check of result.checks) {
+        if (check.status === "ok")
+            continue;
+        if (check.status === "unknown_version") {
+            if (options.forStart)
+                continue;
+            if (!options.strict)
+                continue;
+            return "unknown_version";
+        }
+        return check.status;
+    }
+    return undefined;
+}