stageflow 0.25.0 → 0.27.0

package/dist/config/resolveModel.d.ts

@@ -8,6 +8,12 @@ export type ModelSelection = {
     /** Stage yaml / inline `model`; overrides pipeline/global. */
     stage?: string;
 };
+export type ModelAuthoredTier = "stage" | "pipeline" | "global";
+export type ResolvedModelSelection = {
+    model: string;
+    tier: ModelAuthoredTier;
+};
+export declare function modelAuthoredTier(selection: ModelSelection): ModelAuthoredTier;
 /**
  * stage > pipeline > global. No silent hardcoded fallback — unset is a load error.
  * Present-but-empty / whitespace follows parseModelField (load failure, not "").
@@ -15,6 +21,6 @@ export type ModelSelection = {
 export declare function resolveModelOutcome(selection: ModelSelection, ctx: {
     stageId: string;
     pipelineId: string;
-}): LoadOutcome<string>;
+}): LoadOutcome<ResolvedModelSelection>;
 /** The global tier's model id from an already-loaded manifest, or undefined when missing/unset. */
 export declare function globalModelFromManifest(loaded: LoadedManifest | null): string | undefined;

package/dist/config/resolveModel.js

@@ -1,5 +1,12 @@
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { parseModelField } from "./modelField.js";
+export function modelAuthoredTier(selection) {
+    if (selection.stage !== undefined)
+        return "stage";
+    if (selection.pipeline !== undefined)
+        return "pipeline";
+    return "global";
+}
 /**
  * stage > pipeline > global. No silent hardcoded fallback — unset is a load error.
  * Present-but-empty / whitespace follows parseModelField (load failure, not "").
@@ -27,7 +34,10 @@ export function resolveModelOutcome(selection, ctx) {
             },
         ]);
     }
-    return loadSuccess(parsed.value);
+    return loadSuccess({
+        model: parsed.value,
+        tier: modelAuthoredTier(selection),
+    });
 }
 /** The global tier's model id from an already-loaded manifest, or undefined when missing/unset. */
 export function globalModelFromManifest(loaded) {

package/dist/config/resolveStageMcpServers.d.ts

@@ -1,4 +1,4 @@
-export type StageMcpErrorCode = "missing_catalog" | "unknown_server" | "reserved_name" | "unresolved_var" | "invalid_config" | "connect_failed";
+export type StageMcpErrorCode = "missing_catalog" | "unknown_server" | "reserved_name" | "unresolved_var" | "invalid_config" | "untrusted_config_origin" | "connect_failed";
 export declare class StageMcpError extends Error {
     readonly code: StageMcpErrorCode;
     constructor(message: string, code: StageMcpErrorCode);
@@ -15,6 +15,7 @@ export type InspectedMcpCatalog = {
 };
 export declare function mcpCatalogPath(projectRoot: string): string;
 export declare function parseMcpCatalog(raw: string, catalogPath?: string): McpCatalogServers;
+export declare function mcpCatalogExists(projectRoot: string): Promise<boolean>;
 export declare function loadMcpCatalog(projectRoot: string): Promise<InspectedMcpCatalog>;
 export type ProjectMcpCatalogTransport = "stdio" | "http";
 export type ProjectMcpCatalogEntry = {
@@ -32,4 +33,11 @@ export declare function resolveStageMcpServers(options: {
     projectRoot: string;
     allowlist?: readonly string[];
     env: NodeJS.ProcessEnv;
+    stageId?: string;
+    bindingKind?: "repository" | "checkout" | "none";
+    trustWorkspaceConfig?: string[];
+    /** Host project root used for trust_workspace_config allowlist matching. */
+    trustProjectRoot?: string;
+    /** When true, .mcp.json is treated as workspace-sourced. */
+    workspaceSourced?: boolean;
 }): Promise<ResolvedMcpServers>;

package/dist/config/resolveStageMcpServers.js

@@ -51,6 +51,18 @@ export function parseMcpCatalog(raw, catalogPath = MCP_CATALOG_FILENAME) {
     }
     return servers;
 }
+export async function mcpCatalogExists(projectRoot) {
+    try {
+        await readFile(mcpCatalogPath(projectRoot), "utf8");
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
 export async function loadMcpCatalog(projectRoot) {
     const catalogPath = mcpCatalogPath(projectRoot);
     let raw;
@@ -108,7 +120,7 @@ export function assertMcpAllowlistKnown(servers, allowlist) {
 const INTERPOLATION_TOKEN = /\$\{([^}]*)\}/g;
 const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ENV_VAR_WITH_DEFAULT = /^([A-Za-z_][A-Za-z0-9_]*):-(.*)$/;
-function interpolateString(value, env, serverName) {
+function interpolateString(value, env, serverName, stageId) {
     return value.replace(INTERPOLATION_TOKEN, (_match, inner) => {
         const withDefault = ENV_VAR_WITH_DEFAULT.exec(inner);
         if (withDefault) {
@@ -120,24 +132,27 @@ function interpolateString(value, env, serverName) {
             if (found !== undefined) {
                 return found;
             }
-            throw new StageMcpError(`Unresolved MCP catalog variable "${inner}"`, "unresolved_var");
+            const stagePart = stageId !== undefined ? ` (stage "${stageId}")` : "";
+            throw new StageMcpError(`Unresolved MCP catalog variable "${inner}" for server "${serverName}"${stagePart}. Declare it in secrets: (use as: env for tokens needed in MCP env) or use \${${inner}:-default}.`, "unresolved_var");
         }
         throw new StageMcpError(`MCP catalog server "${serverName}" has an invalid interpolation form`, "invalid_config");
     });
 }
-function interpolateField(key, value, env, serverName) {
+function interpolateField(key, value, env, serverName, stageId) {
     if ((key === "command" || key === "url" || key === "cwd") && typeof value === "string") {
-        return interpolateString(value, env, serverName);
+        return interpolateString(value, env, serverName, stageId);
     }
     if (key === "args" && Array.isArray(value)) {
-        return value.map((item) => typeof item === "string" ? interpolateString(item, env, serverName) : item);
+        return value.map((item) => typeof item === "string"
+            ? interpolateString(item, env, serverName, stageId)
+            : item);
     }
     if ((key === "env" || key === "headers") && isPlainObject(value)) {
         const copied = {};
         for (const [field, fieldValue] of Object.entries(value)) {
             copied[field] =
                 typeof fieldValue === "string"
-                    ? interpolateString(fieldValue, env, serverName)
+                    ? interpolateString(fieldValue, env, serverName, stageId)
                     : fieldValue;
         }
         return copied;
@@ -185,10 +200,10 @@ function stampSpawnRoot(resolved, projectRoot, serverName) {
     }
     return resolved;
 }
-function interpolateServer(entry, env, serverName, projectRoot) {
+function interpolateServer(entry, env, serverName, projectRoot, stageId) {
     const resolved = {};
     for (const [key, value] of Object.entries(entry)) {
-        resolved[key] = interpolateField(key, value, env, serverName);
+        resolved[key] = interpolateField(key, value, env, serverName, stageId);
     }
     return stampSpawnRoot(resolved, projectRoot, serverName);
 }
@@ -197,11 +212,23 @@ export async function resolveStageMcpServers(options) {
     if (allowlist.length === 0) {
         return {};
     }
+    if (options.workspaceSourced === true) {
+        const { decideWorkspaceConfigTrust } = await import("./configOrigin.js");
+        const decision = decideWorkspaceConfigTrust({
+            bindingKind: options.bindingKind ?? "none",
+            projectRoot: options.trustProjectRoot ?? options.projectRoot,
+            trustWorkspaceConfig: options.trustWorkspaceConfig,
+            source: "workspace",
+        });
+        if (!decision.allow) {
+            throw new StageMcpError(decision.message ?? "untrusted_config_origin", "untrusted_config_origin");
+        }
+    }
     const catalog = await loadMcpCatalog(options.projectRoot);
     assertMcpAllowlistKnown(catalog.servers, allowlist);
     const resolved = {};
     for (const name of allowlist) {
-        resolved[name] = interpolateServer(catalog.servers[name], options.env, name, options.projectRoot);
+        resolved[name] = interpolateServer(catalog.servers[name], options.env, name, options.projectRoot, options.stageId);
     }
     return resolved;
 }

package/dist/config/secretFromEnvOrFile.d.ts

@@ -0,0 +1,9 @@
+export declare class SecretFromEnvError extends Error {
+    readonly code = "config_invalid";
+    constructor(message: string);
+}
+/**
+ * Read a secret from `NAME` or `NAME_FILE`. Both set → error.
+ * File values trim exactly one trailing newline (`\n` or `\r\n`).
+ */
+export declare function readSecretFromEnvOrFile(env: NodeJS.ProcessEnv, name: string): string | undefined;

package/dist/config/secretFromEnvOrFile.js

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+export class SecretFromEnvError extends Error {
+    code = "config_invalid";
+    constructor(message) {
+        super(message);
+        this.name = "SecretFromEnvError";
+    }
+}
+/**
+ * Read a secret from `NAME` or `NAME_FILE`. Both set → error.
+ * File values trim exactly one trailing newline (`\n` or `\r\n`).
+ */
+export function readSecretFromEnvOrFile(env, name) {
+    const fileKey = `${name}_FILE`;
+    const plain = env[name];
+    const filePath = env[fileKey];
+    const hasPlain = plain !== undefined && plain.length > 0;
+    const hasFile = filePath !== undefined && filePath.length > 0;
+    if (hasPlain && hasFile) {
+        throw new SecretFromEnvError(`Set only one of ${name} or ${fileKey}, not both`);
+    }
+    if (hasFile) {
+        try {
+            return readFileSync(filePath, "utf8").replace(/\r?\n$/, "");
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new SecretFromEnvError(`Failed to read ${fileKey}=${filePath}: ${detail}`);
+        }
+    }
+    if (hasPlain)
+        return plain;
+    return undefined;
+}

package/dist/config/seededCatalog.d.ts

@@ -0,0 +1,11 @@
+/** Symbolic wire id for the packaged examples catalog root. */
+export declare const SEEDED_EXAMPLES_ID = "examples";
+/**
+ * Absolute path to packaged `examples/` when present next to the package root.
+ * Does not git-init; callers build CatalogContext with fixed projectRoot + manifest.
+ */
+export declare function resolveSeededExamplesPath(fromUrl?: string): string | undefined;
+export declare function defaultSeededRoots(): Array<{
+    id: string;
+    path: string;
+}>;

package/dist/config/seededCatalog.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+/** Symbolic wire id for the packaged examples catalog root. */
+export const SEEDED_EXAMPLES_ID = "examples";
+/**
+ * Absolute path to packaged `examples/` when present next to the package root.
+ * Does not git-init; callers build CatalogContext with fixed projectRoot + manifest.
+ */
+export function resolveSeededExamplesPath(fromUrl = import.meta.url) {
+    const here = path.dirname(fileURLToPath(fromUrl));
+    const candidates = [
+        path.resolve(here, "../../examples"),
+        path.resolve(here, "../../../examples"),
+        path.resolve(process.cwd(), "examples"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(path.join(candidate, "README.md"))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+export function defaultSeededRoots() {
+    const examples = resolveSeededExamplesPath();
+    if (examples === undefined)
+        return [];
+    return [{ id: SEEDED_EXAMPLES_ID, path: examples }];
+}

package/dist/config/toolRequires.d.ts

@@ -0,0 +1,24 @@
+import { type LoadOutcome } from "./loadOutcome.js";
+export type ToolRequirement = {
+    tool: string;
+    version?: string;
+};
+export declare function parseToolRequires(raw: unknown, label: string, options: {
+    code: "pipeline.invalid_requires" | "stage.invalid_requires";
+    category: "pipeline" | "stage";
+    pipelineId?: string;
+    stageId?: string;
+}): LoadOutcome<ToolRequirement[] | undefined>;
+/**
+ * Merge requirement lists: same tool → intersect version ranges (stricter).
+ * Non-intersecting ranges fail with pipeline.requires_conflict.
+ */
+export declare function mergeToolRequires(lists: Array<readonly ToolRequirement[] | undefined>, ctx: {
+    pipelineId: string;
+    label?: string;
+}): LoadOutcome<ToolRequirement[]>;
+export declare function collectEffectiveRequires(options: {
+    pipelineRequires?: readonly ToolRequirement[];
+    stageRequires: Array<readonly ToolRequirement[] | undefined>;
+    pipelineId: string;
+}): LoadOutcome<ToolRequirement[]>;

package/dist/config/toolRequires.js

@@ -0,0 +1,115 @@
+import semver from "semver";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+const ALLOWED_KEYS = new Set(["tool", "version"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiresIssue(options, message) {
+    if (options.category === "pipeline") {
+        return {
+            code: options.code,
+            message,
+            category: "pipeline",
+            ...(options.pipelineId !== undefined
+                ? { pipelineId: options.pipelineId }
+                : {}),
+            ...(options.stageId !== undefined ? { stageId: options.stageId } : {}),
+        };
+    }
+    return {
+        code: options.code,
+        message,
+        category: "stage",
+        ...(options.stageId !== undefined ? { stageId: options.stageId } : {}),
+    };
+}
+export function parseToolRequires(raw, label, options) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!Array.isArray(raw)) {
+        return loadFailure([
+            requiresIssue(options, `Invalid ${label}: requires must be an array of { tool, version? }`),
+        ]);
+    }
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (!isPlainObject(item)) {
+            return loadFailure([
+                requiresIssue(options, `Invalid ${label}: requires[${i}] must be an object`),
+            ]);
+        }
+        for (const key of Object.keys(item)) {
+            if (!ALLOWED_KEYS.has(key)) {
+                return loadFailure([
+                    requiresIssue(options, `Invalid ${label}: requires[${i}] unknown key "${key}" (allowed: tool, version)`),
+                ]);
+            }
+        }
+        if (typeof item.tool !== "string" || item.tool.trim() === "") {
+            return loadFailure([
+                requiresIssue(options, `Invalid ${label}: requires[${i}].tool must be a non-empty string`),
+            ]);
+        }
+        const tool = item.tool.trim();
+        if (item.version !== undefined) {
+            if (typeof item.version !== "string" || item.version.trim() === "") {
+                return loadFailure([
+                    requiresIssue(options, `Invalid ${label}: requires[${i}].version must be a non-empty semver range string`),
+                ]);
+            }
+            const range = item.version.trim();
+            if (!semver.validRange(range)) {
+                return loadFailure([
+                    requiresIssue(options, `Invalid ${label}: requires[${i}].version "${range}" is not a valid semver range`),
+                ]);
+            }
+            out.push({ tool, version: range });
+        }
+        else {
+            out.push({ tool });
+        }
+    }
+    return loadSuccess(out);
+}
+/**
+ * Merge requirement lists: same tool → intersect version ranges (stricter).
+ * Non-intersecting ranges fail with pipeline.requires_conflict.
+ */
+export function mergeToolRequires(lists, ctx) {
+    const byTool = new Map();
+    for (const list of lists) {
+        if (!list)
+            continue;
+        for (const req of list) {
+            const prior = byTool.get(req.tool);
+            if (!byTool.has(req.tool)) {
+                byTool.set(req.tool, req.version);
+                continue;
+            }
+            if (prior === undefined && req.version === undefined)
+                continue;
+            if (prior === undefined) {
+                byTool.set(req.tool, req.version);
+                continue;
+            }
+            if (req.version === undefined)
+                continue;
+            if (!semver.intersects(prior, req.version)) {
+                return loadFailure([
+                    {
+                        code: "pipeline.requires_conflict",
+                        message: `Pipeline ${ctx.pipelineId}${ctx.label ? ` (${ctx.label})` : ""}: tool "${req.tool}" has non-intersecting version ranges "${prior}" and "${req.version}"`,
+                        category: "pipeline",
+                        pipelineId: ctx.pipelineId,
+                    },
+                ]);
+            }
+            byTool.set(req.tool, `${prior} ${req.version}`);
+        }
+    }
+    return loadSuccess([...byTool.entries()].map(([tool, version]) => version !== undefined ? { tool, version } : { tool }));
+}
+export function collectEffectiveRequires(options) {
+    return mergeToolRequires([options.pipelineRequires, ...options.stageRequires], { pipelineId: options.pipelineId });
+}

package/dist/config/validateCatalog.d.ts

@@ -2,7 +2,7 @@ import type { InlinePipelineDefinition, LoadedPipeline } from "../types/pipeline
 import type { LoadIssue } from "./loadOutcome.js";
 export type ValidationSeverity = "error" | "warning";
 export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.invalid_completion" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.invalid_completion" | "catalog.path_case_mismatch" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "pipeline.invalid_requires" | "pipeline.requires_conflict" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_secrets" | "stage.unknown_secret" | "stage.denied_secret" | "stage.invalid_requires" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mcp_command_missing" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml" | "catalog.stageflow_home_absolute_path";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;
@@ -35,6 +35,10 @@ export declare function effectiveSeverity(finding: ValidationFinding, strict: bo
 export declare function buildValidationResult(scope: ValidationScope, findings: ValidationFinding[], strict: boolean): ValidationResult;
 export declare function findingsFromLoadIssues(cwd: string, absPath: string, issues: LoadIssue[]): ValidationFinding[];
 export declare function findingStageIdFilenameMismatch(cwd: string, absPath: string, fileStem: string, declaredId: string): ValidationFinding;
+/** Parent readdir case check — warn by default; error under --strict. */
+export declare function findingPathCaseMismatch(cwd: string, referencedPath: string): Promise<ValidationFinding | null>;
+export declare function collectAbsolutePathCandidates(text: string): string[];
+export declare function isPathUnderStageflowHome(candidate: string, home: string): boolean;
 export type ValidatePipelineOptions = {
     cwd?: string;
     projectRoot?: string;

package/dist/config/validateCatalog.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { INLINE_PIPELINE_PATH, loadPipelineFromObjectOutcome, loadPipelineOutcome, resolvePipelinePath, } from "./loadPipeline.js";
 import { loadStageOutcome } from "./loadStage.js";
 import { loadTaskOutcome } from "./loadTask.js";
@@ -7,6 +8,9 @@ import { resolveCatalogContext } from "./resolveCatalogContext.js";
 import { getCatalogScanPaths } from "./browseCatalog.js";
 import { manifestPathForProject } from "./loadStageflowManifest.js";
 import { MCP_CATALOG_FILENAME, StageMcpError, assertMcpAllowlistKnown, loadMcpCatalog, mcpCatalogPath, } from "./resolveStageMcpServers.js";
+import { loadSecretRegistry } from "../runtime/stageSecrets.js";
+import { isForeverDeniedSecret } from "../runtime/stageEnvironment.js";
+import { findMissingMcpCommands } from "../preflight/mcpCommands.js";
 export function relPath(cwd, absPath) {
     return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
@@ -160,6 +164,35 @@ export function findingStageIdFilenameMismatch(cwd, absPath, fileStem, declaredI
         stageId: declaredId,
     }, "error");
 }
+/** Parent readdir case check — warn by default; error under --strict. */
+export async function findingPathCaseMismatch(cwd, referencedPath) {
+    const { readdir } = await import("node:fs/promises");
+    const abs = path.isAbsolute(referencedPath)
+        ? referencedPath
+        : path.resolve(cwd, referencedPath);
+    const parent = path.dirname(abs);
+    const base = path.basename(abs);
+    let entries;
+    try {
+        entries = await readdir(parent);
+    }
+    catch {
+        return null;
+    }
+    const exact = entries.includes(base);
+    if (exact)
+        return null;
+    const match = entries.find((e) => e.toLowerCase() === base.toLowerCase());
+    if (match === undefined)
+        return null;
+    return baseFinding({
+        cwd,
+        absPath: abs,
+        message: `Path casing differs on disk: referenced "${base}" but found "${match}"`,
+        code: "catalog.path_case_mismatch",
+        category: "catalog",
+    }, "warning");
+}
 async function checkStageIdFilename(cwd, stagePath) {
     const fileStem = path.basename(stagePath, ".yaml");
     try {
@@ -197,6 +230,100 @@ function collectMcpAllowlistNames(loaded) {
     }
     return [...names];
 }
+function findingsForStageSecrets(cwd, pipelinePath, loaded) {
+    const registry = loadSecretRegistry(process.env);
+    const findings = [];
+    for (const stage of loaded.stages) {
+        for (const decl of stage.secrets ?? []) {
+            if (isForeverDeniedSecret(decl.name)) {
+                findings.push(findingStageError(cwd, pipelinePath, `secret "${decl.name}" is permanently denied and cannot be granted`, "stage.denied_secret", stage.id));
+                continue;
+            }
+            if (!registry.has(decl.name)) {
+                findings.push(findingStageError(cwd, pipelinePath, `unknown secret "${decl.name}" is not in the Host secret registry`, "stage.unknown_secret", stage.id));
+            }
+        }
+    }
+    return findings;
+}
+const ABSOLUTE_PATH_IN_TEXT_RE = /(?:^|[\s"'`=:(])(\/(?:[^\s"'`;|&<>()]+))/g;
+const TRAILING_PATH_PUNCT_RE = /[.,:;!?)\]]+$/;
+export function collectAbsolutePathCandidates(text) {
+    const found = [];
+    const seen = new Set();
+    ABSOLUTE_PATH_IN_TEXT_RE.lastIndex = 0;
+    let match;
+    while ((match = ABSOLUTE_PATH_IN_TEXT_RE.exec(text)) !== null) {
+        const raw = match[1]?.replace(TRAILING_PATH_PUNCT_RE, "") ?? "";
+        if (!raw || !path.isAbsolute(raw) || seen.has(raw))
+            continue;
+        seen.add(raw);
+        found.push(raw);
+    }
+    return found;
+}
+export function isPathUnderStageflowHome(candidate, home) {
+    if (!path.isAbsolute(candidate))
+        return false;
+    const resolved = path.resolve(candidate);
+    const homeResolved = path.resolve(home);
+    return (resolved === homeResolved || resolved.startsWith(`${homeResolved}${path.sep}`));
+}
+function stageSourcePath(loaded, stageId) {
+    const source = loaded.stageSources?.[stageId];
+    if (source?.kind === "file")
+        return source.path;
+    return loaded.pipelinePath;
+}
+function stageflowHomeAbsolutePathMessage(stageId, location, absolutePath) {
+    return (`Stage "${stageId}" ${location} contains absolute path under STAGEFLOW_HOME ` +
+        `("${absolutePath}"). Use STAGEFLOW_CHECKOUT / STAGEFLOW_RUN_WORKSPACE ` +
+        `(and related binding env vars) instead of durable-home paths`);
+}
+function findingsForStageflowHomeAbsolutePaths(cwd, loaded) {
+    const home = globalStageflowHome();
+    const findings = [];
+    const seen = new Set();
+    const pushFinding = (stageId, absPath, location, absolutePath) => {
+        const key = `${stageId}\0${location}\0${absolutePath}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        findings.push(baseFinding({
+            cwd,
+            absPath,
+            message: stageflowHomeAbsolutePathMessage(stageId, location, absolutePath),
+            code: "catalog.stageflow_home_absolute_path",
+            category: "catalog",
+            pipelineId: loaded.pipeline.id,
+            stageId,
+        }, "error"));
+    };
+    const scanText = (stageId, absPath, location, text) => {
+        for (const candidate of collectAbsolutePathCandidates(text)) {
+            if (isPathUnderStageflowHome(candidate, home)) {
+                pushFinding(stageId, absPath, location, candidate);
+            }
+        }
+    };
+    for (const stage of loaded.stages) {
+        const absPath = stageSourcePath(loaded, stage.id);
+        scanText(stage.id, absPath, "system_prompt", stage.system_prompt);
+    }
+    for (const node of loaded.dag.nodes) {
+        const checks = node.completion?.checks ?? [];
+        for (const check of checks) {
+            if (check.type !== "command")
+                continue;
+            const absPath = stageSourcePath(loaded, node.id);
+            scanText(node.id, absPath, `verify command "${check.id}" run`, check.run);
+            if (typeof check.cwd === "string") {
+                scanText(node.id, absPath, `verify command "${check.id}" cwd`, check.cwd);
+            }
+        }
+    }
+    return findings;
+}
 async function findingsForStageMcpCatalog(cwd, loaded) {
     const allowlist = collectMcpAllowlistNames(loaded);
     const ctx = await resolveCatalogContext(cwd);
@@ -235,7 +362,17 @@ async function findingsForStageMcpCatalog(cwd, loaded) {
         }
         throw err;
     }
-    return [];
+    const findings = [];
+    const serversForPath = {};
+    for (const name of allowlist) {
+        const entry = catalog.servers[name];
+        if (entry)
+            serversForPath[name] = entry;
+    }
+    for (const missing of findMissingMcpCommands(serversForPath, process.env)) {
+        findings.push(findingCatalog(cwd, catalogAbsPath, `MCP server "${missing.serverName}" command "${missing.command}" was not found on PATH`, "catalog.mcp_command_missing", "error"));
+    }
+    return findings;
 }
 async function runPipelineValidation(nameOrPath, options) {
     const { cwd, validateStages } = options;
@@ -274,6 +411,8 @@ async function runPipelineValidation(nameOrPath, options) {
         findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));
     }
     findings.push(...(await findingsForStageMcpCatalog(cwd, outcome.value)));
+    findings.push(...findingsForStageSecrets(cwd, pipelinePath, outcome.value));
+    findings.push(...findingsForStageflowHomeAbsolutePaths(cwd, outcome.value));
     if (validateStages && outcome.value.stageSources) {
         for (const source of Object.values(outcome.value.stageSources)) {
             if (source.kind === "file") {

package/dist/diagnostics/checks.d.ts

@@ -0,0 +1,39 @@
+import type { RunStore } from "../runstore/port.js";
+export type DiagnosticSeverity = "error" | "warn" | "skipped";
+export type DiagnosticCheckResult = {
+    id: string;
+    ok: boolean;
+    severity: DiagnosticSeverity;
+    message: string;
+    code?: string;
+    detail?: Record<string, unknown>;
+};
+export type ReadyzChecks = {
+    store_openable: boolean;
+    home_writable: boolean;
+    migrations_complete: boolean;
+    git_present: boolean;
+};
+export type ReadyzResult = {
+    ready: boolean;
+    checks: ReadyzChecks;
+    code?: string;
+};
+export declare function resetReadyzCacheForTests(): void;
+export declare function livezBody(): {
+    ok: true;
+    status: "live";
+};
+export declare function probeGitVersion(): Promise<string | undefined>;
+export declare function runReadyzChecks(options: {
+    store: RunStore;
+    homeDir?: string;
+    now?: number;
+    bypassCache?: boolean;
+}): Promise<ReadyzResult>;
+export type SchemaHealthStub = {
+    user_version: number | null;
+    schema_migrations: "present" | "absent" | "unknown";
+    note?: string;
+};
+export declare function readSchemaHealth(store: RunStore): SchemaHealthStub;