@osolmaz/pi-workflows 0.12.1 → 0.13.1

package/docs/workflows.md

@@ -2,8 +2,8 @@
 
 This document is the authoring reference for pi-workflows definitions. It
 covers the file format, every node type, edge routing, the step contract the
-model sees, and how runs behave at runtime. For the on-disk run format, see
-[run-bundles.md](run-bundles.md).
+model sees, and how runs behave at runtime. For durable state, see
+[SQLITE_STATE.md](SQLITE_STATE.md).
 
 ## Workflow files
 
@@ -15,8 +15,8 @@ Files are discovered by suffix (`.workflow.ts`, `.workflow.js`, `.workflow.mts`,
 2. `~/.pi/agent/workflows/` globally
 3. Workflows built into Pi Workflows
 
-Pi Workflows includes built-in `autoplan`, `autodoc`, `autoimplement`,
-`plan-approval`, `sanity-check`, and `monitor` workflows. `autoplan` is the current name for the
+Pi Workflows includes built-in `plain-summary`, `autoplan`, `autodoc`,
+`autoimplement`, `plan-approval`, `sanity-check`, and `monitor` workflows. `autoplan` is the current name for the
 planning workflow that was first released as `autodevise`; the old command and
 export are not retained. A project or global file named `monitor.workflow.ts`
 replaces the built-in monitor. The package registers each built-in in
@@ -105,11 +105,11 @@ Function actions receive `WorkflowActionContext`, which adds
 
 Every interactive `/workflow` run is tracked in the project run queue (see
 [CONTROLLERS.md](CONTROLLERS.md) for the store). The session that starts a run
-claims it and owns it while it executes; every bundle write proves the claim
+claims it and owns it while it executes; every owner-only SQLite write proves the claim
 first (write fencing).
 
 Closing the Pi session mid-run no longer cancels the run. The engine **parks**:
-it stops without a terminal event, releases the claim, and leaves the bundle
+it stops without a terminal event, releases the claim, and leaves the run
 resumable. When a runner is available again (a reopened Pi session or the
 standalone host), the run **resumes** at the node it stopped on. Completed
 nodes replay from the recorded state; only the interrupted node and everything
@@ -124,9 +124,11 @@ pi-workflows host --project /path/to/project
 ```
 
 The host claims parked runs, resumes them, and reconciles durable controllers.
-Conversation nodes execute in headless `pi --mode rpc` children that load a
-small bridge extension; the model sees the same `workflow` tool contract as an
-in-session run. The host is a foreground process: start it in a terminal and
+Agent nodes that submit through the workflow tool execute in headless
+`pi --mode rpc` children that load a small bridge extension. An agent node with
+`expectedOutput: assistantMessage()` parks before prompting and waits for the
+origin Pi session because its result must be a visible assistant message. A
+detached run without an origin session fails clearly. The host is a foreground process: start it in a terminal and
 stop it with Ctrl-C. A second host for the same project refuses to start, and
 a host that dies has its orphaned children reaped by the next one. While the host works, reports enter a durable outbox addressed to the Pi
 session that started the run. They remain pending while that session is closed
@@ -136,8 +138,9 @@ and never enter another conversation in the same project.
 
 ### agent
 
-Sends a prompt into the current pi conversation and waits for the model to
-submit output through the `workflow` tool.
+Sends a prompt to the model. `expectedOutput` selects one of two output forms.
+
+The existing string form waits for a `workflow submit` call:
 
 ```typescript
 agent({
@@ -152,14 +155,28 @@ agent({
 });
 ```
 
-The engine appends a step contract to the prompt (see below). When the model
-calls the tool, the output passes through normalization (a JSON string is
-parsed tolerantly) and then `validate`. If `validate` throws, the tool call
-returns an error and the model can retry within the same step. If the agent
-ends its turn without submitting, the extension nudges it, twice by default,
-then fails the step. If an agent node times out or the workflow is cancelled,
-the extension also aborts its active Pi turn. The model cannot continue to use
-tools after the engine has closed that attempt.
+The assistant-message form waits for one normal visible response and uses its
+exact text as the node output:
+
+```typescript
+agent({
+  prompt: ({ outputs }) => `Explain this plainly: ${JSON.stringify(outputs.review)}`,
+  expectedOutput: assistantMessage(),
+});
+```
+
+`assistantMessage()` has no default character limit. Authors can opt in with
+`assistantMessage({ maxChars: 2_000 })`. It cannot be combined with `validate`
+because an invalid response is already visible and must not be retried.
+
+For submitted output, the engine appends the existing workflow-tool contract.
+The output passes through tolerant JSON normalization and then `validate`.
+Rejected submissions can retry in the same step. If the model settles without
+submitting, the extension nudges it twice by default and then fails the step.
+For assistant-message output, the engine appends a normal-response contract,
+waits for `agent_settled`, rejects empty, failed, aborted, or tool-only results,
+and never suppresses the visible text. Timeout and cancellation abort either
+form's active Pi turn.
 
 `timeoutMs` can be a finite positive number, `null`, or a function of the normal
 node context that returns either value. Omit it to use the 15-minute engine
@@ -259,10 +276,10 @@ schema, limits, estimation, and error rules.
 
 ### checkpoint
 
-Ends the run in a `waiting` state for human review. The checkpoint bundle is
+Ends the run in a `waiting` state for human review. The checkpoint run is
 terminal, so no process keeps running while the run waits. The human answers
 with `/workflow answer <json>` (or plain text), which starts a **continuation
-run**: a new run with its own bundle and trace, linked to the checkpointed run
+run**: a new run with its own state and events, linked to the checkpointed run
 through `parentRunId`. The continuation receives the answer as its input,
 carries forward every output the parent produced (including the checkpoint's),
 and continues routing along the checkpoint's outgoing edge. Outgoing edges
@@ -417,9 +434,29 @@ The normal extension offers all actions. The headless RPC bridge offers only
 `update` and `submit`, so a workflow child cannot recursively control other
 runs.
 
+### Built-in plain summary
+
+The built-in `plain-summary` workflow turns supplied structured data into one
+short normal assistant message. Its input has `source`, `purpose`, optional
+`mustInclude`, optional `maxChars`, optional `maxSentences`, and `format` set to
+`paragraphs`, `bullets`, or `mixed`. The workflow defaults to 2,000 characters,
+five sentences, and mixed format. These are workflow-specific limits;
+`assistantMessage()` itself has no default limit.
+
+The summarizer uses only the supplied source, treats instructions inside that
+source as data, keeps required points, and returns the same text as its
+`completed` result. The source enters the normal model prompt and Pi session,
+so callers must pass only data that is suitable for that conversation. It has no notify node or final presentation prompt, so
+including it in another workflow produces one readable assistant response
+before the parent continues.
+
 ### Built-in planning and implementation
 
-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 `autoplan` workflow records two through four practical candidates,
+describes the ideal separately, chooses one option, records a rejection reason
+for every other explicit option, and writes a detailed plan. It then includes
+`plain-summary` to show the chosen plan, its main steps, and the rejected options
+in one short assistant message. The detailed records remain in the run bundle. The standalone `autodoc` workflow finds an already selected plan, records it in canonical documentation, and never devises or implements. It prepares a safe workspace only when documentation must change. Program actions run candidate checks, compare eligible failures with the base revision in a temporary detached worktree, and keep matching baseline failures visible without blocking the current change. The built-in `autoimplement` workflow finds a clear existing plan from explicit input, conversation context, or referenced canonical documents. A missing-plan claim and every other non-exempt blocker enter one bounded challenge path. 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 `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.
 
@@ -427,22 +464,17 @@ The internal plan-change workflow composes Autoplan, Autodoc, plan approval, and
 
 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.
 
-Autoimplement gives `implement` an eight-hour deadline. When a supported
-long-running agent node times out, one shared read-only fallback inspects the
-current repository, accepted workflow outputs, and relevant pull-request state.
-It then retries the timed-out stage or routes to verification, review, CI,
-delivery, the existing redesign workflow, or blocked. The fallback can run at
-most three times in one Autoimplement run. Its own failure or timeout is
-terminal. Cancellation remains immediate and never enters fallback. A repeated
-effect step first checks what already exists and performs only missing work.
-This graph fallback starts after the timed-out turn ends and is separate from
-successor-turn delivery.
+Autoimplement prepares the workspace before its first edit-capable node. `workspaceMode` accepts `auto`, `branch`, `worktree`, or `defaultBranch`. Auto mode adopts a current task branch, creates a model-named branch from a clean default branch, or creates a model-named standard sibling worktree when the default checkout has existing work. Program actions validate and apply names. Direct default-branch work requires explicit authority and does not imply commit, push, merge, or release authority. Every later stage uses the prepared absolute path.
+
+Autoimplement gives `implement` an eight-hour deadline. When a supported step fails or times out, one shared bounded recovery step inspects accepted outputs and durable repository or pull-request state. It adopts a completed effect or retries only a missing effect. Cancellation remains immediate and never enters recovery. Unsupported or uncertain effects create a qualified blocker claim before challenge.
 
-Autoimplement uses batches for pi-reviewer, pending CI watches, and local verification commands from independent repositories. It keeps model turns, fixes, pushes, comment changes, merges, and releases in their existing order. Reviewer commands are tied to the repository, base branch, pushed head, and relevant dependency fingerprint. A later review round includes only repositories whose head or dependency fingerprint changed. P0 or P1 work still requires another review. P2-only work can be addressed and verified without another reviewer run only because of that P2 work.
+Local verification uses the shared change-verification composition. Direct program actions run candidate checks and read-only base-eligible checks with the same command, arguments, timeout, and output limit. Results separate related, unrelated, fixed-baseline, unknown, and untested findings. Matching base failures do not block the candidate. Related failures enter a two-attempt mechanical or semantic repair loop. Unknown or incomplete evidence needs bounded judgment, and truncated, timed-out, cancelled, or spawn-failed output cannot pass.
+
+Autoimplement uses batches for pi-reviewer and pending CI watches. It keeps model turns, fixes, pushes, comment changes, merges, and releases in their existing order. Reviewer commands are tied to the repository, base branch, pushed head, and relevant dependency fingerprint. A later review round includes only repositories whose head or dependency fingerprint changed. P0 or P1 work still requires another review. P2-only work can be addressed and verified without another reviewer run only because of that P2 work.
 
 Autoimplement inspects every pull request before it waits for CI. It accepts only supported pending `gh pr checks --watch` or `gh run watch` descriptors and binds each one to the validated pull request as `gh pr checks <PR URL> --watch`. Repository and pull-request overrides are rejected. One watch lasts at most five minutes. A failed or timed-out watch affects only its pull request. When checks remain pending, the model runs more useful local tests before checking CI again. Autoimplement does not invent an ETA.
 
-The action abort signal stops active command process groups and prevents queued commands from starting. Accepted outputs use the existing trace and artifacts. An interrupted unaccepted batch runs again because batch commands are read-only or isolated local checks. Progress updates contain metadata only and never control routing. Truncated reviewer or CI output cannot count as clean. See [Run independent commands in bounded batches](plans/2026-08-20-bounded-command-batches-plan.md) for the complete contract and implementation plan.
+The action abort signal stops active command process groups and prevents queued commands from starting. Accepted outputs use immutable events and content-addressed blobs. An interrupted unaccepted batch runs again because batch commands are read-only or isolated local checks. Progress updates contain metadata only and never control routing. Truncated reviewer or CI output cannot count as clean. See [Run independent commands in bounded batches](plans/2026-08-20-bounded-command-batches-plan.md) for the complete contract and implementation plan.
 
 A model-generated blocker from implementation or a safe later stage does not end autoimplement by itself. A separate blocker-challenge agent checks the task, approved plan, current result, evidence, scope, authority, earlier attempts, and practical alternatives. It confirms a blocker only when the blocker exists now, is outside the granted authority, has no safe path forward, has an empty next action, and includes concrete evidence and checked alternatives. A rejected blocker must name the next practical action and routes through the existing redesign workflow before implementation and verification continue.
 
@@ -463,7 +495,7 @@ Serial mode is the default. It runs one review session for all four review areas
 
 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.
+Sanity Check revision 4 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.
 
@@ -477,40 +509,51 @@ Only bounded final assistant text and safe operational facts leave a live child
 
 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.
 
-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.
+Serial mode still uses two child sessions, and parallel mode still uses five. Review prompts, review areas, strict result validation, verdicts, and progress stay unchanged. After verification, an assistant-message agent shows the full bounded report verbatim. A mismatch stops before summary generation. The graph then includes `plain-summary`, which shows a short plain-language explanation with the verdict and the most important next action. The detailed response always settles before the summary starts. A final compute node returns the original strict result, so presentation cannot change the verdict. Sanity Check uses no final notification or root `presentationPrompt`.
+
+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
 
-The built-in `monitor` workflow turns a plain request for repeated checks into
-one looping workflow run. Its input is:
+The built-in `monitor` workflow turns a plain request to finish and monitor an
+authorized goal into one looping workflow run. It accepts only `task`,
+`stopWhen`, `everyMinutes`, and `maxChecks`:
 
 ```json
 {
-  "task": "Check pull request 123",
-  "stopWhen": "The pull request is merged or closed",
-  "repair": {
-    "authorized": true,
-    "scope": "the current repository"
-  }
+  "task": "Finish pull request 123 within the recorded repository and delivery authority.",
+  "stopWhen": "The pull request is merged or safe continuation is blocked.",
+  "everyMinutes": 30
 }
 ```
 
-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.
+The first `observe` step runs immediately and is read-only. It inspects the real
+target with normal tools and chooses `wait`, `act`, or `stop`. `wait` means that
+useful target work is moving or an external event must finish. `act` states one
+safe action that existing authority permits. `stop` means that the goal is
+complete or cannot continue safely.
 
-`everyMinutes` defaults to 30. Each accepted check must provide one concise report and choose `continue`, `repair` when authorized, or `stop`. The
+An `advance` or `recover` action runs directly in a separate normal-tools step.
+A `repair` action composes the shared plan-change workflow and Autoimplement.
+Monitor observes again immediately after every action. It stops instead of
+repeating a completed repair when the same stable failure and target state
+return. The timer is reachable only from `wait`.
+
+`everyMinutes` defaults to 30. Every accepted observation provides one concise
+report that separates Monitor state, goal state, and target work state. The
 runtime queues that report as a workflow notification with `triggerTurn:
-false`, so it does not cause an assistant reply. A check can also provide
-independent progress tracks. The regular Pi model running the check observes
-the target and submits those facts. Pi Workflows validates the counts and
-calculates rates, confidence, and ETA deterministically. The target does not
-need a Pi Workflows dependency or reporting protocol.
+false`, so it does not cause an assistant reply. An observation can also provide
+independent progress tracks. The regular Pi model observes the target and
+submits those facts. Pi Workflows validates counts and calculates rates,
+confidence, and ETA deterministically. The target does not need a Pi Workflows
+dependency or reporting protocol.
 
 Intervals must be whole minutes from 1 through 1,440. When `stopWhen` is
 omitted, the monitor stops only after an explicit user request. `maxChecks`
-defaults to the disclosed safety ceiling of 1,000 and cannot exceed it. Callers
-omit `maxChecks` unless the user requests a fixed count. `checkTimeoutMinutes`
-is from 5 through 1,440 and defaults to the larger of 60 and `everyMinutes`.
-See [MONITOR.md](MONITOR.md) for the check and progress schemas.
+defaults to the disclosed observation safety limit of 1,000 and cannot exceed
+it. Callers omit `maxChecks` unless the user requests a fixed count. Unknown
+fields fail before a run is created. See [MONITOR.md](MONITOR.md) for the
+observation, action, and progress schemas.
 
 The interval uses the existing shell action to launch the current Node
 executable with a timer. This works on every platform supported by Pi. The node
@@ -559,8 +602,8 @@ and [Deferred workflow turns](DEFERRED_TURNS.md) for the successor-turn contract
 
 ## Result presentation
 
-Workflow nodes produce structured JSON for routing and persistence. When a
-person should see a normal prose response after the run, add
+Workflow nodes normally produce structured values for routing and persistence.
+When a person should see a normal prose response only after the root run, add
 `presentationPrompt` at the top level:
 
 ```typescript
@@ -588,8 +631,14 @@ or normal user turn starts; stale presentations are discarded. Once a presentati
 been queued, another workflow cannot start until that assistant response
 settles, so results cannot interleave.
 
+An agent with `expectedOutput: assistantMessage()` is different. Its visible
+assistant response is the node output, can appear before later nodes, and also
+works inside an included workflow. A root `presentationPrompt` would add a
+second response, so workflows that end with assistant-message output normally
+omit it.
+
 Presentation is outside the workflow graph: it cannot route to another node,
-change the run status, or alter the run bundle. If prompt generation or message
+change the run status, or alter the SQLite run state. If prompt generation or message
 delivery fails, the extension reports a warning and leaves the finished run
 unchanged. Opting in adds one hidden custom message and one assistant response
 to the normal Pi session; it adds no other persistent data and uses no Pi
@@ -598,7 +647,7 @@ internals.
 ## Runtime behavior
 
 Runs execute one node at a time. Every transition is persisted to the run
-bundle before the engine moves on, which is what makes the live viewer
+database transaction before the engine moves on, which is what makes the live viewer
 possible. Defaults worth knowing:
 
 - Node timeout is 15 minutes unless the node sets `timeoutMs` to a positive
@@ -617,7 +666,7 @@ possible. Defaults worth knowing:
   `/workflow resume` re-delivers the pending step prompt.
 - A model-started workflow is persisted as `queued` with its final run ID before the start tool
   returns. Activation waits for the initiating agent turn to settle, then moves through `starting`
-  and `running`. `workflow status` and `workflow cancel` accept the run ID before a run bundle
+  and `running`. `workflow status` and `workflow cancel` accept the run ID before a SQLite run state
   exists.
 - If deferred activation fails, the queue stores a bounded safe error, releases the session
   reservation, and creates one deferred-turn intent for the initiating session. A workflow that
@@ -630,7 +679,7 @@ possible. Defaults worth knowing:
   is explicit user control. When no run is live but the widget still shows a parked or finished run,
   the command clears the widget.
 - One workflow runs per session at a time.
-- After the workflow tool accepts an agent-step submission, the extension removes any assistant tail text from the rest of that agent run. The next workflow message is the visible continuation. A deferred intent makes a workflow prompt, presentation, and factual fallback compete to provide one successor turn, so an abort cannot produce two continuation turns.
+- After the workflow tool accepts an agent-step submission, any assistant text that follows remains visible. The next workflow message continues the graph. A deferred intent makes a workflow prompt, presentation, and factual fallback compete to provide one successor turn, so an abort cannot produce two continuation turns.
 - Agent nudges: if the model ends its turn without submitting the pending
   step, it gets a reminder, twice by default, then the step fails.
 
@@ -657,7 +706,7 @@ if (run.state !== "succeeded") {
 }
 ```
 
-Child workflow completion queues the parent resource again. A running child left by a stopped host is recorded as a failed run bundle with a `run_interrupted` event. The controller treats that child attempt as interrupted, and the next parent reconciliation starts another immutable attempt. Consequential external mutations should use the controller effect API so uncertain results are observed before retry.
+Child workflow completion queues the parent resource again. A running child left by a stopped host is recorded as a failed SQLite run state with a `run_interrupted` event. The controller treats that child attempt as interrupted, and the next parent reconciliation starts another immutable attempt. Consequential external mutations should use the controller effect API so uncertain results are observed before retry.
 
 See [CONTROLLERS.md](CONTROLLERS.md) for controller definitions and the full recovery contract.
 

package/examples/workflows/plain-summary.workflow.ts

@@ -0,0 +1 @@
+export { plainSummaryWorkflow as default } from "@osolmaz/pi-workflows/builtins";

package/herdr-plugin.toml

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/plugins/herdr/viewer.mjs

@@ -1,22 +1,12 @@
 #!/usr/bin/env node
 
 import { spawn, spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
 
 const runId = process.env.PI_WORKFLOWS_RUN_ID ?? "";
-const runDir = process.env.PI_WORKFLOWS_RUN_DIR ?? "";
 
 if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/u.test(runId)) {
   fail("PI_WORKFLOWS_RUN_ID is missing or invalid.");
 }
-if (!path.isAbsolute(runDir) || path.basename(runDir) !== runId) {
-  fail("PI_WORKFLOWS_RUN_DIR must be the absolute bundle directory for the selected run.");
-}
-if (!fs.existsSync(path.join(runDir, "manifest.json"))) {
-  fail(`Workflow bundle not found: ${runDir}`);
-}
-
 const paneId = process.env.HERDR_PANE_ID ?? "";
 if (!/^[A-Za-z0-9]+:p[A-Za-z0-9]+$/u.test(paneId)) {
   fail("HERDR_PANE_ID is missing or invalid.");
@@ -33,7 +23,7 @@ if (labeled.status !== 0) {
   fail(`Could not label the Herdr viewer pane: ${bounded(labeled.stderr) || "unknown error"}`);
 }
 
-const viewer = spawn("piw", [runDir], { stdio: "inherit" });
+const viewer = spawn("piw", [runId], { stdio: "inherit" });
 for (const signal of ["SIGINT", "SIGTERM"]) {
   process.on(signal, () => viewer.kill(signal));
 }

package/skills/autodoc/SKILL.md

@@ -15,6 +15,10 @@ Build the input as follows:
 - `task`: State what selected plan must be recorded and that this run is documentation-only.
 - `plan`: Pass the complete selected plan. Autodoc does not devise or improve it.
 - `repository`: Use the absolute path of the repository that owns the canonical documentation.
+- `baseBranch`: Use the requested base or the repository default branch.
+- `scope`: Name the allowed repository and documentation edits. Exclude implementation and unauthorized remote actions.
+- `workspaceMode`: Use `auto` unless the conversation requires `branch`, `worktree`, or explicitly authorized `defaultBranch` work. Autodoc prepares the workspace only when documentation needs an update.
+- `preparedWorkspace`: Include a previously confirmed `pi-workflows.prepared-workspace.v1` result when a parent workflow already prepared the workspace. Omit it otherwise.
 - `documents`: Include every known canonical specification or plan candidate. Use an empty array when none is known.
 - `evidence`: Include implementation evidence or current-document evidence when it affects whether documentation is current.
 
@@ -31,6 +35,9 @@ Replace the example values below with facts from the conversation, then make one
       "requirements": ["Keep cancellation terminal."]
     },
     "repository": "/absolute/path/to/repository",
+    "baseBranch": "main",
+    "scope": "Only /absolute/path/to/repository. May update canonical documentation and run documentation checks. Must not implement, push, merge, release, or deploy.",
+    "workspaceMode": "auto",
     "documents": ["docs/plans/timeout-fallback-plan.md"],
     "evidence": {
       "currentBehavior": "A timeout ends the run."

package/skills/autoimplement/SKILL.md

@@ -18,6 +18,9 @@ Build the input as follows:
 - `scope`: Always include a concrete authority statement. Name every allowed repository and the allowed edit, test, commit, push, pull-request, merge, and release actions. Carry forward exclusions from the conversation. A repository path alone is not a scope.
 - `constraints`: Include all applicable user and repository constraints. Use an empty array when none apply.
 - `baseBranch`: Use the requested base or the repository default branch.
+- `workspaceMode`: Use `auto` unless the user or repository requires `branch`, `worktree`, or `defaultBranch`. `auto` keeps a correct task branch, creates a task branch from a clean default branch, and isolates a dirty default checkout in a standard sibling worktree. Use `defaultBranch` only with explicit direct-work authority.
+- `preparedWorkspace`: Include a previously confirmed `pi-workflows.prepared-workspace.v1` result when the workspace was prepared before the run. Omit it otherwise.
+- `directDefaultBranchAuthorized`: Set `true` only when direct work on the actual default branch is explicit. It does not grant commit, push, merge, or release authority.
 - `merge`: Set `true` only when the user explicitly requested merge or an applicable standing instruction authorizes it. Otherwise set `false`.
 - `documents`: Include known canonical plan or specification paths. Use an empty array when none are known.
 - `approval`: Omit it for the default behavior: ask on each new plan and continue after 10 minutes without an answer. Use `{ "mode": "required" }` when the user says to block on plan changes. Use `{ "mode": "skip" }` when the user says to continue without asking about plan changes.
@@ -46,6 +49,7 @@ Replace the example values below with facts from the conversation, then make one
     "scope": "Only /absolute/path/to/repository. May edit and test task-related files, create commits, push the task branch, and open or update its pull request. Must not modify other repositories, merge, release, deploy, change credentials, or change repository policy.",
     "constraints": ["Preserve immediate cancellation.", "Keep deferred-turn work separate."],
     "baseBranch": "main",
+    "workspaceMode": "auto",
     "merge": false,
     "documents": ["docs/plans/timeout-fallback-plan.md"]
   }

package/skills/autoplan/SKILL.md

@@ -37,13 +37,14 @@ When this skill is loaded inside an active workflow step, do not start another w
 Outside Pi, or when the workflow is unavailable:
 
 1. Frame the problem, observable success criteria, scope, constraints, and interfaces under our control.
-2. Devise the most elegant long-term production-ready solution within that scope.
+2. Record two through four distinct practical candidates. Give each one a stable id, short title, plain gist, full solution, rationale, parts, and trade-offs.
 3. Describe the holy grail separately. Name every dependency outside our authority.
-4. Choose the right option without asking the user to decide between them.
+4. Choose the right option without asking the user to decide between them. Record one rejection reason for every other explicit candidate.
    - Choose the ideal when it is proportionate, production-ready, in scope, and implementable through interfaces we control.
    - Otherwise choose the strongest practical in-scope solution with a clear path toward the ideal.
    - Do not block only because the ideal requires an upstream or external change.
 5. Write a detailed implementation plan. For each step, state what changes, where it changes, and how to verify it.
-6. Stop as blocked only when no truthful in-scope solution can meet the success criteria.
+6. Present one short plain assistant message with the chosen plan, its main steps, and a one-line gist and rejection reason for every other candidate. Call it selected for approval when a later human decision still applies.
+7. Stop as blocked only when no truthful in-scope solution can meet the success criteria.
 
-When revising a plan, preserve the previous plan and new evidence. State whether the plan changed and why. Do not implement unless the user also requested implementation.
+When revising a plan, preserve the previous plan and new evidence. Record whether the previous plan remains a candidate or why new evidence rejects it. State whether the final plan changed and why. “All plans” means the explicit candidate records, never hidden model reasoning. Do not implement unless the user also requested implementation.