agentxchain 2.6.0 → 2.8.0

package/README.md

@@ -10,8 +10,10 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 
 - [Quickstart](https://agentxchain.dev/docs/quickstart/)
 - [CLI reference](https://agentxchain.dev/docs/cli/)
+- [Export schema reference](https://agentxchain.dev/docs/export-schema/)
 - [Adapter reference](https://agentxchain.dev/docs/adapters/)
 - [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
+- [Protocol reference](https://agentxchain.dev/docs/protocol-reference/)
 - [Why governed multi-agent delivery matters](https://agentxchain.dev/why/)
 
 ## Install

package/bin/agentxchain.js

@@ -65,6 +65,7 @@ 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';
@@ -72,6 +73,7 @@ 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 { reportCommand } from '../src/commands/report.js';
 import {
   pluginInstallCommand,
   pluginListCommand,
@@ -129,6 +131,13 @@ program
   .option('--output <path>', 'Write the export artifact to a file instead of stdout')
   .action(exportCommand);
 
+program
+  .command('report')
+  .description('Render a human-readable governance summary from an export artifact')
+  .option('--input <path>', 'Export artifact path, or "-" for stdin', '-')
+  .option('--format <format>', 'Output format: text, json, or markdown', 'text')
+  .action(reportCommand);
+
 program
   .command('start')
   .description('Launch legacy v3 agents in your IDE')
@@ -260,6 +269,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.6.0",
+  "version": "2.8.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/report.js

@@ -0,0 +1,51 @@
+import chalk from 'chalk';
+
+import { loadExportArtifact } from '../lib/export-verifier.js';
+import {
+  buildGovernanceReport,
+  formatGovernanceReportMarkdown,
+  formatGovernanceReportText,
+} from '../lib/report.js';
+
+function printAndExit(report, format, exitCode) {
+  if (format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(exitCode);
+  }
+
+  if (format === 'markdown') {
+    console.log(formatGovernanceReportMarkdown(report));
+    process.exit(exitCode);
+  }
+
+  if (format === 'text') {
+    if (report.overall === 'error') {
+      console.log(chalk.red(formatGovernanceReportText(report)));
+    } else if (report.overall === 'fail') {
+      console.log(chalk.red(formatGovernanceReportText(report)));
+    } else {
+      console.log(formatGovernanceReportText(report));
+    }
+    process.exit(exitCode);
+  }
+
+  console.error(`Unsupported report format "${format}". Use "text", "json", or "markdown".`);
+  process.exit(1);
+}
+
+export async function reportCommand(opts) {
+  const format = opts.format || 'text';
+  const loaded = loadExportArtifact(opts.input || '-', process.cwd());
+
+  if (!loaded.ok) {
+    printAndExit({
+      overall: 'error',
+      input: loaded.input,
+      message: loaded.error,
+    }, format, 2);
+    return;
+  }
+
+  const result = buildGovernanceReport(loaded.artifact, { input: loaded.input });
+  printAndExit(result.report, format, result.exitCode);
+}

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/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,
     };
   }
 

package/src/lib/export-verifier.js

@@ -187,6 +187,7 @@ function verifyRunExport(artifact, errors) {
   const expectedHistoryEntries = countJsonl(artifact.files, '.agentxchain/history.jsonl');
   const expectedDecisionEntries = countJsonl(artifact.files, '.agentxchain/decision-ledger.jsonl');
   const expectedHookAuditEntries = countJsonl(artifact.files, '.agentxchain/hook-audit.jsonl');
+  const expectedNotificationAuditEntries = countJsonl(artifact.files, '.agentxchain/notification-audit.jsonl');
   const expectedDispatchFiles = countDirectoryFiles(artifact.files, '.agentxchain/dispatch');
   const expectedStagingFiles = countDirectoryFiles(artifact.files, '.agentxchain/staging');
   const expectedIntakePresent = Object.keys(artifact.files).some((path) => path.startsWith('.agentxchain/intake/'));
@@ -201,6 +202,9 @@ function verifyRunExport(artifact, errors) {
   if (artifact.summary.hook_audit_entries !== expectedHookAuditEntries) {
     addError(errors, 'summary.hook_audit_entries', 'must match .agentxchain/hook-audit.jsonl entry count');
   }
+  if (artifact.summary.notification_audit_entries !== expectedNotificationAuditEntries) {
+    addError(errors, 'summary.notification_audit_entries', 'must match .agentxchain/notification-audit.jsonl entry count');
+  }
   if (artifact.summary.dispatch_artifact_files !== expectedDispatchFiles) {
     addError(errors, 'summary.dispatch_artifact_files', 'must match .agentxchain/dispatch file count');
   }

package/src/lib/export.js

@@ -24,6 +24,7 @@ const INCLUDED_ROOTS = [
   '.agentxchain/decision-ledger.jsonl',
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
+  '.agentxchain/notification-audit.jsonl',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -172,6 +173,7 @@ export function buildRunExport(startDir = process.cwd()) {
         history_entries: countJsonl(files, '.agentxchain/history.jsonl'),
         decision_entries: countJsonl(files, '.agentxchain/decision-ledger.jsonl'),
         hook_audit_entries: countJsonl(files, '.agentxchain/hook-audit.jsonl'),
+        notification_audit_entries: countJsonl(files, '.agentxchain/notification-audit.jsonl'),
         dispatch_artifact_files: countDirectoryFiles(files, '.agentxchain/dispatch'),
         staging_artifact_files: countDirectoryFiles(files, '.agentxchain/staging'),
         intake_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/intake/')),