@cnrai/pave 0.3.35 → 0.3.51

package/test/agent-status-api.test.js

@@ -1,624 +0,0 @@
-/**
- * Tests for Agent Status API (Phase 2 of issue #107: pave agent is a server)
- *
- * Tests cover:
- * - Server routes: GET /agent/status, GET /agent/identity, GET /agent/history
- * - agentContext object creation and lifecycle in pave/index.js
- * - Iteration history ring buffer behavior
- * - Non-agent mode returns 404 for /agent/* routes
- */
-
-'use strict';
-
-const assert = require('assert');
-const fs = require('fs');
-const path = require('path');
-
-// Read source files for static analysis
-const serverSource = fs.readFileSync(
-  path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'server', 'index.js'),
-  'utf8',
-);
-const paveSource = fs.readFileSync(
-  path.join(__dirname, '..', 'index.js'),
-  'utf8',
-);
-
-let passed = 0;
-let failed = 0;
-let total = 0;
-
-function runTest(name, fn) {
-  total++;
-  try {
-    fn();
-    console.log('\u2705 ' + name);
-    passed++;
-  } catch (e) {
-    console.log('\u274c ' + name + ': ' + e.message);
-    failed++;
-  }
-}
-
-function assertContains(src, needle, msg) {
-  assert(src.indexOf(needle) !== -1, (msg || '') + ' — missing: "' + needle + '"');
-}
-
-// =============================================================
-// 1. Server routes: GET /agent/status
-// =============================================================
-
-runTest('server has GET /agent/status route', () => {
-  assertContains(serverSource, 'app.get("/agent/status"', 'should register /agent/status route');
-});
-
-runTest('server /agent/status returns 404 when not in agent mode', () => {
-  // Route uses shared _requireAgentAccess guard which checks !agentContext
-  const routeIdx = serverSource.indexOf('app.get("/agent/status"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 500);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-  // The guard itself checks agentContext and returns 404
-  const guardIdx = serverSource.indexOf('function _requireAgentAccess(');
-  const guardBody = serverSource.substring(guardIdx, guardIdx + 500);
-  assertContains(guardBody, '!agentContext', 'guard should check for agentContext');
-  assertContains(guardBody, '404', 'guard should return 404');
-  assertContains(guardBody, 'Not running as an agent', 'guard should return descriptive error');
-});
-
-runTest('server /agent/status returns name, status, iteration, uptime', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/status"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1200);
-  assertContains(routeBody, 'agentContext.name', 'should include agent name');
-  assertContains(routeBody, 'agentContext.iteration', 'should include iteration count');
-  assertContains(routeBody, 'agentContext.currentTask', 'should include currentTask');
-  assertContains(routeBody, 'uptime', 'should calculate uptime');
-});
-
-runTest('server /agent/status checks runningSessions for busy state', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/status"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1000);
-  assertContains(routeBody, 'runningSessions', 'should check runningSessions for busy state');
-  // Should check the agent's own session only, not any session
-  assertContains(routeBody, 'agentContext.sessionId', 'should use agent session ID');
-  assertContains(routeBody, 'runningSessions.has(agentSessionId)', 'should check agent-specific session');
-});
-
-runTest('server /agent/status includes consecutiveFailures and lastError', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/status"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1200);
-  assertContains(routeBody, 'consecutiveFailures', 'should include consecutiveFailures');
-  assertContains(routeBody, 'lastError', 'should include lastError');
-});
-
-runTest('server /agent/status includes lastActivity timestamp', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/status"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1200);
-  assertContains(routeBody, 'lastActivity', 'should include lastActivity');
-});
-
-// =============================================================
-// 2. Server routes: GET /agent/identity
-// =============================================================
-
-runTest('server has GET /agent/identity route', () => {
-  assertContains(serverSource, 'app.get("/agent/identity"', 'should register /agent/identity route');
-});
-
-runTest('server /agent/identity returns 404 when not in agent mode', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 500);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-});
-
-runTest('server /agent/identity returns name, soulPath, pid, version', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1000);
-  assertContains(routeBody, 'agentContext.name', 'should include agent name');
-  assertContains(routeBody, 'agentContext.soulPath', 'should include soulPath');
-  assertContains(routeBody, 'process.pid', 'should include process PID');
-  assertContains(routeBody, 'VERSION', 'should include server version');
-});
-
-runTest('server /agent/identity includes sleepMs and reinjectInterval', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 800);
-  assertContains(routeBody, 'sleepMs', 'should include sleepMs');
-  assertContains(routeBody, 'reinjectInterval', 'should include reinjectInterval');
-});
-
-runTest('server /agent/identity uses ?? null (not || null) for numeric fields', () => {
-  // sleepMs=0 and reinjectInterval=0 are valid falsy values; || null would
-  // incorrectly coerce them to null. Use ?? null instead.
-  const routeIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1000);
-  assertContains(routeBody, 'agentContext.sleepMs ?? null',
-    'sleepMs should use ?? null to preserve 0');
-  assertContains(routeBody, 'agentContext.reinjectInterval ?? null',
-    'reinjectInterval should use ?? null to preserve 0');
-});
-
-runTest('server /agent/identity includes sessionId', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1000);
-  assertContains(routeBody, 'sessionId', 'should include sessionId');
-});
-
-// =============================================================
-// 3. Server routes: GET /agent/history
-// =============================================================
-
-runTest('server has GET /agent/history route', () => {
-  assertContains(serverSource, 'app.get("/agent/history"', 'should register /agent/history route');
-});
-
-runTest('server /agent/history returns 404 when not in agent mode', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/history"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 500);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-});
-
-runTest('server /agent/history returns history array and totalIterations', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/history"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1000);
-  assertContains(routeBody, 'history', 'should include history array');
-  assertContains(routeBody, 'totalIterations', 'should include totalIterations');
-  assertContains(routeBody, 'agentContext.name', 'should include agent name');
-});
-
-runTest('server /agent/history supports ?limit=N query param', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/history"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1000);
-  assertContains(routeBody, 'req.query.limit', 'should read limit from query params');
-  assertContains(routeBody, '.slice(', 'should slice history for limit');
-});
-
-// =============================================================
-// 4. Server: agentContext wiring
-// =============================================================
-
-runTest('server createServer accepts agentContext option', () => {
-  assertContains(serverSource, 'opts.agentContext', 'should read agentContext from opts');
-});
-
-runTest('server agentContext defaults to null when not provided', () => {
-  assertContains(serverSource, 'opts.agentContext || null', 'should default to null');
-});
-
-runTest('server defines explicit agent routes and a distinct generic /agent route', () => {
-  // Express app.get('/agent') does not match '/agent/status' (exact match),
-  // so route ordering is irrelevant. We only assert that all routes exist.
-  const statusIdx = serverSource.indexOf('app.get("/agent/status"');
-  const identityIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const historyIdx = serverSource.indexOf('app.get("/agent/history"');
-  const genericIdx = serverSource.indexOf('app.get("/agent",');
-  assert(statusIdx > -1, 'should have /agent/status route');
-  assert(identityIdx > -1, 'should have /agent/identity route');
-  assert(historyIdx > -1, 'should have /agent/history route');
-  assert(genericIdx > -1, 'should have generic /agent route');
-});
-
-// =============================================================
-// 5. pave/index.js: agentContext object
-// =============================================================
-
-runTest('pave/index.js creates agentContext object in agent loop', () => {
-  assertContains(paveSource, 'const agentContext = {', 'should create agentContext object');
-});
-
-runTest('pave/index.js agentContext has required fields', () => {
-  const ctxIdx = paveSource.indexOf('const agentContext = {');
-  const ctxBody = paveSource.substring(ctxIdx, ctxIdx + 800);
-  assertContains(ctxBody, 'name:', 'should have name field');
-  assertContains(ctxBody, 'soulPath:', 'should have soulPath field');
-  assertContains(ctxBody, 'sleepMs', 'should have sleepMs field');
-  assertContains(ctxBody, 'reinjectInterval:', 'should have reinjectInterval field');
-  assertContains(ctxBody, 'sessionId:', 'should have sessionId field');
-  assertContains(ctxBody, 'startedAt:', 'should have startedAt field');
-  assertContains(ctxBody, 'iteration:', 'should have iteration field');
-  assertContains(ctxBody, 'state:', 'should have state field');
-  assertContains(ctxBody, 'currentTask:', 'should have currentTask field');
-  assertContains(ctxBody, 'lastActivity:', 'should have lastActivity field');
-  assertContains(ctxBody, 'consecutiveFailures:', 'should have consecutiveFailures field');
-  assertContains(ctxBody, 'lastError:', 'should have lastError field');
-  assertContains(ctxBody, 'history:', 'should have history ring buffer');
-});
-
-runTest('pave/index.js passes agentContext to startServer', () => {
-  // startServer call should include agentContext
-  assertContains(paveSource, 'agentContext })', 'should pass agentContext to startServer');
-});
-
-runTest('pave/index.js AGENT_HISTORY_MAX defines ring buffer size', () => {
-  assertContains(paveSource, 'AGENT_HISTORY_MAX', 'should define AGENT_HISTORY_MAX constant');
-  const maxIdx = paveSource.indexOf('AGENT_HISTORY_MAX = ');
-  const maxLine = paveSource.substring(maxIdx, maxIdx + 40);
-  assert(maxLine.indexOf('20') !== -1, 'ring buffer should have max size of 20');
-});
-
-// =============================================================
-// 6. pave/index.js: agentContext updates in agent loop
-// =============================================================
-
-runTest('pave/index.js updates agentContext at start of each iteration', () => {
-  // At the top of the while(running) loop, iteration and state should be updated
-  const loopIdx = paveSource.indexOf('// Main agent loop');
-  const loopBody = paveSource.substring(loopIdx, loopIdx + 1000);
-  assertContains(loopBody, 'agentContext.iteration = iteration', 'should update iteration');
-  assertContains(loopBody, "agentContext.state = 'working'", 'should set state to working');
-  assertContains(loopBody, 'agentContext.lastActivity', 'should update lastActivity');
-});
-
-runTest('pave/index.js updates agentContext when entering sleep state', () => {
-  // Before sleeping, agentContext should reflect sleeping state
-  const sleepIdx = paveSource.indexOf('// Update agent registry: sleeping');
-  const sleepBody = paveSource.substring(sleepIdx, sleepIdx + 1000);
-  assertContains(sleepBody, "agentContext.state = 'sleeping'", 'should set state to sleeping');
-  assertContains(sleepBody, 'agentContext.currentTask', 'should update currentTask');
-  assertContains(sleepBody, 'agentContext.consecutiveFailures', 'should update consecutiveFailures');
-});
-
-runTest('pave/index.js updates agentContext on circuit breaker trip', () => {
-  const cbIdx = paveSource.indexOf('// Circuit-breaker: stop after MAX_CONSECUTIVE_FAILURES');
-  const cbBody = paveSource.substring(cbIdx, cbIdx + 800);
-  assertContains(cbBody, "agentContext.state = 'error'", 'should set state to error');
-  assertContains(cbBody, 'agentContext.consecutiveFailures', 'should update failures count');
-  assertContains(cbBody, 'agentContext.lastError', 'should update lastError');
-});
-
-runTest('pave/index.js updates agentContext on cleanup/stop', () => {
-  const stopIdx = paveSource.indexOf('// Update agent registry: stopped');
-  const stopBody = paveSource.substring(stopIdx, stopIdx + 500);
-  assertContains(stopBody, "agentContext.state = 'stopped'", 'should set state to stopped');
-  assertContains(stopBody, 'agentContext.iteration', 'should update final iteration');
-});
-
-runTest('pave/index.js updates agentContext.sessionId after compaction', () => {
-  // When auto-compaction switches sessions, agentContext must stay in sync
-  assertContains(paveSource, 'agentContext.sessionId = sessionId; // Keep agent context in sync',
-    'should update agentContext.sessionId after compaction session switch');
-});
-
-runTest('pave/index.js updates agentContext.sessionId after session creation', () => {
-  // After session is resolved (created or resumed), agentContext should be updated
-  assertContains(paveSource, 'agentContext.sessionId = sessionId;',
-    'should update agentContext.sessionId after session is resolved');
-});
-
-// =============================================================
-// 7. pave/index.js: iteration history ring buffer
-// =============================================================
-
-runTest('pave/index.js pushes iteration summaries to history', () => {
-  // Call sites use _pushHistory helper, which internally calls agentContext.history.push
-  assertContains(paveSource, '_pushHistory(', 'should use _pushHistory helper to push to history');
-});
-
-runTest('pave/index.js history entries have required fields', () => {
-  // Check an entry passed to _pushHistory
-  const pushIdx = paveSource.indexOf('_pushHistory({', paveSource.indexOf('Push iteration summary'));
-  const pushBody = paveSource.substring(pushIdx, pushIdx + 300);
-  assertContains(pushBody, 'iteration', 'history entry should have iteration');
-  assertContains(pushBody, 'timestamp:', 'history entry should have timestamp');
-  assertContains(pushBody, 'status:', 'history entry should have status (ok/error)');
-  assertContains(pushBody, 'error:', 'history entry should have error field');
-});
-
-runTest('pave/index.js history enforces ring buffer max size via _pushHistory helper', () => {
-  // The _pushHistory helper should enforce AGENT_HISTORY_MAX
-  const helperIdx = paveSource.indexOf('function _pushHistory(');
-  assert(helperIdx !== -1, 'should have _pushHistory helper');
-  const helperBody = paveSource.substring(helperIdx, helperIdx + 300);
-  assertContains(helperBody, 'AGENT_HISTORY_MAX', 'helper should check against max size');
-  assertContains(helperBody, '.shift()', 'helper should shift oldest entry when full');
-});
-
-runTest('pave/index.js history uses shift() not splice() for ring buffer', () => {
-  const helperIdx = paveSource.indexOf('function _pushHistory(');
-  const helperBody = paveSource.substring(helperIdx, helperIdx + 300);
-  assertContains(helperBody, 'agentContext.history.shift()', 'should use shift() for FIFO eviction');
-});
-
-// =============================================================
-// 8. Server route ordering and Express path matching
-// =============================================================
-
-runTest('server /agent/status route is separate from /agent generic route', () => {
-  // Make sure /agent/status is a distinct route (not served by /agent)
-  assert(serverSource.indexOf('"/agent/status"') !== -1, 'should have quoted /agent/status path');
-  assert(serverSource.indexOf('"/agent/identity"') !== -1, 'should have quoted /agent/identity path');
-  assert(serverSource.indexOf('"/agent/history"') !== -1, 'should have quoted /agent/history path');
-});
-
-runTest('server /agent/status uptime is calculated in seconds', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/status"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 1200);
-  assertContains(routeBody, '/ 1000', 'should divide by 1000 for seconds');
-  assertContains(routeBody, 'Math.floor', 'should floor to integer seconds');
-});
-
-runTest('server /agent/identity uptime is calculated in seconds', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 800);
-  assertContains(routeBody, '/ 1000', 'should divide by 1000 for seconds');
-  assertContains(routeBody, 'Math.floor', 'should floor to integer seconds');
-  // Should compute now once to avoid double Date.now() causing negative uptime
-  assertContains(routeBody, 'const now = Date.now()', 'should compute now once');
-  assertContains(routeBody, 'now - startedAt', 'should use single now variable');
-});
-
-// =============================================================
-// 9. Comment / documentation
-// =============================================================
-
-runTest('server has Phase 2 issue #107 comment', () => {
-  assertContains(serverSource, 'issue #107', 'should reference issue #107');
-  assertContains(serverSource, 'Agent Status API', 'should describe routes as Agent Status API');
-});
-
-// =============================================================
-// 10. Loopback-only access restriction
-// =============================================================
-
-runTest('server has _isLoopback helper function', () => {
-  assertContains(serverSource, 'function _isLoopback(req)', 'should define _isLoopback helper');
-});
-
-runTest('server _isLoopback checks full 127.0.0.0/8 range and IPv6', () => {
-  const helperIdx = serverSource.indexOf('function _isLoopback(req)');
-  const helperBody = serverSource.substring(helperIdx, helperIdx + 500);
-  // Should use req.socket.remoteAddress (not deprecated req.connection)
-  assertContains(helperBody, 'req.socket', 'should use req.socket (not deprecated req.connection)');
-  // Should handle full 127.x.x.x range via startsWith
-  assertContains(helperBody, 'startsWith("127.")', 'should check full 127.0.0.0/8 range');
-  // Should handle IPv6 loopback
-  assertContains(helperBody, '::1', 'should check IPv6 loopback');
-  // Should handle IPv4-mapped IPv6 loopback range
-  assertContains(helperBody, 'startsWith("::ffff:127.")', 'should check IPv4-mapped IPv6 loopback range');
-});
-
-runTest('server /agent/status enforces loopback-only access', () => {
-  // Guard enforces loopback; routes use _requireAgentAccess
-  const routeIdx = serverSource.indexOf('app.get("/agent/status"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 500);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-});
-
-runTest('server /agent/identity enforces loopback-only access', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 500);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-});
-
-runTest('server /agent/history enforces loopback-only access', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/history"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 500);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-});
-
-// =============================================================
-// 10b. Cross-origin protection for agent routes
-// =============================================================
-
-runTest('server has _isLocalOrigin helper function', () => {
-  assertContains(serverSource, 'function _isLocalOrigin(req)',
-    'should have _isLocalOrigin helper');
-});
-
-runTest('server _isLocalOrigin checks Origin header hostname', () => {
-  const helperIdx = serverSource.indexOf('function _isLocalOrigin(');
-  const helperBody = serverSource.substring(helperIdx, helperIdx + 500);
-  assertContains(helperBody, 'req.headers.origin', 'should read Origin header');
-  assertContains(helperBody, 'localhost', 'should allow localhost origin');
-  assertContains(helperBody, '127.0.0.1', 'should allow 127.0.0.1 origin');
-});
-
-runTest('server _isLocalOrigin allows no-Origin requests', () => {
-  const helperIdx = serverSource.indexOf('function _isLocalOrigin(');
-  const helperBody = serverSource.substring(helperIdx, helperIdx + 500);
-  assertContains(helperBody, '!origin', 'should allow requests with no Origin header');
-  assertContains(helperBody, 'return true', 'should return true for same-origin/non-browser');
-});
-
-runTest('server has _requireAgentAccess shared guard', () => {
-  assertContains(serverSource, 'function _requireAgentAccess(',
-    'should have shared guard helper');
-  const guardIdx = serverSource.indexOf('function _requireAgentAccess(');
-  const guardBody = serverSource.substring(guardIdx, guardIdx + 600);
-  assertContains(guardBody, '_isLoopback(req)', 'guard should check loopback');
-  assertContains(guardBody, '_isLocalOrigin(req)', 'guard should check local origin');
-  assertContains(guardBody, '!agentContext', 'guard should check agentContext');
-  assertContains(guardBody, '403', 'guard should return 403');
-  assertContains(guardBody, '404', 'guard should return 404');
-});
-
-runTest('server /agent/status uses shared guard (not inline checks)', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/status"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 300);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-});
-
-runTest('server /agent/identity uses shared guard (not inline checks)', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/identity"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 300);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-});
-
-runTest('server /agent/history uses shared guard (not inline checks)', () => {
-  const routeIdx = serverSource.indexOf('app.get("/agent/history"');
-  const routeBody = serverSource.substring(routeIdx, routeIdx + 300);
-  assertContains(routeBody, '_requireAgentAccess', 'should use shared guard');
-});
-
-// =============================================================
-// 11. const vs var style consistency
-// =============================================================
-
-runTest('pave/index.js uses const for AGENT_HISTORY_MAX', () => {
-  assertContains(paveSource, 'const AGENT_HISTORY_MAX = ', 'should use const for immutable constant');
-});
-
-runTest('pave/index.js uses const for agentContext', () => {
-  assertContains(paveSource, 'const agentContext = {', 'should use const for object (properties are mutated, not binding)');
-});
-
-runTest('pave/index.js uses const for sleepTask', () => {
-  assertContains(paveSource, 'const sleepTask = ', 'sleepTask is never reassigned, should use const');
-});
-
-runTest('pave/index.js has agentContext documentation comment', () => {
-  assertContains(paveSource, 'Agent context: shared mutable',
-    'should document agentContext purpose');
-});
-
-runTest('test file uses process.exitCode not process.exit (runner-safe)', () => {
-  const testSource = fs.readFileSync(path.join(__dirname, 'agent-status-api.test.js'), 'utf8');
-  // Verify the file uses process.exitCode (not process.exit()) for signaling.
-  // We can't use a simple indexOf because comments/strings in this very test
-  // mention "process.exit(" — so we check that process.exitCode is present.
-  assertContains(testSource, 'process.exitCode',
-    'should use process.exitCode for runner-safe failure signaling');
-});
-
-// =============================================================
-// 12. Circuit-breaker records final iteration in history
-// =============================================================
-
-runTest('circuit-breaker pushes history entry before break', () => {
-  // The circuit-breaker block should use _pushHistory helper so /agent/history
-  // includes the final failing iteration that caused the stop.
-  const cbIdx = paveSource.indexOf('consecutiveFailures >= MAX_CONSECUTIVE_FAILURES');
-  assert(cbIdx !== -1, 'should have circuit-breaker check');
-  const breakIdx = paveSource.indexOf('trippedCircuitBreaker = true;', cbIdx);
-  assert(breakIdx !== -1, 'should have trippedCircuitBreaker flag');
-  const cbBlock = paveSource.substring(cbIdx, breakIdx);
-  assertContains(cbBlock, '_pushHistory(', 'should use _pushHistory helper in circuit-breaker block');
-});
-
-runTest('circuit-breaker history entry has circuit-breaker status', () => {
-  const cbIdx = paveSource.indexOf('consecutiveFailures >= MAX_CONSECUTIVE_FAILURES');
-  const breakIdx = paveSource.indexOf('trippedCircuitBreaker = true;', cbIdx);
-  const cbBlock = paveSource.substring(cbIdx, breakIdx);
-  assertContains(cbBlock, "'circuit-breaker'", 'history entry should use circuit-breaker status');
-});
-
-runTest('_pushHistory helper exists and enforces ring buffer max', () => {
-  const helperIdx = paveSource.indexOf('function _pushHistory(');
-  assert(helperIdx !== -1, 'should have _pushHistory helper');
-  const helperBody = paveSource.substring(helperIdx, helperIdx + 300);
-  assertContains(helperBody, 'AGENT_HISTORY_MAX', 'helper should check ring buffer capacity');
-  assertContains(helperBody, 'agentContext.history.shift()', 'helper should evict oldest entry');
-  assertContains(helperBody, 'agentContext.history.push(entry)', 'helper should push entry');
-});
-
-// =============================================================
-// 13. SOUL read failure updates agentContext before sleeping
-// =============================================================
-
-runTest('SOUL read failure path sets agentContext.state to sleeping', () => {
-  // Find the SOUL file read catch block
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  assert(soulReadIdx !== -1, 'should have SOUL read error handler');
-  // Extract a region around the catch block (before the continue)
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, "agentContext.state = 'sleeping'",
-    'should update agentContext.state to sleeping on SOUL read failure');
-});
-
-runTest('SOUL read failure path sets agentContext.currentTask', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, 'agentContext.currentTask',
-    'should update currentTask on SOUL read failure');
-});
-
-runTest('SOUL read failure path sets agentContext.lastError', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, 'agentContext.lastError',
-    'should update lastError on SOUL read failure');
-});
-
-runTest('SOUL read failure path increments consecutiveFailures', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, 'consecutiveFailures++',
-    'should increment consecutiveFailures on SOUL read failure');
-  assertContains(catchBlock, 'agentContext.consecutiveFailures = consecutiveFailures',
-    'should sync agentContext.consecutiveFailures');
-});
-
-runTest('SOUL read failure path applies backoff sleep', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, 'MAX_BACKOFF_MS',
-    'should apply backoff cap on SOUL read failure');
-});
-
-runTest('SOUL read failure sleep wakes on inbox messages', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, 'inboxHasMessages',
-    'should wake on inbox messages during SOUL read backoff (like normal sleep)');
-});
-
-runTest('SOUL read failure path checks circuit-breaker', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, 'MAX_CONSECUTIVE_FAILURES',
-    'should check circuit-breaker threshold on SOUL read failure');
-  assertContains(catchBlock, 'trippedCircuitBreaker = true',
-    'should trip circuit-breaker if threshold reached via SOUL errors');
-});
-
-runTest('SOUL read failure circuit-breaker writes ERROR status to registry', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, 'registry.writeStatus(agentName',
-    'should write status to on-disk registry in SOUL read failure path');
-});
-
-runTest('SOUL read failure non-circuit-breaker writes SLEEPING status to registry', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, 'registry.STATES.SLEEPING',
-    'should write SLEEPING status when not tripping circuit-breaker');
-});
-
-runTest('SOUL read failure path pushes history entry', () => {
-  const soulReadIdx = paveSource.indexOf('Error reading SOUL file at');
-  const continueIdx = paveSource.indexOf('continue;', soulReadIdx);
-  const catchBlock = paveSource.substring(soulReadIdx, continueIdx);
-  assertContains(catchBlock, '_pushHistory(',
-    'should use _pushHistory helper on SOUL read failure');
-});
-
-runTest('all history call-sites use _pushHistory helper (no inline eviction)', () => {
-  // After extracting _pushHistory, there should be no inline ring-buffer
-  // eviction logic remaining — only the helper itself should reference
-  // agentContext.history.shift() and AGENT_HISTORY_MAX together.
-  const helperIdx = paveSource.indexOf('function _pushHistory(');
-  const helperEnd = paveSource.indexOf('}', helperIdx + 50);
-  const afterHelper = paveSource.substring(helperEnd);
-  // No direct shift+push combo should remain outside the helper
-  const shiftCount = (afterHelper.match(/agentContext\.history\.shift\(\)/g) || []).length;
-  assert(shiftCount === 0, 'no inline agentContext.history.shift() calls should remain outside _pushHistory (found ' + shiftCount + ')');
-});
-
-// =============================================================
-// Summary
-// =============================================================
-
-console.log('');
-console.log('Total: ' + total + ', Passed: ' + passed + ', Failed: ' + failed);
-if (failed > 0) {
-  process.exitCode = 1;
-}