agentxchain 2.156.0 → 2.158.0

package/bin/agentxchain.js

@@ -124,6 +124,8 @@ import { benchmarkCommand } from '../src/commands/benchmark.js';
 import { benchmarkWorkloadsCommand } from '../src/commands/benchmark-workloads.js';
 import { historyCommand } from '../src/commands/history.js';
 import { decisionsCommand } from '../src/commands/decisions.js';
+import { shipStatusCommand } from '../src/commands/ship-status.js';
+import { attentionCommand } from '../src/commands/attention.js';
 import { diffCommand } from '../src/commands/diff.js';
 import { eventsCommand } from '../src/commands/events.js';
 import { connectorCapabilitiesCommand, connectorCheckCommand, connectorValidateCommand } from '../src/commands/connector.js';
@@ -420,6 +422,22 @@ program
   .option('-d, --dir <path>', 'Project directory')
   .action(decisionsCommand);
 
+program
+  .command('ship-status')
+  .description('Evaluate whether the current project is ready to ship')
+  .option('-j, --json', 'Machine-readable JSON output')
+  .option('-v, --verbose', 'Per-dimension detail breakdown')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(shipStatusCommand);
+
+program
+  .command('attention')
+  .description('Show the cross-run human-decision queue — what needs you, and nothing else (govern by exception)')
+  .option('-j, --json', 'Machine-readable JSON output (full HumanAttentionReport)')
+  .option('-a, --all', 'Include informational/non-blocking items (e.g. pending approved intents)')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(attentionCommand);
+
 program
   .command('diff <left_ref> <right_ref>')
   .description('Compare two recorded governed runs or two export artifacts')

package/package.json

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

package/src/commands/attention.js

