@osolmaz/pi-workflows 0.11.2 → 0.12.0

package/docs/DEFERRED_TURNS.md

@@ -0,0 +1,298 @@
+# Deferred workflow turns
+
+This specification defines how Pi Workflows schedules one successor agent turn after a workflow event stops or strands the current turn. It covers cancellation, timeout, terminal failure, launch failure, controller interruption, and claim loss.
+
+The implementation plan is [Guarantee one successor turn after workflow interruption](plans/2026-08-21-deferred-turn-intents-plan.md).
+
+## Terms
+
+- **Source event:** The workflow event that creates the need for another turn.
+- **Turn intent:** The durable obligation to send one successor turn.
+- **Natural successor:** The next workflow agent prompt or result presentation.
+- **Fallback:** A factual model-facing message sent when no natural successor remains.
+- **Resolution:** The recorded fact that one message path satisfied the intent.
+- **Target session:** The Pi session that owns the successor turn.
+
+## Core rule
+
+Each eligible source event creates at most one turn intent. Exactly one of these message paths can resolve it:
+
+1. a workflow agent prompt;
+2. a completed or waiting result presentation;
+3. a factual fallback.
+
+All three paths claim the same intent before sending. A resolved intent cannot start another turn.
+
+Cancellation and process termination remain immediate. Pi Workflows does not keep the old assistant turn alive and does not wait for the successor before stopping active work.
+
+## Intent lifecycle
+
+An intent has two stored states:
+
+| State    | Condition                                                     | Meaning                                                   |
+| -------- | ------------------------------------------------------------- | --------------------------------------------------------- |
+| Pending  | `resolvedAt` is null                                          | No message path has resolved the intent.                  |
+| Resolved | `resolvedAt`, `resolution`, and `resolutionMessageId` are set | One message path was sent or found in the session branch. |
+
+Pending intents have separate fallback eligibility:
+
+| Eligibility | Condition            | Meaning                                                          |
+| ----------- | -------------------- | ---------------------------------------------------------------- |
+| Ineligible  | `eligibleAt` is null | A natural workflow prompt or presentation can still arrive.      |
+| Eligible    | `eligibleAt` is set  | Durable state shows that no immediate natural successor remains. |
+
+A claim is temporary coordination state. A claim does not resolve an intent. An expired claim can be acquired again.
+
+Valid resolutions are:
+
+```text
+workflowPrompt | presentation | fallback
+```
+
+Resolution records message delivery into the Pi session or the presence of the same message in the session branch. It does not prove that a model turn started or completed.
+
+## Source events
+
+Valid causes are:
+
+```text
+agentCancelled | timedOut | failed | launchFailed | controllerInterrupted | claimLost
+```
+
+The event policy is:
+
+| Event                                                          | Intent                                                 | Fallback rule                                                                          |
+| -------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| Agent calls `workflow cancel` during an active workflow turn   | Create before `ctx.abort()` when storage is available. | Make eligible after durable terminal cancellation.                                     |
+| Agent step times out                                           | Create before `ctx.abort()` when storage is available. | Keep ineligible while a recovery prompt can arrive. Make eligible on terminal timeout. |
+| Active workflow turn ends in terminal failure                  | Create or reuse the abort intent.                      | Make eligible after durable terminal failure.                                          |
+| Workflow reports started, then crashes before its first prompt | Create after durable failure.                          | Create as eligible.                                                                    |
+| Queued launch activation fails                                 | Create after the queue row is durably failed.          | Create as eligible.                                                                    |
+| Controller interrupts an active workflow turn                  | Create before the turn abort when possible.            | Durable terminal or handoff state decides eligibility.                                 |
+| Active workflow turn loses its queue claim                     | Create before the turn abort when possible.            | Keep ineligible while a new owner can continue.                                        |
+| Completed or waiting result has a presentation                 | Do not create a new intent.                            | Resolve an existing intent through presentation.                                       |
+| Direct `/workflow cancel`                                      | Do not create.                                         | No automatic model turn.                                                               |
+| Workflow pause                                                 | Do not create.                                         | No automatic model turn.                                                               |
+| User Escape or held workflow                                   | Do not create.                                         | No automatic model turn.                                                               |
+| Session shutdown                                               | Do not create.                                         | A closing session cannot start another turn.                                           |
+
+A terminal failure after a successful start tool result is eligible even when it did not first call `ctx.abort()`. This rule covers asynchronous runtime validation and startup failures that the user can see in the UI but the model cannot see in its current context.
+
+## Stable identity
+
+`intentId` is a deterministic digest of:
+
+- target session ID;
+- run ID;
+- source event ID;
+- node ID or `$launch`;
+- attempt ID when known;
+- cause.
+
+The same source event must always produce the same ID. Reusing an ID with different immutable facts is an error.
+
+`sourceEventId` identifies the source transition independently of delivery retries. Terminal handling must reuse an earlier abort event instead of creating a second terminal event for the same interruption.
+
+IDs use the existing controller-store key limit of 512 characters. The digest representation must be stable across processes and extension restarts.
+
+## Stored record
+
+`workflow_turn_intents` lives in the existing controller SQLite database.
+
+| Column                      | Null | Meaning                                      |
+| --------------------------- | ---- | -------------------------------------------- |
+| `intent_id`                 | No   | Deterministic primary key.                   |
+| `source_event_id`           | No   | Stable source transition identity.           |
+| `run_id`                    | No   | Related workflow run.                        |
+| `workflow_ref`              | No   | Workflow identity used in messages.          |
+| `target_session_id`         | No   | Session that can receive the successor.      |
+| `cause`                     | No   | Closed cause value.                          |
+| `node_id`                   | Yes  | Source node when known.                      |
+| `attempt_id`                | Yes  | Source attempt when known.                   |
+| `fallback_facts_json`       | No   | Bounded factual payload.                     |
+| `requested_at`              | No   | Absolute ISO 8601 creation time.             |
+| `eligible_at`               | Yes  | Absolute ISO 8601 fallback eligibility time. |
+| `resolved_at`               | Yes  | Absolute ISO 8601 resolution time.           |
+| `resolution`                | Yes  | Closed resolution value.                     |
+| `resolution_message_id`     | Yes  | Stable message identity.                     |
+| `delivery_claim_token`      | Yes  | Current claimant.                            |
+| `delivery_claim_expires_at` | Yes  | Claim expiry as epoch milliseconds.          |
+
+The table requires these indexes:
+
+- unresolved intents by run and target session;
+- unresolved eligible intents by target session, eligibility time, and intent ID.
+
+A resolved row has all three resolution fields. A pending row has none of them. A row cannot change immutable identity or source fields after creation.
+
+## Fallback facts
+
+`fallback_facts_json` uses this versioned camelCase object:
+
+```json
+{
+  "schema": "pi-workflows.deferred-turn-facts.v1",
+  "workflowName": "autoimplement",
+  "runId": "20260821T081731Z-autoimplement-407480dd",
+  "observedState": "failed",
+  "cause": "failed",
+  "nodeId": "$launch",
+  "attemptId": null,
+  "reason": "scope must be a non-empty string",
+  "handoff": false
+}
+```
+
+Rules:
+
+- `schema` is required and has the exact value shown above.
+- `workflowName`, `runId`, `observedState`, and `cause` are required strings.
+- `nodeId`, `attemptId`, and `reason` are strings or null.
+- `handoff` is a required boolean.
+- `reason` is safe diagnostic text with at most 8,192 characters.
+- The serialized object is at most 64 KiB.
+- Unknown fields are rejected during alpha.
+- The object must not contain credentials, raw environment values, or unbounded command output.
+
+`handoff: true` means another runner can continue. A handoff message must not describe the run as terminal unless separate durable state proves it.
+
+## Store operations
+
+The controller store provides these internal operations:
+
+- `ensureWorkflowTurnIntent`
+- `getWorkflowTurnIntent`
+- `claimWorkflowTurnIntentForRun`
+- `claimEligibleWorkflowTurnIntentsForSession`
+- `makeWorkflowTurnIntentEligible`
+- `resolveWorkflowTurnIntent`
+- `releaseWorkflowTurnIntentClaim`
+- a bounded diagnostic list operation
+
+`ensureWorkflowTurnIntent` is idempotent when all immutable fields match. It fails on an identity collision.
+
+Claim operations use a caller-supplied token and lease duration. Resolution requires the matching live claim token. Conditional updates ensure that natural delivery and fallback cannot both resolve the same intent.
+
+List operations require a positive bounded limit and deterministic ordering.
+
+## Abort ordering
+
+For an eligible active-turn abort, Pi Workflows performs these steps in order:
+
+1. Record abort provenance on the active run.
+2. Build the source event and intent ID.
+3. Attempt to persist the intent.
+4. Record the intent ID in system-abort bookkeeping.
+5. Call `ctx.abort()`.
+
+The persistence attempt is synchronous because cancellation immediately crosses the turn boundary. A store failure does not prevent `ctx.abort()`. Terminal handling retries the same intent ID. If retry also fails, Pi Workflows reports that it could not preserve the successor-turn guarantee.
+
+## Natural delivery
+
+All extension-owned workflow prompts and result presentations pass through one `DeferredTurnCoordinator`.
+
+If no intent exists, the coordinator preserves current message content and delivery options.
+
+If a pending intent exists, the coordinator:
+
+1. waits until the old turn has settled or the session is verified idle;
+2. claims the intent for the run and session;
+3. adds `turnIntentId` to the message details;
+4. sends the normal prompt or presentation;
+5. resolves the intent with the matching resolution and message ID;
+6. releases the claim if sending fails.
+
+A prompt generated during abort handling must not be sent into the aborting turn. The coordinator releases it after `agent_settled`.
+
+## Fallback delivery
+
+Fallback synchronization runs:
+
+- after `agent_settled` and system-abort cleanup;
+- when the target session starts;
+- during the existing periodic synchronization pass while the session is idle.
+
+The fallback custom message uses this details object:
+
+```json
+{
+  "schema": "pi-workflows.deferred-turn-message.v1",
+  "turnIntentId": "deferred-turn:...",
+  "runId": "20260821T081731Z-autoimplement-407480dd",
+  "cause": "failed"
+}
+```
+
+The message type is `pi-workflows-deferred-turn`. Delivery uses:
+
+```ts
+{
+  deliverAs: "followUp",
+  triggerTurn: true,
+}
+```
+
+The visible content reports observed facts and asks the agent to inspect durable state before it decides whether an authorized correction is needed. It does not claim that recovery occurred, resume the old run, or retry work.
+
+Fallback delivery is disabled during session shutdown and while a user-interrupted workflow is held.
+
+## Delivery recovery
+
+Every resolving message includes the intent ID in its custom-message details.
+
+Before sending, the coordinator scans the current session branch for that ID. If the message is already present, the coordinator resolves the intent without sending again. This repairs a crash or SQLite failure that occurs after `sendMessage` succeeds but before resolution is stored.
+
+Store leases prevent concurrent processes from sending the same resolution. Branch identity handles the remaining send-before-resolution window.
+
+## Claim transfer
+
+Claim loss stops the old runner's work and all fenced run-bundle writes. The intent stays pending and fallback-ineligible while another runner can resume the run.
+
+The new runner's next workflow prompt can resolve the intent. If durable state later proves a terminal outcome with no natural successor, terminal handling makes the intent eligible for fallback to its target session.
+
+Time alone does not prove terminal failure.
+
+## Launch notifications
+
+Workflow-authored `progress` and `final` notifications remain passive. They do not trigger model turns.
+
+The `launch_failure` notification kind is removed. Queued launch failure creates an eligible turn intent instead.
+
+Pending `launch_failure` rows from the earlier alpha contract are incompatible. Pi Workflows must stop with a clear controller-store reset instruction. It must not reinterpret, migrate, or silently delete those rows.
+
+## Availability limits
+
+Pi Workflows can guarantee only the facts under its control:
+
+- the intent was stored;
+- a claimant acquired it;
+- a custom message was sent or found in the session branch;
+- the local intent was resolved.
+
+Pi Workflows cannot guarantee model start or completion with the current Pi API. It also cannot deliver after permanent loss of the process, target session, controller store, machine, or model provider.
+
+Undelivered intents remain pending. The implementation does not add a service to process them outside a live Pi session.
+
+## Compatibility
+
+This is an alpha hard cutover.
+
+- Keep `pi-workflows.controller-store.v1`.
+- Add `workflow_turn_intents` to the existing database.
+- Remove the launch-trigger runtime path.
+- Add no v2 schema, compatibility reader, dual write, alias, or feature flag.
+- Keep historical terminal run bundles readable because their contract does not change.
+
+## Conformance
+
+An implementation conforms when:
+
+- one eligible source event produces at most one intent;
+- one intent produces at most one successor message;
+- an agent self-cancel receives one fallback after settlement;
+- an asynchronous crash after a successful start result receives one fallback after settlement;
+- a natural recovery prompt or presentation suppresses fallback by resolving the same intent;
+- direct cancellation, pause, Escape, user hold, and shutdown produce no automatic turn;
+- claim transfer permits natural resolution by the new owner and prevents stale writes;
+- polling, restart, lease expiry, and send-before-resolution failure do not duplicate turns;
+- passive workflow notifications keep their current behavior.

