@osolmaz/pi-workflows 0.16.1 → 0.16.3

package/docs/2026-09-04-workflow-run-state-plan.md

@@ -0,0 +1,363 @@
+---
+title: Unify workflow run state
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-09-04
+status: implemented
+---
+
+# Unify workflow run state
+
+## Goal
+
+Several Pi Workflows failures appeared together after the out-of-process host change. A provider error left old workflow-turn ownership behind. A composed workflow reused an effect key. Restart treated a failed run as a checkpoint continuation. Terminal code read a text error as JSON. That read error blocked cancellation, while the host repeatedly started a worker that could not make progress.
+
+These failures have the same architectural cause. Important facts are inferred in more than one place. Local node names stand in for compiled identities. A parent run ID stands in for the kind of child run. Callers guess the type of stored data. Process activity stands in for workflow progress. Presentation work can determine whether a control command commits.
+
+The approved design gives each fact one owner and one typed path. The compiler and engine create execution identities. The host state store commits workflow state. A worker executes one explicit run command. The Pi extension delivers messages and reports public Pi events. Renderers display the host view.
+
+This plan replaces the narrower workflow-turn ownership plan. It keeps that fix and adds the effect, restart, terminal-data, cancellation, and worker-retry work needed to remove the shared cause.
+
+## User requirements
+
+- Use the most direct, long-term design instead of separate guards for each symptom.
+- Keep one global out-of-process host as the normal state writer.
+- Keep one client protocol and one production runtime.
+- Use documented Pi extension APIs only.
+- Do not change Pi core or Pi session schemas.
+- Keep schema version 1 and make an alpha hard cut. Do not add migrations, compatibility readers, dual paths, fallbacks, or feature flags.
+- Preserve strict ownership and uniqueness checks.
+- Do not claim exactly-once behavior for model calls or external systems.
+- A paused workflow must remain pausable and cancellable after any earlier run failure.
+
+## Confirmed causes
+
+### Composed effects lose their full node path
+
+`manualEffect()` and `idempotentEffect()` derive a key from `state.currentNode`. Workflow composition projects the state into a child workflow before it evaluates that key. The projection changes a compiled path such as `documentation/workspace/inspect` back to the local name `inspect`.
+
+The outer workspace check and the documentation workspace check therefore shared the run ID and visit number. They also shared the effect type and local node name. Their requests differed, so the effect store correctly rejected the second request with `Managed effect key was reused with another request`.
+
+### Restart uses checkpoint continuation
+
+The run queue records whether a child is a `continuation` or a `restart`. The worker bootstrap receives only `parentRunId`. It calls `continueRun()` for every child with a parent.
+
+`continueRun()` requires a parent that is waiting at a checkpoint. A failed terminal run does not meet that contract. A restart must begin at the workflow start with fresh graph and effect state.
+
+### A failed ancestor error is read with the wrong type
+
+Run errors are stored as text. `terminalAncestorOutcomes()` reads an ancestor `error_hash` with `readJson()`. The blob exists, but its media type is text. The generic database error says that the JSON blob is missing or has the wrong media type.
+
+Terminal-message creation calls this reader. As a result, the error can block child failure handling and cancellation.
+
+### A worker can restart forever without progress
+
+When an uninitialized worker exits, the host parks and claims the same run again. The failed restart never changes its saved workflow revision, but the host keeps launching it. The UI reports `running` because a process is active even though the workflow makes no progress.
+
+### Presentation can roll back control state
+
+Cancellation and terminal-message creation currently share a transaction path. If terminal-message creation cannot read its source data, the cancellation fails too. A display failure must not keep execution authority alive.
+
+## Design
+
+### Clear responsibilities
+
+The compiler assigns complete node paths. The engine uses those paths to identify logical work. Child workflows can receive a local view of inputs and outputs, but that local view cannot replace the compiled identity.
+
+The host state store owns every durable transition. Server orchestration code asks the store to start, pause, finish, cancel, or recover work. It does not update lifecycle tables directly.
+
+The worker receives one explicit command and executes it. It does not infer the command from nullable fields.
+
+The Pi extension keeps only temporary state for the current Pi turn. A host response decides whether that turn belongs to a workflow.
+
+Renderers use the host view. They do not infer workflow progress from process presence, messages, or local timers.
+
+### Complete execution identity
+
+Each logical node visit has a stable identity made from:
+
+- the run ID;
+- the full compiled node path;
+- the visit number.
+
+The visit number is the count for that exact compiled node path. A crash retry of the same unfinished visit keeps the same number. Re-entering the node later gets the next number.
+
+The engine derives managed-effect identity from this logical node visit and the effect type. The projected child context is still used to calculate the effect request, but it is not used to calculate internal identity.
+
+Workflow authors no longer provide the internal effect key. If an external API needs its own idempotency key, the action sends that external key as part of the request to that API. Internal execution identity and an external API key are separate facts.
+
+The effect store keeps its request fingerprint check. Reusing one logical effect identity with a different request remains a hard conflict.
+
+### One run command
+
+The host sends the worker one tagged command:
+
+- `start` begins a root run.
+- `resume` continues the same interrupted run from saved state.
+- `continue` creates a child from an accepted waiting checkpoint.
+- `restart` creates a fresh child after a terminal result.
+
+The worker handles this command with one exhaustive switch. Invalid combinations fail before workflow code runs.
+
+A restart uses the same approved workflow definition and requested input, but it begins at the first node. It does not copy parent steps, outputs, results, open interactions, settings mutations, or effect reservations. The parent run ID and root run ID remain saved as history. The saved history also includes the restart number and terminal fingerprint.
+
+A continuation remains the only path that carries checkpoint state forward. It requires a waiting parent and the exact accepted decision or submission.
+
+The engine should expose one internal entry point that accepts this tagged command. The superseded parent-ID heuristic is removed in the same alpha change.
+
+### One durable transition interface
+
+The existing run store becomes the only interface used by host orchestration for durable run changes. It can use focused internal modules, but callers see typed operations rather than SQL or booleans.
+
+The interface covers:
+
+- starting and ending exact workflow turns;
+- reserving and settling exact effects;
+- starting, pausing, and resuming runs;
+- finishing and timing out runs;
+- cancelling runs;
+- preparing continuations and restarts;
+- recording worker failure and recovery state.
+
+Each operation checks the run generation and claim token in one transaction. It also checks the expected revision and run state against the exact resource identity. It returns one of these results:
+
+- `applied` with the new saved value;
+- `adopted` with an equal saved value;
+- `conflict` with the conflicting evidence;
+- `recoveryRequired` with the saved reason.
+
+A boolean result is not sufficient for a lifecycle change. Callers must know whether another path already completed the same change or whether the request conflicts with current state.
+
+### Workflow-turn ownership
+
+`workflowTurn.report` remains the single version-1 operation for Pi model turns.
+
+At Pi `agent_start`, the extension proposes the exact sent workflow message and a stable turn request ID. The host atomically returns an active turn or reports that no workflow owns the Pi turn. The extension starts workflow recording only after an active result.
+
+At Pi `agent_end`, the extension ends the exact active turn. Matching repeated reports return the saved result. Conflicting evidence remains an error.
+
+When a run becomes terminal, the same state transaction ends its remaining open turns as `lost` and cancels still-pending workflow messages. A late report cannot revive the run. If a connection closes at an uncertain point, the extension does not attach the next Pi turn. The existing branch and idle report lets the host settle an unproved open turn as `lost`.
+
+### Typed run data
+
+Run input and final output are JSON. Run error and presentation instructions are text. Code reads them through named store methods:
+
+- `readRunInput()`;
+- `readRunFinalOutput()`;
+- `readRunError()`;
+- `readPresentationInstructions()`;
+- `readTerminalFacts()`.
+
+Callers do not read these blob hashes directly. `readTerminalFacts()` is the only source for terminal messages and ancestor outcomes. It checks media types and returns one typed result.
+
+The underlying content-addressed blob store remains general. The run store owns the meaning of each run column.
+
+### Control state before presentation
+
+Finishing or cancelling a run commits its execution state first. That transaction saves the final status and ends open turns. It cancels pending interactions and messages before it releases the claim. It also records the terminal facts needed for presentation.
+
+Terminal Pi-message creation is an idempotent follow-up transition derived from those saved facts. A host restart can create a missing terminal message later. A presentation error is recorded for repair, but it cannot undo the terminal state or retain execution authority.
+
+This separation applies to completion, failure, timeout, and cancellation.
+
+### Retry only after progress
+
+Every worker launch records the run revision it received. A normal worker exit reports a typed outcome to the host. Known bootstrap and workflow errors include the phase and error text.
+
+If a worker process disappears without a report, the host compares the current run revision with the launch revision. It may resume automatically only when durable progress or a saved recovery transition changed that revision.
+
+If no revision changed, the host parks the run with the worker failure and stops automatic launch. The user can inspect, cancel, or explicitly resume it. This rule has no arbitrary retry count. The same unchanged state is never executed in a tight loop.
+
+The display reports `running` only while one accepted worker or origin-session turn is doing current work. A parked no-progress failure reports its recovery reason.
+
+## State and protocol changes
+
+This is an alpha hard cut in schema and protocol version 1. The implementation must not add a version-2 identifier or a compatibility path.
+
+Expected changes include:
+
+- a tagged worker run command in the existing worker protocol;
+- full compiled node identity for managed effects;
+- typed results for lifecycle transitions and turn reports;
+- typed run-data readers;
+- durable no-progress worker failure evidence if the existing event records cannot express it without inference.
+
+Prefer existing tables and event records when they express the contract directly. If the durable no-progress rule requires a new column or constraint, change version-1 DDL in place. An old database then fails before mutation with the standard backup-and-reset instruction.
+
+Existing structurally valid state can use normal terminal and idle-session reconciliation. Do not add migration code to repair old table shapes.
+
+## Implementation plan
+
+### Freeze the failures in tests
+
+Add focused tests that reproduce the current behavior before changing it:
+
+- Mount workspace preparation directly and again under documentation, then prove the current automatic effect key collides.
+- Restart a failed workflow and prove the worker selects checkpoint continuation.
+- Build terminal ancestry with a failed parent and prove ancestor reading uses the wrong media type.
+- Cancel a child of a failed run and prove presentation failure rolls back cancellation.
+- Crash an uninitialized worker without a revision change and prove the host repeatedly claims it.
+- End a workflow turn during a terminal race and prove a later ordinary Pi turn can inherit old ownership.
+
+The final versions of these tests must assert the corrected behavior. Do not preserve assertions for the defects.
+
+### Move execution identity into the engine
+
+Change managed-effect identity in `src/workflows/definition.ts`, `src/workflows/composition.ts`, `src/workflows/engine.ts`, and the related types.
+
+The compiled engine passes the full node path and visit number to effect reservation. Child-context projection remains limited to workflow-authored request and action functions. Remove the old automatic key calculation from projected `state.currentNode`.
+
+Update authoring docs and all built-in workflows in the same change. Keep no alias for the old internal key contract.
+
+### Make worker commands explicit
+
+Add the tagged run command to `src/server/workflow-runner-protocol.ts`, the host bootstrap response, and `src/server/workflow-runner-entry.ts`.
+
+Replace the `initialized` and `parentRunId` dispatch heuristic with an exhaustive command switch. Add the engine path for a fresh restart and keep checkpoint continuation separate. Remove the superseded dispatch code.
+
+### Centralize durable transitions
+
+Move direct lifecycle SQL from `src/server/runner.ts` into typed store operations in the state and workflow-store modules. Replace ambiguous boolean returns used by run failure and cancellation with typed results.
+
+Keep claim fencing and revision checks in each state transaction. The runner handles process supervision and protocol routing only.
+
+### Fix terminal state and cancellation
+
+Add the typed run-data readers and use `readTerminalFacts()` for the current result and every ancestor result. Remove direct JSON reads of error hashes.
+
+Commit terminal control state independently from terminal-message creation. Add idempotent reconciliation for a terminal run that has no terminal workflow message.
+
+After this change, the currently paused failed-child case must cancel without a database reset.
+
+### Finish workflow-turn ownership
+
+Implement the approved host-owned turn contract in the state store and host runner. Apply it to the extension coordinator and session view. Then connect it to recorder integration.
+
+A terminal run must have no open workflow turn. A later ordinary Pi turn must produce no workflow-turn report for the terminal run.
+
+### Stop no-progress worker loops
+
+Add structured worker exit reports for all caught bootstrap and execution failures. Save the launch revision and compare it on an unreported exit.
+
+Park an unchanged run with a clear recovery reason. Resume automatically only after a newer durable revision makes another launch meaningful.
+
+### Remove old paths
+
+Delete:
+
+- effect keys derived from projected local node names;
+- restart dispatch based only on `parentRunId`;
+- direct error-hash JSON reads;
+- lifecycle SQL in host orchestration where a typed store operation replaces it;
+- cancellation paths that depend on successful terminal presentation;
+- automatic relaunch of the same unchanged worker state;
+- extension turn ownership that has not been accepted by the host.
+
+Do not keep feature flags or fallback behavior.
+
+### Update documentation
+
+Update `WORKFLOW_SERVER.md`, `SQLITE_STATE.md`, and `workflows.md` after implementation so they describe the shipped interfaces and recovery behavior. Keep this plan as the decision and implementation record.
+
+## Tests
+
+### Composition and effects
+
+- Two mounts of the same action receive different full execution identities.
+- A crash retry of one unfinished node visit reuses its identity.
+- A later loop visit receives a new identity.
+- The same identity and request adopts the saved effect.
+- The same identity with another request returns a controlled conflict.
+
+### Run commands
+
+- Root start begins at the first node.
+- Resume uses the same run and saved current node.
+- Continuation accepts only a waiting checkpoint parent and carries the approved state.
+- Restart accepts a terminal parent and begins with no parent steps, outputs, results, or effects.
+- Invalid command and state combinations fail before workflow code runs.
+
+### Terminal state
+
+- Completed, failed, timed-out, and cancelled ancestors produce typed terminal facts.
+- A text error is never passed to `readJson()`.
+- Cancellation commits even when terminal presentation is forced to fail.
+- A later reconciliation creates the missing terminal message once.
+- Terminalization ends open turns and pending interactions in the same state transaction.
+
+### Runner recovery
+
+- A worker crash after a newer durable revision resumes safely.
+- A worker crash at the same revision parks once and does not relaunch.
+- A known bootstrap error becomes a saved failure instead of a process loop.
+- The widget and `piw` show the same parked reason.
+
+### Pi turn ownership
+
+- A provider error ends the exact accepted turn.
+- Repeated and reordered reports return saved results or controlled conflicts.
+- A terminal race cannot leave an open turn.
+- Reconnect settles an unproved turn as `lost`.
+- A later ordinary Pi message creates no workflow turn or workflow recorder.
+
+### Full regression
+
+Run Autoimplement with its direct workspace preparation and nested Autodoc workspace preparation. Force the first run to fail after a managed action. Restart it and then pause and cancel it. Prove that effect identities do not collide and restart begins cleanly. Also prove that terminal facts remain readable and cancellation commits without a worker loop.
+
+Automated tests use temporary directories and deterministic providers. They do not call a real model.
+
+## Acceptance criteria
+
+- One component owns each identity and state decision.
+- Included workflows cannot collide because they share local node names.
+- Restart and checkpoint continuation cannot enter each other's engine path.
+- Every run column is read with its declared data type.
+- Control commands remain effective when presentation fails.
+- A worker cannot relaunch unchanged state indefinitely.
+- A terminal run has no open workflow turn.
+- Later ordinary Pi turns cannot attach to terminal workflow work.
+- No raw SQLite uniqueness or media-type error reaches normal recovery paths.
+- Server, extension, widget, CLI, Herdr, and `piw` agree on run activity.
+- Pi core and private Pi APIs remain unchanged. Pi session schemas also remain unchanged.
+- One host and one database remain. The system keeps one client protocol and one production runtime.
+
+## Verification
+
+Run:
+
+```bash
+npm run check
+npm run test:e2e
+npm run test:e2e:live -- --runtime-only
+git diff --check
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+cargo test --manifest-path tui/Cargo.toml
+cargo clippy --manifest-path tui/Cargo.toml --all-targets --all-features -- -D warnings
+cargo fmt --manifest-path tui/Cargo.toml --check
+```
+
+After deterministic checks pass, install the built package locally. Run a clean no-op workflow. Then run the composed Autoimplement regression and a forced provider-error recovery check. Confirm the widget and `piw` status at each stage. Use a real model only for the final manual installed-package check, with an explicit provider and model selected by the operator.
+
+Run Pi Reviewer against `main` until no P0 or P1 finding remains. Check pull-request comments and CI before merge.
+
+## Scope
+
+The implementation may change Pi Workflows engine, compiler, worker protocol, host state methods, extension coordination, viewer projection, built-in workflows, tests, and documentation in this repository.
+
+## Non-goals
+
+- No Pi core or private Pi API changes.
+- No Pi session schema changes.
+- No new service, database, state root, or production runtime.
+- No operating-system service installation.
+- No migration or compatibility path for older alpha state.
+- No release or package publication as part of implementation.
+- No exactly-once claim for provider calls or external effects.
+
+## Assumptions
+
+- Pi continues to provide the documented extension lifecycle events and session APIs.
+- The host remains the only production process that opens live SQLite state.
+- A package update can require the documented backup and reset when version-1 DDL changes.
+- External systems remain responsible for their own stable idempotency keys or read-back checks.

