state:cleanup

← Back to CLI Commands

state:cleanup

Clean up stale state data

pnpm state:cleanup

From --help:

Event cleanup checks the tracked WU ledger at 3.5 MiB, below its unchanged 4 MiB shape budget. It archives redundant history of completed WUs whose completion stamps exist. Active and unknown history, lifecycle transitions, pending edits and audit evidence remain protected.

Automatic post-Done cleanup publishes the compact ledger and its exact generated archive segments together. Manual cleanup reports the segment paths to publish with the changed ledger in the owning WU. Preview with --events-only --dry-run. The separate --compact-ledger option moves telemetry payloads to local journals.

The pressure threshold triggers maintenance. Protected rows can keep the ledger above it, and the unchanged shape check can still fail. Preserve and repair any named archive with conflicting bytes or an invalid digest before retrying.

Options:

Flag	Description	Required
--dry-run	Preview cleanup without making changes	No
--signals-only	Only execute signal cleanup	No
--memory-only	Only execute memory cleanup	No
--events-only	Only execute event archival, including state-preserving pressure compaction at 3.5 MiB	No
--compact-ledger	Move gate_attempt, lifecycle_duration, heartbeat and free-text checkpoint payloads out of the tracked wu-events.jsonl into the untracked journals, leaving a compact checkpoint stub per moved checkpoint; combine with —dry-run to preview	No
--claim-markers	Remove the leftover claim marker (refs/lumenflow/claims/<WU>) of every WU that origin main records as done and whose lane branch is gone; an in-progress claim is never touched, and each delete is leased on the marker sha observed. Combine with —dry-run to preview	No
--scratch	Delete engine-owned scratch (directories carrying the engine name prefix AND owner marker) older than the age threshold from the OS temp dir and the LumenFlow tmp dir, plus the leftovers of a crashed run from the per-user socket scratch root (/tmp/lumenflow-sockets-<uid>) with no age wait: only 0700 entries owned by this user whose owning process has ended, and only after that root passes the same ownership and sticky-parent verification used to create it; prune the git worktree registration of any removed checkout. Sessions, worktrees, lifecycle roots, operator and unmarked directories are never touched. Combine with —dry-run to preview	No
--scratch-max-age-days &lt;days&gt;	Age threshold in days for —scratch (default: software_delivery.cleanup.tmp_scratch_max_age_days, 7)	No
--json	Output as JSON	No
-q, --quiet	Suppress output except errors and summary	No
-b, --base-dir &lt;path&gt;	Base directory (defaults to current directory)	No

---

← Back to CLI Commands