stageflow 0.8.0 → 0.12.0

package/dist/cli/validateOutput.d.ts

@@ -1,6 +1,6 @@
 import type { ValidationResult } from "../config/validateCatalog.js";
-export declare const VALIDATION_SCOPE_LINE = "Scope: pipeline and stage YAML only (task, checkout, providers not checked).";
-export declare const VALIDATION_CHECKS = "pipeline and stage YAML only";
+export declare const VALIDATION_SCOPE_LINE = "Scope: catalog YAML (pipelines, stages, and tasks as selected by flags). Provider auth and checkout paths are not checked.";
+export declare const VALIDATION_CHECKS = "catalog YAML (pipelines, stages, tasks as selected by flags)";
 export declare function formatValidationHuman(result: ValidationResult, options?: {
     strict?: boolean;
 }): string;

package/dist/cli/validateOutput.js

@@ -1,6 +1,6 @@
 import { effectiveSeverity } from "../config/validateCatalog.js";
-export const VALIDATION_SCOPE_LINE = "Scope: pipeline and stage YAML only (task, checkout, providers not checked).";
-export const VALIDATION_CHECKS = "pipeline and stage YAML only";
+export const VALIDATION_SCOPE_LINE = "Scope: catalog YAML (pipelines, stages, and tasks as selected by flags). Provider auth and checkout paths are not checked.";
+export const VALIDATION_CHECKS = "catalog YAML (pipelines, stages, tasks as selected by flags)";
 function effectiveSeverityRank(finding, strict) {
     return effectiveSeverity(finding, strict) === "error" ? 0 : 1;
 }

package/dist/cli.d.ts

@@ -3,7 +3,7 @@ import type { OperatorCatalog } from "./runtime/stageAttemptBootstrap.js";
 export declare function parseRunStageArgs(argv: string[]): {
     runId: string;
     stageId: string;
-    mode?: "run" | "resume";
+    mode?: "run" | "resume" | "feedback_resume" | "new_session";
     resumeAnswer?: unknown;
     attempt?: number;
     sessionFilePath?: string;

package/dist/cli.js

@@ -3,13 +3,14 @@ import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { PiAgentAdapter } from "./agent/piAdapter.js";
+import { globalAgentBackendFromManifest, resolveAgentPort } from "./agent/resolveAgentPort.js";
 import { ARTIFACT_USAGE, runArtifactCommand } from "./cli/artifactCommand.js";
 import { ENVELOPE_USAGE, runEnvelopeCommand, } from "./cli/envelopeCommand.js";
 import { EXPORT_RUN_USAGE, runExportRunCommand, } from "./cli/exportRunCommand.js";
 import { INIT_USAGE, runInitCommand } from "./cli/initCommand.js";
 import { PROVIDERS_USAGE, runProvidersCommand } from "./cli/providersCommand.js";
 import { RUN_USAGE, runRunCommand } from "./cli/runCommand.js";
+import { RUNS_USAGE, runRunsCommand } from "./cli/runsCommand.js";
 import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
 import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
 import { VALIDATE_USAGE, runValidateCommand } from "./cli/validateCommand.js";
@@ -20,6 +21,7 @@ import { SF_STAGE_WORKER } from "./runtime/stageWorkerProtocol.js";
 import { DEFAULT_PORT, startUiServer } from "./server/http.js";
 import { startMcpServer } from "./server/mcpHost.js";
 import { resolveMcpStateless } from "./mcp/server.js";
+import { PACKAGE_VERSION } from "./package-meta.js";
 const USAGE = `Usage:
   sf init
   sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]
@@ -27,6 +29,16 @@ const USAGE = `Usage:
   sf artifact read --run <runId> --path <relPath> [--out <file>]
   sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]
   sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]
+  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]
+  sf runs show --run <runId> [--from <sf-run.json>] [--json]
+  sf runs verify --run <runId> --stage <stageId> [--json]
+  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]
+  sf runs waiting [--run <runId>] [--json]
+  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]
+  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]
+  sf runs retry --run <runId> --stage <stageId> [--json]
+  sf runs abandon --run <runId> --stage <stageId> [--json]
+  sf runs rerun --run <runId> [--json]
   sf ui [--port ${DEFAULT_PORT}] [--mcp-stateless]
   sf mcp [--port ${DEFAULT_PORT}] [--mcp-stateless]
   sf providers list
