@osolmaz/pi-workflows 0.2.0 → 0.3.0

package/docs/plans/2026-08-05-always-on-workflows-plan.md

@@ -0,0 +1,125 @@
+---
+title: Add always-on workflow execution
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-05
+updated: 2026-08-05
+status: implemented
+---
+
+# Always-on workflows plan
+
+Pi Workflows should feel the same whether the user watches a run or walks away from it. In the user's words: "I might start a workflow locally in Pi then I wait for it to complete. All the while I am looking at the screen and I'm not closing the Pi window. When the workflow ends I just want to be able to continue the same Pi session like normal with a session up to date with what happened in the workflow." And: "I just want to interact by starting a workflow, closing it, and then coming back and then still being able to continue it when I open it up. It's syncing continuously or something."
+
+These are not two modes. The user asked for "both in a single unified system." This plan makes the Pi window irrelevant to execution: closing or opening the window is a change in observation, not in the run. The work stays on one machine, uses the merged controller runtime as its foundation, and does not modify Pi core.
+
+This revision incorporates an external design review of the first draft. The review confirmed the three design rules and found five structural gaps in the details. The Decisions section resolves each one before implementation starts.
+
+## Design
+
+Four rules define the system:
+
+1. **Durable state is the only source of truth.** Run bundles, the queue, and the event log live on disk. Nothing important lives in a session's memory.
+2. **Runners are interchangeable, but ownership is exclusive.** Any live process running the engine claims work from the durable queue. A run has exactly one owning runner at a time, proven by a claim token, and only that runner may write to the run.
+3. **The session is always a view.** It attaches to a run's event stream and renders it. An open window sees a live tail; a reopened window catches up from the same stream. Interaction such as approvals uses durable waiting states, never prompts tied to the window's lifetime.
+4. **Claims arbitrate every lifecycle decision.** Only the current claim holder may resume, interrupt, or write a terminal event for a run. Recovery code that finds an abandoned run goes through the queue instead of writing to the bundle directly.
+
+The controller runtime already provides most of the machinery: a deduplicated queue with expiring claims, a structured event table, crash recovery through the trace tail, and guarded effect records. This plan extends that treatment to runs the user starts interactively and adds the view layer.
+
+## Decisions
+
+These points were open in the first draft. External review showed each one is load-bearing, so they are decided here.
+
+1. **Write fencing on bundles.** Every claim records a runner ID, a token, and a lease expiry in the store. Every bundle write verifies the token inside the run lock before appending and fails the runner fast when the token no longer matches. Expiring claims alone do not stop a stalled runner from writing; fencing does.
+2. **Explicit resume protocol.** Resume is a named operation, not a restart. It truncates a torn trace tail to the last complete line, rebuilds run state from the trace, seeds the trace sequence from the tail, accounts for already-executed steps against the step limit, and records a resume boundary event before continuing.
+3. **Resume scope.** User-started runs get node-level resume. Controller child runs keep their current new-attempt semantics, because attempt immutability and parent-side retry already work and are tested. Both behaviors are explicit; nothing mixes silently.
+4. **A dedicated run queue.** Interactive runs do not fit the controller queue, which is keyed to controller resources. A new `workflow_run_queue` table shares the claim, lease, and fencing pattern and adds runner affinity fields. Runs stay out of `/controller list`.
+5. **Origin affinity.** An interactively started run is inserted and claimed in one transaction, so the session that started it owns it from birth. The standalone host takes over only when that claim is released or expires. This guarantees a watched run's conversation happens in the watching session.
+6. **Close-to-park shutdown.** `session_shutdown` stops writing a terminal cancel event for queued runs. It aborts in-flight work without a terminal event and releases the claim, leaving a resumable bundle. A clean close releases claims explicitly; a crash relies on lease expiry.
+7. **Per-attempt capture.** Session capture becomes segmented per attempt, keyed by attempt ID, so a run handed off to the host or a new session starts a fresh capture segment instead of failing integrity checks.
+8. **Continuation runs for waiting.** A run that needs human input ends at a checkpoint with status `waiting`, preserving bundle immutability. An answered checkpoint starts a continuation run with a new run ID chained to its parent, carrying forward prior outputs. The parent link makes the chain inspectable.
+9. **Source pinning.** The manifest stores a content hash of the workflow source at run start. Resume refuses to continue against changed source unless forced, and a forced resume records the mismatch in the trace.
+10. **Snapshot catch-up.** Notifications are idempotent snapshots of run state as of a store sequence number, recomputed from the store, not a stream of one-off messages. The watermark persists per session before sending. A skipped incremental notification is subsumed by the next snapshot.
+11. **A run-level event feed.** Run lifecycle transitions write rows into a store table, so one watermark covers both controller and run events. Tailing `trace.ndjson` is reserved for the single actively watched run.
+12. **Store-error backoff.** Worker loops treat store errors such as `SQLITE_BUSY` as transient and back off instead of letting a worker die silently. The host's advisory lock guards host-versus-host only; the embedded runner does not take it, and a second host refuses to start.
+13. **Orphan reaping.** The host spawns `pi --mode rpc` children in their own process group, records child PIDs in the bundle, and reaps known orphans on startup. Consequential actions stay behind guarded effects regardless.
+
+## Requirements
+
+- Starting `/workflow run` in a Pi session creates a durable queued run claimed by that session, and shows its progress live.
+- Closing Pi mid-run never loses the run and never writes a spurious terminal event. With the standalone host alive, the host reclaims and resumes the run. Without a host, the run waits and resumes when a runner returns.
+- Reopening a session brings it up to date with an idempotent snapshot: what finished, what failed, what waits for input. No state is duplicated and no information is permanently lost.
+- A run that needs human input ends at a checkpoint. The user answers with a command, and a continuation run carries the work forward. The wait survives any process lifetime.
+- Killing any process at any point recovers without duplicate trace sequences, duplicate notifications of record, or duplicate external effects. A stalled runner that loses its claim can never write again.
+- Everything uses documented Pi public APIs. No Pi core changes.
+
+## Work items
+
+1. **Run queue and fencing.** Add the `workflow_run_queue` table with claim tokens, lease expiry, and runner affinity. Gate every bundle write on the token inside the run lock. Insert-and-claim interactive starts in one transaction.
+2. **Node-level resume.** Implement the explicit resume protocol from Decision 2, with source pinning from Decision 9. User-started runs resume at the interrupted node; controller child runs are untouched.
+3. **Close-to-park and capture segments.** Change `session_shutdown` to abort-without-terminal plus claim release for queued runs. Split session capture into per-attempt segments the integrity checker understands.
+4. **Continuation runs.** Chain an answered checkpoint to a new run ID with a parent link and carried-forward outputs. Render the chain as one logical run in views.
+5. **Session sync.** Add the run-level event feed, per-session watermarks, snapshot catch-up on `session_start`, and noteworthy-event messages. Live watching tails `trace.ndjson` from a remembered byte offset with `fs.watch`, reusing the TUI viewer's file-tail path.
+6. **Standalone host.** A `pi-workflows` CLI subcommand loads controller definitions, opens the project store, and runs claiming in a loop with store-error backoff. Conversation child nodes run in spawned headless `pi --mode rpc` sessions with orphan reaping. The host takes an advisory lock against other hosts, drains on SIGTERM, and recovers on restart. It is a foreground process the user runs in a terminal; it is not a service.
+
+## Non-goals
+
+- Pi core changes of any kind. Every integration uses public APIs: commands, session events, widgets, `sendUserMessage`, and `pi --mode rpc`.
+- Multi-machine execution, a remote store, or leader election. SQLite and one machine are in scope; the store contracts leave room for a remote implementation later.
+- Installing or configuring a system or user service. The host is a process the user starts and stops.
+- A push channel from an external process into a live session. Polling the shared store is the mechanism, and it is fast enough.
+- Exactly-once chat notifications. The guarantee is no duplicated state and no permanently lost information, delivered through idempotent snapshots.
+- Exactly-once external side effects beyond the existing guarded effect records.
+
+## Assumptions
+
+- One machine and one user, with the store and run bundles on the local filesystem.
+- Spawning `pi --mode rpc` per conversation child run is acceptable at the expected cadence. If startup cost proves too high, the host keeps a small pool of persistent RPC sessions instead. Both options stay outside Pi core.
+- A polling interval of a few seconds is responsive enough for the session view. File watching covers the live tail of a watched run.
+- The user does not need machine-sleep or power-loss coverage beyond crash recovery. A stopped machine stops work until a runner returns.
+
+## Open questions
+
+- Which events deserve a chat message and which belong only in the widget. The default should be quiet.
+- The exact host command shape, for example `pi-workflows run --project <dir>` versus a subcommand under `controllers`.
+
+## Departures from the decisions
+
+The implementation matches the decisions above with these refinements:
+
+- Graph validation now allows outgoing edges from checkpoint nodes. The old
+  rejection encoded terminal-forever checkpoints; continuations make those
+  edges live. This is a deliberate contract change for workflow authors.
+- The host command is `pi-workflows host`, chosen over `run` because the
+  viewer CLI's vocabulary already uses runs for bundles.
+- The first capture stays flat at `session/`; only binds from the second
+  recorder onward write segments under `session/segments/`. This keeps the
+  layout of every existing single-session bundle and the viewer unchanged.
+- Resume always starts unpaused; the operator can pause again.
+- Headless conversation children keep the exact tool contract: a bridge
+  extension loaded with `-e` registers the `workflow` tool and reports
+  submissions to the host over stderr, so no engine prompt changes were
+  needed.
+- The host accepts explicit `storeFile` and `runsDir` options. Its defaults
+  resolve from the project and environment like every other entry point.
+
+## Acceptance criteria
+
+- Start a run in Pi, then close Pi while a conversation node is mid-response and the host is running. The host reclaims and resumes the run, and reopening Pi shows the catch-up snapshot and allows normal conversation about the result.
+- The same flow without the host: the run resumes at the interrupted node when Pi reopens and completes.
+- A stalled runner that loses its claim cannot write to the bundle afterward; fencing rejects its writes.
+- An open session reflects host-driven progress within a few seconds. Two sessions on one project each get complete catch-up; neither starves the other.
+- A waiting-for-input run survives closing and reopening. Answering it starts a continuation run that carries forward prior outputs.
+- `kill -9` on the host mid-append, followed by a restart, repairs the torn trace tail and recovers without duplicate trace sequence numbers and without repeating an applied external effect. Orphaned RPC children are reaped.
+- No changes to Pi core; the diff touches only this package.
+
+## Verification
+
+- `npm run check` and `npm run test:e2e`, including new real-Pi E2E tests that start a run, kill the host, restart it, and assert continuation.
+- A fencing test with both runners alive and a forced lease loss.
+- A two-session watermark test on one project.
+- A `kill -9` mid-append torn-tail resume test.
+- A checkpoint answer-to-continuation round-trip test.
+- Extension tests with fake timers for the polling loop, watermark, and snapshot catch-up.
+- `npx slophammer-ts@latest dry .` and the dependency-boundary check.
+- `npx -y @simpledoc/simpledoc check` for documentation changes.
+- Manual pass through both usage patterns from the user's request with the host in a terminal.

