@osolmaz/pi-workflows 0.12.0 → 0.12.1

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

@@ -1,28 +1,48 @@
 ---
-title: Add the Sanity Check Workflow
+title: Run Sanity Check with Provider Extensions
 author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
 date: 2026-08-21
+updated: 2026-08-22
 ---
 
-# Add the Sanity Check Workflow
+# Run Sanity Check with Provider Extensions
 
 ## Goal
 
-Add a built-in `sanity-check` workflow that reviews a pull request or local contribution before implementation, approval, or merge. The review checks whether the change is needed, duplicates existing code, should use a simpler design, adds unnecessary data models or public plugin APIs, or has scope and test problems.
+Use direct Pi SDK sessions for the built-in `sanity-check` workflow. Each reviewer gets an independent in-memory context. Each child can load the extension that owns its exact configured model provider, while only the parent workflow action can control workflow state.
 
-The workflow runs its model work in temporary read-only Pi sessions. It does not put review prompts or model replies in the Pi session that started the workflow. The origin session receives the final report through a workflow notification that does not start another model turn.
+The child must use the configured provider, model, thinking level, and provider-owned authentication. It must fail before prompting if that exact dispatch is not available. It must never silently use OpenRouter, Kimi, a local model, or another fallback.
+
+The workflow keeps only the final bounded answer and safe operational facts. It does not keep child prompts, reasoning, message history, tool arguments, tool results, repository content, credentials, or extension-private state.
 
 ## Scope
 
-The change is limited to pi-workflows. It adds the built-in workflow, the smallest supporting code needed to run isolated read-only Pi sessions, workflow discovery and exports, documentation, unit tests, and real-Pi end-to-end coverage.
+The change is limited to Pi Workflows. It changes the private SDK agent-group runner, Sanity Check composition, extension admission, model runtime construction, tests, and canonical documentation.
+
+The workflow continues to use existing `action`, `compute`, and `notify` nodes. `src/workflows` and `WorkflowActionContext` remain Pi-independent. The change does not add a workflow primitive, public agent-group export, persisted schema, child workflow run, service, queue, store, transport, Pi core change, or private Pi API.
+
+Sanity Check keeps its existing input, review areas, prompts, evidence rules, session counts, strict result validation, verdicts, final notification, and progress schema.
+
+## Child session contract
 
-The workflow uses existing `action`, `compute`, and `notify` nodes. It does not add a workflow primitive, change a persisted schema, change Pi core, or change the Pi plugin SDK.
+Each child session:
 
-The child sessions can use only `read`, `grep`, `find`, and `ls`. They cannot edit files or run shell commands. They are temporary and do not write Pi session files.
+- has independent in-memory context and history;
+- uses `SessionManager.inMemory` and creates no Pi session file;
+- owns a separate `ModelRuntime`, provider instance, extension runtime, resource loader, and `AgentSession`;
+- can use only the verified built-in `read`, `grep`, `find`, and `ls` tools;
+- may load the extension that registers the exact configured provider;
+- may load another behavior extension only through an explicit private allowlist;
+- loads no skills, prompt templates, themes, or context files;
+- does not receive the workflow tool, workflow commands, parent run id, node id, attempt id, update channel, or workflow callback;
+- returns only bounded final assistant text and bounded safe lifecycle facts;
+- shares the parent Node process and does not provide OS process isolation.
 
-## Input
+Pi extensions are trusted in-process code. The runner prevents normal model, tool, command, and callback access to workflow state. It does not sandbox an extension that directly uses the filesystem or network.
 
-The workflow accepts a review mode and the base reference needed to inspect the current change. Serial mode is the default.
+## Input and review modes
+
+The workflow input stays unchanged. Serial mode remains the default.
 
 ```json
 {
@@ -31,118 +51,192 @@ The workflow accepts a review mode and the base reference needed to inspect the
 }
 ```
 
-`mode` is `serial` or `parallel`. The current repository and checked-out branch are the contribution under review. When `baseRef` is omitted, the workflow tries the remote default branch, the current branch upstream, and the first parent, then uses `HEAD` for a working-tree-only review. Pull request intent, linked issue context, and acceptance criteria are collected when they are available. The workflow also supports a local contribution with no pull request metadata.
+`mode` is `serial` or `parallel`. The current repository and checked-out branch are the contribution under review. When `baseRef` is omitted, the workflow tries the remote default branch, the current branch upstream, and the first parent, then uses `HEAD` for a working-tree-only review.
+
+Serial mode creates one review session for all four review areas, then one verification session. It uses two model sessions.
+
+Parallel mode creates four focused review sessions at the same time, then one verification session. It uses five model sessions.
+
+The agent-group runner enforces maximum concurrency and returns results in request order. A material failure stops queued work, aborts active siblings, waits for every started child to settle, and keeps the first failure as the primary cause.
 
-## Evidence
+## Evidence and results
 
 The first node collects facts without model judgment. It uses fixed, non-mutating commands to collect:
 
