total-recall-brain 3.40.7 → 3.41.0

package/src/core/automatic-brain-updates.mjs

@@ -10,6 +10,7 @@ import { readProcessCommand, shouldHonorPidLock } from './pid-lock.mjs';
 import { updateGlobalBrainPackages } from './global-brain-updates.mjs';
 import { updateMeshBrainPackages } from './mesh-brain-updates.mjs';
 import { updateSourceBrainPackages } from './source-brain-updates.mjs';
+import { updateInstalledPlugins } from './plugin-updates.mjs';
 
 export function automaticUpdateStatus(brainDir) {
   let last;
@@ -34,7 +35,7 @@ export function startAutomaticBrainUpdates({brainDir,intervalMs=60*60*1000,run=r
   return {tick,stop(){stopped=true;clearInterval(timer);}};
 }
 
-export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false,skipThrottle=false,intervalMs=60*60*1000,update=updateAllBrains,compile=maintainCliSurfaces,globalUpdate=updateGlobalBrainPackages,meshUpdate=updateMeshBrainPackages,sourceUpdate=updateSourceBrainPackages,now=Date.now}={}) {
+export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false,skipThrottle=false,intervalMs=60*60*1000,update=updateAllBrains,compile=maintainCliSurfaces,globalUpdate=updateGlobalBrainPackages,meshUpdate=updateMeshBrainPackages,sourceUpdate=updateSourceBrainPackages,pluginUpdate=updateInstalledPlugins,now=Date.now}={}) {
   if(!force && !isPackageAutoUpdateEnabled())return {skipped:true,reason:'disabled',results:[]};
   const file=path.join(brainDir,'memory-derived/automatic-brain-updates.json');
   let saved;try{saved=JSON.parse(fs.readFileSync(file,'utf8'));}catch{}
@@ -56,10 +57,12 @@ export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false
       const summary=await update({brainDir,dryRun:false,ensureDefaults:true});
       const global=summary.versions?await globalUpdate({versions:summary.versions}):{failed:1,results:[],error:'Cannot maintain global packages without verified published versions'};
       const sources=summary.versions?await sourceUpdate({brainDir,versions:summary.versions}):{failed:1,results:[]};
+      // The shared plugin folder follows the source each plugin was installed from (git, mesh peer, directory).
+      const plugins=await pluginUpdate({roots:[path.resolve(brainDir,'../../..')]});
       const mesh=fleet && summary.versions?await meshUpdate({versions:summary.versions,version:summary.versions['total-recall-brain']}):{failed:0,results:[],scope:'local-only'};
-      const changed=summary.updated>0 || global.results.some(row=>row.status==='updated') || sources.results.some(row=>row.status==='updated') || JSON.stringify(saved?.versions)!==JSON.stringify(summary.versions);
+      const changed=summary.updated>0 || plugins.updated>0 || global.results.some(row=>row.status==='updated') || sources.results.some(row=>row.status==='updated') || JSON.stringify(saved?.versions)!==JSON.stringify(summary.versions);
       const surfaces=await compile({brainDir,force:changed});
-      report={...summary,global,sources,mesh,surfaces,failed:(summary.failed || 0)+global.failed+sources.failed+mesh.failed+(surfaces.ok?0:surfaces.results.filter(row=>row.status==='failed').length),checkedAt:now()};
+      report={...summary,global,sources,plugins,mesh,surfaces,failed:(summary.failed || 0)+global.failed+sources.failed+plugins.failed+mesh.failed+(surfaces.ok?0:surfaces.results.filter(row=>row.status==='failed').length),checkedAt:now()};
     }catch(error){report={failed:1,error:error.message,checkedAt:now(),results:[]};}
     const temporary=`${file}.${process.pid}.tmp`;fs.writeFileSync(temporary,JSON.stringify(report,null,2));fs.renameSync(temporary,file);
     return report;

package/src/core/brain-registry.mjs

@@ -40,9 +40,26 @@ function readJson(file, fallback) {
   }
 }
 
