total-recall-brain 3.44.0 → 3.46.0

package/src/cli/dream.mjs

@@ -1,84 +1,108 @@
-/**
- * total-recall dream
- *
- * Manually trigger a single dream cycle (Light → REM → Deep Sleep).
- *
- * Usage:
- *   npx total-recall dream [options]
- *
- * Options:
- *   --vault <path>     Override vault directory (default: ~/.agent/memory-vault)
- *   --help             Show this help
- */
-
+/** Run one dream cycle per selected brain. Scheduling belongs to automations. */
+import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { resolveAgentDir, resolveBrainDir, parseLayerFlag, resolveSurfaceDir } from './agent-dir.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { resolveAgentDir, resolveBrainDir, resolveSurfaceDir, getGlobalBrainDir, getGlobalAgentDir } from './agent-dir.mjs';
+import { listUpdateRoots } from '../core/package-auto-update.mjs';
 
-function parseArgs(args) {
-  const opts = { vault: null, help: false };
+export function parseDreamArgs(args) {
+  const opts = { layer: 'global', allBrains: false, dryRun: false, json: false };
+  let explicitLayer;
   for (let i = 0; i < args.length; i++) {
-    switch (args[i]) {
-      case '--vault': opts.vault = args[++i]; break;
-      case '--help': case '-h': opts.help = true; break;
-    }
+    const arg = args[i];
+    if (arg === '--all-brains') opts.allBrains = true;
+    else if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--global' || arg === '--project') {
+      if (explicitLayer && explicitLayer !== arg) throw new Error('Choose --global or --project.');
+      explicitLayer = arg;
+      opts.layer = arg.slice(2);
+    } else if (arg === '--vault') {
+      if (!args[i + 1] || args[i + 1].startsWith('-')) throw new Error('--vault requires a path.');
+      opts.vault = path.resolve(args[++i]);
+    } else throw new Error(`Unknown dream option: ${arg}`);
   }
+  if (opts.allBrains && (opts.vault || explicitLayer)) throw new Error('--all-brains cannot be combined with --vault, --global or --project.');
   return opts;
 }
 
