let-them-talk 5.5.2 → 5.5.4

package/README.md

@@ -310,7 +310,7 @@ The verify suite doesn't claim to cover every provider or runtime matrix, and do
 - **Rate-limited** API endpoints on non-localhost requests.
 - **No telemetry, no cloud.** Everything runs locally.
 - **Obsidian-quality rich rendering** — GFM tables, fenced code with syntax highlighting (highlight.js), Obsidian-style callouts (`> [!NOTE]`, `> [!WARNING]`, `> [!SUMMARY]-` collapsible), Mermaid diagrams, KaTeX math, clickable image lightbox, copy-code buttons. Every shipping lib is bundled locally under `vendor/` so the dashboard works offline.
-- **0 known vulnerabilities** in the shipped tarball as of v5.5.2.
+- **0 known vulnerabilities** in the shipped tarball as of v5.5.4.
 - **Sensitive-path blocks** on file-share: `.env`, `.pem`, `.key`, `.lan-token`, `mcp.json`, and the agent-bridge data directory cannot be shared.
 - See [`SECURITY.md`](SECURITY.md) for the disclosure policy.
 

package/USAGE.md

@@ -1,6 +1,6 @@
 <!-- Generated from ../USAGE.md by scripts/sync-packaged-docs.js for published package consumers. -->
 
-# Let Them Talk Usage Guide v5.5.2
+# Let Them Talk Usage Guide v5.5.4
 
 This guide is the short operator view of the current runtime. For normative architecture details, use the docs under `docs/architecture/`.
 

package/cli.js