-- the pull request description and linked issue context when available;
+- pull request intent and linked issue context when available;
 - stated acceptance criteria;
-- the base and head revisions;
+- base and head revisions;
 - changed files;
 - the diff and diff statistics;
 - relevant new exports, schemas, persisted fields, and nearby existing code.
 
-Untrusted pull request and repository text is treated as evidence, not as workflow instructions. The evidence is bounded before it enters a model prompt or run bundle.
+Pull request and repository text is untrusted evidence, not instructions. Evidence and review inputs stay bounded before they enter a model prompt or run bundle.
 
-## Review modes
+The verification session receives the evidence and review results. It must remove unsupported claims, require exact file and symbol references, separate facts from assumptions, resolve supported conflicts, and place unresolved questions in `unknowns` or contributor questions. It returns `keep`, `simplify`, `refactor`, `drop`, or `needs_evidence`.
 
-### Serial mode
+The existing strict result parsers stay unchanged. They continue to enforce all review areas, evidence, acceptance case, verdict, string, and item limits.
 
-Serial mode starts one temporary review session. That session checks all four areas in order:
+## Provider-first extension profile
 
-1. Whether the change is needed.
-2. Duplication and refactoring opportunities.
-3. New data models and public plugin or SDK APIs.
-4. Scope and tests.
+The runner resolves one immutable child profile before it starts the group.
 
-The review session must give exact evidence and the strongest case for accepting the current design. A second temporary session verifies and combines the findings. Serial mode therefore uses two model sessions.
+### Resolve candidate paths
 
-### Parallel mode
+Use `SettingsManager` and `DefaultPackageManager.resolve()` to find enabled extension paths without executing extension factories. Canonicalize and deduplicate the paths.
 
-Parallel mode starts four temporary review sessions at the same time. Each session checks one area:
+The default candidate set contains enabled user-scope extensions. Project extensions are excluded unless the private policy admits them explicitly. Direct and wrapper paths for Pi Workflows are excluded before any extension factory runs.
 
-1. Whether the change is needed.
-2. Duplication and refactoring opportunities.
-3. New data models and public plugin or SDK APIs.
-4. Scope and tests.
+### Preflight provider ownership
 
-Each session must give exact evidence and the strongest case for accepting the current design. After all four sessions finish, one temporary session verifies and combines their findings. Parallel mode therefore uses five model sessions.
+Load candidate extensions in a no-session `DefaultResourceLoader` preflight. Pass the paths through `additionalExtensionPaths` and set `noExtensions: true` so the loader does not perform a second discovery pass.
 
-## Verification
+Inspect documented pending native and legacy provider registrations. Admit the one extension path that registers the exact configured provider. Permit other behavior extensions only through an explicit private allowlist.
 
-The final session receives the collected evidence and all review results. It must:
+Fail before session creation when:
 
-- remove claims that the evidence does not support;
-- require exact file and symbol references for repository claims;
-- separate facts from assumptions;
-- resolve conflicting findings when the evidence permits it;
-- place unresolved questions in the final `unknowns` or contributor questions;
-- return one of `keep`, `simplify`, `refactor`, `drop`, or `needs_evidence`.
+- no extension registers the configured provider;
+- more than one extension claims the configured provider;
+- an extension fails to load;
+- an admitted extension registers a reserved workflow tool or command;
+- an extension replaces `read`, `grep`, `find`, or `ls`;
+- a loaded path is outside the frozen candidate snapshot.
 
-There is no extra review loop. Missing product intent or unresolved evidence produces `needs_evidence` instead of an invented conclusion.
+Before invalidation, dispatch `session_shutdown` through a temporary public `ExtensionRunner` so factory-owned setup can clean up. Preflight does not create a session or dispatch `session_start`. Always invalidate the preflight extension runtime in `finally`.
 
-## Result
+Extension factories run before their registrations can be inspected. Pi documents that factories must not start background resources. Pi Workflows relies on that contract and does not claim to contain a factory that violates it.
 
-The accepted result contains a verdict, a short summary, findings with evidence, required changes, contributor questions, and unknowns. Findings cover necessity, duplication, data models, public APIs, scope, and tests.
+## Exact model dispatch
 
-The workflow formats the accepted result as a concise report and sends it to the origin session with `notify({ kind: "final" })`. The notification has `triggerTurn: false`, so the origin model does not restate the report.
+Resolve one immutable `{ provider, modelId, thinkingLevel }` value for the group. A complete explicit override wins. Otherwise, use the configured `SettingsManager` defaults. Reject partial overrides, missing defaults, unsupported thinking values, and prompts that start with an extension slash command.
 
-## Implementation
+Read and strictly validate the configured cached model catalog once. Keep it as an in-memory group snapshot. Create a deep-cloned in-memory model store for each child. Do the same for ordinary Pi credentials read from `auth.json`. Pi Workflows never writes these snapshots back.
 
