stageflow 0.25.0 → 0.27.0

package/examples/verify-tour/README.md

@@ -0,0 +1,80 @@
+# Verify tour
+
+One short spine that walks every **verify check type** in a single successful run. Each stage does one type. Prompts spell the tool calls so the checks we claim actually pass.
+
+This catalog is a **deep spine**: ungated `to:` is the next stop. Open the stage in the operator console and inspect that attempt’s verify evidence.
+
+Illegal catalogs (emit-only `command`, artifact without `when`, `if` on a loop, …) cannot live here — validate would reject the whole pipeline.
+
+## Run
+
+From the repo git root, after `sf ui` is up, pick pipeline `verify-tour` and task `verify-tour`.
+
+The task binds `checkout: .` (this git tree, resolved from the factory cwd). `checkout-check` writes `verify-tour-marker.txt` at that checkout root. Delete the file when you are done; do not commit it.
+
+Or:
+
+```bash
+npx tsx src/cli.ts validate --pipeline examples/verify-tour/verify-tour.pipeline.yaml
+npx tsx src/cli.ts run \
+  --pipeline examples/verify-tour/verify-tour.pipeline.yaml \
+  --task examples/verify-tour/verify-tour.task.yaml
+```
+
+Validate should succeed (`ok: true`). You may see `pipeline.model_applies` because `model` is set on the pipeline, not on each stage.
+
+The run should **succeed**. Every stage should **succeed**. `gate-check` pauses for a **confirm** accept in the operator console (or `--skip-gates` on the CLI).
+
+## Walk (follow-along order)
+
+| Level | Stage | Verify type | What the agent does | What Stageflow checks |
+|-------|-------|-------------|---------------------|------------------------|
+| 1 | `kickoff` | none | Emit empty success | — |
+| 2 | `artifact-check` | `artifact` emit + after | `write_stage_artifact` `note.md`, list it on emit | Basename on `artifacts`; file exists nonempty under the attempt artifacts dir |
+| 3 | `command-check` | `command` after | Emit empty success | Stageflow runs `echo verify-tour-ok` (exit 0) |
+| 4 | `checklist-check` | `checklist` after | Emit `checklist_attestations` for `self-review` | Items match the declared list exactly |
+| 5 | `payload-check` | `payload_schema` after | Emit `{"ok": true}` | Re-check captured payload against `io.output.schema` |
+| 6 | `gate-check` | `gate` confirm emit + after | `ask_operator` confirm, then emit | Last confirm this attempt is accept |
+| 7 | `checkout-check` | `checkout_changes` after | Write `verify-tour-marker.txt` in the checkout | Diff vs pre-attempt snapshot; `changed_files` matches exactly |
+
+## Scenario table
+
+| Scenario | How this pipeline covers it | Evidence |
+|----------|------------------------------|----------|
+| `type: artifact` emit | `note-declared` `when: [emit]` | Emit lists `note.md` (basename / suffix match, no disk I/O) |
+| `type: artifact` after | `note-on-disk` `when: [after]` `nonempty: true` | File on disk under attempt artifacts |
+| `type: command` | `echo-ok` `run: echo verify-tour-ok` | After-phase exit 0; stdout in verify evidence |
+| `type: checklist` | `self-review` two items | Envelope `checklist_attestations` match |
+| `type: payload_schema` | `payload-ok` after `{"ok": true}` | After-phase re-check of `io.output.schema` |
+| `type: gate` emit | `operator-ok` `kind: confirm` `when` includes `emit` | Soft reject until confirm accept |
+| `type: gate` after | same check `when` includes `after` | After-phase sees the accepted confirm on this attempt |
+| `type: checkout_changes` | `repo-touched` `path_fields: [changed_files]` | Marker file appears in the attempt diff and payload |
+| Bound checkout required | task `checkout: .` | Without a git checkout this last stage errors |
+| No `on_verify_fail` | omitted | A failed after-check fails the stage (no silent repair) |
+
+## Expected stage status
+
+| Stage | Status | Why |
+|-------|--------|-----|
+| `kickoff` | succeeded | entry |
+| `artifact-check` | succeeded | both artifact checks passed |
+| `command-check` | succeeded | command exited 0 |
+| `checklist-check` | succeeded | attestation matched |
+| `payload-check` | succeeded | payload matched schema |
+| `gate-check` | succeeded | confirm accepted |
+| `checkout-check` | succeeded | marker file changed the checkout |
+
+## Not in this pipeline
+
+These are real cases, but putting them here would fail validate or fail the run.
+
+| Scenario | Why it is absent | Where to see it |
+|---------|------------------|-----------------|
+| Failing after-phase verify | would fail the stage / run | [Verified Stage Execution](../../docs/verified-stage-execution.md) |
+| `on_verify_fail.mode: repair` | recovery policy, not a check type | `tests/fixtures/target-dialect/demo.pipeline.yaml` |
+| `on_verify_fail.mode: manual` | needs an operator recover decision after a failed check | [Verified Stage Execution — Manual recovery](../../docs/verified-stage-execution.md#manual-recovery) |
+| Other gate kinds (`free_text`, `multi_question`, `artifact_backed`) | `type: gate` is covered; kinds are HITL widgets | `examples/plan-review/`, `tests/fixtures/stages/hitl-four-kinds.yaml` |
+| `command` / `checklist` / `payload_schema` / `checkout_changes` with `when: [emit]` | illegal | yaml-catalog Verify |
+| Artifact without `when` | illegal | yaml-catalog Verify |
+| Gitignored marker file | `--exclude-standard` hides it; the check would fail | git checkout capability |
+| Unbound checkout | `checkout_changes` errors without `task.checkout` | [Verified Stage Execution](../../docs/verified-stage-execution.md) |

package/examples/verify-tour/verify-tour.pipeline.yaml

@@ -0,0 +1,162 @@
+id: verify-tour
+model: cursor/auto
+schemas:
+  empty:
+    type: object
+  ok-flag:
+    type: object
+    required: [ok]
+    properties:
+      ok:
+        type: boolean
+  changed:
+    type: object
+    required: [changed_files]
+    properties:
+      changed_files:
+        type: array
+        items:
+          type: string
+stages:
+  - id: kickoff
+    entry: true
+    route:
+      - to: artifact-check
+    system_prompt: |
+      Start the verify tour in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+
+  - id: artifact-check
+    route:
+      - to: command-check
+    system_prompt: |
+      Cover type: artifact (emit list check and after on-disk check).
+      1. Call write_stage_artifact with path note.md and a short nonempty markdown body.
+      2. Call emit_stage_envelope with status: success, a one-sentence summary, artifacts listing the path returned by write_stage_artifact, and payload: {}.
+      Do not call ask_operator. Do not edit the project checkout.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: note-declared
+        type: artifact
+        basename: note.md
+        when: [emit]
+      - id: note-on-disk
+        type: artifact
+        path: note.md
+        nonempty: true
+        when: [after]
+
+  - id: command-check
+    route:
+      - to: checklist-check
+    system_prompt: |
+      Cover type: command. Stageflow runs the declared command after you emit. Do not run it yourself.
+      Call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: {}.
+      Do not call ask_operator. Do not edit the project checkout.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: echo-ok
+        type: command
+        run: echo verify-tour-ok
+
+  - id: checklist-check
+    route:
+      - to: payload-check
+    system_prompt: |
+      Cover type: checklist. The attestation must match the declared items exactly.
+      Call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], payload: {}, and checklist_attestations:
+        - check_id: self-review
+          items:
+            - Tour steps completed
+            - No extra checkout edits
+      Do not call ask_operator. Do not edit the project checkout.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: self-review
+        type: checklist
+        items:
+          - Tour steps completed
+          - No extra checkout edits
+
+  - id: payload-check
+    route:
+      - to: gate-check
+    system_prompt: |
+      Cover type: payload_schema. Emit a payload that matches io.output.schema.
+      Call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: { "ok": true }.
+      Do not call ask_operator. Do not edit the project checkout.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/ok-flag"
+    verify:
+      - id: payload-ok
+        type: payload_schema
+
+  - id: gate-check
+    route:
+      - to: checkout-check
+    gate_kinds: [confirm]
+    system_prompt: |
+      Cover type: gate kind confirm (emit and after).
+      1. Call ask_operator with kind: confirm and message: "Accept to continue the verify tour."
+      2. Wait for the operator to accept. If they reject, ask again. Do not emit until accepted.
+      3. After accept, call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: {}.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: operator-ok
+        type: gate
+        kind: confirm
+        when: [emit, after]
+
+  - id: checkout-check
+    system_prompt: |
+      Cover type: checkout_changes. Edit the project checkout, not a stage artifact.
+      1. Create or overwrite verify-tour-marker.txt at the checkout root (the Project checkout path in this prompt) with one unique line (include a timestamp or random token).
+      2. Call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: { "changed_files": ["verify-tour-marker.txt"] }.
+      Do not gitignore that file. Do not commit, push, or delete other files. Do not call ask_operator.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/changed"
+    verify:
+      - id: repo-touched
+        type: checkout_changes
+        path_fields: [changed_files]