@@ -9,7 +9,7 @@ const { createCanonicalState } = require('./state/canonical');
 
 function printUsage() {
   console.log(`
-  Let Them Talk — Agent Bridge v5.5.2
+  Let Them Talk — Agent Bridge v5.5.4
   MCP message broker for inter-agent communication
   Supports: Claude Code, Gemini CLI, Codex CLI, Ollama
 
@@ -30,6 +30,8 @@ function printUsage() {
     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
+    node .agent-bridge/launch.js repair       Repair corrupted canonical event log (drops orphan redactions)
+    node .agent-bridge/launch.js repair --dry-run     Preview what repair would do
 
   Or via npx (re-downloads each time):
     npx let-them-talk dashboard
@@ -879,6 +881,15 @@ function cliStatus() {
   console.log('');
 }
 
+function cliRepairEvents() {
+  const { repairBranch: _ } = require('./scripts/repair-canonical-events');
+  // Delegate to the script's main — it reads process.argv and handles --dry-run
+  const scriptPath = path.join(__dirname, 'scripts', 'repair-canonical-events.js');
+  const args = process.argv.slice(3);
+  const child = require('child_process').spawnSync(process.execPath, [scriptPath, ...args], { stdio: 'inherit' });
+  if (child.status !== 0) process.exit(child.status || 1);
+}
+
 function cliMigrate() {
   const args = process.argv.slice(3);
   const dryRun = args.includes('--dry-run') || args.includes('-n');
@@ -1143,6 +1154,10 @@ function runCli() {
     case 'migrate-legacy':
       cliMigrate();
       break;
+    case 'repair':
+    case 'repair-events':
+      cliRepairEvents();
+      break;
     case 'msg':
     case 'message':
     case 'send':

package/dashboard.js

@@ -3445,7 +3445,7 @@ server.listen(PORT, LAN_MODE ? '0.0.0.0' : '127.0.0.1', () => {
   const dataDir = resolveDataDir();
   const lanIP = getLanIP();
   console.log('');
-  console.log('  Let Them Talk - Agent Bridge Dashboard v5.5.2');
+  console.log('  Let Them Talk - Agent Bridge Dashboard v5.5.4');
   console.log('  ============================================');
   console.log('  Dashboard:  http://localhost:' + PORT);
   if (LAN_MODE && lanIP) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "let-them-talk",
-  "version": "5.5.2",
+  "version": "5.5.4",
   "description": "MCP message broker + web dashboard for inter-agent communication. Let AI CLI agents talk to each other.",
   "main": "server.js",
   "bin": {

package/scripts/repair-canonical-events.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// Repair a corrupted canonical event log in-place.
+//
+// Problem this fixes:
+//   Pre-v5.5.3 Clear Messages would emit a message.redacted event for every
+//   message currently in the projection, even if that message had no
+//   corresponding message.sent event in the canonical log (e.g. legacy
+//   projection-only messages left over from a partial migration, or an
+//   earlier clear cycle). On the next rebuild/replay the redacted event
+//   fails with "cannot apply message.redacted because message X does not
+//   exist", which blocks further Clear Messages on that branch.
+//
+//   v5.5.3 fixed the root cause in clearMessages so new redactions are
+//   gated on the presence of a message.sent ancestor. This script cleans
+//   up the orphan redactions that are already in the event log from
+//   previous versions so the branch can replay again.
+//
+// What it does:
+//   - For every branch under .agent-bridge/runtime/branches/<branch>/:
+//     - Reads events.jsonl
+//     - Collects the set of message IDs that have a message.sent event
+//     - Drops message.redacted and message.corrected events whose
+//       payload.message_id is not in that set (orphans)
+//     - Backs up the original events.jsonl to events.jsonl.pre-repair-<ts>
+//     - Writes the cleaned stream back
+//   - Deletes the branch's projection files (messages.jsonl, history.jsonl,
+//     dashboard-query-projection.json, events.head.json) so the runtime
+//     rebuilds them cleanly on the next read.
+//
+// Usage:
+//   node agent-bridge/scripts/repair-canonical-events.js [project-path]
+//   node agent-bridge/scripts/repair-canonical-events.js --dry-run [project-path]
+//
+// project-path defaults to the current working directory.
+
+const fs = require('fs');
+const path = require('path');
+const { resolveDataDir } = require('../data-dir');
+
+function readJsonl(file) {
+  if (!fs.existsSync(file)) return [];
+  return fs
+    .readFileSync(file, 'utf8')
+    .split(/\r?\n/)
+    .filter((line) => line.trim())
+    .map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+function repairBranch(branchDir, opts) {
+  const eventsFile = path.join(branchDir, 'events.jsonl');
+  if (!fs.existsSync(eventsFile)) return { skipped: true, reason: 'no events.jsonl' };
+
+  const events = readJsonl(eventsFile);
+  if (events.length === 0) return { skipped: true, reason: 'empty events.jsonl' };
+
+  const sentIds = new Set();
+  for (const ev of events) {
+    if (ev && ev.type === 'message.sent' && ev.payload && ev.payload.message && typeof ev.payload.message.id === 'string') {
+      sentIds.add(ev.payload.message.id);
+    }
+  }
+
+  const kept = [];
+  const orphans = [];
+  const duplicateRedactions = [];
+  const seenRedactedIds = new Set();
+  for (const ev of events) {
+    if (ev && (ev.type === 'message.redacted' || ev.type === 'message.corrected')) {
+      const msgId = ev.payload && ev.payload.message_id;
+      // Orphan: no corresponding message.sent ancestor.
+      if (msgId && !sentIds.has(msgId)) {
+        orphans.push(ev);
+        continue;
+      }
+      // Duplicate redaction: same message_id already redacted earlier in the
+      // stream. Keep the first, drop subsequent ones. Pre-v5.5.4 the replay
+      // threw on the second redaction; now it tolerates duplicates, but we
+      // still want to prune the log so it's clean.
+      if (ev.type === 'message.redacted' && msgId) {
+        if (seenRedactedIds.has(msgId)) {
+          duplicateRedactions.push(ev);
+          continue;
+        }
+        seenRedactedIds.add(msgId);
+      }
+    }
+    kept.push(ev);
+  }
+
+  const result = {
+    branch: path.basename(branchDir),
+    total_events: events.length,
+    message_sent_events: sentIds.size,
+    orphan_redacted: orphans.filter((o) => o.type === 'message.redacted').length,
+    orphan_corrected: orphans.filter((o) => o.type === 'message.corrected').length,
+    duplicate_redacted: duplicateRedactions.length,
+    kept_events: kept.length,
+  };
+
+  if (opts.dryRun) {
+    result.dryRun = true;
+    return result;
+  }
+
+  if (orphans.length === 0 && duplicateRedactions.length === 0) {
+    result.skipped = true;
+    result.reason = 'no orphan or duplicate events';
+    return result;
+  }
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const backupFile = path.join(branchDir, `events.jsonl.pre-repair-${stamp}`);
+  fs.copyFileSync(eventsFile, backupFile);
+  result.backup = backupFile;
+
+  fs.writeFileSync(eventsFile, kept.map((e) => JSON.stringify(e)).join('\n') + '\n');
+
+  // Drop cached projections + head pointer so the runtime rebuilds next read
+  for (const name of ['messages.jsonl', 'history.jsonl', 'dashboard-query-projection.json', 'events.head.json']) {
+    const p = path.join(branchDir, name);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  }
+  result.projections_cleared = true;
+
+  return result;
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const dryRun = args.includes('--dry-run') || args.includes('-n');
+  const projectArg = args.filter((a) => !a.startsWith('-'))[0] || process.cwd();
+
+  const dataDir = resolveDataDir({ cwd: projectArg });
+  const branchesDir = path.join(dataDir, 'runtime', 'branches');
+
+  console.log('');
+  console.log('  Canonical event log repair');
+  console.log('  ==========================');
+  console.log('  Project: ' + projectArg);
+  console.log('  Runtime: ' + branchesDir);
+  console.log(dryRun ? '  Mode: DRY RUN (no changes written)' : '  Mode: apply');
+  console.log('');
+
+  if (!fs.existsSync(branchesDir)) {
+    console.log('  [info] No canonical runtime at this path. Nothing to repair.');
+    return;
+  }
+
+  const branches = fs.readdirSync(branchesDir).filter((name) => {
+    const p = path.join(branchesDir, name);
+    return fs.statSync(p).isDirectory();
+  });
+
+  if (branches.length === 0) {
+    console.log('  [info] No branches present. Nothing to repair.');
+    return;
+  }
+
+  for (const name of branches) {
+    const r = repairBranch(path.join(branchesDir, name), { dryRun });
+    console.log(`  Branch "${name}":`);
+    if (r.skipped) {
+      console.log('    skipped — ' + r.reason);
+    } else {
+      console.log(`    ${r.total_events} total events, ${r.message_sent_events} sent messages`);
+      console.log(`    orphan redactions: ${r.orphan_redacted}, orphan corrections: ${r.orphan_corrected}, duplicate redactions: ${r.duplicate_redacted}`);
+      if (!dryRun) {
+        console.log('    [ok] rewrote events.jsonl (' + r.kept_events + ' events kept)');
+        console.log('    [ok] backup: ' + r.backup);
+        console.log('    [ok] projections cleared — will rebuild on next read');
+      } else {
+        const drops = r.orphan_redacted + r.orphan_corrected + r.duplicate_redacted;
+        console.log('    [dry-run] would drop ' + drops + ' bad event(s) and back up the original');
+      }
+    }
+  }
+
+  console.log('');
+  if (!dryRun) {
+    console.log('  Done. Clear Messages should now work on the repaired branches.');
+  } else {
+    console.log('  Re-run without --dry-run to apply.');
+  }
+  console.log('');
+}
+
+if (require.main === module) {
+  try { main(process.argv); }
+  catch (e) { console.error('  [error] ' + (e && e.stack ? e.stack : e)); process.exit(1); }
+}
+
+module.exports = { repairBranch };

package/server.js

@@ -3708,7 +3708,7 @@ function buildListenGroupResponse(batch, consumed, agentName, listenStart) {
     return new Date(a.timestamp) - new Date(b.timestamp);
   });
 
-  // LEAN RESPONSE (v5.5.2+): the agent already has every prior message in its
+  // LEAN RESPONSE (v5.5.4+): the agent already has every prior message in its
   // own LLM context, plus the full rule set from get_guide() + AGENTS.md. We
   // only send the NEW messages + the managed-mode signals needed for
   // turn-taking. No repeated reminders, no agent rosters, no "next_action"
@@ -8136,7 +8136,7 @@ function toolToggleRule(ruleId) {
 // --- MCP Server setup ---
 
 const server = new Server(
-  { name: 'agent-bridge', version: '5.5.2' },
+  { name: 'agent-bridge', version: '5.5.4' },
   { capabilities: { tools: {} } }
 );
 
@@ -9265,7 +9265,7 @@ async function main() {
   try {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('Agent Bridge MCP server v5.5.2 running (65 tools)');
+    console.error('Agent Bridge MCP server v5.5.4 running (65 tools)');
   } catch (e) {
     console.error('ERROR: MCP server failed to start: ' + e.message);
     console.error('Fix: Run "npx let-them-talk doctor" to check your setup.');

package/state/canonical.js

@@ -2770,8 +2770,22 @@ function createCanonicalState(options = {}) {
       const redactedAt = params.redactedAt || new Date().toISOString();
       const clearedMessageIds = [];
 
+      // Only redact messages that actually have a canonical message.sent event
+      // in this branch's log. Redacting a message that was never "sent" in
+      // canonical terms (e.g. a legacy projection-only message left over from
+      // pre-canonical clear cycles) would create an orphan redaction that
+      // breaks future replay — the rebuild fails with "cannot apply
+      // message.redacted because message X does not exist".
+      const canonicalSentIds = new Set();
+      for (const event of readCanonicalMessageEvents(branch)) {
+        if (event && event.type === 'message.sent' && event.payload && event.payload.message && typeof event.payload.message.id === 'string') {
+          canonicalSentIds.add(event.payload.message.id);
+        }
+      }
+
       for (const message of Array.isArray(currentMessages) ? currentMessages : []) {
         if (!message || typeof message.id !== 'string' || !message.id) continue;
+        if (!canonicalSentIds.has(message.id)) continue; // skip projection-only / orphan
         appendCanonicalMessageRedactedEvent({
           branch,
           actorAgent,

package/state/messages.js

@@ -397,18 +397,15 @@ function createMessagesState(options = {}) {
       case 'message.redacted': {
         const redaction = validateCanonicalMessageRedactionPayload(event);
         const record = findProjectedMessageRecord(projection, redaction.messageId);
-        if (!record) {
-          throw createCanonicalReplayError(
-            CANONICAL_REPLAY_ERROR_CODES.INVALID_SEQUENCE,
-            `Canonical message replay cannot apply ${describeReplayEvent(event)} because message ${redaction.messageId} does not exist in the current branch projection.`,
-            {
-              event_type: event.type,
-              seq: event.seq,
-              branch_id: event.branch_id,
-              message_id: redaction.messageId,
-            }
-          );
-        }
+        // Redaction is idempotent: if the message is already gone from the
+        // projection (e.g. a prior message.redacted for the same id already
+        // ran during this replay), the second redaction is a no-op rather
+        // than a fatal error. The canonical log can legitimately carry
+        // multiple redaction events per id — operators running Clear
+        // Messages repeatedly on the same branch would produce that shape,
+        // and aborting the whole replay over it is worse than ignoring the
+        // duplicate.
+        if (!record) return projection;
 
         if (record.messageIndex >= 0) {
           record.conversation.messages.splice(record.messageIndex, 1);