package/docs/DESIGN_PHILOSOPHY.md

@@ -1,6 +1,6 @@
 # Design philosophy
 
-Pi Workflows should stay small and easy to combine. A small set of clear, general parts should support many kinds of work.
+pi-workflows should stay small and easy to combine. A small set of clear, general parts should support many kinds of work.
 
 ## Primary rule
 

package/docs/HUMAN_DECISIONS.md

@@ -1,6 +1,6 @@
 # Human decisions
 
-Pi Workflows needs a reusable way to stop at a proposal and wait for a person. The same decision must appear in Pi and Telegram, and either channel must be able to continue the run. Workflows must be able to offer plain choices, choices that collect text, and choices that route back to planning.
+pi-workflows needs a reusable way to stop at a proposal and wait for a person. The same decision must appear in Pi and Telegram, and either channel must be able to continue the run. Workflows must be able to offer plain choices, choices that collect text, and choices that route back to planning.
 
 This document defines that behavior. The implementation is tracked in the [human decision gates plan](plans/2026-08-19-human-decision-gates-plan.md).
 
@@ -197,7 +197,7 @@ Private configuration maps the audience to channels:
 
 The workflow never receives a bot token, user ID, chat ID, Telegram message ID, or Pi session detail. Channel profiles are private host configuration and are excluded from run presentation.
 
