stageflow 0.25.0 → 0.30.0

package/dist/cli/initTemplates.js

@@ -2,18 +2,48 @@ export const STAGEFLOW_YAML = `version: 1
 catalog:
   pipelines:
     - pipelines
+    - workshop
   tasks:
     - tasks
+    - workshop
   patterns:
     pipeline: "*.pipeline.yaml"
     task: "*.task.yaml"
 `;
-export const HELLO_PIPELINE_YAML = `id: hello
-model: anthropic/claude-sonnet-4-5
+export const LOUD_MODEL_PLACEHOLDER = "CHANGE_ME/<provider-model>";
+const PROVIDER_DEFAULT_MODELS = {
+    anthropic: "anthropic/claude-sonnet-4-5",
+    openrouter: "openrouter/auto",
+    cursor: "cursor/auto",
+};
+export function resolveInitDefaultModel(configuredProviderIds) {
+    const ids = [
+        ...new Set(configuredProviderIds
+            .map((id) => id.trim().toLowerCase())
+            .filter((id) => id.length > 0)),
+    ].sort((a, b) => a.localeCompare(b));
+    if (ids.length === 1) {
+        const id = ids[0];
+        return PROVIDER_DEFAULT_MODELS[id] ?? `CHANGE_ME/${id}-model`;
+    }
+    return LOUD_MODEL_PLACEHOLDER;
+}
+export function helloPipelineYaml(model) {
+    return `id: hello
 stages:
   - id: hello
+    model: "${model}"
     system_prompt: Say hello and emit a success envelope.
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
 `;
+}
+export const HELLO_PIPELINE_YAML = helloPipelineYaml("anthropic/claude-sonnet-4-5");
 export const HELLO_TASK_YAML = `id: hello
 goal: Run the hello pipeline scaffold.
 `;

package/dist/cli/resolveSafeOutPath.d.ts

@@ -0,0 +1,2 @@
+/** Resolve `--out` under cwd, realpath-normalizing both sides before containment. */
+export declare function resolveSafeOutPath(outPath: string, cwd: string): string;

package/dist/cli/resolveSafeOutPath.js

@@ -0,0 +1,40 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+function resolveEffectiveRealPathSync(candidatePath) {
+    try {
+        return realpathSync(candidatePath);
+    }
+    catch {
+        const missing = [];
+        let current = candidatePath;
+        while (true) {
+            missing.unshift(path.basename(current));
+            const parent = path.dirname(current);
+            if (parent === current) {
+                return path.resolve(candidatePath);
+            }
+            try {
+                const realParent = realpathSync(parent);
+                return path.join(realParent, ...missing);
+            }
+            catch {
+                current = parent;
+            }
+        }
+    }
+}
+/** Resolve `--out` under cwd, realpath-normalizing both sides before containment. */
+export function resolveSafeOutPath(outPath, cwd) {
+    const segments = outPath.split(/[/\\]/);
+    if (segments.some((segment) => segment === "..")) {
+        throw new Error("path must not contain .. segments");
+    }
+    const resolved = path.resolve(cwd, outPath);
+    const cwdResolved = resolveEffectiveRealPathSync(path.resolve(cwd));
+    const outResolved = resolveEffectiveRealPathSync(resolved);
+    if (!isInsideDir(outResolved, cwdResolved)) {
+        throw new Error("output path must resolve under the current working directory");
+    }
+    return resolved;
+}

package/dist/cli/restoreCommand.d.ts

@@ -0,0 +1,10 @@
+import { probeGlobalServiceDetailed } from "../server/ensureGlobalService.js";
+export declare const RESTORE_USAGE = "Usage:\n  sf restore <file> [--force] [--json]\n\nRestores a Stageflow backup. The Host must be down (probed via /livez).\nNever autostarts a Host. Previous state.db is moved aside, not deleted.";
+export type RestoreCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runRestoreCommand(args: string[], options?: {
+    io?: Partial<RestoreCommandIo>;
+    probe?: typeof probeGlobalServiceDetailed;
+}): Promise<number>;

package/dist/cli/restoreCommand.js

@@ -0,0 +1,90 @@
+import path from "node:path";
+import { applyRestoreArchive, RestoreError, } from "../runstore/restore.js";
+import { StoreSchemaError } from "../runstore/sqlite/storeSchemaError.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+export const RESTORE_USAGE = `Usage:
+  sf restore <file> [--force] [--json]
+
+Restores a Stageflow backup. The Host must be down (probed via /livez).
+Never autostarts a Host. Previous state.db is moved aside, not deleted.`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseRestoreArgs(args) {
+    let help = false;
+    let file;
+    let force = false;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg?.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else if (file === undefined) {
+            file = arg;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, file, force, json };
+}
+export async function runRestoreCommand(args, options = {}) {
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseRestoreArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(RESTORE_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(RESTORE_USAGE);
+        return 0;
+    }
+    if (!parsed.file) {
+        out.error("Missing <file>");
+        out.error(RESTORE_USAGE);
+        return 1;
+    }
+    try {
+        const result = await applyRestoreArchive({
+            archivePath: path.resolve(parsed.file),
+            homeDir: globalStageflowHome(),
+            force: parsed.force,
+            probe: options.probe,
+        });
+        if (parsed.json) {
+            out.log(JSON.stringify({ ok: true, ...result }));
+        }
+        else {
+            out.log(`Restored schema_version=${result.schema_version}` +
+                (result.missing_a2a_artifact_rows > 0
+                    ? ` (missing A2A artifact bytes: ${result.missing_a2a_artifact_rows})`
+                    : ""));
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof RestoreError || err instanceof StoreSchemaError) {
+            out.error(`${err.code}: ${err.message}`);
+            return 1;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+}

package/dist/cli/runCommand.d.ts

@@ -1,11 +1,12 @@
 import type { RunStore } from "../runstore/port.js";
 import type { StartRunResult } from "../runtime/runManager.js";
+import type { TaskFile } from "../types/task.js";
 import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
 import { type CliRunReportIo } from "./runOutput.js";
-export declare const RUN_USAGE = "Usage:\n  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>]";
+export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
 export type RunCommandIo = CliRunReportIo;
 export type StartRunFn = (input: {
-    task: string;
+    task: string | TaskFile;
     pipeline: string;
     checkoutOverride?: string;
     skipGates?: boolean;

package/dist/cli/runCommand.js

@@ -1,11 +1,16 @@
-import { PipelineValidationError } from "../runtime/pipelineRunner.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { coerceTaskFile } from "../config/loadTask.js";
+import { relativizeLocalPathForNetwork } from "../config/catalogRelativePath.js";
+import { PipelinePreflightError, PipelineValidationError } from "../runtime/pipelineRunner.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
-import { httpStartRun, httpStoreReader, resolveAbsolute } from "./hostClient.js";
-import { reportCliRun, } from "./runOutput.js";
+import { httpEnsureProject, httpStartRun, httpStoreReader } from "./hostClient.js";
+import { reportCliRun, writeQueuedAdmissionLine, } from "./runOutput.js";
 import { resolveCiIdentity } from "./ciIdentity.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const RUN_USAGE = `Usage:
