stageflow 0.13.0 → 0.15.0

package/dist/envelope/payloadSchema.js

@@ -1,6 +1,49 @@
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { EnvelopeError } from "../types/envelope.js";
+export class UnresolvedSchemaRefError extends Error {
+    ref;
+    constructor(path, ref) {
+        super(`${path}: unresolved $ref "${ref}"`);
+        this.name = "UnresolvedSchemaRefError";
+        this.ref = ref;
+    }
+}
+const SCHEMA_REF_PREFIX = "#/schemas/";
+function readSchemaRefName(ref, path) {
+    if (typeof ref !== "string" || !ref.startsWith(SCHEMA_REF_PREFIX)) {
+        throw new Error(`${path}: $ref must be a JSON Pointer of the form #/schemas/<name>`);
+    }
+    const name = ref.slice(SCHEMA_REF_PREFIX.length);
+    if (!name || name.includes("/")) {
+        throw new Error(`${path}: $ref must be a JSON Pointer of the form #/schemas/<name>`);
+    }
+    return name;
+}
+function derefSchemaNode(node, path, ctx) {
+    if (node === null || typeof node !== "object" || Array.isArray(node)) {
+        throw new Error(`${path}: schema must be an object`);
+    }
+    const schema = node;
+    if (schema.$ref === undefined) {
+        return { schema, stack: ctx.stack };
+    }
+    const name = readSchemaRefName(schema.$ref, path);
+    if (ctx.stack.includes(name)) {
+        const cycle = [...ctx.stack, name]
+            .map((item) => `${SCHEMA_REF_PREFIX}${item}`)
+            .join(" → ");
+        throw new Error(`${path}: $ref cycle involving ${cycle}`);
+    }
+    const target = ctx.schemas?.[name];
+    if (target === undefined) {
+        throw new UnresolvedSchemaRefError(path, `${SCHEMA_REF_PREFIX}${name}`);
+    }
+    return derefSchemaNode(target, path, {
+        schemas: ctx.schemas,
+        stack: [...ctx.stack, name],
+    });
+}
 function readEnum(schema, path, valueType) {
     if (schema.enum === undefined) {
         return undefined;
@@ -84,11 +127,9 @@ function stringOptions(schema, path) {
         ...(maxLength !== undefined ? { maxLength } : {}),
     };
 }
-function compileNode(node, path) {
-    if (node === null || typeof node !== "object" || Array.isArray(node)) {
-        throw new Error(`${path}: schema must be an object`);
-    }
-    const schema = node;
+function compileNode(node, path, ctx) {
+    const { schema, stack } = derefSchemaNode(node, path, ctx);
+    const childCtx = { schemas: ctx.schemas, stack };
     if (typeof schema.type !== "string") {
         throw new Error(`${path}: type is required`);
     }
@@ -138,7 +179,7 @@ function compileNode(node, path) {
                     schema.minItems < 0)) {
                 throw new Error(`${path}: minItems must be a non-negative integer when present`);
             }
-            const items = compileNode(schema.items, `${path}.items`);
+            const items = compileNode(schema.items, `${path}.items`, childCtx);
             base =
                 schema.minItems !== undefined
                     ? Type.Array(items, { minItems: schema.minItems })
@@ -164,7 +205,7 @@ function compileNode(node, path) {
             }
             const compiledProps = {};
             for (const [key, value] of Object.entries(properties)) {
-                const propSchema = compileNode(value, `${path}.properties.${key}`);
+                const propSchema = compileNode(value, `${path}.properties.${key}`, childCtx);
                 compiledProps[key] = required.has(key)
                     ? propSchema
                     : Type.Optional(propSchema);
@@ -181,28 +222,227 @@ function compileNode(node, path) {
     return nullable ? Type.Union([base, Type.Null()]) : base;
 }
 /**
- * Compile a JSON Schema subset used for stage payload_schema.
+ * Compile a JSON Schema subset for IR `payload_schema` / `clone_input_schema`
+ * (YAML: `io.output.schema` / `io.input.schema`).
  * Supported: type object/string/number/integer/boolean/array,
  * properties, required, items, additionalProperties (boolean),
  * minItems, enum, minimum, maximum. String nodes also accept
  * pattern (a JS RegExp validated with the unicode flag), minLength,
  * and maxLength (non-negative integers). Nested nodes accept
  * nullable (boolean), compiling to a union of that type with null;
- * the root object cannot be nullable. Unknown keywords are ignored.
+ * the root object cannot be nullable. `$ref` is resolved against
+ * `options.schemas` using JSON Pointer `#/schemas/<name>`. Unknown
+ * keywords other than `$ref` are ignored.
  */
-export function compilePayloadSchema(raw) {
-    if (raw !== null &&
-        typeof raw === "object" &&
-        !Array.isArray(raw) &&
-        raw.nullable === true) {
+export function compilePayloadSchema(raw, options) {
+    const ctx = { schemas: options?.schemas, stack: [] };
+    const { schema: resolved } = derefSchemaNode(raw, "payload_schema", ctx);
+    if (resolved.nullable === true) {
         throw new Error("payload_schema: root cannot be nullable");
     }
-    const compiled = compileNode(raw, "payload_schema");
+    const compiled = compileNode(raw, "payload_schema", ctx);
     if (!Type.IsObject(compiled)) {
         throw new Error("payload_schema: root type must be object");
     }
     return compiled;
 }
+function isPlainSchemaObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readRequiredKeys(schema) {
+    if (schema.required === undefined)
+        return [];
+    if (!Array.isArray(schema.required) ||
+        !schema.required.every((key) => typeof key === "string")) {
+        return [];
+    }
+    return schema.required;
+}
+function readProperties(schema) {
+    if (!isPlainSchemaObject(schema.properties))
+        return {};
+    return schema.properties;
+}
+function typesCompatible(consumerType, producerType) {
+    if (consumerType === producerType)
+        return true;
+    return consumerType === "number" && producerType === "integer";
+}
+function readEnumValues(schema) {
+    if (!Array.isArray(schema.enum) || schema.enum.length === 0)
+        return undefined;
+    return schema.enum;
+}
+function enumCompatible(consumer, producer, type) {
+    if (type !== "string" && type !== "integer")
+        return true;
+    const consumerEnum = readEnumValues(consumer);
+    const producerEnum = readEnumValues(producer);
+    if (consumerEnum === undefined)
+        return true;
+    if (producerEnum === undefined)
+        return false;
+    const allowed = new Set(consumerEnum);
+    return producerEnum.every((value) => allowed.has(value));
+}
+function patternCompatible(consumer, producer) {
+    const consumerPattern = typeof consumer.pattern === "string" ? consumer.pattern : undefined;
+    const producerPattern = typeof producer.pattern === "string" ? producer.pattern : undefined;
+    if (consumerPattern === undefined)
+        return true;
+    if (producerPattern === undefined)
+        return false;
+    return consumerPattern === producerPattern;
+}
+function numericBound(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    return value;
+}
+function minBoundFits(consumerBound, producerBound) {
+    const consumer = numericBound(consumerBound);
+    if (consumer === undefined)
+        return true;
+    const producer = numericBound(producerBound);
+    if (producer === undefined)
+        return false;
+    return producer >= consumer;
+}
+function maxBoundFits(consumerBound, producerBound) {
+    const consumer = numericBound(consumerBound);
+    if (consumer === undefined)
+        return true;
+    const producer = numericBound(producerBound);
+    if (producer === undefined)
+        return false;
+    return producer <= consumer;
+}
+function isSubsetNode(consumer, producer, path, ctx) {
+    const consumerDeref = derefSchemaNode(consumer, path, ctx);
+    const producerDeref = derefSchemaNode(producer, path, ctx);
+    const consumerNode = consumerDeref.schema;
+    const producerNode = producerDeref.schema;
+    if (typeof consumerNode.type !== "string" || typeof producerNode.type !== "string") {
+        return false;
+    }
+    if (!typesCompatible(consumerNode.type, producerNode.type)) {
+        return false;
+    }
+    if (producerNode.nullable === true && consumerNode.nullable !== true) {
+        return false;
+    }
+    if (consumerNode.type === "array") {
+        if (consumerNode.items === undefined || producerNode.items === undefined) {
+            return false;
+        }
+        if (!isSubsetNode(consumerNode.items, producerNode.items, `${path}.items`, {
+            schemas: ctx.schemas,
+            stack: consumerDeref.stack,
+        })) {
+            return false;
+        }
+        return minBoundFits(consumerNode.minItems, producerNode.minItems);
+    }
+    if (consumerNode.type === "object") {
+        const consumerRequired = readRequiredKeys(consumerNode);
+        const producerRequired = new Set(readRequiredKeys(producerNode));
+        const producerProps = readProperties(producerNode);
+        const consumerProps = readProperties(consumerNode);
+        for (const key of consumerRequired) {
+            if (!(key in producerProps) || !producerRequired.has(key)) {
+                return false;
+            }
+        }
+        for (const [key, consumerProp] of Object.entries(consumerProps)) {
+            if (producerProps[key] === undefined)
+                continue;
+            if (!isSubsetNode(consumerProp, producerProps[key], `${path}.properties.${key}`, {
+                schemas: ctx.schemas,
+                stack: consumerDeref.stack,
+            })) {
+                return false;
+            }
+        }
+        if (consumerNode.additionalProperties === false) {
+            if (producerNode.additionalProperties !== false) {
+                return false;
+            }
+            for (const key of Object.keys(producerProps)) {
+                if (!(key in consumerProps)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    if (!enumCompatible(consumerNode, producerNode, consumerNode.type)) {
+        return false;
+    }
+    if (consumerNode.type === "string") {
+        if (!patternCompatible(consumerNode, producerNode))
+            return false;
+        if (!minBoundFits(consumerNode.minLength, producerNode.minLength))
+            return false;
+        if (!maxBoundFits(consumerNode.maxLength, producerNode.maxLength))
+            return false;
+    }
+    if (consumerNode.type === "number" || consumerNode.type === "integer") {
+        if (!minBoundFits(consumerNode.minimum, producerNode.minimum))
+            return false;
+        if (!maxBoundFits(consumerNode.maximum, producerNode.maximum))
+            return false;
+    }
+    return true;
+}
+/**
+ * After `$ref` resolve, true when every success payload that satisfies the
+ * producer schema also satisfies the consumer schema (producer output
+ * assignable to consumer input). Extra producer fields are allowed unless
+ * the consumer sets `additionalProperties: false`, which also requires the
+ * producer to close extras. A number consumer accepts an integer producer;
+ * the reverse is incompatible. Producer enums must be subsets of consumer
+ * enums; a consumer enum with an unconstrained producer is incompatible.
+ * String `pattern` values must be identical when the consumer sets one.
+ * Producer `minimum`/`maximum`, `minLength`/`maxLength`, and array `minItems`
+ * must fit inside the consumer bounds (a consumer bound with an omitted
+ * producer bound is incompatible). A nullable producer is incompatible unless
+ * the consumer is also nullable.
+ */
+export function isPayloadSchemaSubset(consumer, producer, options) {
+    return isSubsetNode(consumer, producer, "payload_schema", {
+        schemas: options?.schemas,
+        stack: [],
+    });
+}
+export function expandPayloadSchemaRefs(raw, options) {
+    return expandSchemaNode(raw, "payload_schema", {
+        schemas: options?.schemas,
+        stack: [],
+    });
+}
+function expandSchemaNode(node, path, ctx) {
+    const { schema, stack } = derefSchemaNode(node, path, ctx);
+    const childCtx = { schemas: ctx.schemas, stack };
+    const clone = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "$ref")
+            continue;
+        if (key === "properties" && isPlainSchemaObject(value)) {
+            const props = {};
+            for (const [pk, pv] of Object.entries(value)) {
+                props[pk] = expandSchemaNode(pv, `${path}.properties.${pk}`, childCtx);
+            }
+            clone.properties = props;
+            continue;
+        }
+        if (key === "items") {
+            clone.items = expandSchemaNode(value, `${path}.items`, childCtx);
+            continue;
+        }
+        clone[key] = value;
+    }
+    return clone;
+}
 function formatPayloadInstancePath(instancePath) {
     const translated = instancePath.replace(/\//g, ".").replace(/^\./, "");
     return translated ? `payload.${translated}` : "payload";
@@ -212,14 +452,20 @@ function payloadSchemaMismatchDetails(schema, payload) {
         .map((err) => `${formatPayloadInstancePath(err.instancePath)} ${err.message}`)
         .join("; ");
 }
-export function assertEnvelopePayload(envelope, payloadSchema) {
+export function payloadInstanceMismatch(instance, payloadSchema, options) {
+    const schema = compilePayloadSchema(payloadSchema, options);
+    if (Value.Check(schema, instance))
+        return undefined;
+    return payloadSchemaMismatchDetails(schema, instance);
+}
+export function assertEnvelopePayload(envelope, payloadSchema, options) {
     if (payloadSchema === undefined) {
         return;
     }
     if (envelope.status !== "success") {
         return;
     }
-    const schema = compilePayloadSchema(payloadSchema);
+    const schema = compilePayloadSchema(payloadSchema, options);
     if (envelope.payload === undefined) {
         throw new EnvelopeError("payload is required by stage payload_schema");
     }
@@ -230,19 +476,23 @@ export function assertEnvelopePayload(envelope, payloadSchema) {
             : "payload does not match payload_schema");
     }
 }
-export function assertCloneAssignmentPayload(envelope, cloneInputSchema, successorId, itemPath = "") {
+/**
+ * Validate clone/fan-out assignment against the successor's IR
+ * `clone_input_schema` (YAML: `io.input.schema`).
+ */
+export function assertCloneAssignmentPayload(envelope, cloneInputSchema, successorId, itemPath = "", options) {
     if (envelope.status !== "success") {
         return;
     }
-    const schema = compilePayloadSchema(cloneInputSchema);
+    const schema = compilePayloadSchema(cloneInputSchema, options);
     const pathLead = itemPath ? `${itemPath}: ` : "";
     if (envelope.payload === undefined) {
-        throw new EnvelopeError(`${pathLead}clone assignment payload is required by clone_input_schema for ${successorId}`);
+        throw new EnvelopeError(`${pathLead}clone assignment payload is required by io.input.schema for ${successorId}`);
     }
     if (!Value.Check(schema, envelope.payload)) {
         const details = payloadSchemaMismatchDetails(schema, envelope.payload);
         throw new EnvelopeError(details
-            ? `${pathLead}clone assignment payload does not match clone_input_schema for ${successorId}: ${details}`
-            : `${pathLead}clone assignment payload does not match clone_input_schema for ${successorId}`);
+            ? `${pathLead}clone assignment payload does not match io.input.schema for ${successorId}: ${details}`
+            : `${pathLead}clone assignment payload does not match io.input.schema for ${successorId}`);
     }
 }

package/dist/mcp/catalogTools.js

@@ -11,6 +11,7 @@ const taskFileSchema = z.object({
     context: z.string().optional(),
     constraints: z.string().optional(),
     checkout: z.string().optional(),
+    input: z.record(z.string(), z.unknown()).optional(),
 });
 const startRunSchema = z
     .object({

package/dist/package-meta.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.13.0";
+export declare const PACKAGE_VERSION = "0.15.0";

package/dist/package-meta.js

@@ -1,2 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.13.0";
+export const PACKAGE_VERSION = "0.15.0";

package/dist/runstore/pipelineDagSnapshot.js

@@ -1,6 +1,8 @@
 import { hydrateResolvedNeeds } from "../config/pipelineNeeds.js";
 import { mintCloneInstanceIds } from "./stageInstanceId.js";
 export function buildPipelineDagSnapshotFromLoaded(loaded) {
+    // Snapshot JSON keeps IR keys (`completion`, `recovery`, `clone_input_schema`).
+    // Do not rewrite these from target YAML names. Resume hydrates this shape.
     const gate_kinds = {};
     const clone_input_schema = {};
     for (const stage of loaded.stages) {

package/dist/runstore/port.d.ts

@@ -8,6 +8,7 @@ export type RunStatus = "created" | "running" | "succeeded" | "failed";
 export type RunPipelineDagSnapshot = ResolvedPipelineDag & {
     stage_ids: string[];
     gate_kinds?: Record<string, StageGateKind[]>;
+    /** IR: per-stage clone assignment schema. YAML: `io.input.schema`. */
     clone_input_schema?: Record<string, unknown>;
 };
 export type StageReadiness = "blocked" | "ready" | "running" | "waiting" | "succeeded" | "failed" | "skipped";

package/dist/runtime/completionCheckRunner.d.ts

@@ -131,7 +131,8 @@ export type CompletionVerificationResult = {
 /** Default Node implementation; callers may substitute a sandboxed executor. */
 export declare const nodeCommandExecutor: CommandExecutor;
 /**
- * Run every completion check in declaration order. A failed check never throws
- * or prevents later checks from producing their own repair evidence.
+ * Run every after-phase IR check in declaration order. YAML: `verify` when after.
+ * A failed check never throws or prevents later checks from producing their own
+ * repair evidence.
  */
 export declare function runCompletionContract(input: CompletionCheckRunnerInput): Promise<CompletionVerificationResult>;

package/dist/runtime/completionCheckRunner.js

@@ -343,8 +343,9 @@ async function runCheck(check, input) {
     }
 }
 /**
- * Run every completion check in declaration order. A failed check never throws
- * or prevents later checks from producing their own repair evidence.
+ * Run every after-phase IR check in declaration order. YAML: `verify` when after.
+ * A failed check never throws or prevents later checks from producing their own
+ * repair evidence.
  */
 export async function runCompletionContract(input) {
     const checks = [];

package/dist/runtime/envelopeRouting.d.ts

@@ -1,9 +1,9 @@
 import type { RunStore, StageSnapshot } from "../runstore/port.js";
 import type { StageEnvelope, TerminalEnvelope } from "../types/envelope.js";
 import type { LoadedPipeline, ResolvedPipelineDag } from "../types/pipeline.js";
-import type { StageConfig } from "../types/stage.js";
+import type { LoadedStageConfig } from "../types/stage.js";
 export declare function buildCompletedEnvelopesFromRun(store: RunStore, runId: string, stages?: StageSnapshot[], dag?: ResolvedPipelineDag): Promise<Map<string, StageEnvelope>>;
-export declare function buildStageConfigById(loaded: LoadedPipeline): Map<string, StageConfig>;
+export declare function buildStageConfigById(loaded: LoadedPipeline): Map<string, LoadedStageConfig>;
 export type ResolvePriorEnvelopeResult = {
     ok: true;
     prior: StageEnvelope | null;

package/dist/runtime/pipelineRunner.d.ts

@@ -1,4 +1,5 @@
 import type { AgentPort } from "../agent/port.js";
+import { type ValidationFinding } from "../config/validateCatalog.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { StageHitlController } from "./stageHitl.js";
@@ -15,6 +16,7 @@ export type PipelineRunResult = {
     runDir: string;
     runId: string;
     reason?: string;
+    findings?: ValidationFinding[];
 };
 export type StartedPipeline = {
     runId: string;
@@ -38,6 +40,7 @@ export type PreparedPipeline = {
     stageProcessLauncher?: StageProcessLauncher;
     operatorCatalog?: OperatorCatalog;
     skipGates?: boolean;
+    findings?: ValidationFinding[];
 };
 export type ExecuteStagesOptions = {
     maxActiveStagesPerRun?: number;

package/dist/runtime/pipelineRunner.js

@@ -1,8 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { loadPipelineValidated } from "../config/validateCatalog.js";
+import { buildValidationResult, loadPipelineValidated, } from "../config/validateCatalog.js";
 import { loadTaskFromYaml } from "../config/loadTask.js";
-import { buildValidationResult } from "../config/validateCatalog.js";
 import { resolveAndValidateCheckout } from "./stageRoots.js";
 import { buildPipelineDagSnapshotFromLoaded } from "../runstore/pipelineDagSnapshot.js";
 import { normalizeCatalogPath } from "../runstore/normalizeCatalogPath.js";
@@ -10,6 +9,7 @@ import { runPipelineDag } from "./pipelineScheduler.js";
 import { readMaxActiveStagesPerRun, readStageExecutionMode, } from "./stageConcurrency.js";
 import { StageProcessLauncher } from "./stageProcessLauncher.js";
 import { PipelineValidationError } from "./pipelineValidationError.js";
+import { checkTaskEntryInput } from "./taskInput.js";
 export { PipelineValidationError } from "./pipelineValidationError.js";
 let defaultStageProcessLauncher;
 function resolveStageProcessLauncher(executionMode, override) {
@@ -27,6 +27,7 @@ function resolveStageProcessLauncher(executionMode, override) {
 async function preparePipeline(options) {
     const loadResult = await loadPipelineValidated(options.pipeline, {
         cwd: options.cwd,
+        projectRoot: options.projectRoot ?? options.cwd,
         validateStages: true,
     });
     if (!loadResult.ok) {
@@ -41,6 +42,20 @@ async function preparePipeline(options) {
             })());
     const label = options.taskPath ?? "task.yaml";
     const task = loadTaskFromYaml(taskYaml, `task file ${label}`);
+    const pairing = checkTaskEntryInput(task, loaded, {
+        cwd: options.cwd,
+        taskPath: options.taskPath,
+    });
+    if (pairing.some((finding) => finding.severity === "error")) {
+        throw new PipelineValidationError(buildValidationResult("pipeline", pairing, false));
+    }
+    const warningFindings = [
+        ...loadResult.findings.filter((finding) => finding.severity === "warning"),
+        ...pairing.filter((finding) => finding.severity === "warning"),
+    ];
+    for (const finding of warningFindings) {
+        console.error(`${finding.code}: ${finding.message}`);
+    }
     const checkoutRoot = await resolveAndValidateCheckout(task, options.checkoutOverride, options.cwd);
     const pipelinePath = normalizeCatalogPath(loaded.pipelinePath);
     const taskPath = options.taskPath
@@ -76,6 +91,7 @@ async function preparePipeline(options) {
         stageProcessLauncher,
         operatorCatalog: options.operatorCatalog,
         skipGates: options.skipGates,
+        ...(warningFindings.length > 0 ? { findings: warningFindings } : {}),
     };
 }
 export async function executeStages(prepared, options) {
@@ -84,7 +100,7 @@ export async function executeStages(prepared, options) {
         prepared.executionMode ??
         readStageExecutionMode(process.env);
     const stageProcessLauncher = resolveStageProcessLauncher(executionMode, options?.stageProcessLauncher ?? prepared.stageProcessLauncher);
-    return runPipelineDag({
+    const result = await runPipelineDag({
         prepared,
         maxActiveStagesPerRun,
         resumeFromStageId: options?.resumeFromStageId,
@@ -93,6 +109,10 @@ export async function executeStages(prepared, options) {
         executionMode,
         stageProcessLauncher,
     });
+    if (prepared.findings !== undefined && prepared.findings.length > 0) {
+        return { ...result, findings: prepared.findings };
+    }
+    return result;
 }
 export async function runPipeline(options) {
     const cwd = options.cwd ?? process.cwd();

package/dist/runtime/runManager.js

@@ -383,7 +383,7 @@ export class RunManager {
             gitSha: input.gitSha,
             ciPrUrl: input.ciPrUrl,
             ciJobUrl: input.ciJobUrl,
-        });
+        }, undefined, resolved.kind === "path" ? resolved.taskPath : undefined);
     }
     async rerun(runId) {
         const cwd = this.options.cwd ?? process.cwd();
@@ -1061,7 +1061,7 @@ export class RunManager {
             this.attachedWaiting.delete(`${runId}\0${stageId}`);
         }
     }
-    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot) {
+    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot, taskPath) {
         let checkoutKey;
         try {
             const task = loadTaskFromYaml(taskYaml, taskLabel);
@@ -1086,6 +1086,7 @@ export class RunManager {
                 agent: this.options.agent,
                 store: this.options.store,
                 taskYaml,
+                taskPath,
                 pipeline,
                 cwd,
                 projectRoot: projectRoot ?? this.projectRoot,

package/dist/runtime/stageAttemptBootstrap.d.ts

@@ -2,7 +2,7 @@ import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunInput, StageS
 import type { RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
-import type { StageConfig } from "../types/stage.js";
+import type { LoadedStageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
 import { type StageAttemptContext } from "./stageAttemptContext.js";
 import { type StageRoots } from "./stageRoots.js";
@@ -14,7 +14,7 @@ export type StageAttemptOpenInput = {
     agent: Pick<AgentPort, "openStage">;
     store: RunStore;
     runId: string;
-    stage: StageConfig;
+    stage: LoadedStageConfig;
     task: TaskFile;
     dag: ResolvedPipelineDag;
     checkoutRoot?: string;

package/dist/runtime/stageRunner.d.ts

@@ -1,6 +1,6 @@
 import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunResult, StageSessionMode } from "../agent/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { StageConfig } from "../types/stage.js";
+import type { LoadedStageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
 import type { RunStore } from "../runstore/port.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
@@ -21,7 +21,7 @@ export type RunStageOptions = {
     agent: AgentPort;
     store: RunStore;
     runId: string;
-    stage: StageConfig;
+    stage: LoadedStageConfig;
     task: TaskFile;
     dag?: ResolvedPipelineDag;
     priorEnvelope?: StageEnvelope | null;

package/dist/runtime/taskInput.d.ts

@@ -1,3 +1,5 @@
+import { type ValidationFinding } from "../config/validateCatalog.js";
+import type { LoadedPipeline } from "../types/pipeline.js";
 import type { TaskFile } from "../types/task.js";
 export type StartTaskInput = {
     task?: string | TaskFile;
@@ -12,4 +14,9 @@ export type ResolvedTaskInput = {
 };
 export declare function isTaskFile(value: unknown): value is TaskFile;
 export declare function taskFileToYaml(task: TaskFile): string;
+/** Validate optional `task.input` against entry-stage IR `clone_input_schema` (YAML: `io.input.schema`). */
+export declare function checkTaskEntryInput(task: TaskFile, loaded: LoadedPipeline, options: {
+    cwd: string;
+    taskPath?: string;
+}): ValidationFinding[];
 export declare function resolveStartTaskInput(input: StartTaskInput, cwd: string): ResolvedTaskInput;