agentxchain 2.109.0 → 2.111.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,14 @@ 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'));
+    console.log(chalk.dim(`  Chain mode: enabled (max ${chainOpts.maxChains} continuations, on: ${chainOpts.chainOn.join(',')}, cooldown: ${chainOpts.cooldownSeconds}s)`));
+    const { exitCode } = await executeChainedRun(context, opts, chainOpts, executeGovernedRun);
+    process.exit(exitCode);
+  }
+
   const execution = await executeGovernedRun(context, opts);
   process.exit(execution.exitCode);
 }
@@ -167,8 +176,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 +184,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 +417,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/commands/status.js

@@ -358,9 +358,9 @@ function renderGovernedStatus(context, opts) {
     for (const action of gateActionAttempt.actions) {
       const label = action.action_label || action.command || `action ${action.action_index || '?'}`;
       const outcome = action.status === 'failed'
-        ? chalk.red('failed')
+        ? (action.timed_out ? chalk.red(`timed out after ${action.timeout_ms}ms`) : chalk.red('failed'))
         : chalk.green('succeeded');
-      const exit = action.exit_code == null ? '' : ` (exit ${action.exit_code})`;
+      const exit = action.timed_out ? '' : (action.exit_code == null ? '' : ` (exit ${action.exit_code})`);
       console.log(`    ${action.action_index || '?'}. ${label} — ${outcome}${exit}`);
       if (action.status === 'failed' && action.stderr_tail) {
         console.log(`      ${chalk.dim(action.stderr_tail)}`);

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,7 @@ 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';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -462,6 +463,13 @@ 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/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/state-reader.js

@@ -62,6 +62,7 @@ FILE_TO_RESOURCE[normalizeRelativePath(REPO_DECISIONS_FILE)] = '/api/repo-decisi
 export const WATCH_DIRECTORIES = [
   '',
   MULTIREPO_DIR,
+  'reports',
 ];
 
 export function normalizeRelativePath(filePath) {
@@ -69,7 +70,11 @@ export function normalizeRelativePath(filePath) {
 }
 
 export function resourceForRelativePath(filePath) {
-  return FILE_TO_RESOURCE[normalizeRelativePath(filePath)] || null;
+  const normalized = normalizeRelativePath(filePath);
+  if (normalized.startsWith('reports/chain-') && normalized.endsWith('.json')) {
+    return '/api/chain-reports';
+  }
+  return FILE_TO_RESOURCE[normalized] || 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,

package/src/lib/gate-actions.js

@@ -5,6 +5,16 @@ import { spawnSync } from 'child_process';
 
 const LEDGER_PATH = '.agentxchain/decision-ledger.jsonl';
 const MAX_OUTPUT_TAIL_CHARS = 1200;
+export const DEFAULT_GATE_ACTION_TIMEOUT_MS = 15 * 60 * 1000;
+const MIN_GATE_ACTION_TIMEOUT_MS = 1000;
+const MAX_GATE_ACTION_TIMEOUT_MS = 60 * 60 * 1000;
+
+function normalizeGateActionTimeoutMs(action) {
+  if (Number.isInteger(action?.timeout_ms)) {
+    return action.timeout_ms;
+  }
+  return DEFAULT_GATE_ACTION_TIMEOUT_MS;
+}
 
 export function validateGateActionsConfig(gates, errors) {
   if (!gates || typeof gates !== 'object' || Array.isArray(gates)) {
@@ -44,6 +54,15 @@ export function validateGateActionsConfig(gates, errors) {
       if ('label' in action && (typeof action.label !== 'string' || !action.label.trim())) {
         errors.push(`${prefix}.label must be a non-empty string when provided`);
       }
+      if ('timeout_ms' in action) {
+        if (!Number.isInteger(action.timeout_ms)
+          || action.timeout_ms < MIN_GATE_ACTION_TIMEOUT_MS
+          || action.timeout_ms > MAX_GATE_ACTION_TIMEOUT_MS) {
+          errors.push(
+            `${prefix}.timeout_ms must be an integer between ${MIN_GATE_ACTION_TIMEOUT_MS} and ${MAX_GATE_ACTION_TIMEOUT_MS} when provided`,
+          );
+        }
+      }
     }
   }
 }
@@ -60,6 +79,7 @@ export function getGateActions(config, gateId) {
       index: index + 1,
       label: typeof action.label === 'string' && action.label.trim() ? action.label.trim() : null,
       run: action.run.trim(),
+      timeout_ms: normalizeGateActionTimeoutMs(action),
     }));
 }
 
@@ -78,6 +98,11 @@ function trimOutputTail(value) {
 }
 
 function buildGateActionEntry(action, meta, runtimeResult, status) {
+  const timedOut = runtimeResult?.error?.code === 'ETIMEDOUT';
+  const stderrTail = trimOutputTail(runtimeResult?.stderr) || (timedOut ? `Timed out after ${action.timeout_ms}ms` : null);
+  const spawnError = timedOut
+    ? `Timed out after ${action.timeout_ms}ms`
+    : runtimeResult?.error?.message || null;
   return {
     type: 'gate_action',
     timestamp: new Date().toISOString(),
@@ -90,12 +115,14 @@ function buildGateActionEntry(action, meta, runtimeResult, status) {
     action_index: action.index,
     action_label: action.label,
     command: action.run,
+    timeout_ms: action.timeout_ms,
     status,
     exit_code: Number.isInteger(runtimeResult?.status) ? runtimeResult.status : null,
     signal: runtimeResult?.signal || null,
     stdout_tail: trimOutputTail(runtimeResult?.stdout),
-    stderr_tail: trimOutputTail(runtimeResult?.stderr),
-    spawn_error: runtimeResult?.error?.message || null,
+    stderr_tail: stderrTail,
+    spawn_error: spawnError,
+    timed_out: timedOut,
   };
 }
 
@@ -125,6 +152,8 @@ export function executeGateActions(root, config, meta, opts = {}) {
       },
       encoding: 'utf8',
       maxBuffer: 10 * 1024 * 1024,
+      timeout: action.timeout_ms,
+      killSignal: 'SIGTERM',
     });
 
     const status = runtimeResult.error || runtimeResult.status !== 0 ? 'failed' : 'succeeded';
@@ -170,6 +199,8 @@ export function normalizeGateActionEntry(entry) {
     stdout_tail: entry.stdout_tail || null,
     stderr_tail: entry.stderr_tail || null,
     spawn_error: entry.spawn_error || null,
+    timeout_ms: Number.isInteger(entry.timeout_ms) ? entry.timeout_ms : null,
+    timed_out: entry.timed_out === true,
     timestamp: entry.timestamp || null,
   };
 }

