let-them-talk 5.3.0 → 5.4.0

package/cli.js

@@ -4,30 +4,37 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
-
-const command = process.argv[2];
+const { resolveDataDir: resolveSharedDataDir } = require('./data-dir');
+const { createCanonicalState } = require('./state/canonical');
 
 function printUsage() {
   console.log(`
-  Let Them Talk — Agent Bridge v5.3.0
+  Let Them Talk — Agent Bridge v5.4.0
   MCP message broker for inter-agent communication
   Supports: Claude Code, Gemini CLI, Codex CLI, Ollama
 
-  Usage:
+  Setup (one-time):
     npx let-them-talk init              Auto-detect CLI and configure MCP
     npx let-them-talk init --claude     Configure for Claude Code
     npx let-them-talk init --gemini     Configure for Gemini CLI
     npx let-them-talk init --codex      Configure for Codex CLI
     npx let-them-talk init --all        Configure for all supported CLIs
-    npx let-them-talk init --ollama    Setup Ollama agent bridge (local LLM)
-    npx let-them-talk init --template T  Initialize with a team template (pair, team, review, debate, ollama)
+    npx let-them-talk init --ollama      Setup Ollama agent bridge (local LLM)
+    npx let-them-talk init --template <name>  Initialize and print an agent template
+
+  After init, use the local launcher (no re-download):
+    node .agent-bridge/launch.js              Dashboard (http://localhost:3000)
+    node .agent-bridge/launch.js --lan        Dashboard on LAN (phone/tablet)
+    node .agent-bridge/launch.js status       Show active agents and message count
+    node .agent-bridge/launch.js msg <agent> <text>  Send a message to an agent
+    node .agent-bridge/launch.js reset        Clear all conversation data
+    node .agent-bridge/launch.js migrate      Backfill canonical event stream from legacy projections
+    node .agent-bridge/launch.js migrate --dry-run    Preview what migrate would do
+
+  Or via npx (re-downloads each time):
+    npx let-them-talk dashboard
+    npx let-them-talk status
     npx let-them-talk templates         List available agent templates
-    npx let-them-talk dashboard         Launch the web dashboard (http://localhost:3000)
-    npx let-them-talk dashboard --lan   Launch dashboard accessible on LAN (phone/tablet)
-    npx let-them-talk reset             Clear all conversation data
-    npx let-them-talk msg <agent> <text> Send a message to an agent
-    npx let-them-talk run "prompt" [--agents N] [--timeout M]  Autonomous execution with N agents, auto-stop after M minutes
-    npx let-them-talk status             Show active agents and message count
     npx let-them-talk uninstall          Remove agent-bridge from all CLI configs
     npx let-them-talk help               Show this help message
 
@@ -77,11 +84,11 @@ function detectOllama() {
 
 // The data directory where all agents read/write — must be the same for server + dashboard
 function dataDir(cwd) {
-  return path.join(cwd, '.agent-bridge');
+  return resolveSharedDataDir({ cwd });
 }
 
 // Configure for Claude Code (.mcp.json in project root)
-function setupClaude(serverPath, cwd) {
+function setupClaude(serverPath, cwd, log = console.log) {
   const mcpConfigPath = path.join(cwd, '.mcp.json');
   let mcpConfig = { mcpServers: {} };
   if (fs.existsSync(mcpConfigPath)) {
@@ -92,7 +99,7 @@ function setupClaude(serverPath, cwd) {
       // Backup corrupted file before overwriting
       const backup = mcpConfigPath + '.backup';
       fs.copyFileSync(mcpConfigPath, backup);
-      console.log('  [warn] Existing .mcp.json was invalid — backed up to .mcp.json.backup');
+      log('  [warn] Existing .mcp.json was invalid — backed up to .mcp.json.backup');
     }
   }
 
@@ -103,11 +110,11 @@ function setupClaude(serverPath, cwd) {
   };
 
   fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + '\n');
-  console.log('  [ok] Claude Code: .mcp.json updated');
+  log('  [ok] Claude Code: .mcp.json updated');
 }
 
 // Configure for Gemini CLI (.gemini/settings.json or GEMINI.md with MCP config)
-function setupGemini(serverPath, cwd) {
+function setupGemini(serverPath, cwd, log = console.log) {
   // Gemini CLI uses .gemini/settings.json for MCP configuration
   const geminiDir = path.join(cwd, '.gemini');
   const settingsPath = path.join(geminiDir, 'settings.json');
@@ -124,7 +131,7 @@ function setupGemini(serverPath, cwd) {
     } catch {
       const backup = settingsPath + '.backup';
       fs.copyFileSync(settingsPath, backup);
-      console.log('  [warn] Existing settings.json was invalid — backed up to settings.json.backup');
+      log('  [warn] Existing settings.json was invalid — backed up to settings.json.backup');
     }
   }
 
@@ -136,11 +143,11 @@ function setupGemini(serverPath, cwd) {
   };
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-  console.log('  [ok] Gemini CLI: .gemini/settings.json updated');
+  log('  [ok] Gemini CLI: .gemini/settings.json updated');
 }
 
 // Configure for Codex CLI (uses .codex/config.toml)
-function setupCodex(serverPath, cwd) {
+function setupCodex(serverPath, cwd, log = console.log) {
   const codexDir = path.join(cwd, '.codex');
   const configPath = path.join(codexDir, 'config.toml');
 
@@ -171,16 +178,16 @@ timeout = 300
     fs.writeFileSync(configPath, config);
   }
 
-  console.log('  [ok] Codex CLI: .codex/config.toml updated');
+  log('  [ok] Codex CLI: .codex/config.toml updated');
 }
 
 // Setup Ollama agent bridge script
-function setupOllama(serverPath, cwd) {
+function setupOllama(serverPath, cwd, log = console.log) {
   const dir = dataDir(cwd);
-  const scriptPath = path.join(cwd, '.agent-bridge', 'ollama-agent.js');
+  const scriptPath = path.join(dir, 'ollama-agent.js');
 
-  if (!fs.existsSync(path.join(cwd, '.agent-bridge'))) {
-    fs.mkdirSync(path.join(cwd, '.agent-bridge'), { recursive: true });
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
   }
 
   const script = `#!/usr/bin/env node
@@ -291,27 +298,112 @@ process.on('SIGINT', function() { console.log('\\n[' + name + '] Shutting down.'
   const tmpPath = scriptPath + '.tmp.' + process.pid;
   fs.writeFileSync(tmpPath, script);
   fs.renameSync(tmpPath, scriptPath);
-  console.log('  [ok] Ollama agent script created: .agent-bridge/ollama-agent.js');
-  console.log('');
-  console.log('  Launch an Ollama agent with:');
-  console.log('    node .agent-bridge/ollama-agent.js <name> <model>');
-  console.log('');
-  console.log('  Examples:');
-  console.log('    node .agent-bridge/ollama-agent.js Ollama llama3');
-  console.log('    node .agent-bridge/ollama-agent.js Coder codellama');
-  console.log('    node .agent-bridge/ollama-agent.js Writer mistral');
+  log('  [ok] Ollama agent script created: .agent-bridge/ollama-agent.js');
+  log('');
+  log('  Launch an Ollama agent with:');
+  log('    node .agent-bridge/ollama-agent.js <name> <model>');
+  log('');
+  log('  Examples:');
+  log('    node .agent-bridge/ollama-agent.js Ollama llama3');
+  log('    node .agent-bridge/ollama-agent.js Coder codellama');
+  log('    node .agent-bridge/ollama-agent.js Writer mistral');
 }
 
-function init() {
-  const cwd = process.cwd();
+// Merge-safe AGENTS.md / CLAUDE.md updater. Writes a marker block with the
+// background-worker rules so any agent cd'd into this folder gets them every
+// session. Re-running replaces only the marked block, leaving user content alone.
+function setupAgentsMarkdown(cwd, log = console.log) {
+  const BEGIN = '<!-- BEGIN let-them-talk (auto-managed — do not edit between markers) -->';
+  const END = '<!-- END let-them-talk -->';
+  const block = [
+    BEGIN,
+    '',
+    '## Let Them Talk — Background-Worker Mode',
+    '',
+    'This project uses the `agent-bridge` MCP server for multi-agent coordination.',
+    'When you run in this folder, you are a **background worker on a team**, not an',
+    'interactive chat assistant. Follow these rules strictly:',
+    '',
+    '1. **Your CLI terminal output is invisible** to the owner and to every other',
+    '   agent. If you want anyone to see something, it MUST go through',
+    '   `send_message(to="...", content="...")` or `broadcast(content="...")`.',
+    '',
+    '2. **No narration in terminal.** Do not "reply" to messages in your terminal',
+    '   window. Do not summarize your progress in terminal. Do not print status',
+    '   updates in terminal. Those are invisible. Talk like a human on a team chat',
+    '   — announce starts, finishes, blockers, and questions via `send_message`.',
+    '',
+    '3. **Stay in the listen loop.** After every action, call `listen_group()` (or',
+    '   `listen()` in direct mode). When it returns an empty batch, that is NORMAL',
+    '   — call it again immediately. If it returns a tool error like',
+    '   `"timed out awaiting tools/call"`, that is a Codex-level transport hiccup',
+    '   — immediately call it again. Never stop looping, never treat an empty',
+    '   return or tool error as "done".',
+    '',
+    '4. **Reply to Dashboard/Owner via `send_message(to="Dashboard")`.** The owner',
+    '   reads replies in the dashboard Messages tab, not your terminal.',
+    '',
+    '5. **Do not answer on another agent\'s behalf.** If a message targets a',
+    '   specific agent (`msg.to`), only that agent should reply.',
+    '',
+    '6. The loop only ends when the owner sends a message telling you to stop.',
+    '',
+    END,
+  ].join('\n');
+
+  const targets = [
+    { file: 'AGENTS.md', label: 'Codex / oh-my-codex' },
+    { file: 'CLAUDE.md', label: 'Claude Code' },
+  ];
+
+  for (const { file, label } of targets) {
+    const fp = path.join(cwd, file);
+    let existing = '';
+    let existed = false;
+    if (fs.existsSync(fp)) {
+      existing = fs.readFileSync(fp, 'utf8');
+      existed = true;
+    }
+
+    const markerRegex = new RegExp(
+      BEGIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+        '[\\s\\S]*?' +
+        END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+      'g'
+    );
+
+    let next;
+    if (markerRegex.test(existing)) {
+      // Replace only the managed block
+      next = existing.replace(markerRegex, block);
+      log('  [ok] ' + file + ': refreshed Let Them Talk block (' + label + ')');
+    } else if (existed) {
+      // Append below user content
+      const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+      next = existing + separator + block + '\n';
+      log('  [ok] ' + file + ': appended Let Them Talk block (' + label + ')');
+    } else {
+      // New file — minimal content so only our block is present
+      next = '# ' + path.basename(cwd) + ' — Agent Instructions\n\n' + block + '\n';
+      log('  [ok] ' + file + ': created with Let Them Talk block (' + label + ')');
+    }
+    fs.writeFileSync(fp, next);
+  }
+}
+
+function init(options) {
+  const opts = options || {};
+  const cwd = opts.cwd || process.cwd();
   const serverPath = path.join(__dirname, 'server.js').replace(/\\/g, '/');
   const gitignorePath = path.join(cwd, '.gitignore');
-  const flag = process.argv[3];
+  const argv = Array.isArray(opts.argv) ? opts.argv : process.argv;
+  const flag = opts.flag !== undefined ? opts.flag : argv[3];
+  const log = typeof opts.log === 'function' ? opts.log : console.log;
 
-  console.log('');
-  console.log('  Let Them Talk — Initializing Agent Bridge');
-  console.log('  ==========================================');
-  console.log('');
+  log('');
+  log('  Let Them Talk — Initializing Agent Bridge');
+  log('  ==========================================');
+  log('');
 
   let targets = [];
 
@@ -326,12 +418,12 @@ function init() {
   } else if (flag === '--ollama') {
     const ollama = detectOllama();
     if (!ollama.installed) {
-      console.log('  Ollama not found. Install it from: https://ollama.com/download');
-      console.log('  After installing, run: ollama pull llama3');
-      console.log('');
+      log('  Ollama not found. Install it from: https://ollama.com/download');
+      log('  After installing, run: ollama pull llama3');
+      log('');
     } else {
-      console.log('  Ollama detected: ' + ollama.version);
-      setupOllama(serverPath, cwd);
+      log('  Ollama detected: ' + ollama.version);
+      setupOllama(serverPath, cwd, log);
     }
     targets = detectCLIs();
     if (targets.length === 0) targets = ['claude'];
@@ -341,22 +433,28 @@ function init() {
     if (targets.length === 0) {
       // Default to claude if nothing detected
       targets = ['claude'];
-      console.log('  No CLI detected, defaulting to Claude Code config.');
+      log('  No CLI detected, defaulting to Claude Code config.');
     } else {
-      console.log(`  Detected CLI(s): ${targets.join(', ')}`);
+      log(`  Detected CLI(s): ${targets.join(', ')}`);
     }
   }
 
-  console.log('');
+  log('');
 
   for (const target of targets) {
     switch (target) {
-      case 'claude': setupClaude(serverPath, cwd); break;
-      case 'gemini': setupGemini(serverPath, cwd); break;
-      case 'codex':  setupCodex(serverPath, cwd);  break;
+      case 'claude': setupClaude(serverPath, cwd, log); break;
+      case 'gemini': setupGemini(serverPath, cwd, log); break;
+      case 'codex':  setupCodex(serverPath, cwd, log);  break;
     }
   }
 
+  // Persistent system-level directive for any agent that starts in this folder.
+  // Codex (via oh-my-codex's developer_instructions) and Claude Code both read
+  // AGENTS.md / CLAUDE.md automatically on startup. A marker block lets us merge
+  // in/out cleanly without clobbering whatever else the user has written.
+  setupAgentsMarkdown(cwd, log);
+
   // Add .agent-bridge/ and MCP config files to .gitignore
   const gitignoreEntries = ['.agent-bridge/', '.mcp.json', '.codex/', '.gemini/'];
   if (fs.existsSync(gitignorePath)) {
@@ -365,24 +463,62 @@ function init() {
     if (missing.length) {
       content += '\n# Agent Bridge (auto-added by let-them-talk init)\n' + missing.join('\n') + '\n';
       fs.writeFileSync(gitignorePath, content);
-      console.log('  [ok] Added to .gitignore: ' + missing.join(', '));
+      log('  [ok] Added to .gitignore: ' + missing.join(', '));
     } else {
-      console.log('  [ok] .gitignore already configured');
+      log('  [ok] .gitignore already configured');
     }
   } else {
     fs.writeFileSync(gitignorePath, '# Agent Bridge (auto-added by let-them-talk init)\n' + gitignoreEntries.join('\n') + '\n');
-    console.log('  [ok] .gitignore created');
+    log('  [ok] .gitignore created');
   }
 
-  console.log('');
-  console.log('  Agent Bridge is ready! Restart your CLI to pick up the MCP tools.');
-  console.log('');
+  // Save local launcher scripts so users never need to re-download
+  const bridgeDir = dataDir(cwd);
+  if (!fs.existsSync(bridgeDir)) {
+    fs.mkdirSync(bridgeDir, { recursive: true });
+  }
+
+  const cliPath = path.join(__dirname, 'cli.js').replace(/\\/g, '/');
+
+  // Dashboard launcher - run with: node .agent-bridge/launch.js
+  const launcherScript = `#!/usr/bin/env node
+// Auto-generated by let-them-talk init - launch dashboard without re-downloading
+// Usage: node .agent-bridge/launch.js [--lan|dashboard|status|reset|msg]
+
+const firstArg = process.argv[2] || 'dashboard';
+const cliPath = ${JSON.stringify(cliPath)};
+
+try {
+  require('fs').accessSync(cliPath);
+} catch {
+  console.error('  Let Them Talk CLI not found at: ' + cliPath);
+  console.error('  The npx cache may have been cleaned. Fix with either:');
+  console.error('    npx let-them-talk init          (re-creates launcher)');
+  console.error('    npm i -g let-them-talk          (permanent global install)');
+  process.exit(1);
+}
+
+// Forward to cli.js with the command
+const forwardedArgs = firstArg === '--lan'
+  ? ['dashboard', '--lan', ...process.argv.slice(3)]
+  : [firstArg, ...process.argv.slice(3)];
+process.argv = [process.argv[0], cliPath, ...forwardedArgs];
+require(cliPath);
+`;
+
+  fs.writeFileSync(path.join(bridgeDir, 'launch.js'), launcherScript);
+  const launcherPath = path.join(bridgeDir, 'launch.js');
+  log('  [ok] Local launcher saved to .agent-bridge/launch.js');
+
+  log('');
+  log('  Agent Bridge is ready! Restart your CLI to pick up the MCP tools.');
+  log('');
 
   // Show template if --template was provided
   var templateFlag = null;
-  for (var i = 3; i < process.argv.length; i++) {
-    if (process.argv[i] === '--template' && process.argv[i + 1]) {
-      templateFlag = process.argv[i + 1];
+  for (var i = 3; i < argv.length; i++) {
+    if (argv[i] === '--template' && argv[i + 1]) {
+      templateFlag = argv[i + 1];
       break;
     }
   }
@@ -390,22 +526,30 @@ function init() {
   if (templateFlag) {
     showTemplate(templateFlag);
   } else {
-    console.log('  Open two terminals and start a conversation between agents.');
-    console.log('  Tip: Use "npx let-them-talk init --template pair" for ready-made prompts.');
-    console.log('');
-    console.log('  \x1b[1m  Try autonomous mode:\x1b[0m');
-    console.log('    npx let-them-talk run "build a REST API" --agents 3');
-    console.log('');
-    console.log('  \x1b[1m  Monitor:\x1b[0m');
-    console.log('    npx let-them-talk dashboard');
-    console.log('    npx let-them-talk status');
-    console.log('    npx let-them-talk doctor');
-    console.log('');
+    log('  Open two terminals and start a conversation between agents.');
+    log('  Tip: Use "npx let-them-talk init --template pair" for ready-made prompts.');
+    log('');
+    log('  \x1b[1m  Monitor:\x1b[0m');
+    log('    node .agent-bridge/launch.js              (dashboard)');
+    log('    node .agent-bridge/launch.js status       (agent status)');
+    log('    node .agent-bridge/launch.js reset        (clear data)');
+    log('');
+    log('  Or use npx (re-downloads each time):');
+    log('    npx let-them-talk dashboard');
+    log('');
   }
+
+  return {
+    cwd,
+    flag: flag || null,
+    targets,
+    bridgeDir,
+    launcherPath,
+  };
 }
 
 function reset() {
-  const targetDir = process.env.AGENT_BRIDGE_DATA_DIR || path.join(process.cwd(), '.agent-bridge');
+  const targetDir = resolveDataDirCli();
 
   if (!fs.existsSync(targetDir)) {
     console.log('  No .agent-bridge/ directory found. Nothing to reset.');
@@ -436,38 +580,79 @@ function reset() {
   const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
   const archivePath = path.join(archiveDir, timestamp);
   try {
-    fs.mkdirSync(archivePath, { recursive: true });
-    const filesToArchive = ['history.jsonl', 'messages.jsonl', 'agents.json', 'decisions.json', 'tasks.json'];
-    let archived = 0;
-    for (const f of filesToArchive) {
-      const src = path.join(targetDir, f);
-      if (fs.existsSync(src)) {
-        fs.copyFileSync(src, path.join(archivePath, f));
-        archived++;
-      }
-    }
-    if (archived > 0) {
-      console.log('  [ok] Archived ' + archived + ' files to .agent-bridge-archive/' + timestamp + '/');
+    const archiveResult = getCanonicalStateCli().archiveFiles({
+      fileNames: ['history.jsonl', 'messages.jsonl', 'agents.json', 'decisions.json', 'tasks.json'],
+      destinationDir: archivePath,
+    });
+    if (archiveResult.archived > 0) {
+      console.log('  [ok] Archived ' + archiveResult.archived + ' files to .agent-bridge-archive/' + timestamp + '/');
     }
   } catch (e) {
     console.log('  [warn] Could not archive: ' + e.message + ' — proceeding with reset anyway.');
   }
 
-  fs.rmSync(targetDir, { recursive: true, force: true });
-  fs.mkdirSync(targetDir, { recursive: true });
+  getCanonicalStateCli().resetRuntime({
+    fixedFileNames: [
+      'messages.jsonl',
+      'history.jsonl',
+      'agents.json',
+      'acks.json',
+      'tasks.json',
+      'profiles.json',
+      'workflows.json',
+      'branches.json',
+      'read_receipts.json',
+      'permissions.json',
+      'config.json',
+      'decisions.json',
+    ],
+  });
   console.log('  Cleared all data from ' + targetDir);
 }
 
 function getTemplates() {
-  const templatesDir = path.join(__dirname, 'templates');
-  if (!fs.existsSync(templatesDir)) return [];
-  return fs.readdirSync(templatesDir)
-    .filter(f => f.endsWith('.json'))
-    .map(f => {
-      try { return JSON.parse(fs.readFileSync(path.join(templatesDir, f), 'utf8')); }
-      catch { return null; }
-    })
-    .filter(Boolean);
+  var all = [];
+
+  // 1. Built-in templates (shipped with the package)
+  var builtinDir = path.join(__dirname, 'templates');
+  if (fs.existsSync(builtinDir)) {
+    fs.readdirSync(builtinDir).filter(f => f.endsWith('.json')).forEach(f => {
+      try { var t = JSON.parse(fs.readFileSync(path.join(builtinDir, f), 'utf8')); t._source = 'built-in'; all.push(t); }
+      catch {}
+    });
+  }
+
+  // 2. Project-local templates: .agent-bridge/templates/ in current working directory
+  var localDir = path.join(resolveDataDirCli(), 'templates');
+  if (fs.existsSync(localDir)) {
+    fs.readdirSync(localDir).filter(f => f.endsWith('.json')).forEach(f => {
+      try {
+        var t = JSON.parse(fs.readFileSync(path.join(localDir, f), 'utf8'));
+        t._source = 'local';
+        // Don't add duplicates (local overrides built-in with same name)
+        var existing = all.findIndex(e => e.name === t.name);
+        if (existing >= 0) all[existing] = t;
+        else all.push(t);
+      } catch {}
+    });
+  }
+
+  // 3. User-global templates: ~/.let-them-talk/templates/
+  var homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  var globalDir = path.join(homeDir, '.let-them-talk', 'templates');
+  if (fs.existsSync(globalDir)) {
+    fs.readdirSync(globalDir).filter(f => f.endsWith('.json')).forEach(f => {
+      try {
+        var t = JSON.parse(fs.readFileSync(path.join(globalDir, f), 'utf8'));
+        t._source = 'global';
+        var existing = all.findIndex(e => e.name === t.name);
+        if (existing >= 0) all[existing] = t;
+        else all.push(t);
+      } catch {}
+    });
+  }
+
+  return all;
 }
 
 function listTemplates() {
@@ -478,11 +663,17 @@ function listTemplates() {
   console.log('');
   for (const t of templates) {
     const agentNames = t.agents.map(a => a.name).join(', ');
-    console.log('  ' + t.name.padEnd(12) + ' ' + t.description);
+    const sourceTag = t._source === 'local' ? ' [local]' : t._source === 'global' ? ' [global]' : '';
+    console.log('  ' + t.name.padEnd(12) + ' ' + t.description + sourceTag);
     console.log('  ' + ''.padEnd(12) + ' Agents: ' + agentNames);
     console.log('');
   }
   console.log('  Usage: npx let-them-talk init --template <name>');
+  console.log('  Note: this command lists agent templates only. Conversation workflow templates ship separately in agent-bridge/conversation-templates/*.json.');
+  console.log('');
+  console.log('  Custom templates:');
+  console.log('    Project-local:  .agent-bridge/templates/*.json');
+  console.log('    User-global:    ~/.let-them-talk/templates/*.json');
   console.log('');
 }
 
@@ -499,8 +690,9 @@ function showTemplate(templateName) {
   console.log('  Template: ' + template.name);
   console.log('  ' + template.description);
   console.log('');
-  console.log('  Copy these prompts into each terminal:');
+  console.log('  Copy these agent prompts into each terminal:');
   console.log('  ======================================');
+  console.log('  These prompts assume current onboarding: register, get_briefing(), then get_guide() when you need the current rules.');
 
   for (var i = 0; i < template.agents.length; i++) {
     var a = template.agents[i];
@@ -520,7 +712,11 @@ function dashboard() {
 }
 
 function resolveDataDirCli() {
-  return process.env.AGENT_BRIDGE_DATA_DIR || path.join(process.cwd(), '.agent-bridge');
+  return resolveSharedDataDir();
+}
+
+function getCanonicalStateCli() {
+  return createCanonicalState({ dataDir: resolveDataDirCli(), processPid: process.pid });
 }
 
 function readJsonl(filePath) {
@@ -569,10 +765,7 @@ function cliMsg() {
     timestamp: new Date().toISOString(),
   };
 
-  const messagesFile = path.join(dir, 'messages.jsonl');
-  const historyFile = path.join(dir, 'history.jsonl');
-  fs.appendFileSync(messagesFile, JSON.stringify(msg) + '\n');
-  fs.appendFileSync(historyFile, JSON.stringify(msg) + '\n');
+  getCanonicalStateCli().appendMessage(msg);
 
   console.log('  Message sent to ' + recipient + ': ' + text);
 }
@@ -658,155 +851,13 @@ function cliStatus() {
   console.log('');
 }
 
-// v5.0: One-command autonomous execution
-function cliRun() {
-  const prompt = process.argv[3];
-  if (!prompt) {
-    console.error('  Usage: npx let-them-talk run "build a login system" [--agents N] [--timeout M]');
-    console.error('  Spawns N agent processes, auto-assigns roles, creates autonomous workflow, and starts execution.');
-    process.exit(1);
-  }
-
-  // Parse --agents flag (default: 3)
-  let agentCount = 3;
-  const agentsIdx = process.argv.indexOf('--agents');
-  if (agentsIdx !== -1 && process.argv[agentsIdx + 1]) {
-    agentCount = Math.max(2, Math.min(10, parseInt(process.argv[agentsIdx + 1]) || 3));
-  }
-
-  // Parse --timeout flag (default: no timeout, in minutes)
-  let timeoutMin = 0;
-  const timeoutIdx = process.argv.indexOf('--timeout');
-  if (timeoutIdx !== -1 && process.argv[timeoutIdx + 1]) {
-    timeoutMin = Math.max(1, parseInt(process.argv[timeoutIdx + 1]) || 0);
-  }
-
-  const cwd = process.cwd();
-  const dir = path.join(cwd, '.agent-bridge');
-  const serverPath = path.join(__dirname, 'server.js');
-
-  // Ensure data directory exists
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-
-  // Set group conversation mode
-  const configPath = path.join(dir, 'config.json');
-  const config = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, 'utf8')) : {};
-  config.conversation_mode = 'group';
-  fs.writeFileSync(configPath, JSON.stringify(config));
-
-  // Agent names based on count
-  const AGENT_NAMES = ['Lead', 'Builder', 'Reviewer', 'Architect', 'Frontend', 'Backend', 'Tester', 'Designer', 'DevOps', 'Security'];
-  const names = AGENT_NAMES.slice(0, agentCount);
-
-  console.log('');
-  console.log('  Let Them Talk — Autonomous Run');
-  console.log('  ===============================');
-  console.log('  Prompt: ' + prompt);
-  console.log('  Agents: ' + agentCount + ' (' + names.join(', ') + ')');
-  console.log('  Mode: Autonomous (proactive work loop)');
-  console.log('');
-
-  const { spawn } = require('child_process');
-  const children = [];
-
-  // Spawn agent processes
-  for (let i = 0; i < agentCount; i++) {
-    const agentName = names[i];
-    console.log('  Spawning agent: ' + agentName + '...');
-
-    const child = spawn('node', [serverPath], {
-      env: {
-        ...process.env,
-        AGENT_BRIDGE_DATA_DIR: dir,
-        AGENT_BRIDGE_AUTO_REGISTER: agentName,
-        AGENT_BRIDGE_AUTO_PROMPT: i === 0 ? prompt : '', // only first agent gets the prompt
-      },
-      stdio: 'pipe',
-      cwd: cwd,
-    });
-
-    child.on('error', (err) => {
-      console.error('  [' + agentName + '] Error: ' + err.message);
-    });
-
-    child.on('exit', (code) => {
-      if (code !== 0 && code !== null) {
-        console.log('  \x1b[33m[' + agentName + '] Crashed (code ' + code + '). Auto-restarting...\x1b[0m');
-        const restart = spawn('node', [serverPath], {
-          env: { ...process.env, AGENT_BRIDGE_DATA_DIR: dir, AGENT_BRIDGE_AUTO_REGISTER: agentName },
-          stdio: 'pipe', cwd: cwd,
-        });
-        const entry = children.find(c => c.name === agentName);
-        if (entry) entry.process = restart;
-      } else {
-        console.log('  [' + agentName + '] Exited.');
-      }
-    });
-
-    children.push({ name: agentName, process: child });
-  }
-
-  console.log('');
-  console.log('  All ' + agentCount + ' agents spawned. They will auto-register and start working.');
-  console.log('  Open the dashboard to monitor: npx let-them-talk dashboard');
-  console.log('');
-  console.log('  Press Ctrl+C to stop all agents.');
-  console.log('');
-
-  // Inject the prompt as a dashboard message after agents register
-  setTimeout(() => {
-    try {
-      const messagesFile = path.join(dir, 'messages.jsonl');
-      const msg = {
-        id: 'run_' + Date.now().toString(36),
-        from: 'Dashboard',
-        to: '__group__',
-        content: prompt,
-        timestamp: new Date().toISOString(),
-        broadcast: true,
-      };
-      fs.appendFileSync(messagesFile, JSON.stringify(msg) + '\n');
-      const historyFile = path.join(dir, 'history.jsonl');
-      fs.appendFileSync(historyFile, JSON.stringify(msg) + '\n');
-      console.log('  Prompt injected to team. Agents will pick it up via get_work().');
-    } catch (e) {
-      console.error('  Failed to inject prompt: ' + e.message);
-    }
-  }, 3000); // 3s delay for agents to register
-
-  // Clean shutdown on Ctrl+C
-  process.on('SIGINT', () => {
-    console.log('\n  Stopping all agents...');
-    for (const c of children) {
-      try { c.process.kill(); } catch {}
-    }
-    process.exit(0);
-  });
-
-  // Auto-stop after --timeout minutes
-  if (timeoutMin > 0) {
-    console.log('  Auto-stop in ' + timeoutMin + ' minute(s).');
-    setTimeout(() => {
-      console.log('\n  Timeout reached (' + timeoutMin + 'min). Stopping all agents...');
-      for (const c of children) { try { c.process.kill(); } catch {} }
-      process.exit(0);
-    }, timeoutMin * 60000);
-  }
-
-  // Periodic progress updates every 30s
-  setInterval(() => {
-    try {
-      const agentsData = fs.existsSync(path.join(dir, 'agents.json')) ? JSON.parse(fs.readFileSync(path.join(dir, 'agents.json'), 'utf8')) : {};
-      const online = Object.values(agentsData).filter(a => {
-        try { process.kill(a.pid, 0); return true; } catch { return false; }
-      }).length;
-      const history = fs.existsSync(path.join(dir, 'history.jsonl')) ? fs.readFileSync(path.join(dir, 'history.jsonl'), 'utf8').trim().split(/\r?\n/).filter(l => l.trim()).length : 0;
-      const tasksData = fs.existsSync(path.join(dir, 'tasks.json')) ? JSON.parse(fs.readFileSync(path.join(dir, 'tasks.json'), 'utf8')) : [];
-      const done = Array.isArray(tasksData) ? tasksData.filter(t => t.status === 'done').length : 0;
-      const active = Array.isArray(tasksData) ? tasksData.filter(t => t.status === 'in_progress').length : 0;
-      console.log(`  \x1b[90m[${new Date().toLocaleTimeString()}]\x1b[0m ${online} agents | ${history} msgs | ${done} done, ${active} active`);
-    } catch {}
-  }, 30000);
+function cliMigrate() {
+  const args = process.argv.slice(3);
+  const dryRun = args.includes('--dry-run') || args.includes('-n');
+  const positional = args.filter((a) => !a.startsWith('-'));
+  const projectArg = positional[0] || process.cwd();
+  const { migrate } = require('./scripts/migrate-legacy-to-canonical');
+  migrate(projectArg, { dryRun });
 }
 
 // v5.0: Diagnostic health check
@@ -817,7 +868,7 @@ function cliDoctor() {
   let issues = 0;
 
   // Check data directory
-  const dir = path.join(process.cwd(), '.agent-bridge');
+  const dir = resolveDataDirCli();
   if (fs.existsSync(dir)) {
     console.log('  \x1b[32m✓\x1b[0m .agent-bridge/ directory exists');
     try { fs.accessSync(dir, fs.constants.W_OK); console.log('  \x1b[32m✓\x1b[0m .agent-bridge/ is writable'); }
@@ -1041,49 +1092,154 @@ function uninstall() {
   console.log('');
 }
 
-switch (command) {
-  case 'init':
-    init();
-    break;
-  case 'templates':
-    listTemplates();
-    break;
-  case 'dashboard':
-    dashboard();
-    break;
-  case 'reset':
-    reset();
-    break;
-  case 'doctor':
-    cliDoctor();
-    break;
-  case 'msg':
-  case 'message':
-  case 'send':
-    cliMsg();
-    break;
-  case 'status':
-    cliStatus();
-    break;
-  case 'run':
-    cliRun();
-    break;
-  case 'uninstall':
-  case 'remove':
-    uninstall();
-    break;
-  case 'plugin':
-  case 'plugins':
-    console.log('  Plugins have been removed in v3.4.3. CLI terminals have their own extension systems.');
-    break;
-  case 'help':
-  case '--help':
-  case '-h':
-  case undefined:
-    printUsage();
-    break;
-  default:
-    console.error(`  Unknown command: ${command}`);
-    printUsage();
-    process.exit(1);
+// --- Assistant init ---
+function assistantInit() {
+  const cwd = process.cwd();
+  const dataDir = path.join(cwd, '.agent-bridge');
+  const assistantDir = path.join(dataDir, 'assistant');
+
+  console.log('');
+  console.log('  \x1b[1m\x1b[35mLet Them Talk — Assistant Setup\x1b[0m');
+  console.log('  ════════════════════════════════════');
+  console.log('');
+
+  // Check if Let Them Talk is already initialized
+  if (!fs.existsSync(dataDir)) {
+    console.log('  \x1b[31m✗ Let Them Talk not found.\x1b[0m');
+    console.log('  Run \x1b[36mnpx let-them-talk init\x1b[0m first.');
+    console.log('');
+    return;
+  }
+
+  // Create assistant directory with template files
+  if (!fs.existsSync(assistantDir)) {
+    fs.mkdirSync(assistantDir, { recursive: true });
+  }
+
+  const templateDir = path.join(__dirname, 'assistant');
+  const files = ['Soul.md', 'Identity.md', 'Memory.md', 'Skills.md', 'Tools.md', 'SafetyRules.md'];
+  let created = 0;
+  let skipped = 0;
+
+  for (const file of files) {
+    const dest = path.join(assistantDir, file);
+    if (fs.existsSync(dest)) {
+      console.log('  \x1b[33m⊘\x1b[0m ' + file + ' (already exists, skipped)');
+      skipped++;
+      continue;
+    }
+    const src = path.join(templateDir, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+    } else {
+      // Fallback: create minimal template
+      const content = `# ${file.replace('.md', '')}\n\nEdit this file to customize your assistant.\n`;
+      fs.writeFileSync(dest, content);
+    }
+    console.log('  \x1b[32m✓\x1b[0m ' + file);
+    created++;
+  }
+
+  console.log('');
+  if (created > 0) {
+    console.log(`  Created ${created} file${created > 1 ? 's' : ''} in .agent-bridge/assistant/`);
+  }
+  if (skipped > 0) {
+    console.log(`  Skipped ${skipped} existing file${skipped > 1 ? 's' : ''}`);
+  }
+
+  console.log('');
+  console.log('  \x1b[1mNext steps:\x1b[0m');
+  console.log('');
+  console.log('  1. Edit the personality files in \x1b[36m.agent-bridge/assistant/\x1b[0m');
+  console.log('     - Soul.md      → personality and tone');
+  console.log('     - Identity.md  → name and role');
+  console.log('     - Skills.md    → what it can do');
+  console.log('     - Tools.md     → allowed/blocked tools');
+  console.log('     - SafetyRules.md → safety guardrails');
+  console.log('');
+  console.log('  2. Start the dashboard:');
+  console.log('     \x1b[36mnode .agent-bridge/launch.js\x1b[0m');
+  console.log('');
+  console.log('  3. Open the Assistant tab in the dashboard:');
+  console.log('     \x1b[36mhttp://<your-ip>:3000\x1b[0m → click \x1b[35mAssistant\x1b[0m tab');
+  console.log('');
+  console.log('  4. Open a terminal with Let Them Talk and register as "Assistant"');
+  console.log('     The agent should use the \x1b[36massistant()\x1b[0m tool to listen.');
+  console.log('');
+}
+
+function runCli() {
+  const command = process.argv[2];
+
+  switch (command) {
+    case 'init':
+      init();
+      break;
+    case 'assistant':
+      assistantInit();
+      break;
+    case 'templates':
+      listTemplates();
+      break;
+    case 'dashboard':
+      dashboard();
+      break;
+    case 'reset':
+      reset();
+      break;
+    case 'doctor':
+      cliDoctor();
+      break;
+    case 'migrate':
+    case 'migrate-legacy':
+      cliMigrate();
+      break;
+    case 'msg':
+    case 'message':
+    case 'send':
+      cliMsg();
+      break;
+    case 'status':
+      cliStatus();
+      break;
+    case 'uninstall':
+    case 'remove':
+      uninstall();
+      break;
+    case 'plugin':
+    case 'plugins':
+      console.log('  Plugins have been removed in v3.4.3. CLI terminals have their own extension systems.');
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      printUsage();
+      break;
+    default:
+      console.error(`  Unknown command: ${command}`);
+      printUsage();
+      process.exit(1);
+  }
+}
+
+function shouldAutoRunCli() {
+  if (require.main === module) return true;
+  const argvPath = process.argv[1];
+  if (!argvPath) return false;
+  const normalizedArgvPath = path.resolve(argvPath).replace(/\\/g, '/');
+  const normalizedFilePath = path.resolve(__filename).replace(/\\/g, '/');
+  return process.platform === 'win32'
+    ? normalizedArgvPath.toLowerCase() === normalizedFilePath.toLowerCase()
+    : normalizedArgvPath === normalizedFilePath;
+}
+
+module.exports = {
+  init,
+  runCli,
+};
+
+if (shouldAutoRunCli()) {
+  runCli();
 }