let-them-talk 5.3.0 → 5.4.0

package/scripts/check-provider-capabilities.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { ApiAgentEngine } = require(path.resolve(__dirname, '..', 'api-agents.js'));
+const {
+  inferApiAgentCapabilities,
+  resolveAgentRuntimeMetadata,
+  validateExplicitRuntimeDescriptor,
+} = require(path.resolve(__dirname, '..', 'runtime-descriptor.js'));
+
+function fail(lines, exitCode = 1) {
+  process.stderr.write(lines.join('\n') + '\n');
+  process.exit(exitCode);
+}
+
+function assert(condition, message, problems) {
+  if (!condition) problems.push(message);
+}
+
+function readJson(filePath, fallback) {
+  if (!fs.existsSync(filePath)) return fallback;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function getExplicitDescriptor(record = {}) {
+  return {
+    runtime_type: record.runtime_type,
+    provider_id: record.provider_id,
+    model_id: record.model_id,
+    capabilities: record.capabilities,
+  };
+}
+
+function routeAgentsByExplicitCapability(agentRecords, requiredCapability) {
+  const matched = [];
+  const rejected = [];
+
+  for (const record of agentRecords) {
+    const validation = validateExplicitRuntimeDescriptor(getExplicitDescriptor(record));
+    if (!validation.valid) {
+      rejected.push({
+        name: record && record.name ? record.name : '<unknown>',
+        errors: validation.errors,
+      });
+      continue;
+    }
+
+    if (validation.normalized.capabilities.includes(requiredCapability)) {
+      matched.push(record.name);
+    }
+  }
+
+  matched.sort();
+  rejected.sort((left, right) => String(left.name).localeCompare(String(right.name)));
+  return { matched, rejected };
+}
+
+function createFixtureDataDir() {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ltt-provider-capabilities-'));
+  const dataDir = path.join(tempRoot, '.agent-bridge');
+  fs.mkdirSync(dataDir, { recursive: true });
+  return { tempRoot, dataDir };
+}
+
+function removeFixture(tempRoot) {
+  try {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  } catch {}
+}
+
+function main() {
+  const problems = [];
+  const fixture = createFixtureDataDir();
+
+  try {
+    const engine = new ApiAgentEngine(fixture.dataDir);
+
+    const createResults = [
+      engine.create('vision_bot', 'zai', { model: 'glm-4.6v' }),
+      engine.create('video_bot', 'comfyui', { model: 'wan_i2v' }),
+      engine.create('image_bot', 'gemini', { model: 'gemini-3-pro-image-preview' }),
+      engine.create('gemini_vid_override', 'gemini', {
+        model: 'gemini-3-pro-image-preview',
+        capabilities: ['video_generation'],
+      }),
+      engine.create('ollama_tex_override', 'ollama', {
+        model: 'llava:34b',
+        capabilities: ['texture_generation'],
+      }),
+      engine.create('zai_chat_override', 'zai', {
+        model: 'glm-image',
+        capabilities: ['chat'],
+      }),
+    ];
+
+    createResults.forEach((result, index) => {
+      assert(result && result.ok, `API agent create() should succeed for fixture agent ${index + 1}.`, problems);
+    });
+
+    const agentsFile = path.join(fixture.dataDir, 'agents.json');
+    const agents = readJson(agentsFile, {});
+    const listedAgents = engine.list();
+
+    const expectedAgents = [
+      {
+        name: 'vision_bot',
+        provider_id: 'zai',
+        model_id: 'glm-4.6v',
+        capabilities: ['vision', 'chat'],
+        bot_capability: 'vision',
+      },
+      {
+        name: 'video_bot',
+        provider_id: 'comfyui',
+        model_id: 'wan_i2v',
+        capabilities: ['video_generation'],
+        bot_capability: 'video_gen',
+      },
+      {
+        name: 'image_bot',
+        provider_id: 'gemini',
+        model_id: 'gemini-3-pro-image-preview',
+        capabilities: ['image_generation'],
+        bot_capability: 'image_gen',
+      },
+      {
+        name: 'gemini_vid_override',
+        provider_id: 'gemini',
+        model_id: 'gemini-3-pro-image-preview',
+        capabilities: ['video_generation'],
+        bot_capability: 'video_gen',
+      },
+      {
+        name: 'ollama_tex_override',
+        provider_id: 'ollama',
+        model_id: 'llava:34b',
+        capabilities: ['texture_generation'],
+        bot_capability: 'texture_gen',
+      },
+      {
+        name: 'zai_chat_override',
+        provider_id: 'zai',
+        model_id: 'glm-image',
+        capabilities: ['chat'],
+        bot_capability: 'chat',
+      },
+    ];
+
+    for (const expected of expectedAgents) {
+      const stored = agents[expected.name] || {};
+      const listed = listedAgents.find((entry) => entry.name === expected.name) || {};
+      const validation = validateExplicitRuntimeDescriptor({
+        runtime_type: stored.runtime_type,
+        provider_id: stored.provider_id,
+        model_id: stored.model_id,
+        capabilities: stored.capabilities,
+      });
+
+      assert(validation.valid, `Stored descriptor for ${expected.name} should validate: ${validation.errors.join('; ')}`, problems);
+      assert(stored.runtime_type === 'api', `${expected.name} should store runtime_type="api".`, problems);
+      assert(stored.provider_id === expected.provider_id, `${expected.name} should store provider_id="${expected.provider_id}".`, problems);
+      assert(stored.model_id === expected.model_id, `${expected.name} should store model_id="${expected.model_id}".`, problems);
+      assert(JSON.stringify(stored.capabilities || []) === JSON.stringify(expected.capabilities), `${expected.name} should store capabilities ${JSON.stringify(expected.capabilities)}.`, problems);
+      assert(stored.provider === expected.provider_id, `${expected.name} should project legacy provider from provider_id.`, problems);
+      assert(typeof stored.provider_color === 'string' && stored.provider_color.length > 0, `${expected.name} should project a legacy provider_color.`, problems);
+      assert(stored.bot_capability === expected.bot_capability, `${expected.name} should project legacy bot_capability="${expected.bot_capability}".`, problems);
+
+      assert(listed.runtime_type === 'api', `engine.list() should expose runtime_type for ${expected.name}.`, problems);
+      assert(listed.provider_id === expected.provider_id, `engine.list() should expose provider_id for ${expected.name}.`, problems);
+      assert(listed.model_id === expected.model_id, `engine.list() should expose model_id for ${expected.name}.`, problems);
+      assert(JSON.stringify(listed.capabilities || []) === JSON.stringify(expected.capabilities), `engine.list() should expose capabilities for ${expected.name}.`, problems);
+      assert(listed.bot_capability === expected.bot_capability, `engine.list() should expose projected bot_capability for ${expected.name}.`, problems);
+    }
+
+    const heuristicOverrideFixtures = expectedAgents.filter((expected) => (
+      expected.name === 'gemini_vid_override'
+      || expected.name === 'ollama_tex_override'
+      || expected.name === 'zai_chat_override'
+    ));
+
+    for (const expected of heuristicOverrideFixtures) {
+      const heuristicCapabilities = inferApiAgentCapabilities({
+        name: expected.name,
+        provider_id: expected.provider_id,
+        model_id: expected.model_id,
+      });
+      assert(
+        !sameJson(heuristicCapabilities, expected.capabilities),
+        `${expected.name} fixture should differ from provider/model heuristics so the validator proves explicit capability routing.`,
+        problems
+      );
+    }
+
+    const videoRoute = routeAgentsByExplicitCapability(listedAgents, 'video_generation');
+    const textureRoute = routeAgentsByExplicitCapability(listedAgents, 'texture_generation');
+    const imageRoute = routeAgentsByExplicitCapability(listedAgents, 'image_generation');
+    const chatRoute = routeAgentsByExplicitCapability(listedAgents, 'chat');
+    const visionRoute = routeAgentsByExplicitCapability(listedAgents, 'vision');
+
+    assert(sameJson(videoRoute.matched, ['gemini_vid_override', 'video_bot']), 'Explicit video-generation routing should select only the mixed-provider agents whose explicit capabilities include video_generation.', problems);
+    assert(sameJson(textureRoute.matched, ['ollama_tex_override']), 'Explicit texture-generation routing should select the capability override even when provider/model heuristics would not.', problems);
+    assert(sameJson(imageRoute.matched, ['image_bot']), 'Explicit image-generation routing should exclude agents whose providers/models look image-capable but whose explicit capabilities say otherwise.', problems);
+    assert(sameJson(chatRoute.matched, ['vision_bot', 'zai_chat_override']), 'Explicit chat routing should include only agents whose explicit capabilities expose chat.', problems);
+    assert(sameJson(visionRoute.matched, ['vision_bot']), 'Explicit vision routing should not silently route to provider/model heuristic matches without explicit vision capability metadata.', problems);
+    assert(videoRoute.rejected.length === 0 && textureRoute.rejected.length === 0 && imageRoute.rejected.length === 0 && chatRoute.rejected.length === 0 && visionRoute.rejected.length === 0, 'Valid API-agent rows should not be rejected by strict explicit-capability routing.', problems);
+
+    const explicitPreferred = resolveAgentRuntimeMetadata({
+      name: 'explicit_preferred',
+      is_api_agent: true,
+      runtime_type: 'api',
+      provider_id: 'zai',
+      model_id: 'glm-image',
+      capabilities: ['image_generation'],
+      provider: 'legacy-provider-should-not-win',
+      bot_capability: 'chat',
+    });
+    assert(explicitPreferred.provider === 'zai', 'Explicit provider_id should override stale legacy provider projection.', problems);
+    assert(explicitPreferred.bot_capability === 'image_gen', 'Explicit capabilities should override stale legacy bot_capability.', problems);
+
+    const legacyFallback = resolveAgentRuntimeMetadata({
+      name: 'legacy_wan_worker',
+      is_api_agent: true,
+      provider: 'comfyui',
+    });
+    assert(JSON.stringify(legacyFallback.capabilities || []) === JSON.stringify(['video_generation']), 'Legacy API-agent fallback should infer video_generation from provider/name hints.', problems);
+    assert(legacyFallback.bot_capability === 'video_gen', 'Legacy API-agent fallback should still project legacy bot_capability.', problems);
+
+    const missingCapabilityMetadata = validateExplicitRuntimeDescriptor({
+      runtime_type: 'api',
+      provider_id: 'zai',
+      model_id: 'glm-image',
+    });
+    assert(!missingCapabilityMetadata.valid, 'Descriptor validation should fail closed when capabilities metadata is absent entirely.', problems);
+
+    const missingCapabilities = validateExplicitRuntimeDescriptor({
+      runtime_type: 'api',
+      provider_id: 'zai',
+      model_id: 'glm-5',
+      capabilities: [],
+    });
+    assert(!missingCapabilities.valid, 'Descriptor validation should fail closed when capabilities are missing.', problems);
+
+    const invalidCapability = validateExplicitRuntimeDescriptor({
+      runtime_type: 'api',
+      provider_id: 'zai',
+      model_id: 'glm-5',
+      capabilities: ['telepathy'],
+    });
+    assert(!invalidCapability.valid, 'Descriptor validation should reject unsupported capability tokens.', problems);
+
+    const staleCompatibilityFixtures = [
+      {
+        name: 'missing_caps_fixture',
+        runtime_type: 'api',
+        provider_id: 'zai',
+        model_id: 'glm-image',
+        capabilities: null,
+        provider: 'zai',
+        bot_capability: 'image_gen',
+      },
+      {
+        name: 'invalid_caps_fixture',
+        runtime_type: 'api',
+        provider_id: 'gemini',
+        model_id: 'gemini-3-pro-image-preview',
+        capabilities: ['telepathy'],
+        provider: 'gemini',
+        bot_capability: 'image_gen',
+      },
+    ];
+
+    for (const fixtureAgent of staleCompatibilityFixtures) {
+      const compatibilityProjection = resolveAgentRuntimeMetadata(fixtureAgent);
+      assert(
+        Array.isArray(compatibilityProjection.capabilities) && compatibilityProjection.capabilities.includes('image_generation'),
+        `${fixtureAgent.name} should remain inferable through the compatibility resolver so the strict router proves it is failing closed instead of using fallback heuristics.`,
+        problems
+      );
+    }
+
+    const strictImageRouteWithStaleRows = routeAgentsByExplicitCapability(
+      listedAgents.concat(staleCompatibilityFixtures),
+      'image_generation'
+    );
+    assert(sameJson(strictImageRouteWithStaleRows.matched, ['image_bot']), 'Strict explicit-capability routing should still select only explicitly valid image agents when stale fallback-only rows are present.', problems);
+    assert(strictImageRouteWithStaleRows.rejected.some((entry) => entry.name === 'missing_caps_fixture'), 'Strict explicit-capability routing should reject rows with missing capability metadata instead of inferring from legacy fields.', problems);
+    assert(strictImageRouteWithStaleRows.rejected.some((entry) => entry.name === 'invalid_caps_fixture'), 'Strict explicit-capability routing should reject rows with invalid capability metadata instead of inferring from provider/model hints.', problems);
+  } finally {
+    removeFixture(fixture.tempRoot);
+  }
+
+  if (problems.length > 0) {
+    fail([
+      'Provider capability validation failed.',
+      ...problems.map((problem) => `- ${problem}`),
+    ]);
+  }
+
+  console.log([
+    'Provider capability validation passed.',
+    '- API agent descriptors are stored explicitly with runtime_type/provider_id/model_id/capabilities.',
+    '- Mixed-provider routing fixtures prove explicit capabilities win even when provider/model heuristics disagree.',
+    '- Strict explicit-capability routing rejects missing/invalid metadata instead of silently using compatibility fallbacks.',
+    '- Legacy provider/provider_color/bot_capability projections still resolve from the shared descriptor helper.',
+    '- Older API-agent rows still fall back through the centralized compatibility inference path.',
+  ].join('\n'));
+}
+
+main();

package/scripts/check-runtime-contract.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const CONTRACT_PATH = path.resolve(__dirname, '..', '..', 'docs', 'architecture', 'runtime-contract.md');
+const CONTRACT_DISPLAY_PATH = 'docs/architecture/runtime-contract.md';
+const USAGE = 'Usage: node agent-bridge/scripts/check-runtime-contract.js [--simulate-missing <section-key>]';
+
+const REQUIRED_SECTIONS = [
+  { key: 'authority_boundaries', heading: '## Authority boundaries' },
+  { key: 'canonical_writer_rule', heading: '### 1. Canonical writer rule' },
+  { key: 'storage_model', heading: '## Storage model' },
+  { key: 'event_command_model', heading: '## Event / command model' },
+  { key: 'required_event_envelope', heading: '### 3. Required event envelope' },
+  { key: 'evidence_model', heading: '### 5. Evidence-backed completion semantics' },
+  { key: 'branch_semantics', heading: '## Branching / isolation semantics' },
+  { key: 'session_scope', heading: '### 5. Session scope / resumption semantics' },
+  { key: 'versioning_migration', heading: '## Versioning / migration / compatibility' },
+  { key: 'migration_policy', heading: '### 4. Migration policy' },
+];
+
+function fail(message, exitCode) {
+  console.error(message);
+  process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+  if (argv.length === 0) {
+    return { simulateMissingKey: null };
+  }
+
+  if (argv.length === 2 && argv[0] === '--simulate-missing') {
+    const simulateMissingKey = argv[1];
+    const supportedKeys = REQUIRED_SECTIONS.map((section) => section.key);
+
+    if (!supportedKeys.includes(simulateMissingKey)) {
+      fail(
+        [
+          `Unknown section key for --simulate-missing: ${simulateMissingKey}`,
+          `Supported keys: ${supportedKeys.join(', ')}`,
+          USAGE,
+        ].join('\n'),
+        2
+      );
+    }
+
+    return { simulateMissingKey };
+  }
+
+  fail(USAGE, 2);
+}
+
+function collectHeadings(markdown) {
+  return new Set(
+    markdown
+      .split(/\r?\n/)
+      .map((line) => line.trimEnd())
+      .filter((line) => /^(##|###)\s+/.test(line))
+  );
+}
+
+function main() {
+  const { simulateMissingKey } = parseArgs(process.argv.slice(2));
+
+  if (!fs.existsSync(CONTRACT_PATH)) {
+    fail(`Runtime contract validation failed.\nMissing file: ${CONTRACT_DISPLAY_PATH}`, 1);
+  }
+
+  const markdown = fs.readFileSync(CONTRACT_PATH, 'utf8');
+  const headings = collectHeadings(markdown);
+  const missingSections = REQUIRED_SECTIONS.filter((section) => {
+    if (section.key === simulateMissingKey) {
+      return true;
+    }
+
+    return !headings.has(section.heading);
+  });
+
+  if (missingSections.length > 0) {
+    const lines = ['Runtime contract validation failed.', `Checked file: ${CONTRACT_DISPLAY_PATH}`];
+
+    if (simulateMissingKey) {
+      lines.push(`Simulated missing section key: ${simulateMissingKey}`);
+    }
+
+    lines.push('Missing required contract sections:');
+
+    for (const section of missingSections) {
+      lines.push(`- ${section.key}: ${section.heading}`);
+    }
+
+    fail(lines.join('\n'), 1);
+  }
+
+  const successLines = [
+    'Runtime contract validation passed.',
+    `Checked file: ${CONTRACT_DISPLAY_PATH}`,
+    `Validated ${REQUIRED_SECTIONS.length} required contract sections.`,
+  ];
+
+  for (const section of REQUIRED_SECTIONS) {
+    successLines.push(`- ${section.key}: ${section.heading}`);
+  }
+
+  console.log(successLines.join('\n'));
+}
+
+main();

package/scripts/check-session-aware-context.js

@@ -0,0 +1,172 @@
+#!/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'));
+
+const SERVER_FILE = path.resolve(__dirname, '..', 'server.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 readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function extractBlock(source, startAnchor, endAnchor) {
+  const startIndex = source.indexOf(startAnchor);
+  if (startIndex === -1) return '';
+  const endIndex = endAnchor ? source.indexOf(endAnchor, startIndex + startAnchor.length) : source.length;
+  if (endIndex === -1) return source.slice(startIndex);
+  return source.slice(startIndex, endIndex);
+}
+
+function countOccurrences(source, needle) {
+  if (!needle) return 0;
+  return source.split(needle).length - 1;
+}
+
+function buildWorkflow() {
+  return {
+    id: 'wf_context',
+    name: 'Session-aware context workflow',
+    status: 'active',
+    created_by: 'alpha',
+    created_at: '2026-04-16T03:20:00.000Z',
+    updated_at: '2026-04-16T03:20:00.000Z',
+    steps: [
+      {
+        id: 1,
+        description: 'Complete the upstream verified step',
+        assignee: 'alpha',
+        depends_on: [],
+        status: 'in_progress',
+        started_at: '2026-04-16T03:20:00.000Z',
+        completed_at: null,
+        notes: '',
+      },
+      {
+        id: 2,
+        description: 'Resume from upstream evidence',
+        assignee: 'alpha',
+        depends_on: [1],
+        status: 'pending',
+        started_at: null,
+        completed_at: null,
+        notes: '',
+      },
+    ],
+  };
+}
+
+function main() {
+  const problems = [];
+  const serverSource = fs.readFileSync(SERVER_FILE, 'utf8');
+  const registerBlock = extractBlock(serverSource, 'function toolRegister(name, provider = null) {', '// Update last_activity timestamp for this agent');
+  const getWorkBlock = extractBlock(serverSource, 'async function toolGetWork(params = {}) {', 'async function toolVerifyAndAdvance(params) {');
+  const getBriefingBlock = extractBlock(serverSource, 'function toolGetBriefing() {', 'function toolLockFile(filePath) {');
+
+  assert(serverSource.includes('function getAuthoritativeSessionSummary(agentName = registeredName, branchName = currentBranch, sessionId = currentSessionId) {'), 'server.js must define getAuthoritativeSessionSummary() for manifest/index-backed resume lookup.', problems);
+  assert(serverSource.includes('function buildAuthoritativeResumeContext(options = {}) {'), 'server.js must define buildAuthoritativeResumeContext() for session/evidence-first context assembly.', problems);
+  assert(serverSource.includes('function collectMessageHandoffContext(messages, branchName = currentBranch) {'), 'server.js must define collectMessageHandoffContext() for evidence-backed message resume context.', problems);
+
+  assert(registerBlock.includes('const recoveryContext = buildAuthoritativeResumeContext({'), 'toolRegister() must assemble recovery context from authoritative session/evidence helpers first.', problems);
+  assert(registerBlock.includes('result.recovery.session_summary = recoveryContext.session_summary;'), 'toolRegister() recovery payload must expose the authoritative session summary.', problems);
+  assert(registerBlock.includes('result.recovery.checkpoint_fallbacks = checkpointFallbacks;'), 'toolRegister() must keep workspace checkpoints as fallback recovery state.', problems);
+  assert(registerBlock.includes('result.recovery.compatibility_hint = compatibilityHint;'), 'toolRegister() must downgrade recovery snapshots to compatibility fallback context instead of replacing the authoritative hint.', problems);
+
+  assert(countOccurrences(getWorkBlock, 'buildAuthoritativeResumeContext({') >= 2, 'toolGetWork() must use authoritative session/evidence context in both the active-step and upcoming-step branches.', problems);
+  assert(countOccurrences(getWorkBlock, 'resume_context: { message_handoffs: messageContext }') >= 2, 'toolGetWork() must enrich both message-return branches with evidence-backed handoff context.', problems);
+  assert(getWorkBlock.includes('Fallback checkpoint (saved ${checkpoint.saved_at})'), 'toolGetWork() active-step branch must keep checkpoints as fallback after authoritative context.', problems);
+  assert(getWorkBlock.includes('checkpoint_fallbacks contains older workspace WIP notes for this workflow if you need compatibility context.'), 'toolGetWork() upcoming-step branch must preserve checkpoint fallback wording after authoritative evidence context.', problems);
+
+  assert(getBriefingBlock.includes('const briefingContext = buildAuthoritativeResumeContext({'), 'toolGetBriefing() must start from authoritative session/evidence context.', problems);
+  assert(getBriefingBlock.includes('...(briefingContext.session_summary ? { session_summary: briefingContext.session_summary } : {}),'), 'toolGetBriefing() must surface the authoritative session summary in its response.', problems);
+  assert(getBriefingBlock.includes('...(Object.keys(resumeContext).length > 0 ? { resume_context: resumeContext } : {}),'), 'toolGetBriefing() must expose resume_context before the heuristic message/task summary fields.', problems);
+  assert(getBriefingBlock.indexOf('session_summary') !== -1 && getBriefingBlock.indexOf('session_summary') < getBriefingBlock.indexOf('recent_messages'), 'toolGetBriefing() must place session_summary before recent_messages in the response assembly.', problems);
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'letthemtalk-session-aware-context-'));
+  const dataDir = path.join(tempRoot, '.agent-bridge');
+  const branchName = 'feature_task5c';
+  const branchPaths = createBranchPathResolvers(dataDir);
+  const io = createStateIo({ dataDir });
+  const eventLog = createCanonicalEventLog({ dataDir });
+  const sessionsState = createSessionsState({ io, branchPaths, canonicalEventLog: eventLog });
+  const canonicalState = createCanonicalState({ dataDir, processPid: 5150 });
+
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(branchPaths.getWorkflowsFile(branchName), JSON.stringify([buildWorkflow()], null, 2));
+
+    const activation = sessionsState.activateSession({
+      agentName: 'alpha',
+      branchName,
+      provider: 'claude',
+      reason: 'register',
+      at: '2026-04-16T03:20:00.000Z',
+    });
+    const sessionSummary = sessionsState.getLatestSessionSummaryForAgent(branchName, 'alpha', {
+      indexedAt: '2026-04-16T03:20:05.000Z',
+    });
+
+    assert(!!sessionSummary, 'sessionsState must be able to project an authoritative session summary for the active branch session.', problems);
+    assert(sessionSummary && sessionSummary.session_id === activation.session.session_id, 'Projected session summary must track the active session manifest id.', problems);
+    assert(sessionSummary && sessionSummary.branch_id === branchName, 'Projected session summary must remain branch-scoped.', problems);
+    assert(sessionSummary && sessionSummary.state === 'active', 'Projected session summary must reflect the active session state.', problems);
+
+    const completion = canonicalState.advanceWorkflow({
+      workflowId: 'wf_context',
+      actor: 'alpha',
+      branch: branchName,
+      sessionId: activation.session.session_id,
+      expectedAssignee: 'alpha',
+      sourceTool: 'verify_and_advance',
+      evidence: {
+        summary: 'Completed the upstream step with evidence',
+        verification: 'Ran the Task 5C deterministic fixture',
+        files_changed: ['agent-bridge/server.js'],
+        confidence: 92,
+      },
+    });
+
+    assert(completion.success, 'canonicalState.advanceWorkflow() must produce evidence-backed workflow context for the Task 5C fixture.', problems);
+    assert(!!completion.evidence_ref, 'advanceWorkflow() must return an evidence reference for the completed upstream step.', problems);
+
+    const projectedEvidence = canonicalState.projectEvidence(branchName, completion.evidence_ref);
+    const workflows = readJson(branchPaths.getWorkflowsFile(branchName));
+    const workflow = workflows.find((entry) => entry.id === 'wf_context');
+    const completedStep = workflow.steps.find((step) => step.id === 1);
+    const activeStep = workflow.steps.find((step) => step.status === 'in_progress');
+
+    assert(!!projectedEvidence, 'canonicalState.projectEvidence() must resolve an evidence reference into the existing verification projection shape.', problems);
+    assert(projectedEvidence && projectedEvidence.evidence_ref && projectedEvidence.evidence_ref.evidence_id === completion.evidence_ref.evidence_id, 'Projected evidence must preserve the evidence reference identity.', problems);
+    assert(projectedEvidence && projectedEvidence.recorded_by_session === activation.session.session_id, 'Projected evidence must retain the recorded_by_session field for resume context.', problems);
+    assert(projectedEvidence && projectedEvidence.summary === 'Completed the upstream step with evidence', 'Projected evidence must preserve the summary text for downstream briefing/work context.', problems);
+    assert(completedStep && completedStep.verification && completedStep.verification.summary === projectedEvidence.summary, 'Workflow step verification projection must stay aligned with projectEvidence() output.', problems);
+    assert(activeStep && activeStep.id === 2, 'Evidence-backed completion fixture must activate the dependency step for downstream prep/resume context.', problems);
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+
+  if (problems.length > 0) {
+    fail(['Session-aware context validation failed.', ...problems.map((problem) => `- ${problem}`)], 1);
+  }
+
+  console.log([
+    'Session-aware context validation passed.',
+    'Validated session summary and evidence projection helpers plus the targeted server seams for get_briefing(), get_work(), and register recovery.',
+  ].join('\n'));
+}
+
+main();