package/examples/verify-tour/verify-tour.task.yaml

@@ -0,0 +1,11 @@
+id: verify-tour
+goal: Walk each verify type and leave a checkout marker file.
+context: |
+  Verify tour — each stage covers one check type. Payloads and tool calls
+  are spelled in the stage prompts. checkout_changes needs this bound git
+  checkout; Stageflow compares it before and after checkout-check.
+constraints: |
+  Docs and one marker file only. Do not commit or push.
+  One-sentence summaries. Use each prompt's payload and attestations verbatim.
+  Never emit fork_choice. On gate-check, wait for confirm accept before emit.
+checkout: .

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "skills",
+    "examples",
     "README.md",
     "LICENSE"
   ],
@@ -56,6 +57,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^26.2.0",
+    "@types/semver": "^7.8.0",
     "tsx": "^4.23.11",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
@@ -71,7 +73,9 @@
     "better-sqlite3": "^13.0.3",
     "jiti": "^2.7.0",
     "pi-mcp-adapter": "^2.32.1",
+    "semver": "^7.8.5",
     "typebox": "^1.3.7",
+    "undici": "^7.29.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },

package/skills/stageflow/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: stageflow
 description: >-
-  Routes Stageflow work to one job: setup (install, catalog, or provider),
-  session-capture (reuse this chat or a past session), author (a loop the human
-  can explain), run (start, watch, or answer a pipeline), or delegate (a
-  repeating pattern). Use when the user mentions Stageflow, sf, a pipeline,
-  HITL, or a repeating Stageflow workflow.
+  Routes Stageflow work to one job: setup (install, catalog, provider, or
+  optional Docker Compose local try), session-capture (reuse this chat or a past
+  session), author (a loop the human can explain), run (start, watch, or answer
+  a pipeline), or delegate (a repeating pattern). Use when the user mentions
+  Stageflow, sf, a pipeline, HITL, or a repeating Stageflow workflow.
 compatibility: Requires the Stageflow CLI (sf). An MCP host (sf ui or sf mcp) is optional.
 ---
 