-Add a built-in definition named `sanity-check` and register it in the built-in catalog and exports. The graph has these stages:
+Provider extensions use their existing provider-owned credential store in place. Pi Workflows does not copy, inspect, print, migrate, or persist those credentials.
 
-```text
-collect evidence
-      |
-run serial review or four parallel reviews
-      |
-verify and combine
-      |
-notify origin session
-```
+For each child:
+
+1. Create a fresh non-networked `ModelRuntime` from cloned snapshots.
+2. Create a fresh resource loader with only the frozen admitted extension paths.
+3. Disable secondary extension discovery, skills, prompt templates, themes, and context files.
+4. Load a fresh extension and provider instance.
+5. Find the exact cached model and pass it to `createAgentSession`.
+6. Pass the exact configured thinking level.
+7. Verify the session's actual provider, model, thinking level, authentication, extension state, active tools, and built-in tool sources.
+8. Start the prompt only after all checks pass.
+
+Any mismatch is terminal. The runner does not select another provider, model, or thinking level.
+
+A transient model selected only in the parent TUI is not inherited. The runner enforces the configured process default unless the private request gives a complete explicit dispatch.
+
+## Workflow authority boundary
+
+The parent Sanity Check action is the only workflow owner.
 
-The review nodes are function actions. The isolated runner starts Pi in non-interactive JSON mode with no saved session, no discovered extensions or skills, and only the read-only tools:
+Children receive only the built-in read-only tool instances requested by Sanity Check. Extension tools can register but remain inactive. The runner rejects same-name replacements for the built-in tools.
+
+Children receive no:
+
+- `workflow` tool;
+- `/workflow`, `/piw`, `/controller`, or workflow-channel command;
+- run, node, or attempt identifier;
+- workflow update, answer, submit, pause, resume, or cancel callback;
+- child workflow run or parent workflow handle.
+
+The runner rejects prompts that would invoke extension slash commands. These controls prevent the normal child model and admitted extension bindings from inspecting or changing workflow state.
+
+## Lifecycle and privacy
+
+One owner controls each child from creation through cleanup.
+
+The owner:
+
+1. Creates the child runtime and session.
+2. Subscribes before prompting.
+3. Emits only bounded safe lifecycle phases.
+4. Waits for prompt settlement.
+5. Extracts only the latest final assistant text.
+6. Bounds the returned text before validation.
+7. Calls and awaits `abort()` on timeout or cancellation.
+8. Waits for prompt settlement after abort.
+9. Unsubscribes.
+10. Disposes the session so extension shutdown runs.
+11. Invalidates remaining extension runtime state.
+12. Releases provider resources.
+
+Cleanup runs for success, creation failure, authentication failure, provider failure, malformed output, timeout, parent cancellation, sibling failure, and disposal failure. A cleanup failure remains a bounded secondary diagnostic and does not replace an earlier primary error.
+
+The workflow never copies extension events or extension-private state into progress or run bundles.
+
+## Progress and visibility
+
+Sanity Check keeps the existing `pi-workflows.progress.v1` records and keys:
 
 ```text
---mode json
---print
---no-session
---no-extensions
---no-skills
---no-context-files
---tools read,grep,find,ls
+agents/review
+agents/review/necessity
+agents/review/duplication
+agents/review/contracts
+agents/review/scope_tests
+agents/verification
+agents/verification/verification
 ```
 
-Serial mode starts one combined review and then one verification session. Parallel mode starts the four focused reviews concurrently, waits for all of them, and then starts one verification session. Cancellation and timeout stop every affected child process. Output and error text are bounded. Serialized evidence and review results are also bounded before prompt construction, with an explicit truncation marker when the full input does not fit.
+Aggregate tracks report completed and total sessions. Child tracks report a bounded role label, the verified actual model when known, and a safe phase such as `starting`, `thinking`, `tool: read`, `finalizing`, or a terminal phase.
 
-The workflow validates its input and every model result. A missing child result, failed child process, malformed result, cancellation, or timeout fails the active action with a clear bounded error.
+Updates are deduplicated, throttled, and observational. They cannot change agent execution.
 
-## Documentation
+The Pi widget shows the aggregate plus failed and active children within its ten-line limit. `piw` shows all durable child tracks and samples. Both views use existing progress records. No new persisted field or schema is added.
 
-Add `sanity-check` to the built-in workflow list and document its input, review modes, read-only session boundary, result, and notification behavior in `docs/workflows.md`. Keep this plan as the record of the selected implementation.
+## Implementation plan
 
