@adhdev/daemon-core 1.0.18-rc.5 → 1.0.18-rc.7

package/src/mesh/mesh-disk-retention.ts

@@ -0,0 +1,370 @@
+// ---------------------------------------------------------------------------
+// mesh-disk-retention — periodic disk / worktree retention for ~/.adhdev
+// ---------------------------------------------------------------------------
+// Legacy on-disk artifacts under ~/.adhdev accumulated with NO lifetime/GC and
+// grew the data volume until a refine bootstrap failed at 98% disk (mission
+// 86def38d). Immediate reclaim was manual; this module implements the code-level
+// RETENTION so it does not recur.
+//
+// What it prunes (all thresholds defensive — never touches a live/in-use file):
+//   1. JSONL ledger files      ~/.adhdev/mesh-ledger/*.jsonl  older than 30 days
+//      (legacy after the SQLite ledger; zero lifetime before this).
+//   2. session-host runtimes   ~/.adhdev/session-host/*/runtimes/*.json for
+//      TERMINATED (dead) runtimes older than 14 days (live runtimes never touched).
+//   3. DB backups              ~/.adhdev/mesh-ledger/mesh-runtime.db.bak-* older
+//      than 7 days.
+// Plus DETECTION-ONLY orphan-worktree signalling (see mesh-reconcile-loop.ts):
+//   4. a worktree present on disk with no matching live mesh node is reported as a
+//      cleanup_candidate ledger entry — NEVER auto-deleted (that stays manual /
+//      coordinator-driven).
+//
+// The functions are split into PURE core selectors (age/orphan decisions, taking
+// explicit paths + a `now` timestamp so they are deterministic and require no fs
+// mocking in tests) and thin runtime wrappers that resolve the real ~/.adhdev
+// paths and perform the unlink. The pure selectors are the unit-tested surface.
+// ---------------------------------------------------------------------------
+
+import {
+    existsSync,
+    readdirSync,
+    statSync,
+    unlinkSync,
+    readFileSync,
+} from 'fs';
+import { join } from 'path';
+import { getConfigDir } from '../config/config.js';
+import { getLedgerDir, appendLedgerEntry, readLedgerEntries } from './mesh-ledger.js';
+import { isSessionHostLiveRuntime } from '../session-host/runtime-surface.js';
+import type { SessionHostSurfaceRecordLike } from '../session-host/runtime-surface.js';
+import { listWorktrees } from '../git/git-worktree.js';
+import type { LocalMeshEntry } from '../repo-mesh-types.js';
+import { LOG } from '../logging/logger.js';
+
+// ─── Thresholds (all defensive) ────────────────────────────────────────────
+export const DAY_MS = 24 * 60 * 60 * 1000;
+/** JSONL ledger files are legacy after the SQLite ledger — 30-day lifetime. */
+export const LEDGER_JSONL_MAX_AGE_MS = 30 * DAY_MS;
+/** Terminated session-host runtimes: conservative 14-day retention. */
+export const SESSION_HOST_RUNTIME_MAX_AGE_MS = 14 * DAY_MS;
+/** mesh-runtime.db.bak-* backups: 7-day retention. */
+export const DB_BAK_MAX_AGE_MS = 7 * DAY_MS;
+
+// ─── (1) JSONL ledger retention ─────────────────────────────────────────────
+
+/** A file candidate for age-based pruning: absolute path + last-modified epoch ms. */
+export interface AgedFile {
+    path: string;
+    mtimeMs: number;
+}
+
+/**
+ * PURE. Select the JSONL ledger files whose mtime is older than `maxAgeMs`
+ * relative to `now`. A file exactly at the threshold is KEPT (strict `>`), so a
+ * 30-day-old file survives its 30th day and is pruned on the 31st. Deterministic:
+ * no fs access, no clock read.
+ */
+export function selectExpiredLedgerJsonl(
+    files: AgedFile[],
+    now: number,
+    maxAgeMs: number = LEDGER_JSONL_MAX_AGE_MS,
+): AgedFile[] {
+    return files.filter(f => now - f.mtimeMs > maxAgeMs);
+}
+
+// ─── (2) session-host runtime retention ─────────────────────────────────────
+
+/** A parsed session-host runtime file: its path, mtime, and the wrapped record. */
+export interface SessionHostRuntimeFile {
+    path: string;
+    mtimeMs: number;
+    /** The `record` object from the on-disk `{ record, snapshot, updatedAt }` file. */
+    record: SessionHostSurfaceRecordLike | null;
+}
+
+/**
+ * PURE. Select the session-host runtime files safe to delete: ONLY those whose
+ * runtime is terminated/dead (NOT a live runtime — decided by the session-host-core
+ * SSOT `isSessionHostLiveRuntime`) AND older than `maxAgeMs`. A live runtime, or a
+ * dead-but-recent one, is always kept. A file whose record failed to parse is treated
+ * as NON-live but is still age-gated, so a corrupt-but-fresh file is never removed.
+ */
+export function selectExpiredSessionHostRuntimes(
+    files: SessionHostRuntimeFile[],
+    now: number,
+    maxAgeMs: number = SESSION_HOST_RUNTIME_MAX_AGE_MS,
+): SessionHostRuntimeFile[] {
+    return files.filter(f => {
+        // Never delete a live runtime, regardless of age.
+        if (isSessionHostLiveRuntime(f.record ?? undefined)) return false;
+        // Terminated/dead: age-gate it.
+        return now - f.mtimeMs > maxAgeMs;
+    });
+}
+
+// ─── (3) DB backup retention ────────────────────────────────────────────────
+
+/** True for a `mesh-runtime.db.bak-*` backup filename (basename only). */
+export function isDbBackupFileName(name: string): boolean {
+    return /^mesh-runtime\.db\.bak-/.test(name);
+}
+
+/** PURE. Select `.bak-*` backups older than `maxAgeMs`. Strict `>` (see ledger). */
+export function selectExpiredDbBackups(
+    files: AgedFile[],
+    now: number,
+    maxAgeMs: number = DB_BAK_MAX_AGE_MS,
+): AgedFile[] {
+    return files.filter(f => now - f.mtimeMs > maxAgeMs);
+}
+
+// ─── (4) orphan worktree detection (detection-only) ─────────────────────────
+
+/** Minimal shape needed to decide whether a worktree path is orphaned. */
+export interface WorktreePathLike {
+    path: string;
+    bare?: boolean;
+}
+
+/** A live mesh node's known workspace paths (self workspace + repoRoot, normalized). */
+export interface LiveNodeWorkspaceLike {
+    workspace?: string;
+    repoRoot?: string;
+}
+
+function normalizePath(p: string): string {
+    // Trim a single trailing separator so "/a/b/" and "/a/b" compare equal.
+    // Case-preserving (git worktree list + meshes.json are both raw paths from the
+    // same daemon, so a case-fold would be over-eager on case-sensitive FS).
+    return p.replace(/[/\\]+$/, '');
+}
+
+/**
+ * PURE. Given the worktrees git reports on disk and the set of live-node workspace
+ * paths, return the worktrees that have NO matching live node — the orphan
+ * cleanup_candidates.
+ *
+ * SAFETY:
+ *  - `mainWorktreePath` (the primary repo checkout, i.e. worktree[0]) is NEVER an
+ *    orphan — it is the base repo, not a mesh clone.
+ *  - `bare` worktrees are skipped (git's internal bookkeeping, not a node checkout).
+ *  - Matching is path-equality after trailing-separator normalization against the
+ *    union of every live node's `workspace` and `repoRoot`.
+ * This is DETECTION ONLY — the caller signals a cleanup_candidate; it must not delete.
+ */
+export function detectOrphanWorktrees(
+    worktrees: WorktreePathLike[],
+    liveNodes: LiveNodeWorkspaceLike[],
+    mainWorktreePath: string,
+): WorktreePathLike[] {
+    const liveePaths = new Set<string>();
+    for (const n of liveNodes) {
+        if (n.workspace) liveePaths.add(normalizePath(n.workspace));
+        if (n.repoRoot) liveePaths.add(normalizePath(n.repoRoot));
+    }
+    const mainNorm = normalizePath(mainWorktreePath);
+    return worktrees.filter(wt => {
+        if (wt.bare) return false;
+        const norm = normalizePath(wt.path);
+        if (norm === mainNorm) return false; // base repo checkout — never an orphan
+        return !liveePaths.has(norm);
+    });
+}
+
+// ─── Runtime wrappers (resolve real paths + perform the unlink) ──────────────
+// These are the side-effecting callers used by the reconcile loop. They are thin:
+// gather → delegate to a PURE selector → unlink. Kept out of the unit tests (which
+// target the deterministic selectors); their I/O is exercised by the daemon at runtime.
+
+function safeUnlink(path: string): boolean {
+    try {
+        unlinkSync(path);
+        return true;
+    } catch (e: any) {
+        LOG.warn('DiskRetention', `Failed to delete ${path}: ${e?.message || e}`);
+        return false;
+    }
+}
+
+function listDirFiles(dir: string): AgedFile[] {
+    if (!existsSync(dir)) return [];
+    const out: AgedFile[] = [];
+    let names: string[];
+    try {
+        names = readdirSync(dir);
+    } catch {
+        return [];
+    }
+    for (const name of names) {
+        const path = join(dir, name);
+        try {
+            const st = statSync(path);
+            if (st.isFile()) out.push({ path, mtimeMs: st.mtimeMs });
+        } catch {
+            // vanished between readdir and stat — skip
+        }
+    }
+    return out;
+}
+
+/**
+ * Prune expired legacy JSONL ledger files under ~/.adhdev/mesh-ledger/.
+ * Matches only `*.jsonl` (never the SQLite .db / -wal / -shm files). Returns the
+ * count deleted. Best-effort: individual unlink failures are logged, not thrown.
+ */
+export function pruneExpiredLedgerJsonl(now: number = Date.now()): number {
+    const dir = getLedgerDir();
+    const jsonl = listDirFiles(dir).filter(f => f.path.endsWith('.jsonl'));
+    const expired = selectExpiredLedgerJsonl(jsonl, now);
+    let deleted = 0;
+    for (const f of expired) if (safeUnlink(f.path)) deleted++;
+    if (deleted > 0) LOG.info('DiskRetention', `Pruned ${deleted} JSONL ledger file(s) older than 30d`);
+    return deleted;
+}
+
+/**
+ * Prune expired `mesh-runtime.db.bak-*` backups under ~/.adhdev/mesh-ledger/.
+ * Never touches the live DB (only names matching the .bak- prefix). Returns count.
+ */
+export function pruneExpiredDbBackups(now: number = Date.now()): number {
+    const dir = getLedgerDir();
+    const baks = listDirFiles(dir).filter(f => isDbBackupFileName(f.path.split(/[/\\]/).pop() || ''));
+    const expired = selectExpiredDbBackups(baks, now);
+    let deleted = 0;
+    for (const f of expired) if (safeUnlink(f.path)) deleted++;
+    if (deleted > 0) LOG.info('DiskRetention', `Pruned ${deleted} mesh-runtime.db.bak-* backup(s) older than 7d`);
+    return deleted;
+}
+
+/**
+ * Prune terminated session-host runtime files older than 14 days across every
+ * ~/.adhdev/session-host/<app>/runtimes/ directory. A LIVE runtime is never deleted
+ * regardless of age (isSessionHostLiveRuntime SSOT). Returns count deleted.
+ */
+export function pruneExpiredSessionHostRuntimes(now: number = Date.now()): number {
+    const root = join(getConfigDir(), 'session-host');
+    if (!existsSync(root)) return 0;
+    let apps: string[];
+    try {
+        apps = readdirSync(root);
+    } catch {
+        return 0;
+    }
+    const candidates: SessionHostRuntimeFile[] = [];
+    for (const app of apps) {
+        const runtimesDir = join(root, app, 'runtimes');
+        if (!existsSync(runtimesDir)) continue;
+        for (const f of listDirFiles(runtimesDir)) {
+            if (!f.path.endsWith('.json')) continue;
+            let record: SessionHostRuntimeFile['record'] = null;
+            try {
+                const parsed = JSON.parse(readFileSync(f.path, 'utf-8'));
+                const rec = parsed && typeof parsed === 'object' ? parsed.record : null;
+                record = rec && typeof rec === 'object' ? (rec as SessionHostSurfaceRecordLike) : null;
+            } catch {
+                // Unparseable → treat as non-live; still age-gated by the selector,
+                // so a corrupt-but-fresh file is preserved.
+                record = null;
+            }
+            candidates.push({ path: f.path, mtimeMs: f.mtimeMs, record });
+        }
+    }
+    const expired = selectExpiredSessionHostRuntimes(candidates, now);
+    let deleted = 0;
+    for (const f of expired) if (safeUnlink(f.path)) deleted++;
+    if (deleted > 0) LOG.info('DiskRetention', `Pruned ${deleted} terminated session-host runtime file(s) older than 14d`);
+    return deleted;
+}
+
+/**
+ * Run the file-deleting retention passes (JSONL ledger, DB backups, session-host
+ * runtimes) once. Each pass is isolated so one failing pass never blocks the others.
+ * Orphan-worktree DETECTION is driven separately in the reconcile loop (it needs the
+ * live mesh config + git worktree list and emits a ledger signal rather than deleting).
+ */
+export function runDiskRetentionSweep(now: number = Date.now()): { ledgerJsonl: number; dbBackups: number; sessionHostRuntimes: number } {
+    let ledgerJsonl = 0;
+    let dbBackups = 0;
+    let sessionHostRuntimes = 0;
+    try { ledgerJsonl = pruneExpiredLedgerJsonl(now); } catch (e: any) { LOG.warn('DiskRetention', `Ledger JSONL prune failed: ${e?.message || e}`); }
+    try { dbBackups = pruneExpiredDbBackups(now); } catch (e: any) { LOG.warn('DiskRetention', `DB backup prune failed: ${e?.message || e}`); }
+    try { sessionHostRuntimes = pruneExpiredSessionHostRuntimes(now); } catch (e: any) { LOG.warn('DiskRetention', `Session-host runtime prune failed: ${e?.message || e}`); }
+    return { ledgerJsonl, dbBackups, sessionHostRuntimes };
+}
+
+// ─── Orphan worktree detection (detection-only, emits cleanup_candidate) ──────
+
+/** How many recent worktree_cleanup_candidate entries to scan for the re-emit guard. */
+const ORPHAN_DEDUPE_WINDOW = 200;
+
+/**
+ * Detect orphaned worktrees for ONE mesh and emit a `worktree_cleanup_candidate`
+ * ledger signal for each — DETECTION ONLY, never deletes. An orphan is a git worktree
+ * on disk with no matching live mesh node (compared by path). It:
+ *   1. picks a base (non-worktree) node owned by this mesh to anchor `git worktree list`;
+ *   2. diffs the reported worktrees against the union of every node's workspace/repoRoot;
+ *   3. skips the main worktree + bare entries (detectOrphanWorktrees safety);
+ *   4. suppresses a repeat for a worktreePath already signalled within the recent window
+ *      (idempotent re-emit guard), so the hourly sweep doesn't spam the ledger.
+ * Returns the list of newly-signalled orphan paths. Best-effort: git/ledger failures are
+ * logged and yield an empty result, never thrown.
+ */
+export async function detectAndSignalOrphanWorktrees(
+    mesh: LocalMeshEntry,
+    now: number = Date.now(),
+): Promise<string[]> {
+    const nodes = Array.isArray(mesh.nodes) ? mesh.nodes : [];
+    // Anchor: a base (non-worktree) node's repoRoot (preferred) or workspace. The base
+    // node is the primary checkout; its git dir enumerates every worktree of the repo.
+    const baseNode = nodes.find(n => !n.isLocalWorktree && (n.repoRoot || n.workspace));
+    const repoRoot = baseNode?.repoRoot || baseNode?.workspace;
+    if (!repoRoot) return []; // no local base checkout for this mesh on this daemon
+
+    let worktrees: WorktreePathLike[];
+    try {
+        worktrees = await listWorktrees(repoRoot);
+    } catch (e: any) {
+        LOG.warn('DiskRetention', `git worktree list failed for mesh ${mesh.id} (${repoRoot}): ${e?.message || e}`);
+        return [];
+    }
+    // git worktree list emits the main worktree first; treat it as the base repo.
+    const mainWorktreePath = worktrees[0]?.path || repoRoot;
+    const liveNodes: LiveNodeWorkspaceLike[] = nodes.map(n => ({ workspace: n.workspace, repoRoot: n.repoRoot }));
+    const orphans = detectOrphanWorktrees(worktrees, liveNodes, mainWorktreePath);
+    if (orphans.length === 0) return [];
+
+    // Re-emit guard: skip a worktreePath already signalled in the recent window so the
+    // hourly sweep is idempotent and does not flood the ledger with duplicates.
+    let recentPaths = new Set<string>();
+    try {
+        const recent = readLedgerEntries(mesh.id, { kind: ['worktree_cleanup_candidate'], tail: ORPHAN_DEDUPE_WINDOW });
+        for (const e of recent) {
+            const p = typeof e.payload?.worktreePath === 'string' ? e.payload.worktreePath : '';
+            if (p) recentPaths.add(p);
+        }
+    } catch {
+        recentPaths = new Set();
+    }
+
+    const signalled: string[] = [];
+    for (const wt of orphans) {
+        if (recentPaths.has(wt.path)) continue;
+        try {
+            appendLedgerEntry(mesh.id, {
+                kind: 'worktree_cleanup_candidate',
+                payload: {
+                    worktreePath: wt.path,
+                    reason: 'no_matching_live_node',
+                    state: 'cleanup_candidate',
+                    detectedAt: new Date(now).toISOString(),
+                },
+            });
+            signalled.push(wt.path);
+        } catch (e: any) {
+            LOG.warn('DiskRetention', `Failed to record orphan worktree signal for ${wt.path}: ${e?.message || e}`);
+        }
+    }
+    if (signalled.length > 0) {
+        LOG.info('DiskRetention', `Detected ${signalled.length} orphan worktree(s) for mesh ${mesh.id} (cleanup_candidate — NOT deleted): ${signalled.join(', ')}`);
+    }
+    return signalled;
+}

