@osolmaz/pi-workflows 0.13.4 → 0.14.0

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.4"
+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.4",
+  "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 Long term elegant and production ready solution, compare it with the Holy grail, and produce the best practical in-scope implementation plan without asking the user to resolve the gap.
+description: Compares practical solutions with the ideal end state, selects the best in-scope option, and produces an implementation plan. Use only when the user explicitly asks to run autoplan.
 compatibility: Requires pi-workflows and the built-in autoplan workflow.
 ---
 

package/skills/pi-workflows/SKILL.md

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

package/src/controllers/index.ts

@@ -24,7 +24,10 @@ export {
   SqliteControllerStore,
   type RunEventRecord,
   type WorkflowNotificationRecord,
+  type WorkflowRunClaimOptions,
+  type WorkflowRunPreparationResult,
   type WorkflowRunQueueRecord,
+  type WorkflowRunReservationOptions,
 } from "./sqlite.js";
 export {
   type ControllerStore,