@mindrian_os/install 1.13.0-beta.12 → 1.13.0-beta.14

package/lib/core/cache-prune.cjs

@@ -0,0 +1,208 @@
+'use strict';
+/*
+ * lib/core/cache-prune.cjs -- prune stale marketplace-cache version dirs.
+ *
+ * Phase 123 Plan-05 (HARNESS-123-13). Canon Part 8: this reads LOCAL files
+ * only (~/.claude/plugins/) and writes LOCAL files only (fs.rmSync on
+ * stale version dirs). Zero network surface.
+ *
+ * Background: Claude Code's marketplace install path is
+ *   ~/.claude/plugins/cache/<marketplace>/mos/<version>/
+ * where each <version> subdir is a self-contained install of that
+ * version. On `claude plugin update`, the new version is downloaded
+ * into a new <version> dir, but the old <version> dir is NEVER removed.
+ * The Windows live test of v1.13.0-beta.12 surfaced two orphans on disk
+ * (`1.12.0/`, `1.13.0-beta.9/`) alongside the active `1.13.0-beta.12/`.
+ *
+ * This helper prunes the cache, keying off Claude Code's own
+ * installed_plugins.json (the source of truth for "which version is active"):
+ *
+ *   - active version (from installed_plugins.json's mos@mindrian-marketplace
+ *     entry) is ALWAYS kept, regardless of mtime.
+ *   - the N most recent non-active versions (default N=2, sorted by mtime
+ *     DESC) are also kept.
+ *   - everything else is removed.
+ *
+ * Belt + suspenders: before every fs.rmSync call, the path's basename is
+ * cross-checked against the active version string -- if it matches, the
+ * removal is SKIPPED with a logged reason (defends against a malformed
+ * installed_plugins.json that somehow lists two different basenames as
+ * "active", or a race between this function and a concurrent install).
+ *
+ * If installed_plugins.json is unreadable (ENOENT, parse error, or no
+ * mos@mindrian-marketplace entry), the function returns
+ *   { kept: [], removed: [], skipped: true, reason: '...' }
+ * with NO mutation. Never guesses; never deletes anything in the absence
+ * of an authoritative active-version answer.
+ *
+ * Signature:
+ *   pruneMarketplaceCache({
+ *     home = os.homedir(),
+ *     marketplace = 'mindrian-marketplace',
+ *     retainCount = 2,
+ *     dryRun = false,
+ *   } = {}) => {
+ *     kept: string[],     // version basenames kept on disk (incl. active)
+ *     removed: string[],  // version basenames removed (or would be, in dryRun)
+ *     skipped: boolean,   // true if we declined to act (see `reason`)
+ *     reason: string|null // human-readable explanation, or null on success
+ *   }
+ *
+ * Canon Part 8 sanity check (cp.6): the forbidden-network-token grep
+ * exits 1 (no match) on this source file. Test cp.6 enforces it.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// Read installed_plugins.json and pull the mos@mindrian-marketplace active
+// version. Returns { activeVersion, activeInstallPath } on success, or
+// { skipped: true, reason } on any failure.
+function readActiveVersion(home) {
+  const installedPath = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(installedPath, 'utf8');
+  } catch (e) {
+    return { skipped: true, reason: 'installed_plugins.json unreadable (' + (e && e.code || e.message) + ') -- skipping prune' };
+  }
+  let ip;
+  try {
+    ip = JSON.parse(raw);
+  } catch (e) {
+    return { skipped: true, reason: 'installed_plugins.json parse error -- skipping prune' };
+  }
+  if (!ip || typeof ip !== 'object' || !ip.plugins || typeof ip.plugins !== 'object') {
+    return { skipped: true, reason: 'installed_plugins.json has no plugins map -- skipping prune' };
+  }
+  // Accept either key shape: 'mos@mindrian-marketplace' or 'mos'.
+  let entry = ip.plugins['mos@mindrian-marketplace'];
+  if (!entry) {
+    // Defensive: find any key whose left-of-@ is mos or mindrian-os.
+    const keys = Object.keys(ip.plugins);
+    for (const k of keys) {
+      const name = String(k).split('@')[0];
+      if (name === 'mos' || name === 'mindrian-os') { entry = ip.plugins[k]; break; }
+    }
+  }
+  if (!entry) {
+    return { skipped: true, reason: 'no active mos@mindrian-marketplace entry in installed_plugins.json -- skipping prune' };
+  }
+  if (Array.isArray(entry)) entry = entry[0];
+  if (!entry || !entry.version) {
+    return { skipped: true, reason: 'mos@mindrian-marketplace entry has no version field -- skipping prune' };
+  }
+  return {
+    activeVersion: String(entry.version),
+    activeInstallPath: entry.installPath || entry.path || entry.dir || null,
+  };
+}
+
+// List child directory names under <home>/.claude/plugins/cache/<marketplace>/mos/.
+// Returns [] if the cache dir does not exist (no-op case).
+function listCacheVersions(home, marketplace) {
+  const cacheDir = path.join(home, '.claude', 'plugins', 'cache', marketplace, 'mos');
+  if (!fs.existsSync(cacheDir)) return { cacheDir, names: [] };
+  let names = [];
+  try {
+    names = fs.readdirSync(cacheDir).filter(function (name) {
+      try { return fs.statSync(path.join(cacheDir, name)).isDirectory(); }
+      catch (_) { return false; }
+    });
+  } catch (_) { /* unreadable -- treat as empty */ }
+  return { cacheDir, names };
+}
+
+// Sort version names by mtime DESC (newest first). Falls back to lexicographic
+// order if statSync fails on any path (defensive).
+function sortByMtimeDesc(cacheDir, names) {
+  const stats = names.map(function (name) {
+    let mtimeMs = 0;
+    try { mtimeMs = fs.statSync(path.join(cacheDir, name)).mtimeMs || 0; }
+    catch (_) { mtimeMs = 0; }
+    return { name, mtimeMs };
+  });
+  stats.sort(function (a, b) {
+    if (b.mtimeMs !== a.mtimeMs) return b.mtimeMs - a.mtimeMs;
+    return a.name < b.name ? 1 : -1; // tie-break lexicographic DESC (stable)
+  });
+  return stats.map(function (s) { return s.name; });
+}
+
+function pruneMarketplaceCache(opts) {
+  const o = opts || {};
+  const home = o.home || os.homedir();
+  const marketplace = o.marketplace || 'mindrian-marketplace';
+  const retainCount = (typeof o.retainCount === 'number' && o.retainCount >= 0) ? o.retainCount : 2;
+  const dryRun = !!o.dryRun;
+
+  // Step 1: read active version. Skip entirely if unavailable -- never guess.
+  const active = readActiveVersion(home);
+  if (active.skipped) {
+    return { kept: [], removed: [], skipped: true, reason: active.reason };
+  }
+  const activeVersion = active.activeVersion;
+
+  // Step 2: list cache version dirs.
+  const { cacheDir, names } = listCacheVersions(home, marketplace);
+  if (names.length === 0) {
+    // No cache dir to prune. The active version is still "kept" conceptually
+    // (it lives in the cache when it exists; absent cache = nothing to do).
+    return { kept: [activeVersion], removed: [], skipped: false, reason: 'no cache dir to prune' };
+  }
+
+  // Step 3: build the keep-set.
+  //   - the active version is ALWAYS kept (regardless of mtime).
+  //   - then the N most recent non-active versions (by mtime DESC).
+  const sorted = sortByMtimeDesc(cacheDir, names);
+  const keep = new Set();
+  keep.add(activeVersion);
+  for (const name of sorted) {
+    if (name === activeVersion) continue;
+    if (keep.size >= retainCount + 1) break; // +1 reserves the slot for active
+    keep.add(name);
+  }
+
+  // Step 4: compute the prune set and act on it.
+  const removed = [];
+  for (const name of names) {
+    if (keep.has(name)) continue;
+    // Belt + suspenders: NEVER rm the active version's dir, no matter what.
+    if (name === activeVersion) {
+      // (Cannot reach here under normal flow -- the keep-set above always
+      // contains activeVersion. Defensive sentinel for malformed inputs.)
+      continue;
+    }
+    const target = path.join(cacheDir, name);
+    if (dryRun) {
+      removed.push(name);
+      continue;
+    }
+    try {
+      fs.rmSync(target, { recursive: true, force: true });
+      removed.push(name);
+    } catch (e) {
+      // Best-effort: a failed removal does not abort the whole prune; we
+      // record it in the reason field at the end if any failures occurred.
+      // The caller (session-start with `|| true`; doctor with try/catch +
+      // report.recoveries) handles the partial state.
+      removed.push(name + ' (rm-failed: ' + (e && e.code || e.message) + ')');
+    }
+  }
+
+  return {
+    kept: Array.from(keep),
+    removed,
+    skipped: false,
+    reason: null,
+  };
+}
+
+module.exports = {
+  pruneMarketplaceCache,
+  // Internal helpers exposed for testability + future reuse.
+  readActiveVersion,
+  listCacheVersions,
+  sortByMtimeDesc,
+};