package/docs/plans/2026-08-10-agent-managed-monitor-workflows-plan.md

@@ -0,0 +1,184 @@
+---
+title: Let agents run and manage monitor workflows
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-10
+updated: 2026-08-10
+status: implemented
+---
+
+# Agent-managed monitor workflows plan
+
+The user should be able to tell an agent, "Monitor this every 30 minutes," and have the agent start the right workflow. The user must not write controller records or JSON. The existing `workflow` model tool should manage workflows instead of serving only as a step-submission tool.
+
+A monitor is one Pi Workflows graph. It checks the target, reports a meaningful change, sleeps for the requested interval with the existing shell node, and loops. This plan does not use controllers, Unified Exec, a new wait node, or a second scheduler.
+
+## Shipped design
+
+The implementation follows this plan. The built-in monitor defaults to 1,000 checks, caps the interval at 24 hours, and uses a 5,010-step engine limit as a second guard. The normal Pi extension exposes all workflow tool actions. The headless RPC bridge exposes only `submit`. A real-Pi end-to-end test proves that a normal model turn can start the built-in monitor and complete its first check. The automated test inspects the exact 30-minute Node timer command and both timeout margins instead of making the test suite wait for 30 minutes. The Node timer keeps the shell action portable across Pi's supported platforms.
+
+## User experience
+
+A normal request looks like this:
+
+> Monitor PR 123 every 30 minutes. Tell me when checks fail. Stop when it is merged or closed.
+
+The agent recognizes repeated monitoring from the `workflow` tool description and starts the built-in `monitor` workflow. The tool call contains the structured input, but the user does not write it.
+
+The monitor checks immediately, then waits between later checks. It writes a normal assistant message only when the requested report condition is met. It stops when the requested stop condition is met, when it reaches its safety limit, or when the user or agent cancels it.
+
+Existing controls remain available:
+
+```text
+/workflow pause
+/workflow resume
+/workflow cancel
+```
+
+The same operations become available to the model through the `workflow` tool. One active workflow per Pi session remains the rule. A long monitor therefore occupies that session's workflow slot.
+
+## Workflow tool
+
+Replace the current submit-only schema with one discriminated tool schema. Use Pi's documented `registerTool` API and `StringEnum` helper.
+
+The tool supports these actions:
+
+- `list`: list discovered workflows and their source.
+- `start`: start a workflow by name or path with structured input.
+- `status`: return a bounded summary of the active or named run.
+- `pause`: pause the active run at its next node boundary.
+- `resume`: resume the active paused run.
+- `cancel`: cancel the active run.
+- `answer`: answer a waiting checkpoint, with an optional run ID.
+- `submit`: submit the result required by the current workflow step contract.
+
+The `submit` form becomes:
+
+```json
+{
+  "action": "submit",
+  "step": "check",
+  "attempt": "attempt-id",
+  "output": {}
+}
+```
+
+Update workflow step prompts and reminders to include `action: "submit"`. Do not retain the old submit shape as a compatibility alias.
+
+Slash commands and tool actions must call the same internal lifecycle functions. This avoids separate behavior for humans and models. Tool results must be structured and bounded. Errors must state whether the operation failed because no run exists, a run is already active, a checkpoint is not waiting, or the requested workflow cannot be found.
+
+A tool call happens during an agent turn. The `start` action must validate and queue the launch, then deliver the first workflow prompt after the initiating turn settles. This prevents the new run from treating the initiating turn as a failed workflow step. It also prevents a workflow prompt from being injected in the middle of the tool call.
+
+The headless RPC bridge keeps a submit-only version of the tool. Headless workflow children must not start or control other workflows. Its submit schema and parser still change to require `action: "submit"`.
+
+## Agent guidance
+
+The tool description must tell the model when to use the built-in workflow:
+
+- Use `start` with workflow `monitor` when the user asks to watch, monitor, poll, or check something repeatedly.
+- Start directly when the task and interval are clear.
+- Ask one short question when the target or interval is missing.
+- Use observation-only behavior unless the user explicitly authorizes a mutation.
+- Do not create repeated work without a user request or an existing workflow instruction that authorizes it.
+
+The `list` result identifies `monitor` as a built-in workflow and gives a short description. This keeps discovery inside the tool instead of adding a skill or a system-prompt injection.
+
+## Built-in monitor workflow
+
+Ship `monitor` as a built-in workflow in the Pi Workflows package. Built-ins have the lowest discovery precedence:
+
+1. Project workflows under `.pi/workflows/`
+2. Global workflows under `~/.pi/agent/workflows/`
+3. Workflows bundled with Pi Workflows
+
+A project or global `monitor.workflow.ts` can therefore replace the default. The built-in remains a real workflow file so run bundles can record its path and source hash with the existing rules.
+
+The workflow input contains:
+
+- `task`: what to inspect.
+- `everyMinutes`: the interval between checks.
+- `reportWhen`: changes or states that deserve a user message.
+- `stopWhen`: the condition that ends monitoring.
+- `maxChecks`: a hard safety limit.
+
+The model supplies these fields from the user's request. The workflow validates the input and applies documented bounds. The first release supports intervals from 1 minute through 24 hours. It defaults `maxChecks` to a documented finite value when the request gives no end limit.
+
+The graph is:
+
+```text
+prepare -> guard -> check
+                    | continue quietly -> sleep -> guard
+                    | continue and report -> report -> sleep -> guard
+                    | stop quietly -> finish
+                    | stop and report -> report-final -> finish
+```
+
+`prepare` validates and normalizes the input. `guard` enforces `maxChecks`. `check` is an agent node that performs one observation and returns a validated route, a bounded observation, and an optional report. The next `check` can read the previous accepted `check` output, which Pi Workflows already keeps for looped nodes.
+
+The report nodes write a normal assistant message and then submit an acknowledgement. Keeping reporting after accepted check output prevents the agent from showing a report before the structured result passes validation. The final presentation reports why the monitor stopped without repeating a report that the user already saw.
+
+The sleep node uses the existing Pi Workflows shell action to launch the current Node executable with a timer. Set the node timeout above the largest supported interval because the engine default is 15 minutes. Set the shell execution timeout above the requested wait by a small fixed margin. Cancellation aborts the timer process immediately.
+
+If the Pi TUI or standalone workflow host stops during sleep, Pi Workflows parks the run and kills the shell child. Resuming the run starts that sleep node again from the beginning. This is existing workflow behavior and is acceptable for this feature. No special timer persistence is added.
+
+The workflow uses a high but finite `maxSteps` value as a second safety guard. Check and report values have explicit size limits so a long run cannot grow its bundle without bound.
+
+## Repository changes
+
+Make the feature in `osolmaz/pi-workflows`:
+
+- Refactor workflow lifecycle operations out of the slash-command handler.
+- Expand the normal Pi `workflow` tool and update its tests.
+- Update the RPC bridge submit contract.
+- Add built-in workflow discovery with project and global override precedence.
+- Add the built-in monitor workflow and focused tests.
+- Update `README.md` and `docs/workflows.md`.
+
+After the upstream change is complete, update the pinned Pi Workflows commit in OnurPi's thin `packages/workflows` wrapper. Do not add a new OnurPi extension or copy a monitor file into live global state.
+
+## State and API impact
+
+- **Session state:** Normal workflow prompts, model replies, tool calls, and monitor reports are appended through Pi's normal session behavior.
+- **Other persistent data:** No new data model. The feature uses existing run bundles and the existing workflow run queue.
+- **Pi internals:** None.
+- **Pi public API:** `registerTool`, `registerCommand`, `sendUserMessage`, and documented agent and session lifecycle events.
+- **Pi Workflows API:** The workflow definition and run-state models do not change. The model-facing `workflow` tool contract changes, and discovery gains a lowest-priority built-in source.
+
+## Non-goals
+
+This work does not add cron expressions, calendar schedules, a background service, controller resources, OS notifications, concurrent workflows in one session, resumable shell processes, or guaranteed wall-clock wake times across runner shutdowns. It does not let headless child agents recursively start workflows.
+
+## Acceptance criteria
+
+- A user can ask for repeated monitoring in plain language, and the agent starts `monitor` through the existing `workflow` tool.
+- The user does not type JSON or a slash command to start the monitor.
+- The monitor checks immediately, sleeps for the requested interval, and checks again.
+- An unchanged observation produces no normal assistant report.
+- A matching report condition produces one concise assistant report.
+- A matching stop condition reports as requested and ends the run.
+- The safety limit ends a monitor that never reaches its stop condition.
+- The model can list, start, inspect, pause, resume, cancel, answer, and submit through one tool.
+- Slash commands and tool actions use the same lifecycle code.
+- Starting from a model tool call does not cause an early nudge or record the initiating turn as the first workflow attempt.
+- A 30-minute sleep is not stopped by the default 15-minute node timeout.
+- Cancelling during sleep stops the shell child and ends the workflow.
+- Project and global workflows override the built-in `monitor` name.
+- Existing workflow, controller, host, viewer, and run-bundle tests continue to pass.
+- OnurPi loads the updated wrapper and Pi starts successfully.
+
+## Verification
+
+Add unit and integration coverage for tool action validation, lifecycle dispatch, deferred model-start launches, built-in discovery precedence, monitor routing, quiet checks, reports, stop conditions, safety limits, cancellation during sleep, and the headless submit bridge.
+
+Run:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+```
+
+Test the extension from the Pi Workflows checkout with `pi -e src/extension/index.ts`. Use a short test interval in a controlled fixture, then perform one manual 30-minute monitor run to confirm that the configured node timeout does not stop it. Test plain-language startup with the normal model, then test list, status, pause, resume, cancel, and checkpoint answer actions.
+
+After updating OnurPi, run its full checks and start Pi with the installed OnurPi package. Confirm that the model sees one `workflow` tool, discovers `monitor`, and can start it from a plain-language request.

package/docs/run-bundles.md

@@ -77,9 +77,9 @@ Consequences for readers:
 
 Large payloads are stored once, content-addressed, under `artifacts/` and
 referenced from the documents that use them. This applies uniformly to every
-**persisted value position**: `input`, `outputs.*`, `results.*.output`,
-`steps[*].prompt`, `steps[*].output`, `finalOutput`, and trace event payload
-values.
+**persisted value position**. These positions include `input`, `outputs.*`,
+`results.*.output`, `steps[*].prompt`, `steps[*].output`, and `finalOutput`.
+Trace event payload values follow the same rule.
 
 Encoding rule, applied recursively to a persisted value:
 
@@ -109,9 +109,9 @@ Artifact rules:
 - Artifacts are immutable once written and deduplicate by content hash.
 - Readers must tolerate unknown `mediaType` values.
 
-Because the same output can legitimately appear in `outputs`, `results`,
-`steps`, and the trace, externalization makes that duplication cheap: each
-copy is the same small reference.
+The same output can legitimately appear in several places. Externalization
+keeps each copy in `outputs`, `results`, `steps`, or the trace as the same small
+reference.
 
 ## manifest.json
 
@@ -154,6 +154,29 @@ validators are not serialized. Each node keeps only its metadata (`nodeType`,
 and edges are copied verbatim. The snapshot is what lets viewers draw all
 nodes, including ones that have not run yet. It is immutable after run start.
 
+## Resume and repair
+
+An interrupted run (status `running` with no terminal trace event) can resume
+instead of failing. Resume is a named operation with strict rules:
+
+1. The caller must hold the run's queue claim. Only the current claim holder
+   may resume or interrupt a bundle, and every bundle write verifies the
+   claim token first (write fencing).
+2. A torn trace tail (a crash mid-append) is truncated to the last complete
+   line. Trace events the state projection never recorded are dropped, so
+   `state.traceSeq` and the trace agree again before any new event.
+3. Completed nodes replay from the projection. The in-flight node reruns with
+   a fresh attempt; a `run_resumed` trace event marks the boundary.
+4. `state.workflowHash` pins the workflow source from run start. Resume
+   refuses a hash mismatch unless forced, and a forced resume records the
+   mismatch in the `run_resumed` payload.
+
+Continuation runs (answering a checkpoint) are new bundles, not resumed ones.
+They link back through `state.parentRunId`, carry the parent's outputs,
+results, and step records forward, and note `continuedFrom` in their
+`run_started` payload. Bundles stay append-only; a continuation is the only
+way work follows a terminal `waiting` state.
+
 ## state.json
 
 The full run projection (`WorkflowRunState` in
@@ -177,10 +200,16 @@ The full run projection (`WorkflowRunState` in
 ```
 
 - `status` is one of `running`, `waiting`, `completed`, `failed`, `timed_out`,
