@osolmaz/pi-workflows 0.11.2 → 0.12.1

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

@@ -0,0 +1,322 @@
+---
+title: Plan Change Approval Policy Plan
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-21
+---
+
+# Plan change approval policy plan
+
+## Summary
+
+Autoimplement and Monitor must use one shared workflow whenever they create or revise a plan. The shared workflow plans, records the plan in canonical documentation, asks for the configured human decision, and handles bounded replanning.
+
+The default policy is autonomous. It asks the `operator` audience to continue, stop, or replan. If no valid answer is accepted within 10 minutes, it continues with the exact presented plan. A required policy waits for an explicit answer. A skip policy continues immediately without creating a human decision.
+
+The timeout default belongs to the general `humanDecision()` contract. It must be durable, deterministic, bound to the exact request and plan digest, and separate from a human answer. Autoimplement and Monitor must not contain their own decision timers or copies of approval and replan logic.
+
+## Goals
+
+The change must provide these results:
+
+- Every plan newly created or changed by Autoimplement or Monitor passes through one shared plan-change workflow.
+- Existing supplied or discovered plans do not receive a new decision.
+- The default policy asks for a decision and continues after 10 minutes when there is no answer.
+- Operators can require an explicit answer or skip the decision.
+- Pi and Telegram show and settle the same durable decision.
+- A human answer, timeout default, and cancellation cannot create more than one continuation.
+- Cancellation remains immediate and terminal.
+- Repeated entry with the same plan digest does not create another decision.
+- Monitor does not cause Autoimplement to ask again for the plan that Monitor already selected.
+
+## Approval policy
+
+Autoimplement and Monitor use the same policy shape:
+
+```ts
+type PlanApprovalPolicy = {
+  mode: "auto" | "required" | "skip";
+  audience?: string;
+  timeoutMinutes?: number;
+  maxReplans?: number;
+};
+```
+
+The workflow input field remains `approval`. When it is absent, parsing supplies this policy:
+
+```json
+{
+  "mode": "auto",
+  "audience": "operator",
+  "timeoutMinutes": 10,
+  "maxReplans": 3
+}
+```
+
+The modes have these meanings:
+
+- `auto` creates a human decision. It continues with the presented plan when no valid answer is accepted before the deadline.
+- `required` creates a human decision with no automatic response. It waits for `continue`, `stop`, or `replan`.
+- `skip` creates no human decision and continues immediately.
+
+`audience` defaults to `operator`. `timeoutMinutes` applies only to `auto` and defaults to 10. `maxReplans` defaults to 3 and bounds the exact-instructions replan loop. Parsers reject unknown fields, unsupported combinations, non-positive timeouts, and invalid replan limits.
+
+The skills must map common requests as follows:
+
+```json
+{
+  "approval": {
+    "mode": "required"
+  }
+}
+```
+
+Use this for requests such as “block on plan changes.”
+
+```json
+{
+  "approval": {
+    "mode": "skip"
+  }
+}
+```
+
+Use this for requests such as “do not block on plan changes.” Omitting `approval` uses the 10-minute autonomous default.
+
+## Shared plan-change workflow
+
+Add one internal finite workflow that owns this sequence:
+
+```text
+autoplan
+  -> autodoc
+  -> plan-approval
+       -> continue -> ready
+       -> stop -> blocked
+       -> replan -> autoplan
+```
+
+The workflow receives the planning problem, scope, constraints, repository and document context, previous plan, new evidence, and approval policy. It returns either:
+
+- `ready`, with the selected plan, plan digest, canonical documents, revision, and decision provenance; or
+- `blocked`, with the reason and evidence.
+
+The workflow owns the replan count and passes exact operator instructions back to Autoplan. Each changed plan gets a new positive revision. The plan digest binds the plan, documentation result, approval request, and final output.
+
+The workflow bypasses the human-decision node in `skip` mode but still records `skipped` as the plan selection provenance. It does not create a synthetic human receipt.
+
+Promote the existing approved-plan composition pattern into this internal built-in workflow. Keep `plan-approval` as the low-level reusable decision workflow. Do not add a standalone `plan-approval` skill.
+
+## Human-decision timeout default
+
+Extend the public `humanDecision()` definition with a general optional timeout response:
+
+```ts
+humanDecision({
+  audience: "operator",
+  choices,
+  request,
+  onTimeout: {
+    afterMs: 10 * 60_000,
+    response: { choice: "continue" },
+  },
+});
+```
+
+The policy may also be derived from the node context so the shared plan-change workflow can use its parsed input. `afterMs` must be a positive finite duration. The response must satisfy the same typed choice and input contract as a human response. An absent `onTimeout` keeps the current indefinite wait.
+
+When the engine creates the request, it computes and persists:
+
+- the absolute expiry time;
+- the validated default response;
+- the request and presentation digests;
+- the exact node and attempt identity; and
+- the plan digest and revision already present in the decision subject.
+
+The request digest includes the deadline policy and default response. A changed deadline, response, plan, or revision therefore creates a different request identity.
+
+## Resolution and provenance
+
+A timeout default is an automatic workflow-policy resolution. It is not a human answer and must not use a human actor or channel identity.
+
+The existing resolution record gains a distinct timeout-default outcome and provenance in place. Human acceptance, timeout default, and cancellation all compete for the same immutable resolution record. The first valid resolution wins. The accepted workflow output states whether the result came from:
+
+- `human`;
+- `timeout`;
+- `skipped`; or
+- `cancelled`, where a terminal record is exposed.
+
+A human answer is valid only before the deadline and while no terminal resolution exists. A late answer cannot replace a timeout default. A timeout resolver must re-read an existing resolution and adopt it rather than create another result.
+
+The plan-approval continue result carries the plan digest, decision revision, response, and resolution provenance. A timeout result carries no human actor. A skipped result carries no human-decision receipt.
+
+## Recovery and ownership
+
+Use the existing one-second human-decision recovery loop. Do not add a service, daemon, controller, or second timer system.
+
+For an unresolved request with an eligible timeout default, the current owner must:
+
+1. confirm that the parent run is still waiting at the same request;
+2. confirm that the request deadline has passed;
+3. confirm that the run and decision are not cancelled;
+4. atomically write or adopt the timeout-default resolution;
+5. create or adopt the deterministic continuation record;
+6. start the continuation only when the owning process can claim it; and
+7. settle every open Pi and Telegram view.
+
+If no owner is active at the deadline, the request becomes eligible at that time. The next active owner resolves it and starts or adopts the continuation. The saved absolute deadline means a restart does not restart the 10-minute period.
+
+Auto mode must continue after the deadline even when no decision channel is configured. Required mode remains waiting and reports the missing channel configuration. Skip mode does not use a channel.
+
+## Cancellation and races
+
+Explicit workflow cancellation remains terminal. It must cancel the waiting decision, close channel views, and prevent a timeout continuation.
+
+The cancellation path and timeout resolver must check the durable run cancellation state before and after claiming the decision resolution and before starting a continuation. If cancellation races with an automatic resolution, the cancelled run and its deterministic continuation must not execute more workflow nodes. A later recovery pass must not revive either run.
+
+A human answer and timeout default use the immutable resolution as their race boundary. Tests must cover both winners at the deadline boundary and prove that only one continuation can exist.
+
+## Autoimplement integration
+
+Autoimplement must use the shared plan-change workflow only for a changed plan produced by its internal redesign route.
+
+These plans bypass the gate:
+
+- an explicit plan supplied in the Autoimplement input;
+- a current plan found by plan discovery; and
+- a plan passed by Monitor after Monitor completed the shared plan-change workflow.
+
+When new evidence routes Autoimplement to redesign, the shared workflow receives the current plan as `previousPlan` and the new issue as evidence. A changed ready plan returns to implementation. A stopped or exhausted plan change returns blocked. The same digest must not create another decision after resume or route re-entry.
+
+Remove Autoimplement’s duplicate approval route, approval input mapping, and replan guard. Keep only policy parsing and the mapping into the shared workflow.
+
+## Monitor integration
+
+Each Monitor repair that requires a new plan enters the shared plan-change workflow. This includes every exact-instructions replan requested by the operator.
+
+A ready plan is passed to Autoimplement with its plan digest and canonical documentation state. Autoimplement treats it as selected and does not ask about it again. If Autoimplement later produces a changed plan because of implementation, review, or CI evidence, Autoimplement uses the shared workflow for that new digest.
+
+Remove Monitor’s duplicate approval route, plan-approval input mapping, and replan guard. Keep the monitor repair authorization, no-progress protection, and post-repair observation unchanged.
+
+## Skills and examples
+
+Update the Autoimplement and Monitor skills with complete one-shot calls for:
+
+- omitted approval, which uses the 10-minute autonomous default;
+- `approval.mode: "required"`; and
+- `approval.mode: "skip"`.
+
+The examples must retain the required task, scope, constraints, repository, base branch, merge authority, and other workflow-specific input. They must not show a model calling the answer action for a protected human decision.
+
+Update the workflow authoring skill and examples to explain `humanDecision().onTimeout`, timeout provenance, and the rule that only a policy-defined response can run automatically.
+
+## Public contracts and persisted data
+
+Change the current alpha contracts in place:
+
+- add `onTimeout` to the public typed human-decision definition;
+- add the persisted deadline and default response to the current human-decision request contract;
+- add timeout-default provenance to the current accepted result, receipt, resolution, continuation, and channel settlement handling where it applies;
+- add the shared `PlanApprovalPolicy` and plan-change input and output types;
+- change Autoimplement and Monitor approval inputs to the shared policy; and
+- keep existing camelCase JSON fields and current schema and contract identifiers.
+
+Persisted request and resolution JSON remains under the current human-decision state root. Run bundles remain under the current run store. Add no migration reader, dual read, dual write, alias, feature flag, or new schema generation.
+
+Increment the affected built-in revisions as one hard alpha cutover:
+
+- Autoimplement revision 6 to 7;
+- Monitor revision 7 to 8; and
+- plan-approval revision 2 to 3.
+
+Older active runs refuse resume through the existing source-change behavior. The new internal plan-change workflow does not need to be a user-facing catalog entry or skill.
+
+## Documentation
+
+When implementation ships, update:
+
+- `docs/HUMAN_DECISIONS.md` for timeout responses, provenance, recovery, races, and channel behavior;
+- `docs/WORKFLOW_COMPOSITION.md` for the shared plan-change workflow;
+- `docs/workflows.md` for the public API and Autoimplement behavior;
+- `docs/MONITOR.md` for repair-plan decisions;
+- `docs/run-bundles.md` for request, resolution, continuation, and snapshot fields;
+- Autoimplement and Monitor skill text and examples; and
+- package examples and generated layout fixtures affected by the graph change.
+
+Keep the previous human-decision and composition plans unchanged as historical records.
+
+## Implementation steps
+
+1. Add and validate the typed `humanDecision().onTimeout` contract. Bind the validated default response and absolute deadline into request identity and persisted request data.
+2. Extend the human-decision store with one atomic timeout-default resolution operation. Preserve one immutable resolution and one deterministic continuation.
+3. Update extension decision recovery to resolve eligible defaults, recover after restart, settle channels, and start only the owned continuation. Keep cancellation checks around resolution and continuation claims.
+4. Update Pi and Telegram decision presentation and settlement so the deadline and automatic action are clear and a completed timeout closes pending views.
+5. Extend plan-approval with the shared policy and explicit human, timeout, and skipped provenance.
+6. Add the internal shared plan-change workflow with Autoplan, Autodoc, plan approval, and bounded exact-instructions replanning.
+7. Replace the duplicate Autoimplement planning approval path with the shared workflow and gate only changed internal redesign results.
+8. Replace the duplicate Monitor repair-plan approval path with the shared workflow and pass its selected plan to Autoimplement without another decision.
+9. Update public exports, current schemas, built-in revisions, skills, examples, documentation, and generated fixtures.
+10. Run all unit, integration, real-Pi, documentation, formatting, dependency-boundary, and package-resource checks.
+
+## Tests
+
+Use fake clocks, temporary directories, and fake channels. Tests must not call a real model, use a real Telegram credential, or mutate a real remote.
+
+Cover:
+
+- `onTimeout` type and runtime validation;
+- absent timeout behavior;
+- the default 10-minute deadline;
+- custom positive timeout values;
+- invalid timeout and response combinations;
+- auto, required, and skip policy parsing;
+- human continue, stop, and exact-text replan;
+- human-answer and timeout-default races with each winner;
+- timeout provenance without a human actor;
+- late answer rejection;
+- immediate terminal cancellation before and during timeout resolution;
+- one continuation after concurrent or repeated recovery;
+- restart recovery before and after the deadline;
+- auto mode with no configured channel;
+- required mode with no configured channel;
+- Pi and Telegram delivery, expiry text, and settlement;
+- plan digest and positive revision binding;
+- no duplicate decision for the same digest;
+- bounded replans;
+- Autoimplement changed-plan routing;
+- Autoimplement supplied and discovered plan bypass;
+- Monitor repair-plan routing;
+- no second decision when Monitor passes its selected plan to Autoimplement;
+- later Autoimplement redesign after Monitor selection;
+- built-in revision refusal for old active runs;
+- package skill and workflow discovery; and
+- real-Pi continuation with a short fake-clock deadline and no real model.
+
+## Verification
+
+Run:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+git diff --check
+```
+
+Inspect the complete public diff before each commit, push, or pull-request update. Verify GitHub CI and Pi Reviewer before delivery.
+
+## Boundaries
+
+This work changes only the pi-workflows repository. It may change the workflow engine, extension decision recovery, built-in workflow composition, skills, tests, examples, fixtures, and documentation needed for this policy.
+
+It must not:
+
+- change Pi core or use undocumented Pi APIs;
+- add a service, daemon, controller, scheduler, or persistence location;
+- change external services, credentials, Telegram configuration, CI policy, or unrelated repositories;
+- add a standalone plan-approval skill;
+- queue, revive, or extend deferred successor turns;
+- add compatibility readers, migrations, dual paths, new schema generations, aliases, or feature flags;
+- merge the implementation pull request; or
+- publish a package or release.

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

@@ -0,0 +1,283 @@
+---
+title: Run Sanity Check with Provider Extensions
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-21
+updated: 2026-08-22
+---
+
+# Run Sanity Check with Provider Extensions
+
+## Goal
+
+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 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 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
+
+Each child session:
+
+- 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.
+
+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.
+
+## Input and review modes
+
+The workflow input stays unchanged. Serial mode remains the default.
+
+```json
+{
+  "mode": "serial",
+  "baseRef": "origin/main"
+}
+```
+
+`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 and results
+
+The first node collects facts without model judgment. It uses fixed, non-mutating commands to collect:
+
+- pull request intent and linked issue context when available;
+- stated acceptance criteria;
+- base and head revisions;
+- changed files;
+- the diff and diff statistics;
+- relevant new exports, schemas, persisted fields, and nearby existing code.
+
+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.
+
+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`.
+
+The existing strict result parsers stay unchanged. They continue to enforce all review areas, evidence, acceptance case, verdict, string, and item limits.
+
+## Provider-first extension profile
+
+The runner resolves one immutable child profile before it starts the group.
+
+### Resolve candidate paths
+
+Use `SettingsManager` and `DefaultPackageManager.resolve()` to find enabled extension paths without executing extension factories. Canonicalize and deduplicate the paths.
+
+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.
+
+### Preflight provider ownership
+
+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.
+
+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.
+
+Fail before session creation when:
+
+- 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.
+
+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`.
+
+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.
+
+## Exact model dispatch
+
+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.
+
+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.
+
+Provider extensions use their existing provider-owned credential store in place. Pi Workflows does not copy, inspect, print, migrate, or persist those credentials.
+
+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.
+
+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
+agents/review
+agents/review/necessity
+agents/review/duplication
+agents/review/contracts
+agents/review/scope_tests
+agents/verification
+agents/verification/verification
+```
+
+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.
+
+Updates are deduplicated, throttled, and observational. They cannot change agent execution.
+
+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.
+
+## Implementation plan
+
+1. Update the Pi SDK development baseline to one compatible 0.84.x release. Keep the Pi coding-agent, Pi AI, and Pi TUI packages aligned and set an honest peer compatibility floor. Do not add Pi Factory or a provider extension as a dependency.
+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.
+
+## Revision and compatibility
+
+Sanity Check moves from built-in revision 2 to revision 3.
+
+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.
+
+## 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
+npm run test:e2e
+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 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.
+- **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.
@@ -183,7 +183,9 @@ A serializable snapshot of the graph taken at run start
 (`pi-workflows.definition-snapshot.v1`). Functions such as prompts and
 validators are not serialized. Each node keeps only its metadata (`nodeType`,
 `timeoutMs`, `statusDetail`, `expectedOutput`, `summary`, `actionExecution`),
-and edges are copied verbatim. 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.
+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.
+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