@osolmaz/pi-workflows 0.16.0 → 0.16.2

package/docs/DEFERRED_TURNS.md

@@ -1,338 +1,110 @@
-# Deferred workflow turns
+# Terminal workflow messages
 
-This specification defines how Pi Workflows schedules one successor agent turn after a workflow event stops or strands the current turn. It covers every top-level interactive terminal result, cancellation, timeout, launch failure, controller interruption, and claim loss.
+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).
 
-The implementation plans are [Guarantee one successor turn after workflow interruption](plans/2026-08-21-deferred-turn-intents-plan.md) and [Workflow terminal decision and restart](plans/2026-08-27-workflow-terminal-restart-plan.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.
 
 ## Terms
 
-- **Source event:** The workflow event that creates the need for another turn.
-- **Turn intent:** The durable obligation to send one successor turn.
-- **Natural successor:** The next workflow agent prompt or result presentation.
-- **Fallback:** A factual model-facing message sent when no natural successor remains.
-- **Resolution:** The recorded fact that one message path satisfied the intent.
-- **Target session:** The Pi session that owns the successor turn.
+- **Continuation chain:** One interactive workflow and the runs created to continue its checkpoints.
+- **Final run:** The last run in the continuation chain.
+- **Terminal outcome:** The final run's completed, failed, timed-out, or cancelled result.
+- **Terminal workflow message:** The one model-facing message that reports the terminal outcome and offers valid next actions.
+- **Restart:** A new immutable run created from an allowed action in the terminal turn.
 
 ## Core rule
 
-Each eligible source event creates at most one turn intent. Exactly one of these message paths can resolve it:
+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.
 
-1. a workflow agent prompt;
-2. a result presentation;
-3. a factual fallback.
+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.
 
-Every top-level interactive terminal run owns one intent. Its presentation and fallback claim that same intent before sending. A waiting presentation can resolve an earlier interruption intent, but waiting state does not create a terminal intent. A resolved intent cannot start another turn.
+The terminal message records the factual outcome before it starts a model turn. It does not keep the old assistant turn alive and does not delay cancellation or process cleanup.
 
-Cancellation and process termination remain immediate. Pi Workflows does not keep the old assistant turn alive and does not wait for the successor before stopping active work.
+## Outcomes
 
-## Intent lifecycle
+A terminal message can report:
 
-An intent has two stored states:
+- successful completion;
+- workflow failure;
+- timeout with no recovery edge;
+- cancellation;
+- launch or worker failure that became the final run outcome.
 
-| State    | Condition                                                     | Meaning                                                   |
-| -------- | ------------------------------------------------------------- | --------------------------------------------------------- |
-| Pending  | `resolvedAt` is null                                          | No message path has resolved the intent.                  |
-| Resolved | `resolvedAt`, `resolution`, and `resolutionMessageId` are set | One message path was sent or found in the session branch. |
+Pause, Escape, a waiting checkpoint, a nonfinal continuation parent, user hold, and normal host shutdown do not create a terminal message.
 
-Pending intents have separate fallback eligibility:
+A claim loss is a handoff. It creates no terminal outcome or terminal message unless later recovery proves that the run itself failed.
 
-| Eligibility | Condition            | Meaning                                                          |
-| ----------- | -------------------- | ---------------------------------------------------------------- |
-| Ineligible  | `eligibleAt` is null | A natural workflow prompt or presentation can still arrive.      |
-| Eligible    | `eligibleAt` is set  | Durable state shows that no immediate natural successor remains. |
+## Message content and controls
 
-A claim is temporary coordination state. A claim does not resolve an intent. An expired claim can be acquired again.
+The message names the outcome and the run. It contains only controls valid for that saved outcome. A successful final run can offer follow-up work. A failed or timed-out final run can offer an allowed restart. A cancelled run offers no restart. An ambiguous external effect remains parked and creates no terminal message until explicit recovery produces a real terminal outcome.
 
-Valid resolutions are:
+A restart creates a new run. It does not reopen or mutate the terminal run. It keeps the approved input and source identity, uses a stable action fingerprint, rejects duplicate activation, and stops after three restarts in one chain.
 
-```text
-workflowPrompt | presentation | fallback
-```
+The terminal result remains visible in the origin-session view while its terminal workflow message is pending or its first model turn is open, and then for 60 seconds after that turn ends. This display retention gives no claim, queue reservation, or execution authority. A new run in that session replaces it immediately. A verified operator can also clear it through `sessionView.clearTerminal`, exposed by `/workflow clear` and `piw`.
 
-Resolution records message delivery into the Pi session or the presence of the same message in the session branch. It does not prove that a model turn started or completed.
+## Turn tracking
 
-## Source events
+A terminal workflow message is open only until its first model turn ends. The extension reports the matching `agent_start` and `agent_end` through `workflowTurn.report`.
 
-Valid causes are:
+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.
 
-```text
-agentCancelled | timedOut | failed | launchFailed | controllerInterrupted | claimLost | terminal | cancelled
-```
+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.
 
-The event policy is:
+## Sending and recovery
 
-| Event                                                          | Intent                                        | Fallback rule                                                                |
-| -------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |
-| Top-level interactive run completes                            | Create one terminal intent.                   | Presentation and factual fallback compete for the intent.                    |
-| Top-level interactive run fails or times out                   | Create or reuse the abort intent.             | Make eligible after the terminal state is durable.                           |
-| Agent or user cancels a top-level run                          | Create before turn abort when needed.         | Make eligible after durable cancellation; the decision defaults to stopping. |
-| Workflow reports started, then crashes before its first prompt | Create after durable failure.                 | Create as eligible.                                                          |
-| Queued launch activation fails                                 | Create after the queue row is durably failed. | Create as eligible.                                                          |
-| Controller interrupts an active workflow turn                  | Create before the turn abort when possible.   | Durable terminal or handoff state decides eligibility.                       |
-| Active workflow turn loses its queue claim                     | Create before the turn abort when possible.   | Keep ineligible while a new owner can continue.                              |
-| Waiting result has a presentation                              | Do not create a terminal intent.              | It can resolve an earlier interruption intent through presentation.          |
-| Controller child or internally owned run ends                  | Do not create a terminal intent.              | Its owner receives the result.                                               |
-| Workflow pause                                                 | Do not create.                                | No automatic model turn.                                                     |
-| User Escape or held workflow                                   | Do not create.                                | No automatic model turn.                                                     |
-| Session shutdown                                               | Do not create.                                | A closing session cannot start another turn.                                 |
+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.
 
-A terminal failure after a successful start tool result is eligible even when it did not first call `ctx.abort()`. This rule covers asynchronous runtime validation and startup failures that the user can see in the UI but the model cannot see in its current context.
+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.
 
-## Stable identity
+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.
 
-`intentId` is a deterministic digest of:
+Absence is usable only when all three facts are true:
 
-- target session ID;
-- run ID;
-- source event ID;
-- node ID or `$launch`;
-- attempt ID when known;
-- cause.
+1. the active branch has no matching hidden workflow message ID;
+2. `ctx.isIdle()` is true; and
+3. `ctx.hasPendingMessages()` is false.
 
-The same source event must always produce the same ID. Reusing an ID with different immutable facts is an error.
+If Pi or the extension disappears after `pi.sendMessage()` but before the branch report, the message stays `pending`. A replacement extension reports the active branch before it sends. Documented Pi APIs do not prove cross-branch absence or exactly-once model execution. Pi Workflows guarantees its saved message identity, active-branch evidence, and recovery decisions. It does not claim more.
 
-`sourceEventId` identifies the source transition independently of delivery retries. Terminal handling must reuse an earlier abort event instead of creating a second terminal event for the same interruption.
+## Follow-ups
 
-IDs use the existing controller-store key limit of 512 characters. The digest representation must be stable across processes and extension restarts.
+Successful completion can have ordered [follow-up prompts](2026-08-25-workflow-follow-ups.md). They use the same workflow-message coordinator.
 
-## Stored record
+A follow-up is eligible only after:
 
-`workflow_turn_intents` lives in the existing controller SQLite database.
+- the final run is successfully completed;
+- its terminal workflow message has been sent;
+- the terminal model turn has ended;
+- every earlier follow-up is settled or cancelled; and
+- no nonterminal run reserves the origin session.
 
-| Column                      | Null | Meaning                                      |
-| --------------------------- | ---- | -------------------------------------------- |
-| `intent_id`                 | No   | Deterministic primary key.                   |
-| `source_event_id`           | No   | Stable source transition identity.           |
-| `run_id`                    | No   | Related workflow run.                        |
-| `workflow_ref`              | No   | Workflow identity used in messages.          |
-| `target_session_id`         | No   | Session that can receive the successor.      |
-| `cause`                     | No   | Closed cause value.                          |
-| `node_id`                   | Yes  | Source node when known.                      |
-| `attempt_id`                | Yes  | Source attempt when known.                   |
-| `fallback_facts_json`       | No   | Bounded factual payload.                     |
-| `requested_at`              | No   | Absolute ISO 8601 creation time.             |
-| `eligible_at`               | Yes  | Absolute ISO 8601 fallback eligibility time. |
-| `resolved_at`               | Yes  | Absolute ISO 8601 resolution time.           |
-| `resolution`                | Yes  | Closed resolution value.                     |
-| `resolution_message_id`     | Yes  | Stable message identity.                     |
-| `delivery_claim_token`      | Yes  | Current claimant.                            |
-| `delivery_claim_expires_at` | Yes  | Claim expiry as epoch milliseconds.          |
+A follow-up turn is reported for ordering and recovery, but it does not make the completed workflow display as `running`.
 
-The table requires these indexes:
+## State and compatibility
 
-- unresolved intents by run and target session;
-- unresolved eligible intents by target session, eligibility time, and intent ID.
+This is an alpha hard cut in `pi-workflows-state` schema version 1.
 
-A resolved row has all three resolution fields. A pending row has none of them. A row cannot change immutable identity or source fields after creation.
+- `workflow_messages` owns terminal message content, `pending`, `sent`, or `cancelled` state, Pi entry evidence, and turn reports.
+- Run and continuation rows own terminal outcomes and chain identity.
+- `workflow_follow_ups` owns accepted follow-up source prompts and cancellation only.
+- `workflow_turn_intents` and `workflow_follow_up_queues` do not exist.
 
-## Fallback facts
-
-`fallback_facts_json` uses this versioned camelCase object:
-
-```json
-{
-  "schema": "pi-workflows.deferred-turn-facts.v1",
-  "workflowName": "autoimplement",
-  "runId": "20260821T081731Z-autoimplement-407480dd",
-  "observedState": "failed",
-  "cause": "failed",
-  "nodeId": "$launch",
-  "attemptId": null,
-  "reason": "scope must be a non-empty string",
-  "handoff": false
-}
-```
-
-Rules:
-
-- `schema` is required and has the exact value shown above.
-- `workflowName`, `runId`, `observedState`, and `cause` are required strings.
-- `nodeId`, `attemptId`, and `reason` are strings or null.
-- `handoff` is a required boolean.
-- `reason` is safe diagnostic text with at most 8,192 characters.
-- The serialized object is at most 64 KiB.
-- Unknown fields are rejected during alpha.
-- The object must not contain credentials, raw environment values, or unbounded command output.
-
-`handoff: true` means another runner can continue. A handoff message must not describe the run as terminal unless separate durable state proves it.
-
-## Store operations
-
-The controller store provides these internal operations:
-
-- `ensureWorkflowTurnIntent`
-- `getWorkflowTurnIntent`
-- `claimWorkflowTurnIntentForRun`
-- `claimEligibleWorkflowTurnIntentsForSession`
-- `makeWorkflowTurnIntentEligible`
-- `resolveWorkflowTurnIntent`
-- `releaseWorkflowTurnIntentClaim`
-- a bounded diagnostic list operation
-
-`ensureWorkflowTurnIntent` is idempotent when all immutable fields match. It fails on an identity collision.
-
-Claim operations use a caller-supplied token and lease duration. Resolution requires the matching live claim token. Conditional updates ensure that natural delivery and fallback cannot both resolve the same intent.
-
-List operations require a positive bounded limit and deterministic ordering.
-
-## Abort ordering
-
-For an eligible active-turn abort, Pi Workflows performs these steps in order:
-
-1. Record abort provenance on the active run.
-2. Build the source event and intent ID.
-3. Attempt to persist the intent.
-4. Record the intent ID in system-abort bookkeeping.
-5. Call `ctx.abort()`.
-
-The persistence attempt is synchronous because cancellation immediately crosses the turn boundary. A store failure does not prevent `ctx.abort()`. Terminal handling retries the same intent ID. If retry also fails, Pi Workflows reports that it could not preserve the successor-turn guarantee.
-
-## Natural delivery
-
-All extension-owned workflow prompts and result presentations pass through one `DeferredTurnCoordinator`.
-
-If no intent exists, the coordinator preserves current message content and delivery options.
-
-If a pending intent exists, the coordinator:
-
-1. waits until the old turn has settled or the session is verified idle;
-2. claims the intent for the run and session;
-3. adds `turnIntentId` to the message details;
-4. sends the normal prompt or presentation;
-5. resolves the intent with the matching resolution and message ID;
-6. releases the claim if sending fails.
-
-A prompt generated during abort handling must not be sent into the aborting turn. The coordinator releases it after `agent_settled`.
-
-## Fallback delivery
-
-Fallback synchronization runs:
-
-- after `agent_settled` and system-abort cleanup;
-- when the target session starts;
-- during the existing periodic synchronization pass while the session is idle.
-
-The fallback custom message uses this details object:
-
-```json
-{
-  "schema": "pi-workflows.deferred-turn-message.v1",
-  "turnIntentId": "deferred-turn:...",
-  "runId": "20260821T081731Z-autoimplement-407480dd",
-  "cause": "failed",
-  "presentation": {
-    "workflowName": "autoimplement",
-    "state": "failed",
-    "reasonKind": "maxSteps",
-    "restart": {
-      "count": 0,
-      "limit": 3
-    }
-  }
-}
-```
-
-`presentation` contains small, bounded display fields. `reasonKind` and `restart` are present only when the run records provide them. These fields do not replace or shorten the model prompt.
-
-The message type is `pi-workflows-deferred-turn`. Delivery uses:
-
-```ts
-{
-  deliverAs: "followUp",
-  triggerTurn: true,
-}
-```
-
-### Compact TUI card
-
-Interactive Pi registers a custom renderer for `pi-workflows-deferred-turn`. The collapsed card shows the workflow name, state or cause, run identity, and restart count when it is available. It does not show the terminal facts JSON, exact input, result, fingerprint, or model instructions.
-
-The renderer reads only the structured message details for its compact fields. It sanitizes workflow-derived text and uses Pi's standard TUI components, theme colors, and `expanded` state. A message with missing or invalid details renders as a safe generic workflow card.
-
-Expanding the card shows the complete existing message content. The model and session history receive that same content whether the card is collapsed or expanded. Restored messages use the same renderer and do not create another entry or model turn.
-
-This display behavior uses the documented `pi.sendMessage()` and `pi.registerMessageRenderer()` APIs. It does not change headless or RPC delivery. Presentation messages that already use `display: false` stay hidden. It adds no Pi core change, private API, database table, migration, store, or external resource.
-
-For a terminal run, the complete content contains the workflow identity and revision, terminal run ID, exact stored input, bounded result, terminal state and reason, restart count, and earlier terminal outcomes in the chain. It tells the model to use the current conversation, prefer a safe restart for an unfinished task after a technical or temporary failure, and stop for completed work, cancellation, missing authority, a required user decision, or a repeated failure. Values from input and result are data, not instructions.
-
-The content comes only from existing run and queue records. Pi owns conversation history. Pi Workflows does not identify, hash, copy, or store an original user message.
-
-Fallback delivery is disabled during session shutdown and while a user-interrupted workflow is held.
-
-## Selected launch and restart
-
-A terminal decision turn can reserve at most one workflow launch: `restart`, Monitor through normal `start`, or another workflow through normal `start`. The reservation records the source terminal intent, model tool call, and request fingerprint in the new run's existing launch options. It does not activate before `agent_settled`.
-
-Repeating the same tool call adopts the existing reservation or run. A different launch from the same terminal intent fails. Session-start and queue recovery activate a surviving reservation once when the session is idle.
-
-`restart` accepts the terminal run ID. It checks session ownership, terminal state, explicit cancellation, source identity and revision, repeated failure, and the restart limit. It creates a new immutable run from the exact stored reference, input, and safe launch settings. The old run does not change.
-
-Restart lineage in launch options records the root run ID, parent run ID, restart number, and parent terminal fingerprint. The fingerprint covers workflow identity and revision, exact input, terminal state, canonical result or error, and terminal reason. It excludes timestamps and run IDs. The same fingerprint cannot restart twice in one chain. A chain permits three restarts after the original run. Starting Monitor does not add restart lineage.
-
-## Delivery recovery
-
-Every resolving message includes the intent ID in its custom-message details.
-
-Before sending, the coordinator scans the current session branch for that ID. If the message is already present, the coordinator resolves the intent without sending again. This repairs a crash or SQLite failure that occurs after `sendMessage` succeeds but before resolution is stored.
-
-Store leases prevent concurrent processes from sending the same resolution. Branch identity handles the remaining send-before-resolution window.
-
-## Claim transfer
-
-Claim loss stops the old runner's work and all fenced SQLite writes. The intent stays pending and fallback-ineligible while another runner can resume the run.
-
-The new runner's next workflow prompt can resolve the intent. If durable state later proves a terminal outcome with no natural successor, terminal handling makes the intent eligible for fallback to its target session.
-
-Time alone does not prove terminal failure.
-
-## Launch notifications
-
-Workflow-authored `progress` and `final` notifications remain passive. They do not trigger model turns.
-
-The `launch_failure` notification kind is removed. Queued launch failure creates an eligible turn intent instead.
-
-Pending `launch_failure` rows from the earlier alpha contract are incompatible. Pi Workflows must stop with a clear controller-store reset instruction. It must not reinterpret, migrate, or silently delete those rows.
-
-## Post-completion follow-ups
-
-Deferred turns provide the terminal decision before ordered post-completion prompts. Those prompts represent user-requested normal work after successful completion, use `workflow_follow_up_queues` and `workflow_follow_ups`, and are delivered by the separate follow-up coordinator after the terminal intent is resolved. Neither feature reads or changes the other's rows.
-
-See [Continue normal work after a workflow finishes](2026-08-25-workflow-follow-ups.md).
-
-## Availability limits
-
-Pi Workflows can guarantee only the facts under its control:
-
-- the intent was stored;
-- a claimant acquired it;
-- a custom message was sent or found in the session branch;
-- the local intent was resolved.
-
-Pi Workflows cannot guarantee model start or completion with the current Pi API. It also cannot deliver after permanent loss of the process, target session, controller store, machine, or model provider.
-
-Undelivered intents remain pending. The implementation does not add a service to process them outside a live Pi session.
-
-## Compatibility
-
-This is an alpha hard cutover.
-
-- Keep `pi-workflows.controller-store.v1`.
-- Add `workflow_turn_intents` to the existing database.
-- Remove the launch-trigger runtime path.
-- Add no v2 schema, compatibility reader, dual write, alias, or feature flag.
-- Keep historical terminal SQLite runs readable because their contract does not change.
+The DDL digest changes in place. There is no migration, compatibility reader, dual path, fallback sender, alias, feature flag, or second schema. Incompatible state remains untouched and fails with the standard backup-and-reset instruction.
 
 ## Conformance
 
 An implementation conforms when:
 
-- every top-level interactive terminal run produces at most one intent and one decision message;
-- an agent self-cancel and a direct cancellation receive one fallback after settlement;
-- an asynchronous crash after a successful start result receives one fallback after settlement;
-- a natural recovery prompt or presentation suppresses fallback by resolving the same intent;
-- waiting checkpoints, controller children, internal owners, pause, Escape, user hold, and shutdown do not create terminal turns;
-- claim transfer permits natural resolution by the new owner and prevents stale writes;
-- one terminal turn reserves at most one launch and activates it after `agent_settled`;
-- exact replay adopts the same launch, while reload, lease expiry, and send-before-resolution failure do not duplicate turns or runs;
-- restart keeps the prior run immutable, preserves exact input, rejects cancellation and repeated fingerprints, and stops after three restarts;
-- passive workflow notifications keep their current behavior.
+- one continuation chain creates at most one terminal workflow message;
+- only the final run creates that message;
+- every terminal outcome uses the shared workflow-message path;
+- a busy Pi session cannot cause duplicate terminal messages or model turns;
+- reload reports the branch and adopts an existing active-branch entry before another send;
+- unproved absence leaves the message `pending` and cannot cause a retry before branch reporting;
+- a stale or disconnected coordinator epoch cannot send or report message state;
+- active-branch evidence changes a matching pending or cancelled message to sent;
+- an unended sent message receives a synthetic `lost` end only from an idle-session branch report after Pi restart;
+- terminal status remains visible while its message is pending or its first turn is open, and then for 60 seconds after that turn ends, without retaining workflow authority;
+- restart creates one separate run and never mutates the terminal run;
+- follow-ups wait for the terminal turn and use the same coordinator; and
+- no deferred-turn table, sender, or production fallback remains.

package/docs/HUMAN_DECISIONS.md

@@ -214,51 +214,49 @@ pi-workflows keeps credential references in a separate private file. A Telegram
 }
 ```
 
-Run `/workflow-channel setup` in Pi TUI to verify and install a profile, `/workflow-channel status` to inspect whether profiles are active, and `/workflow-channel reload` after a private configuration change. Setup asks for the token file path, not the token. It updates mode-`0600` private files and does not copy the token. Token values never enter source files, workflow inputs, SQLite runs, logs, child environments, or model-visible tool results.
+Run `/workflow-channel setup` in Pi TUI to verify and install a profile, `/workflow-channel status` to inspect active profiles and uncertain operations, and `/workflow-channel reload` after a private configuration change. When status reports an uncertain operation, inspect Telegram before you run `/workflow-channel recover <message-id> confirm|retry`. `confirm` records that the operation happened. `retry` starts a new attempt and can duplicate the Telegram operation when the first result cannot be proved.
 
-The same Unix account can read a local credential file. This design prevents accidental propagation, not a hostile same-account process. A separately owned connector can implement the same channel interface later if stronger isolation becomes necessary.
+Setup asks for the token file path, not the token. It updates mode-`0600` private files and does not copy the token. Token values never enter source files, workflow inputs, SQLite runs, logs, child environments, or model-visible tool results.
+
+The same Unix account can read a local credential file. This design prevents accidental propagation, not a hostile same-account process. A separately owned connector can implement the same channel-child protocol later if stronger isolation becomes necessary.
 
 ## Channel interface
 
-All decision channels implement one 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:
 
-```typescript
-interface HumanDecisionChannel {
-  readonly id: string;
-  start(): Promise<void>;
-  deliver(request: HumanDecisionRequest): Promise<DecisionDeliveryResult>;
-  settle(decision: AcceptedHumanDecision | HumanDecisionCancellation): Promise<void>;
-  stop(): Promise<void>;
-}
-```
+- `channel.ready`;
+- `channel.present`;
+- `channel.answer`;
+- `channel.settle`; and
+- `channel.exiting`.
 
-The context exposes a narrow answer submission function. It does not expose the workflow engine, arbitrary run mutation, or another channel's credentials.
+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.
 
-Channel delivery is independent from workflow routing. A failed Telegram delivery leaves the decision available in Pi. Audience policy decides whether one successful channel is enough or whether all configured channels are required before the request is considered delivered.
+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 Pi channel uses documented extension UI APIs. It shows the request, lists the choices, and opens a text editor when the selected choice requires input. The host records the interactive session as the answer source.
+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 waiting workflow remains durable before the UI opens. Closing Pi or cancelling the view cannot lose the checkpoint. A later Pi session can reopen pending decisions.
+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.
 
 ### Telegram channel
 
-The Telegram channel uses the Bot API and private profile configuration. It sends one decision message with inline buttons.
+The Telegram adapter uses the Bot API and private profile configuration. It sends one decision message with inline buttons.
 
 A choice without input submits from its button. A text choice such as `replan` works as follows:
 
 1. the operator presses **Replan**;
 2. the bot sends a `ForceReply` prompt tied to that decision and choice;
 3. the operator replies to that exact prompt;
-4. the channel verifies the numeric user ID, chat ID, reply message ID, decision ID, and request digest; and
+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. Private local SQLite rows map each opaque ID to the validated decision presentation. Credentials remain outside the database.
+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.
 
-Telegram permits one long-polling consumer for a bot profile. Active Pi processes use the shared SQLite lease so one process owns polling and the others observe the same channel state. The lease owner can accept a verified reply, but only the Pi session that owns the waiting run creates its continuation. Active sessions inspect the durable accepted-answer fence and recover their own continuation. If no Pi process is running, Telegram delivery and reply collection resume when Pi starts again. Running an always-on service is outside this design.
+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.
 
-The Bot API does not provide an idempotency key for `sendMessage`. pi-workflows therefore writes a delivery intent before sending and never blindly retries an ambiguous send. A timed-out send is recorded as `unknown`; Pi remains available and an operator can request another delivery. This avoids automatic duplicate messages while keeping decision acceptance exactly once.
+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.
 
 ## Durable decision records
 
@@ -268,8 +266,8 @@ Human decisions use the canonical [SQLite state](SQLITE_STATE.md) database:
 - `human_decision_submissions` records human, policy, channel, and control candidates;
 - `human_decision_resolutions` stores the one accepted-or-cancelled winner;
 - `continuations` links the parent and continuation runs;
-- `effects` records parent settlement, continuation, and presentation settlement work; and
-- channel tables store delivery and settlement receipts.
+- `effects` and `effect_attempts` record parent settlement, continuation, external delivery, and external settlement work; and
+- `channels`, `channel_cursors`, and `channel_messages` store channel identity, polling position, and decision delivery or settlement receipts.
 
 A valid human answer, eligible timeout policy, explicit cancellation, or no-default expiry competes for the same resolution primary key. The winning transaction records the immutable resolution, audit event, and required effects together. A retry adopts the existing matching result. A conflicting or late answer receives the durable winner.
 
@@ -315,7 +313,7 @@ Recovery follows these rules:
 - duplicate channel updates are harmless;
 - stale responses are rejected;
 - one human or timeout response creates one continuation;
-- the winning human answer or timeout policy dismisses any pending Pi dialog;
+- the winning human answer or timeout policy settles or cancels the pending Pi decision workflow message;
 - confirmed channel settlement is adopted without another remote call;
 - failed channel settlement has a bounded retry count and cannot create an unbounded record loop; and
 - cancellation resolves the owned waiting decision from durable state, even after restart, closes pending views, and prevents a later answer from continuing the run.
@@ -330,15 +328,15 @@ 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, validation, durable acceptance, and continuation. The Pi extension owns UI and channel lifecycle. The Telegram adapter 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 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.
 
 ## Contract impact
 
 - **Session state:** Pi records normal workflow messages and interactive decision results.
-- **Other persistent data:** decision requests and resolutions can carry a deadline, automatic response, and resolution provenance in the existing decision store. Continuation startup uses existing run, queue, source, binding, lease, event, continuation, and decision-effect records. It adds no new persistent shape. The private channel index remains rebuildable.
+- **Other persistent data:** decision requests and resolutions can carry a deadline, automatic response, and resolution provenance in the existing decision store. Continuation startup uses existing run, queue, source, binding, lease, event, continuation, and decision-effect records. External channel attempts use the shared effect records, and channel delivery and settlement records remain separate feature evidence.
 - **Pi internals:** none.
-- **Public Pi API:** documented extension lifecycle and UI methods only.
-- **Public pi-workflows API:** typed human choices, `humanDecision().onTimeout`, `humanDecisionEdge()`, the channel interface, the plan approval policy, the shared plan-change workflow, and the additive queue prepare-or-adopt operation.
+- **Public Pi API:** documented extension lifecycle, message, command, session, and status APIs only.
+- **Public pi-workflows API:** typed human choices, `humanDecision().onTimeout`, `humanDecisionEdge()`, channel profile configuration, the plan approval policy, the shared plan-change workflow, and the additive queue prepare-or-adopt operation.
 
 ## Verification requirements
 
@@ -349,7 +347,8 @@ The implementation must test:
 - runtime choice and input validation;
 - legacy checkpoint continuation;
 - model-tool answer rejection;
-- Pi interactive answers;
+- Pi decision workflow messages, branch adoption, branch-specific decision messages, and verified answers;
+- supervised channel-child protocol fencing and restart recovery;
 - Telegram callbacks and reply binding with a fake Bot API;
 - unauthorized users and chats;
 - stale request digests;
@@ -361,7 +360,7 @@ The implementation must test:
 - identical and conflicting retries;
 - crashes before and after answer acceptance and continuation creation;
 - ambiguous Telegram sends;
-- long-poll lease handoff between Pi processes;
+- one supervised long-poll adapter per profile and host-restart recovery;
 - decision cancellation and expiry;
 - included `plan-approval` routes and bounded replan loops;
 - viewer redaction; and

package/docs/HUMAN_DECISION_PRESENTATIONS.md

@@ -1,6 +1,6 @@
 # Human decision presentations
 
-This contract is implemented. Human decision requests separate their canonical
+Human decision requests separate their canonical
 subject from the complete readable message shown to an operator. Human decisions use
 one v1 contract with no legacy body form or parallel schema version.
 The implementation plan is in
@@ -216,20 +216,13 @@ The renderer:
 
 The renderer never adds an ellipsis in place of omitted decision content.
 
-The channel records intent before sending. It records each part after an
-unambiguous response. If a send result is ambiguous, it marks delivery unknown
-and does not retry that part or later parts automatically. Another configured
-channel can still answer the decision.
+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.
 
 ### Pi
 
-Pi uses the documented extension TUI API. A custom decision component shows the
-complete presentation and fingerprint together with the choices and optional
-text prompt. It wraps and scrolls while responding to resize, theme, cancellation,
-and `AbortSignal` events.
+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.
 
-When Telegram or another channel accepts the decision, the signal closes the Pi
-dialog. pi-workflows does not 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 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.
 
 ### Other channels