@@ -17,7 +17,7 @@ Read the matching job `SKILL.md` and follow it. Do not invent job behavior in th
 
 | Reach this job when | Read |
 |---|---|
-| Install is missing, there is no catalog, or a provider is not logged in | [../stageflow-setup/SKILL.md](../stageflow-setup/SKILL.md) |
+| Install is missing, there is no catalog, a provider is not logged in, or the operator wants Docker Compose local try | [../stageflow-setup/SKILL.md](../stageflow-setup/SKILL.md) |
 | The request should reuse a past session or this chat | [../stageflow-session-capture/SKILL.md](../stageflow-session-capture/SKILL.md) |
 | The request describes a loop the human can explain | [../stageflow-author/SKILL.md](../stageflow-author/SKILL.md) |
 | The request needs to start, watch, or answer a run | [../stageflow-run/SKILL.md](../stageflow-run/SKILL.md) |

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

@@ -11,18 +11,24 @@ 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**. 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).
+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**. Health stays Host/Origin-only (no bearer), so loopback probes keep working when a control token is configured. 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.
+Stdout is one line: `up <baseUrl>` or `down <baseUrl>`, with an optional trailing `bearer` when `STAGEFLOW_CONTROL_TOKEN` or `STAGEFLOW_CONTROL_TOKEN_FILE` is set in this environment (MCP/Compose need `Authorization: Bearer` — see [`../../stageflow-run/references/mcp-call.md`](../../stageflow-run/references/mcp-call.md)). Exit `0` when up, `1` when down, `2` on usage error.
 
