let-them-talk 5.3.0 → 5.4.0

package/scripts/check-session-lifecycle.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { createCanonicalEventLog } = require(path.resolve(__dirname, '..', 'events', 'log.js'));
+const { createBranchPathResolvers } = require(path.resolve(__dirname, '..', 'state', 'canonical.js'));
+const { createStateIo } = require(path.resolve(__dirname, '..', 'state', 'io.js'));
+const { createSessionsState } = require(path.resolve(__dirname, '..', 'state', 'sessions.js'));
+
+function fail(lines, exitCode = 1) {
+  fs.writeSync(2, lines.join('\n') + '\n');
+  process.exit(exitCode);
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function assert(condition, message, problems) {
+  if (!condition) problems.push(message);
+}
+
+function sessionTypesForAgent(eventLog, branchName, agentName) {
+  return eventLog
+    .readBranchEvents(branchName, { typePrefix: 'session.' })
+    .filter((event) => event.actor_agent === agentName)
+    .map((event) => event.type);
+}
+
+function main() {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'letthemtalk-session-lifecycle-'));
+  const dataDir = path.join(tempDir, '.agent-bridge');
+  const branchPaths = createBranchPathResolvers(dataDir);
+  const io = createStateIo({ dataDir });
+  const eventLog = createCanonicalEventLog({ dataDir });
+  const sessionsState = createSessionsState({ io, branchPaths, canonicalEventLog: eventLog });
+
+  const times = {
+    alphaRegister: '2026-04-16T01:00:00.000Z',
+    alphaHeartbeat: '2026-04-16T01:00:10.000Z',
+    alphaSwitchAway: '2026-04-16T01:00:20.000Z',
+    alphaFeatureStart: '2026-04-16T01:00:30.000Z',
+    alphaFeatureTouch: '2026-04-16T01:00:40.000Z',
+    alphaDeadSnapshot: '2026-04-16T01:00:50.000Z',
+    alphaResume: '2026-04-16T01:01:00.000Z',
+    alphaGracefulExit: '2026-04-16T01:01:10.000Z',
+    alphaFreshStart: '2026-04-16T01:01:20.000Z',
+    betaStart: '2026-04-16T01:01:30.000Z',
+    betaResume: '2026-04-16T01:01:40.000Z',
+    rebuildIndex: '2026-04-16T01:01:50.000Z',
+  };
+
+  const problems = [];
+
+  try {
+    const alphaMain = sessionsState.activateSession({
+      agentName: 'alpha',
+      branchName: 'main',
+      provider: 'claude',
+      reason: 'register',
+      at: times.alphaRegister,
+    });
+    const alphaMainId = alphaMain.session.session_id;
+
+    sessionsState.touchSession({
+      sessionId: alphaMainId,
+      branchName: 'main',
+      at: times.alphaHeartbeat,
+      heartbeat: true,
+    });
+
+    sessionsState.transitionSession({
+      sessionId: alphaMainId,
+      branchName: 'main',
+      state: 'interrupted',
+      reason: 'branch_switch',
+      at: times.alphaSwitchAway,
+    });
+
+    const alphaFeature = sessionsState.activateSession({
+      agentName: 'alpha',
+      branchName: 'feature_task5a',
+      provider: 'claude',
+      reason: 'branch_activate',
+      at: times.alphaFeatureStart,
+    });
+    const alphaFeatureId = alphaFeature.session.session_id;
+
+    sessionsState.touchSession({
+      sessionId: alphaFeatureId,
+      branchName: 'feature_task5a',
+      at: times.alphaFeatureTouch,
+    });
+
+    const alphaInterrupted = sessionsState.transitionLatestSessionForAgent({
+      agentName: 'alpha',
+      branchName: 'feature_task5a',
+      state: 'interrupted',
+      reason: 'dead_agent_snapshot',
+      recoverySnapshotFile: 'recovery-alpha.json',
+      at: times.alphaDeadSnapshot,
+    });
+
+    const alphaResumed = sessionsState.activateSession({
+      agentName: 'alpha',
+      branchName: 'feature_task5a',
+      provider: 'claude',
+      reason: 'register',
+      at: times.alphaResume,
+    });
+
+    sessionsState.transitionSession({
+      sessionId: alphaResumed.session.session_id,
+      branchName: 'feature_task5a',
+      state: 'completed',
+      reason: 'graceful_exit',
+      recoverySnapshotFile: 'recovery-alpha.json',
+      at: times.alphaGracefulExit,
+    });
+
+    const alphaFresh = sessionsState.activateSession({
+      agentName: 'alpha',
+      branchName: 'feature_task5a',
+      provider: 'claude',
+      reason: 'register',
+      at: times.alphaFreshStart,
+    });
+
+    const betaStart = sessionsState.activateSession({
+      agentName: 'beta',
+      branchName: 'main',
+      provider: 'gemini',
+      reason: 'register',
+      at: times.betaStart,
+    });
+
+    const betaResume = sessionsState.activateSession({
+      agentName: 'beta',
+      branchName: 'main',
+      provider: 'gemini',
+      reason: 'register',
+      at: times.betaResume,
+    });
+
+    const alphaMainManifest = readJson(branchPaths.getBranchSessionFile(alphaMainId, 'main'));
+    const alphaFeatureManifest = readJson(branchPaths.getBranchSessionFile(alphaFeatureId, 'feature_task5a'));
+    const alphaFreshManifest = readJson(branchPaths.getBranchSessionFile(alphaFresh.session.session_id, 'feature_task5a'));
+    const betaManifest = readJson(branchPaths.getBranchSessionFile(betaStart.session.session_id, 'main'));
+    const indexFile = branchPaths.getSessionsIndexFile();
+    const index = readJson(indexFile);
+
+    assert(alphaMain.created && !alphaMain.resumed, 'Initial register should create a main-branch session for alpha.', problems);
+    assert(alphaMainManifest.state === 'interrupted', 'Switching branches should interrupt alpha\'s main-branch session.', problems);
+    assert(alphaMainManifest.transition_reason === 'branch_switch', 'Main-branch interruption should record the branch_switch reason.', problems);
+    assert(alphaMainManifest.last_heartbeat_at === times.alphaHeartbeat, 'Heartbeat touch should update the session heartbeat timestamp.', problems);
+
+    assert(alphaFeature.created && !alphaFeature.resumed, 'First feature-branch activation should create a fresh branch-local session.', problems);
+    assert(alphaInterrupted.session && alphaInterrupted.session.state === 'interrupted', 'Dead-agent snapshot should mark the active feature session interrupted.', problems);
+    assert(alphaInterrupted.session && alphaInterrupted.session.recovery_snapshot_file === 'recovery-alpha.json', 'Dead-agent interruption should retain the recovery snapshot reference.', problems);
+
+    assert(alphaResumed.resumed, 'Registering again on the same interrupted branch should resume the feature session.', problems);
+    assert(alphaResumed.session.session_id === alphaFeatureId, 'Branch-local resume should reuse the interrupted feature session id.', problems);
+    assert(alphaFeatureManifest.state === 'completed', 'Graceful exit should mark the resumed feature session completed.', problems);
+    assert(alphaFeatureManifest.resume_count === 1, 'Feature session should record one resume after interruption.', problems);
+    assert(alphaFeatureManifest.transition_reason === 'graceful_exit', 'Graceful completion should keep the graceful_exit reason.', problems);
+
+    assert(alphaFresh.created && !alphaFresh.resumed, 'Registering after a completed session should create a new feature session.', problems);
+    assert(alphaFresh.session.session_id !== alphaFeatureId, 'Completed sessions must not be resumed as the next live interval.', problems);
+    assert(alphaFreshManifest.state === 'active', 'Fresh post-completion session should be active.', problems);
+
+    assert(betaStart.created && !betaStart.resumed, 'Beta should start with a new main-branch session.', problems);
+    assert(betaResume.resumed, 'An orphaned active session should be reclaimed by interrupt+resume on register.', problems);
+    assert(betaResume.session.session_id === betaStart.session.session_id, 'Orphaned active recovery should reuse the same beta session id.', problems);
+    assert(betaManifest.resume_count === 1, 'Recovered orphaned beta session should record one resume.', problems);
+
+    assert(fs.existsSync(indexFile), 'Session discovery index should be written under runtime/projections.', problems);
+    assert(index.sessions[alphaMainId] && index.sessions[alphaFeatureId] && index.sessions[alphaFresh.session.session_id], 'Index should contain every session summary.', problems);
+    assert(index.by_agent.alpha && index.by_agent.alpha.active_session_id === alphaFresh.session.session_id, 'Index should point alpha to the latest active branch session.', problems);
+    assert(index.by_branch.feature_task5a && index.by_branch.feature_task5a.active_session_ids.includes(alphaFresh.session.session_id), 'Index should expose the active feature-branch session.', problems);
+
+    fs.unlinkSync(indexFile);
+    const rebuiltIndex = sessionsState.rebuildIndex({ at: times.rebuildIndex });
+    assert(rebuiltIndex.sessions[alphaFeatureId] && rebuiltIndex.sessions[alphaFeatureId].state === 'completed', 'Rebuilt index should recover completed feature-session state from manifests.', problems);
+    assert(rebuiltIndex.by_agent.alpha.active_session_id === alphaFresh.session.session_id, 'Rebuilt index should restore the latest active alpha session.', problems);
+
+    const alphaMainEvents = sessionTypesForAgent(eventLog, 'main', 'alpha');
+    const alphaFeatureEvents = sessionTypesForAgent(eventLog, 'feature_task5a', 'alpha');
+    const betaEvents = sessionTypesForAgent(eventLog, 'main', 'beta');
+
+    assert(JSON.stringify(alphaMainEvents) === JSON.stringify(['session.started', 'session.interrupted']), 'Main branch should log start+interrupt events for alpha.', problems);
+    assert(JSON.stringify(alphaFeatureEvents) === JSON.stringify(['session.started', 'session.interrupted', 'session.resumed', 'session.completed', 'session.started']), 'Feature branch should log the full alpha lifecycle sequence.', problems);
+    assert(JSON.stringify(betaEvents) === JSON.stringify(['session.started', 'session.interrupted', 'session.resumed']), 'Main branch should log orphaned-active recovery for beta as start+interrupt+resume.', problems);
+
+    if (problems.length > 0) {
+      fail(['Session lifecycle validation failed.', ...problems], 1);
+    }
+
+    console.log([
+      'Session lifecycle validation passed.',
+      'Validated branch-scoped session creation, heartbeat activity, branch interruption, dead-agent interruption, resume, graceful completion, orphaned-active recovery, and index rebuild.',
+      `Index file: .agent-bridge/${path.relative(dataDir, indexFile).split(path.sep).join('/')}`,
+    ].join('\n'));
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+main();

package/scripts/export-markdown-workspace.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+const {
+  resolveDataDir,
+  resolveDefaultDataRoot,
+} = require(path.resolve(__dirname, '..', 'data-dir.js'));
+const { createCanonicalState } = require(path.resolve(__dirname, '..', 'state', 'canonical.js'));
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const USAGE = [
+  'Usage: node agent-bridge/scripts/export-markdown-workspace.js',
+  '  [--data-dir <path>] [--project-root <path>] [--output <path>] [--branch <branch> ...]',
+].join('\n');
+
+function fail(message, exitCode = 1) {
+  process.stderr.write(`${message}\n`);
+  process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+  const result = {
+    branches: [],
+    dataDir: null,
+    outputRoot: null,
+    projectRoot: null,
+  };
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      fail(USAGE, 0);
+    }
+
+    if (!['--data-dir', '--output', '--project-root', '--branch'].includes(arg)) {
+      fail(USAGE, 2);
+    }
+
+    if (index + 1 >= argv.length) {
+      fail(USAGE, 2);
+    }
+
+    const value = argv[index + 1];
+    index += 1;
+
+    if (arg === '--data-dir') {
+      result.dataDir = path.resolve(value);
+      continue;
+    }
+
+    if (arg === '--output') {
+      result.outputRoot = path.resolve(value);
+      continue;
+    }
+
+    if (arg === '--project-root') {
+      result.projectRoot = path.resolve(value);
+      continue;
+    }
+
+    result.branches.push(value);
+  }
+
+  return result;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const projectRoot = args.projectRoot
+    || (args.dataDir ? path.resolve(args.dataDir, '..') : resolveDefaultDataRoot({ cwd: process.cwd(), moduleDir: PACKAGE_ROOT }));
+  const dataDir = args.dataDir
+    || resolveDataDir({ cwd: projectRoot, moduleDir: PACKAGE_ROOT });
+  const canonicalState = createCanonicalState({ dataDir, processPid: process.pid });
+  const result = canonicalState.exportMarkdownWorkspace({
+    projectRoot,
+    outputRoot: args.outputRoot,
+    branches: args.branches.length > 0 ? args.branches : null,
+  });
+
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+main();

