@yeaft/webchat-agent 0.1.629 → 0.1.631

package/unify/dream-v2/runner.js

@@ -0,0 +1,267 @@
+/**
+ * dream-v2/runner.js — DESIGN-v2 §13.
+ *
+ * Orchestrates one full dream pass:
+ *
+ *   trigger
+ *     ↓
+ *   enumerateGroups()                  via opts.listGroups()
+ *     ↓
+ *   for each group with newCount ≥ MIN_NEW_PER_GROUP (auto)
+ *                    or > 0 (manual):
+ *       loadDiff()                     via opts.loadGroupDiff(groupId, sinceId)
+ *       applyOverlap()                 via opts.loadOverlapPreamble(...)
+ *       segment()                      segmentDiff(...)
+ *       triageGroupSegments()          → group-local actions[]
+ *
+ *   mergeByTarget()                    → per-target actions
+ *   for each merged target:
+ *       applyMergedTarget()            (snapshot + UPDATE/CREATE + atomic write)
+ *
+ *   bookkeep:
+ *     for each processed group:
+ *       group .dream-state ←
+ *         { lastDreamMessageId: tail of real diff,
+ *           lastDreamAt: nowIso,
+ *           messageCount: <after> }
+ *
+ *   pruneOldSnapshots()
+ *
+ *   onProgress emits dream_progress events that the web bridge forwards
+ *   as `unify_output` messages so the debug panel can render live state
+ *   (DESIGN-v2 §19.4). All events flow through the same channel; no new
+ *   WebSocket message type is introduced.
+ *
+ * Everything that touches a shell of the system (LLM, message store,
+ * scope listing, topic tree) is injected. The default exports below
+ * are pure orchestration.
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+import { listScopes, readSummary } from '../memory/store-v2.js';
+import {
+  DEFAULT_LIMITS,
+} from './limits.js';
+import { readGroupState, writeGroupState } from './state.js';
+import { segmentDiff, truncateMessage, estimateMessagesTokens } from './segment.js';
+import { triageGroupSegments } from './triage.js';
+import { mergeByTarget } from './merge.js';
+import { applyMergedTarget } from './apply.js';
+import { tsForBackup, pruneOldSnapshots } from './snapshot.js';
+
+/**
+ * @typedef {Object} RunDreamOpts
+ * @property {string} root                    — memory root, e.g. ~/.yeaft/memory
+ * @property {boolean} [manual=false]         — manual trigger overrides newCount<20 skip
+ * @property {string[]} [scopeFilter]         — optional: only dream these targets (still respects newCount per group; '*' allowed)
+ * @property {(req: {pass:string, prompt:string, system:string}) => Promise<string>} llm
+ * @property {() => Promise<Array<string>>} listGroups   — return all group ids (incl. '_no-group')
+ * @property {(groupId: string) => Promise<number>} countMessages   — total message count for a group
+ * @property {(groupId: string, sinceMessageId: string|null) => Promise<Array<object>>} loadGroupDiff
+ * @property {(groupId: string, beforeMessageId: string|null, count: number) => Promise<Array<object>>} loadOverlapPreamble
+ * @property {() => Promise<Array<{path:string, summary:string}>>} [listTopicSummaries]
+ * @property {(target: string) => Promise<Array<{path:string, summary:string}>>} [siblingTopicsFor]
+ * @property {(event: object) => void} [onProgress]
+ * @property {object} [limits]                — override DEFAULT_LIMITS
+ * @property {() => string} [nowIso]
+ */
+
+/**
+ * Run one dream pass. Returns a structured report consumed by the
+ * debug panel (and tests).
+ *
+ * @param {RunDreamOpts} opts
+ */
+export async function runDream(opts) {
+  if (!opts || !opts.root) throw new Error('runDream: opts.root required');
+  if (!opts.llm) throw new Error('runDream: opts.llm required');
+  const limits = { ...DEFAULT_LIMITS, ...(opts.limits || {}) };
+  const onProgress = typeof opts.onProgress === 'function' ? opts.onProgress : () => {};
+  const nowIso = (opts.nowIso ? opts.nowIso() : new Date().toISOString());
+  const ts = tsForBackup(new Date(nowIso));
+  const startedAt = Date.now();
+
+  onProgress({ phase: 'start', manual: !!opts.manual, ts });
+
+  // 1. enumerate groups
+  const groupIds = await safeCall(opts.listGroups, []);
+  const filter = Array.isArray(opts.scopeFilter) ? new Set(opts.scopeFilter) : null;
+  const groupsReport = [];
+  const groupTriages = [];
+  const processedGroups = [];
+
+  // 2. per-group: skip / segment / triage
+  const topicSummaries = opts.listTopicSummaries
+    ? await safeCall(opts.listTopicSummaries, [])
+    : await defaultListTopicSummaries(opts.root).catch(() => []);
+
+  for (const groupId of groupIds) {
+    // NOTE: scopeFilter is applied at the merge/apply stage, not here.
+    // A filter like ['user'] still requires triaging every group so their
+    // hard-rule actions can contribute to the user target.
+    const state = await readGroupState(opts.root, groupId);
+    const beforeCount = await safeCall(() => opts.countMessages(groupId), 0);
+    const newCount = Math.max(0, beforeCount - (state.messageCount || 0));
+
+    if (newCount === 0) {
+      groupsReport.push({ groupId, new: 0, status: 'skipped', reason: 'no-new-messages' });
+      continue;
+    }
+    if (!opts.manual && newCount < limits.MIN_NEW_PER_GROUP) {
+      groupsReport.push({ groupId, new: newCount, status: 'skipped', reason: 'below-threshold' });
+      continue;
+    }
+
+    onProgress({ phase: 'load-diff', groupId });
+    const diffNew = await safeCall(() => opts.loadGroupDiff(groupId, state.lastDreamMessageId), []);
+    if (!diffNew || diffNew.length === 0) {
+      groupsReport.push({ groupId, new: newCount, status: 'skipped', reason: 'empty-diff' });
+      continue;
+    }
+    const overlapMessages = state.lastDreamMessageId
+      ? await safeCall(
+          () => opts.loadOverlapPreamble
+            ? opts.loadOverlapPreamble(groupId, state.lastDreamMessageId, limits.DREAM_OVERLAP)
+            : [],
+          [],
+        )
+      : [];
+    const taggedOverlap = overlapMessages.map(m => ({ ...m, kind: 'overlap', body: truncateMessage(m.body || '') }));
+    const taggedNew = diffNew.map(m => ({ ...m, kind: 'new', body: truncateMessage(m.body || '') }));
+    const fullDiff = [...taggedOverlap, ...taggedNew];
+
+    const segments = segmentDiff(fullDiff, limits.MAX_DIFF_TOKENS_PER_TRIAGE, limits.DREAM_OVERLAP);
+    onProgress({ phase: 'triage', groupId, status: 'running', segments: segments.length });
+
+    let actions;
+    try {
+      actions = await triageGroupSegments({
+        groupId,
+        segments,
+        topicSummaries,
+        llm: opts.llm,
+        onProgress,
+      });
+    } catch (err) {
+      groupsReport.push({ groupId, new: newCount, status: 'error', error: err.message });
+      onProgress({ phase: 'triage', groupId, status: 'error', error: err.message });
+      continue;
+    }
+
+    onProgress({ phase: 'triage', groupId, status: 'done', actions: actions.length });
+    groupTriages.push({ groupId, diff: fullDiff, actions });
+
+    const tailId = lastMessageId(diffNew);
+    processedGroups.push({ groupId, tailId, beforeCount, newCount, segments: segments.length, actions: actions.length });
+    groupsReport.push({ groupId, new: newCount, segments: segments.length, actions: actions.length, status: 'triaged' });
+  }
+
+  // 3. merge
+  const mergedTargets = mergeByTarget(groupTriages);
+  const targetsToApply = filter && filter.size > 0 && !filter.has('*')
+    ? mergedTargets.filter(t => filter.has(t.target))
+    : mergedTargets;
+
+  onProgress({ phase: 'merge', targets: targetsToApply.length });
+
+  // 4. apply
+  const targetsReport = [];
+  for (const merged of targetsToApply) {
+    try {
+      const r = await applyMergedTarget(merged, {
+        root: opts.root,
+        ts,
+        llm: opts.llm,
+        limits,
+        nowIso: opts.nowIso || (() => nowIso),
+        onProgress,
+        siblingTopicsFor: opts.siblingTopicsFor,
+      });
+      targetsReport.push({ ...r, sources: merged.sources.length, status: 'done' });
+    } catch (err) {
+      targetsReport.push({
+        target: merged.target,
+        kind: merged.kind,
+        sources: merged.sources.length,
+        status: 'error',
+        error: err.message,
+      });
+      onProgress({ phase: 'apply', target: merged.target, status: 'error', error: err.message });
+    }
+  }
+
+  // 5. bookkeep — only when at least one apply for this group's actions
+  // succeeded. We use a permissive policy: if ANY merged-target apply
+  // succeeded for a group's contributed actions, advance that group's
+  // cursor. (If everything errored, we keep the cursor so next run
+  // retries.)
+  const successfulTargets = new Set(targetsReport.filter(r => r.status === 'done').map(r => r.target));
+  for (const pg of processedGroups) {
+    const contributed = (groupTriages.find(g => g.groupId === pg.groupId) || { actions: [] })
+      .actions.map(a => a.scope);
+    const anySuccess = contributed.some(t => successfulTargets.has(t));
+    if (!anySuccess) continue;
+    if (pg.tailId) {
+      await writeGroupState(opts.root, pg.groupId, {
+        lastDreamMessageId: pg.tailId,
+        lastDreamAt: nowIso,
+        messageCount: pg.beforeCount,
+      });
+    }
+  }
+
+  // 6. prune backups
+  const pruned = await pruneOldSnapshots(opts.root, limits.DREAM_BACKUP_KEEP);
+
+  const duration = Date.now() - startedAt;
+  onProgress({
+    phase: 'done',
+    groups: processedGroups.length,
+    targets: targetsReport.length,
+    duration,
+    backupsKept: pruned.kept.length,
+    backupsRemoved: pruned.removed.length,
+  });
+
+  return {
+    startedAt: nowIso,
+    durationMs: duration,
+    groups: groupsReport,
+    targets: targetsReport,
+    backups: pruned,
+    ts,
+  };
+}
+
+// ─── helpers ──────────────────────────────────────────────────
+
+function lastMessageId(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return null;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    if (messages[i] && messages[i].id) return messages[i].id;
+  }
+  return null;
+}
+
+async function safeCall(fn, fallback) {
+  try {
+    if (typeof fn !== 'function') return fallback;
+    const v = await fn();
+    return v == null ? fallback : v;
+  } catch {
+    return fallback;
+  }
+}
+
+async function defaultListTopicSummaries(root) {
+  const all = await listScopes({ root });
+  const out = [];
+  for (const sc of all) {
+    if (sc.kind !== 'topic') continue;
+    const summary = await readSummary(sc, { root });
+    out.push({ path: sc.path.join('/'), summary });
+  }
+  return out;
+}

