@osolmaz/pi-workflows 0.13.3 → 0.14.0

package/docs/plans/2026-08-27-workflow-terminal-restart-plan.md

@@ -0,0 +1,357 @@
+---
+title: Workflow terminal decision and restart plan
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-27
+---
+
+# Full plan
+
+## Goal
+
+After every top-level workflow run ends, give the model one normal successor turn.
+
+That turn contains the workflow result and terminal reason. The model uses the conversation it already has to decide whether to:
+
+- stop because the user’s task is complete
+- restart the same workflow as a new run
+- start Monitor for an authorized external wait
+- ask the user for a required decision or authority
+- take another safe authorized action
+
+The system does not save or identify the original user message. It does not restart automatically. It gives the model one clear decision opportunity and makes safe retry the default for unfinished work after technical failures.
+
+## Shared terminal behavior
+
+The shared terminal message must include:
+
+- workflow name and revision
+- terminal run ID
+- exact workflow input
+- workflow result
+- terminal state
+- terminal reason
+- restart count
+- earlier terminal outcomes in the same restart chain
+
+The message must tell the model:
+
+> A workflow run ended, but that does not prove the user’s task is complete. Use the current conversation and this result to decide what to do next. If the task is unfinished because of an unexpected technical or temporary failure, prefer a safe restart. Stop if the work is complete, the user cancelled it, new authority is required, the user must make a decision, or the same failure has repeated. Use Monitor only for an authorized external wait.
+
+Use the term **result**, not “durable result.”
+
+## Implementation steps
+
+### 1. Build one shared terminal-decision message
+
+**Where**
+
+- `src/extension/deferred-turn.ts`
+- Add `src/extension/terminal-decision.ts` if a separate pure module keeps the code smaller.
+
+**Change**
+
+Add a pure builder that reads the existing run record and produces the shared terminal facts and prompt.
+
+It must not read, copy, hash, or store an original user message.
+
+Use the existing stored workflow input and result. Apply the existing output-size rules to large results, but always include the run ID, state, reason, and restart history.
+
+**Verification**
+
+Unit tests must cover completed, failed, timed-out, maxSteps, cancelled, and blocked results.
+
+### 2. Create one terminal turn for every top-level run
+
+**Where**
+
+- `finishRun` in `src/extension/index.ts`
+- `src/extension/deferred-turn-coordinator.ts`
+- Existing turn-intent state in `src/controllers/sqlite.ts`
+
+**Change**
+
+Create one terminal turn intent when a top-level interactive run reaches a terminal state.
+
+Normal presentation and fallback delivery must compete for the same intent. The first successful delivery settles it. Every later delivery attempt becomes a no-op.
+
+Do not create this turn for:
+
+- waiting checkpoints
+- controller child runs
+- internal helper runs that already report to an owner
+
+**Verification**
+
+Race tests must prove that presentation, fallback, reload recovery, and crash recovery produce one model turn, not two.
+
+### 3. Replace the current terminal presentation instruction
+
+**Where**
+
+- `buildPresentationMessage`
+- `buildDeferredTurnContent`
+- Related presentation helpers in `src/extension/index.ts`
+
+**Change**
+
+Remove the current instruction that says the model must not call the workflow tool.
+
+Replace it with the shared decision instructions. The terminal turn must permit one workflow launch selected by the model.
+
+Completed runs still get a result turn. A workflow state of `completed` does not always mean the larger user task is complete. For example, the result can say that work is blocked.
+
+Explicit human cancellation must default to stopping.
+
+**Verification**
+
+Tests must prove that the model can select restart or Monitor during the terminal turn and that ordinary completed work does not cause an automatic restart.
+
+### 4. Add a generic restart action
+
+**Where**
+
+- `src/workflows/tool-input.ts`
+- Workflow tool registration, schema, help text, and control switch under `src/workflows/`
+- Restart handling in `src/extension/index.ts`
+
+**Contract**
+
+```json
+{
+  "action": "restart",
+  "runId": "terminal-run-id"
+}
+```
+
+**Change**
+
+The action must:
+
+1. Read the terminal run.
+2. Confirm that it belongs to the current session.
+3. Confirm that it is terminal.
+4. Reuse the exact workflow reference, input, and safe launch settings.
+5. Create a new immutable run.
+6. Record the restart relationship.
+7. Leave the old run unchanged.
+
+Reject restart when:
+
+- the run is active or waiting
+- the run is unknown
+- the run belongs to another session
+- the run was explicitly cancelled
+- the workflow source or revision is no longer available
+- the restart limit was reached
+- the same terminal failure already repeated
+
+A later explicit user request can still use normal `start`.
+
+**Verification**
+
+Tool-schema and extension tests must prove exact input reuse, immutable old runs, session checks, source checks, and correct rejection behavior.
+
+### 5. Permit one selected launch during the terminal turn
+
+**Where**
+
+- `queueToolLaunch`
+- presentation tracking in `src/extension/index.ts`
+- `agent_settled`
+- existing queued-launch recovery
+
+**Change**
+
+The current presentation guard rejects workflow launches. Add one narrow exception for the active terminal-decision turn.
+
+The model can reserve one of these:
+
+- restart
+- Monitor
+- another workflow start
+
+The reservation must not activate until the model turn settles. A second workflow launch from the same terminal turn must fail.
+
+Other tool calls remain subject to their normal rules.
+
+**Verification**
+
+Tests must prove that:
+
+- one launch can be reserved during presentation
+- it starts only after `agent_settled`
+- a second launch is rejected
+- reload after reservation does not lose it
+- crash recovery does not start it twice
+
+### 6. Add bounded restart lineage
+
+**Where**
+
+- Add `src/extension/restart-policy.ts`
+- Existing run launch-options JSON and accessors
+- No new database table
+
+**Change**
+
+Store this information for restarted runs:
+
+- root run ID
+- parent run ID
+- restart number
+- parent terminal fingerprint
+
+A terminal fingerprint is a stable hash of:
+
+- workflow identity and revision
+- exact input
+- terminal state
+- canonical result or error
+- canonical terminal reason
+
+Do not include timestamps or new run IDs in the fingerprint.
+
+Allow at most three restart actions after the original run. This permits at most four runs in one chain.
+
+If a terminal fingerprint occurs again in the same chain, reject another restart immediately. If the result changes because the workflow made progress, another restart can remain eligible until the total limit is reached.
+
+Starting Monitor does not consume a restart.
+
+**Verification**
+
+Tests must cover:
+
+- first technical retry
+- progress followed by a different failure
+- repeated identical maxSteps failure
+- three-restart limit
+- Monitor selection
+- restart history after database reopen
+
+### 7. Make restart reservation idempotent
+
+**Where**
+
+- Existing effect records
+- Existing run queue and reservation code
+- Terminal turn-intent settlement code
+
+**Change**
+
+Key the selected launch to the source terminal turn intent and tool call.
+
+If the host repeats the same tool call after a crash or reload, return the existing reservation or new run instead of creating another one.
+
+The terminal turn intent, launch reservation, and resulting run must have one inspectable chain.
+
+**Verification**
+
+Inject failures after:
+
+- turn-intent claim
+- launch reservation
+- run creation
+- terminal response settlement
+
+After recovery, there must still be one terminal message and one successor run.
+
+### 8. Document the contract
+
+**Where**
+
+- `docs/workflows.md`
+- `docs/SQLITE_STATE.md`
+- Workflow tool reference and examples
+- Relevant README text
+
+**Change**
+
+Document:
+
+- the shared terminal decision turn
+- the `restart` action
+- the difference between a workflow ending and the user’s task finishing
+- retry defaults and limits
+- Monitor selection
+- explicit cancellation behavior
+- top-level versus child-run behavior
+- recovery and duplicate prevention
+- that conversation context remains owned by Pi
+- that Pi Workflows does not capture or persist an original user message
+
+No workflow definition needs an opt-in or terminal restart step.
+
+## Contract changes
+
+- The workflow tool gains `restart`.
+- Every top-level terminal run owns one terminal turn intent.
+- Restart always creates a new run.
+- Restart reuses the exact prior workflow input.
+- The model makes the continuation decision from the current conversation.
+- Restart is preferred, not forced, for unfinished work after technical or temporary failures.
+- Explicit cancellation, missing authority, required user decisions, repeated failures, and completed work stop.
+- Restart lineage uses existing run launch data.
+- No new store, service, controller, or Pi API is added.
+- No original-message provenance contract is added.
+
+## Test plan
+
+Add regression coverage for:
+
+1. Successful completion produces one result turn and no automatic restart.
+2. A blocked result from a completed workflow lets the model select restart.
+3. Failed, timed-out, and maxSteps runs offer restart.
+4. Explicit cancellation is not restartable through the shortcut.
+5. Waiting checkpoints do not produce a terminal turn.
+6. Controller child runs do not produce competing turns.
+7. Presentation and fallback races produce one turn.
+8. Restart uses the exact workflow reference and input.
+9. Restart leaves the prior run unchanged.
+10. Monitor starts through the normal start path.
+11. A selected launch waits for `agent_settled`.
+12. Reload and crash recovery do not duplicate turns or runs.
+13. The same terminal failure cannot repeat indefinitely.
+14. A chain cannot exceed three restarts.
+15. No new code captures, hashes, or stores an original user message.
+16. The maxSteps failure that caused this incident produces a terminal decision turn instead of silently ending the task.
+
+Run the full repository checks:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+```
+
+## Main risks
+
+- **The model restarts completed work.**
+  Make stopping the default for successful results and enforce restart limits.
+
+- **A retry repeats external effects.**
+  Include the prior result and restart history so the model can inspect the current state before it retries.
+
+- **Presentation and fallback both fire.**
+  Make both settle the same turn intent.
+
+- **A launch starts while the terminal response is still active.**
+  Reserve it first and activate it after `agent_settled`.
+
+- **A temporary outage causes a loop.**
+  Use Monitor for external waits, stop repeated fingerprints, and allow only three restarts.
+
+## Boundaries
+
+Do not:
+
+- modify Pi core or private APIs
+- store or identify an original user message
+- add restart nodes to individual workflows
+- modify Autoimplement, Monitor, or other workflow definitions
+- create a new controller, database, service, or daemon
+- bypass cancellation, checkpoints, reviews, CI, authority, or safety rules
+- add compatibility shims or parallel state contracts
+- release or deploy anything as part of this plan
+
+This is the selected plan.

package/docs/workflows.md

@@ -430,6 +430,7 @@ 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.
+- `restart` with a terminal run ID. It creates a new run from the exact stored workflow reference and 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.
@@ -439,8 +440,47 @@ The model sees one `workflow` tool. Its `action` field supports:
 - `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