package/scripts/fixtures/message-replay/clean.jsonl

@@ -0,0 +1,2 @@
+{"event_id":"evt-task3c-clean-1","stream":"branch","branch_id":"main","seq":1,"type":"message.sent","occurred_at":"2026-04-15T20:10:00.000Z","schema_version":1,"actor_agent":"fixture-alpha","session_id":"session_task3c_clean","command_id":"cmd_task3c_clean_1","causation_id":null,"correlation_id":"corr_task3c_clean","payload":{"message":{"id":"msg-task3c-clean-1","from":"fixture-alpha","to":"fixture-beta","content":"Fixture clean hello","timestamp":"2026-04-15T20:10:00.000Z","reply_to":null,"system":false}}}
+{"event_id":"evt-task3c-clean-2","stream":"branch","branch_id":"main","seq":2,"type":"message.sent","occurred_at":"2026-04-15T20:10:05.000Z","schema_version":1,"actor_agent":"fixture-beta","session_id":"session_task3c_clean","command_id":"cmd_task3c_clean_2","causation_id":"evt-task3c-clean-1","correlation_id":"corr_task3c_clean","payload":{"message":{"id":"msg-task3c-clean-2","from":"fixture-beta","to":"fixture-alpha","content":"Fixture clean reply","timestamp":"2026-04-15T20:10:05.000Z","reply_to":"msg-task3c-clean-1","system":false}}}