-Pi Workflows keeps credential references in a separate private file. A Telegram credential points to an existing absolute mode-`0600` token file:
+pi-workflows keeps credential references in a separate private file. A Telegram credential points to an existing absolute mode-`0600` token file:
 
 ```json
 {
@@ -254,11 +254,11 @@ The adapter does not infer a choice from ordinary chat text. Callback payloads c
 
 Telegram permits one long-polling consumer for a bot profile. Active Pi processes use a shared lease so one process owns polling and the others use the same private channel state. The lease owner can accept a verified reply, but only the Pi session that owns the waiting run creates its continuation. Active sessions inspect the durable accepted-answer fence and recover their own continuation. If no Pi process is running, Telegram delivery and reply collection resume when Pi starts again. Running an always-on service is outside this design.
 
-The Bot API does not provide an idempotency key for `sendMessage`. Pi Workflows therefore writes a delivery intent before sending and never blindly retries an ambiguous send. A timed-out send is recorded as `unknown`; Pi remains available and an operator can request another delivery. This avoids automatic duplicate messages while keeping decision acceptance exactly once.
+The Bot API does not provide an idempotency key for `sendMessage`. pi-workflows therefore writes a delivery intent before sending and never blindly retries an ambiguous send. A timed-out send is recorded as `unknown`; Pi remains available and an operator can request another delivery. This avoids automatic duplicate messages while keeping decision acceptance exactly once.
 
 ## Durable decision records
 
-Decision records live next to workflow run bundles under the Pi Workflows state root. They are additive and linked by run ID. A decision directory contains immutable records for:
+Decision records live next to workflow run bundles under the pi-workflows state root. They are additive and linked by run ID. A decision directory contains immutable records for:
 
 - the request;
 - channel delivery intents and results;
@@ -276,7 +276,7 @@ SQLite may index pending decisions and channel leases, but immutable decision fi
 
 ## Planning workflow composition
 
-Pi Workflows keeps solution choice, documentation, and implementation in separate built-ins:
+pi-workflows keeps solution choice, documentation, and implementation in separate built-ins:
 
 - `autoplan` chooses a solution or revises one after new evidence.
 - `autodoc` records an already selected solution in the canonical specification and implementation plan. It does not choose a solution or implement it.
@@ -290,7 +290,7 @@ If later implementation, verification, review, comments, or CI evidence invalida
 
 ## Reusable plan approval workflow
 
-Pi Workflows ships a typed `plan-approval` workflow built on `humanDecision()`. Its input contains the documented plan, plan digest, audience, and display summary. It has three named exits:
+pi-workflows ships a typed `plan-approval` workflow built on `humanDecision()`. Its input contains the documented plan, plan digest, audience, and display summary. It has three named exits:
 
 - `continue`, with the approval receipt;
 - `stop`, with the stop receipt; and
@@ -345,7 +345,7 @@ The engine remains independent from Pi and Telegram. Core code owns decision con
 - **Other persistent data:** additive decision records, a rebuildable private channel index, and private channel configuration.
 - **Pi internals:** none.
 - **Public Pi API:** documented extension lifecycle and UI methods only.
-- **Public Pi Workflows API:** typed human choices, `humanDecision()`, `humanDecisionEdge()`, the channel interface, and the `plan-approval` workflow.
+- **Public pi-workflows API:** typed human choices, `humanDecision()`, `humanDecisionEdge()`, the channel interface, and the `plan-approval` workflow.
 
 ## Verification requirements
 

package/docs/HUMAN_DECISION_PRESENTATIONS.md

@@ -7,7 +7,7 @@ The implementation plan is in
 [the human decision presentations plan](plans/2026-08-19-human-decision-presentations-plan.md).
 
 A human decision contains machine data and a separate message for the operator.
-Pi Workflows stores and validates the machine data. Pi and Telegram render only
+pi-workflows stores and validates the machine data. Pi and Telegram render only
 the operator message, and future channels follow the same rule.
 
 ## Minimal example
@@ -229,7 +229,7 @@ text prompt. It wraps and scrolls while responding to resize, theme, cancellatio
 and `AbortSignal` events.
 
 When Telegram or another channel accepts the decision, the signal closes the Pi
-dialog. Pi Workflows does not modify Pi core or use undocumented TUI state.
+dialog. pi-workflows does not modify Pi core or use undocumented TUI state.
 
 ### Other channels
 
@@ -239,7 +239,7 @@ for display.
 
 ## Plan presentation
 
-Pi Workflows provides a reusable plan presenter for built-in workflows. It
+pi-workflows provides a reusable plan presenter for built-in workflows. It
 derives a presentation from the same typed plan stored as the subject.
 
 The presenter uses these sections when data exists:

package/docs/MONITOR.md

@@ -148,9 +148,9 @@ A check may use available tools to read current state. It must use the target's
 
 ## Progress ownership boundary
 
-The regular Pi model running the check is the observation adapter. It uses the target-specific tools authorized by the task, converts observed facts into `pi-workflows.progress.v1` tracks, and publishes them through the existing `workflow` tool. Pi Workflows validates, stores, estimates, and displays those tracks.
+The regular Pi model running the check is the observation adapter. It uses the target-specific tools authorized by the task, converts observed facts into `pi-workflows.progress.v1` tracks, and publishes them through the existing `workflow` tool. pi-workflows validates, stores, estimates, and displays those tracks.
 
-The monitored target stays independent of Pi Workflows. A monitor must not require a target Job or application to import Pi Workflows, emit a Pi schema, write a Pi progress file, expose a Pi endpoint, create a progress store, or add a progress reader command solely for monitoring. Provider-specific clients and credentials do not belong in Pi Workflows.
+The monitored target stays independent of pi-workflows. A monitor must not require a target Job or application to import pi-workflows, emit a Pi schema, write a Pi progress file, expose a Pi endpoint, create a progress store, or add a progress reader command solely for monitoring. Provider-specific clients and credentials do not belong in pi-workflows.
 
 When a target does not expose a factual count, total, or source estimate, the check reports that ETA is unavailable. Better application telemetry is separate work. It should expose normal operational facts for all operators, not a Pi-specific reporting protocol.
 

package/docs/WORKFLOW_COMPOSITION.md

@@ -1,6 +1,6 @@
 # Workflow composition
 
-Pi Workflows can include one workflow inside another without copying nodes, prompts, or routing logic. The included workflow still runs on its own. The parent supplies input and connects the included workflow's named exits to later parent steps.
+pi-workflows can include one workflow inside another without copying nodes, prompts, or routing logic. The included workflow still runs on its own. The parent supplies input and connects the included workflow's named exits to later parent steps.
 
 Composition keeps one run, trace, pause state, cancellation state, and final presentation. Controllers remain the correct tool for independent or indefinitely reconciled child runs.
 
@@ -306,7 +306,7 @@ This is a compatible public API addition under the project's pre-1.0 policy. It
 - **Other persistent data:** additive source and mount data, definition digests, and include events in existing run bundles.
 - **Pi internals:** none.
 - **Public Pi API:** existing extension APIs only.
-- **Public Pi Workflows API:** typed workflow inputs and exits, `includeWorkflow()`, direct imports, dynamic references, and `defineWorkflowRegistry()`.
+- **Public pi-workflows API:** typed workflow inputs and exits, `includeWorkflow()`, direct imports, dynamic references, and `defineWorkflowRegistry()`.
 
 ## Required tests
 

package/docs/WORKFLOW_STEP_MESSAGES.md

@@ -1,6 +1,6 @@
 # Workflow step messages
 
-This specification defines how Pi Workflows shows agent-step instructions in an interactive Pi session. The model receives the complete step prompt, while the user sees a small workflow card that can be expanded.
+This specification defines how pi-workflows shows agent-step instructions in an interactive Pi session. The model receives the complete step prompt, while the user sees a small workflow card that can be expanded.
 
 This contract is implemented for the release after `0.5.3`.
 
@@ -8,7 +8,7 @@ This contract is implemented for the release after `0.5.3`.
 
 Agent-step prompts contain the task, workflow identity, attempt identity, output shape, and submission rules. This information is required by the model, but showing it as a large user message makes the conversation hard to read.
 
-Pi Workflows will send the same prompt as a custom Pi message. A custom renderer will show a compact summary by default and the full content when expanded.
+pi-workflows will send the same prompt as a custom Pi message. A custom renderer will show a compact summary by default and the full content when expanded.
 
 This is a presentation change. It does not add a workflow primitive, change graph execution, or change the step completion contract.
 
@@ -85,7 +85,7 @@ The expanded card shows:
 - expected output
 - full model prompt
 
-Expansion uses Pi's existing custom-message expansion state and keys. Pi Workflows does not add another toggle or store separate expansion state.
+Expansion uses Pi's existing custom-message expansion state and keys. pi-workflows does not add another toggle or store separate expansion state.
 
 ## Reminders and resumes
 
@@ -105,9 +105,9 @@ The two message types must not share delivery code that can accidentally change
 
 New interactive step deliveries replace `sendUserMessage` with `sendMessage`. Existing session entries remain readable and are not rewritten.
 
-The custom message is a normal documented Pi session message. Pi Workflows adds no Pi session schema, private entry type, or separate persistent store. Run bundles keep the existing full prompt and structured step contract, so this change does not alter the run-bundle schema.
+The custom message is a normal documented Pi session message. pi-workflows adds no Pi session schema, private entry type, or separate persistent store. Run bundles keep the existing full prompt and structured step contract, so this change does not alter the run-bundle schema.
 
-If the renderer is unavailable, Pi still retains the custom message content. Pi Workflows does not add a fallback path that sends a duplicate user message.
+If the renderer is unavailable, Pi still retains the custom message content. pi-workflows does not add a fallback path that sends a duplicate user message.
 
 ## Public API boundary
 

package/docs/WORKFLOW_UPDATES.md

@@ -1,6 +1,6 @@
 # Workflow updates
 
-This specification defines durable, non-terminal updates from running Pi Workflows nodes. An update reports current state without finishing a node or choosing a graph route.
+This specification defines durable, non-terminal updates from running pi-workflows nodes. An update reports current state without finishing a node or choosing a graph route.
 
 ## Minimal examples
 
@@ -54,7 +54,7 @@ The `update` tool action does not complete the agent step. The agent still calls
 
 ## Place in the workflow model
 
-Pi Workflows keeps its current node primitives:
+pi-workflows keeps its current node primitives:
 
 - `agent` for model judgment and language work
 - `compute` for pure local calculation
@@ -76,11 +76,34 @@ Updates do not:
 
 A node's final result remains the only value that completes the node and controls routing.
 
+## Command batch updates
+
+A bounded command-batch action can publish one metadata update when an item settles:
+
+```json
+{
+  "type": "command-batch.item",
+  "key": "review/4f2a9c1d",
+  "data": {
+    "schema": "pi-workflows.command-batch-item.v1",
+    "batchKind": "review",
+    "itemId": "4f2a9c1d",
+    "outcome": "succeeded",
+    "completed": 2,
+    "total": 4
+  }
+}
+```
+
+`batchKind` identifies `review`, `ciWatch`, or `verification`. `outcome` is `succeeded`, `failed`, `timedOut`, or `cancelled`. `completed` and `total` are observed command counts. The key stays stable for one batch item.
+
+These updates do not contain stdout, stderr, command environments, credentials, or private provider data. The accepted action output contains command receipts and controls workflow routing. A command-batch update cannot satisfy review, CI, or verification. If an unaccepted batch runs again after interruption, its earlier updates remain diagnostic records only.
+
 ## Model-mediated observation
 
 For monitoring, the regular Pi model running the workflow step observes the external target and publishes progress with the existing `workflow` tool. This is the intended adapter boundary. Deterministic runtime code validates, persists, estimates, and renders the submitted data.
 
-External Jobs and applications do not need a Pi Workflows dependency or reporting protocol. Provider-specific observation stays in the agent task and its authorized tools. If the target does not expose enough facts, the model publishes only what is known and leaves ETA unavailable.
+External Jobs and applications do not need a pi-workflows dependency or reporting protocol. Provider-specific observation stays in the agent task and its authorized tools. If the target does not expose enough facts, the model publishes only what is known and leaves ETA unavailable.
 
 Do not add a transport, endpoint, store, schema, or provider integration when the regular Pi model can observe the target and use `workflow update` or `submit`.
 
@@ -333,7 +356,7 @@ Fields:
 
 A progress object is a full snapshot for its key. Omitted optional fields clear their previous values. Publishers mark finished tracks with a terminal status instead of deleting them.
 
-The reserved key `overall` represents an explicit aggregate supplied by the workflow. Pi Workflows never combines unrelated tracks automatically. Without `overall`, displays list independent tracks.
+The reserved key `overall` represents an explicit aggregate supplied by the workflow. pi-workflows never combines unrelated tracks automatically. Without `overall`, displays list independent tracks.
 
 Unknown fields in `pi-workflows.progress.v1` are validation errors.
 
@@ -355,7 +378,7 @@ A measured ETA requires a known total and at least two usable samples in the cur
 
 The median interval rate is the central estimate. The 25th and 75th percentile rates form the ETA range. The faster rate gives the lower remaining-time bound and the slower rate gives the upper bound. One usable interval has low confidence. With two through four intervals, a ratio of interquartile range to median no greater than 0.5 gives medium confidence; a wider spread gives low confidence. With five or more intervals, a ratio no greater than 0.25 gives high confidence, a ratio through 0.5 gives medium confidence, and a wider spread gives low confidence. A non-positive median makes ETA unavailable. A non-positive lower rate removes the upper time bound, so the formatter shows the central ETA with low confidence instead of a closed range.
 
-A fresh `sourceEstimatedFinishAt` takes priority over a measured ETA and is labelled as a source estimate. It is fresh when it comes from the latest track update, is later than the matching `sourceUpdatedAt` or runtime receipt time, and has not passed. When `sourceUpdatedAt` is absent, the runtime receipt time is the source time. A passed source estimate is expired and does not override a measured estimate. Pi Workflows does not ask a model to invent an ETA. When the target supplies no usable estimate and the samples cannot support one, the formatter says `ETA unavailable` and states the reason.
+A fresh `sourceEstimatedFinishAt` takes priority over a measured ETA and is labelled as a source estimate. It is fresh when it comes from the latest track update, is later than the matching `sourceUpdatedAt` or runtime receipt time, and has not passed. When `sourceUpdatedAt` is absent, the runtime receipt time is the source time. A passed source estimate is expired and does not override a measured estimate. pi-workflows does not ask a model to invent an ETA. When the target supplies no usable estimate and the samples cannot support one, the formatter says `ETA unavailable` and states the reason.
 
 For `waiting` or `blocked` tracks, measured ETA is paused and the display reports the current state. A source estimate may still be shown when the target reports one. For terminal tracks, remaining work and ETA are omitted.
 

package/docs/plans/2026-08-04-controller-runtime-plan.md

@@ -8,7 +8,7 @@ status: implemented
 
 # Controller runtime plan
 
-Pi Workflows needs a controller mode for automation that spans repeated events, external state changes, and process restarts. The design in [CONTROLLERS.md](../CONTROLLERS.md) follows the Kubernetes controller pattern. Durable resources hold desired and observed state, events enqueue resource keys, and each reconciliation reads current facts before acting.
+pi-workflows needs a controller mode for automation that spans repeated events, external state changes, and process restarts. The design in [CONTROLLERS.md](../CONTROLLERS.md) follows the Kubernetes controller pattern. Durable resources hold desired and observed state, events enqueue resource keys, and each reconciliation reads current facts before acting.
 
 The implementation keeps the graph engine focused on finite jobs. Controllers start and observe workflows through a child-run interface. Workflow graphs keep their finite execution model.
 

package/docs/plans/2026-08-05-always-on-workflows-plan.md

@@ -8,7 +8,7 @@ status: implemented
 
 # Always-on workflows plan
 
-Pi Workflows should feel the same whether the user watches a run or walks away from it. In the user's words: "I might start a workflow locally in Pi then I wait for it to complete. All the while I am looking at the screen and I'm not closing the Pi window. When the workflow ends I just want to be able to continue the same Pi session like normal with a session up to date with what happened in the workflow." And: "I just want to interact by starting a workflow, closing it, and then coming back and then still being able to continue it when I open it up. It's syncing continuously or something."
+pi-workflows should feel the same whether the user watches a run or walks away from it. In the user's words: "I might start a workflow locally in Pi then I wait for it to complete. All the while I am looking at the screen and I'm not closing the Pi window. When the workflow ends I just want to be able to continue the same Pi session like normal with a session up to date with what happened in the workflow." And: "I just want to interact by starting a workflow, closing it, and then coming back and then still being able to continue it when I open it up. It's syncing continuously or something."
 
 These are not two modes. The user asked for "both in a single unified system." This plan makes the Pi window irrelevant to execution: closing or opening the window is a change in observation, not in the run. The work stays on one machine, uses the merged controller runtime as its foundation, and does not modify Pi core.
 

package/docs/plans/2026-08-10-agent-managed-monitor-workflows-plan.md

@@ -10,7 +10,7 @@ status: implemented
 
 The user should be able to tell an agent, "Monitor this every 30 minutes," and have the agent start the right workflow. The user must not write controller records or JSON. The existing `workflow` model tool should manage workflows instead of serving only as a step-submission tool.
 
-A monitor is one Pi Workflows graph. It checks the target, reports a meaningful change, sleeps for the requested interval with the existing shell node, and loops. This plan does not use controllers, Unified Exec, a new wait node, or a second scheduler.
+A monitor is one pi-workflows graph. It checks the target, reports a meaningful change, sleeps for the requested interval with the existing shell node, and loops. This plan does not use controllers, Unified Exec, a new wait node, or a second scheduler.
 
 ## Shipped design
 
@@ -84,11 +84,11 @@ The `list` result identifies `monitor` as a built-in workflow and gives a short
 
 ## Built-in monitor workflow
 
-Ship `monitor` as a built-in workflow in the Pi Workflows package. Built-ins have the lowest discovery precedence:
+Ship `monitor` as a built-in workflow in the pi-workflows package. Built-ins have the lowest discovery precedence:
 
 1. Project workflows under `.pi/workflows/`
 2. Global workflows under `~/.pi/agent/workflows/`
-3. Workflows bundled with Pi Workflows
+3. Workflows bundled with pi-workflows
 
 A project or global `monitor.workflow.ts` can therefore replace the default. The built-in remains a real workflow file so run bundles can record its path and source hash with the existing rules.
 
@@ -112,13 +112,13 @@ prepare -> guard -> check
                     | stop and report -> report-final -> finish
 ```
 