-  or `cancelled`.
-- While a node is executing, `currentNode`, `currentAttemptId`,
-  `currentNodeStartedAt`, and `statusDetail` describe it; they disappear when
-  the node finishes. The executing node's type comes from the definition
+  or `cancelled`. A controller host records an abandoned bundle as `failed`
+  with a final `run_interrupted` trace event. Before doing that, recovery checks
+  the trace tail and repairs a stale projection when the terminal event was
+  already appended. The controller store can then retry a genuinely abandoned
+  child attempt without changing this schema. If startup stopped before a
+  manifest existed, the scheduler preserves that incomplete directory as a
+  hidden sibling before creating the reserved run.
+- While a node is executing, `currentNode` and `currentAttemptId` identify it.
+  `currentNodeStartedAt` and `statusDetail` add timing and display context.
+  These fields disappear when the node finishes. The executing node's type comes from the definition
   snapshot, not from the state.
 - While a pause request holds the run at a step boundary, `paused` is `true`
   (with matching `run_paused`/`run_resumed` trace events); it disappears when
@@ -218,10 +247,9 @@ The full run projection (`WorkflowRunState` in
   produced by this attempt, from prompt delivery through accepted submission.
   Viewers must use this explicit linkage and never infer it heuristically.
 - Action steps carry an `action` receipt with `actionType`
-  (`shell`/`function`) and, for shell actions, `command`, `args`, `cwd`,
-  `exitCode`, `signal`, and `durationMs`. Shell stdout/stderr live in the
-  step output (the parsed or raw shell result) and are externalized when
-  large.
+  (`shell`/`function`). Shell actions also record `command`, `args`, `cwd`,
+  `exitCode`, `signal`, and `durationMs`. Shell stdout/stderr live in the step
+  output (the parsed or raw shell result) and are externalized when large.
 - When a run pauses at a checkpoint, `waitingOn` names the checkpoint node.
   Terminal runs carry `finalOutput` on success and `error` on failure.
 
@@ -248,8 +276,8 @@ One event per line, monotonically sequenced per run, schema
 ignore unknown event types and unknown payload fields so new ones can be added
 within the same schema version.
 
-The trace alone is sufficient to reconstruct the run: outputs and receipts are
-part of the terminal node events, not only of `state.json`.
+The trace alone is sufficient to reconstruct the run because terminal node
+events carry outputs and receipts.
 
 Event catalog and payload contracts:
 
@@ -268,6 +296,7 @@ Event catalog and payload contracts:
 | `run_failed`        | run     | `status`, `error`                                                   |
 | `run_timed_out`     | run     | `status`, `error`                                                   |
 | `run_cancelled`     | run     | `status`, `error?`                                                  |
+| `run_interrupted`   | run     | `error`                                                             |
 
 Invariants:
 
@@ -283,6 +312,15 @@ Present when the run executed inside a Pi conversation. The extension records
 the conversation into the bundle so replay never depends on Pi's global
 session store.
 
+A run that outlives its first session (parked, then resumed by another
+session or the host) gains a second capture under
+`session/segments/<attemptId>/` with the same file layout (`binding.json`,
+`entries.ndjson`, `events.ndjson`, `capture.json`). The first capture stays
+flat at `session/`; only captures from the second bind onward become
+segments, so readers that predate segments keep working on single-session
+bundles. An interrupted run finalizes any segment still `recording` as
+`failed` with the interruption reason.
+
 ### binding.json
 
 Written once when the run binds to the conversation
@@ -325,22 +363,23 @@ while the run was active, schema `pi-workflows.session-entry.v1`:
 - `entry` is the verbatim Pi session entry (Pi's own versioned format),
   including user messages, assistant messages, tool results, model changes,
   and compaction entries. Nothing is normalized or rewritten.
-- Entries include everything that happened in the conversation during the run:
-  workflow prompts, nudges, and user interruptions are all part of the record.
+- Entries include everything that happened in the conversation during the run.
+  This includes workflow prompts and nudges together with user interruptions.
 - `conversation` ranges in step records and `node_finished` events address
   entries by Pi entry id (`entry.id`).
 
 ### events.ndjson
 
-The temporal journal records documented Pi `turn_*`, `message_*`, and
+The temporal journal records documented Pi `turn_*` and `message_*` hooks plus
 `tool_execution_*` hooks with schema `pi-workflows.session-event.v1`. Each
-record has a per-file `seq`, timestamp, `nodeId`, `attemptId`, optional
-`turnId`, `messageId`, and `toolCallId`, a normalized `type`, and `payload`.
+record has a per-file `seq`, timestamp, `nodeId`, and `attemptId`. Optional
+turn, message, and tool call IDs link related records. A normalized `type` and
+`payload` carry the event data.
 The full contract and event catalog are in
 [session-event-journal.md](session-event-journal.md).
 
-Events preserve semantic deltas. Assistant `partial`, terminal `message`, and
-terminal `error` snapshots are never stored. Tool update records omit Pi's
+Events preserve semantic deltas. Assistant `partial` snapshots are never
+stored, and neither are terminal `message` or `error` snapshots. Tool update records omit Pi's
 cumulative `partialResult`. Final `message_finished` records link to settled
 Pi entries with `entryId`; after that linkage, `entries.ndjson` is the
 verbatim content authority.
@@ -364,10 +403,10 @@ complete lines, sequence gaps, and terminal torn tails are integrity failures.
 }
 ```
 
-`status` is `recording`, `complete`, or `failed`. Failed capture adds
-`failure` with `failedAt`, `code`, and `message`. Capture failure is visible to
-readers but does not fail the workflow. Terminal readers verify the counts,
-last sequence, schemas, and contiguous event sequence. Missing temporal files
+`status` starts as `recording` and ends as `complete` or `failed`. Failed
+capture adds `failure` with `failedAt` plus a code and message. Capture failure
+is visible to readers but does not fail the workflow. Terminal readers verify
+the counts and last sequence, then check schemas and contiguous event order. Missing temporal files
 in a session-bound bundle are invalid, not an older supported layout.
 
 ## Versioning