package/docs/DEFERRED_TURNS.md

@@ -1,6 +1,6 @@
 # Terminal workflow messages
 
-This specification defines the final Pi message for an interactive workflow. It replaces the separate deferred-turn and `workflow_turn_intents` design. Terminal messages use the same host state, client operations, and extension coordinator as all other [workflow messages](WORKFLOW_STEP_MESSAGES.md).
+This specification defines the final Pi message for an interactive workflow. It replaces the separate deferred-turn and `workflow_turn_intents` design. Terminal messages use the same server state, client operations, and extension coordinator as all other [workflow messages](WORKFLOW_STEP_MESSAGES.md).
 
 The earlier [deferred-turn plan](plans/2026-08-21-deferred-turn-intents-plan.md) and [terminal restart plan](plans/2026-08-27-workflow-terminal-restart-plan.md) remain historical design records. This document is the current contract.
 
@@ -14,7 +14,7 @@ The earlier [deferred-turn plan](plans/2026-08-21-deferred-turn-intents-plan.md)
 
 ## Core rule
 
-The host creates one `terminal` workflow message in the same transaction that records the final terminal outcome. Only the final run in a continuation chain creates this message. A parent settled by a continuation does not create one.
+The server creates one `terminal` workflow message in the same transaction that records the final terminal outcome. Only the final run in a continuation chain creates this message. A parent settled by a continuation does not create one.
 
 The terminal message uses the same `workflow_messages` table and `WorkflowMessageCoordinator` as steps, decisions, notifications, and follow-ups. Initial, reminder, and resumed prompts are one step-message kind. There is no `workflow_turn_intents` table, deferred-turn sender, terminal sender, or second send path.
 