-Start a host with `sf ui` or `sf mcp` when the user wants MCP. Do not auto-start one.
+**Health is not auth.** `GET /api/health` is ungated (Host/Origin only — no bearer). Do **not** treat a health 200 as authenticated MCP. Non-loopback and Compose Hosts require a drive bearer (`STAGEFLOW_CONTROL_TOKEN`); MCP and protected API calls need `Authorization: Bearer <drive-token>` when a control token is set. See Stageflow docs: MCP (Access control); Docker and self-hosting — Local try.
+
+Start a host with `sf ui` or `sf mcp` when the user wants MCP. Do not auto-start one. Compose local try is the standing-Host path — see `stageflow-setup` and Stageflow docs: Docker and self-hosting.
 
 ## When the host is up
 
-Use MCP tools over the Streamable HTTP endpoint at `{baseUrl}/mcp`. Tool names and payloads live in [docs/mcp.md](../../../docs/mcp.md). Typical talking-job tools: `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `decide_feedback_loop`, `get_envelope`, `read_artifact`, `validate`, `describe_pipeline`, `get_health`, `list_providers`, `list_models`, `list_project_mcp`, `probe_project_mcp`.
+Use MCP tools over the Streamable HTTP endpoint at `{baseUrl}/mcp`. Send `Authorization: Bearer <drive-token>` when `STAGEFLOW_CONTROL_TOKEN` (or a named drive token) is configured. Tool names and payloads live in Stageflow docs: MCP (checkout: [docs/mcp.md](../../../docs/mcp.md)). Typical talking-job tools: `list_pipelines`, `list_tasks`, `start_run`, `run_stage`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `decide_feedback_loop`, `get_envelope`, `read_artifact`, `list_checkout_changes`, `get_run_diff`, `read_checkout_file`, `validate`, `describe_pipeline`, `get_health`, `list_providers`, `list_models`, `list_project_mcp`, `probe_project_mcp`, `export_run`, `list_skills`, `list_stage_events`, `get_stage_verification`.
+
+`get_health` returns capacity fields plus an on-demand `disk` breakdown (`runs_bytes`, `worktrees_bytes`, `repos_bytes`, `state_db_bytes`, `a2a_artifacts_bytes`, `free_bytes`) for the durable root. When `slotsAvailable` is `0`, starts may still succeed as queued until `STAGEFLOW_MAX_QUEUED` is full — see `start_run` in the MCP docs.
+
+Some capabilities stay **CLI-only** (or `docker exec` on a container Host): `sf graph`, `sf migrate-yaml`, `sf skills install` (durable host install; prefer `start_run.skills` for harnesses), A2A config mutate/validate, and provider OAuth login. Provider API keys for Host boot use `STAGEFLOW_PROVIDER_<ID>_API_KEY(_FILE)`, not an MCP login tool. Use the MCP **CLI-only capabilities** decision table (Stageflow docs: MCP) instead of inventing MCP substitutes.
 
 ## 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 runs waiting`, `sf runs answer`, `sf runs feedback-decide`, `sf runs wait`, `sf validate`, `sf envelope get`, `sf artifact read`, `sf providers`.