-`prepare` validates and normalizes the input. `guard` enforces `maxChecks`. `check` is an agent node that performs one observation and returns a validated route, a bounded observation, and an optional report. The next `check` can read the previous accepted `check` output, which Pi Workflows already keeps for looped nodes.
+`prepare` validates and normalizes the input. `guard` enforces `maxChecks`. `check` is an agent node that performs one observation and returns a validated route, a bounded observation, and an optional report. The next `check` can read the previous accepted `check` output, which pi-workflows already keeps for looped nodes.
 
 The report nodes write a normal assistant message and then submit an acknowledgement. Keeping reporting after accepted check output prevents the agent from showing a report before the structured result passes validation. The final presentation reports why the monitor stopped without repeating a report that the user already saw.
 
-The sleep node uses the existing Pi Workflows shell action to launch the current Node executable with a timer. Set the node timeout above the largest supported interval because the engine default is 15 minutes. Set the shell execution timeout above the requested wait by a small fixed margin. Cancellation aborts the timer process immediately.
+The sleep node uses the existing pi-workflows shell action to launch the current Node executable with a timer. Set the node timeout above the largest supported interval because the engine default is 15 minutes. Set the shell execution timeout above the requested wait by a small fixed margin. Cancellation aborts the timer process immediately.
 
-If the Pi TUI or standalone workflow host stops during sleep, Pi Workflows parks the run and kills the shell child. Resuming the run starts that sleep node again from the beginning. This is existing workflow behavior and is acceptable for this feature. No special timer persistence is added.
+If the Pi TUI or standalone workflow host stops during sleep, pi-workflows parks the run and kills the shell child. Resuming the run starts that sleep node again from the beginning. This is existing workflow behavior and is acceptable for this feature. No special timer persistence is added.
 
 The workflow uses a high but finite `maxSteps` value as a second safety guard. Check and report values have explicit size limits so a long run cannot grow its bundle without bound.
 