-## Tests
+1. Update the Pi SDK development baseline to one compatible 0.84.x release. Keep the Pi coding-agent, Pi AI, and Pi TUI packages aligned and set an honest peer compatibility floor. Do not add Pi Factory or a provider extension as a dependency.
+2. Add the private dispatch and child extension profile contracts under `src/builtins`. Do not export them from package entry points.
+3. Resolve enabled extension paths without execution. Canonicalize paths, exclude project extensions by default, and exclude direct and wrapper Pi Workflows paths.
+4. Add the no-session extension preflight. Identify the exact native or legacy provider owner and reject reserved workflow capabilities, provider conflicts, load errors, and built-in tool overrides.
+5. Keep the model-catalog snapshot work, but change it to one validated group snapshot and one clone per child. Add the same ownership for ordinary Pi credentials. Remove the previous empty-catalog behavior.
+6. Replace the shared group `ModelRuntime` with one complete runtime per child.
+7. Verify exact provider, model, thinking, authentication, admitted extensions, active tools, and tool sources before every prompt.
+8. Complete provider, extension, and session cleanup on every exit path.
+9. Pass the private profile and exact dispatch through Sanity Check without changing its review behavior or progress schema. Remove any `--no-extensions` launch guidance.
+10. Change the built-in Sanity Check revision from 2 to 3.
+11. Add temporary fixture extensions and full unit, integration, interactive Pi, and standalone host coverage.
+12. Update this plan and `docs/workflows.md` to match the shipped behavior.
+13. Run the complete repository gate and inspect the full public diff.
+14. After mock-provider verification, run one bounded real acceptance on OpenClaw pull request 126028 with `openai-codex/gpt-5.6-sol` and high thinking. Abort immediately if any child reports another provider or model. Do not modify OpenClaw.
 
-Unit tests must cover:
+## Revision and compatibility
 
-- input validation and the serial default;
-- serial mode starting exactly one review session and one verification session;
-- parallel mode starting exactly four concurrent review sessions and one verification session;
-- the four required review areas;
-- the acceptance case and evidence requirements in every review prompt;
-- read-only child tool arguments and disabled session, extension, and skill discovery;
-- structured result validation and all five verdicts;
-- unsupported and conflicting finding handling in the verification prompt;
-- bounded output and error handling;
-- child failure, malformed output, timeout, cancellation, and process cleanup;
-- final notification delivery without a model turn;
-- built-in discovery and export behavior.
+Sanity Check moves from built-in revision 2 to revision 3.
 
-The real-Pi end-to-end test must use the repository test provider. It must not call a real model or make destructive changes.
+This is an alpha hard cutover. Do not retain the revision-2 child runtime, fallback, compatibility runner, migration, alias, dual path, or feature flag. An unfinished revision-2 run must fail with clear cancel-and-restart guidance. Terminal revision-2 bundles remain readable historical evidence because the persisted schema does not change.
 
-Before completion, run all checks required by `AGENTS.md`:
+## Tests
+
+Unit and integration tests must cover:
+
+- dispatch parsing and exact provider, model, and thinking enforcement;
+- missing authentication and no fallback;
+- extension path resolution, canonicalization, scope filtering, disabled paths, and explicit behavior paths;
+- direct and wrapper Pi Workflows exclusion;
+- native and legacy provider-owner discovery;
+- reserved workflow command and tool rejection;
+- inactive extension tools and built-in tool override rejection;
+- per-child runtime, provider, extension, loader, and history isolation under parallel execution;
+- validated model and credential snapshots, deep clones, cancellation, malformed input, and no writes;
+- provider-owned mock authentication without credential exposure;
+- success, provider error, empty output, malformed output, oversized output, timeout, cancellation, fail-fast, and cleanup-error precedence;
+- final-only retention and absence of private child content in results, errors, updates, and bundles;
+- serial two-session and parallel five-session behavior;
+- existing progress keys, model labels, throttling, and rendering;
+- interactive Pi with normal extensions enabled and the local mock provider;
+- standalone `WorkflowHost` through the same private runtime path;
+- no child session files or child workflow runs;
+- built-in revision 3 and historical terminal bundle reading;
+- final notification without another model turn.
+
+Tests use mock providers and temporary directories. They do not call real models or write outside temporary directories.
+
+Before completion, run:
 
 ```bash
 npm run check
@@ -151,25 +245,39 @@ npx slophammer-ts@latest dry .
 npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
 ```
 
+After these checks and Pi Reviewer pass, perform the one explicitly authorized bounded GPT-5.6 Sol acceptance run.
+
 ## Acceptance criteria
 
 The implementation is complete when:
 