+Use the `sf` CLI. Command names and flags live in Stageflow docs: CLI reference (checkout: [docs/cli-reference.md](../../../docs/cli-reference.md)). Typical talking-job commands: `sf run`, `sf runs waiting`, `sf runs answer`, `sf runs feedback-decide`, `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/scripts/detect-host.mjs

@@ -33,6 +33,15 @@ function parseArgs(argv) {
   return { baseUrl };
 }
 
+function clientHasControlToken(env = process.env) {
+  const plain = env.STAGEFLOW_CONTROL_TOKEN;
+  const filePath = env.STAGEFLOW_CONTROL_TOKEN_FILE;
+  return (
+    (plain !== undefined && plain.length > 0) ||
+    (filePath !== undefined && filePath.length > 0)
+  );
+}
+
 async function probe(baseUrl) {
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
@@ -50,5 +59,9 @@ async function probe(baseUrl) {
 
 const { baseUrl } = parseArgs(process.argv.slice(2));
 const status = await probe(baseUrl);
-console.log(`${status} ${baseUrl}`);
+const parts = [status, baseUrl];
+if (clientHasControlToken()) {
+  parts.push("bearer");
+}
+console.log(parts.join(" "));
 process.exit(status === "up" ? 0 : 1);

package/skills/stageflow/scripts/detect-host.test.mjs

@@ -7,10 +7,18 @@ import { test } from "node:test";
 
 const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "detect-host.mjs");
 
-function run(baseUrl) {
+function cleanEnv(extra = {}) {
+  const env = { ...process.env };
+  delete env.STAGEFLOW_CONTROL_TOKEN;
+  delete env.STAGEFLOW_CONTROL_TOKEN_FILE;
+  return { ...env, ...extra };
+}
+
+function run(baseUrl, opts = {}) {
   return new Promise((resolve) => {
     const child = spawn(process.execPath, [script, "--base-url", baseUrl], {
       stdio: ["ignore", "pipe", "pipe"],
+      env: opts.env ?? cleanEnv(),
     });
     let stdout = "";
     let stderr = "";
@@ -95,3 +103,23 @@ test("classifies a hung /api/health as down", async () => {
     server.close();
   }
 });
+
+test("notes bearer when STAGEFLOW_CONTROL_TOKEN is set without changing health probe", async () => {
+  const { server, baseUrl } = await listen((req, res) => {
+    assert.equal(req.url, "/api/health");
+    assert.equal(req.headers.authorization, undefined);
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ ok: true }));
+  });
+  try {
+    const result = await run(baseUrl, {
+      env: cleanEnv({
+        STAGEFLOW_CONTROL_TOKEN: "b".repeat(32),
+      }),
+    });
+    assert.equal(result.status, 0);
+    assert.equal(result.stdout.trim(), `up ${baseUrl} bearer`);
+  } finally {
+    server.close();
+  }
+});

package/skills/stageflow-author/SKILL.md

@@ -35,9 +35,9 @@ Ask until you can name every step, how they sequence, any decision point, and an
 
 ## Map
 
-Read [`references/catalog-mapping.md`](references/catalog-mapping.md). Apply those rules to the confirmed structure. Read [`references/stage-prompt-template.md`](references/stage-prompt-template.md) for each stage's `system_prompt`, optional `model`, `io`, `verify`, and `gate_kinds`. Apply the Anti-patterns section below while mapping. When the human needs hard advance gates, plan body `verify` and wiring `on_verify_fail`. When a review can demand changes, include an address-feedback stage before approve/ship.
+Read [`references/catalog-mapping.md`](references/catalog-mapping.md). Apply those rules to the confirmed structure. Read [`references/stage-prompt-template.md`](references/stage-prompt-template.md) for each stage's `system_prompt`, optional `model`, `io`, `verify`, and `gate_kinds`. Apply the Anti-patterns section below while mapping. When the human needs hard advance gates, plan body `verify` and wiring `on_verify_fail`. When a stage needs git/`gh`/registry credentials, plan `secrets:` (do not assume ambient Host env). When a review can demand changes, include an address-feedback stage before approve/ship.
 
-**Done when** you have a pipeline id, one stage id per step, `route` / `entry` wiring (optional `if`, `{ type: loop }`, sealed Clone Chain when the human wants one run per list item), a prompt plan per stage, and any `verify` / `on_verify_fail` / remediation stages the structure requires.
+**Done when** you have a pipeline id, one stage id per step, `route` / `entry` wiring (optional `if`, `{ type: loop }`, sealed Clone Chain when the human wants one run per list item), a prompt plan per stage, and any `verify` / `on_verify_fail` / remediation stages / `secrets` the structure requires.
 
 ## Anti-patterns
 
@@ -52,7 +52,8 @@ Author these contracts explicitly. They come from long runs that failed after ho
 | Give review blockers a place to land | Wire `review → address-feedback → approve/ship`. Put `verdict` / `blocking_findings` (or equivalent) in the review `io.output.schema`. |
 | Bind success to the full checklist | If a plan lists N commands, success requires all of them in `commands_run` with exit 0. Cheap checks first; slow suites last or in a verify stage. Size `timeout_ms` to the work. |
 | Use configured models on every sibling | Same configured `model` family after fan-out unless the human asks otherwise. Reliable model on publish/PR stages. |
-| Finish publish in the accept attempt | After `artifact_backed` accept: side effects (commit/push/PR) → final artifact → emit in the same attempt. Fix emit/schema errors by re-emitting. |
+| Finish publish in the accept attempt | After `artifact_backed` accept: side effects (commit/push/PR) → final artifact → emit in the same attempt. Declare `secrets:` for those side effects; do not assume ambient `GITHUB_TOKEN`. Fix emit/schema errors by re-emitting. |
+| Declare credentials the stage needs | Stages get a curated env — not Host `process.env`. Put `secrets:` on the stage body or pipeline entry. Never put `STAGEFLOW_CONTROL_TOKEN` / read tokens in `secrets:`. See [`catalog-mapping.md`](references/catalog-mapping.md#stage-secrets). |
 | Author a sealed Clone Chain | One run per list item is emitter → clone child → Join. Never write `clonable`, `clone_forks`, or emit-time `skip` / `once` / `fanout`. See [YAML catalog — Clone Chain](../../docs/yaml-catalog.md#clone-chain). |
 
 Throwaway checkout deliverables (HTML spike, scratch file): prompt builtin `write` at a checkout-relative path, `artifacts: []` on emit, path in `payload`.

package/skills/stageflow-author/references/catalog-mapping.md

@@ -114,6 +114,22 @@ See [YAML catalog — Clone Chain](../../../docs/yaml-catalog.md#clone-chain) an
 
 Do not author `clonable`, `clone_actions`, or envelope `clone_forks`. Do not put `clone_cap` / `clone_mode` on a stage that is not a Clone Chain emitter.
 
+## Stage secrets
+
+Stages receive a **curated** environment — not Host `process.env`. Credentials reach a stage only via `secrets:` on the stage body or the pipeline `uses:` entry. Do not assume ambient `GITHUB_TOKEN` in the stage.
+
+```yaml
+secrets:
+  - GITHUB_TOKEN                      # GIT_ASKPASS + materialised token file (no raw env)
+  - { name: GITHUB_TOKEN, as: env }   # when gh/MCP need the env var (askpass still set)
+```
+
+`GITHUB_TOKEN` / `GH_TOKEN` default to askpass (no raw env). Prefer `{ name: GITHUB_TOKEN, as: env }` when `gh` or MCP needs the env var — askpass remains set for plain HTTPS `git`. Never put `STAGEFLOW_CONTROL_TOKEN` or read tokens in `secrets:` (never grantable). The Host still needs `GITHUB_TOKEN` / `GH_TOKEN` for clone/fetch materialize even for public repos; that Host token is separate from stage grants.
+
+When a publish stage calls `gh`, add `requires: [{ tool: gh }]`. The base Docker image has no `gh` — operators derive an image. Stageflow never installs tools from `requires:`.
+
+Full reference: [YAML catalog — Stage secrets](../../../docs/yaml-catalog.md#stage-secrets), [migration-stage-environment.md](../../../docs/migration-stage-environment.md). Legacy contract-key catalogs → `sf migrate-yaml` (laptop / `docker exec`, not MCP).
+
 ## Models
 
 Confirm providers before writing. After fan-out, give every sibling the same configured `model` unless the human asks for different ones. Prefer a reliable configured model on side-effecting final stages.

package/skills/stageflow-author/references/catalog-write-conventions.md

@@ -20,7 +20,7 @@ One directory (or the project root) holds:
 | `<pipeline-id>.pipeline.yaml` | `id` matching the filename stem; `stages:` array of object entries |
 | `<stage-id>.yaml` | `id`, `system_prompt`; `model` when not inherited; required `io.input.schema` and `io.output.schema`; `verify` / `gate_kinds` when the step needs them |
 
-Each pipeline stage entry has `id` and `uses: ./<id>.yaml` (path relative to the pipeline file). At least one root marks `entry: true`. Sources list forward `route: [{ to: <id> }, …]`. Optional `on:` is skip-cascade policy (default succeeded-only); it does not launch from skipped/failed. Optional `if` gates a successor after the source succeeds (predicate on required `io.output.schema` fields). A review that can send work back adds `{ type: loop, to, max_replays, on_max_replays, replay_session }` inside `route`. A Clone Chain emitter puts `clone_cap` and `clone_mode` on that **pipeline entry**, never on the reusable stage body. Put `on_verify_fail` on the pipeline entry when after-phase `verify` should repair or wait for an operator. Filename stem matches `id`. Optional pipeline-root `model` fills stages that omit `model`. Sequencing rules: [`catalog-mapping.md`](catalog-mapping.md). Catalog load rejects `needs`, `fork`, and `feedback_loop` as YAML keys.
+Each pipeline stage entry has `id` and `uses: ./<id>.yaml` (path relative to the pipeline file). At least one root marks `entry: true`. Sources list forward `route: [{ to: <id> }, …]`. Optional `on:` is skip-cascade policy (default succeeded-only); it does not launch from skipped/failed. Optional `if` gates a successor after the source succeeds (predicate on required `io.output.schema` fields). A review that can send work back adds `{ type: loop, to, max_replays, on_max_replays, replay_session }` inside `route`. A Clone Chain emitter puts `clone_cap` and `clone_mode` on that **pipeline entry**, never on the reusable stage body. Put `on_verify_fail` on the pipeline entry when after-phase `verify` should repair or wait for an operator. `secrets` and `requires` may sit on the stage body or the `uses:` wrapper — stages get a curated env, not Host ambient credentials; see [`catalog-mapping.md`](catalog-mapping.md#stage-secrets). Filename stem matches `id`. Optional pipeline-root `model` fills stages that omit `model`. Sequencing rules: [`catalog-mapping.md`](catalog-mapping.md). Catalog load rejects `needs`, `fork`, and `feedback_loop` as YAML keys.
 
 ## Collisions
 

package/skills/stageflow-run/SKILL.md

@@ -17,6 +17,8 @@ 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.
+
 ## Preconditions
 
 Run `sf --version`. **Done when** it prints a version. If `sf` is missing, stop and name `stageflow-setup`.
@@ -30,9 +32,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 +51,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 +126,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 +134,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 +146,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 +185,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 +195,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.