let-them-talk 5.3.0 → 5.4.1

package/scripts/check-migration-hardening.js

@@ -0,0 +1,300 @@
+#!/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 {
+  CANONICAL_REPLAY_ERROR_CODES,
+  isCanonicalReplayError,
+} = require(path.resolve(__dirname, '..', 'events', 'replay.js'));
+const {
+  createBranchPathResolvers,
+  createCanonicalState,
+} = require(path.resolve(__dirname, '..', 'state', 'canonical.js'));
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const RUNTIME_CONTRACT_PATH = path.join(REPO_ROOT, 'docs', 'architecture', 'runtime-contract.md');
+const RUNTIME_CONTRACT_DISPLAY = 'docs/architecture/runtime-contract.md';
+const HARDENING_DOC_PATH = path.join(REPO_ROOT, 'docs', 'architecture', 'runtime-migration-hardening.md');
+const HARDENING_DOC_DISPLAY = 'docs/architecture/runtime-migration-hardening.md';
+const USAGE = 'Usage: node agent-bridge/scripts/check-migration-hardening.js [--scenario healthy|legacy-projection-without-canonical-log]';
+
+const SCENARIOS = Object.freeze({
+  healthy: 'healthy',
+  legacyProjectionWithoutCanonicalLog: 'legacy-projection-without-canonical-log',
+});
+
+const REQUIRED_RUNTIME_CONTRACT_SNIPPETS = Object.freeze([
+  '- if a compatibility projection exists but its canonical event stream is missing, rebuild and rollback MUST fail explicitly instead of treating the projection as authoritative.',
+  'Migration hardening is not complete until deterministic validation proves both canonical-first rebuild and explicit rejection of legacy-only rollback assumptions. Task 13C freezes that validator-facing slice in `docs/architecture/runtime-migration-hardening.md`.',
+  '- Missing canonical stream with surviving compatibility projections -> fail explicit rebuild/rollback checks instead of promoting the projection back to authority.',
+  '9. compatibility projections are rejected as rollback authority when the corresponding canonical stream is missing.',
+]);
+
+const REQUIRED_HARDENING_DOC_HEADINGS = Object.freeze([
+  '## Cutover invariants',
+  '## Rollback and recovery rules',
+  '## Stale transitional assumptions that stay invalid',
+  '## Guarded runtime slice in current code',
+  '## Validation path',
+]);
+
+const REQUIRED_HARDENING_DOC_SNIPPETS = Object.freeze([
+  'Legacy filenames such as `messages.jsonl`, `history.jsonl`, `tasks.json`, and `workflows.json` are compatibility projections during migration. They are not rollback authority.',
+  'If a compatibility projection exists without its canonical event stream, rebuild and rollback checks MUST fail explicitly instead of silently promoting the projection back to authority.',
+  'Legacy `messages.jsonl` or `history.jsonl` can stand in for a missing canonical branch event log during rebuild',
+  'The second command exits `1` by design. It proves the runtime does not treat surviving compatibility projections as rollback authority when the canonical branch event stream is missing.',
+]);
+
+function fail(lines, exitCode = 1) {
+  fs.writeSync(2, lines.join('\n') + '\n');
+  process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+  if (argv.length === 0) {
+    return { scenario: SCENARIOS.healthy };
+  }
+
+  if (argv.length === 2 && argv[0] === '--scenario') {
+    const scenario = argv[1];
+    const supportedScenarios = Object.values(SCENARIOS);
+    if (!supportedScenarios.includes(scenario)) {
+      fail([
+        `Unknown scenario: ${scenario}`,
+        `Supported scenarios: ${supportedScenarios.join(', ')}`,
+        USAGE,
+      ], 2);
+    }
+
+    return { scenario };
+  }
+
+  fail([USAGE], 2);
+}
+
+function collectHeadings(markdown) {
+  return new Set(
+    markdown
+      .split(/\r?\n/)
+      .map((line) => line.trimEnd())
+      .filter((line) => /^(##|###)\s+/.test(line))
+  );
+}
+
+function readRequiredFile(filePath, displayPath) {
+  if (!fs.existsSync(filePath)) {
+    fail([
+      'Migration hardening validation failed.',
+      `Missing file: ${displayPath}`,
+    ]);
+  }
+
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function expectIncludes(problems, markdown, snippet, label) {
+  if (!markdown.includes(snippet)) {
+    problems.push(`${label} Missing snippet: ${snippet}`);
+  }
+}
+
+function expectHeading(problems, headings, heading, label) {
+  if (!headings.has(heading)) {
+    problems.push(`${label} Missing heading: ${heading}`);
+  }
+}
+
+function toJsonl(messages) {
+  return messages.map((message) => JSON.stringify(message)).join('\n') + (messages.length ? '\n' : '');
+}
+
+function relativeFromDataDir(dataDir, filePath) {
+  return path.relative(dataDir, filePath).split(path.sep).join('/');
+}
+
+function deleteFile(filePath) {
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+}
+
+function validateDocs() {
+  const problems = [];
+  const runtimeContract = readRequiredFile(RUNTIME_CONTRACT_PATH, RUNTIME_CONTRACT_DISPLAY);
+  const hardeningDoc = readRequiredFile(HARDENING_DOC_PATH, HARDENING_DOC_DISPLAY);
+  const hardeningHeadings = collectHeadings(hardeningDoc);
+
+  for (const snippet of REQUIRED_RUNTIME_CONTRACT_SNIPPETS) {
+    expectIncludes(problems, runtimeContract, snippet, `${RUNTIME_CONTRACT_DISPLAY}.`);
+  }
+
+  for (const heading of REQUIRED_HARDENING_DOC_HEADINGS) {
+    expectHeading(problems, hardeningHeadings, heading, `${HARDENING_DOC_DISPLAY}.`);
+  }
+
+  for (const snippet of REQUIRED_HARDENING_DOC_SNIPPETS) {
+    expectIncludes(problems, hardeningDoc, snippet, `${HARDENING_DOC_DISPLAY}.`);
+  }
+
+  return problems;
+}
+
+function runHealthyScenario() {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'letthemtalk-migration-hardening-'));
+  const dataDir = path.join(tempRoot, '.agent-bridge');
+  const branchName = 'feature_migration_guard';
+  const branchPaths = createBranchPathResolvers(dataDir);
+  const canonicalState = createCanonicalState({ dataDir, processPid: 4545 });
+  const canonicalEventLog = createCanonicalEventLog({ dataDir });
+  const message = {
+    id: 'msg-migration-guard-1',
+    from: 'alpha',
+    to: 'beta',
+    content: 'Migration guard baseline',
+    timestamp: '2026-04-16T23:40:00.000Z',
+    reply_to: null,
+    system: false,
+  };
+  const expectedJsonl = toJsonl([message]);
+  const problems = [];
+
+  try {
+    canonicalState.appendMessage(message, { branch: branchName });
+
+    const targets = branchPaths.getMessageTargets(branchName);
+    const eventFile = canonicalEventLog.getBranchEventsFile(branchName);
+    const eventFileRelative = relativeFromDataDir(dataDir, eventFile);
+    const messageFileRelative = relativeFromDataDir(dataDir, targets.messageFile);
+    const historyFileRelative = relativeFromDataDir(dataDir, targets.historyFile);
+
+    if (!fs.existsSync(eventFile)) {
+      problems.push(`Missing canonical branch event file: ${eventFileRelative}`);
+    }
+    if (!fs.existsSync(targets.messageFile)) {
+      problems.push(`Missing compatibility message projection: ${messageFileRelative}`);
+    }
+    if (!fs.existsSync(targets.historyFile)) {
+      problems.push(`Missing compatibility history projection: ${historyFileRelative}`);
+    }
+    if (eventFileRelative !== `runtime/branches/${branchName}/events.jsonl`) {
+      problems.push(`Canonical message events should live under runtime/branches/<branch>/events.jsonl. Actual: ${eventFileRelative}`);
+    }
+    if (messageFileRelative !== `branch-${branchName}-messages.jsonl`) {
+      problems.push(`Compatibility message projection path drifted. Actual: ${messageFileRelative}`);
+    }
+    if (historyFileRelative !== `branch-${branchName}-history.jsonl`) {
+      problems.push(`Compatibility history projection path drifted. Actual: ${historyFileRelative}`);
+    }
+
+    const canonicalBeforeRebuild = fs.readFileSync(eventFile, 'utf8');
+    deleteFile(targets.messageFile);
+    deleteFile(targets.historyFile);
+    canonicalState.rebuildMessageProjections({ branch: branchName });
+    const canonicalAfterRebuild = fs.readFileSync(eventFile, 'utf8');
+
+    if (canonicalBeforeRebuild !== canonicalAfterRebuild) {
+      problems.push('Projection rebuild mutated the canonical event log instead of treating it as read-only authority.');
+    }
+    if (fs.readFileSync(targets.messageFile, 'utf8') !== expectedJsonl) {
+      problems.push('Compatibility messages.jsonl projection did not rebuild deterministically from canonical events.');
+    }
+    if (fs.readFileSync(targets.historyFile, 'utf8') !== expectedJsonl) {
+      problems.push('Compatibility history.jsonl projection did not rebuild deterministically from canonical events.');
+    }
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+
+  return problems;
+}
+
+function runLegacyProjectionWithoutCanonicalLogScenario() {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'letthemtalk-migration-legacy-only-'));
+  const dataDir = path.join(tempRoot, '.agent-bridge');
+  const branchName = 'feature_migration_guard';
+  const branchPaths = createBranchPathResolvers(dataDir);
+  const canonicalState = createCanonicalState({ dataDir, processPid: 4646 });
+  const targets = branchPaths.getMessageTargets(branchName);
+
+  try {
+    fs.mkdirSync(path.dirname(targets.messageFile), { recursive: true });
+    fs.writeFileSync(targets.messageFile, '{"id":"legacy-only-message"}\n');
+    fs.writeFileSync(targets.historyFile, '{"id":"legacy-only-message"}\n');
+
+    try {
+      canonicalState.rebuildMessageProjections({ branch: branchName });
+      fail([
+        'Migration hardening validation failed.',
+        `Scenario: ${SCENARIOS.legacyProjectionWithoutCanonicalLog}`,
+        'Expected rebuild to reject the legacy-only projection fixture, but it succeeded.',
+      ]);
+    } catch (error) {
+      if (!isCanonicalReplayError(error) || error.code !== CANONICAL_REPLAY_ERROR_CODES.MISSING_CANONICAL_STREAM) {
+        fail([
+          'Migration hardening validation failed.',
+          `Scenario: ${SCENARIOS.legacyProjectionWithoutCanonicalLog}`,
+          `Expected replay error code: ${CANONICAL_REPLAY_ERROR_CODES.MISSING_CANONICAL_STREAM}`,
+          `Actual error code: ${error && error.code ? error.code : 'unknown'}`,
+          `Actual error message: ${error && error.message ? error.message : String(error)}`,
+        ]);
+      }
+
+      if (!String(error.message).includes('legacy-only recovery')
+        || !String(error.message).includes('compatibility projections still exist')) {
+        fail([
+          'Migration hardening validation failed.',
+          `Scenario: ${SCENARIOS.legacyProjectionWithoutCanonicalLog}`,
+          'Expected the rejection message to explain the legacy-only rebuild guard clearly.',
+          `Actual error message: ${error.message}`,
+        ]);
+      }
+
+      fail([
+        'Migration hardening rejected legacy-only rebuild fixture.',
+        `Scenario: ${SCENARIOS.legacyProjectionWithoutCanonicalLog}`,
+        `Replay error code: ${error.code}`,
+        `Replay error message: ${error.message}`,
+      ]);
+    }
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function main() {
+  const { scenario } = parseArgs(process.argv.slice(2));
+  const docProblems = validateDocs();
+
+  if (docProblems.length > 0) {
+    fail([
+      'Migration hardening validation failed.',
+      ...docProblems.map((problem) => `- ${problem}`),
+    ]);
+  }
+
+  if (scenario === SCENARIOS.legacyProjectionWithoutCanonicalLog) {
+    runLegacyProjectionWithoutCanonicalLogScenario();
+    return;
+  }
+
+  const healthyProblems = runHealthyScenario();
+  if (healthyProblems.length > 0) {
+    fail([
+      'Migration hardening validation failed.',
+      `Scenario: ${SCENARIOS.healthy}`,
+      ...healthyProblems.map((problem) => `- ${problem}`),
+    ]);
+  }
+
+  console.log([
+    'Migration hardening validation passed.',
+    `Checked file: ${RUNTIME_CONTRACT_DISPLAY}`,
+    `Checked file: ${HARDENING_DOC_DISPLAY}`,
+    'Validated canonical-first rebuild from branch-local event streams, read-only canonical rollback behavior, and explicit rejection of legacy-only projection authority.',
+  ].join('\n'));
+}
+
+main();

package/scripts/check-performance-indexing.js

@@ -0,0 +1,272 @@
+#!/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 { createCanonicalState, 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 assert(condition, message, problems) {
+  if (!condition) problems.push(message);
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+}
+
+function normalizeTarget(filePath) {
+  return typeof filePath === 'string' ? path.resolve(filePath) : filePath;
+}
+
+function withBlockedReadFileSync(blockedFiles, fn) {
+  const blocked = new Set(blockedFiles.map(normalizeTarget));
+  const originalReadFileSync = fs.readFileSync;
+
+  fs.readFileSync = function patchedReadFileSync(filePath, ...args) {
+    if (blocked.has(normalizeTarget(filePath))) {
+      throw new Error(`Blocked readFileSync for hot-path validation: ${filePath}`);
+    }
+    return originalReadFileSync.call(this, filePath, ...args);
+  };
+
+  try {
+    return fn();
+  } finally {
+    fs.readFileSync = originalReadFileSync;
+  }
+}
+
+function withBlockedReaddirSync(blockedDirs, fn) {
+  const blocked = new Set(blockedDirs.map(normalizeTarget));
+  const originalReaddirSync = fs.readdirSync;
+
+  fs.readdirSync = function patchedReaddirSync(dirPath, ...args) {
+    if (blocked.has(normalizeTarget(dirPath))) {
+      throw new Error(`Blocked readdirSync for hot-path validation: ${dirPath}`);
+    }
+    return originalReaddirSync.call(this, dirPath, ...args);
+  };
+
+  try {
+    return fn();
+  } finally {
+    fs.readdirSync = originalReaddirSync;
+  }
+}
+
+function main() {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'letthemtalk-performance-indexing-'));
+  const dataDir = path.join(tempRoot, '.agent-bridge');
+  const branchName = 'feature_perf_index';
+  const secondaryBranchName = 'feature_perf_index_secondary';
+  const problems = [];
+
+  try {
+    const branchPaths = createBranchPathResolvers(dataDir);
+    const io = createStateIo({ dataDir });
+    const eventLog = createCanonicalEventLog({ dataDir });
+    const sessionsState = createSessionsState({ io, branchPaths, canonicalEventLog: eventLog });
+    const canonicalState = createCanonicalState({ dataDir, processPid: process.pid });
+
+    eventLog.appendEvent({
+      type: 'session.started',
+      branchId: branchName,
+      actorAgent: 'alpha',
+      sessionId: 'sess_perf_alpha',
+      occurredAt: '2026-04-16T23:20:00.000Z',
+      payload: {
+        state: 'active',
+        reason: 'validator_setup',
+      },
+    });
+    const secondEvent = eventLog.appendEvent({
+      type: 'session.resumed',
+      branchId: branchName,
+      actorAgent: 'alpha',
+      sessionId: 'sess_perf_alpha',
+      occurredAt: '2026-04-16T23:20:05.000Z',
+      payload: {
+        state: 'active',
+        reason: 'validator_setup',
+      },
+    });
+
+    const eventFile = eventLog.getBranchEventsFile(branchName);
+    const headFile = eventLog.getBranchEventsHeadFile(branchName);
+    fs.unlinkSync(headFile);
+
+    const coldHeadLog = createCanonicalEventLog({ dataDir });
+    let repairedHead = null;
+    withBlockedReadFileSync([eventFile], () => {
+      repairedHead = coldHeadLog.getEventsHead({
+        stream: 'branch',
+        branchId: branchName,
+        at: '2026-04-16T23:20:06.000Z',
+      });
+    });
+
+    assert(repairedHead && repairedHead.last_seq === secondEvent.seq, 'Event heads should rebuild from the stream tail without a full event-file read when the head is missing.', problems);
+    assert(repairedHead && repairedHead.event_count === secondEvent.seq, 'Tail-repaired event heads should preserve the monotonic branch event count.', problems);
+
+    fs.unlinkSync(headFile);
+    const coldAppendLog = createCanonicalEventLog({ dataDir });
+    let thirdEvent = null;
+    withBlockedReadFileSync([eventFile], () => {
+      thirdEvent = coldAppendLog.appendEvent({
+        type: 'session.completed',
+        branchId: branchName,
+        actorAgent: 'alpha',
+        sessionId: 'sess_perf_alpha',
+        occurredAt: '2026-04-16T23:20:10.000Z',
+        payload: {
+          state: 'completed',
+          reason: 'validator_setup',
+        },
+      });
+    });
+    assert(thirdEvent && thirdEvent.seq === secondEvent.seq + 1, 'Event append should derive the next seq from tail/head metadata without rescanning the branch log.', problems);
+
+    const generalMessage = {
+      id: 'msg_perf_general',
+      from: 'alpha',
+      to: 'beta',
+      content: 'General projection baseline',
+      timestamp: '2026-04-16T23:21:00.000Z',
+    };
+    const labMessage = {
+      id: 'msg_perf_lab',
+      from: 'beta',
+      to: 'alpha',
+      channel: 'lab',
+      content: 'Lab query needle',
+      timestamp: '2026-04-16T23:21:10.000Z',
+    };
+
+    canonicalState.appendMessage(generalMessage, { branch: branchName });
+    canonicalState.appendScopedMessage(labMessage, { branch: branchName, channel: 'lab' });
+    writeJson(branchPaths.getChannelsFile(branchName), {
+      general: {
+        description: 'General channel',
+        members: ['*'],
+      },
+      lab: {
+        description: 'Perf validator lab channel',
+        members: ['alpha', 'beta'],
+      },
+    });
+    writeJson(branchPaths.getAcksFile(branchName), {
+      [generalMessage.id]: true,
+      [labMessage.id]: true,
+    });
+
+    const initialConversation = canonicalState.getConversationMessages({ branch: branchName });
+    const projectionFile = branchPaths.getBranchDashboardProjectionFile(branchName);
+    assert(initialConversation.length === 2, 'Dashboard conversation projection should merge general and non-general branch history.', problems);
+    assert(fs.existsSync(projectionFile), 'Dashboard branch queries should persist a branch-scoped merged-history projection file.', problems);
+
+    const historyFile = branchPaths.getHistoryFile(branchName);
+    const channelHistoryFile = branchPaths.getChannelHistoryFile('lab', branchName);
+    let cachedConversation = null;
+    let cachedChannels = null;
+    let cachedSearch = null;
+    withBlockedReadFileSync([historyFile, channelHistoryFile], () => {
+      cachedConversation = canonicalState.getConversationMessages({ branch: branchName });
+      cachedChannels = canonicalState.getChannelsView({ branch: branchName });
+      cachedSearch = canonicalState.getSearchResultsView({
+        branch: branchName,
+        query: 'query needle',
+        limit: 10,
+      });
+    });
+
+    assert(Array.isArray(cachedConversation) && cachedConversation.length === 2, 'Cached dashboard conversation reads should succeed from the shared projection without rereading branch history files.', problems);
+    assert(cachedChannels && cachedChannels.lab && cachedChannels.lab.message_count === 1, 'Cached dashboard channel queries should preserve branch-local channel counts from the shared projection.', problems);
+    assert(Array.isArray(cachedSearch) && cachedSearch.length === 1 && cachedSearch[0].id === labMessage.id, 'Cached dashboard search should reuse the shared merged projection and stay branch-local.', problems);
+
+    fs.unlinkSync(projectionFile);
+    const rebuiltConversation = canonicalState.getConversationMessages({ branch: branchName });
+    assert(Array.isArray(rebuiltConversation) && rebuiltConversation.length === 2 && fs.existsSync(projectionFile), 'Dashboard query projection should rebuild cleanly when the branch projection file is missing.', problems);
+
+    const activation = sessionsState.activateSession({
+      agentName: 'alpha',
+      branchName,
+      provider: 'claude',
+      reason: 'register',
+      at: '2026-04-16T23:22:00.000Z',
+    });
+    sessionsState.touchSession({
+      sessionId: activation.session.session_id,
+      branchName,
+      at: '2026-04-16T23:22:10.000Z',
+      heartbeat: true,
+    });
+
+    const secondaryActivation = sessionsState.activateSession({
+      agentName: 'alpha',
+      branchName: secondaryBranchName,
+      provider: 'claude',
+      reason: 'branch_switch',
+      at: '2026-04-16T23:22:20.000Z',
+    });
+
+    const indexFile = branchPaths.getSessionsIndexFile();
+    const indexRaw = fs.readFileSync(indexFile, 'utf8');
+    const index = JSON.parse(indexRaw);
+    assert(!indexRaw.includes('\n'), 'Session index writes should stay compact on hot heartbeat/touch paths to reduce churn.', problems);
+    assert(index.by_agent.alpha && index.by_agent.alpha.latest_branch_id === secondaryBranchName, 'Session index should track the latest branch per agent for hot resume lookups.', problems);
+    assert(index.by_agent.alpha && index.by_agent.alpha.active_session_id === secondaryActivation.session.session_id && index.by_agent.alpha.active_branch_id === secondaryBranchName, 'Session index should point agent-level active session metadata at the latest active branch session.', problems);
+    assert(index.by_branch[branchName] && index.by_branch[branchName].latest_by_agent && index.by_branch[branchName].latest_by_agent.alpha === activation.session.session_id, 'Session index should expose the latest session id per branch+agent.', problems);
+    assert(index.by_branch[secondaryBranchName] && index.by_branch[secondaryBranchName].latest_by_agent && index.by_branch[secondaryBranchName].latest_by_agent.alpha === secondaryActivation.session.session_id, 'Session index should expose the latest session id for newly activated secondary branches.', problems);
+
+    sessionsState.transitionSession({
+      sessionId: secondaryActivation.session.session_id,
+      branchName: secondaryBranchName,
+      state: 'interrupted',
+      reason: 'secondary_branch_paused',
+      at: '2026-04-16T23:22:30.000Z',
+    });
+
+    const repointedIndex = JSON.parse(fs.readFileSync(indexFile, 'utf8'));
+    assert(repointedIndex.by_agent.alpha && repointedIndex.by_agent.alpha.active_session_id === activation.session.session_id && repointedIndex.by_agent.alpha.active_branch_id === branchName, 'Session index should repoint the agent active-session pointer to another still-active branch session instead of clearing it.', problems);
+
+    const sessionsDir = branchPaths.getBranchSessionsDir(branchName);
+    let latestSession = null;
+    let latestSummary = null;
+    let exactSummary = null;
+    withBlockedReaddirSync([sessionsDir], () => {
+      latestSession = sessionsState.getLatestSessionForAgent(branchName, 'alpha');
+      latestSummary = sessionsState.getLatestSessionSummaryForAgent(branchName, 'alpha', {
+        indexedAt: '2026-04-16T23:22:15.000Z',
+      });
+      exactSummary = sessionsState.getSessionSummary(activation.session.session_id, branchName, {
+        indexedAt: '2026-04-16T23:22:15.000Z',
+      });
+    });
+
+    assert(latestSession && latestSession.session_id === activation.session.session_id, 'Latest session manifest lookup should resolve from the session index without rescanning the branch sessions directory.', problems);
+    assert(latestSummary && latestSummary.session_id === activation.session.session_id, 'Latest session summary lookup should resolve from the session index hot path.', problems);
+    assert(exactSummary && exactSummary.session_id === activation.session.session_id && exactSummary.last_heartbeat_at === '2026-04-16T23:22:10.000Z', 'Direct session summary lookup should reuse indexed summary state before falling back to the manifest.', problems);
+
+    if (problems.length > 0) {
+      fail(['Performance/indexing validation failed.', ...problems.map((problem) => `- ${problem}`)], 1);
+    }
+
+    console.log([
+      'Performance/indexing validation passed.',
+      'Validated tail-based canonical event-head repair, branch-scoped dashboard query projection reuse/rebuild, and session-index-driven hot lookups with compact touch-path index writes.',
+    ].join('\n'));
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+main();