feat(M023): storage lifecycle, disk reclamation, and orphan cleanup

[hiepau1231]

Summary

M023 makes Muster account for its own disk footprint and actually give bytes back — without deleting a single row of conversation history and without bumping the schema version.

The milestone is ordered so the measurement instrument lands first, and every later byte claim is forced through it. The storage report and the reclamation therefore cannot disagree.

• Measurement first (S01). A storageReport request kind on the SQLite worker protocol returns file/WAL/shm bytes, page and freelist counts, page size, live auto_vacuum mode, and a descending per-table breakdown — plus a four-bucket orphan classifier separating the live SQLite trio from dead legacy stores, active leases, and stale leases. Both tracked ledgers report tableBytesSource: dbstat from a real Extension Host, so dbstat availability under Electron is proven rather than assumed.
• Freed pages actually leave the file (S02). New stores open auto_vacuum = INCREMENTAL with journal_size_limit = 16777216; reclamation runs in bounded page batches with checked WAL checkpoints. Legacy NONE stores need roughly twice the file size in free space, so an fs.statfsSync precheck refuses up front reporting required vs available bytes instead of dying mid-VACUUM. A legacy fixture reopens unmutated and SQLITE_SCHEMA_VERSION stays 2.
• Recurring retention that keeps history (S03). The single activation-time retention call becomes a recurring scheduler on the existing single-flight guard. Heavy tool_calls.payload_json diff text is stripped on aged turns while path and change summaries survive behind an explicit retentionTruncated flag, so the webview can distinguish truncation from an empty change set.
• R044 repaired structurally. The terminal-task DELETE FROM turns / DELETE FROM messages path was removed, not gated behind a flag, so retention cannot be reconfigured into deleting history.
• Orphan cleanup and uninstall (S04, S06). Classification now precedes the confirmation prompt, an empty removable set never prompts, and removal is pinned to the exact snapshot the prompt rendered — prompt/mutation divergence is impossible by construction rather than by assertion. The vscode:uninstall hook is profile-aware: activation registers the actual context.globalStorageUri; uninstall reclaims only an exact registered extension-id path (or the explicit test override), never guesses Stable/Insiders/portable locations. Concurrent Extension Hosts tolerate Windows registry-write contention without blocking activation.
• One liveness predicate (S09). Terminal workflow metadata reclamation and payload retention could each weaken the other's guarantee, so the predicate is extracted to exactly one definition consumed by both the schema trigger and the reclamation command, with a pinned normalized trigger fingerprint proving the extraction is token-preserving.

Composition detail worth knowing: truncation alone only moves bytes to the freelist. The byte tests assert on-disk shrink only after the reclaim call, so S03 cannot report savings that never materialise.

Observed in one continuous packaged two-window run: fileBytes 6,811,648 → 1,507,328 with freelistCount: 0; tool_calls bytes 6,127,616 → 819,200 while durable counts stay identical at tasks 8 / turns 12 / messages 14. Uninstall emits reclaimed_bytes: 2448 / absent / refused, exit 0 each, no paths in stdout.

52 commits, 78 files changed. No .gsd/ planning artifacts in the diff.

Merge resolution — please read, it touches the M022 security boundary

This branch was cut from 168b39c (the M021 merge), before M022 landed the UAT surface tiering, so main was 35 commits ahead and the conflict fell directly on the boundary M022 introduced.

M022 redefined isUatModeEnabled as resolveUatSurface(...) !== 'none', which now returns true for a Production VSIX with MUSTER_UAT_MODE=1 — that is the redacted packaging tier the real-install gate needs. M023 had gated its store-mutating harness commands on that same boolean. Taking either side verbatim would have reopened exactly the marketplace exposure M022 closed in its review round 2.

Conflict	Resolution
registerLiveUatCommands signature — M022 added tier, M023 added storage args	Kept both: (context, uatSurface, storageDirectory, reclaimOrphanedFilesForUat). All six M023 command ids register after the tier !== 'full' early return, so a packaging host cannot reach them
M023's two non-command affordances were gated on liveUatEnabled, which is now true at the packaging tier	Introduced fullUatSurface (uatSurface === 'full'). The path-bearing DOM render probe (D079) and the retention-interval override are both keyed off it, keeping them Development-only
uat-commands.test.ts	Both sides only appended tests — kept both
uat-surface-tier.invariant.test.ts requires every declared command to be bucketed deliberately	Classified the six M023 ids as mutable/stateful, and added a case asserting the probe and retention override stay behind the stronger full check
sqlite-only-activation.test.ts pinned the old call signature	Updated the regex to the merged four-argument form

liveUatEnabled deliberately stays uatSurface !== 'none' — narrowing it to full would have broken M022's packaging gate, which needs bridgeHealth / runDeactivate from a Production install.

Verification

