npm - pi-baton - Versions diffs - 0.8.0 → 0.8.6 - Mend

pi-baton 0.8.0 → 0.8.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/CHANGELOG.md +208 -178
package/README.md +184 -184
package/lib/run-store.ts +23 -12
package/lib/workflow-discovery.ts +70 -28
package/package.json +67 -67

package/CHANGELOG.md CHANGED Viewed

@@ -1,178 +1,208 @@
-# Changelog
-All notable changes to this project will be documented in this file.
-This project follows semantic versioning.
-## [Unreleased]
-## [0.8.0] - 2026-09-14
-### Added
-- `/baton:history` lists recent completed or failed Baton runs from persisted `.pi/baton/runs/` manifests, with bounded scan/output limits, skip diagnostics for unreadable manifests, and tests for empty, single, multi-run, exclusion, scan-cap ordering, and command registration cases.
-- `/baton:status` and `formatStatusSummary` now include the stored `failure` reason for terminal failed runs, with status tests covering iteration-cap exhaustion and other failure paths.
-### Changed
-- README quick start and `docs/workflows.md` now document when to use `/baton:history` versus `/baton:status`, including the terminal-run fallback behavior for status.
-- README quick start and `docs/workflows.md` now document that `/baton:status` falls back to the most recent finished run when no active run exists.
-- Refreshed ROADMAP.md: marked S-109 done, updated release direction for 0.8.0/0.9.0, and added maintenance seed candidates S-110 through S-113 for the weekly seed planner.
-- Updated ROADMAP.md to mark S-108 done and refresh the security status table after the two-stage review gauntlet shipped in 0.7.5.
-- Aligned ROADMAP S-109 status with the shipped `docs/workflows.md` authoring guide.
-## [0.7.5] - 2026-08-22
-### Changed
-- Merge the 2026-08-22 managed OSS dependency and maintenance PR batch.
-### Added
-- Added the builtin `Two-Stage Review Gauntlet` workflow to demonstrate a non-default two-stage review graph.
-### Changed
-- Bump package version to `0.7.3` for the next patch release.
-- Bumped Pi dev toolchain packages to clear the transitive `protobufjs` audit advisory; the remaining `brace-expansion` finding is documented as upstream-blocked by `@earendil-works/pi-coding-agent`'s published shrinkwrap.
-- Removed unused `clearActiveRunPointer` export from `lib/run-store.ts` (dead code with no callers; `loadActiveRun` / `loadMostRecentTerminalRun` already treat a missing `runId` as no active pointer).
-## [0.7.2] - 2026-07-04
-### Added
-- `/baton:status` now shows the most recent finished run summary (state, last step, iteration, run directory) after a run reaches `completed` or `failed`, with clear finished-run framing instead of the no-active-run message.
-- Buy Me a Coffee sponsor button in README and native GitHub funding link via `.github/FUNDING.yml`.
-### Changed
-- Merged Dependabot PR #14: bump `@earendil-works/pi-ai` devDependency from 0.78.1 to 0.80.2 (type-check clean, 57/57 tests passing).
-- Removed leftover template scaffolding (`prompts/`, `themes/`, `skills/`).
-- Deleted stale template bootstrap docs (`docs/examples.md`, `docs/github-template.md`, `docs/repository-settings.md`, `docs/typescript.md`, `docs/template-checklist.md`) that shipped to npm consumers describing non-existent commands.
-- Updated ROADMAP.md to reflect current version (0.7.2), test count (57), and seed completion status for S-101, S-102, S-103, S-105.
-## [0.7.1] - 2026-06-27
-### Changed
-- README aligned to the current Pi extension template: added `Features`, `Release`, `Security`, and `Links` sections; expanded install flows (`npm`, GitHub, project-local, and `pi -e`); and updated `Package contents` to match the published tarball.
-## [0.7.0] - 2026-06-25
-### Added
-- Command handler tests for `/baton:new`, `/baton:start`, `/baton:run`, and `/baton:status` covering scaffold creation, inline validation, active-run guard, and no-active-run messaging.
-- Handoff payload shape tests for implement, linear, and fix transitions.
-- Run-store tests for active-run visibility across idle, running, and terminal states.
-### Changed
-- Finalizes the shipped builtin `default-review-loop` workflow (`worker` / `reviewer` / `worker`) with full v1 command-surface test coverage.
-## [0.6.0] - 2026-06-25
-### Added
-- Structured step envelopes for every run step (`summary`, `rawOutputPath`, and review fields when applicable).
-- Step handoff payload carries `taskBrief`, prior `stepOutputSummary`, `rawOutputPath`, and run metadata between isolated steps.
-- Review contract enforcement: `reject` requires non-empty `findings`; `accept` requires `acceptanceNote`.
-- Builtin `default-review-loop` routes `fix` back to `review`; iteration cap stops infinite reject loops.
-- Step-level `model` override with placeholder and session-model fallback via `resolveStepModel`.
-### Changed
-- Expanded `run-engine` and `review-contract` tests for fix→review routing, model routing, envelope persistence, and contract violations.
-## [0.5.0] - 2026-06-23
-### Added
-- `/baton:run` continuous run engine executes the active idle run through isolated subagent steps to a terminal state.
-- Step records persist under `.pi/baton/runs/<run>/steps/` and raw outputs under `outputs/`.
-- Terminal run summaries report the failing step as `last step` when step execution fails.
-### Changed
-- Expanded `run-engine` tests for step/output persistence, state transitions, and failure `last step` reporting.
-## [0.4.0] - 2026-06-22
-### Added
-- `/baton:start` creates an idle run from workflow selection and a task brief without starting execution.
-- `/baton:status` reports workflow name, task brief, last/current step, run state, iteration count, and run directory.
-- Single active run guard blocks a second `/baton:start` and points users to `/baton:status` or `/baton:run`.
-- Run manifests persist under `.pi/baton/runs/` with an active-run pointer.
-- Expanded workflow schema validation tests covering required fields, linear `next` transitions, review `on_accept` / `on_reject` branches, and invalid YAML handling at discovery time.
-### Changed
-- Workflow selection display names continue to come from YAML `name`; invalid or incomplete workflow documents now fail with explicit validation errors during `/baton:start` and `/baton:run` discovery.
-## [0.3.0] - 2026-06-18
-### Added
-- `/baton:new` re-prompts for a workflow name when the derived filename collides with an existing scaffold.
-- Tests for lazy `.pi/baton/workflows/` creation and kebab-case filename derivation.
-### Changed
-- Workflow discovery keeps user-defined `.pi/baton/workflows/*.yaml` entries ahead of builtin package workflows in selection order.
-## [0.2.3] - 2026-06-13
-### Added
-- README header icon and packaged `assets/pi-baton-icon-512.png` branding asset.
-### Changed
-- `assets/` is now included in the published package.
-## [0.2.2] - 2026-06-13
-### Added
-- Live Baton run widget above the editor during `/baton:run`, showing workflow, brief, active step, agent, judgment, and step checklist.
-- Footer status line (`baton: implement`, `baton: review`, etc.) while a run is in progress.
-## [0.2.1] - 2026-06-13
-### Fixed
-- Ship builtin `worker` and `reviewer` subagent definitions so `default-review-loop` runs without pre-created `.pi/agents/` files.
-- Validate required workflow agents during `/baton:start` and `/baton:run` with clearer missing-agent errors.
-## [0.2.0] - 2026-06-13
-### Added
-- `/baton:new`, `/baton:start`, `/baton:run`, and `/baton:status` command surface.
-- Builtin `default-review-loop` workflow with `worker` / `reviewer` / `worker` agent mapping.
-- YAML workflow discovery, inline validation, scaffold generation, and run persistence under `.pi/baton/`.
-- Isolated subagent step execution with structured handoff, review contract enforcement, and per-step model routing.
-## [0.1.2] - 2026-06-04
-### Changed
-- README and `docs/template-checklist.md` now follow the Pi OSS minimal-docs policy: `docs/` is optional, with explicit post-generation cleanup for template bootstrap docs.
-- Template bootstrap docs (`github-template.md`, `repository-settings.md`, `typescript.md`) are labeled for delete-or-merge after setup.
-## [0.1.1] - 2026-06-01
-### Changed
-- Publish workflow now supports npm publishing on merged package version bumps in addition to tags, releases, and manual dispatch.
-- Publish workflow now installs a current npm CLI so npm Trusted Publishing OIDC is supported.
-- CI and publish workflow commands no longer include literal trailing `\\n` text.
-## [0.1.0] - YYYY-MM-DD
-### Added
-- Initial Pi package template.
-- Example extension, Agent Skill, prompt, and theme.
-- CI and npm Trusted Publishing workflow.
+# Changelog
+## 0.8.5 - 2026-09-27
+- chore: periodic patch bump after 7+ days without npm publish
+## 0.8.4 - 2026-09-27
+- chore: periodic patch bump after 7+ days without npm publish
+## 0.8.3 - 2026-09-27
+- chore: periodic patch bump after 7+ days without npm publish
+## 0.8.2 - 2026-09-27
+- chore: periodic patch bump after 7+ days without npm publish
+## 0.8.1 - 2026-09-27
+- chore: periodic patch bump after 7+ days without npm publish
+All notable changes to this project will be documented in this file.
+This project follows semantic versioning.
+## [0.8.6] - 2026-09-30
+### Changed
+- Update `@earendil-works/pi-*` dependencies to `0.99.1`.
+## [Unreleased]
+### Added
+- Regression tests for exhausted `iteration_cap` pre-check behavior in `runContinuous`, malformed unreadable active-run manifests in `loadActiveRun`/`loadMostRecentTerminalRun`, recovery via `createIdleRun`, and `/baton:status` terminal-fallback messaging for iteration-cap failures.
+## [0.8.0] - 2026-09-14
+### Added
+- `/baton:history` lists recent completed or failed Baton runs from persisted `.pi/baton/runs/` manifests, with bounded scan/output limits, skip diagnostics for unreadable manifests, and tests for empty, single, multi-run, exclusion, scan-cap ordering, and command registration cases.
+- `/baton:status` and `formatStatusSummary` now include the stored `failure` reason for terminal failed runs, with status tests covering iteration-cap exhaustion and other failure paths.
+### Changed
+- README quick start and `docs/workflows.md` now document when to use `/baton:history` versus `/baton:status`, including the terminal-run fallback behavior for status.
+- README quick start and `docs/workflows.md` now document that `/baton:status` falls back to the most recent finished run when no active run exists.
+- Refreshed ROADMAP.md: marked S-109 done, updated release direction for 0.8.0/0.9.0, and added maintenance seed candidates S-110 through S-113 for the weekly seed planner.
+- Updated ROADMAP.md to mark S-108 done and refresh the security status table after the two-stage review gauntlet shipped in 0.7.5.
+- Aligned ROADMAP S-109 status with the shipped `docs/workflows.md` authoring guide.
+## [0.7.5] - 2026-08-22
+### Changed
+- Merge the 2026-08-22 managed OSS dependency and maintenance PR batch.
+### Added
+- Added the builtin `Two-Stage Review Gauntlet` workflow to demonstrate a non-default two-stage review graph.
+### Changed
+- Bump package version to `0.7.3` for the next patch release.
+- Bumped Pi dev toolchain packages to clear the transitive `protobufjs` audit advisory; the remaining `brace-expansion` finding is documented as upstream-blocked by `@earendil-works/pi-coding-agent`'s published shrinkwrap.
+- Removed unused `clearActiveRunPointer` export from `lib/run-store.ts` (dead code with no callers; `loadActiveRun` / `loadMostRecentTerminalRun` already treat a missing `runId` as no active pointer).
+## [0.7.2] - 2026-07-04
+### Added
+- `/baton:status` now shows the most recent finished run summary (state, last step, iteration, run directory) after a run reaches `completed` or `failed`, with clear finished-run framing instead of the no-active-run message.
+- Buy Me a Coffee sponsor button in README and native GitHub funding link via `.github/FUNDING.yml`.
+### Changed
+- Merged Dependabot PR #14: bump `@earendil-works/pi-ai` devDependency from 0.78.1 to 0.80.2 (type-check clean, 57/57 tests passing).
+- Removed leftover template scaffolding (`prompts/`, `themes/`, `skills/`).
+- Deleted stale template bootstrap docs (`docs/examples.md`, `docs/github-template.md`, `docs/repository-settings.md`, `docs/typescript.md`, `docs/template-checklist.md`) that shipped to npm consumers describing non-existent commands.
+- Updated ROADMAP.md to reflect current version (0.7.2), test count (57), and seed completion status for S-101, S-102, S-103, S-105.
+## [0.7.1] - 2026-06-27
+### Changed
+- README aligned to the current Pi extension template: added `Features`, `Release`, `Security`, and `Links` sections; expanded install flows (`npm`, GitHub, project-local, and `pi -e`); and updated `Package contents` to match the published tarball.
+## [0.7.0] - 2026-06-25
+### Added
+- Command handler tests for `/baton:new`, `/baton:start`, `/baton:run`, and `/baton:status` covering scaffold creation, inline validation, active-run guard, and no-active-run messaging.
+- Handoff payload shape tests for implement, linear, and fix transitions.
+- Run-store tests for active-run visibility across idle, running, and terminal states.
+### Changed
+- Finalizes the shipped builtin `default-review-loop` workflow (`worker` / `reviewer` / `worker`) with full v1 command-surface test coverage.
+## [0.6.0] - 2026-06-25
+### Added
+- Structured step envelopes for every run step (`summary`, `rawOutputPath`, and review fields when applicable).
+- Step handoff payload carries `taskBrief`, prior `stepOutputSummary`, `rawOutputPath`, and run metadata between isolated steps.
+- Review contract enforcement: `reject` requires non-empty `findings`; `accept` requires `acceptanceNote`.
+- Builtin `default-review-loop` routes `fix` back to `review`; iteration cap stops infinite reject loops.
+- Step-level `model` override with placeholder and session-model fallback via `resolveStepModel`.
+### Changed
+- Expanded `run-engine` and `review-contract` tests for fix→review routing, model routing, envelope persistence, and contract violations.
+## [0.5.0] - 2026-06-23
+### Added
+- `/baton:run` continuous run engine executes the active idle run through isolated subagent steps to a terminal state.
+- Step records persist under `.pi/baton/runs/<run>/steps/` and raw outputs under `outputs/`.
+- Terminal run summaries report the failing step as `last step` when step execution fails.
+### Changed
+- Expanded `run-engine` tests for step/output persistence, state transitions, and failure `last step` reporting.
+## [0.4.0] - 2026-06-22
+### Added
+- `/baton:start` creates an idle run from workflow selection and a task brief without starting execution.
+- `/baton:status` reports workflow name, task brief, last/current step, run state, iteration count, and run directory.
+- Single active run guard blocks a second `/baton:start` and points users to `/baton:status` or `/baton:run`.
+- Run manifests persist under `.pi/baton/runs/` with an active-run pointer.
+- Expanded workflow schema validation tests covering required fields, linear `next` transitions, review `on_accept` / `on_reject` branches, and invalid YAML handling at discovery time.
+### Changed
+- Workflow selection display names continue to come from YAML `name`; invalid or incomplete workflow documents now fail with explicit validation errors during `/baton:start` and `/baton:run` discovery.
+## [0.3.0] - 2026-06-18
+### Added
+- `/baton:new` re-prompts for a workflow name when the derived filename collides with an existing scaffold.
+- Tests for lazy `.pi/baton/workflows/` creation and kebab-case filename derivation.
+### Changed
+- Workflow discovery keeps user-defined `.pi/baton/workflows/*.yaml` entries ahead of builtin package workflows in selection order.
+## [0.2.3] - 2026-06-13
+### Added
+- README header icon and packaged `assets/pi-baton-icon-512.png` branding asset.
+### Changed
+- `assets/` is now included in the published package.
+## [0.2.2] - 2026-06-13
+### Added
+- Live Baton run widget above the editor during `/baton:run`, showing workflow, brief, active step, agent, judgment, and step checklist.
+- Footer status line (`baton: implement`, `baton: review`, etc.) while a run is in progress.
+## [0.2.1] - 2026-06-13
+### Fixed
+- Ship builtin `worker` and `reviewer` subagent definitions so `default-review-loop` runs without pre-created `.pi/agents/` files.
+- Validate required workflow agents during `/baton:start` and `/baton:run` with clearer missing-agent errors.
+## [0.2.0] - 2026-06-13
+### Added
+- `/baton:new`, `/baton:start`, `/baton:run`, and `/baton:status` command surface.
+- Builtin `default-review-loop` workflow with `worker` / `reviewer` / `worker` agent mapping.
+- YAML workflow discovery, inline validation, scaffold generation, and run persistence under `.pi/baton/`.
+- Isolated subagent step execution with structured handoff, review contract enforcement, and per-step model routing.
+## [0.1.2] - 2026-06-04
+### Changed
+- README and `docs/template-checklist.md` now follow the Pi OSS minimal-docs policy: `docs/` is optional, with explicit post-generation cleanup for template bootstrap docs.
+- Template bootstrap docs (`github-template.md`, `repository-settings.md`, `typescript.md`) are labeled for delete-or-merge after setup.
+## [0.1.1] - 2026-06-01
+### Changed
+- Publish workflow now supports npm publishing on merged package version bumps in addition to tags, releases, and manual dispatch.
+- Publish workflow now installs a current npm CLI so npm Trusted Publishing OIDC is supported.
+- CI and publish workflow commands no longer include literal trailing `\\n` text.
+## [0.1.0] - YYYY-MM-DD
+### Added
+- Initial Pi package template.
+- Example extension, Agent Skill, prompt, and theme.
+- CI and npm Trusted Publishing workflow.

