stageflow 0.23.0 → 0.27.0

package/examples/oss-issue-contribution/pydantic-ai-7971.task.yaml

@@ -0,0 +1,53 @@
+id: pydantic-ai-7971
+goal: >
+  Deliver a verified minimal local fix for Pydantic AI issue #7971, Carry a
+  durable unit's emitted events and enqueued messages in its recorded output,
+  applied as source and test edits in the checkout working tree, plus an
+  operator-approved pull request opened against tejasghutukade/pydantic-ai
+  rather than pydantic/pydantic-ai.
+context: |
+  Issue: https://github.com/pydantic/pydantic-ai/issues/7971
+  Title: Carry a durable unit's emitted events and enqueued messages in its recorded output
+  Upstream repo: https://github.com/pydantic/pydantic-ai
+  Fork (PR target after the run): https://github.com/tejasghutukade/pydantic-ai
+  State: OPEN, unassigned. Pydantic contributing guidance asks for assignment
+  before an upstream PR, so this run prepares a local change for a fork PR only.
+
+  Reported behavior: under durable execution, ctx.emit() and ctx.enqueue() are
+  side effects of running a durable unit rather than part of its recorded
+  result, so they do not survive replay. On Prefect/DBOS a replayed result
+  never re-emits; on Temporal emit from a tool or event stream handler raises;
+  ctx.enqueue() is rejected on all three engines. A capability therefore cannot
+  emit from its own tools under durable execution.
+
+  Expected behavior (proposal on the issue): carry the emitted events and
+  enqueued messages back in the unit's recorded output and replay them
+  container-side. (1) Worker-side, install capture sinks on the unit's
+  RunContext so emit and enqueue append instead of raising or reaching the live
+  buffer. (2) Return them alongside the operation's value in an envelope over
+  ResultT. (3) Container-side, re-emit the captured events and extend
+  pending_messages before handing the value back. DurableOperation already has
+  the shape: one handler, one result_codec, and declaration sites in
+  durable_exec/_base.py.
+
+  Care needed: liveness on in-process engines (live delivery vs
+  capture-then-replay), and wire compatibility (decode both the bare value and
+  the envelope; see test_durable_exec_compat.py).
+
+  The full issue write-up, including per-engine detail and related issues, is
+  captured by the intake stage in issue-intake.md.
+constraints: |
+  Respect pydantic-ai AGENTS.md, CONTRIBUTING.md, and test docs.
+  Do not commit, push, create a branch, or open a pull request in any stage
+  except oss-approve-contribution, which may do so only after the operator
+  has explicitly accepted the contribution package through its
+  artifact_backed gate.
+  Do not target pydantic/pydantic-ai. The PR base is always
+  tejasghutukade/pydantic-ai (gh pr create --repo tejasghutukade/pydantic-ai).
+  Keep the change limited to the reproduced issue and its regression test.
+  Do not treat missing maintainer assignment as a reason to skip local work.
+  Source and test edits belong in the checkout working tree and must never be
+  replaced by a Stageflow artifact or report describing the change.
+  In the explainer stages only (oss-explain-issue, oss-explain-fix), the
+  explainer HTML belongs in Stageflow artifacts, never in the checkout.
+checkout: /Users/tejasghutukade/Projects/pydantic-ai

package/examples/oss-quick-fix/README.md