CI is green on 1ec4b47 (run 30683259259) — all six jobs pass: compile, Packaging gate (Extension Host), Packaging install gate (real install), and SQLite Extension Host on 1.100.0 / 1.101.0 / stable.

Local gates, run against the merge commit:

Gate	Result
npx tsc -p . --noEmit	exit 0
npm test -- --run	201 files / 2598 passed / 4 skipped
npm run compile	exit 0
npm run check:svelte	0 errors, 0 warnings
npm run test:webview	82 passed
npm run test:m023-evidence-gate	pass (six static verifiers, one CI invocation)
test:source-boundary, test:source-boundary:fixtures, test:evidence	pass
test:settings-docs, test:settings-live-evidence	pass
test:m022-s02 … test:m022-s05	pass — M022's gates still hold post-merge

The current 2598/201 figure includes the post-review storage lifecycle coverage; no test was dropped or newly skipped. The later flake fix touches only an e2e/ spec, which is outside vitest's include.

Post-review live UAT rerun (2026-08-02): all packaged Electron runners were re-executed after the storage fixes: test:m023-s05-storage-lifecycle-live-uat passed scenarios A–I; test:m023-s07-truncated-render-live-uat passed; and the S08 orphan ledger was emitted by the same two-window lifecycle run. The three tracked ledgers are schema-validated, ok: true, and pin their commitSha to 03e6e84fad4faf44d2874214efa5fb3e51ed6151, the exact source candidate packaged for those runs. npm run test:m023-evidence-gate passes.

The one CI failure, and why the fix is a test fix

The first CI run on the merge commit failed on exactly one test — M020 S03 collapse — where expect(expandedBox!.height).toBeGreaterThan(1) received 0. Every assertion around it passed: aria-expanded was true, data-collapsed was false, and the added diff line was visible. That combination rules out a rendering regression and points at timing.

The panel expands through a grid-template-rows: 0fr → 1fr transition. Playwright's attribute and visibility assertions auto-retry, so they settle the moment the class flips — but boundingBox() is a single sample with no retry, so it can be taken while the row is still animating. A loaded Linux runner is simply likelier to land inside that window than a local machine.

Established by controlled experiment rather than inference:

• Temporarily raising the transition to 5s reproduced the failure locally at height 0.046875 — mid-animation.
• The polled assertion passed with the transition still at 1s, five times slower than production.
• Production CSS is unchanged at 0.2s; only the assertion changed.
• Negative control: with the threshold temporarily set to 999999 the test fails and reports the real settled height of 21.33px, so the assertion still has teeth rather than passing vacuously.

Backend / area

• Claude adapter
• Grok adapter
• Kiro adapter
• Codex adapter
• OpenCode adapter
• agy adapter
• Muster Bridge (MCP ask_user)
• Webview / extension host
• Docs only
• Other: SQLite storage lifecycle, retention scheduler, uninstall hook

Checklist

• npm run compile passes locally
• Tested in Extension Development Host (F5) — packaged two-window live runs per slice; see the caveat above about post-merge re-execution
• Updated relevant doc under docs/ (docs/SQLITE-STORAGE.md, plus three tracked evidence ledgers and the requirement-evidence map)

Known limitations and follow-ups

Blocking before the first published release (pre-existing, not introduced here)

• R035 — migration framework. Per K001, storage is clean-break reset-only at SQLITE_SCHEMA_VERSION = 2; connection.ts rejects every other user_version. Free today at v0.1.0 with no published users, but after the first release any schema bump silently erases task and chat history. M023 shipped zero schema change and did not worsen this.

Verifier hardening

• scripts/verify-m023-requirement-evidence.test.mjs pins requiredMappings to R040–R045 — its own test name reads maps R040 through R045. That is precisely why R046 sat active for days after shipping in S04: no gate ever observed it. Extending the range would close the blind spot.
• The narrative figures in docs/plans/m023-requirement-evidence.md are not gated, so quoted ordinals can drift from a regenerated ledger without failing CI.
• Pre-existing, unrelated to this PR: npm run test:file-drop-docs fails on docs/WEBVIEW.md missing contract marker: ## 12. Workspace file-drop mentions. It fails identically with this branch stashed, none of the files it checks differ from origin/main, and it is not wired into ci.yml — which is why it has gone unnoticed. Worth either fixing or wiring in, but out of scope here.

Needs a human at a real host (5 items, none touching data safety)

Command Palette read-throughs for the S01 storage report and S02 compaction output; a genuine partial-removal failure (chmod 0444 does not prevent unlink on Windows — use an exclusive lock or icacls deny-delete); visual confirmation of the native modal copy for S06/S08; and the real marketplace uninstall flow, which is unexercised by design since VS Code itself invokes the hook.

Cosmetic

• S04 renders removed: .muster-tasks.json (54 bytes) rather than the UAT spec's literal removed: <basename> bytes: <n>. Content matches intent; either the line or the spec should be aligned.