@@ -28,9 +28,9 @@ A terminal message can report:
 - workflow failure;
 - timeout with no recovery edge;
 - cancellation;
-- launch or worker failure that became the final run outcome.
+- launch or runner failure that became the final run outcome.
 
-Pause, Escape, a waiting checkpoint, a nonfinal continuation parent, user hold, and normal host shutdown do not create a terminal message.
+Pause, Escape, a waiting checkpoint, a nonfinal continuation parent, user hold, and normal server shutdown do not create a terminal message.
 
 A claim loss is a handoff. It creates no terminal outcome or terminal message unless later recovery proves that the run itself failed.
 
@@ -48,15 +48,15 @@ A terminal workflow message is open only until its first model turn ends. The ex
 
 The end report includes `stopReason: "completed"`, `"aborted"`, or `"error"`. Response-entry evidence comes from `ctx.sessionManager.getBranch()` after `agent_end` and can be null. A repeated report adopts the stored result. A stale turn ID cannot end a newer turn.
 
-If Pi restarts after a terminal message was sent but before its end was reported, the extension's idle-session active-branch report records a synthetic end with `stopReason: "lost"`. Host restart alone does not close the turn. The terminal result remains durable and visible, but the host does not pretend that the model turn completed.
+If Pi restarts after a terminal message was sent but before its end was reported, the extension's idle-session active-branch report records a synthetic end with `stopReason: "lost"`. Server restart alone does not close the turn. The terminal result remains durable and visible, but the server does not pretend that the model turn completed.
 
 ## Sending and recovery
 