package/unify/dream-v2/schedule.js

@@ -0,0 +1,73 @@
+/**
+ * dream-v2/schedule.js — DESIGN-v2 §10.2.
+ *
+ * Two trigger paths:
+ *
+ *   1. 12-hour interval timer.
+ *   2. Manual trigger (UI button or `/dream` command), routed in via
+ *      `triggerNow()` — sets `manual: true` so the per-group threshold
+ *      is bypassed.
+ *
+ * The scheduler is a thin wrapper around `runDream()` that prevents
+ * concurrent passes (a second tick while the previous is still running
+ * is dropped, not queued — DESIGN-v2 §10.1: "slow is OK, doesn't
+ * compete with user latency").
+ */
+
+import { DREAM_INTERVAL_HOURS } from './limits.js';
+
+export const DEFAULT_INTERVAL_MS = DREAM_INTERVAL_HOURS * 60 * 60 * 1000;
+
+/**
+ * Build a scheduler around `runDream()`. The runner closure captures
+ * everything `runDream` needs (memory root, llm, message-store hooks,
+ * onProgress sink); the scheduler only knows how to call it.
+ *
+ * @param {{
+ *   run: (opts: { manual: boolean, scopeFilter?: string[] }) => Promise<object>,
+ *   intervalMs?: number,
+ *   logger?: { info?: (...a:any) => void, warn?: (...a:any) => void, error?: (...a:any) => void },
+ * }} args
+ */
+export function createDreamScheduler({ run, intervalMs = DEFAULT_INTERVAL_MS, logger }) {
+  if (typeof run !== 'function') throw new Error('createDreamScheduler: run callable required');
+  const log = logger || {};
+  let timer = null;
+  let inflight = null;
+
+  async function fire(opts) {
+    if (inflight) {
+      log.warn?.('[dream] tick dropped — previous run still in progress');
+      return inflight;
+    }
+    inflight = (async () => {
+      try {
+        return await run(opts);
+      } catch (err) {
+        log.error?.('[dream] run failed:', err && err.message ? err.message : err);
+        return { error: err && err.message ? err.message : String(err) };
+      } finally {
+        inflight = null;
+      }
+    })();
+    return inflight;
+  }
+
+  return {
+    start() {
+      if (timer) return;
+      timer = setInterval(() => { fire({ manual: false }).catch(() => {}); }, intervalMs);
+      // Don't keep the event loop alive solely for the dream ticker.
+      if (typeof timer.unref === 'function') timer.unref();
+    },
+    stop() {
+      if (timer) { clearInterval(timer); timer = null; }
+    },
+    triggerNow(scopeFilter) {
+      return fire({ manual: true, scopeFilter });
+    },
+    isRunning() { return !!inflight; },
+    /** Test hook: fires once without scheduling a timer. */
+    _fire: fire,
+  };
+}

