@osolmaz/pi-workflows 0.16.4 → 0.16.6

package/docs/WORKFLOW_STEP_MESSAGES.md

@@ -1,10 +1,10 @@
 # Workflow messages in Pi
 
-Status: this is the implemented workflow-message contract. [Unify workflow messages and restore hosted behavior](2026-09-02-unify-workflow-messages-plan.md) records the approved design and implementation plan.
+This is the current workflow-message contract. The [durable execution plan](2026-09-06-durable-execution-plan.md) supersedes the earlier automatic terminal-turn and reminder behavior.
 
 ## Goal
 
-Pi Workflows must add several kinds of content to an origin Pi conversation. These include interactive step prompts, protected human decisions, passive notifications, terminal results, and follow-up prompts. Initial, reminder, and resumed prompts are one step-message kind with different display reasons.
+Pi Workflows must add several kinds of content to an origin Pi conversation. These include interactive step prompts, protected human decisions, passive notifications, terminal results, and follow-up prompts. Initial and resumed prompts are one step-message kind with different display reasons.
 
 The server saves all of them as workflow messages. One extension component sends them through documented Pi APIs. Feature records continue to own workflow results, answers, settings, and timeouts.
 
@@ -16,13 +16,13 @@ A workflow message is content that Pi Workflows requires Pi to add to one conver
 
 The message kinds are:
 
-| Kind           | Pi behavior                                     | Purpose                                          |
-| -------------- | ----------------------------------------------- | ------------------------------------------------ |
-| `step`         | Custom message that starts a model turn         | Initial, reminder, or resumed interactive prompt |
-| `decision`     | Custom message that does not start a model turn | Protected choice for a person                    |
-| `notification` | Custom message that does not start a model turn | Passive workflow notice                          |
-| `terminal`     | Custom message that starts a model turn         | Final result and safe recovery choice            |
-| `followUp`     | Custom message that starts normal work          | Work saved for after successful completion       |
+| Kind           | Pi behavior                                      | Purpose                                    |
+| -------------- | ------------------------------------------------ | ------------------------------------------ |
+| `step`         | Custom message that starts a model turn          | Initial or resumed interactive prompt      |
+| `decision`     | Custom message that does not start a model turn  | Protected choice for a person              |
+| `notification` | Custom message that does not start a model turn  | Passive workflow notice                    |
+| `terminal`     | Visible message that does not start a model turn | Recorded terminal result                   |
+| `followUp`     | Custom message that starts normal work           | Work saved for after successful completion |
 
 The server stores one `WorkflowMessage` record before Pi can send it:
 