@@ -38,6 +50,8 @@ const USAGE = `Usage:
   sf skills list
   sf skills install --from-path <dir> [--skill-name <name>]
   sf skills install --from-zip <url-or-path> [--skill-name <name>] [--checksum sha256:<hex>]
+  sf --version
+  sf -V
   sf --help
 
 Stageflow (sf) runs YAML-defined automatic stage pipelines.
@@ -56,6 +70,8 @@ ${ENVELOPE_USAGE}
 
 ${EXPORT_RUN_USAGE}
 
+${RUNS_USAGE}
+
 ${PROVIDERS_USAGE}
 
 ${SKILLS_USAGE}`;
@@ -68,6 +84,12 @@ function parseArgs(argv) {
         args.length === 1) {
         return { help: true };
     }
+    if (args[0] === "--version" || args[0] === "-V") {
+        if (args.length > 1) {
+            throw new Error(`Unexpected argument: ${args[1]}`);
+        }
+        return { help: false, version: true };
+    }
     const command = args[0];
     if (command === "providers" ||
         command === "validate" ||
@@ -76,6 +98,7 @@ function parseArgs(argv) {
         command === "artifact" ||
         command === "envelope" ||
         command === "export-run" ||
+        command === "runs" ||
         command === "skills") {
         return { help: false, command };
     }
@@ -133,8 +156,11 @@ export function parseRunStageArgs(argv) {
         }
         else if (argv[i] === "--mode") {
             const raw = argv[++i];
-            if (raw !== "run" && raw !== "resume") {
-                throw new Error("--mode must be run or resume");
+            if (raw !== "run" &&
+                raw !== "resume" &&
+                raw !== "feedback_resume" &&
+                raw !== "new_session") {
+                throw new Error("--mode must be run, resume, feedback_resume, or new_session");
             }
             mode = raw;
         }
@@ -240,6 +266,10 @@ async function main(argv) {
             console.log(USAGE);
             return argv.slice(2).length === 0 ? 1 : 0;
         }
+        if (parsed.version) {
+            console.log(PACKAGE_VERSION);
+            return 0;
+        }
         const ctx = await resolveStageflowContext(process.cwd());
         if (parsed.command === "init") {
             return runInitCommand(argv.slice(3), { cwd: ctx.invocationCwd });
@@ -272,6 +302,13 @@ async function main(argv) {
                 projectRoot: ctx.projectRoot,
             });
         }
+        if (parsed.command === "runs") {
+            return runRunsCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+                isGitProject: ctx.isGitProject,
+            });
+        }
         if (parsed.command === "providers") {
             return runProvidersCommand(argv.slice(3), ctx.invocationCwd);
         }
@@ -282,12 +319,13 @@ async function main(argv) {
             });
         }
         const store = createRunStore({ rootDir: ctx.projectRoot });
