total-recall-brain 3.41.1 → 3.41.3

package/scaffold/.agent/skills/total-recall/plugins/security/cli.mjs

@@ -907,7 +907,13 @@ export async function run(argv = []) {
   }
   if (IMPLEMENTED[sub]) {
     try { return await IMPLEMENTED[sub](args.slice(1)); }
-    catch { console.log(JSON.stringify({ status: 'failed', operation: sub, error: 'Security operation failed; verify arguments, owning plugin availability and authorization. No success was established.' })); process.exitCode = 1; return; }
+    catch (error) {
+      // Say what failed. The generic text hid every cause, including a scan that
+      // simply hit its coverage limit. Messages are paths and limits, never matched content.
+      console.log(JSON.stringify({ status: 'failed', operation: sub, error: `Security operation failed: ${String(error?.message || error).slice(0, 300)}. No success was established.` }));
+      process.exitCode = 1;
+      return;
+    }
   }
   console.error(`Security: "${sub}" is not implemented.`);
   process.exitCode = 2;

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

@@ -1,16 +1,16 @@
 {
   "name": "tr-plugin-security",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-security",
-      "version": "0.3.2",
+      "version": "0.3.3",
       "license": "MIT",
       "devDependencies": {
         "jsdom": "^26.1.0",
-        "total-recall-brain": "^3.40.7"
+        "total-recall-brain": "3.41.2"
       }
     },
     "node_modules/@asamuzakjp/css-color": {
@@ -2916,9 +2916,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.7",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.7.tgz",
-      "integrity": "sha512-G+sEWXVucI5Zs8uV1ie8P+mV/6cncWX76ES72T5dnPB3sFAwlcG9ous2SYTUaYUOETGB2vHTSo3cV4XWkHQ0Ww==",
+      "version": "3.41.2",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.2.tgz",
+      "integrity": "sha512-bwJFAFAyvk9ysf+5zhBzMxrKus1Hj1AygUWdBNt+vQbM2sfSEf6701sa30KwfGyU8+cMuN6YNT5Mn63mFZIi/w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

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

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-security",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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.2",
+  "version": "0.3.3",
   "description": "Machine and device security assessments for macOS, Linux, Windows, Android, Chromebook, iPhone and iPad, with explicit measured and manual coverage.",
   "license": "MIT",
   "branding": {

package/scaffold/.agent/skills/total-recall/plugins/security/src/scanner.mjs

@@ -5,8 +5,12 @@ import path from 'node:path';
 export function scanSource(targetPath) {
   const root = fs.realpathSync(path.resolve(targetPath));
   const findings = [];
-  const skipped = new Set(['node_modules', '.git', 'dist', 'coverage', 'memory-vault', '.cache', '.venv', '__pycache__']);
+  // Generated brain data (indexes, sessions, logs) is not source; scanning it
+  // only hit the size limit and aborted the whole scan.
+  const skipped = new Set(['node_modules', '.git', 'dist', 'coverage', 'memory-vault', 'memory-derived', 'sessions', '.cache', '.venv', '__pycache__']);
+  const MAX_FILES = 20000, MAX_BYTES = 2097152;
   let count = 0;
+  let limited = false;
   function visit(file) {
     const stat = fs.lstatSync(file);
     if (stat.isSymbolicLink()) {
@@ -14,11 +18,21 @@ export function scanSource(targetPath) {
       return;
     }
     if (stat.isDirectory()) {
-      for (const name of fs.readdirSync(file)) if (!skipped.has(name)) visit(path.join(file, name));
+      for (const name of fs.readdirSync(file)) { if (limited) return; if (!skipped.has(name)) visit(path.join(file, name)); }
       return;
     }
     if (!stat.isFile() || !/\.(?:[cm]?js|tsx?|py|sh|bash|ps1|json|env|ya?ml)$|(?:^|\/)\.env(?:\.|$)/.test(file)) return;
-    if (++count > 20000 || stat.size > 2097152) throw new Error('Scan coverage limit exceeded; narrow the target');
+    // Report incomplete coverage as a finding instead of aborting: an aborted
+    // scan returned nothing, which callers could not tell apart from a failure.
+    if (stat.size > MAX_BYTES) {
+      findings.push({ file: path.relative(root, file), line: 0, rule: 'oversized-file-unscanned', severity: 'HIGH', detail: `Larger than ${MAX_BYTES} bytes; not inspected, coverage incomplete` });
+      return;
+    }
+    if (++count > MAX_FILES) {
+      limited = true;
+      findings.push({ file: '.', line: 0, rule: 'coverage-limit-reached', severity: 'HIGH', detail: `Stopped after ${MAX_FILES} files; narrow the target, coverage incomplete` });
+      return;
+    }
     const testFile = /(?:^|\/)(?:test|tests|fixtures)(?:\/|$)|\.(?:test|spec)\./.test(file);
     fs.readFileSync(file, 'utf8').split('\n').forEach((line, index) => {
       const rules = [];

package/scaffold/.agent/skills/total-recall/plugins/security/ui/DESIGN.md

@@ -1,18 +1,41 @@
-# DESIGN.md — Tin Foil
+# DESIGN.md — Security Plugin (Tin Foil)
 
-```yaml
-tokens:
-  brand-name: "Tin Foil"
-  wordmark: "[TIN//FOIL]"
-  color-primary: "#f59e0b"
-  color-background: "#0a0a0c"
-  color-accent: "#e2e8f0"
-  badge: "Hardening"
-  font-mono: "'JetBrains Mono', 'Fira Code', monospace"
-  border-radius: "8px"
+## Brand Identity & Aesthetic
+- **Brand Name**: Tin Foil
+- **Wordmark**: `[TIN//FOIL]`
+- **Theme**: Crimson and Obsidian Host Hardening Console
+- **Tone**: Deterministic, vigilant, fail-closed, precise
+
+## Design Tokens
+
+The card face defines and consumes these custom properties:
+
+```css
+:host {
+  --face-bg: #180d11;
+  --face-bg-subtle: #251017;
+  --face-bg-surface: #11070a;
+  --face-bg-table: #0d0508;
+  --face-bg-code: #0a0406;
+  --face-accent: #f43f5e;
+  --face-accent-hover: rgba(244, 63, 94, 0.22);
+  --face-accent-glow: rgba(244, 63, 94, 0.35);
+  --face-border-subtle: rgba(244, 63, 94, 0.28);
+  --face-border-faint: rgba(244, 63, 94, 0.2);
+  --face-border-cell: rgba(244, 63, 94, 0.15);
+  --face-border-alert: rgba(244, 63, 94, 0.25);
+  --face-text: #f1f5f9;
+  --face-text-heading: #fecdd3;
+  --face-text-muted: #fda4af;
+  --face-text-cell: #f8fafc;
+  --face-text-desc: #cbd5e1;
+  --face-danger: #fb7185;
+  --face-warning: #fca5a5;
+}
 ```
 
-## Brand & Typographic Wordmark
-- **Name**: Tin Foil
-- **Wordmark Logo**: `[TIN//FOIL]` (custom typographic badge, no generic icons)
-- **Palette**: Primary `#f59e0b`, Surface `#0a0a0c`, Accent `#e2e8f0`.
+## System Integration
+- The face binds `--text-primary` with fallback to `var(--face-text)`.
+- The face binds `--border` with fallback to `var(--face-accent-glow)`.
+- All clickable elements enforce a minimum height of 44px for touch ergonomics.
+- Reduced motion styles suppress animation when requested by system settings.

package/scaffold/.agent/skills/total-recall/plugins/security/ui/card.js

@@ -5,11 +5,31 @@ export class SecuritySecurityCard extends HTMLElement {
     root.innerHTML = `
       <style>
         :host {
+          --face-bg: #180d11;
+          --face-bg-subtle: #251017;
+          --face-bg-surface: #11070a;
+          --face-bg-table: #0d0508;
+          --face-bg-code: #0a0406;
+          --face-accent: #f43f5e;
+          --face-accent-hover: rgba(244, 63, 94, 0.22);
+          --face-accent-glow: rgba(244, 63, 94, 0.35);
+          --face-border-subtle: rgba(244, 63, 94, 0.28);
+          --face-border-faint: rgba(244, 63, 94, 0.2);
+          --face-border-cell: rgba(244, 63, 94, 0.15);
+          --face-border-alert: rgba(244, 63, 94, 0.25);
+          --face-text: #f1f5f9;
+          --face-text-heading: #fecdd3;
+          --face-text-muted: #fda4af;
+          --face-text-cell: #f8fafc;
+          --face-text-desc: #cbd5e1;
+          --face-danger: #fb7185;
+          --face-warning: #fca5a5;
+
           display: block;
           font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-          color: #f1f5f9;
-          background: #180d11;
-          border: 1px solid rgba(244, 63, 94, 0.35);
+          color: var(--text-primary, var(--face-text));
+          background: var(--face-bg);
+          border: 1px solid var(--border, var(--face-accent-glow));
           border-radius: 10px;
           padding: 18px;
           box-shadow: 0 10px 28px rgba(0, 0, 0, 0.45);
@@ -27,7 +47,7 @@ export class SecuritySecurityCard extends HTMLElement {
         .brand-icon {
           width: 32px;
           height: 38px;
-          color: #f43f5e;
+          color: var(--face-accent);
           flex-shrink: 0;
         }
 
@@ -43,12 +63,12 @@ export class SecuritySecurityCard extends HTMLElement {
           font-weight: 700;
           letter-spacing: 0.03em;
           text-transform: uppercase;
-          color: #fecdd3;
+          color: var(--face-text-heading);
         }
 
         p.desc {
           margin: 0 0 14px 0;
-          color: #fda4af;
+          color: var(--face-text-muted);
           font-size: 12px;
           line-height: 1.5;
         }
@@ -66,11 +86,11 @@ export class SecuritySecurityCard extends HTMLElement {
 
         button, input, select {
           min-height: 44px;
-          border: 1px solid rgba(244, 63, 94, 0.28);
+          border: 1px solid var(--face-border-subtle);
           border-radius: 6px;
           padding: 8px 12px;
-          background: #251017;
-          color: #f1f5f9;
+          background: var(--face-bg-subtle);
+          color: var(--face-text);
           font-size: 11px;
           font-weight: 600;
           letter-spacing: 0.02em;
@@ -84,8 +104,8 @@ export class SecuritySecurityCard extends HTMLElement {
         }
 
         button:hover {
-          background: rgba(244, 63, 94, 0.22);
-          border-color: #f43f5e;
+          background: var(--face-accent-hover);
+          border-color: var(--face-accent);
         }
 
         button:active {
@@ -101,17 +121,17 @@ export class SecuritySecurityCard extends HTMLElement {
           min-width: 0;
           flex: 1;
           font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-          background: #11070a;
+          background: var(--face-bg-surface);
         }
 
         input:focus, select:focus {
-          border-color: #f43f5e;
+          border-color: var(--face-accent);
           outline: none;
-          box-shadow: 0 0 0 1px rgba(244, 63, 94, 0.3);
+          box-shadow: 0 0 0 1px var(--face-accent-glow);
         }
 
         select {
-          background: #11070a;
+          background: var(--face-bg-surface);
           cursor: pointer;
         }
 
@@ -120,66 +140,66 @@ export class SecuritySecurityCard extends HTMLElement {
           font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
           font-size: 11px;
           font-weight: 700;
-          color: #fb7185;
-          background: #11070a;
+          color: var(--face-danger);
+          background: var(--face-bg-surface);
           padding: 6px 10px;
           border-radius: 4px;
-          border: 1px solid rgba(244, 63, 94, 0.2);
+          border: 1px solid var(--face-border-faint);
         }
 
         .scroll {
           overflow-x: auto;
           margin-bottom: 10px;
           border-radius: 6px;
-          border: 1px solid rgba(244, 63, 94, 0.2);
+          border: 1px solid var(--face-border-faint);
         }
 
         table {
           width: 100%;
           border-collapse: collapse;
           font-size: 11px;
-          background: #0d0508;
+          background: var(--face-bg-table);
         }
 
         th {
-          background: #251017;
-          color: #fecdd3;
+          background: var(--face-bg-subtle);
+          color: var(--face-text-heading);
           font-weight: 700;
           text-transform: uppercase;
           letter-spacing: 0.04em;
           padding: 8px 10px;
-          border-bottom: 1px solid rgba(244, 63, 94, 0.3);
+          border-bottom: 1px solid var(--face-border-subtle);
           text-align: left;
         }
 
         td {
           padding: 8px 10px;
           text-align: left;
-          border-bottom: 1px solid rgba(244, 63, 94, 0.15);
+          border-bottom: 1px solid var(--face-border-cell);
           vertical-align: top;
-          color: #f8fafc;
+          color: var(--face-text-cell);
         }
 
         td:first-child {
           font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
           font-weight: 600;
-          color: #fda4af;
+          color: var(--face-text-muted);
         }
 
         td:last-child {
           line-height: 1.45;
-          color: #cbd5e1;
+          color: var(--face-text-desc);
         }
 
         pre {
-          background: #0a0406;
-          border: 1px solid rgba(244, 63, 94, 0.2);
+          background: var(--face-bg-code);
+          border: 1px solid var(--face-border-faint);
           border-radius: 6px;
           padding: 8px 10px;
           font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
           font-size: 10.5px;
           line-height: 1.45;
-          color: #fb7185;
+          color: var(--face-danger);
           white-space: pre-wrap;
           overflow-wrap: anywhere;
           max-height: 160px;
@@ -188,8 +208,8 @@ export class SecuritySecurityCard extends HTMLElement {
         }
 
         #device-review {
-          background: #11070a;
-          border: 1px solid rgba(244, 63, 94, 0.25);
+          background: var(--face-bg-surface);
+          border: 1px solid var(--face-border-alert);
           border-radius: 6px;
           padding: 10px;
           margin-top: 10px;
@@ -198,7 +218,7 @@ export class SecuritySecurityCard extends HTMLElement {
         #device-review p {
           margin: 0 0 8px 0;
           font-size: 11px;
-          color: #fca5a5;
+          color: var(--face-warning);
         }
 
         #device-checks label {
@@ -209,9 +229,15 @@ export class SecuritySecurityCard extends HTMLElement {
         #device-checks label p {
           margin: 0 0 4px 0;
           font-size: 11px;
-          color: #fecdd3;
+          color: var(--face-text-heading);
           font-weight: 600;
         }
+
+        @media (prefers-reduced-motion: reduce) {
+          button, input, select {
+            transition: none !important;
+          }
+        }
       </style>
 
       <header>

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

@@ -8,6 +8,8 @@ There is one secrets store per host: the global auth store. The CLI never select
 
 For provider key setup, verify against an authenticated provider operation before saving; format-only checks and timeouts are not verification. Require HTTPS except explicit loopback development, reject redirects containing credentials, and return safe errors. Rotation follows verify → store/project → deploy/verify → revoke, respecting the provider's supported recipe and user authorization. Manual provider steps remain manual. Exported environment files are deployment projections, not an alternate credential authority.
 
+Every secret operation goes through `total-recall auth secret`; never read, compare or copy credential values with shell tools. Check a copied credential with `fingerprint --from-clipboard --expect-prefix <p> --not <KEY>` before `rotate <KEY> --from-clipboard`. After `remote deploy <target> --keys … [--path <repo>]`, confirm with `remote verify <target> --keys …` (fingerprint match, no values). A process manager can keep a captured environment that overrides the deployed file (pm2 does): move the keys the app uses into the store with `remote import-pm2 <target> --app <name> --keys … --apply`, then restart the app with a clean environment so it reads only the projection. Stripe webhook signing secrets are issued by Stripe; roll them in the dashboard, never mint them.
+
 Current migration remains in progress until package/bootstrap tests, all-plugin bypass checks, owner suites and end-to-end UI/API checks pass. Manifest `auth.plugin` declarations alone do not certify any of these properties.
 
 ## Sessions, passwords and legacy data

package/src/cli/command.mjs

@@ -222,6 +222,27 @@ function headerTags(description, risk) {
   return (description ? `// @description ${one(description)}\n` : '') + (risk ? `// @risk ${risk}\n` : '');
 }
 
+/**
+ * Build a custom command's file from author-supplied source.
+ *
+ * The source may be a BODY for run(argv) or a complete module. Blindly wrapping it failed two ways:
+ * a module produced "Unexpected identifier 'fs'", and a body that declared its own `args` produced
+ * "Identifier 'args' has already been declared". Detect the shape instead of assuming it, and declare
+ * `args` only when the body does not. The default export delegates so the body is written once.
+ */
+function buildCommandFile(name, description, risk, code) {
+  const source = String(code ?? '');
+  const header = `// Auto-generated custom CLI command: ${name}\n${headerTags(description, risk)}`;
+  if (/^\s*(?:import|export)\s/m.test(source)) {
+    return `${header}// Supplied as a complete module; used as written.\n${source}\n`;
+  }
+  const declaresArgs = /(?:^|\n)\s*(?:const|let|var)\s+args\b/.test(source);
+  const argsLine = declaresArgs ? '' : 'const args = Array.isArray(argv) ? argv.slice(3) : [];\n';
+  return `${header}// Your source is the BODY of run(argv). \`argv\` is in scope${declaresArgs ? '' : ', and so is `args` (argv minus the command name)'}.\n`
+    + "// Use `await import('node:module')`; write no import/export statements here.\n"
+    + `export async function run(argv = []) {\n${argsLine}${source}\n}\nexport default function (argv = []) {\n  return run(argv);\n}\n`;
+}
+
 function existingTag(file, key) {
   try { return fs.readFileSync(file, 'utf8').match(new RegExp(`^// @${key} (.+)$`, 'm'))?.[1] || undefined; } catch { return undefined; }
 }
@@ -373,15 +394,7 @@ export default async function commandCmd(rawArgs = []) {
     }
     
     // Wrap code in an exported run/default function for composable CLI execution
-    const fileContent = `// Auto-generated custom CLI command: ${name}
-${headerTags(description, risk)}export async function run(argv = []) {
-  const args = Array.isArray(argv) ? argv.slice(3) : [];
-  ${code}
-}
-export default async function (args = []) {
-  ${code}
-}
-`;
+    const fileContent = buildCommandFile(name, description, risk, code);
 
     fs.writeFileSync(commandPath, fileContent, 'utf8');
     console.log(`\x1b[32m✔ Successfully created custom command: \x1b[1mnpx total-recall ${name}\x1b[0m`);
@@ -413,15 +426,7 @@ export default async function (args = []) {
     // Keep the declared description/risk unless the update replaces them.
     const keptDescription = description ?? existingTag(commandPath, 'description');
     const keptRisk = risk ?? existingTag(commandPath, 'risk');
-    const fileContent = `// Auto-generated custom CLI command: ${name}
-${headerTags(keptDescription, keptRisk)}export async function run(argv = []) {
-  const args = Array.isArray(argv) ? argv.slice(3) : [];
-  ${code}
-}
-export default async function (args = []) {
-  ${code}
-}
-`;
+    const fileContent = buildCommandFile(name, keptDescription, keptRisk, code);
 
     fs.writeFileSync(commandPath, fileContent, 'utf8');
     console.log(`\x1b[32m✔ Successfully updated custom command: \x1b[1m${name}\x1b[0m`);

package/src/cli/daemon.mjs

@@ -218,7 +218,29 @@ export default async function daemon(args) {
 
   switch (subcommand) {
     case 'ensure': {
-      if(!useSystemd)throw new Error('Managed daemon ensure currently requires systemd on the daemon host');
+      if(useLaunchd){
+        // macOS: the launchd agent owns the daemon. Load it if needed, restart it
+        // on --restart (or start it when nothing runs), then verify the process
+        // launchd reports is the one holding the brain lock.
+        const label='com.totalrecall.daemon',target=`gui/${process.getuid()}/${label}`;
+        const launchdPid=()=>{const r=spawnSync('launchctl',['list',label],{encoding:'utf8'});const m=r.status===0&&/"PID"\s*=\s*(\d+)/.exec(r.stdout||'');return m?Number(m[1]):0;};
+        if(spawnSync('launchctl',['list',label],{stdio:'ignore'}).status!==0){
+          const boot=spawnSync('launchctl',['bootstrap',`gui/${process.getuid()}`,launchAgentPlist(label)],{encoding:'utf8'});
+          if(boot.status!==0)throw new Error(`Cannot load ${label}: ${(boot.stderr||'').trim()}`);
+        }
+        const owner=readPid(),managedPid=launchdPid();
+        if(owner && owner!==managedPid && !await stopDaemon())throw new Error('Cannot stop verified detached daemon');
+        if(args.includes('--restart') || !managedPid || (owner && owner!==managedPid)){
+          const kick=spawnSync('launchctl',['kickstart','-k',target],{encoding:'utf8'});
+          if(kick.status!==0)throw new Error(`launchctl kickstart failed: ${(kick.stderr||'').trim()}`);
+        }
+        await new Promise(resolve=>setTimeout(resolve,3000));
+        const pid=readPid(),current=launchdPid();
+        if(!pid || pid!==current)throw new Error('Managed daemon did not retain ownership of the brain lock');
+        console.log(JSON.stringify({ok:true,manager:'launchd',pid,enabled:true}));
+        break;
+      }
+      if(!useSystemd)throw new Error('Managed daemon ensure needs systemd or a launchd agent on the daemon host');
       // A detached worker can hold the same brain lock while systemd reports a
       // successful short-lived start. Stop that verified owner before takeover.
       const managed=spawnSync('systemctl',['show','total-recall-daemon','--property=MainPID','--value'],{encoding:'utf8'});

package/src/cli/plugin/copies.mjs

@@ -17,8 +17,9 @@ export function pluginCopyRows(projectRoot = process.cwd(), { sharedDir = global
     root: projectRoot,
     sharedDir,
     count: audit.count,
-    removable: audit.copies.filter(copy => copy.edited === false).map(copy => copy.id),
-    edited: audit.copies.filter(copy => copy.edited === true).map(copy => copy.id),
+    removable: audit.copies.filter(copy => copy.edited === false || copy.stale === true).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),
     unverified: audit.copies.filter(copy => copy.edited === null).map(copy => copy.id),
     copies: audit.copies
   };
@@ -58,11 +59,13 @@ export async function manageProjectPluginCopies(args = []) {
     return;
   }
   for (const copy of report.copies) {
-    const verdict = copy.edited === false ? 'identical to the shared install' : copy.edited === true ? 'DIFFERS from the shared install' : 'no shared install to compare';
+    const verdict = copy.stale === true ? 'STALE — older than the shared install; it shadows the shared plugin and must be removed'
+      : copy.edited === false ? 'identical to the shared install'
+      : copy.edited === true ? 'DIFFERS from the shared install' : 'no shared install to compare';
     console.log(`  ${copy.id} v${copy.version || '?'} (shared: v${copy.sharedVersion || '—'}) — ${verdict}`);
   }
-  console.log(`\n  ${report.removable.length} removable, ${report.edited.length} edited, ${report.unverified.length} unverified`);
+  console.log(`\n  ${report.removable.length} removable (${report.stale.length} stale), ${report.edited.length} edited, ${report.unverified.length} unverified`);
   if (report.removal) console.log(`  Removed: ${report.removal.removed.join(', ') || 'none'}${report.removal.failed.length ? `; failed: ${report.removal.failed.map(row => row.id).join(', ')}` : ''}`);
-  else if (report.removable.length) console.log('  Re-run with --apply to remove the identical copies.');
+  else if (report.removable.length) console.log('  Re-run with --apply to remove the removable copies.');
   console.log();
 }

package/src/cli/plugin/index.mjs

@@ -6,8 +6,8 @@ import { createPlugin } from './create.mjs';
 import { vendorPlugin, listProjectBricks } from './vendor.mjs';
 import { manageProjectPluginCopies } from './copies.mjs';
 import { managePluginLicense } from './monetization.mjs';
-import { getPlugin, getPluginMonetization } from '../../core/plugin-loader.mjs';
-import { describePlugin } from '../../core/plugin-store.mjs';
+import { getPlugin, getPluginMonetization, globalPluginsDir, projectPluginsDir } from '../../core/plugin-loader.mjs';
+import { describePlugin, pruneReplacementArchives, replacementArchiveDir } from '../../core/plugin-store.mjs';
 import { buildPluginCatalog } from '../../core/plugin-catalog.mjs';
 import { setPluginActive } from '../../core/plugin-activation.mjs';
 
@@ -29,6 +29,10 @@ Commands:
   refresh                   Rebuild installed command inventories and instruction surfaces
   copies [dir] [--apply]    Audit this repository's leftover copies of the shared default
                             plugins; --apply removes only the ones identical to the shared install
+  replacements [--prune] [--keep N] [--project] [--json]
+                            Copies kept by install --replace (default: shared folder). Reports
+                            the space; --prune keeps the newest N per plugin (default 1) and
+                            drops node_modules from the kept ones
   on <id> / off <id>         Enable/disable host execution for this repository alone
                               --all-repos   Change the shared setting for every repository
                               --clear       Drop this repository's override; follow the shared setting
@@ -136,6 +140,25 @@ export async function run(argv = []) {
     return;
   }
 
+  if (command === 'replacements') {
+    const keepAt = rest.indexOf('--keep');
+    const keep = keepAt === -1 ? 1 : Number(rest[keepAt + 1]);
+    if (!Number.isInteger(keep) || keep < 0) {
+      console.error('Usage: total-recall plugin replacements [--prune] [--keep N] [--project] [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const dir = replacementArchiveDir(rest.includes('--project') ? projectPluginsDir(process.cwd()) : globalPluginsDir());
+    const apply = rest.includes('--prune');
+    const r = pruneReplacementArchives(dir, { keep, apply });
+    if (rest.includes('--json')) { console.log(JSON.stringify({ ...r, applied: apply }, null, 2)); return; }
+    const gb = (r.bytesFreed / 1073741824).toFixed(2);
+    console.log(`\n  ${r.archiveDir}`);
+    console.log(`  ${r.kept.length + r.removed.length} retained cop${r.kept.length + r.removed.length === 1 ? 'y' : 'ies'}; keeping ${r.kept.length}, ${apply ? 'removed' : 'would remove'} ${r.removed.length}, ${apply ? 'stripped' : 'would strip'} node_modules from ${r.stripped.length}`);
+    console.log(`  ${apply ? 'Freed' : 'Would free'} ${gb} GB${apply ? '' : ' — run with --prune to apply'}\n`);
+    return;
+  }
+
   if (command === 'copies' || command === 'duplicates') {
     await manageProjectPluginCopies(rest);
     return;

package/src/cli/rebuild.mjs

@@ -163,6 +163,28 @@ export async function compileRegisteredProjects({ brains = listLocalBrains(), co
 }
 
 export default async function cli(args) {
+  // `--help` must never execute the command. This parsed flags and went straight to a rebuild, so
+  // `total-recall compile --help` (and rebuild) threw away the derived indexes and recompiled every
+  // brain instead of printing usage.
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  total-recall compile | rebuild — SSSS projection rebuild
+
+  Discards the derived indexes and rebuilds them deterministically from the canonical vault,
+  then recompiles instruction surfaces.
+
+    total-recall compile [--check] [--force] [--all] [--global|--project]
+
+    --check     Report drift between the vault and derived indexes; change nothing.
+    --force     Rebuild even when nothing is stale.
+    --all       Recompile every registered project brain as well.
+    --global    Target the global brain (~/.agent).
+    --project   Target this repository's brain (<cwd>/.agent).
+
+  A global compile is what \`remember --global\` runs, because global rules land in every project.
+`);
+    process.exit(0);
+  }
   const { layer, remainingArgs } = parseLayerFlag(args);
   const options = {
     check: remainingArgs.includes('--check'),

package/src/cli/reset-password.mjs

@@ -54,9 +54,10 @@ export default async function resetPassword(args) {
     console.log(`
   total-recall reset-password
 
-  Resets the dashboard admin password in ~/.agent/skills/total-recall/config/security.yml.
+  Resets the dashboard admin password in the encrypted auth store (the only place the server
+  reads it; any password_hash left in config/security.yml is ignored).
   Prompts for the new password; it is never taken as an argument.
-  Sets force_password_reset to true so you will be prompted to change it upon first login.
+  Existing sessions are invalidated. Setting the well-known default forces a change on first login.
 
   For automation, pipe it instead:  echo "\$NEW_PW" | total-recall reset-password
 `);