total-recall-brain 3.41.4 → 3.41.5

package/scaffold/.agent/skills/total-recall/plugins/security/package.json

@@ -24,6 +24,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@gregiteen/ssss-cli": "0.14.3"
+    "@gregiteen/ssss-cli": "0.14.4"
   }
 }

package/src/cli/compact.mjs

@@ -0,0 +1,108 @@
+import { parseLayerFlag } from './agent-dir.mjs';
+import { loadContextNodes } from './context.mjs';
+import { curatedRules, selectRules } from '../core/context-policy.mjs';
+import { compactRules } from '../core/context-compactor.mjs';
+import { cosineSimilarity, getEmbedding, loadEmbeddingsIndex } from '../core/embeddings.mjs';
+import { legacyRuleContributions } from '../core/surface.mjs';
+
+const DEFAULT_BUDGET = 4000;
+const EMBED_TIMEOUT_MS = 8000;
+
+const USAGE = `Usage: total-recall compact "task" [--budget 4000] [--action edit,test] [--expand slug,slug] [--format text|json] [--project|--global]
+Fits the applicable rules into --budget estimated tokens, ranked against the task. Rules keep their own words: full text, a leading excerpt, or a slug under Referenced. Read any of them in full with --expand. The output is partial by design; \`total-recall context\` prints the complete capsule.`;
+
+function parseArgs(args) {
+  const options = { budget: DEFAULT_BUDGET, actions: [], expand: [], format: 'text' };
+  for (let i = 1; i < args.length; i++) {
+    const flag = args[i];
+    const value = args[++i];
+    if (flag === '--budget') options.budget = Number(value);
+    else if (flag === '--action') options.actions = value?.split(',').filter(Boolean) || [];
+    else if (flag === '--expand') options.expand = value?.split(',').filter(Boolean) || [];
+    else if (flag === '--format' && ['json', 'text'].includes(value)) options.format = value;
+    else throw new Error(`Unknown compact option: ${flag}`);
+  }
+  if (!Number.isFinite(options.budget) || options.budget < 1) throw new Error('--budget must be a positive number of tokens');
+  return options;
+}
+
+function loadVectors(derivedDirs) {
+  const vectors = {};
+  for (const dir of derivedDirs) {
+    try {
+      for (const [slug, entry] of Object.entries(loadEmbeddingsIndex(dir))) vectors[slug] ??= entry.embedding;
+    } catch { /* a brain without an index simply contributes no vectors */ }
+  }
+  return vectors;
+}
+
+async function embedTask(task) {
+  let timer;
+  const timeout = new Promise(resolve => { timer = setTimeout(() => resolve(null), EMBED_TIMEOUT_MS); });
+  try {
+    return await Promise.race([getEmbedding(task), timeout]);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function lexicalScore(terms, text) {
+  if (!terms.length) return 0;
+  const haystack = text.toLowerCase();
+  return terms.filter(term => haystack.includes(term)).length / terms.length;
+}
+
+/** Rank the applicable rules against the task and fit them into `budget`. Shared by `compact` and `context`. */
+export async function compactNodes({ task, actions = [], budget, expand = [], complete = false, nodes, skillsDir, derivedDirs, header }) {
+  const rules = selectRules(curatedRules(nodes), { actions, projectRoot: process.cwd() });
+  const vectors = loadVectors(derivedDirs);
+  const taskVector = await embedTask(task);
+  const terms = String(task).toLowerCase().match(/[\p{L}\p{N}_-]{3,}/gu) || [];
+  const semantic = Boolean(taskVector);
+
+  const score = (slug, text) => semantic && vectors[slug] ? cosineSimilarity(taskVector, vectors[slug]) : lexicalScore(terms, text);
+  const items = rules.map(node => {
+    const body = (node._directive || node.body || node.content || '').trim();
+    return {
+      slug: node.slug, body, priority: node.priority, importance: node.importance,
+      text: node._directive ? `[${node.slug}] ${node._directive}` : `## ${node.title || node.slug} [${node.slug}]\n\n${body}`,
+      vector: vectors[node.slug], score: score(node.slug, `${node.title || ''} ${body}`),
+    };
+  });
+  for (const { id, text } of legacyRuleContributions(skillsDir)) {
+    items.push({ slug: id, body: text, text, score: lexicalScore(terms, text) });
+  }
+
+  const ranking = semantic ? 'semantic' : 'lexical';
+  return { ranking, ...compactRules(items, { budget, expand, complete, header: (counts, tokens) => header(counts, tokens, ranking) }) };
+}
+
+export default async function compact(args = []) {
+  if (!args.length || args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE);
+    return;
+  }
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  const task = remainingArgs[0];
+  const { budget, actions, expand, format } = parseArgs(remainingArgs);
+  const { nodes, skillsDir, derivedDirs } = loadContextNodes(layer);
+  const header = (counts, tokens, ranking) => [
+    `compacted:true tokens:${tokens} budget:${budget} rules:${counts.rules} full:${counts.full} summarized:${counts.summarized} referenced:${counts.referenced} duplicate:${counts.duplicate} omitted:${counts.omitted} ranking:${ranking}`,
+    'PARTIAL: read any rule in full with --expand <slug>; total-recall context prints the complete capsule.',
+  ].join('\n');
+
+  let result;
+  try {
+    result = await compactNodes({ task, actions, budget, expand, nodes, skillsDir, derivedDirs, header });
+  } catch (error) {
+    console.log(error.requiredBudget ? `compacted:false reason:budget-too-small budget:${budget} required_budget:${error.requiredBudget}` : `compacted:false reason:${error.message}`);
+    process.exitCode = 2;
+    return;
+  }
+  const { context, counts, tokens, tiers, ranking } = result;
+  console.log(format === 'json'
+    ? JSON.stringify({ compacted: true, ranking, budget, tokens, counts, tiers, context })
+    : context);
+}

package/src/cli/context.mjs

@@ -2,15 +2,61 @@ import path from 'node:path';
 import { getBothBrains, parseLayerFlag } from './agent-dir.mjs';
 import { getNodes } from '../core/vault-cache.mjs';
 import { mergeGlobalRuleNodes, legacyRuleContributions } from '../core/surface.mjs';
-import { compileContext, capsuleResponse, renderCapsule } from '../core/context-compiler.mjs';
+import { compileContext, capsuleResponse, renderCapsule, PREFLIGHT_NOTICE } from '../core/context-compiler.mjs';
 import { isBrainEnabled } from '../core/brain-registry.mjs';
 import { surfaceInputsHash } from '../core/command-surface.mjs';
 import { readConfigValue } from './config.mjs';
 import { recordCapsule } from '../core/context-telemetry.mjs';
 
+/** About 28 KB: harnesses save output over about 30 KB to a file instead of showing it, which agents then cannot read (audit C-005, F-019). */
+export const CAPSULE_LIMIT = 7000;
+const JSON_ESCAPE_SHARE = 0.97;
+const JSON_WRAPPER_TOKENS = 128;
+
+/** The merged rule nodes a capsule draws from, for the selected layer. */
+export function loadContextNodes(layer) {
+  const brains = getBothBrains();
+  const own = layer !== 'global' && brains.project && isBrainEnabled(brains.project.brainDir) ? brains.project.brainDir : null;
+  const global = layer !== 'project' && brains.global && isBrainEnabled(brains.global.brainDir) ? brains.global.brainDir : null;
+  if (!own && !global) throw new Error('No enabled brain in selected scope');
+  const nodes = own ? mergeGlobalRuleNodes(getNodes(path.join(own, 'memory-vault')), global ? getNodes(path.join(global, 'memory-vault')) : []) :
+    getNodes(path.join(global, 'memory-vault')).map(n => ({ ...n, _layer: 'global' }));
+  return { nodes, skillsDir: path.dirname(own || global),
+    derivedDirs: [own, global].filter(Boolean).map(dir => path.join(dir, 'memory-derived')) };
+}
+
+/** Compact the over-budget capsule, or explain the budget it needs. `fullRequired` is what the uncompacted capsule would take. */
+async function printCompacted({ query, actions, budget, format, version, fullRequired, nodes, skillsDir, derivedDirs }) {
+  const { compactNodes } = await import('./compact.mjs');
+  // JSON escaping and its wrapper count against the budget too.
+  const target = format === 'json' ? Math.floor(budget * JSON_ESCAPE_SHARE) - JSON_WRAPPER_TOKENS : budget;
+  const header = (counts, tokens, ranking) => [
+    `ready:true compacted:true tokens:${tokens} budget:${budget} version:${version} rules:${counts.rules} full:${counts.full} summarized:${counts.summarized} referenced:${counts.referenced} duplicate:${counts.duplicate} ranking:${ranking}`,
+    PREFLIGHT_NOTICE,
+    `COMPACTED: every rule below still applies. Read a referenced rule with: total-recall compact "<task>" --expand <slug>`,
+  ].join('\n');
+  let result;
+  try {
+    result = await compactNodes({ task: query, actions, budget: Math.max(target, 1), complete: true, nodes, skillsDir, derivedDirs, header });
+  } catch (error) {
+    if (!error.requiredBudget) throw error;
+    const floor = format === 'json' ? Math.ceil((error.requiredBudget + JSON_WRAPPER_TOKENS) / JSON_ESCAPE_SHARE) : error.requiredBudget;
+    const requiredBudget = Math.min(fullRequired, floor);
+    console.log(format === 'json'
+      ? JSON.stringify({ ready: false, reason: 'budget-overflow', context: '', stats: { version, budget, required_budget: requiredBudget, token_measurement: 'estimated_chars_divided_by_four' } })
+      : `ready:false reason:budget-overflow budget:${budget} required_budget:${requiredBudget} version:${version}\nThis budget cannot hold every rule even compacted. Retry with --budget ${requiredBudget}; do not act until ready:true.`);
+    process.exitCode = 2;
+    return;
+  }
+  console.log(format === 'json'
+    ? JSON.stringify({ ready: true, compacted: true, ranking: result.ranking, context: result.context, counts: result.counts,
+      stats: { version, budget, total_tokens: result.tokens, token_measurement: 'estimated_chars_divided_by_four' } })
+    : result.context);
+}
+
 export default async function context(args = []) {
   if (!args.length || args.includes('--help')) {
-    console.log('Usage: total-recall context "task" [--action edit,test,publish] [--budget 4000] [--format text|json] [--knowledge] [--debug] [--project|--global]\nLocal rules only by default. Unknown applicability is required. Overflow exits 2; do not act until the complete output fits. --knowledge adds supporting documents; --debug exposes inventories within the same budget. Refresh on task/action/project or policy changes.');
+    console.log(`Usage: total-recall context "task" [--action edit,test,publish] [--budget ${CAPSULE_LIMIT}] [--format text|json] [--knowledge] [--debug] [--project|--global]\nLocal rules only by default. Unknown applicability is required. Over budget, the capsule compacts automatically: absolute rules keep at least a summary and every other rule keeps at least its slug. Configured budgets are capped at ${CAPSULE_LIMIT}; pass a larger --budget to print the full capsule. Exit 2 means the budget cannot hold every rule; do not act until ready:true. --knowledge adds supporting documents; --debug exposes inventories within the same budget. Refresh on task/action/project or policy changes.`);
     return;
   }
   const { layer, remainingArgs } = parseLayerFlag(args);
@@ -24,7 +70,7 @@ export default async function context(args = []) {
     }
     return undefined;
   })();