@@ -0,0 +1,65 @@
+# oss-quick-fix
+
+A minimal, fully unattended sibling of
+[`oss-issue-contribution`](../oss-issue-contribution/): one straight-line
+spine from "understand the issue" to "PR opened against my fork," with no
+operator gate anywhere in the run.
+
+Every stage declares `gate_kinds: []`, which unregisters `ask_operator`
+entirely — stages must decide and proceed, never pause for a human. Use this
+shape for issues small enough that you trust a single unsupervised pass; use
+`oss-issue-contribution` when you want parallel investigation/review and an
+operator approval before anything ships.
+
+## Flow
+
+```
+understand-issue → implement-fix → verify-fix → ship-fix
+```
+
+1. **understand-issue** — Reads the task goal/context, locates the responsible
+   code, reproduces the bug if practical, and writes `investigation.md`.
+2. **implement-fix** — Writes a failing regression test, fixes the root cause,
+   confirms the test (and the broader suite) passes, and writes
+   `fix-report.md`. `changed_files` must match `git diff --name-only` exactly.
+3. **verify-fix** — Independently re-runs the repo's real check/lint/test
+   commands against the actual diff (not the report's description of it) and
+   writes `verification.md`. `all_passed` is true only if every command it
+   ran actually exited zero.
+4. **ship-fix** — Commits, pushes, and opens a pull request against
+   `publish_repo` — the fork named in the task, never the upstream repo — and
+   writes `ship-report.md`. Refuses to proceed if `verify-fix` did not pass or
+   if the task does not name a fork.
+
+Every stage declares `on_verify_fail: { mode: repair, retry_safety: idempotent, max_attempts: 3 }`
+except `ship-fix`, which uses `mode: manual` / `retry_safety: side_effecting`
+because it is the only stage with side effects (git push, PR creation).
+
+## Runtime contracts
+
+| Stage | Required artifact | Other checks |
+|-------|--------------------|---------------|
+| `understand-issue` | `investigation.md` | — |
+| `implement-fix` | `fix-report.md` | `type: checkout_changes` on `changed_files` |
+| `verify-fix` | `verification.md` | — |
+| `ship-fix` | `ship-report.md` | — |
+
+## Run
+
+Fill in [`oss-quick-fix.task.yaml`](oss-quick-fix.task.yaml) — the issue, the
+fork to publish to, and `checkout` pointed at a clean working tree of the
+target repository.
+
+```bash
+sf validate --pipeline examples/oss-quick-fix/oss-quick-fix.pipeline.yaml --strict
+sf run \
+  --pipeline examples/oss-quick-fix/oss-quick-fix.pipeline.yaml \
+  --task examples/oss-quick-fix/oss-quick-fix.task.yaml
+```
+
+Needs a configured provider (`sf providers status`), and `gh` on `PATH`
+authenticated (`GH_TOKEN` or `GITHUB_TOKEN`) before `ship-fix` runs, or the
+publish step fails after the fix is already verified.
+
+Run `sf ui` in another terminal to inspect envelopes and artifacts — there are
+no gates to answer.

package/examples/oss-quick-fix/implement-fix.yaml

@@ -0,0 +1,84 @@
+id: implement-fix
+system_prompt: |
+  Fix the issue in the checkout: edit source, add a regression test, and get
+  both passing. Never call ask_operator — decide and proceed.
+
+  Read investigation.md from the prior envelope's artifacts (a run-relative
+  path under the "Factory run workspace" value given in this stage's user
+  prompt) for the root cause, target files, and fix approach. Treat it as the
+  starting point, not gospel — if the real fix differs once you're in the
+  code, take the correct one and say why in fix-report.md.
+
+  1. Write a regression test that fails against the current (buggy) code for
+     the reason described in investigation.md, using the repo's actual test
+     framework and conventions (find an existing test file near the affected
+     code and match its style; do not invent a new test setup pattern).
+     Confirm it fails, and capture that failing output.
+  2. Edit the source to fix the root cause. Keep the change minimal and
+     scoped to this issue — do not refactor, rename, or clean up unrelated
+     code along the way.
+  3. Run the regression test again and confirm it now passes. Then run the
+     broader test suite (or the most relevant scoped slice if a full run is
+     impractical) to check you haven't broken anything else. If something
+     breaks, fix it before moving on — you own this loop end to end; nothing
+     downstream can repair a broken implementation.
+  4. Call write_stage_artifact with path fix-report.md containing: what you
+     changed and why, the regression test's id/path and its before/after
+     output, every command you ran with its result, and anything from
+     investigation.md you deviated from and why.
+  5. Call emit_stage_envelope exactly once. changed_files must match
+     git diff --name-only exactly — no more, no fewer.
+model: openrouter/minimax/minimax-m3:free
+timeout_ms: 7200000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - root_cause
+        - target_files
+        - repro_confirmed
+        - fix_approach
+      properties:
+        root_cause:
+          type: string
+        target_files:
+          type: array
+          items:
+            type: string
+        repro_confirmed:
+          type: boolean
+        fix_approach:
+          type: string
+      additionalProperties: false
+  output:
+    schema:
+      type: object
+      required:
+        - changed_files
+        - regression_test
+        - tests_passed
+      properties:
+        changed_files:
+          type: array
+          items:
+            type: string
+        regression_test:
+          type: string
+        tests_passed:
+          type: boolean
+      additionalProperties: false
+verify:
+  - id: fix-report
+    type: artifact
+    path: fix-report.md
+    nonempty: true
+    when:
+      - after
+  - id: checkout-changed
+    type: checkout_changes
+    path_fields:
+      - changed_files
+    when:
+      - after
+gate_kinds: []