package/scripts/fixtures/message-replay/corrupt-correction-payload.jsonl

@@ -0,0 +1 @@
+{"event_id":"evt-task3c-corrupt-correction-payload-1","stream":"branch","branch_id":"main","seq":1,"type":"message.corrected","occurred_at":"2026-04-15T20:13:00.000Z","schema_version":1,"actor_agent":"fixture-alpha","session_id":"session_task3c_corrupt_correction_payload","command_id":"cmd_task3c_corrupt_correction_payload_1","causation_id":null,"correlation_id":"corr_task3c_corrupt_correction_payload","payload":{"message_id":"msg-task3c-corrupt-correction-payload-1","content":42}}

package/scripts/fixtures/message-replay/corrupt-jsonl.jsonl

@@ -0,0 +1 @@
+{"event_id":"evt-task3c-corrupt-jsonl-1","stream":"branch","branch_id":"main","seq":1,"type":"message.sent","occurred_at":"2026-04-15T20:11:00.000Z","schema_version":1,"actor_agent":"fixture-alpha","session_id":"session_task3c_corrupt_jsonl","command_id":"cmd_task3c_corrupt_jsonl_1","causation_id":null,"correlation_id":"corr_task3c_corrupt_jsonl","payload":{"message":{"id":"msg-task3c-corrupt-jsonl-1","from":"fixture-alpha","to":"fixture-beta","content":"This line is intentionally malformed","timestamp":"2026-04-15T20:11:00.000Z","reply_to":null,"system":false}}

package/scripts/fixtures/message-replay/corrupt-payload.jsonl

@@ -0,0 +1 @@
+{"event_id":"evt-task3c-corrupt-payload-1","stream":"branch","branch_id":"main","seq":1,"type":"message.sent","occurred_at":"2026-04-15T20:12:00.000Z","schema_version":1,"actor_agent":"fixture-alpha","session_id":"session_task3c_corrupt_payload","command_id":"cmd_task3c_corrupt_payload_1","causation_id":null,"correlation_id":"corr_task3c_corrupt_payload","payload":{"message":"not-an-object"}}

package/scripts/fixtures/message-replay/out-of-order.jsonl

@@ -0,0 +1,2 @@
+{"event_id":"evt-task3c-out-of-order-1","stream":"branch","branch_id":"main","seq":2,"type":"message.sent","occurred_at":"2026-04-15T20:13:05.000Z","schema_version":1,"actor_agent":"fixture-beta","session_id":"session_task3c_out_of_order","command_id":"cmd_task3c_out_of_order_2","causation_id":"evt-task3c-out-of-order-2","correlation_id":"corr_task3c_out_of_order","payload":{"message":{"id":"msg-task3c-out-of-order-2","from":"fixture-beta","to":"fixture-alpha","content":"Second event placed first on purpose","timestamp":"2026-04-15T20:13:05.000Z","reply_to":"msg-task3c-out-of-order-1","system":false}}}
+{"event_id":"evt-task3c-out-of-order-2","stream":"branch","branch_id":"main","seq":1,"type":"message.sent","occurred_at":"2026-04-15T20:13:00.000Z","schema_version":1,"actor_agent":"fixture-alpha","session_id":"session_task3c_out_of_order","command_id":"cmd_task3c_out_of_order_1","causation_id":null,"correlation_id":"corr_task3c_out_of_order","payload":{"message":{"id":"msg-task3c-out-of-order-1","from":"fixture-alpha","to":"fixture-beta","content":"First event placed second on purpose","timestamp":"2026-04-15T20:13:00.000Z","reply_to":null,"system":false}}}

package/scripts/migrate-legacy-to-canonical.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// Migrate a pre-canonical .agent-bridge/ project to the canonical event-stream model.
+//
+// Old projects have legacy projection files (messages.jsonl, history.jsonl) under
+// .agent-bridge/ but no canonical stream at .agent-bridge/runtime/branches/main/events.jsonl.
+// The current canonical layer fail-closes any rebuild on legacy-only state to prevent
+// silent data loss, which makes Clear Messages and several other dashboard actions error
+// out on those projects.
+//
+// This script:
+//   1. Detects the legacy-only condition.
+//   2. Backs up the legacy projections to .agent-bridge/legacy-backup-<timestamp>/.
+//   3. Removes the bare projections so the canonical layer is willing to write.
+//   4. Replays each legacy message through canonicalState.appendMessage() so the canonical
+//      stream is created and projections are rewritten in lockstep.
+//
+// Usage:
+//   node agent-bridge/scripts/migrate-legacy-to-canonical.js [project-path]
+//   node agent-bridge/scripts/migrate-legacy-to-canonical.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');
+const { createCanonicalState } = require('../state/canonical');
+
+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 loadLegacyMessages(dataDir) {
+  const history = readJsonl(path.join(dataDir, 'history.jsonl'));
+  if (history.length > 0) return history;
+  return readJsonl(path.join(dataDir, 'messages.jsonl'));
+}
+
+function backupLegacyProjections(dataDir) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const backupDir = path.join(dataDir, 'legacy-backup-' + stamp);
+  fs.mkdirSync(backupDir, { recursive: true });
+  let copied = 0;
+  for (const fileName of ['messages.jsonl', 'history.jsonl']) {
+    const src = path.join(dataDir, fileName);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(backupDir, fileName));
+      copied++;
+    }
+  }
+  return { backupDir, copied };
+}
+
+function removeLegacyProjections(dataDir) {
+  for (const fileName of ['messages.jsonl', 'history.jsonl']) {
+    const src = path.join(dataDir, fileName);
+    if (fs.existsSync(src)) fs.unlinkSync(src);
+  }
+}
+
+function migrate(projectArg, opts) {
+  const dataDir = resolveDataDir({ cwd: projectArg });
+  const eventFile = path.join(dataDir, 'runtime', 'branches', 'main', 'events.jsonl');
+  const legacyMessages = path.join(dataDir, 'messages.jsonl');
+  const legacyHistory = path.join(dataDir, 'history.jsonl');
+
+  console.log('');
+  console.log('  Let Them Talk — Legacy Migration');
+  console.log('  ================================');
+  console.log('  Project data dir: ' + dataDir);
+  console.log('');
+
+  if (!fs.existsSync(dataDir)) {
+    console.log('  [info] No .agent-bridge/ directory at this path. Nothing to migrate.');
+    return { migrated: 0 };
+  }
+
+  const hasLegacy = fs.existsSync(legacyMessages) || fs.existsSync(legacyHistory);
+  const hasCanonical = fs.existsSync(eventFile);
+
+  if (!hasLegacy && !hasCanonical) {
+    console.log('  [info] No legacy projections and no canonical stream — nothing to do.');
+    return { migrated: 0 };
+  }
+
+  if (hasCanonical && hasLegacy) {
+    console.log('  [info] Both canonical stream and legacy projections exist.');
+    console.log('         Canonical stream wins; legacy projection files will be archived to be safe.');
+    if (opts.dryRun) {
+      console.log('  [dry-run] Would archive legacy projections to .agent-bridge/legacy-backup-<ts>/');
+      return { migrated: 0, archived: true };
+    }
+    const backup = backupLegacyProjections(dataDir);
+    if (backup.copied > 0) {
+      removeLegacyProjections(dataDir);
+      console.log('  [ok] Archived ' + backup.copied + ' legacy projection file(s) to ' + backup.backupDir);
+    }
+    return { migrated: 0, archived: true };
+  }
+
+  if (hasCanonical && !hasLegacy) {
+    console.log('  [info] Canonical event stream already exists and no legacy projections present.');
+    console.log('         Project is already on the canonical schema.');
+    return { migrated: 0 };
+  }
+
+  // Legacy-only — the case the canonical layer refuses to operate on.
+  const messages = loadLegacyMessages(dataDir);
+  console.log('  [info] Legacy-only project detected.');
+  console.log('  [info] Found ' + messages.length + ' legacy message(s) to replay onto branch "main".');
+
+  if (opts.dryRun) {
+    console.log('');
+    console.log('  [dry-run] Would back up legacy projections, then replay messages through the canonical layer.');
+    console.log('  [dry-run] Run again without --dry-run to perform the migration.');
+    return { migrated: 0, dryRun: true, candidate: messages.length };
+  }
+
+  const backup = backupLegacyProjections(dataDir);
+  if (backup.copied > 0) {
+    console.log('  [ok] Archived ' + backup.copied + ' legacy projection file(s) to ' + backup.backupDir);
+  }
+
+  // Remove legacy projections so the canonical layer is willing to (re)build them.
+  removeLegacyProjections(dataDir);
+
+  const canonicalState = createCanonicalState({ dataDir });
+
+  let migrated = 0;
+  let skipped = 0;
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') { skipped++; continue; }
+    if (typeof m.id !== 'string' || !m.id) { skipped++; continue; }
+    try {
+      canonicalState.appendMessage(m, { branch: 'main', actorAgent: m.from || 'system' });
+      migrated++;
+    } catch (e) {
+      skipped++;
+      console.warn('  [warn] Skipped message ' + m.id + ': ' + (e && e.message ? e.message : e));
+    }
+  }
+
+  console.log('');
+  console.log('  [ok] Migrated ' + migrated + '/' + messages.length + ' message(s) onto the canonical event stream.');
+  if (skipped > 0) console.log('  [warn] Skipped ' + skipped + ' message(s) — see warnings above.');
+  console.log('  [ok] Canonical event log: ' + eventFile);
+  console.log('  [info] Original projections are preserved in: ' + backup.backupDir);
+  console.log('');
+  console.log('  You can now use Clear Messages and other dashboard actions on this project.');
+  console.log('');
+
+  return { migrated, skipped, backupDir: backup.backupDir };
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = { dryRun: false };
+  const positional = [];
+  for (const a of args) {
+    if (a === '--dry-run' || a === '-n') opts.dryRun = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else positional.push(a);
+  }
+  opts.project = positional[0] || process.cwd();
+  return opts;
+}
+
+function printUsage() {
+  console.log('');
+  console.log('  migrate-legacy-to-canonical');
+  console.log('  ===========================');
+  console.log('  Backfills the canonical event stream from legacy projection files so');
+  console.log('  pre-upgrade projects work with the new dashboard control plane.');
+  console.log('');
+  console.log('  Usage:');
+  console.log('    node agent-bridge/scripts/migrate-legacy-to-canonical.js [project-path]');
+  console.log('    node agent-bridge/scripts/migrate-legacy-to-canonical.js --dry-run [project-path]');
+  console.log('');
+  console.log('  project-path defaults to the current working directory.');
+  console.log('');
+}
+
+if (require.main === module) {
+  const opts = parseArgs(process.argv);
+  if (opts.help) { printUsage(); process.exit(0); }
+  try {
+    migrate(opts.project, opts);
+  } catch (e) {
+    console.error('  [error] ' + (e && e.stack ? e.stack : e));
+    process.exit(1);
+  }
+}
+
+module.exports = { migrate };