stageflow 0.1.0 → 0.3.0

package/dist/agent/piAdapter.js

@@ -41,8 +41,8 @@ import { createAskOperatorTool, } from "../tools/askOperator.js";
 import { createWriteStageArtifactTool } from "../tools/writeStageArtifact.js";
 import "./cursorProvider.js";
 import { findProviderSupport } from "./providerSupport.js";
-import { mapSessionEventToActivity } from "./activity.js";
-import { createStageActivityObserver } from "./activityObserver.js";
+import { mapSessionEventToActivity, readActivityVerbose } from "./activity.js";
+import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runStageViaOpen } from "./port.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
@@ -260,31 +260,98 @@ export function createConnectedAskWaitStageHandle(options) {
         },
     };
 }
+/**
+ * Extract display text from a Pi tool_execution_update partialResult.
+ * Prefers content[].text blocks; otherwise JSON-stringifies.
+ */
+export function extractPartialResultText(partialResult) {
+    if (partialResult === undefined || partialResult === null) {
+        return "";
+    }
+    if (typeof partialResult === "string") {
+        return partialResult;
+    }
+    if (typeof partialResult === "object") {
+        const content = partialResult.content;
+        if (Array.isArray(content)) {
+            const parts = [];
+            for (const block of content) {
+                if (!block || typeof block !== "object")
+                    continue;
+                const b = block;
+                if (b.type === "text" && typeof b.text === "string") {
+                    parts.push(b.text);
+                }
+            }
+            if (parts.length > 0) {
+                return parts.join("");
+            }
+        }
+        try {
+            return JSON.stringify(partialResult);
+        }
+        catch {
+            return String(partialResult);
+        }
+    }
+    return String(partialResult);
+}
+/**
+ * Adapter-edge routing: stream deltas to the observer, map milestones to
+ * StageActivityEvent. Verbose thinking / live tool partials go to observer
+ * hooks (stderr streams + coalesced/throttled persist via onActivity).
+ */
+export function routeSessionEventToProgress(event, options) {
+    const { observer, verbose } = options;
+    if (event.type === "message_update") {
+        const ame = event.assistantMessageEvent;
+        if (ame && typeof ame === "object") {
+            const update = ame;
+            if (update.type === "text_delta") {
+                observer.onAssistantTextDelta(update.delta ?? "");
+                return;
+            }
+            if (verbose && update.type === "thinking_delta") {
+                observer.onThinkingDelta(update.delta ?? "");
+                return;
+            }
+        }
+        return;
+    }
+    if (verbose &&
+        event.type === "tool_execution_update") {
+        const text = extractPartialResultText(event.partialResult);
+        if (text) {
+            observer.onToolPartialResult(text);
+        }
+        return;
+    }
+    if (event.type === "message_end" || event.type === "agent_end") {
+        observer.onStreamBoundary();
+    }
+    if (event.type === "agent_start" ||
+        event.type === "turn_start" ||
+        event.type === "tool_execution_start") {
+        observer.onStreamBoundary();
+    }
+    const activity = mapSessionEventToActivity(event);
+    if (!activity) {
+        return;
+    }
+    observer.onActivity(activity);
+}
 /**
  * Map Pi session events to StageActivityEvent at the adapter edge, then
  * forward to the activity observer (stderr + onActivity).
  */
 function attachStageProgress(session, onActivity) {
     const observer = createStageActivityObserver({ onActivity, writeStderr: true });
+    const verbose = readActivityVerbose();
     const unsubscribe = session.subscribe((event) => {
-        if (event.type === "message_update" &&
-            event.assistantMessageEvent.type === "text_delta") {
-            observer.onAssistantTextDelta(event.assistantMessageEvent.delta ?? "");
-            return;
-        }
-        if (event.type === "message_end" || event.type === "agent_end") {
-            observer.onStreamBoundary();
-        }
-        if (event.type === "agent_start" ||
-            event.type === "turn_start" ||
-            event.type === "tool_execution_start") {
-            observer.onStreamBoundary();
-        }
-        const activity = mapSessionEventToActivity(event);
-        if (!activity) {
-            return;
-        }
-        observer.onActivity(activity);
+        routeSessionEventToProgress(event, {
+            observer,
+            verbose,
+        });
     });
     return () => {
         unsubscribe();
@@ -616,7 +683,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
     const provider = findProviderSupport(input.stage.model);
     const capture = {};
     const askWaitChannel = existingAskWaitChannel ?? new AskOperatorWaitChannel();
-    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema);
+    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext);
     const emitTool = defineTool(emitDef);
     const askDef = createAskOperatorTool({
         requestWait: (prompt) => askWaitChannel.requestWait(prompt),

package/dist/agent/port.d.ts

@@ -1,4 +1,5 @@
 import type { StageEnvelope } from "../types/envelope.js";
+import type { ForkEmitContext } from "../types/forkChoice.js";
 import type { StageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
 import type { StageActivityEvent } from "./activity.js";
@@ -15,6 +16,7 @@ export type StageRunInput = {
     /** Optional observe hook; HITL wait/answer uses openStage beside this. */
     onActivity?: (event: StageActivityEvent) => void;
     skillFilePath?: string;
+    forkEmitContext?: ForkEmitContext;
 };
 export type StageRunResult = {
     ok: true;

package/dist/agent/providerAuth.js

@@ -1,5 +1,7 @@
 import { CredentialSynchronizationError, ModelRuntime, } from "@earendil-works/pi-coding-agent";
-import { isUsableAuthFile, parseCredentialSource, piHomeAuthPath, readCredentialSourceFromFile, resolveCredentialBinding, writeCredentialSourceToFile, } from "../runtime/credentialBinding.js";
+import { isUsableAuthFile, parseCredentialSource, piHomeAuthPath, resolveCredentialBinding, writeCredentialSourceToContext, } from "../runtime/credentialBinding.js";
+import { readPersistedCredentialSourceFromContext, } from "../runtime/settingsFile.js";
+import { resolveProjectContext } from "../project/resolveProjectContext.js";
 export function makeMutationLock() {
     let tail = Promise.resolve();
     return {
@@ -245,8 +247,9 @@ export async function logoutProvider(cwd, providerId, ctx = defaultContext) {
     });
 }
 export function detectPiHome(cwd) {
-    const binding = resolveCredentialBinding(cwd);
-    const persisted = readCredentialSourceFromFile(cwd);
+    const projectCtx = resolveProjectContext(cwd);
+    const binding = resolveCredentialBinding(projectCtx);
+    const persisted = readPersistedCredentialSourceFromContext(projectCtx);
     return {
         piHomeUsable: isUsableAuthFile(piHomeAuthPath()),
         ...(persisted !== undefined ? { credentialSource: persisted } : {}),
@@ -255,8 +258,9 @@ export function detectPiHome(cwd) {
     };
 }
 export function getCredentialSourceSettings(cwd) {
-    const persisted = readCredentialSourceFromFile(cwd);
-    const binding = resolveCredentialBinding(cwd);
+    const projectCtx = resolveProjectContext(cwd);
+    const persisted = readPersistedCredentialSourceFromContext(projectCtx);
+    const binding = resolveCredentialBinding(projectCtx);
     return {
         ...(persisted !== undefined ? { credentialSource: persisted } : {}),
         binding: {
@@ -270,8 +274,9 @@ export function setCredentialSource(cwd, credentialSource) {
     if (parsed === undefined) {
         throw new ProviderAuthError('credentialSource must be "pi_home" or "sf_owned"', 400);
     }
-    writeCredentialSourceToFile(cwd, parsed);
-    const binding = resolveCredentialBinding(cwd);
+    const projectCtx = resolveProjectContext(cwd);
+    writeCredentialSourceToContext(projectCtx, parsed);
+    const binding = resolveCredentialBinding(projectCtx);
     return {
         credentialSource: parsed,
         binding: {

package/dist/catalog/displayCatalogPath.d.ts

@@ -0,0 +1,12 @@
+export declare function displayCatalogPath(absPath: string, projectRoot?: string): string;
+export declare function normalizeCatalogSlashes(pathValue: string): string;
+export type PipelinePathMatchInput = {
+    pipeline_id: string;
+    pipeline_path?: string;
+    project_root?: string;
+};
+export type PipelineListingPath = {
+    id: string;
+    path: string;
+};
+export declare function matchPipelineRun(run: PipelinePathMatchInput, pipeline: PipelineListingPath): boolean;

package/dist/catalog/displayCatalogPath.js

@@ -0,0 +1,28 @@
+export function displayCatalogPath(absPath, projectRoot) {
+    if (projectRoot) {
+        const root = projectRoot.replace(/\\/g, "/").replace(/\/$/, "");
+        const normalized = absPath.replace(/\\/g, "/");
+        if (normalized === root)
+            return ".";
+        const prefix = `${root}/`;
+        if (normalized.startsWith(prefix)) {
+            return normalized.slice(prefix.length);
+        }
+    }
+    const parts = absPath.replace(/\\/g, "/").split("/");
+    return parts[parts.length - 1] ?? absPath;
+}
+export function normalizeCatalogSlashes(pathValue) {
+    return pathValue.replace(/\\/g, "/");
+}
+export function matchPipelineRun(run, pipeline) {
+    if (run.pipeline_id === pipeline.id)
+        return true;
+    if (run.pipeline_path && run.project_root) {
+        const rel = displayCatalogPath(run.pipeline_path, run.project_root);
+        if (normalizeCatalogSlashes(rel) === normalizeCatalogSlashes(pipeline.path)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/cli/ciIdentity.d.ts

@@ -0,0 +1,14 @@
+export type CiIdentityFlags = {
+    gitSha?: string;
+    ciPrUrl?: string;
+    ciJobUrl?: string;
+};
+export type CiIdentity = {
+    gitSha?: string;
+    ciPrUrl?: string;
+    ciJobUrl?: string;
+};
+export declare function resolveCiIdentity(input: {
+    flags: CiIdentityFlags;
+    env: Record<string, string | undefined>;
+}): CiIdentity;

package/dist/cli/ciIdentity.js

@@ -0,0 +1,52 @@
+function nonempty(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function prNumberFromEnv(env) {
+    const ref = nonempty(env.GITHUB_REF);
+    if (ref !== undefined) {
+        const match = /^refs\/pull\/(\d+)\//.exec(ref);
+        if (match?.[1] !== undefined)
+            return match[1];
+    }
+    const refName = nonempty(env.GITHUB_REF_NAME);
+    if (refName !== undefined) {
+        const match = /^(\d+)\/merge$/.exec(refName);
+        if (match?.[1] !== undefined)
+            return match[1];
+    }
+    return undefined;
+}
+export function resolveCiIdentity(input) {
+    const result = {};
+    const gitSha = nonempty(input.flags.gitSha) ?? nonempty(input.env.GITHUB_SHA);
+    if (gitSha !== undefined)
+        result.gitSha = gitSha;
+    const flagPrUrl = nonempty(input.flags.ciPrUrl);
+    if (flagPrUrl !== undefined) {
+        result.ciPrUrl = flagPrUrl;
+    }
+    else {
+        const prNumber = prNumberFromEnv(input.env);
+        const server = nonempty(input.env.GITHUB_SERVER_URL);
+        const repo = nonempty(input.env.GITHUB_REPOSITORY);
+        if (prNumber !== undefined && server !== undefined && repo !== undefined) {
+            result.ciPrUrl = `${server}/${repo}/pull/${prNumber}`;
+        }
+    }
+    const flagJobUrl = nonempty(input.flags.ciJobUrl);
+    if (flagJobUrl !== undefined) {
+        result.ciJobUrl = flagJobUrl;
+    }
+    else {
+        const server = nonempty(input.env.GITHUB_SERVER_URL);
+        const repo = nonempty(input.env.GITHUB_REPOSITORY);
+        const runId = nonempty(input.env.GITHUB_RUN_ID);
+        if (server !== undefined && repo !== undefined && runId !== undefined) {
+            result.ciJobUrl = `${server}/${repo}/actions/runs/${runId}`;
+        }
+    }
+    return result;
+}

package/dist/cli/initCommand.d.ts

@@ -0,0 +1,9 @@
+export declare const INIT_USAGE = "Usage:\n  sf init";
+export type InitCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runInitCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<InitCommandIo>;
+}): Promise<number>;

package/dist/cli/initCommand.js

@@ -0,0 +1,71 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { findProjectRoot } from "../project/findProjectRoot.js";
+import { ensureGlobalHome } from "../project/globalHome.js";
+import { HELLO_PIPELINE_YAML, HELLO_TASK_YAML, STAGEFLOW_YAML, } from "./initTemplates.js";
+export const INIT_USAGE = `Usage:
+  sf init`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+const INIT_TARGETS = [
+    { relPath: "stageflow.yaml", content: STAGEFLOW_YAML },
+    { relPath: "pipelines/hello.pipeline.yaml", content: HELLO_PIPELINE_YAML },
+    { relPath: "tasks/hello.task.yaml", content: HELLO_TASK_YAML },
+];
+async function fileExists(absPath) {
+    try {
+        await access(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseInitArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    if (args[0].startsWith("-")) {
+        throw new Error(`Unknown flag: ${args[0]}`);
+    }
+    throw new Error(`Unexpected argument: ${args[0]}`);
+}
+export async function runInitCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const out = { ...defaultIo, ...options.io };
+    try {
+        const parsed = parseInitArgs(args);
+        if (parsed.help) {
+            out.error(INIT_USAGE);
+            return 0;
+        }
+        const initRoot = findProjectRoot(cwd) ?? path.resolve(cwd);
+        ensureGlobalHome();
+        for (const target of INIT_TARGETS) {
+            const absPath = path.join(initRoot, target.relPath);
+            if (await fileExists(absPath)) {
+                out.log(`Skipped ${target.relPath} (exists)`);
+                continue;
+            }
+            await mkdir(path.dirname(absPath), { recursive: true });
+            await writeFile(absPath, target.content, "utf8");
+            out.log(`Created ${target.relPath}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error
+            ? err.message
+            : typeof err === "string"
+                ? err
+                : "Init command failed";
+        out.error(message);
+        out.error(INIT_USAGE);
+        return 1;
+    }
+}

package/dist/cli/initTemplates.d.ts

@@ -0,0 +1,3 @@
+export declare const STAGEFLOW_YAML = "version: 1\ncatalog:\n  pipelines:\n    - pipelines\n  tasks:\n    - tasks\n  patterns:\n    pipeline: \"*.pipeline.yaml\"\n    task: \"*.task.yaml\"\n";
+export declare const HELLO_PIPELINE_YAML = "id: hello\nstages:\n  - id: hello\n    system_prompt: Say hello and emit a success envelope.\n    model: anthropic/claude-sonnet-4-5\n";
+export declare const HELLO_TASK_YAML = "id: hello\ngoal: Run the hello pipeline scaffold.\n";

package/dist/cli/initTemplates.js

@@ -0,0 +1,19 @@
+export const STAGEFLOW_YAML = `version: 1
+catalog:
+  pipelines:
+    - pipelines
+  tasks:
+    - tasks
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"
+`;
+export const HELLO_PIPELINE_YAML = `id: hello
+stages:
+  - id: hello
+    system_prompt: Say hello and emit a success envelope.
+    model: anthropic/claude-sonnet-4-5
+`;
+export const HELLO_TASK_YAML = `id: hello
+goal: Run the hello pipeline scaffold.
+`;

package/dist/cli/operatorCatalog.d.ts

@@ -0,0 +1,10 @@
+import type { OperatorCatalog } from "../runtime/stageAttemptBootstrap.js";
+export type OperatorCatalogFlags = {
+    operatorCwd?: string;
+    operatorAgentDir?: string;
+};
+export declare function resolveOperatorCatalog(input: {
+    flags: OperatorCatalogFlags;
+    env: Record<string, string | undefined>;
+    defaultCwd: string;
+}): OperatorCatalog;

package/dist/cli/operatorCatalog.js

@@ -0,0 +1,16 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+function nonempty(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+export function resolveOperatorCatalog(input) {
+    const cwd = nonempty(input.flags.operatorCwd) ??
+        nonempty(input.env.STAGEFLOW_OPERATOR_CWD) ??
+        input.defaultCwd;
+    const agentDir = nonempty(input.flags.operatorAgentDir) ??
+        nonempty(input.env.STAGEFLOW_OPERATOR_AGENT_DIR) ??
+        getAgentDir();
+    return { cwd, agentDir };
+}

package/dist/cli/runCommand.d.ts

@@ -0,0 +1,26 @@
+import { type StartRunResult } from "../runtime/runManager.js";
+import { type CliRunReportIo } from "./runOutput.js";
+export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--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;
+    pipeline: string;
+    checkoutOverride?: string;
+    skipGates?: boolean;
+    gitSha?: string;
+    ciPrUrl?: string;
+    ciJobUrl?: string;
+}) => Promise<StartRunResult>;
+export declare function completeCliRun(started: Extract<StartRunResult, {
+    ok: true;
+}>, io?: RunCommandIo, options?: {
+    json?: boolean;
+}): Promise<number>;
+export declare function runRunCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    isGitProject?: boolean;
+    io?: Partial<RunCommandIo>;
+    startRun?: StartRunFn;
+    env?: Record<string, string | undefined>;
+}): Promise<number>;

package/dist/cli/runCommand.js

@@ -0,0 +1,209 @@
+import { PiAgentAdapter } from "../agent/piAdapter.js";
+import { createRunStore } from "../runstore/createStore.js";
+import { PipelineValidationError } from "../runtime/pipelineRunner.js";
+import { RunManager } from "../runtime/runManager.js";
+import { readStageExecutionMode } from "../runtime/stageConcurrency.js";
+import { reportCliRun, } from "./runOutput.js";
+import { resolveCiIdentity } from "./ciIdentity.js";
+import { resolveOperatorCatalog } from "./operatorCatalog.js";
+import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
+export const RUN_USAGE = `Usage:
+  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--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),
+};
+function parseRunArgs(args) {
+    if (args.length === 0) {
+        return { help: false, json: false, skipGates: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, json: false, skipGates: false };
+    }
+    let task;
+    let pipeline;
+    let checkout;
+    let gitSha;
+    let ciPrUrl;
+    let ciJobUrl;
+    let operatorCwd;
+    let operatorAgentDir;
+    let json = false;
+    let skipGates = false;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--task") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --task");
+            }
+            task = value;
+        }
+        else if (arg === "--pipeline") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --pipeline");
+            }
+            pipeline = value;
+        }
+        else if (arg === "--checkout") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --checkout");
+            }
+            checkout = value;
+        }
+        else if (arg === "--git-sha") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --git-sha");
+            }
+            gitSha = value;
+        }
+        else if (arg === "--ci-pr-url") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --ci-pr-url");
+            }
+            ciPrUrl = value;
+        }
+        else if (arg === "--ci-job-url") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --ci-job-url");
+            }
+            ciJobUrl = value;
+        }
+        else if (arg === "--operator-cwd") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --operator-cwd");
+            }
+            operatorCwd = value;
+        }
+        else if (arg === "--operator-agent-dir") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --operator-agent-dir");
+            }
+            operatorAgentDir = value;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--skip-gates") {
+            skipGates = true;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return {
+        help,
+        json,
+        skipGates,
+        task,
+        pipeline,
+        checkout,
+        gitSha,
+        ciPrUrl,
+        ciJobUrl,
+        operatorCwd,
+        operatorAgentDir,
+    };
+}
+function defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog) {
+    return async (input) => {
+        const store = createRunStore({ rootDir: projectRoot });
+        const manager = new RunManager({
+            agent: new PiAgentAdapter(),
+            store,
+            cwd,
+            projectRoot,
+            isGitProject,
+            operatorCatalog,
+            executionMode: readStageExecutionMode(process.env, "process"),
+        });
+        return manager.startRun(input);
+    };
+}
+export async function completeCliRun(started, io = defaultIo, options = {}) {
+    const result = await started.done;
+    return reportCliRun({ kind: "completion", result }, { json: options.json, io });
+}
+export async function runRunCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const isGitProject = options.isGitProject ?? false;
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseRunArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(RUN_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(RUN_USAGE);
+        return 0;
+    }
+    if (!parsed.task || !parsed.pipeline) {
+        out.error("Missing --task and/or --pipeline");
+        out.error(RUN_USAGE);
+        return 1;
+    }
+    const operatorCatalog = resolveOperatorCatalog({
+        flags: {
+            operatorCwd: parsed.operatorCwd,
+            operatorAgentDir: parsed.operatorAgentDir,
+        },
+        env: options.env ?? process.env,
+        defaultCwd: cwd,
+    });
+    const startRun = options.startRun ??
+        defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog);
+    const identity = resolveCiIdentity({
+        flags: {
+            gitSha: parsed.gitSha,
+            ciPrUrl: parsed.ciPrUrl,
+            ciJobUrl: parsed.ciJobUrl,
+        },
+        env: options.env ?? process.env,
+    });
+    try {
+        const started = await startRun({
+            task: parsed.task,
+            pipeline: parsed.pipeline,
+            checkoutOverride: parsed.checkout,
+            ...(parsed.skipGates ? { skipGates: true } : {}),
+            ...identity,
+        });
+        if (!started.ok) {
+            return reportCliRun({ kind: "start-failure", started }, { json: parsed.json, io: out });
+        }
+        return completeCliRun(started, out, { json: parsed.json });
+    }
+    catch (err) {
+        if (err instanceof PipelineValidationError) {
+            if (parsed.json) {
+                out.log(formatValidationJson(err.result));
+            }
+            else {
+                out.error(formatValidationHuman(err.result));
+            }
+            return exitCodeForValidation(err.result);
+        }
+        out.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}