@@ -0,0 +1,66 @@
+/**
+ * CLI command: agentxchain attention
+ *
+ * Answers "what needs MY attention right now — and nothing else?" by composing the
+ * cross-category human-decision queue into a single HumanAttentionReport. All evaluation
+ * logic lives in lib/human-attention.js — this command is presentation only
+ * (Architecture Invariant #6).
+ *
+ * It is a status surface, not a gate: it exits 0 in BOTH the clear and attention states.
+ * When the queue is empty it prints "Nothing needs your attention." — the operational
+ * proof that the human can step back and let governed autonomy run (VISION.md:51).
+ */
+
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { evaluateHumanAttention } from '../lib/human-attention.js';
+
+export async function attentionCommand(opts) {
+  const dir = opts.dir ? resolve(opts.dir) : process.cwd();
+  const root = findProjectRoot(dir);
+  if (!root) {
+    console.error(chalk.red('No agentxchain project found. Run "agentxchain init" first.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const report = evaluateHumanAttention(root);
+
+  if (opts.json) {
+    // --json always emits the full, schema-valid HumanAttentionReport; exit 0 in both states.
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (report.overall === 'clear') {
+    console.log(chalk.green('Nothing needs your attention.'));
+    return;
+  }
+
+  // Default view surfaces blocking + escalation items first; informational pending-intent
+  // items are summarized as a count unless --all is passed.
+  const visible = opts.all ? report.items : report.items.filter((item) => item.blocking);
+  const hidden = report.items.length - visible.length;
+
+  console.log(
+    `\n${chalk.bold('Attention needed')}: ${report.items_count} `
+    + `item${report.items_count === 1 ? '' : 's'} (${report.blocking_count} blocking)`,
+  );
+
+  visible.forEach((item, idx) => {
+    const tag = chalk.cyan(String(item.category).padEnd(16));
+    const run = item.run_id ? `${chalk.dim(item.run_id)} ` : '';
+    console.log(`  [${idx + 1}] ${tag} ${run}${item.summary}`);
+    console.log(`      ${chalk.dim('→')} ${item.action_hint}`);
+  });
+
+  if (hidden > 0) {
+    console.log(
+      chalk.dim(`  (+${hidden} informational item${hidden === 1 ? '' : 's'} — run with --all to show)`),
+    );
+  }
+
+  console.log('');
+  // Status surface, not a gate — no non-zero exit even in the attention state.
+}

package/src/commands/ship-status.js

@@ -0,0 +1,104 @@
+/**
+ * CLI command: agentxchain ship-status
+ *
+ * Answers "is this ready to ship?" by composing five evidence dimensions into a
+ * single ShipStatusReport. All evaluation logic lives in lib/ship-status.js — this
+ * command is presentation only (Architecture Invariant #5).
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { COORDINATOR_CONFIG_FILE } from '../lib/coordinator-config.js';
+import { evaluateShipStatus, evaluateCoordinatorShipStatus } from '../lib/ship-status.js';
+
+function statusIcon(status) {
+  if (status === 'pass') return chalk.green('✓');
+  if (status === 'fail') return chalk.red('✗');
+  return chalk.yellow('?');
+}
+
+function overallLabel(overall) {
+  if (overall === 'pass') return chalk.green.bold('YES');
+  if (overall === 'fail') return chalk.red.bold('NO');
+  return chalk.yellow.bold('PENDING');
+}
+
+function countPassed(report) {
+  return (report.dimensions || []).filter((d) => d.status === 'pass').length;
+}
+
+function printDimensions(dimensions, indent) {
+  for (const dim of dimensions || []) {
+    console.log(`${indent}${statusIcon(dim.status)}  ${dim.name}: ${dim.detail}`);
+  }
+}
+
+function printSingle(report, opts) {
+  const passed = countPassed(report);
+  const total = (report.dimensions || []).length;
+  const blocking = report.blocking_reasons || [];
+  const suffix = blocking.length ? `, ${blocking.length} blocking` : '';
+  console.log(`\nShip Status: ${overallLabel(report.overall)} (${passed}/${total} dimensions pass${suffix})`);
+
+  if (opts.verbose) {
+    console.log('');
+    printDimensions(report.dimensions, '  ');
+  } else {
+    for (const reason of blocking) {
+      console.log(`  ${chalk.dim('-')} ${reason}`);
+    }
+  }
+  console.log('');
+}
+
+export async function shipStatusCommand(opts) {
+  const dir = opts.dir ? resolve(opts.dir) : process.cwd();
+  const coordinatorConfigPath = join(dir, COORDINATOR_CONFIG_FILE);
+
+  let report;
+  let isCoordinator = false;
+
+  if (existsSync(coordinatorConfigPath)) {
+    isCoordinator = true;
+    report = evaluateCoordinatorShipStatus(dir);
+  } else {
+    const root = findProjectRoot(dir);
+    if (!root) {
+      console.error(chalk.red('No agentxchain project found. Run "agentxchain init" first.'));
+      process.exitCode = 1;
+      return;
+    }
+    report = evaluateShipStatus(root);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (isCoordinator) {
+    const blocking = report.blocking_repos || [];
+    const total = (report.repos || []).length;
+    const shippable = total - blocking.length;
+    console.log(`\nCoordinator Ship Status: ${overallLabel(report.overall)} (${shippable}/${total} repos shippable)`);
+    for (const entry of report.repos || []) {
+      const passed = countPassed(entry.ship_status);
+      const dimTotal = (entry.ship_status.dimensions || []).length;
+      console.log(`\n  ${chalk.bold(entry.repo_id)}: ${overallLabel(entry.ship_status.overall)} (${passed}/${dimTotal})`);
+      if (opts.verbose) {
+        printDimensions(entry.ship_status.dimensions, '    ');
+      } else {
+        for (const reason of entry.ship_status.blocking_reasons || []) {
+          console.log(`    ${chalk.dim('-')} ${reason}`);
+        }
+      }
+    }
+    console.log('');
+  } else {
+    printSingle(report, opts);
+  }
+
+  // Non-zero exit when not shippable (useful for CI gating).
+  if (report.overall === 'fail') {
+    process.exitCode = 1;
+  }
+}

package/src/lib/adapters/local-cli-adapter.js

@@ -44,6 +44,10 @@ import {
   parseRateLimitResetMs,
   resolveClaudeCompatibleNodeBinary,
 } from '../claude-local-auth.js';
+import {
+  createStreamJsonCostParser,
+  buildCostFromStreamJson,
+} from '../stream-json-cost-parser.js';
 
 const DIAGNOSTIC_ENV_KEYS = [
   'PATH',
@@ -147,6 +151,16 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     };
   }
 
+  // Create stream-json cost parser for Claude runtimes with stream-json output.
+  // Only Claude runtimes emit parseable NDJSON with result events; other runtimes
+  // (Codex, Cursor, Windsurf, OpenCode) have different stdout formats.
+  const tokens = [command, ...args].filter((t) => typeof t === 'string');
+  const usesStreamJson = tokens.includes('--output-format=stream-json')
+    || (tokens.includes('--output-format') && tokens[tokens.indexOf('--output-format') + 1] === 'stream-json');
+  const costParser = isClaudeLocalCliRuntime(runtime) && usesStreamJson
+    ? createStreamJsonCostParser()
+    : null;
+
   // Compute timeout from explicit dispatch deadline, turn deadline, or default (20 minutes).
   const timeoutMs = options.dispatchTimeoutMs != null
     ? options.dispatchTimeoutMs
@@ -425,6 +439,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
         stdoutBytes += Buffer.byteLength(text);
         recordFirstOutput('stdout');
         logs.push(text);
+        if (costParser) costParser.push(text);
         if (onStdout) onStdout(text);
       });
     }
@@ -558,6 +573,28 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       appendDiagnostic(logs, 'process_exit', exitDiagnostic);
 
       if (hasResult) {
+        // Enrich cost from stream-json if available (best-effort, never blocks settle)
+        if (costParser) {
+          try {
+            const parsedCost = costParser.getResult();
+            if (parsedCost) {
+              const stagingPath = join(root, getTurnStagingResultPath(turn.turn_id));
+              const raw = readFileSync(stagingPath, 'utf8');
+              const turnResult = JSON.parse(raw);
+              turnResult.cost = buildCostFromStreamJson(parsedCost, config);
+              writeFileSync(stagingPath, JSON.stringify(turnResult, null, 2) + '\n');
+              appendDiagnostic(logs, 'stream_json_cost_enriched', {
+                input_tokens: parsedCost.input_tokens,
+                output_tokens: parsedCost.output_tokens,
+                cost_usd: parsedCost.cost_usd,
+                model: parsedCost.model,
+                computed_usd: turnResult.cost.usd,
+              });
+            }
+          } catch {
+            // Cost enrichment is best-effort — if it fails, agent-reported cost is preserved
+          }
+        }
         settle({ ok: true, exitCode, timedOut: false, aborted: false, logs, firstOutputAt });
       } else if (isClaudeLocalCliRuntime(runtime) && hasClaudeAuthFailureOutput(logs)) {
         const recovery = 'Refresh Claude credentials before resuming: export a valid ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN, then run agentxchain step --resume.';

package/src/lib/ci-reporter.js

@@ -1,5 +1,22 @@
 import { appendFileSync } from 'node:fs';
 
+/**
+ * Normalize gate_summary to [gateName, statusString] entries.
+ * Handles both array format ([{ gate_id, status }]) from the real report pipeline
+ * and object format ({ gateName: statusString }) from legacy/synthetic fixtures.
+ */
+function normalizeGateEntries(gates) {
+  if (Array.isArray(gates)) {
+    return gates
+      .filter(g => typeof g?.gate_id === 'string' && typeof g?.status === 'string')
+      .map(g => [g.gate_id, g.status]);
+  }
+  if (gates && typeof gates === 'object') {
+    return Object.entries(gates).filter(([, v]) => typeof v === 'string');
+  }
+  return [];
+}
+
 /**
  * Detect CI environment from process.env.
  * @returns {{ provider: string, run_url: string|null, run_id: string|null, ref: string|null, sha: string|null } | null}
@@ -55,16 +72,12 @@ export function formatGitHubAnnotations(report) {
   }
 
   // Gate annotations
-  const gates = report.subject?.run?.gate_summary;
-  if (gates && typeof gates === 'object') {
-    for (const [gateName, gateStatus] of Object.entries(gates)) {
-      if (typeof gateStatus !== 'string') continue;
-      const normalizedStatus = gateStatus.toLowerCase();
-      if (normalizedStatus === 'satisfied' || normalizedStatus === 'pass' || normalizedStatus === 'passed') {
-        lines.push(`::notice title=Gate ${gateName}::satisfied`);
-      } else {
-        lines.push(`::warning title=Gate ${gateName}::${gateStatus}`);
-      }
+  for (const [gateName, gateStatus] of normalizeGateEntries(report.subject?.run?.gate_summary)) {
+    const normalizedStatus = gateStatus.toLowerCase();
+    if (normalizedStatus === 'satisfied' || normalizedStatus === 'pass' || normalizedStatus === 'passed') {
+      lines.push(`::notice title=Gate ${gateName}::satisfied`);
+    } else {
+      lines.push(`::warning title=Gate ${gateName}::${gateStatus}`);
     }
   }
 
@@ -113,7 +126,6 @@ export function writeGitHubOutputVars(report, outputPath) {
  */
 export function formatJUnitXml(report) {
   const run = report.subject?.run || {};
-  const gates = run.gate_summary || {};
   const turns = run.turns || [];
 
   // Escape XML special characters
@@ -124,7 +136,7 @@ export function formatJUnitXml(report) {
     .replace(/"/g, '"');
 
   // Build gate test cases
-  const gateEntries = Object.entries(gates).filter(([, v]) => typeof v === 'string');
+  const gateEntries = normalizeGateEntries(run.gate_summary);
   const gateFailures = gateEntries.filter(([, status]) => {
     const s = status.toLowerCase();
     return s !== 'satisfied' && s !== 'pass' && s !== 'passed';

package/src/lib/continuous-run.js

@@ -1141,10 +1141,27 @@ export function maybeAutoReconcileOperatorCommits(context, session, contOpts, lo
   }
 
   const errorClass = result.error_class || 'reconcile_refused';
+  // RB-14: `reconcile-state --accept-operator-head` runs the SAME safety check, so it
+  // cannot clear an unsafe-edit refusal — recommending it for governance_state_modified
+  // or critical_artifact_deleted is a dead end. Give the recovery that actually applies.
+  const offendingCommit = result.offending_commit || result.commit || null;
+  const offendingPath = result.offending_path || result.path || null;
+  let recoveryAction;
+  let recoveryDetailTail;
+  if (errorClass === 'governance_state_modified') {
+    recoveryAction = offendingCommit ? `git revert ${offendingCommit.slice(0, 12)}` : 'git revert <offending-commit>';
+    recoveryDetailTail = `${offendingPath || 'A commit'} edits governed state under .agentxchain/ directly, which the anti-tamper guard never auto-accepts (reconcile-state --accept-operator-head enforces the same check). Revert it (${recoveryAction}) to restore the governed lineage, or restart from an explicit prior checkpoint.`;
+  } else if (errorClass === 'critical_artifact_deleted') {
+    recoveryAction = (offendingCommit && offendingPath) ? `git checkout ${offendingCommit.slice(0, 12)}^ -- ${offendingPath}` : 'git checkout <commit>^ -- <deleted-path>';
+    recoveryDetailTail = `Critical governed evidence ${offendingPath || ''} was deleted; restore it (${recoveryAction}), then resume.`;
+  } else {
+    recoveryAction = 'agentxchain reconcile-state --accept-operator-head';
+    recoveryDetailTail = `Run: ${recoveryAction} once the unsafe changes are resolved, or revert them.`;
+  }
   const detailLines = [
     `Operator-commit auto-reconcile refused (${errorClass}).`,
     result.error || 'Unsafe operator commits detected; manual recovery required.',
-    'Run: agentxchain reconcile-state --accept-operator-head once the unsafe changes are resolved, or revert them.',
+    recoveryDetailTail,
   ];
   const detail = detailLines.join(' ');
 
@@ -1164,7 +1181,7 @@ export function maybeAutoReconcileOperatorCommits(context, session, contOpts, lo
           ...((state.blocked_reason || {}).recovery || {}),
           typed_reason: 'operator_commit_reconcile_refused',
           owner: 'human',
-          recovery_action: 'agentxchain reconcile-state --accept-operator-head',
+          recovery_action: recoveryAction,
           turn_retained: false,
           detail,
         },
@@ -1196,7 +1213,7 @@ export function maybeAutoReconcileOperatorCommits(context, session, contOpts, lo
     status: 'blocked',
     action: 'operator_commit_reconcile_refused',
     run_id: session.current_run_id,
-    recovery_action: 'agentxchain reconcile-state --accept-operator-head',
+    recovery_action: recoveryAction,
     blocked_category: 'operator_commit_reconcile_refused',
     error_class: errorClass,
   };
@@ -2579,10 +2596,47 @@ export async function executeContinuousRun(context, contOpts, executeGovernedRun
   process.on('SIGINT', sigHandler);
 
   try {
+    // RB-13: circuit-breaker for the recover-and-continue path. A deterministic,
+    // recurring failure (e.g. an unclean baseline) must escalate, not busy-loop
+    // forever — without this, the same start error spun 582 times in seconds.
+    // Track consecutive identical recoveries; halt and escalate after a cap, and
+    // back off between attempts so even allowed retries can't tight-loop.
+    let consecutiveRecoveries = 0;
+    let lastRecoveryReason = null;
+    const maxConsecutiveRecoveries = Math.max(1, contOpts.maxConsecutiveRecoveries ?? 3);
+
     while (!stopping) {
       const step = await advanceContinuousRunOnce(context, session, contOpts, executeGovernedRun, log);
 
       if (step.status === 'failed' && isGovernedRunStillActiveForSession(root, context.config, session)) {
+        const recoveryReason = step.stop_reason || step.action || 'unknown';
+        if (recoveryReason === lastRecoveryReason) {
+          consecutiveRecoveries += 1;
+        } else {
+          consecutiveRecoveries = 1;
+          lastRecoveryReason = recoveryReason;
+        }
+
+        if (consecutiveRecoveries >= maxConsecutiveRecoveries) {
+          // Circuit open: the same recoverable failure keeps recurring without
+          // progress. Escalate to a human instead of spinning the loop.
+          session.status = 'blocked';
+          writeContinuousSession(root, session);
+          emitRunEvent(root, 'continuous_recovery_circuit_open', {
+            run_id: session.current_run_id || null,
+            phase: null,
+            status: 'blocked',
+            payload: {
+              session_id: session.session_id,
+              failed_action: step.action || null,
+              failed_reason: recoveryReason,
+              consecutive_recoveries: consecutiveRecoveries,
+            },
+          });
+          log(`Continuous loop halted (circuit-breaker): the same recoverable failure recurred ${consecutiveRecoveries} times with no progress — escalating to a human instead of spinning. Reason: ${recoveryReason}`);
+          return { exitCode: 1, session };
+        }
+
         session.status = 'running';
         writeContinuousSession(root, session);
         emitRunEvent(root, 'session_failed_recovered_active_run', {
@@ -2593,12 +2647,20 @@ export async function executeContinuousRun(context, contOpts, executeGovernedRun
             session_id: session.session_id,
             failed_action: step.action || null,
             failed_reason: step.stop_reason || null,
+            consecutive_recoveries: consecutiveRecoveries,
           },
         });
-        log('Session failure recovered - governed run still active, continuing.');
+        log(`Session failure recovered - governed run still active, continuing (recovery ${consecutiveRecoveries}/${maxConsecutiveRecoveries}).`);
+        // Backoff before retrying so a recurring failure cannot busy-loop.
+        const recoveryBackoffMs = Math.max(1000, (contOpts.cooldownSeconds ?? 5) * 1000);
+        await new Promise((resolve) => setTimeout(resolve, recoveryBackoffMs));
         continue;
       }
 
+      // A non-recovery step means the loop made forward progress — reset the breaker.
+      consecutiveRecoveries = 0;
+      lastRecoveryReason = null;
+
       // Terminal states
       if (step.status === 'completed' || step.status === 'idle_exit' || step.status === 'failed' || step.status === 'blocked' || step.status === 'stopped' || step.status === 'vision_exhausted' || step.status === 'vision_expansion_exhausted' || step.status === 'session_budget') {
         const terminalMessage = describeContinuousTerminalStep(step, contOpts);

package/src/lib/dispatch-bundle.js

@@ -471,6 +471,18 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
   }
 
+  // Single-shot execution model — prevents ghost turns from async / background-wait patterns.
+  lines.push('## Single-Shot Execution (read carefully)');
+  lines.push('');
+  lines.push('You run as a **single, non-interactive `--print` subprocess**. You get exactly ONE invocation with no "later": there is no async wake-up, no second message, and nothing will notify you after you stop responding. The moment you end your turn the subprocess exits — if you have not written your turn result by then, the entire turn is **discarded as a ghost** (no result, wasted run).');
+  lines.push('');
+  lines.push('Therefore:');
+  lines.push('- Do ALL work **synchronously** within this one turn. Run every command to completion in the foreground and read its output inline before continuing.');
+  lines.push('- **NEVER** start a background job and then wait for it. Do not use `ScheduleWakeup`; do not start a `Monitor` or `tail -f` and wait for events; do not background a process with `&` and poll for a notification; do not defer any conclusion to "after the suite/build finishes". You will not be re-invoked to finish.');
+  lines.push('- If you need a long command or test suite result, run it **blocking in the foreground** (e.g. `npm test`) and wait for it to return in-line — the per-turn timeout is generous, so budget your time for it.');
+  lines.push('- Writing the structured turn result below is your **final action**: gather every piece of evidence first, then write the result before you finish.');
+  lines.push('');
+
   // Output format with complete JSON template
   lines.push('## Required Output');
   lines.push('');