@osolmaz/pi-workflows 0.16.3 → 0.16.5

package/docs/WORKFLOW_SERVER.md

@@ -1,6 +1,6 @@
 # Workflow server
 
-Status: the out-of-process server, unified live client, workflow-message contract, and restored session behavior are implemented. [Unify workflow run state](2026-09-04-workflow-run-state-plan.md) records the approved refactor for turn ownership, managed effects, restarts, terminal data, cancellation, and runner recovery. [Unify workflow messages and restore hosted behavior](2026-09-02-unify-workflow-messages-plan.md), [run workflows outside Pi](2026-08-30-out-of-process-workflow-host-plan.md), [restore workflow session delivery and controls](2026-09-01-restore-session-delivery-controls-plan.md), and [unify live workflow clients](2026-09-01-unified-workflow-client-plan.md) record the earlier design and implementation plans.
+Status: the out-of-process server, unified live client, workflow-message contract, and restored session behavior are implemented. [Unify workflow run state](2026-09-04-workflow-run-state-plan.md) records the approved refactor for turn ownership, managed effects, restarts, terminal data, cancellation, and runner recovery. [Add automatic workflow state retention](plans/2026-09-04-automatic-state-retention-plan.md) records the approved 30-day cleanup contract. [Unify workflow messages and restore hosted behavior](2026-09-02-unify-workflow-messages-plan.md), [run workflows outside Pi](2026-08-30-out-of-process-workflow-host-plan.md), [restore workflow session delivery and controls](2026-09-01-restore-session-delivery-controls-plan.md), and [unify live workflow clients](2026-09-01-unified-workflow-client-plan.md) record the earlier design and implementation plans.
 
 ## Purpose
 
@@ -426,11 +426,32 @@ At startup the server:
 9. Resumes any remaining provisional `validating` submission in a new supervised child.
 10. Waits for the extension's active-branch report before it confirms pending entries as sent, closes a turn as `lost`, or creates a branch-specific replacement. The extension sends this report after every server connection.
 11. Starts no model turn until a matching Pi session connects or headless mode is declared.
+12. Requests an automatic state-retention sweep after recovery. The sweep waits until normal server work is idle.
 
 Recovery resumes from the last committed boundary. An uncommitted compute node may run again because compute is pure. An action with a stored effect receipt adopts that receipt. An effect in `ambiguous` state requires explicit recovery.
 
 Claim loss is a handoff, not a run failure. The old owner writes no terminal event after claim loss.
 
+## State retention
+
+The server keeps terminal root-run trees for 30 days from `finished_at`. A tree can expire only when all restart and continuation descendants are terminal, older than the cutoff, and free of protected state or references from outside the tree.
+
+The server protects waiting and parked runs, live queue rows, pending workflow messages, open workflow turns, pending interactions and human decisions, recording session segments, queued follow-ups, active leases, unsettled effects, controller ownership, active runner content, resumable checkpoints, and undelivered terminal results. A cross-tree continuation or step reference also blocks deletion. Unknown ownership blocks deletion.
+
+The server requests a sweep after startup recovery and after a workflow runner exits. It also schedules the next daily check after a completed sweep. Overlapping requests join one in-process task. A sweep starts only when there is no active or pending workflow runner, resource-manager runner, state-maintenance command, or shutdown. One server process completes at most one sweep in 24 hours. If new work appears, cleanup stops between complete root trees and remains due. The next idle lifecycle trigger or a five-minute idle retry continues it.
+
+Automatic cleanup and `state prune` use the same selector, exact-tree deletion, and unreferenced-blob collection. Automatic cleanup does not make a backup. The explicit manual apply command still requires a new absolute verified backup.
+
+Automatic cleanup deletes one root tree per transaction and rechecks that tree before deletion. It then yields so server work can start. Matching repeated cleanup has no additional effect.
+
+After deletion, SQLite can reuse free pages. The server truncates the WAL while idle. It runs automatic `VACUUM` only when it is still idle, at least 64 MiB is reclaimable, and at least 20 percent of database pages are free. A skipped or failed compaction leaves committed deletion and reusable pages intact.
+
+A cleanup failure records one bounded diagnostic. It does not fail a workflow or stop the server. The next attempt waits five minutes, so it cannot start a tight retry loop.
+
+Retained runs keep their normal resume, bounded viewer, content-reference, and terminal-result behavior. Deleted expired runs disappear from run lists and direct views. Pi session history is unchanged.
+
+This policy limits old completed history. It does not set a hard database-size cap because recent or protected work can be arbitrarily large. Physical file shrink also depends on a safe, successful SQLite compaction.
+
 ## Effects and retry safety
 
 Compute nodes must not perform external side effects. They can repeat after a runner crash.