package/examples/oss-quick-fix/oss-quick-fix.pipeline.yaml

@@ -0,0 +1,35 @@
+id: oss-quick-fix
+stages:
+  - id: understand-issue
+    entry: true
+    route:
+      - to: implement-fix
+    uses: ./understand-issue.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: implement-fix
+    route:
+      - to: verify-fix
+    uses: ./implement-fix.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: verify-fix
+    route:
+      - to: ship-fix
+    uses: ./verify-fix.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: ship-fix
+    uses: ./ship-fix.yaml
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting

package/examples/oss-quick-fix/oss-quick-fix.task.yaml

@@ -0,0 +1,19 @@
+id: oss-quick-fix-template
+goal: >
+  Deliver a verified minimal local fix for <issue URL / short description>,
+  applied as source and test edits in the checkout working tree, plus a pull
+  request opened against your own fork (never the upstream repository).
+context: |
+  Issue: <issue URL>
+  Title: <copy the current issue title>
+  Upstream repo: <owner/repo>
+  Fork (PR target): <your-username>/<repo>
+  Reported behavior: <copy or summarize the concrete failure>
+  Expected behavior: <copy or summarize the acceptance criterion>
+constraints: |
+  Respect the target repository's AGENTS.md / CONTRIBUTING.md and test
+  conventions.
+  publish_repo in the final stage must be exactly the fork named above —
+  never the upstream owner/repo.
+  Keep the change limited to the reported issue and its regression test.
+checkout: /absolute/path/to/checkout

package/examples/oss-quick-fix/ship-fix.yaml

@@ -0,0 +1,81 @@
+id: ship-fix
+system_prompt: |
+  Publish the verified fix as a pull request against your own fork —
+  never the upstream project. Opening a PR against upstream is a separate,
+  explicitly-authorized manual step outside this pipeline; this stage never
+  does that. Never call ask_operator or pause for review — within that
+  fork-only boundary, commit, push, and open the pull request yourself.
+
+  Read verification.md, fix-report.md, and investigation.md from prior
+  envelopes' artifacts (run-relative paths under the "Factory run workspace"
+  value given in this stage's user prompt). Do not proceed if
+  verification.md's all_passed is not true — emit failure instead and say
+  what's unresolved.
+
+  publish_repo is exactly the fork repository the task goal/context names as
+  the PR target (e.g. your-username/project, not the original upstream
+  owner/project). If the task does not explicitly name a fork, emit failure
+  instead of guessing — never push or open a PR against a repository nobody
+  named, and never target the upstream repository under any circumstance.
+
+  1. Run git status to confirm the diff from implement-fix/verify-fix is
+     still present and is the only thing you're about to commit.
+  2. Stage exactly the changed files (never a blanket add), commit with a
+     concise message describing the fix and why (match the target repo's
+     commit conventions from investigation.md if it recorded any), and push
+     to a new branch on publish_repo (your fork).
+  3. Open a pull request with gh pr create --repo <publish_repo> against that
+     fork's default branch: title stating the fix, body with the issue
+     reference, root cause, what changed, and the verification commands that
+     passed. Note in the body that this targets the fork and that opening it
+     against upstream is a separate manual step.
+  4. Confirm the PR exists with gh pr view. Call write_stage_artifact with
+     path ship-report.md containing the branch, commit sha, PR url, and the
+     exact git/gh commands you ran.
+  5. Call emit_stage_envelope exactly once. opened is true only if gh pr view
+     confirmed the PR exists.
+model: openrouter/minimax/minimax-m3:free
+timeout_ms: 7200000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - commands_run
+        - all_passed
+      properties:
+        commands_run:
+          type: array
+          items:
+            type: string
+        all_passed:
+          type: boolean
+        notes:
+          type: string
+      additionalProperties: false
+  output:
+    schema:
+      type: object
+      required:
+        - publish_repo
+        - branch
+        - opened
+        - pr_url
+      properties:
+        publish_repo:
+          type: string
+        branch:
+          type: string
+        opened:
+          type: boolean
+        pr_url:
+          type: string
+      additionalProperties: false
+verify:
+  - id: ship-report
+    type: artifact
+    path: ship-report.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/oss-quick-fix/understand-issue.yaml

