stageflow 0.36.0 → 0.40.0

package/examples/memory/file-release.task.yaml

@@ -0,0 +1,24 @@
+id: file-release
+goal: File the release card with a table and the rollback command
+context: Memory new-notebook already exists. This key does not. It is not the older releases/2.4.1 card.
+constraints: The card body is the note exactly. Do not change the cover.
+input:
+  key: releases/2.5.0
+  note: |
+    # Release 2.5.0
+
+    Held. Do not deploy until the checkout incident on `TICKET-3180` is closed.
+
+    | Check | State | Owner |
+    | --- | --- | --- |
+    | Payments migration | reverted on 2.4.1 | payments |
+    | EU checkout | recovered 16:40 UTC | ada@example.com |
+    | This release | held | release desk |
+
+    Rollback command that was used for 2.4.1:
+
+    ```
+    sf runs rerun --run <previous> --from payments-migrate
+    ```
+
+    Decision: ship 2.5.0 only after a clean EU checkout hour, with the migration left out.

package/examples/memory/file-rich.pipeline.yaml

@@ -0,0 +1,40 @@
+id: file-rich
+memories:
+  - new-notebook
+stages:
+  - id: file
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "note".
+      The note is the full card body. It may contain headings, lists, tables, and fenced blocks. Copy it unchanged.
+      Do these steps in order, then stop:
+      1. Call add_memory_card with memory "new-notebook", that key, and content set to the note exactly. Do not summarize, rewrap, or drop a line.
+      2. Call read_memory_card with memory "new-notebook" and that key.
+      3. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","note":"<the exact text read_memory_card returned>"}.
+      Do not call replace_memory. Do not call update_memory_card. Do not call any memory id other than new-notebook. Do not write files. If add_memory_card returns MEMORY_CARD_EXISTS, stop and emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false

package/examples/memory/file-ticket.task.yaml

@@ -0,0 +1,7 @@
+id: file-ticket-1842
+goal: File one ticket card in the shared notebook
+context: First card for this ticket. The cover page is separate.
+constraints: One card. Do not change the cover.
+input:
+  key: TICKET-1842
+  note: Refund approved for order 4412. Customer asked for store credit.

package/examples/memory/file-timeline.task.yaml

@@ -0,0 +1,28 @@
+id: file-timeline
+goal: File the checkout outage as a structured card
+context: Memory new-notebook already exists. This key does not.
+constraints: The card body is the note exactly. Do not change the cover.
+input:
+  key: TICKET-3180
+  note: |
+    # Checkout 502s — EU
+
+    ## What broke
+
+    EU checkout returned 502 from 14:10 UTC. The payments migration in `releases/2.4.1` was the trigger. US traffic stayed up.
+
+    ## Timeline
+
+    1. **14:10** — Error rate crossed 8% on `POST /checkout`.
+    2. **14:22** — On-call paged `ada@example.com`.
+    3. **15:05** — Rollback of `releases/2.4.1` started.
+    4. **16:40** — 502s stopped.
+
+    ## Not the cause
+
+    > The storefront cache was flushed at 13:40. That was a separate change and the 502s started later, only in EU.
+
+    ## Next
+
+    - Write the rollback note on `releases/2.4.1`
+    - Keep this ticket as the incident record

package/examples/memory/find-card.pipeline.yaml

@@ -0,0 +1,46 @@
+id: find-card
+stages:
+  - id: find
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "query".
+      Do these steps in order, then stop:
+      1. Call read_memory_card with memory "notebook" and that key.
+      2. Call search_memory_cards with memory "notebook" and that query.
+      3. Call read_memory with memory "notebook".
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","note":"<the exact card body>","hits":"<the search result as JSON text>","page":"<the exact cover>"}.
+      Do not call add_memory_card, update_memory_card, or replace_memory. Do not call any memory id other than notebook. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - query
+          properties:
+            key:
+              type: string
+            query:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+            - hits
+            - page
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+            hits:
+              type: string
+            page:
+              type: string
+          additionalProperties: false
+memories:
+  - notebook

package/examples/memory/find-ticket.task.yaml

@@ -0,0 +1,7 @@
+id: find-ticket-1842
+goal: Read the ticket card and search the notebook
+context: A later run. The card should already be filed under TICKET-1842.
+constraints: Do not change the card or the cover.
+input:
+  key: TICKET-1842
+  query: refund

package/examples/memory/missing.pipeline.yaml

@@ -0,0 +1,16 @@
+id: missing-memory
+memories:
+  - does-not-exist
+stages:
+  - id: blocked
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      This pipeline must not start. The memory it names does not exist.
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/memory/probe-bash.task.yaml