package/unify/dream-v2/segment.js

@@ -0,0 +1,191 @@
+/**
+ * dream-v2/segment.js — DESIGN-v2 §17.
+ *
+ * Three independent length-control concerns, kept pure so they can be
+ * unit-tested without touching disk or any LLM:
+ *
+ *   1. truncateMessage — clamp a single message body to
+ *      MAX_SINGLE_MESSAGE_CHARS, appending a clear notice. The full
+ *      body is still preserved in the conversation log; this only
+ *      affects what dream sees. (§17.3)
+ *
+ *   2. estimateTokens — rough chars-to-tokens approximation (we use 4
+ *      chars/token, a stable industry approximation that doesn't drag
+ *      a tokenizer into this layer; precise counts aren't required for
+ *      "should we segment?" decisions and a small over-count is the
+ *      safe direction).
+ *
+ *   3. segmentDiff — split a long per-group diff into K consecutive
+ *      slices, each ≤ MAX_DIFF_TOKENS_PER_TRIAGE, with a 3-message
+ *      overlap between adjacent slices for context continuity. (§17.1)
+ *
+ *   4. needsBatchedApply / batchSourcesForApply — when an Apply target's
+ *      memory + summary + sources cumulatively exceed MAX_APPLY_TOKENS,
+ *      split the sources (one source = one group's contribution) into
+ *      batches; the LLM is then called once per batch, threading the
+ *      written-back memory.md as input to the next batch. (§17.2)
+ *
+ * No side-effects. All functions are deterministic given their inputs.
+ */
+
+import {
+  MAX_SINGLE_MESSAGE_CHARS,
+  MAX_DIFF_TOKENS_PER_TRIAGE,
+  MAX_APPLY_TOKENS,
+  DREAM_OVERLAP,
+} from './limits.js';
+
+const TRUNCATION_NOTICE = '\n\n[message truncated for dream, original preserved in conversation log]';
+
+/**
+ * Truncate a single message body if it exceeds the per-message char cap.
+ * Idempotent: passing in an already-truncated body returns it unchanged.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function truncateMessage(body) {
+  const s = String(body || '');
+  if (s.length <= MAX_SINGLE_MESSAGE_CHARS) return s;
+  if (s.endsWith(TRUNCATION_NOTICE)) return s;
+  // Reserve room for the notice without overflowing the cap.
+  const room = Math.max(0, MAX_SINGLE_MESSAGE_CHARS - TRUNCATION_NOTICE.length);
+  return s.slice(0, room) + TRUNCATION_NOTICE;
+}
+
+/**
+ * Conservative chars-to-tokens approximation. We over-count slightly
+ * (1 token ≈ 4 chars) to make MAX_*_TOKENS act as a true upper bound.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(String(text).length / 4);
+}
+
+/**
+ * Estimate the token cost of an array of messages (header + body for each).
+ * @param {Array<{id?: string, role?: string, body?: string}>} msgs
+ */
+export function estimateMessagesTokens(msgs) {
+  if (!Array.isArray(msgs)) return 0;
+  let n = 0;
+  for (const m of msgs) {
+    n += estimateTokens(m.role || '');
+    n += estimateTokens(m.body || '');
+    n += 2; // separator overhead
+  }
+  return n;
+}
+
+/**
+ * Split a contiguous group diff into ≤MAX-token segments, with a
+ * DREAM_OVERLAP-message tail/head overlap between consecutive segments.
+ *
+ * Returns segments in temporal order. Each segment is `{ messages, kind }`
+ * where `kind` is 'overlap' for messages that exist only as continuity
+ * preamble (because they appeared in a prior segment), and 'new' for
+ * the rest. The first segment has no overlap header.
+ *
+ * Properties:
+ *   - The union of `kind: 'new'` messages across all segments equals
+ *     the input diff exactly, in order, with no duplicates.
+ *   - Each segment's total token estimate ≤ MAX_DIFF_TOKENS_PER_TRIAGE
+ *     unless a single message alone exceeds the cap, in which case
+ *     that message gets its own segment (we never split a message).
+ *
+ * @param {Array<{id?: string, role?: string, body?: string}>} diff
+ * @param {number} [maxTokens=MAX_DIFF_TOKENS_PER_TRIAGE]
+ * @param {number} [overlap=DREAM_OVERLAP]
+ * @returns {Array<{ messages: Array<object>, overlapCount: number, newCount: number }>}
+ */
+export function segmentDiff(diff, maxTokens = MAX_DIFF_TOKENS_PER_TRIAGE, overlap = DREAM_OVERLAP) {
+  const msgs = Array.isArray(diff) ? diff : [];
+  if (msgs.length === 0) return [];
+
+  // Fast path: whole diff fits in one segment.
+  if (estimateMessagesTokens(msgs) <= maxTokens) {
+    return [{ messages: msgs, overlapCount: 0, newCount: msgs.length }];
+  }
+
+  const segments = [];
+  let cursor = 0;
+  while (cursor < msgs.length) {
+    const overlapHead = segments.length > 0
+      ? msgs.slice(Math.max(0, cursor - overlap), cursor)
+      : [];
+    let used = estimateMessagesTokens(overlapHead);
+    let end = cursor;
+    while (end < msgs.length) {
+      const cost = estimateTokens(msgs[end].body || '') + estimateTokens(msgs[end].role || '') + 2;
+      if (used + cost > maxTokens && end > cursor) break;
+      used += cost;
+      end += 1;
+    }
+    // If we made no progress (single oversized message), advance by 1.
+    if (end === cursor) end = cursor + 1;
+    segments.push({
+      messages: [...overlapHead, ...msgs.slice(cursor, end)],
+      overlapCount: overlapHead.length,
+      newCount: end - cursor,
+    });
+    cursor = end;
+  }
+  return segments;
+}
+
+// ─── apply batching ───────────────────────────────────────────
+
+/**
+ * Decide whether a merged apply target needs to be split into batches.
+ *
+ * @param {{ memoryMd?: string, summaryMd?: string, sources: Array<{ groupId: string, diff: any }> }} merged
+ * @param {number} [maxTokens=MAX_APPLY_TOKENS]
+ */
+export function needsBatchedApply(merged, maxTokens = MAX_APPLY_TOKENS) {
+  return totalApplyTokens(merged) > maxTokens;
+}
+
+function totalApplyTokens(merged) {
+  let n = estimateTokens(merged.memoryMd || '') + estimateTokens(merged.summaryMd || '');
+  for (const src of merged.sources || []) n += estimateMessagesTokens(src.diff || []);
+  return n;
+}
+
+/**
+ * Pack `merged.sources` into ordered batches such that each batch's
+ * (memoryMd + summaryMd + that batch's sources) ≤ maxTokens. The first
+ * batch uses the original memoryMd; subsequent batches assume the LLM's
+ * previous-batch output replaces memoryMd, so we account for the same
+ * baseline cost in each batch.
+ *
+ * If a single source (one group's diff) alone would overflow, it still
+ * goes into its own batch — we never split a source diff here (segment
+ * happens earlier, in triage).
+ *
+ * @param {{ memoryMd?: string, summaryMd?: string, sources: Array<{ groupId: string, diff: any }> }} merged
+ * @param {number} [maxTokens=MAX_APPLY_TOKENS]
+ * @returns {Array<{ groupId: string, diff: any }[]>}
+ */
+export function batchSourcesForApply(merged, maxTokens = MAX_APPLY_TOKENS) {
+  const sources = Array.isArray(merged.sources) ? merged.sources : [];
+  if (sources.length === 0) return [];
+  const baseline = estimateTokens(merged.memoryMd || '') + estimateTokens(merged.summaryMd || '');
+  const batches = [];
+  let cur = [];
+  let used = baseline;
+  for (const src of sources) {
+    const cost = estimateMessagesTokens(src.diff || []);
+    if (cur.length > 0 && used + cost > maxTokens) {
+      batches.push(cur);
+      cur = [];
+      used = baseline;
+    }
+    cur.push(src);
+    used += cost;
+  }
+  if (cur.length > 0) batches.push(cur);
+  return batches;
+}

