@mindrian_os/install 1.13.0-beta.11

package/lib/core/statusline-cache.cjs

@@ -0,0 +1,266 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 88.1-04 -- statusline MINTO segment cache + format helpers
+ * =================================================================
+ * Pure, disk-backed, 5-second TTL cache for the Claude Code statusline
+ * MINTO segment. The statusline fires once per turn via scripts/context-monitor
+ * and must stay within a 300ms render budget (CONTEXT R1 mitigation).
+ *
+ * Cold path (no cache):  readTriple + cache write. Target < 200ms on fresh WSL2.
+ * Warm path (cache hit): JSON parse + string format. Target < 10ms.
+ *
+ * The cache is LOCAL by construction per Canon Part 8: all writes land at
+ * roomRoot/.mindrian/statusline-cache.json and never egress. No Brain calls,
+ * no fetch, no external endpoints.
+ *
+ * Canon references:
+ *   Part 2  UI glyph vocabulary -- classifyHealth emits check / warn / low / --
+ *     for the MINTO reasoning_health_score (shared with
+ *     lib/memory/triple-context-formatter.cjs + Phase 88.1-03 hook sysmsg
+ *     retrofit so rendering is byte-identical across surfaces).
+ *   Part 3  Tri-Context Decision Gate -- statusline renders LOCAL only.
+ *     Never BRAIN (BRAIN payloads are generic methodology only), never SIGNAL
+ *     (SIGNAL belongs to scheduled sweeps, not per-turn UI).
+ *   Part 8  Graph Boundary -- all cached bytes describe this specific user's
+ *     room state. They stay in this room. The boundary is architectural.
+ *
+ * Composes with:
+ *   Phase 87-02  atomic write pattern (openSync('wx') + fsync + rename) for
+ *     concurrent-safe cache persistence under rapid-statusline-fire.
+ *   Phase 88-01  folder-memory.readTriple(sectionPath) is the read contract;
+ *     cached 'triple' values are the shape readTriple returns.
+ *   Phase 88-07 / 88.1-03  classifyHealth shared vocabulary so every L3
+ *     surface (session-start sysmsg, guardian, statusline, /mos:status) uses
+ *     the same glyph classifier.
+ *
+ * Pure CJS, node built-ins only, zero npm dependencies. Three-surface
+ * compatible by construction (CLI + Desktop MCP + Cowork).
+ *
+ * API:
+ *   TTL_MS                                       -- number, fixed at 5000ms.
+ *   getCached(roomRoot, sectionPath)             -> {value, fresh}
+ *   setCached(roomRoot, sectionPath, triple)     -> void (graceful on error)
+ *   truncateGoverningThought(str)                -> string (60-char budget)
+ *   classifyHealth(score)                        -> 'check'|'warn'|'low'|'--'
+ *
+ * Cache file shape:
+ *   { ts: number, sectionPath: string, triple: object }
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ---------- Tunables (frozen invariants) ----------
+
+// 5-second TTL per CONTEXT R1 mitigation. Short enough that users perceive
+// freshness (a change to MINTO.md shows up on the next statusline tick after
+// 5s), long enough that 12 statusline fires/min all hit the warm path.
+const TTL_MS = 5000;
+
+// 60-char budget for the governing_thought segment. Matches the description-
+// discipline budget from Plan 88.1-01 so the statusline honors the same
+// text-economy contract the rest of L3 uses.
+const GOVERNING_THOUGHT_BUDGET = 60;
+
+// Cache filename under roomRoot/.mindrian/. Named separately from the Phase
+// 88-06 session-snapshot.json to avoid any cross-purpose coupling.
+const CACHE_FILENAME = 'statusline-cache.json';
+
+// ---------- Path helpers ----------
+
+function cacheDir(roomRoot) {
+  return path.join(roomRoot, '.mindrian');
+}
+
+function cacheFile(roomRoot) {
+  return path.join(cacheDir(roomRoot), CACHE_FILENAME);
+}
+
+// ---------- classifyHealth (shared with triple-context-formatter) ----------
+//
+// Canon Part 2 glyph vocabulary: check / warn / low / --. Byte-identical to
+// the classifier extracted in Phase 88.1-03 so the statusline, the hook
+// systemMessage retrofit, and the TRIPLE_CONTEXT formatter all render the
+// same glyph for the same score. See lib/memory/triple-context-formatter.cjs
+// lines 80-101 for the canonical source; this copy mirrors it for zero-cost
+// import from lib/core/ consumers that should not reach into lib/memory/.
+//
+// Signature: classifyHealth(score: number | null | undefined)
+//   -> 'check' | 'warn' | 'low' | '--'
+
+function classifyHealth(score) {
+  if (typeof score !== 'number' || !Number.isFinite(score)) return '--';
+  if (score >= 0.7) return 'check';
+  if (score >= 0.4) return 'warn';
+  return 'low';
+}
+
+// ---------- truncateGoverningThought ----------
+
+/**
+ * truncateGoverningThought
+ *   Enforce the 60-char statusline budget on a governing_thought string.
+ *   Short inputs (<= 60 chars) pass through byte-identical. Long inputs are
+ *   truncated to 59 chars plus a Unicode ellipsis (U+2026) for a total of
+ *   exactly 60 chars. Non-string / empty inputs return the empty string.
+ */
+function truncateGoverningThought(str) {
+  if (typeof str !== 'string') return '';
+  if (str.length <= GOVERNING_THOUGHT_BUDGET) return str;
+  // 59 chars + 1 ellipsis = exactly 60 chars, matching the budget.
+  return str.slice(0, GOVERNING_THOUGHT_BUDGET - 1) + '\u2026';
+}
+
+// ---------- Disk read ----------
+
+function safeReadSync(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * getCached(roomRoot, sectionPath) -> {value, fresh}
+ *
+ * Returns {value: null, fresh: false} when:
+ *   - cache file does not exist
+ *   - cache file is malformed JSON
+ *   - cache entry belongs to a different sectionPath
+ *   - cache entry is older than TTL_MS
+ *
+ * Returns {value: triple, fresh: true} on a warm hit. The statusline reads
+ * the triple fields directly (reasoning.governing_thought,
+ * reasoning.reasoning_health_score, reasoning.is_stale).
+ *
+ * Never throws. Graceful fallback on every error path.
+ */
+function getCached(roomRoot, sectionPath) {
+  const miss = { value: null, fresh: false };
+  if (!roomRoot || !sectionPath) return miss;
+
+  const file = cacheFile(roomRoot);
+  const raw = safeReadSync(file);
+  if (raw === null) return miss;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (_e) {
+    return miss;
+  }
+
+  if (!parsed || typeof parsed !== 'object') return miss;
+  if (parsed.sectionPath !== sectionPath) return miss;
+  if (typeof parsed.ts !== 'number' || !Number.isFinite(parsed.ts)) return miss;
+
+  const age = Date.now() - parsed.ts;
+  if (age < 0 || age >= TTL_MS) {
+    return { value: null, fresh: false };
+  }
+  if (!parsed.triple || typeof parsed.triple !== 'object') return miss;
+
+  return { value: parsed.triple, fresh: true };
+}
+
+// ---------- Disk write (atomic) ----------
+
+/**
+ * setCached(roomRoot, sectionPath, triple) -> void
+ *
+ * Atomic write sequence (Phase 87-02 pattern):
+ *   - mkdir -p roomRoot/.mindrian/ (idempotent)
+ *   - openSync('wx') on a pid-scoped tmp file
+ *   - writeSync + fsyncSync + closeSync
+ *   - renameSync over the real cache file
+ *
+ * Graceful fallback: any filesystem error (EEXIST on tmp, EACCES on mkdir,
+ * ENOENT on rename, disk full, etc.) is swallowed silently. The cache is
+ * a performance optimization; a failed write must NEVER bubble up to
+ * context-monitor because the statusline has to render regardless.
+ *
+ * Never throws. This is the Part 8-by-construction guarantee: a pure
+ * persistence side-effect that cannot leak state anywhere except the
+ * LOCAL roomRoot/.mindrian/ directory.
+ */
+function setCached(roomRoot, sectionPath, triple) {
+  if (!roomRoot || !sectionPath) return;
+
+  const dir = cacheDir(roomRoot);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (_e) {
+    // If mkdir fails (e.g. .mindrian is a regular file, not a directory),
+    // bail out silently. Graceful-fallback invariant.
+    return;
+  }
+
+  const payload = {
+    ts: Date.now(),
+    sectionPath: sectionPath,
+    triple: triple,
+  };
+
+  let serialized;
+  try {
+    serialized = JSON.stringify(payload);
+  } catch (_e) {
+    // Cyclic references in triple -> serialization failure. Bail.
+    return;
+  }
+
+  const finalPath = cacheFile(roomRoot);
+  const tmpPath = finalPath + '.tmp.' + process.pid + '.statusline';
+
+  let fd;
+  try {
+    fd = fs.openSync(tmpPath, 'wx');
+  } catch (e) {
+    if (e && e.code === 'EEXIST') {
+      // Stale tmp from a prior crash owned by the same pid slot. Clean and
+      // retry once. Any second failure is swallowed.
+      try { fs.unlinkSync(tmpPath); } catch (_) {}
+      try {
+        fd = fs.openSync(tmpPath, 'wx');
+      } catch (_e2) {
+        return;
+      }
+    } else {
+      return;
+    }
+  }
+
+  try {
+    fs.writeSync(fd, serialized);
+    try { fs.fsyncSync(fd); } catch (_) { /* fsync best-effort */ }
+  } catch (_e) {
+    try { fs.closeSync(fd); } catch (_) {}
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    return;
+  } finally {
+    try { fs.closeSync(fd); } catch (_) {}
+  }
+
+  try {
+    fs.renameSync(tmpPath, finalPath);
+  } catch (_e) {
+    // Rename failed. Clean up tmp and bail.
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    return;
+  }
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  TTL_MS: TTL_MS,
+  GOVERNING_THOUGHT_BUDGET: GOVERNING_THOUGHT_BUDGET,
+  getCached: getCached,
+  setCached: setCached,
+  truncateGoverningThought: truncateGoverningThought,
+  classifyHealth: classifyHealth,
+};

package/lib/core/token-estimator.cjs

@@ -0,0 +1,348 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 88.1-16 -- query-efficiency token estimator + aggregation math.
+ * =====================================================================
+ * Pure utility module consumed by two callers:
+ *
+ *   1. scripts/query-efficiency-telemetry.cjs (PostToolUse hook) uses
+ *      estimateTokens(payload) to measure tokens_used per Read|Grep|Glob
+ *      return, and estimateRoomTokens(roomRoot) to compute the
+ *      tokens_naive_estimate baseline that defines the 57x efficiency claim.
+ *
+ *   2. scripts/scout-telemetry-aggregator.cjs (aggregation helper spawned
+ *      by /mos:scout) uses aggregateEvents(events) to render the median
+ *      ratio + top-5 commands + threshold-status summary.
+ *
+ * Canon:
+ *   Part 6 Product-as-Venture -- the 57x token-efficiency claim is a
+ *     venture claim; without this measurement arm it is marketing copy.
+ *     This module is the measurement arm: the ratio it produces is the
+ *     release-gate signal (>= 40x PASS; < 40x RETUNE) per CONTEXT
+ *     criterion #15.
+ *   Part 8 Graph Boundary -- LOCAL-by-construction. Zero http/https
+ *     imports, zero child_process, zero network egress. Only fs reads
+ *     (for estimateRoomTokens walking .md files). The caller hooks
+ *     persist ONLY scalar integer counts to the JSONL; no user-artifact
+ *     bytes reach the telemetry file.
+ *
+ * Design notes:
+ *   - estimateTokens uses the chars/4 approximation established by
+ *     lib/memory/triple-context-formatter.cjs (Phase 88-07). Consistency
+ *     across the codebase matters: if the Phase 88-07 formatter reports
+ *     "this emission is 3825 tokens", the telemetry hook must estimate
+ *     with the same yardstick so ratios compare apples-to-apples.
+ *
+ *   - estimateRoomTokens uses a module-level in-memory cache keyed by
+ *     absolute room path. First call walks the tree summing .md file
+ *     sizes; subsequent calls return the cached value. The cache is
+ *     session-scoped (cleared when the Node process exits). A ledger
+ *     cache is NOT persisted to disk because:
+ *       (a) the estimator is fast enough (single walk of a room tree
+ *           typically completes in < 50ms on commodity SSDs), and
+ *       (b) on-disk caches introduce invalidation complexity that is
+ *           unnecessary for a per-session approximation used as the
+ *           denominator of a ratio. Staleness by up to one session is
+ *           within the noise floor of the measurement itself.
+ *
+ *   - validateEventShape enforces the 8-field contract specified in
+ *     88.1-16 PLAN <interfaces>. The hook uses this as a pre-write guard
+ *     so a malformed event can never reach the JSONL.
+ *
+ *   - aggregateEvents reduces a raw event stream to { median, mean, top5,
+ *     count }. Top-5 is computed per-command (taking the MAX ratio
+ *     observed for each command) so a single command cannot occupy
+ *     multiple slots. This matches the CONTEXT-specified "top 5 commands
+ *     by ratio" rendering.
+ *
+ *   - classifyRatio maps a numeric ratio to { 'normal' | 'warn' } at the
+ *     10x threshold per PLAN <action>. Below-10x arms the hook's warn
+ *     systemMessage; at-or-above 10x stays silent (no verification fatigue
+ *     per Plan 03 reviewer R5).
+ *
+ * API:
+ *   estimateTokens(str)                -> integer >= 0
+ *   estimateRoomTokens(roomRoot)       -> integer >= 0 | null
+ *   clearCache()                       -> void  (test hygiene)
+ *   validateEventShape(obj)            -> { valid, missing:string[] }
+ *   classifyRatio(ratio)               -> 'normal' | 'warn'
+ *   aggregateEvents(events)            -> { count, median, mean, top5 }
+ *   EVENT_REQUIRED_FIELDS              -> readonly string[]
+ *   BELOW_THRESHOLD_RATIO              -> 10
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ---------- Constants ----------
+
+// Classification threshold for below-10x warn emission. Canon: anything
+// <10x is a leakage signal (query is pulling more room context than it
+// needs). This is the hook's advisory trigger, not the 57x release gate.
+const BELOW_THRESHOLD_RATIO = 10;
+
+// 8-field contract per 88.1-16 PLAN <interfaces>. validateEventShape
+// enforces this on every event before it is appended to the JSONL.
+const EVENT_REQUIRED_FIELDS = Object.freeze([
+  'event',
+  'ts',
+  'command',
+  'tool',
+  'tokens_used',
+  'tokens_naive_estimate',
+  'ratio',
+  'room_slug',
+]);
+
+// Max depth guard for the estimateRoomTokens walker. Rooms are expected
+// to be shallow (<10 levels). A runaway symlink loop or surprise deep
+// tree must not hang the hook.
+const MAX_ROOM_DEPTH = 12;
+
+// ---------- Module-level session cache ----------
+//
+// Key: absolute, resolved room path (realpath when possible).
+// Value: cached token count (integer).
+// Cleared via clearCache() for tests; otherwise persists for the life
+// of the Node process (i.e. for the duration of a single hook fork or
+// scout invocation).
+const roomTokenCache = new Map();
+
+// ---------- estimateTokens ----------
+
+/**
+ * estimateTokens(str) -> integer >= 0
+ *
+ * Chars-over-4 estimator, matching Phase 88-07 triple-context-formatter.
+ * Graceful on null / undefined / non-string: returns 0. This matches the
+ * behavior established by formatter.estimateTokens so the two producers
+ * are interchangeable.
+ */
+function estimateTokens(str) {
+  if (typeof str !== 'string') return 0;
+  if (str.length === 0) return 0;
+  return Math.ceil(str.length / 4);
+}
+
+// ---------- estimateRoomTokens ----------
+
+/**
+ * Walk the room tree summing the byte-length of every .md file, divide
+ * by 4 to approximate tokens. Skips non-.md files (binaries, images,
+ * generated JSON, etc.) so the denominator of the efficiency ratio
+ * reflects ONLY the text payload a naive whole-room ingestion would
+ * consume.
+ *
+ * Uses fs.readdirSync with withFileTypes so a single syscall per
+ * directory yields both names and types; avoids the stat-per-entry
+ * overhead that a readdir+stat loop would incur.
+ *
+ * Returns null on:
+ *   - invalid input (non-string, empty string, null, undefined)
+ *   - path does not exist
+ *   - path is not a directory
+ *   - any error during the walk (defensive; the hook must never throw)
+ *
+ * Caches the result in module-level roomTokenCache keyed by the resolved
+ * path. Second call returns cached value without re-walking; this is the
+ * property test 5 asserts.
+ */
+function estimateRoomTokens(roomRoot) {
+  if (typeof roomRoot !== 'string' || roomRoot.length === 0) return null;
+
+  // Cache hit?
+  if (roomTokenCache.has(roomRoot)) {
+    return roomTokenCache.get(roomRoot);
+  }
+
+  let stat;
+  try {
+    stat = fs.statSync(roomRoot);
+  } catch (_e) {
+    return null;
+  }
+  if (!stat || !stat.isDirectory()) return null;
+
+  let totalChars = 0;
+
+  function walk(dir, depth) {
+    if (depth > MAX_ROOM_DEPTH) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_e) {
+      return; // permission denied, vanished dir, etc.
+    }
+    for (const entry of entries) {
+      if (!entry) continue;
+      const name = entry.name;
+      // Skip hidden directories / files starting with '.' (e.g. .git,
+      // .mindrian, .obsidian). Counting them would over-estimate the
+      // naive baseline and dilute the ratio.
+      if (typeof name === 'string' && name.length > 0 && name[0] === '.') continue;
+      const full = path.join(dir, name);
+      if (entry.isDirectory()) {
+        walk(full, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue; // skip symlinks, sockets, devices
+      // Only count .md files.
+      if (!/\.md$/i.test(name)) continue;
+      try {
+        const s = fs.statSync(full);
+        if (s && typeof s.size === 'number') {
+          totalChars += s.size;
+        }
+      } catch (_e) { /* vanished file, skip */ }
+    }
+  }
+
+  try {
+    walk(roomRoot, 0);
+  } catch (_e) {
+    return null;
+  }
+
+  const tokens = Math.ceil(totalChars / 4);
+  roomTokenCache.set(roomRoot, tokens);
+  return tokens;
+}
+
+// ---------- clearCache ----------
+
+/**
+ * Reset the session cache. Used by tests for deterministic between-case
+ * isolation; production callers typically do not need to invoke this
+ * (process lifetime bounds the cache naturally).
+ */
+function clearCache() {
+  roomTokenCache.clear();
+}
+
+// ---------- validateEventShape ----------
+
+/**
+ * Return { valid, missing } for a telemetry event object. An event is
+ * valid iff every field in EVENT_REQUIRED_FIELDS is present AND
+ * non-null / non-undefined. The hook uses this as a write guard: a
+ * malformed event must never reach the JSONL (prevents aggregation
+ * NaN poisoning later).
+ */
+function validateEventShape(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { valid: false, missing: EVENT_REQUIRED_FIELDS.slice() };
+  }
+  const missing = [];
+  for (let i = 0; i < EVENT_REQUIRED_FIELDS.length; i += 1) {
+    const k = EVENT_REQUIRED_FIELDS[i];
+    const v = obj[k];
+    if (v === undefined || v === null) missing.push(k);
+  }
+  return { valid: missing.length === 0, missing: missing };
+}
+
+// ---------- classifyRatio ----------
+
+/**
+ * Classify a ratio into 'normal' or 'warn' at the 10x threshold.
+ * Defensive: any non-finite or non-numeric input -> 'warn' (the ratio
+ * was never computed correctly, which is itself a signal the hook
+ * should surface).
+ */
+function classifyRatio(ratio) {
+  if (typeof ratio !== 'number' || !Number.isFinite(ratio)) return 'warn';
+  if (ratio >= BELOW_THRESHOLD_RATIO) return 'normal';
+  return 'warn';
+}
+
+// ---------- aggregateEvents ----------
+
+/**
+ * Reduce an event stream to { count, median, mean, top5 }.
+ *
+ * - count:  events.length.
+ * - median: midpoint of the sorted ratios. Even-length: average of the
+ *           two middle values. Odd-length: the middle value.
+ * - mean:   arithmetic mean of ratios, rounded to 1 decimal for display
+ *           friendliness in the scout render.
+ * - top5:   up to 5 entries, sorted descending by ratio, deduped by
+ *           command (each command appears at most once, with its MAX
+ *           observed ratio).
+ *
+ * Empty input -> { count:0, median:null, mean:null, top5:[] }.
+ *
+ * Filters out malformed events (missing or non-numeric ratio) so a
+ * corrupt JSONL line cannot poison the aggregate.
+ */
+function aggregateEvents(events) {
+  const out = { count: 0, median: null, mean: null, top5: [] };
+  if (!Array.isArray(events) || events.length === 0) return out;
+
+  // Collect only well-formed ratio values. A malformed event counts
+  // toward `count` (reported events) but NOT toward median/mean/top5.
+  const ratios = [];
+  const byCommand = new Map(); // command -> max ratio
+  for (let i = 0; i < events.length; i += 1) {
+    const e = events[i];
+    if (!e || typeof e !== 'object') continue;
+    const r = e.ratio;
+    if (typeof r !== 'number' || !Number.isFinite(r)) continue;
+    ratios.push(r);
+    const cmd = typeof e.command === 'string' && e.command.length > 0
+      ? e.command
+      : '(unknown)';
+    const prev = byCommand.get(cmd);
+    if (prev === undefined || r > prev) byCommand.set(cmd, r);
+  }
+
+  out.count = events.length;
+
+  if (ratios.length === 0) return out;
+
+  // Median: sort asc, pick middle.
+  const sorted = ratios.slice().sort(function (a, b) { return a - b; });
+  const n = sorted.length;
+  if (n % 2 === 1) {
+    out.median = sorted[(n - 1) / 2];
+  } else {
+    const lo = sorted[(n / 2) - 1];
+    const hi = sorted[n / 2];
+    out.median = (lo + hi) / 2;
+  }
+
+  // Mean, 1-decimal rounded for display.
+  let sum = 0;
+  for (let i = 0; i < n; i += 1) sum += sorted[i];
+  const rawMean = sum / n;
+  out.mean = Math.round(rawMean * 10) / 10;
+
+  // Top-5 per-command, sorted desc by ratio. Ties broken by command
+  // name for determinism.
+  const pairs = [];
+  const keys = Array.from(byCommand.keys());
+  for (let i = 0; i < keys.length; i += 1) {
+    pairs.push({ command: keys[i], ratio: byCommand.get(keys[i]) });
+  }
+  pairs.sort(function (a, b) {
+    if (b.ratio !== a.ratio) return b.ratio - a.ratio;
+    return a.command < b.command ? -1 : a.command > b.command ? 1 : 0;
+  });
+  out.top5 = pairs.slice(0, 5);
+
+  return out;
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  BELOW_THRESHOLD_RATIO: BELOW_THRESHOLD_RATIO,
+  EVENT_REQUIRED_FIELDS: EVENT_REQUIRED_FIELDS,
+  estimateTokens: estimateTokens,
+  estimateRoomTokens: estimateRoomTokens,
+  clearCache: clearCache,
+  validateEventShape: validateEventShape,
+  classifyRatio: classifyRatio,
+  aggregateEvents: aggregateEvents,
+};