@@ -0,0 +1,3 @@
+id: probe-bash
+goal: See whether bash can find memory files on the host.
+input: {}

package/examples/memory/recall.pipeline.yaml

@@ -0,0 +1,24 @@
+id: recall
+memories:
+  - notebook
+stages:
+  - id: read-page
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      Call read_memory with memory "notebook". Do not call replace_memory.
+      Then call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"page":"<the exact text read_memory returned>"}.
+      Do not change the page. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+          required:
+            - page
+          properties:
+            page:
+              type: string
+          additionalProperties: false

package/examples/memory/recall.task.yaml

@@ -0,0 +1,5 @@
+id: recall-notebook
+goal: Read the shared notebook and report the page exactly
+context: A later pipeline, attached to the same memory
+constraints: Do not change the page
+input: {}

package/examples/memory/remember-ada.task.yaml

@@ -0,0 +1,6 @@
+id: remember-ada
+goal: Add Ada to the shared notebook
+context: First note in an empty notebook
+constraints: One line only. Do not drop earlier lines.
+input:
+  note: Ada was sourced.

package/examples/memory/remember-grace.task.yaml

@@ -0,0 +1,6 @@
+id: remember-grace
+goal: Add Grace to the shared notebook
+context: The notebook already has earlier lines. Keep them.
+constraints: One new line only. Do not drop earlier lines.
+input:
+  note: Grace was shortlisted.

package/examples/memory/remember.pipeline.yaml

@@ -0,0 +1,58 @@
+id: remember
+stages:
+  - id: record
+    entry: true
+    route:
+      - to: confirm
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has one field, "note".
+      Do these steps in order, then stop:
+      1. Call read_memory with memory "notebook".
+      2. Call replace_memory with memory "notebook". Set content to the previous page, unchanged, then a newline if the page was not empty, then one new line "- " followed by the note. Keep every earlier line.
+      3. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"note":"<the note>","page":"<the full new page>"}.
+      Do not call any memory id other than notebook. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - note
+          properties:
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - note
+            - page
+          properties:
+            note:
+              type: string
+            page:
+              type: string
+          additionalProperties: false
+  - id: confirm
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      Call read_memory with memory "notebook". Do not call replace_memory.
+      Then call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"page":"<the exact text read_memory returned>"}.
+      Do not change the page. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          additionalProperties: true
+      output:
+        schema:
+          type: object
+          required:
+            - page
+          properties:
+            page:
+              type: string
+          additionalProperties: false
+memories:
+  - notebook

package/examples/memory/sandbox-memory-bash.pipeline.yaml

@@ -0,0 +1,28 @@
+id: sandbox-memory-bash
+stages:
+  - id: probe
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      Use the bash tool to look up the other memory which we dont have access to if its their. it might not be if its not found. 
+      if found or not then call the following emit stage tool.  
+      then also add something to the memory you have access to .
+      Then call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"found": true if the bash found the other memory, otherwise false, "output":"<the bash stdout>"}.
+    io:
+      input:
+        schema:
+          type: object
+          additionalProperties: true
+      output:
+        schema:
+          type: object
+          required:
+            - found
+            - output
+          properties:
+            found:
+              type: boolean
+            output:
+              type: string
+          additionalProperties: false
+memories:
+  - shared-notes

package/examples/memory/stageflow.yaml

@@ -0,0 +1,12 @@
+version: 1
+model: openrouter/nvidia/nemotron-3.5-lightning:free
+catalog:
+  pipelines:
+    - .
+  tasks:
+    - .
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"
+  exclude:
+    - missing.pipeline.yaml

package/examples/memory/update-card.pipeline.yaml

@@ -0,0 +1,43 @@
+id: update-card
+memories:
+  - notebook
+stages:
+  - id: revise
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "note".
+      Do these steps in order, then stop:
+      1. Call read_memory_card with memory "notebook" and that key.
+      2. Call update_memory_card with memory "notebook", that key, and content set to the note.
+      3. Call read_memory_card again with memory "notebook" and that key.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","before":"<the first read>","note":"<the second read>"}.
+      Do not call add_memory_card. Do not call replace_memory. Do not call any memory id other than notebook. Do not write files. If the first read returns MEMORY_CARD_NOT_FOUND, stop and emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - before
+            - note
+          properties:
+            key:
+              type: string
+            before:
+              type: string
+            note:
+              type: string
+          additionalProperties: false

package/examples/memory/update-ledger.task.yaml