-After every host connection, the coordinator waits for the complete origin-session view and reports the active branch before it sends a workflow message or reports a model turn. The host gives the next eligible pending message only to the active coordinator epoch for that session. A replacement connection fences the old one.
+After every server connection, the coordinator waits for the complete origin-session view and reports the active branch before it sends a workflow message or reports a model turn. The server gives the next eligible pending message only to the active coordinator epoch for that session. A replacement connection fences the old one.
 
 The coordinator waits until Pi is idle and has no pending messages. It keeps the terminal workflow message ID in its in-memory queued map, checks the active branch, and reports a matching entry before any send. Otherwise, it performs one final synchronous check that Pi is idle, has no pending input, the message is absent, and its connection still owns the active epoch. It calls documented `pi.sendMessage()` without an `await` between that check and the call.
 
-A matching hidden workflow message ID in the active branch proves that Pi accepted the message. The host records the matching Pi entry ID and changes the message to `sent`, even if its source cancelled it after the send. If the extension reloads, it reports the active branch and adopts that entry before another send.
+A matching hidden workflow message ID in the active branch proves that Pi accepted the message. The server records the matching Pi entry ID and changes the message to `sent`, even if its source cancelled it after the send. If the extension reloads, it reports the active branch and adopts that entry before another send.
 
 Absence is usable only when all three facts are true:
 