package/src/lib/governed-state.js

@@ -1281,6 +1281,8 @@ function blockRunForGateActionFailure(root, state, gateFailure, config) {
     : 'agentxchain approve-transition';
   const actionLabel = gateFailure.action_label || gateFailure.command || gateFailure.gate_id || 'gate action';
   const blockedAt = gateFailure.timestamp || new Date().toISOString();
+  const failureVerb = gateFailure.timed_out ? 'timed out' : 'failed';
+  const failureDetail = `Gate action ${failureVerb} for "${gateFailure.gate_id || 'unknown'}": ${actionLabel}`;
   const blockedState = {
     ...state,
     status: 'blocked',
@@ -1289,13 +1291,13 @@ function blockRunForGateActionFailure(root, state, gateFailure, config) {
       category: 'gate_action_failed',
       blocked_at: blockedAt,
       turn_id: gateFailure.requested_by_turn || null,
-      detail: `Gate action failed for "${gateFailure.gate_id || 'unknown'}": ${actionLabel}`,
+      detail: failureDetail,
       recovery: {
         typed_reason: 'gate_action_failed',
         owner: 'human',
         recovery_action: recoveryAction,
         turn_retained: false,
-        detail: `${gateFailure.gate_id || 'unknown'} action ${gateFailure.action_index || '?'} (${actionLabel})`,
+        detail: `${gateFailure.gate_id || 'unknown'} action ${gateFailure.action_index || '?'} (${actionLabel})${gateFailure.timed_out ? ` timed out after ${gateFailure.timeout_ms}ms` : ''}`,
       },
       gate_action: {
         attempt_id: gateFailure.attempt_id || null,
@@ -1306,6 +1308,8 @@ function blockRunForGateActionFailure(root, state, gateFailure, config) {
         command: gateFailure.command || null,
         exit_code: gateFailure.exit_code ?? null,
         stderr_tail: gateFailure.stderr_tail || null,
+        timeout_ms: gateFailure.timeout_ms ?? null,
+        timed_out: gateFailure.timed_out === true,
       },
     },
   };

package/src/lib/report.js

@@ -1444,7 +1444,8 @@ export function formatGovernanceReportText(report) {
       for (const action of run.gate_actions) {
         const label = action.action_label || action.command || `action ${action.action_index || '?'}`;
         const exit = action.exit_code == null ? 'n/a' : String(action.exit_code);
-        lines.push(`  - ${action.gate_id || 'unknown'} | ${action.gate_type || 'unknown'} | action ${action.action_index || '?'} | ${action.status} | ${label} | exit: ${exit} | at: ${action.timestamp || 'n/a'}`);
+        const timeoutTag = action.timed_out ? ` | timed_out after ${action.timeout_ms}ms` : '';
+        lines.push(`  - ${action.gate_id || 'unknown'} | ${action.gate_type || 'unknown'} | action ${action.action_index || '?'} | ${action.status} | ${label} | exit: ${exit}${timeoutTag} | at: ${action.timestamp || 'n/a'}`);
         if (action.stderr_tail) {
           lines.push(`      stderr: ${action.stderr_tail}`);
         }
@@ -2014,7 +2015,8 @@ export function formatGovernanceReportMarkdown(report) {
       for (const action of run.gate_actions) {
         const label = action.action_label || action.command || `action ${action.action_index || '?'}`;
         const exit = action.exit_code == null ? 'n/a' : String(action.exit_code);
-        lines.push(`- \`${action.gate_id || 'unknown'}\` (${action.gate_type || 'unknown'}) action ${action.action_index || '?'} — **${action.status}** at \`${action.timestamp || 'n/a'}\`: ${label} (exit \`${exit}\`)`);
+        const mdTimeout = action.timed_out ? ` ⏱ timed out after ${action.timeout_ms}ms` : '';
+        lines.push(`- \`${action.gate_id || 'unknown'}\` (${action.gate_type || 'unknown'}) action ${action.action_index || '?'} — **${action.status}** at \`${action.timestamp || 'n/a'}\`: ${label} (exit \`${exit}\`)${mdTimeout}`);
         if (action.stderr_tail) {
           lines.push(`  - stderr: ${action.stderr_tail}`);
         }
@@ -2723,7 +2725,8 @@ function renderRunHtml(report) {
     for (const action of run.gate_actions) {
       const label = action.action_label || action.command || `action ${action.action_index || '?'}`;
       const exit = action.exit_code == null ? 'n/a' : String(action.exit_code);
-      gaHtml += `<li><code>${esc(action.gate_id || 'unknown')}</code> (${esc(action.gate_type || 'unknown')}) action ${esc(String(action.action_index || '?'))} — <strong>${esc(action.status)}</strong> at <code>${esc(action.timestamp || 'n/a')}</code>: ${esc(label)} (exit <code>${esc(exit)}</code>)`;
+      const htmlTimeout = action.timed_out ? ` <em>⏱ timed out after ${esc(String(action.timeout_ms))}ms</em>` : '';
+      gaHtml += `<li><code>${esc(action.gate_id || 'unknown')}</code> (${esc(action.gate_type || 'unknown')}) action ${esc(String(action.action_index || '?'))} — <strong>${esc(action.status)}</strong> at <code>${esc(action.timestamp || 'n/a')}</code>: ${esc(label)} (exit <code>${esc(exit)}</code>)${htmlTimeout}`;
       if (action.stderr_tail) {
         gaHtml += `<br><code>${esc(action.stderr_tail)}</code>`;
       }