stageflow 0.25.0 → 0.30.0

package/skills/stageflow-run/SKILL.md

@@ -17,6 +17,10 @@ Talking jobs cite [`../stageflow/references/control-surface.md`](../stageflow/re
 
 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).
 
+Runs live under **`$STAGEFLOW_HOME`** (default `~/.stageflow/`), not the project tree. Project `.stageflow/settings.json` is settings only.
+
+`STAGEFLOW_OPERATOR_CWD` (skills resolution) is **not** catalog `project_root` / registration — see [MCP — Skills cwd vs catalog project_root](../../docs/mcp.md#skills-cwd-vs-catalog-project_root).
+
 ## Preconditions
 
 Run `sf --version`. **Done when** it prints a version. If `sf` is missing, stop and name `stageflow-setup`.
@@ -30,9 +34,11 @@ node ../stageflow/scripts/detect-host.mjs --base-url http://127.0.0.1:3847
 
 | stdout | path |
 |---|---|
-| `up <baseUrl>` | [MCP path](#mcp-path) |
+| `up <baseUrl>` … | [MCP path](#mcp-path) |
 | `down <baseUrl>` | [CLI path](#cli-path) |
 
+Optional trailing `bearer` means `STAGEFLOW_CONTROL_TOKEN` (or `_FILE`) is set in this environment — send it on MCP via [`mcp-call.md`](references/mcp-call.md) (Compose / non-loopback Hosts require a token). `/api/health` stays unauthenticated; the probe does not break loopback.
+
 **Done when** you have `up` or `down` and the base URL.
 
 ## Select
@@ -47,21 +53,23 @@ If this chat already has a `runId` and the request is check, answer, or continue
 
 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 these Stageflow MCP tools: `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `list_runs`, `answer_gate`, `decide_feedback_loop`, `read_artifact`, `describe_pipeline`, `validate`, `list_providers`, `list_models`, `list_project_mcp`, `probe_project_mcp`, `get_health`. Host question tools already in this harness's tool list (`AskQuestion`, `AskUserQuestion`, `ask_user`) are for [Gate](#gate) presentation, not Stageflow MCP.
+Call only these Stageflow MCP tools: `list_pipelines`, `list_tasks`, `start_run`, `run_stage`, `get_run`, `wait_run`, `list_waiting`, `list_runs`, `answer_gate`, `decide_feedback_loop`, `get_envelope`, `read_artifact`, `list_checkout_changes`, `get_run_diff`, `read_checkout_file`, `describe_pipeline`, `validate`, `list_providers`, `list_models`, `list_project_mcp`, `probe_project_mcp`, `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
 
 ### Start
 
-`start_run` with `pipeline` plus exactly one of `task_path` or inline `task`.
+`start_run` with `pipeline` plus exactly one of `task_path` or inline `task`. Binding: task `repository`+`ref` XOR `checkout` (see selection). Repository-bound runs get a Host worktree under `$STAGEFLOW_HOME/worktrees/<runId>/`.
 
 | result | next |
 |---|---|
 | `{ "runId" }` | [Wait](#wait) |
-| `busy_capacity` / `busy_checkout` | [Report](#report) the included fields. Stop. Do not retry. |
+| `{ "runId", "queued": true }` (optional `queuePosition`) | Same as `{ "runId" }` — queued is still success, just slower. [Wait](#wait) |
+| `busy_capacity` / `busy_checkout` | [Report](#report) the included fields. Stop. Do not retry. `busy_capacity` means the **admission queue is full** (active-slot exhaustion queues instead). `busy_checkout` is a **path-bound checkout lease** only (never queued); repository-bound runs may parallelize on the same repo. |
+| `insufficient_disk` | [Report](#report) `freeBytes` / `minFreeBytes`. Stop. Do not retry. Distinct from busy — the run was not queued. |
 | other `isError` | [Report](#report) the payload. Stop. |
 
-**Done when** you have a `runId`, or a busy/error report is printed.
+**Done when** you have a `runId`, or a busy/disk/error report is printed.
 
 ### Wait
 
@@ -120,7 +128,7 @@ Discovery without a host: read `stageflow.yaml` catalog roots as in [`references
 sf run --task <path> --pipeline <path> --json
 ```
 
-Add `--checkout`, `--git-sha`, `--ci-pr-url`, `--ci-job-url`, `--operator-cwd`, or `--operator-agent-dir` only when the human supplied them. Always pass `--json`. Omit `--include stages` unless the human asked for a stage projection — and then only together with `--json`.
+Add `--checkout`, `--repository` / `--ref`, `--git-sha`, `--ci-pr-url`, or `--ci-job-url` only when the human supplied them (binding: `repository`+`ref` XOR `checkout`). Do **not** pass `--operator-cwd` / `--operator-agent-dir` — they are no-ops on `sf run`; set `STAGEFLOW_OPERATOR_CWD` / `STAGEFLOW_OPERATOR_AGENT_DIR` before the Host first starts. Always pass `--json`. Omit `--include stages` unless the human asked for a stage projection — and then only together with `--json`.
 
 Parse the single JSON document.
 
@@ -128,7 +136,9 @@ Parse the single JSON document.
 |---|---|
 | `0` | `succeeded` | [Report](#report) |
 | `1` | `failed` | [Report](#report) `reason` verbatim |
+| `1` | `cancelled` | [Report](#report) `reason` verbatim |
 | `1` | `busy` | [Report](#report) `busy_capacity` / `busy_checkout` and the included fields. Stop. |
+| `1` | `failed` with `code: "insufficient_disk"` | [Report](#report) `freeBytes` / `minFreeBytes`. Stop. |
 | `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.
@@ -138,7 +148,7 @@ Parse the single JSON document.
 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`. HITL presentation follows [`references/native-question-ui.md`](references/native-question-ui.md). Submit HITL with `sf runs answer --json`. If `waiting_kind` is `feedback_loop_decision`, present extend / continue / abandon and submit with `sf runs feedback-decide --json` — not `sf runs answer`.
 
 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` or `sf runs feedback-decide`.
-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).
+2. **Up:** use that host — native tools if present, otherwise `mcp-call.mjs` (omit `--stateless` unless the user started the host with `--mcp-stateless`; send bearer when the probe notes `bearer` or `STAGEFLOW_CONTROL_TOKEN` is set). Continue at [Gate](#gate).
 3. **Down:**
 
 ```
@@ -177,7 +187,7 @@ Wait abort (exit `130`, `{ "error", "code": "aborted" }`) → [Report](#report):
 
 4. If `sf runs answer` or `sf runs feedback-decide` 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).
+If this chat ends before terminal, say the run stays under `$STAGEFLOW_HOME` (default `~/.stageflow/`) and to continue by re-invoking this skill (or starting a host and using MCP).
 
 **Done when** the run is terminal, aborted, or a hard error is printed.
 
@@ -187,14 +197,14 @@ Print one shape on every path:
 
 1. Current or last-known stage (MCP live snapshot, or "start/finish only" on a CLI-only stretch).
 2. Waiting prompt text verbatim when the run is parked.
-3. Outcome: `succeeded`, `failed`, `waiting`, or `busy`.
+3. Outcome: `succeeded`, `failed`, `cancelled`, `waiting`, `busy`, or `insufficient_disk`.
 4. Run id.
-5. Run folder (`runDir` / `.stageflow/`).
+5. Run location under `$STAGEFLOW_HOME` (`runDir` / `runs/<runId>/`; default home `~/.stageflow/`). For repository-bound succeeded runs, the Host worktree under `worktrees/<runId>/` may already be reclaimed (`checkout_reclaimed` if the path is gone; `run_branch` is kept).
 
-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.
+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 durable location and does not keep waiting language. A failure names `reason` in this same shape. Stop-and-report codes from Start include `busy_capacity`, `busy_checkout`, and `insufficient_disk`.
 
 **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. It does not start `sf mcp`. It does not retry, resume, abandon, recover, or rerun stages.
+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, resume, abandon, recover, cancel, delete, gc, or rerun stages or runs.

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

@@ -8,10 +8,18 @@ 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 `{}`.
 
+## Auth
+
+When `STAGEFLOW_CONTROL_TOKEN` or `STAGEFLOW_CONTROL_TOKEN_FILE` is set, the script sends `Authorization: Bearer <token>` on every `/mcp` request (initialize, tools/call, session DELETE). Docker Compose and any non-loopback Host require a drive token — set the same env in the harness before calling. Loopback with no token stays unauthenticated. `/api/health` (detect-host) does not need a bearer.
+
+## Session
+
 `--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`.
 
 Stdout is the tool JSON. Exit `0` on success, including `wait_run` with `reason: "timeout"` (keep polling). Exit `1` on transport failure or `isError: true`. Exit `2` on usage or malformed `--args` — that parse error happens before any network call.
 
-Allowed `--tool` names (see [`docs/mcp.md`](../../../docs/mcp.md)): `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `list_runs`, `answer_gate`, `decide_feedback_loop`, `read_artifact`, `describe_pipeline`, `validate`, `list_providers`, `list_models`, `list_project_mcp`, `probe_project_mcp`, `get_health`.
+Allowed `--tool` names (see [`docs/mcp.md`](../../../docs/mcp.md)): `list_pipelines`, `list_tasks`, `start_run`, `run_stage`, `get_run`, `wait_run`, `list_waiting`, `list_runs`, `answer_gate`, `decide_feedback_loop`, `get_envelope`, `read_artifact`, `list_checkout_changes`, `get_run_diff`, `read_checkout_file`, `describe_pipeline`, `validate`, `list_providers`, `list_models`, `list_project_mcp`, `probe_project_mcp`, `get_health`.
+
+`start_run` may return `{ "runId", "queued": true }` — treat that like `{ "runId" }` (success, slower start). `busy_capacity` means the admission queue is full; `busy_checkout` is path-bound lease only; `insufficient_disk` is a hard stop (not queued). Do not call `cancel_run`, `delete_run`, or `gc_runs` from this skill.

package/skills/stageflow-run/references/task-and-pipeline-selection.md

@@ -12,7 +12,9 @@ Print a short pick list (id + path). Ask which.
 
 ## MCP catalog
 
-`list_pipelines` and `list_tasks` (native tools, or [`mcp-call.md`](mcp-call.md)). Listing objects carry `path` and `id`.
+`list_pipelines` and `list_tasks` (native tools, or [`mcp-call.md`](mcp-call.md)). Listing objects carry `path` and `id`. The Host must already know the catalog root (seeded or registered via ensure / `POST /api/projects`) and that root needs a readable `stageflow.yaml`. Git is optional for listing — register + manifest is enough.
+
+**Paths:** MCP requires catalog-relative paths under `project_root`. Absolute pipeline/task/checkout paths return `absolute_path_not_allowed` (with `registered_roots`). Local CLI may pass absolute paths and auto-register.
 
 ## CLI catalog
 
@@ -20,6 +22,17 @@ There is no CLI list command. Read `stageflow.yaml` at the project root (git top
 
 Walk each `catalog.pipelines` / `catalog.tasks` root. Match `catalog.patterns.pipeline` (default `*.pipeline.yaml`) and `catalog.patterns.task` (default `*.task.yaml`). Skip paths whose repo-relative prefix is in `catalog.exclude`.
 
+## Repository binding
+
+Task binding is **`repository` + `ref` XOR `checkout`** (code `task.binding_conflict` if both). Do not set both.
+
+| Binding | Meaning |
+|---|---|
+| `repository` + `ref` | GitHub `owner/repo` plus branch/tag/SHA. Host creates a worktree at `$STAGEFLOW_HOME/worktrees/<runId>/`. On **succeeded**, that worktree may be reclaimed (`run_branch` kept; path may be gone → checkout tools return `checkout_reclaimed`). Repository-bound runs parallelize; they do not take the path `busy_checkout` lease. |
+| `checkout` | Path-bound working tree. `busy_checkout` is this path lease only — conflicting path-bound starts fail and never queue. |
+
+CLI parity with MCP inline: `sf run --repository owner/repo --ref <ref>` (or `--checkout <path>`), and the same fields on throwaway scratch YAML.
+
 ## Task input
 
 ### MCP
@@ -27,14 +40,14 @@ Walk each `catalog.pipelines` / `catalog.tasks` root. Match `catalog.patterns.pi
 An existing `task_path` from `list_tasks`, or an inline `task` object built from the stated goal:
 
 ```json
-{ "id": "<slug>", "goal": "<goal>", "context": "optional", "constraints": "optional", "checkout": "optional" }
+{ "id": "<slug>", "goal": "<goal>", "context": "optional", "constraints": "optional", "checkout": "optional", "repository": "optional", "ref": "optional" }
 ```
 
-`start_run` accepts that object. Do not write a scratch file on the MCP path.
+Use either `repository`+`ref` or `checkout`, not both. `start_run` accepts that object. Do not write a scratch file on the MCP path. After start, inspect checkout state with `list_checkout_changes`, `get_run_diff`, or `read_checkout_file` when the human asks what changed in the bound tree (reclaimed succeeded worktrees → `checkout_reclaimed`).
 
 ### CLI
 
-`sf run` accepts `--task <path>` only. Reuse a catalog `*.task.yaml`, or write a throwaway file at the project root:
+`sf run` accepts `--task <path>` plus optional `--repository` / `--ref` or `--checkout`. Reuse a catalog `*.task.yaml`, or write a throwaway file at the project root:
 
 ```
 .scratch/stageflow-run/<id>.task.yaml
@@ -45,8 +58,8 @@ id: <slug>
 goal: <human goal>
 ```
 
-Add `context`, `constraints`, or `checkout` only when the human gave them. Pass that path as `--task`.
+Add `context`, `constraints`, `checkout`, or `repository` + `ref` only when the human gave them (same XOR as MCP). Pass that path as `--task`. Overrides: `--repository owner/repo --ref <ref>` or `--checkout <path>`.
 
 ## Optional run flags
 
-`--checkout`, `--git-sha`, `--ci-pr-url`, `--ci-job-url` only when the human supplied them.
+`--checkout`, `--repository`, `--ref`, `--git-sha`, `--ci-pr-url`, `--ci-job-url` only when the human supplied them. Do not use `--operator-cwd` / `--operator-agent-dir` (no-ops); set `STAGEFLOW_OPERATOR_CWD` / `STAGEFLOW_OPERATOR_AGENT_DIR` before Host first start.

package/skills/stageflow-run/scripts/mcp-call.mjs

@@ -1,17 +1,24 @@
 #!/usr/bin/env node
 
+import { readFileSync } from "node:fs";
+
 const DEFAULT_BASE_URL = "http://127.0.0.1:3847";
 const ALLOWED_TOOLS = new Set([
   "list_pipelines",
   "list_tasks",
   "start_run",
+  "run_stage",
   "get_run",
   "wait_run",
   "list_waiting",
   "list_runs",
   "answer_gate",
   "decide_feedback_loop",
+  "get_envelope",
   "read_artifact",
+  "list_checkout_changes",
+  "get_run_diff",
+  "read_checkout_file",
   "describe_pipeline",
   "validate",
   "list_providers",
@@ -27,6 +34,34 @@ const WAIT_RUN_DEFAULT_MS = 60_000;
 const WAIT_RUN_BUFFER_MS = 5_000;
 const WAIT_RUN_CAP_MS = 250_000;
 
+function controlTokenFromEnv(env = process.env) {
+  const plain = env.STAGEFLOW_CONTROL_TOKEN;
+  const filePath = env.STAGEFLOW_CONTROL_TOKEN_FILE;
+  const hasPlain = plain !== undefined && plain.length > 0;
+  const hasFile = filePath !== undefined && filePath.length > 0;
+  if (hasPlain && hasFile) {
+    console.error("mcp-call: set only one of STAGEFLOW_CONTROL_TOKEN or STAGEFLOW_CONTROL_TOKEN_FILE");
+    process.exit(2);
+  }
+  if (hasFile) {
+    try {
+      return readFileSync(filePath, "utf8").replace(/\r?\n$/, "");
+    } catch (err) {
+      console.error(
+        `mcp-call: failed to read STAGEFLOW_CONTROL_TOKEN_FILE=${filePath}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      process.exit(2);
+    }
+  }
+  if (hasPlain) return plain;
+  return undefined;
+}
+
+function authHeaders(token) {
+  if (!token) return {};
+  return { Authorization: `Bearer ${token}` };
+}
+
 function usage() {
   return "Usage: mcp-call.mjs --base-url URL --tool NAME --args JSON [--stateless]";
 }
@@ -156,13 +191,14 @@ function extractToolPayload(message) {
   return { payload, isError: result.isError === true };
 }
 
-async function postMcp(mcpUrl, { body, sessionId, timeoutMs }) {
+async function postMcp(mcpUrl, { body, sessionId, timeoutMs, token }) {
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), timeoutMs);
   try {
     const headers = {
       "Content-Type": "application/json",
       Accept: "application/json, text/event-stream",
+      ...authHeaders(token),
     };
     if (sessionId) headers["mcp-session-id"] = sessionId;
     const res = await fetch(mcpUrl, {
@@ -185,7 +221,7 @@ function failTransport(detail, extra) {
   console.error(`mcp-call: ${detail}`);
 }
 
-async function initializeSession(mcpUrl) {
+async function initializeSession(mcpUrl, token) {
   const { res, text } = await postMcp(mcpUrl, {
     body: {
       jsonrpc: "2.0",
@@ -198,6 +234,7 @@ async function initializeSession(mcpUrl) {
       },
     },
     timeoutMs: INIT_TIMEOUT_MS,
+    token,
   });
   if (res.status < 200 || res.status >= 300) {
     let extra;
@@ -215,19 +252,20 @@ async function initializeSession(mcpUrl) {
       body: { jsonrpc: "2.0", method: "notifications/initialized" },
       sessionId,
       timeoutMs: INIT_TIMEOUT_MS,
+      token,
     });
   } catch {}
   return sessionId;
 }
 
-async function closeSession(mcpUrl, sessionId) {
+async function closeSession(mcpUrl, sessionId, token) {
   if (!sessionId) return;
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), INIT_TIMEOUT_MS);
   try {
     await fetch(mcpUrl, {
       method: "DELETE",
-      headers: { "mcp-session-id": sessionId },
+      headers: { "mcp-session-id": sessionId, ...authHeaders(token) },
       signal: ac.signal,
     });
   } catch {
@@ -274,12 +312,13 @@ if (!ALLOWED_TOOLS.has(tool)) {
 const toolArgs = parseToolArgs(argsText);
 const mcpUrl = `${baseUrl}/mcp`;
 const timeoutMs = toolTimeoutMs(tool, toolArgs);
+const token = controlTokenFromEnv();
 
 let sessionId;
 let exitCode = 1;
 try {
   if (!stateless) {
-    sessionId = await initializeSession(mcpUrl);
+    sessionId = await initializeSession(mcpUrl, token);
   }
   const { res, text } = await postMcp(mcpUrl, {
     body: {
@@ -290,6 +329,7 @@ try {
     },
     sessionId,
     timeoutMs,
+    token,
   });
   exitCode = handleToolResponse(res, text);
 } catch (err) {
@@ -302,7 +342,7 @@ try {
   }
 } finally {
   if (sessionId) {
-    await closeSession(mcpUrl, sessionId);
+    await closeSession(mcpUrl, sessionId, token);
   }
 }
 process.exit(exitCode);

package/skills/stageflow-run/scripts/mcp-call.test.mjs

@@ -7,10 +7,18 @@ import { test } from "node:test";
 
 const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "mcp-call.mjs");
 
+function cleanEnv(extra = {}) {
+  const env = { ...process.env };
+  delete env.STAGEFLOW_CONTROL_TOKEN;
+  delete env.STAGEFLOW_CONTROL_TOKEN_FILE;
+  return { ...env, ...extra };
+}
+
 function run(args, opts = {}) {
   return new Promise((resolve) => {
     const child = spawn(process.execPath, [script, ...args], {
       stdio: ["ignore", "pipe", "pipe"],
+      env: opts.env ?? cleanEnv(),
     });
     let stdout = "";
     let stderr = "";
@@ -238,6 +246,62 @@ test("isError true exits non-zero and prints the payload", async () => {
   }
 });
 
+test("sends Authorization Bearer when STAGEFLOW_CONTROL_TOKEN is set", async () => {
+  let sawAuth;
+  const { server, baseUrl } = await listen(async (req, res) => {
+    sawAuth = req.headers.authorization;
+    const body = await readJsonBody(req);
+    writeToolResult(res, body.id, HEALTH);
+  });
+  try {
+    const token = "a".repeat(32);
+    const result = await run(
+      [
+        "--base-url",
+        baseUrl,
+        "--tool",
+        "get_health",
+        "--args",
+        "{}",
+        "--stateless",
+      ],
+      {
+        env: cleanEnv({ STAGEFLOW_CONTROL_TOKEN: token }),
+      },
+    );
+    assert.equal(result.status, 0);
+    assert.equal(sawAuth, `Bearer ${token}`);
+  } finally {
+    server.close();
+  }
+});
+
+test("allows run_stage and get_envelope tool names", async () => {
+  const seen = [];
+  const { server, baseUrl } = await listen(async (req, res) => {
+    const body = await readJsonBody(req);
+    seen.push(body?.params?.name);
+    writeToolResult(res, body.id, { ok: true });
+  });
+  try {
+    for (const tool of ["run_stage", "get_envelope"]) {
+      const result = await run([
+        "--base-url",
+        baseUrl,
+        "--tool",
+        tool,
+        "--args",
+        "{}",
+        "--stateless",
+      ]);
+      assert.equal(result.status, 0, tool);
+    }
+    assert.deepEqual(seen, ["run_stage", "get_envelope"]);
+  } finally {
+    server.close();
+  }
+});
+
 test("--stateless against a session-mode-only mock errors without hanging", async () => {
   const { server, baseUrl } = await listen((_req, res) => {
     res.writeHead(400, { "content-type": "application/json" });

package/skills/stageflow-session-capture/references/catalog-authoring.md

@@ -24,6 +24,8 @@ Write reviewable or required outputs with `write_stage_artifact`, not checkout `
 
 Omit `gate_kinds`. A human-review checkpoint from the source session stays as prose in the stage approach, not a HITL gate.
 
+When a captured phase pushes, opens a PR, or otherwise needs git/`gh` credentials, declare `secrets:` on that stage (or its pipeline entry) — stages do not inherit Host ambient `GITHUB_TOKEN`. See [`../../stageflow-author/references/catalog-mapping.md`](../../stageflow-author/references/catalog-mapping.md#stage-secrets).
+
 Worked example: `assets/example-pipeline/research.yaml` and `assets/example-pipeline/implement.yaml`.
 
 ## Pipeline file

package/skills/stageflow-setup/SKILL.md

@@ -2,11 +2,12 @@
 name: stageflow-setup
 description: >-
   Installs Stageflow, scaffolds a starter catalog with sf init, then hard-stops
-  for provider login. Use when this project has no Stageflow install, sf is not
-  found, there is no catalog, first time running Stageflow here, the user asks
-  to set up Stageflow, or a provider is not logged in. Install, scaffold, and
-  provider-gate only — does not author pipelines or stages, capture a session,
-  or manage an MCP host.
+  for provider login. Optional Docker Compose path for a standing Host (UI+MCP).
+  Use when this project has no Stageflow install, sf is not found, there is no
+  catalog, first time running Stageflow here, the user asks to set up Stageflow,
+  a provider is not logged in, or the operator wants Compose local try. Install,
+  scaffold, and provider-gate only — does not author pipelines or stages, capture
+  a session, or auto-start an MCP host.
 disable-model-invocation: true
 ---
 
@@ -16,7 +17,7 @@ Install the CLI, scaffold a catalog, then hard-stop until a provider is configur
 
 Author pipelines and stages with `stageflow-author`. Capture a chat or past session with `stageflow-session-capture`. Start, watch, or answer a run with `stageflow-run`. Codify a repeating pattern with `stageflow-delegate`.
 
-This job does not author catalog YAML, capture a session, or manage an MCP host. Its surface is the `sf` CLI. Talking jobs cite [`../stageflow/references/control-surface.md`](../stageflow/references/control-surface.md) for MCP-vs-CLI; do not run the host probe in that file from this job.
+This job does not author catalog YAML, capture a session, or auto-start an MCP host. Its default surface is the `sf` CLI; Compose local try (below) is the optional standing-Host path. Talking jobs cite [`../stageflow/references/control-surface.md`](../stageflow/references/control-surface.md) for MCP-vs-CLI; do not run the host probe in that file from this job.
 
 ## Detect-before-mutate
 
@@ -68,9 +69,14 @@ Skip `$SF init` when probe 2 passed.
 
 Run this phase only after Install and Scaffold have succeeded or were already satisfied. Never print `ready to author` while no provider is `configured`.
 
+**Credential surface (do not mix):**
+
+- **Local CLI** (this job's default path): `providers login --api-key-env` / bare `<ID>_API_KEY` (e.g. `ANTHROPIC_API_KEY`). See Stageflow docs: Providers.
+- **Host / Compose boot:** `STAGEFLOW_PROVIDER_<ID>_API_KEY` or `STAGEFLOW_PROVIDER_<ID>_API_KEY_FILE`. Bare `OPENROUTER_API_KEY` / `ANTHROPIC_API_KEY` alone does **not** configure Host boot. See Stageflow docs: Providers — Non-interactive Host boot credentials; Docker and self-hosting — Local try.
+
 1. Run `$SF providers status`. **Done when** any row is `configured` — go to Completion. If a non-interactive login just succeeded, name that provider id.
 
-2. If none are configured, run `$SF providers list`. For each id (first column), test whether the environment has `<ID>_API_KEY` with `ID` uppercased (`anthropic` → `ANTHROPIC_API_KEY`). Test presence only — do not read or print the value.
+2. If none are configured, run `$SF providers list`. For each id (first column), test whether the environment has `<ID>_API_KEY` with `ID` uppercased (`anthropic` → `ANTHROPIC_API_KEY`). Test presence only — do not read or print the value. Do not treat `STAGEFLOW_PROVIDER_*` as satisfying this local CLI gate.
 
 3. On the first match, run:
 
@@ -90,7 +96,7 @@ Run this phase only after Install and Scaffold have succeeded or were already sa
    $SF providers login <id> --type oauth
    ```
 
-   Point at `docs/providers.md` for `pi_home` vs `sf_owned`. Leave the storage mode to the human.
+   Point at Stageflow docs: Providers (`pi_home` vs `sf_owned`). Leave the storage mode to the human. If the operator will use Compose instead, point them at the Docker Compose section below and `STAGEFLOW_PROVIDER_<ID>_API_KEY(_FILE)`.
 
 ## Completion
 
@@ -108,3 +114,40 @@ If this invocation used the `npx` fallback, add a following line:
 `CLI: npx stageflow (EACCES on npm i -g stageflow; this session only — a later invocation will re-check the global install)`
 
 A later job calls this skill as preflight. It does not re-implement the provider gate.
+
+## Optional: Docker Compose (standing Host)
+
+This job does **not** auto-start `sf ui` or `sf mcp`. Compose local try is the path to a standing Host (operator console **and** MCP on port **3847**). Keep the npm / `sf init` / local provider path above for CLI authoring; use Compose when the operator wants a container Host.
+
+Do not invent compose flags or env names. See Stageflow docs: Docker and self-hosting — Local try (checkout: `docs/docker.md`; also `.env.example`).
+
+1. From a Stageflow checkout (or image + compose that matches shipped contracts), copy `.env.example` → `.env`. Do not commit `.env`.
+
+2. Set `STAGEFLOW_CONTROL_TOKEN` to ≥32 characters, no whitespace (e.g. `openssl rand -hex 32`). Required when the image binds non-loopback.
+
+3. Set Host boot providers as `STAGEFLOW_PROVIDER_<ID>_API_KEY` or `_FILE` (e.g. `STAGEFLOW_PROVIDER_OPENROUTER_API_KEY`). Not bare `OPENROUTER_API_KEY` alone.
+
+4. Optional: `GITHUB_TOKEN` (or `GH_TOKEN`) for Host clone/fetch askpass — needed even for public repos.
+
+5. **Shell env overrides Compose `.env`.** Empty exported `GITHUB_TOKEN` / `GH_TOKEN` blanks the container value. Prefer:
+
+   ```bash
+   env -u GITHUB_TOKEN -u GH_TOKEN docker compose up --build -d
+   ```
+
+6. Wait for live: `curl -fsS http://127.0.0.1:3847/livez` → `{"ok":true,"status":"live",…}`.
+
+7. Open `http://127.0.0.1:3847` and paste the same control token under **Settings** (drive bearer for API/MCP).
+
+After Compose is up, talking jobs use MCP with `Authorization: Bearer <drive-token>` — see [`../stageflow/references/control-surface.md`](../stageflow/references/control-surface.md). `/api/health` is ungated; a health 200 is not authenticated MCP.
+
+## MCP checklist (optional standing Host)
+
+Do **not** auto-start `sf ui` / `sf mcp` from this job unless the operator already chose Compose or asked to start a Host. When a Host is up:
+
+1. Host up — probe [`../stageflow/scripts/detect-host.mjs`](../stageflow/scripts/detect-host.mjs) or `curl -fsS http://127.0.0.1:3847/livez`
+2. Register/ensure the catalog folder (`POST /api/projects` on trusted loopback, or a prior local `sf run`) — or use seeded `project_root: "examples"`
+3. Use **catalog-relative** paths only on MCP (absolute → `absolute_path_not_allowed`); CLI may pass abs and auto-register
+4. `list_pipelines` → `start_run` → `wait_run` (see Stageflow docs: MCP; Quickstart — MCP smoke path)
+
+`STAGEFLOW_OPERATOR_CWD` (skills) ≠ catalog `project_root` — see Stageflow docs: MCP — Skills cwd vs catalog project_root.