agentxchain 2.110.0 → 2.112.0

package/src/commands/run.js

@@ -44,6 +44,7 @@ import {
   getDispatchTurnDir,
   getTurnStagingResultPath,
 } from '../lib/turn-paths.js';
+import { resolveChainOptions, executeChainedRun } from '../lib/run-chain.js';
 
 export async function runCommand(opts) {
   const context = loadProjectContext();
@@ -52,6 +53,16 @@ export async function runCommand(opts) {
     process.exit(1);
   }
 
+  const chainOpts = resolveChainOptions(opts, context.config);
+  if (chainOpts.enabled) {
+    console.log(chalk.cyan.bold('agentxchain run --chain'));
+    const chainParts = [`max ${chainOpts.maxChains} continuations`, `on: ${chainOpts.chainOn.join(',')}`, `cooldown: ${chainOpts.cooldownSeconds}s`];
+    if (chainOpts.mission) chainParts.push(`mission: ${chainOpts.mission}`);
+    console.log(chalk.dim(`  Chain mode: enabled (${chainParts.join(', ')})`));
+    const { exitCode } = await executeChainedRun(context, opts, chainOpts, executeGovernedRun);
+    process.exit(exitCode);
+  }
+
   const execution = await executeGovernedRun(context, opts);
   process.exit(execution.exitCode);
 }