-  let actions = [], budget = configuredBudget ?? 4000, format = 'text', includeKnowledge = false, debug = false;
+  let actions = [], budget = Math.min(configuredBudget ?? CAPSULE_LIMIT, CAPSULE_LIMIT), format = 'text', includeKnowledge = false, debug = false;
   for (let i = 1; i < remainingArgs.length; i++) {
     const flag = remainingArgs[i];
     if (flag === '--knowledge') { includeKnowledge = true; continue; }
@@ -35,14 +81,8 @@ export default async function context(args = []) {
     else if (flag === '--format' && ['json', 'text'].includes(value)) format = value;
     else throw new Error(`Unknown context option: ${flag}`);
   }
-  const brains = getBothBrains();
-  const own = layer !== 'global' && brains.project && isBrainEnabled(brains.project.brainDir) ? brains.project.brainDir : null;
-  const global = layer !== 'project' && brains.global && isBrainEnabled(brains.global.brainDir) ? brains.global.brainDir : null;
-  if (!own && !global) throw new Error('No enabled brain in selected scope');
-  const nodes = own ? mergeGlobalRuleNodes(getNodes(path.join(own, 'memory-vault')), global ? getNodes(path.join(global, 'memory-vault')) : []) :
-    getNodes(path.join(global, 'memory-vault')).map(n => ({ ...n, _layer: 'global' }));
-  const skillsDir = path.dirname(own || global);
-  const derivedDir = own ? path.join(own, 'memory-derived') : (global ? path.join(global, 'memory-derived') : null);
+  const { nodes, skillsDir, derivedDirs } = loadContextNodes(layer);
+  const derivedDir = derivedDirs[0];
   const result = await compileContext({ query, actions, nodes, includeKnowledge, budget: { total: budget }, projectRoot: process.cwd(),
     derivedDir, contributions: legacyRuleContributions(skillsDir), versionInputs: surfaceInputsHash({ skillsDir }) });
   if (debug && format === 'text') throw new Error('--debug requires --format json');
@@ -55,18 +95,7 @@ export default async function context(args = []) {
     derivedDir, action: actions, query, consumer: 'cli',
   });
   if (!response.ready && !debug) {
-    // Admission failed: emitting bodies here makes each budget retry load the
-    // same rules again. Keep the full set in the compiler/API, and admit it only
-    // after the caller explicitly raises the budget or curates applicability.
-    const requiredBudget = response.stats.total_tokens + 32;
-    const diagnostic = { ready: false, reason: 'budget-overflow', context: '', stats: {
-      version: response.stats.version, required_count: response.stats.required_count,
-      budget, required_budget: requiredBudget,
-      token_measurement: 'estimated_chars_divided_by_four',
-    } };
-    console.log(format === 'json' ? JSON.stringify(diagnostic) :
-      `ready:false reason:budget-overflow budget:${budget} required_budget:${requiredBudget} required_rules:${response.stats.required_count} version:${response.stats.version}\nRetry with --budget ${requiredBudget}; do not act until ready:true.\nTo shorten the rules for good: total-recall rules audit, then rules draft/apply.`);
-    process.exitCode = 2;
+    await printCompacted({ query, actions, budget, format, version: response.stats.version, fullRequired: response.stats.total_tokens + 32, nodes, skillsDir, derivedDirs });
     return;
   }
   console.log(renderCapsule(response, format));

