v5.0 Maintenance Center
The Maintenance Center is the operator surface for local-first upkeep. It lives
in Settings -> Maintenance and is backed by /api/v1/maintenance.
What It Shows
- Health checks for storage, disk space, logs, work products, agent runner
registry state, recent run success, and lifecycle policy loading.
- Storage usage for task files, attachments, telemetry/traces, workflow runs,
worktrees, logs, debug bundles, and work products.
- Cleanup previews that separate active work, archived/restorable work, and
safe-to-review generated data.
- Redacted log tails from allowlisted sources only.
- Redacted debug bundles with a manifest of included and excluded categories.
- CLI runtime snapshots through
vk snapshot, with JSON or Markdown output
safe to paste into support handoffs by default.
- SQLite export/import actions that report bundle path, database path, table
counts, warnings, and failure messages.
- Redacted authoritative SQLite filesystem type/posture, detection and decision
source, effective journal mode, override source, and last one-time integrity
check when SQLite storage is active.
- SQLite journal previews and restart-time conversion status, including
sidecars, ownership, backup class, risks, degraded single-host policy, expiry,
revocation, rollback, and recovery-required state without raw paths.
- Admin-only skill security scans through
/api/v1/maintenance/skill-security/scan, with redacted JSON and Markdown
reports persisted for audit review.
Safety Rules
- Cleanup is preview-only until a dedicated delete handler exists for the
affected data class.
- Destructive cleanup must require explicit confirmation and must never delete
active task worktrees or current run state silently.
- Debug bundles include redacted log tails, health metadata, storage summaries,
lifecycle policy metadata, work-product preview metadata, and a bounded
phase-authority.json diagnostic export. Phase diagnostics retain identities,
source kinds, scope counts, transition expansions, and completion bindings
while omitting exact scopes, paths, credential references, and full digests.
- Maintenance summaries and log-tail responses redact local log paths before
returning data to the UI.
- SQLite posture diagnostics omit the database path, mount point, and mount
source. Known-unsafe or unknown filesystems refuse startup before Maintenance
becomes reachable.
- Journal conversion never runs inside a normal API request. An authenticated
admin schedules an exact, short-lived preview; the bootstrap executes it
before any SQLite consumer opens. A verified backup and fsynced external stage
journal remain available after failures.
DELETE compatibility mode is explicitly degraded and single-host. It
requires VERITAS_SQLITE_TOPOLOGY=single-host, a stable
VERITAS_SQLITE_HOST_ID, an expiring/revocable signed policy, and a
process/host ownership lock. Clustered or known-unsafe storage is rejected.- Schedule a return to supported-local WAL mode before a compatibility policy
expires. Expired or revoked policy fails readiness immediately and refuses
the next database open; it never silently widens or renews authority.
- Debug bundles exclude raw tokens, token hashes, cookies, private keys, raw
prompts, raw chat content, and generated sensitive text.
- Local home, project, storage, runtime, and log paths are redacted in bundle
files by default.
Verification
Focused regression coverage:
pnpm --filter @veritas-kanban/server test -- maintenance-service.test.ts
pnpm --filter @veritas-kanban/server exec vitest run src/__tests__/sqlite-journal-maintenance-service.test.ts src/__tests__/sqlite-journal-ownership-policy.test.ts
pnpm --filter @veritas-kanban/server test -- skill-security-service.test.ts
pnpm --filter @veritas-kanban/web test -- settings-maintenance-mantine.test.tsx