-function printHelp() {
-  console.log(`
-  total-recall dream — Manually trigger a dream cycle
+function target(brainDir, agentDir, surfaceDir, root) {
+  return { root, brainDir, vaultDir: path.join(brainDir, 'memory-vault'),
+    derivedDir: path.join(brainDir, 'memory-derived'), skillsDir: path.join(agentDir, 'skills'),
+    conflictsDir: path.join(brainDir, 'memory-inbox', 'conflicts'),
+    instructionsFile: path.join(surfaceDir, 'INSTRUCTIONS.md') };
+}
 
-  The dream cycle runs three phases:
-    1. Light Sleep — Scan vault for recent modifications
-    2. REM         — Score, conflict-check, and promote/decay candidates
-    3. Deep Sleep  — Recompile the surface (indexes + INSTRUCTIONS.md)
+export function discoverDreamBrains({ brainDir = getGlobalBrainDir(), agentDir = getGlobalAgentDir(), roots } = {}) {
+  const brains = [target(brainDir, agentDir, agentDir, agentDir)];
+  const seen = new Set([fs.existsSync(brainDir) ? fs.realpathSync(brainDir) : path.resolve(brainDir)]);
+  for (const { root } of listUpdateRoots({ brainDir, roots })) {
+    // Fleet selection is explicit. AGENT_DIR must not redirect project brains.
+    const projectAgent = ['.agent', '.agents'].map(name => path.join(root, name))
+      .find(dir => fs.existsSync(path.join(dir, 'skills/total-recall/memory-vault'))
+        || fs.existsSync(path.join(dir, 'skills/total-recall/SKILL.md')));
+    if (!projectAgent) continue;
+    const projectBrain = path.join(projectAgent, 'skills/total-recall');
+    const real = fs.realpathSync(projectBrain);
+    if (seen.has(real)) continue;
+    seen.add(real);
+    brains.push(target(projectBrain, projectAgent, root, root));
+  }
+  return brains;
+}
 
-  Usage: total-recall dream [options]
+async function previewDecay({ vaultDir, derivedDir }) {
+  const [{ loadNodes }, { readAccess }, { decayCandidates }] = await Promise.all([
+    import('../core/vault.mjs'), import('../core/access-ledger.mjs'), import('../core/optimizer.mjs'),
+  ]);
+  return decayCandidates(loadNodes(vaultDir), readAccess(derivedDir)).map(node => node.slug);
+}
 
-  Options:
-    --vault <path>     Override vault directory
-    --global           Dream the global brain (default)
-    --project          Dream the project brain for the current repo
-    --help, -h         Show this help
-`);
+function printHelp() {
+  console.log(`Usage: total-recall dream [--global | --project | --all-brains] [--vault <path>] [--dry-run] [--json]
+  Dream consolidates memory and runs phase 4 decay.
+  --all-brains  Run the global brain and registered project brains on this node, one at a time.
+  --dry-run     List brains and decay candidates without changes or runtime calls.
+  --json        Print an array of per-brain results.
+  --help, -h    Show this help.`);
 }
 
-export default async function dream(args) {
-  const { layer, remainingArgs } = parseLayerFlag(args);
-  const effectiveLayer = layer === 'auto' ? 'global' : layer;
-  const opts = parseArgs(remainingArgs);
+export default async function dream(args = [], dependencies = {}) {
+  let opts;
+  try { opts = parseDreamArgs(args); }
+  catch (error) { console.error(error.message); process.exitCode = 2; return; }
   if (opts.help) { printHelp(); return; }
-
-  const agentDir = resolveAgentDir(effectiveLayer);
-  const brainDir = resolveBrainDir(effectiveLayer);
-  const vaultDir = opts.vault || path.join(brainDir, 'memory-vault');
-  const skillsDir = path.join(agentDir, 'skills');
-  const derivedDir = path.join(brainDir, 'memory-derived');
-  const conflictsDir = path.join(brainDir, 'memory-inbox', 'conflicts');
-  const instructionsFile = path.join(resolveSurfaceDir(effectiveLayer), 'INSTRUCTIONS.md');
-
-  console.error('\n  🌙 Starting dream cycle...\n');
-  const startTime = Date.now();
-
+  const results = [];
   try {
-    const { runDreamCycle } = await import('../core/dream.mjs');
-    const result = await runDreamCycle({
-      vaultDir,
-      skillsDir,
-      derivedDir,
-      conflictsDir,
-      instructionsFile,
-    });
-
-    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-    console.error(`\n  ✅ Dream cycle complete (${elapsed}s) — status: ${result.status}`);
-  } catch (err) {
-    console.error(`\n  ❌ Dream cycle failed: ${err.message}`);
-    console.error(err.stack);
-    process.exit(1);
-  }
+    const brains = opts.allBrains ? (dependencies.discover || discoverDreamBrains)() : [
+      target(resolveBrainDir(opts.layer), resolveAgentDir(opts.layer), resolveSurfaceDir(opts.layer), resolveSurfaceDir(opts.layer)),
+    ];
+    if (opts.vault) {
+      brains[0].vaultDir = opts.vault;
+      brains[0].brainDir = path.dirname(opts.vault);
+      brains[0].derivedDir = path.join(brains[0].brainDir, 'memory-derived');
+      brains[0].conflictsDir = path.join(brains[0].brainDir, 'memory-inbox', 'conflicts');
+    }
+    const run = opts.dryRun ? null : (dependencies.run || (await import('../core/dream.mjs')).runDreamCycle);
+    for (const brain of brains) {
+      let row;
+      try {
+        if (!fs.existsSync(brain.vaultDir)) throw new Error(`Vault not found: ${brain.vaultDir}`);
+        const result = opts.dryRun
+          ? { status: 'dry_run', decay_candidates: await (dependencies.preview || previewDecay)(brain) }
+          : await run(brain);
+        row = { ...brain, ...result };
+      } catch (error) { row = { ...brain, status: 'failed', error: error.message }; }
+      results.push(row);
+      if (!opts.json) {
+        console.log(`${row.brainDir}: ${row.status}${row.error ? ` — ${row.error}` : ''}`);
+        if (row.decay_candidates) console.log(`  Decay candidates: ${row.decay_candidates.join(', ') || 'none'}`);
+        for (const error of row.errors || []) console.error(`  ${error}`);
+      }
+    }
+  } catch (error) { results.push({ status: 'failed', error: error.message }); }
+  if (opts.json) console.log(JSON.stringify(results, null, 2));
+  else if (results.length === 1 && results[0].error && !results[0].brainDir) console.error(results[0].error);
+  if (results.some(row => !['success', 'dry_run'].includes(row.status))) process.exitCode = 1;
+  return results;
 }

package/src/cli/harness.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/** Legacy command door. Native harness behavior is owned by the Meta Harness plugin. */
+/** Legacy command door. Native harness behavior is owned by the Metaharness plugin. */
 import { checkAnyReceipt, findRoot, ACK_COMMAND } from '../core/preflight-receipt.mjs';
 import path from 'node:path';
 
@@ -11,9 +11,9 @@ async function callPlugin(subcommand, args, options = {}) {
   const result = await runPluginCommand(plugin, { subcommand, args: [...args, '--json'], timeoutMs: 600000, ...options });
   let data;
   try { data = JSON.parse(result.output); }
-  catch { throw new Error(`Meta Harness returned invalid JSON for ${subcommand}`); }
+  catch { throw new Error(`Metaharness returned invalid JSON for ${subcommand}`); }
   if (!result.ok || data?.ok === false) {
-    const error = new Error(data?.error || `Meta Harness ${subcommand} failed`);
+    const error = new Error(data?.error || `Metaharness ${subcommand} failed`);
     error.result = data;
     throw error;
   }
@@ -32,7 +32,7 @@ export async function run(argv = []) {
   const asJson = args.includes('--json');
   try {
     if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
-      console.log('Usage: total-recall harness list|usage [--node ID] [--json] | dispatch <id> <task> [--node ID --cwd /remote/workspace] [--write] [--allow-unknown-auth] [--json] | council <task> [--allow-unknown-auth] [--json]. Harness operations delegate to the Meta Harness plugin.');
+      console.log('Usage: total-recall harness list|usage [--node ID] [--json] | dispatch <id> <task> [--node ID --cwd /remote/workspace] [--write] [--allow-unknown-auth] [--json] | council <task> [--allow-unknown-auth] [--json]. Harness operations delegate to the Metaharness plugin.');
       return;
     }
     const command = args[0] || 'list', positional = [];

package/src/cli/help.mjs

@@ -19,7 +19,7 @@ const ROOT = path.join(__dirname, '..', '..');
 export default async function run(argv) {
   const args = argv || [];
   const requestedTopic = args.find(arg => !arg.startsWith('-'))?.toLowerCase() || null;
-  const topic = ({ server: 'start', 'startup-check': 'startup' })[requestedTopic] || requestedTopic;
+  const topic = ({ 'startup-check': 'startup' })[requestedTopic] || requestedTopic;
   const isJson = args.includes('--json') || args.includes('-j');
 
   const cliRefPath = path.join(ROOT, 'docs', 'reference', 'cli-reference.md');

package/src/cli/init.mjs

@@ -407,31 +407,6 @@ export default async function init(args) {
     logOk('Default memory vault seeded');
   }
 
-  // ── Step 3.5: Seed the onboarding interview task ──
-  logStep('3.5/4', 'Seeding onboarding interview into scheduler queue');
-
-  const queueDir = path.join(brainDir, 'scheduler', 'queue');
-  const interviewDest = path.join(queueDir, 'onboarding-interview.md');
-  const interviewSrc = path.join(ROOT, 'templates', 'onboarding-interview.md');
-
-  if (!fs.existsSync(interviewDest)) {
-    if (!opts.dryRun) {
-      fs.mkdirSync(queueDir, { recursive: true });
-      if (fs.existsSync(interviewSrc)) {
-        const now = new Date().toISOString();
-        const content = fs.readFileSync(interviewSrc, 'utf8').replace(/\{\{CREATED_AT\}\}/g, now);
-        fs.writeFileSync(interviewDest, content);
-        logOk('Onboarding interview task queued — agent will conduct it on first chat');
-      } else {
-        logWarn('Interview template not found — skipping');
-      }
-    } else {
-      log(`  Would write ${path.relative(cwd, interviewDest)}`);
-    }
-  } else {
-    logSkip('onboarding-interview.md already in queue');
-  }
-
   // Seed non-credential settings. Auth owns password and signing state.
   if (!opts.dryRun) {
     const configDir = path.join(brainDir, 'config');

package/src/cli/lessons.mjs

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicWrite } from '../core/vault.mjs';
+import { parseLayerFlag, resolveBrainDir } from './agent-dir.mjs';
+import { tickLessons, enqueueSessionReviews } from '../core/lessons.mjs';
+
+export default async function lessons(args) {
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  const [command, ...flags] = remainingArgs;
+  if (!command || flags.includes('--help') || ['--help', '-h'].includes(command)) {
+    console.log('Usage: total-recall lessons tick|session-end|scan [--session ID] [--transcript PATH] [--harness ID] [--interval N] [--hold]\nHooks pass JSON on stdin. Stop queues completed turn ranges; session-end queues the remaining turns. scan reviews locally ingested sessions.');
+    return;
+  }
+  if (!['tick', 'session-end', 'scan'].includes(command)) throw new Error(`Unknown lessons command: ${command}`);
+  const opts = {};
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    if (flag === '--hold') { opts.hold = true; continue; }
+    if (!['--session', '--transcript', '--harness', '--interval', '--event'].includes(flag) || !flags[i + 1]) throw new Error(`Invalid lessons option: ${flag}`);
+    opts[flag.slice(2)] = flags[++i];
+  }
+  const brainDir = resolveBrainDir(layer);
+  if (command === 'scan') {
+    console.log(JSON.stringify(enqueueSessionReviews({ brainDir, interval: opts.interval ? Number(opts.interval) : undefined, hold: opts.hold })));
+    return;
+  }
+  let input = {};
+  if (!process.stdin.isTTY && !opts.session) {
+    const raw = fs.readFileSync(0, 'utf8');
+    if (raw.trim()) input = JSON.parse(raw);
+  }
+  const history = input.entries || input.conversation_history || input.extra?.conversation_history;
+  if (!opts.transcript && !input.transcript_path && Array.isArray(history)) {
+    const id = input.session_id || input.sessionId;
+    if (!id) throw new Error('Lesson hook history requires a session id');
+    const key = crypto.createHash('sha256').update(`${opts.harness || 'unknown'}:${id}`).digest('hex').slice(0, 12);
+    const dir = path.join(brainDir, 'sessions');
+    fs.mkdirSync(dir, { recursive: true });
+    opts.transcript = path.join(dir, `${key}.jsonl`);
+    atomicWrite(opts.transcript, history.map(entry => JSON.stringify(entry)).join('\n') + '\n');
+  }
+  const result = tickLessons({ brainDir, sessionId: opts.session || input.session_id || input.sessionId || input.conversation_id,
+    transcriptPath: opts.transcript || input.transcript_path || input.transcriptPath,
+    harness: opts.harness || 'unknown', turnId: input.turn_id || input.prompt_id,
+    event: command === 'session-end' ? 'SessionEnd' : (opts.event || input.hook_event_name || input.event || 'Stop'),
+    interval: opts.interval ? Number(opts.interval) : undefined, hold: opts.hold });
+  // Hook JSON must not ask the harness to continue, stop, or approve a tool.
+  if (opts.session) console.log(JSON.stringify(result));
+  else console.log('{}');
+}

package/src/cli/memory-plugin.mjs

@@ -26,6 +26,6 @@ export default async function plugin(args = []) {
     const result = await uninstallPlugin(value, { projectRoot: process.cwd(), global: global ? true : undefined });
     console.log(JSON.stringify(result, null, 2));
   } else if (['help', '--help', '-h'].includes(action)) {
-    console.log('Usage: total-recall plugin list|info <id>|install <directory-or-git-url>|remove <id> [--global] [--link]');
+    console.log('Usage: total-recall plugin list|info <id>|install <directory-or-git-url>|remove <id> [--link]');
   } else throw new Error(`Unsupported plugin action '${action}'`);
 }

package/src/cli/plugin/chunks.mjs

@@ -0,0 +1,145 @@
+import { parseArgs } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import { auditUiChunkCoverage, getUiChunk, searchUiChunks, uiChunkRegistryPath, validateUiChunkFile } from '../../core/ui-chunks.mjs';
+import { chooseUiChunk } from '../../core/ui-chunk-choice.mjs';
+import { callApi } from '../api.mjs';
+
+const help = [
+  'Usage: total-recall plugin chunks [query] [--plugin ID] [--surface page|left|right|bottom] [--limit N] [--decision|--workspace] [--brain ID] [--json]',
+  '       total-recall plugin chunks get <plugin:id> [--surface SURFACE] [--workspace] [--brain ID] [--json]',
+  '       total-recall plugin chunks validate <file> [--plugin-dir DIR] [--json]',
+  '       total-recall plugin chunks registry',
+  '       total-recall plugin chunks coverage [--plugin ID] [--json]',
+  '       total-recall plugin chunks add <id.md> --plugin ID [--brain ID] [--json]',
+  '       total-recall plugin chunks page <id> --brain ID [--json]',
+  '       total-recall plugin chunks page <id> <plugin:block>... --brain ID (--title TITLE | --revision VERSION) [--json]',
+  '',
+  'Use --decision with a concise, non-sensitive query to request a ranked choice through the configured Decision plugin.',
+  'Search and validation run locally by default. Decision requests send only the query and up to 20 eligible metadata records.',
+  'Agents use total-recall decision compose to publish a Jev-selected page.',
+].join('\n');
+
+export async function runPluginChunks(args) {
+  const asJson = args.includes('--json');
+  try {
+    const { values, positionals } = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        json: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+        decision: { type: 'boolean' },
+        workspace: { type: 'boolean' },
+        brain: { type: 'string' },
+        surface: { type: 'string' },
+        plugin: { type: 'string' },
+        limit: { type: 'string' },
+        'plugin-dir': { type: 'string' },
+        title: { type: 'string' },
+        revision: { type: 'string' },
+      },
+    });
+    if (values.help) return console.log(help);
+
+    const [verb, target, ...extra] = positionals;
+    if (verb === 'page') {
+      const { brain, title, revision } = values;
+      if (!target || !brain?.trim() || values.plugin || values.workspace || values.decision || values.surface || values.limit || values['plugin-dir']) throw new Error(help);
+      const writing = extra.length > 0;
+      const create = typeof title === 'string' && title.trim() && revision === undefined;
+      const edit = typeof revision === 'string' && revision.trim() && title === undefined;
+      if (writing ? !create && !edit : title !== undefined || revision !== undefined) throw new Error(help);
+      const collection = '/api/workspace/pages';
+      const detail = collection + '/' + encodeURIComponent(target);
+      const response = !writing
+        ? await callApi('GET', detail, { query: { brain } })
+        : await callApi(edit ? 'PUT' : 'POST', edit ? detail : collection, {
+          data: JSON.stringify({ id: target, brainId: brain, title, revision, keys: extra }),
+        });
+      if (!response.ok) throw new Error(response.body?.error || 'Could not access the saved page.');
+      const page = response.body;
+      if (asJson) return console.log(JSON.stringify({ ok: true, ...page }));
+      console.log(page.path || `${page.title} (${page.version})`);
+      for (const chunk of page.chunks) console.log(chunk.key);
+      return;
+    }
+    if (values.title !== undefined || values.revision !== undefined) throw new Error(help);
+    if (values.brain !== undefined && ((!values.workspace && verb !== 'add') || !values.brain.trim())) {
+      throw new Error('--brain requires a registered brain ID and --workspace, or an add operation.');
+    }
+    if (values.workspace && (values.decision || ['add', 'coverage', 'registry', 'validate'].includes(verb))) throw new Error(help);
+    if (verb === 'add') {
+      if (!target || !values.plugin || extra.length || values.decision || values.surface || values.limit || values['plugin-dir'] || path.extname(target) !== '.md') throw new Error(help);
+      const stat = fs.statSync(target);
+      if (!stat.isFile() || stat.size > 64 * 1024) throw new Error('Choose a Markdown block no larger than 64 KiB.');
+      const markdown = fs.readFileSync(target, 'utf8');
+      const { ok, body } = await callApi('POST', '/api/ui-chunks/pool', {
+        data: JSON.stringify({ plugin: values.plugin, id: path.basename(target, '.md'), markdown, brainId: values.brain }),
+      });
+      if (!ok) throw new Error(body?.error || 'The dashboard could not add the block.');
+      return console.log(asJson ? JSON.stringify({ ok, ...body }) : 'Added ' + body.chunk.key);
+    }
+    if (verb === 'coverage') {
+      if (target || values.decision || values.surface || values.limit || values['plugin-dir']) throw new Error(help);
+      const plugins = auditUiChunkCoverage({ plugin: values.plugin });
+      if (values.plugin && !plugins.length) throw new Error('Plugin is not installed.');
+      if (asJson) return console.log(JSON.stringify({ ok: true, plugins }));
+      for (const item of plugins) {
+        const bound = item.operations.total - item.operations.missing.length;
+        console.log(`${item.plugin}: ${item.pageBlocks} page blocks, ${bound}/${item.operations.total} operations, ${item.dataBindings.length} data bindings, design ${item.design || 'missing'}${item.partial ? ' (partial audit)' : ''}`);
+      }
+      return;
+    }
+    if (verb === 'registry') {
+      if (target || values.decision || values.surface || values.plugin || values.limit || values['plugin-dir']) throw new Error(help);
+      return console.log(asJson ? JSON.stringify({ ok: true, file: uiChunkRegistryPath }) : uiChunkRegistryPath);
+    }
+    if (verb === 'validate') {
+      if (!target || extra.length || values.decision || values.surface || values.plugin || values.limit) throw new Error(help);
+      const chunk = validateUiChunkFile(target, { pluginDir: values['plugin-dir'] });
+      return console.log(asJson ? JSON.stringify({ ok: true, chunk }) : 'Validated ' + chunk.key);
+    }
+    if (values['plugin-dir']) throw new Error('--plugin-dir is only available with validate.');
+    if (verb === 'get') {
+      if (!target || extra.length || values.decision || values.plugin || values.limit) throw new Error(help);
+      const [plugin, id, ...rest] = target.split(':');
+      if (!plugin || !id || rest.length) throw new Error('Specify a chunk as plugin:id.');
+      const query = values.surface ? { surface: values.surface } : {};
+      if (values.brain) query.brain = values.brain;
+      const chunk = values.workspace
+        ? (await callApi('GET', `/api/ui-chunks/${encodeURIComponent(plugin)}/${encodeURIComponent(id)}`, { query })).body?.chunk
+        : getUiChunk(plugin, id, { surface: values.surface });
+      if (!chunk) throw new Error('UI chunk unavailable.');
+      return console.log(asJson ? JSON.stringify({ ok: true, chunk }) : chunk.html);
+    }
+
+    const query = positionals.join(' ').trim();
+    const limit = values.limit === undefined ? undefined : Number(values.limit);
+    if (values.decision && !query) throw new Error('--decision requires an explicit query.');
+    let result;
+    if (values.workspace) {
+      const filters = Object.fromEntries(Object.entries({ plugin: values.plugin, surface: values.surface, q: query, limit, brain: values.brain }).filter(([, value]) => value !== undefined));
+      const response = await callApi('GET', '/api/ui-chunks', { query: filters });
+      if (!response.ok) throw new Error(response.body?.error || 'The dashboard could not read the workspace pool.');
+      result = response.body;
+    } else {
+      result = searchUiChunks({ plugin: values.plugin, surface: values.surface, query, limit });
+    }
+    if (values.decision) result.selection = await chooseUiChunk(result.chunks, query, values.surface);
+    if (asJson) return console.log(JSON.stringify({ ok: true, ...result }));
+    for (const chunk of result.chunks) console.log(chunk.key + '  ' + chunk.title + '  [' + chunk.surfaces.join(', ') + ']');
+    if (!result.chunks.length) console.log('No eligible UI chunks.');
+    for (const issue of result.diagnostics) {
+      console.error(issue.plugin + (issue.id ? ':' + issue.id : '') + '  ' + issue.message);
+    }
+    if (result.selection) {
+      const { key, source, reason } = result.selection;
+      console.log('Selection (' + source + '): ' + (key ?? 'none') + (reason ? ' (' + reason + ')' : ''));
+    }
+  } catch (error) {
+    process.exitCode = 1;
+    if (asJson) console.log(JSON.stringify({ ok: false, error: error.message }));
+    else console.error(error.message);
+  }
+}