+        const globalAgent = globalAgentBackendFromManifest(ctx.manifest);
         if (parsed.command === "ui") {
             const mcpStateless = resolveMcpStateless({
                 mcpStateless: parsed.mcpStateless,
             });
             const { url, mcpUrl } = await startUiServer({
-                agent: new PiAgentAdapter(),
+                agent: resolveAgentPort({ global: globalAgent }),
                 store,
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
@@ -305,7 +343,7 @@ async function main(argv) {
                 mcpStateless: parsed.mcpStateless,
             });
             const { mcpUrl } = await startMcpServer({
-                agent: new PiAgentAdapter(),
+                agent: resolveAgentPort({ global: globalAgent }),
                 store,
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,

package/dist/config/browseCatalog.js

@@ -14,7 +14,7 @@ function repoRelPath(projectRoot, absPath) {
 function mapStageListing(stage, source, projectRoot) {
     const listing = {
         id: stage.id,
-        ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+        ...(stage.gate_kinds !== undefined ? { gate_kinds: stage.gate_kinds } : {}),
     };
     if (source?.kind === "inline") {
         listing.inline = true;

package/dist/config/createPipeline.d.ts

@@ -1,3 +1,4 @@
+import type { PipelineNeeds } from "../types/pipeline.js";
 import type { StageGateKind } from "../types/stage.js";
 import type { PipelineListing } from "./listConfig.js";
 export type CreatePipelineStageInline = {
@@ -7,7 +8,7 @@ export type CreatePipelineStageInline = {
 };
 export type CreatePipelineStageRef = {
     id: string;
-    needs?: string;
+    needs?: PipelineNeeds;
     uses?: string;
     inline?: CreatePipelineStageInline;
 };

package/dist/config/createPipeline.js

@@ -1,5 +1,6 @@
 import { access, mkdir, readdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { parsePipelineNeeds } from "./pipelineNeeds.js";
 import { STAGE_ID_PATTERN } from "./createStage.js";
 import { inferIdFromUsesPath, normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
 import { readYamlObject } from "./readYamlObject.js";
@@ -149,14 +150,15 @@ function parseStageEntry(entry, index) {
     }
     const ref = { id };
     if (entry.needs !== undefined) {
-        if (typeof entry.needs !== "string") {
+        const parsedNeeds = parsePipelineNeeds(entry.needs, id);
+        if (!parsedNeeds.ok) {
             return {
                 ok: false,
                 status: 400,
-                error: `stages[${index}].needs must be a string`,
+                error: parsedNeeds.message.replace(/^stage "[^"]+": /, `stages[${index}].`),
             };
         }
-        ref.needs = entry.needs;
+        ref.needs = parsedNeeds.value;
     }
     if (entry.uses !== undefined) {
         if (typeof entry.uses !== "string" || !entry.uses.trim()) {
@@ -224,6 +226,24 @@ export function parseCreatePipelineBody(body) {
         stages: refs,
     };
 }
+function appendNeedsYaml(lines, needs) {
+    if (typeof needs === "string") {
+        lines.push(`    needs: ${needs}`);
+        return;
+    }
+    lines.push("    needs:");
+    for (const edge of needs) {
+        if (edge.on.length === 1 && edge.on[0] === "succeeded") {
+            lines.push(`      - ${edge.id}`);
+            continue;
+        }
+        lines.push(`      - id: ${edge.id}`);
+        lines.push("        on:");
+        for (const state of edge.on) {
+            lines.push(`          - ${state}`);
+        }
+    }
+}
 function formatInlineYamlScalar(value) {
     if (value.includes("\n") ||
         /[:#"'&*!|>@`[\]{}]/.test(value) ||
@@ -245,13 +265,18 @@ export function pipelineConfigToYaml(pipeline, options) {
         }
         lines.push(`  - id: ${stage.id}`);
         if (stage.needs) {
-            lines.push(`    needs: ${stage.needs}`);
+            appendNeedsYaml(lines, stage.needs);
         }
         if (stage.inline) {
-            if (stage.inline.gate_kinds && stage.inline.gate_kinds.length > 0) {
-                lines.push("    gate_kinds:");
-                for (const kind of stage.inline.gate_kinds) {
-                    lines.push(`      - ${kind}`);
+            if (stage.inline.gate_kinds !== undefined) {
+                if (stage.inline.gate_kinds.length === 0) {
+                    lines.push("    gate_kinds: []");
+                }
+                else {
+                    lines.push("    gate_kinds:");
+                    for (const kind of stage.inline.gate_kinds) {
+                        lines.push(`      - ${kind}`);
+                    }
                 }
             }
             if (stage.inline.system_prompt.includes("\n")) {
@@ -364,7 +389,7 @@ function buildPipelineListing(projectRoot, relPath, loaded) {
             const source = loaded.stageSources?.[stage.id];
             const listing = {
                 id: stage.id,
-                ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+                ...(stage.gate_kinds !== undefined ? { gate_kinds: stage.gate_kinds } : {}),
             };
             if (source?.kind === "inline") {
                 return { ...listing, inline: true };

package/dist/config/createStage.js

@@ -22,7 +22,7 @@ function validateStageId(id) {
 function parseGateKinds(raw) {
     if (raw === undefined)
         return undefined;
-    if (!Array.isArray(raw) || raw.length === 0)
+    if (!Array.isArray(raw))
         return "invalid";
     const kinds = [];
     for (const item of raw) {
@@ -71,7 +71,7 @@ export function parseCreateStageBody(body) {
         return {
             ok: false,
             status: 400,
-            error: `gate_kinds must be a non-empty array of: ${STAGE_GATE_KINDS.join(", ")}`,
+            error: `gate_kinds must be an array of: ${STAGE_GATE_KINDS.join(", ")}`,
         };
     }
     return {
@@ -80,7 +80,7 @@ export function parseCreateStageBody(body) {
         id: body.id,
         system_prompt: body.system_prompt,
         model: body.model,
-        ...(gateKinds ? { gate_kinds: gateKinds } : {}),
+        ...(gateKinds !== undefined ? { gate_kinds: gateKinds } : {}),
     };
 }
 function formatInlineYamlScalar(value) {
@@ -96,10 +96,15 @@ function formatInlineYamlScalar(value) {
 }
 export function stageConfigToYaml(stage) {
     const lines = [`id: ${stage.id}`];
-    if (stage.gate_kinds && stage.gate_kinds.length > 0) {
-        lines.push("gate_kinds:");
-        for (const kind of stage.gate_kinds) {
-            lines.push(`  - ${kind}`);
+    if (stage.gate_kinds !== undefined) {
+        if (stage.gate_kinds.length === 0) {
+            lines.push("gate_kinds: []");
+        }
+        else {
+            lines.push("gate_kinds:");
+            for (const kind of stage.gate_kinds) {
+                lines.push(`  - ${kind}`);
+            }
         }
     }
     if (stage.system_prompt.includes("\n")) {
@@ -186,7 +191,7 @@ export async function createStage(projectRoot, input) {
             id: input.id,
             system_prompt: input.system_prompt,
             model: input.model,
-            ...(input.gate_kinds ? { gate_kinds: input.gate_kinds } : {}),
+            ...(input.gate_kinds !== undefined ? { gate_kinds: input.gate_kinds } : {}),
         }), "utf8");
     }
     catch (err) {
@@ -200,7 +205,7 @@ export async function createStage(projectRoot, input) {
             stage: {
                 path: relPath,
                 id: stage.id,
-                ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+                ...(stage.gate_kinds !== undefined ? { gate_kinds: stage.gate_kinds } : {}),
             },
         };
     }

package/dist/config/loadPipeline.js

@@ -5,6 +5,7 @@ import { mergePipelineStages } from "./mergePipelineIncludes.js";
 import { normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
 import { loadStageFromObjectOutcome, loadStageOutcome } from "./loadStage.js";
 import { resolvePipelineDagFromRefs } from "./resolvePipelineDag.js";
+import { validateCompletionContractForStage } from "./validateCompletionContract.js";
 export async function resolvePipelinePath(pipelinePath, cwd) {
     const resolved = path.normalize(path.resolve(cwd, pipelinePath));
     try {
@@ -21,7 +22,7 @@ async function loadPipelineFromPath(pipelinePath) {
     if (!mergeOutcome.ok) {
         return loadFailure(mergeOutcome.issues);
     }
-    const { entries: rawEntries, pipelineId } = mergeOutcome.value;
+    const { entries: rawEntries, pipelineId, agent: pipelineAgent } = mergeOutcome.value;
     const ctx = { pipelineId, path: normalizedPipelinePath };
     const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
     if (!normalizeOutcome.ok) {
@@ -106,7 +107,15 @@ async function loadPipelineFromPath(pipelinePath) {
     const pipeline = {
         id: pipelineId,
         stages: stageIds,
+        ...(pipelineAgent !== undefined ? { agent: pipelineAgent } : {}),
     };
+    const nodeById = new Map(dag.nodes.map((node) => [node.id, node]));
+    for (const stage of stages) {
+        const completion = nodeById.get(stage.id)?.completion;
+        const completionOutcome = validateCompletionContractForStage(stage, completion);
+        if (!completionOutcome.ok)
+            return loadFailure(completionOutcome.issues);
+    }
     return loadSuccess({
         pipeline,
         stages,

package/dist/config/loadStage.js

@@ -1,10 +1,69 @@
+import { parseAgentField } from "../agent/agentBackend.js";
+import { CLONE_ACTIONS } from "../types/forkChoice.js";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
 import { compilePayloadSchema } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
 function isGateKind(value) {
     return STAGE_GATE_KINDS.includes(value);
 }
+function isCloneAction(value) {
+    return CLONE_ACTIONS.includes(value);
+}
+function parseCloneActions(raw, label) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!Array.isArray(raw) || !raw.every((item) => typeof item === "string")) {
+        return loadFailure([
+            {
+                code: "stage.invalid_clone_actions",
+                message: `Invalid stage ${label}: clone_actions must be a non-empty array of strings`,
+                category: "stage",
+            },
+        ]);
+    }
+    if (raw.length === 0) {
+        return loadFailure([
+            {
+                code: "stage.invalid_clone_actions",
+                message: `Invalid stage ${label}: clone_actions must not be empty`,
+                category: "stage",
+            },
+        ]);
+    }
+    const actions = [];
+    for (const item of raw) {
+        if (!isCloneAction(item)) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_clone_actions",
+                    message: `Invalid stage ${label}: unsupported clone_actions value "${item}" (allowed: ${CLONE_ACTIONS.join(", ")})`,
+                    category: "stage",
+                },
+            ]);
+        }
+        actions.push(item);
+    }
+    return loadSuccess(actions);
+}
+function parseTimeoutMs(raw, label) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (typeof raw !== "number" ||
+        !Number.isFinite(raw) ||
+        !Number.isInteger(raw) ||
+        raw <= 0) {
+        return loadFailure([
+            {
+                code: "stage.invalid_timeout_ms",
+                message: `Invalid stage ${label}: timeout_ms must be a positive integer (milliseconds)`,
+                category: "stage",
+            },
+        ]);
+    }
+    return loadSuccess(raw);
+}
 function parseGateKinds(raw, label) {
     if (raw === undefined)
         return loadSuccess(undefined);
@@ -30,7 +89,7 @@ function parseGateKinds(raw, label) {
         }
         kinds.push(item);
     }
-    return loadSuccess(kinds.length > 0 ? kinds : undefined);
+    return loadSuccess(kinds);
 }
 function parseStageFields(raw, label, entryId) {
     if (typeof raw.system_prompt !== "string" ||
@@ -78,6 +137,46 @@ function parseStageFields(raw, label, entryId) {
         }
         stage.payload_schema = raw.payload_schema;
     }
+    if (raw.clone_input_schema !== undefined) {
+        if (raw.clone_input_schema === null ||
+            typeof raw.clone_input_schema !== "object" ||
+            Array.isArray(raw.clone_input_schema)) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_clone_input_schema",
+                    message: `Invalid stage ${label}: clone_input_schema must be an object`,
+                    category: "stage",
+                    stageId: entryId,
+                },
+            ]);
+        }
+        try {
+            compilePayloadSchema(raw.clone_input_schema);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return loadFailure([
+                {
+                    code: "stage.invalid_clone_input_schema",
+                    message: `Invalid stage ${label}: invalid clone_input_schema: ${message}`,
+                    category: "stage",
+                    stageId: entryId,
+                },
+            ]);
+        }
+        stage.clone_input_schema = raw.clone_input_schema;
+    }
+    const cloneActionsOutcome = parseCloneActions(raw.clone_actions, label);
+    if (!cloneActionsOutcome.ok) {
+        const issues = cloneActionsOutcome.issues.map((issue) => ({
+            ...issue,
+            stageId: entryId,
+        }));
+        return loadFailure(issues);
+    }
+    if (cloneActionsOutcome.value !== undefined) {
+        stage.clone_actions = cloneActionsOutcome.value;
+    }
     const gateKindsOutcome = parseGateKinds(raw.gate_kinds, label);
     if (!gateKindsOutcome.ok) {
         const issues = gateKindsOutcome.issues.map((issue) => ({
@@ -86,8 +185,31 @@ function parseStageFields(raw, label, entryId) {
         }));
         return loadFailure(issues);
     }
-    if (gateKindsOutcome.value)
+    if (gateKindsOutcome.value !== undefined) {
         stage.gate_kinds = gateKindsOutcome.value;
+    }
+    const timeoutMsOutcome = parseTimeoutMs(raw.timeout_ms, label);
+    if (!timeoutMsOutcome.ok) {
+        const issues = timeoutMsOutcome.issues.map((issue) => ({
+            ...issue,
+            stageId: entryId,
+        }));
+        return loadFailure(issues);
+    }
+    if (timeoutMsOutcome.value !== undefined) {
+        stage.timeout_ms = timeoutMsOutcome.value;
+    }
+    const preEmitChecksOutcome = parsePreEmitChecks(raw.pre_emit_checks, label);
+    if (!preEmitChecksOutcome.ok) {
+        const issues = preEmitChecksOutcome.issues.map((issue) => ({
+            ...issue,
+            stageId: entryId,
+        }));
+        return loadFailure(issues);
+    }
+    if (preEmitChecksOutcome.value !== undefined) {
+        stage.pre_emit_checks = preEmitChecksOutcome.value;
+    }
     if (raw.skill !== undefined) {
         if (typeof raw.skill !== "string" || raw.skill.trim() === "") {
             return loadFailure([
@@ -101,6 +223,20 @@ function parseStageFields(raw, label, entryId) {
         }
         stage.skill = raw.skill.trim();
     }
+    const agentField = parseAgentField(raw.agent);
+    if (!agentField.ok) {
+        return loadFailure([
+            {
+                code: "stage.invalid_agent",
+                message: `Invalid stage ${label}: ${agentField.message}`,
+                category: "stage",
+                stageId: entryId,
+            },
+        ]);
+    }
+    if (agentField.value !== undefined) {
+        stage.agent = agentField.value;
+    }
     return loadSuccess(stage);
 }
 export function loadStageFromObjectOutcome(raw, ctx) {

package/dist/config/loadStageflowManifest.js

@@ -1,6 +1,7 @@
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
 const DEFAULT_TASK_PATTERN = "*.task.yaml";
@@ -108,6 +109,14 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
         }
     }
     const patterns = parsePatterns(catalogRecord.patterns, issues);
+    let agent;
+    const agentField = parseAgentField(record.agent);
+    if (!agentField.ok) {
+        issues.push(catalogIssue("catalog.manifest_invalid", agentField.message));
+    }
+    else {
+        agent = agentField.value;
+    }
     if (issues.length > 0) {
         return loadFailure(issues);
     }
@@ -127,7 +136,11 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
             catalog.patterns.task = patterns.task;
         }
     }
-    const manifest = { version: 1, catalog };
+    const manifest = {
+        version: 1,
+        catalog,
+        ...(agent !== undefined ? { agent } : {}),
+    };
     return loadSuccess({
         path: manifestPath,
         projectRoot,

package/dist/config/mergePipelineIncludes.d.ts

@@ -6,4 +6,5 @@ export type RawMergedEntry = {
 export declare function mergePipelineStages(rootPath: string): Promise<LoadOutcome<{
     entries: RawMergedEntry[];
     pipelineId: string;
+    agent?: string;
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { readYamlObject } from "./readYamlObject.js";
 function isPlainObject(value) {
@@ -123,6 +124,18 @@ export async function mergePipelineStages(rootPath) {
         ]);
     }
     const pipelineId = raw.id;
+    const agentField = parseAgentField(raw.agent);
+    if (!agentField.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_agent",
+                message: `Invalid pipeline ${absRoot}: ${agentField.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    const agent = agentField.value;
     const idLocations = new Map();
     const entries = [];
     const mergeResult = await visitPipelineFile(absRoot, [], idLocations, entries);
@@ -137,5 +150,5 @@ export async function mergePipelineStages(rootPath) {
             },
         ]);
     }
-    return loadSuccess({ entries, pipelineId });
+    return loadSuccess({ entries, pipelineId, ...(agent !== undefined ? { agent } : {}) });
 }

package/dist/config/normalizePipelineStageEntry.d.ts

@@ -1,4 +1,5 @@
-import type { NormalizedPipelineStageEntry } from "../types/pipeline.js";
+import type { CompletionContract, RecoveryPolicy } from "../types/completion.js";
+import type { NormalizedPipelineStageEntry, PipelineNeeds } from "../types/pipeline.js";
 import { type LoadOutcome } from "./loadOutcome.js";
 import type { RawMergedEntry } from "./mergePipelineIncludes.js";
 export declare function inferIdFromUsesPath(usesPath: string): string | null;
@@ -8,11 +9,15 @@ export declare function normalizePipelineStageEntries(rawEntries: RawMergedEntry
 }): LoadOutcome<NormalizedPipelineStageEntry[]>;
 export declare function toWiringRefs(entries: NormalizedPipelineStageEntry[]): Array<{
     id: string;
-    needs?: string;
+    needs?: PipelineNeeds;
     fork?: {
         select: "one" | "subset";
         allow_none?: boolean;
     };
     clonable?: boolean;
     clone_cap?: number;
+    completion?: CompletionContract;
+    recovery?: RecoveryPolicy;
+    feedback_loop?: NormalizedPipelineStageEntry["feedback_loop"];
+    replay_safe?: boolean;
 }>;