@@ -0,0 +1,23 @@
+id: update-ledger
+goal: Replace the refund ledger after the customer confirmed the payout
+context: orders/4412/ledger already exists on new-notebook. This replaces that card and leaves the previous copy for the operator.
+constraints: The card body is the note exactly. Do not change the cover. Do not add a second card.
+input:
+  key: orders/4412/ledger
+  note: |
+    # Refund ledger — order 4412
+
+    Closed. The customer confirmed the payout.
+
+    | When | Who | Action | Amount |
+    | --- | --- | --- | --- |
+    | 2026-10-18 09:12 | grace@example.com | Request opened | 86.40 USD |
+    | 2026-10-18 11:04 | TICKET-2040 | Store credit declined | — |
+    | 2026-10-19 16:22 | payments | Paid to original card | 86.40 USD |
+    | 2026-10-20 09:03 | customer | Confirmed payout | 86.40 USD |
+
+    Still open:
+
+    - [x] Customer confirmed the payout
+    - [x] Reviewer recorded the decline
+    - [x] Receipt attached to the ticket

package/examples/memory/update-rich.pipeline.yaml

@@ -0,0 +1,44 @@
+id: update-rich
+memories:
+  - new-notebook
+stages:
+  - id: revise
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "note".
+      The note is the full new card body. Copy it unchanged, including tables and lists.
+      Do these steps in order, then stop:
+      1. Call read_memory_card with memory "new-notebook" and that key.
+      2. Call update_memory_card with memory "new-notebook", that key, and content set to the note exactly.
+      3. Call read_memory_card again with memory "new-notebook" and that key.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","before":"<the first read>","note":"<the second read>"}.
+      Do not call add_memory_card or replace_memory. Do not call any memory id other than new-notebook. Do not write files. If the card is missing, emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - before
+            - note
+          properties:
+            key:
+              type: string
+            before:
+              type: string
+            note:
+              type: string
+          additionalProperties: false

package/examples/memory/update-ticket.task.yaml

@@ -0,0 +1,7 @@
+id: update-ticket-1842
+goal: Replace the ticket card with a later decision
+context: The card TICKET-1842 already exists. This run changes that card only.
+constraints: Do not add a second card. Do not change the cover.
+input:
+  key: TICKET-1842
+  note: Refund paid out for order 4412. Store credit was declined.

package/examples/ship-feature/README.md

@@ -121,6 +121,21 @@ run finishes (or if it fails partway through), remove the worktree with
 `git worktree remove ../your-repo-feature-branch` from the main clone once
 you no longer need it.
 
+Alternatively, let Stageflow do this for you: point `checkout` at an object
+instead of a path —
+
+```yaml
+checkout:
+  branch: your-feature-branch   # optional — defaults to stageflow/<task id>
+  base: origin/main             # optional — defaults to HEAD
+```
+
+— and Stageflow creates (or reuses, if it already exists) a worktree for
+that branch the same way, as a sibling of your project root
+(`../.stageflow-worktrees/<branch>`). It's never auto-removed, same as one
+you make by hand — clean it up yourself with `git worktree remove` when
+you're done.
+
 ## Create a task
 
 Task context is the pipeline's portable feature brief. Include enough detail

package/examples/stage-mcp/README.md

@@ -39,7 +39,7 @@ PI_CURSOR_SETTING_SOURCES=all STAGEFLOW_ACTIVITY_VERBOSE=1 node dist/cli.js ui
 
 `npm run dev -- ui` runs the TypeScript CLI via tsx; use `node dist/cli.js ui` after `ui:build` so the console is served from `dist/ui`. Do not use a globally installed `sf` — Homebrew `sf` is an older build that cannot load this catalog.
 
-Open `http://127.0.0.1:3847`. Browse should list **stage-mcp** and **stage-mcp-missing-var**. **stage-mcp-dead** is excluded from the catalog manifest (so `sf validate --strict` and release CI stay green) but remains loadable by explicit path — see Scenario C.
+Open `http://127.0.0.1:3847`. Browse should list **stage-mcp** and **stage-mcp-missing-var**. **stage-mcp-dead** is excluded from the catalog manifest (so bare `sf validate --strict` stays green) but remains loadable by explicit path — see Scenario C.
 
 ## Terminal 2 — start a run (repo root)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.36.0",
+  "version": "0.40.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "main": "./dist/index.js",
@@ -81,6 +81,7 @@
     "@earendil-works/pi-tui": "^0.99.1",
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
+    "agentmail": "0.5.46",
     "better-sqlite3": "^13.0.3",
     "croner": "^10.0.1",
     "imapflow": "^2.2.5",