-  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>]`;
+  sf run --task <path> --pipeline <path> [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
@@ -20,6 +25,8 @@ function parseRunArgs(args) {
     let task;
     let pipeline;
     let checkout;
+    let repository;
+    let ref;
     let gitSha;
     let ciPrUrl;
     let ciJobUrl;
@@ -55,6 +62,20 @@ function parseRunArgs(args) {
             }
             checkout = value;
         }
+        else if (arg === "--repository") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --repository");
+            }
+            repository = value;
+        }
+        else if (arg === "--ref") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --ref");
+            }
+            ref = value;
+        }
         else if (arg === "--git-sha") {
             const value = args[++i];
             if (value === undefined || value.length === 0) {
@@ -123,6 +144,8 @@ function parseRunArgs(args) {
         task,
         pipeline,
         checkout,
+        repository,
+        ref,
         gitSha,
         ciPrUrl,
         ciJobUrl,
@@ -130,18 +153,60 @@ function parseRunArgs(args) {
         operatorAgentDir,
     };
 }
+async function loadTaskWithBindingOverrides(taskPath, cwd, overrides) {
+    const absolute = path.resolve(cwd, taskPath);
+    const yamlText = await readFile(absolute, "utf8");
+    const raw = parseYaml(yamlText);
+    const task = coerceTaskFile(raw);
+    if (task === undefined) {
+        throw new Error(`Invalid task file ${absolute}: id and goal are required strings`);
+    }
+    if (overrides.repository !== undefined)
+        task.repository = overrides.repository;
+    if (overrides.ref !== undefined)
+        task.ref = overrides.ref;
+    return task;
+}
 function defaultStartRun(cwd, base, ensureService) {
     return async (input) => {
         const ensured = await ensureService();
         if (!ensured.ok) {
-            return { ok: false, reason: ensured.message, status: 503 };
+            return {
+                ok: false,
+                reason: ensured.message,
+                status: 503,
+                ...(ensured.reason === "autostart_disabled"
+                    ? { code: "autostart_disabled" }
+                    : {}),
+            };
         }
+        const pipelineRef = relativizeLocalPathForNetwork(cwd, input.pipeline);
+        let task = input.task;
+        let projectRoot = pipelineRef.project_root;
+        if (typeof input.task === "string") {
+            const absTask = path.resolve(cwd, input.task);
+            const cwdAbs = path.resolve(cwd);
+            const relTask = path.relative(cwdAbs, absTask);
+            if (relTask.startsWith("..") || path.isAbsolute(relTask)) {
+                task = await loadTaskWithBindingOverrides(input.task, cwd, {});
+            }
+            else {
+                const taskRef = relativizeLocalPathForNetwork(cwd, input.task);
+                task = taskRef.path;
+                projectRoot = taskRef.project_root;
+            }
+        }
+        const ensuredProject = await httpEnsureProject(base, projectRoot);
+        if (!ensuredProject.ok)
+            return ensuredProject;
+        const checkoutOverride = input.checkoutOverride !== undefined
+            ? relativizeLocalPathForNetwork(cwd, input.checkoutOverride).path
+            : undefined;
         return httpStartRun(base, {
-            pipeline: resolveAbsolute(cwd, input.pipeline),
-            task: resolveAbsolute(cwd, input.task),
-            ...(input.checkoutOverride !== undefined
-                ? { checkoutOverride: resolveAbsolute(cwd, input.checkoutOverride) }
-                : {}),
+            pipeline: pipelineRef.path,
+            task,
+            project_root: ensuredProject.project_root,
+            ...(checkoutOverride !== undefined ? { checkoutOverride } : {}),
             ...(input.skipGates !== undefined ? { skipGates: input.skipGates } : {}),
             ...(input.gitSha !== undefined ? { gitSha: input.gitSha } : {}),
             ...(input.ciPrUrl !== undefined ? { ciPrUrl: input.ciPrUrl } : {}),
@@ -200,8 +265,15 @@ export async function runRunCommand(args, options = {}) {
     });
     const store = options.store ?? (parsed.includeStages ? httpStoreReader(base) : undefined);
     try {
+        const hasBindingOverride = parsed.repository !== undefined || parsed.ref !== undefined;
+        const taskInput = hasBindingOverride
+            ? await loadTaskWithBindingOverrides(parsed.task, cwd, {
+                repository: parsed.repository,
+                ref: parsed.ref,
+            })
+            : parsed.task;
         const started = await startRun({
-            task: parsed.task,
+            task: taskInput,
             pipeline: parsed.pipeline,
             checkoutOverride: parsed.checkout,
             ...(parsed.skipGates ? { skipGates: true } : {}),
@@ -210,6 +282,7 @@ export async function runRunCommand(args, options = {}) {
         if (!started.ok) {
             return reportCliRun({ kind: "start-failure", started }, { json: parsed.json, io: out });
         }
+        writeQueuedAdmissionLine(started, out);
         return completeCliRun(started, out, {
             json: parsed.json,
             includeStages: parsed.includeStages,
@@ -226,6 +299,15 @@ export async function runRunCommand(args, options = {}) {
             }
             return exitCodeForValidation(err.result);
         }
+        if (err instanceof PipelinePreflightError) {
+            if (parsed.json) {
+                out.log(JSON.stringify(err.toNetworkBody(), null, 2));
+            }
+            else {
+                out.error(err.message);
+            }
+            return 1;
+        }
         out.error(err instanceof Error ? err.message : String(err));
         return 1;
     }

package/dist/cli/runOutput.d.ts

@@ -14,6 +14,10 @@ export type CliRunReportEvent = {
     kind: "completion";
     result: PipelineRunResult;
 };
+/** Stderr line when start_run was admitted to the queue (origin transparency rule). */
+export declare function writeQueuedAdmissionLine(started: Extract<StartRunResult, {
+    ok: true;
+}>, io: Pick<CliRunReportIo, "error">): void;
 export declare function reportCliRun(event: CliRunReportEvent, options: {
     json?: boolean;
     io: CliRunReportIo;

package/dist/cli/runOutput.js

@@ -20,6 +20,12 @@ async function tryReadTotalCostUsd(store, runId) {
 function isBusyCode(code) {
     return code === "busy_capacity" || code === "busy_checkout";
 }
+/** Stderr line when start_run was admitted to the queue (origin transparency rule). */
+export function writeQueuedAdmissionLine(started, io) {
+    if (started.queued === true && started.queuePosition !== undefined) {
+        io.error(`queued at position ${started.queuePosition}`);
+    }
+}
 function formatRunBusyJson(started) {
     const payload = {
         ok: false,
@@ -52,6 +58,13 @@ function formatRunStartFailedJson(started) {
     };
     if (started.code !== undefined)
         payload.code = started.code;
+    if (started.freeBytes !== undefined)
+        payload.freeBytes = started.freeBytes;
+    if (started.minFreeBytes !== undefined) {
+        payload.minFreeBytes = started.minFreeBytes;
+    }
+    if (started.stderr !== undefined)
+        payload.stderr = started.stderr;
     return stringify(payload);
 }
 function formatStartFailureJson(started) {
@@ -75,13 +88,21 @@ function baseRunCompletionPayload(result) {
                 runId: result.runId,
                 runDir: result.runDir,
             }
-            : {
-                ok: false,
-                outcome: "failed",
-                runId: result.runId,
-                runDir: result.runDir,
-            };
-    if (result.outcome === "failed" && result.reason !== undefined) {
+            : result.outcome === "cancelled"
+                ? {
+                    ok: false,
+                    outcome: "cancelled",
+                    runId: result.runId,
+                    runDir: result.runDir,
+                }
+                : {
+                    ok: false,
+                    outcome: "failed",
+                    runId: result.runId,
+                    runDir: result.runDir,
+                };
+    if ((result.outcome === "failed" || result.outcome === "cancelled") &&
+        result.reason !== undefined) {
         payload.reason = result.reason;
     }
     if (Array.isArray(result.findings) && result.findings.length > 0) {
@@ -130,6 +151,10 @@ function writeCompletionHuman(result, io, totalCostUsd) {
             io.error(`Pipeline failed: ${result.reason}`);
             io.error(`Run folder: ${result.runDir}`);
             break;
+        case "cancelled":
+            io.error(`Pipeline cancelled${result.reason ? `: ${result.reason}` : ""}`);
+            io.error(`Run folder: ${result.runDir}`);
+            break;
         case "succeeded":
             io.log(`Pipeline succeeded. Run folder: ${result.runDir}`);
             break;
@@ -145,6 +170,7 @@ function exitCodeForRunOutcome(outcome) {
         case "waiting":
             return 2;
         case "failed":
+        case "cancelled":
             return 1;
     }
 }

package/dist/cli/runStageCommand.d.ts

@@ -7,6 +7,7 @@ export type RunStageEnvelopeRef = {
 };
 export type RunStageToolArgs = {
     stage: string | Record<string, unknown>;
+    project_root?: string;
     task_path?: string;
     task?: Record<string, unknown>;
     envelope_ref?: RunStageEnvelopeRef | RunStageEnvelopeRef[];

package/dist/cli/runStageCommand.js

@@ -1,6 +1,7 @@
+import { relativizeLocalPathForNetwork } from "../config/catalogRelativePath.js";
 import { PACKAGE_VERSION } from "../package-meta.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
-import { resolveAbsolute } from "./hostClient.js";
+import { httpEnsureProject } from "./hostClient.js";
 export const RUN_STAGE_USAGE = `Usage:
   sf run-stage (--stage <path> | --stage-inline '<json>') (--task <path> | --task-inline '<json>' | --envelope-ref <runId>:<stageId>[:<attempt>] [--envelope-ref ...]) [--checkout <path>] [--model <id>] [--blocking] [--timeout-ms <n>] [--json]
 
