total-recall-brain 3.44.0 → 3.45.0

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

@@ -1,19 +1,19 @@
 {
   "name": "tr-plugin-security",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-security",
-      "version": "0.3.6",
+      "version": "0.3.7",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
         "jsdom": "^26.1.0",
-        "total-recall-brain": "3.43.3"
+        "total-recall-brain": "3.44.0"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5698,9 +5698,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.43.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.43.3.tgz",
-      "integrity": "sha512-yjfPN/BQxEEa+iodyFXQov/6fRt1pZg/7RcmgsbpALwBt6Ki3JJjT3tzArBC7NxHQmXgGYyKnCYId6xe/W2rPg==",
+      "version": "3.44.0",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.44.0.tgz",
+      "integrity": "sha512-VNPaIO9zsSwoxAsJ5ByIQBP9zPpLq4RiQO7Vrex4rBOHFQJT50P7utcZiLMSZTyZJU4C/m5uB8qTCSBMp6+l6Q==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -5708,7 +5708,7 @@
       ],
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
-        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.4",
+        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.5",
         "bcrypt": "^6.0.0",
         "better-sqlite3": "^12.11.1",
         "cookie-parser": "^1.4.7",

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

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-security",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "description": "Standalone security suite for Total Recall: static analysis, file and permission hardening schemes, AES-256-GCM encryption tools, and egress audit controls",
   "scripts": {

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

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "security",
   "name": "Security Assessments",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Machine and device security assessments for macOS, Linux, Windows, Android, Chromebook, iPhone and iPad, with explicit measured and manual coverage.",
   "license": "MIT",
   "requires": [{ "id": "auth", "range": ">=1.2.1" }],

package/scaffold/.agent/skills/total-recall/references/operations.md

@@ -16,7 +16,7 @@ Publication/deployment use the owning push/deploy procedures when authorized. Sh
 
 Use `brain status` to check the current project and physical global storage. Preview `brain relocate-global <dir>` before adding `--apply`. The destination must be a new private directory outside Git on the same filesystem as home. The home skills path links to the relocated tree. Keep repository brains in their own directories.
 
-Run normal preflight from home for global orchestration. Pass a repository working directory when routing repository work through Meta Harness. Use `plugin copies` to audit old project copies of shared defaults. `--apply` deletes verified bundled matches. Add `--archive-stale` to retain differing older copies in the replacement archive and use the shared versions.
+Run normal preflight from home for global orchestration. Pass a repository working directory when routing repository work through Metaharness. Use `plugin copies` to audit old project copies of shared defaults. `--apply` deletes verified bundled matches. Add `--archive-stale` to retain differing older copies in the replacement archive and use the shared versions.
 
 ## Optional developer API
 

package/src/cli/agent.mjs

@@ -31,7 +31,7 @@ Options:
   --allow-unknown-auth     Explicitly permit a harness without a verified login probe
 
 Auth:
-  The Meta Harness owner probes login and resolves only adapter-declared credentials through auth.
+  The Metaharness owner probes login and resolves only adapter-declared credentials through auth.
 
 Available Harnesses:
   agy, claude, codex, dsh, hermes, openclaw

package/src/cli/command.mjs

@@ -247,21 +247,59 @@ function existingTag(file, key) {
   try { return fs.readFileSync(file, 'utf8').match(new RegExp(`^// @${key} (.+)$`, 'm'))?.[1] || undefined; } catch { return undefined; }
 }
 
+/** Where the background recompile records its outcome: <agentDir>/state and <agentDir>/logs. */
+export function compileRecordPaths(isGlobal) {
+  const agentDir = path.dirname(resolveTargetDir(isGlobal));
+  return {
+    status: path.join(agentDir, 'state', 'command-compile.json'),
+    log: path.join(agentDir, 'logs', 'command-compile.log'),
+  };
+}
+
+// Runs in the detached child: compile, then record the exit code and output.
+const COMPILE_RECORDER = `
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const [cli, layer, statusFile, logFile] = process.argv.slice(1);
+const startedAt = new Date().toISOString();
+const r = spawnSync(process.execPath, [cli, 'compile', layer], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+const code = r.status === null ? 1 : r.status;
+fs.writeFileSync(logFile, (r.stdout || '') + (r.stderr || '') + (r.error ? String(r.error) + '\\n' : ''));
+const record = { ok: code === 0, code, signal: r.signal || null, layer, startedAt, finishedAt: new Date().toISOString(), log: logFile };
+fs.writeFileSync(statusFile + '.tmp', JSON.stringify(record, null, 2));
+fs.renameSync(statusFile + '.tmp', statusFile);
+`;
+
 /**
  * Composable instructions: the surfaces list every command, so any change to
  * the command set recompiles them (project layer, or every project for global).
+ * A global compile takes minutes, so it runs in the background; its exit code and
+ * output are recorded, and the next `command` call reports a failure.
  */
 export function recompileSurfaces(isGlobal) {
   if (process.env.TR_COMMAND_NO_COMPILE === '1' || !process.argv[1]) return;
   try {
-    const child = spawn(process.execPath, [process.argv[1], 'compile', isGlobal ? '--global' : '--project'], { detached: true, stdio: 'ignore' });
+    const { status, log } = compileRecordPaths(isGlobal);
+    fs.mkdirSync(path.dirname(status), { recursive: true });
+    fs.mkdirSync(path.dirname(log), { recursive: true });
+    const child = spawn(process.execPath, ['-e', COMPILE_RECORDER, process.argv[1], isGlobal ? '--global' : '--project', status, log], { detached: true, stdio: 'ignore' });
     child.unref();
-    console.log('  ⏳ Instruction surfaces recompiling in the background (command list updated).');
+    console.log(`  ⏳ Instruction surfaces recompiling in the background (command list updated). Outcome: ${status}`);
   } catch (error) {
     console.warn(`  ⚠️  Command saved, but surface recompile failed to start: ${error.message}`);
+    process.exitCode = 1;
   }
 }
 
+/** Report a failed background recompile; returns the record when it failed. */
+export function reportFailedCompile(isGlobal, out = console.warn) {
+  let record;
+  try { record = JSON.parse(fs.readFileSync(compileRecordPaths(isGlobal).status, 'utf8')); } catch { return null; }
+  if (record.ok) return null;
+  out(`  ❌ The last instruction-surface recompile (${record.layer}, ${record.finishedAt}) failed with exit ${record.code}. Surfaces may not list current commands. Log: ${record.log}. Run 'total-recall compile ${record.layer}' to retry.`);
+  return record;
+}
+
 /**
  * Register every `commands` entry of an installed plugin as a composable command.
  * A command that already exists and was generated from this plugin is refreshed;
@@ -319,6 +357,7 @@ export default async function commandCmd(rawArgs = []) {
 
   const action = cleanArgs[0];
   const name = cleanArgs[1];
+  if (process.env.TR_COMMAND_NO_COMPILE !== '1') reportFailedCompile(isGlobal);
 
   if (!action || action === '--help' || action === '-h') {
     printHelp();

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/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';