@@ -133,7 +133,7 @@ Make the feature in `osolmaz/pi-workflows`:
 - Add the built-in monitor workflow and focused tests.
 - Update `README.md` and `docs/workflows.md`.
 
-After the upstream change is complete, update the pinned Pi Workflows commit in OnurPi's thin `packages/workflows` wrapper. Do not add a new OnurPi extension or copy a monitor file into live global state.
+After the upstream change is complete, update the pinned pi-workflows commit in OnurPi's thin `packages/workflows` wrapper. Do not add a new OnurPi extension or copy a monitor file into live global state.
 
 ## State and API impact
 
@@ -141,7 +141,7 @@ After the upstream change is complete, update the pinned Pi Workflows commit in
 - **Other persistent data:** No new data model. The feature uses existing run bundles and the existing workflow run queue.
 - **Pi internals:** None.
 - **Pi public API:** `registerTool`, `registerCommand`, `sendUserMessage`, and documented agent and session lifecycle events.
-- **Pi Workflows API:** The workflow definition and run-state models do not change. The model-facing `workflow` tool contract changes, and discovery gains a lowest-priority built-in source.
+- **pi-workflows API:** The workflow definition and run-state models do not change. The model-facing `workflow` tool contract changes, and discovery gains a lowest-priority built-in source.
 
 ## Non-goals
 
