stageflow 0.23.0 → 0.27.0

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

@@ -20,6 +20,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 +38,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 +56,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,29 @@ 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.