mindforge-cc 8.2.0 → 10.0.0

package/bin/autonomous/state-manager.js

@@ -0,0 +1,116 @@
+/**
+ * MindForge — State Manager
+ * Extracted from auto-runner.js — handles state transitions, HANDOFF.json and
+ * auto-state.json read/write, and phase management.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const VALID_PHASES = ['idle', 'planning', 'executing', 'verifying', 'complete', 'running', 'paused', 'completed'];
+
+/**
+ * Creates a state manager for the given planning directory.
+ * @param {string} planningDir — Absolute path to the .planning directory
+ * @returns {{ getState, updateState, transition, readHandoff, writeHandoff }}
+ */
+function createStateManager(planningDir) {
+  const statePath = path.join(planningDir, 'auto-state.json');
+  const handoffPath = path.join(planningDir, 'HANDOFF.json');
+
+  /**
+   * Reads the current state from auto-state.json.
+   * Returns a fresh object (never a shared reference).
+   */
+  function getState() {
+    if (!fs.existsSync(statePath)) {
+      return Object.create(null);
+    }
+
+    try {
+      const raw = fs.readFileSync(statePath, 'utf8');
+      const parsed = JSON.parse(raw);
+      return sanitizeState(parsed);
+    } catch (e) {
+      // Corrupt state file — return empty
+      return Object.create(null);
+    }
+  }
+
+  /**
+   * Merges a patch into the current state (immutable — writes new object to disk).
+   * @param {object} patch — Key/value pairs to merge
+   */
+  function updateState(patch) {
+    const current = getState();
+    const merged = Object.assign(Object.create(null), current, patch);
+    fs.writeFileSync(statePath, JSON.stringify(merged, null, 2));
+    return merged;
+  }
+
+  /**
+   * Transitions the state to a new status phase.
+   * @param {string} newPhase — One of: idle, planning, executing, verifying, complete, running, paused, completed
+   */
+  function transition(newPhase) {
+    if (!VALID_PHASES.includes(newPhase)) {
+      throw new Error(`Invalid state transition target: "${newPhase}". Valid: ${VALID_PHASES.join(', ')}`);
+    }
+    return updateState({
+      status: newPhase,
+      lastTransition: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * Reads and parses HANDOFF.json. Throws if missing or malformed.
+   * @returns {object} Parsed handoff data (fresh object)
+   */
+  function readHandoff() {
+    if (!fs.existsSync(handoffPath)) {
+      throw new Error('HANDOFF.json not found — run /mindforge:plan-phase first');
+    }
+
+    let handoff;
+    try {
+      handoff = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+    } catch (e) {
+      throw new Error(`HANDOFF.json is malformed: ${e.message}`);
+    }
+
+    if (!handoff.handoffs || !Array.isArray(handoff.handoffs)) {
+      throw new Error('HANDOFF.json has no handoffs array');
+    }
+
+    return handoff;
+  }
+
+  /**
+   * Writes data to HANDOFF.json (immutable — creates new file contents).
+   * @param {object} data — The handoff object to persist
+   */
+  function writeHandoff(data) {
+    const timestamped = Object.assign(Object.create(null), data, {
+      last_updated: new Date().toISOString(),
+    });
+    fs.writeFileSync(handoffPath, JSON.stringify(timestamped, null, 2) + '\n');
+    return timestamped;
+  }
+
+  return Object.freeze({ getState, updateState, transition, readHandoff, writeHandoff });
+}
+
+/**
+ * Sanitizes parsed JSON to prevent prototype pollution.
+ */
+function sanitizeState(parsed) {
+  const clean = Object.create(null);
+  for (const key of Object.keys(parsed)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+    clean[key] = parsed[key];
+  }
+  return clean;
+}
+
+module.exports = { createStateManager };

package/bin/autonomous/task-dispatcher.js

@@ -0,0 +1,114 @@
+/**
+ * MindForge — Task Dispatcher
+ * Extracted from auto-runner.js — handles task parsing from HANDOFF.json,
+ * task queue management, task prioritization, and dispatch logic.
+ */
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Parses a HANDOFF.json file content into a normalized task list.
+ * @param {object} handoffData — Parsed HANDOFF.json object (must have .handoffs array)
+ * @returns {Array<{ id: string, name: string, plan: string|null, depends_on: string[], wave: number }>}
+ */
+function parseHandoff(handoffData) {
+  if (!handoffData || !Array.isArray(handoffData.handoffs)) {
+    throw new Error('Invalid handoff data — missing handoffs array');
+  }
+
+  return handoffData.handoffs.map(h => Object.freeze({
+    id: h.id || h.task_id || `task_${crypto.randomBytes(4).toString('hex')}`,
+    name: h.name || h.task || h.description || h.id || 'unnamed-task',
+    plan: h.plan || null,
+    depends_on: Array.isArray(h.depends_on) ? [...h.depends_on] : [],
+    wave: typeof h.wave === 'number' ? h.wave : null,
+  }));
+}
+
+/**
+ * Prioritizes tasks based on dependency depth and wave ordering.
+ * Tasks with fewer dependencies come first; within same depth, preserves original order.
+ * @param {Array} tasks — Normalized task list from parseHandoff
+ * @returns {Array} — New sorted array (input is not mutated)
+ */
+function prioritizeTasks(tasks) {
+  // Build a dependency depth map
+  const depthMap = new Map();
+
+  function getDepth(task, visited = new Set()) {
+    if (depthMap.has(task.id)) return depthMap.get(task.id);
+    if (visited.has(task.id)) return 0; // circular — break cycle
+    visited.add(task.id);
+
+    if (task.depends_on.length === 0) {
+      depthMap.set(task.id, 0);
+      return 0;
+    }
+
+    const maxParentDepth = task.depends_on.reduce((max, depId) => {
+      const parent = tasks.find(t => t.id === depId);
+      if (!parent) return max;
+      return Math.max(max, getDepth(parent, new Set(visited)));
+    }, 0);
+
+    const depth = maxParentDepth + 1;
+    depthMap.set(task.id, depth);
+    return depth;
+  }
+
+  // Compute depth for all tasks
+  for (const task of tasks) {
+    getDepth(task);
+  }
+
+  // Sort by wave first (if present), then by depth, then by original order
+  const indexed = tasks.map((task, i) => ({ task, originalIndex: i }));
+
+  const sorted = [...indexed].sort((a, b) => {
+    // Wave ordering first
+    const waveA = a.task.wave ?? Infinity;
+    const waveB = b.task.wave ?? Infinity;
+    if (waveA !== waveB) return waveA - waveB;
+
+    // Then by dependency depth
+    const depthA = depthMap.get(a.task.id) || 0;
+    const depthB = depthMap.get(b.task.id) || 0;
+    if (depthA !== depthB) return depthA - depthB;
+
+    // Preserve original order as tiebreaker
+    return a.originalIndex - b.originalIndex;
+  });
+
+  return sorted.map(item => item.task);
+}
+
+/**
+ * Dispatches a single task to an executor function.
+ * Returns the result wrapped in a status envelope.
+ * @param {object} task — A normalized task object
+ * @param {function} executor — async function(task) => result
+ * @returns {Promise<{ task_id: string, status: string, result?: any, error?: string, duration_ms: number }>}
+ */
+async function dispatchTask(task, executor) {
+  const start = Date.now();
+
+  try {
+    const result = await executor(task);
+    return Object.freeze({
+      task_id: task.id,
+      status: 'completed',
+      result,
+      duration_ms: Date.now() - start,
+    });
+  } catch (err) {
+    return Object.freeze({
+      task_id: task.id,
+      status: 'failed',
+      error: err.message,
+      duration_ms: Date.now() - start,
+    });
+  }
+}
+
+module.exports = { parseHandoff, prioritizeTasks, dispatchTask };

package/bin/autonomous/wave-executor.js

@@ -0,0 +1,169 @@
+/**
+ * MindForge — Wave Executor
+ * Extracted from auto-runner.js — handles wave orchestration: grouping tasks
+ * into waves, executing waves in sequence, and managing wave dependencies.
+ */
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Creates a wave executor with the given configuration.
+ * @param {object} config
+ * @param {function} [config.onTaskStart] — Called when a task begins
+ * @param {function} [config.onTaskComplete] — Called when a task finishes
+ * @param {function} [config.onTaskFail] — Called when a task fails
+ * @param {function} [config.onWaveStart] — Called when a wave begins
+ * @param {function} [config.onWaveComplete] — Called when a wave finishes
+ * @returns {{ planWaves, executeWave, getWaveStatus }}
+ */
+function createWaveExecutor(config = {}) {
+  const {
+    onTaskStart = () => {},
+    onTaskComplete = () => {},
+    onTaskFail = () => {},
+    onWaveStart = () => {},
+    onWaveComplete = () => {},
+  } = config;
+
+  // Internal state — immutable snapshots exposed via getWaveStatus
+  let waves = [];
+  let currentWaveIndex = 0;
+  let completedTasks = new Set();
+  let status = 'idle'; // idle | running | paused | completed
+
+  /**
+   * Groups handoff tasks into sequential waves based on wave field or dependency topology.
+   * Returns a new array of wave objects — does not mutate input.
+   * @param {Array} handoffs — Raw handoffs array from HANDOFF.json
+   * @returns {Array<{ wave: number, tasks: Array }>}
+   */
+  function planWaves(handoffs) {
+    if (!Array.isArray(handoffs) || handoffs.length === 0) {
+      waves = [];
+      return [];
+    }
+
+    const hasWaveField = handoffs.some(h => typeof h.wave === 'number');
+
+    if (hasWaveField) {
+      const byWave = new Map();
+      for (const h of handoffs) {
+        const w = h.wave ?? 0;
+        if (!byWave.has(w)) byWave.set(w, []);
+        byWave.get(w).push(normalizeTask(h));
+      }
+
+      waves = Array.from(byWave.entries())
+        .sort((a, b) => a[0] - b[0])
+        .map(([waveNum, tasks]) => Object.freeze({ wave: waveNum, tasks: Object.freeze(tasks) }));
+    } else {
+      // Single wave with all tasks
+      waves = [Object.freeze({
+        wave: 0,
+        tasks: Object.freeze(handoffs.map(normalizeTask)),
+      })];
+    }
+
+    currentWaveIndex = 0;
+    completedTasks = new Set();
+    status = 'idle';
+
+    return waves;
+  }
+
+  /**
+   * Executes a single wave — runs tasks sequentially, skipping already-completed ones.
+   * @param {object} wave — A wave object from planWaves
+   * @param {object} context — Execution context passed to callbacks
+   * @param {object} context.executor — async function(task) => result (performs actual work)
+   * @returns {Promise<{ completed: string[], failed: string[], skipped: string[] }>}
+   */
+  async function executeWave(wave, context = {}) {
+    const { executor = async () => {} } = context;
+    status = 'running';
+
+    const pending = wave.tasks.filter(t => !completedTasks.has(t.id));
+    const result = { completed: [], failed: [], skipped: [] };
+
+    onWaveStart({ wave: wave.wave, taskCount: pending.length });
+
+    for (const task of pending) {
+      const taskStart = Date.now();
+      onTaskStart({ task, wave: wave.wave });
+
+      try {
+        await executor(task);
+
+        const duration = Date.now() - taskStart;
+        completedTasks = new Set([...completedTasks, task.id]);
+        result.completed.push(task.id);
+
+        onTaskComplete({ task, wave: wave.wave, duration_ms: duration });
+      } catch (err) {
+        const duration = Date.now() - taskStart;
+        result.failed.push(task.id);
+
+        onTaskFail({ task, wave: wave.wave, error: err, duration_ms: duration });
+
+        // Re-throw to let caller decide on retry/escalation strategy
+        throw err;
+      }
+    }
+
+    currentWaveIndex++;
+    onWaveComplete({ wave: wave.wave, result });
+
+    if (currentWaveIndex >= waves.length) {
+      status = 'completed';
+    }
+
+    return Object.freeze(result);
+  }
+
+  /**
+   * Returns a snapshot of the current wave execution status.
+   */
+  function getWaveStatus() {
+    return Object.freeze({
+      status,
+      currentWaveIndex,
+      totalWaves: waves.length,
+      completedTasks: Array.from(completedTasks),
+      waves: waves.map(w => Object.freeze({
+        wave: w.wave,
+        taskCount: w.tasks.length,
+        completedCount: w.tasks.filter(t => completedTasks.has(t.id)).length,
+      })),
+    });
+  }
+
+  /**
+   * Restores progress from a previously saved state.
+   * @param {{ currentWaveIndex: number, completedTasks: string[] }} savedState
+   */
+  function restore(savedState) {
+    if (savedState && typeof savedState.currentWaveIndex === 'number') {
+      currentWaveIndex = savedState.currentWaveIndex;
+    }
+    if (savedState && Array.isArray(savedState.completedTasks)) {
+      completedTasks = new Set(savedState.completedTasks);
+    }
+  }
+
+  return Object.freeze({ planWaves, executeWave, getWaveStatus, restore });
+}
+
+/**
+ * Normalizes a raw handoff entry into a clean task object.
+ */
+function normalizeTask(h) {
+  return Object.freeze({
+    id: h.id || h.task_id || `task_${crypto.randomBytes(4).toString('hex')}`,
+    name: h.name || h.task || h.description || h.id || 'unnamed-task',
+    plan: h.plan || null,
+    depends_on: Array.isArray(h.depends_on) ? [...h.depends_on] : [],
+  });
+}
+
+module.exports = { createWaveExecutor };

package/bin/browser/browser-daemon.js

@@ -6,6 +6,7 @@
 'use strict';
 
 const http      = require('http');
+const crypto    = require('crypto');
 const playwright = require('playwright-core');
 const fs        = require('fs');
 const path      = require('path');
@@ -14,6 +15,26 @@ const PORT      = process.env.BROWSER_PORT || 7338;
 const HEADLESS  = process.env.BROWSER_HEADLESS !== 'false';
 const TIMEOUT   = (parseInt(process.env.BROWSER_IDLE_TIMEOUT_MINUTES) || 30) * 60 * 1000;
 
+// ── Bearer token authentication ──────────────────────────────────────────────
+const DAEMON_TOKEN = crypto.randomBytes(32).toString('hex');
+const DAEMON_TOKEN_FILE = path.join(process.cwd(), '.mindforge', '.browser-daemon-token');
+
+// Write token to file with restrictive permissions (owner-only read/write)
+fs.mkdirSync(path.dirname(DAEMON_TOKEN_FILE), { recursive: true });
+fs.writeFileSync(DAEMON_TOKEN_FILE, DAEMON_TOKEN, { mode: 0o600 });
+
+/**
+ * Validate bearer token from Authorization header.
+ * Returns true if valid, false otherwise.
+ */
+function isAuthValid(req) {
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith('Bearer ')) return false;
+  const provided = authHeader.slice(7);
+  if (provided.length !== DAEMON_TOKEN.length) return false;
+  return crypto.timingSafeEqual(Buffer.from(provided), Buffer.from(DAEMON_TOKEN));
+}
+
 let browser, lastActionAt = Date.now(), isLaunching = false;
 const sessions = new Map(); // name -> { context, page }
 
@@ -98,6 +119,9 @@ const server = http.createServer(async (req, res) => {
       }
 
       if (req.url === '/evaluate' && req.method === 'POST') {
+        if (!isAuthValid(req)) {
+          return send({ error: 'Authentication required. Use the token printed at daemon startup.' }, 401);
+        }
         const result = await page.evaluate(script);
         return send({ success: true, result });
       }
@@ -123,7 +147,11 @@ const server = http.createServer(async (req, res) => {
 });
 
 init().then(() => {
-  server.listen(PORT, '127.0.0.1', () => console.log(`[daemon] Browser daemon listening on port ${PORT}`));
+  server.listen(PORT, '127.0.0.1', () => {
+    console.log(`[BrowserDaemon] Listening on port ${PORT}`);
+    console.log(`[BrowserDaemon] Auth token: ${DAEMON_TOKEN}`);
+    console.log(`[BrowserDaemon] Token file: ${DAEMON_TOKEN_FILE}`);
+  });
 }).catch(err => {
   console.error('[daemon] Initialization failed:', err);
   process.exit(1);
@@ -131,6 +159,8 @@ init().then(() => {
 
 async function shutdown() {
   console.log('[daemon] Shutting down gracefully...');
+  // Remove sensitive token file on shutdown
+  if (fs.existsSync(DAEMON_TOKEN_FILE)) fs.unlinkSync(DAEMON_TOKEN_FILE);
   if (browser) await browser.close();
   process.exit(0);
 }

package/bin/change-classifier.js

@@ -6,7 +6,7 @@
 
 'use strict';
 
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 
 const SENSITIVE_PATHS = [
@@ -33,7 +33,7 @@ function classify() {
   try {
     // Get list of changed files compared to origin/main or HEAD~1
     const base = process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : 'HEAD~1';
-    const diffFiles = execSync(`git diff --name-only ${base}..HEAD`, { encoding: 'utf8' }).split('\n').filter(Boolean);
+    const diffFiles = execFileSync('git', ['diff', '--name-only', `${base}..HEAD`], { encoding: 'utf8' }).split('\n').filter(Boolean);
     
     let tier = 1;
     let reasons = [];
@@ -47,7 +47,7 @@ function classify() {
 
     // 2. Pattern-based detection in diff (Tier 3)
     if (tier < 3) {
-      const diffContent = execSync(`git diff ${base}..HEAD`, { encoding: 'utf8' });
+      const diffContent = execFileSync('git', ['diff', `${base}..HEAD`], { encoding: 'utf8' });
       for (const pattern of SENSITIVE_PATTERNS) {
         if (pattern.test(diffContent)) {
           tier = 3;

package/bin/dashboard/api-router.js

@@ -130,18 +130,29 @@ function register(app) {
   });
 
   // ── Steering (requires auto mode running) ───────────────────────────────────
+  const VALID_STEER_ACTIONS = ['pause', 'resume', 'switch_phase', 'priority_bump', 'skip_task', 'abort'];
+
   app.post('/api/steer', (req, res) => {
     try {
-      const { instruction, priority = 'normal' } = req.body || {};
+      const { action, params = {} } = req.body || {};
 
-      if (!instruction || typeof instruction !== 'string') {
-        return res.status(400).json({ error: 'Missing "instruction" field' });
+      // Validate action is present and in allowlist
+      if (!action || typeof action !== 'string') {
+        return res.status(400).json({
+          error: `Invalid action. Valid actions: ${VALID_STEER_ACTIONS.join(', ')}`
+        });
       }
-      if (instruction.length > 500) {
-        return res.status(400).json({ error: 'Instruction too long (max 500 chars)' });
+      if (!VALID_STEER_ACTIONS.includes(action)) {
+        return res.status(400).json({
+          error: `Invalid action. Valid actions: ${VALID_STEER_ACTIONS.join(', ')}`
+        });
       }
-      if (!['normal', 'urgent', 'stop'].includes(priority)) {
-        return res.status(400).json({ error: 'Invalid priority. Use: normal|urgent|stop' });
+
+      // If params contains freeText, cap at 200 characters
+      if (params.freeText && typeof params.freeText === 'string') {
+        if (params.freeText.length > 200) {
+          return res.status(400).json({ error: 'params.freeText exceeds 200 character limit' });
+        }
       }
 
       // Check auto mode is running
@@ -153,24 +164,12 @@ function register(app) {
         return res.status(409).json({ error: 'Auto mode is not running. Steering has no effect.' });
       }
 
-      // Run injection guard
-      const INJECTION_PATTERNS = [
-        /IGNORE ALL PREVIOUS INSTRUCTIONS/i,
-        /DISREGARD YOUR INSTRUCTIONS/i,
-        /FORGET YOUR TRAINING/i,
-        /YOUR NEW INSTRUCTIONS ARE/i,
-        /OVERRIDE:/i,
-      ];
-      if (INJECTION_PATTERNS.some(p => p.test(instruction))) {
-        return res.status(400).json({ error: 'Instruction rejected: contains prohibited patterns' });
-      }
-
       // Write to steering queue
       const entry = {
         id:          require('crypto').randomBytes(8).toString('hex'),
         timestamp:   new Date().toISOString(),
-        instruction: instruction.trim(),
-        priority,
+        action,
+        params,
         authored_by: 'dashboard',
         applies_to:  'all',
         status:      'queued',
@@ -183,7 +182,7 @@ function register(app) {
       }
       fs.appendFileSync(STEERING_QUEUE, JSON.stringify(entry) + '\n');
 
-      res.json({ success: true, queued: true, id: entry.id, priority });
+      res.json({ success: true, queued: true, id: entry.id, action });
     } catch (err) {
       res.status(500).json({ error: err.message });
     }

package/bin/dashboard/metrics-aggregator.js

@@ -8,6 +8,24 @@
 const fs   = require('fs');
 const path = require('path');
 
+// ── TTL Cache (5-second window) ──────────────────────────────────────────────
+const _cache = new Map();
+const CACHE_TTL_MS = 5000;
+
+function cacheGet(key) {
+  const entry = _cache.get(key);
+  if (!entry) return undefined;
+  if (Date.now() - entry.timestamp >= CACHE_TTL_MS) {
+    _cache.delete(key);
+    return undefined;
+  }
+  return entry.data;
+}
+
+function cacheSet(key, data) {
+  _cache.set(key, { data, timestamp: Date.now() });
+}
+
 // Paths are resolved lazily to support testing in temp directories
 const getPaths = () => ({
   quality:   path.join(process.cwd(), '.mindforge', 'metrics', 'session-quality.jsonl'),
@@ -70,6 +88,10 @@ function getStatus() {
 
 // ── Audit ─────────────────────────────────────────────────────────────────────
 function getAuditEntries(limit = 50, offset = 0, eventFilter = null) {
+  const cacheKey = `audit:${limit}:${offset}:${eventFilter || ''}`;
+  const cached = cacheGet(cacheKey);
+  if (cached !== undefined) return cached;
+
   const paths = getPaths();
   const all   = readJSONL(paths.audit, 1000);
   const reversed = all.reverse(); // Newest first
@@ -78,16 +100,22 @@ function getAuditEntries(limit = 50, offset = 0, eventFilter = null) {
     ? reversed.filter(e => e.event === eventFilter)
     : reversed;
 
-  return {
+  const result = {
     entries: filtered.slice(offset, offset + limit),
     total:   filtered.length,
     limit,
     offset,
   };
+
+  cacheSet(cacheKey, result);
+  return result;
 }
 
 // ── Metrics ───────────────────────────────────────────────────────────────────
 function getMetrics() {
+  const cached = cacheGet('metrics');
+  if (cached !== undefined) return cached;
+
   const paths          = getPaths();
   const qualityEntries = readJSONL(paths.quality, 20);
   const usageEntries   = readJSONL(paths.usage, 200);
@@ -123,7 +151,7 @@ function getMetrics() {
   const node_repair_rate = taskEvents.length
     ? repairEvents.length / taskEvents.length : 0;
 
-  return {
+  const result = {
     sessions,
     avg_quality:        Math.round(avg_quality * 100) / 100,
     avg_cost_usd:       Math.round(avg_cost_usd * 10000) / 10000,
@@ -131,6 +159,9 @@ function getMetrics() {
     node_repair_rate:   Math.round(node_repair_rate * 100) / 100,
     total_tasks:        taskEvents.filter(e => e.event === 'task_completed').length,
   };
+
+  cacheSet('metrics', result);
+  return result;
 }
 
 // ── Approvals ─────────────────────────────────────────────────────────────────
@@ -168,6 +199,9 @@ function getApprovals() {
 
 // ── Team activity ─────────────────────────────────────────────────────────────
 function getTeamActivity() {
+  const cached = cacheGet('teamActivity');
+  if (cached !== undefined) return cached;
+
   const paths        = getPaths();
   const auditEntries = readJSONL(paths.audit, 200);
 
@@ -197,7 +231,9 @@ function getTeamActivity() {
   // Conflict detection — two authors recently touching same file
   const conflicts = detectFileConflicts(auditEntries);
 
-  return { active, conflicts };
+  const result = { active, conflicts };
+  cacheSet('teamActivity', result);
+  return result;
 }
 
 function detectFileConflicts(auditEntries) {
@@ -249,6 +285,10 @@ function getMemory(query = '', limit = 20) {
 
 // ── Costs ─────────────────────────────────────────────────────────────────────
 function getCosts(windowDays = 7) {
+  const cacheKey = `costs:${windowDays}`;
+  const cached = cacheGet(cacheKey);
+  if (cached !== undefined) return cached;
+
   const paths      = getPaths();
   const entries    = readJSONL(paths.usage, 1000);
   const cutoff     = new Date(Date.now() - windowDays * 86_400_000).toISOString().slice(0, 10);
@@ -282,6 +322,7 @@ function getCosts(windowDays = 7) {
     stats.by_model[m] = Math.round(stats.by_model[m] * 100) / 100;
   }
 
+  cacheSet(cacheKey, stats);
   return stats;
 }