@cnrai/pave 0.3.32 → 0.3.34

package/test/agent-auto-compaction.test.js

@@ -0,0 +1,552 @@
+#!/usr/bin/env node
+/**
+ * Agent auto-compaction tests
+ * Uses functional testing with simulated agent compaction flow
+ * Run with: node test/agent-auto-compaction.test.js
+ */
+
+// ============================================================================
+// Import shared helper with sandbox fallback
+// ============================================================================
+// Try to import from lib/compaction.js first (normal Node execution).
+// Fall back to inline implementation for sandbox environments where the
+// relative require path doesn't work (test files are copied to temp directory).
+let parseModelForCompaction;
+try {
+  const compaction = require('../lib/compaction');
+  parseModelForCompaction = compaction.parseModelForCompaction;
+} catch (e) {
+  // Fallback for sandbox: simplified inline version of lib/compaction.js.
+  // This uses hardcoded defaults (no env var support) since sandbox tests
+  // cannot modify process.env. See lib/compaction.js for the canonical
+  // implementation with full PAVE_COMPACT_MODEL/PAVE_MODEL precedence.
+  const KNOWN_COMPACTION_MODELS = [
+    'claude-opus-4.5',
+    'claude-opus-4.6',
+    'claude-sonnet-4', // Canonical model advertised in CLI help
+    'claude-sonnet-4.5',
+    'claude-sonnet-4.6',
+    'claude-3-5-sonnet-20241022',
+    'claude-3-5-haiku-20241022',
+    'claude-3-opus-20240229',
+    'gpt-4',
+    'gpt-4-turbo',
+    'gpt-3.5-turbo',
+  ];
+  const DEFAULT_PROVIDER_ID = 'github-copilot';
+  const DEFAULT_MODEL_ID = 'claude-opus-4.5';
+
+  parseModelForCompaction = function (model) {
+    let providerID = DEFAULT_PROVIDER_ID;
+    let modelID = DEFAULT_MODEL_ID;
+
+    if (model) {
+      if (model.includes('/')) {
+        const parts = model.split('/');
+        providerID = parts[0];
+        modelID = parts.slice(1).join('/');
+      } else {
+        modelID = model;
+      }
+    }
+
+    const compactionModelID = KNOWN_COMPACTION_MODELS.includes(modelID) ? modelID : DEFAULT_MODEL_ID;
+    return { providerID, modelID, compactionModelID };
+  };
+}
+
+// ============================================================================
+// Test Utilities
+// ============================================================================
+
+function runTest(name, testFn) {
+  try {
+    testFn();
+    console.log(`✅ ${name}`);
+  } catch (error) {
+    console.log(`❌ ${name}: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+function assertEqual(actual, expected, message) {
+  if (actual !== expected) {
+    throw new Error(`${message}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+function assertDeepEqual(actual, expected, message) {
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(`${message}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+// ============================================================================
+// parseModelForCompaction Tests
+// ============================================================================
+
+console.log('Running agent-auto-compaction.test.js...');
+console.log('\n=== parseModelForCompaction Tests ===');
+
+runTest('parseModelForCompaction: should return defaults when model is undefined', () => {
+  const result = parseModelForCompaction(undefined);
+  assertEqual(result.providerID, 'github-copilot', 'providerID');
+  assertEqual(result.modelID, 'claude-opus-4.5', 'modelID');
+  assertEqual(result.compactionModelID, 'claude-opus-4.5', 'compactionModelID');
+});
+
+runTest('parseModelForCompaction: should return defaults when model is empty string', () => {
+  const result = parseModelForCompaction('');
+  assertEqual(result.providerID, 'github-copilot', 'providerID');
+  assertEqual(result.modelID, 'claude-opus-4.5', 'modelID');
+  assertEqual(result.compactionModelID, 'claude-opus-4.5', 'compactionModelID');
+});
+
+runTest('parseModelForCompaction: should parse provider/model format correctly', () => {
+  const result = parseModelForCompaction('github-copilot/claude-sonnet-4');
+  assertEqual(result.providerID, 'github-copilot', 'providerID');
+  assertEqual(result.modelID, 'claude-sonnet-4', 'modelID');
+  assertEqual(result.compactionModelID, 'claude-sonnet-4', 'compactionModelID should use known model directly');
+});
+
+runTest('parseModelForCompaction: should handle model without provider (uses default provider)', () => {
+  const result = parseModelForCompaction('gpt-4');
+  assertEqual(result.providerID, 'github-copilot', 'providerID');
+  assertEqual(result.modelID, 'gpt-4', 'modelID');
+  assertEqual(result.compactionModelID, 'gpt-4', 'compactionModelID should use known model directly');
+});
+
+runTest('parseModelForCompaction: should handle models with multiple slashes', () => {
+  const result = parseModelForCompaction('openai/gpt-4/turbo');
+  assertEqual(result.providerID, 'openai', 'providerID');
+  assertEqual(result.modelID, 'gpt-4/turbo', 'modelID');
+});
+
+runTest('parseModelForCompaction: should fallback to default for unknown models', () => {
+  const result = parseModelForCompaction('github-copilot/some-unknown-model');
+  assertEqual(result.providerID, 'github-copilot', 'providerID');
+  assertEqual(result.modelID, 'some-unknown-model', 'modelID should preserve original');
+  assertEqual(result.compactionModelID, 'claude-opus-4.5', 'compactionModelID should fallback to default');
+});
+
+runTest('parseModelForCompaction: should use known model directly without fallback', () => {
+  const result = parseModelForCompaction('anthropic/gpt-4');
+  assertEqual(result.providerID, 'anthropic', 'providerID');
+  assertEqual(result.modelID, 'gpt-4', 'modelID');
+  assertEqual(result.compactionModelID, 'gpt-4', 'compactionModelID should use known model directly');
+});
+
+// ============================================================================
+// Agent-specific Compaction Flow Simulation
+// ============================================================================
+
+/**
+ * Simulates the agent auto-compaction flow with stubbed httpRequest.
+ * This mirrors the actual logic in handleAgentCommand.
+ */
+async function simulateAgentCompaction(options) {
+  const {
+    httpRequestStub,
+    serverUrl = 'http://localhost:4096',
+    sessionId = 'test-session-123',
+    model = 'github-copilot/claude-sonnet-4',
+    verbose = false,
+    isNewSession = false,
+    iteration = 2,
+    agentName = 'test-agent',
+  } = options;
+
+  const logs = [];
+  const mockLog = (msg) => logs.push(msg);
+
+  // Use shared helper for model parsing (same as production code)
+  const { providerID, modelID, compactionModelID } = parseModelForCompaction(model);
+
+  let currentSessionId = sessionId;
+  let compactionCheck = null;
+  let compactionResult = null;
+  const apiCalls = [];
+  let sessionFileUpdated = false;
+  let newSessionFileContent = null;
+
+  // Skip compaction check on first iteration of new session (same as production)
+  if (!(isNewSession && iteration === 1)) {
+    // Step 1: Check if compaction is needed
+    try {
+      const checkUrl = `${serverUrl}/api/sessions/${currentSessionId}/compaction/check?modelID=${encodeURIComponent(compactionModelID)}`;
+      apiCalls.push({ method: 'GET', url: checkUrl, originalModelID: modelID, compactionModelID });
+      compactionCheck = await httpRequestStub(checkUrl, 'GET');
+    } catch (checkError) {
+      if (verbose) {
+        mockLog(`Compaction check failed: ${checkError.message}`);
+      }
+    }
+  } else {
+    logs.push('[SKIPPED] First iteration of new session - no compaction check');
+  }
+
+  // Step 2: Perform compaction if needed
+  if (compactionCheck && compactionCheck.needed) {
+    const threshold = compactionCheck.usage?.limits?.threshold;
+    if (verbose) {
+      mockLog(`Auto-compaction triggered: ${compactionCheck.totalTokens} > ${threshold} tokens`);
+    }
+
+    try {
+      const compactUrl = `${serverUrl}/api/sessions/${currentSessionId}/compaction/compact`;
+      const compactBody = {
+        title: `Agent Auto-compacted (${agentName}) - ${new Date().toISOString().split('T')[0]}`,
+        auto: true,
+        force: false,
+        model: { providerID, modelID },
+      };
+      apiCalls.push({ method: 'POST', url: compactUrl, body: compactBody });
+      compactionResult = await httpRequestStub(compactUrl, 'POST', compactBody);
+
+      if (compactionResult && compactionResult.success) {
+        const newSessionID = compactionResult.newSessionID;
+        if (!newSessionID || typeof newSessionID !== 'string' || newSessionID.trim() === '') {
+          // Always show this warning (not gated by verbose) - matches production
+          mockLog(`Auto-compaction warning: invalid newSessionID, keeping original session`);
+        } else {
+          const originalTokens = compactionCheck.totalTokens;
+          currentSessionId = newSessionID;
+
+          sessionFileUpdated = true;
+          newSessionFileContent = { sessionId: currentSessionId, agentName };
+
+          // Calculate token savings (same logic as production - no || 0 fallback)
+          const summaryTokens = compactionResult.summaryTokens;
+          const hasSummaryTokens = typeof summaryTokens === 'number';
+          const savedTokens = hasSummaryTokens ? originalTokens - summaryTokens : 0;
+
+          if (verbose) {
+            mockLog(`Auto-compaction completed: switched to session ${currentSessionId}`);
+            if (originalTokens && savedTokens > 0) {
+              mockLog(`Saved ${savedTokens} tokens`);
+            }
+          } else {
+            if (originalTokens && hasSummaryTokens) {
+              mockLog(`Auto-compacted conversation (${originalTokens} → ${summaryTokens} tokens)`);
+            } else {
+              mockLog(`Auto-compacted conversation to new session`);
+            }
+          }
+        }
+      } else {
+        // Always show compaction failure warnings (not gated by verbose)
+        // This matches production behavior in handleAgentCommand
+        mockLog(`Auto-compaction failed: ${compactionResult?.error || 'unknown error'}`);
+      }
+    } catch (compactError) {
+      // Always show compaction failure warnings (not gated by verbose)
+      // This matches production behavior in handleAgentCommand
+      mockLog(`Compaction execution failed: ${compactError.message}`);
+    }
+  }
+
+  return {
+    sessionId: currentSessionId,
+    apiCalls,
+    logs,
+    compactionCheck,
+    compactionResult,
+    sessionFileUpdated,
+    newSessionFileContent,
+  };
+}
+
+async function runAsyncTest(name, testFn) {
+  try {
+    await testFn();
+    console.log(`✅ ${name}`);
+  } catch (error) {
+    console.log(`❌ ${name}: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ============================================================================
+// Agent Integration Tests
+// ============================================================================
+
+async function runAgentIntegrationTests() {
+  console.log('\n=== Agent Compaction Flow Tests ===');
+
+  // Test: Skip compaction check on first iteration of new session
+  await runAsyncTest('Agent: should skip compaction check on first iteration of new session', async () => {
+    let checkCalled = false;
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        checkCalled = true;
+        return { needed: false };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      isNewSession: true,
+      iteration: 1,
+    });
+
+    if (checkCalled) {
+      throw new Error('compaction check should NOT be called on first iteration of new session');
+    }
+    assertEqual(result.apiCalls.length, 0, 'should make 0 API calls');
+    if (!result.logs.some((l) => l.includes('SKIPPED'))) {
+      throw new Error('should log that check was skipped');
+    }
+  });
+
+  // Test: Should check compaction on second iteration of new session
+  await runAsyncTest('Agent: should check compaction on second iteration of new session', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: false, totalTokens: 5000, usage: { limits: { threshold: 100000 } } };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      isNewSession: true,
+      iteration: 2,
+    });
+
+    assertEqual(result.apiCalls.length, 1, 'should make 1 API call');
+    if (!result.apiCalls[0].url.includes('/compaction/check')) {
+      throw new Error('should call compaction check');
+    }
+  });
+
+  // Test: Should check compaction on resumed session (not new)
+  await runAsyncTest('Agent: should check compaction on resumed session', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: false, totalTokens: 50000, usage: { limits: { threshold: 100000 } } };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      isNewSession: false,
+      iteration: 1,
+    });
+
+    assertEqual(result.apiCalls.length, 1, 'should make 1 API call');
+  });
+
+  // Test: Agent session file should include agentName after compaction
+  await runAsyncTest('Agent: session file should include agentName after compaction', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: true, totalTokens: 150000, usage: { limits: { threshold: 100000 } } };
+      }
+      if (url.includes('/compaction/compact')) {
+        return { success: true, newSessionID: 'new-session-456', summaryTokens: 5000 };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      agentName: 'my-agent',
+    });
+
+    assertEqual(result.sessionFileUpdated, true, 'session file should be updated');
+    assertDeepEqual(result.newSessionFileContent, {
+      sessionId: 'new-session-456',
+      agentName: 'my-agent',
+    }, 'session file should include agentName');
+  });
+
+  // Test: Agent compaction title should include agent name
+  await runAsyncTest('Agent: compaction title should include agent name', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: true, totalTokens: 150000, usage: { limits: { threshold: 100000 } } };
+      }
+      if (url.includes('/compaction/compact')) {
+        return { success: true, newSessionID: 'new-session-456', summaryTokens: 5000 };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      agentName: 'my-awesome-agent',
+    });
+
+    assertEqual(result.apiCalls.length, 2, 'should make 2 API calls');
+    const compactBody = result.apiCalls[1].body;
+    if (!compactBody.title.includes('my-awesome-agent')) {
+      throw new Error(`compaction title should include agent name, got: ${compactBody.title}`);
+    }
+    if (!compactBody.title.includes('Agent Auto-compacted')) {
+      throw new Error(`compaction title should include 'Agent Auto-compacted', got: ${compactBody.title}`);
+    }
+  });
+
+  // Test: Uses shared parseModelForCompaction helper with fallback
+  await runAsyncTest('Agent: should use fallback model for unknown models', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: false };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      model: 'custom-provider/unknown-model-xyz',
+      isNewSession: false,
+    });
+
+    const checkUrl = result.apiCalls[0].url;
+    if (checkUrl.includes('unknown-model-xyz')) {
+      throw new Error('should NOT use unknown model in URL');
+    }
+    if (!checkUrl.includes('modelID=claude-opus-4.5')) {
+      throw new Error('should use fallback model claude-opus-4.5 in URL');
+    }
+    assertEqual(result.apiCalls[0].originalModelID, 'unknown-model-xyz', 'should track original model');
+    assertEqual(result.apiCalls[0].compactionModelID, 'claude-opus-4.5', 'should use fallback for compaction');
+  });
+
+  // Test: Dead code fix - hasSummaryTokens check works correctly
+  await runAsyncTest('Agent: should show correct message when summaryTokens is undefined', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: true, totalTokens: 150000, usage: { limits: { threshold: 100000 } } };
+      }
+      if (url.includes('/compaction/compact')) {
+        return { success: true, newSessionID: 'new-session-456' }; // No summaryTokens
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      verbose: false,
+    });
+
+    if (!result.logs.some((l) => l.includes('Auto-compacted conversation to new session'))) {
+      throw new Error(`should show simple message when summaryTokens not available, got: ${result.logs.join(', ')}`);
+    }
+    if (result.logs.some((l) => l.includes('→'))) {
+      throw new Error('should NOT show token counts when summaryTokens not available');
+    }
+  });
+
+  // Test: Should show token counts when summaryTokens is available
+  await runAsyncTest('Agent: should show token counts when summaryTokens is available', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: true, totalTokens: 150000, usage: { limits: { threshold: 100000 } } };
+      }
+      if (url.includes('/compaction/compact')) {
+        return { success: true, newSessionID: 'new-session-456', summaryTokens: 5000 };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      verbose: false,
+    });
+
+    if (!result.logs.some((l) => l.includes('150000') && l.includes('5000'))) {
+      throw new Error(`should show token counts, got logs: ${result.logs.join(', ')}`);
+    }
+  });
+
+  // Test: Non-verbose failure path - compaction fails with error
+  await runAsyncTest('Agent: should always show compaction failure even when verbose is false', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: true, totalTokens: 150000, usage: { limits: { threshold: 100000 } } };
+      }
+      if (url.includes('/compaction/compact')) {
+        return { success: false, error: 'Server error during compaction' };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      verbose: false, // Non-verbose mode
+    });
+
+    // Should always show failure message even without verbose
+    if (!result.logs.some((l) => l.includes('Auto-compaction failed'))) {
+      throw new Error(`should show failure message even in non-verbose mode, got: ${result.logs.join(', ')}`);
+    }
+    if (!result.logs.some((l) => l.includes('Server error during compaction'))) {
+      throw new Error(`should include error details, got: ${result.logs.join(', ')}`);
+    }
+  });
+
+  // Test: Non-verbose failure path - compaction execution throws
+  await runAsyncTest('Agent: should always show execution failure even when verbose is false', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: true, totalTokens: 150000, usage: { limits: { threshold: 100000 } } };
+      }
+      if (url.includes('/compaction/compact')) {
+        throw new Error('Network timeout');
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      verbose: false, // Non-verbose mode
+    });
+
+    // Should always show execution failure message even without verbose
+    if (!result.logs.some((l) => l.includes('Compaction execution failed'))) {
+      throw new Error(`should show execution failure message even in non-verbose mode, got: ${result.logs.join(', ')}`);
+    }
+    if (!result.logs.some((l) => l.includes('Network timeout'))) {
+      throw new Error(`should include error message, got: ${result.logs.join(', ')}`);
+    }
+  });
+
+  // Test: Non-verbose mode - invalid newSessionID warning should always be shown
+  await runAsyncTest('Agent: should always show invalid newSessionID warning even when verbose is false', async () => {
+    const httpRequestStub = async (url, method, body) => {
+      if (url.includes('/compaction/check')) {
+        return { needed: true, totalTokens: 150000, usage: { limits: { threshold: 100000 } } };
+      }
+      if (url.includes('/compaction/compact')) {
+        // Server returns success but with null/invalid newSessionID
+        return { success: true, newSessionID: null };
+      }
+      throw new Error(`Unexpected API call: ${url}`);
+    };
+
+    const result = await simulateAgentCompaction({
+      httpRequestStub,
+      verbose: false, // Non-verbose mode
+    });
+
+    // Should always show invalid session warning even without verbose
+    if (!result.logs.some((l) => l.includes('invalid newSessionID'))) {
+      throw new Error(`should show invalid newSessionID warning even in non-verbose mode, got: ${result.logs.join(', ')}`);
+    }
+    // Should keep original session
+    if (result.sessionFileUpdated) {
+      throw new Error('should not update session file when newSessionID is invalid');
+    }
+  });
+}
+
+// Run tests
+runAgentIntegrationTests().then(() => {
+  console.log('\n✓ Agent auto-compaction tests completed');
+}).catch((err) => {
+  console.error('Agent tests failed:', err.message);
+  process.exitCode = 1;
+});