@@ -61,7 +61,7 @@ Every step message uses the custom type `pi-workflows-step`:
 export type WorkflowAgentStepMessageDetails = {
   schema: "pi-workflows.agent-step-message.v1";
   workflowMessageId: string;
-  reason: "initial" | "reminder" | "resumed";
+  reason: "initial" | "resumed";
   contract: AgentStepContract;
   presentation?: {
     runTitle?: string;
@@ -84,7 +84,7 @@ pi.sendMessage(
 
 The renderer reads `details` and does not parse the prompt. It shows a compact summary by default and the complete prompt when expanded. If the renderer is unavailable, Pi still retains the custom message and its content.
 
-Submitted agent steps call the `workflow` tool. Assistant-message steps reply normally. Both forms keep the existing `agent` node and use `expectedOutput` to select the completion form.
+Submitted agent steps call `workflow submit` or `workflow update` with the exact `requestId`. Assistant-message steps reply normally and are accepted only through the separate assistant-response path at `agent_settled`. Ordinary checkpoints accept `answer`; protected decisions accept only the verified human path or their declared timeout policy. Both forms keep the existing `agent` node and use `expectedOutput` to select the completion form.
 
 ## Engine boundary
 
@@ -103,10 +103,10 @@ A collapsed step card shows only the workflow identity and current work. For exa
 Checking the monitored target
 ```
 
-A reminder or resumed prompt adds a short label:
+A resumed prompt adds a short label:
 
 ```text
-↻ monitor › check · reminder
+↻ monitor › check · resumed
 Checking the monitored target
 ```
 
@@ -141,58 +141,75 @@ After Pi, the extension, or the server restarts, branch reporting runs before an
 
 ## Model-turn status
 
-`agent_start` has no message payload. The extension binds it through the current origin-session view. Turn binding ignores branch membership; only branch reporting and re-presentation inspect the active branch:
-
-- the latest sent step is open while its interaction remains pending and its run is not paused;
-- a terminal or follow-up message is open only until its first turn ends;
-- decisions and notifications never open a turn.
-
-A start against a closed message is rejected. Follow-up turns are reported for ordering but do not show the completed workflow as `running`.
-
-The extension creates one workflow turn ID at `agent_start` and keeps it through the matching `agent_end` and server reconnect. It buffers starts and ends until the session view and message receipt are ready.
-
-At `agent_end`, it derives `completed`, `aborted`, or `error` from the documented assistant messages. It reads response-entry evidence from `ctx.sessionManager.getBranch()`; the entry ID can be null. The server saves one immutable end result. A repeated report adopts it, and a stale turn ID cannot clear newer activity. A supervised runner can continue after accepted tool output while that Pi turn is still open. This normal continuation leaves the session capture recording until `agent_end`; it does not mark the capture as interrupted.
-
-The server applies the end and its workflow consequence in one transaction. An aborted turn sets the run pause and cancels the request's pending step messages; the interaction derives its paused state from the run. Resuming that submitted-output step atomically clears the pause, increments the interaction revision, and creates one new step message with reason `resumed`. That message starts a fresh Pi model turn. A protected decision does not start a model turn, so its revision and decision message do not change when its run resumes. A completed, recoverably failed, or proved-lost turn increments `unproductiveTurnEnds` only when the submitted-output step is pending, not paused, and has no accepted or validating submission. Values one and two create one step message with reason `reminder`; a value above two fails the attempt. A partial unique index enforces at most one pending step message for the request, regardless of reason. Acceptance, pause, cancel, timeout, and branch re-presentation cancel all pending step messages. A cancelled message did not start a turn and does not increment the counter.
-
-There is no activity heartbeat, refresh lease, or sequence counter. The server shows `running` from the matching start until the matching end. Server startup never marks a Pi turn lost. On `session_start`, only an idle-session branch report can close an open sent message with synthetic stop reason `lost`. Polling and time alone cannot create a reminder.
+`agent_start` has no message payload. A locally delivered prompt binds its start
+through the coordinator's saved message identity. Late binding and reconnect
+also require the exact message in the active branch. A session view alone does
+not prove that a message caused the current turn.
+
+Only pending, unpaused agent requests and explicit follow-ups can open model
+turns. Decisions, notifications, and terminal notices cannot. A stale start can
+adopt an already closed result but cannot create new activity. An identity
+mismatch is rejected before a turn changes.
+
+`agent_end` records low-level stop information. The coordinator retains the
+workflow turn through automatic Pi retries and waits for `agent_settled` before
+submitting visible assistant text, recording the turn end, or delivering more
+work. End reports carry `completed`, `aborted`, `error`, or `lost` and the exact
+response-entry evidence when available. A delayed acknowledgment keeps the settled
+response ID pending. Once message and turn ownership are confirmed, the coordinator
+submits that exact response before it reports the end. Later events cannot replace
+the pending turn or its response. Repeated reports adopt the saved result.
+
+An aborted pending step pauses its run. Resume retains the request and attempt,
+advances the request revision, and creates one resumed step message when needed.
+A protected decision keeps its answer revision and decision message. A missing
+submission stays pending: the host adds no reminder turn or hidden retry limit.
+
+Execution status and Pi activity remain separate. A completed run remains
+completed during reporting or follow-up work. A waiting run can have an active
+origin-session turn without changing its execution status to running. Host
+recovery closes active-time intervals at their last durable samples, not the Pi
+turn itself. Only an idle-session branch report can prove an unended turn lost.
 
 ## Feature ownership
 
 The workflow message stores only Pi send facts. Other records remain authoritative:
 
-- interactive requests own step contracts, attempts, deadlines, validation, model submissions, and `unproductiveTurnEnds`;
-- human decisions own choices, verified answers, expiry, and continuation;
+- interactive requests own exact response identity, kind, validation, and accepted submissions;
+- node attempts and active intervals own execution history and the active-time budget;
+- human decisions own choices, verified answers, and absolute expiry;
 - terminal runs own outcomes, reasons, restart lineage, and results;
 - notification nodes own their node results;
 - follow-up records own prompt source and authority;
 - settings records own current values and accepted changes.
 
-Submitted-output steps can use reminders. Assistant-message steps do not send a reminder after a visible response. An interrupted assistant-message step keeps its attempt ID and adopts a matching completed response from the active branch. A stale attempt or another branch remains invalid.
-
-Each source event creates its workflow message in the same SQLite transaction. The message cannot exist without its source fact, and a source fact cannot require a Pi message without the matching record.
+Submitted and assistant-message steps keep their exact attempt while parked.
+Recovery adopts accepted receipts and matching branch evidence; it does not use
+the oldest pending request or accept text from another request or branch.
 
-## Restored behavior
+Requests and their required messages commit together. Terminal reporting can be
+retried from recorded facts after execution settles; a reporting failure cannot
+reverse execution or cancellation.
 
-The shared contract supports these features without separate send paths:
+## Terminal results and follow-ups
 
-- at most two reminder-reason step messages after model turns end without a valid submission;
-- one resumed-reason step message after a presented paused step resumes;
-- one terminal result and recovery turn for the final outcome of each interactive continuation chain;
-- safe restart with lineage, a limit of three, and repeated-failure protection;
-- ordered follow-up prompts after successful completion, terminal turn end, and release of later workflow reservations;
-- protected decisions in Pi and approved external channels;
-- passive notifications that do not start model turns;
-- terminal result retention while its message is pending or its first turn is open, and then for 60 seconds after that turn ends, in the widget and `piw`;
-- conversation recording linked to workflow attempts.
+A terminal result is visible but does not start a model turn. It stays in the
+origin-session view while pending and for 60 seconds after confirmed delivery.
+An explicit restart targets the terminal run and revision and creates fresh
+work without copying old steps, changed settings, approvals, or effects. It has
+no terminal-turn prerequisite or hard-coded count limit.
 
-A terminal or follow-up message does not reopen the completed workflow. A slash-looking follow-up remains plain model input because `pi.sendMessage()` does not dispatch extension commands or expand prompt templates. External effects remain idempotent or explicitly ambiguous.
+Explicit follow-ups wait for successful completion, terminal notice delivery,
+prior follow-up settlement, and release of the session reservation. They remain
+normal conversation work. Slash-looking text cannot dispatch an extension
+command. External effects still require saved receipts or explicit recovery of
+an ambiguous outcome. See [terminal workflow messages](DEFERRED_TURNS.md).
 
 ## Session recording
 
 The extension records workflow-related Pi events through a batched server client operation. It uses documented Pi events and does not read or edit Pi session files.
 
-The server deduplicates settled entries by Pi entry ID. It links attempts to their prompt, response, first, and last entries. A recording failure does not fail workflow execution.
+The server deduplicates settled entries by Pi entry ID. It links attempts to their prompt, response, first, and last entries. The coordinator finalizes capture after the terminal notice has a confirmed entry on the current branch, without starting a model turn. Explicit follow-up turns have their own capture segment. A recording failure does not fail workflow execution or block the next delivery.
 
 ## Public API boundary
 
@@ -205,26 +222,27 @@ This design does not change Pi core, use private Pi APIs, or change Pi session s
 Tests must prove:
 
 - every message kind uses the one coordinator;
-- one workflow message ID creates at most one confirmed Pi entry and one automatic model turn;
+- one workflow message ID adopts its confirmed Pi entry before another send;
+- an automatic Pi retry cannot submit a partial response before the settled boundary;
 - a later manual turn uses a new workflow turn ID without creating another Pi entry;
 - two Pi processes that open one session cannot both send because one process-local coordinator epoch is active;
 - restart recovery reports the branch and adopts an existing entry before it sends;
 - branch absence is usable only when Pi is idle and has no pending input;
 - a crash after send leaves the message pending and cannot cause a resend before branch reporting;
 - messages remain in saved order without message-pointer deadlocks;
-- an early `agent_start` and `agent_end` wait for the message receipt and session view, then apply in order;
-- every matching model turn shows `running` for its full duration;
-- normal runner continuation leaves the active session capture open until the matching turn ends;
+- an early `agent_start` and `agent_settled` wait for the message receipt and session view, then apply in order;
+- model activity remains separate from durable execution status;
+- normal runner progress leaves the active session capture open until the matching turn ends;
 - stale turn-end reports and starts against closed messages are rejected;
 - a manual turn cancels pending step messages that it supersedes;
 - a turn cannot bind to an interaction whose run is paused;
-- aborted turns pause without incrementing the unproductive-turn counter;
+- aborted pending turns pause without adding reminder work;
 - resuming an aborted step creates one new resumed message and one fresh model turn;
 - resuming a protected decision keeps its answer revision and does not create a duplicate decision message;
 - server restart does not close a live Pi turn, while an idle-session branch report can close an unended turn as lost;
-- two reminder-reason steps are sent at most once and the next unproductive turn fails;
-- initial, reminder, and resumed prompts use the same step kind and differ only by reason;
-- terminal and follow-up messages each start only at their durable boundary;
+- repeated missing submissions remain pending without automatic extra model turns;
+- initial and resumed prompts use the same step kind and differ only by reason;
+- terminal messages never start turns, and follow-ups start only at their declared boundary;
 - a branch switch creates one resumed-reason step only when that branch has no entry for the interaction;
 - a missing protected decision creates another decision message, not a step;
 - branch evidence changes a cancelled message to sent;

package/docs/plans/2026-08-04-controller-runtime-plan.md

@@ -8,6 +8,8 @@ status: implemented
 
 # ResourceManager runtime plan
 
+> Historical plan. The [durable execution plan](../2026-09-06-durable-execution-plan.md) supersedes its continuation, scheduling, and automatic model-turn choices. Use the current reference pages for the implemented contract.
+
 pi-workflows needs a controller mode for automation that spans repeated events, external state changes, and process restarts. The design in [RESOURCE_MANAGERS.md](../RESOURCE_MANAGERS.md) follows the Kubernetes controller pattern. Durable resources hold desired and observed state, events enqueue resource keys, and each reconciliation reads current facts before acting.
 
 The implementation keeps the graph engine focused on finite jobs. Controllers start and observe workflows through a child-run interface. Workflow graphs keep their finite execution model.

package/docs/plans/2026-08-21-deferred-turn-intents-plan.md

@@ -6,6 +6,8 @@ date: 2026-08-21
 
 # Guarantee one successor turn after workflow interruption
 
+> Historical plan. The [durable execution plan](../2026-09-06-durable-execution-plan.md) supersedes its continuation, scheduling, and automatic model-turn choices. Use the current reference pages for the implemented contract.
+
 Pi Workflows can stop the active agent turn before the agent receives a tool result or can take its next action. This happens when an active workflow step is cancelled, times out, loses its queue claim, or is interrupted by a controller. The workflow can also return a successful start result and then fail asynchronously before it sends its first prompt. In that case, the user can see a UI error while the model still believes that the workflow started successfully.
 
 Add one general rule: an eligible workflow event creates one durable obligation for one later agent turn. The next normal workflow prompt or result presentation satisfies the obligation when one exists. Otherwise, Pi Workflows sends one factual fallback turn after the old turn settles.

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

@@ -6,6 +6,8 @@ date: 2026-08-27
 
 # Full plan
 
+> Historical plan. The [durable execution plan](../2026-09-06-durable-execution-plan.md) supersedes its continuation, scheduling, and automatic model-turn choices. Use the current reference pages for the implemented contract.
+
 ## Goal
 
 After every top-level workflow run ends, give the model one normal successor turn.

package/docs/plans/2026-09-04-automatic-state-retention-plan.md

@@ -0,0 +1,283 @@
+---
+title: Add automatic workflow state retention
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-09-04
+status: approved
+---
+
+# Add automatic workflow state retention
+
+## Goal
+
+Pi Workflows will remove old completed workflow state automatically. It will keep active, resumable, pending, unsettled, and undelivered work.
+
+The server will retain terminal run trees for 30 days. It will then remove safe expired trees and blobs that no retained record or active runner uses. The manual prune command will use the same safety rules.
+
+A regression test will also protect the earlier runner fix. Repeated runner replies must not copy growing Pi session history and make the database grow by several gigabytes.
+
+## Observed problem
+
+One old state database reached about 6.1 GB. The `blobs` table held about 6.06 GB across 101,355 blobs, which were almost all JSON. `worker_messages.result_hash` was the main reference path.
+
+Older runner replies copied growing session and workflow history into new immutable result blobs. Small changes produced another large blob, so content hashing could not deduplicate the replies. [Keep large workflow history out of runner resume replies](2026-09-04-workflow-runner-resume-state-plan.md) fixed that interface by returning only the execution state a runner needs.
+
+That fix stops the main amplification path. Completed workflow history still remains until a person runs `pi-workflows state prune`, so the database can still grow without a retention rule.
+
+## Selected design
+
+Use the existing run-tree prune logic as the one cleanup engine. Automatic cleanup and manual prune will share selection, deletion, blob collection, and compaction rules.
+
+A terminal root run and all its restart or continuation descendants remain for 30 days after `finished_at`. Every descendant must be terminal and older than the cutoff before the server can remove the tree. Protected state or a reference from outside the tree blocks removal.
+
+The Workflow Server checks for cleanup after startup recovery and after workflow runners exit. It also schedules a daily check after each completed sweep. It starts cleanup only while normal server work is idle. One server process completes no more than one sweep in 24 hours. An interrupted sweep remains due. The next idle lifecycle trigger or a five-minute idle retry continues it.
+
+Automatic cleanup creates no backup. Creating a new backup for every sweep would cause another unbounded store. The explicit manual prune command keeps its current dry-run and backup-first apply forms.
+
+This design does not add size-based deletion. A clear time limit gives users predictable history. Recent or protected data can still be large, so this design does not promise a hard disk-size cap.
+
+## Retention contract
+
+### Eligible run trees
+
+A run tree is eligible only when all of these facts are true:
+
+- The root run and every descendant have status `completed`, `failed`, `timed_out`, or `cancelled`.
+- Every run in the tree has `finished_at` earlier than the 30-day cutoff.
+- No row outside the tree depends on a row inside it.
+- No protected work belongs to the tree.
+
+The cleanup transaction rechecks the exact root tree before deletion. A changed tree is skipped.
+
+### Protected work
+
+Automatic cleanup must keep a tree when it contains or owns any of this work:
+
+- a waiting or parked run
+- a queued, starting, running, or parked queue row
+- a pending workflow message
+- an open workflow turn
+- a pending interaction or human decision
+- a recording session segment
+- a queued follow-up
+- an active lease
+- a pending, applying, or ambiguous effect
+- controller ownership or a managed resource reference
+- a continuation or step reference from outside the tree
+- an active runner content hash
+- a resumable checkpoint
+- an undelivered terminal result
+
+Unknown or conflicting ownership blocks deletion. Cleanup must fail closed.
+
+### Automatic scheduling
+
+The server requests one automatic sweep after recovery and after a workflow runner exits. Overlapping requests join the same in-process task.
+
+A sweep starts only when there is no active or pending workflow runner, resource-manager runner, state-maintenance command, or server shutdown. It deletes one complete root tree in one transaction, yields, and checks for new work before it selects another tree.
+
+A completed sweep starts a 24-hour in-process interval and schedules the next daily check. A sweep that stops because new work appeared remains due. The next idle lifecycle trigger or a five-minute idle retry continues it. A new request during the completed-sweep interval waits until that interval ends.
+
+The cleanup scheduler is part of the existing server process. It does not add a service, scheduler process, or second writer.
+
+### Blob cleanup
+
+After run deletion, the state layer removes only blobs with no database foreign-key reference and no active runner reference. The existing schema scan remains the source for blob references, so a future blob foreign key is protected automatically.
+
+A repeated sweep is safe. A second sweep finds no extra rows from work that was already removed.
+
+### Space reuse and file compaction
+
+After logical deletion, the server truncates the WAL while idle and reads SQLite `page_count`, `freelist_count`, and `page_size`. SQLite can reuse free pages even when the main file does not shrink.
+
+Automatic cleanup runs `VACUUM` only when all of these facts are true:
+
+- normal server work is still idle
+- at least 64 MiB is reclaimable
+- at least 20 percent of database pages are free
+
+A skipped or failed `VACUUM` does not undo committed logical deletion. The server reports the outcome and leaves the free pages available for reuse. It does not claim that the file shrank unless measurement proves it.
+
+Manual prune keeps its current backup-first full compaction and integrity checks.
+
+### Failure handling
+
+A cleanup error does not fail a workflow or stop the server. The server records one clear diagnostic and waits five minutes before another safe attempt. It does not retry in a tight loop.
+
+Cleanup is atomic for one complete root tree. An interruption can leave later trees for another sweep, but it cannot leave half of one lineage tree deleted.
+
+## Public behavior
+
+Retained runs keep their current resume, viewer, content-reference, and terminal-result behavior. The viewer continues to read bounded pages. Pi Workflows does not edit Pi session history.
+
+After an expired tree is removed, it no longer appears in run lists. A direct run view returns not found.
+
+The manual commands remain:
+
+```bash
+pi-workflows state prune --before <timestamp> --dry-run
+pi-workflows state prune --before <timestamp> --backup <absolute-path> --apply
+```
+
+Automatic cleanup adds no client protocol operation. The SQLite schema name and version remain `pi-workflows-state` version 1. This change adds no migration, compatibility reader, second state path, fallback, feature flag, archive, or external resource.
+
+## Implementation
+
+### Share the cleanup engine
+
+**Where**
+
+- `src/state/prune.ts`
+- version-1 invariants in `src/state/schema.ts`
+
+**Change**
+
+Split the current prune work into shared run-tree selection, exact-tree deletion, unreferenced-blob collection, page measurement, and compaction operations. Add every protected-state check from this plan.
+
+Automatic deletion must recheck and delete one root tree in the same transaction. Manual prune keeps its backup and complete-selection recheck.
+
+**Check**
+
+State tests prove that eligible trees are removed as one unit. Each protected state keeps its whole tree. Foreign-key and integrity checks pass after deletion.
+
+### Add automatic cleanup
+
+**Where**
+
+- `src/state/prune.ts`
+- `src/server/server.ts`
+
+**Change**
+
+Add an automatic entry point with a cutoff of the current time minus 30 days. It uses the shared cleanup engine without creating a backup.
+
+Process one complete root tree per transaction. Yield between trees. Stop when normal server work appears and leave the sweep due.
+
+**Check**
+
+Automatic and manual cleanup select the same eligible trees. Automatic cleanup creates no backup. A stopped sweep continues later without duplicate deletion.
+
+### Schedule cleanup from the server lifecycle
+
+**Where**
+
+- lifecycle fields in `src/server/server.ts`
+- `WorkflowServer.start()`
+- server shutdown
+- the active-run exit path after the server removes the run from `activeRuns`
+
+**Change**
+
+Request cleanup after startup recovery and after runner exit. Schedule a daily check after each completed sweep. Coalesce overlapping requests. Enforce the idle check, five-minute idle retry, and 24-hour completed-sweep interval.
+
+A failed sweep logs one bounded error and waits for a later trigger. Shutdown starts no new sweep and settles any current scheduling task safely.
+
+**Check**
+
+Server tests use controlled scheduler timestamps and temporary databases to cover startup, runner exit, coalescing, the 24-hour interval, interruption, clean shutdown, and one injected failure.
+
+### Reuse pages and compact when worthwhile
+
+**Where**
+
+- database-size helpers in `src/state/prune.ts`
+- `test/prune.test.ts`
+
+**Change**
+
+Measure free SQLite pages after deletion. Truncate the WAL while idle. Run automatic `VACUUM` only above the 64 MiB and 20 percent thresholds.
+
+Keep committed deletion when compaction is skipped or fails. Report logical deletion and physical file size separately.
+
+**Check**
+
+Tests prove page reuse below the thresholds, no early automatic `VACUUM`, physical reduction after successful compaction, and intact retained data after a simulated compaction failure.
+
+### Add the large-state regression
+
+**Where**
+
+- `test/server.test.ts`
+- `test/workflow-runner-content.test.ts`
+- the existing large-resume test fixture
+
+**Change**
+
+Create more than 2 MiB of distinct recorded session history. Run several resume, wait, continue, and terminal runner exchanges. Add a small unique item between exchanges.
+
+Measure distinct blobs referenced by `worker_messages.result_hash`, every runner frame, total blob bytes, and SQLite pages. The test must prove that runner control replies contain only required execution state or content references. They must not copy complete session history into every reply.
+
+**Check**
+
+The regression fails when each reply includes the growing history. It passes when result growth follows new workflow state, and every runner frame stays inside its protocol limit.
+
+### Cover retention behavior
+
+**Where**
+
+- `test/prune.test.ts`
+- `test/server.test.ts`
+- `test/server-view.test.ts`
+- the existing state-prune client tests
+
+**Change**
+
+Test recent and expired trees, restart and continuation families, pending and sent terminal messages, open turns, waiting and parked work, every blocker, concurrent manual prune, automatic blob cleanup, viewer access, and resume.
+
+Use temporary databases and deterministic executors. Automated tests must not call a model or touch the user's live state.
+
+**Check**
+
+Retained runs still resume and render. Expired delivered terminal trees disappear as one unit. Protected trees remain. Repeated cleanup has no additional effect.
+
+### Update documentation
+
+**Where**
+
+- `docs/SQLITE_STATE.md`
+- `docs/WORKFLOW_SERVER.md`
+- `docs/workflows.md`
+- CLI help where it describes state retention
+
+**Change**
+
+Document the contract in this plan. Remove the old statement that Pi Workflows never prunes at startup.
+
+**Check**
+
+Documentation matches the code constants and tests. It makes no hard size or file-shrink promise.
+
+## Tests and checks
+
+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
+git diff --check
+```
+
+Automated tests use temporary directories and deterministic executors. They do not call a real model.
+
+After these checks pass, run the separate installed-package E2E with the exact authenticated low-cost model `openai/gpt-5.6-luna`. Use temporary workflow state. Do not prune or seed the user's live database.
+
+## Acceptance criteria
+
+The work is complete when all of these statements are true:
+
+- Terminal root-run trees remain for 30 days.
+- Cleanup removes only complete eligible trees.
+- Every active, pending, open, resumable, recording, queued, leased, unsettled, controller-owned, cross-linked, undelivered, or active-content case remains protected.
+- Automatic cleanup runs without a second service or manual command.
+- Manual prune remains backup-first.
+- Repeated cleanup is safe and does not partly delete a lineage tree.
+- Freed pages can be reused.
+- Automatic `VACUUM` follows the 64 MiB, 20 percent, and idle rules.
+- Retained runs still resume and render through bounded reads.
+- Deleted runs return not found.
+- The large-state regression proves that repeated runner replies do not copy growing session history.
+- The SQLite schema stays at version 1 with no migration or compatibility path.
+- Pi core, Pi session history, other repositories, external services, and the user's live workflow state remain unchanged.
+- All repository checks and the separate real-model E2E pass.