@osolmaz/pi-workflows 0.12.0 → 0.13.0

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

@@ -1,28 +1,49 @@
 ---
-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-23
+status: implemented
 ---
 
-# 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 uses existing `action`, `agent`, and `compute` nodes and includes the existing `plain-summary` workflow. `src/workflows` and `WorkflowActionContext` remain Pi-independent. The change does not add a workflow primitive, public agent-group export, persisted schema, child workflow run, service, queue, store, transport, Pi core change, or private Pi API.
+
+Sanity Check keeps its existing input, review areas, child prompts, evidence rules, session counts, strict result validation, verdicts, and progress schema. After verification, it shows two ordered normal assistant responses: the full detailed report first, then a short plain-language summary.
+
+## Child session contract
+
+Each child session:
 
-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.
+- 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.
 
-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.
+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
+## Input and review modes
 
-The workflow accepts a review mode and the base reference needed to inspect the current change. Serial mode is the default.
+The workflow input stays unchanged. Serial mode remains the default.
 
 ```json
 {
@@ -31,118 +52,203 @@ 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.
 
-## Evidence
+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:
 
-- 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.
+
+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:
 
-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:
+- `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.
+## Ordered assistant reports
 
-## Tests
+After strict verification succeeds, an assistant-message `agent` shows the complete bounded report. Its prompt supplies the deterministic report and requires a verbatim response without tools. A mismatch stops before summary generation. This replaces the old final workflow notification.
+
+The graph then includes `plain-summary`. The summarizer receives the verified verdict and detailed report, keeps the verdict, and writes one short plain-language response. It uses the plain-summary workflow limits of 2,000 characters and five sentences. The detailed response always settles before the summary starts.
+
+Neither response uses `presentationPrompt`, and neither can change the verified verdict. A final compute node returns the original strict `SanityCheckResult` as the workflow result. Both visible responses and their normal assistant receipts use existing Pi session and SQLite records. A detached host parks before these session-visible nodes until the origin Pi session can continue them.
+
+## Implementation plan
 
-Unit tests must cover:
+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. Add the ordered detailed assistant response and included plain summary, then return the original verified result from a final compute node.
+11. Change the built-in Sanity Check revision from 3 to 4 for the presentation graph change.
+12. Add temporary fixture extensions and full unit, integration, interactive Pi, and standalone host coverage.
+13. Update this plan and `docs/workflows.md` to match the shipped behavior.
+14. Run the complete repository gate and inspect the full public diff.
+15. After mock-provider verification of the provider architecture, run one bounded real acceptance on OpenClaw pull request 126028 with `openai-codex/gpt-5.6-sol` and high thinking. Abort immediately if any child reports another provider or model. Do not modify OpenClaw.
 
-- 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.
+## Revision and compatibility
 
-The real-Pi end-to-end test must use the repository test provider. It must not call a real model or make destructive changes.
+Sanity Check revision 3 introduced the provider-first child runtime. Revision 4 replaces the final notification with the ordered detailed and plain assistant responses.
 
-Before completion, run all checks required by `AGENTS.md`:
+This is an alpha hard cutover. Do not retain the revision-3 notification graph, compatibility runner, migration, alias, dual path, or feature flag. An unfinished revision-3 run must fail with clear cancel-and-restart guidance. Terminal older runs remain readable historical evidence because the persisted schema does not change.
+
+## Tests
+
+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 4 and historical terminal run reading;
+- one full detailed assistant response followed by one short plain-language assistant response;
+- unchanged strict final result after both visible responses;
+- no final notification or root presentation turn.
+
+Tests use mock providers and temporary directories. They do not call real models or write outside temporary directories.
+
+Before completion, run:
 
 ```bash
 npm run check
@@ -151,25 +257,41 @@ 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 4;
+- the parent Pi process runs with its normal configured extensions;
+- serial mode uses two independent in-memory SDK sessions;
+- parallel mode uses five independent in-memory SDK sessions, with four reviews running concurrently;
+- 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, and progress remain unchanged;
+- the full detailed assistant response appears before the short plain-language summary;
+- the final workflow result remains the strict verified result;
+- interactive and headless runs use the same private SDK path, while session-visible reports wait for the origin Pi session;
+- all required checks pass with coverage margin;
+- the bounded acceptance run on OpenClaw pull request 126028 reports GPT-5.6 Sol for every child and completes with a strict verdict without modifying OpenClaw.
 
 ## Contract impact
 
-- **Origin session:** The normal workflow start record and one final workflow notification.
-- **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.
+- **Origin session:** The normal workflow start record, one detailed assistant response, and one short plain-language assistant response.
+- **Parent extensions:** The parent Pi process loads its normal configured extensions.
+- **Child extensions:** Only the exact provider owner and explicit private behavior paths are admitted.
+- **Child sessions:** Independent in-memory contexts and complete per-child runtimes in the same Node process. No child session file or child workflow run.
+- **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/plans/2026-08-22-goal-finishing-monitor-plan.md

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