-- `/workflow sanity-check` discovers and starts the built-in workflow;
-- omitted mode selects serial mode;
-- serial mode uses two temporary model sessions;
-- parallel mode uses five temporary model sessions, with the four review sessions running concurrently;
-- child sessions have only read-only repository tools and create no session files;
-- both modes cover all required review questions and the case for accepting the design;
-- final verification rejects unsupported claims and requires exact repository evidence;
-- the final verdict is one of the five selected values;
-- the origin session receives the report without another model turn;
-- documentation and all required checks pass.
+- `/workflow sanity-check` discovers built-in revision 3;
+- the parent Pi process runs with its normal configured extensions;
+- serial mode uses two independent in-memory SDK sessions;
+- parallel mode uses five independent in-memory SDK sessions, with four reviews running concurrently;
+- every child loads the extension that owns the exact configured provider;
+- every child reports the exact required provider, model, and thinking level before prompting;
+- no child silently falls back to OpenRouter, Kimi, a local model, or another dispatch;
+- children use only verified built-in read-only tools and create no session files;
+- children cannot use normal workflow tools, commands, identifiers, or callbacks;
+- the workflow keeps only bounded final answers and safe operational facts;
+- child prompts, reasoning, tool payloads, histories, credentials, and extension state do not enter run bundles or progress updates;
+- provider, extension, and session cleanup completes on every exit path;
+- Sanity Check review behavior, strict validation, verdicts, progress, and final notification remain unchanged;
+- interactive and headless runs use the same private SDK path;
+- all required checks pass with coverage margin;
+- the bounded acceptance run on OpenClaw pull request 126028 reports GPT-5.6 Sol for every child and completes with a strict verdict without modifying OpenClaw.
 
 ## Contract impact
 
 - **Origin session:** The normal workflow start record and one final workflow notification.
-- **Other persistent data:** The normal workflow run bundle only. Child Pi sessions are not saved.
-- **Pi internals:** None.
-- **Pi public API:** Existing documented CLI and extension behavior only.
-- **Pi Workflows public API:** Existing workflow definitions and `action`, `compute`, and `notify` nodes only.
+- **Parent extensions:** The parent Pi process loads its normal configured extensions.
+- **Child extensions:** Only the exact provider owner and explicit private behavior paths are admitted.
+- **Child sessions:** Independent in-memory contexts and complete per-child runtimes in the same Node process. No child session file or child workflow run.
+- **Model dispatch:** Exact provider, model, and thinking are required. Fallback is forbidden.
+- **Credentials:** Pi Workflows does not copy or persist credentials. Provider extensions use their existing stores in place.
+- **Other persistent data:** The normal workflow run bundle and existing progress updates only.
+- **Private content:** Prompts, reasoning, intermediate messages, tool payloads, histories, credentials, and extension-private state are not persisted by Pi Workflows.
+- **Pi public API:** Documented package manager, resource loader, extension and provider registration, model runtime, session, event, abort, and disposal APIs only.
+- **Pi Workflows public API:** No change.
+- **Isolation:** Workflow capability is withheld from normal child bindings. Arbitrary trusted in-process extension code is not sandboxed.

package/docs/run-bundles.md

@@ -40,18 +40,18 @@ Human decision records use a separate additive directory next to `runs/` so a wa
     request.json
     deliveries/<channel>/<attempt-id>.json
     answers/<attempt-id>.json
-    resolution.json # atomic accepted-or-cancelled fence
-    accepted.json
-    cancelled.json   # present only when a pending request is cancelled or expires
+    resolution.json # atomic resolved-or-cancelled fence
+    accepted.json    # human or timeout response with explicit provenance
+    cancelled.json   # terminal cancellation tombstone
     settlements/<channel>/<attempt-id>.json
     continuation.json
 ```
 
-The request links to the waiting run, node, attempt, workflow source, and canonical request digest. A v2 request stores the canonical subject and a separate normalized operator presentation. Its subject, presentation, revision, choices, and input prompts are bound to the request digest. V2 accepted records and redacted continuation receipts preserve the subject and presentation digests. Final records use no-replace creation and adopt only identical retries. `resolution.json` is the first accepted-or-cancelled fence. It materializes either `accepted.json` or the mutually exclusive `cancelled.json`; a crash can rebuild that detail from the resolution. `continuation.json` binds an accepted answer to one deterministic continuation run. Delivery and settlement records cannot change the accepted answer.
+The request links to the waiting run, node, attempt, workflow source, and canonical request digest. The single v1 request stores the canonical subject and a separate normalized operator presentation. Its subject, presentation, revision, choices, input prompts, optional deadline, and optional automatic response are bound to the request digest. Accepted records and redacted continuation receipts preserve the subject and presentation digests and state `human` or `timeout` provenance. A timeout record has no human source. Final records use no-replace creation and adopt only identical retries. `resolution.json` is the first resolved-or-cancelled fence. It materializes either `accepted.json` or `cancelled.json`; a crash can rebuild that detail from the resolution. A cancellation tombstone prevents later automatic continuation. `continuation.json` binds one resolved response and its provenance to one deterministic continuation run. Delivery and settlement records cannot change the result. Older human-decision record shapes are incompatible alpha state and require reset; there is no migration reader.
 
 Telegram multipart delivery uses additive v2 delivery records for the overall intent, each part, and completion. Part records contain only recipient indexes, part indexes, counts, and content digests. Telegram chat and message IDs remain in the private disposable channel projection and never enter run or decision bundles. An ambiguous part remains unknown and is not retried blindly.
 
-A human-decision continuation preserves the parent's original workflow input and replaces the carried checkpoint output with the accepted typed response for routing. Its `humanDecision` state is a redacted receipt. A v2 receipt includes the subject digest, presentation digest, and revision, but not the subject itself. Verified actor, channel, event, and idempotency provenance remains in the private sibling decision records and is not copied into the run bundle. Ordinary checkpoint continuations keep using the answer as the continuation input. Existing bundles without human decision data remain valid. V1 requests and their original digests are never rewritten.
+A human-decision continuation preserves the parent's original workflow input and replaces the carried checkpoint output with the resolved typed response for routing. Its `humanDecision` state is a redacted receipt with `human` or `timeout` provenance. A v2 receipt includes the subject digest, presentation digest, and revision, but not the subject itself. Verified human actor, channel, event, and idempotency details remain in the private sibling decision records and are not copied into the run bundle. Ordinary checkpoint continuations keep using the answer as the continuation input. This alpha contract changes current v1 and v2 field sets in place; old active definitions refuse resume instead of using a compatibility path.
 
 Run ids are `<UTC timestamp>-<workflow slug>-<8 hex chars>`, so lexical order
 is chronological order.
@@ -185,7 +185,7 @@ validators are not serialized. Each node keeps only its metadata (`nodeType`,
 `timeoutMs`, `statusDetail`, `expectedOutput`, `summary`, `actionExecution`),
 and edges are copied verbatim. A fixed `timeoutMs: null` is preserved and means
 that the node has no wall-clock deadline. Timeout callbacks remain omitted.
-Included nodes also record `mountPath`, `localNodeId`, and internal entry or exit status. The top-level `composition.mounts` list records every mount, entry, named exit, and child step limit. The snapshot is what lets viewers draw all nodes, including ones that have not run yet. It is immutable after run start.
+A human-decision snapshot records fixed `onTimeout` duration and response values. A dynamic timeout callback is omitted and marked as dynamic. Included nodes also record `mountPath`, `localNodeId`, and internal entry or exit status. The top-level `composition.mounts` list records every mount, entry, named exit, and child step limit. The snapshot is what lets viewers draw all nodes, including ones that have not run yet. It is immutable after run start.
 
 ## Resume and repair
 

package/docs/workflows.md

@@ -291,6 +291,10 @@ const choices = defineHumanChoices({
 humanDecision({
   audience: "operator",
   choices,
+  onTimeout: {
+    afterMs: 10 * 60_000,
+    response: { choice: "continue" },
+  },
   request: ({ outputs }) => ({
     title: "Approve plan",
     subject: outputs.plan,
@@ -303,7 +307,7 @@ humanDecision({
 });
 ```
 