package/lib/core/feynman/ROOM.md

@@ -0,0 +1,25 @@
+# lib/core/feynman/
+
+Phase 124 (FEYNMAN.md temporal awareness) renderer + runner ship here.
+
+Contains (after Plans 124-01 and 124-02 land):
+- `timeline-renderer.cjs` -- pure function `renderTimeline(db, sectionSlug, opts) -> { markdown_body, summary_stats }`. Reads ONLY via `lib/core/navigation.cjs` (the Phase 109 closed chokepoint): `findRecentChanges`, `findStaleDecisions`, and the new `firstCapturedLastTouchedBySection` (added as the 15th re-export in Plan 124-01, mirroring the Phase 110-03 `logMemoryEvent` re-export idiom). ZERO filesystem reads. ZERO Brain calls. ZERO LLM calls.
+- `timeline-runner.cjs` -- `refreshAll(roomDir)` + `refreshSection(roomDir, sectionSlug)`. Walks the room's section folders, finds each `FEYNMAN.md` with the sentinel pair (creates the pair if absent on first run), reads the surrounding body, calls the renderer, writes the file back with the body byte-preserved and the sentinel-bounded section replaced, sets `timeline_last_rendered: <ISO>` frontmatter (second-resolution). Each refresh logs a `memory_event` of type `feynman_timeline_refreshed`. Idempotent (re-run -> byte-identical output).
+
+Sentinel pair (D-02 hard invariant; bytes outside the pair are byte-preserved across regeneration):
+- `<!-- TIMELINE_AUTO_START -->`
+- `<!-- TIMELINE_AUTO_END -->`
+
+Stale thresholds (D-06; overridable via `process.env.MINDRIAN_TIMELINE_THRESHOLDS_JSON` for tests):
+- recent < 7 days
+- quiet 7-30 days
+- stale 30-90 days
+- dormant > 90 days
+
+Owner: Phase 124 FEYNMAN.md Temporal Awareness.
+Canon: Part 9 (the Larry-explains face of memory_event). Renderer reads ONLY room.db via navigation.cjs (D-03). Writes ONLY FEYNMAN.md inside the sentinels (D-02 hard invariant).
+Boundary: NO Brain calls (Canon Part 8); NO filesystem reads outside the FEYNMAN.md being written and the room.db family (allow-list pattern enforced by `tests/test-feynman-timeline-canon-part-9-invariant.cjs`).
+
+Upstream: `lib/core/navigation.cjs` (Phase 109 chokepoint), `lib/core/navigation/memory-events.cjs` (EVENT_TYPES +2 in Plan 124-02), `lib/core/navigation/insights.cjs` (source_section provenance).
+
+See: `.planning/phases/124-feynman-temporal-awareness/124-CONTEXT.md`.

