stageflow 0.33.0 → 0.36.0

package/dist/mcp/triggerTools.js

@@ -63,10 +63,7 @@ export function registerTriggerTools(server, deps) {
         description: "List catalog-declared triggers (same source as GET /api/triggers): manual/schedule/event kind, enabled, and store-recorded last_fired_at/last_run_id/next_run_at when present.",
         inputSchema: z.object({}),
     }, async () => {
-        const items = await loadCatalogTriggers(cwd, store);
-        if (items === undefined) {
-            return textResult({ error: "No Stageflow catalog found", status: 404 }, true);
-        }
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
         return textResult({ triggers: items });
     });
     server.registerTool("get_trigger", {
@@ -75,10 +72,7 @@ export function registerTriggerTools(server, deps) {
             id: z.string(),
         }),
     }, async ({ id }) => {
-        const items = await loadCatalogTriggers(cwd, store);
-        if (items === undefined) {
-            return textResult({ error: "No Stageflow catalog found", status: 404 }, true);
-        }
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
         const found = items.find((item) => item.id === id);
         if (!found) {
             return textResult({ error: `Trigger not found: ${id}`, status: 404 }, true);

package/dist/operatorAgent/agentPort.d.ts

@@ -0,0 +1,11 @@
+import { type LiveWorkshopOperatorHostOptions } from "./piModel.js";
+import type { OperatorAgentHost } from "./types.js";
+export declare const AGENT_PORT_BACKENDS: readonly ["pi"];
+export type AgentPortBackendId = (typeof AGENT_PORT_BACKENDS)[number];
+/** Stays up, takes a message, and answers. Stage runs stay on StagePort. */
+export type AgentPort = OperatorAgentHost;
+export type AgentPortOptions = LiveWorkshopOperatorHostOptions & {
+    backend?: AgentPortBackendId;
+};
+export declare function createPiAgentPort(options: LiveWorkshopOperatorHostOptions): AgentPort;
+export declare function resolveAgentPort(options: AgentPortOptions): AgentPort;

package/dist/operatorAgent/agentPort.js

@@ -0,0 +1,12 @@
+import { createLiveWorkshopOperatorHost, } from "./piModel.js";
+export const AGENT_PORT_BACKENDS = ["pi"];
+export function createPiAgentPort(options) {
+    return createLiveWorkshopOperatorHost(options);
+}
+export function resolveAgentPort(options) {
+    const backend = options.backend ?? "pi";
+    switch (backend) {
+        case "pi":
+            return createPiAgentPort(options);
+    }
+}

package/dist/operatorAgent/index.d.ts

@@ -1,6 +1,7 @@
 export type { AcceptProposalResult, OperatorAgentContextAdapter, OperatorAgentHost, OperatorAgentProfile, OperatorAgentProposal, OperatorAgentSession, OperatorAgentSessionEvent, OperatorAgentTool, OperatorAgentToolContext, OperatorAgentToolResult, ProposalArtifactDiff, UndoMutationResult, WorkshopDraftContext, WorkshopToolActivityUpdate, } from "./types.js";
 export { createOperatorAgentHost, invokeProfileTool, type OperatorAgentModel, type OperatorAgentModelTurn, } from "./host.js";
 export { createFakeOperatorAgentModel, createWorkshopOperatorHost, type FakeOperatorTurn, type WorkshopOperatorHostOptions, } from "./fakeHost.js";
+export { AGENT_PORT_BACKENDS, createPiAgentPort, resolveAgentPort, type AgentPortBackendId, type AgentPort, type AgentPortOptions, } from "./agentPort.js";
 export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, type LiveWorkshopOperatorHostOptions, type PiOperatorAgentModel, type PiOperatorAgentModelOptions, type PiOperatorOpenSessionInput, type PiOperatorSessionHandle, type WorkshopTranscriptSeedMessage, } from "./piModel.js";
 export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, type DocsRetrievalHit, type DocsRetrievalResult, type DocsRetriever, } from "./docsRetrieval.js";
 export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";

package/dist/operatorAgent/index.js

@@ -1,5 +1,6 @@
 export { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
 export { createFakeOperatorAgentModel, createWorkshopOperatorHost, } from "./fakeHost.js";
+export { AGENT_PORT_BACKENDS, createPiAgentPort, resolveAgentPort, } from "./agentPort.js";
 export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, } from "./piModel.js";
 export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, } from "./docsRetrieval.js";
 export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";

package/dist/operatorAgent/piModel.js

@@ -1,7 +1,8 @@
 /**
  * Live Pi-backed OperatorAgentModel for Workshop Author.
  *
- * Uses the shared Pi session factory (not AgentPort). Workshop tools only —
+ * Pi backend behind AgentPort, using the shared session factory. Not a StagePort.
+ * Workshop tools only —
  * resolveWorkshopToolNames / assertWorkshopToolsExcludeDiskShell. Durable Pi
  * session per host tool-context (R7). Restart: new Pi + transcript replay (KTD7).
  */