@@ -549,4 +570,11 @@ The implementation conforms when:
 - a terminal run remains in the origin-session view while its terminal message is pending or its first turn is open, and then for 60 seconds after that turn ends, without retaining execution authority;
 - a TypeScript-created live database is viewable by the matching Rust `piw` through the client protocol without a duplicated SQLite digest;
 - no removed server, replay, or direct SQLite client path remains selectable;
+- only complete terminal run trees older than 30 days and free of protected work can expire;
+- startup and runner-exit cleanup share the manual prune selector and deletion rules;
+- automatic cleanup creates no backup, while manual apply remains backup-first;
+- repeated cleanup cannot partly delete a lineage tree or remove a referenced blob;
+- retained runs keep their resume, viewer, content-reference, and terminal-result behavior;
+- large session history does not get copied into repeated runner result blobs;
+- free pages remain reusable when automatic compaction is skipped or fails;
 - real Pi end-to-end tests, repository checks, reviewer checks, and CI pass.

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.

package/docs/workflows.md

@@ -771,6 +771,22 @@ resume` takes a new generation and reruns only work after the last durable
 - Server status reports safe counts and timestamps. It does not report session
   IDs, project paths, prompts, payloads, tokens, process IDs, or credentials.
 
+## Run history retention
+
+Pi Workflows keeps a terminal root run and all its restart or continuation descendants for 30 days from `finished_at`. The server can remove the tree after that point only when every descendant is terminal and no protected work or outside reference remains.
+
+Protected work includes waiting or parked runs, live queue rows, pending workflow messages, open workflow turns, pending interactions or decisions, recording session segments, queued follow-ups, active leases, unsettled effects, controller ownership, active runner content, resumable checkpoints, and undelivered terminal results.
+
+The server checks for cleanup after startup recovery and after workflow runners exit. It also schedules a daily check after each completed sweep. Cleanup runs only while normal server work is idle. One process completes at most one sweep in 24 hours. If work appears, cleanup stops between complete root trees. The next idle lifecycle trigger or a five-minute idle retry continues it.
+
+Automatic cleanup does not create a backup. The explicit `pi-workflows state prune` apply command still requires a new absolute verified backup. Both paths use the same eligibility, deletion, and blob-reference rules.
+
+Deleting a run tree removes its unreferenced blobs. SQLite can reuse those pages immediately. Automatic `VACUUM` runs only while the server remains idle, at least 64 MiB is reclaimable, and at least 20 percent of pages are free. A failed or skipped compaction does not restore deleted history or make free pages unusable.
+
+Retained runs keep complete resume and viewer behavior through the existing bounded reads. An expired deleted run no longer appears in lists and a direct view returns not found. Pi session history is not changed.
+
+This is a history policy, not a hard disk limit. Recent or protected runs can be large. See [SQLite state](SQLITE_STATE.md) and [the automatic state-retention plan](plans/2026-09-04-automatic-state-retention-plan.md) for the full safety and test contract.
+
 ## Workflows started by resource managers
 
 A resource manager can start a workflow as a finite child job with `ctx.workflows.ensure()`. The request key is stable across reconciliation passes, and the input fingerprint prevents one key from being reused for different work.

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.16.3"
+version = "0.16.5"
 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.16.3",
+  "version": "0.16.5",
   "description": "Workflow and resource manager runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
@@ -71,14 +71,15 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@earendil-works/pi-server": ">=0.85.0",
     "better-sqlite3": "^13.0.2",
     "jiti": "^2.7.0",
     "tsx": "^4.23.13"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.2",
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@earendil-works/pi-tui": "0.84.2",
+    "@earendil-works/pi-ai": "0.85.0",
+    "@earendil-works/pi-coding-agent": "0.85.0",
+    "@earendil-works/pi-tui": "0.85.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^26.1.1",
     "@vitest/coverage-istanbul": "^4.1.10",
@@ -89,9 +90,9 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.84.2 <0.85.0",
-    "@earendil-works/pi-coding-agent": ">=0.84.2 <0.85.0",
-    "@earendil-works/pi-tui": ">=0.84.2 <0.85.0",
+    "@earendil-works/pi-ai": ">=0.84.2",
+    "@earendil-works/pi-coding-agent": ">=0.84.2",
+    "@earendil-works/pi-tui": ">=0.84.2",
     "typebox": "*"
   },
   "engines": {

package/src/server/server.ts

@@ -62,7 +62,11 @@ import {
 import { StateDatabase, workflowStatePath } from "../state/database.js";
 import { canonicalJson, type JsonValue } from "../state/json.js";
 import { resourceIdFor } from "../state/mutation.js";
-import { pruneState } from "../state/prune.js";
+import {
+  AUTOMATIC_STATE_PRUNE_INTERVAL_MS,
+  pruneState,
+  pruneStateAutomatically,
+} from "../state/prune.js";
 import { recordViewerDeltas } from "../state/viewer.js";
 import { workflowMessageIdFor } from "../state/workflow-messages.js";
 import { humanDecisionChannelRequest } from "../workflows/decision-presentation.js";
@@ -135,6 +139,7 @@ const SERVER_RENEW_MS = 10_000;
 const PACKAGE_VERSION = runtimePackageVersion();
 const CLAIM_POLL_MS = 2_000;
 const TERMINAL_MESSAGE_RECONCILE_MS = 1_000;
+const AUTOMATIC_STATE_PRUNE_IDLE_RETRY_MS = 5 * 60 * 1_000;
 const RUN_CLAIM_LEASE_MS = 30_000;
 const RESOURCE_MANAGER_CLAIM_LEASE_MS = 120_000;
 const RESOURCE_MANAGER_RENEW_MS = 30_000;
@@ -264,6 +269,12 @@ export class WorkflowServer {
   private decisionChannelConfig: DecisionChannelConfig | null = null;
   private decisionChannelError: string | null = null;
   private channelReloading = false;
+  private automaticStatePruneTask: Promise<void> | null = null;
+  private automaticStatePruneTimer: ReturnType<typeof setTimeout> | null = null;
+  private automaticStatePruneScheduled = false;
+  private automaticStatePruneDue = true;
+  private lastAutomaticStatePruneAt: number | null = null;
+  private nextAutomaticStatePruneAttemptAt = 0;
   private nextTerminalMessageReconciliationAt = 0;
 
   constructor(options: WorkflowServerOptions = {}) {
@@ -347,13 +358,16 @@ export class WorkflowServer {
       this.startTimers();
       this.started = true;
       this.log(`ready on ${this.socketPath} at epoch ${this.claim.epoch}`);
+      this.requestAutomaticStatePrune();
       this.expireTimedOutInteraction();
-      void this.expireTimedOutDecision();
-      void this.claimOne();
-      void this.claimResourceManagerOne();
-      void this.reloadDecisionChannels().catch((error) => {
-        this.log(`decision channel startup failed: ${errorMessage(error)}`);
-      });
+      void this.expireTimedOutDecision().finally(() => this.resumeAutomaticStatePruneIfDue());
+      void this.claimOne().finally(() => this.resumeAutomaticStatePruneIfDue());
+      void this.claimResourceManagerOne().finally(() => this.resumeAutomaticStatePruneIfDue());
+      void this.reloadDecisionChannels()
+        .catch((error) => {
+          this.log(`decision channel startup failed: ${errorMessage(error)}`);
+        })
+        .finally(() => this.resumeAutomaticStatePruneIfDue());
     } catch (error) {
       const server = this.server;
       this.server = null;
@@ -378,9 +392,12 @@ export class WorkflowServer {
     if (this.heartbeatTimer !== null) clearInterval(this.heartbeatTimer);
     if (this.pollTimer !== null) clearInterval(this.pollTimer);
     if (this.viewTimer !== null) clearInterval(this.viewTimer);
+    if (this.automaticStatePruneTimer !== null) clearTimeout(this.automaticStatePruneTimer);
     this.heartbeatTimer = null;
     this.pollTimer = null;
     this.viewTimer = null;
+    this.automaticStatePruneTimer = null;
+    this.automaticStatePruneScheduled = false;
     const server = this.server;
     this.server = null;
     this.detachSessionCoordinators();
@@ -419,6 +436,9 @@ export class WorkflowServer {
     this.activeChannels.clear();
     await Promise.allSettled(this.activationTasks.values());
     await Promise.allSettled(this.maintenanceCommands.values());
+    if (this.automaticStatePruneTask !== null) {
+      await Promise.allSettled([this.automaticStatePruneTask]);
+    }
     this.registry.killAll();
     if (this.claim !== null) this.serverState.releaseServer(this.claim);
     this.claim = null;
@@ -763,6 +783,7 @@ export class WorkflowServer {
           });
         case "state.prune":
           return await this.executeMaintenanceCommand(request, async () => {
+            await this.waitForAutomaticStatePrune();
             const payload = requireRecord(request.payload, "state.prune payload");
             const before = requireString(payload.before, "before");
             const apply = requireBoolean(payload.apply, "apply");
@@ -836,6 +857,7 @@ export class WorkflowServer {
       if (this.maintenanceCommands.get(key) === execution) {
         this.maintenanceCommands.delete(key);
       }
+      this.requestAutomaticStatePrune();
     }
   }
 
@@ -1927,6 +1949,127 @@ export class WorkflowServer {
     return [...digests].map((digest) => Buffer.from(digest, "hex"));
   }
 
+  private requestAutomaticStatePrune(): void {
+    this.automaticStatePruneDue = true;
+    if (
+      !this.started ||
+      this.stopping ||
+      this.automaticStatePruneScheduled ||
+      this.automaticStatePruneTask !== null
+    ) {
+      return;
+    }
+    this.automaticStatePruneScheduled = true;
+    setImmediate(() => {
+      if (!this.automaticStatePruneScheduled) return;
+      this.automaticStatePruneScheduled = false;
+      this.startAutomaticStatePrune();
+    });
+  }
+
+  private resumeAutomaticStatePruneIfDue(): void {
+    if (this.automaticStatePruneDue) this.requestAutomaticStatePrune();
+  }
+
+  private startAutomaticStatePrune(): void {
+    if (this.automaticStatePruneTask !== null || this.stopping || !this.started) return;
+    const task = this.runAutomaticStatePrune();
+    this.automaticStatePruneTask = task;
+    void task.finally(() => {
+      if (this.automaticStatePruneTask === task) this.automaticStatePruneTask = null;
+    });
+  }
+
+  private async runAutomaticStatePrune(): Promise<void> {
+    if (!this.automaticStatePruneDue) return;
+    if (!this.automaticStatePruneCanContinue()) {
+      this.scheduleAutomaticStatePruneTimer(AUTOMATIC_STATE_PRUNE_IDLE_RETRY_MS);
+      return;
+    }
+    const now = Date.now();
+    if (now < this.nextAutomaticStatePruneAttemptAt) {
+      this.scheduleAutomaticStatePruneTimer(this.nextAutomaticStatePruneAttemptAt - now);
+      return;
+    }
+    if (
+      this.lastAutomaticStatePruneAt !== null &&
+      now - this.lastAutomaticStatePruneAt < AUTOMATIC_STATE_PRUNE_INTERVAL_MS
+    ) {
+      this.scheduleAutomaticStatePruneTimer(
+        this.lastAutomaticStatePruneAt + AUTOMATIC_STATE_PRUNE_INTERVAL_MS - now,
+      );
+      return;
+    }
+    try {
+      const report = await pruneStateAutomatically(this.state, this.databasePath, {
+        now,
+        activeBlobHashes: () => this.activeRunnerContentHashes(),
+        shouldContinue: () => this.automaticStatePruneCanContinue(),
+      });
+      if (!report.completed) {
+        this.automaticStatePruneDue = true;
+        this.scheduleAutomaticStatePruneTimer(AUTOMATIC_STATE_PRUNE_IDLE_RETRY_MS);
+        return;
+      }
+      this.lastAutomaticStatePruneAt = now;
+      this.nextAutomaticStatePruneAttemptAt = 0;
+      this.automaticStatePruneDue = false;
+      this.scheduleAutomaticStatePruneTimer(AUTOMATIC_STATE_PRUNE_INTERVAL_MS);
+      this.log(
+        `automatic state prune completed: ${report.selectedRuns} run(s) selected, ` +
+          `${report.blockedTrees} tree(s) blocked, ${report.deletedBlobs} blob(s) and ` +
+          `${report.deletedBlobBytes} byte(s) removed`,
+      );
+      if (report.compactionError !== undefined) {
+        this.log(`automatic state compaction failed: ${report.compactionError}`);
+      }
+    } catch (error) {
+      this.automaticStatePruneDue = true;
+      this.nextAutomaticStatePruneAttemptAt = Date.now() + AUTOMATIC_STATE_PRUNE_IDLE_RETRY_MS;
+      this.scheduleAutomaticStatePruneTimer(AUTOMATIC_STATE_PRUNE_IDLE_RETRY_MS);
+      this.log(`automatic state prune failed: ${errorMessage(error)}`);
+    }
+  }
+
+  private scheduleAutomaticStatePruneTimer(delayMs: number): void {
+    if (this.stopping || !this.started) return;
+    if (this.automaticStatePruneTimer !== null) clearTimeout(this.automaticStatePruneTimer);
+    this.automaticStatePruneTimer = setTimeout(
+      () => {
+        this.automaticStatePruneTimer = null;
+        this.requestAutomaticStatePrune();
+      },
+      Math.max(1, delayMs),
+    );
+    this.automaticStatePruneTimer.unref?.();
+  }
+
+  private automaticStatePruneCanContinue(): boolean {
+    return (
+      this.started &&
+      !this.stopping &&
+      this.activeRuns.size === 0 &&
+      this.activeResourceManagers.size === 0 &&
+      this.activationTasks.size === 0 &&
+      this.maintenanceCommands.size === 0 &&
+      this.pendingStarts.size === 0 &&
+      this.pendingRunClaims.size === 0 &&
+      this.pendingResumes.size === 0 &&
+      this.controlClaims.size === 0 &&
+      this.pendingTerminalMessageReconciliations.size === 0 &&
+      !this.resourceManagerPollActive &&
+      !this.decisionTimeoutActive &&
+      !this.channelReloading &&
+      [...this.activeChannels.values()].every((channel) => channel.inFlight.size === 0)
+    );
+  }
+
+  private async waitForAutomaticStatePrune(): Promise<void> {
+    this.automaticStatePruneScheduled = false;
+    const task = this.automaticStatePruneTask;
+    if (task !== null) await task;
+  }
+
   private stateStatusReceipt(): JsonValue {
     const count = (sql: string, ...params: unknown[]): number => {
       const row = this.state.connection.prepare(sql).get(...params) as
@@ -3139,6 +3282,7 @@ export class WorkflowServer {
     } finally {
       clearInterval(renewTimer);
       this.activeResourceManagers.delete(key);
+      this.requestAutomaticStatePrune();
       if (!this.stopping) setImmediate(() => void this.claimResourceManagerOne());
     }
   }
@@ -3798,6 +3942,7 @@ export class WorkflowServer {
     } finally {
       this.reapRunnerDescendants(envelope.runnerEpoch);
       this.activeRuns.delete(runId);
+      this.requestAutomaticStatePrune();
     }
   }
 
@@ -4434,6 +4579,10 @@ export class WorkflowServer {
            AND generation = ?`,
       )
       .run(context.runId, active.generation);
+    this.queue.settleRunEffect(
+      context.runId,
+      context.state.status === "waiting" ? "run.park_queue" : "run.settle_queue",
+    );
   }
 
   private ensureTerminalWorkflowMessage(