package/src/cli/plugin/copies.mjs

@@ -1,17 +1,21 @@
 /**
- * Audit and remove per-repository copies of the shared default plugins.
+ * Audit and remove plugin installs inside a repository.
  *
- * One shared plugin folder per machine is the design; copies inside repositories
- * are leftovers from an earlier release that put the nine defaults in every
- * brain. Only copies matching the bundled source can be deleted. The operator
- * can explicitly archive older differing copies to use the shared versions.
+ * Nothing is installed per repository: every plugin lives in the one shared
+ * folder and a repository only switches it on or off. Entries found in a
+ * repository are leftovers. Copies matching the bundled source are deleted;
+ * older differing copies can be archived on request; shadow links (to a plugin
+ * the shared folder installs, or any linked default) are removed as links only.
+ * A repository-only plugin is reported until it is installed in the shared folder.
  */
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { auditProjectPluginCopies } from '../../core/required-plugins.mjs';
-import { globalPluginsDir } from '../../core/plugin-loader.mjs';
-import { recompileAfterPluginMutation, replacementArchiveDir } from '../../core/plugin-store.mjs';
+import { globalPluginsDir, projectPluginsDir, vaultForPluginsDir } from '../../core/plugin-loader.mjs';
+import { recompileAfterPluginMutation, replacementArchiveDir, recordPath } from '../../core/plugin-store.mjs';
+import { findVfsDocumentByPath } from '../../core/vfs-documents.mjs';
+import { deleteVfsDocument } from '../../core/ssss-operation-service.mjs';
 
 export function pluginCopyRows(projectRoot = process.cwd(), { sharedDir = globalPluginsDir() } = {}) {
   const audit = auditProjectPluginCopies(projectRoot, { sharedDir });
@@ -19,7 +23,9 @@ export function pluginCopyRows(projectRoot = process.cwd(), { sharedDir = global
     root: projectRoot,
     sharedDir,
     count: audit.count,
-    removable: audit.copies.filter(copy => copy.edited === false && copy.sharedDir && !copy.linked).map(copy => copy.id),
+    removable: audit.copies.filter(copy => (copy.edited === false && copy.sharedDir && !copy.linked) || copy.shadow).map(copy => copy.id),
+    shadows: audit.copies.filter(copy => copy.shadow).map(copy => copy.id),
+    repoOnly: audit.copies.filter(copy => copy.repoOnly).map(copy => copy.id),
     archivable: audit.copies.filter(copy => copy.stale && copy.edited !== false && !copy.linked).map(copy => copy.id),
     edited: audit.copies.filter(copy => copy.edited === true && copy.stale !== true).map(copy => copy.id),
     stale: audit.copies.filter(copy => copy.stale === true).map(copy => copy.id),
@@ -28,13 +34,49 @@ export function pluginCopyRows(projectRoot = process.cwd(), { sharedDir = global
   };
 }
 
+/**
+ * Install records in this repository's brain for plugins that exist neither in
+ * the repository nor in the shared folder. They describe a repository install
+ * that is gone, so no on/off overlay is lost by removing them.
+ */
+export function orphanRecordIds(projectRoot, { sharedDir = globalPluginsDir() } = {}) {
+  const vaultRoot = vaultForPluginsDir(projectPluginsDir(projectRoot));
+  const dir = path.join(vaultRoot, 'system', 'plugins');
+  let files = [];
+  try { files = fs.readdirSync(dir).filter(name => name.endsWith('.md')); } catch { return []; }
+  return files.map(name => name.slice(0, -3)).filter(id => {
+    if (fs.existsSync(path.join(projectPluginsDir(projectRoot), id))) return false;
+    if (fs.existsSync(path.join(sharedDir, id))) return false;
+    const record = findVfsDocumentByPath(recordPath(id), vaultRoot);
+    return record?.frontmatter?.type === 'plugin_record' && record.frontmatter.source?.kind !== 'shared';
+  });
+}
+
+async function removeOrphanRecords(projectRoot, ids) {
+  const vaultRoot = vaultForPluginsDir(projectPluginsDir(projectRoot));
+  const removed = [];
+  const failed = [];
+  for (const id of ids) {
+    try {
+      await deleteVfsDocument(recordPath(id), { actorRole: 'system', intent: `Remove repository install record ${id}`, vaultRoot });
+      removed.push(id);
+    } catch (error) {
+      failed.push({ id, error: error.message });
+    }
+  }
+  return { removed, failed };
+}
+
 export function removePluginCopies(projectRoot, ids) {
   const removed = [];
   const failed = [];
   for (const id of ids) {
     const dir = path.join(projectRoot, '.agent', 'skills', 'total-recall', 'plugins', id);
     try {
-      fs.rmSync(dir, { recursive: true, force: true });
+      // A link is removed by itself: its target checkout and this repository's
+      // plugin records (including on/off overlays) are left untouched.
+      if (fs.lstatSync(dir).isSymbolicLink()) fs.unlinkSync(dir);
+      else fs.rmSync(dir, { recursive: true, force: true });
       removed.push(id);
     } catch (error) {
       failed.push({ id, error: error.message });
@@ -65,28 +107,36 @@ export async function manageProjectPluginCopies(args = []) {
   const json = args.includes('--json');
   const apply = args.includes('--apply');
   const archiveStale = args.includes('--archive-stale');
+  const dropRepoOnly = args.includes('--drop-repo-only');
   const roots = args.filter(argument => !argument.startsWith('-'));
   const root = roots[0] || process.cwd();
   const report = pluginCopyRows(root);
   if (apply) {
-    report.removal = removePluginCopies(root, report.removable);
+    report.removal = removePluginCopies(root, dropRepoOnly ? [...new Set([...report.removable, ...report.repoOnly])] : report.removable);
+    report.records = await removeOrphanRecords(root, orphanRecordIds(root, { sharedDir: report.sharedDir }));
     if (archiveStale) report.archival = archivePluginCopies(report.copies.filter(copy => report.archivable.includes(copy.id)));
-    if (report.removal.removed.length || report.archival?.archived.length) {
+    if (report.removal.removed.length || report.records.removed.length || report.archival?.archived.length) {
       report.compilation = await recompileAfterPluginMutation(root);
     }
-    if (report.removal.failed.length || report.archival?.failed.length || report.compilation?.ok === false) process.exitCode = 1;
+    if (report.removal.failed.length || report.records.failed.length || report.archival?.failed.length || report.compilation?.ok === false) process.exitCode = 1;
   }
+  if (!apply) report.orphanRecords = orphanRecordIds(root, { sharedDir: report.sharedDir });
   if (json) {
     console.log(JSON.stringify(report, null, 2));
     return;
   }
-  console.log(`\n📦 Per-repository copies of shared plugins in ${report.root}\n`);
+  console.log(`\n📦 Plugin installs inside ${report.root} (all plugins belong in the shared folder)\n`);
+  const records = report.records?.removed || report.orphanRecords || [];
+  if (records.length) console.log(`  ${report.records ? 'Removed' : 'Leftover'} install records for plugins installed nowhere: ${records.join(', ')}${report.records ? '' : ' (re-run with --apply)'}`);
+  if (report.records?.failed.length) console.error(`  Could not remove records: ${report.records.failed.map(row => row.id).join(', ')}`);
   if (report.count === 0) {
     console.log('  None — this repository resolves the shared folder directly.\n');
     return;
   }
   for (const copy of report.copies) {
-    const verdict = copy.linked ? 'linked checkout'
+    const verdict = copy.repoOnly ? `REPOSITORY-ONLY install${copy.target ? ` (link to ${copy.target})` : ''} — install it in the shared folder (plugin install <source>), or delete it with --apply --drop-repo-only`
+      : copy.shadow ? `SHADOW link to ${copy.target} — shadows the shared install`
+      : copy.linked ? 'linked checkout'
       : copy.stale === true ? 'STALE — older than the shared install and shadows it'
       : copy.edited === false ? 'identical to the bundled source'
       : copy.edited === true ? 'DIFFERS from the shared install' : 'no shared install to compare';