agentxchain 2.5.0 → 2.7.0

package/bin/agentxchain.js

@@ -59,18 +59,20 @@ import { generateCommand } from '../src/commands/generate.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
-import { verifyProtocolCommand } from '../src/commands/verify.js';
+import { verifyExportCommand, verifyProtocolCommand } from '../src/commands/verify.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
 import { migrateCommand } from '../src/commands/migrate.js';
 import { resumeCommand } from '../src/commands/resume.js';
+import { escalateCommand } from '../src/commands/escalate.js';
 import { acceptTurnCommand } from '../src/commands/accept-turn.js';
 import { rejectTurnCommand } from '../src/commands/reject-turn.js';
 import { stepCommand } from '../src/commands/step.js';
 import { approveTransitionCommand } from '../src/commands/approve-transition.js';
 import { approveCompletionCommand } from '../src/commands/approve-completion.js';
 import { dashboardCommand } from '../src/commands/dashboard.js';
+import { exportCommand } from '../src/commands/export.js';
 import {
   pluginInstallCommand,
   pluginListCommand,
@@ -121,6 +123,13 @@ program
   .option('-j, --json', 'Output as JSON')
   .action(statusCommand);
 
+program
+  .command('export')
+  .description('Export the governed run audit surface as a single artifact')
+  .option('--format <format>', 'Export format (json)', 'json')
+  .option('--output <path>', 'Write the export artifact to a file instead of stdout')
+  .action(exportCommand);
+
 program
   .command('start')
   .description('Launch legacy v3 agents in your IDE')
@@ -231,6 +240,13 @@ verifyCmd
   .option('--format <format>', 'Output format: text or json', 'text')
   .action(verifyProtocolCommand);
 
+verifyCmd
+  .command('export')
+  .description('Verify an AgentXchain export artifact against its embedded file bytes and summaries')
+  .option('--input <path>', 'Export artifact path, or "-" for stdin', '-')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .action(verifyExportCommand);
+
 program
   .command('migrate')
   .description('Migrate a legacy v3 project to governed format')
@@ -245,6 +261,15 @@ program
   .option('--turn <id>', 'Target a specific retained turn when multiple exist')
   .action(resumeCommand);
 
+program
+  .command('escalate')
+  .description('Raise an operator escalation and block the governed run intentionally')
+  .requiredOption('--reason <reason>', 'Operator escalation summary')
+  .option('--detail <detail>', 'Longer escalation detail for status and ledger surfaces')
+  .option('--action <action>', 'Override the default recovery action string')
+  .option('--turn <id>', 'Target a specific active turn when multiple turns exist')
+  .action(escalateCommand);
+
 program
   .command('accept-turn')
   .description('Accept the currently staged governed turn result')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/escalate.js

@@ -0,0 +1,63 @@
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { raiseOperatorEscalation } from '../lib/governed-state.js';
+
+export async function escalateCommand(opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+
+  if (config.protocol_mode !== 'governed') {
+    console.log(chalk.red('The escalate command is only available for governed projects.'));
+    console.log(chalk.dim('Legacy projects use: agentxchain claim / release'));
+    process.exit(1);
+  }
+
+  const state = loadProjectState(root, config);
+  if (!state) {
+    console.log(chalk.red('No governed state.json found. Run `agentxchain init --governed` first.'));
+    process.exit(1);
+  }
+
+  const result = raiseOperatorEscalation(root, config, {
+    reason: opts.reason,
+    detail: opts.detail,
+    action: opts.action,
+    turnId: opts.turn,
+  });
+  if (!result.ok) {
+    console.log(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  const recovery = deriveRecoveryDescriptor(result.state);
+
+  console.log('');
+  console.log(chalk.yellow('  Run Escalated'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log('');
+  console.log(`  ${chalk.dim('Reason:')}   ${result.escalation.reason}`);
+  if (result.escalation.detail && result.escalation.detail !== result.escalation.reason) {
+    console.log(`  ${chalk.dim('Detail:')}   ${result.escalation.detail}`);
+  }
+  console.log(`  ${chalk.dim('Blocked:')}  ${result.state.blocked_on}`);
+  console.log(`  ${chalk.dim('Source:')}   operator`);
+  console.log(`  ${chalk.dim('Turn:')}     ${result.escalation.from_turn_id || 'none retained'}`);
+  if (result.escalation.from_role) {
+    console.log(`  ${chalk.dim('Role:')}     ${result.escalation.from_role}`);
+  }
+  console.log('');
+
+  if (recovery) {
+    console.log(`  ${chalk.dim('Typed:')}    ${recovery.typed_reason}`);
+    console.log(`  ${chalk.dim('Owner:')}    ${recovery.owner}`);
+    console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
+    console.log(`  ${chalk.dim('Retained:')} ${recovery.turn_retained ? 'yes' : 'no'}`);
+  }
+  console.log('');
+}

package/src/commands/export.js

@@ -0,0 +1,63 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { buildRunExport, buildCoordinatorExport } from '../lib/export.js';
+import { COORDINATOR_CONFIG_FILE } from '../lib/coordinator-config.js';
+import { safeWriteJson } from '../lib/safe-write.js';
+
+function detectExportKind(cwd) {
+  // Governed project takes priority (agentxchain.json)
+  if (existsSync(join(cwd, 'agentxchain.json'))) {
+    return 'governed';
+  }
+  // Coordinator workspace (agentxchain-multi.json)
+  if (existsSync(join(cwd, COORDINATOR_CONFIG_FILE))) {
+    return 'coordinator';
+  }
+  return null;
+}
+
+export async function exportCommand(options) {
+  const format = options.format || 'json';
+  if (format !== 'json') {
+    console.error(`Unsupported export format "${format}". Only "json" is supported in this slice.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const cwd = process.cwd();
+  const kind = detectExportKind(cwd);
+
+  let result;
+  try {
+    if (kind === 'governed') {
+      result = buildRunExport(cwd);
+    } else if (kind === 'coordinator') {
+      result = buildCoordinatorExport(cwd);
+    } else {
+      result = {
+        ok: false,
+        error: 'No governed project or coordinator workspace found. Run this inside an AgentXchain governed project or coordinator workspace.',
+      };
+    }
+  } catch (error) {
+    console.error(error.message || String(error));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!result.ok) {
+    console.error(result.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.output) {
+    const outputPath = resolve(cwd, options.output);
+    safeWriteJson(outputPath, result.export);
+    console.log(`Exported ${kind === 'coordinator' ? 'coordinator workspace' : 'governed run'} audit to ${options.output}`);
+    return;
+  }
+
+  console.log(JSON.stringify(result.export, null, 2));
+}

package/src/commands/resume.js

@@ -24,6 +24,7 @@ import {
   markRunBlocked,
   getActiveTurns,
   getActiveTurnCount,
+  reactivateGovernedRun,
   STATE_PATH,
 } from '../lib/governed-state.js';
 import { writeDispatchBundle, getDispatchTurnDir, getTurnStagingResultPath } from '../lib/dispatch-bundle.js';
@@ -154,6 +155,62 @@ export async function resumeCommand(opts) {
     }
   }
 
+  if (state.status === 'blocked' && activeCount > 0) {
+    let retainedTurn = null;
+    if (opts.turn) {
+      retainedTurn = activeTurns[opts.turn];
+      if (!retainedTurn) {
+        console.log(chalk.red(`No active turn found for --turn ${opts.turn}`));
+        process.exit(1);
+      }
+    } else if (activeCount > 1) {
+      console.log(chalk.red('Multiple retained turns exist. Use --turn <id> to specify which to re-dispatch.'));
+      for (const turn of Object.values(activeTurns)) {
+        console.log(`  ${chalk.yellow('●')} ${turn.turn_id} — ${chalk.bold(turn.assigned_role)} (${turn.status})`);
+      }
+      console.log('');
+      console.log(chalk.dim('Example: agentxchain resume --turn <turn_id>'));
+      process.exit(1);
+    } else {
+      retainedTurn = Object.values(activeTurns)[0];
+    }
+
+    if (retainedTurn.status === 'conflicted') {
+      console.log(chalk.red(`Turn ${retainedTurn.turn_id} is conflicted. Resolve the conflict before resuming.`));
+      process.exit(1);
+    }
+
+    console.log(chalk.yellow(`Re-dispatching blocked turn: ${retainedTurn.turn_id}`));
+    console.log(`  Role:    ${retainedTurn.assigned_role}`);
+    console.log(`  Attempt: ${retainedTurn.attempt}`);
+    console.log('');
+
+    const reactivated = reactivateGovernedRun(root, state, { via: 'resume --turn', notificationConfig: config });
+    if (!reactivated.ok) {
+      console.log(chalk.red(`Failed to reactivate blocked run: ${reactivated.error}`));
+      process.exit(1);
+    }
+    state = reactivated.state;
+
+    const bundleResult = writeDispatchBundle(root, state, config, { turnId: retainedTurn.turn_id });
+    if (!bundleResult.ok) {
+      console.log(chalk.red(`Failed to write dispatch bundle: ${bundleResult.error}`));
+      process.exit(1);
+    }
+    printDispatchBundleWarnings(bundleResult);
+
+    const hooksConfig = config.hooks || {};
+    if (hooksConfig.after_dispatch?.length > 0) {
+      const afterDispatchResult = runAfterDispatchHooks(root, hooksConfig, state, retainedTurn, config);
+      if (!afterDispatchResult.ok) {
+        process.exit(1);
+      }
+    }
+
+    printDispatchSummary(state, config, retainedTurn);
+    return;
+  }
+
   // §47: idle + no run_id → initialize new run
   if (state.status === 'idle' && !state.run_id) {
     const initResult = initializeGovernedRun(root, config);
@@ -165,10 +222,22 @@ export async function resumeCommand(opts) {
     console.log(chalk.green(`Initialized governed run: ${state.run_id}`));
   }
 
+  // §47: paused + run_id exists → resume same run
+  if (state.status === 'blocked' && state.run_id) {
+    const reactivated = reactivateGovernedRun(root, state, { via: 'resume', notificationConfig: config });
+    if (!reactivated.ok) {
+      console.log(chalk.red(`Failed to reactivate blocked run: ${reactivated.error}`));
+      process.exit(1);
+    }
+    state = reactivated.state;
+    console.log(chalk.green(`Resumed blocked run: ${state.run_id}`));
+  }
+
   // §47: paused + run_id exists → resume same run
   if (state.status === 'paused' && state.run_id) {
     state.status = 'active';
     state.blocked_on = null;
+    state.blocked_reason = null;
     state.escalation = null;
     safeWriteJson(statePath, state);
     console.log(chalk.green(`Resumed governed run: ${state.run_id}`));
@@ -203,7 +272,7 @@ export async function resumeCommand(opts) {
   const hooksConfig = config.hooks || {};
   const turn = state.current_turn;
   if (hooksConfig.after_dispatch?.length > 0) {
-    const afterDispatchResult = runAfterDispatchHooks(root, hooksConfig, state, turn);
+    const afterDispatchResult = runAfterDispatchHooks(root, hooksConfig, state, turn, config);
     if (!afterDispatchResult.ok) {
       process.exit(1);
     }
@@ -259,7 +328,7 @@ function resolveTargetRole(opts, state, config) {
   return null;
 }
 
-function runAfterDispatchHooks(root, hooksConfig, state, turn) {
+function runAfterDispatchHooks(root, hooksConfig, state, turn, config) {
   const turnId = turn.turn_id;
   const roleId = turn.assigned_role;
 
@@ -300,6 +369,7 @@ function runAfterDispatchHooks(root, hooksConfig, state, turn) {
         detail,
       },
       turnId,
+      notificationConfig: config,
     });
 
     printDispatchHookFailure({

package/src/commands/step.js

@@ -32,6 +32,7 @@ import {
   markRunBlocked,
   getActiveTurnCount,
   getActiveTurns,
+  reactivateGovernedRun,
   STATE_PATH,
 } from '../lib/governed-state.js';
 import { getMaxConcurrentTurns } from '../lib/normalized-config.js';
@@ -203,8 +204,12 @@ export async function stepCommand(opts) {
       }
 
       console.log(chalk.yellow(`Re-dispatching blocked turn: ${targetTurn.turn_id}`));
-      state = clearBlockedState(state);
-      safeWriteJson(join(root, STATE_PATH), state);
+      const reactivated = reactivateGovernedRun(root, state, { via: 'step --resume', notificationConfig: config });
+      if (!reactivated.ok) {
+        console.log(chalk.red(`Failed to reactivate blocked run: ${reactivated.error}`));
+        process.exit(1);
+      }
+      state = reactivated.state;
       skipAssignment = true;
 
       const bundleResult = writeDispatchBundle(root, state, config);
@@ -251,8 +256,12 @@ export async function stepCommand(opts) {
 
     // paused → resume
     if (!skipAssignment && state.status === 'blocked' && state.run_id) {
-      state = clearBlockedState(state);
-      safeWriteJson(join(root, STATE_PATH), state);
+      const reactivated = reactivateGovernedRun(root, state, { via: 'step', notificationConfig: config });
+      if (!reactivated.ok) {
+        console.log(chalk.red(`Failed to reactivate blocked run: ${reactivated.error}`));
+        process.exit(1);
+      }
+      state = reactivated.state;
       console.log(chalk.green(`Resumed blocked run: ${state.run_id}`));
     }
 
@@ -332,6 +341,7 @@ export async function stepCommand(opts) {
         hookResults: afterDispatchHooks,
         phase: 'after_dispatch',
         defaultDetail: `after_dispatch hook blocked dispatch for turn ${turn.turn_id}`,
+        config,
       });
       printLifecycleHookFailure('Dispatch Blocked By Hook', blocked.result, {
         turnId: turn.turn_id,
@@ -382,6 +392,7 @@ export async function stepCommand(opts) {
         },
         turnId: turn.turn_id,
         hooksConfig,
+        notificationConfig: config,
       });
       if (blocked.ok) {
         state = blocked.state;
@@ -462,6 +473,7 @@ export async function stepCommand(opts) {
         },
         turnId: turn.turn_id,
         hooksConfig,
+        notificationConfig: config,
       });
       if (blocked.ok) {
         state = blocked.state;
@@ -530,6 +542,7 @@ export async function stepCommand(opts) {
         },
         turnId: turn.turn_id,
         hooksConfig,
+        notificationConfig: config,
       });
       if (blocked.ok) {
         state = blocked.state;
@@ -556,6 +569,7 @@ export async function stepCommand(opts) {
         },
         turnId: turn.turn_id,
         hooksConfig,
+        notificationConfig: config,
       });
       if (blocked.ok) {
         state = blocked.state;
@@ -643,6 +657,7 @@ export async function stepCommand(opts) {
         hookResults: beforeValidationHooks,
         phase: 'before_validation',
         defaultDetail: `before_validation hook blocked validation for turn ${turn.turn_id}`,
+        config,
       });
       printLifecycleHookFailure('Validation Blocked By Hook', blocked.result, {
         turnId: turn.turn_id,
@@ -674,6 +689,7 @@ export async function stepCommand(opts) {
         hookResults: afterValidationHooks,
         phase: 'after_validation',
         defaultDetail: `after_validation hook blocked acceptance for turn ${turn.turn_id}`,
+        config,
       });
       printLifecycleHookFailure('Validation Blocked By Hook', blocked.result, {
         turnId: turn.turn_id,
@@ -758,7 +774,7 @@ function loadHookStagedTurn(root, stagingRel) {
   }
 }
 
-function blockStepForHookIssue(root, turn, { hookResults, phase, defaultDetail }) {
+function blockStepForHookIssue(root, turn, { hookResults, phase, defaultDetail, config }) {
   const hookName = hookResults.blocker?.hook_name
     || hookResults.results?.find((entry) => entry.hook_name)?.hook_name
     || 'unknown';
@@ -777,6 +793,7 @@ function blockStepForHookIssue(root, turn, { hookResults, phase, defaultDetail }
       detail,
     },
     turnId: turn.turn_id,
+    notificationConfig: config,
   });
 
   return {
@@ -860,16 +877,6 @@ function resolveTargetRole(opts, state, config) {
   return null;
 }
 
-function clearBlockedState(state) {
-  return {
-    ...state,
-    status: 'active',
-    blocked_on: null,
-    blocked_reason: null,
-    escalation: null,
-  };
-}
-
 function printRecoverySummary(state, heading) {
   const recovery = deriveRecoveryDescriptor(state);
   console.log(chalk.yellow(heading));

package/src/commands/verify.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { resolve } from 'node:path';
+import { loadExportArtifact, verifyExportArtifact } from '../lib/export-verifier.js';
 import { verifyProtocolConformance } from '../lib/protocol-conformance.js';
 
 export async function verifyProtocolCommand(opts) {
@@ -35,6 +36,38 @@ export async function verifyProtocolCommand(opts) {
   process.exit(result.exitCode);
 }
 
+export async function verifyExportCommand(opts) {
+  const format = opts.format || 'text';
+  const loaded = loadExportArtifact(opts.input || '-', process.cwd());
+
+  if (!loaded.ok) {
+    if (format === 'json') {
+      console.log(JSON.stringify({
+        overall: 'error',
+        input: loaded.input,
+        message: loaded.error,
+      }, null, 2));
+    } else {
+      console.log(chalk.red(`Export verification failed: ${loaded.error}`));
+    }
+    process.exit(2);
+  }
+
+  const result = verifyExportArtifact(loaded.artifact);
+  const report = {
+    ...result.report,
+    input: loaded.input,
+  };
+
+  if (format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printExportReport(report);
+  }
+
+  process.exit(result.ok ? 0 : 1);
+}
+
 function printProtocolReport(report) {
   console.log('');
   console.log(chalk.bold('  AgentXchain Protocol Conformance'));
@@ -74,3 +107,30 @@ function printProtocolReport(report) {
 
   console.log('');
 }
+
+function printExportReport(report) {
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Export Verification'));
+  console.log(chalk.dim('  ' + '─'.repeat(43)));
+  console.log(chalk.dim(`  Input: ${report.input}`));
+  console.log(chalk.dim(`  Export kind: ${report.export_kind || 'unknown'}`));
+  console.log(chalk.dim(`  Schema: ${report.schema_version || 'unknown'}`));
+  console.log('');
+
+  const overallLabel = report.overall === 'pass'
+    ? chalk.green('PASS')
+    : report.overall === 'fail'
+      ? chalk.red('FAIL')
+      : chalk.red('ERROR');
+  console.log(`  Overall: ${overallLabel}`);
+  console.log(chalk.dim(`  Files verified: ${report.file_count}`));
+  if (report.repo_count) {
+    console.log(chalk.dim(`  Embedded repos: ${report.repo_count}`));
+  }
+
+  for (const error of report.errors || []) {
+    console.log(chalk.red(`    ✗ ${error}`));
+  }
+
+  console.log('');
+}

package/src/lib/blocked-state.js

@@ -65,12 +65,16 @@ export function deriveRecoveryDescriptor(state) {
   }
 
   if (state.blocked_on.startsWith('escalation:')) {
+    const isOperatorEscalation = state.blocked_on.startsWith('escalation:operator:') || state.escalation?.source === 'operator';
+    const recoveryAction = turnRetained
+      ? 'Resolve the escalation, then run agentxchain step --resume'
+      : 'Resolve the escalation, then run agentxchain step';
     return {
-      typed_reason: 'retries_exhausted',
+      typed_reason: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
       owner: 'human',
-      recovery_action: 'Resolve the escalation, then run agentxchain step --resume',
+      recovery_action: recoveryAction,
       turn_retained: turnRetained,
-      detail: state.blocked_on,
+      detail: state.escalation?.detail || state.escalation?.reason || state.blocked_on,
     };
   }