package/docs/DESIGN_PHILOSOPHY.md

@@ -38,7 +38,7 @@ Reading shared state never gives mutation authority. Every durable write checks
 
 ## Boundaries
 
-The workflow engine stays independent of Pi. The Pi extension hosts the engine and connects it to a conversation. Controllers manage durable external resources. Viewers read recorded state without changing it.
+The workflow engine stays independent of Pi. The Pi extension servers the engine and connects it to a conversation. Controllers manage durable external resources. Viewers read recorded state without changing it.
 
 Keep these layers separate and connect them through small public interfaces.
 

package/docs/HUMAN_DECISIONS.md

@@ -168,7 +168,7 @@ The accepted human sources are:
 - the Pi interactive decision view; and
 - a configured external decision channel such as Telegram.
 
-The host assigns the source. A workflow or model cannot claim that an answer came from a person. Pi non-interactive modes can wait for Telegram, but they cannot manufacture a Pi UI answer.
+The server assigns the source. A workflow or model cannot claim that an answer came from a person. Pi non-interactive modes can wait for Telegram, but they cannot manufacture a Pi UI answer.
 
 ## Audiences and channel profiles
 
@@ -199,7 +199,7 @@ Private configuration maps the audience to channels:
 }
 ```
 
-The workflow never receives a bot token, user ID, chat ID, Telegram message ID, or Pi session detail. Channel profiles are private host configuration and are excluded from run presentation.
+The workflow never receives a bot token, user ID, chat ID, Telegram message ID, or Pi session detail. Channel profiles are private server configuration and are excluded from run presentation.
 
 pi-workflows keeps credential references in a separate private file. A Telegram credential points to an existing absolute mode-`0600` token file:
 
@@ -222,7 +222,7 @@ The same Unix account can read a local credential file. This design prevents acc
 
 ## Channel interface
 
-The host owns decision state and launches each external channel adapter as a supervised child process. The private child protocol has these message kinds:
+The server owns decision state and launches each external channel adapter as a supervised child process. The private child protocol has these message kinds:
 
 - `channel.ready`;
 - `channel.present`;
@@ -230,15 +230,15 @@ The host owns decision state and launches each external channel adapter as a sup
 - `channel.settle`; and
 - `channel.exiting`.
 
-Each message names the adapter epoch, channel profile, saved request or settlement record, expected revision, and stable attempt ID. The host validates and saves every state change. The child never opens SQLite, loads workflow code, changes a run directly, receives the canonical decision subject, or receives another channel's credentials.
+Each message names the adapter epoch, channel profile, saved request or settlement record, expected revision, and stable attempt ID. The server validates and saves every state change. The child never opens SQLite, loads workflow code, changes a run directly, receives the canonical decision subject, or receives another channel's credentials.
 
 Channel handling is independent from workflow routing. A failed Telegram send leaves the decision available in Pi. Audience policy decides whether one successful channel is enough or whether all configured channels must receive the request.
 
 ### Pi channel
 
-The host creates one `decision` workflow message for the origin session. The shared extension coordinator shows it through documented `pi.sendMessage()` with no model turn. The message lists the request ID, choices, input rule, and deadline. It uses no blocking Pi dialog and no private Pi API.
+The server creates one `decision` workflow message for the origin session. The shared extension coordinator shows it through documented `pi.sendMessage()` with no model turn. The message lists the request ID, choices, input rule, and deadline. It uses no blocking Pi dialog and no private Pi API.
 
-A verified operator answers with `/workflow answer` or the matching `piw` control. The host validates the choice and optional text, records the Pi channel as the source, and accepts only the first valid winner. Closing or reloading Pi cannot lose the request. On `session_start` or `session_tree`, the extension adopts an existing decision message or creates one new `decision` message when the pending request has no entry on the active branch.
+A verified operator answers with `/workflow answer` or the matching `piw` control. The server validates the choice and optional text, records the Pi channel as the source, and accepts only the first valid winner. Closing or reloading Pi cannot lose the request. On `session_start` or `session_tree`, the extension adopts an existing decision message or creates one new `decision` message when the pending request has no entry on the active branch.
 
 ### Telegram channel
 
@@ -252,11 +252,11 @@ A choice without input submits from its button. A text choice such as `replan` w
 4. the adapter verifies the numeric user ID, chat ID, reply message ID, decision ID, and request digest; and
 5. the exact received text becomes `input.instructions`.
 
-The adapter does not infer a choice from ordinary chat text. Callback payloads contain short opaque IDs because Telegram limits callback data. The host's channel records map each opaque ID to the validated decision request. Credentials remain outside the database and reach only the matching supervised adapter child.
+The adapter does not infer a choice from ordinary chat text. Callback payloads contain short opaque IDs because Telegram limits callback data. The server's channel records map each opaque ID to the validated decision request. Credentials remain outside the database and reach only the matching supervised adapter child.
 
-Telegram permits one long-polling consumer for a bot profile. The global host starts at most one adapter child for that profile and keeps the package-owned on-demand host process alive while an external decision is pending. No Pi process or adapter child owns a SQLite lease. If the host stops, the next Pi, CLI, or `piw` client starts it and the host recovers the saved channel state before it starts another adapter child. This design installs no operating-system service.
+Telegram permits one long-polling consumer for a bot profile. The global server starts at most one adapter child for that profile and keeps the package-owned on-demand server process alive while an external decision is pending. No Pi process or adapter child owns a SQLite lease. If the server stops, the next Pi, CLI, or `piw` client starts it and the server recovers the saved channel state before it starts another adapter child. This design installs no operating-system service.
 
-The Bot API does not provide an idempotency key for `sendMessage`. Before it tells the adapter to send or settle a message, the host records the exact attempt in `effects` and `effect_attempts`. A confirmed Telegram message ID settles the effect and remains in its result. A timed-out, disconnected, or interrupted exact attempt with no proof becomes `ambiguous` and is not retried automatically. Pi remains available while the operator checks Telegram and explicitly confirms or retries the operation. This prevents blind duplicate sends without claiming exactly-once Telegram behavior.
+The Bot API does not provide an idempotency key for `sendMessage`. Before it tells the adapter to send or settle a message, the server records the exact attempt in `effects` and `effect_attempts`. A confirmed Telegram message ID settles the effect and remains in its result. A timed-out, disconnected, or interrupted exact attempt with no proof becomes `ambiguous` and is not retried automatically. Pi remains available while the operator checks Telegram and explicitly confirms or retries the operation. This prevents blind duplicate sends without claiming exactly-once Telegram behavior.
 
 ## Durable decision records
 
@@ -328,7 +328,7 @@ Adoption does not change the lease, claim generation, queue state, timestamps, o
 
 This alpha change updates the current request, accepted-result, receipt, resolution, continuation, and snapshot contracts in place. Old active runs refuse resume through normal source and definition identity checks. There is no compatibility reader, migration, dual path, or new schema generation. The continuation startup fix uses existing queue and lease records. It adds no field, table, migration, or schema version. Existing compatible prepared or initialized continuations are adopted. Updated viewers label a human decision as a checkpoint, show its deadline and automatic action when present, and keep the canonical subject separate. Private channel configuration and transport identifiers remain hidden.
 
-The engine remains independent from Pi and Telegram. Core code owns decision contracts and validation. The host owns durable acceptance, continuation, workflow messages, and channel-child supervision. The Pi extension owns documented session presentation and controls. The Telegram adapter child owns Bot API translation. Workflow definitions own only the question, choices, audience, and routes.
+The engine remains independent from Pi and Telegram. Core code owns decision contracts and validation. The server owns durable acceptance, continuation, workflow messages, and channel-child supervision. The Pi extension owns documented session presentation and controls. The Telegram adapter child owns Bot API translation. Workflow definitions own only the question, choices, audience, and routes.
 
 ## Contract impact
 
@@ -360,7 +360,7 @@ The implementation must test:
 - identical and conflicting retries;
 - crashes before and after answer acceptance and continuation creation;
 - ambiguous Telegram sends;
-- one supervised long-poll adapter per profile and host-restart recovery;
+- one supervised long-poll adapter per profile and server-restart recovery;
 - decision cancellation and expiry;
 - included `plan-approval` routes and bounded replan loops;
 - viewer redaction; and

package/docs/HUMAN_DECISION_PRESENTATIONS.md

@@ -59,7 +59,7 @@ A request uses `pi-workflows.human-decision-request.v1`. It contains:
 | `title`              | Yes      | Short decision title shown by every channel.    |
 | `subject`            | Yes      | Canonical JSON data used by the workflow.       |
 | `presentation`       | Yes      | Human-readable content defined below.           |
-| `audience`           | Yes      | Named audience resolved by the host.            |
+| `audience`           | Yes      | Named audience resolved by the server.          |
 | `choices`            | Yes      | Typed choices and optional input contracts.     |
 | `revision`           | Yes      | Positive decision revision.                     |
 | `subjectDigest`      | Yes      | SHA-256 digest of the canonical subject.        |
@@ -216,13 +216,13 @@ The renderer:
 
 The renderer never adds an ellipsis in place of omitted decision content.
 
-The host saves each channel message before the adapter sends it. It records each part after an unambiguous response. If a send result is uncertain, the host marks that channel message `ambiguous` and does not retry that part or later parts automatically. Another configured channel can still answer the decision.
+The server saves each channel message before the adapter sends it. It records each part after an unambiguous response. If a send result is uncertain, the server marks that channel message `ambiguous` and does not retry that part or later parts automatically. Another configured channel can still answer the decision.
 
 ### Pi
 
-The host creates one `decision` workflow message. The shared extension coordinator sends it through documented `pi.sendMessage()` without starting a model turn. Its custom renderer shows the complete presentation and fingerprint with the choices, input rules, request ID, and deadline. It wraps and scrolls with normal Pi custom-message behavior.
+The server creates one `decision` workflow message. The shared extension coordinator sends it through documented `pi.sendMessage()` without starting a model turn. Its custom renderer shows the complete presentation and fingerprint with the choices, input rules, request ID, and deadline. It wraps and scrolls with normal Pi custom-message behavior.
 
-A verified operator answers through `/workflow answer` or the matching `piw` control. When Telegram or another channel accepts the decision, the host cancels an unsent Pi decision message. A sent card remains normal conversation history, while later answer controls return the saved winner. Pi Workflows does not open a blocking dialog, modify Pi core, or use undocumented TUI state.
+A verified operator answers through `/workflow answer` or the matching `piw` control. When Telegram or another channel accepts the decision, the server cancels an unsent Pi decision message. A sent card remains normal conversation history, while later answer controls return the saved winner. Pi Workflows does not open a blocking dialog, modify Pi core, or use undocumented TUI state.
 
 ### Other channels
 

package/docs/MONITOR.md

@@ -125,7 +125,7 @@ The action step returns whether the action succeeded, failed, or was blocked, wi
 
 The repair input preserves the action request, target evidence, authority, constraints, repository, and delivery limits. Existing plan approval rules still apply when the recorded contract requires them.
 
-Paid workers affected by a shared code or data defect must stop at safe boundaries before repair starts. Monitor preserves their durable outputs and failure evidence.
+Paid runners affected by a shared code or data defect must stop at safe boundaries before repair starts. Monitor preserves their durable outputs and failure evidence.
 
 After a completed repair, Monitor runs `observe` immediately. If the same failure ID and target-state ID return, Monitor stops. It does not run the same repair cycle again.