package/src/mesh/mesh-ledger.ts

@@ -88,6 +88,14 @@ export type MeshLedgerKind =
     // payload: { keys: string[], hasDestructive: boolean, result: 'injected'|'refused'|'error',
     //            refused?: string, submits?: boolean, confirmDestructive?: boolean }
     | 'key_injection'
+    // Disk/worktree retention (mission 86def38d): DETECTION-ONLY signal that a git
+    // worktree present on disk has no matching live mesh node — an orphan cleanup
+    // candidate. The reconcile loop emits this so the coordinator can decide whether
+    // to remove it; retention NEVER auto-deletes a worktree (manual/coordinator-driven).
+    // Keyed by worktreePath so a re-emit for the same orphan is idempotent (a prior
+    // unresolved entry within the dedupe window suppresses the repeat).
+    // payload: { worktreePath, branch?, head?, reason: 'no_matching_live_node', state: 'cleanup_candidate' }
+    | 'worktree_cleanup_candidate'
     ;
 
 export interface MeshLedgerEntry {
@@ -317,6 +325,70 @@ export const OPERATING_NOTE_DEDUPE_WINDOW = 40;
 // a coordinator actually sees while still capping unbounded store growth.
 export const OPERATING_NOTE_KEEP_LATEST = 100;
 
+// ─── Operating-note lifecycle: category TTL + expiry (read-side only) ──────────
+// Minimal first cut of the operating-notes lifecycle. Expiry is READ/INJECTION
+// side ONLY — the store prune (keep-latest-100 above) stays purely count-based
+// and NEVER deletes by age, so audit history is preserved. isNoteExpired decides
+// whether an UNPINNED note still rides into a coordinator prompt.
+//
+// Per-category retention (days). A category not listed here — including the
+// uncategorized case — is durable (never expires). provider_quirk is durable
+// because a runtime quirk stays true until the provider changes.
+export const OPERATING_NOTE_CATEGORY_TTL_DAYS: Readonly<Record<string, number>> = {
+    recovery_lesson: 14,
+    pattern_to_avoid: 30,
+    // provider_quirk: durable (intentionally absent → never expires)
+};
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Shape isNoteExpired reads. Structural so mesh-ledger stays free of a
+ * coordinator-prompt import (CoordinatorOperatingNote satisfies this).
+ */
+export interface OperatingNoteExpiryInput {
+    category?: string;
+    pinned?: boolean;
+    createdAt?: string;
+    /** Explicit expiry override; wins over the category TTL when parseable. */
+    expiresAt?: string;
+    /** Fallback creation time (ledger entry timestamp) when createdAt absent. */
+    timestamp?: string;
+}
+
+/**
+ * Pure helper: is this UNPINNED operating note expired as of `now` (epoch ms)?
+ *
+ * Rules:
+ *  - pinned notes NEVER expire (always false).
+ *  - an explicit, parseable `expiresAt` in the past → expired.
+ *  - otherwise the category TTL applies; a durable category (provider_quirk,
+ *    uncategorized, or any category not in the TTL map) never expires.
+ *  - age is measured from createdAt, falling back to `timestamp` (ledger entry
+ *    time). If neither is a valid date, the note is treated as NOT expired
+ *    (never silently drop a note we cannot age).
+ */
+export function isNoteExpired(note: OperatingNoteExpiryInput, now: number): boolean {
+    if (!note || note.pinned) return false;
+
+    // Explicit expiresAt wins when present and parseable.
+    if (typeof note.expiresAt === 'string') {
+        const exp = new Date(note.expiresAt).getTime();
+        if (!Number.isNaN(exp)) return exp <= now;
+    }
+
+    const ttlDays = note.category ? OPERATING_NOTE_CATEGORY_TTL_DAYS[note.category] : undefined;
+    if (typeof ttlDays !== 'number' || !Number.isFinite(ttlDays)) {
+        // Durable category (provider_quirk / uncategorized / unknown) → never expires.
+        return false;
+    }
+
+    const created = new Date(note.createdAt ?? note.timestamp ?? '').getTime();
+    if (Number.isNaN(created)) return false; // cannot age → keep
+
+    return now - created >= ttlDays * MS_PER_DAY;
+}
+
 // ─── Path Helpers ───────────────────────────────
 
 export function getLedgerDir(): string {

package/src/mesh/mesh-reconcile-loop.ts

@@ -76,6 +76,7 @@ import {
     resolveReconcileIntervalMs,
 } from './mesh-reconcile-config.js';
 import { pullRemoteNodeQueues } from './mesh-remote-event-pull.js';
+import { runDiskRetentionSweep, detectAndSignalOrphanWorktrees } from './mesh-disk-retention.js';
 import {
     reconcileUnterminatedDirectDispatches,
     autoPruneStaleDirectDispatches,
@@ -126,6 +127,16 @@ interface LiveCoordinator {
 // "restart does not clear it" symptom the operator needs visibility into).
 const coordinatorModalParkState = new Map<string, boolean>();
 
+// Disk/worktree retention throttle. The reconcile tick runs every ~4s, but the
+// retention sweep (fs walks + git worktree list) is far too heavy for that cadence
+// and its artifacts age in days, so it runs at most once per hour. `undefined`
+// means "never run yet" → runs on the first tick after daemon start so a long-lived
+// backlog is reclaimed promptly rather than an hour later. Per-process; a restart
+// re-runs it immediately, which is the desired behavior (a restart is exactly when
+// stale artifacts from the previous run should be swept).
+const DISK_RETENTION_INTERVAL_MS = 60 * 60 * 1000; // 1h
+let lastDiskRetentionRunAt: number | undefined;
+
 // Find live CLI coordinator instances on THIS daemon, keyed by mesh.
 function findLiveCoordinators(components: DaemonComponents): LiveCoordinator[] {
     const out: LiveCoordinator[] = [];
@@ -1354,6 +1365,44 @@ export async function runMeshReconcileTick(components: DaemonComponents): Promis
         }
     }
 
+    // ── PHASE 6: disk / worktree retention (hourly, mission 86def38d) ──────────
+    // Legacy on-disk artifacts under ~/.adhdev accumulated with NO lifetime and grew
+    // the data volume until a refine bootstrap failed at 98% disk. This throttled pass
+    // (≤1×/hour — the artifacts age in days and the fs/git walk is too heavy for the 4s
+    // tick) reclaims them:
+    //   • JSONL ledger files older than 30d (legacy after the SQLite ledger)
+    //   • terminated session-host runtime files older than 14d (live never touched)
+    //   • mesh-runtime.db.bak-* backups older than 7d
+    //   • orphan worktree DETECTION → cleanup_candidate ledger signal (NEVER deleted).
+    // Runs BEFORE PHASE 2's early return so it fires whether or not a live CLI
+    // coordinator exists on this daemon. Isolated in try/catch so it can never kill the
+    // tick. All file deletions are defensive (age + live-runtime guards in the pure
+    // selectors); worktree cleanup stays manual/coordinator-driven.
+    {
+        const nowMs = Date.now();
+        const due = lastDiskRetentionRunAt === undefined
+            || (nowMs - lastDiskRetentionRunAt) >= DISK_RETENTION_INTERVAL_MS;
+        if (due) {
+            lastDiskRetentionRunAt = nowMs;
+            try {
+                runDiskRetentionSweep(nowMs);
+            } catch (e: any) {
+                LOG.warn('MeshReconcile', `Disk retention sweep failed: ${e?.message || e}`);
+            }
+            // Orphan-worktree detection is per-mesh (needs the mesh's base repo + node set)
+            // and only for meshes this daemon hosts (its local base checkout is the git anchor).
+            for (const mesh of listMeshes()) {
+                const selfIds = resolveCoordinatorSelfIds(mesh, drainDaemonIds);
+                if (!daemonHostsMesh(mesh, selfIds)) continue;
+                try {
+                    await detectAndSignalOrphanWorktrees(mesh, nowMs);
+                } catch (e: any) {
+                    LOG.warn('MeshReconcile', `Orphan worktree detection failed for mesh ${mesh.id}: ${e?.message || e}`);
+                }
+            }
+        }
+    }
+
     // ── PHASE 2: inject into live CLI coordinators on this daemon ──────────────
     const coordinators = findLiveCoordinators(components);
     if (coordinators.length === 0) {

package/src/mesh/mesh-runtime-store.ts

@@ -174,6 +174,27 @@ export class MeshRuntimeStore {
         this.instance = undefined;
     }
 
+    /**
+     * VACUUM the SQLite database to reclaim on-disk space. Retention prunes rows
+     * with DELETE, which frees pages inside the file but does NOT shrink it — the
+     * mesh-runtime.db grew to hundreds of MB (mission 86def38d disk-accumulation
+     * bootstrap failure) precisely because the file was never compacted. This
+     * rewrites the DB into a minimal footprint. Best-effort: a VACUUM failure (e.g.
+     * insufficient temp space, a read lock) is logged and swallowed so it can never
+     * block daemon shutdown. Called once on shutdown (see daemon-lifecycle), never
+     * on the hot path — VACUUM takes an exclusive lock and rewrites the whole file.
+     */
+    vacuum(): void {
+        try {
+            // Fold the WAL back into the main DB first so VACUUM reclaims those pages too.
+            try { this.db.pragma('wal_checkpoint(TRUNCATE)'); } catch { /* checkpoint best-effort */ }
+            this.db.exec('VACUUM;');
+            LOG.info('MeshRuntimeStore', 'VACUUM completed on shutdown');
+        } catch (err: any) {
+            LOG.warn('MeshRuntimeStore', `VACUUM on shutdown failed (ignored): ${err?.message || err}`);
+        }
+    }
+
     close(): void {
         this.db.close();
     }

package/src/providers/cli-provider-instance-types.ts

@@ -120,6 +120,31 @@ export const NATIVE_HISTORY_MESH_IDLE_SETTLE_MS = 4000;
 // met. Scoped (at the call site) to autonomous mesh sessions, so interactive sessions are
 // untouched.
 export const PTY_PARSED_FINAL_ASSISTANT_QUIET_DWELL_MS = 1200;
+// (ANTIGRAVITY-30S-CAP-PREMATURE) Minimum PTY quiet dwell required before the
+// COMPLETED_FINALIZATION_MAX_WAIT_MS (30s) cap may RELEASE an antigravity `holdForTranscript`
+// block into the forced weak completion. Antigravity is a native-source provider: its
+// idle/generating verdict is PTY-screen-derived, but its assistant answer lands in
+// native-history and can legitimately lag past 30s on a long turn (tool phase + slow reply).
+// The 30s cap releases on ELAPSED TIME, not proof-of-idle — so on a long turn it fired a
+// premature completed/idle to the coordinator while the PTY was still generating (live-repro:
+// a routed RCA task emitted "completed" in 10s with no result). Require instead that the PTY
+// has been quiet (no raw output) for at least this long AND the adapter reports no pending
+// response before the cap may force-emit. A genuinely quiescent tool-only turn (no assistant
+// bubble) has a stable screen well past this bound and still finalizes; a turn whose PTY is
+// still producing output keeps holding past 30s (up to ANTIGRAVITY_HOLD_HARD_CAP_MS). Scoped
+// (at the call site) to antigravity-cli holdForTranscript blocks, so claude-cli/codex-cli
+// completion timing is untouched.
+export const ANTIGRAVITY_HOLD_QUIET_DWELL_MS = 3000;
+// (ANTIGRAVITY-30S-CAP-PREMATURE) Absolute upper bound on how long an antigravity
+// `holdForTranscript` block may be held once the 30s cap is reached but the PTY is still
+// active. The quiet-dwell gate above keeps holding while the PTY keeps emitting output, so a
+// truly runaway turn (PTY never falls quiet) must still eventually release rather than wedge
+// the session in generating forever — strictly worse than the original premature-emit bug.
+// Once a pending completion has been held this long we force-emit regardless of PTY activity.
+// Sized generously (5 min) so realistic long antigravity turns (multi-tool + slow reply)
+// finish and let the transcript land / the PTY fall quiet naturally, while still guaranteeing
+// eventual release. Mirrors BACKGROUND_TASK_HOLD_MAX_MS's escape-hatch rationale.
+export const ANTIGRAVITY_HOLD_HARD_CAP_MS = 5 * 60_000;
 // (FALSE-IDLE-BACKGROUND-CMD) Hard cap on how long a pending completion may be HELD
 // solely because the claude-cli transcript still shows an unresolved run_in_background
 // bash job (backgroundTaskActive). The hold is the correct behaviour while the job is