@osolmaz/pi-workflows 0.11.2 → 0.12.1

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).
 
@@ -60,6 +60,10 @@ export default defineWorkflow({
     approve: humanDecision({
       audience: "operator",
       choices: planChoices,
+      onTimeout: {
+        afterMs: 10 * 60_000,
+        response: { choice: "continue" },
+      },
       request: ({ outputs }) => ({
         title: "Approve the implementation plan",
         subject: outputs.propose,
@@ -106,6 +110,8 @@ type PlanDecision =
 
 `humanDecisionEdge()` requires one destination for every choice. A missing or extra case is a TypeScript error. Runtime validation applies the same choice and input contract before an answer can win.
 
+`onTimeout` is optional. It supplies a positive duration and a response that satisfies the same choice contract. The request stores the resulting absolute deadline and validated response. When no human answer wins before the deadline, the decision recovery owner applies that response with `timeout` provenance. Omitting `onTimeout` keeps an indefinite wait. A request cannot combine `onTimeout` with a separate `expiresAt` value.
+
 ## Checkpoint behavior
 
 A human decision still has `nodeType: "checkpoint"`. The helper adds a human decision contract to that checkpoint.
@@ -118,9 +124,7 @@ When the engine reaches the node, it:
 4. asks the configured channels to deliver it; and
 5. parks the run in `waiting` state.
 
-When a valid answer is accepted, the continuation keeps the workflow's original input. The human answer becomes the checkpoint node's output in the continuation. Existing checkpoints keep their current behavior, where `/workflow answer` supplies the continuation input.
-
-This distinction preserves old workflow definitions and run bundles.
+When a valid answer is accepted, the continuation keeps the workflow's original input. The human answer becomes the checkpoint node's output in the continuation. Ordinary checkpoints keep their current behavior, where `/workflow answer` supplies the continuation input.
 
 ## Request and response contracts
 
@@ -136,12 +140,12 @@ A new decision request contains:
 - the logical audience;
 - the complete choice contract;
 - the canonical request digest;
-- an optional expiry rule; and
+- an optional absolute deadline and automatic response; and
 - the creation time.
 
-The presentation is an explicit display allowlist. A channel does not receive the subject and cannot infer operator text from it. The request digest binds the subject, visible presentation, title, revision, choices, and input prompts. Each choice has a stable ID and may have no input or one validated text input contract.
+The presentation is an explicit display allowlist. A channel does not receive the subject and cannot infer operator text from it. The request digest binds the subject, visible presentation, title, revision, choices, input prompts, deadline, and automatic response. Each choice has a stable ID and may have no input or one validated text input contract.
 
-The former `body` form remains available for existing workflow definitions. It creates a v1 request and uses a deterministic readable compatibility formatter. Oversized historical bodies receive a bounded readable prefix and an explicit omission notice with the full body digest and size. V1 request bytes and digests do not change.
+Human decisions use only `pi-workflows.human-decision-request.v1`. The former `body` request and all human-decision `v2` records are invalid. This is an alpha hard cutover: old waiting runs and decision state must be reset rather than migrated or reinterpreted.
 
 A submitted response contains:
 
@@ -197,7 +201,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 +258,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;
@@ -268,15 +272,15 @@ Decision records live next to workflow run bundles under the Pi Workflows state
 - channel settlement results; and
 - the continuation request and result.
 
-The resolution record uses a no-replace create. The first valid acceptance, cancellation, or expiry writer wins. Acceptance then materializes the matching accepted-answer detail. Cancellation or expiry materializes cancellation detail. A retry with the same response and idempotency key adopts the existing answer. A conflicting answer receives an `already decided` result.
+The resolution record uses a no-replace create. A valid human answer or eligible timeout response claims the same immutable resolution. The saved result includes `human` or `timeout` provenance. A timeout result has no human actor or channel identity. Cancellation writes a terminal tombstone that takes precedence over automatic continuation. A retry adopts the existing matching result. A conflicting or late answer receives an `already decided` result.
 
-The continuation run ID is derived from the accepted decision ID. Recovery adopts an existing matching continuation or creates it once. A crash after answer acceptance cannot run the next workflow step twice. The continuation run carries a redacted receipt with the decision ID, request digest, gate node ID, choice, acceptance time, and answer digest. Actor, channel, event, and idempotency provenance stays only in the private decision records and never enters the run bundle or model context.
+The continuation run ID is derived from the decision ID. Recovery adopts an existing matching continuation or creates it once. A crash after resolution cannot run the next workflow step twice. The continuation record and redacted receipt carry the resolution provenance, decision ID, request digest, gate node ID, choice, acceptance time, and answer digest. Human actor, channel, event, and idempotency details stay only in the private decision records and never enter the run bundle or model context.
 
 SQLite may index pending decisions and channel leases, but immutable decision files remain the source of truth. The index is disposable and rebuildable.
 
 ## 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.
@@ -286,33 +290,19 @@ Pi Workflows keeps solution choice, documentation, and implementation in separat
 
 `autoimplement` first finds the clear existing plan in its input, the conversation, or referenced canonical documents. It blocks when no clear plan exists. A caller can bypass discovery and autodoc only by supplying both the explicit plan and a `documentation` receipt whose plan digest matches it. A plan without that current-document evidence enters autodoc so the canonical documents are inspected and adopted or updated. The absence of a structured `plan` input never authorizes `autoplan`.
 
-If later implementation, verification, review, comments, or CI evidence invalidates the plan, autoimplement runs `autoplan`, sends the revised plan through `autodoc`, and then resumes implementation. An optional approval policy inserts `plan-approval` after the revised documentation.
+If later implementation, verification, review, comments, or CI evidence invalidates the plan, Autoimplement enters the shared plan-change workflow. That workflow runs Autoplan, Autodoc, plan approval, and bounded exact-text replanning. Monitor uses the same workflow for each new repair plan and passes the selected plan into Autoimplement without a second decision.
 
 ## 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:
-
-- `continue`, with the approval receipt;
-- `stop`, with the stop receipt; and
-- `replan`, with the exact instructions and receipt.
-
-A parent can include it without copying prompts or channel handling:
+pi-workflows ships a typed `plan-approval` workflow built on `humanDecision()`. Its policy has three modes:
 
-```typescript
-includes: {
-  approval: includeWorkflow(planApproval, {
-    input: ({ outputs }) => ({
-      plan: outputs.devise.plan,
-      planDigest: outputs.devise.planDigest,
-      audience: "operator",
-    }),
-  }),
-},
-```
+- `auto` asks the configured audience and continues after the configured deadline. It defaults to audience `operator` and 10 minutes.
+- `required` waits for an explicit human answer.
+- `skip` creates no human decision and continues immediately.
 
-A `replan` exit returns to `autoplan` with the previous plan and the exact human instructions as new evidence. The revised plan passes through `autodoc`, receives a new digest, and enters a new approval decision. Step limits bound repeated replanning.
+The workflow has `continue`, `stop`, and exact-text `replan` exits. Continue reports `human`, `timeout`, or `skipped` provenance. Stop and replan always require a human answer.
 
-Monitor repair composes `autoplan`, `autodoc`, optional `plan-approval`, `autoimplement`, and a fresh target check. Autoimplement can mount the same approval workflow after evidence-driven redesign. Existing behavior stays unchanged when no approval policy is present.
+The internal plan-change workflow composes Autoplan, Autodoc, and plan approval once. It owns the replan count, plan digest, and positive revision. Autoimplement and Monitor include this workflow instead of copying approval routes. A plan supplied by the caller or already selected by Monitor bypasses another decision. Only a changed plan digest enters the gate.
 
 ## Recovery and cancellation
 
@@ -325,27 +315,27 @@ Recovery follows these rules:
 - ambiguous Telegram sends are not retried automatically;
 - duplicate channel updates are harmless;
 - stale responses are rejected;
-- one accepted response creates one continuation;
-- the winning channel dismisses any pending Pi dialog;
+- one human or timeout response creates one continuation;
+- the winning human answer or timeout policy dismisses any pending Pi dialog;
 - confirmed channel settlement is adopted without another remote call;
 - failed channel settlement has a bounded retry count and cannot create an unbounded record loop; and
 - cancellation resolves the owned waiting decision from durable state, even after restart, closes pending views, and prevents a later answer from continuing the run.
 
-A decision with no available channel remains waiting and reports the configuration problem. It does not silently continue or choose a default.
+A required decision with no available channel remains waiting and reports the configuration problem. An automatic decision does not need a channel to apply its saved response after the deadline. A skipped plan policy creates no decision.
 
 ## Compatibility
 
-Ordinary checkpoints, their continuation input behavior, and existing run bundles remain unchanged. V2 requests, accepted records, receipts, resolutions, and multipart delivery records are additive. Older viewers ignore them. Updated viewers label a human decision as a checkpoint, show the readable presentation and its fingerprint, and keep the canonical subject separate. Private channel configuration and transport identifiers remain hidden.
+This alpha change updates the current request, accepted-result, receipt, resolution, continuation, and snapshot contracts in place. Old active runs refuse resume through normal source and definition identity checks. There is no compatibility reader, migration, dual path, or new schema generation. Updated viewers label a human decision as a checkpoint, show its deadline and automatic action when present, and keep the canonical subject separate. Private channel configuration and transport identifiers remain hidden.
 
 The engine remains independent from Pi and Telegram. Core code owns decision contracts, validation, durable acceptance, and continuation. The Pi extension owns UI and channel lifecycle. The Telegram adapter owns Bot API translation. Workflow definitions own only the question, choices, audience, and routes.
 
 ## Contract impact
 
 - **Session state:** Pi records normal workflow messages and interactive decision results.
-- **Other persistent data:** additive decision records, a rebuildable private channel index, and private channel configuration.
+- **Other persistent data:** decision requests and resolutions can carry a deadline, automatic response, and resolution provenance in the existing decision store. The private channel index remains rebuildable.
 - **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().onTimeout`, `humanDecisionEdge()`, the channel interface, the plan approval policy, and the shared plan-change workflow.
 
 ## Verification requirements
 

package/docs/HUMAN_DECISION_PRESENTATIONS.md

@@ -1,13 +1,13 @@
 # Human decision presentations
 
-This contract is implemented. New human decision requests separate their canonical
-subject from the complete readable message shown to an operator. Historical requests
-that use `body` remain compatible through a deterministic readable formatter.
+This contract is implemented. Human decision requests separate their canonical
+subject from the complete readable message shown to an operator. Human decisions use
+one v1 contract with no legacy body form or parallel schema version.
 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
@@ -52,7 +52,7 @@ not see `subject` unless the workflow explicitly copies selected text into
 
 ## Request contract
 
-A new request uses `pi-workflows.human-decision-request.v2`. It contains:
+A request uses `pi-workflows.human-decision-request.v1`. It contains:
 
 | Field                | Required | Meaning                                         |
 | -------------------- | -------- | ----------------------------------------------- |
@@ -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:
@@ -255,25 +255,15 @@ It omits absent sections. It never serializes the plan object. `plan-approval`,
 `monitor`, `autoplan`, `autodoc`, and `autoimplement` reuse this presenter where
 they ask a person to approve a plan.
 
-## Compatibility
+## Alpha cutover
 
-Current v1 requests remain immutable.
+The human-decision request, accepted result, receipt, delivery, and resolution use one
+v1 schema family. The current structured subject and explicit presentation contract
+replaced the former body request and parallel v2 records in place.
 
-- A v1 string body becomes one readable paragraph at delivery time.
-- A v1 object body uses a deterministic compatibility formatter. It converts
-  stable key order into readable labels and fields with sections and lists.
-- An oversized v1 body remains answerable. The formatter keeps a bounded readable
-  prefix and adds an explicit omission notice with the full body digest and size.
-  It never hides omitted content behind an ellipsis.
-- The compatibility formatter reads only the historical `body`, which was
-  already the display field. It never reads a new structured subject.
-- V1 request bytes and digests do not change.
-- Pending and accepted v1 decisions continue to use v1 validation and digest
-  rules.
-- New preferred authoring emits v2. The existing body form remains a deprecated
-  compatibility overload until a separate removal is approved.
-
-No migration rewrites run bundles or decision records.
+Old waiting runs and human-decision state are incompatible. The runtime fails with a
+reset instruction instead of reading, migrating, or silently reinterpreting them.
+There is no compatibility reader, dual path, alias, or migration.
 
 ## Privacy and security
 
@@ -311,10 +301,10 @@ npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
 npx -y @simpledoc/simpledoc check
 ```
 
-Tests must cover schema validation, canonical digests, readable legacy bodies,
+Tests must cover schema validation, canonical digests, structured-value formatting,
 plan rendering, Pi and Telegram content parity, unsafe text, Unicode, multipart
-delivery, ambiguous sends, recovery, stale answers, viewer output, and proof
-that no channel serializes a subject as JSON.
+delivery, ambiguous sends, recovery, stale answers, viewer output, incompatible-state
+failure, and proof that no channel serializes a subject as JSON.
 
 ## Boundaries
 

package/docs/MONITOR.md

@@ -38,7 +38,7 @@ The monitor checks a target, sends one status notification after every accepted
 
 `repair` must set `authorized: true`. It can constrain scope, repository, base branch, merge behavior, and other implementation constraints. Omitted `merge` means the repair can prepare but cannot merge a pull request; merging requires explicit `merge: true`. Without this object the monitor is observation-only. Repair authority does not permit a protected model, benchmark, credential, hardware, spending, or scope change.
 
-`repair.approval` is optional. It contains a logical `audience` and `maxReplans` from 1 through 20. When present, monitor sends the documented repair plan through the reusable human `plan-approval` workflow. Continue starts implementation, stop ends the repair truthfully, and replan preserves exact operator text before autoplan and autodoc run again. The model-facing workflow tool cannot approve the gate.
+`repair.approval` uses `auto`, `required`, or `skip` mode. When omitted, Monitor uses `auto` with audience `operator`, a 10-minute timeout, and three allowed replans. Auto mode asks and then continues with the exact plan if no answer is accepted by the deadline. Required mode waits for an explicit human answer. Skip mode asks nothing. Continue starts implementation, stop ends the repair truthfully, and replan preserves exact operator text before the shared plan-change workflow runs again. The model-facing workflow tool cannot approve the gate.
 
 `reportWhen` is removed. The monitor always reports after every accepted check.
 
@@ -102,17 +102,11 @@ prepare
       ├─ continue → schedule → sleep → check
       └─ repair → repairGuard
            ├─ blocked → repairBlocked → repairReport → finish
-           └─ initialDesign: autoplan
+           └─ planChange
                 ├─ blocked → repairBlocked
-                └─ documentation: autodoc
+                └─ ready → implementation: autoimplement
                      ├─ blocked → repairBlocked
-                     ├─ no approval → implementation: autoimplement
-                     └─ approval: plan-approval
-                          ├─ stop → repairBlocked
-                          ├─ replan → initialDesign
-                          └─ continue → implementation: autoimplement
-                               ├─ blocked → repairBlocked
-                               └─ completed → check
+                     └─ completed → check
 ```
 
 - `prepare` is a `compute` node that validates and applies input defaults.
@@ -122,7 +116,7 @@ prepare
 - `report` is a `notify` node that queues exactly one report.
 - `decide` is a `compute` node that applies the route and check safety limit.
 - `repairGuard` stops a repeated issue when a completed repair did not change its fingerprint or observed target state.
-- `initialDesign`, `documentation`, optional `approval`, and `implementation` are included workflows. Replan returns exact operator text to initialDesign. Autoimplement can enter nested `autoplan`, then autodoc, when later evidence requires redesign.
+- `planChange` and `implementation` are included workflows. Plan change owns Autoplan, Autodoc, approval policy, and exact-text replanning. Autoimplement receives the selected plan without another decision and enters its own plan-change mount only when later evidence requires a changed plan.
 - `repairBlocked` and `repairReport` preserve a truthful blocked result and user notification.
 - `schedule` is a function `action` that publishes the next-check time.
 - `sleep` is the existing runtime-owned shell wait.
@@ -148,9 +142,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.
 
@@ -265,7 +265,7 @@ monitor
 
 `autoimplement` requires a clear existing plan, but the structured `plan` input is optional because the plan can already be in conversation context or canonical documentation. It blocks when it cannot find a clear plan. It skips autodoc when documentation is current and includes autodoc when documentation is missing or stale. The absence of `input.plan` never routes to initial autoplan.
 
-Autoimplement includes `autoplan` only as evidence-driven `redesign`. When implementation, verification, review, comments, or CI proves that the approach is wrong, the revised plan passes through autodoc before implementation resumes. Local bugs go to a fix step instead.
+Autoimplement includes the shared plan-change workflow only as evidence-driven `redesign`. When implementation, verification, review, comments, or CI proves that the approach is wrong, the shared workflow runs Autoplan, Autodoc, the configured plan decision, and bounded replanning before implementation resumes. Local bugs go to a fix step instead. Existing supplied or discovered plans bypass the decision.
 
 Review rounds record findings at every severity from P0 through P2. P0 or P1 findings require another implementation and review round. A P2-only round can be addressed, but the workflow does not run the reviewer again solely because P2 work changed files.
 
@@ -281,16 +281,17 @@ Monitor remains observation-only unless its input explicitly authorizes mutation
 
 ```text
 check
-  -> initialDesign: autoplan
-  -> documentation: autodoc
-  -> approval: plan-approval when requested
-       -> replan: initialDesign
+  -> planChange
+       -> autoplan
+       -> autodoc
+       -> plan-approval
+            -> replan: autoplan
   -> implementation: autoimplement
-       -> redesign: autoplan -> autodoc when needed
+       -> redesign: planChange when needed
   -> check
 ```
 
-The outer `autoplan` creates the first plan. Autodoc records it before implementation. An optional plan approval gate can continue, stop, or return exact replan instructions to autoplan. The inner redesign mount revises a plan only when new evidence invalidates it and records the revision through autodoc. The monitor checks the target again after implementation and does not trust a repair claim by itself.
+The shared plan-change workflow creates, records, and gates each repair plan. Its default policy asks the `operator` audience and continues after 10 minutes without an answer. Required mode waits for an explicit answer. Skip mode creates no decision. Monitor passes the selected plan into Autoimplement, so Autoimplement does not ask about that digest again. A later Autoimplement redesign uses the same shared workflow for the changed digest. The monitor checks the target again after implementation and does not trust a repair claim by itself.
 
 A protected change to model choice, benchmark method, credentials, hardware, spending authority, or another user decision exits as blocked. The workflow never changes the protected part of the task silently.
 
@@ -306,7 +307,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.
 

package/docs/plans/2026-08-13-session-addressed-workflow-notifications-plan.md

@@ -6,7 +6,7 @@ date: 2026-08-13
 
 # Route workflow reports to their starting session
 
-Pi Workflows must not send one workflow's report into an unrelated conversation. A workflow started in one Pi session must report only to that session, even when another session or the standalone host executes part of the run.
+pi-workflows must not send one workflow's report into an unrelated conversation. A workflow started in one Pi session must report only to that session, even when another session or the standalone host executes part of the run.
 
 ## Requirements