@@ -10,7 +11,7 @@ import path from "node:path";
 import { defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { createPiAgentSession, createSealedResourceLoader, resolveWorkshopToolNames, } from "../agent/piSessionFactory.js";
-import { cursorBridgePrompt } from "../agent/cursorProvider.js";
+import { bindCursorApiKey, cursorBridgePrompt } from "../agent/cursorProvider.js";
 import { findProviderSupport } from "../agent/providerSupport.js";
 import "../agent/cursorProvider.js";
 import { logger as rootLogger } from "../logging/logger.js";
@@ -158,8 +159,16 @@ function formatTranscriptReplay(transcript) {
         ...lines,
     ].join("\n");
 }
+function processDataAuthPath() {
+    return path.join(globalStageflowHome(), "agent", "auth.json");
+}
 function authNotConfiguredError(authPath) {
-    return new Error(`Workshop Author provider auth is not configured (auth file missing or empty: ${authPath}). Configure credentials via \`sf providers\` / the operator console Providers page, then retry.`);
+    const dataAuth = processDataAuthPath();
+    const unusedDataFile = path.resolve(dataAuth) !== path.resolve(authPath) &&
+        isUsableAuthFile(dataAuth)
+        ? ` A usable auth file at ${dataAuth} in the process data directory is not used.`
+        : "";
+    return new Error(`Workshop Author provider auth is not configured (auth file missing or empty: ${authPath}).${unusedDataFile} Configure credentials via \`sf providers\` / the operator console Providers page, then retry.`);
 }
 function syncAgentMessages(session, sessionManager) {
     if (session.agent?.state) {
@@ -185,15 +194,23 @@ function extractAssistantText(message) {
     return parts.length > 0 ? parts.join("") : undefined;
 }
 async function openDefaultPiSession(input) {
-    if (!isUsableAuthFile(input.authPath)) {
+    const provider = findProviderSupport(input.modelId);
+    if (!provider && !isUsableAuthFile(input.authPath)) {
         throw authNotConfiguredError(input.authPath);
     }
-    const provider = findProviderSupport(input.modelId);
     const additionalExtensionPaths = [];
     let restoreProvider;
+    let restoreCursorKey;
+    const bindCursor = (modelId) => {
+        const restore = bindCursorApiKey(modelId);
+        if (restore)
+            restoreCursorKey = restore;
+    };
+    bindCursor(input.modelId);
     if (provider) {
         const prepared = provider.prepare(input.modelId);
         if (prepared.error) {
+            restoreCursorKey?.();
             throw new Error(prepared.error);
         }
         additionalExtensionPaths.push(...prepared.extensionPaths);
@@ -260,6 +277,7 @@ async function openDefaultPiSession(input) {
         const applyModel = async (modelId) => {
             if (modelId === currentModelId)
                 return;
+            bindCursor(modelId);
             const provider = findProviderSupport(modelId);
             if (provider) {
                 const prepared = provider.prepare(modelId);
@@ -294,6 +312,7 @@ async function openDefaultPiSession(input) {
                 catch {
                     // best-effort
                 }
+                restoreCursorKey?.();
                 restoreProvider?.();
             },
         };
@@ -305,6 +324,7 @@ async function openDefaultPiSession(input) {
         catch {
             // best-effort
         }
+        restoreCursorKey?.();
         restoreProvider?.();
         throw err;
     }
@@ -522,7 +542,7 @@ export function createLiveWorkshopOperatorHost(options) {
     }), [
         createWorkshopAuthorProfile({
             retriever,
-            projectRoot: projectRoot ?? cwd,
+            ...(projectRoot !== undefined ? { projectRoot } : {}),
         }),
     ]);
 }

package/dist/operatorAgent/profiles/workshopAuthorPlaybook.d.ts

@@ -3,4 +3,4 @@
  * guidance and public YAML catalog concepts. First-class Workshop editors
  * cover the core path; advanced topics are explain-only.
  */
-export declare const WORKSHOP_AUTHOR_PLAYBOOK = "You are the Stageflow Workshop Author: a colleague designing a workflow with the operator. You are not a task runner and not a documentation bot.\n\n## How you talk\n- Sound like a working conversation. Short turns, plain words, present tense.\n- Default length is one to four sentences. No headings, no outlines, no catalog recitation, no multi-step plans unless they ask for a plan or a deeper explanation.\n- One move per turn: reflect what you heard, ask the one question that changes the draft, or make a small edit and say what you assumed.\n- Mirror their words. Refer back to decisions already made. If they correct you, drop the old assumption and continue.\n- Do not narrate tools (\"I'll call create_stage\"). The studio shows the draft. Say what changed in plain language.\n- The reference below is private. Use it when you edit. Do not recite it.\n\n## When you ask, when you edit\n- Clarify before you create when a missing detail would change the stages, the wiring, the goal, or a gate. Do not invent that detail.\n- Ask the single most useful question. Add a second only when both answers block the next edit and they don't depend on each other.\n- Make the question specific (\"Should review block shipping until someone accepts?\") rather than open (\"Tell me more\").\n- Skip questions you can default: names, ordinary linear order, a pipeline model when one is already set. Say the assumption in the same breath as the edit.\n- When the request is already specific, edit. Do not ask permission to do what they just asked.\n- Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.\n- When nothing is selected, create an untitled build and focus it.\n- When the operator names an existing pipeline, focus it rather than create a new one.\n- After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.\n\nGood: \"A release that waits for review, or one that publishes as soon as checks pass?\"\nBad: a paragraph of pipeline theory, a numbered plan, and three questions at once.\n\n## Tools\n- Never invent a disk path; never use bash/write/edit.\n- Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace \u2014 avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose\u2192Accept gating is superseded by immediate mutate + soft undo.\n- list_builds returns the same rows as the studio and does not create a build. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.\n- Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.\n- Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.\n- Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).\n- Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.\n- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML.\n- Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, \u2026) \u2014 not product stage types.\n- Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.\n- Core path = first-class Workshop editors. Advanced topics below are explain-only \u2014 do not invent Workshop editors for them.\n\n## Core: DAG / linear stages\n- Pipeline needs id + non-empty stages. Set model on pipeline (or stage / stageflow.yaml); empty at all tiers fails load.\n- Wire on the source only: entry: true on \u22651 root; forward route: [{ to }]. Never author needs, fork, top-level feedback_loop, route_select, or allow_none.\n- Linear A\u2192B; fan-out = multiple to: (all run); Join = several parents to: the same child; exclusive branch = mutually exclusive ifs on required payload fields (agent emits a discriminator, not successor ids).\n- if: leaf {field,op,value} or all/any/not; ops eq|ne|gt|gte|lt|lte|in|not_in. Path segments must be required in the producer io.output.schema.\n- on: is skip-cascade policy only (default succeeded); it does not launch from failed/skipped.\n- Consumer io.input \u2286 each parent's io.output. Prefer external stages when shared or larger than a tiny draft.\n\n## Core: prompts\n- Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).\n- Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.\n- Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.\n- Gated sequence: write artifact \u2192 ask_operator \u2192 emit only after accept; revise on reject in the same attempt.\n- Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.\n\n## Core: io / verify / on_verify_fail\n- Always author both io.input.schema and io.output.schema (object roots). Success payload is validated on emit.\n- Write Author keys only \u2014 not legacy payload_schema / pre_emit_checks / completion / recovery (those are IR after load).\n- verify lives on the stage body; when: [emit] | [after] | both. Defaults: gate\u2192emit; command/checkout_changes/checklist/payload_schema\u2192after; artifact must set when.\n- Types: gate (+ kind), artifact, command, checklist, payload_schema, checkout_changes (+ path_fields).\n- Emit-phase fail = soft reject (retry same turn). After-phase = verified stage execution hard proof.\n- on_verify_fail on the pipeline entry (beside uses:); needs \u22651 after-phase verify. Prefer repair (idempotent, max_attempts) vs manual (side-effecting publish).\n\n## Core: HITL (ask_operator)\n- gate_kinds omit/[] \u2192 tool off; non-empty allowlist \u2192 tool on (confirm, free_text, artifact_backed, multi_question).\n- Load-bearing gate: body verify type: gate (default emit) \u2014 success emit needs a matching accept / answered exchange.\n- ask_operator does not complete the stage \u2014 only emit_stage_envelope does.\n- artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.\n\n## Core: artifacts / envelopes\n- Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.\n- One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.\n- Catalog routing \u2260 agent fork_choice. Rejected: envelope clone_forks.\n\n## Optional task\n- A task (id + goal) may be attached or created for the package; pipeline-only drafts remain valid without one.\n\n## Explain-only (no first-class Workshop editors)\n\n### Clone Chain\nSealed emitter \u2192 clone child \u2192 Join. One named $ref array on the emitter; the child's whole input is that $ref. clone_cap + clone_mode on the emitter pipeline entry only. Empty/over-cap fails emitter emit. Never author clonable, clone_forks, or emit-time skip|once|fanout. Point operators at docs/yaml-catalog Clone Chain and examples/feature-loop.\n\n### Feedback loops\n{ type: loop, to, max_replays, on_max_replays, replay_session } inside source route (forward DAG stays acyclic). Success emit must include envelope feedback_loop: continue | send_back. replay_safe: false blocks replay. Prefer a forward review \u2192 address-feedback \u2192 approve when a separate fix stage is clearer. See examples/feedback-loop.\n\n### Stage MCP\nmcp: [names] on the pipeline entry; project-root .mcp.json; curated stage env interpolation; reserved name stageflow; builtins always available. Validate checks shape/names/PATH; connect/env fail at run. Explain and retrieve docs/examples (e.g. examples/stage-mcp); do not offer a Workshop MCP editor.\n\n### Complex recovery\nBeyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage; after-phase gates/artifacts are history- and disk-aware. Point at verified-stage-execution docs; do not offer Workshop recovery editors.\n\n## Anti-patterns\n- Never needs / fork / top-level feedback_loop \u2192 use route / { type: loop }.\n- Never legacy contract keys \u2192 use io / verify / on_verify_fail.\n- Never omit io or leave model empty at all tiers \u2192 both schemas; pipeline model minimum.\n- Never emit before HITL accept \u2192 verify gate + prompt sequence.\n- Never ambient Host secrets \u2192 stage secrets:.\n- Never clonable / clone_forks \u2192 sealed Clone Chain.\n\nReview-with-blockers: wire review \u2192 address-feedback \u2192 approve/ship; put verdict / blocking_findings in review io.output.schema.\n";
+export declare const WORKSHOP_AUTHOR_PLAYBOOK = "You are the Stageflow Workshop Author: a colleague designing a workflow with the operator. You are not a task runner and not a documentation bot.\n\n## How you talk\n- Sound like a working conversation. Short turns, plain words, present tense.\n- Default length is one to four sentences. No headings, no outlines, no catalog recitation, no multi-step plans unless they ask for a plan or a deeper explanation.\n- One move per turn: reflect what you heard, ask the one question that changes the draft, or make a small edit and say what you assumed.\n- Mirror their words. Refer back to decisions already made. If they correct you, drop the old assumption and continue.\n- Do not narrate tools (\"I'll call create_stage\"). The studio shows the draft. Say what changed in plain language.\n- The reference below is private. Use it when you edit. Do not recite it.\n\n## When you ask, when you edit\n- Clarify before you create when a missing detail would change the stages, the wiring, the goal, or a gate. Do not invent that detail.\n- Ask the single most useful question. Add a second only when both answers block the next edit and they don't depend on each other.\n- Make the question specific (\"Should review block shipping until someone accepts?\") rather than open (\"Tell me more\").\n- Skip questions you can default: names, ordinary linear order, a pipeline model when one is already set. Say the assumption in the same breath as the edit.\n- When the request is already specific, edit. Do not ask permission to do what they just asked.\n- Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.\n- When nothing is selected, create an untitled build and focus it.\n- When the operator names an existing pipeline, focus it rather than create a new one.\n- After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.\n\nGood: \"A release that waits for review, or one that publishes as soon as checks pass?\"\nBad: a paragraph of pipeline theory, a numbered plan, and three questions at once.\n\n## Tools\n- Never invent a disk path; never use bash/write/edit.\n- Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace \u2014 avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose\u2192Accept gating is superseded by immediate mutate + soft undo.\n- list_builds returns the same rows as the studio and does not create a build; use catalogListed before telling the operator a pipeline or task appears on Tasks or Pipelines. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.\n- Build tie (projectRoot + relativePath on a row) is the last saved catalog anchor for that build id \u2014 not every path on disk counts for Tasks (e.g. image package roots or paths outside stageflow.yaml scan). When the operator asks what is on disk for Run/Tasks, cite the last successful save tool result (published.project_root_path, published.pipeline_path, published.task_path) or a catalogListed row. Draft-only task changes are not on disk until save returns task_path.\n- Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.\n- Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.\n- Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).\n- Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.\n- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML. After save, use published.* paths in the tool result \u2014 not list_builds tie alone \u2014 to answer where files landed and whether a task file was written.\n- Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, \u2026) \u2014 not product stage types.\n- Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.\n- Core path = first-class Workshop editors. Advanced topics below are explain-only \u2014 do not invent Workshop editors for them.\n\n## Core: DAG / linear stages\n- Pipeline needs id + non-empty stages. Set model on pipeline (or stage / stageflow.yaml); empty at all tiers fails load.\n- Wire on the source only: entry: true on \u22651 root; forward route: [{ to }]. Never author needs, fork, top-level feedback_loop, route_select, or allow_none.\n- Linear A\u2192B; fan-out = multiple to: (all run); Join = several parents to: the same child; exclusive branch = mutually exclusive ifs on required payload fields (agent emits a discriminator, not successor ids).\n- if: leaf {field,op,value} or all/any/not; ops eq|ne|gt|gte|lt|lte|in|not_in. Path segments must be required in the producer io.output.schema.\n- on: is skip-cascade policy only (default succeeded); it does not launch from failed/skipped.\n- Consumer io.input \u2286 each parent's io.output. Prefer external stages when shared or larger than a tiny draft.\n\n## Core: prompts\n- Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).\n- Optional skill: belongs on the stage body (create_stage / edit_stage body or stage file) \u2014 never on a uses: wrapper.\n- Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.\n- Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.\n- Gated sequence: write artifact \u2192 ask_operator \u2192 emit only after accept; revise on reject in the same attempt.\n- Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.\n\n## Core: io / verify / on_verify_fail\n- Always author both io.input.schema and io.output.schema (object roots). Success payload is validated on emit.\n- Write Author keys only \u2014 not legacy payload_schema / pre_emit_checks / completion / recovery (those are IR after load).\n- verify lives on the stage body; when: [emit] | [after] | both. Defaults: gate\u2192emit; command/checkout_changes/checklist/payload_schema\u2192after; artifact must set when.\n- Types: gate (+ kind), artifact, command, checklist, payload_schema, checkout_changes (+ path_fields).\n- Emit-phase fail = soft reject (retry same turn). After-phase = verified stage execution hard proof.\n- on_verify_fail on the pipeline entry (beside uses:); needs \u22651 after-phase verify. Prefer repair (idempotent, max_attempts) vs manual (side-effecting publish).\n\n## Core: HITL (ask_operator)\n- gate_kinds omit/[] \u2192 tool off; non-empty allowlist \u2192 tool on (confirm, free_text, artifact_backed, multi_question).\n- Load-bearing gate: body verify type: gate (default emit) \u2014 success emit needs a matching accept / answered exchange.\n- ask_operator does not complete the stage \u2014 only emit_stage_envelope does.\n- artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.\n\n## Core: artifacts / envelopes\n- Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.\n- One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.\n- Catalog routing \u2260 agent fork_choice. Rejected: envelope clone_forks.\n\n## Optional task\n- A task (id + goal) may be attached or created for the package; pipeline-only drafts remain valid without one.\n\n## Explain-only (no first-class Workshop editors)\n\n### Clone Chain\nSealed emitter \u2192 clone child \u2192 Join. One named $ref array on the emitter; the child's whole input is that $ref. clone_cap + clone_mode on the emitter pipeline entry only. Empty/over-cap fails emitter emit. Never author clonable, clone_forks, or emit-time skip|once|fanout. Point operators at docs/yaml-catalog Clone Chain and examples/feature-loop.\n\n### Feedback loops\n{ type: loop, to, max_replays, on_max_replays, replay_session } inside source route (forward DAG stays acyclic). Success emit must include envelope feedback_loop: continue | send_back. replay_safe: false blocks replay. Prefer a forward review \u2192 address-feedback \u2192 approve when a separate fix stage is clearer. See examples/feedback-loop.\n\n### Stage MCP\nmcp: [names] on the pipeline entry; project-root .mcp.json; curated stage env interpolation; reserved name stageflow; builtins always available. Validate checks shape/names/PATH; connect/env fail at run. Explain and retrieve docs/examples (e.g. examples/stage-mcp); do not offer a Workshop MCP editor.\n\n### Complex recovery\nBeyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage; after-phase gates/artifacts are history- and disk-aware. Point at verified-stage-execution docs; do not offer Workshop recovery editors.\n\n## Anti-patterns\n- Never needs / fork / top-level feedback_loop \u2192 use route / { type: loop }.\n- Never legacy contract keys \u2192 use io / verify / on_verify_fail.\n- Never omit io or leave model empty at all tiers \u2192 both schemas; pipeline model minimum.\n- Never emit before HITL accept \u2192 verify gate + prompt sequence.\n- Never ambient Host secrets \u2192 stage secrets:.\n- Never clonable / clone_forks \u2192 sealed Clone Chain.\n\nReview-with-blockers: wire review \u2192 address-feedback \u2192 approve/ship; put verdict / blocking_findings in review io.output.schema.\n";

package/dist/operatorAgent/profiles/workshopAuthorPlaybook.js

@@ -30,12 +30,13 @@ Bad: a paragraph of pipeline theory, a numbered plan, and three questions at onc
 ## Tools
 - Never invent a disk path; never use bash/write/edit.
 - Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace — avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose→Accept gating is superseded by immediate mutate + soft undo.
-- list_builds returns the same rows as the studio and does not create a build. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.
+- list_builds returns the same rows as the studio and does not create a build; use catalogListed before telling the operator a pipeline or task appears on Tasks or Pipelines. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.
+- Build tie (projectRoot + relativePath on a row) is the last saved catalog anchor for that build id — not every path on disk counts for Tasks (e.g. image package roots or paths outside stageflow.yaml scan). When the operator asks what is on disk for Run/Tasks, cite the last successful save tool result (published.project_root_path, published.pipeline_path, published.task_path) or a catalogListed row. Draft-only task changes are not on disk until save returns task_path.
 - Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.
 - Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.
 - Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).
 - Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.
-- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML.
+- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML. After save, use published.* paths in the tool result — not list_builds tie alone — to answer where files landed and whether a task file was written.
 - Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, …) — not product stage types.
 - Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.
 - Core path = first-class Workshop editors. Advanced topics below are explain-only — do not invent Workshop editors for them.
@@ -50,6 +51,7 @@ Bad: a paragraph of pipeline theory, a numbered plan, and three questions at onc
 
 ## Core: prompts
 - Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).
+- Optional skill: belongs on the stage body (create_stage / edit_stage body or stage file) — never on a uses: wrapper.
 - Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.
 - Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.
 - Gated sequence: write artifact → ask_operator → emit only after accept; revise on reject in the same attempt.

package/dist/operatorAgent/profiles/workshopAuthorTools.js

@@ -1,6 +1,9 @@
+import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { CatalogPathError, resolveDefaultWriteRoot, } from "../../config/catalogRelativePath.js";
 import { defaultWorkshopPackageDirectory } from "../../config/ensureCatalogScanRoot.js";
 import { publishDraftPackage } from "../../config/publishDraftPackage.js";
+import { globalStageflowHome } from "../../project/globalHome.js";
 import { emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDraft, } from "../draftContext.js";
 import { focusUnboundWorkshopBuild, getWorkshopBuild, listWorkshopPickerRows, resolvePickerCatalogPipelines, } from "../../workshop/buildStore.js";
 import { focusWorkshopBuildPointer, pinWorkshopBuildOnCreate, recordPinnedWorkshopSave, resolveLiveWorkshopBinding, resolvePinnedSaveDestination, } from "../../workshop/workshopPin.js";
@@ -99,10 +102,10 @@ function readWorkshopContext(ctx) {
         return raw;
     return { draft: readDraftFromContext(raw) };
 }
-function resolveDestination(ctx, args) {
+function resolveDestination(ctx, args, catalogRootKind) {
     const directory = stringArg(args, "directory") ??
         readWorkshopContext(ctx).destination?.directory ??
-        defaultWorkshopPackageDirectory(readDraftFromContext(ctx.getContext()).pipeline.id);
+        defaultWorkshopPackageDirectory(readDraftFromContext(ctx.getContext()).pipeline.id, catalogRootKind);
     const pipelineFilename = stringArg(args, "pipelineFilename") ??
         stringArg(args, "pipeline_filename") ??
         readWorkshopContext(ctx).destination?.pipelineFilename;
@@ -113,6 +116,64 @@ function resolveProjectRoot(ctx, defaultProjectRoot) {
     // (or the profile/host default passed into createSaveTool).
     return readWorkshopContext(ctx).projectRoot ?? defaultProjectRoot ?? null;
 }
+async function resolveSaveWriteTarget(ctx, options) {
+    const bound = resolveProjectRoot(ctx, options.projectRoot);
+    const live = liveWorkshopBinding(ctx);
+    const storeRoot = live?.storeRoot ?? globalStageflowHome();
+    const { createRunStore } = await import("../../runstore/createStore.js");
+    const store = createRunStore({ rootDir: storeRoot });
+    try {
+        if (bound) {
+            try {
+                const { wireRoot } = await resolveDefaultWriteRoot({ store }, bound);
+                return {
+                    ok: true,
+                    target: {
+                        fsRoot: wireRoot.path,
+                        wireProjectRoot: wireRoot.project_root,
+                        catalogRootKind: wireRoot.kind,
+                    },
+                };
+            }
+            catch (err) {
+                if (err instanceof CatalogPathError &&
+                    err.code === "unknown_project_root") {
+                    const abs = path.resolve(bound);
+                    return {
+                        ok: true,
+                        target: {
+                            fsRoot: abs,
+                            wireProjectRoot: abs,
+                            catalogRootKind: "registered",
+                        },
+                    };
+                }
+                if (err instanceof CatalogPathError) {
+                    return { ok: false, error: err.message };
+                }
+                throw err;
+            }
+        }
+        const { wireRoot } = await resolveDefaultWriteRoot({ store }, undefined);
+        return {
+            ok: true,
+            target: {
+                fsRoot: wireRoot.path,
+                wireProjectRoot: wireRoot.project_root,
+                catalogRootKind: wireRoot.kind,
+            },
+        };
+    }
+    catch (err) {
+        if (err instanceof CatalogPathError) {
+            return { ok: false, error: err.message };
+        }
+        throw err;
+    }
+    finally {
+        await store.close();
+    }
+}
 export function buildCreateStageDraft(draft, args) {
     const existingIds = new Set(draft.pipeline.stages.map((s) => (typeof s.id === "string" ? s.id : "")));
     let stageId = stringArg(args, "id") ??
@@ -366,7 +427,7 @@ async function listPickerCatalog(storeRoot) {
 export function createWorkshopBuildTools() {
     const listBuildsTool = {
         name: "list_builds",
-        description: "List the same workshop rows as the studio picker (open builds and unbound disk pipelines). Does not create a build. Works when no build is focused.",
+        description: "List the same workshop rows as the studio picker (open builds and unbound disk pipelines). Each row includes catalogListed (whether Tasks/Pipelines would list that pipeline path). Does not create a build. Works when no build is focused.",
         async handler(_args, ctx) {
             const live = liveWorkshopBinding(ctx);
             if (!live) {
@@ -374,7 +435,16 @@ export function createWorkshopBuildTools() {
             }
             try {
                 const catalog = await listPickerCatalog(live.storeRoot);
-                const rows = listWorkshopPickerRows(live.storeRoot, catalog.pipelines, catalog.roots);
+                const rows = listWorkshopPickerRows(live.storeRoot, catalog.pipelines, catalog.roots).map((row) => {
+                    if (!row.projectRoot || !row.relativePath) {
+                        return { ...row, catalogListed: false };
+                    }
+                    const relPath = row.relativePath;
+                    const normalize = (value) => value.replace(/\\/g, "/").replace(/^\.\//, "");
+                    const listed = catalog.pipelines.some((pipeline) => pipeline.project_root === row.projectRoot &&
+                        normalize(pipeline.path) === normalize(relPath));
+                    return { ...row, catalogListed: listed };
+                });
                 return { ok: true, content: { rows } };
             }
             catch (err) {
@@ -556,23 +626,24 @@ export function createWorkshopAuthorMutatingTools() {
 export function createSaveTool(options = {}) {
     return {
         name: "save",
-        description: "Validate-then-write the draft via catalog facades (createDraftPackage / overwriteDraftPackage). When directory is omitted, writes under workshop/<pipeline-id>, which the host adds to the catalog so Run can see the pipeline and task. Pass directory only when the operator names a folder. Soft undo does not reverse disk. Prefer mode auto; set allowInvalid only when the operator explicitly requests saving invalid YAML. Do not pass projectRoot — the host binds it.",
+        description: "Validate-then-write the draft via catalog facades (createDraftPackage / overwriteDraftPackage). When directory is omitted, writes under workshop/<pipeline-id> on registered catalogs (or <pipeline-id> on the workspace catalog). The host adds registered workshop paths to stageflow.yaml so Run can see them. Pass directory only when the operator names a folder. Soft undo does not reverse disk. Prefer mode auto; set allowInvalid only when the operator explicitly requests saving invalid YAML. Do not pass projectRoot — the host binds it.",
         async handler(args, ctx) {
-            const pinnedDestination = resolvePinnedSaveDestination(ctx.getContext());
-            const destination = pinnedDestination ?? resolveDestination(ctx, args);
-            if (!destination) {
+            const writeTarget = await resolveSaveWriteTarget(ctx, options);
+            if (!writeTarget.ok) {
                 return {
                     ok: false,
                     content: null,
-                    error: "destination is required — set context.destination or pass directory (do not invent a disk path)",
+                    error: writeTarget.error,
                 };
             }
-            const projectRoot = resolveProjectRoot(ctx, options.projectRoot);
-            if (!projectRoot) {
+            const { fsRoot, catalogRootKind, wireProjectRoot } = writeTarget.target;
+            const pinnedDestination = resolvePinnedSaveDestination(ctx.getContext(), fsRoot);
+            const destination = pinnedDestination ?? resolveDestination(ctx, args, catalogRootKind);
+            if (!destination) {
                 return {
                     ok: false,
                     content: null,
-                    error: "projectRoot is required — bind it on the draft context (host-owned; do not invent from tool args)",
+                    error: "destination is required — set context.destination or pass directory (do not invent a disk path)",
                 };
             }
             const draft = readDraftFromContext(ctx.getContext());
@@ -589,7 +660,9 @@ export function createSaveTool(options = {}) {
                     : {}),
                 ...(allowInvalid ? { allowInvalid: true } : {}),
             };
-            const published = await publishDraftPackage(projectRoot, input, mode);
+            const published = await publishDraftPackage(fsRoot, input, mode, {
+                catalogRootKind,
+            });
             const result = published.write;
             if (result.ok) {
                 const current = readWorkshopContext(ctx);
@@ -602,20 +675,34 @@ export function createSaveTool(options = {}) {
                             ? { pipelineFilename: destination.pipelineFilename }
                             : {}),
                     },
-                    projectRoot,
+                    projectRoot: fsRoot,
                 });
                 recordPinnedWorkshopSave(ctx.getContext(), {
                     directory: destination.directory,
                     ...(destination.pipelineFilename
                         ? { pipelineFilename: destination.pipelineFilename }
                         : {}),
-                    projectRoot,
+                    projectRoot: fsRoot,
                     draft,
+                    relativePath: result.pipelinePath,
                 });
             }
             return {
                 ok: result.ok,
-                content: result,
+                content: result.ok
+                    ? {
+                        ...result,
+                        published: {
+                            project_root: wireProjectRoot,
+                            project_root_path: fsRoot,
+                            pipeline_path: result.pipelinePath,
+                            stage_paths: result.stagePaths,
+                            ...(result.taskPath !== undefined
+                                ? { task_path: result.taskPath }
+                                : { task_path: null }),
+                        },
+                    }
+                    : result,
                 ...(result.ok ? {} : { error: result.error }),
             };
         },

package/dist/package-meta.d.ts

@@ -1,3 +1,3 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.33.0";
+export declare const PACKAGE_VERSION = "0.36.0";
 export declare const BUILD_SHA: string;

package/dist/package-meta.js

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

package/dist/preflight/channelChecks.d.ts

@@ -0,0 +1,17 @@
+import type { AnyChannelProvider } from "../channels/types.js";
+import type { LoadedPipeline } from "../types/pipeline.js";
+import type { PreflightItem } from "./pipelinePreflight.js";
+export type ChannelCheckOptions = {
+    projectRoot: string;
+    hostEnv?: NodeJS.ProcessEnv;
+    providers?: readonly AnyChannelProvider[];
+    /** Waits between attempts. Each entry allows one more retry. */
+    retryDelaysMs?: readonly number[];
+    attemptTimeoutMs?: number;
+};
+export declare const DEFAULT_CHANNEL_RETRY_DELAYS_MS: readonly [500, 1500];
+export declare const DEFAULT_CHANNEL_ATTEMPT_TIMEOUT_MS = 8000;
+/** Live check of every connection a pipeline's stages declare. Never sends a message. */
+export declare function checkStageChannels(loaded: LoadedPipeline, options: ChannelCheckOptions): Promise<PreflightItem[]>;
+/** One line naming each failed connection and why. Codes and plain reasons only, never a secret. */
+export declare function channelFailureSummary(checks: readonly PreflightItem[]): string | undefined;

package/dist/preflight/channelChecks.js

@@ -0,0 +1,106 @@
+import { ChannelError } from "../channels/errors.js";
+import { ChannelRegistry } from "../channels/registry.js";
+import { channelErrorReason } from "../channels/errorInfo.js";
+import { channelTarget } from "../channels/stageChannels.js";
+export const DEFAULT_CHANNEL_RETRY_DELAYS_MS = [500, 1500];
+export const DEFAULT_CHANNEL_ATTEMPT_TIMEOUT_MS = 8000;
+function failed(code, retryable) {
+    return { state: "failed", checkedAt: new Date().toISOString(), error: { code, retryable } };
+}
+async function attempt(run, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise(resolve => {
+        timer = setTimeout(() => { controller.abort(); resolve(failed("CHANNEL_TIMEOUT", true)); }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run(controller.signal), timeout]);
+    }
+    catch (error) {
+        return error instanceof ChannelError
+            ? failed(error.code, error.retryable)
+            : failed("CHANNEL_CONNECTION_FAILED", false);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Retries only failures the provider marked transient. Authentication, configuration,
+ * permission and target problems return at once so a bad setup is never slowed or hidden.
+ */
+async function withRetry(run, options) {
+    let result = await attempt(run, options.timeoutMs);
+    for (const delay of options.delays) {
+        if (result.state === "ok" || result.error?.retryable !== true)
+            break;
+        await new Promise(resolve => setTimeout(resolve, delay));
+        result = await attempt(run, options.timeoutMs);
+    }
+    return result;
+}
+function item(connection, health) {
+    if (health.state === "ok")
+        return { kind: "channel", status: "ok", connection };
+    const code = health.error?.code ?? "CHANNEL_CONNECTION_FAILED";
+    return {
+        kind: "channel", status: "channel_check_failed", connection, channelCode: code,
+        retryable: health.error?.retryable ?? false, message: `connection "${connection}": ${code}`,
+    };
+}
+/** Live check of every connection a pipeline's stages declare. Never sends a message. */
+export async function checkStageChannels(loaded, options) {
+    const targetsByConnection = new Map();
+    for (const stage of loaded.stages) {
+        for (const channel of stage.channels ?? []) {
+            const targets = targetsByConnection.get(channel.connection) ?? new Map();
+            targets.set(JSON.stringify(channelTarget(channel)), channelTarget(channel));
+            targetsByConnection.set(channel.connection, targets);
+        }
+    }
+    if (targetsByConnection.size === 0)
+        return [];
+    let registry;
+    try {
+        registry = new ChannelRegistry({ cwd: options.projectRoot, env: options.hostEnv, providers: options.providers });
+    }
+    catch (error) {
+        const code = error instanceof ChannelError ? error.code : "CHANNEL_INVALID_INPUT";
+        return [...targetsByConnection.keys()].map(connection => item(connection, failed(code, false)));
+    }
+    const retry = {
+        delays: options.retryDelaysMs ?? DEFAULT_CHANNEL_RETRY_DELAYS_MS,
+        timeoutMs: options.attemptTimeoutMs ?? DEFAULT_CHANNEL_ATTEMPT_TIMEOUT_MS,
+    };
+    return Promise.all([...targetsByConnection].map(async ([id, targets]) => {
+        let resolved;
+        let provider;
+        try {
+            provider = registry.providerFor(id);
+            resolved = registry.resolve(id);
+        }
+        catch (error) {
+            return item(id, error instanceof ChannelError ? failed(error.code, false) : failed("CHANNEL_CONNECTION_FAILED", false));
+        }
+        const health = await withRetry(signal => provider.check(resolved, signal), retry);
+        if (health.state !== "ok" || !provider.checkTargets)
+            return item(id, health);
+        const validated = [...targets.values()].map(target => provider.validateTarget(target));
+        if (validated.some(result => !result.ok))
+            return item(id, failed("CHANNEL_TARGET_INVALID", false));
+        const values = validated.flatMap(result => (result.ok ? [result.value] : []));
+        return item(id, await withRetry(signal => provider.checkTargets(resolved, values, signal), retry));
+    }));
+}
+/** One line naming each failed connection and why. Codes and plain reasons only, never a secret. */
+export function channelFailureSummary(checks) {
+    const failed = checks.filter(check => check.kind === "channel" && check.status === "channel_check_failed");
+    if (failed.length === 0)
+        return undefined;
+    return failed
+        .map(check => {
+        const code = check.channelCode ?? "CHANNEL_CONNECTION_FAILED";
+        return `${check.connection}: ${channelErrorReason(code)} (${code})`;
+    })
+        .join("; ");
+}

package/dist/preflight/pipelinePreflight.d.ts

@@ -1,10 +1,11 @@
 import type { LoadedPipeline } from "../types/pipeline.js";
 import { type ToolRequirement } from "../config/toolRequires.js";
+import { type ChannelCheckOptions } from "./channelChecks.js";
 import { type CheckToolchainOptions, type ToolchainCheckResult } from "./toolchain.js";
-export type PreflightCheckKind = "toolchain" | "secret" | "mcp";
+export type PreflightCheckKind = "toolchain" | "secret" | "mcp" | "channel";
 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";
+    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" | "channel_check_failed";
     tool?: string;
     required?: string;
     found?: string;
@@ -12,6 +13,11 @@ export type PreflightItem = {
     secret?: string;
     stageId?: string;
     server?: string;
+    /** Connection id for `kind: "channel"`. */
+    connection?: string;
+    /** Provider-neutral channel error code, such as CHANNEL_AUTH_FAILED. */
+    channelCode?: string;
+    retryable?: boolean;
     message?: string;
 };
 export type PipelinePreflightResult = {
@@ -33,6 +39,7 @@ export declare function runPipelinePreflight(loaded: LoadedPipeline, options: {
     strict?: boolean;
     /** start_run: unknown_version passes; missing/mismatch fail. */
     forStart?: boolean;
+    channels?: Pick<ChannelCheckOptions, "providers" | "retryDelaysMs" | "attemptTimeoutMs">;
 }): Promise<PipelinePreflightResult>;
 export declare function preflightFailureCode(result: PipelinePreflightResult, options?: {
     strict?: boolean;