+/** Authorization consumers must distinguish missing metadata from corruption. */
+function readStrictJson(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (err) { if (err.code === 'ENOENT') return fallback; throw new Error('Brain registry metadata is unavailable'); }
+}
+
+export function readRegisteredProjects(globalBrainDir = globalBrainDirFor()) {
+  const rows = readStrictJson(registryPath(globalBrainDir), []);
+  if (!Array.isArray(rows) || rows.some(row => !row || typeof row !== 'object' || Array.isArray(row))) {
+    throw new Error('Invalid project registry');
+  }
+  return rows;
+}
+
 /** `{ [resolvedBrainDir]: false }` for every brain switched off. */
-export function readBrainToggles(globalBrainDir = globalBrainDirFor()) {
-  const data = readJson(togglesPath(globalBrainDir), {});
+export function readBrainToggles(globalBrainDir = globalBrainDirFor(), { strict = false } = {}) {
+  const data = strict ? readStrictJson(togglesPath(globalBrainDir), {}) : readJson(togglesPath(globalBrainDir), {});
+  if (strict && (!data || typeof data !== 'object' || Array.isArray(data) || Object.values(data).some(v => typeof v !== 'boolean'))) {
+    throw new Error('Invalid brain toggles');
+  }
   return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
 }
 

package/src/core/brain-state.mjs

@@ -43,9 +43,32 @@ export const BRAIN_STATE = load();
  * @param {string} relPath e.g. "references/api-reference.md"
  * @returns {boolean}
  */
+/**
+ * Bundled plugin SOURCE inside the shipped scaffold is a template, not state.
+ *
+ * `plugins/` is state because an installed plugin directory is one brain's own
+ * collection. But the scaffold ships bundled plugin source at
+ * `scaffold/.agent/skills/total-recall/plugins/<id>/`, and `.gitignore` states
+ * plainly that it must stay in git. Matching the `plugins` segment anywhere in
+ * the path therefore flagged the template itself and failed the release gate.
+ * The exemption is anchored to the scaffold's own brain path, so an installed
+ * or brain-local `plugins/` directory is still state.
+ */
+function isScaffoldBundledPluginSource(parts) {
+  const at = parts.lastIndexOf('scaffold');
+  if (at === -1) return false;
+  const rest = parts.slice(at + 1);
+  return rest[0] === '.agent'
+    && rest[1] === 'skills'
+    && rest[2] === 'total-recall'
+    && rest[3] === 'plugins'
+    && rest.length > 4;
+}
+
 export function isBrainState(relPath) {
   if (!relPath) return false;
   const parts = String(relPath).split(/[\\/]+/).filter(Boolean);
+  if (isScaffoldBundledPluginSource(parts)) return false;
   if (parts.some((seg) => BRAIN_STATE.dirs.has(seg))) return true;
   const base = parts[parts.length - 1];
   if (!base) return false;

package/src/core/cli-commands.mjs

@@ -22,6 +22,7 @@ export const CLI_COMMANDS = {
   edit:     'edit.mjs',
   recall:   'recall.mjs',
   context:  'context.mjs',
+  'context-stats': 'context-stats.mjs',
   rules:    'rules.mjs',
   search:   'recall.mjs',
   research: 'research.mjs',

package/src/core/cli-maintenance.mjs

@@ -29,7 +29,7 @@ export async function maintainCliSurfaces({brainDir,brains,force=false,run=runBo
     const current=fingerprint(root);
     if(!force && previous?.fingerprint===current){results.push({root,status:'current'});continue;}
     const result=await run(process.execPath,[path.join(PACKAGE_ROOT,'bin/total-recall.mjs'),'plugin','refresh',...(brain.kind==='global'?['--global']:[])],{cwd:root,timeoutMs:600000,maxBytes:262144});
-    if(result.code!==0){results.push({root,status:'failed',error:result.reason || result.output?.slice(-1000) || 'CLI compilation failed'});continue;}
+    if(result.code!==0){results.push({root,status:'failed',error:result.reason || (result.stderr || result.output)?.trim().slice(-1000) || `CLI compilation failed (exit ${result.code})`});continue;}
     fs.mkdirSync(path.dirname(file),{recursive:true});
     const temp=`${file}.${process.pid}.tmp`;fs.writeFileSync(temp,JSON.stringify({fingerprint:current,compiledAt:new Date().toISOString()}));fs.renameSync(temp,file);
     results.push({root,status:'refreshed'});

package/src/core/cli-semantic-index.mjs

@@ -30,7 +30,7 @@ const CORE_METADATA = {
     effect: 'read'
   },
   init: {
-    description: 'Bootstrap global or project brain and openwiki documentation.',
+    description: 'Bootstrap a portable global or project memory brain.',
     usage: 'total-recall init [--project]',
     effect: 'write'
   },

package/src/core/command-surface.mjs

@@ -16,10 +16,10 @@ const NAME = /^[a-z][a-z0-9-]{0,63}$/;
 const MAX_DESCRIPTION = 180;
 
 /** Static scope metadata shared by catalogs and instruction projections. */
-export function commandScopeDirectories(projectRoot, agentDir) {
-  const dirs = [{ scope: 'project', dir: path.join(projectRoot, '.agent', 'commands') }];
+export function commandScopeDirectories(projectRoot, agentDir, { projectAgentDir = path.join(projectRoot, '.agent') } = {}) {
+  const dirs = projectAgentDir ? [{ scope: 'project', dir: path.join(projectAgentDir, 'commands') }] : [];
   let projectId;
-  try { projectId = JSON.parse(fs.readFileSync(path.join(projectRoot, '.agent/skills/total-recall/config/brain.json'), 'utf8')).project_id; } catch {}
+  try { if (projectAgentDir) projectId = JSON.parse(fs.readFileSync(path.join(projectAgentDir, 'skills/total-recall/config/brain.json'), 'utf8')).project_id; } catch {}
   const groups = path.join(agentDir, 'skills/total-recall/groups');
   if (typeof projectId === 'string' && projectId) {
     let files = [];

package/src/core/composed-command-resolution.mjs

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { globalAgentDir, resolveBrainLayer } from './config.mjs';
+import { commandScopeDirectories } from './command-surface.mjs';
+
+/** Execution and invoke discovery use the same selected brain as the CLI. */
+export function composedCommandDirectories(target = process.cwd()) {
+  let projectAgentDir = null;
+  try { projectAgentDir = resolveBrainLayer('project', undefined, target).agentDir; } catch {}
+  return commandScopeDirectories(target, globalAgentDir, { projectAgentDir });
+}
+
+/** Resolve statically; importing a candidate is an execution boundary. */
+export function resolveComposedCommand(name, dirs = composedCommandDirectories()) {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) return null;
+  for (const { dir } of dirs) {
+    const file = path.join(dir, `${name}.mjs`);
+    try { if (fs.statSync(file).isFile()) return file; } catch {}
+  }
+  return null;
+}

package/src/core/config.mjs

@@ -257,8 +257,27 @@ export function detectProjectBrain(startDir = process.cwd()) {
 
   let dir = startDir;
   const homeDir = os.homedir();
+  // Resolved live rather than from the module constant above: the agent dir can
+  // be overridden per process, and the guard must follow the folder actually in
+  // use.
+  const agentDirLive = process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR || path.join(homeDir, '.agent');
+  const pluginsRoot = path.join(agentDirLive, 'skills', 'total-recall', 'plugins');
+  // A shared plugin is either a directory inside the shared folder or a symlink
+  // to its owner checkout. Working inside one — directly or through the link —
+  // must never be treated as working in a project, or the plugin provisions a
+  // complete nested brain into itself, one level deeper on every run. The owner
+  // checkout's TOP LEVEL is the one exception: that is the plugin's repository,
+  // registered and edited in its own right.
+  const targets = pluginTargets(pluginsRoot);
+  const reachedThroughPlugin = isInsideSharedFolder(startDir, pluginsRoot, targets);
   while (dir !== path.dirname(dir)) {
     if (dir === homeDir) break; // don't detect global as project
+    if (dir === pluginsRoot || dir.startsWith(pluginsRoot + path.sep)) break;
+    // A plugin's own checkout stops the walk unless it is a registered project.
+    // The shared folder links every plugin to its owner repository, and those
+    // repositories are registered and worked in directly, so reaching one is
+    // only "a project" when the registry says it is.
+    if (reachedThroughPlugin && targets.has(fs.existsSync(dir) ? safeRealpath(dir) : dir) && !isRegisteredProject(dir)) break;
     // Both `.agent` (canonical) and `.agents` (the upstream harness convention)
     // are supported. This function used to check only `.agent` while its former
     // sibling in src/cli/agent-dir.mjs checked both, so the two could disagree
@@ -283,6 +302,71 @@ export function detectProjectBrain(startDir = process.cwd()) {
   return null;
 }
 
+/**
+ * Whether a starting path belongs to a shared plugin rather than to a repository
+ * in its own right.
+ *
+ * True when the caller's path lies beneath the shared folder literally, or when
+ * it resolves into one of the folder's link targets — including the target root,
+ * because a plugin that resolved its own directory asks from exactly there. The
+ * registry is what separates that plugin's own repository from a plugin install;
+ * this function only reports where the caller came from.
+ */
+function isInsideSharedFolder(startDir, pluginsRoot, targets) {
+  const candidates = [startDir, safeRealpath(startDir)].filter(Boolean);
+  for (const candidate of candidates) {
+    if (candidate === pluginsRoot || candidate.startsWith(pluginsRoot + path.sep)) return true;
+    for (const target of targets) {
+      if (candidate === target || candidate.startsWith(target + path.sep)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether this directory is a project the operator registered, read from the
+ * brain registry. A registered repository is a real project even when it is also
+ * installed as a shared plugin; anything else that is only reachable as a plugin
+ * is a plugin. Unreadable registry metadata is treated as "not registered",
+ * which keeps provisioning safe.
+ */
+function isRegisteredProject(dir) {
+  try {
+    const registry = path.join(
+      process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR || path.join(os.homedir(), '.agent'),
+      'skills', 'total-recall', 'config', 'project-registry.json'
+    );
+    const rows = JSON.parse(fs.readFileSync(registry, 'utf8'));
+    if (!Array.isArray(rows)) return false;
+    const wanted = fs.existsSync(dir) ? safeRealpath(dir) : path.resolve(dir);
+    return rows.some((row) => {
+      const candidate = row?.path || row?.root;
+      if (typeof candidate !== 'string' || !candidate) return false;
+      return (fs.existsSync(candidate) ? safeRealpath(candidate) : path.resolve(candidate)) === wanted;
+    });
+  } catch { return false; }
+}
+
+function safeRealpath(target) {
+  try { return fs.realpathSync(target); } catch { return null; }
+}
+
+/**
+ * The real directories behind the shared plugin folder. Each entry is normally a
+ * symlink to the plugin's owner checkout, which is where a nested brain would
+ * actually be written once the link is resolved.
+ */
+function pluginTargets(pluginsRoot) {
+  const targets = new Set();
+  let entries = [];
+  try { entries = fs.readdirSync(pluginsRoot, { withFileTypes: true }); } catch { return targets; }
+  for (const entry of entries) {
+    if (!entry.isSymbolicLink()) continue;
+    try { targets.add(fs.realpathSync(path.join(pluginsRoot, entry.name))); } catch { /* broken link */ }
+  }
+  return targets;
+}
+
 /**
  * Get both brain layers for the current context.
  *

package/src/core/confined-memory.mjs

@@ -0,0 +1,93 @@
+/** Trusted memory-owner adapter. No CLI, configuration, auth or plugin imports. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import matter from './frontmatter.mjs';
+import { processOperationAsync } from './operation-validator.mjs';
+import { buildLocalSearchIndex } from './fast-recall.mjs';
+
+export function validateConfinedFact(params) {
+  if (!params || typeof params !== 'object' || Array.isArray(params)) throw new Error('Invalid fact');
+  const allowed = new Set(['category', 'title', 'content', 'tags', 'target', 'timeoutMs']);
+  if (Object.keys(params).some(k => !allowed.has(k))) throw new Error('Unknown fact field');
+  if (params.category !== undefined && params.category !== 'fact') throw new Error('Only facts are supported');
+  if (params.target !== undefined && params.target !== 'server') throw new Error('Invalid target');
+  if (typeof params.content !== 'string' || !params.content.trim() || Buffer.byteLength(params.content) > 12000) throw new Error('Invalid content');
+  if (params.title !== undefined && (typeof params.title !== 'string' || !params.title.trim() || params.title.length > 200)) throw new Error('Invalid title');
+  if (params.tags !== undefined && (!Array.isArray(params.tags) || params.tags.length > 16 ||
+    params.tags.some(t => typeof t !== 'string' || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(t) || ['universal', 'absolute'].includes(t)))) throw new Error('Invalid tags');
+  if (params.timeoutMs !== undefined && (typeof params.timeoutMs !== 'number' || !Number.isFinite(params.timeoutMs) || params.timeoutMs <= 0)) throw new Error('Invalid timeout');
+}
+
+/** Resolve an operator-selected brain once; reject links below that boundary. */
+function checkTree(dir) {
+  if (!fs.existsSync(dir)) {
+    // existsSync follows links, so dangling links must still be refused.
+    try { if (fs.lstatSync(dir).isSymbolicLink()) throw new Error('Unsafe path'); }
+    catch (err) { if (err.code !== 'ENOENT') throw err; }
+    return;
+  }
+  const stat = fs.lstatSync(dir);
+  if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile()) throw new Error('Unsafe path');
+  if (stat.isDirectory()) for (const name of fs.readdirSync(dir)) checkTree(path.join(dir, name));
+}
+
+function readMemoryNodes(vault) {
+  const nodes = [];
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || entry.name === 'proposals') continue;
+      const file = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) throw new Error('Unsafe vault path');
+      if (entry.isDirectory()) walk(file);
+      else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const { data, content } = matter(fs.readFileSync(file, 'utf8'));
+        if (data.type === 'memory') nodes.push({ ...data, body: content, _filePath: file });
+      }
+    }
+  }
+  walk(vault);
+  return nodes;
+}
+
+/** Create-only SSSS fact; rebuilding the local projection never runs generators. */
+export async function createConfinedFact(brain, params, caller = 'local-operator') {
+  validateConfinedFact(params);
+  if (typeof caller !== 'string' || !caller || caller.length > 200) throw new Error('Invalid caller');
+  const base = fs.realpathSync(brain);
+  const vault = path.join(base, 'memory-vault'), derived = path.join(base, 'memory-derived');
+  checkTree(vault); checkTree(derived);
+  const slug = `fact-${crypto.randomUUID()}`, relative = `facts/${slug}.md`;
+  const title = params.title || params.content.trim().split('\n')[0].slice(0, 160);
+  const now = new Date().toISOString();
+  const data = { type: 'memory', slug, category: 'facts', title, description: title, timestamp: now,
+    schema_version: 2, status: 'active', confidence: 1, importance: 3, modality: 'descriptive',
+    created: now, updated: now, last_accessed: now, subject: 'agent', predicate: 'remembers_fact', object: slug,
+    sentiment_polarity: 'descriptive', sentiment_target: 'memory', tags: [...new Set(['invoke', ...(params.tags || [])])],
+    source: { type: 'confined-memory', session_id: 'confined-memory', agent: caller, evidence_count: 1 },
+    x_temporal_context: now };
+  // No overwrite grant and no caller-selected path, metadata, role or source.
+  const principal = { id: caller, kind: 'agent', workspaceIds: ['confined-memory'],
+    capabilities: ['memory:create', 'ssss:memory:create'],
+    authentication: { provider: 'total-recall-confined-memory', assurance: 'verified' } };
+  const result = { category: 'fact', path: `memory-vault/${relative}`, slug, committed: false, indexed: false };
+  try {
+    const written = await processOperationAsync({ type: 'operation', idempotency_key: crypto.randomUUID(),
+      path: relative, workspace_id: 'confined-memory', content: matter.stringify(params.content, data),
+      actor: { role: 'confined-memory' } }, vault, { agentRole: 'confined-memory', principal });
+    if (!written.success) throw new Error('Canonical write failed');
+    result.committed = true;
+    result.operation_id = written.operation_id;
+    buildLocalSearchIndex(readMemoryNodes(vault), { vaultDir: vault, derivedDir: derived });
+    result.indexed = true;
+    return result;
+  } catch (cause) {
+    // Kernel rolls back failed canonical event commits. A later host-audit or
+    // index error may leave the fact committed; never advertise safe blind retry.
+    result.committed = fs.existsSync(path.join(vault, relative));
+    const err = new Error(result.committed ? 'Fact committed; local indexing incomplete' : 'Fact creation failed', { cause });
+    err.result = result;
+    throw err;
+  }
+}

package/src/core/context-telemetry.mjs

@@ -0,0 +1,214 @@
+/**
+ * context-telemetry — measurement for the one number that governs every session.
+ *
+ * `compileContext` already computed everything needed to judge the context
+ * policy (total tokens, required tokens, overflow, which rules were included,
+ * which were dropped) and then threw it away. Without a record, the budget
+ * question could only ever be argued from a point-in-time anecdote — TR-003
+ * recorded "12 of 13 capsules overflow" once and nobody could later say whether
+ * a change helped, or whether the gate still failed at all.
+ *
+ * This records one line per capsule so the policy is decided from a trend
+ * rather than a memory.
+ *
+ * Bounded by construction. An append-only event log in this project once
+ * reached 306 MB, GitHub silently rejected every backup for five weeks, and the
+ * cause was invisible until someone looked. So this file carries its own size
+ * cap and retention, enforced on write, and it records counts and identifiers
+ * ONLY: never rule text, never capsule content, never a credential. Identifiers
+ * are slugs that already appear in the vault.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Append-only ledger for capsule measurements, inside the brain's derived space. */
+export const LEDGER_NAME = 'context-ledger.jsonl';
+
+/**
+ * Fraction of the cap retained when trimming (TR_CONTEXT_LEDGER_RETAIN, default
+ * 0.5). Trimming to the cap on every crossing would re-trim constantly; leaving
+ * headroom makes the trim rare and keeps a real window of history.
+ */
+const RETAIN_FRACTION = (() => {
+  const n = Number(process.env.TR_CONTEXT_LEDGER_RETAIN ?? 0.5);
+  return Number.isFinite(n) && n > 0 && n <= 1 ? n : 0.5;
+})();
+
+/**
+ * Max bytes the ledger may reach (TR_CONTEXT_LEDGER_MAX_BYTES, default 8 MiB,
+ * 0 disables). Small on purpose: this is telemetry, not memory, and it must
+ * never be able to threaten a backup or a disk the way default.jsonl did.
+ */
+const maxBytes = () => {
+  const n = Number(process.env.TR_CONTEXT_LEDGER_MAX_BYTES ?? 8 * 1024 * 1024);
+  return Number.isFinite(n) && n >= 0 ? n : 8 * 1024 * 1024;
+};
+
+/** Whether telemetry is recorded at all (TR_CONTEXT_TELEMETRY=off disables). */
+export const telemetryEnabled = () => String(process.env.TR_CONTEXT_TELEMETRY || '').toLowerCase() !== 'off';
+
+/** Ledger path for a brain's derived directory. */
+export function ledgerPath(derivedDir) {
+  return derivedDir ? path.join(derivedDir, LEDGER_NAME) : null;
+}
+
+/**
+ * Keep the ledger bounded while preserving a usable trend.
+ *
+ * Two failure modes, both observed rather than imagined:
+ *   1. An append-only log in this project reached 306 MB and silently broke
+ *      every backup for five weeks. So growth must be bounded by construction.
+ *   2. The first attempt here renamed the live file over the previous
+ *      generation, so 40 writes under a small cap left 4 records — the trend
+ *      the ledger exists for was destroyed by its own housekeeping.
+ *
+ * The ledger therefore trims to a retained fraction of the cap rather than
+ * collapsing: the newest half survives, the rest is dropped. Trimming runs only
+ * once the cap is crossed (not on every write), so the common path stays a
+ * single append.
+ */
+function enforceBound(file, cap, fsImpl = fs) {
+  if (cap <= 0) return;
+  let size;
+  try { size = fsImpl.statSync(file).size; } catch { return; }
+  if (size <= cap) return;
+  try {
+    const lines = fsImpl.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    const keep = [];
+    let bytes = 0;
+    const retainBytes = Math.floor(cap * RETAIN_FRACTION);
+    // Walk backwards so the most recent measurements are the ones retained.
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const next = Buffer.byteLength(lines[i]) + 1;
+      if (bytes + next > retainBytes && keep.length) break;
+      bytes += next;
+      keep.unshift(lines[i]);
+    }
+    fsImpl.writeFileSync(file, keep.length ? `${keep.join('\n')}\n` : '');
+  } catch { /* a concurrent writer or an unreadable file: leave it alone */ }
+}
+
+/**
+ * Record one capsule measurement.
+ *
+ * Returns the record written, or null when telemetry is off or the write
+ * failed. Never throws: measurement must never be able to break a session.
+ */
+export function recordCapsule(stats, { derivedDir, action = [], query, consumer = 'cli', now = Date.now(), fsImpl = fs } = {}) {
+  if (!telemetryEnabled() || !stats || !derivedDir) return null;
+  try {
+    const file = ledgerPath(derivedDir);
+    fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+    enforceBound(file, maxBytes(), fsImpl);
+    const contributions = Array.isArray(stats.contributions) ? stats.contributions : [];
+    const record = {
+      at: new Date(now).toISOString(),
+      consumer,
+      // Actions and the query are what make a measurement interpretable; the
+      // query is truncated because it is free text, not an identifier.
+      actions: Array.isArray(action) ? action : [action].filter(Boolean),
+      query_chars: typeof query === 'string' ? query.length : 0,
+      total_tokens: stats.total_tokens ?? null,
+      // `budget` is added by the caller's capsuleResponse wrapper; absent here.
+      required_tokens: stats.required_tokens ?? null,
+      overflow_tokens: stats.overflow_tokens ?? null,
+      ready: typeof stats.overflow_tokens === 'number' ? stats.overflow_tokens === 0 : null,
+      required_count: Array.isArray(stats.required_ids) ? stats.required_ids.length : contributions.filter(c => c.required).length,
+      excluded_count: Array.isArray(stats.excluded_ids) ? stats.excluded_ids.length : 0,
+      // Identifier lists only, and only the ones that decided the budget.
+      required_ids: Array.isArray(stats.required_ids) ? stats.required_ids : [],
+      excluded_ids: Array.isArray(stats.excluded_ids) ? stats.excluded_ids.slice(0, 40) : [],
+      version: stats.version || null,
+    };
+    // A torn final line — an interrupted write, a full disk — would otherwise
+    // have the next record appended onto it, corrupting both. Repair the tail
+    // before appending so one bad write costs one measurement, not two.
+    repairTornTail(file, fsImpl);
+    fsImpl.appendFileSync(file, JSON.stringify(record) + '\n');
+    return record;
+  } catch { return null; }
+}
+
+/**
+ * Give a torn final line its own terminator.
+ *
+ * An append-only ledger assumes the file ends at a record boundary. When it
+ * does not — the process died mid-write — the next append lands on that line
+ * and both records become unparseable. Dropping the damaged tail keeps the loss
+ * at exactly the one measurement that failed.
+ */
+function repairTornTail(file, fsImpl = fs) {
+  let text;
+  try { text = fsImpl.readFileSync(file, 'utf8'); } catch { return; }
+  if (!text || text.endsWith('\n')) return;
+  const lastBreak = text.lastIndexOf('\n');
+  const tail = lastBreak === -1 ? text : text.slice(lastBreak + 1);
+  try { JSON.parse(tail); return; } catch { /* the tail is torn */ }
+  try { fsImpl.writeFileSync(file, lastBreak === -1 ? '' : text.slice(0, lastBreak + 1)); } catch { /* leave it alone */ }
+}
+
+/**
+ * Read ledger records, oldest first.
+ *
+ * Skips a malformed line individually. A torn write must cost one measurement,
+ * never the whole ledger — an earlier version discarded every valid record that
+ * followed the torn one.
+ */
+export function readLedger(derivedDir, { limit = 0, fsImpl = fs } = {}) {
+  const file = ledgerPath(derivedDir);
+  if (!file) return [];
+  const records = [];
+  for (const candidate of [file]) {
+    let text;
+    try { text = fsImpl.readFileSync(candidate, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try { records.push(JSON.parse(line)); } catch { /* skip this line only */ }
+    }
+  }
+  return limit > 0 ? records.slice(-limit) : records;
+}
+
+/**
+ * Summarise a ledger into the numbers a design decision needs.
+ *
+ * Reports per action, because "the capsule is too big" is not actionable while
+ * "read overflows and edit does not" is. `top_required` answers which rules
+ * carry the cost, which is the input to action-scoping a rule.
+ */
+export function summariseLedger(records = []) {
+  const byAction = new Map();
+  const ruleTokens = new Map();
+  const ruleAppearances = new Map();
+  for (const r of records) {
+    const actions = r.actions?.length ? r.actions : ['(none)'];
+    for (const action of actions) {
+      const entry = byAction.get(action) || { action, samples: 0, overflow: 0, required_max: 0, required_sum: 0, total_max: 0, excluded_total: 0 };
+      entry.samples++;
+      if (r.overflow_tokens > 0) entry.overflow++;
+      entry.required_sum += r.required_tokens || 0;
+      entry.required_max = Math.max(entry.required_max, r.required_tokens || 0);
+      entry.total_max = Math.max(entry.total_max, r.total_tokens || 0);
+      entry.excluded_total += r.excluded_count || 0;
+      byAction.set(action, entry);
+    }
+    for (const id of r.required_ids || []) {
+      ruleAppearances.set(id, (ruleAppearances.get(id) || 0) + 1);
+    }
+  }
+  const actions = [...byAction.values()]
+    .map(e => ({ ...e, required_avg: e.samples ? Math.round(e.required_sum / e.samples) : 0, overflow_rate: e.samples ? +(e.overflow / e.samples).toFixed(3) : 0 }))
+    .sort((a, b) => b.overflow_rate - a.overflow_rate || b.required_max - a.required_max);
+  const mostRequired = [...ruleAppearances.entries()]
+    .map(([id, appearances]) => ({ id, appearances }))
+    .sort((a, b) => b.appearances - a.appearances)
+    .slice(0, 25);
+  return {
+    samples: records.length,
+    first_at: records.length ? records[0].at : null,
+    last_at: records.length ? records[records.length - 1].at : null,
+    actions,
+    most_required: mostRequired,
+    rule_tokens: [...ruleTokens.entries()].map(([id, tokens]) => ({ id, tokens })),
+  };
+}