package/src/cli/forget.mjs

@@ -33,6 +33,8 @@ function printHelp() {
 }
 
 export default async function forget(args) {
+  // Checked first: a destructive command must never act on a request for help.
+  if (args.includes('--help') || args.includes('-h')) { printHelp(); return; }
   const { layer: explicitLayer, remainingArgs } = parseLayerFlag(args);
 
   // Check for --project-all

package/src/cli/release.mjs

@@ -0,0 +1,386 @@
+/**
+ * total-recall release — publish a package, propagate it, and verify every consumer.
+ *
+ * The missing capability this fills: publishing to npm and verifying that the
+ * published artifact actually reached every registered consumer were manual
+ * steps outside any TR command. A release that is only on npm is not released,
+ * and a release whose consumers were never verified is a claim, not a fact.
+ *
+ * Usage:
+ *   npx total-recall release plan <pkg> [--version X.Y.Z]
+ *   npx total-recall release publish <pkg> [--version X.Y.Z] [--otp N]
+ *   npx total-recall release propagate [--apply]
+ *   npx total-recall release verify <pkg> [--version X.Y.Z]
+ *   npx total-recall release all <pkg> [--version X.Y.Z] [--apply] [--otp N]
+ *
+ * Never publishes without --apply. Never trusts the publish command's own
+ * report: verification reads the registry and each consumer's resolved
+ * installation independently.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { BRAIN_PACKAGES, updateAllBrains } from '../core/brain-updates.mjs';
+import { listUpdateRoots, rootsFromEnv } from '../core/package-auto-update.mjs';
+
+const DEFAULT_PACKAGES = BRAIN_PACKAGES;
+
+/** @param {string[]} args */
+export function parseArgs(args) {
+  const opts = {
+    action: null,
+    packages: [],
+    version: null,
+    apply: false,
+    otp: null,
+    json: false,
+    help: false,
+    root: null,
+    timeoutMs: 20 * 60 * 1000,
+  };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--apply') opts.apply = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--version' && args[i + 1]) opts.version = args[++i];
+    else if (a === '--otp' && args[i + 1]) opts.otp = args[++i];
+    else if (a === '--root' && args[i + 1]) opts.root = args[++i];
+    else if (a === '--timeout' && args[i + 1]) opts.timeoutMs = Number(args[++i]);
+    else if (!a.startsWith('-')) positional.push(a);
+  }
+  opts.action = positional.shift() || null;
+  opts.packages = positional;
+  return opts;
+}
+
+const ACTIONS = ['plan', 'publish', 'propagate', 'verify', 'all'];
+
+function printHelp() {
+  console.log(`
+  total-recall release — publish, propagate and verify a package release
+
+  Usage:
+    total-recall release plan <pkg> [--version X.Y.Z]
+    total-recall release publish <pkg> [--version X.Y.Z] [--otp N] --apply
+    total-recall release propagate [--apply] [--json]
+    total-recall release verify <pkg> [--version X.Y.Z] [--json]
+    total-recall release all <pkg> [--version X.Y.Z] [--apply] [--otp N] [--json]
+
+  Actions:
+    plan        Resolve the release version and report gate/consumer readiness. No writes.
+    publish     Run the package's prepublish gate, then npm publish. Requires --apply.
+    propagate   Pin the published version across every registered consumer (update --all-brains).
+    verify      Independently confirm the registry artifact and each consumer's resolved install.
+    all         plan → publish → propagate → verify, stopping at the first failure.
+
+  Rules enforced here:
+    • Publishing requires --apply; plan/verify never write.
+    • Verification never trusts the publish or propagate report: it re-reads the
+      npm registry and each consumer's own resolved package.json.
+    • A version that is only on npm is reported as incomplete, not as released.
+
+  Options:
+    --apply          Perform writes (required for publish/propagate).
+    --version X.Y.Z  Expect or assert a specific version (defaults to the source package.json).
+    --otp N          npm one-time password, passed through to npm publish.
+    --root PATH      Source repo for the package (defaults to $PWD).
+    --json           Machine-readable output.
+`);
+}
+
+/** Read a package's source metadata without assuming a monorepo layout. */
+export function readSourcePackage(root, pkg) {
+  const candidates = [path.join(root, 'package.json')];
+  // A workspace source may live one level down (packages/<dir>/package.json).
+  for (const dir of ['packages', 'apps']) {
+    const base = path.join(root, dir);
+    if (!fs.existsSync(base)) continue;
+    for (const entry of fs.readdirSync(base)) {
+      candidates.push(path.join(base, entry, 'package.json'));
+    }
+  }
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    try {
+      const pkgJson = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (pkgJson.name === pkg) return { file, dir: path.dirname(file), pkgJson };
+    } catch {
+      /* ignore malformed candidates rather than failing the whole release */
+    }
+  }
+  return null;
+}
+
+/** npm registry read. This is the independent source of truth for "published". */
+export function publishedVersion(pkg, { exec = spawnSync } = {}) {
+  const res = exec('npm', ['view', pkg, 'version'], { encoding: 'utf8', timeout: 60000 });
+  if (res.status !== 0) return { ok: false, version: null, error: (res.stderr || '').trim() || 'npm view failed' };
+  return { ok: true, version: (res.stdout || '').trim(), error: null };
+}
+
+/** Wait for a just-published version to become readable from the registry. */
+export async function awaitPublished(pkg, version, { attempts = 8, delayMs = 20000, exec = spawnSync, sleep } = {}) {
+  const pause = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let last = null;
+  for (let i = 0; i < attempts; i++) {
+    const read = publishedVersion(pkg, { exec });
+    last = read;
+    if (read.ok && read.version === version) return { ok: true, version: read.version, attempts: i + 1 };
+    if (i < attempts - 1) await pause(delayMs);
+  }
+  return { ok: false, version: last?.version ?? null, error: last?.error ?? `registry still reports ${last?.version}`, attempts };
+}
+
+/**
+ * Every consumer root TR knows about: the project registry plus TR_SYNC_REPOS.
+ * Used by verify so it never depends on the propagate step's own bookkeeping.
+ */
+export function consumerRoots(opts = {}) {
+  // Explicit roots are authoritative: passing them means "verify exactly these",
+  // which is what makes this callable from tests and from --root. Without them,
+  // fall back to the whole registered fleet plus TR_SYNC_REPOS.
+  const explicit = (opts.roots || []).filter(Boolean);
+  const source = explicit.length
+    ? explicit
+    : [...listUpdateRoots(opts).map((row) => (typeof row === 'string' ? row : row.root)), ...rootsFromEnv()];
+  const seen = new Set();
+  const out = [];
+  for (const root of source) {
+    if (!root) continue;
+    const resolved = path.resolve(root);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+/** Read the version a consumer actually resolves for a package (declared + installed). */
+export function consumerState(root, pkg, version = null) {
+  const declaredFiles = [];
+  const pkgFile = path.join(root, 'package.json');
+  let declared = null;
+  if (fs.existsSync(pkgFile)) {
+    try {
+      const j = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+      const all = { ...(j.dependencies || {}), ...(j.devDependencies || {}), ...(j.optionalDependencies || {}) };
+      declared = all[pkg] ?? null;
+      if (declared) declaredFiles.push(pkgFile);
+    } catch {
+      /* unreadable package.json is reported as unknown, not as satisfied */
+    }
+  }
+  if (!declared) return { root, declared: null, installed: null, satisfied: false, reason: 'not-declared' };
+
+  // Resolve the version a spec pins. Handles plain versions ("0.14.4"),
+  // npm: aliases ("npm:@scope/pkg@0.14.4") and ranges. A range is satisfied by
+  // the installed version rather than by string equality.
+  const spec = String(declared).trim();
+  let want = null;
+  let range = false;
+  if (spec.startsWith('npm:')) {
+    const afterAt = spec.slice(4);
+    const idx = afterAt.lastIndexOf('@');
+    want = idx > 0 ? afterAt.slice(idx + 1) : null;
+  } else if (/^[~^]|^[<>]=?|\|\||\s-\s|\*|x$/i.test(spec)) {
+    range = true;
+  } else {
+    want = spec;
+  }
+
+  const installedCandidates = [
+    path.join(root, 'node_modules', pkg, 'package.json'),
+    // npm: aliases install under the alias directory, which is what .bin shims run.
+    ...aliasDirs(root, pkg),
+  ];
+  let installed = null;
+  for (const file of installedCandidates) {
+    if (!fs.existsSync(file)) continue;
+    try {
+      installed = JSON.parse(fs.readFileSync(file, 'utf8')).version ?? null;
+      if (installed) break;
+    } catch {
+      /* keep looking */
+    }
+  }
+  const satisfied = range ? Boolean(installed) && installed === version : Boolean(want && installed === want);
+  return {
+    root,
+    declared,
+    want,
+    range,
+    installed,
+    satisfied,
+    reason: !installed ? 'not-installed' : satisfied ? 'ok' : 'installed-mismatch',
+  };
+}
+
+/** Alias install dirs for a package, e.g. @ssss/cli -> node_modules/@ssss/cli. */
+function aliasDirs(root, pkg) {
+  const dirs = [];
+  const nm = path.join(root, 'node_modules');
+  if (!fs.existsSync(nm)) return dirs;
+  // Known alias pair for the SSSS CLI: the alias dir is what .bin/ssss executes.
+  if (pkg === '@gregiteen/ssss-cli') {
+    dirs.push(path.join(nm, '@ssss', 'cli', 'package.json'));
+  }
+  return dirs;
+}
+
+export function verifyConsumers(pkg, version, opts = {}) {
+  const roots = consumerRoots(opts);
+  const states = roots.map((root) => consumerState(root, pkg, version));
+  const relevant = states.filter((s) => s.declared);
+  const failing = relevant.filter((s) => !s.satisfied);
+  return {
+    pkg,
+    version,
+    roots_considered: roots.length,
+    consumers: relevant.length,
+    failing: failing.length,
+    failures: failing.map((s) => ({ root: s.root, declared: s.declared, installed: s.installed, reason: s.reason })),
+  };
+}
+
+function runPrepublish(dir, pkgJson, { exec = spawnSync, timeoutMs } = {}) {
+  if (!pkgJson?.scripts?.prepublishOnly) return { ok: true, skipped: true };
+  const manager = fs.existsSync(path.join(dir, 'pnpm-lock.yaml')) ? 'pnpm' : 'npm';
+  const res = exec(manager, ['run', 'prepublishOnly'], { cwd: dir, encoding: 'utf8', stdio: 'pipe', timeout: timeoutMs });
+  return { ok: res.status === 0, skipped: false, output: `${res.stdout || ''}${res.stderr || ''}`.trim() };
+}
+
+function doPublish(dir, { otp, exec = spawnSync, timeoutMs } = {}) {
+  const args = ['publish'];
+  if (otp) args.push('--otp', otp);
+  const res = exec('npm', args, { cwd: dir, encoding: 'utf8', stdio: 'pipe', timeout: timeoutMs });
+  return { ok: res.status === 0, output: `${res.stdout || ''}${res.stderr || ''}`.trim() };
+}
+
+/**
+ * @param {string[]} argv full process argv (bin convention)
+ */
+export async function run(argv = process.argv, deps = {}) {
+  const opts = parseArgs(argv.slice(3));
+  const log = opts.json ? () => {} : (...a) => console.log(...a);
+  const emit = (obj) => { if (opts.json) console.log(JSON.stringify(obj, null, 2)); };
+
+  if (opts.help || !opts.action) {
+    printHelp();
+    if (!opts.action && !opts.help) process.exitCode = 1;
+    return;
+  }
+  if (!ACTIONS.includes(opts.action)) {
+    console.error(`Unknown release action: ${opts.action}. Expected one of: ${ACTIONS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const report = { action: opts.action, packages: {}, ok: false, steps: [] };
+  const fail = (message) => {
+    report.error = message;
+    report.ok = false;
+    if (opts.json) emit(report); else console.error(`\n  ✗ ${message}\n`);
+    process.exitCode = 1;
+  };
+
+  // propagate and verify act on the whole fleet and need no package argument.
+  if (opts.action === 'propagate') {
+    const dryRun = !opts.apply;
+    log(`\n  Propagating ${DEFAULT_PACKAGES.join(' + ')} across every registered consumer${dryRun ? ' (plan)' : ''}...`);
+    const summary = await (deps.updateAllBrains || updateAllBrains)({ dryRun, force: !dryRun, skipThrottle: !dryRun });
+    report.steps.push({ step: 'propagate', dryRun, summary });
+    report.ok = (summary.failed || 0) === 0;
+    if (opts.json) { emit(report); return; }
+    log(`\n  roots: ${summary.root_count ?? '—'}  consumers: ${summary.consumer_count ?? '—'}  failed: ${summary.failed ?? 0}`);
+    if (dryRun) log('  Run with --apply to install.\n');
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+
+  const packages = opts.packages.length ? opts.packages : DEFAULT_PACKAGES;
+  if (!packages.length) return fail('No package given.');
+
+  for (const pkg of packages) {
+    const root = opts.root || process.cwd();
+    const source = readSourcePackage(root, pkg);
+    const entry = { pkg, root, source: source?.file ?? null };
+    report.packages[pkg] = entry;
+
+    if (opts.action === 'verify') {
+      const version = opts.version || source?.pkgJson?.version;
+      if (!version) return fail(`${pkg}: no --version and no source package.json found under ${root}`);
+      entry.version = version;
+      const reg = await awaitPublished(pkg, version, { attempts: 1, delayMs: 0 });
+      entry.registry = reg;
+      const consumers = verifyConsumers(pkg, version, { roots: opts.root ? [opts.root] : [] });
+      entry.consumers = consumers;
+      if (!reg.ok) return fail(`${pkg}@${version} is not readable from the npm registry (${reg.error}).`);
+      if (consumers.failing > 0) {
+        return fail(`${pkg}@${version}: ${consumers.failing}/${consumers.consumers} consumers not satisfied. First: ${consumers.failures[0].root} (${consumers.failures[0].installed ?? 'not installed'}).`);
+      }
+      log(`  ✓ ${pkg}@${version} verified: registry + ${consumers.consumers}/${consumers.consumers} consumers`);
+      continue;
+    }
+
+    if (!source) return fail(`${pkg}: source package.json not found under ${root}. Pass --root <repo>.`);
+    const version = opts.version || source.pkgJson.version;
+    entry.version = version;
+    if (opts.version && source.pkgJson.version !== opts.version) {
+      return fail(`${pkg}: source is ${source.pkgJson.version} but --version ${opts.version} was requested. Bump the source first.`);
+    }
+
+    if (opts.action === 'plan') {
+      const reg = publishedVersion(pkg);
+      entry.registry = reg;
+      entry.gates = source.pkgJson.scripts?.prepublishOnly ? 'present' : 'absent';
+      entry.alreadyPublished = reg.ok && reg.version === version;
+      log(`  ${pkg}: source ${version}, registry ${reg.version ?? '—'}${entry.alreadyPublished ? ' (already published)' : ''}, prepublish gate ${entry.gates}`);
+      continue;
+    }
+
+    if (opts.action === 'publish' || opts.action === 'all') {
+      const reg = publishedVersion(pkg);
+      entry.registry_before = reg;
+      if (reg.ok && reg.version === version) {
+        log(`  · ${pkg}@${version} already published — skipping publish`);
+        entry.published = 'already';
+      } else {
+        if (!opts.apply) return fail(`publish requires --apply (would publish ${pkg}@${version}).`);
+        const gate = runPrepublish(source.dir, source.pkgJson, { timeoutMs: opts.timeoutMs });
+        entry.gate = gate.ok ? 'passed' : 'failed';
+        report.steps.push({ step: 'prepublish', pkg, ok: gate.ok, skipped: gate.skipped });
+        if (!gate.ok) return fail(`${pkg}: prepublishOnly gate failed.\n${gate.output}`);
+        const pub = doPublish(source.dir, { otp: opts.otp, timeoutMs: opts.timeoutMs });
+        entry.publish_output = pub.output;
+        if (!pub.ok) return fail(`${pkg}: npm publish failed.\n${pub.output}`);
+        const confirmed = await (deps.awaitPublished || awaitPublished)(pkg, version, deps);
+        entry.registry_after = confirmed;
+        if (!confirmed.ok) return fail(`${pkg}@${version} published but the registry still reports ${confirmed.version}. Treat as NOT released.`);
+        entry.published = 'yes';
+        log(`  ✓ ${pkg}@${version} published and confirmed on the registry`);
+      }
+      if (opts.action === 'publish') continue;
+    }
+
+    if (opts.action === 'all') {
+      const dryRun = !opts.apply;
+      const summary = await (deps.updateAllBrains || updateAllBrains)({ dryRun, force: !dryRun, skipThrottle: !dryRun });
+      report.steps.push({ step: 'propagate', pkg, summary });
+      if ((summary.failed || 0) > 0) return fail(`${pkg}: propagation reported ${summary.failed} failure(s).`);
+      const consumers = verifyConsumers(pkg, version, {});
+      entry.consumers = consumers;
+      if (consumers.failing > 0) {
+        return fail(`${pkg}@${version}: ${consumers.failing}/${consumers.consumers} consumers still not satisfied after propagation.`);
+      }
+      log(`  ✓ ${pkg}@${version}: registry + ${consumers.consumers}/${consumers.consumers} consumers`);
+    }
+  }
+
+  report.ok = true;
+  if (opts.json) emit(report);
+  else if (opts.action === 'plan') log('\n  Plan only — nothing published or changed.\n');
+  else log('');
+}

package/src/core/cli-commands.mjs

@@ -14,6 +14,7 @@ export const CLI_COMMANDS = {
   restore:  'restore.mjs',
   upgrade:  'upgrade.mjs',
   update:   'update.mjs',
+  release:  'release.mjs',
   friction: 'friction.mjs',
   chat:     'chat.mjs',
   status:   'status.mjs',
@@ -22,6 +23,7 @@ export const CLI_COMMANDS = {
   edit:     'edit.mjs',
   recall:   'recall.mjs',
   context:  'context.mjs',
+  compact:  'compact.mjs',
   preflight: 'preflight.mjs',
   'tr-preflight': 'preflight.mjs',
   'context-stats': 'context-stats.mjs',