-The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, and input prompts. The first valid verified human answer wins. A continuation preserves the original workflow input and exposes the accepted answer as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. Existing `body` requests remain a legacy compatibility form and use deterministic readable formatting.
+The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, input prompts, and any deadline policy. The first valid verified human answer wins. When `onTimeout` is present and no human answer wins before the saved deadline, recovery applies the validated response with `timeout` provenance. This policy can continue without a configured channel. A continuation preserves the original workflow input and exposes the resolved response as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. Existing `body` requests remain a legacy compatibility form and use deterministic readable formatting.
 
 The model-facing workflow tool cannot answer a protected human decision. Pi interactive UI and configured external channels use a host-owned answer path. Ordinary checkpoints keep the existing `/workflow answer` behavior.
 
@@ -417,7 +421,9 @@ runs.
 
 The built-in `autoplan` workflow selects a practical in-scope solution and writes a detailed plan. The standalone `autodoc` workflow finds an already selected plan, records it in canonical documentation, verifies those documents, and never devises or implements. The built-in `autoimplement` workflow finds a clear existing plan from explicit input, conversation context, or referenced canonical documents. It blocks when no clear plan exists. An explicit plan bypasses autodoc only when a current-document receipt carries its matching plan digest; otherwise autodoc inspects and adopts or updates the canonical documents. Later invalidating evidence returns to `autoplan` followed by `autodoc`.
 
-The built-in `plan-approval` workflow offers verified human `continue`, `stop`, and exact-text `replan` exits. It is optional. A replan exit returns the unchanged text to autoplan, documents the revised plan, and asks again through a new plan digest.
+The built-in `plan-approval` workflow offers `continue`, `stop`, and exact-text `replan` exits. Its shared policy uses `auto`, `required`, or `skip` mode. Omitted policy defaults to `auto`: ask audience `operator`, then continue with the exact plan after 10 minutes without an answer. Required mode waits for a human. Skip mode creates no decision. Stop and replan always require a human answer.
+
+The internal plan-change workflow composes Autoplan, Autodoc, plan approval, and bounded replanning. Autoimplement and Monitor use it whenever they create or change a plan. Existing supplied or discovered plans bypass the gate. A plan selected by Monitor enters Autoimplement without another decision for the same digest.
 
 Autoimplement runs independent commands through bounded command batches. A batch is an ordinary function action that calls the public `runCommandBatch` helper. Each command has a stable ID, executable, arguments, absolute working directory, timeout, and output limit. Results stay separate and return in input order. One command uses the same path with concurrency one.
 
