agentxchain 0.8.7 → 0.8.8

package/src/commands/init.js

@@ -52,7 +52,12 @@ export async function initCommand(opts) {
     project = 'My AgentXchain project';
     agents = DEFAULT_AGENTS;
     folderName = slugify(project);
-    rules = { max_consecutive_claims: 2, require_message: true, compress_after_words: 5000 };
+    rules = {
+      max_consecutive_claims: 2,
+      require_message: true,
+      compress_after_words: 5000,
+      strict_next_owner: false
+    };
   } else {
     const templates = loadTemplates();
 
@@ -86,7 +91,12 @@ export async function initCommand(opts) {
       project = projectName;
     } else if (template === 'default') {
       agents = DEFAULT_AGENTS;
-      rules = { max_consecutive_claims: 2, require_message: true, compress_after_words: 5000 };
+      rules = {
+      max_consecutive_claims: 2,
+      require_message: true,
+      compress_after_words: 5000,
+      strict_next_owner: false
+    };
       const { projectName } = await inquirer.prompt([{
         type: 'input',
         name: 'projectName',
@@ -103,7 +113,12 @@ export async function initCommand(opts) {
       }]);
       project = projectName;
       agents = {};
-      rules = { max_consecutive_claims: 2, require_message: true, compress_after_words: 5000 };
+      rules = {
+      max_consecutive_claims: 2,
+      require_message: true,
+      compress_after_words: 5000,
+      strict_next_owner: false
+    };
 
       const { count } = await inquirer.prompt([{
         type: 'number',
@@ -192,6 +207,7 @@ export async function initCommand(opts) {
       compress_after_words: rules.compress_after_words || 5000,
       ttl_minutes: rules.ttl_minutes || 10,
       watch_interval_ms: rules.watch_interval_ms || 5000,
+      strict_next_owner: rules.strict_next_owner === true,
       ...(rules.verify_command ? { verify_command: rules.verify_command } : {})
     }
   };
@@ -209,7 +225,7 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, 'TALK.md'), `# ${project} — Team Talk File\n\nCanonical human-readable handoff log for all agents.\n\n## How to write entries\n\nUse this exact structure:\n\n## Turn N — <agent_id> (<role>)\n- Status:\n- Decision:\n- Action:\n- Risks/Questions:\n- Next owner:\n\n---\n\n`);
   writeFileSync(join(dir, 'HUMAN_TASKS.md'), '# Human Tasks\n\n(Agents append tasks here when they need human action.)\n');
   const gitignorePath = join(dir, '.gitignore');
-  const requiredIgnores = ['.env', '.agentxchain-trigger.json', '.agentxchain-prompts/', '.agentxchain-workspaces/'];
+  const requiredIgnores = ['.env', '.agentxchain-trigger.json', '.agentxchain-prompts/', '.agentxchain-workspaces/', '.agentxchain-watch.pid', '.agentxchain-autonudge.state'];
   if (!existsSync(gitignorePath)) {
     writeFileSync(gitignorePath, requiredIgnores.join('\n') + '\n');
   } else {
@@ -230,10 +246,13 @@ export async function initCommand(opts) {
 
   writeFileSync(join(dir, '.planning', 'REQUIREMENTS.md'), `# Requirements — ${project}\n\n## v1 (MVP)\n\n(PM fills this: numbered list of requirements. Each requirement has one-sentence acceptance criteria.)\n\n| # | Requirement | Acceptance criteria | Phase | Status |\n|---|-------------|-------------------|-------|--------|\n| 1 | | | | Pending |\n\n## v2 (Future)\n\n(Out of scope for MVP. Captured here so they don't creep in.)\n\n## Out of scope\n\n(Explicitly not building.)\n`);
 
-  writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${project}\n\n## Phases\n\n| Phase | Description | Status | Requirements |\n|-------|-------------|--------|-------------|\n| 1 | Discovery + setup | In progress | — |\n\n(PM updates this as phases are planned and completed.)\n`);
+  writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${project}\n\n## Waves\n\n| Wave | Goal | Status |\n|------|------|--------|\n| Wave 1 | Discovery, planning, and phase setup | In progress |\n\n## Phases\n\n| Phase | Description | Status | Requirements |\n|-------|-------------|--------|-------------|\n| 1 | Discovery + setup | In progress | — |\n\n(PM updates this as phases are planned and completed.)\n`);
   writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${project}\n\nApproved: NO\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
 
   // QA structure
+  mkdirSync(join(dir, '.planning', 'phases', 'phase-1'), { recursive: true });
+  writeFileSync(join(dir, '.planning', 'phases', 'phase-1', 'PLAN.md'), `# Phase 1 Plan — ${project}\n\n## Goal\n\nAlign scope, requirements, and initial implementation plan.\n\n## Deliverables\n\n- PM signoff\n- Initial requirements and roadmap\n- First implementation slice\n`);
+  writeFileSync(join(dir, '.planning', 'phases', 'phase-1', 'TESTS.md'), `# Phase 1 Tests — ${project}\n\n## Planned checks\n\n- Kickoff validation passes\n- Requirements have acceptance criteria\n- First implementation slice has an executable verification path\n`);
   writeFileSync(join(dir, '.planning', 'qa', 'TEST-COVERAGE.md'), `# Test Coverage — ${project}\n\n## Coverage Map\n\n| Feature / Area | Unit tests | Integration tests | E2E tests | Manual QA | UX audit | Status |\n|---------------|-----------|------------------|----------|----------|---------|--------|\n| (QA fills this as testing progresses) | | | | | | |\n\n## Coverage gaps\n\n(Areas with no tests or insufficient coverage.)\n`);
 
   writeFileSync(join(dir, '.planning', 'qa', 'REGRESSION-LOG.md'), `# Regression Log — ${project}\n\nBugs that were found and fixed. Each entry has a regression test to prevent recurrence.\n\n| Bug ID | Description | Found turn | Fixed turn | Regression test | Status |\n|--------|-------------|-----------|-----------|----------------|--------|\n| (QA adds entries as bugs are found and fixed) | | | | | |\n`);

package/src/commands/stop.js

@@ -2,8 +2,10 @@ import { readFileSync, existsSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig } from '../lib/config.js';
+import { getWatchPid } from './watch.js';
 
 const SESSION_FILE = '.agentxchain-session.json';
+const WATCH_PID_FILE = '.agentxchain-watch.pid';
 
 export async function stopCommand() {
   const result = loadConfig();
@@ -11,47 +13,77 @@ export async function stopCommand() {
 
   const { root } = result;
   const sessionPath = join(root, SESSION_FILE);
+  const watchPidPath = join(root, WATCH_PID_FILE);
+  const watchPid = getWatchPid(root);
+  let didStopAnything = false;
 
-  if (!existsSync(sessionPath)) {
-    console.log(chalk.yellow('  No active session found.'));
-    console.log(chalk.dim('  If agents are running in VS Code / Cursor, close their chat sessions manually.'));
-    return;
+  if (watchPid) {
+    try {
+      process.kill(watchPid, 'SIGTERM');
+      didStopAnything = true;
+      console.log('');
+      console.log(chalk.green(`  ✓ Stopped watch process (PID: ${watchPid})`));
+      console.log('');
+    } catch (err) {
+      if (err.code === 'ESRCH') {
+        if (existsSync(watchPidPath)) {
+          try { unlinkSync(watchPidPath); } catch {}
+        }
+      } else {
+        console.log(chalk.red(`  ✗ Could not stop watch process (PID: ${watchPid}): ${err.message}`));
+      }
+    }
+  } else if (existsSync(watchPidPath)) {
+    // Stale PID file from an unexpected shutdown.
+    try {
+      unlinkSync(watchPidPath);
+      console.log(chalk.dim('  Removed stale watch PID file.'));
+    } catch {}
   }
 
-  let session;
-  try {
-    session = JSON.parse(readFileSync(sessionPath, 'utf8'));
-  } catch {
-    console.log(chalk.yellow('  Could not read session file.'));
-    return;
-  }
+  if (existsSync(sessionPath)) {
+    let session;
+    try {
+      session = JSON.parse(readFileSync(sessionPath, 'utf8'));
+    } catch {
+      console.log(chalk.yellow('  Could not read session file.'));
+      return;
+    }
+
+    console.log('');
+    console.log(chalk.bold(`  Stopping ${session.launched?.length || 0} agents (${session.ide || 'unknown'})`));
+    console.log('');
 
-  console.log('');
-  console.log(chalk.bold(`  Stopping ${session.launched?.length || 0} agents (${session.ide || 'unknown'})`));
-  console.log('');
-
-  if (session.ide === 'claude-code') {
-    for (const agent of (session.launched || [])) {
-      if (agent.pid) {
-        try {
-          process.kill(agent.pid, 'SIGTERM');
-          console.log(chalk.green(`  ✓ Sent SIGTERM to ${agent.id} (PID: ${agent.pid})`));
-        } catch (err) {
-          if (err.code === 'ESRCH') {
-            console.log(chalk.dim(`  ${agent.id} (PID: ${agent.pid}) — already stopped`));
-          } else {
-            console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
+    if (session.ide === 'claude-code') {
+      for (const agent of (session.launched || [])) {
+        if (agent.pid) {
+          try {
+            process.kill(agent.pid, 'SIGTERM');
+            didStopAnything = true;
+            console.log(chalk.green(`  ✓ Sent SIGTERM to ${agent.id} (PID: ${agent.pid})`));
+          } catch (err) {
+            if (err.code === 'ESRCH') {
+              console.log(chalk.dim(`  ${agent.id} (PID: ${agent.pid}) — already stopped`));
+            } else {
+              console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
+            }
           }
         }
       }
+    } else {
+      console.log(chalk.dim('  For VS Code / Cursor agents, close the chat sessions manually.'));
     }
-  } else {
-    console.log(chalk.dim('  For VS Code / Cursor agents, close the chat sessions manually.'));
+
+    unlinkSync(sessionPath);
+    console.log('');
+    console.log(chalk.dim('  Session file removed.'));
+    console.log(chalk.green('  Done.'));
+    console.log('');
+    return;
   }
 
-  unlinkSync(sessionPath);
-  console.log('');
-  console.log(chalk.dim('  Session file removed.'));
-  console.log(chalk.green('  Done.'));
-  console.log('');
+  if (!didStopAnything) {
+    console.log(chalk.yellow('  No active session found.'));
+    console.log(chalk.dim('  If agents are running in VS Code / Cursor, close their chat sessions manually.'));
+  }
 }

package/src/commands/update.js

@@ -4,6 +4,19 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import chalk from 'chalk';
 
+function printGlobalInstallFallbacks() {
+  console.log(chalk.dim('  If global install failed with permission errors (EACCES):'));
+  console.log(`    ${chalk.bold('sudo npm install -g agentxchain@latest')}  ${chalk.dim('(macOS/Linux)')}`);
+  console.log(`    ${chalk.bold('npm config get prefix')}  ${chalk.dim('— fix ownership of that directory, or use a user prefix:')}`);
+  console.log(`    ${chalk.bold('mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global')}`);
+  console.log(`    ${chalk.dim('(add ~/.npm-global/bin to PATH)')}`);
+  console.log(chalk.dim('  Or run without global install:'));
+  console.log(`    ${chalk.bold('npx agentxchain@latest <command>')}`);
+  console.log('');
+  console.log(chalk.dim('  Node: use 18.17+ or 20.5+ to avoid engine warnings from dependencies.'));
+  console.log('');
+}
+
 export async function updateCommand() {
   const __dirname = dirname(fileURLToPath(import.meta.url));
   const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'));
@@ -24,18 +37,26 @@ export async function updateCommand() {
 
     console.log(`  ${chalk.dim('Latest version:')}  ${chalk.cyan(latest)}`);
     console.log('');
-    console.log(`  Updating...`);
+    console.log('  Updating...');
 
-    execSync('npm install -g agentxchain@latest', { stdio: 'inherit' });
+    try {
+      execSync('npm install -g agentxchain@latest', { stdio: 'inherit' });
+    } catch {
+      console.log('');
+      console.log(chalk.yellow('  Global install failed. Common fixes:'));
+      printGlobalInstallFallbacks();
+      return;
+    }
 
     console.log('');
     console.log(chalk.green(`  ✓ Updated to ${latest}`));
     console.log('');
   } catch (err) {
     console.log('');
-    console.log(chalk.yellow('  Could not auto-update. Run manually:'));
+    console.log(chalk.yellow('  Could not check or install the latest version.'));
     console.log(`    ${chalk.bold('npm install -g agentxchain@latest')}`);
     console.log('');
+    printGlobalInstallFallbacks();
     console.log(chalk.dim(`  Error: ${err.message}`));
     console.log('');
   }

package/src/commands/watch.js

@@ -1,12 +1,15 @@
-import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, appendFileSync, unlinkSync } from 'fs';
 import { join, dirname } from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
+import { safeWriteJson } from '../lib/safe-write.js';
 import { notifyHuman as sendNotification } from '../lib/notify.js';
 import { validateProject } from '../lib/validation.js';
-import { resolveNextAgent } from '../lib/next-owner.js';
+import { resolveNextAgent, resolveExpectedClaimer } from '../lib/next-owner.js';
+
+const PID_FILE = '.agentxchain-watch.pid';
 
 export async function watchCommand(opts) {
   if (opts.daemon && process.env.AGENTXCHAIN_WATCH_DAEMON !== '1') {
@@ -37,12 +40,15 @@ export async function watchCommand(opts) {
   console.log(chalk.dim(`  Poll:    ${interval}ms | TTL: ${ttlMinutes}min`));
   console.log(chalk.dim(`  Mode:    Local file watcher + trigger file`));
   console.log('');
+  writePidFile(root);
+
   console.log(chalk.cyan('  Watching lock.json... (Ctrl+C to stop)'));
   console.log(chalk.dim('  Note: In VS Code/Cursor, the Stop hook coordinates turns automatically.'));
   console.log(chalk.dim('  This watch process is a fallback for non-IDE environments.'));
   console.log('');
 
   let lastState = null;
+  let lastClaimedState = null;
 
   const tick = async () => {
     try {
@@ -51,17 +57,6 @@ export async function watchCommand(opts) {
 
       const stateKey = `${lock.holder}:${lock.turn_number}`;
 
-      if (lock.holder && lock.holder !== 'human') {
-        const expected = pickNextAgent(root, lock, config);
-        if (!isValidClaimer(root, lock, config)) {
-          log('warn', `Illegal claim detected: holder=${lock.holder}, expected=${expected}. Handing lock to HUMAN.`);
-          blockOnIllegalClaim(root, lock, config, expected);
-          sendNotification(`Illegal claim detected (${lock.holder}). Human intervention required.`);
-          lastState = null;
-          return;
-        }
-      }
-
       if (lock.holder && lock.holder !== 'human' && lock.claimed_at) {
         const elapsed = Date.now() - new Date(lock.claimed_at).getTime();
         const ttlMs = ttlMinutes * 60 * 1000;
@@ -86,11 +81,27 @@ export async function watchCommand(opts) {
       }
 
       if (lock.holder) {
+        // Validate claim ownership only once per new claimed state.
+        // With handoff-driven routing, TALK.md may change during an active turn.
+        // Re-validating every tick can produce false "illegal claim" alerts.
+        if (stateKey !== lastClaimedState && lock.holder !== 'human') {
+          const expected = pickNextAgent(root, lock, config);
+          if (!isValidClaimer(root, lock, config)) {
+            log('warn', `Illegal claim detected: holder=${lock.holder}, expected=${expected ?? 'none'}. Handing lock to HUMAN.`);
+            blockOnIllegalClaim(root, lock, config, expected);
+            sendNotification(`Illegal claim detected (${lock.holder}). Human intervention required.`);
+            lastState = null;
+            lastClaimedState = null;
+            return;
+          }
+        }
+
         if (stateKey !== lastState) {
           const name = config.agents[lock.holder]?.name || lock.holder;
           log('claimed', `${lock.holder} (${name}) working... (turn ${lock.turn_number})`);
           lastState = stateKey;
         }
+        lastClaimedState = stateKey;
         return;
       }
 
@@ -109,7 +120,15 @@ export async function watchCommand(opts) {
           }
         }
 
-        const next = pickNextAgent(root, lock, config);
+        const resolved = resolveNextAgent(root, config, lock);
+        const next = resolved.next;
+        if (!next) {
+          log('warn', `No next owner (${resolved.source}). strict_next_owner requires TALK.md handoff. Handing lock to HUMAN.`);
+          blockOnMissingNext(root, lock, config, resolved.source);
+          sendNotification('No next owner in TALK.md. Human action required.');
+          lastState = null;
+          return;
+        }
         log('free', `Lock free (released by ${lock.last_released_by || 'none'}). Next: ${chalk.bold(next)}.`);
         writeTrigger(root, next, lock, config);
         lastState = stateKey;
@@ -122,12 +141,16 @@ export async function watchCommand(opts) {
   await tick();
   const timer = setInterval(tick, interval);
 
-  process.on('SIGINT', () => {
+  const cleanup = () => {
     clearInterval(timer);
+    removePidFile(root);
     console.log('');
     log('stop', 'Watch stopped.');
     process.exit(0);
-  });
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
 }
 
 function pickNextAgent(root, lock, config) {
@@ -137,7 +160,7 @@ function pickNextAgent(root, lock, config) {
 function isValidClaimer(root, lock, config) {
   if (!lock.holder || lock.holder === 'human') return true;
   if (!config.agents?.[lock.holder]) return false;
-  const expected = pickNextAgent(root, lock, config);
+  const expected = resolveExpectedClaimer(root, config, lock).next;
   return lock.holder === expected;
 }
 
@@ -146,10 +169,10 @@ function forceRelease(root, lock, staleAgent, config) {
   const newLock = {
     holder: null,
     last_released_by: `system:ttl:${staleAgent}`,
-    turn_number: lock.turn_number,
+    turn_number: lock.turn_number + 1,
     claimed_at: null
   };
-  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  safeWriteJson(lockPath, newLock);
 
   const logFile = config.log || 'log.md';
   const logPath = join(root, logFile);
@@ -161,12 +184,12 @@ function forceRelease(root, lock, staleAgent, config) {
 function writeTrigger(root, agentId, lock, config) {
   if (!agentId) return;
   const triggerPath = join(root, '.agentxchain-trigger.json');
-  writeFileSync(triggerPath, JSON.stringify({
+  safeWriteJson(triggerPath, {
     agent: agentId,
     turn_number: lock.turn_number,
     triggered_at: new Date().toISOString(),
     project: config.project
-  }, null, 2) + '\n');
+  });
 }
 
 function blockOnValidation(root, lock, config, validation) {
@@ -177,7 +200,7 @@ function blockOnValidation(root, lock, config, validation) {
     turn_number: lock.turn_number,
     claimed_at: new Date().toISOString()
   };
-  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  safeWriteJson(lockPath, newLock);
 
   const statePath = join(root, 'state.json');
   if (existsSync(statePath)) {
@@ -189,7 +212,7 @@ function blockOnValidation(root, lock, config, validation) {
         blocked: true,
         blocked_on: `validation: ${message}`
       };
-      writeFileSync(statePath, JSON.stringify(nextState, null, 2) + '\n');
+      safeWriteJson(statePath, nextState);
     } catch {}
   }
 
@@ -204,6 +227,39 @@ function blockOnValidation(root, lock, config, validation) {
   }
 }
 
+function blockOnMissingNext(root, lock, config, source) {
+  const lockPath = join(root, LOCK_FILE);
+  const newLock = {
+    holder: 'human',
+    last_released_by: lock.last_released_by,
+    turn_number: lock.turn_number,
+    claimed_at: new Date().toISOString()
+  };
+  safeWriteJson(lockPath, newLock);
+
+  const statePath = join(root, 'state.json');
+  if (existsSync(statePath)) {
+    try {
+      const current = JSON.parse(readFileSync(statePath, 'utf8'));
+      const nextState = {
+        ...current,
+        blocked: true,
+        blocked_on: `missing-next-owner: ${source}`
+      };
+      safeWriteJson(statePath, nextState);
+    } catch {}
+  }
+
+  const logFile = config.log || 'log.md';
+  const logPath = join(root, logFile);
+  if (existsSync(logPath)) {
+    appendFileSync(
+      logPath,
+      `\n---\n\n### [system] (Watch) | Turn ${lock.turn_number}\n\n**Status:** Could not resolve next agent (${source}).\n\n**Action:** Add \`Next owner: <agent_id>\` to ${config.talk_file || 'TALK.md'}, or set \`rules.strict_next_owner\` to false for cyclic fallback.\n\n`
+    );
+  }
+}
+
 function blockOnIllegalClaim(root, lock, config, expected) {
   const lockPath = join(root, LOCK_FILE);
   const newLock = {
@@ -212,7 +268,7 @@ function blockOnIllegalClaim(root, lock, config, expected) {
     turn_number: lock.turn_number,
     claimed_at: new Date().toISOString()
   };
-  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  safeWriteJson(lockPath, newLock);
 
   const statePath = join(root, 'state.json');
   if (existsSync(statePath)) {
@@ -223,7 +279,7 @@ function blockOnIllegalClaim(root, lock, config, expected) {
         blocked: true,
         blocked_on: `illegal-claim: expected ${expected}, got ${lock.holder}`
       };
-      writeFileSync(statePath, JSON.stringify(nextState, null, 2) + '\n');
+      safeWriteJson(statePath, nextState);
     } catch {}
   }
 
@@ -262,8 +318,39 @@ function startWatchDaemon() {
   });
   child.unref();
 
+  const result = loadConfig();
+  if (result) {
+    writeFileSync(join(result.root, PID_FILE), String(child.pid));
+  }
+
   console.log('');
   console.log(chalk.green(`  ✓ Watch started in daemon mode (PID: ${child.pid})`));
   console.log(chalk.dim('  Use `agentxchain stop` or kill the PID to stop it.'));
   console.log('');
 }
+
+function writePidFile(root) {
+  try {
+    writeFileSync(join(root, PID_FILE), String(process.pid));
+  } catch {}
+}
+
+function removePidFile(root) {
+  try {
+    const pidPath = join(root, PID_FILE);
+    if (existsSync(pidPath)) unlinkSync(pidPath);
+  } catch {}
+}
+
+export function getWatchPid(root) {
+  try {
+    const pidPath = join(root, PID_FILE);
+    if (!existsSync(pidPath)) return null;
+    const pid = parseInt(readFileSync(pidPath, 'utf8').trim(), 10);
+    if (!Number.isFinite(pid)) return null;
+    process.kill(pid, 0);
+    return pid;
+  } catch {
+    return null;
+  }
+}

package/src/lib/config.js

@@ -1,36 +1,71 @@
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, parse as pathParse, resolve } from 'path';
+import { safeParseJson, validateConfigSchema, validateLockSchema, validateStateSchema } from './schema.js';
 
 const CONFIG_FILE = 'agentxchain.json';
 const LOCK_FILE = 'lock.json';
 const STATE_FILE = 'state.json';
 
 export function findProjectRoot(startDir = process.cwd()) {
-  let dir = startDir;
-  while (dir !== '/') {
+  let dir = resolve(startDir);
+  const { root: fsRoot } = pathParse(dir);
+  while (true) {
     if (existsSync(join(dir, CONFIG_FILE))) return dir;
+    if (dir === fsRoot) return null;
     dir = join(dir, '..');
   }
-  return null;
 }
 
 export function loadConfig(dir = process.cwd()) {
   const root = findProjectRoot(dir);
   if (!root) return null;
-  const raw = readFileSync(join(root, CONFIG_FILE), 'utf8');
-  return { root, config: JSON.parse(raw) };
+  const filePath = join(root, CONFIG_FILE);
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  const result = safeParseJson(raw, validateConfigSchema);
+  if (!result.ok) {
+    console.error(`  Warning: agentxchain.json has issues: ${result.errors.join(', ')}`);
+    return null;
+  }
+  return { root, config: result.data };
 }
 
 export function loadLock(root) {
-  const path = join(root, LOCK_FILE);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, 'utf8'));
+  const filePath = join(root, LOCK_FILE);
+  if (!existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  const result = safeParseJson(raw, validateLockSchema);
+  if (!result.ok) {
+    console.error(`  Warning: lock.json has issues: ${result.errors.join(', ')}`);
+    return null;
+  }
+  return result.data;
 }
 
 export function loadState(root) {
-  const path = join(root, STATE_FILE);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, 'utf8'));
+  const filePath = join(root, STATE_FILE);
+  if (!existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  const result = safeParseJson(raw, validateStateSchema);
+  if (!result.ok) {
+    console.error(`  Warning: state.json has issues: ${result.errors.join(', ')}`);
+    return null;
+  }
+  return result.data;
 }
 
 export { CONFIG_FILE, LOCK_FILE, STATE_FILE };

package/src/lib/filter-agents.js

@@ -0,0 +1,12 @@
+import chalk from 'chalk';
+
+export function filterAgents(config, specificId) {
+  if (specificId) {
+    if (!config.agents[specificId]) {
+      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
+      process.exit(1);
+    }
+    return { [specificId]: config.agents[specificId] };
+  }
+  return config.agents;
+}