package/README.md CHANGED Viewed

@@ -1,184 +1,184 @@
-# Pi Baton
-[![Join dotfield.xyz on Discord](https://img.shields.io/badge/Join%20dotfield.xyz%20on%20Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/4945dXZVW5)
-<p align="center">
-  <img src="./assets/pi-baton-icon-512.png" alt="Pi Baton icon" width="192" height="192" />
-</p>
-[![CI](https://github.com/eiei114/pi-baton/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-baton/actions/workflows/ci.yml)
-[![Publish](https://github.com/eiei114/pi-baton/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-baton/actions/workflows/publish.yml)
-[![npm version](https://img.shields.io/npm/v/pi-baton.svg)](https://www.npmjs.com/package/pi-baton)
-[![npm downloads](https://img.shields.io/npm/dm/pi-baton.svg)](https://www.npmjs.com/package/pi-baton)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
-[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
-<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
-> Run YAML-defined review loops in Pi with per-step model switching and isolated step context.
-## What this is
-Pi Baton is a Pi-native workflow baton runner. Define `implement → review → fix` loops in YAML, and let Pi Baton execute them with automatic baton handoff between isolated subagent steps.
-## Features
-- **Per-step model switching** — fast model for implement, strong model for review
-- **Isolated step context** — no shared conversation pollution between steps
-- **Structured review contract** — `accept`/`reject` with mandatory findings or acceptance notes
-- **Live progress widget** — see which step is running, its agent, and judgment in real time
-## Install
-Install the published npm package with Pi:
-```bash
-pi install npm:pi-baton
-```
-Pin a specific version when you want reproducible installs:
-```bash
-pi install npm:pi-baton@0.8.0
-```
-Install into the current project instead of your user Pi settings:
-```bash
-pi install npm:pi-baton -l
-```
-Or install from GitHub:
-```bash
-pi install git:github.com/eiei114/pi-baton
-```
-Try it without permanently installing:
-```bash
-pi -e npm:pi-baton
-```
-## Quick start
-Try this package locally from a clone of this repository:
-```bash
-pi -e .
-```
-Then run:
-```txt
-/baton:new        create a workflow scaffold
-/baton:start      choose workflow + task brief → idle run
-/baton:run        execute run to terminal state (with live widget)
-/baton:status     show the active run summary, or the most recent finished run
-/baton:history    list recent completed or failed runs from persisted history
-```
-Use `/baton:status` for the active run or the single most recent finished run. Use `/baton:history` when you need a short list of recent completed or failed runs and their `.pi/baton/runs/<id>` directories.
-Builtin workflows work out of the box — no agent setup required:
-- `Default Review Loop` (`implement → review → fix`)
-- `Two-Stage Review Gauntlet` (`draft → technical_review → editorial_review`, with rejects routed through `fix`)
-## Prerequisites
-Pi Baton ships builtin `worker` and `reviewer` subagents under `agents/`. They work with your current Pi model.
-To override with custom agents, place `.md` files under:
-```
-.pi/agents/worker.md
-.pi/agents/reviewer.md
-```
-Discovery order: project `.pi/agents/` → user `~/.pi/agent/agents/` → pi-baton builtin.
-## Workflow authoring
-See [`docs/workflows.md`](docs/workflows.md) for an end-to-end walkthrough: step kinds, transitions, the review contract, `iteration_cap`, model overrides, and agent discovery order.
-```txt
-/baton:new
-```
-Pick a name and a scaffold from `default-review-loop` is written to `.pi/baton/workflows/` and opened in editor. The scaffold includes `<your-fast-model>` / `<your-strong-model>` placeholders for step-level model overrides.
-The shipped `workflows/` directory also includes `two-stage-review-gauntlet.yaml`, a second builtin graph that demonstrates chaining two review gates before completion.
-### Workflow YAML reference
-```yaml
-name: My Review Loop
-iteration_cap: 5
-steps:
-  implement:
-    agent: worker
-    model: openai/gpt-5.4        # optional: fast model
-    prompt: work prompt
-    next: review
-  review:
-    agent: reviewer
-    model: anthropic/claude-opus-4-5  # optional: strong model
-    prompt: review prompt
-    on_accept: _complete         # or a step name
-    on_reject: fix
-  fix:
-    agent: worker
-    model: openai/gpt-5.4
-    prompt: fix prompt
-    next: review
-```
-- `on_accept: _complete` ends the run.
-- `iteration_cap` prevents infinite review loops — the run fails at the cap.
-- Review agents must return `accept`/`reject` with findings or acceptance notes.
-## Package contents
-| Path | Purpose |
-|---|---|
-| `extensions/` | Slash-command entrypoints (`/baton:new`, `/baton:start`, `/baton:run`, `/baton:status`, `/baton:history`) |
-| `lib/` | Workflow parser, run engine, subagent runner, review contract, UI widget |
-| `agents/` | Builtin `worker` and `reviewer` subagent definitions |
-| `workflows/` | Builtin workflows (`default-review-loop.yaml`, `two-stage-review-gauntlet.yaml`) |
-| `assets/` | README / package branding assets |
-| `docs/` | Workflow authoring guide, release and maintainer documentation |
-## Development
-```bash
-npm install
-npm run ci
-```
-## Release
-This package uses npm Trusted Publishing with GitHub Actions OIDC — no `NPM_TOKEN` is required.
-```bash
-npm version patch
-git push
-```
-On `main`, version bumps trigger auto-release and publish workflows. See [`docs/release.md`](docs/release.md) for setup details.
-## Security
-Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.
-For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
-## Links
-- npm: https://www.npmjs.com/package/pi-baton
-- GitHub: https://github.com/eiei114/pi-baton
-- Issues: https://github.com/eiei114/pi-baton/issues
-## License
-MIT
+# Pi Baton
+[![Join dotfield.xyz on Discord](https://img.shields.io/badge/Join%20dotfield.xyz%20on%20Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/4945dXZVW5)
+<p align="center">
+  <img src="./assets/pi-baton-icon-512.png" alt="Pi Baton icon" width="192" height="192" />
+</p>
+[![CI](https://github.com/eiei114/pi-baton/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-baton/actions/workflows/ci.yml)
+[![Publish](https://github.com/eiei114/pi-baton/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-baton/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/pi-baton.svg)](https://www.npmjs.com/package/pi-baton)
+[![npm downloads](https://img.shields.io/npm/dm/pi-baton.svg)](https://www.npmjs.com/package/pi-baton)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
+[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
+<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
+> Run YAML-defined review loops in Pi with per-step model switching and isolated step context.
+## What this is
+Pi Baton is a Pi-native workflow baton runner. Define `implement → review → fix` loops in YAML, and let Pi Baton execute them with automatic baton handoff between isolated subagent steps.
+## Features
+- **Per-step model switching** — fast model for implement, strong model for review
+- **Isolated step context** — no shared conversation pollution between steps
+- **Structured review contract** — `accept`/`reject` with mandatory findings or acceptance notes
+- **Live progress widget** — see which step is running, its agent, and judgment in real time
+## Install
+Install the published npm package with Pi:
+```bash
+pi install npm:pi-baton
+```
+Pin a specific version when you want reproducible installs:
+```bash
+pi install npm:pi-baton@0.8.6
+```
+Install into the current project instead of your user Pi settings:
+```bash
+pi install npm:pi-baton -l
+```
+Or install from GitHub:
+```bash
+pi install git:github.com/eiei114/pi-baton
+```
+Try it without permanently installing:
+```bash
+pi -e npm:pi-baton
+```
+## Quick start
+Try this package locally from a clone of this repository:
+```bash
+pi -e .
+```
+Then run:
+```txt
+/baton:new        create a workflow scaffold
+/baton:start      choose workflow + task brief → idle run
+/baton:run        execute run to terminal state (with live widget)
+/baton:status     show the active run summary, or the most recent finished run
+/baton:history    list recent completed or failed runs from persisted history
+```
+Use `/baton:status` for the active run or the single most recent finished run. Use `/baton:history` when you need a short list of recent completed or failed runs and their `.pi/baton/runs/<id>` directories.
+Builtin workflows work out of the box — no agent setup required:
+- `Default Review Loop` (`implement → review → fix`)
+- `Two-Stage Review Gauntlet` (`draft → technical_review → editorial_review`, with rejects routed through `fix`)
+## Prerequisites
+Pi Baton ships builtin `worker` and `reviewer` subagents under `agents/`. They work with your current Pi model.
+To override with custom agents, place `.md` files under:
+```
+.pi/agents/worker.md
+.pi/agents/reviewer.md
+```
+Discovery order: project `.pi/agents/` → user `~/.pi/agent/agents/` → pi-baton builtin.
+## Workflow authoring
+See [`docs/workflows.md`](docs/workflows.md) for an end-to-end walkthrough: step kinds, transitions, the review contract, `iteration_cap`, model overrides, and agent discovery order.
+```txt
+/baton:new
+```
+Pick a name and a scaffold from `default-review-loop` is written to `.pi/baton/workflows/` and opened in editor. The scaffold includes `<your-fast-model>` / `<your-strong-model>` placeholders for step-level model overrides.
+The shipped `workflows/` directory also includes `two-stage-review-gauntlet.yaml`, a second builtin graph that demonstrates chaining two review gates before completion.
+### Workflow YAML reference
+```yaml
+name: My Review Loop
+iteration_cap: 5
+steps:
+  implement:
+    agent: worker
+    model: openai/gpt-5.4        # optional: fast model
+    prompt: work prompt
+    next: review
+  review:
+    agent: reviewer
+    model: anthropic/claude-opus-4-5  # optional: strong model
+    prompt: review prompt
+    on_accept: _complete         # or a step name
+    on_reject: fix
+  fix:
+    agent: worker
+    model: openai/gpt-5.4
+    prompt: fix prompt
+    next: review
+```
+- `on_accept: _complete` ends the run.
+- `iteration_cap` prevents infinite review loops — the run fails at the cap.
+- Review agents must return `accept`/`reject` with findings or acceptance notes.
+## Package contents
+| Path | Purpose |
+|---|---|
+| `extensions/` | Slash-command entrypoints (`/baton:new`, `/baton:start`, `/baton:run`, `/baton:status`, `/baton:history`) |
+| `lib/` | Workflow parser, run engine, subagent runner, review contract, UI widget |
+| `agents/` | Builtin `worker` and `reviewer` subagent definitions |
+| `workflows/` | Builtin workflows (`default-review-loop.yaml`, `two-stage-review-gauntlet.yaml`) |
+| `assets/` | README / package branding assets |
+| `docs/` | Workflow authoring guide, release and maintainer documentation |
+## Development
+```bash
+npm install
+npm run ci
+```
+## Release
+This package uses npm Trusted Publishing with GitHub Actions OIDC — no `NPM_TOKEN` is required.
+```bash
+npm version patch
+git push
+```
+On `main`, version bumps trigger auto-release and publish workflows. See [`docs/release.md`](docs/release.md) for setup details.
+## Security
+Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.
+For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
+## Links
+- npm: https://www.npmjs.com/package/pi-baton
+- GitHub: https://github.com/eiei114/pi-baton
+- Issues: https://github.com/eiei114/pi-baton/issues
+## License
+MIT

package/lib/run-store.ts CHANGED Viewed

@@ -134,22 +134,33 @@ export async function loadTerminalRunHistory(
     .sort(compareRunIdsNewestFirst)
     .slice(0, TERMINAL_HISTORY_MAX_SCAN);
+  const scanResults = await Promise.all(
+    runIds.map(async (runId) => {
+      try {
+        const manifest = await readJson<unknown>(getRunManifestPath(cwd, runId));
+        if (!isCompleteManifest(manifest)) {
+          return { kind: "skipped" as const };
+        }
+        if (!isTerminalRunState(manifest.state)) {
+          return { kind: "non-terminal" as const };
+        }
+        return { kind: "terminal" as const, manifest };
+      } catch {
+        return { kind: "skipped" as const };
+      }
+    }),
+  );
   const terminalRuns: RunManifest[] = [];
   let skippedCount = 0;
-  for (const runId of runIds) {
-    try {
-      const manifest = await readJson<unknown>(getRunManifestPath(cwd, runId));
-      if (!isCompleteManifest(manifest)) {
-        skippedCount++;
-        continue;
-      }
-      if (!isTerminalRunState(manifest.state)) {
-        continue;
-      }
-      terminalRuns.push(manifest);
-    } catch {
+  for (const result of scanResults) {
+    if (result.kind === "skipped") {
       skippedCount++;
+      continue;
+    }
+    if (result.kind === "terminal") {
+      terminalRuns.push(result.manifest);
     }
   }

package/lib/workflow-discovery.ts CHANGED Viewed

@@ -15,48 +15,90 @@ async function listYamlFiles(dir: string): Promise<string[]> {
   }
 }
+async function loadWorkflowItems(
+  filePaths: string[],
+  source: "user" | "builtin",
+): Promise<WorkflowListItem[]> {
+  return Promise.all(
+    filePaths.map(async (filePath) => {
+      const yamlText = await readFile(filePath, "utf8");
+      const id = basename(filePath, ".yaml");
+      const workflow = parseWorkflowDocument(yamlText, { id, source, path: filePath });
+      return { id, name: workflow.name, source, path: filePath };
+    }),
+  );
+}
 export async function discoverWorkflowItems(cwd: string): Promise<WorkflowListItem[]> {
-  const userFiles = await listYamlFiles(getWorkflowsDir(cwd));
-  const builtinFiles = await listYamlFiles(getPackageWorkflowsDir());
-  const userItems: WorkflowListItem[] = [];
-  for (const filePath of userFiles) {
-    const yamlText = await readFile(filePath, "utf8");
-    const id = basename(filePath, ".yaml");
-    const workflow = parseWorkflowDocument(yamlText, { id, source: "user", path: filePath });
-    userItems.push({ id, name: workflow.name, source: "user", path: filePath });
-  }
+  const [userFiles, builtinFiles] = await Promise.all([
+    listYamlFiles(getWorkflowsDir(cwd)),
+    listYamlFiles(getPackageWorkflowsDir()),
+  ]);
-  const builtinItems: WorkflowListItem[] = [];
-  for (const filePath of builtinFiles) {
-    const yamlText = await readFile(filePath, "utf8");
-    const id = basename(filePath, ".yaml");
-    const workflow = parseWorkflowDocument(yamlText, { id, source: "builtin", path: filePath });
-    builtinItems.push({ id, name: workflow.name, source: "builtin", path: filePath });
-  }
+  const [userItems, builtinItems] = await Promise.all([
+    loadWorkflowItems(userFiles, "user"),
+    loadWorkflowItems(builtinFiles, "builtin"),
+  ]);
   return [...userItems, ...builtinItems];
 }
+function isMissingFileError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+async function loadWorkflowFile(
+  filePath: string,
+  options: { id: string; source: "user" | "builtin" },
+): Promise<WorkflowDefinition> {
+  const yamlText = await readFile(filePath, "utf8");
+  return parseWorkflowDocument(yamlText, { ...options, path: filePath });
+}
+const UNSAFE_WORKFLOW_ID_PATTERN = /[\\/\0]/;
+function isSafeWorkflowId(workflowId: string): boolean {
+  return (
+    workflowId.length > 0 &&
+    workflowId !== "." &&
+    workflowId !== ".." &&
+    !UNSAFE_WORKFLOW_ID_PATTERN.test(workflowId)
+  );
+}
 export async function loadWorkflowById(cwd: string, workflowId: string): Promise<WorkflowDefinition> {
-  const items = await discoverWorkflowItems(cwd);
-  const match = items.find((item) => item.id === workflowId);
-  if (!match) {
+  // The direct lookup builds a path from the id, so ids that could escape the
+  // workflow directories are rejected before any read is attempted.
+  if (!isSafeWorkflowId(workflowId)) {
     throw new Error(`Unknown workflow: ${workflowId}`);
   }
-  const yamlText = await readFile(match.path, "utf8");
-  return parseWorkflowDocument(yamlText, {
-    id: match.id,
-    source: match.source,
-    path: match.path,
-  });
+  const candidates = [
+    { path: join(getWorkflowsDir(cwd), `${workflowId}.yaml`), source: "user" as const },
+    { path: join(getPackageWorkflowsDir(), `${workflowId}.yaml`), source: "builtin" as const },
+  ];
+  for (const candidate of candidates) {
+    try {
+      return await loadWorkflowFile(candidate.path, { id: workflowId, source: candidate.source });
+    } catch (error) {
+      if (!isMissingFileError(error)) {
+        throw error;
+      }
+    }
+  }
+  throw new Error(`Unknown workflow: ${workflowId}`);
 }
 export async function loadWorkflowFromPath(
   filePath: string,
   options: { id: string; source: "user" | "builtin" },
 ): Promise<WorkflowDefinition> {
-  const yamlText = await readFile(filePath, "utf8");
-  return parseWorkflowDocument(yamlText, { ...options, path: filePath });
+  return loadWorkflowFile(filePath, options);
 }

package/package.json CHANGED Viewed

@@ -1,67 +1,67 @@
-{
-  "name": "pi-baton",
-  "version": "0.8.0",
-  "description": "Pi-native workflow baton runner with per-step model switching and isolated step context.",
-  "type": "module",
-  "engines": {
-    "node": ">=22.6.0"
-  },
-  "license": "MIT",
-  "author": "eiei114",
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "workflow",
-    "review-loop",
-    "typescript"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/eiei114/pi-baton.git"
-  },
-  "bugs": {
-    "url": "https://github.com/eiei114/pi-baton/issues"
-  },
-  "homepage": "https://github.com/eiei114/pi-baton#readme",
-  "files": [
-    "assets/",
-    "extensions/",
-    "lib/",
-    "agents/",
-    "workflows/",
-    "docs/",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "node --test tests/*.test.mjs",
-    "ci": "npm run typecheck && npm test && npm run pack:check",
-    "pack:check": "npm pack --dry-run"
-  },
-  "pi": {
-    "extensions": [
-      "./extensions"
-    ]
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "yaml": "^2.9.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "typebox": "latest",
-    "@types/node": "^26.0.1",
-    "typescript": "^7.0.2"
-  }
-}
+{
+  "name": "pi-baton",
+  "version": "0.8.6",
+  "description": "Pi-native workflow baton runner with per-step model switching and isolated step context.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "license": "MIT",
+  "author": "eiei114",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "workflow",
+    "review-loop",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-baton.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-baton/issues"
+  },
+  "homepage": "https://github.com/eiei114/pi-baton#readme",
+  "files": [
+    "assets/",
+    "extensions/",
+    "lib/",
+    "agents/",
+    "workflows/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/*.test.mjs",
+    "ci": "npm run typecheck && npm test && npm run pack:check",
+    "pack:check": "npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.99.1",
+    "@earendil-works/pi-coding-agent": "^0.99.1",
+    "typebox": "latest",
+    "@types/node": "^26.0.1",
+    "typescript": "^7.0.2"
+  }
+}