@@ -0,0 +1,67 @@
+id: understand-issue
+system_prompt: |
+  Understand the reported issue well enough to fix it, then write
+  investigation.md as the durable record downstream stages read instead of
+  re-deriving this work. Do not edit source files in this stage. Never call
+  ask_operator — this pipeline runs unattended; make the best defensible call
+  yourself and keep going.
+
+  1. Read the task goal and context for the issue statement (what's broken,
+     why, why it matters). If the checkout has AGENTS.md, CONTRIBUTING.md, or
+     other repo-instruction files, read the ones that govern the suspected
+     code area and note anything that constrains how a fix should look
+     (commit conventions, test runner, things you must not touch).
+  2. Locate the actual code responsible, by reading it — not by guessing from
+     the issue text. Trace the failure to specific files and line ranges.
+  3. Reproduce the bug if at all practical: write and run a minimal script,
+     failing test, or repro command that demonstrates the broken behavior
+     right now, in this checkout. If true reproduction isn't practical
+     (e.g. needs hardware or a live external service you don't have), say so
+     explicitly and explain what you verified by reading the code instead —
+     do not claim a reproduction that didn't happen.
+  4. Call write_stage_artifact with path investigation.md containing: the
+     issue restated in full (not abbreviated — downstream stages rely on
+     this, not on the task text), root cause with file:line references,
+     repro method and its actual output, the fix approach you intend to take
+     and why, and any repo rules from step 1 that constrain the fix.
+  5. Call emit_stage_envelope exactly once with a payload matching the
+     schema.
+
+  No placeholder values (n/a, tbd, unknown, "see issue") anywhere in the
+  payload or artifact — if something is genuinely unknown, say what you'd
+  need to find out and why you couldn't, and still record what you did
+  verify.
+model: openrouter/minimax/minimax-m3:free
+timeout_ms: 7200000
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - root_cause
+        - target_files
+        - repro_confirmed
+        - fix_approach
+      properties:
+        root_cause:
+          type: string
+        target_files:
+          type: array
+          items:
+            type: string
+        repro_confirmed:
+          type: boolean
+        fix_approach:
+          type: string
+      additionalProperties: false
+verify:
+  - id: investigation
+    type: artifact
+    path: investigation.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/oss-quick-fix/verify-fix.yaml

@@ -0,0 +1,73 @@
+id: verify-fix
+system_prompt: |
+  Independently verify the fix is correct, complete, and clean before it
+  ships — you are the only check this pipeline has; there is no human review
+  step. Never call ask_operator. If you find a problem, fix it yourself and
+  re-verify rather than reporting it downstream.
+
+  Read fix-report.md and investigation.md from prior envelopes' artifacts
+  (run-relative paths under the "Factory run workspace" value given in this
+  stage's user prompt).
+
+  1. Read the actual diff (git diff) rather than trusting fix-report.md's
+     description of it. Confirm the change matches the claimed root cause
+     and is scoped to the issue — flag and fix anything unrelated, debug
+     leftovers, commented-out code, or stray files.
+  2. Run the repo's real check/lint/typecheck command and its real test
+     command (found in AGENTS.md, package scripts, or equivalent — use
+     whatever investigation.md recorded, or find it yourself if that's
+     incomplete). Run the regression test by its exact id, and the broader
+     suite. Record every command and its exit status.
+  3. If anything fails or looks wrong, fix it in this stage and re-run until
+     it's clean. Do not report success on a red run, and do not hand a known
+     problem downstream with a note about it instead of fixing it.
+  4. Call write_stage_artifact with path verification.md containing: every
+     command run and its result, confirmation the regression test passes,
+     confirmation of no unrelated changes, and any issues you found and
+     fixed in this stage.
+  5. Call emit_stage_envelope exactly once with all_passed true only if
+     every command you ran actually exited zero.
+model: openrouter/minimax/minimax-m3:free
+timeout_ms: 7200000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - changed_files
+        - regression_test
+        - tests_passed
+      properties:
+        changed_files:
+          type: array
+          items:
+            type: string
+        regression_test:
+          type: string
+        tests_passed:
+          type: boolean
+      additionalProperties: false
+  output:
+    schema:
+      type: object
+      required:
+        - commands_run
+        - all_passed
+      properties:
+        commands_run:
+          type: array
+          items:
+            type: string
+        all_passed:
+          type: boolean
+        notes:
+          type: string
+      additionalProperties: false
+verify:
+  - id: verification
+    type: artifact
+    path: verification.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/plan-review/README.md

@@ -0,0 +1,37 @@
+# plan-review
+
+Two-stage pipeline with an **artifact-backed operator gate** (`ask_operator`). This is an **SDLC-style example** — plan review before implementation — but the same HITL pattern applies to any workflow you author.
+
+Fixture twin: `tests/fixtures/pipelines/plan-review-proving.pipeline.yaml`.
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed
+- Provider auth connected
+- Operator console: `sf ui` (default `http://127.0.0.1:3847`)
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --pipeline examples/plan-review/plan-review.pipeline.yaml --strict
+```
+
+Terminal 1:
+
+```bash
+sf ui
+```
+
+Terminal 2:
+
+```bash
+sf run \
+  --pipeline examples/plan-review/plan-review.pipeline.yaml \
+  --task examples/plan-review/plan-review.task.yaml
+```
+
+When the first stage blocks on HITL, open the run in the console, review the plan artifact, and accept or reject. Exit code `2` means waiting on operator input.
+
+See [docs/hitl.md](../../docs/hitl.md).

package/examples/plan-review/plan-review-followup.yaml

@@ -0,0 +1,13 @@
+id: plan-review-followup
+system_prompt: |
+  Acknowledge that the prior plan-review stage completed with operator acceptance
+  of the plan. Call emit_stage_envelope once with a short summary. Do not call
+  ask_operator. Do not perform further HITL.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/plan-review/plan-review.pipeline.yaml

@@ -0,0 +1,9 @@
+id: plan-review
+stages:
+  - id: plan-review
+    entry: true
+    route:
+      - to: plan-review-followup
+    uses: ./plan-review.yaml
+  - id: plan-review-followup
+    uses: ./plan-review-followup.yaml

package/examples/plan-review/plan-review.task.yaml

@@ -0,0 +1,9 @@
+id: plan-review
+goal: Prove plan-review HITL through artifact-backed accept/reject then follow-up
+context: |
+  Operator-console proving task for the plan-review pipeline. The first stage
+  must write a plan artifact, gate on ask_operator kind artifact_backed, and
+  emit only after accept. The follow-up stage only acknowledges acceptance.
+constraints: |
+  Do not skip ask_operator. Do not emit_stage_envelope before plan accept.
+  Follow-up must not call ask_operator.

package/examples/plan-review/plan-review.yaml

@@ -0,0 +1,25 @@
+id: plan-review
+gate_kinds:
+  - artifact_backed
+system_prompt: |
+  Your job is to produce a concise feature plan for the task and get operator
+  acceptance before completing this stage.
+
+  1. Write a concise feature plan via write_stage_artifact to a stage artifact
+     path (for example plan.md under stages/plan-review/attempts/1/artifacts/).
+  2. Call ask_operator with kind artifact_backed referencing that artifact path
+     so the operator can review the plan.
+  3. On reject or change text: revise the plan artifact and call ask_operator
+     again with artifact_backed in this same stage. Do not complete yet.
+  4. Call emit_stage_envelope with an advancing success status only after the
+     operator accepts/confirms the plan. Never emit before plan accept.
+  5. Optionally, before the plan gate, you may ask one clarifying free_text or
+     multi_question via ask_operator if needed. Never emit before plan accept.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/playwright-mcp/README.md

@@ -0,0 +1,39 @@
+# playwright-mcp
+
+One-stage walkthrough: **open a page and screenshot it**, using Microsoft Playwright MCP (`npx @playwright/mcp@latest`) from git-root `.mcp.json`.
+
+Playwright's `--output-dir` is interpolated to `STAGEFLOW_STAGE_ARTIFACTS_DIR` (this attempt's artifacts folder). Auto-named snapshots use that directory. A named `browser_take_screenshot` `filename` does **not** — Playwright MCP resolves it against the MCP client workspace (the project checkout). The stage prompt therefore passes `${STAGEFLOW_STAGE_ARTIFACTS_DIR}/page.png` (stamped to an absolute artifacts path at attach) so the PNG lands in the run Files pane instead of the git root.
+
+| Stage | MCP | What it does |
+|-------|-----|----------------|
+| `screenshot` | `playwright` | `browser_navigate` → `browser_take_screenshot` (`page.png`) |
+
+Completion requires `page.png` on disk. Settings Check (no stage) falls back to `examples/playwright-mcp/.playwright-mcp/` (gitignored).
+
+## Prerequisites
+
+- Node.js ≥ 20 and this repo's CLI (`npm run build`), not an older global `sf`
+- Provider auth (`sf ui` → Settings → Providers)
+- First run may download Chromium via Playwright (needs network)
+
+Git-root `.mcp.json` already names `playwright`. The stage still passes `mcp: [playwright]` — listing it in the catalog is not attach.
+
+Optional: Settings → **Project MCP servers** → Check `playwright` before the run.
+
+## Run (repo root)
+
+```bash
+npm run build
+node dist/cli.js validate --pipeline examples/playwright-mcp/playwright-mcp.pipeline.yaml --strict
+node dist/cli.js run \
+  --pipeline examples/playwright-mcp/playwright-mcp.pipeline.yaml \
+  --task examples/playwright-mcp/playwright-mcp.task.yaml
+```
+
+Inspect:
+
+```bash
+node dist/cli.js envelope get --run <runId> --stage screenshot --json
+```
+
+The Files row is `page.png`.

package/examples/playwright-mcp/playwright-mcp.pipeline.yaml

@@ -0,0 +1,5 @@
+id: playwright-mcp
+stages:
+  - id: screenshot
+    uses: ./screenshot.yaml
+    mcp: [playwright]

package/examples/playwright-mcp/playwright-mcp.task.yaml

@@ -0,0 +1,4 @@
+id: playwright-mcp
+goal: Open https://google.com and take a screenshot of that page as a PNG artifact.
+context: One-stage Playwright MCP walkthrough. Playwright must save page.png under this attempt's artifacts directory (absolute path in the stage prompt), not the repo root.
+constraints: Use only the playwright server named on the stage. Do not call ask_operator. The screenshot must be page.png in artifacts, not markdown and not the git root.

package/examples/playwright-mcp/screenshot.yaml

@@ -0,0 +1,40 @@
+id: screenshot
+system_prompt: |
+  Open the URL from the task in Playwright MCP, then take a screenshot.
+  Call browser_navigate, then browser_take_screenshot with type png and
+  filename exactly ${STAGEFLOW_STAGE_ARTIFACTS_DIR}/page.png — copy that
+  path verbatim. Playwright resolves a bare filename like page.png against
+  the project checkout (repo root), not --output-dir. Do not pass filename
+  page.png without the artifacts-directory prefix. Do not write screenshot.md.
+  Do not call write_stage_artifact for the image. Do not call ask_operator.
+
+  When finished, call emit_stage_envelope exactly once with status success,
+  a short summary, payload { "url": "<final page URL>", "screenshot": "page.png" },
+  and artifacts listing the run-relative PNG path this session already names
+  (stages/screenshot/attempts/<n>/artifacts/page.png). summary and payload are
+  handed downstream verbatim. State outcomes and artifact pointers only.
+
+  Your last tool call in this attempt must be emit_stage_envelope.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - url
+        - screenshot
+      properties:
+        url:
+          type: string
+        screenshot:
+          type: string
+verify:
+  - id: png
+    type: artifact
+    path: page.png
+    nonempty: true
+    when:
+      - after