@@ -167,8 +178,7 @@ export async function executeGovernedRun(context, opts = {}) {
   let aborted = false;
   let sigintCount = 0;
   const controller = new AbortController();
-
-  process.on('SIGINT', () => {
+  const onSigint = () => {
     sigintCount++;
     if (sigintCount >= 2) {
       process.exit(130);
@@ -176,37 +186,39 @@ export async function executeGovernedRun(context, opts = {}) {
     aborted = true;
     controller.abort();
     log(chalk.yellow('\nSIGINT received — finishing current turn, then stopping.'));
-  });
+  };
+  process.on('SIGINT', onSigint);
 
-  // ── Run header ──────────────────────────────────────────────────────────
-  log(chalk.cyan.bold('agentxchain run'));
-  log(chalk.dim(`  Max turns: ${maxTurns}  Gate mode: ${autoApprove ? 'auto-approve' : 'interactive'}`));
-  if (provenance) {
-    const provenanceSummary = summarizeRunProvenance(provenance);
-    if (provenanceSummary) {
-      log(`  ${chalk.dim('Origin:')}    ${chalk.magenta(provenanceSummary)}`);
+  try {
+    // ── Run header ──────────────────────────────────────────────────────────
+    log(chalk.cyan.bold('agentxchain run'));
+    log(chalk.dim(`  Max turns: ${maxTurns}  Gate mode: ${autoApprove ? 'auto-approve' : 'interactive'}`));
+    if (provenance) {
+      const provenanceSummary = summarizeRunProvenance(provenance);
+      if (provenanceSummary) {
+        log(`  ${chalk.dim('Origin:')}    ${chalk.magenta(provenanceSummary)}`);
+      }
     }
-  }
-  if (inheritedContext) {
-    const ic = inheritedContext;
-    const phasesCount = ic.parent_phases_completed?.length || 0;
-    const decisionsCount = ic.recent_decisions?.length || 0;
-    const turnsCount = ic.recent_accepted_turns?.length || 0;
-    const parts = [];
-    if (phasesCount) parts.push(`${phasesCount} phase${phasesCount !== 1 ? 's' : ''}`);
-    if (decisionsCount) parts.push(`${decisionsCount} decision${decisionsCount !== 1 ? 's' : ''}`);
-    if (turnsCount) parts.push(`${turnsCount} turn${turnsCount !== 1 ? 's' : ''}`);
-    const detail = parts.length ? ` — ${parts.join(', ')}` : '';
-    log(`  ${chalk.dim('Inherits:')} ${chalk.magenta(`parent ${ic.parent_run_id} (${ic.parent_status || 'unknown'})${detail}`)}`);
-  }
-  log('');
+    if (inheritedContext) {
+      const ic = inheritedContext;
+      const phasesCount = ic.parent_phases_completed?.length || 0;
+      const decisionsCount = ic.recent_decisions?.length || 0;
+      const turnsCount = ic.recent_accepted_turns?.length || 0;
+      const parts = [];
+      if (phasesCount) parts.push(`${phasesCount} phase${phasesCount !== 1 ? 's' : ''}`);
+      if (decisionsCount) parts.push(`${decisionsCount} decision${decisionsCount !== 1 ? 's' : ''}`);
+      if (turnsCount) parts.push(`${turnsCount} turn${turnsCount !== 1 ? 's' : ''}`);
+      const detail = parts.length ? ` — ${parts.join(', ')}` : '';
+      log(`  ${chalk.dim('Inherits:')} ${chalk.magenta(`parent ${ic.parent_run_id} (${ic.parent_status || 'unknown'})${detail}`)}`);
+    }
+    log('');
 
-  // ── Track first-call for --role override ────────────────────────────────
-  let firstSelectRole = true;
-  let qaMissingCredentialsFallback = null;
+    // ── Track first-call for --role override ────────────────────────────────
+    let firstSelectRole = true;
+    let qaMissingCredentialsFallback = null;
 
-  // ── Callbacks ───────────────────────────────────────────────────────────
-  const callbacks = {
+    // ── Callbacks ───────────────────────────────────────────────────────────
+    const callbacks = {
     selectRole(state, cfg) {
       if (aborted) return null;
 
@@ -407,84 +419,87 @@ export async function executeGovernedRun(context, opts = {}) {
           break;
       }
     },
-  };
-
-  // ── Execute ─────────────────────────────────────────────────────────────
-  const runLoopOpts = {
-    maxTurns,
-    startNewRunFromCompleted: true,
-    startNewRunFromBlocked: opts.allowBlockedRestart ?? Boolean(provenance),
-  };
-  if (provenance) runLoopOpts.provenance = provenance;
-  if (inheritedContext) runLoopOpts.inheritedContext = inheritedContext;
-  const result = await runLoop(root, config, callbacks, runLoopOpts);
+    };
 
-  // ── Summary ─────────────────────────────────────────────────────────────
-  log('');
-  log(chalk.dim('─── Run Summary ───'));
-  log(`  Status:  ${result.ok ? chalk.green('completed') : chalk.yellow(result.stop_reason)}`);
-  log(`  Turns:   ${result.turns_executed}`);
-  log(`  Gates:   ${result.gates_approved} approved`);
-  log(`  Errors:  ${result.errors.length ? chalk.red(result.errors.length) : 'none'}`);
-
-  if (result.errors.length) {
-    for (const err of result.errors) {
-      log(chalk.red(`    ${err}`));
+    // ── Execute ─────────────────────────────────────────────────────────────
+    const runLoopOpts = {
+      maxTurns,
+      startNewRunFromCompleted: true,
+      startNewRunFromBlocked: opts.allowBlockedRestart ?? Boolean(provenance),
+    };
+    if (provenance) runLoopOpts.provenance = provenance;
+    if (inheritedContext) runLoopOpts.inheritedContext = inheritedContext;
+    const result = await runLoop(root, config, callbacks, runLoopOpts);
+
+    // ── Summary ─────────────────────────────────────────────────────────────
+    log('');
+    log(chalk.dim('─── Run Summary ───'));
+    log(`  Status:  ${result.ok ? chalk.green('completed') : chalk.yellow(result.stop_reason)}`);
+    log(`  Turns:   ${result.turns_executed}`);
+    log(`  Gates:   ${result.gates_approved} approved`);
+    log(`  Errors:  ${result.errors.length ? chalk.red(result.errors.length) : 'none'}`);
+
+    if (result.errors.length) {
+      for (const err of result.errors) {
+        log(chalk.red(`    ${err}`));
+      }
     }
-  }
 
-  if (qaMissingCredentialsFallback) {
-    printManualQaFallback(log);
-  }
+    if (qaMissingCredentialsFallback) {
+      printManualQaFallback(log);
+    }
 
-  // Recovery guidance for blocked/rejected states
-  if (result.state && (result.stop_reason === 'blocked' || result.stop_reason === 'reject_exhausted' || result.stop_reason === 'dispatch_error')) {
-    const recovery = deriveRecoveryDescriptor(result.state, config);
-    if (recovery) {
-      log('');
-      log(chalk.yellow(`  Recovery: ${recovery.typed_reason}`));
-      log(chalk.dim(`  Action:   ${recovery.recovery_action}`));
-      if (recovery.detail) {
-        log(chalk.dim(`  Detail:   ${recovery.detail}`));
+    // Recovery guidance for blocked/rejected states
+    if (result.state && (result.stop_reason === 'blocked' || result.stop_reason === 'reject_exhausted' || result.stop_reason === 'dispatch_error')) {
+      const recovery = deriveRecoveryDescriptor(result.state, config);
+      if (recovery) {
+        log('');
+        log(chalk.yellow(`  Recovery: ${recovery.typed_reason}`));
+        log(chalk.dim(`  Action:   ${recovery.recovery_action}`));
+        if (recovery.detail) {
+          log(chalk.dim(`  Detail:   ${recovery.detail}`));
+        }
       }
     }
-  }
-
-  // ── Auto governance report ──────────────────────────────────────────────
-  if (opts.report !== false && result.state) {
-    try {
-      const reportsDir = join(root, '.agentxchain', 'reports');
-      mkdirSync(reportsDir, { recursive: true });
-
-      const exportResult = buildRunExport(root);
-      if (exportResult.ok) {
-        const runId = result.state.run_id || 'unknown';
-        const exportPath = join(reportsDir, `export-${runId}.json`);
-        writeFileSync(exportPath, JSON.stringify(exportResult.export, null, 2));
-
-        const reportResult = buildGovernanceReport(exportResult.export, { input: exportPath });
-        const reportPath = join(reportsDir, `report-${runId}.md`);
-        writeFileSync(reportPath, formatGovernanceReportMarkdown(reportResult.report));
 
-        log('');
-        log(chalk.dim(`  Governance report: .agentxchain/reports/report-${runId}.md`));
-      } else {
-        log(chalk.dim(`  Governance report skipped: ${exportResult.error}`));
+    // ── Auto governance report ──────────────────────────────────────────────
+    if (opts.report !== false && result.state) {
+      try {
+        const reportsDir = join(root, '.agentxchain', 'reports');
+        mkdirSync(reportsDir, { recursive: true });
+
+        const exportResult = buildRunExport(root);
+        if (exportResult.ok) {
+          const runId = result.state.run_id || 'unknown';
+          const exportPath = join(reportsDir, `export-${runId}.json`);
+          writeFileSync(exportPath, JSON.stringify(exportResult.export, null, 2));
+
+          const reportResult = buildGovernanceReport(exportResult.export, { input: exportPath });
+          const reportPath = join(reportsDir, `report-${runId}.md`);
+          writeFileSync(reportPath, formatGovernanceReportMarkdown(reportResult.report));
+
+          log('');
+          log(chalk.dim(`  Governance report: .agentxchain/reports/report-${runId}.md`));
+        } else {
+          log(chalk.dim(`  Governance report skipped: ${exportResult.error}`));
+        }
+      } catch (err) {
+        log(chalk.dim(`  Governance report failed: ${err.message}`));
       }
-    } catch (err) {
-      log(chalk.dim(`  Governance report failed: ${err.message}`));
     }
-  }
 
-  // ── Exit code ───────────────────────────────────────────────────────────
-  const successReasons = new Set(['completed', 'gate_held', 'caller_stopped', 'max_turns_reached']);
-  return {
-    exitCode: result.ok || successReasons.has(result.stop_reason) ? 0 : 1,
-    result,
-    skipped: false,
-    skipReason: null,
-    provenance: provenance || null,
-  };
+    // ── Exit code ───────────────────────────────────────────────────────────
+    const successReasons = new Set(['completed', 'gate_held', 'caller_stopped', 'max_turns_reached']);
+    return {
+      exitCode: result.ok || successReasons.has(result.stop_reason) ? 0 : 1,
+      result,
+      skipped: false,
+      skipReason: null,
+      provenance: provenance || null,
+    };
+  } finally {
+    process.removeListener('SIGINT', onSigint);
+  }
 }
 
 // ── Helpers ───────────────────────────────────────────────────────────────

package/src/lib/chain-reports.js

@@ -0,0 +1,54 @@
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export function getChainReportsDir(root) {
+  return join(root, '.agentxchain', 'reports');
+}
+
+export function loadAllChainReports(root) {
+  const reportsDir = getChainReportsDir(root);
+  if (!existsSync(reportsDir)) return [];
+
+  const files = readdirSync(reportsDir)
+    .filter((file) => file.startsWith('chain-') && file.endsWith('.json'))
+    .sort()
+    .reverse();
+
+  const reports = [];
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(reportsDir, file), 'utf8');
+      reports.push(JSON.parse(content));
+    } catch {
+      // Advisory artifact only. Skip malformed files instead of failing the surface.
+    }
+  }
+
+  reports.sort((a, b) => {
+    const aTime = a.started_at ? new Date(a.started_at).getTime() : 0;
+    const bTime = b.started_at ? new Date(b.started_at).getTime() : 0;
+    return bTime - aTime;
+  });
+
+  return reports;
+}
+
+export function loadLatestChainReport(root) {
+  const reports = loadAllChainReports(root);
+  return reports.length > 0 ? reports[0] : null;
+}
+
+export function loadChainReport(root, chainId) {
+  const reportsDir = getChainReportsDir(root);
+  const exactPath = join(reportsDir, `${chainId}.json`);
+  if (existsSync(exactPath)) {
+    try {
+      return JSON.parse(readFileSync(exactPath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  const reports = loadAllChainReports(root);
+  return reports.find((report) => report.chain_id === chainId) || null;
+}

package/src/lib/dashboard/bridge-server.js

@@ -29,6 +29,8 @@ import { queryRunHistory } from '../run-history.js';
 import { loadProjectContext, loadProjectState } from '../config.js';
 import { evaluateApprovalSlaReminders } from '../notification-runner.js';
 import { readGateActionSnapshot } from './gate-action-reader.js';
+import { readChainReportSnapshot } from './chain-report-reader.js';
+import { readMissionSnapshot } from './mission-reader.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -462,6 +464,20 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       return;
     }
 
+    if (pathname === '/api/chain-reports') {
+      const limit = url.searchParams.get('limit') ? parseInt(url.searchParams.get('limit'), 10) : undefined;
+      const result = readChainReportSnapshot(workspacePath, { limit });
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
+    if (pathname === '/api/missions') {
+      const limit = url.searchParams.get('limit') ? parseInt(url.searchParams.get('limit'), 10) : undefined;
+      const result = readMissionSnapshot(workspacePath, { limit });
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     if (pathname === '/api/gate-actions') {
       const result = readGateActionSnapshot(workspacePath);
       writeJson(res, result.status, result.body);

package/src/lib/dashboard/chain-report-reader.js

@@ -0,0 +1,15 @@
+import { loadAllChainReports, loadLatestChainReport } from '../chain-reports.js';
+
+export function readChainReportSnapshot(workspacePath, { limit } = {}) {
+  const reports = loadAllChainReports(workspacePath);
+  const effectiveLimit = Number.isInteger(limit) && limit > 0 ? limit : reports.length;
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      latest: loadLatestChainReport(workspacePath),
+      reports: reports.slice(0, effectiveLimit),
+    },
+  };
+}

package/src/lib/dashboard/file-watcher.js

@@ -8,7 +8,7 @@
 import { watch, existsSync } from 'fs';
 import { basename, join } from 'path';
 import { EventEmitter } from 'events';
-import { WATCH_DIRECTORIES, resourceForRelativePath } from './state-reader.js';
+import { WATCH_DIRECTORIES, resourcesForRelativePath } from './state-reader.js';
 
 const DEBOUNCE_MS = 100;
 
@@ -40,24 +40,26 @@ export class FileWatcher extends EventEmitter {
         if (!filename || this.#closed) return;
         const base = basename(filename);
         const relativePath = relativeDir ? `${relativeDir}/${base}` : base;
-        const resource = resourceForRelativePath(relativePath);
+        const resources = resourcesForRelativePath(relativePath);
 
-        if (!resource) {
+        if (resources.length === 0) {
           if (!relativeDir && base === 'multirepo') {
             this.#watchPath('multirepo');
           }
           return;
         }
 
-        if (this.#debounceTimers.has(resource)) {
-          clearTimeout(this.#debounceTimers.get(resource));
-        }
-        this.#debounceTimers.set(resource, setTimeout(() => {
-          this.#debounceTimers.delete(resource);
-          if (!this.#closed) {
-            this.emit('invalidate', { resource });
+        for (const resource of resources) {
+          if (this.#debounceTimers.has(resource)) {
+            clearTimeout(this.#debounceTimers.get(resource));
           }
-        }, DEBOUNCE_MS));
+          this.#debounceTimers.set(resource, setTimeout(() => {
+            this.#debounceTimers.delete(resource);
+            if (!this.#closed) {
+              this.emit('invalidate', { resource });
+            }
+          }, DEBOUNCE_MS));
+        }
       });
 
       watcher.on('error', (err) => {

package/src/lib/dashboard/mission-reader.js

@@ -0,0 +1,14 @@
+import { buildMissionListSummary, loadLatestMissionSnapshot } from '../missions.js';
+
+export function readMissionSnapshot(workspacePath, { limit } = {}) {
+  const missions = buildMissionListSummary(workspacePath, limit);
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      latest: loadLatestMissionSnapshot(workspacePath),
+      missions,
+    },
+  };
+}

package/src/lib/dashboard/state-reader.js

@@ -62,14 +62,28 @@ FILE_TO_RESOURCE[normalizeRelativePath(REPO_DECISIONS_FILE)] = '/api/repo-decisi
 export const WATCH_DIRECTORIES = [
   '',
   MULTIREPO_DIR,
+  'missions',
+  'reports',
 ];
 
 export function normalizeRelativePath(filePath) {
   return normalize(filePath).replace(/\\/g, '/').replace(/^\.\/+/, '');
 }
 
+export function resourcesForRelativePath(filePath) {
+  const normalized = normalizeRelativePath(filePath);
+  if (normalized.startsWith('missions/') && normalized.endsWith('.json')) {
+    return ['/api/missions'];
+  }
+  if (normalized.startsWith('reports/chain-') && normalized.endsWith('.json')) {
+    return ['/api/chain-reports', '/api/missions'];
+  }
+  return FILE_TO_RESOURCE[normalized] ? [FILE_TO_RESOURCE[normalized]] : [];
+}
+
 export function resourceForRelativePath(filePath) {
-  return FILE_TO_RESOURCE[normalizeRelativePath(filePath)] || null;
+  const resources = resourcesForRelativePath(filePath);
+  return resources[0] || null;
 }
 
 /**

package/src/lib/export-diff.js

@@ -216,6 +216,9 @@ function normalizeRunExport(artifact) {
     budget_warn_mode: budgetStatus.warn_mode === true,
     budget_exhausted: budgetStatus.exhausted === true,
     phase_gate_status: normalizeGateStatusMap(phaseGateStatus),
+    blocked_category: state.blocked_reason?.category || null,
+    blocked_gate_action_timed_out: state.blocked_reason?.gate_action?.timed_out === true,
+    blocked_gate_action_timeout_ms: typeof state.blocked_reason?.gate_action?.timeout_ms === 'number' ? state.blocked_reason.gate_action.timeout_ms : null,
     delegation_missing_decisions: normalizeDelegationMissingMap(summary.delegation_summary),
   };
 }
@@ -563,11 +566,17 @@ function detectRunRegressions(left, right) {
     const leftGate = (left.phase_gate_status || {})[gateId] || null;
     const rightGate = (right.phase_gate_status || {})[gateId] || null;
     if (leftGate && rightGate && GATE_PASSED_STATES.has(leftGate) && GATE_FAILED_STATES.has(rightGate)) {
+      let causeDetail = '';
+      if (right.blocked_category === 'gate_action_failed') {
+        causeDetail = right.blocked_gate_action_timed_out
+          ? ` (gate action timed out after ${right.blocked_gate_action_timeout_ms}ms)`
+          : ' (gate action failed)';
+      }
       regressions.push({
         id: `REG-GATE-${String(++counter).padStart(3, '0')}`,
         category: 'gate',
         severity: 'error',
-        message: `Gate "${gateId}" regressed from ${leftGate} to ${rightGate}`,
+        message: `Gate "${gateId}" regressed from ${leftGate} to ${rightGate}${causeDetail}`,
         field: `phase_gate_status.${gateId}`,
         left: leftGate,
         right: rightGate,