@@ -453,11 +459,25 @@ The built-in `sanity-check` workflow reviews a pull request or local contributio
 }
 ```
 
-Serial mode is the default. It runs one temporary read-only Pi session for all four review areas, then one temporary session to verify and combine the findings. Parallel mode runs four focused review sessions at the same time, then one verification session. Serial mode uses two model sessions. Parallel mode uses five. When `baseRef` is omitted, the workflow tries the remote default branch, the current branch upstream, and the first parent, then uses `HEAD` for a working-tree-only review.
+Serial mode is the default. It runs one review session for all four review areas, then one verification session. Parallel mode runs four focused review sessions at the same time, then one verification session. Serial mode uses two model sessions. Parallel mode uses five. When `baseRef` is omitted, the workflow tries the remote default branch, the current branch upstream, and the first parent, then uses `HEAD` for a working-tree-only review.
+
+The workflow collects pull request intent and repository diff evidence before model review. It bounds evidence and review results before prompt construction and marks truncated input. Every review must cite evidence and give the strongest case for accepting the current design. The verification session removes unsupported claims, requires exact file and symbol references, resolves supported conflicts, and returns `keep`, `simplify`, `refactor`, `drop`, or `needs_evidence`.
+
+Sanity Check revision 3 creates child sessions directly through the documented Pi SDK. A private built-in runner uses `createAgentSession` with `SessionManager.inMemory`, one independent context per child, and only the verified built-in `read`, `grep`, `find`, and `ls` tools. Child sessions load no skills, prompt templates, themes, or context files. They create no Pi session file.
+
+The parent Pi process keeps its normal configured extensions enabled. The child runner resolves enabled user extension paths, excludes Pi Workflows and project extensions by default, and preflights the remaining paths without creating a session. It admits only the extension that registers the exact configured provider, plus any behavior extension on an explicit private allowlist. It rejects competing provider owners, workflow tools or commands, and extensions that replace a built-in read-only tool. The admitted paths are frozen for the group, and each child loads only those explicit paths without a second discovery pass.
+
+Each child owns a separate `ModelRuntime`, provider instance, extension runtime, resource loader, and in-memory session. The runner loads validated model and ordinary credential snapshots into per-child in-memory stores without writing them back. A provider extension uses its existing provider-owned credential store in place; Pi Workflows does not copy, print, migrate, or persist those credentials.
+
+A complete explicit provider, model, and thinking override wins. Otherwise, the runner uses the configured process defaults. It passes the exact cached model and thinking level to the child, then verifies the actual provider, model, thinking level, authentication, extension state, active tools, and tool sources before prompting. A missing or different dispatch is terminal. The runner never silently falls back to OpenRouter, Kimi, a local model, or another provider or model. It does not promise to inherit a model selected temporarily in the origin Pi TUI.
+
+Children do not receive the `workflow` tool, workflow commands, parent run identifiers, update channels, or workflow callbacks. Prompts that invoke extension slash commands are rejected. The parent Sanity Check action remains the only workflow owner. These controls block normal child model and extension bindings from inspecting or changing workflow state. Extensions still run as trusted code in the parent Node process, so this is not an OS sandbox against direct filesystem or network access.
+
+Only bounded final assistant text and safe operational facts leave a live child session. Pi Workflows does not persist child prompts, reasoning, intermediate messages, tool arguments, tool results, message history, credentials, or extension-private state. Timeout and cancellation abort and settle active work before the runner disposes the session, shuts down extensions, and releases provider resources.
 
-The workflow collects pull request intent and repository diff evidence before model review. It bounds serialized evidence and review results before prompt construction and marks truncated input. Every review must cite evidence and give the strongest case for accepting the current design. The verification session removes unsupported claims, requires exact file and symbol references, resolves supported conflicts, and returns `keep`, `simplify`, `refactor`, `drop`, or `needs_evidence`.
+The workflow publishes aggregate and per-agent `pi-workflows.progress.v1` tracks under `agents/review/*` and `agents/verification/*`. Progress contains role, the verified actual model when known, state, elapsed facts, and safe phases such as `thinking` or `tool: read`. The Pi widget shows the aggregate plus failed and active children within its ten-line limit. `piw` shows every durable child track and its samples. Both views use existing progress records, so no child workflow run or new persisted schema is needed.
 
-Child sessions have only `read`, `grep`, `find`, and `ls`. They do not load discovered extensions, skills, or repository context files, cannot mutate the repository, and do not save Pi session files. The workflow sends the final report through a final notification with `triggerTurn: false`, so the origin model does not produce another response. See [the Sanity Check plan](plans/2026-08-21-sanity-check-plan.md) for the selected implementation and test boundaries.
+Serial mode still uses two sessions, and parallel mode still uses five. Prompts, review areas, strict result validation, verdicts, and final notification stay unchanged. The workflow sends the final report through a final notification with `triggerTurn: false`, so the origin model does not produce another response. The CLI, JSON or RPC stream, temporary prompt file, standard-output cap, subprocess fallback, shared child runtime, and blanket child-extension ban are not retained. See [the Sanity Check plan](plans/2026-08-21-sanity-check-plan.md) for the selected implementation and test boundaries.
 
 ### Built-in monitor
 
@@ -475,7 +495,7 @@ one looping workflow run. Its input is:
 }
 ```
 
-The first check runs immediately. Omit `repair` for observation-only monitoring. An authorized repair routes through outer `autoplan`, `autodoc`, optional `plan-approval`, `autoimplement`, and internal redesign before the monitor checks the target again. A repeated issue with unchanged target evidence stops as blocked. Add `repair.approval` with a named audience and bounded replan limit only when the operator wants a human decision before implementation.
+The first check runs immediately. Omit `repair` for observation-only monitoring. An authorized repair routes through the shared plan-change workflow, Autoimplement, and a fresh check. A repeated issue with unchanged target evidence stops as blocked. Omit `repair.approval` for the 10-minute autonomous default. Use `approval.mode: "required"` to wait for an explicit answer or `approval.mode: "skip"` to continue without asking.
 
 `everyMinutes` defaults to 30. Each accepted check must provide one concise report and choose `continue`, `repair` when authorized, or `stop`. The
 runtime queues that report as a workflow notification with `triggerTurn:

package/examples/workflows/approved-plan.workflow.ts

@@ -1,58 +1,31 @@
-import { compute, defineWorkflow, includeWorkflow, includedResult } from "@osolmaz/pi-workflows";
-import autodoc from "../../src/builtins/autodoc.workflow.js";
-import autoplan from "../../src/builtins/autoplan.workflow.js";
-import planApproval from "../../src/builtins/plan-approval.workflow.js";
+import { compute, defineWorkflow, includeWorkflow } from "@osolmaz/pi-workflows";
+import planChange from "../../src/builtins/plan-change.workflow.js";
 
 export default defineWorkflow({
   name: "approved-plan-example",
-  startAt: "design",
-  maxSteps: 80,
+  startAt: "start",
+  maxSteps: 100,
   includes: {
-    design: includeWorkflow(autoplan, {
-      input: ({ input, outputs }) => {
-        const prior = outputs.design as { exit?: string; output?: { plan?: unknown } } | undefined;
-        const answer = outputs.approval as
-          | { exit?: string; output?: { instructions?: string } }
-          | undefined;
-        return {
-          problem: (input as { task: string }).task,
-          ...(prior?.exit === "ready" ? { previousPlan: prior.output?.plan } : {}),
-          ...(answer?.exit === "replan" ? { newEvidence: answer.output?.instructions } : {}),
-        };
-      },
-    }),
-    documentation: includeWorkflow(autodoc, {
-      input: ({ input, outputs }) => {
-        const result = includedResult(autoplan, outputs.design);
-        if (result.exit !== "ready") throw new Error("design is not ready");
-        return { task: (input as { task: string }).task, plan: result.output.plan };
-      },
-    }),
-    approval: includeWorkflow(planApproval, {
-      input: ({ input, outputs }) => {
-        const result = includedResult(autodoc, outputs.documentation);
-        if (result.exit !== "ready") throw new Error("documentation is not ready");
-        return {
-          task: (input as { task: string }).task,
-          plan: result.output.plan,
-          planDigest: result.output.planDigest,
+    planChange: includeWorkflow(planChange, {
+      input: ({ input }) => ({
+        task: (input as { task: string }).task,
+        approval: {
+          mode: "auto" as const,
           audience: "operator",
-        };
-      },
+          timeoutMinutes: 10,
+          maxReplans: 3,
+        },
+      }),
     }),
   },
   nodes: {
-    done: compute({ run: ({ outputs }) => ({ status: "approved", approval: outputs.approval }) }),
-    stopped: compute({ run: ({ outputs }) => ({ status: "stopped", approval: outputs.approval }) }),
-    blocked: compute({ run: ({ outputs }) => ({ status: "blocked", outputs }) }),
+    start: compute({ run: () => ({ route: "plan" }) }),
+    done: compute({ run: ({ outputs }) => ({ status: "ready", plan: outputs.planChange }) }),
+    blocked: compute({ run: ({ outputs }) => ({ status: "blocked", plan: outputs.planChange }) }),
   },
   edges: [
-    { from: "design.ready", to: "documentation" },
-    { from: "design.blocked", to: "blocked" },
-    { from: "documentation.ready", to: "approval" },
-    { from: "documentation.blocked", to: "blocked" },
-    { from: "approval.continue", to: "done" },
-    { from: "approval.stop", to: "stopped" },
-    { from: "approval.replan", to: "design" },
+    { from: "start", to: "planChange" },
+    { from: "planChange.ready", to: "done" },
+    { from: "planChange.blocked", to: "blocked" },
   ],
 });

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.12.0"
+version = "0.12.1"
 min_herdr_version = "0.7.0"
 description = "Open the active pi-workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]