package/lib/core/feynman/timeline-renderer.cjs

@@ -0,0 +1,197 @@
+'use strict';
+// Phase 124-01 -- FEYNMAN.md timeline renderer
+// ===========================================
+// Pure function. Given (db, sectionSlug, opts) returns { markdown_body, summary_stats }.
+// Reads ONLY via lib/core/navigation.cjs (the Phase 109 closed chokepoint per D-03).
+// ZERO filesystem reads. ZERO Brain calls. ZERO LLM calls.
+//
+// Canon Part 9: the Larry-explains face of memory_event -- structured SQL becomes
+// human-readable explanation strings via templated rendering, never LLM in the loop.
+//
+// Canon Part 8: zero net new Brain surface; the renderer is local-only.
+//
+// Canon Part 5: "stale" is a context signal (4 buckets: recent / quiet / stale / dormant)
+// alongside the existing evidence tier; thresholds frozen at 7 / 30 / 90 days per D-06.
+//
+// Output format (D-05 LOCKED):
+//   *Last refreshed: {ISO}. {N} insight events, first captured {first_iso}, last touched {last_iso} ({last_delta_human}).*
+//
+//   **Recent events** (within 7 days, top 5):
+//   - {iso}: {event_type} -- {one_line_explain}
+//   - ...
+//
+//   **Flagged stale** (over 30 days untouched, top 5):
+//   - {iso}: {event_type} on {target_summary} -- last touched {delta_human}
+//   - ...
+//
+//   **Health:** recent={n_recent} / quiet={n_quiet} / stale={n_stale} / dormant={n_dormant}.
+//
+// Empty state (zero memory_event rows scoped to section):
+//   *No timeline events yet.*
+
+const navigation = require('../navigation.cjs');
+
+// ---------- D-06 thresholds ----------
+
+const THRESHOLDS = Object.freeze({
+  recent_ms: 7 * 24 * 60 * 60 * 1000,
+  quiet_ms: 30 * 24 * 60 * 60 * 1000,
+  stale_ms: 90 * 24 * 60 * 60 * 1000,
+});
+
+function resolveThresholds() {
+  const raw = process.env.MINDRIAN_TIMELINE_THRESHOLDS_JSON;
+  if (!raw) return THRESHOLDS;
+  try {
+    const parsed = JSON.parse(raw);
+    const r = Number.isFinite(parsed.recent_ms) ? parsed.recent_ms : THRESHOLDS.recent_ms;
+    const q = Number.isFinite(parsed.quiet_ms) ? parsed.quiet_ms : THRESHOLDS.quiet_ms;
+    const s = Number.isFinite(parsed.stale_ms) ? parsed.stale_ms : THRESHOLDS.stale_ms;
+    if (!(r < q && q < s)) return THRESHOLDS;
+    return Object.freeze({ recent_ms: r, quiet_ms: q, stale_ms: s });
+  } catch (_) {
+    return THRESHOLDS;
+  }
+}
+
+// ---------- ISO + human delta helpers ----------
+
+function isoSecond(ms) {
+  if (!Number.isFinite(ms)) return '';
+  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function humanDelta(deltaMs) {
+  if (!Number.isFinite(deltaMs) || deltaMs < 0) return 'unknown';
+  const sec = Math.floor(deltaMs / 1000);
+  if (sec < 60) return sec + ' seconds ago';
+  const min = Math.floor(sec / 60);
+  if (min < 60) return min + ' minutes ago';
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return hr + ' hours ago';
+  const days = Math.floor(hr / 24);
+  if (days < 30) return days + ' days ago';
+  const months = Math.floor(days / 30);
+  if (months < 12) return months + ' months ago';
+  const years = Math.floor(days / 365);
+  return years + ' years ago';
+}
+
+// ---------- Section scoping (D-08) ----------
+
+function isInSection(sourcePath, sectionSlug) {
+  if (typeof sourcePath !== 'string' || typeof sectionSlug !== 'string') return false;
+  if (sourcePath === sectionSlug) return true;
+  return sourcePath.startsWith(sectionSlug + '/');
+}
+
+// ---------- Explanation strings (templated; colocated fallback) ----------
+//
+// The Phase 109-05 renderExplanation(kind, payload) signature does not directly
+// match the memory_event row shape returned by findRecentChanges, so we use a
+// colocated templated fallback that renders generic event_type + target_node_id.
+// Zero LLM in the loop -- the strings are pure string concatenation over typed
+// SQL fields.
+
+function oneLineExplain(row) {
+  // row = { eventType, targetNodeId, sourcePath, properties, createdAt }
+  const tgt = row && row.targetNodeId ? (' on ' + row.targetNodeId) : '';
+  const evt = (row && row.eventType) ? row.eventType : 'event';
+  return evt + tgt;
+}
+
+// ---------- The renderer ----------
+
+function renderTimeline(db, sectionSlug, opts) {
+  const options = opts || {};
+  const now_ms = Number.isFinite(options.now_ms) ? options.now_ms : Date.now();
+  const thresholds = resolveThresholds();
+
+  // 1. Summary stats (first / last / total) via the new navigation primitive (D-08 scoping).
+  const summary = navigation.firstCapturedLastTouchedBySection(db, sectionSlug);
+
+  // Empty-state branch (D-05): zero memory_event rows scoped to the section.
+  if (summary.total_events === 0) {
+    return {
+      markdown_body: '*No timeline events yet.*',
+      summary_stats: { total_events: 0, n_recent: 0, n_quiet: 0, n_stale: 0, n_dormant: 0 },
+    };
+  }
+
+  // 2. Recent events (within recent_ms; section-scoped post-fetch filter).
+  // findRecentChanges returns rows for the WHOLE room; we filter by sourcePath per D-08.
+  const recentLookback = thresholds.recent_ms;
+  let allRecent = [];
+  try {
+    allRecent = navigation.findRecentChanges(db, now_ms - recentLookback, { limit: 200 }) || [];
+  } catch (_) { allRecent = []; }
+  const scopedRecent = allRecent.filter((r) => isInSection(r.sourcePath, sectionSlug));
+  const topRecent = scopedRecent.slice(0, 5);
+
+  // 3. Flagged stale: rows whose delta sits in the [quiet_ms .. stale_ms) window.
+  let allStaleWindow = [];
+  try {
+    const sinceStale = now_ms - thresholds.stale_ms;
+    const allWindow = navigation.findRecentChanges(db, sinceStale, { limit: 500 }) || [];
+    allStaleWindow = allWindow.filter((r) => isInSection(r.sourcePath, sectionSlug)
+      && Number.isFinite(r.createdAt)
+      && (now_ms - r.createdAt) >= thresholds.quiet_ms
+      && (now_ms - r.createdAt) < thresholds.stale_ms);
+  } catch (_) { allStaleWindow = []; }
+  const topStale = allStaleWindow.slice(0, 5);
+
+  // 4. Health buckets across ALL memory_event rows scoped to the section.
+  let allRows = [];
+  try {
+    allRows = navigation.findRecentChanges(db, 0, { limit: 10000 }) || [];
+  } catch (_) { allRows = []; }
+  const scoped = allRows.filter((r) => isInSection(r.sourcePath, sectionSlug)
+    && Number.isFinite(r.createdAt));
+  let n_recent = 0, n_quiet = 0, n_stale = 0, n_dormant = 0;
+  for (const r of scoped) {
+    const delta = now_ms - r.createdAt;
+    if (delta < thresholds.recent_ms) n_recent += 1;
+    else if (delta < thresholds.quiet_ms) n_quiet += 1;
+    else if (delta < thresholds.stale_ms) n_stale += 1;
+    else n_dormant += 1;
+  }
+
+  // 5. Assemble the D-05 markdown body.
+  const lines = [];
+  const firstIso = isoSecond(summary.first_captured_ms);
+  const lastIso = isoSecond(summary.last_touched_ms);
+  const lastDeltaHuman = humanDelta(now_ms - summary.last_touched_ms);
+  const nowIso = isoSecond(now_ms);
+  lines.push('*Last refreshed: ' + nowIso + '. ' + summary.total_events + ' insight events, first captured '
+    + firstIso + ', last touched ' + lastIso + ' (' + lastDeltaHuman + ').*');
+  lines.push('');
+  lines.push('**Recent events** (within 7 days, top 5):');
+  if (topRecent.length === 0) {
+    lines.push('- (none in the last 7 days)');
+  } else {
+    for (const r of topRecent) {
+      lines.push('- ' + isoSecond(r.createdAt) + ': ' + (r.eventType || 'event') + ' -- ' + oneLineExplain(r));
+    }
+  }
+  lines.push('');
+  lines.push('**Flagged stale** (over 30 days untouched, top 5):');
+  if (topStale.length === 0) {
+    lines.push('- (none over 30 days untouched)');
+  } else {
+    for (const r of topStale) {
+      const tgt = r.targetNodeId || '(unscoped)';
+      lines.push('- ' + isoSecond(r.createdAt) + ': ' + (r.eventType || 'event') + ' on ' + tgt
+        + ' -- last touched ' + humanDelta(now_ms - r.createdAt));
+    }
+  }
+  lines.push('');
+  lines.push('**Health:** recent=' + n_recent + ' / quiet=' + n_quiet + ' / stale=' + n_stale
+    + ' / dormant=' + n_dormant + '.');
+
+  return {
+    markdown_body: lines.join('\n'),
+    summary_stats: { total_events: summary.total_events, n_recent, n_quiet, n_stale, n_dormant },
+  };
+}
+
+module.exports = { renderTimeline, THRESHOLDS, resolveThresholds, isoSecond, humanDelta, isInSection };