total-recall-brain 3.26.0 → 3.28.0

package/src/cli/agent.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+import { listAgents, spawnAgent, killAgent, getAgentLogs } from '../core/agent-manager.mjs';
+import { detectHarnesses } from '../core/meta-harness.mjs';
+
+function printHelp() {
+  console.log(`
+🤖 Total Recall — CLI Agent Management & Process Controller
+
+Usage:
+  npx total-recall agent <command> [options]
+
+Commands:
+  list                      List all running and recent agent processes
+  spawn <harness> "<task>"  Spawn a background or foreground agent task
+  status [id]               Show detailed status of an agent
+  logs <id> [--tail 50]     Inspect streaming logs of a spawned agent
+  kill <id|pid>             Terminate an active agent process
+
+Options:
+  --node <name>             Target a remote mesh node (macmini, cloud, etc.)
+  --json                    Output machine-readable JSON for Unix pipelines
+  --detach                  Spawn process detached in background (default: true)
+  --name <label>            Assign a human-readable name to the agent session
+  --tail <lines>            Number of log lines to inspect (default: 50)
+
+Available Harnesses:
+  agy, claude, codex, gemini
+
+Examples:
+  npx total-recall agent list
+  npx total-recall agent spawn claude "Refactor src/cli/harness.mjs error handling"
+  npx total-recall agent spawn agy "Crawl recent preprints on quantum shuttling" --name "Quantum Scout"
+  npx total-recall agent logs agent-claude-xyz --tail 100
+  npx total-recall agent kill agent-claude-xyz
+`);
+}
+
+export async function run(argv) {
+  let args = argv;
+  if (Array.isArray(args) && args[0]?.endsWith('node')) {
+    args = args.slice(2);
+  }
+  if (args[0] === 'agent' || args[0] === 'agents') {
+    args = args.slice(1);
+  }
+
+  const command = args[0];
+  const rest = args.slice(1);
+
+  if (!command || command === 'list') {
+    const isJson = rest.includes('--json');
+    const agents = listAgents();
+
+    if (isJson) {
+      console.log(JSON.stringify(agents, null, 2));
+      return;
+    }
+
+    console.log(`\n🤖 Total Recall — Active Agent Process Registry\n`);
+    if (agents.length === 0) {
+      console.log('No agents currently active or tracked.');
+      console.log('Spawn an agent with: npx total-recall agent spawn <harness> "<task>"\n');
+      return;
+    }
+
+    const pad = (s, l) => String(s || '').padEnd(l).slice(0, l);
+    console.log('┌────────────────────────┬──────────────┬────────┬────────────┬────────────────────────────┬─────────────────────────────┐');
+    console.log(`│ ${pad('Agent ID', 22)} │ ${pad('Harness', 12)} │ ${pad('PID', 6)} │ ${pad('Status', 10)} │ ${pad('Started At', 26)} │ ${pad('Task Intent', 27)} │`);
+    console.log('├────────────────────────┼──────────────┼────────┼────────────┼────────────────────────────┼─────────────────────────────┤');
+
+    for (const a of agents) {
+      const statusBadge = a.status === 'running' ? '\x1b[32mrunning\x1b[0m   ' : (a.status === 'completed' ? '\x1b[36mcompleted\x1b[0m ' : '\x1b[90mstopped\x1b[0m   ');
+      const time = (a.startedAt || '').replace('T', ' ').slice(0, 19);
+      console.log(`│ \x1b[1m${pad(a.id, 22)}\x1b[0m │ ${pad(a.harness, 12)} │ ${pad(a.pid, 6)} │ ${statusBadge} │ ${pad(time, 26)} │ ${pad(a.task, 27)} │`);
+    }
+    console.log('└────────────────────────┴──────────────┴────────┴────────────┴────────────────────────────┴─────────────────────────────┘\n');
+    return;
+  }
+
+  if (command === 'spawn') {
+    let targetNode = null;
+    const filteredRest = [];
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === '--node' || rest[i] === '-n') {
+        targetNode = rest[i + 1];
+        i++;
+      } else {
+        filteredRest.push(rest[i]);
+      }
+    }
+
+    const harness = filteredRest[0];
+    const task = filteredRest.filter(r => !r.startsWith('--')).slice(1).join(' ').trim();
+    const detach = !filteredRest.includes('--no-detach');
+    const isJson = filteredRest.includes('--json');
+    const nameIdx = filteredRest.indexOf('--name');
+    const name = nameIdx !== -1 ? filteredRest[nameIdx + 1] : null;
+
+    if (!harness || !task) {
+      console.error('Error: Please specify harness ID and task prompt.');
+      console.error('Usage: npx total-recall agent spawn <harness> "<task>" [--name "..."] [--node <node>]');
+      process.exit(1);
+    }
+
+    const nodeStr = targetNode ? ` on mesh node \x1b[1;33m${targetNode}\x1b[0m` : '';
+    if (!isJson) console.log(`\n🚀 Spawning agent on harness: \x1b[1;36m${harness}\x1b[0m${nodeStr}...`);
+    try {
+      const record = await spawnAgent(harness, task, { detach, name, node: targetNode });
+      if (isJson) {
+        console.log(JSON.stringify(record, null, 2));
+        return;
+      }
+      console.log(`✅ Agent session spawned successfully!`);
+      console.log(`   Session ID: \x1b[1m${record.id}\x1b[0m (PID: ${record.pid || 'remote'})`);
+      console.log(`   Status:     \x1b[32m${record.status}\x1b[0m`);
+      if (record.node) console.log(`   Mesh Node:  ${record.node}`);
+      if (record.logFile) console.log(`   Log File:   ${record.logFile}`);
+      console.log(`\nMonitor logs with: \x1b[36mnpx total-recall agent logs ${record.id}\x1b[0m\n`);
+    } catch (err) {
+      console.error(`\n❌ Failed to spawn agent: ${err.message}\n`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'logs') {
+    const id = rest.find(r => !r.startsWith('--'));
+    if (!id) {
+      console.error('Error: Please specify agent ID or PID.');
+      console.error('Usage: npx total-recall agent logs <id> [--tail 50]');
+      process.exit(1);
+    }
+
+    const tailIdx = rest.indexOf('--tail');
+    const tailLines = tailIdx !== -1 ? parseInt(rest[tailIdx + 1], 10) : 50;
+
+    try {
+      const logs = await getAgentLogs(id, tailLines);
+      console.log(`\n📜 Logs for Agent [${id}]:\n`);
+      console.log(logs || '(Log is empty)');
+      console.log('');
+    } catch (err) {
+      console.error(`\n❌ ${err.message}\n`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'kill') {
+    const id = rest.find(r => !r.startsWith('--'));
+    if (!id) {
+      console.error('Error: Please specify agent ID or PID to terminate.');
+      console.error('Usage: npx total-recall agent kill <id|pid>');
+      process.exit(1);
+    }
+
+    try {
+      const res = await killAgent(id);
+      console.log(`\n✅ ${res.message}\n`);
+    } catch (err) {
+      console.error(`\n❌ ${err.message}\n`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  printHelp();
+}
+
+export default async function (args) {
+  await run(args);
+}

package/src/cli/connect.mjs

@@ -28,6 +28,30 @@ const CLIENTS = {
     mode: 'hermes',
     memoryPath: path.join(os.homedir(), '.hermes', 'memories', 'MEMORY.md'),
     userPath:   path.join(os.homedir(), '.hermes', 'memories', 'USER.md'),
+    skillsProjection: { scope: 'project', dir: path.join('.hermes', 'skills') }
+  },
+  'hermes-agent': {
+    label: 'Hermes Agent',
+    mode: 'hermes',
+    memoryPath: path.join(os.homedir(), '.hermes', 'memories', 'MEMORY.md'),
+    userPath:   path.join(os.homedir(), '.hermes', 'memories', 'USER.md'),
+    skillsProjection: { scope: 'project', dir: path.join('.hermes', 'skills') }
+  },
+  dsh: {
+    label: 'DeepSeek Harness (dsh)',
+    mode: 'dsh',
+    globalMemoryPath: path.join(os.homedir(), '.dsh', 'memory', 'MEMORY.md'),
+    globalUserPath:   path.join(os.homedir(), '.dsh', 'memory', 'user.md'),
+    localTarget: 'AGENTS.md',
+    skillsProjection: { scope: 'project', dir: path.join('.agents', 'skills') }
+  },
+  'deepseek-harness': {
+    label: 'DeepSeek Harness',
+    mode: 'dsh',
+    globalMemoryPath: path.join(os.homedir(), '.dsh', 'memory', 'MEMORY.md'),
+    globalUserPath:   path.join(os.homedir(), '.dsh', 'memory', 'user.md'),
+    localTarget: 'AGENTS.md',
+    skillsProjection: { scope: 'project', dir: path.join('.agents', 'skills') }
   },
   openclaw: {
     label: 'OpenClaw',
@@ -163,6 +187,10 @@ function printHelp() {
     antigravity
     gemini
     aider
+    pi
+    hermes
+    dsh
+    openclaw
     http-api
     obsidian
     generic
@@ -797,14 +825,71 @@ export default async function connect(args) {
     result.notes.push(`  ~/.pi/agent/AGENTS.md → ${instructionsPath}`);
   } else if (preset.mode === 'hermes') {
     // Hermes: write compiled MEMORY.md to ~/.hermes/memories/MEMORY.md (max 2200 chars)
+    // and project-local .hermes/memories/MEMORY.md if inside a project workspace
     const instructions = readInstructions(cwd, agentDir);
     if (!instructions) throw new Error('No INSTRUCTIONS.md found. Run npx total-recall init or compile first.');
-    fs.mkdirSync(path.dirname(preset.memoryPath), { recursive: true });
+    const homeDir = process.env.HOME || os.homedir();
+    const globalMemPath = path.join(homeDir, '.hermes', 'memories', 'MEMORY.md');
     const capped = instructions.slice(0, 2200);
-    fs.writeFileSync(preset.memoryPath, capped, 'utf8');
-    result.projection = { targetPath: preset.memoryPath, action: 'written' };
-    result.notes.push(`  Hermes MEMORY.md (${capped.length} chars) → ${preset.memoryPath}`);
+
+    let wroteGlobal = false;
+    try {
+      fs.mkdirSync(path.dirname(globalMemPath), { recursive: true });
+      fs.writeFileSync(globalMemPath, capped, 'utf8');
+      wroteGlobal = true;
+    } catch {
+      // Gracefully continue if global directory is unwritable in sandbox
+    }
+
+    let localMemPath = null;
+    if (!isHome) {
+      localMemPath = path.join(cwd, '.hermes', 'memories', 'MEMORY.md');
+      fs.mkdirSync(path.dirname(localMemPath), { recursive: true });
+      fs.writeFileSync(localMemPath, capped, 'utf8');
+    }
+
+    result.projection = { targetPath: localMemPath || globalMemPath, action: 'written' };
+    if (wroteGlobal) {
+      result.notes.push(`  Hermes MEMORY.md (${capped.length} chars) → ${globalMemPath}`);
+    }
+    if (localMemPath) {
+      result.notes.push(`  Hermes local MEMORY.md → ${localMemPath}`);
+    }
     result.notes.push('  Note: Hermes has a 2,200-char limit on MEMORY.md. Total Recall auto-caps this.');
+  } else if (preset.mode === 'dsh') {
+    // DeepSeek Harness: write global ~/.dsh/memory/MEMORY.md and symlink project AGENTS.md
+    const instructions = readInstructions(cwd, agentDir);
+    if (!instructions) throw new Error('No INSTRUCTIONS.md found. Run npx total-recall init or compile first.');
+    const homeDir = process.env.HOME || os.homedir();
+    const globalMemPath = path.join(homeDir, '.dsh', 'memory', 'MEMORY.md');
+
+    let wroteGlobal = false;
+    try {
+      fs.mkdirSync(path.dirname(globalMemPath), { recursive: true });
+      fs.writeFileSync(globalMemPath, instructions, 'utf8');
+      wroteGlobal = true;
+    } catch {
+      // Gracefully continue if global directory is unwritable in sandbox
+    }
+
+    const agentsPath = path.join(cwd, preset.localTarget);
+    if (pathExists(agentsPath)) {
+      if (opts.force) {
+        try {
+          fs.unlinkSync(agentsPath);
+        } catch {
+          fs.rmSync(agentsPath, { force: true, recursive: true });
+        }
+        fs.symlinkSync('INSTRUCTIONS.md', agentsPath);
+      }
+    } else {
+      fs.symlinkSync('INSTRUCTIONS.md', agentsPath);
+    }
+    result.projection = { targetPath: agentsPath, action: 'symlinked' };
+    if (wroteGlobal) {
+      result.notes.push(`  DeepSeek Harness MEMORY.md → ${globalMemPath}`);
+    }
+    result.notes.push(`  DeepSeek Harness AGENTS.md → INSTRUCTIONS.md`);
   } else if (preset.mode === 'openclaw') {
     // OpenClaw: write MEMORY.md + symlink AGENTS.md in cwd
     const instructions = readInstructions(cwd, agentDir);

package/src/cli/deploy-ui.mjs

@@ -692,6 +692,9 @@ export function startDeployUI(port = 3001) {
           'gemini':      [HOME + '/.gemini'],
           'pi':          [HOME + '/.pi/agent'],
           'hermes':      [HOME + '/.hermes'],
+          'hermes-agent':[HOME + '/.hermes'],
+          'dsh':         [HOME + '/.dsh'],
+          'deepseek-harness': [HOME + '/.dsh'],
           'openclaw':    [HOME + '/.openclaw'],
           'obsidian':    [HOME + '/Library/Application Support/obsidian', HOME + '/.config/obsidian'],
         };
@@ -725,6 +728,9 @@ export function startDeployUI(port = 3001) {
             'gemini':      { client: 'gemini',       label: 'Gemini CLI' },
             'pi':          { client: 'pi',           label: 'Pi Coding Agent' },
             'hermes':      { client: 'hermes',       label: 'Hermes Agent' },
+            'hermes-agent':{ client: 'hermes-agent', label: 'Hermes Agent' },
+            'dsh':         { client: 'dsh',          label: 'DeepSeek Harness (dsh)' },
+            'deepseek-harness': { client: 'deepseek-harness', label: 'DeepSeek Harness' },
             'openclaw':    { client: 'openclaw',     label: 'OpenClaw' },
           };
 

package/src/cli/harness.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+import { detectHarnesses, dispatchTask, runCouncil, HARNESS_SPECS } from '../core/meta-harness.mjs';
+
+function printHelp() {
+  console.log(`
+🎮 Total Recall — Meta Harness & Multi-Agent Management Layer
+
+Usage:
+  npx total-recall harness <command> [options]
+
+Commands:
+  list                      Inspect all external IDE and CLI developer harnesses
+  dispatch <id> "<task>"    Headlessly invoke a specific agent harness
+                            Options: --node <name> to execute remotely on a mesh node
+  council "<task>"          Run concurrent multi-harness consensus deliberation
+
+Available Harness IDs:
+  agy                       Google Antigravity CLI (Frontier reasoning, AI Ultra)
+  claude                    Claude Code CLI (Deep codebase refactoring & Unix execution)
+  codex                     OpenAI Codex CLI (Program synthesis & sandbox execution)
+  gemini                    Google Gemini CLI (Fast utilities & completion chaining)
+  ollama                    Ollama Local LLM (Local neural reasoning, zero API cost)
+
+Examples:
+  npx total-recall harness list
+  npx total-recall harness dispatch claude "Review and run code quality checks on src/core/"
+  npx total-recall harness dispatch ollama --node macmini "What is test-time compute scaling?"
+  npx total-recall harness council "Propose architecture for decentralized research mesh"
+`);
+}
+
+export async function run(argv) {
+  let args = argv;
+  if (Array.isArray(args) && args[0]?.endsWith('node')) {
+    args = args.slice(2);
+  }
+  if (args[0] === 'harness') {
+    args = args.slice(1);
+  }
+
+  const command = args[0];
+  const rest = args.slice(1);
+
+  if (!command || command === 'list' || command === 'status') {
+    const harnesses = detectHarnesses();
+    console.log(`\n🎮 Total Recall — Connected Agent Harnesses & Runtimes\n`);
+
+    const pad = (s, l) => String(s || '').padEnd(l).slice(0, l);
+    console.log('┌──────────────┬──────────────────────────────┬──────────────┬────────────────────────────────────────────────────────┐');
+    console.log(`│ ${pad('Harness ID', 12)} │ ${pad('Name', 28)} │ ${pad('Status', 12)} │ ${pad('Binary Path', 54)} │`);
+    console.log('├──────────────┼──────────────────────────────┼──────────────┼────────────────────────────────────────────────────────┤');
+
+    for (const h of harnesses) {
+      const status = h.available ? '\x1b[32mActive ✅\x1b[0m   ' : '\x1b[31mNot Found ❌\x1b[0m';
+      const p = h.binaryPath || '—';
+      console.log(`│ \x1b[1m${pad(h.id, 12)}\x1b[0m │ ${pad(h.name, 28)} │ ${status} │ ${pad(p, 54)} │`);
+    }
+    console.log('└──────────────┴──────────────────────────────┴──────────────┴────────────────────────────────────────────────────────┘\n');
+    return;
+  }
+
+  if (command === 'dispatch') {
+    let targetNode = null;
+    const filteredRest = [];
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === '--node' || rest[i] === '-n') {
+        targetNode = rest[i + 1];
+        i++;
+      } else {
+        filteredRest.push(rest[i]);
+      }
+    }
+
+    const harnessId = filteredRest[0];
+    const task = filteredRest.slice(1).join(' ').trim();
+    if (!harnessId || !task) {
+      console.error('Error: Please specify harness ID and task prompt.');
+      console.error('Usage: npx total-recall harness dispatch <id> [--node <node>] "<task>"');
+      process.exit(1);
+    }
+
+    const nodeStr = targetNode ? ` on mesh node \x1b[1;33m${targetNode}\x1b[0m` : '';
+    console.log(`\n🚀 Dispatching task to \x1b[1;36m${harnessId}\x1b[0m${nodeStr}...`);
+    try {
+      const res = await dispatchTask(harnessId, task, { node: targetNode });
+      console.log(`\n--- [Response from ${res.harnessName}${targetNode ? ' (' + targetNode + ')' : ''}] ---\n`);
+      console.log(res.response);
+      console.log(`\n✅ Exit code: ${res.exitCode}`);
+    } catch (err) {
+      console.error(`\n❌ Dispatch failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'council') {
+    const task = rest.join(' ').trim();
+    if (!task) {
+      console.error('Error: Please specify task prompt for council deliberation.');
+      console.error('Usage: npx total-recall harness council "<task>"');
+      process.exit(1);
+    }
+
+    console.log(`\n🏛️  Convening Multi-Agent Council across all available harnesses...`);
+    console.log(`   Task: "${task}"\n`);
+
+    try {
+      const councilRes = await runCouncil(task);
+      console.log(`Participating Harnesses: ${councilRes.participants.join(', ')}\n`);
+
+      for (const r of councilRes.results) {
+        console.log(`================================================================`);
+        console.log(`● Harness: \x1b[1;36m${r.harnessName}\x1b[0m (${r.harnessId})`);
+        console.log(`================================================================`);
+        if (r.success) {
+          console.log(r.response);
+        } else {
+          console.log(`\x1b[31mError: ${r.error || r.stderr || 'Execution failed'}\x1b[0m`);
+        }
+        console.log('');
+      }
+    } catch (err) {
+      console.error(`\n❌ Council deliberation failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  printHelp();
+}
+
+export default async function (args) {
+  await run(args);
+}

package/src/cli/ingest-openwiki.mjs

@@ -11,6 +11,7 @@ function printHelp() {
     --dry-run                 Preview import without writing
     --global                  Target the global brain
     --project                 Target the project brain (default)
+    --plugins                 Discover and ingest OpenWiki hubs from installed plugins
     --help, -h                Show this help
   `);
 }
@@ -18,6 +19,7 @@ function printHelp() {
 export async function runOpenWikiIngest(args) {
   let openwikiPath = null;
   let dryRun = false;
+  let includePlugins = false;
   let layerFlag = '--project';
   let help = false;
 
@@ -27,6 +29,7 @@ export async function runOpenWikiIngest(args) {
       case '--dry-run': dryRun = true; break;
       case '--global': layerFlag = '--global'; break;
       case '--project': layerFlag = '--project'; break;
+      case '--plugins': includePlugins = true; break;
       case '--help': case '-h': help = true; break;
       default:
         if (!arg.startsWith('-') && !openwikiPath) {
@@ -35,12 +38,12 @@ export async function runOpenWikiIngest(args) {
     }
   }
 
-  if (help || !openwikiPath) {
+  if (help || (!openwikiPath && !includePlugins)) {
     printHelp();
     return;
   }
 
-  if (!fs.existsSync(openwikiPath)) {
+  if (openwikiPath && !fs.existsSync(openwikiPath)) {
     console.error(`❌ Error: OpenWiki directory not found at ${openwikiPath}`);
     process.exit(1);
   }
@@ -116,6 +119,20 @@ export async function runOpenWikiIngest(args) {
     }
   }
 
+  if (includePlugins) {
+    console.log(`\n  🔌 Ingesting OpenWiki hubs from installed plugins...`);
+    const pluginResults = await syncPluginOpenWikiHubs({ dryRun, layerFlag });
+    for (const r of pluginResults) {
+      if (r.status === 'imported' || r.status === 'dry_run') {
+        console.log(`  🟢 [Plugin Hub] ${r.slug} ("${r.title}")`);
+        imported++;
+      } else {
+        console.error(`  🔴 [Plugin Hub] Error importing ${r.slug}: ${r.error}`);
+        errors++;
+      }
+    }
+  }
+
   console.log(`\n  Import Summary:`);
   console.log(`  🟢 Imported: ${imported} files`);
   console.log(`  🔴 Errors:   ${errors} files`);
@@ -124,3 +141,55 @@ export async function runOpenWikiIngest(args) {
      console.log(`\n  ✅ OpenWiki successfully integrated into Total Recall.`);
   }
 }
+
+/**
+ * Discover and ingest OpenWiki hubs declared by installed plugins.
+ */
+export async function syncPluginOpenWikiHubs(options = {}) {
+  const { projectRoot = process.cwd(), dryRun = false, layerFlag = '--project' } = options;
+  const { discoverPlugins } = await import('../core/plugin-loader.mjs');
+  const plugins = discoverPlugins(projectRoot);
+  const results = [];
+
+  for (const plugin of plugins) {
+    const hubs = plugin.manifest?.openwiki_hubs || [];
+    for (const hub of hubs) {
+      if (!hub.path) continue;
+      const hubFilePath = path.isAbsolute(hub.path) ? hub.path : path.join(plugin.dir, hub.path);
+      if (!fs.existsSync(hubFilePath)) continue;
+
+      try {
+        const content = fs.readFileSync(hubFilePath, 'utf8');
+        const title = hub.title || path.basename(hub.path, '.md').replace(/[-_]/g, ' ');
+        const slug = `openwiki-plugin-${plugin.id}-${path.basename(hub.path, '.md')}`.toLowerCase();
+
+        if (dryRun) {
+          results.push({ slug, title, status: 'dry_run' });
+          continue;
+        }
+
+        const cliArgs = [
+          process.argv[1],
+          'remember', 'fact',
+          content,
+          '--title', title,
+          '--slug', slug,
+          '--tags', `openwiki,plugin,plugin-${plugin.id}`,
+          layerFlag
+        ];
+
+        const res = spawnSync(process.argv[0], cliArgs, { encoding: 'utf8' });
+        results.push({
+          slug,
+          title,
+          status: res.status === 0 ? 'imported' : 'error',
+          error: res.status === 0 ? null : res.stderr
+        });
+      } catch (err) {
+        results.push({ slug: hub.path, title: hub.title, status: 'error', error: err.message });
+      }
+    }
+  }
+
+  return results;
+}

package/src/cli/init.mjs

@@ -199,6 +199,7 @@ export default async function init(args) {
 
   const dirs = [
     path.join(agentDir, 'skills'),
+    path.join(agentDir, 'plugins'),
   ];
 
   let created = 0;

package/src/cli/lint.mjs

@@ -22,13 +22,14 @@ import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 function parseArgs(args) {
-  const opts = { vault: null, strict: false, json: false, help: false, okf: false };
+  const opts = { vault: null, strict: false, json: false, help: false, okf: false, plugins: false };
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
       case '--vault': opts.vault = args[++i]; break;
       case '--strict': opts.strict = true; break;
       case '--json': opts.json = true; break;
       case '--okf': opts.okf = true; break;
+      case '--plugins': opts.plugins = true; break;
       case '--help': case '-h': opts.help = true; break;
     }
   }
@@ -37,10 +38,11 @@ function parseArgs(args) {
 
 function printHelp() {
   console.log(`
-  total-recall lint — Validate vault nodes against SSSS schema v2 or OKF spec
+  total-recall lint — Validate vault nodes against SSSS schema v2, OKF spec, or plugins
 
   Scans all .md files in the memory vault and validates their YAML
-  frontmatter against the Zod schemas or checks for OKF compliance.
+  frontmatter against the Zod schemas, checks OKF compliance, or validates
+  installed plugin.json manifests.
 
   Usage: total-recall lint [options]
 
@@ -50,6 +52,7 @@ function printHelp() {
     --project          Lint the project vault for the current repo
     --strict           Treat warnings as errors (exit 1 on any issue)
     --okf              Verify OKF v0.1 draft metadata compliance
+    --plugins          Validate all installed plugin manifests (plugin.json)
     --json             Output results as JSONL
     --help, -h         Show this help
 
@@ -102,6 +105,47 @@ export default async function lint(args) {
     return;
   }
 
+  if (opts.plugins) {
+    const { discoverPlugins } = await import('../core/plugin-loader.mjs');
+    const plugins = discoverPlugins(process.cwd());
+    let pluginErrors = 0;
+
+    if (!opts.json) {
+      console.error(`\n  🔌 Linting installed plugins:\n`);
+    }
+
+    for (const p of plugins) {
+      if (!p.valid) {
+        pluginErrors += p.errors.length;
+        if (opts.json) {
+          console.log(JSON.stringify({ plugin: p.id, manifestPath: p.manifestPath, level: 'error', errors: p.errors }));
+        } else {
+          console.error(`  ❌ Plugin '${p.id}' (${p.manifestPath}):`);
+          for (const err of p.errors) {
+            console.error(`       ${err}`);
+          }
+        }
+      } else {
+        if (opts.json) {
+          console.log(JSON.stringify({ plugin: p.id, manifestPath: p.manifestPath, level: 'info', valid: true }));
+        } else {
+          console.error(`  ✅ Plugin '${p.id}' (v${p.manifest.version || '0.0.0'}): valid`);
+        }
+      }
+    }
+
+    if (!opts.json) {
+      console.error(`\n  ── Plugin Results ──`);
+      console.error(`     Total plugins scanned: ${plugins.length}`);
+      console.error(`     Errors:               ${pluginErrors}\n`);
+    }
+
+    if (pluginErrors > 0) {
+      process.exit(1);
+    }
+    return;
+  }
+
   if (!opts.json) {
     console.error(`\n  🔍 Linting vault: ${vaultDir}\n`);
   }