@@ -247,9 +248,17 @@ function defaultCallTool(base, ensureService) {
         if (!ensured.ok) {
             throw new Error(ensured.message);
         }
+        let toolArgs = args;
+        if (args.project_root !== undefined) {
+            const ensuredProject = await httpEnsureProject(base, args.project_root);
+            if (!ensuredProject.ok) {
+                throw new Error(ensuredProject.reason);
+            }
+            toolArgs = { ...args, project_root: ensuredProject.project_root };
+        }
         const sessionId = await mcpInitializeSession(base);
         try {
-            return await mcpToolCall(base, sessionId, "run_stage", args);
+            return await mcpToolCall(base, sessionId, "run_stage", toolArgs);
         }
         finally {
             await mcpCloseSession(base, sessionId);
@@ -338,37 +347,48 @@ export async function runRunStageCommand(args, options = {}) {
         return 1;
     }
     let stage;
-    if (parsed.stage !== undefined) {
-        stage = resolveAbsolute(cwd, parsed.stage);
-    }
-    else {
-        try {
-            stage = parseJsonFlag(parsed.stageInline, "--stage-inline");
+    let projectRoot;
+    try {
+        if (parsed.stage !== undefined) {
+            const stageRef = relativizeLocalPathForNetwork(cwd, parsed.stage);
+            stage = stageRef.path;
+            projectRoot = stageRef.project_root;
         }
-        catch (err) {
-            out.error(err instanceof Error ? err.message : String(err));
-            return 1;
+        else {
+            stage = parseJsonFlag(parsed.stageInline, "--stage-inline");
         }
     }
+    catch (err) {
+        out.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
     let taskPath;
     let task;
     let envelopeRef;
-    if (parsed.task !== undefined) {
-        taskPath = resolveAbsolute(cwd, parsed.task);
-    }
-    else if (parsed.taskInline !== undefined) {
-        try {
+    try {
+        if (parsed.task !== undefined) {
+            const taskRef = relativizeLocalPathForNetwork(cwd, parsed.task);
+            taskPath = taskRef.path;
+            projectRoot = taskRef.project_root;
+        }
+        else if (parsed.taskInline !== undefined) {
             task = parseJsonFlag(parsed.taskInline, "--task-inline");
         }
-        catch (err) {
-            out.error(err instanceof Error ? err.message : String(err));
-            return 1;
+        else {
+            const refs = parsed.envelopeRef.map(parseEnvelopeRefFlag);
+            envelopeRef = refs.length === 1 ? refs[0] : refs;
         }
     }
-    else {
+    catch (err) {
+        out.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    let checkout;
+    if (parsed.checkout !== undefined) {
         try {
-            const refs = parsed.envelopeRef.map(parseEnvelopeRefFlag);
-            envelopeRef = refs.length === 1 ? refs[0] : refs;
+            const checkoutRef = relativizeLocalPathForNetwork(cwd, parsed.checkout);
+            checkout = checkoutRef.path;
+            projectRoot = projectRoot ?? checkoutRef.project_root;
         }
         catch (err) {
             out.error(err instanceof Error ? err.message : String(err));
@@ -377,12 +397,11 @@ export async function runRunStageCommand(args, options = {}) {
     }
     const toolArgs = {
         stage,
+        ...(projectRoot !== undefined ? { project_root: projectRoot } : {}),
         ...(taskPath !== undefined ? { task_path: taskPath } : {}),
         ...(task !== undefined ? { task } : {}),
         ...(envelopeRef !== undefined ? { envelope_ref: envelopeRef } : {}),
-        ...(parsed.checkout !== undefined
-            ? { checkout: resolveAbsolute(cwd, parsed.checkout) }
-            : {}),
+        ...(checkout !== undefined ? { checkout } : {}),
         ...(parsed.model !== undefined ? { model: parsed.model } : {}),
         ...(parsed.blocking ? { blocking: true } : {}),
         ...(parsed.timeoutMs !== undefined ? { timeout_ms: parsed.timeoutMs } : {}),

package/dist/cli/runsCommand.d.ts

@@ -1,6 +1,6 @@
 import type { RunStore } from "../runstore/port.js";
 import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
-export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs verify --run <runId> --stage <stageId> [--json]\n  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs resume --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs rerun --run <runId> [--json]";
+export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|queued|running|succeeded|failed|cancelled] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs verify --run <runId> --stage <stageId> [--json]\n  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs resume --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs cancel --run <runId> --reason <text> [--json]\n  sf runs delete --run <runId> [--force] [--json]\n  sf runs gc [--dry-run] [--json]\n  sf runs rerun --run <runId> [--pinned] [--json]";
 export type RunsCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;