stageflow 0.19.0 → 0.23.0

package/README.md

@@ -190,7 +190,7 @@ Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository
 
 Host MCP via `sf ui` or `sf mcp` at `http://127.0.0.1:3847/mcp` (URL printed on boot). Sessions are the default. Point a Cursor (or other) MCP client at that URL. Do not run both hosts against the same store.
 
-HITL-aware tools include `wait_run`, `answer_gate`, and `list_waiting`. Full tool list: [docs/mcp.md](docs/mcp.md).
+HITL-aware tools include `wait_run`, `answer_gate`, `list_waiting`, and `decide_feedback_loop`. Inspect tools (`list_providers`, `list_models`, `describe_pipeline`, …) are read-only. Full tool list: [docs/mcp.md](docs/mcp.md).
 
 Stages use project `.mcp.json` plus stage `mcp` names. See [YAML catalog — Stage MCP](docs/yaml-catalog.md#stage-mcp).
 
@@ -222,6 +222,7 @@ If you want deterministic YAML routing across many agents, look at [Conductor](h
 | [playwright-mcp](examples/playwright-mcp/) | One stage: open a page and save a PNG screenshot (Playwright MCP) |
 | [context7-mcp](examples/context7-mcp/) | Three stages: resolve a library, fetch docs, write a brief (Context7 MCP) |
 | [github-release](examples/github-release/) | Dogfood: draft + publish GitHub Release |
+| [mcp-hitl-tour](examples/mcp-hitl-tour/) | MCP-first HITL: gates, fan-out/join, `wait_for_human` decide |
 | [ci-validate](examples/ci-validate/) | Strict validate in CI |
 
 Index: [examples/README.md](examples/README.md)

package/dist/agent/activity.d.ts

@@ -86,6 +86,11 @@ export type StageLifecycleEvent = {
 /** Operator chose to leave the verified failure terminal. */
  | {
     event: "manual_recovery_stopped";
+} | {
+    event: "feedback_loop_decided";
+    decision: "extend" | "continue" | "abandon";
+    loopId: string;
+    reason?: string;
 };
 export type StageLogLine = StageActivityEvent | StageLifecycleEvent;
 export declare function truncateActivityText(value: unknown, limit?: number): string | undefined;

package/dist/agent/activityObserver.d.ts

@@ -1,5 +1,6 @@
 import { type StageActivityEvent } from "./activity.js";
 export declare const TOOL_PROGRESS_THROTTLE_MS = 300;
+export declare const STREAM_FLUSH_THROTTLE_MS = 300;
 export type StageActivityObserver = {
     onAssistantTextDelta(delta: string): void;
     onThinkingDelta(delta: string): void;
@@ -10,6 +11,8 @@ export type StageActivityObserver = {
 };
 export type CreateStageActivityObserverOptions = {
     onActivity?: (event: StageActivityEvent) => void;
+    /** Fired for every non-empty assistant text delta, regardless of writeStderr. */
+    onAssistantTextDelta?: (delta: string) => void;
     writeStderr?: boolean;
     toolProgressThrottleMs?: number;
 };

package/dist/agent/activityObserver.js

@@ -1,5 +1,6 @@
 import { truncateActivityText, } from "./activity.js";
 export const TOOL_PROGRESS_THROTTLE_MS = 300;
+export const STREAM_FLUSH_THROTTLE_MS = 300;
 function writeIndentedPreview(preview) {
     for (const line of preview.split("\n")) {
         process.stderr.write(`    ${line}\n`);
@@ -127,7 +128,11 @@ export function createStageActivityObserver(options = {}) {
     };
     return {
         onAssistantTextDelta(delta) {
-            if (!writeStderr || !delta) {
+            if (!delta) {
+                return;
+            }
+            options.onAssistantTextDelta?.(delta);
+            if (!writeStderr) {
                 return;
             }
             assistantStreamedForMessage = true;

package/dist/agent/piAdapter.js

@@ -371,8 +371,12 @@ export function routeSessionEventToProgress(event, options) {
  * Map Pi session events to StageActivityEvent at the adapter edge, then
  * forward to the activity observer (stderr + onActivity).
  */
-function attachStageProgress(session, onActivity, usage) {
-    const observer = createStageActivityObserver({ onActivity, writeStderr: true });
+function attachStageProgress(session, onActivity, usage, onAssistantTextDelta) {
+    const observer = createStageActivityObserver({
+        onActivity,
+        onAssistantTextDelta,
+        writeStderr: true,
+    });
     const verbose = readActivityVerbose();
     const unsubscribe = session.subscribe((event) => {
         routeSessionEventToProgress(event, {
@@ -1119,7 +1123,7 @@ export class PiAgentAdapter {
                 return;
             }
             session = bound;
-            unsubscribeProgress = attachStageProgress(session, input.onActivity, wiring.usage);
+            unsubscribeProgress = attachStageProgress(session, input.onActivity, wiring.usage, input.onAssistantTextDelta);
         })();
         const runWithTimeout = async (work) => {
             await preparePromise;

package/dist/agent/port.d.ts

@@ -60,6 +60,8 @@ export type StageRunInput = {
     sessionMode?: StageSessionMode;
     /** Optional observe hook; HITL wait/answer uses openStage beside this. */
     onActivity?: (event: StageActivityEvent) => void;
+    /** Optional raw assistant-text-delta sink, fired alongside onActivity, not instead of it. */
+    onAssistantTextDelta?: (delta: string) => void;
     skillFilePath?: string;
     forkEmitContext?: ForkEmitContext;
     cloneEmitContext?: CloneEmitContext;

package/dist/agent/providerInspect.d.ts

@@ -0,0 +1,19 @@
+import { type PiHomeDetectResult, type ProviderAuthContext, type ProviderAuthStatus, type ProviderSummary, type ProvidersListResult } from "./providerAuth.js";
+export type ProviderReadinessRow = ProviderSummary & {
+    configured: boolean;
+    authKind?: ProviderAuthStatus["authKind"];
+    source?: string;
+};
+export type ProviderReadinessInspect = {
+    authShell: ProvidersListResult["authShell"];
+    via: ProvidersListResult["via"];
+    detect: PiHomeDetectResult;
+    providers: ProviderReadinessRow[];
+};
+export declare function inspectProviderReadiness(cwd: string, ctx?: ProviderAuthContext): Promise<ProviderReadinessInspect>;
+export declare function mapProviderAuthError(err: unknown): {
+    status: number;
+    body: {
+        error: string;
+    };
+};

package/dist/agent/providerInspect.js

@@ -0,0 +1,35 @@
+import { defaultContext, detectPiHome, getAuthStatus, listProviders, ProviderAuthError, } from "./providerAuth.js";
+function statusList(statuses) {
+    return Array.isArray(statuses) ? statuses : [statuses];
+}
+export async function inspectProviderReadiness(cwd, ctx = defaultContext) {
+    const listed = await listProviders(cwd, ctx);
+    const statuses = statusList(await getAuthStatus(cwd, undefined, ctx));
+    const statusById = new Map(statuses.map((status) => [status.providerId, status]));
+    const detect = detectPiHome(cwd);
+    return {
+        authShell: listed.authShell,
+        via: listed.via,
+        detect,
+        providers: listed.providers.map((provider) => {
+            const status = statusById.get(provider.id);
+            return {
+                ...provider,
+                configured: status?.configured ?? false,
+                ...(status?.authKind !== undefined
+                    ? { authKind: status.authKind }
+                    : {}),
+                ...(status?.source !== undefined ? { source: status.source } : {}),
+            };
+        }),
+    };
+}
+export function mapProviderAuthError(err) {
+    if (err instanceof ProviderAuthError) {
+        return { status: err.status, body: { error: err.message } };
+    }
+    return {
+        status: 500,
+        body: { error: "Provider auth operation failed" },
+    };
+}

package/dist/agent/streamLogRedact.d.ts

@@ -0,0 +1,2 @@
+/** Scrub common secret-shaped substrings before text is persisted or returned. */
+export declare function redactSecrets(text: string): string;

package/dist/agent/streamLogRedact.js

@@ -0,0 +1,13 @@
+const SECRET_PATTERNS = [
+    /\bsk-[A-Za-z0-9_-]{16,}\b/g,
+    /\bghp_[A-Za-z0-9]{20,}\b/g,
+    /\b[A-Za-z_]*KEY[A-Za-z_]*\s*[:=]\s*['"]?[A-Za-z0-9+/_-]{16,}['"]?/gi,
+];
+/** Scrub common secret-shaped substrings before text is persisted or returned. */
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of SECRET_PATTERNS) {
+        out = out.replace(pattern, "[redacted]");
+    }
+    return out;
+}

package/dist/cli/artifactCommand.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from "node:fs";
 import path from "node:path";
 import { readRunArtifact } from "../mcp/readArtifact.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { isInsideDir } from "../runstore/workspaceLayout.js";
 export const ARTIFACT_USAGE = `Usage:
@@ -73,7 +74,6 @@ function resolveSafeOutPath(outPath, cwd) {
 }
 export async function runArtifactCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -99,7 +99,7 @@ export async function runArtifactCommand(args, options = {}) {
         out.error(ARTIFACT_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     try {
         const contents = await readRunArtifact(store, parsed.runId, parsed.artifactPath);
         if (parsed.outPath !== undefined) {

package/dist/cli/envelopeCommand.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { buildHandoffDeliverable, isHandoffSkipped, } from "./handoffFormat.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 export const ENVELOPE_USAGE = `Usage:
   sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]`;
@@ -198,7 +199,6 @@ function formatHandoffHuman(result) {
 }
 export async function runEnvelopeCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -224,7 +224,7 @@ export async function runEnvelopeCommand(args, options = {}) {
         out.error(ENVELOPE_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     let runContext;
     try {
         runContext = resolveRunContext(parsed, cwd, store);

package/dist/cli/exportRunCommand.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { projectRun } from "../projection/projectRun.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { isInsideDir } from "../runstore/workspaceLayout.js";
 export const EXPORT_RUN_USAGE = `Usage:
@@ -94,7 +95,6 @@ function assertRunComplete(status, runId) {
 }
 export async function runExportRunCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -126,7 +126,7 @@ export async function runExportRunCommand(args, options = {}) {
         out.error(EXPORT_RUN_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     try {
         const detail = await store.readRun(runId);
         assertRunComplete(detail.status, runId);

package/dist/cli/hostClient.d.ts

@@ -0,0 +1,43 @@
+import type { PipelineRunResult } from "../runtime/pipelineRunner.js";
+import type { AbandonStageResult, DecideFeedbackLoopResult, StartRunResult, StopManualRecoveryResult } from "../runtime/runManager.js";
+import type { DeliverAnswerResult } from "../runtime/stageHitl.js";
+import type { RetryStageResult } from "../runtime/runRetryCoordinator.js";
+import type { RunDetail, RunStore } from "../runstore/port.js";
+export declare function computeRunDir(runId: string): string;
+export declare function httpReadRun(base: string, runId: string): Promise<RunDetail>;
+/** Thin RunStore-shaped reader backed by the global service, for the CLI output helpers that only need `readRun`. */
+export declare function httpStoreReader(base: string): Pick<RunStore, "readRun">;
+export declare function pollRunUntilTerminal(base: string, runId: string, options?: {
+    pollIntervalMs?: number;
+}): Promise<RunDetail>;
+export declare function runDetailToPipelineRunResult(detail: RunDetail): PipelineRunResult;
+export type HttpStartRunInput = {
+    pipeline: string;
+    task: string;
+    checkoutOverride?: string;
+    skipGates?: boolean;
+    gitSha?: string;
+    ciPrUrl?: string;
+    ciJobUrl?: string;
+};
+export declare function httpStartRun(base: string, input: HttpStartRunInput): Promise<StartRunResult>;
+export declare function httpRerun(base: string, runId: string): Promise<StartRunResult>;
+export declare function httpDeliverAnswer(base: string, runId: string, stageId: string, answer: unknown): Promise<DeliverAnswerResult>;
+export declare function httpDecideFeedbackLoop(base: string, runId: string, stageId: string, input: {
+    decision: "extend" | "continue" | "abandon";
+    loopId?: string;
+    reason?: string;
+}): Promise<DecideFeedbackLoopResult>;
+type RetryOrchestrationResult = {
+    ok: true;
+    pipeline: PipelineRunResult;
+} | Extract<RetryStageResult, {
+    ok: false;
+}>;
+export declare function httpRetryStageUntilStop(base: string, runId: string, stageId: string): Promise<RetryOrchestrationResult>;
+export declare function httpResumeTimedOutStage(base: string, runId: string, stageId: string): Promise<RetryStageResult>;
+export declare function httpRecoverManualStageUntilStop(base: string, runId: string, stageId: string, guidance?: string): Promise<RetryOrchestrationResult>;
+export declare function httpStopManualRecovery(base: string, runId: string, stageId: string): Promise<StopManualRecoveryResult>;
+export declare function httpAbandonStage(base: string, runId: string, stageId: string): Promise<AbandonStageResult>;
+export declare function resolveAbsolute(cwd: string, maybeRelative: string): string;
+export {};

package/dist/cli/hostClient.js

@@ -0,0 +1,182 @@
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { PipelineValidationError } from "../runtime/pipelineValidationError.js";
+import { runWorkspaceDir, storeRootFor } from "../runstore/paths.js";
+async function postJson(base, urlPath, body) {
+    const res = await fetch(`${base}${urlPath}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body ?? {}),
+    });
+    return { status: res.status, body: await parseJsonBody(res) };
+}
+async function getJson(base, urlPath) {
+    const res = await fetch(`${base}${urlPath}`);
+    return { status: res.status, body: await parseJsonBody(res) };
+}
+async function parseJsonBody(res) {
+    const text = await res.text();
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractError(body, status) {
+    if (body && typeof body === "object" && typeof body.error === "string") {
+        return body.error;
+    }
+    return `request to global Stageflow service failed (status ${status})`;
+}
+function enc(value) {
+    return encodeURIComponent(value);
+}
+export function computeRunDir(runId) {
+    return runWorkspaceDir(storeRootFor(globalStageflowHome()), runId);
+}
+export async function httpReadRun(base, runId) {
+    const { status, body } = await getJson(base, `/api/runs/${enc(runId)}`);
+    if (status !== 200) {
+        throw new Error(extractError(body, status));
+    }
+    return body;
+}
+/** Thin RunStore-shaped reader backed by the global service, for the CLI output helpers that only need `readRun`. */
+export function httpStoreReader(base) {
+    return { readRun: (runId) => httpReadRun(base, runId) };
+}
+function isRunTerminal(detail) {
+    return (detail.status === "succeeded" ||
+        detail.status === "failed" ||
+        (detail.status === "running" && detail.waiting_stage_id !== undefined));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function pollRunUntilTerminal(base, runId, options) {
+    const pollIntervalMs = options?.pollIntervalMs ?? 500;
+    for (;;) {
+        const detail = await httpReadRun(base, runId);
+        if (isRunTerminal(detail))
+            return detail;
+        await sleep(pollIntervalMs);
+    }
+}
+export function runDetailToPipelineRunResult(detail) {
+    const outcome = detail.status === "succeeded"
+        ? "succeeded"
+        : detail.status === "failed"
+            ? "failed"
+            : "waiting";
+    return {
+        ok: outcome === "succeeded",
+        outcome,
+        runId: detail.run_id,
+        runDir: computeRunDir(detail.run_id),
+        ...(outcome === "failed" && detail.failed_reason !== undefined
+            ? { reason: detail.failed_reason }
+            : {}),
+    };
+}
+function toStartFailure(status, body) {
+    const rest = body && typeof body === "object" ? { ...body } : {};
+    const error = typeof rest.error === "string" ? rest.error : undefined;
+    delete rest.error;
+    return {
+        ok: false,
+        reason: error ?? extractError(body, status),
+        status,
+        ...rest,
+    };
+}
+function validationResultFrom(body) {
+    if (body && typeof body === "object" && "validation" in body) {
+        return body.validation;
+    }
+    return undefined;
+}
+export async function httpStartRun(base, input) {
+    const { status, body } = await postJson(base, "/api/runs", input);
+    if (status === 400) {
+        const validation = validationResultFrom(body);
+        if (validation !== undefined)
+            throw new PipelineValidationError(validation);
+    }
+    if (status !== 202)
+        return toStartFailure(status, body);
+    const runId = body.runId;
+    return {
+        ok: true,
+        runId,
+        done: pollRunUntilTerminal(base, runId).then(runDetailToPipelineRunResult),
+    };
+}
+export async function httpRerun(base, runId) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/rerun`, {});
+    if (status !== 202)
+        return toStartFailure(status, body);
+    const newRunId = body.runId;
+    return {
+        ok: true,
+        runId: newRunId,
+        done: pollRunUntilTerminal(base, newRunId).then(runDetailToPipelineRunResult),
+    };
+}
+export async function httpDeliverAnswer(base, runId, stageId, answer) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/stages/${enc(stageId)}/answer`, answer);
+    if (status === 202)
+        return { ok: true };
+    return { ok: false, reason: extractError(body, status), status: status };
+}
+export async function httpDecideFeedbackLoop(base, runId, stageId, input) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/stages/${enc(stageId)}/feedback-decision`, input);
+    if (status === 202) {
+        const parsed = body;
+        return { ok: true, effect: parsed.effect, loopId: parsed.loopId };
+    }
+    return { ok: false, reason: extractError(body, status), status };
+}
+export async function httpRetryStageUntilStop(base, runId, stageId) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/stages/${enc(stageId)}/retry`, {});
+    if (status !== 202) {
+        return { ok: false, reason: extractError(body, status), status };
+    }
+    const detail = await pollRunUntilTerminal(base, runId);
+    return { ok: true, pipeline: runDetailToPipelineRunResult(detail) };
+}
+export async function httpResumeTimedOutStage(base, runId, stageId) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/stages/${enc(stageId)}/resume`, {});
+    if (status === 202) {
+        const parsed = body;
+        return { ok: true, runId: parsed.runId, stageId: parsed.stageId, attemptIndex: parsed.attemptIndex };
+    }
+    return { ok: false, reason: extractError(body, status), status };
+}
+export async function httpRecoverManualStageUntilStop(base, runId, stageId, guidance) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/stages/${enc(stageId)}/recovery`, guidance !== undefined ? { guidance } : {});
+    if (status !== 202) {
+        return { ok: false, reason: extractError(body, status), status };
+    }
+    const detail = await pollRunUntilTerminal(base, runId);
+    return { ok: true, pipeline: runDetailToPipelineRunResult(detail) };
+}
+export async function httpStopManualRecovery(base, runId, stageId) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/stages/${enc(stageId)}/recovery/stop`, {});
+    if (status === 202)
+        return body;
+    return { ok: false, reason: extractError(body, status), status };
+}
+export async function httpAbandonStage(base, runId, stageId) {
+    const { status, body } = await postJson(base, `/api/runs/${enc(runId)}/stages/${enc(stageId)}/abandon`, {});
+    if (status === 202) {
+        const parsed = body;
+        return { ok: true, runId: parsed.runId, stageId: parsed.stageId };
+    }
+    return { ok: false, reason: extractError(body, status), status };
+}
+export function resolveAbsolute(cwd, maybeRelative) {
+    return path.resolve(cwd, maybeRelative);
+}

package/dist/cli/providersCommand.js

@@ -1,4 +1,5 @@
-import { defaultContext, detectPiHome, getAuthStatus, getCredentialSourceSettings, listProviders, loginWithApiKey, loginWithOauth, logoutProvider, ProviderAuthError, setCredentialSource, } from "../agent/providerAuth.js";
+import { defaultContext, detectPiHome, getAuthStatus, getCredentialSourceSettings, listProviders, loginWithApiKey, loginWithOauth, logoutProvider, setCredentialSource, } from "../agent/providerAuth.js";
+import { mapProviderAuthError } from "../agent/providerInspect.js";
 import { createTerminalAuthInteraction } from "./terminalAuthInteraction.js";
 import { promptSecret, readApiKeyFromEnv } from "./terminalSecret.js";
 export const PROVIDERS_USAGE = `Usage:
@@ -152,8 +153,9 @@ export async function runProvidersCommand(args, cwd, io = {}, ctx = defaultConte
                     return 0;
                 }
                 catch (err) {
-                    if (err instanceof ProviderAuthError && err.status === 404) {
-                        out.error("Provider not found");
+                    const mapped = mapProviderAuthError(err);
+                    if (mapped.status === 404) {
+                        out.error(mapped.body.error);
                         return 1;
                     }
                     throw err;

package/dist/cli/runCommand.d.ts

@@ -1,5 +1,6 @@
 import type { RunStore } from "../runstore/port.js";
-import { type StartRunResult } from "../runtime/runManager.js";
+import type { StartRunResult } from "../runtime/runManager.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 type RunCommandIo = CliRunReportIo;
@@ -16,15 +17,15 @@ export declare function completeCliRun(started: Extract<StartRunResult, {
     ok: true;
 }>, io?: RunCommandIo, options?: {
     json?: boolean;
-    store?: RunStore;
+    store?: Pick<RunStore, "readRun">;
     includeStages?: boolean;
 }): Promise<number>;
 export declare function runRunCommand(args: string[], options?: {
     cwd?: string;
-    projectRoot?: string;
-    isGitProject?: boolean;
     io?: Partial<RunCommandIo>;
     startRun?: StartRunFn;
-    store?: RunStore;
+    store?: Pick<RunStore, "readRun">;
     env?: Record<string, string | undefined>;
+    hostBaseUrl?: string;
+    ensureService?: () => Promise<EnsureGlobalServiceResult>;
 }): Promise<number>;

package/dist/cli/runCommand.js

@@ -1,11 +1,8 @@
-import { resolveGlobalOnlyAgentPort } from "../agent/resolveAgentPort.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 { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
+import { httpStartRun, httpStoreReader, resolveAbsolute } from "./hostClient.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] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
@@ -133,19 +130,23 @@ function parseRunArgs(args) {
         operatorAgentDir,
     };
 }
-function defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog) {
+function defaultStartRun(cwd, base, ensureService) {
     return async (input) => {
-        const store = createRunStore({ rootDir: projectRoot });
-        const manager = new RunManager({
-            agent: await resolveGlobalOnlyAgentPort(projectRoot),
-            store,
-            cwd,
-            projectRoot,
-            isGitProject,
-            operatorCatalog,
-            executionMode: readStageExecutionMode(process.env, "process"),
+        const ensured = await ensureService();
+        if (!ensured.ok) {
+            return { ok: false, reason: ensured.message, status: 503 };
+        }
+        return httpStartRun(base, {
+            pipeline: resolveAbsolute(cwd, input.pipeline),
+            task: resolveAbsolute(cwd, input.task),
+            ...(input.checkoutOverride !== undefined
+                ? { checkoutOverride: resolveAbsolute(cwd, input.checkoutOverride) }
+                : {}),
+            ...(input.skipGates !== undefined ? { skipGates: input.skipGates } : {}),
+            ...(input.gitSha !== undefined ? { gitSha: input.gitSha } : {}),
+            ...(input.ciPrUrl !== undefined ? { ciPrUrl: input.ciPrUrl } : {}),
+            ...(input.ciJobUrl !== undefined ? { ciJobUrl: input.ciJobUrl } : {}),
         });
-        return manager.startRun(input);
     };
 }
 export async function completeCliRun(started, io = defaultIo, options = {}) {
@@ -159,9 +160,8 @@ export async function completeCliRun(started, io = defaultIo, options = {}) {
 }
 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 };
+    const base = options.hostBaseUrl ?? hostBaseUrl();
     let parsed;
     try {
         parsed = parseRunArgs(args);
@@ -185,16 +185,11 @@ export async function runRunCommand(args, options = {}) {
         out.error("error: --include stages requires --json");
         return 1;
     }
-    const operatorCatalog = resolveOperatorCatalog({
-        flags: {
-            operatorCwd: parsed.operatorCwd,
-            operatorAgentDir: parsed.operatorAgentDir,
-        },
-        env: options.env ?? process.env,
-        defaultCwd: cwd,
-    });
+    if (parsed.operatorCwd !== undefined || parsed.operatorAgentDir !== undefined) {
+        out.error("warning: --operator-cwd/--operator-agent-dir have no effect on `sf run` now that pipelines execute in the shared global Stageflow service; set STAGEFLOW_OPERATOR_CWD/STAGEFLOW_OPERATOR_AGENT_DIR before that service first starts instead.");
+    }
     const startRun = options.startRun ??
-        defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog);
+        defaultStartRun(cwd, base, options.ensureService ?? (() => ensureGlobalService()));
     const identity = resolveCiIdentity({
         flags: {
             gitSha: parsed.gitSha,
@@ -203,10 +198,7 @@ export async function runRunCommand(args, options = {}) {
         },
         env: options.env ?? process.env,
     });
-    const store = options.store ??
-        (parsed.includeStages
-            ? createRunStore({ rootDir: projectRoot })
-            : undefined);
+    const store = options.store ?? (parsed.includeStages ? httpStoreReader(base) : undefined);
     try {
         const started = await startRun({
             task: parsed.task,

package/dist/cli/runOutput.d.ts

@@ -17,6 +17,6 @@ export type CliRunReportEvent = {
 export declare function reportCliRun(event: CliRunReportEvent, options: {
     json?: boolean;
     io: CliRunReportIo;
-    store?: RunStore;
+    store?: Pick<RunStore, "readRun">;
     includeStages?: boolean;
 }): Promise<number>;

package/dist/cli/runsCommand.d.ts

@@ -1,22 +1,18 @@
 import type { RunStore } from "../runstore/port.js";
-import { RunManager } from "../runtime/runManager.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 type RunsCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;
 };
-export type HostProbeResult = "up" | "down";
-export declare function defaultProbeHost(): Promise<HostProbeResult>;
 export declare function runRunsCommand(args: string[], options?: {
     cwd?: string;
-    projectRoot?: string;
-    isGitProject?: boolean;
     io?: Partial<RunsCommandIo>;
     store?: RunStore;
-    probeHost?: () => Promise<HostProbeResult>;
     stdinIsTTY?: boolean;
     readStdin?: () => string;
     waitSignal?: AbortSignal;
     env?: NodeJS.ProcessEnv;
-    createManager?: (store: RunStore) => RunManager;
+    hostBaseUrl?: string;
+    ensureService?: () => Promise<EnsureGlobalServiceResult>;
 }): Promise<number>;