@cnrai/pave 0.3.35 → 0.3.51

package/test/agent-spawn.test.js

@@ -1,933 +0,0 @@
-// Tests for Issue #253: agent_spawn tool + pave agent restart CLI
-// Verifies spawn tool, restart subcommand, status config persistence, and rate limiting
-
-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++;
-  }
-}
-
-// ============================================================
-// Load source files for inspection
-// ============================================================
-
-const agentCommSource = fs.readFileSync(
-  path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'agent-comm.js'), 'utf8');
-const toolsIndexSource = fs.readFileSync(
-  path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'index.js'), 'utf8');
-const paveSource = fs.readFileSync(
-  path.join(__dirname, '..', '..', 'pave', 'index.js'), 'utf8');
-const argsParserSource = fs.readFileSync(
-  path.join(__dirname, '..', '..', 'pave', 'lib', 'args-parser.js'), 'utf8');
-
-// ============================================================
-// 1. agent_spawn tool definition tests
-// ============================================================
-
-runTest('agent_spawn: tool definition exists in getAgentCommTools', () => {
-  assert(agentCommSource.indexOf('name: "agent_spawn"') !== -1,
-    'should have agent_spawn tool definition');
-});
-
-runTest('agent_spawn: tool has required parameters (name and soul)', () => {
-  const toolIdx = agentCommSource.indexOf('name: "agent_spawn"');
-  const toolSection = agentCommSource.substring(toolIdx, toolIdx + 2000);
-  assert(toolSection.indexOf('"name"') !== -1, 'should have name parameter');
-  assert(toolSection.indexOf('"soul"') !== -1, 'should have soul parameter');
-  assert(toolSection.indexOf('required: ["name", "soul"]') !== -1,
-    'name and soul should be required');
-});
-
-runTest('agent_spawn: tool has optional parameters', () => {
-  const toolIdx = agentCommSource.indexOf('name: "agent_spawn"');
-  const toolSection = agentCommSource.substring(toolIdx, toolIdx + 2000);
-  assert(toolSection.indexOf('working_directory') !== -1, 'should have working_directory param');
-  assert(toolSection.indexOf('sleep') !== -1, 'should have sleep param');
-  assert(toolSection.indexOf('reinject_interval') !== -1, 'should have reinject_interval param');
-  assert(toolSection.indexOf('config') !== -1, 'should have config param');
-});
-
-// ============================================================
-// 2. agent_spawn executor tests
-// ============================================================
-
-runTest('agent_spawn: executeAgentSpawn function exists', () => {
-  assert(agentCommSource.indexOf('function executeAgentSpawn(') !== -1,
-    'should define executeAgentSpawn function');
-});
-
-runTest('agent_spawn: validates required name parameter', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 500);
-  assert(execSection.indexOf("!args.name") !== -1,
-    'should check for missing name parameter');
-});
-
-runTest('agent_spawn: validates required soul parameter', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 500);
-  assert(execSection.indexOf("!args.soul") !== -1,
-    'should check for missing soul parameter');
-});
-
-runTest('agent_spawn: checks if agent is already alive (handles object return)', () => {
-  assert(agentCommSource.indexOf('isAgentAlive(agentName)') !== -1,
-    'should check if agent name is already running');
-  // isAgentAlive returns { alive, status } - must extract .alive boolean
-  const aliveIdx = agentCommSource.indexOf('_registry.isAgentAlive(agentName)');
-  assert(aliveIdx !== -1, 'should find _registry.isAgentAlive(agentName) call');
-  const aliveSection = agentCommSource.substring(aliveIdx, aliveIdx + 300);
-  assert(aliveSection.indexOf('.alive') !== -1,
-    'should extract .alive from isAgentAlive result (not treat object as boolean)');
-});
-
-runTest('agent_spawn: validates SOUL file exists', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 3000);
-  assert(execSection.indexOf('statSync(resolvedSoul)') !== -1,
-    'should validate SOUL file via statSync');
-  assert(execSection.indexOf('SOUL file not found') !== -1 || execSection.indexOf('isFile()') !== -1,
-    'should validate SOUL is a file or show missing error');
-});
-
-runTest('agent_spawn: spawns with detached mode and PAVE_DAEMON env', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 7000);
-  assert(execSection.indexOf('detached: true') !== -1,
-    'should spawn with detached: true');
-  assert(execSection.indexOf("PAVE_DAEMON: '1'") !== -1,
-    'should set PAVE_DAEMON=1 env var');
-});
-
-runTest('agent_spawn: calls child.unref() to detach from parent', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 7000);
-  assert(execSection.indexOf('child.unref()') !== -1,
-    'should call child.unref() for daemon detachment');
-});
-
-runTest('agent_spawn: returns success with PID and name', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 7000);
-  assert(execSection.indexOf('pid: child.pid') !== -1,
-    'should return PID in result');
-  assert(execSection.indexOf('name: agentName') !== -1,
-    'should return agent name in result');
-});
-
-// ============================================================
-// 3. Spawn rate limiting tests
-// ============================================================
-
-runTest('agent_spawn: spawn rate limit constant defined (3/min)', () => {
-  assert(agentCommSource.indexOf('SPAWN_RATE_LIMIT_MAX = 3') !== -1,
-    'should define SPAWN_RATE_LIMIT_MAX = 3');
-  assert(agentCommSource.indexOf('SPAWN_RATE_LIMIT_WINDOW_MS = 60 * 1000') !== -1,
-    'should define 60-second spawn rate limit window');
-});
-
-runTest('agent_spawn: max total agents guard (10)', () => {
-  assert(agentCommSource.indexOf('MAX_TOTAL_AGENTS = 10') !== -1,
-    'should define MAX_TOTAL_AGENTS = 10');
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 3000);
-  assert(execSection.indexOf('aliveCount >= MAX_TOTAL_AGENTS') !== -1,
-    'should check alive count against max total');
-});
-
-runTest('agent_spawn: warns when many agents running (>= 3)', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 3000);
-  assert(execSection.indexOf('aliveCount >= 3') !== -1,
-    'should warn when >= 3 agents running');
-});
-
-runTest('agent_spawn: _checkSpawnRateLimit function exists', () => {
-  assert(agentCommSource.indexOf('function _checkSpawnRateLimit()') !== -1,
-    'should define _checkSpawnRateLimit function');
-});
-
-runTest('agent_spawn: spawn rate limit resets window correctly', () => {
-  const agentComm = require(path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'agent-comm.js'));
-  // Reset state
-  agentComm._spawnRateState.count = 0;
-  agentComm._spawnRateState.windowStart = 0;
-  // First check should be allowed
-  let result = agentComm._checkSpawnRateLimit();
-  assert(result.allowed === true, 'first check should be allowed');
-  // Second and third should also be allowed
-  result = agentComm._checkSpawnRateLimit();
-  assert(result.allowed === true, 'second check should be allowed');
-  result = agentComm._checkSpawnRateLimit();
-  assert(result.allowed === true, 'third check should be allowed');
-  // Fourth should be rate limited
-  result = agentComm._checkSpawnRateLimit();
-  assert(result.allowed === false, 'fourth check should be rate limited');
-  assert(result.error.indexOf('Spawn rate limited') !== -1, 'should have rate limit error message');
-});
-
-runTest('agent_spawn: spawn rate limit window expires', () => {
-  const agentComm = require(path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'agent-comm.js'));
-  // Set window start to past (> 60s ago) with count at max
-  const state = agentComm._spawnRateState;
-  state.count = agentComm.SPAWN_RATE_LIMIT_MAX;
-  state.windowStart = Date.now() - (agentComm.SPAWN_RATE_LIMIT_WINDOW_MS + 1000);
-  // Should reset window and allow
-  const result = agentComm._checkSpawnRateLimit();
-  assert(result.allowed === true, 'should be allowed after window expires');
-  // After reset, count should be 1 (the new request)
-  assert(state.count === 1, 'count should reset to 1 after window expires, got ' + state.count);
-});
-
-// ============================================================
-// 4. Module exports tests
-// ============================================================
-
-runTest('agent_spawn: executeAgentSpawn is exported', () => {
-  // Check for shorthand or explicit property
-  assert(agentCommSource.indexOf('executeAgentSpawn') !== -1
-    && /module\.exports\s*=\s*\{[^}]*executeAgentSpawn/s.test(agentCommSource),
-  'should export executeAgentSpawn');
-});
-
-runTest('agent_spawn: SPAWN_RATE_LIMIT_MAX is exported', () => {
-  assert(/module\.exports\s*=\s*\{[^}]*SPAWN_RATE_LIMIT_MAX/s.test(agentCommSource),
-    'should export SPAWN_RATE_LIMIT_MAX');
-});
-
-runTest('agent_spawn: MAX_TOTAL_AGENTS is exported', () => {
-  assert(/module\.exports\s*=\s*\{[^}]*MAX_TOTAL_AGENTS/s.test(agentCommSource),
-    'should export MAX_TOTAL_AGENTS');
-});
-
-// ============================================================
-// 5. tools/index.js wiring tests
-// ============================================================
-
-runTest('tools/index.js: imports executeAgentSpawn', () => {
-  assert(toolsIndexSource.indexOf('executeAgentSpawn') !== -1,
-    'should import executeAgentSpawn from agent-comm');
-});
-
-runTest('tools/index.js: dispatches agent_spawn tool calls', () => {
-  assert(toolsIndexSource.indexOf('name === "agent_spawn"') !== -1,
-    'should have agent_spawn dispatch check');
-  const dispatchIdx = toolsIndexSource.indexOf('name === "agent_spawn"');
-  const dispatchSection = toolsIndexSource.substring(dispatchIdx, dispatchIdx + 300);
-  assert(dispatchSection.indexOf('executeAgentSpawn(args, toolId)') !== -1,
-    'should call executeAgentSpawn with args and toolId');
-});
-
-// ============================================================
-// 6. args-parser: restart subcommand tests
-// ============================================================
-
-runTest('args-parser: recognizes restart as agentSubcommand', () => {
-  assert(argsParserSource.indexOf("'restart'") !== -1,
-    'should recognize restart as a subcommand');
-  // Check it's in the subcommand assignment block
-  const restartIdx = argsParserSource.indexOf("'restart'");
-  const nearbySection = argsParserSource.substring(restartIdx - 200, restartIdx + 200);
-  assert(nearbySection.indexOf('agentSubcommand') !== -1,
-    'restart should be in agentSubcommand assignment context');
-});
-
-runTest('args-parser: restart subcommand accepts agent name positional', () => {
-  // The validation guard that accepts agent name should include restart
-  assert(argsParserSource.indexOf("'stop' || a === 'logs' || a === 'restart'") !== -1,
-    'restart should be alongside stop/logs for name positional acceptance');
-});
-
-runTest('args-parser: restart appears in help text', () => {
-  assert(argsParserSource.indexOf('pave agent restart') !== -1,
-    'restart should appear in usage/help text');
-});
-
-runTest('args-parser: functional - parse "pave agent restart designer"', () => {
-  const parseArgsMod = require(path.join(__dirname, '..', '..', 'pave', 'lib', 'args-parser.js'));
-  const parseFn = parseArgsMod.parseArgs || parseArgsMod;
-  assert(typeof parseFn === 'function', 'should be able to get parseArgs function, got ' + typeof parseFn);
-  const args = parseFn(['agent', 'restart', 'designer']);
-  assert(args.command === 'agent', 'should set command to agent');
-  assert(args.agentSubcommand === 'restart', 'should set agentSubcommand to restart');
-  assert(args.commandArgs[0] === 'designer', 'should capture agent name as commandArgs[0]');
-});
-
-runTest('args-parser: functional - parse "pave agent restart" (no name)', () => {
-  const parseArgsMod = require(path.join(__dirname, '..', '..', 'pave', 'lib', 'args-parser.js'));
-  const parseFn = parseArgsMod.parseArgs || parseArgsMod;
-  const args = parseFn(['agent', 'restart']);
-  assert(args.command === 'agent', 'should set command to agent');
-  assert(args.agentSubcommand === 'restart', 'should set agentSubcommand to restart');
-  assert(!args.commandArgs || args.commandArgs.length === 0, 'should have no commandArgs');
-});
-
-runTest('args-parser: functional - parse "pave agent start hr-manager"', () => {
-  const parseArgsMod = require(path.join(__dirname, '..', '..', 'pave', 'lib', 'args-parser.js'));
-  const parseFn = parseArgsMod.parseArgs || parseArgsMod;
-  assert(typeof parseFn === 'function', 'should be able to get parseArgs function');
-  const args = parseFn(['agent', 'start', 'hr-manager']);
-  assert(args.command === 'agent', 'should set command to agent');
-  assert(args.agentSubcommand === 'start', 'should set agentSubcommand to start');
-  assert(args.commandArgs[0] === 'hr-manager', 'should capture agent name as commandArgs[0]');
-});
-
-runTest('args-parser: functional - parse "pave agent start" (no name)', () => {
-  const parseArgsMod = require(path.join(__dirname, '..', '..', 'pave', 'lib', 'args-parser.js'));
-  const parseFn = parseArgsMod.parseArgs || parseArgsMod;
-  const args = parseFn(['agent', 'start']);
-  assert(args.command === 'agent', 'should set command to agent');
-  assert(args.agentSubcommand === 'start', 'should set agentSubcommand to start');
-  assert(!args.commandArgs || args.commandArgs.length === 0, 'should have no commandArgs');
-});
-
-// ============================================================
-// 7. pave/index.js: restart handler tests
-// ============================================================
-
-runTest('index.js: handleAgentRestart function exists', () => {
-  assert(paveSource.indexOf('function handleAgentRestart(') !== -1,
-    'should define handleAgentRestart function');
-});
-
-runTest('index.js: restart subcommand is dispatched', () => {
-  assert(paveSource.indexOf("agentSubcommand === 'restart'") !== -1,
-    'should check for restart subcommand');
-  const restartIdx = paveSource.indexOf("agentSubcommand === 'restart'");
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 200);
-  assert(restartSection.indexOf('handleAgentRestart') !== -1,
-    'should call handleAgentRestart');
-});
-
-runTest('index.js: restart reads saved config from status', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 4000);
-  assert(restartSection.indexOf('status.soulPath') !== -1,
-    'should read soulPath from status');
-  assert(restartSection.indexOf('status.sleepMs') !== -1,
-    'should read sleepMs from status');
-  assert(restartSection.indexOf('status.reinjectInterval') !== -1,
-    'should read reinjectInterval from status');
-});
-
-runTest('index.js: restart validates soulPath exists in status', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 3000);
-  assert(restartSection.indexOf('!status.soulPath') !== -1,
-    'should check if soulPath is missing in status');
-  assert(restartSection.indexOf('has no soulPath') !== -1,
-    'should have error message for missing soulPath');
-});
-
-runTest('index.js: restart preserves session ID', () => {
-  // handleAgentRestart reads sessionId from status and passes it to _spawnFromStatus
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 7000);
-  assert(restartSection.indexOf('status.sessionId') !== -1,
-    'should read sessionId from status');
-  assert(restartSection.indexOf('_spawnFromStatus') !== -1,
-    'should delegate to _spawnFromStatus');
-  // _spawnFromStatus passes --session flag
-  const spawnHelper = paveSource.substring(paveSource.indexOf('function _spawnFromStatus('),
-    paveSource.indexOf('function _spawnFromStatus(') + 3000);
-  assert(spawnHelper.indexOf("'--session'") !== -1,
-    'should pass --session flag when re-spawning');
-});
-
-runTest('index.js: restart stops agent before re-spawning', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 7000);
-  assert(restartSection.indexOf('registry.stopAgent(agentName)') !== -1,
-    'should call stopAgent before respawning');
-  // Stop should come before _spawnFromStatus call
-  const stopIdx = restartSection.indexOf('stopAgent');
-  const spawnIdx = restartSection.indexOf('_spawnFromStatus');
-  assert(stopIdx < spawnIdx, 'stop should come before spawn');
-});
-
-runTest('index.js: restart spawns detached daemon', () => {
-  // Spawn details are now in the shared _spawnFromStatus helper
-  const spawnHelperIdx = paveSource.indexOf('function _spawnFromStatus(');
-  const spawnSection = paveSource.substring(spawnHelperIdx, spawnHelperIdx + 3000);
-  assert(spawnSection.indexOf('detached: true') !== -1,
-    'should spawn with detached: true');
-  assert(spawnSection.indexOf("PAVE_DAEMON: '1'") !== -1,
-    'should set PAVE_DAEMON env var');
-});
-
-runTest('index.js: restart has no unused spawn import (delegated to _spawnFromStatus)', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  // Find the end of handleAgentRestart by looking for the next top-level function
-  const nextFnIdx = paveSource.indexOf('\nfunction ', restartIdx + 1);
-  const nextAsyncFnIdx = paveSource.indexOf('\nasync function ', restartIdx + 1);
-  // Use the nearest one
-  const candidates = [];
-  if (nextFnIdx !== -1) candidates.push(nextFnIdx);
-  if (nextAsyncFnIdx !== -1) candidates.push(nextAsyncFnIdx);
-  const endIdx = candidates.length > 0 ? Math.min.apply(null, candidates) : paveSource.length;
-  const restartBody = paveSource.substring(restartIdx, endIdx);
-  assert(restartBody.indexOf("require('child_process')") === -1,
-    'handleAgentRestart should not import child_process (spawning is in _spawnFromStatus)');
-});
-
-runTest('index.js: restart infers agent from CWD when no name given', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 2000);
-  // Should have same CWD inference as handleAgentStop
-  assert(restartSection.indexOf('process.cwd()') !== -1,
-    'should use process.cwd() for CWD-based inference');
-  assert(restartSection.indexOf("a.status.cwd === cwd") !== -1,
-    'should match agent status CWD');
-});
-
-runTest('index.js: restart uses resolveAgentName for prefix matching', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 3000);
-  assert(restartSection.indexOf('registry.resolveAgentName(nameArg)') !== -1,
-    'should use resolveAgentName for prefix matching');
-});
-
-// ============================================================
-// 7b. Copilot review fixes (Issue #258)
-// ============================================================
-
-runTest('index.js: restart validates SOUL file using validateSoulFile()', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 4000);
-  assert(restartSection.indexOf('validateSoulFile(status.soulPath)') !== -1,
-    'should call validateSoulFile() for SOUL validation');
-  assert(restartSection.indexOf('soulValidation.valid') !== -1 || restartSection.indexOf('!soulValidation.valid') !== -1,
-    'should check validation result');
-  assert(restartSection.indexOf('Cannot restart') !== -1,
-    'should have clear error when SOUL validation fails');
-});
-
-runTest('index.js: restart uses explicit index.js for pavePath', () => {
-  // pavePath is now in the shared _spawnFromStatus helper
-  const spawnHelperIdx = paveSource.indexOf('function _spawnFromStatus(');
-  const spawnSection = paveSource.substring(spawnHelperIdx, spawnHelperIdx + 3000);
-  assert(spawnSection.indexOf("path.join(__dirname, 'index.js')") !== -1,
-    'should use path.join(__dirname, index.js) not path.resolve(__dirname)');
-});
-
-runTest('index.js: restart destructures isAgentAlive return value', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 5000);
-  assert(restartSection.indexOf('aliveResult') !== -1,
-    'should store isAgentAlive result as aliveResult');
-  assert(restartSection.indexOf('aliveResult.alive') !== -1,
-    'should check .alive property from isAgentAlive result');
-});
-
-// ============================================================
-// 8. handleAgentStart tests (Issue #266)
-// ============================================================
-
-runTest('index.js: handleAgentStart function exists', () => {
-  assert(paveSource.indexOf('function handleAgentStart(') !== -1,
-    'should have handleAgentStart function');
-});
-
-runTest('index.js: start subcommand is dispatched', () => {
-  assert(paveSource.indexOf("agentSubcommand === 'start'") !== -1,
-    'should check for start subcommand');
-  assert(paveSource.indexOf('handleAgentStart(args)') !== -1,
-    'should call handleAgentStart');
-});
-
-runTest('args-parser: recognizes start as agentSubcommand', () => {
-  assert(argsParserSource.indexOf("'start'") !== -1,
-    'should include start in subcommand detection');
-});
-
-runTest('args-parser: start appears in help text', () => {
-  assert(argsParserSource.indexOf('pave agent start') !== -1,
-    'help text should mention pave agent start');
-});
-
-runTest('index.js: start refuses if agent is already running', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 5000);
-  assert(startSection.indexOf('isAgentAlive') !== -1,
-    'should check if agent is alive');
-  assert(startSection.indexOf('already running') !== -1,
-    'should print error when agent is already running');
-  assert(startSection.indexOf('pave agent restart') !== -1,
-    'should suggest using restart instead');
-});
-
-runTest('index.js: start reads saved config from status', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 5000);
-  assert(startSection.indexOf('registry.readStatus(agentName)') !== -1,
-    'should read status from registry');
-  assert(startSection.indexOf('status.soulPath') !== -1,
-    'should access soulPath from status');
-});
-
-runTest('index.js: start validates soulPath exists in status', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 5000);
-  assert(startSection.indexOf('!status.soulPath') !== -1,
-    'should check soulPath is present in status');
-  assert(startSection.indexOf('Cannot start') !== -1,
-    'should have clear error when no soulPath');
-});
-
-runTest('index.js: start validates SOUL file exists', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 5000);
-  assert(startSection.indexOf('validateSoulFile(status.soulPath)') !== -1,
-    'should call validateSoulFile');
-});
-
-runTest('index.js: start validates cwd still exists and is a directory', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 5000);
-  assert(startSection.indexOf('fs.statSync(agentCwd)') !== -1 ||
-    startSection.indexOf('cwdStat') !== -1,
-  'should validate working directory still exists');
-  assert(startSection.indexOf('isDirectory') !== -1,
-    'should verify cwd is actually a directory');
-  assert(startSection.indexOf('no longer exists') !== -1,
-    'should print error when cwd is missing');
-  // Should not fall back to process.cwd() — require explicit cwd in status
-  assert(startSection.indexOf("status.cwd || process.cwd()") === -1,
-    'should not fall back to process.cwd() for agent cwd');
-});
-
-runTest('index.js: start delegates to _spawnFromStatus', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 5000);
-  assert(startSection.indexOf('_spawnFromStatus') !== -1,
-    'should delegate to shared spawn helper');
-  assert(startSection.indexOf("'started'") !== -1,
-    'should use started as verb');
-});
-
-runTest('index.js: start infers agent from CWD (includes stopped agents)', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 3000);
-  assert(startSection.indexOf('process.cwd()') !== -1,
-    'should use process.cwd() for inference');
-  // start should find stopped agents too (not just alive ones)
-  assert(startSection.indexOf('cwdMatches') !== -1,
-    'should match all agents in cwd (not just alive)');
-});
-
-runTest('index.js: start uses resolveAgentName for prefix matching', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 3000);
-  assert(startSection.indexOf('registry.resolveAgentName(nameArg)') !== -1,
-    'should use resolveAgentName for prefix matching');
-});
-
-runTest('index.js: start preserves session from saved config', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 5000);
-  assert(startSection.indexOf('status.sessionId') !== -1,
-    'should read sessionId from status');
-});
-
-runTest('index.js: _spawnFromStatus shared helper exists', () => {
-  assert(paveSource.indexOf('function _spawnFromStatus(') !== -1,
-    'should have _spawnFromStatus helper function');
-});
-
-runTest('index.js: _spawnFromStatus handles both start and restart verbs', () => {
-  const helperIdx = paveSource.indexOf('function _spawnFromStatus(');
-  const helperSection = paveSource.substring(helperIdx, helperIdx + 300);
-  assert(helperSection.indexOf('verb') !== -1,
-    'should accept verb parameter for user messages');
-});
-
-runTest('index.js: _spawnFromStatus uses ACTION_LABELS instead of brittle verb.replace', () => {
-  const helperIdx = paveSource.indexOf('function _spawnFromStatus(');
-  const helperSection = paveSource.substring(helperIdx, helperIdx + 3000);
-  assert(helperSection.indexOf('ACTION_LABELS') !== -1,
-    'should use ACTION_LABELS map for verb-to-action conversion');
-  assert(helperSection.indexOf("verb.replace('ed'") === -1,
-    'should not use brittle verb.replace() pattern');
-  assert(helperSection.indexOf("action + ' agent") !== -1,
-    'should use action variable in error messages');
-});
-
-runTest('index.js: _spawnFromStatus passes --port when saved in config', () => {
-  const helperIdx = paveSource.indexOf('function _spawnFromStatus(');
-  const helperSection = paveSource.substring(helperIdx, helperIdx + 3000);
-  assert(helperSection.indexOf("savedConfig.port") !== -1,
-    'should check for port in savedConfig');
-  assert(helperSection.indexOf("'--port'") !== -1,
-    'should pass --port flag to child args');
-});
-
-runTest('index.js: start savedConfig includes port from status', () => {
-  const startIdx = paveSource.indexOf('function handleAgentStart(');
-  const startSection = paveSource.substring(startIdx, startIdx + 5000);
-  assert(startSection.indexOf('port: status.port') !== -1,
-    'should carry port from status.json into savedConfig');
-});
-
-runTest('index.js: restart savedConfig includes port from status', () => {
-  const restartIdx = paveSource.indexOf('function handleAgentRestart(');
-  const restartSection = paveSource.substring(restartIdx, restartIdx + 5000);
-  assert(restartSection.indexOf('port: status.port') !== -1,
-    'should carry port from status.json into savedConfig');
-});
-
-runTest('index.js: help text includes start subcommand', () => {
-  assert(paveSource.indexOf('pave agent start') !== -1,
-    'agent help should mention start');
-  assert(paveSource.indexOf('Start a stopped agent') !== -1,
-    'help should describe start functionality');
-});
-
-runTest('index.js: examples include start command', () => {
-  assert(paveSource.indexOf('pave agent start github-watcher') !== -1,
-    'examples should show start command');
-});
-
-// ============================================================
-// 8b. Port field fix (Issue #266)
-// ============================================================
-
-runTest('index.js: writeStatus uses actualPort instead of PORT constant', () => {
-  // After the server starts, status should use the actual listening port
-  // The declaration of actualPort should exist in the agent daemon handler
-  const daemonIdx = paveSource.indexOf('let actualPort = PORT');
-  assert(daemonIdx !== -1, 'should declare actualPort variable initialized to PORT');
-
-  // After startServer, actualPort should be updated
-  assert(paveSource.indexOf('actualPort = serverResult.actualPort') !== -1,
-    'should update actualPort from serverResult after startServer');
-
-  // writeStatus calls should use actualPort, not PORT
-  // Find the first writeStatus after startServer in the agent handler
-  const serverStartIdx = paveSource.indexOf('serverResult = await startServer');
-  const afterServer = paveSource.substring(serverStartIdx, serverStartIdx + 20000);
-  const writeStatusInSection = afterServer.indexOf('port: actualPort');
-  assert(writeStatusInSection !== -1,
-    'writeStatus after startServer should use actualPort');
-});
-
-runTest('index.js: SOUL-read failure circuit-breaker uses actualPort', () => {
-  // When the circuit breaker trips after max SOUL read failures,
-  // the registry write should use actualPort, not PORT
-  // Use the unique string that only appears in writeStatus (not agentContext)
-  const cbIdx = paveSource.indexOf("currentTask: 'stopped after ' + consecutiveFailures + ' consecutive failures',");
-  assert(cbIdx !== -1, 'should find circuit-breaker currentTask in writeStatus');
-  // Look backwards ~600 chars for the port: field in the same writeStatus call
-  const startIdx = Math.max(0, cbIdx - 600);
-  const section = paveSource.substring(startIdx, cbIdx);
-  const portLine = section.lastIndexOf('port:');
-  assert(portLine !== -1, 'should find port field in circuit-breaker writeStatus');
-  const portValue = section.substring(portLine, portLine + 30);
-  assert(portValue.indexOf('actualPort') !== -1,
-    'circuit-breaker writeStatus should use actualPort, not PORT');
-});
-
-runTest('index.js: SOUL-read failure backoff sleep uses actualPort', () => {
-  // When SOUL read fails but hasn't tripped the circuit breaker yet,
-  // the sleep status should use actualPort, not PORT
-  const soulErrorSleepIdx = paveSource.indexOf('signalAwareSleep(soulErrorSleepMs');
-  assert(soulErrorSleepIdx !== -1, 'should find soulErrorSleep call');
-  // Look backwards ~500 chars for the port: field in the writeStatus before sleep
-  const startIdx = Math.max(0, soulErrorSleepIdx - 500);
-  const section = paveSource.substring(startIdx, soulErrorSleepIdx);
-  const portLine = section.lastIndexOf('port:');
-  assert(portLine !== -1, 'should find port field before soulErrorSleep');
-  const portValue = section.substring(portLine, portLine + 30);
-  assert(portValue.indexOf('actualPort') !== -1,
-    'SOUL-read backoff writeStatus should use actualPort, not PORT');
-});
-
-runTest('index.js: unreliable port comment still exists as documentation', () => {
-  // The comment explaining the port discrepancy should still be present
-  assert(paveSource.indexOf('status.port is unreliable') !== -1 ||
-    paveSource.indexOf('actualPort') !== -1,
-  'should document the port behavior');
-});
-
-runTest('agent_spawn: awaits spawn confirmation with Promise pattern', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 7000);
-  assert(execSection.indexOf('await new Promise') !== -1,
-    'should await a Promise for spawn confirmation');
-  assert(execSection.indexOf("child.once('error'") !== -1,
-    'should listen for error event on child process');
-  assert(execSection.indexOf("child.once('spawn'") !== -1,
-    'should listen for spawn event on child process');
-  assert(execSection.indexOf('setTimeout') !== -1,
-    'should have a timeout fallback');
-  assert(execSection.indexOf('Agent spawn failed') !== -1,
-    'should return error message when spawn fails');
-  assert(execSection.indexOf('removeListener') !== -1,
-    'should remove listeners on settlement to prevent leaks');
-});
-
-runTest('agent_spawn: function is async for await support', () => {
-  assert(agentCommSource.indexOf('async function executeAgentSpawn(') !== -1,
-    'executeAgentSpawn should be declared async');
-});
-
-runTest('agent_spawn: dispatcher awaits executeAgentSpawn', () => {
-  const toolsSource = fs.readFileSync(
-    path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'index.js'), 'utf8');
-  const idx = toolsSource.indexOf('agent_spawn');
-  assert(idx !== -1, 'should find agent_spawn in tools/index.js');
-  const section = toolsSource.substring(idx, idx + 300);
-  assert(section.indexOf('await executeAgentSpawn') !== -1,
-    'dispatcher should await executeAgentSpawn to capture errors and duration correctly');
-});
-
-runTest('agent_spawn: handles isAgentAlive object return shape', () => {
-  const execIdx = agentCommSource.indexOf('function executeAgentSpawn(');
-  const execSection = agentCommSource.substring(execIdx, execIdx + 2000);
-  assert(execSection.indexOf('aliveResult') !== -1,
-    'should store isAgentAlive result in aliveResult');
-  assert(execSection.indexOf('.alive') !== -1,
-    'should extract .alive boolean from result');
-});
-
-runTest('agent-comm.test.js: uses agentComm.xxx not bare identifiers', () => {
-  const testSource = fs.readFileSync(
-    path.join(__dirname, 'agent-comm.test.js'), 'utf8');
-  // Line 65 should use agentComm.registerAgentComm, not bare registerAgentComm
-  const toolsTestIdx = testSource.indexOf('returns 3 tools when registered');
-  assert(toolsTestIdx !== -1, 'should find tool count test');
-  const testSection = testSource.substring(toolsTestIdx, toolsTestIdx + 500);
-  assert(testSection.indexOf('agentComm.registerAgentComm') !== -1,
-    'should use agentComm.registerAgentComm, not bare registerAgentComm');
-  assert(testSection.indexOf('agentComm.getAgentCommTools') !== -1,
-    'should use agentComm.getAgentCommTools, not bare getAgentCommTools');
-});
-
-// ============================================================
-// 8. Status config persistence tests
-// ============================================================
-
-runTest('index.js: writeStatus stores soulPath', () => {
-  const statusIdx = paveSource.indexOf("state: registry.STATES.SLEEPING");
-  assert(statusIdx !== -1, 'should find SLEEPING writeStatus call');
-  const statusSection = paveSource.substring(statusIdx, statusIdx + 500);
-  assert(statusSection.indexOf('soulPath:') !== -1,
-    'writeStatus should include soulPath field');
-});
-
-runTest('index.js: writeStatus stores sleepMs', () => {
-  const statusIdx = paveSource.indexOf('state: registry.STATES.SLEEPING');
-  const statusSection = paveSource.substring(statusIdx, statusIdx + 500);
-  // Match shorthand `sleepMs,` or explicit `sleepMs:`
-  assert(statusSection.indexOf('sleepMs') !== -1,
-    'writeStatus should include sleepMs field');
-});
-
-runTest('index.js: writeStatus stores reinjectInterval', () => {
-  const statusIdx = paveSource.indexOf("state: registry.STATES.SLEEPING");
-  const statusSection = paveSource.substring(statusIdx, statusIdx + 500);
-  assert(statusSection.indexOf('reinjectInterval:') !== -1,
-    'writeStatus should include reinjectInterval field');
-});
-
-// ============================================================
-// 9. _msToSleepArg helper function tests
-// ============================================================
-
-runTest('index.js: _msToSleepArg function exists', () => {
-  assert(paveSource.indexOf('function _msToSleepArg(') !== -1,
-    'should define _msToSleepArg function');
-});
-
-runTest('index.js: _msToSleepArg converts correctly', () => {
-  // Test the logic by inspecting the function body
-  const fnIdx = paveSource.indexOf('function _msToSleepArg(');
-  const fnSection = paveSource.substring(fnIdx, fnIdx + 400);
-  // Should handle hours, minutes, and seconds
-  assert(fnSection.indexOf("'h'") !== -1, 'should handle hours suffix');
-  assert(fnSection.indexOf("'m'") !== -1, 'should handle minutes suffix');
-  assert(fnSection.indexOf("'s'") !== -1, 'should handle seconds suffix');
-  // Should have default fallback
-  assert(fnSection.indexOf("'1m'") !== -1, 'should default to 1m for invalid/zero input');
-});
-
-// ============================================================
-// 10. Help text and documentation tests
-// ============================================================
-
-runTest('index.js: help text includes restart subcommand', () => {
-  assert(paveSource.indexOf('pave agent restart [name]') !== -1,
-    'main help should mention restart subcommand');
-});
-
-runTest('index.js: restart help describes session preservation', () => {
-  // The restart subcommand description mentions preserving session
-  const restartHelpIdx = paveSource.indexOf('Restart a running agent');
-  assert(restartHelpIdx !== -1, 'should find restart help text');
-  const helpSection = paveSource.substring(restartHelpIdx, restartHelpIdx + 300);
-  assert(helpSection.indexOf('session') !== -1 || helpSection.indexOf('Session') !== -1,
-    'restart help should mention session preservation');
-});
-
-runTest('index.js: examples include restart command', () => {
-  assert(paveSource.indexOf('pave agent restart github-watcher') !== -1,
-    'examples should include restart command');
-});
-
-// ============================================================
-// 11. agent-comm.js module header updated
-// ============================================================
-
-runTest('agent-comm.js: module comment mentions agent_spawn', () => {
-  assert(agentCommSource.indexOf('agent_spawn') !== -1,
-    'module header should mention agent_spawn tool');
-});
-
-// ============================================================
-// 12. Functional: executeAgentSpawn without registration
-// ============================================================
-
-runTest('agent_spawn: returns error when not registered', () => {
-  const agentComm = require(path.join(__dirname, '..', '..', 'opencode-lite', 'src', 'tools', 'agent-comm.js'));
-  const resultPromise = agentComm.executeAgentSpawn({ name: 'test', soul: '/tmp/test.md' }, 'test-1');
-  // Since function is now async, it returns a Promise.
-  assert(resultPromise instanceof Promise, 'should return a Promise (async function)');
-  // Verify the source has the early-return guard for unregistered state
-  assert(agentCommSource.indexOf("'agent_spawn tool is not available") !== -1 ||
-    agentCommSource.indexOf('not available') !== -1,
-  'should have not-available error for unregistered state');
-  // Verify the early-return produces { success: false, error: ... }
-  const earlyReturnIdx = agentCommSource.indexOf('not available');
-  assert(earlyReturnIdx !== -1, 'should find not-available guard');
-  const earlySection = agentCommSource.substring(earlyReturnIdx - 100, earlyReturnIdx + 200);
-  assert(earlySection.indexOf('success: false') !== -1,
-    'early return should have success: false');
-});
-
-runTest('agent_spawn: JSDoc @returns shows Promise type', () => {
-  const idx = agentCommSource.indexOf('function executeAgentSpawn(');
-  assert(idx !== -1, 'should find executeAgentSpawn');
-  const docSection = agentCommSource.substring(Math.max(0, idx - 300), idx);
-  assert(docSection.indexOf('Promise') !== -1,
-    '@returns JSDoc should mention Promise for async function');
-});
-
-// ============================================================
-// 13. Daemon preliminary status write tests (Issue #286)
-// ============================================================
-
-// Helper: extract daemon section from paveSource with guard assertion
-function getDaemonSection(size) {
-  const daemonIdx = paveSource.indexOf('if (args.daemon)');
-  assert(daemonIdx !== -1, 'should have daemon mode check (if (args.daemon))');
-  return paveSource.substring(daemonIdx, daemonIdx + (size || 5000));
-}
-
-// Helper: extract the writeStatus call section within the daemon block
-function getWriteStatusSection(daemonSection, size) {
-  const writeIdx = daemonSection.indexOf('registry.writeStatus(agentName');
-  assert(writeIdx !== -1, 'should have registry.writeStatus(agentName in daemon block');
-  return daemonSection.substring(writeIdx, writeIdx + (size || 400));
-}
-
-runTest('index.js: daemon writes preliminary status after spawn', () => {
-  const daemonSection = getDaemonSection();
-  assert(daemonSection.indexOf('registry.writeStatus(agentName') !== -1,
-    'daemon branch should call registry.writeStatus');
-  assert(daemonSection.indexOf('daemon spawning...') !== -1,
-    'should set currentTask to daemon spawning...');
-  // Verify ordering: writeStatus must come AFTER spawn (not before)
-  const spawnIdx = daemonSection.indexOf('spawn(process.execPath');
-  const writeIdx = daemonSection.indexOf('registry.writeStatus(agentName');
-  assert(spawnIdx !== -1, 'should have spawn call');
-  assert(writeIdx !== -1, 'should have writeStatus call');
-  assert(spawnIdx < writeIdx,
-    'writeStatus should come AFTER spawn (needs child.pid)');
-});
-
-runTest('index.js: daemon preliminary status uses same agent name as child', () => {
-  const daemonSection = getDaemonSection();
-  assert(daemonSection.indexOf("args.name || 'PAVE Agent'") !== -1,
-    'daemon should use args.name || \'PAVE Agent\' to match child logic');
-  assert(daemonSection.indexOf('path.basename(soulPath') === -1,
-    'daemon should NOT derive name from SOUL path basename');
-});
-
-runTest('index.js: daemon preliminary status uses registry.STATES constant', () => {
-  const daemonSection = getDaemonSection();
-  const writeSection = getWriteStatusSection(daemonSection);
-  assert(writeSection.indexOf('state: registry.STATES.STARTING') !== -1,
-    'should use registry.STATES.STARTING constant, not string literal');
-  assert(writeSection.indexOf("state: 'starting'") === -1,
-    'should NOT use string literal starting');
-});
-
-runTest('index.js: daemon preliminary status uses relative config path', () => {
-  const daemonSection = getDaemonSection();
-  const writeSection = getWriteStatusSection(daemonSection);
-  assert(writeSection.indexOf("config: args.config || '.pave'") !== -1,
-    'should use relative config path (args.config || .pave) matching child convention');
-  assert(writeSection.indexOf('config: configDir') === -1,
-    'should NOT use absolute configDir');
-});
-
-runTest('index.js: daemon preliminary status is wrapped in try/catch (best-effort)', () => {
-  const daemonSection = getDaemonSection();
-  const prelimIdx = daemonSection.indexOf('preliminary status');
-  assert(prelimIdx !== -1, 'should have preliminary status comment');
-  const tryIdx = daemonSection.indexOf('try {', prelimIdx);
-  const writeIdx = daemonSection.indexOf('registry.writeStatus(agentName');
-  const catchIdx = daemonSection.indexOf('catch (statusErr)');
-  assert(tryIdx !== -1 && writeIdx !== -1 && catchIdx !== -1,
-    'writeStatus should be wrapped in try/catch');
-  assert(tryIdx < writeIdx && writeIdx < catchIdx,
-    'try should come before writeStatus, which should come before catch');
-});
-
-runTest('index.js: daemon preliminary status includes required fields', () => {
-  const daemonSection = getDaemonSection();
-  const writeSection = getWriteStatusSection(daemonSection);
-  assert(writeSection.indexOf('pid: child.pid') !== -1, 'should include pid');
-  assert(writeSection.indexOf('cwd: process.cwd()') !== -1, 'should include cwd');
-  assert(writeSection.indexOf('startedAt: Date.now()') !== -1, 'should include startedAt');
-  assert(writeSection.indexOf('iteration: 0') !== -1, 'should include iteration');
-});
-
-runTest('index.js: daemon pre-flight checks liveness before spawning', () => {
-  const daemonSection = getDaemonSection();
-  // Should check isAgentAlive BEFORE spawn() to prevent unnecessary child
-  const aliveIdx = daemonSection.indexOf('isAgentAlive(agentName)');
-  assert(aliveIdx !== -1,
-    'should call isAgentAlive in daemon block');
-  const spawnIdx = daemonSection.indexOf('spawn(process.execPath');
-  assert(spawnIdx !== -1, 'should have spawn call in daemon block');
-  // Liveness check must come BEFORE spawn
-  assert(aliveIdx < spawnIdx,
-    'isAgentAlive check should come BEFORE spawn() to avoid unnecessary child');
-  // Should abort with non-zero on duplicate
-  const alreadyRunningIdx = daemonSection.indexOf('already running');
-  assert(alreadyRunningIdx !== -1,
-    'should report already running error');
-  // The 'return 1' must come AFTER the 'already running' error and BEFORE spawn
-  const sectionBetween = daemonSection.substring(alreadyRunningIdx, spawnIdx);
-  assert(sectionBetween.indexOf('return 1') !== -1,
-    'should return 1 between already-running error and spawn call');
-});
-
-// ============================================================
-// Summary
-// ============================================================
-
-console.log('\nTotal: ' + (passed + failed) + ', Passed: ' + passed + ', Failed: ' + failed);
-if (failed > 0) process.exitCode = 1;