stageflow 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # <img src="ui/public/stageflow-icon.svg" alt="" width="44" height="44" valign="middle"> Stageflow
 
-CLI pipeline runtime for **configurable stages** on [Pi](https://github.com/badlogic/pi-mono), with a local operator console.
+Open-source runtime for **configurable multi-stage agent workflows** with typed handoffs, DAG execution, human gates, MCP, CI, and a local operator console.
 
 [![npm version](https://img.shields.io/npm/v/stageflow)](https://www.npmjs.com/package/stageflow)
 [![npm downloads](https://img.shields.io/npm/dm/stageflow)](https://www.npmjs.com/package/stageflow)
@@ -9,7 +9,7 @@ CLI pipeline runtime for **configurable stages** on [Pi](https://github.com/badl
 [![GitHub issues](https://img.shields.io/github/issues/tejasghutukade/stageflow)](https://github.com/tejasghutukade/stageflow/issues)
 [![CI](https://img.shields.io/github/actions/workflow/status/tejasghutukade/stageflow/ci.yml?branch=main)](https://github.com/tejasghutukade/stageflow/actions/workflows/ci.yml)
 
-Author pipeline-owned YAML in your project. Stageflow runs each stage in a fresh Pi agent session, writes a structured handoff envelope, and keeps run state under `.stageflow/`. Bins: **`sf`** and **`stageflow`**.
+Author pipeline-owned YAML in your project. Stageflow schedules each stage in a fresh agent session, moves context through explicit envelopes and artifacts, and persists run state under `.stageflow/`. [Pi](https://github.com/badlogic/pi-mono) is the current agent execution backend. Bins: **`sf`** and **`stageflow`**.
 
 ## Why Stageflow?
 
@@ -21,7 +21,7 @@ The same pipeline runs three ways without rewriting anything:
 
 - **Locally** — `sf ui` for triage, provider setup, and gate replies
 - **Headless / CI** — `sf validate` and `sf run --json` with predictable exit codes
-- **Via MCP** — Streamable HTTP tools when the console is running
+- **Via MCP** — Streamable HTTP tools when `sf ui` or `sf mcp` is running
 
 **Stageflow is not an SDLC tool.** Software delivery is a popular pattern in fixtures and dogfood flows, but stages are user-authored and domain-agnostic. If you can express a multi-step workflow in YAML, Stageflow can run it on Pi.
 
@@ -33,12 +33,20 @@ The same pipeline runs three ways without rewriting anything:
 - **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
 - **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
 - **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
-- **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` is running
+- **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
 - **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
 - **Parallel stages** — pipeline DAG with fan-out and join (see [YAML catalog](docs/yaml-catalog.md))
 - **Clonable fan-out** — clone one successor N times at completion, then join (see [YAML catalog](docs/yaml-catalog.md#clonable-successors))
 - **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`
 
+## Architecture at a glance
+
+![Stageflow architecture: pipeline definitions and operator interfaces drive the orchestration runtime, which coordinates agent execution and persisted state](docs/img/stageflow-architecture.svg)
+
+The scheduler owns orchestration semantics: DAG readiness, bounded parallelism, fan-out/join, conditional routing, retries, skipped branches, and resumable human gates. Agent execution sits behind `AgentPort`; Pi supplies the current coding-agent session, while Stageflow owns pipeline state, stage workspaces, handoff validation, and the interfaces used by the CLI, console, MCP, and CI.
+
+See [Architecture](docs/architecture.md) for component boundaries, execution flow, persistence, recovery behavior, and the tradeoffs behind fresh sessions and explicit handoffs.
+
 ## Installation
 
 Requires **Node.js ≥ 20**.
@@ -117,7 +125,7 @@ sf providers detect
 sf providers source set pi_home    # or sf_owned
 ```
 
-Stageflow is a thin Pi shell — you do not need Pi CLI `/login` as a hard prerequisite if you configure providers via the console or `sf providers`.
+Pi is Stageflow's current agent execution backend. Stageflow owns the workflow layer around it, and you do not need Pi CLI `/login` as a prerequisite when providers are configured through the console or `sf providers`.
 
 Full reference: [docs/providers.md](docs/providers.md)
 
@@ -126,12 +134,12 @@ Full reference: [docs/providers.md](docs/providers.md)
 Start the console with `sf ui` (default `http://127.0.0.1:3847`).
 
 - **Runs** — active and recent pipeline runs, capacity, and status at a glance
-- **Run detail** — stage timeline, transcripts, envelope payloads, and artifact paths
+- **Run detail** — spatial stage map; select a stage for the gated workspace (logs, files, envelopes, HITL). Created runs show **not started** with a **Start run** action until history exists
 - **HITL reply** — answer operator gates (`ask_operator`) without leaving the browser
 - **Pipelines** — browse manifest-declared pipeline definitions
 - **Settings → Providers** — connect model providers (`pi_home` or `sf_owned` credential storage)
 
-*Screenshot coming soon — capture after console polish lands (see `docs/img/`).*
+Brand assets live under `docs/img/` (`stageflow-og.svg`, `stageflow-icon.svg`).
 
 ## Headless / CI
 
@@ -141,7 +149,7 @@ The guest actor is the CLI (`sf` / `stageflow`). `sf ui` and MCP are not require
 sf validate --strict --json
 ```
 
-Validate exits `0` or `1` only (no waiting / `2`). It checks pipeline and stage YAML only; it does not prove provider auth, Task, or checkout.
+Validate exits `0` or `1` only (no waiting / `2`). With no flags, `sf validate` checks pipelines and tasks in the manifest (plus stages). `--pipeline` validates that pipeline and its stages only; `--task` validates that task file. It never proves provider auth or checkout paths.
 
 ```bash
 sf providers login <providerId> --api-key-env <VAR>
@@ -180,11 +188,9 @@ Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository
 
 ## MCP
 
-`sf ui` also serves a Streamable HTTP MCP endpoint at `http://127.0.0.1:3847/mcp` (URL printed on boot). Point a Cursor (or other) MCP client at that URL.
-
-Available tools: `list_pipelines`, `list_tasks`, `list_runs`, `get_health`, `start_run`, `get_run`, `read_artifact`.
+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.
 
-Full reference: [docs/mcp.md](docs/mcp.md)
+HITL-aware tools include `wait_run`, `answer_gate`, and `list_waiting`. Full tool list: [docs/mcp.md](docs/mcp.md).
 
 ## Stageflow vs Conductor
 
@@ -196,7 +202,7 @@ Both projects address multi-step agent workflows. They differ in orchestration m
 | **Orchestration** | Pipeline DAG + stage worker | Jinja routing, no LLM in router |
 | **Unit of work** | Task → Pipeline → Stage attempts | Workflow → Agents |
 | **Handoff** | Typed **envelope** + artifacts | Agent output → context |
-| **Human gates** | Operator console + MCP | Dashboard + TUI fleet |
+| **Human gates** | Console + MCP + harness native question UI | Dashboard + TUI fleet |
 | **Runtime** | Node.js, Pi coding agent | Python, Copilot/Claude SDKs |
 | **Best for** | Personal/team **multi-stage Pi workflows** you define (releases, research, SDLC, …) | Enterprise multi-agent workflows |
 
@@ -210,6 +216,7 @@ If you want deterministic YAML routing across many agents, look at [Conductor](h
 | [hello-world](examples/hello-world/) | Single stage, domain-neutral |
 | [plan-review](examples/plan-review/) | Multi-stage with operator gate — SDLC-style **example** |
 | [conditional-fork](examples/conditional-fork/) | Exclusive fork routing with operator branch choice |
+| [clonable-fanout](examples/clonable-fanout/) | Clone one successor N times, then join |
 | [github-release](examples/github-release/) | Dogfood: draft + publish GitHub Release |
 | [ci-validate](examples/ci-validate/) | Strict validate in CI |
 
@@ -222,15 +229,17 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 | Doc | Description |
 |-----|-------------|
 | [docs/README.md](docs/README.md) | Documentation index |
+| [docs/architecture.md](docs/architecture.md) | Runtime components, execution flow, persistence, and design decisions |
 | [docs/quickstart.md](docs/quickstart.md) | Expanded quick start |
 | [docs/yaml-catalog.md](docs/yaml-catalog.md) | Pipelines, stages, tasks schema |
-| [docs/cli-reference.md](docs/cli-reference.md) | `sf run`, `sf envelope`, `sf skills`, `sf validate`, `sf ui`, `sf providers` |
+| [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |
 | [docs/envelopes.md](docs/envelopes.md) | Handoff envelope contract |
 | [docs/hitl.md](docs/hitl.md) | Gate kinds, `--skip-gates`, exit code `2` |
 | [docs/ci.md](docs/ci.md) | `--json`, env vars, GitHub Actions |
 | [docs/mcp.md](docs/mcp.md) | MCP tool reference |
 | [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
 | [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
+| [docs/skills-suite.md](docs/skills-suite.md) | Harness skills — router + jobs for Cursor, Claude Code, Codex, Pi, OpenCode |
 | [docs/compare-conductor.md](docs/compare-conductor.md) | Positioning deep dive |
 
 ## Develop from source

package/dist/cli/runsCommand.d.ts

@@ -0,0 +1,22 @@
+import type { RunStore } from "../runstore/port.js";
+import { RunManager } from "../runtime/runManager.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 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 retry --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;
+}): Promise<number>;

package/dist/cli/runsCommand.js

@@ -0,0 +1,591 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { PiAgentAdapter } from "../agent/piAdapter.js";
+import { projectRun } from "../projection/projectRun.js";
+import { waitRun } from "../mcp/waitRun.js";
+import { projectWaitingGates } from "../mcp/waitingGates.js";
+import { resolveOperatorCatalog } from "./operatorCatalog.js";
+import { completeCliRun } from "./runCommand.js";
+import { reportCliRun } from "./runOutput.js";
+import { createRunStore } from "../runstore/createStore.js";
+import { RunManager } from "../runtime/runManager.js";
+import { readStageExecutionMode } from "../runtime/stageConcurrency.js";
+import { DEFAULT_PORT } from "../server/createHttpHost.js";
+import { mapRetryStageFailure } from "../server/operatorResults.js";
+import { AskOperatorError, parseAskOperatorAnswer, } from "../tools/askOperator.js";
+export const RUNS_USAGE = `Usage:
+  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]
+  sf runs show --run <runId> [--from <sf-run.json>] [--json]
+  sf runs waiting [--run <runId>] [--json]
+  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]
+  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]
+  sf runs retry --run <runId> --stage <stageId> [--json]
+  sf runs abandon --run <runId> --stage <stageId> [--json]
+  sf runs rerun --run <runId> [--json]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+const RUN_STATUSES = [
+    "created",
+    "running",
+    "succeeded",
+    "failed",
+];
+const LIST_FLAGS = new Set([
+    "--status",
+    "--since",
+    "--pipeline",
+    "--json",
+    "--help",
+    "-h",
+]);
+const SHOW_FLAGS = new Set(["--run", "--from", "--json", "--help", "-h"]);
+const WAITING_FLAGS = new Set(["--run", "--json", "--help", "-h"]);
+const WAIT_FLAGS = new Set([
+    "--run",
+    "--from",
+    "--until",
+    "--timeout-ms",
+    "--json",
+    "--help",
+    "-h",
+]);
+const ANSWER_FLAGS = new Set([
+    "--run",
+    "--stage",
+    "--answer",
+    "--json",
+    "--help",
+    "-h",
+]);
+const RETRY_FLAGS = new Set(["--run", "--stage", "--json", "--help", "-h"]);
+const ABANDON_FLAGS = new Set(["--run", "--stage", "--json", "--help", "-h"]);
+const RERUN_FLAGS = new Set(["--run", "--json", "--help", "-h"]);
+const VALUE_FLAGS = new Set([
+    "--status",
+    "--since",
+    "--pipeline",
+    "--run",
+    "--from",
+    "--until",
+    "--timeout-ms",
+    "--stage",
+    "--answer",
+]);
+function flagsFor(subcommand) {
+    switch (subcommand) {
+        case "list":
+            return LIST_FLAGS;
+        case "show":
+            return SHOW_FLAGS;
+        case "waiting":
+            return WAITING_FLAGS;
+        case "wait":
+            return WAIT_FLAGS;
+        case "answer":
+            return ANSWER_FLAGS;
+        case "retry":
+            return RETRY_FLAGS;
+        case "abandon":
+            return ABANDON_FLAGS;
+        case "rerun":
+            return RERUN_FLAGS;
+        default:
+            return undefined;
+    }
+}
+function parseRunsArgs(args) {
+    if (args.length === 0) {
+        return { help: false, json: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, json: false };
+    }
+    const subcommand = args[0];
+    const allowed = flagsFor(subcommand);
+    if (allowed === undefined) {
+        return { subcommand, help: false, json: false };
+    }
+    let help = false;
+    let json = false;
+    let status;
+    let since;
+    let pipeline;
+    let runId;
+    let fromPath;
+    let until;
+    let timeoutMs;
+    let stageId;
+    let answer;
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (VALUE_FLAGS.has(arg)) {
+            if (!allowed.has(arg)) {
+                throw new Error(`Unknown flag: ${arg}`);
+            }
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error(`Missing value for ${arg}`);
+            }
+            if (arg === "--status")
+                status = value;
+            else if (arg === "--since")
+                since = value;
+            else if (arg === "--pipeline")
+                pipeline = value;
+            else if (arg === "--run")
+                runId = value;
+            else if (arg === "--from")
+                fromPath = value;
+            else if (arg === "--until")
+                until = value;
+            else if (arg === "--timeout-ms")
+                timeoutMs = Number(value);
+            else if (arg === "--stage")
+                stageId = value;
+            else if (arg === "--answer")
+                answer = value;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return {
+        help,
+        json,
+        subcommand,
+        status,
+        since,
+        pipeline,
+        runId,
+        fromPath,
+        until,
+        timeoutMs,
+        stageId,
+        answer,
+    };
+}
+function resolveRunIdFromFile(fromPath, cwd) {
+    const resolved = path.resolve(cwd, fromPath);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(resolved, "utf8"));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read --from file: ${message}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("--from file must contain a JSON object with runId");
+    }
+    const runId = parsed.runId;
+    if (typeof runId !== "string" || runId.length === 0) {
+        throw new Error("--from file must contain a JSON object with runId");
+    }
+    return runId;
+}
+function hostBaseUrl() {
+    return `http://127.0.0.1:${DEFAULT_PORT}`;
+}
+export async function defaultProbeHost() {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 1500);
+    try {
+        const res = await fetch(`${hostBaseUrl()}/api/health`, {
+            signal: ac.signal,
+        });
+        if (res.status !== 200)
+            return "down";
+        JSON.parse(await res.text());
+        return "up";
+    }
+    catch {
+        return "down";
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function printJson(io, payload) {
+    io.log(JSON.stringify(payload, null, 2));
+}
+function isRunStatus(value) {
+    return RUN_STATUSES.includes(value);
+}
+function isWaitUntil(value) {
+    return value === "any" || value === "waiting" || value === "terminal";
+}
+function usageError(io, message) {
+    if (message !== undefined)
+        io.error(message);
+    io.error(RUNS_USAGE);
+    return 1;
+}
+async function resolveShowWaitRunId(parsed, cwd, io) {
+    if (parsed.fromPath !== undefined) {
+        try {
+            return resolveRunIdFromFile(parsed.fromPath, cwd);
+        }
+        catch (err) {
+            io.error(err instanceof Error ? err.message : String(err));
+            return undefined;
+        }
+    }
+    return parsed.runId;
+}
+export async function runRunsCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const isGitProject = options.isGitProject ?? false;
+    const out = { ...defaultIo, ...options.io };
+    const env = options.env ?? process.env;
+    const stdinIsTTY = options.stdinIsTTY ?? process.stdin.isTTY === true;
+    const readStdin = options.readStdin ?? (() => readFileSync(0, "utf8"));
+    const probeHost = options.probeHost ?? defaultProbeHost;
+    let parsed;
+    try {
+        parsed = parseRunsArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return usageError(out, message);
+    }
+    if (parsed.help) {
+        out.error(RUNS_USAGE);
+        return 0;
+    }
+    if (!parsed.subcommand) {
+        return usageError(out);
+    }
+    let resolvedStore = options.store;
+    const getStore = () => {
+        if (resolvedStore === undefined) {
+            resolvedStore = createRunStore({ rootDir: projectRoot });
+        }
+        return resolvedStore;
+    };
+    const mutatingIo = out;
+    const buildManager = () => {
+        const store = getStore();
+        if (options.createManager)
+            return options.createManager(store);
+        const operatorCatalog = resolveOperatorCatalog({
+            flags: {},
+            env,
+            defaultCwd: cwd,
+        });
+        return new RunManager({
+            agent: new PiAgentAdapter(),
+            store,
+            cwd,
+            projectRoot,
+            isGitProject,
+            operatorCatalog,
+            executionMode: readStageExecutionMode(env, "process"),
+        });
+    };
+    const guardHost = async () => {
+        const status = await probeHost();
+        if (status === "up") {
+            out.error(`A Stageflow host is already running at ${hostBaseUrl()}. Use the operator console or MCP instead of mutating the store from the CLI.`);
+            return 1;
+        }
+        return undefined;
+    };
+    switch (parsed.subcommand) {
+        case "list": {
+            if (parsed.status === "waiting") {
+                out.error("waiting is not a run status; parked HITL runs stay running. Use sf runs waiting.");
+                return 1;
+            }
+            if (parsed.status !== undefined && !isRunStatus(parsed.status)) {
+                out.error("--status must be created, running, succeeded, or failed");
+                return 1;
+            }
+            if (parsed.since !== undefined && !Number.isFinite(Date.parse(parsed.since))) {
+                out.error("since must be a valid date");
+                return 1;
+            }
+            const filter = {};
+            if (parsed.status !== undefined)
+                filter.status = parsed.status;
+            if (parsed.since !== undefined)
+                filter.since = parsed.since;
+            if (parsed.pipeline !== undefined)
+                filter.pipeline = parsed.pipeline;
+            const runs = await getStore().listRuns(Object.keys(filter).length > 0 ? filter : undefined);
+            if (parsed.json) {
+                printJson(out, { runs });
+            }
+            else {
+                for (const run of runs) {
+                    out.log(`${run.run_id}\t${run.status}`);
+                }
+            }
+            return 0;
+        }
+        case "show": {
+            const runId = await resolveShowWaitRunId(parsed, cwd, out);
+            if (parsed.fromPath !== undefined && runId === undefined) {
+                return 1;
+            }
+            if (!runId) {
+                return usageError(out, "Missing --run (or --from <sf-run.json>)");
+            }
+            try {
+                const detail = await getStore().readRun(runId);
+                const projection = projectRun(detail);
+                if (parsed.json) {
+                    printJson(out, projection);
+                }
+                else {
+                    out.log(`${projection.run_id}\t${projection.status}`);
+                }
+                return 0;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                out.error(message);
+                return 1;
+            }
+        }
+        case "waiting": {
+            const waiting = await projectWaitingGates(getStore(), {
+                runId: parsed.runId,
+            });
+            if (parsed.json) {
+                printJson(out, { waiting });
+            }
+            else {
+                for (const item of waiting) {
+                    const runId = typeof item.runId === "string" ? item.runId : "";
+                    const stageId = typeof item.stageId === "string" ? item.stageId : "";
+                    out.log(`${runId}\t${stageId}`);
+                }
+            }
+            return 0;
+        }
+        case "wait": {
+            const runId = await resolveShowWaitRunId(parsed, cwd, out);
+            if (parsed.fromPath !== undefined && runId === undefined) {
+                return 1;
+            }
+            if (!runId) {
+                return usageError(out, "Missing --run (or --from <sf-run.json>)");
+            }
+            const untilRaw = parsed.until ?? "any";
+            if (!isWaitUntil(untilRaw)) {
+                return usageError(out, "--until must be any, waiting, or terminal");
+            }
+            let signal = options.waitSignal;
+            let onSigInt;
+            if (signal === undefined) {
+                const controller = new AbortController();
+                signal = controller.signal;
+                onSigInt = () => controller.abort();
+                process.once("SIGINT", onSigInt);
+            }
+            try {
+                const result = await waitRun({
+                    store: getStore(),
+                    runId,
+                    timeoutMs: parsed.timeoutMs,
+                    until: untilRaw,
+                    signal,
+                });
+                if (!result.ok) {
+                    if (result.code === "aborted") {
+                        if (parsed.json) {
+                            printJson(out, { error: result.error, code: "aborted" });
+                        }
+                        else {
+                            out.error(result.error);
+                        }
+                        return 130;
+                    }
+                    if (parsed.json) {
+                        const payload = { error: result.error };
+                        if (result.status !== undefined)
+                            payload.status = result.status;
+                        printJson(out, payload);
+                    }
+                    else {
+                        out.error(result.error);
+                    }
+                    return 1;
+                }
+                if (parsed.json) {
+                    printJson(out, result);
+                }
+                else {
+                    out.log(`${result.reason}\t${result.run.status}`);
+                }
+                return 0;
+            }
+            finally {
+                if (onSigInt !== undefined) {
+                    process.removeListener("SIGINT", onSigInt);
+                }
+            }
+        }
+        case "answer": {
+            const blocked = await guardHost();
+            if (blocked !== undefined)
+                return blocked;
+            if (!parsed.runId) {
+                return usageError(out, "Missing --run");
+            }
+            if (!parsed.stageId) {
+                return usageError(out, "Missing --stage");
+            }
+            let answerRaw = parsed.answer;
+            if (answerRaw === undefined) {
+                if (stdinIsTTY) {
+                    return usageError(out, "Missing --answer (pass --answer '<json>' or pipe JSON on stdin)");
+                }
+                answerRaw = readStdin().trim();
+                if (answerRaw.length === 0) {
+                    return usageError(out, "Missing --answer (pass --answer '<json>' or pipe JSON on stdin)");
+                }
+            }
+            let parsedJson;
+            try {
+                parsedJson = JSON.parse(answerRaw);
+            }
+            catch {
+                const message = "--answer must be valid JSON";
+                if (parsed.json) {
+                    printJson(out, { error: message, status: 400 });
+                }
+                else {
+                    out.error(message);
+                }
+                return 1;
+            }
+            let answer;
+            try {
+                answer = parseAskOperatorAnswer(parsedJson);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (err instanceof AskOperatorError) {
+                    if (parsed.json) {
+                        printJson(out, { error: message, status: 400 });
+                    }
+                    else {
+                        out.error(message);
+                    }
+                    return 1;
+                }
+                out.error(message);
+                return 1;
+            }
+            const manager = buildManager();
+            const result = await manager.deliverAnswer(parsed.runId, parsed.stageId, answer);
+            if (!result.ok) {
+                const payload = { error: result.reason };
+                if (result.status !== undefined)
+                    payload.status = result.status;
+                if (parsed.json) {
+                    printJson(out, payload);
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            if (parsed.json) {
+                printJson(out, { ok: true });
+            }
+            else {
+                out.log("ok");
+            }
+            return 0;
+        }
+        case "retry": {
+            const blocked = await guardHost();
+            if (blocked !== undefined)
+                return blocked;
+            if (!parsed.runId || !parsed.stageId) {
+                return usageError(out, "Missing --run and/or --stage");
+            }
+            const manager = buildManager();
+            const result = await manager.retryStageUntilStop(parsed.runId, parsed.stageId);
+            if (!result.ok) {
+                if (parsed.json) {
+                    printJson(out, {
+                        ...mapRetryStageFailure(result),
+                        status: result.status,
+                    });
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            return reportCliRun({ kind: "completion", result: result.pipeline }, { json: parsed.json, io: mutatingIo });
+        }
+        case "abandon": {
+            const blocked = await guardHost();
+            if (blocked !== undefined)
+                return blocked;
+            if (!parsed.runId || !parsed.stageId) {
+                return usageError(out, "Missing --run and/or --stage");
+            }
+            const manager = buildManager();
+            const result = await manager.abandonStage(parsed.runId, parsed.stageId);
+            if (!result.ok) {
+                const payload = { error: result.reason };
+                if (result.status !== undefined)
+                    payload.status = result.status;
+                if (parsed.json) {
+                    printJson(out, payload);
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            if (parsed.json) {
+                printJson(out, {
+                    ok: true,
+                    runId: result.runId,
+                    stageId: result.stageId,
+                });
+            }
+            else {
+                out.log(`${result.runId}\t${result.stageId}`);
+            }
+            return 0;
+        }
+        case "rerun": {
+            const blocked = await guardHost();
+            if (blocked !== undefined)
+                return blocked;
+            if (!parsed.runId) {
+                return usageError(out, "Missing --run");
+            }
+            const manager = buildManager();
+            const started = await manager.rerun(parsed.runId);
+            if (!started.ok) {
+                return reportCliRun({ kind: "start-failure", started }, { json: parsed.json, io: mutatingIo });
+            }
+            return completeCliRun(started, mutatingIo, {
+                json: parsed.json,
+                store: getStore(),
+            });
+        }
+        default:
+            return usageError(out, `Unknown runs subcommand: ${parsed.subcommand}`);
+    }
+}

package/dist/cli/validateOutput.d.ts

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

package/dist/cli/validateOutput.js

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

package/dist/cli.js

@@ -10,6 +10,7 @@ import { EXPORT_RUN_USAGE, runExportRunCommand, } from "./cli/exportRunCommand.j
 import { INIT_USAGE, runInitCommand } from "./cli/initCommand.js";
 import { PROVIDERS_USAGE, runProvidersCommand } from "./cli/providersCommand.js";
 import { RUN_USAGE, runRunCommand } from "./cli/runCommand.js";
+import { RUNS_USAGE, runRunsCommand } from "./cli/runsCommand.js";
 import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
 import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
 import { VALIDATE_USAGE, runValidateCommand } from "./cli/validateCommand.js";
@@ -20,6 +21,7 @@ import { SF_STAGE_WORKER } from "./runtime/stageWorkerProtocol.js";
 import { DEFAULT_PORT, startUiServer } from "./server/http.js";
 import { startMcpServer } from "./server/mcpHost.js";
 import { resolveMcpStateless } from "./mcp/server.js";
+import { PACKAGE_VERSION } from "./package-meta.js";
 const USAGE = `Usage:
   sf init
   sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]
@@ -27,6 +29,14 @@ const USAGE = `Usage:
   sf artifact read --run <runId> --path <relPath> [--out <file>]
   sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]
   sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]
+  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]
+  sf runs show --run <runId> [--from <sf-run.json>] [--json]
+  sf runs waiting [--run <runId>] [--json]
+  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]
+  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]
+  sf runs retry --run <runId> --stage <stageId> [--json]
+  sf runs abandon --run <runId> --stage <stageId> [--json]
+  sf runs rerun --run <runId> [--json]
   sf ui [--port ${DEFAULT_PORT}] [--mcp-stateless]
   sf mcp [--port ${DEFAULT_PORT}] [--mcp-stateless]
   sf providers list
@@ -38,6 +48,8 @@ const USAGE = `Usage:
   sf skills list
   sf skills install --from-path <dir> [--skill-name <name>]
   sf skills install --from-zip <url-or-path> [--skill-name <name>] [--checksum sha256:<hex>]
+  sf --version
+  sf -V
   sf --help
 
 Stageflow (sf) runs YAML-defined automatic stage pipelines.
@@ -56,6 +68,8 @@ ${ENVELOPE_USAGE}
 
 ${EXPORT_RUN_USAGE}
 
+${RUNS_USAGE}
+
 ${PROVIDERS_USAGE}
 
 ${SKILLS_USAGE}`;
@@ -68,6 +82,12 @@ function parseArgs(argv) {
         args.length === 1) {
         return { help: true };
     }
+    if (args[0] === "--version" || args[0] === "-V") {
+        if (args.length > 1) {
+            throw new Error(`Unexpected argument: ${args[1]}`);
+        }
+        return { help: false, version: true };
+    }
     const command = args[0];
     if (command === "providers" ||
         command === "validate" ||
@@ -76,6 +96,7 @@ function parseArgs(argv) {
         command === "artifact" ||
         command === "envelope" ||
         command === "export-run" ||
+        command === "runs" ||
         command === "skills") {
         return { help: false, command };
     }
@@ -240,6 +261,10 @@ async function main(argv) {
             console.log(USAGE);
             return argv.slice(2).length === 0 ? 1 : 0;
         }
+        if (parsed.version) {
+            console.log(PACKAGE_VERSION);
+            return 0;
+        }
         const ctx = await resolveStageflowContext(process.cwd());
         if (parsed.command === "init") {
             return runInitCommand(argv.slice(3), { cwd: ctx.invocationCwd });
@@ -272,6 +297,13 @@ async function main(argv) {
                 projectRoot: ctx.projectRoot,
             });
         }
+        if (parsed.command === "runs") {
+            return runRunsCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+                isGitProject: ctx.isGitProject,
+            });
+        }
         if (parsed.command === "providers") {
             return runProvidersCommand(argv.slice(3), ctx.invocationCwd);
         }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/f
 export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
 export { resolveProjectContext, legacyProjectContext, type ProjectContext, } from "./project/resolveProjectContext.js";
 export { resolveStageflowContext, projectContextFromStageflow, type StageflowContext, type CatalogManifestStatus, } from "./project/resolveStageflowContext.js";
-export { PACKAGE_NAME } from "./package-meta.js";
+export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export type { StageEnvelope } from "./types/envelope.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
 export type { AgentPort } from "./agent/port.js";

package/dist/index.js

@@ -2,7 +2,7 @@ export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/f
 export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
 export { resolveProjectContext, legacyProjectContext, } from "./project/resolveProjectContext.js";
 export { resolveStageflowContext, projectContextFromStageflow, } from "./project/resolveStageflowContext.js";
-export { PACKAGE_NAME } from "./package-meta.js";
+export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
 export { createRunStore } from "./runstore/createStore.js";

package/dist/package-meta.d.ts

@@ -1 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
+export declare const PACKAGE_VERSION = "0.9.0";

package/dist/package-meta.js

@@ -1 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
+export const PACKAGE_VERSION = "0.9.0";

package/dist/runtime/runManager.d.ts

@@ -111,6 +111,13 @@ export declare class RunManager {
     }): Promise<StartRunResult>;
     rerun(runId: string): Promise<StartRunResult>;
     retryStage(runId: string, stageId: string): Promise<RetryStageResult>;
+    retryStageUntilStop(runId: string, stageId: string): Promise<{
+        ok: true;
+        pipeline: PipelineRunResult;
+    } | Extract<RetryStageResult, {
+        ok: false;
+    }>>;
+    private retryStageInternal;
     /**
      * Deliver an operator answer for `(runId, stageId)` (KTD2 / KTD6).
      * Same-process: unparks the live yield loop. After restart: reconstructs

package/dist/runtime/runManager.js

@@ -389,6 +389,29 @@ export class RunManager {
         return this.reserveAndStartPipeline(taskYaml, pipeline, `run ${runId} task`, rerunCwd, undefined, undefined, undefined, rerunProjectRoot);
     }
     async retryStage(runId, stageId) {
+        return this.retryStageInternal(runId, stageId, true);
+    }
+    async retryStageUntilStop(runId, stageId) {
+        const retryKey = waitKey(runId, stageId);
+        const retried = await this.retryStageInternal(runId, stageId, false);
+        if (!retried.ok)
+            return retried;
+        try {
+            if (retried.done === undefined) {
+                return {
+                    ok: false,
+                    reason: `Retry orchestration did not start for run ${runId} stage ${stageId}`,
+                    status: 500,
+                };
+            }
+            const pipeline = await retried.done;
+            return { ok: true, pipeline };
+        }
+        finally {
+            this.retryInFlight.delete(retryKey);
+        }
+    }
+    async retryStageInternal(runId, stageId, awaitRoot) {
         const retryKey = waitKey(runId, stageId);
         if (this.retryInFlight.has(retryKey)) {
             return {
@@ -401,7 +424,7 @@ export class RunManager {
         try {
             const orchestrationConflict = this.active.has(runId) &&
                 !this.attachedWaiting.has(waitKey(runId, stageId));
-            return await this.retryCoordinator.retryStage({
+            const result = await this.retryCoordinator.retryStage({
                 runId,
                 stageId,
                 store: this.options.store,
@@ -414,10 +437,16 @@ export class RunManager {
                 hitl: this.hitl,
                 orchestrationConflict,
                 tracking: this.retryTracking,
+                awaitRoot,
             });
+            if (!result.ok || awaitRoot !== false) {
+                this.retryInFlight.delete(retryKey);
+            }
+            return result;
         }
-        finally {
+        catch (err) {
             this.retryInFlight.delete(retryKey);
+            throw err;
         }
     }
     /**

package/dist/runtime/runRetryCoordinator.d.ts

@@ -29,6 +29,7 @@ export type RetryStageResult = {
     runId: string;
     stageId: string;
     attemptIndex: number;
+    done?: Promise<PipelineRunResult>;
 } | {
     ok: false;
     reason: string;
@@ -62,6 +63,7 @@ export type RetryStageRequest = {
     hitl: StageHitlController;
     orchestrationConflict: boolean;
     tracking: RetryTrackingPort;
+    awaitRoot?: boolean;
 };
 export declare function assertStageRetryEligible(detail: RunDetail, stageId: string, opts?: {
     recoveryActive?: boolean;

package/dist/runtime/runRetryCoordinator.js

@@ -315,12 +315,15 @@ export class RunRetryCoordinator {
                     tracking.onOrchestrationStarted(runId, orchestrationPromise);
                 }
             }
-            await this.waitForRoot(runId, stageId, store);
+            if (req.awaitRoot !== false) {
+                await this.waitForRoot(runId, stageId, store);
+            }
             return {
                 ok: true,
                 runId,
                 stageId,
                 attemptIndex: execution.attempt,
+                done: this.getOrchestrationPromise(runId),
             };
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "bin": {

package/skills/stageflow/references/control-surface.md

@@ -11,7 +11,7 @@ node ../scripts/detect-host.mjs
 node ../scripts/detect-host.mjs --base-url http://127.0.0.1:3847
 ```
 
-The script `GET`s `{baseUrl}/api/health` (default `http://127.0.0.1:3847`, 1500 ms timeout). **up** means HTTP 200 and parseable JSON. Non-200, non-JSON, or timeout is **down**.
+The script `GET`s `{baseUrl}/api/health` (default `http://127.0.0.1:3847`, 1500 ms timeout). **up** means HTTP 200 and parseable JSON. Non-200, non-JSON, or timeout is **down**. This probe is Stageflow host up/down only — it does not detect a coding-agent question UI. Gate presentation lives in [`../../stageflow-run/references/native-question-ui.md`](../../stageflow-run/references/native-question-ui.md).
 
 Stdout is one line: `up <baseUrl>` or `down <baseUrl>`. Exit `0` when up, `1` when down, `2` on usage error.
 
@@ -23,4 +23,6 @@ Use MCP tools over the Streamable HTTP endpoint at `{baseUrl}/mcp`. Tool names a
 
 ## When the host is down
 
-Use the `sf` CLI. Command names and flags live in [docs/cli-reference.md](../../../docs/cli-reference.md). Typical talking-job commands: `sf run`, `sf validate`, `sf envelope get`, `sf artifact read`, `sf providers`.
+Use the `sf` CLI. Command names and flags live in [docs/cli-reference.md](../../../docs/cli-reference.md). Typical talking-job commands: `sf run`, `sf runs waiting`, `sf runs answer`, `sf runs wait`, `sf validate`, `sf envelope get`, `sf artifact read`, `sf providers`.
+
+Probe before each mutating `sf runs` verb. If the probe is **up** or the command refuses because a host is up, continue that gate via MCP — do not start a second mutating writer, and do not start `sf mcp` as a disposable bridge.

package/skills/stageflow-run/SKILL.md

@@ -2,19 +2,20 @@
 name: stageflow-run
 description: >-
   Starts a catalog pipeline from the harness, reports progress, and answers
-  every HITL gate in this chat. Triggers: run a pipeline, start <pipeline>,
-  check on my run, answer the pending question.
+  every HITL gate on the host native question UI when it can, otherwise in
+  this chat. Triggers: run a pipeline, start <pipeline>, check on my run,
+  answer the pending question.
 compatibility: Requires the sf CLI on PATH. An MCP host (sf ui or sf mcp) is optional.
 disable-model-invocation: true
 ---
 
 # Stageflow run
 
-Start a catalog pipeline, keep every HITL gate in this chat, and report the outcome. Author and session-capture own catalog YAML; this job owns the run and any throwaway `*.task.yaml`.
+Start a catalog pipeline, present HITL on the host native question UI when it can, and report the outcome. Author and session-capture own catalog YAML; this job owns the run and any throwaway `*.task.yaml`.
 
 Talking jobs cite [`../stageflow/references/control-surface.md`](../stageflow/references/control-surface.md). Probe with [`../stageflow/scripts/detect-host.mjs`](../stageflow/scripts/detect-host.mjs) only. Do not write a second probe.
 
-MCP tool shapes: [`docs/mcp.md`](../../docs/mcp.md). CLI flags and exit codes: [`docs/cli-reference.md`](../../docs/cli-reference.md). Direct tool calls: [`references/mcp-call.md`](references/mcp-call.md). Selection: [`references/task-and-pipeline-selection.md`](references/task-and-pipeline-selection.md).
+MCP tool shapes: [`docs/mcp.md`](../../docs/mcp.md). CLI flags and exit codes: [`docs/cli-reference.md`](../../docs/cli-reference.md). Direct tool calls: [`references/mcp-call.md`](references/mcp-call.md). Selection: [`references/task-and-pipeline-selection.md`](references/task-and-pipeline-selection.md). Gate presentation: [`references/native-question-ui.md`](references/native-question-ui.md).
 
 ## Preconditions
 
@@ -38,15 +39,15 @@ node ../stageflow/scripts/detect-host.mjs --base-url http://127.0.0.1:3847
 
 Read [`references/task-and-pipeline-selection.md`](references/task-and-pipeline-selection.md). Follow it until you have a pipeline filesystem path and a task (catalog path, MCP inline object, or CLI throwaway file).
 
-If this chat already has a `runId` and the request is check, answer, or continue: skip start. Host up → [Wait](#wait). Host down and the human wants to answer → [Bridge](#bridge).
+If this chat already has a `runId` and the request is check, answer, or continue: skip start. Host up → [Wait](#wait). Host down → [CLI wait](#cli-wait).
 
 **Done when** the target is named, or a live `runId` is in hand.
 
 ## MCP tools
 
-Prefer this harness's native Stageflow MCP tools when their names are already in the tool list. When they are not, call [`scripts/mcp-call.mjs`](scripts/mcp-call.mjs) — see [`references/mcp-call.md`](references/mcp-call.md). Always use `mcp-call.mjs --stateless` for a bridge this skill started.
+Prefer this harness's native Stageflow MCP tools when their names are already in the tool list. When they are not, call [`scripts/mcp-call.mjs`](scripts/mcp-call.mjs) — see [`references/mcp-call.md`](references/mcp-call.md). Use `--stateless` only when the **user** started the host with `--mcp-stateless`. Do not start `sf mcp` from this skill.
 
-Call only `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `get_health`.
+Call only these Stageflow MCP tools: `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `get_health`. Host question tools already in this harness's tool list (`AskQuestion`, `AskUserQuestion`, `ask_user`) are for [Gate](#gate) presentation, not Stageflow MCP.
 
 ## MCP path
 
@@ -78,9 +79,14 @@ Call only `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `l
 
 ### Gate
 
+Read [`references/native-question-ui.md`](references/native-question-ui.md) before presenting a pending prompt.
+
 1. `list_waiting` with `{ "runId" }`.
 2. Print the pending prompt text **verbatim** (and artifacts / sub-questions when present).
-3. Collect the human's reply in this chat. Map it to the prompt `kind`:
+3. Present the decision as that reference directs:
+   - If a host question tool is already in this harness's tool list and the gate is representable, invoke that picker. For `multi_question`, one picker call with one question per sub-item when **every** sub-question is representable, then one `answer_gate`; otherwise the **whole** gate in this chat.
+   - Otherwise collect the reply in this chat.
+4. Map the reply to the prompt `kind` (picker Accept/Reject → `accept`/`reject`):
 
 | kind | `answer` |
 |---|---|
@@ -89,12 +95,12 @@ Call only `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `l
 | `artifact_backed` | `{ "promptId", "kind": "artifact_backed", "decision": "accept" \| "reject" }` |
 | `multi_question` | `{ "promptId", "kind": "multi_question", "answers": { "<id>": { "kind", "text" \| "decision" } } }` |
 
-`promptId` is `pending_prompt.id` or `waiting_prompt_id`. Map yes/y/accept/approve to `accept`; no/n/reject/deny to `reject`. Ask once when the kind is `multi_question` and any sub-question is unanswered, or when confirm/artifact_backed is not a clear decision.
+`promptId` is `pending_prompt.id` or `waiting_prompt_id`. Map yes/y/accept/approve/Accept to `accept`; no/n/reject/deny/Reject to `reject`. Each `multi_question` sub-answer keeps that sub's `kind` (`confirm` → `decision`, `free_text` → `text`). Collect every sub-answer before `answer_gate`.
 
-4. `answer_gate` with `{ "runId", "stageId", "answer" }`.
-5. Return to [Wait](#wait).
+5. `answer_gate` with `{ "runId", "stageId", "answer" }`.
+6. Return to [Wait](#wait).
 
-**Done when** `answer_gate` returns `{ "ok": true }` and Wait is re-entered. On `isError` (400 / 404 / 409), print the payload and ask for a corrected reply — do not open another surface.
+**Done when** `answer_gate` returns `{ "ok": true }` and Wait is re-entered. On `isError` (400 / 404 / 409), print the payload and collect a corrected reply the same way (picker if still representable; otherwise this chat).
 
 ## CLI path
 
@@ -113,24 +119,49 @@ Parse the single JSON document.
 | `0` | `succeeded` | [Report](#report) |
 | `1` | `failed` | [Report](#report) `reason` verbatim |
 | `1` | `busy` | [Report](#report) `busy_capacity` / `busy_checkout` and the included fields. Stop. |
-| `2` | `waiting` | [Bridge](#bridge) with this `runId` / `runDir` |
+| `2` | `waiting` | [CLI wait](#cli-wait) with this `runId` / `runDir` |
+
+**Done when** the outcome is reported, or a waiting exit has handed `runId` to CLI wait.
+
+## CLI wait
+
+Host down after `sf run` exit `2`, or when this chat already has a `runId` and the host is down. Do not start `sf mcp`. Presentation follows [`references/native-question-ui.md`](references/native-question-ui.md). Submit with `sf runs answer --json`.
+
+1. Probe again with [`../stageflow/scripts/detect-host.mjs`](../stageflow/scripts/detect-host.mjs) (the host may have appeared). Probe before each `sf runs answer`.
+2. **Up:** use that host — native tools if present, otherwise `mcp-call.mjs` (omit `--stateless` unless the user started the host with `--mcp-stateless`). Continue at [Gate](#gate).
+3. **Down:**
 
-**Done when** the outcome is reported, or a waiting exit has handed `runId` and `runDir` to Bridge.
+```
+sf runs waiting --run <runId> --json
+```
+
+Print the pending prompt **verbatim**. Present it as native-question-ui directs (picker or chat). Map the reply with the [Gate](#gate) kind table.
 
-## Bridge
+```
+sf runs answer --run <runId> --stage <stageId> --answer '<json>' --json
+```
+
+Success is `{ "ok": true }` exit `0` even if the run parks again. Do not treat answer as terminal.
+
+```
+sf runs wait --run <runId> --json --until any
+```
+
+A shorter `--timeout-ms` is fine when the harness timeout is tight. Default `60000`, max `240000`. Branch on JSON `reason`, not wait exit `0`:
+
+| `reason` | next |
+|---|---|
+| `waiting` or `already` with a waiting snapshot | `sf runs waiting` then answer |
+| `terminal` | [Report](#report) |
+| `timeout` | call `sf runs wait` again |
 
-A CLI waiting exit has no answer command. Keep the gate in this chat by joining a host on the same project root (git top-level when `git rev-parse --show-toplevel` succeeds, otherwise the current directory).
+Wait abort (exit `130`, `{ "error", "code": "aborted" }`) → [Report](#report): the run continues, resumable later. Stop. Do not reuse `sf run` exit `2` for wait.
 
-1. Probe again with [`../stageflow/scripts/detect-host.mjs`](../stageflow/scripts/detect-host.mjs) (the host may have appeared).
-2. **Up:** use that host — native tools if present, otherwise `mcp-call.mjs` (omit `--stateless`). Continue at [Gate](#gate).
-3. **Down:** start `sf mcp --mcp-stateless` as a background process on that same project root. This is a disposable HITL bridge, not setup auto-start.
-4. Probe until stdout is `up <baseUrl>`, at most 8 times. **Done when** the host is up. If it stays down, [Report](#report) the parked `runId` / `runDir` and the bind/stderr text. Stop.
-5. Drive the rest with `mcp-call.mjs --stateless` only: [Gate](#gate) → [Wait](#wait) until terminal. A second wait on the same run reuses this process.
-6. When the run is terminal, stop the bridge process.
+4. If `sf runs answer` refuses because the host came up, continue that gate via MCP [Gate](#gate). Do not dual-write.
 
 If this chat ends before terminal, say the run stays in `.stageflow/` and to continue by re-invoking this skill (or starting a host and using MCP).
 
-**Done when** the run is terminal and the bridge this skill started is stopped, or a parked-run failure is reported.
+**Done when** the run is terminal, aborted, or a hard error is printed.
 
 ## Report
 
@@ -142,10 +173,10 @@ Print one shape on every path:
 4. Run id.
 5. Run folder (`runDir` / `.stageflow/`).
 
-MCP `get_run` / `wait_run` carry live stage state. `sf run --json` reports start and finish only — say that in chat when the CLI path ran without a host. A succeeded report names id and folder and does not keep waiting language. A failure names `reason` in this same shape.
+MCP `get_run` / `wait_run` and `sf runs wait` / `sf runs show` `--json` carry live stage state. `sf run --json` reports start and finish only — say that in chat when the CLI path ran without a later wait/show. A succeeded report names id and folder and does not keep waiting language. A failure names `reason` in this same shape.
 
 **Done when** that five-part report is printed.
 
 ## Non-goals
 
-This job starts, watches, and answers runs. It does not require `sf ui`. The operator console is not the answer path. It does not register or invent an MCP tool.
+This job starts, watches, and answers runs. It does not require `sf ui`. The operator console is not the answer path. It does not register or invent an MCP tool. It does not start `sf mcp`. It does not retry, abandon, or rerun stages.

package/skills/stageflow-run/references/mcp-call.md

@@ -1,6 +1,6 @@
 # mcp-call
 
-Use [`../scripts/mcp-call.mjs`](../scripts/mcp-call.mjs) when this harness has no native Stageflow MCP tools, and always for a self-started `sf mcp --mcp-stateless` bridge.
+Use [`../scripts/mcp-call.mjs`](../scripts/mcp-call.mjs) when the Stageflow host is up and this harness has no native Stageflow MCP tools. Do not start `sf mcp` from this skill.
 
 ```
 node scripts/mcp-call.mjs --base-url <url> --tool <name> --args '<json>' [--stateless]
@@ -8,7 +8,7 @@ node scripts/mcp-call.mjs --base-url <url> --tool <name> --args '<json>' [--stat
 
 Default `--base-url` is `http://127.0.0.1:3847`. `--args` defaults to `{}`.
 
-`--stateless` sends one `tools/call` and no session header. Use it for hosts started with `sf mcp --mcp-stateless`.
+`--stateless` sends one `tools/call` and no session header. Use it for hosts the **user** started with `sf mcp --mcp-stateless`, not a skill-started process.
 
 Without `--stateless`: `initialize`, capture `Mcp-Session-Id`, reuse it for `tools/call`.
 

package/skills/stageflow-run/references/native-question-ui.md

@@ -0,0 +1,78 @@
+# Native question UI
+
+Present a waiting HITL gate on the coding-agent host's structured question tool when that tool can represent the gate. Otherwise collect the reply in this chat. Submit with `answer_gate` when the Stageflow host is up, or `sf runs answer --json` when it is down. This file is presentation only — it does not change MCP tools, `detect-host.mjs`, or the operator console.
+
+Read `pending_prompt` from `list_waiting` or `sf runs waiting --json` (not only `waiting_questions` strings).
+
+## Detect a picker
+
+Inspect **this harness's current tool list**. A picker is a tool that collects a structured choice (question text plus labeled options), not a free-form chat reply.
+
+Do not run `detect-host.mjs` for this. That script is Stageflow host up/down (MCP vs CLI). It does not detect a question UI.
+
+| If this name is in the tool list | Use it |
+|---|---|
+| `AskQuestion` | Cursor question cards |
+| `AskUserQuestion` | Claude Code questions |
+| `ask_user` | Pi questions |
+
+If none of those (or another options-based question tool already in the list) is present, collect in chat. Do not invent a tool name or call shape. Codex and OpenCode stay in chat until an options-based question tool appears in the list.
+
+Pass the pending message as the question text and the mapped labels as that tool's options. One question per call except `multi_question`: one call with one question per representable sub-item when the tool accepts a questions array (Cursor `AskQuestion` does). Do not invent placeholder options such as Type in Other — host Other is the custom-text escape. If the picker returns a custom or Other value, map that text the same as a chat reply.
+
+**Done when** you know picker or chat for this gate.
+
+## Representable vs chat
+
+| Gate | Picker | Chat |
+|---|---|---|
+| `confirm` | Accept and Reject | Host has no picker |
+| `artifact_backed` | Accept and Reject (decision only) | Host has no picker |
+| `free_text` with a harvested closed set | Those names as options | Open-ended, or harvest is ambiguous |
+| `free_text` with no closed set | — | Always |
+| `multi_question` | One picker call with one question per sub-item when **every** sub-question is representable; then one submit | Any sub-question is open or unmappable — the **whole** gate in chat |
+
+Map picker Accept / yes / approve → `accept`. Reject / no / deny → `reject`. Always include `promptId` (`pending_prompt.id` or `waiting_prompt_id`).
+
+| Item | Submit |
+|---|---|
+| Top-level or sub `confirm` | `{ "kind": "confirm", "decision": "accept" \| "reject" }` |
+| Top-level `artifact_backed` | `{ "kind": "artifact_backed", "decision": "accept" \| "reject" }` plus optional `text` after a reject follow-up |
+| Top-level or sub `free_text` (including harvested) | `{ "kind": "free_text", "text": "<selected label>" }` |
+
+Never submit a `confirm` item as `free_text`. For `multi_question`, wrap sub-answers in the Gate `answers` object and submit once (`answer_gate` or `sf runs answer --json`).
+
+When in doubt, chat.
+
+**Done when** the path (picker or chat) is chosen from this table.
+
+## Harvest
+
+Harvest only from `pending_prompt.message` (or a `multi_question` item `message`) when it names a **hard closed set**:
+
+- `reply with exactly one of:`
+- `choose one of:`
+- `exactly one of`
+
+Split the names after that directive (commas, `or`, newlines). Those literal names are the picker options.
+
+Do **not** harvest loose example lists (`you might try`, `e.g.`, `for example` without `exactly one of`). A listed example set that is not a hard closed directive stays in chat.
+
+Submit the selected label as `text` for `free_text` items. If the prompt also lists aliases for the same choice (for example `minimal` and `prototype~1`), keep every listed name on the card; do not rewrite the label at submit — the stage maps synonyms.
+
+**Done when** the option list is the prompt's literal closed set, or the gate stayed in chat.
+
+## Artifact-backed
+
+1. Print the pending message and artifact paths (from `list_waiting`) in this chat. Do not put artifact bodies on the card. Do not call `read_artifact` unless the human asked to open a file.
+2. Open the picker with Accept and Reject.
+3. Accept → submit immediately (`decision: "accept"`).
+4. Reject → one chat follow-up for optional notes, then submit `decision: "reject"` and `text` when they typed notes.
+
+**Done when** the operator has seen the paths in chat and the decision is on the picker (or chat if there is no picker).
+
+## Errors
+
+On MCP `answer_gate` `isError` (400 / 404 / 409) or CLI `sf runs answer` exit `1`, print the payload. Collect a corrected reply on the picker if the gate is still representable; otherwise chat. Then submit again.
+
+**Done when** `{ "ok": true }` or the error payload has been printed and a corrected reply is in hand.