@adhdev/daemon-core 1.0.18-rc.6 → 1.0.18-rc.8

package/src/mesh/coordinator-prompt.ts

@@ -34,6 +34,7 @@ import type {
 import { mergeAndNormalizePolicy, resolveProviderMaxParallel } from '../repo-mesh-types.js';
 import { getDifficultyBrains } from '../config/mesh-config.js';
 import { resolveNodeCapabilitySlots } from './mesh-node-slots.js';
+import { isNoteExpired, OPERATING_NOTE_CATEGORY_TTL_DAYS } from './mesh-ledger.js';
 import { MESH_TASK_DIFFICULTIES } from '@adhdev/mesh-shared';
 import type { MagiKindPanelMap, MagiSlot, MagiTaskKind } from '@adhdev/mesh-shared';
 
@@ -84,6 +85,41 @@ export interface CoordinatorOperatingNote {
     category?: 'provider_quirk' | 'pattern_to_avoid' | 'recovery_lesson';
     createdAt?: string;
     sourceCoordinator?: string;
+    /**
+     * Operating-notes lifecycle (minimal first cut). When true the note ALWAYS
+     * rides into the coordinator prompt — it is never dropped by TTL expiry and
+     * survives the injection cap ahead of unpinned notes. Legacy notes without
+     * this field default to false.
+     */
+    pinned?: boolean;
+    /**
+     * Optional explicit expiry ISO timestamp. When set and in the past, an
+     * UNPINNED note is dropped from the injected prompt (read-side only — the
+     * ledger entry is never pruned by age). When absent, the category→TTL map
+     * (see isNoteExpired) governs expiry; pinned notes never expire regardless.
+     */
+    expiresAt?: string;
+    /**
+     * Phase 2 — the ledger id of this note, when known. Threaded from the ledger
+     * entry id at launch so version-supersede can target a specific note and
+     * same-class folding can list the subsumed ids. Repo-declared notes may lack
+     * one; absent is fine (folding/supersede fall back to the subject key).
+     */
+    noteId?: string;
+    /**
+     * Phase 2 (b) version-supersede — an optional note-id or stable subject-key
+     * this note replaces. At injection, any earlier LIVE note whose `noteId` or
+     * `subjectKey` matches this value is hidden from the prompt (the ledger entry
+     * is retained for audit). Optional and lossless: absent = supersedes nothing.
+     */
+    supersedes?: string;
+    /**
+     * Phase 2 (b)/(c) — an optional stable subject-key grouping notes about the
+     * same subject. Drives version-supersede targeting and same-class folding.
+     * When absent, folding derives a key from a leading `[tag]` bracket instead,
+     * so legacy notes still collapse by their conventional tag prefix.
+     */
+    subjectKey?: string;
 }
 
 // ─── Prompt Builder ─────────────────────────────
@@ -582,33 +618,243 @@ function buildRecentActivitySection(activity?: CoordinatorRecentActivity): strin
 const OPERATING_NOTES_PROMPT_CAP = 20;
 const OPERATING_NOTE_MAX_CHARS = 300;
 
-function buildOperatingNotesSection(notes?: CoordinatorOperatingNote[]): string {
+/**
+ * Phase 2 (d) — byte budget for the injected Operating Notes list. The count cap
+ * above (20) is still a ceiling, but selection now fills up to this UTF-8 byte
+ * budget on the RENDERED note lines, ranked pinned > durable > recency, so a few
+ * long notes don't crowd out many short ones and vice-versa. Pinned notes are
+ * ALWAYS kept even if they alone exceed the budget (pinned is author-opt-in and
+ * bounded by the author); the budget only bounds the unpinned tail.
+ *
+ * ~6KB ≈ the 20-note cap at typical note length, so on ordinary meshes this
+ * changes nothing — it only kicks in when notes run long. It sits well under the
+ * whole-prompt PROMPT_SOFT_CAP_BYTES (60KB) so the two caps don't fight.
+ */
+const OPERATING_NOTE_INJECTION_BYTE_BUDGET = 6 * 1024;
+
+/**
+ * A category is "durable" (survives the cap ahead of recency) when it has no
+ * TTL entry — provider_quirk, uncategorized, or any unknown category. This
+ * mirrors isNoteExpired's durability rule so ranking and expiry agree.
+ */
+function isDurableCategory(category?: string): boolean {
+    if (!category) return true;
+    return !(category in OPERATING_NOTE_CATEGORY_TTL_DAYS);
+}
+
+/**
+ * Phase 2 (b)/(c) — derive a note's subject key for supersede targeting and
+ * same-class folding. Precedence:
+ *   1. an explicit `subjectKey` (trimmed, lowercased) when present, else
+ *   2. a leading `[tag]` bracket, so legacy notes that follow the conventional
+ *      `[some-tag] …` prefix still group/supersede by that tag, else
+ *   3. undefined — the note has no derivable subject and never folds/supersedes
+ *      by key (it can still be targeted by exact noteId).
+ * Pure. Lowercased so `[Foo]` and `[foo]` collapse together.
+ */
+function deriveSubjectKey(note: CoordinatorOperatingNote): string | undefined {
+    const explicit = typeof note.subjectKey === 'string' ? note.subjectKey.trim().toLowerCase() : '';
+    if (explicit) return explicit;
+    const text = typeof note.text === 'string' ? note.text.trimStart() : '';
+    const m = /^\[([^\]]{1,80})\]/.exec(text);
+    const tag = m ? m[1].trim().toLowerCase() : '';
+    return tag || undefined;
+}
+
+/**
+ * Phase 2 (c) — deterministic same-class fold. Given ranked notes (already
+ * highest-priority first), collapse runs of UNPINNED notes that share the same
+ * category AND subject key into a single injected entry: keep the highest-ranked
+ * (first-seen) note and record the note-ids/count it subsumes so the rendered
+ * line can say "(+N earlier)". Pinned notes never fold — each pinned note is
+ * author-opted-in and shown verbatim. The store is untouched; this is a pure,
+ * model-free text fold at injection time.
+ *
+ * Returns the folded note list (order preserved) with per-entry subsumed info.
+ */
+interface FoldedNote {
+    note: CoordinatorOperatingNote;
+    /** note-ids of same-class notes this entry subsumes (may be empty). */
+    subsumedIds: string[];
+    /** count of subsumed notes (== subsumedIds.length, but counts id-less ones too). */
+    subsumedCount: number;
+}
+
+function foldSameClassNotes(ranked: CoordinatorOperatingNote[]): FoldedNote[] {
+    const out: FoldedNote[] = [];
+    // group key → index into `out` of the surviving (highest-ranked) entry.
+    const survivorByKey = new Map<string, number>();
+    for (const note of ranked) {
+        const subject = deriveSubjectKey(note);
+        // Only unpinned notes with a category AND a subject key are foldable —
+        // without both there is no reliable "same class/subject" signal, so we
+        // keep the note standalone (lossless for legacy/uncategorized notes).
+        const foldable = !note.pinned && !!note.category && !!subject;
+        if (foldable) {
+            const key = `${note.category}${subject}`;
+            const existing = survivorByKey.get(key);
+            if (existing !== undefined) {
+                const survivor = out[existing];
+                survivor.subsumedCount += 1;
+                if (typeof note.noteId === 'string' && note.noteId) survivor.subsumedIds.push(note.noteId);
+                continue;
+            }
+            survivorByKey.set(key, out.length);
+        }
+        out.push({ note, subsumedIds: [], subsumedCount: 0 });
+    }
+    return out;
+}
+
+/** Estimate the UTF-8 byte cost of one rendered operating-note line (Phase 2 d). */
+function renderedNoteBytes(folded: FoldedNote): number {
+    return byteLength(renderOperatingNoteLine(folded));
+}
+
+/**
+ * Operating-notes lifecycle selection (read-side). Given the effective notes
+ * (oldest-first, ledger order) and the current time, produce the ordered list
+ * that rides into the prompt:
+ *   (i)    ALWAYS include pinned notes.
+ *   (ii)   drop expired UNPINNED notes (per category TTL / explicit expiresAt).
+ *   (iii)  Phase 2 (b) drop any note SUPERSEDED by a later live note (by noteId
+ *          or subjectKey); pinned notes are never dropped by supersede.
+ *   (iv)   rank pinned-first, then durable-category, then recency (newest first).
+ *   (v)    Phase 2 (c) fold same-category/same-subject unpinned runs into one.
+ *   (vi)   Phase 2 (d) fill up to a byte budget AND a count cap; pinned always
+ *          kept even if they alone exceed the byte budget.
+ * Pure + deterministic given `now`. Returns { shown, omittedCount } where `shown`
+ * carries per-entry fold info for the renderer.
+ *
+ * Ranking is stable on the original ledger index so, within a tier, newest notes
+ * lead. The caps keep the leading (highest-priority) entries.
+ */
+export function selectOperatingNotesForPrompt(
+    notes: CoordinatorOperatingNote[],
+    now: number,
+    cap: number = OPERATING_NOTES_PROMPT_CAP,
+    byteBudget: number = OPERATING_NOTE_INJECTION_BYTE_BUDGET,
+): { shown: FoldedNote[]; omittedCount: number } {
     const valid = Array.isArray(notes)
         ? notes.filter(n => n && typeof n.text === 'string' && n.text.trim())
         : [];
-    if (valid.length === 0) return '';
 
+    // (i)+(ii): keep pinned always; drop expired unpinned. Retain original index
+    // for a stable recency tiebreak (later index == newer, ledger is oldest-first).
+    let kept = valid
+        .map((note, index) => ({ note, index }))
+        .filter(({ note }) => note.pinned || !isNoteExpired(note as any, now));
+
+    // (iii) Phase 2 (b) version-supersede: a LATER live note may name (via
+    // `supersedes`) an earlier note's noteId or subjectKey; the earlier one is
+    // then hidden. "Later" == higher ledger index. Collect every supersede target
+    // paired with the max index that supersedes it, then drop any UNPINNED note
+    // whose id/subjectKey is superseded by a strictly-later note. Pinned notes are
+    // never dropped by supersede (pinned always wins, mirroring TTL).
+    const supersededAtIndex = new Map<string, number>();
+    for (const { note, index } of kept) {
+        const target = typeof note.supersedes === 'string' ? note.supersedes.trim().toLowerCase() : '';
+        if (!target) continue;
+        const prev = supersededAtIndex.get(target);
+        if (prev === undefined || index > prev) supersededAtIndex.set(target, index);
+    }
+    if (supersededAtIndex.size > 0) {
+        kept = kept.filter(({ note, index }) => {
+            if (note.pinned) return true;
+            const byId = typeof note.noteId === 'string' ? note.noteId.trim().toLowerCase() : '';
+            const bySubject = deriveSubjectKey(note);
+            const supIdx = Math.max(
+                byId ? (supersededAtIndex.get(byId) ?? -1) : -1,
+                bySubject ? (supersededAtIndex.get(bySubject) ?? -1) : -1,
+            );
+            return !(supIdx > index); // superseded by a strictly-later note → drop
+        });
+    }
+
+    // (iv): rank pinned > durable > recency (newest first within a tier).
+    const rank = (n: CoordinatorOperatingNote): number =>
+        n.pinned ? 0 : isDurableCategory(n.category) ? 1 : 2;
+    kept.sort((a, b) => {
+        const r = rank(a.note) - rank(b.note);
+        if (r !== 0) return r;
+        return b.index - a.index; // newer (higher index) first
+    });
+
+    // (v) Phase 2 (c): fold same-class/same-subject unpinned runs into one entry.
+    const folded = foldSameClassNotes(kept.map(k => k.note));
+
+    // (vi) Phase 2 (d): fill up to the byte budget AND the count cap. Pinned
+    // entries are always kept (never dropped to fit the budget); the budget/cap
+    // bound the unpinned tail. Entries are already highest-priority first, so we
+    // walk in order and stop once an UNPINNED entry would break a bound.
+    const shown: FoldedNote[] = [];
+    let usedBytes = 0;
+    let usedCount = 0;
+    for (const entry of folded) {
+        if (entry.note.pinned) {
+            shown.push(entry);
+            usedBytes += renderedNoteBytes(entry);
+            usedCount += 1;
+            continue;
+        }
+        if (usedCount >= cap) break;
+        const bytes = renderedNoteBytes(entry);
+        if (usedCount > 0 && usedBytes + bytes > byteBudget) break;
+        shown.push(entry);
+        usedBytes += bytes;
+        usedCount += 1;
+    }
+
+    // omittedCount counts eligible (non-expired, non-superseded, post-fold) entries
+    // that did not make the cut. Folded-away duplicates are not "omitted" — they are
+    // represented by their survivor's "(+N earlier)" marker, so exclude them here.
+    const omittedCount = Math.max(0, folded.length - shown.length);
+    return { shown, omittedCount };
+}
+
+/**
+ * Render one operating-note bullet line (Phase 2 c fold-aware). Shared by the
+ * byte-budget estimator and the section renderer so the budget is measured on
+ * the exact bytes that ship.
+ */
+function renderOperatingNoteLine(folded: FoldedNote): string {
+    const n = folded.note;
     const categoryLabel: Record<string, string> = {
         provider_quirk: 'provider quirk',
         pattern_to_avoid: 'pattern to avoid',
         recovery_lesson: 'recovery lesson',
     };
+    const pin = n.pinned ? '📌 ' : '';
+    const cat = n.category && categoryLabel[n.category] ? `[${categoryLabel[n.category]}] ` : '';
+    const fold = folded.subsumedCount > 0
+        ? ` _(+${folded.subsumedCount} earlier same-subject note${folded.subsumedCount === 1 ? '' : 's'} folded${folded.subsumedIds.length ? `: ${folded.subsumedIds.join(', ')}` : ''})_`
+        : '';
+    return `- ${pin}${cat}${truncateNote(n.text.trim())}${fold}`;
+}
+
+function buildOperatingNotesSection(notes?: CoordinatorOperatingNote[], now: number = Date.now()): string {
+    const hasAny = Array.isArray(notes)
+        ? notes.some(n => n && typeof n.text === 'string' && n.text.trim())
+        : false;
+    if (!hasAny) return '';
 
-    // Keep only the most recent OPERATING_NOTES_PROMPT_CAP notes in the prompt.
-    // `valid` is oldest-first (ledger order), so the newest are at the tail.
-    const omittedCount = Math.max(0, valid.length - OPERATING_NOTES_PROMPT_CAP);
-    const shown = omittedCount > 0 ? valid.slice(-OPERATING_NOTES_PROMPT_CAP) : valid;
+    // Lifecycle selection: pinned-always + expired-unpinned-dropped +
+    // superseded-dropped + rank (pinned > durable > recency) + same-class fold +
+    // byte-budget/count cap. `shown` is already highest-priority-first and carries
+    // per-entry fold info; renderOperatingNoteLine emits the exact bytes the
+    // budget was measured against.
+    const { shown, omittedCount } = selectOperatingNotesForPrompt(notes ?? [], now);
+    if (shown.length === 0) return '';
 
     const lines: string[] = ['## Operating Notes', ''];
     lines.push('Lessons earlier coordinators on this mesh recorded via `mesh_record_note`. Treat them as accumulated operating knowledge — apply them. When you learn a durable lesson (a provider quirk, a pattern to avoid, a recovery lesson), record it with `mesh_record_note` so future coordinators inherit it.');
     lines.push('');
-    for (const n of shown) {
-        const cat = n.category && categoryLabel[n.category] ? `[${categoryLabel[n.category]}] ` : '';
-        lines.push(`- ${cat}${truncateNote(n.text.trim())}`);
+    for (const entry of shown) {
+        lines.push(renderOperatingNoteLine(entry));
     }
     if (omittedCount > 0) {
         lines.push('');
-        lines.push(`_${omittedCount} older note${omittedCount === 1 ? '' : 's'} omitted (kept in ledger; prune with \`mesh_forget_note\`)._`);
+        lines.push(`_${omittedCount} lower-priority note${omittedCount === 1 ? '' : 's'} omitted to fit the injection cap/byte-budget (kept in ledger; expired, superseded, and same-subject-folded notes are also hidden from this list but retained for audit; prune with \`mesh_forget_note\`)._`);
     }
     return lines.join('\n');
 }

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;
+}