+A direct user request to continue or resume the active workflow maps to the
+`resume` action immediately. The model does not call `status` instead of
+`resume`, and it does not use `status` as a prerequisite.
+
+`resume` is idempotent while a run is active. A held, pausing, or paused run is
+released and reports `resumed: true`. An active run that is already executing
+returns normal success with `resumed: false` and `alreadyRunning: true`. It does
+not change the run state. With no active run, `resume` still returns a warning.
+
+Model-facing `status` keeps `status` as the durable workflow lifecycle state.
+It also reports the host action fields `paused`, `workState`, and `resumable`.
+For the current active run, `paused` is true when the host has requested or
+applied a hold, or when the durable run state has `paused: true`. `workState`
+is `running`, `pausing`, or `paused` for that active host run and `inactive`
+when no current host run can act on the durable state. `resumable` is true only
+when `resume` can release the current active run. Queue-only status uses its
+launch state, such as `queued` or `starting`, as `workState`; queue-only and
+no-run results report `paused: false` and `resumable: false`. Thus, a durable
+`status: "running"` can correctly appear with `workState: "pausing"` or
+`workState: "paused"`, and the status message names that actionable state
+instead of saying only that the workflow is running.
+
+Restart uses this contract:
+
+```json
+{
+  "action": "restart",
+  "runId": "terminal-run-id"
+}
+```
+
+The terminal run must belong to the current Pi session and must not be active,
+waiting, or explicitly cancelled. Its source and revision must still resolve
+exactly. Restart creates a new immutable run and leaves the terminal run
+unchanged. It copies the stored input and safe launch settings; it does not
+reconstruct input from conversation history.
+
+A model-started run is queued until the model's current turn settles. A terminal
+decision turn can reserve one restart, Monitor run, or other workflow start.
+A second workflow launch from that turn fails. 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
@@ -665,19 +705,30 @@ export default defineWorkflow({
 });
 ```
 
-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.
+After a top-level interactive run becomes terminal, the Pi extension gives the
+model one normal terminal decision turn. The message contains the workflow name
+and revision, terminal run ID, exact stored input, bounded result, terminal
+state and reason, restart count, and earlier terminal outcomes in the restart
+chain. A completed state does not prove that the user's larger task is complete.
+The model uses the current Pi conversation to stop, restart safely, start
+Monitor for an authorized external wait, ask for a decision or authority, or
+take another safe authorized action.
+
+`presentationPrompt` adds workflow-specific presentation instructions to this
+shared terminal decision message for completed runs. Returning `undefined`,
+returning an empty string, omitting `presentationPrompt`, or ending in failure,
+timeout, or cancellation uses the factual terminal fallback instead. Normal
+presentation and fallback claim the same terminal turn intent, so races,
+reload, crash recovery, and compaction cannot create a second decision turn.
+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.
+
+Waiting checkpoints are not terminal and do not create a terminal decision
+turn. Controller child runs and internally owned runs report to their owner and
+do not create competing turns. Explicit cancellation produces terminal facts,
+but its decision instruction defaults to stopping and the `restart` shortcut
+rejects it.
 
 An agent with `expectedOutput: assistantMessage()` is different. Its visible
 assistant response is the node output, can appear before later nodes, and also
@@ -685,12 +736,11 @@ 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.
+Presentation and terminal decisions are outside the workflow graph: they cannot
+route to another node, change the terminal run, or alter its result. A selected
+restart always creates a new run. Workflow definitions need no opt-in,
+continuation node, or restart prompt. Pi owns conversation history. Pi Workflows
+does not identify, hash, copy, or store an original user message.
 
 ## Runtime behavior
 
@@ -712,20 +762,26 @@ possible. Defaults worth knowing:
   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.
+- Resuming an active run that is already running succeeds without changing the
+  engine, executor, widget, or durable workflow state. This makes duplicate
+  `resume` calls safe.
 - 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
+  reservation, and creates one terminal 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 factual decision turn after settlement. Pi Workflows does not retry automatically.
+- Agent-issued and direct `workflow cancel` actions that cancel an active or queued run create or
+  settle one terminal turn intent. The resulting decision defaults to stopping, and `restart`
+  rejects the cancelled run. When no run is live but the widget still shows a parked or finished
+  run, the command clears the widget.
+- A restart chain allows at most three restart actions after the original run. The terminal
+  fingerprint excludes timestamps and run IDs. If the same workflow revision, exact input, state,
+  result or error, and reason occur again in that chain, another restart fails immediately. A
+  changed outcome can remain restartable until the chain limit. Starting Monitor does not consume
+  a restart.
 - 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

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.13.3"
+version = "0.14.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.3",
+  "version": "0.14.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 elegant long-term production-ready solution, compare it with the ideal end state, 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.
 ---
 
@@ -37,12 +37,12 @@ When this skill is loaded inside an active workflow step, do not start another w
 Outside Pi, or when the workflow is unavailable:
 
 1. Frame the problem, observable success criteria, scope, constraints, and interfaces under our control.
-2. Record two through four distinct practical candidates. Give each one a stable id, short title, plain gist, full solution, rationale, parts, and trade-offs.
-3. Describe the holy grail separately. Name every dependency outside our authority.
+2. Record two through four distinct practical candidates. Ask whether each is a Long term elegant and production ready solution. Give each one a stable id, short title, plain gist, full solution, rationale, parts, and trade-offs.
+3. Describe the Holy grail separately. Ask whether it is the Holy grail for the problem. Name every dependency outside our authority.
 4. Choose the right option without asking the user to decide between them. Record one rejection reason for every other explicit candidate.
-   - Choose the ideal when it is proportionate, production-ready, in scope, and implementable through interfaces we control.
-   - Otherwise choose the strongest practical in-scope solution with a clear path toward the ideal.
-   - Do not block only because the ideal requires an upstream or external change.
+   - Choose the Holy grail when it is proportionate, production-ready, in scope, and implementable through interfaces we control.
+   - Otherwise choose the strongest practical in-scope solution with a clear path toward the Holy grail.
+   - Do not block only because the Holy grail requires an upstream or external change.
 5. Write a detailed implementation plan. For each step, state what changes, where it changes, and how to verify it.
 6. Present one short plain assistant message with the chosen plan, its main steps, and a one-line gist and rejection reason for every other candidate. Call it selected for approval when a later human decision still applies.
 7. Stop as blocked only when no truthful in-scope solution can meet the success criteria.

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: