@osolmaz/pi-workflows 0.12.1 → 0.13.0

package/docs/live-replay-protocol.md

@@ -1,18 +1,18 @@
 # Live replay protocol
 
-The Rust viewer (`tui/`) can watch runs in two ways: by reading run bundles
+The Rust viewer (`tui/`) can watch runs in two ways: by reading SQLite runs
 directly from the filesystem (the default, in-process) or by connecting to a
 `piw serve` WebSocket server. Both paths produce the same semantic state; the
 protocol below is the network form of that state. Protocol id:
 `pi-workflows.replay.v1`.
 
-The server is a reader like any other: it only consumes run bundles (see
-[run-bundles.md](run-bundles.md)) and never writes them. The protocol has no
+The server is a reader like any other: it only consumes SQLite runs (see
+[SQLITE_STATE.md](SQLITE_STATE.md)) and never writes them. The protocol has no
 authentication, so the server only accepts loopback bind addresses and refuses
-to start on anything else; bundles contain private data, and remote viewing
+to start on anything else; workflow state contains private data, and remote viewing
 goes through an SSH tunnel. Handshakes that
 carry an `Origin` header are rejected: browsers always send one, and a web
-page must not be able to read bundles by opening a WebSocket to localhost.
+page must not be able to read workflow state by opening a WebSocket to localhost.
 
 ## Transport and framing
 
@@ -49,18 +49,15 @@ run:
 }
 ```
 
-- `manifest`, `workflow`, `state`, `events`, and every `session` field are the
-  bundle documents verbatim. `workflow` is the definition snapshot,
-  top-level `events` are parsed workflow trace lines, `session.entries` are
-  settled Pi entries, `session.events` are normalized temporal events, and
-  `session.capture` is capture integrity. `session.eventsMalformed` and
-  `session.eventsTornTail` are derived transport diagnostics from the live
-  tailer, not bundle documents. `session` is `null` until a binding exists.
-- `live` is true while the run status is non-terminal and the bundle is still
-  growing. `possiblyInterrupted` is true when the status is `running` but the
-  bundle has not changed for 60 seconds.
-- Artifact references inside the view stay references; contents are fetched
-  on demand.
+- `manifest`, `workflow`, `state`, `events`, and every `session` field are
+  semantic projections from SQLite. `workflow` is the definition snapshot,
+  top-level `events` are workflow events, `session.entries` are settled Pi
+  entries, `session.events` are normalized temporal events, and
+  `session.capture` is capture integrity. `session` is `null` until a binding
+  exists.
+- `live` is true while the run status is non-terminal. `possiblyInterrupted`
+  is a reader-side diagnostic based on current ownership and update time.
+- Values are resolved from content-addressed SQLite blobs.
 
 Because the full trace and session history are part of the view, replay
 scrubbing is a pure client-side operation; rewinding never requires the
@@ -106,7 +103,7 @@ Client to server:
 | `watch_runs`     | —               | subscribe to the run listing |
 | `watch_run`      | `runId`         | subscribe to one run's view  |
 | `unwatch_run`    | `runId`         | end a run subscription       |
-| `fetch_artifact` | `runId`, `path` | request artifact contents    |
+| `fetch_artifact` | `runId`, `path` | unsupported; returns `error` |
 
 Server to client:
 
@@ -116,13 +113,11 @@ Server to client:
 | `runs`         | `runs`                       | full run listing (summaries), re-sent on change |
 | `run_snapshot` | `runId`, `revision`, `view`  | full view after subscribe                       |
 | `run_patch`    | `runId`, `revision`, `patch` | incremental view update                         |
-| `artifact`     | `runId`, `path`, `content`   | artifact contents (UTF-8)                       |
+| `artifact`     | `runId`, `path`, `content`   | reserved; not sent by SQLite-backed servers     |
 | `error`        | `message`, `runId?`          | request failed                                  |
 
-Artifact requests are answered only from files below the artifact directory
-declared by `manifest.paths.artifacts`. Paths outside that directory and
-symlinks whose canonical targets leave it are refused. Responses are capped at
-4 MiB of actual file size; anything else produces an `error`.
+SQLite-backed views contain resolved values. A `fetch_artifact` request returns
+an `error` because there is no artifact directory.
 
 Run listing summaries are the manifest plus `live` and
 `possiblyInterrupted`:
@@ -136,20 +131,16 @@ run views use patches.
 
 ## Reconnection
 
-The native client treats the run listing, selected run, and pending artifact
-reads as desired state rather than one-shot commands. After a connection closes,
+The native client treats the run listing and selected run as desired state rather
+than one-shot commands. After a connection closes,
 it keeps the cached run visible with a stale/reconnecting label, retries with
 bounded backoff, sends `watch_runs` after the next valid `hello`, and restores
 the current `watch_run`. A reconnect receives a fresh snapshot before later
-patches. Pending artifact reads are resubmitted once per connection.
-
-## Filesystem semantics behind the protocol
-
-The server watches the runs directory (inotify with polling fallback) and
-tails `trace.ndjson`, `session/entries.ndjson`, and `session/events.ndjson`
-incrementally. Torn final NDJSON lines are buffered until complete. The server
-also re-reads atomic `session/capture.json` changes. `state.json` and
-`manifest.json` are
-re-read on change; a `state.json` whose `traceSeq` is older than the last
-tailed trace event is stale and is replaced when the writer catches up. After
-a terminal status, watching stops.
+patches.
+
+## SQLite semantics behind the protocol
+
+The server polls `state.sqlite` through a query-only connection. Each refresh
+reads a committed run projection, immutable events, session rows, and blob
+values. A transaction is either fully visible or not visible, so a client never
+observes half of a state transition.

package/docs/plans/2026-08-16-workflow-updates-plan.md

@@ -355,7 +355,7 @@ Update:
 
 - `README.md`
 - `docs/workflows.md`
-- `docs/run-bundles.md`
+- `docs/SQLITE_STATE.md`
 - `docs/development.md`
 - `docs/WORKFLOW_UPDATES.md`
 - `docs/WORKFLOW_STEP_MESSAGES.md`

package/docs/plans/2026-08-19-human-decision-gates-plan.md

@@ -68,7 +68,7 @@ Pi and Telegram implement one channel interface. Workflows address a named audie
 ### Documentation and display
 
 - Add the authoring API to `docs/workflows.md`.
-- Add human decision state to `docs/run-bundles.md`.
+- Add human decision state to `docs/SQLITE_STATE.md`.
 - Add channel setup and recovery instructions.
 - Add a custom gate example and a composed plan approval example.
 - Show pending and accepted choices in TypeScript and Rust viewers.

package/docs/plans/2026-08-21-autoimplement-timeout-fallback-plan.md

@@ -153,7 +153,7 @@ A repeated node performs only missing work. It must not create a duplicate commi
 7. Route supported `timed_out` outcomes to the fallback. Preserve success, failure, and cancellation behavior.
 8. Update consequential-node prompts so repeated attempts inspect state and perform only missing work.
 9. Increment the built-in Autoimplement revision from 5 to 6 in `src/builtins/catalog.ts`.
-10. Update `docs/workflows.md` and `docs/run-bundles.md` when implementation ships so public documentation matches the code.
+10. Update `docs/workflows.md` and `docs/SQLITE_STATE.md` when implementation ships so public documentation matches the code.
 
 ## Alpha cutover
 

package/docs/plans/2026-08-21-plan-change-approval-policy-plan.md

@@ -238,7 +238,7 @@ When implementation ships, update:
 - `docs/WORKFLOW_COMPOSITION.md` for the shared plan-change workflow;
 - `docs/workflows.md` for the public API and Autoimplement behavior;
 - `docs/MONITOR.md` for repair-plan decisions;
-- `docs/run-bundles.md` for request, resolution, continuation, and snapshot fields;
+- `docs/SQLITE_STATE.md` for request, resolution, continuation, and snapshot fields;
 - Autoimplement and Monitor skill text and examples; and
 - package examples and generated layout fixtures affected by the graph change.
 

package/docs/plans/2026-08-21-sanity-check-plan.md

@@ -2,7 +2,8 @@
 title: Run Sanity Check with Provider Extensions
 author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
 date: 2026-08-21
-updated: 2026-08-22
+updated: 2026-08-23
+status: implemented
 ---
 
 # Run Sanity Check with Provider Extensions
@@ -19,9 +20,9 @@ The workflow keeps only the final bounded answer and safe operational facts. It
 
 The change is limited to Pi Workflows. It changes the private SDK agent-group runner, Sanity Check composition, extension admission, model runtime construction, tests, and canonical documentation.
 
-The workflow continues to use existing `action`, `compute`, and `notify` nodes. `src/workflows` and `WorkflowActionContext` remain Pi-independent. The change does not add a workflow primitive, public agent-group export, persisted schema, child workflow run, service, queue, store, transport, Pi core change, or private Pi API.
+The workflow uses existing `action`, `agent`, and `compute` nodes and includes the existing `plain-summary` workflow. `src/workflows` and `WorkflowActionContext` remain Pi-independent. The change does not add a workflow primitive, public agent-group export, persisted schema, child workflow run, service, queue, store, transport, Pi core change, or private Pi API.
 
-Sanity Check keeps its existing input, review areas, prompts, evidence rules, session counts, strict result validation, verdicts, final notification, and progress schema.
+Sanity Check keeps its existing input, review areas, child prompts, evidence rules, session counts, strict result validation, verdicts, and progress schema. After verification, it shows two ordered normal assistant responses: the full detailed report first, then a short plain-language summary.
 
 ## Child session contract
 
@@ -187,6 +188,14 @@ Updates are deduplicated, throttled, and observational. They cannot change agent
 
 The Pi widget shows the aggregate plus failed and active children within its ten-line limit. `piw` shows all durable child tracks and samples. Both views use existing progress records. No new persisted field or schema is added.
 
+## Ordered assistant reports
+
+After strict verification succeeds, an assistant-message `agent` shows the complete bounded report. Its prompt supplies the deterministic report and requires a verbatim response without tools. A mismatch stops before summary generation. This replaces the old final workflow notification.
+
+The graph then includes `plain-summary`. The summarizer receives the verified verdict and detailed report, keeps the verdict, and writes one short plain-language response. It uses the plain-summary workflow limits of 2,000 characters and five sentences. The detailed response always settles before the summary starts.
+
+Neither response uses `presentationPrompt`, and neither can change the verified verdict. A final compute node returns the original strict `SanityCheckResult` as the workflow result. Both visible responses and their normal assistant receipts use existing Pi session and SQLite records. A detached host parks before these session-visible nodes until the origin Pi session can continue them.
+
 ## Implementation plan
 
 1. Update the Pi SDK development baseline to one compatible 0.84.x release. Keep the Pi coding-agent, Pi AI, and Pi TUI packages aligned and set an honest peer compatibility floor. Do not add Pi Factory or a provider extension as a dependency.
@@ -198,17 +207,18 @@ The Pi widget shows the aggregate plus failed and active children within its ten
 7. Verify exact provider, model, thinking, authentication, admitted extensions, active tools, and tool sources before every prompt.
 8. Complete provider, extension, and session cleanup on every exit path.
 9. Pass the private profile and exact dispatch through Sanity Check without changing its review behavior or progress schema. Remove any `--no-extensions` launch guidance.
-10. Change the built-in Sanity Check revision from 2 to 3.
-11. Add temporary fixture extensions and full unit, integration, interactive Pi, and standalone host coverage.
-12. Update this plan and `docs/workflows.md` to match the shipped behavior.
-13. Run the complete repository gate and inspect the full public diff.
-14. After mock-provider verification, run one bounded real acceptance on OpenClaw pull request 126028 with `openai-codex/gpt-5.6-sol` and high thinking. Abort immediately if any child reports another provider or model. Do not modify OpenClaw.
+10. Add the ordered detailed assistant response and included plain summary, then return the original verified result from a final compute node.
+11. Change the built-in Sanity Check revision from 3 to 4 for the presentation graph change.
+12. Add temporary fixture extensions and full unit, integration, interactive Pi, and standalone host coverage.
+13. Update this plan and `docs/workflows.md` to match the shipped behavior.
+14. Run the complete repository gate and inspect the full public diff.
+15. After mock-provider verification of the provider architecture, run one bounded real acceptance on OpenClaw pull request 126028 with `openai-codex/gpt-5.6-sol` and high thinking. Abort immediately if any child reports another provider or model. Do not modify OpenClaw.
 
 ## Revision and compatibility
 
-Sanity Check moves from built-in revision 2 to revision 3.
+Sanity Check revision 3 introduced the provider-first child runtime. Revision 4 replaces the final notification with the ordered detailed and plain assistant responses.
 
-This is an alpha hard cutover. Do not retain the revision-2 child runtime, fallback, compatibility runner, migration, alias, dual path, or feature flag. An unfinished revision-2 run must fail with clear cancel-and-restart guidance. Terminal revision-2 bundles remain readable historical evidence because the persisted schema does not change.
+This is an alpha hard cutover. Do not retain the revision-3 notification graph, compatibility runner, migration, alias, dual path, or feature flag. An unfinished revision-3 run must fail with clear cancel-and-restart guidance. Terminal older runs remain readable historical evidence because the persisted schema does not change.
 
 ## Tests
 
@@ -231,8 +241,10 @@ Unit and integration tests must cover:
 - interactive Pi with normal extensions enabled and the local mock provider;
 - standalone `WorkflowHost` through the same private runtime path;
 - no child session files or child workflow runs;
-- built-in revision 3 and historical terminal bundle reading;
-- final notification without another model turn.
+- built-in revision 4 and historical terminal run reading;
+- one full detailed assistant response followed by one short plain-language assistant response;
+- unchanged strict final result after both visible responses;
+- no final notification or root presentation turn.
 
 Tests use mock providers and temporary directories. They do not call real models or write outside temporary directories.
 
@@ -251,7 +263,7 @@ After these checks and Pi Reviewer pass, perform the one explicitly authorized b
 
 The implementation is complete when:
 
-- `/workflow sanity-check` discovers built-in revision 3;
+- `/workflow sanity-check` discovers built-in revision 4;
 - the parent Pi process runs with its normal configured extensions;
 - serial mode uses two independent in-memory SDK sessions;
 - parallel mode uses five independent in-memory SDK sessions, with four reviews running concurrently;
@@ -263,14 +275,16 @@ The implementation is complete when:
 - the workflow keeps only bounded final answers and safe operational facts;
 - child prompts, reasoning, tool payloads, histories, credentials, and extension state do not enter run bundles or progress updates;
 - provider, extension, and session cleanup completes on every exit path;
-- Sanity Check review behavior, strict validation, verdicts, progress, and final notification remain unchanged;
-- interactive and headless runs use the same private SDK path;
+- Sanity Check review behavior, strict validation, verdicts, and progress remain unchanged;
+- the full detailed assistant response appears before the short plain-language summary;
+- the final workflow result remains the strict verified result;
+- interactive and headless runs use the same private SDK path, while session-visible reports wait for the origin Pi session;
 - all required checks pass with coverage margin;
 - the bounded acceptance run on OpenClaw pull request 126028 reports GPT-5.6 Sol for every child and completes with a strict verdict without modifying OpenClaw.
 
 ## Contract impact
 
-- **Origin session:** The normal workflow start record and one final workflow notification.
+- **Origin session:** The normal workflow start record, one detailed assistant response, and one short plain-language assistant response.
 - **Parent extensions:** The parent Pi process loads its normal configured extensions.
 - **Child extensions:** Only the exact provider owner and explicit private behavior paths are admitted.
 - **Child sessions:** Independent in-memory contexts and complete per-child runtimes in the same Node process. No child session file or child workflow run.

package/docs/plans/2026-08-22-goal-finishing-monitor-plan.md

@@ -0,0 +1,200 @@
+---
+title: Make Monitor finish authorized goals
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-22
+status: implemented
+---
+
+# Goal-finishing Monitor plan
+
+## Goal
+
+Change the built-in Monitor workflow so it finishes the user's authorized goal instead of only checking it.
+
+A request such as "resume this work and monitor it" must resume the work, prove that useful work is moving, and then check it on schedule. Monitor continues until the full goal is complete or cannot continue safely.
+
+The canonical behavior is specified in [Built-in monitor](../MONITOR.md).
+
+## Boundaries
+
+The implementation must:
+
+- preserve the full goal and authority from `task`, `stopWhen`, repository instructions, and the conversation
+- keep the first observation read-only
+- use normal Pi tools for observations and actions
+- keep only `task`, `stopWhen`, `everyMinutes`, and `maxChecks` as public inputs
+- reject unknown input fields before run creation
+- keep target processes and systems independent of Pi Workflows
+- use the existing plan-change and Autoimplement workflows for real repairs
+- keep normal starts, resumes, and restarts direct and small
+- stop before an action exceeds authority, cost, provider, runtime, credential, or safety limits
+- stop paid workers before repairing a shared code or data defect
+- avoid compatibility aliases or shims for removed alpha inputs and routes
+
+The work may change the Pi Workflows source, Monitor tests, the Monitor skill, and relevant documentation. It may run local checks and the non-destructive real-Pi end-to-end suite. It may commit and push the verified change directly to `origin/main`.
+
+The work must not:
+
+- add a target-specific Pi API, transport, schema, store, file, command, service, or dependency
+- copy the planning, documentation, implementation, review, or delivery logic from existing workflows
+- open a pull request
+- deploy, publish an npm package, or create a release
+- change OnurPi or another repository
+
+## Selected design
+
+### Strict input
+
+Replace the Monitor input parser with strict validation for:
+
+- `task`
+- `stopWhen`
+- `everyMinutes`
+- `maxChecks`
+
+Keep the full goal, scope, authority, constraints, and recovery contract in `task` instead of adding process-specific or provider-specific fields. Reject all other fields with a direct unsupported-field error.
+
+### Read-only observation
+
+Replace the current check result with a read-only observation result. Its route is one of:
+
+- `wait`: Work is moving, or an external event must finish.
+- `act`: The goal is incomplete and a safe authorized action is available.
+- `stop`: The goal is complete or cannot continue safely.
+
+The observation records goal state and target work state separately. It includes factual evidence, the safe actions already authorized by the user, optional progress, a stable target-state ID, and a concise report.
+
+An `act` result also includes:
+
+- action kind: `advance`, `recover`, or `repair`
+- what is incomplete
+- evidence that proves it
+- the exact next action
+- why existing authority covers it
+- files, systems, and resources it may change
+- how to verify it
+- a stable failure ID
+
+The observation cannot grant new authority.
+
+### Direct action step
+
+Add one mutation-capable agent step that uses normal Pi tools. It performs only the action stated by the observation.
+
+Route `advance` and `recover` directly to this step. These actions cover normal starts, resumes, restarts, next commands, launch-file refreshes, safe retries, and verified checkpoint continuation. They do not run planning or documentation workflows.
+
+The step returns a factual success, failure, or blocked result with verification evidence.
+
+### Existing repair path
+
+Route `repair` through the existing shared plan-change workflow and Autoimplement workflow. Pass the observed defect, evidence, repository, authority, constraints, and delivery boundaries into those workflows.
+
+Do not copy or replace their design, documentation, approval, implementation, test, review, or delivery behavior.
+
+Stop affected paid workers at safe boundaries before repairing a shared code or data defect.
+
+### Immediate verification
+
+Run a new read-only observation immediately after every direct action or completed repair. Do not schedule or sleep first.
+
+The immediate observation must establish one of these states:
+
+- the goal is complete
+- useful work is moving
+- the action failed in a new way
+- the same failure returned
+- a blocker exists
+
+Only the `wait` route can publish the next schedule and enter the timer.
+
+### Repeated failure guard
+
+Store stable failure and target-state IDs in accepted outputs. After one repair completes, compare the next observation with prior repaired failures.
+
+If the same failure ID and target-state ID return, stop. Do not run the same repair cycle again.
+
+A failed direct action can produce a new `recover` action when the new observation proves that recovery is authorized. All loops remain bounded by accepted observations and the Monitor safety limit.
+
+### Reports
+
+Format every observation report with separate facts for:
+
+- Monitor state
+- goal state
+- target work state
+- factual progress when available
+- last action or next action
+- next check when scheduled
+
+Never report target work as running only because Monitor is active.
+
+### Workflow graph
+
+```text
+observe
+  ├─ stop → finish
+  ├─ wait → report → schedule → sleep → observe
+  └─ act
+       ├─ advance → direct action → observe immediately
+       ├─ recover → direct action → observe immediately
+       └─ repair → plan change → Autoimplement → observe immediately
+```
+
+The timer belongs only on the `wait` path.
+
+## Implementation steps
+
+1. Replace Monitor's public input parser with strict validation for `task`, `stopWhen`, `everyMinutes`, and `maxChecks` only.
+2. Replace `continue`, `repair`, and `stop` observation routes with `wait`, `act`, and `stop`.
+3. Add structured goal state, work state, evidence, progress, stable IDs, and complete action details to observation output validation.
+4. Add the direct mutation-capable action step for `advance` and `recover`.
+5. Keep the existing shared plan-change and Autoimplement includes for `repair`.
+6. Route every action result directly back to read-only observation.
+7. Route only `wait` through report, schedule, sleep, and the next observation.
+8. Add the repeated repaired-failure guard using stable failure and target-state IDs.
+9. Update report formatting so Monitor, goal, and target work states remain separate.
+10. Update the Monitor skill and workflow documentation for the new graph and simple input contract.
+11. Replace and extend Monitor tests for the new behavior.
+12. Run all required checks, review the diff, commit, and push directly to `origin/main`.
+
+## Tests
+
+Add tests for these cases:
+
+1. The goal is already complete.
+2. Work is active, so Monitor waits.
+3. Work is idle, so Monitor starts it.
+4. Saved work exists, so Monitor resumes it.
+5. An action succeeds, so Monitor observes again immediately.
+6. An action fails once, then recovery succeeds.
+7. The same repaired failure returns, so Monitor stops.
+8. An action is outside authority, so Monitor stops.
+9. A paid action exceeds the limit, so Monitor does not launch it.
+10. Monitor is active while the target is idle.
+11. The target completes between timed observations.
+12. Unknown input fields fail clearly before run creation.
+13. A normal restart does not trigger planning or documentation.
+14. A real code defect uses the existing repair path.
+15. No target-specific monitoring API is required.
+
+Keep applicable existing tests for progress, reports, notifications, schedule updates, safety limits, cancellation, interruption, resume, and the widget.
+
+## Verification
+
+Run:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+git diff --check
+```
+
+Review the full diff and fix each valid issue before delivery.
+
+## Delivery
+
+Commit the verified change with a Conventional Commit message and push it directly to `origin/main` without a pull request.
+
+Do not deploy, publish, or create a release.