package/test/agent-comm-abort.test.js

@@ -0,0 +1,95 @@
+// Tests for agent-comm urgent abort behavior and sleep-wake logic
+// Split from abort-stream.test.js per Copilot review to keep test scopes narrow
+
+const fs = require('fs');
+const path = require('path');
+const assert = require('assert');
+
+let passed = 0;
+let failed = 0;
+
+function runTest(name, fn) {
+  try {
+    fn();
+    console.log('\u2705 ' + name);
+    passed++;
+  } catch (e) {
+    console.log('\u274C ' + name + ': ' + e.message);
+    failed++;
+  }
+}
+
+// ============================================================
+// agent-comm.js: urgent abort HTTP wiring
+// ============================================================
+
+runTest('agent-comm: urgent abort uses serverUrl hostname and port', () => {
+  const agentCommSource = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'agent-comm.js'), 'utf8');
+  // Should parse hostname from status.serverUrl
+  assert(agentCommSource.indexOf('status.serverUrl') !== -1,
+    'should reference status.serverUrl for hostname');
+  assert(agentCommSource.indexOf('new URL(status.serverUrl)') !== -1,
+    'should parse serverUrl with URL constructor');
+  // Port should be extracted from serverUrl (not PAVE_PORT env)
+  assert(agentCommSource.indexOf('parsed.port') !== -1,
+    'should extract port from parsed serverUrl');
+});
+
+runTest('agent-comm: urgent success message uses cautious wording', () => {
+  const agentCommSource = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'agent-comm.js'), 'utf8');
+  // Should NOT promise guaranteed abort — the abort POST is best-effort
+  assert(agentCommSource.indexOf('will abort its current task') === -1,
+    'should not promise guaranteed abort (best-effort fire-and-forget)');
+});
+
+runTest('agent-comm: urgent param description uses best-effort wording', () => {
+  const agentCommSource = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'agent-comm.js'), 'utf8');
+  // The urgent parameter description should NOT say "forces immediate processing"
+  assert(agentCommSource.indexOf('forces immediate processing') === -1,
+    'urgent param should not promise forced immediate processing');
+  // Should use best-effort wording
+  assert(agentCommSource.indexOf('best-effort') !== -1,
+    'urgent param should mention best-effort delivery');
+  assert(agentCommSource.indexOf('attempts to abort') !== -1,
+    'urgent param should say it attempts to abort');
+});
+
+// ============================================================
+// pave/index.js: sleep-wake behavior
+// ============================================================
+
+runTest('pave/index.js: SOUL read error sleep does not check inbox', () => {
+  const paveSource = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'pave', 'index.js'), 'utf8');
+  // Find the SOUL read error section
+  const soulErrIdx = paveSource.indexOf('Error reading SOUL file');
+  assert(soulErrIdx !== -1, 'should find SOUL read error handler');
+  const errSection = paveSource.substring(soulErrIdx, soulErrIdx + 400);
+  // The signalAwareSleep in the error path should NOT check inboxHasMessages
+  // to prevent tight loops when SOUL is unreadable + inbox has messages
+  assert(errSection.indexOf('inboxHasMessages') === -1,
+    'SOUL read error sleep should NOT check inbox to prevent tight loop');
+});
+
+runTest('pave/index.js: normal agent sleep wakes on inbox messages', () => {
+  const paveSource = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'pave', 'index.js'), 'utf8');
+  // Find the agent sleep at end of iteration loop — look for the comment we added
+  const sleepCommentIdx = paveSource.indexOf('Wake early from sleep if');
+  assert(sleepCommentIdx !== -1, 'should find sleep comment');
+  const sleepSection = paveSource.substring(sleepCommentIdx, sleepCommentIdx + 600);
+  assert(sleepSection.indexOf('inboxHasMessages') !== -1,
+    'normal agent sleep should check inboxHasMessages to wake promptly');
+  assert(sleepSection.indexOf('hasInterrupt') !== -1,
+    'normal agent sleep should also check interrupt file');
+});
+
+// ============================================================
+// Summary
+// ============================================================
+
+console.log('\nTotal: ' + (passed + failed) + ', Passed: ' + passed + ', Failed: ' + failed);
+if (failed > 0) process.exitCode = 1;