agentxchain 0.8.7 → 2.1.1

package/src/commands/approve-completion.js

@@ -0,0 +1,80 @@
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { approveRunCompletion } from '../lib/governed-state.js';
+import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+
+export async function approveCompletionCommand(opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  if (context.config.protocol_mode !== 'governed') {
+    console.log(chalk.red('approve-completion is only available in governed mode.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+  const state = loadProjectState(root, config);
+
+  if (!state?.pending_run_completion) {
+    console.log(chalk.yellow('No pending run completion to approve.'));
+    if (state?.status === 'completed') {
+      console.log(chalk.dim('  This run is already completed.'));
+    } else if (state?.phase) {
+      console.log(chalk.dim(`  Current phase: ${state.phase}, status: ${state.status}`));
+    }
+    process.exit(1);
+  }
+
+  const pc = state.pending_run_completion;
+  console.log('');
+  console.log(chalk.bold('  Approving Run Completion'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Phase:')}  ${state.phase}`);
+  console.log(`  ${chalk.dim('Gate:')}   ${pc.gate}`);
+  console.log(`  ${chalk.dim('Turn:')}   ${pc.requested_by_turn}`);
+  console.log('');
+
+  const result = approveRunCompletion(root, config);
+
+  if (!result.ok) {
+    if (result.error_code?.startsWith('hook_') || result.error_code === 'hook_blocked') {
+      printGateHookFailure(result, 'run_completion', pc);
+    } else {
+      console.log(chalk.red(`  Failed: ${result.error}`));
+    }
+    process.exit(1);
+  }
+
+  console.log(chalk.green('  \u2713 Run completed'));
+  console.log(chalk.dim(`  Completed at: ${result.state.completed_at}`));
+  console.log('');
+}
+
+function printGateHookFailure(result, gateType, gateInfo) {
+  const recovery = deriveRecoveryDescriptor(result.state);
+  const hookName = result.hookResults?.blocker?.hook_name
+    || result.hookResults?.results?.find((entry) => entry.hook_name)?.hook_name
+    || '(unknown)';
+
+  console.log('');
+  console.log(chalk.yellow(`  ${gateType === 'phase_transition' ? 'Phase Transition' : 'Run Completion'} Blocked By Hook`));
+  console.log(chalk.dim('  ' + '-'.repeat(44)));
+  console.log('');
+  console.log(`  ${chalk.dim('Gate:')}     ${gateInfo.gate}`);
+  console.log(`  ${chalk.dim('Hook:')}     ${hookName}`);
+  console.log(`  ${chalk.dim('Error:')}    ${result.error}`);
+  if (recovery) {
+    console.log(`  ${chalk.dim('Reason:')}   ${recovery.typed_reason}`);
+    console.log(`  ${chalk.dim('Owner:')}    ${recovery.owner}`);
+    console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
+    if (recovery.detail) {
+      console.log(`  ${chalk.dim('Detail:')}   ${recovery.detail}`);
+    }
+  } else {
+    console.log(`  ${chalk.dim('Action:')}   Fix or reconfigure hook "${hookName}", then rerun agentxchain approve-completion`);
+  }
+  console.log('');
+}

package/src/commands/approve-transition.js

@@ -0,0 +1,85 @@
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { approvePhaseTransition } from '../lib/governed-state.js';
+import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+
+export async function approveTransitionCommand(opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  if (context.config.protocol_mode !== 'governed') {
+    console.log(chalk.red('approve-transition is only available in governed mode.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+  const state = loadProjectState(root, config);
+
+  if (!state?.pending_phase_transition) {
+    console.log(chalk.yellow('No pending phase transition to approve.'));
+    if (state?.phase) {
+      console.log(chalk.dim(`  Current phase: ${state.phase}`));
+    }
+    process.exit(1);
+  }
+
+  const pt = state.pending_phase_transition;
+  console.log('');
+  console.log(chalk.bold('  Approving Phase Transition'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('From:')}  ${pt.from}`);
+  console.log(`  ${chalk.dim('To:')}    ${pt.to}`);
+  console.log(`  ${chalk.dim('Gate:')}  ${pt.gate}`);
+  console.log(`  ${chalk.dim('Turn:')}  ${pt.requested_by_turn}`);
+  console.log('');
+
+  const result = approvePhaseTransition(root, config);
+
+  if (!result.ok) {
+    if (result.error_code?.startsWith('hook_') || result.error_code === 'hook_blocked') {
+      printGateHookFailure(result, 'phase_transition', pt);
+    } else {
+      console.log(chalk.red(`  Failed: ${result.error}`));
+    }
+    process.exit(1);
+  }
+
+  console.log(chalk.green(`  ✓ Phase advanced: ${pt.from} → ${pt.to}`));
+  console.log(chalk.dim(`  Run status: ${result.state.status}`));
+  console.log('');
+  console.log(chalk.dim(`  Next: agentxchain step  (to run the first turn in ${pt.to} phase)`));
+  console.log('');
+}
+
+function printGateHookFailure(result, gateType, gateInfo) {
+  const recovery = deriveRecoveryDescriptor(result.state);
+  const hookName = result.hookResults?.blocker?.hook_name
+    || result.hookResults?.results?.find((entry) => entry.hook_name)?.hook_name
+    || '(unknown)';
+
+  console.log('');
+  console.log(chalk.yellow(`  ${gateType === 'phase_transition' ? 'Phase Transition' : 'Run Completion'} Blocked By Hook`));
+  console.log(chalk.dim('  ' + '-'.repeat(44)));
+  console.log('');
+  if (gateType === 'phase_transition') {
+    console.log(`  ${chalk.dim('From:')}     ${gateInfo.from}`);
+    console.log(`  ${chalk.dim('To:')}       ${gateInfo.to}`);
+  }
+  console.log(`  ${chalk.dim('Gate:')}     ${gateInfo.gate}`);
+  console.log(`  ${chalk.dim('Hook:')}     ${hookName}`);
+  console.log(`  ${chalk.dim('Error:')}    ${result.error}`);
+  if (recovery) {
+    console.log(`  ${chalk.dim('Reason:')}   ${recovery.typed_reason}`);
+    console.log(`  ${chalk.dim('Owner:')}    ${recovery.owner}`);
+    console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
+    if (recovery.detail) {
+      console.log(`  ${chalk.dim('Detail:')}   ${recovery.detail}`);
+    }
+  } else {
+    console.log(`  ${chalk.dim('Action:')}   Fix or reconfigure hook "${hookName}", then rerun agentxchain approve-transition`);
+  }
+  console.log('');
+}

package/src/commands/branch.js

@@ -1,7 +1,7 @@
-import { writeFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+import { safeWriteJson } from '../lib/safe-write.js';
 import { getCurrentBranch } from '../lib/repo.js';
 
 export async function branchCommand(name, opts) {
@@ -94,5 +94,5 @@ function setBranchOverride(config, configPath, branch) {
 }
 
 function saveConfig(configPath, config) {
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  safeWriteJson(configPath, config);
 }

package/src/commands/claim.js

@@ -1,8 +1,10 @@
-import { writeFileSync, existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
-import { resolveNextAgent } from '../lib/next-owner.js';
+import { safeWriteJson } from '../lib/safe-write.js';
+import { resolveExpectedClaimer } from '../lib/next-owner.js';
+import { runConfiguredVerify } from '../lib/verify-command.js';
 
 export async function claimCommand(opts) {
   const result = loadConfig();
@@ -40,7 +42,12 @@ export async function claimCommand(opts) {
     turn_number: lock.turn_number,
     claimed_at: new Date().toISOString()
   };
-  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  safeWriteJson(lockPath, newLock);
+  const verify = loadLock(root);
+  if (verify?.holder !== 'human') {
+    console.log(chalk.red(`  Claim race: expected holder=human, got ${verify?.holder}. Another process won.`));
+    process.exit(1);
+  }
   clearBlockedState(root);
 
   console.log('');
@@ -76,6 +83,11 @@ export async function releaseCommand(opts) {
   }
 
   const who = lock.holder;
+  const verifyResult = runConfiguredVerify(config, root);
+  if (!verifyResult.ok) {
+    console.log(chalk.red(`  Verification failed: ${verifyResult.command}`));
+    process.exit(1);
+  }
   const lockPath = join(root, LOCK_FILE);
   const newLock = {
     holder: null,
@@ -83,14 +95,19 @@ export async function releaseCommand(opts) {
     turn_number: who === 'human' ? lock.turn_number : lock.turn_number + 1,
     claimed_at: null
   };
-  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  safeWriteJson(lockPath, newLock);
+  const verify = loadLock(root);
+  if (verify?.holder !== null || verify?.last_released_by !== who || verify?.turn_number !== newLock.turn_number) {
+    console.log(chalk.red('  Release race: lock.json changed unexpectedly after release attempt.'));
+    process.exit(1);
+  }
   if (who === 'human') {
     clearBlockedState(root);
   }
 
   console.log('');
   console.log(chalk.green(`  ✓ Lock released by ${chalk.bold(who)} (turn ${newLock.turn_number})`));
-  console.log(chalk.dim('  The Stop hook will coordinate the next agent turn in VS Code.'));
+  console.log(chalk.dim('  Next turn will be coordinated by the VS Code Stop hook or watch/supervise.'));
   console.log('');
 }
 
@@ -108,11 +125,25 @@ function claimAsAgent({ opts, root, config, lock }) {
   }
 
   const expected = pickNextAgent(root, lock, config);
+  if (!opts.force && config.rules?.strict_next_owner && (expected === null || expected === undefined)) {
+    console.log(chalk.red('  No next owner resolved. Add a valid `Next owner: <agent_id>` line to TALK.md, or set rules.strict_next_owner to false.'));
+    process.exit(1);
+  }
   if (!opts.force && expected && expected !== agentId) {
     console.log(chalk.red(`  Out-of-turn claim blocked. Expected: ${expected}, got: ${agentId}.`));
     process.exit(1);
   }
 
+  const maxClaims = Number(config.rules?.max_consecutive_claims || 0);
+  if (!opts.force && maxClaims > 0 && lock.last_released_by === agentId) {
+    const consecutiveTurns = countRecentTurnsByAgent(root, config, agentId);
+    if (consecutiveTurns >= maxClaims) {
+      console.log(chalk.red(`  Consecutive-claim limit reached for "${agentId}" (${consecutiveTurns}/${maxClaims}).`));
+      console.log(chalk.dim('  Hand off to another agent or use --force for recovery only.'));
+      process.exit(1);
+    }
+  }
+
   const lockPath = join(root, LOCK_FILE);
   const next = {
     holder: agentId,
@@ -120,7 +151,14 @@ function claimAsAgent({ opts, root, config, lock }) {
     turn_number: lock.turn_number,
     claimed_at: new Date().toISOString()
   };
-  writeFileSync(lockPath, JSON.stringify(next, null, 2) + '\n');
+  safeWriteJson(lockPath, next);
+
+  const verify = loadLock(root);
+  if (verify?.holder !== agentId) {
+    console.log(chalk.red(`  Claim race: expected holder=${agentId}, got ${verify?.holder}. Another process won.`));
+    process.exit(1);
+  }
+
   console.log(chalk.green(`  ✓ Lock claimed by ${agentId} (turn ${next.turn_number})`));
 }
 
@@ -135,6 +173,12 @@ function releaseAsAgent({ opts, root, config, lock }) {
     process.exit(1);
   }
 
+  const verifyResult = runConfiguredVerify(config, root);
+  if (!verifyResult.ok) {
+    console.log(chalk.red(`  Verification failed: ${verifyResult.command}`));
+    process.exit(1);
+  }
+
   const lockPath = join(root, LOCK_FILE);
   const next = {
     holder: null,
@@ -142,12 +186,21 @@ function releaseAsAgent({ opts, root, config, lock }) {
     turn_number: lock.turn_number + 1,
     claimed_at: null
   };
-  writeFileSync(lockPath, JSON.stringify(next, null, 2) + '\n');
+  safeWriteJson(lockPath, next);
+  const verifyRelease = loadLock(root);
+  if (
+    verifyRelease?.holder !== null ||
+    verifyRelease?.last_released_by !== agentId ||
+    verifyRelease?.turn_number !== next.turn_number
+  ) {
+    console.log(chalk.red('  Release race: lock.json changed unexpectedly after release attempt.'));
+    process.exit(1);
+  }
   console.log(chalk.green(`  ✓ Lock released by ${agentId} (turn ${next.turn_number})`));
 }
 
 function pickNextAgent(root, lock, config) {
-  return resolveNextAgent(root, config, lock).next;
+  return resolveExpectedClaimer(root, config, lock).next;
 }
 
 function clearBlockedState(root) {
@@ -157,7 +210,29 @@ function clearBlockedState(root) {
     const state = JSON.parse(readFileSync(statePath, 'utf8'));
     if (state.blocked || state.blocked_on) {
       const next = { ...state, blocked: false, blocked_on: null };
-      writeFileSync(statePath, JSON.stringify(next, null, 2) + '\n');
+      safeWriteJson(statePath, next);
     }
   } catch {}
 }
+
+function countRecentTurnsByAgent(root, config, agentId) {
+  const historyPath = join(root, config.history_file || 'history.jsonl');
+  if (!existsSync(historyPath)) return 0;
+
+  try {
+    const lines = readFileSync(historyPath, 'utf8')
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(Boolean);
+
+    let count = 0;
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      const entry = JSON.parse(lines[i]);
+      if (entry?.agent !== agentId) break;
+      count += 1;
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}

package/src/commands/config.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+import { validateConfigSchema } from '../lib/schema.js';
 
 export async function configCommand(opts) {
   const result = loadConfig();
@@ -127,6 +128,12 @@ function setSetting(config, configPath, keyValPair) {
   const key = parts[0];
   const rawVal = parts.slice(1).join(' ');
   const segments = key.split('.');
+  const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
+
+  if (segments.some(segment => forbiddenKeys.has(segment))) {
+    console.log(chalk.red('  Refusing to write reserved object path.'));
+    process.exit(1);
+  }
 
   let target = config;
   for (let i = 0; i < segments.length - 1; i++) {
@@ -145,6 +152,15 @@ function setSetting(config, configPath, keyValPair) {
   else if (!isNaN(rawVal) && rawVal !== '') val = Number(rawVal);
 
   target[lastKey] = val;
+  const validation = validateConfigSchema(config);
+  if (!validation.ok) {
+    target[lastKey] = oldVal;
+    if (oldVal === undefined) {
+      delete target[lastKey];
+    }
+    console.log(chalk.red(`  Refusing to save invalid config: ${validation.errors.join(', ')}`));
+    process.exit(1);
+  }
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 
   console.log('');

package/src/commands/dashboard.js

@@ -0,0 +1,70 @@
+/**
+ * CLI command: agentxchain dashboard
+ *
+ * Starts the read-only dashboard bridge server and opens a browser.
+ * See: V2_DASHBOARD_SPEC.md, DEC-DASH-002 (read-only in v2.0).
+ */
+
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createBridgeServer } from '../lib/dashboard/bridge-server.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_PORT = 3847;
+
+export async function dashboardCommand(options) {
+  const cwd = process.cwd();
+  const agentxchainDir = join(cwd, '.agentxchain');
+  const dashboardDir = join(__dirname, '..', '..', 'dashboard');
+
+  if (!existsSync(agentxchainDir)) {
+    console.error('Error: No .agentxchain/ directory found in the current directory.');
+    console.error('Run "agentxchain init --governed" first to create a governed project.');
+    process.exit(1);
+  }
+
+  if (!existsSync(dashboardDir)) {
+    console.error('Error: Dashboard assets not found at', dashboardDir);
+    process.exit(1);
+  }
+
+  const port = parseInt(options.port, 10) || DEFAULT_PORT;
+  const bridge = createBridgeServer({ agentxchainDir, dashboardDir, port });
+
+  try {
+    const { port: actualPort } = await bridge.start();
+    const url = `http://localhost:${actualPort}`;
+
+    console.log(`Dashboard running at ${url}`);
+    console.log('Press Ctrl+C to stop.\n');
+
+    if (options.open !== false) {
+      try {
+        const { exec } = await import('child_process');
+        const openCmd = process.platform === 'darwin' ? 'open'
+          : process.platform === 'win32' ? 'start'
+          : 'xdg-open';
+        exec(`${openCmd} ${url}`);
+      } catch {
+        // Browser open is best-effort
+      }
+    }
+
+    // Keep running until interrupted
+    const shutdown = async () => {
+      console.log('\nShutting down dashboard...');
+      await bridge.stop();
+      process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`Error: Port ${port} is already in use. Try --port <number>.`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}

package/src/commands/doctor.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock } from '../lib/config.js';
 import { validateProject } from '../lib/validation.js';
+import { getWatchPid } from './watch.js';
 
 export async function doctorCommand() {
   const result = loadConfig();
@@ -86,9 +87,16 @@ function checkPm(config) {
 }
 
 function checkWatchProcess() {
+  const result = loadConfig();
+  if (result) {
+    const pid = getWatchPid(result.root);
+    if (pid) {
+      return { name: 'watch process', level: 'pass', detail: `watch running (PID: ${pid})` };
+    }
+  }
   try {
     execSync('pgrep -f "agentxchain.*watch" >/dev/null', { stdio: 'ignore' });
-    return { name: 'watch process', level: 'pass', detail: 'watch appears to be running' };
+    return { name: 'watch process', level: 'pass', detail: 'watch appears to be running (no PID file)' };
   } catch {
     return { name: 'watch process', level: 'warn', detail: 'watch not running (start with `agentxchain watch` or `agentxchain supervise --autonudge`)' };
   }