@osolmaz/pi-workflows 0.13.4 → 0.15.0

package/docs/workflows.md

@@ -19,14 +19,12 @@ 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
-a process-local catalog with a stable reference such as `builtin:monitor` and
-an explicit revision. Built-ins are imported with the engine when a Pi process
-starts. They are not read from the package directory when a run starts or
-resumes. Updating the package on disk cannot mix a new built-in with that
-process's old engine; reload or restart Pi to use the new built-in. A revision
-mismatch refuses resume. Project and global workflow files still reload on
-each run and use their path and SHA-256 hash as their source identity.
+replaces the built-in monitor. Each built-in has a stable reference such as
+`builtin:monitor` and an explicit revision. A resolver child snapshots the
+selected built-in before start, and each run worker verifies that identity
+before execution. A revision mismatch refuses resume. Project and global
+workflow files also use their absolute path and SHA-256 hash as source
+identity.
 
 The workflow's command name is the file stem, so `.pi/workflows/triage.workflow.ts`
 runs as `/workflow triage`. A direct path also works: `/workflow ./somewhere/x.workflow.ts`.
@@ -40,7 +38,6 @@ import { agent, compute, defineWorkflow } from "@osolmaz/pi-workflows";
 export default defineWorkflow({
   name: "example",
   title: ({ input }) => `example: ${(input as { task?: string }).task}`,
-  presentationPrompt: "Present the final answer clearly and concisely.",
   startAt: "ask",
   maxSteps: 50,
   nodes: {
@@ -56,20 +53,19 @@ export default defineWorkflow({
 
 Top-level fields:
 
-| Field                | Type                      | Notes                                                                                                                                                                                                              |
-| -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name`               | `string`                  | Required. Used in run ids and the step contract. `answer`, `cancel`, `list`, `pause`, `resume`, and `status` are reserved for `/workflow` subcommands.                                                             |
-| `source`             | `string`                  | Optional `import.meta.url` for exact provenance when another TypeScript workflow imports this definition directly.                                                                                                 |
-| `contractId`         | `string`                  | Optional stable input-and-exit contract identity. Dynamic overrides must match it.                                                                                                                                 |
-| `input`              | `function`                | Optional runtime input normalizer and validator. Its return type is the workflow input type.                                                                                                                       |
-| `title`              | `string` or function      | Optional run title, resolved once at start from `{ input, workflowName }`. Async resolution is bounded (30s) and cancellable.                                                                                      |
-| `presentationPrompt` | `string` or function      | Optional instructions for a normal assistant response after the run. A function receives `{ state, finalOutput, signal }` and may return a prompt or `undefined`. See [Result presentation](#result-presentation). |
-| `startAt`            | `string`                  | Required. Id of the first node.                                                                                                                                                                                    |
-| `nodes`              | `Record<string, node>`    | Required, non-empty. Node ids must match `[A-Za-z_][A-Za-z0-9_-]*`.                                                                                                                                                |
-| `includes`           | `Record<string, include>` | Optional imported or dynamically resolved child workflows.                                                                                                                                                         |
-| `exits`              | `Record<string, exit>`    | Optional named successful terminal nodes used when another workflow includes this workflow.                                                                                                                        |
-| `edges`              | `WorkflowEdge[]`          | Required. See routing below.                                                                                                                                                                                       |
-| `maxSteps`           | `number`                  | Optional loop bound, default 100. The run fails when exceeded.                                                                                                                                                     |
+| Field        | Type                      | Notes                                                                                                                                                  |
+| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`       | `string`                  | Required. Used in run ids and the step contract. `answer`, `cancel`, `list`, `pause`, `resume`, and `status` are reserved for `/workflow` subcommands. |
+| `source`     | `string`                  | Optional `import.meta.url` for exact provenance when another TypeScript workflow imports this definition directly.                                     |
+| `contractId` | `string`                  | Optional stable input-and-exit contract identity. Dynamic overrides must match it.                                                                     |
+| `input`      | `function`                | Optional runtime input normalizer and validator. Its return type is the workflow input type.                                                           |
+| `title`      | `string` or function      | Optional run title, resolved once at start from `{ input, workflowName }`. Async resolution is bounded (30s) and cancellable.                          |
+| `startAt`    | `string`                  | Required. Id of the first node.                                                                                                                        |
+| `nodes`      | `Record<string, node>`    | Required, non-empty. Node ids must match `[A-Za-z_][A-Za-z0-9_-]*`.                                                                                    |
+| `includes`   | `Record<string, include>` | Optional imported or dynamically resolved child workflows.                                                                                             |
+| `exits`      | `Record<string, exit>`    | Optional named successful terminal nodes used when another workflow includes this workflow.                                                            |
+| `edges`      | `WorkflowEdge[]`          | Required. See routing below.                                                                                                                           |
+| `maxSteps`   | `number`                  | Optional loop bound, default 100. The run fails when exceeded.                                                                                         |
 
 `defineWorkflow` validates the shape eagerly (node ids, edge shapes, function
 fields) and validates the graph (unknown targets, duplicate outgoing edges,
@@ -112,36 +108,51 @@ Function actions receive `WorkflowActionContext`, which adds
 
 ## Durable runs, parking, and resume
 
-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 owner-only SQLite write proves the claim
-first (write fencing).
+Every run enters one global SQLite queue. One package-owned host claims runs,
+renews live claims, commits state, and supervises one child process for each
+active run generation. The extension is a local host client. It does not run
+the workflow engine or workflow definitions.
 
-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 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
-downstream rerun. Resume repairs a torn trace tail, drops trace events the
-state projection never recorded, and refuses to continue if the workflow
-source changed since the run started (a forced resume records the mismatch).
-
-The standalone host runs without any Pi session:
+The host starts on demand when a Pi or CLI client needs it. These commands
+control the same user-level host for all projects:
 
 ```bash
-pi-workflows host --project /path/to/project
+pi-workflows host start
+pi-workflows host status
+pi-workflows host stop
+pi-workflows host run
 ```
 
-The host claims parked runs, resumes them, and reconciles durable controllers.
-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
-and never enter another conversation in the same project.
+`host run` stays attached. The other commands start, inspect, or stop the
+on-demand process. No command installs an operating-system service.
+
+A worker verifies the root and all mounted source identities before it loads
+workflow modules. It then checks the resolved mounted-source map and executes
+from committed state through a host-backed store. A source mismatch parks the
+run with `workflowSourceChanged`; normal scheduling does not retry it. Restore
+the recorded source and explicitly resume, or cancel the run. A headless Pi
+child uses its own registered process group. The worker stops that group on
+normal completion, and the host reaps it if the worker exits first. If the
+worker stops for another recoverable reason, pure work can run again. A
+protected write checks and renews the exact live token and generation in one
+transaction. An expired or replaced owner cannot revive itself.
+
+Interactive agent and assistant-message steps do not run headlessly for a Pi
+session. The worker commits a durable interaction request and parks. The origin
+session presents the request through documented Pi APIs and submits the exact
+request, node, attempt, and revision. The host records submitted output as
+provisional. A new supervised worker loads the workflow and runs its `validate`
+function before the host accepts the submission. A validation error leaves the
+same request pending and returns the error to the model. Closing Pi leaves that
+request pending; reopening the same session adopts the existing session entry
+or presents it once. Notifications use the durable session outbox. A root
+`presentationPrompt` creates a durable terminal turn only after completion is
+committed. A controller child without an origin session can use a supervised
+headless `pi --mode rpc` child for structured agent steps.
+
+Pause stops the worker and parks at the last durable boundary. Resume takes a
+new generation. Cancellation can stop a live worker or atomically claim and
+cancel an expired running row. Resume refuses changed workflow source.
 
 ## Node types
 
@@ -179,10 +190,13 @@ agent({
 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,
+The host checks the durable transport identifiers, stores a `validating`
+submission, and starts a supervised worker. In that worker, the output passes
+through tolerant JSON normalization and then `validate`. The tool reports
+success only after this check accepts the output. Rejected submissions return
+the validation error and can retry in the same step. If the model settles
+without submitting, the durable request stays pending until it receives valid
+output, times out, or is cancelled. 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.
@@ -225,20 +239,34 @@ controller resource instead.
 
 ### action
 
-Performs a side effect. Two forms exist. The function form runs arbitrary
-TypeScript:
+Performs managed work. Every function action and shell action must declare how
+the host recovers if the worker exits after the external operation but before
+it saves a receipt.
+
+Use `idempotentEffect(type)` only when the operation has a stable external
+idempotency key or a read-back check that makes another attempt safe:
 
 ```typescript
-action({ run: async ({ input }) => await deployPreview(input) });
+import { action, idempotentEffect } from "@osolmaz/pi-workflows";
+
+action({
+  effect: idempotentEffect("preview.deploy"),
+  run: async ({ input }) => await deployPreview(input),
+});
 ```
 
+Use `manualEffect(type)` when the external system cannot prove whether an
+uncertain request applied. An uncertain worker exit marks that effect
+`ambiguous`, parks the run, and requires explicit operator recovery. The host
+does not retry it automatically.
+
 The shell form (`shell` is a synonym that requires `exec`) runs a command owned
-by the runtime, so the workflow author decides exactly what executes, with a
-timeout and captured output:
+by the workflow definition, with a timeout and captured output:
 
 ```typescript
 shell({
-  exec: ({ input }) => ({
+  effect: idempotentEffect("repository.status"),
+  exec: () => ({
     command: "git",
     args: ["status", "--porcelain"],
     cwd: "/path/to/repo",
@@ -261,6 +289,7 @@ A function action can publish a durable update without completing the node:
 
 ```typescript
 action({
+  effect: idempotentEffect("dataset.process"),
   run: async ({ publishUpdate }) => {
     await publishUpdate({
       type: "progress",
@@ -283,6 +312,12 @@ keeps normal output capture. Lines and update data are each limited to 64 KiB.
 See [WORKFLOW_UPDATES.md](WORKFLOW_UPDATES.md) for the envelope, progress
 schema, limits, estimation, and error rules.
 
+The host reserves the effect before it lets the action run. A repeated key with
+the same request adopts the durable record; the same key with another request
+is a conflict. A normal caught error settles the attempt as rejected. After an
+uncertain process exit, an idempotent effect returns to pending for retry, while
+a manual effect becomes ambiguous. This is not an exactly-once claim.
+
 ### checkpoint
 
 Ends the run in a `waiting` state for human review. The checkpoint run is
@@ -333,9 +368,9 @@ humanDecision({
 });
 ```
 
-The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, input prompts, and any deadline policy. The first valid verified human answer wins. When `onTimeout` is present and no human answer wins before the saved deadline, recovery applies the validated response with `timeout` provenance. This policy can continue without a configured channel. A continuation preserves the original workflow input and exposes the resolved response as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. Existing `body` requests remain a legacy compatibility form and use deterministic readable formatting.
+The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, input prompts, and any deadline policy. The first valid verified human answer wins. When `onTimeout` is present and no human answer wins before the saved deadline, the host takes a control claim on the waiting parent and atomically applies the validated response with `timeout` provenance, closes the interaction, and reserves the continuation. This policy can continue without a configured channel. A continuation preserves the original workflow input and exposes the resolved response as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. Existing `body` requests remain a legacy compatibility form and use deterministic readable formatting.
 
-The model-facing workflow tool cannot answer a protected human decision. Pi interactive UI and configured external channels use a host-owned answer path. Ordinary checkpoints keep the existing `/workflow answer` behavior.
+The model-facing workflow tool cannot answer a protected human decision. The origin Pi session displays the request without starting a model turn. A person uses `/workflow answer` to send the answer through the host-owned path. Ordinary checkpoints can also use the model-facing `answer` action.
 
 See [Human decisions](HUMAN_DECISIONS.md) for channels, recovery, persistence, and plan approval.
 
@@ -428,32 +463,31 @@ The run records every mounted source and a digest of the resolved graph. Resume
 
 The model sees one `workflow` tool. Its `action` field supports:
 
-- `list` for discovered workflow names and sources.
-- `start` with a workflow name or path and structured input.
-- `status` for the active run or a supplied run ID.
-- `pause`, `resume`, and `cancel` for the active run.
-- `answer` with ordinary checkpoint input and an optional run ID. Protected `humanDecision()` gates reject this model-facing action.
-- `change-settings` with an RFC 6902 patch, optional scope ID, and optional expected change number.
-- `queue-follow-up` to save one ordered normal user prompt for after successful completion.
-- `remove-follow-up` to remove an unsent prompt created by the same model source.
-- `update` for a non-completing update from the current agent attempt.
+- `list` for discovered workflow names and sources;
+- `start` with a workflow name or path and structured input;
+- `status` for the active run or a supplied run ID;
+- `pause` and `resume` for the active session run;
+- `cancel` for the active run or a supplied run ID;
+- `answer` with checkpoint input and an optional run ID;
+- `update` for a non-completing update from the current agent attempt;
 - `submit` for the current workflow step contract.
 
-A model-started run is queued until the model's current turn settles. The first
-workflow prompt then starts a new turn. This keeps the requesting turn outside
-the workflow's first attempt and prevents an early missing-submission reminder.
-The normal extension offers all actions. The headless RPC bridge offers only
-`update` and `submit`, so a workflow child cannot recursively control other
-runs. Direct `/workflow change-settings`, `queue-follow-up`, and
-`remove-follow-up` commands use verified interactive provenance. Controller
-code can use the matching `ctx.workflows` methods. All surfaces call the same
-SQLite operations.
-
-Follow-up prompts stay separate from workflow settings. Successful terminal
-state is saved before delivery. A final presentation settles first. The Pi
-extension then sends prompts in order as normal user messages without
-reactivating the completed run. See [Continue normal work after a workflow
-finishes](2026-08-25-workflow-follow-ups.md).
+A direct user request to continue or resume the active workflow maps to
+`resume` immediately. The model does not call `status` instead of `resume` or
+use it as a prerequisite. An already active run adopts the resume request. A
+paused or parked run gets a new claim generation and worker. With no resumable
+run, the host rejects the request.
+
+`status` reports the durable queue projection. A host command succeeds only
+after its transaction commits. The protocol stores request fingerprints and
+receipts, so an exact duplicate adopts the committed result and conflicting
+reuse is rejected.
+
+The normal extension offers these actions through the origin Pi session. The
+headless RPC bridge offers only `update` and `submit`, so a controller child
+cannot recursively control unrelated runs. Controller code can use its narrow
+`ctx.workflows` methods for child runs, settings, and follow-up records. Those
+methods also commit through the global host.
 
 ### Built-in plain summary
 
@@ -557,7 +591,7 @@ 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 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`.
+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 creates no extra terminal model turn.
 
 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.
 
@@ -648,49 +682,22 @@ use an internal turn-intent contract instead of the notification outbox. See
 [WORKFLOW_STEP_MESSAGES.md](WORKFLOW_STEP_MESSAGES.md) for the step-message contract
 and [Deferred workflow turns](DEFERRED_TURNS.md) for the successor-turn contract.
 
-## Result presentation
+## Visible responses
 
 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:
+When a person must receive normal prose, use an agent node with
+`expectedOutput: assistantMessage()`. The worker parks and records the exact
+step request. The origin Pi session starts the model turn, and the visible
+assistant text becomes the node output after the turn settles.
 
-```typescript
-export default defineWorkflow({
-  name: "report",
-  presentationPrompt: ({ state, finalOutput }) =>
-    state.status === "waiting"
-      ? `Explain this recommendation and ask the user to decide: ${JSON.stringify(finalOutput)}`
-      : "Summarize the completed result and any remaining limitations.",
-  // ...startAt, nodes, and edges
-});
-```
+The request keeps its node and attempt ID across Pi reload. The extension first
+looks for an existing session entry with the durable request ID. It inserts a
+new visible message only when no adopted entry exists. A repeated submission
+returns its stored receipt.
 
-After the final run state has been persisted, the Pi extension sends the
-presentation instructions and bounded final result to the model as a hidden
-follow-up message. The next visible message is a normal assistant response.
-Returning `undefined`, returning an empty string, or omitting
-`presentationPrompt` produces no presentation. Failed, timed-out, and cancelled
-runs are never presented. When one of those outcomes would otherwise strand an
-agent after a workflow-caused turn abort or asynchronous crash, the extension
-uses the deferred-turn contract to send one factual fallback after settlement.
-Async prompt builders have 30 seconds to finish and receive an
-`AbortSignal` that fires on timeout, session shutdown, or when a new workflow
-or normal user turn starts; stale presentations are discarded. Once a presentation message has
-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 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
-internals.
+A headless controller child cannot produce a visible assistant message without
+an approved origin-session binding. Use structured agent output for detached
+work. Terminal run state does not create an extra model turn.
 
 ## Runtime behavior
 
@@ -701,35 +708,31 @@ possible. Defaults worth knowing:
 - Node timeout is 15 minutes unless the node sets `timeoutMs` to a positive
   number or context callback. A timed-out node has outcome `timed_out` and can
   be routed with `$result.outcome`. A timed-out agent node also aborts its Pi
-  turn, and late output for that attempt is rejected.
+  turn, and late output for that attempt is rejected. Interactive runs save the
+  resolved wall-clock deadline before they park. The host enforces that deadline
+  while Pi is closed and after host restart.
 - `maxSteps` (workflow-level, default 100) bounds loops built from cycles in
   the graph.
-- `/workflow pause` requests a pause: the current step finishes normally,
-  then the run holds at the step boundary (`paused: true` in the run state,
-  `run_paused` in the trace) until `/workflow resume` or `/workflow cancel`.
-  Pausing never interrupts a node mid-flight.
-- Interrupting a turn (escape) auto-pauses the run: the pending agent step is
-  held without nudges and the engine pauses at the next boundary. Node
-  timeouts keep ticking while held, so a long-abandoned step still times out.
-  `/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 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
-  reports `started` and then crashes before its first prompt follows the same path. The model gets
-  one factual follow-up after settlement and can make a new explicit start call. Pi Workflows does
-  not retry blindly.
-- An agent-issued `workflow cancel` aborts the current node and the current Pi turn, then creates
-  one deferred-turn intent. The next natural workflow message resolves it when possible; otherwise
-  one factual fallback starts after settlement. Direct `/workflow cancel` remains quiet because it
-  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, 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.
+- `/workflow pause` atomically parks the run with `paused: true`, stores the
+  receipt, and fences the worker before process-group shutdown. `/workflow
+resume` takes a new generation and reruns only work after the last durable
+  boundary.
+- Resuming an active run adopts the existing work. Duplicate start, control,
+  update, and submission messages return their stored receipts.
+- A start is committed as `queued` with its final run ID before the command
+  reports success. Cancellation can use that run ID before its scheduled worker
+  starts. Active cancellation commits its terminal state and command receipt
+  together before worker shutdown. It cancels effects that have not started and
+  marks applying effects ambiguous for explicit recovery. `workflow status` and
+  `workflow cancel` can use the run ID immediately.
+- One interactive workflow request is presented per Pi session. Other requests
+  remain durable and ordered.
+- Each protected write renews only its exact live token and generation in the
+  same transaction. Claim loss does not write a failed run event.
+- An uncommitted pure or idempotent node can run again after a worker crash. An
+  uncertain manual effect parks as ambiguous and never retries automatically.
+- Host status reports safe counts and timestamps. It does not report session
+  IDs, project paths, prompts, payloads, tokens, process IDs, or credentials.
 
 ## Workflows started by controllers
 
@@ -754,14 +757,16 @@ 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 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.
+Child workflow completion queues the parent resource again. The global host runs the child through the same queue and supervised worker model as any other run. A host or worker crash resumes the existing durable run when its committed effect state makes that safe. Consequential external mutations belong in the workflow or controller effect API; an uncertain result stops for explicit recovery.
 
 See [CONTROLLERS.md](CONTROLLERS.md) for controller definitions and the full recovery contract.
 
-## Using the engine outside pi
+## Using the engine outside Pi
 
-The engine is pi-agnostic. `WorkflowEngine` takes any `AgentStepExecutor`, so
-tests (and other hosts) can script agent steps:
+The engine remains Pi-agnostic. `WorkflowEngine` takes any `AgentStepExecutor`,
+so tests and custom library integrations can script agent steps. The package's
+production extension does not use this as a selectable embedded runtime; it
+always sends runs to the global host.
 
 ```typescript
 import { WorkflowEngine, type AgentStepExecutor } from "@osolmaz/pi-workflows";
@@ -774,6 +779,9 @@ const executor: AgentStepExecutor = {
   },
 };
 
-const engine = new WorkflowEngine({ executor, outputRoot: "/tmp/runs" });
+const engine = new WorkflowEngine({
+  executor,
+  databasePath: "/tmp/workflow-state.sqlite",
+});
 const { state } = await engine.run(workflow, { task: "..." });
 ```

package/examples/workflows/command-batch.workflow.ts

@@ -2,6 +2,7 @@ import {
   action,
   compute,
   defineWorkflow,
+  manualEffect,
   runCommandBatch,
   type CommandBatchRequest,
 } from "@osolmaz/pi-workflows";
@@ -40,6 +41,7 @@ export default defineWorkflow({
         }) satisfies CommandBatchRequest,
     }),
     run: action({
+      effect: manualEffect("example.command-batch.run"),
       run: async (context) =>
         await runCommandBatch(context.outputs.prepare as CommandBatchRequest, {
           signal: context.signal,

package/examples/workflows/shell.workflow.ts

@@ -1,4 +1,4 @@
-import { compute, defineWorkflow, shell } from "@osolmaz/pi-workflows";
+import { compute, defineWorkflow, manualEffect, shell } from "@osolmaz/pi-workflows";
 
 type ShellInput = {
   text?: string;
@@ -10,6 +10,7 @@ export default defineWorkflow({
   startAt: "echo_text",
   nodes: {
     echo_text: shell({
+      effect: manualEffect("example.shell.echo-text"),
       exec: ({ input }) => ({
         command: "printf",
         args: ["%s", (input as ShellInput).text ?? "hello from pi-workflows"],

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.13.4"
+version = "0.15.0"
 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.13.4",
+  "version": "0.15.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/skills/autodoc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autodoc
-description: Use when an existing selected solution or clear implementation plan must be recorded or updated in canonical documentation before implementation, including choosing the right repository and applying SimpleDoc conventions.
+description: Records or updates an existing selected plan in canonical documentation without implementing it. Use only when the user explicitly asks to run autodoc.
 compatibility: Requires pi-workflows and the built-in autodoc workflow.
 ---
 

package/skills/autoimplement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autoimplement
-description: Use when the user asks to implement a plan end-to-end, test it, run pi-reviewer against the base branch in a loop until no P0/P1 issues remain, and make sure CI/CD is green before finishing.
+description: Implements an existing plan end to end, tests it, runs pi-reviewer until no P0/P1 issues remain, and verifies CI/CD. Use only when the user explicitly asks to run autoimplement.
 compatibility: Requires Pi Workflows and the built-in autoimplement workflow.
 ---
 

package/skills/autoplan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autoplan
-description: Use when the user asks to devise, choose, or plan the most Long term elegant and production ready solution, compare it with the Holy grail, and produce the best practical in-scope implementation plan without asking the user to resolve the gap.
+description: Compares practical solutions with the ideal end state, selects the best in-scope option, and produces an implementation plan. Use only when the user explicitly asks to run autoplan.
 compatibility: Requires pi-workflows and the built-in autoplan workflow.
 ---
 

package/skills/pi-workflows/SKILL.md

@@ -22,6 +22,8 @@ Use the smallest applicable action:
 - `update` publishes a non-completing durable update for the active step attempt.
 - `submit` completes an active submitted agent step with its required output. An assistant-message step completes through its normal visible reply instead.
 
+When the user asks to continue or resume the active workflow, call `workflow` with `action: "resume"` immediately. Do not use `workflow status` as a substitute or prerequisite.
+
 Use `start` only once for one requested run. Before starting, load the matching workflow skill when one exists and build its complete input. Include scope, authority, constraints, identifiers, and finish criteria required by that skill. Do not start with placeholders that still need user or model repair.
 
 For a workflow without a specialized skill, inspect its input contract and make one complete call. For example:

package/src/builtins/autoimplement.workflow.ts

@@ -11,6 +11,7 @@ import {
   defineWorkflow,
   includeWorkflow,
   includedResult,
+  manualEffect,
 } from "../workflows/definition.js";
 import { digest } from "../workflows/human-decision.js";
 import { allowSettingsPath, workflowSettings } from "../workflows/settings.js";
@@ -1768,6 +1769,7 @@ export const autoimplementWorkflow = defineWorkflow({
       run: selectReviewCommands,
     }),
     runReview: action({
+      effect: manualEffect("pi-workflows.autoimplement.review"),
       statusDetail: "running pi-reviewer commands",
       timeoutMs: (context) => {
         const selected = latestOutput<ReviewCommandSelection>(context, ["selectReviewCommands"]);
@@ -1884,6 +1886,7 @@ export const autoimplementWorkflow = defineWorkflow({
       validate: parseCiInspectionForPublished,
     }),
     trackCi: action({
+      effect: manualEffect("pi-workflows.autoimplement.track-ci"),
       statusDetail: "tracking pending CI commands",
       timeoutMs: (context) => {
         const inspected = latestOutput<CiInspectionBatch>(context, ["inspectCi"]);