@@ -179,6 +179,6 @@ npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
 npx -y @simpledoc/simpledoc check
 ```
 
-Test the extension from the Pi Workflows checkout with `pi -e src/extension/index.ts`. Use a short test interval in a controlled fixture, then perform one manual 30-minute monitor run to confirm that the configured node timeout does not stop it. Test plain-language startup with the normal model, then test list, status, pause, resume, cancel, and checkpoint answer actions.
+Test the extension from the pi-workflows checkout with `pi -e src/extension/index.ts`. Use a short test interval in a controlled fixture, then perform one manual 30-minute monitor run to confirm that the configured node timeout does not stop it. Test plain-language startup with the normal model, then test list, status, pause, resume, cancel, and checkpoint answer actions.
 
 After updating OnurPi, run its full checks and start Pi with the installed OnurPi package. Confirm that the model sees one `workflow` tool, discovers `monitor`, and can start it from a plain-language request.

package/docs/plans/2026-08-13-built-in-workflow-catalog-plan.md

@@ -66,7 +66,7 @@ If identity or revision cannot be proved, leave the run unchanged and report a c
 
 ## Scope and non-goals
 
-This changes Pi Workflows only. It uses no Pi internals and changes no Pi session entry. It updates Pi Workflows run bundles and controller queue records as described above.
+This changes pi-workflows only. It uses no Pi internals and changes no Pi session entry. It updates pi-workflows run bundles and controller queue records as described above.
 
 It does not add runtime compatibility readers, aliases, dual-write fields, or a permanent migration service. It does not hot-reload package-provided built-ins. A package update takes effect after Pi reload or restart.