package/unify/dream-v2/snapshot.js

@@ -0,0 +1,80 @@
+/**
+ * dream-v2/snapshot.js — DESIGN-v2 §16.3 + §10.
+ *
+ * Pre-Apply backup of memory.md + summary.md to
+ * `~/.yeaft/memory/.dream-bak/<ts>/<scope-path>/`. The runner takes a
+ * snapshot once per merged target before Apply mutates it; that snapshot
+ * is the unit of rollback in case of LLM error or write failure.
+ *
+ * `pruneOldSnapshots()` keeps the most recent DREAM_BACKUP_KEEP
+ * timestamp directories under `.dream-bak/` and rm-rf's the rest.
+ *
+ * Pure I/O. No LLM. No control-flow.
+ */
+
+import { promises as fsp, existsSync } from 'fs';
+import { join, dirname } from 'path';
+
+import { DREAM_BACKUP_KEEP } from './limits.js';
+
+/** Folder name where snapshots live, relative to memory root. */
+export const BACKUP_DIRNAME = '.dream-bak';
+
+/**
+ * Build a stable filesystem-safe ISO timestamp string. Same shape that
+ * the migration script uses (`migrate-r6-to-v2.js`).
+ */
+export function tsForBackup(d = new Date()) {
+  return d.toISOString().replace(/[:.]/g, '-');
+}
+
+/**
+ * Snapshot a single scope's memory.md + summary.md into
+ * `<root>/.dream-bak/<ts>/<scopeRelDir>/`. Missing source files are
+ * skipped silently; the destination dir is always created so that an
+ * absent snapshot is still distinguishable from "didn't run".
+ *
+ * @param {string} root — memory root
+ * @param {string} ts   — timestamp folder name (re-use across all
+ *                        scopes in one dream pass)
+ * @param {string} scopeRelDir — e.g. 'user', 'group/g-eng', 'topic/sci/phys'
+ * @returns {Promise<{ backupDir: string, copied: string[] }>}
+ */
+export async function snapshotScope(root, ts, scopeRelDir) {
+  const srcDir = join(root, scopeRelDir);
+  const dstDir = join(root, BACKUP_DIRNAME, ts, scopeRelDir);
+  await fsp.mkdir(dstDir, { recursive: true });
+  const copied = [];
+  for (const name of ['memory.md', 'summary.md']) {
+    const s = join(srcDir, name);
+    if (!existsSync(s)) continue;
+    const d = join(dstDir, name);
+    await fsp.copyFile(s, d);
+    copied.push(name);
+  }
+  return { backupDir: dstDir, copied };
+}
+
+/**
+ * Keep the `keep` newest snapshot timestamps, rm-rf the rest.
+ *
+ * @param {string} root
+ * @param {number} [keep=DREAM_BACKUP_KEEP]
+ * @returns {Promise<{ kept: string[], removed: string[] }>}
+ */
+export async function pruneOldSnapshots(root, keep = DREAM_BACKUP_KEEP) {
+  const baseDir = join(root, BACKUP_DIRNAME);
+  if (!existsSync(baseDir)) return { kept: [], removed: [] };
+  let entries;
+  try { entries = await fsp.readdir(baseDir, { withFileTypes: true }); }
+  catch (err) { if (err && err.code === 'ENOENT') return { kept: [], removed: [] }; throw err; }
+  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+  // sort() of ISO-with-dashes timestamps is chronological.
+  const cutoff = Math.max(0, dirs.length - keep);
+  const removed = dirs.slice(0, cutoff);
+  const kept = dirs.slice(cutoff);
+  for (const name of removed) {
+    await fsp.rm(join(baseDir, name), { recursive: true, force: true }).catch(() => {});
+  }
+  return { kept, removed };
+}