agentxchain 2.124.0 → 2.126.0

package/bin/agentxchain.js

@@ -121,7 +121,7 @@ import { historyCommand } from '../src/commands/history.js';
 import { decisionsCommand } from '../src/commands/decisions.js';
 import { diffCommand } from '../src/commands/diff.js';
 import { eventsCommand } from '../src/commands/events.js';
-import { connectorCheckCommand } from '../src/commands/connector.js';
+import { connectorCheckCommand, connectorValidateCommand } from '../src/commands/connector.js';
 import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, scheduleStatusCommand } from '../src/commands/schedule.js';
 import { chainLatestCommand, chainListCommand, chainShowCommand } from '../src/commands/chain.js';
 import { missionAttachChainCommand, missionListCommand, missionPlanApproveCommand, missionPlanAutopilotCommand, missionPlanCommand, missionPlanLaunchCommand, missionPlanListCommand, missionPlanShowCommand, missionShowCommand, missionStartCommand } from '../src/commands/mission.js';
@@ -297,6 +297,15 @@ connectorCmd
   .option('--timeout <ms>', 'Per-probe timeout in milliseconds', '8000')
   .action(connectorCheckCommand);
 
+connectorCmd
+  .command('validate <runtime_id>')
+  .description('Dispatch one synthetic governed turn through a runtime and validate the staged turn result')
+  .option('--role <role_id>', 'Validate a specific role binding for the runtime')
+  .option('-j, --json', 'Output as JSON')
+  .option('--timeout <ms>', 'Synthetic dispatch timeout in milliseconds', '120000')
+  .option('--keep-artifacts', 'Keep the scratch validation workspace even on success')
+  .action(connectorValidateCommand);
+
 program
   .command('demo')
   .description('Run a complete governed lifecycle demo (no API keys required)')

package/package.json

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

package/src/commands/connector.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 
 import { loadProjectContext } from '../lib/config.js';
+import { DEFAULT_VALIDATE_TIMEOUT_MS, validateConfiguredConnector } from '../lib/connector-validate.js';
 import { DEFAULT_TIMEOUT_MS, probeConfiguredConnectors } from '../lib/connector-probe.js';
 
 function printJson(result, exitCode) {
@@ -120,3 +121,95 @@ export async function connectorCheckCommand(runtimeId, options = {}) {
 
   printText(payload, result.exitCode);
 }
+
+function printValidateText(result, exitCode) {
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Connector Validate'));
+  console.log(chalk.dim('  ' + '─'.repeat(47)));
+  console.log(`  ${chalk.dim(`Runtime:`)} ${result.runtime_id} (${result.runtime_type})`);
+  console.log(`  ${chalk.dim(`Role:`)}    ${result.role_id}`);
+  console.log(`  ${chalk.dim(`Timeout:`)} ${result.timeout_ms}ms`);
+  console.log('');
+
+  const badge = result.overall === 'pass'
+    ? chalk.green('PASS')
+    : result.overall === 'error'
+      ? chalk.red('ERROR')
+      : chalk.red('FAIL');
+  const summary = result.overall === 'pass'
+    ? 'Synthetic governed dispatch produced a valid turn result'
+    : (result.error || result.dispatch?.error || result.validation?.errors?.[0] || 'Connector validation failed');
+  console.log(`  ${badge}  ${summary}`);
+
+  if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+    console.log('');
+    for (const warning of result.warnings) {
+      console.log(`  ${chalk.yellow('!')} ${warning}`);
+    }
+  }
+
+  if (result.dispatch) {
+    console.log('');
+    console.log(`  ${chalk.dim('Dispatch:')} ${result.dispatch.ok ? chalk.green('ok') : chalk.red('failed')}`);
+    if (result.dispatch.error) {
+      console.log(`  ${chalk.dim('Detail:')}   ${result.dispatch.error}`);
+    }
+  }
+
+  if (result.validation) {
+    console.log(`  ${chalk.dim('Validator:')} ${result.validation.ok ? chalk.green('ok') : chalk.red(result.validation.stage || 'failed')}`);
+    if (Array.isArray(result.validation.errors) && result.validation.errors.length > 0) {
+      console.log(`  ${chalk.dim('Errors:')}   ${result.validation.errors.join(' | ')}`);
+    }
+  }
+
+  if (typeof result.cost_usd === 'number') {
+    console.log(`  ${chalk.dim('Cost:')}     $${result.cost_usd.toFixed(3)}`);
+  }
+
+  if (result.scratch_root) {
+    console.log('');
+    console.log(`  ${chalk.dim('Scratch:')} ${result.scratch_root}`);
+  }
+
+  console.log('');
+  process.exit(exitCode);
+}
+
+export async function connectorValidateCommand(runtimeId, options = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    const payload = { overall: 'error', error: 'No governed agentxchain.json found.' };
+    if (options.json) {
+      printJson(payload, 2);
+      return;
+    }
+    console.error(chalk.red('No governed agentxchain.json found. Run this inside a governed project.'));
+    process.exit(2);
+  }
+
+  const timeoutMs = Number.parseInt(options.timeout || DEFAULT_VALIDATE_TIMEOUT_MS, 10);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    const payload = { overall: 'error', error: 'Timeout must be a positive integer.' };
+    if (options.json) {
+      printJson(payload, 2);
+      return;
+    }
+    console.error(chalk.red('Timeout must be a positive integer.'));
+    process.exit(2);
+  }
+
+  const result = await validateConfiguredConnector(context.root, {
+    runtimeId,
+    roleId: options.role || null,
+    timeoutMs,
+    keepArtifacts: options.keepArtifacts === true,
+  });
+
+  if (options.json) {
+    printJson(result, result.exitCode ?? 1);
+    return;
+  }
+
+  printValidateText(result, result.exitCode ?? 1);
+}

package/src/commands/doctor.js

@@ -423,7 +423,7 @@ function getConnectorProbeRecommendation(runtimes) {
   return {
     recommended: true,
     runtimeIds,
-    detail: 'run `agentxchain connector check` to live-probe api / remote HTTP runtimes before the first governed turn.',
+    detail: 'run `agentxchain connector check` to live-probe api / remote HTTP runtimes, then `agentxchain connector validate <runtime_id>` to prove one binding produces valid governed turn results.',
   };
 }
 

package/src/commands/init.js

@@ -990,6 +990,10 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.bold('agentxchain doctor')} ${chalk.dim('# verify runtimes, config, and readiness')}`);
   if (hasLiveConnectorProbe) {
     console.log(`    ${chalk.bold('agentxchain connector check')} ${chalk.dim('# live-probe configured runtimes before the first turn')}`);
+    const firstNonManualRtId = Object.entries(config.runtimes || {}).find(([, rt]) => rt?.type && rt.type !== 'manual')?.[0];
+    if (firstNonManualRtId) {
+      console.log(`    ${chalk.bold(`agentxchain connector validate ${firstNonManualRtId}`)} ${chalk.dim('# prove the runtime produces valid governed turn results')}`);
+    }
   }
   console.log(`    ${chalk.bold('git add -A')} ${chalk.dim('# stage the governed scaffold')}`);
   console.log(`    ${chalk.bold('git commit -m "initial governed scaffold"')} ${chalk.dim('# checkpoint the starting state')}`);

package/src/commands/run.js

@@ -300,7 +300,7 @@ export async function executeGovernedRun(context, opts = {}) {
 
       // ── Route to adapter ──────────────────────────────────────────────
       const adapterOpts = {
-        signal: controller.signal,
+        signal: combineAbortSignals(controller.signal, ctx.dispatchAbortSignal),
         onStatus: (msg) => log(chalk.dim(`  ${msg}`)),
         verifyManifest: true,
         turnId: turn.turn_id,
@@ -557,3 +557,28 @@ function printManualQaFallback(log = console.log) {
   log(chalk.dim('  - Then recover the retained QA turn with: agentxchain step --resume'));
   log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
 }
+
+function combineAbortSignals(primarySignal, secondarySignal) {
+  if (!secondarySignal) {
+    return primarySignal;
+  }
+  if (!primarySignal) {
+    return secondarySignal;
+  }
+  if (typeof AbortSignal.any === 'function') {
+    return AbortSignal.any([primarySignal, secondarySignal]);
+  }
+
+  const combined = new AbortController();
+  const forward = (signal) => {
+    if (!signal) return;
+    if (signal.aborted) {
+      combined.abort(signal.reason);
+      return;
+    }
+    signal.addEventListener('abort', () => combined.abort(signal.reason), { once: true });
+  };
+  forward(primarySignal);
+  forward(secondarySignal);
+  return combined.signal;
+}

package/src/commands/status.js

@@ -13,7 +13,7 @@ import { getContinuityStatus } from '../lib/continuity-status.js';
 import { getConnectorHealth } from '../lib/connector-health.js';
 import { readRepoDecisions, summarizeRepoDecisions } from '../lib/repo-decisions.js';
 import { deriveWorkflowKitArtifacts } from '../lib/workflow-kit-artifacts.js';
-import { evaluateTimeouts } from '../lib/timeout-evaluator.js';
+import { evaluateTimeouts, computeTimeoutBudget } from '../lib/timeout-evaluator.js';
 import { evaluateApprovalSlaReminders } from '../lib/notification-runner.js';
 import { summarizeRunProvenance } from '../lib/run-provenance.js';
 import { readRecentRunEventSummary } from '../lib/recent-event-summary.js';
@@ -283,7 +283,19 @@ function renderGovernedStatus(context, opts) {
           elapsedTag = m > 0 ? ` — ${m}m ${s % 60}s` : ` — ${s}s`;
         }
       }
-      console.log(`    ${marker} ${turn.turn_id} — ${chalk.bold(turn.assigned_role)} (${statusLabel}) [attempt ${turn.attempt}]${elapsedTag}`);
+      let budgetTag = '';
+      if (config.timeouts?.per_turn_minutes && turn.started_at) {
+        const tb = computeTimeoutBudget({ config, state, turn, now: new Date() });
+        const tBudget = tb.find((b) => b.scope === 'turn');
+        if (tBudget) {
+          if (tBudget.exceeded) {
+            budgetTag = ` ${chalk.red('[TIMEOUT]')}`;
+          } else {
+            budgetTag = ` ${chalk.dim(`[${tBudget.remaining_minutes}m left]`)}`;
+          }
+        }
+      }
+      console.log(`    ${marker} ${turn.turn_id} — ${chalk.bold(turn.assigned_role)} (${statusLabel}) [attempt ${turn.attempt}]${elapsedTag}${budgetTag}`);
       if (turn.status === 'conflicted' && turn.conflict_state) {
         const cs = turn.conflict_state;
         const files = cs.conflict_error?.conflicting_files || [];
@@ -314,6 +326,21 @@ function renderGovernedStatus(context, opts) {
         console.log(`  ${chalk.dim('Elapsed:')}  ${elapsed}`);
       }
     }
+    // Turn-level timeout budget inline with turn info
+    if (config.timeouts?.per_turn_minutes && singleActiveTurn.started_at) {
+      const turnBudgets = computeTimeoutBudget({ config, state, turn: singleActiveTurn, now: new Date() });
+      const turnBudget = turnBudgets.find((b) => b.scope === 'turn');
+      if (turnBudget) {
+        if (turnBudget.exceeded) {
+          console.log(`  ${chalk.dim('Budget:')}   ${chalk.red(`EXCEEDED — was ${turnBudget.limit_minutes}m, over by ${turnBudget.elapsed_minutes - turnBudget.limit_minutes}m`)}`);
+        } else {
+          const remMins = Math.floor(turnBudget.remaining_seconds / 60);
+          const remSecs = turnBudget.remaining_seconds % 60;
+          const remLabel = remMins > 0 ? `${remMins}m ${remSecs}s` : `${remSecs}s`;
+          console.log(`  ${chalk.dim('Budget:')}   ${chalk.green(`${remLabel} remaining`)} of ${turnBudget.limit_minutes}m (deadline ${new Date(turnBudget.deadline_iso).toLocaleTimeString()})`);
+        }
+      }
+    }
     if (singleActiveTurn.status === 'conflicted' && singleActiveTurn.conflict_state) {
       const cs = singleActiveTurn.conflict_state;
       const files = cs.conflict_error?.conflicting_files || [];
@@ -474,19 +501,22 @@ function renderGovernedStatus(context, opts) {
   renderWorkflowKitArtifactsSection(workflowKitArtifacts);
 
   if (config.timeouts && (state?.status === 'active' || approvalPending)) {
+    const nowDate = new Date();
     const activeTurn = state?.status === 'active' ? getActiveTurn(state) : null;
     const turnResult = activeTurn ? { role: activeTurn.assigned_role } : undefined;
-    const timeoutEval = evaluateTimeouts({ config, state, turn: activeTurn, turnResult, now: new Date().toISOString() });
+    const timeoutEval = evaluateTimeouts({ config, state, turn: activeTurn, turnResult, now: nowDate.toISOString() });
     const allItems = [...timeoutEval.exceeded, ...timeoutEval.warnings];
-    if (allItems.length > 0 || approvalPending) {
+    // Compute full budget for phase/run scopes (turn budget is shown inline with turn info above)
+    const budgets = computeTimeoutBudget({ config, state, turn: activeTurn, now: nowDate })
+      .filter((b) => b.scope !== 'turn'); // turn budget already shown inline
+
+    if (allItems.length > 0 || budgets.length > 0 || approvalPending) {
       console.log('');
       console.log(`  ${chalk.dim('Timeouts:')}`);
       if (approvalPending) {
         console.log(`    ${chalk.yellow('◷')} approval wait does not mutate timeout state; phase/run clocks keep ticking until the next accepted turn`);
       }
-      if (approvalPending && allItems.length === 0) {
-        console.log(`    ${chalk.dim('No current phase/run timeout pressure.')}`);
-      }
+      // Show exceeded/warned items
       for (const item of allItems) {
         const isExceeded = timeoutEval.exceeded.includes(item);
         const elapsed = item.elapsed_minutes != null ? `${item.elapsed_minutes}m` : '?';
@@ -495,6 +525,17 @@ function renderGovernedStatus(context, opts) {
         const label = isExceeded ? chalk.red(`EXCEEDED ${item.scope}`) : chalk.yellow(`${item.scope}`);
         console.log(`    ${icon} ${label}: ${elapsed}/${limit} (action: ${item.action || 'n/a'})`);
       }
+      // Show remaining budget for non-exceeded phase/run scopes
+      const exceededScopes = new Set(allItems.map((i) => `${i.scope}:${i.phase || ''}`));
+      for (const b of budgets) {
+        const key = `${b.scope}:${b.phase || ''}`;
+        if (exceededScopes.has(key)) continue; // already shown as exceeded above
+        const scopeLabel = b.scope === 'phase' ? `phase (${b.phase})` : b.scope;
+        console.log(`    ${chalk.green('✓')} ${scopeLabel}: ${b.elapsed_minutes}m/${b.limit_minutes}m — ${chalk.green(`${b.remaining_minutes}m remaining`)}`);
+      }
+      if (approvalPending && allItems.length === 0 && budgets.length === 0) {
+        console.log(`    ${chalk.dim('No current phase/run timeout pressure.')}`);
+      }
     }
   }
 

package/src/commands/turn.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import { getActiveTurnCount, getActiveTurns } from '../lib/governed-state.js';
+import { computeTimeoutBudget } from '../lib/timeout-evaluator.js';
 import {
   getDispatchAssignmentPath,
   getDispatchContextPath,
@@ -54,11 +55,11 @@ export function turnShowCommand(turnId, opts) {
   }
 
   if (opts.json) {
-    console.log(JSON.stringify(buildTurnPayload(selectedTurnId, turn, state, artifacts, assignment), null, 2));
+    console.log(JSON.stringify(buildTurnPayload(selectedTurnId, turn, state, artifacts, assignment, context.config), null, 2));
     return;
   }
 
-  printTurnSummary(selectedTurnId, turn, state, artifacts, assignment);
+  printTurnSummary(selectedTurnId, turn, state, artifacts, assignment, context.config);
 }
 
 function requireGovernedContext() {
@@ -118,9 +119,9 @@ function buildArtifactIndex(root, turnId) {
   );
 }
 
-function buildTurnPayload(turnId, turn, state, artifacts, assignment) {
+function buildTurnPayload(turnId, turn, state, artifacts, assignment, config) {
   const elapsedMs = getElapsedMs(turn.started_at);
-  return {
+  const payload = {
     turn_id: turnId,
     run_id: state.run_id || assignment?.run_id || null,
     phase: state.phase || assignment?.phase || null,
@@ -140,9 +141,17 @@ function buildTurnPayload(turnId, turn, state, artifacts, assignment) {
       }]),
     ),
   };
+  // Add timeout budget if configured
+  if (config?.timeouts) {
+    const budgets = computeTimeoutBudget({ config, state, turn, now: new Date() });
+    if (budgets.length > 0) {
+      payload.timeout_budget = budgets;
+    }
+  }
+  return payload;
 }
 
-function printTurnSummary(turnId, turn, state, artifacts, assignment) {
+function printTurnSummary(turnId, turn, state, artifacts, assignment, config) {
   const elapsedMs = getElapsedMs(turn.started_at);
   console.log('');
   console.log(chalk.bold(`  Turn: ${chalk.cyan(turnId)}`));
@@ -159,6 +168,21 @@ function printTurnSummary(turnId, turn, state, artifacts, assignment) {
   if (elapsedMs != null) {
     console.log(`  ${chalk.dim('Elapsed:')}  ${formatElapsed(elapsedMs)}`);
   }
+  // Timeout budget per scope
+  if (config?.timeouts) {
+    const budgets = computeTimeoutBudget({ config, state, turn, now: new Date() });
+    for (const b of budgets) {
+      const scopeLabel = b.scope === 'phase' ? `phase (${b.phase})` : b.scope;
+      if (b.exceeded) {
+        console.log(`  ${chalk.dim('Timeout:')}  ${chalk.red(`${scopeLabel} EXCEEDED`)} — was ${b.limit_minutes}m, over by ${b.elapsed_minutes - b.limit_minutes}m`);
+      } else {
+        const remMins = Math.floor(b.remaining_seconds / 60);
+        const remSecs = b.remaining_seconds % 60;
+        const remLabel = remMins > 0 ? `${remMins}m ${remSecs}s` : `${remSecs}s`;
+        console.log(`  ${chalk.dim('Timeout:')}  ${scopeLabel} — ${chalk.green(`${remLabel} remaining`)} of ${b.limit_minutes}m`);
+      }
+    }
+  }
   console.log(`  ${chalk.dim('Dispatch:')} ${getDispatchTurnDir(turnId)}`);
   if (assignment?.staging_result_path) {
     console.log(`  ${chalk.dim('Staging:')}  ${assignment.staging_result_path}`);

package/src/lib/connector-validate.js

@@ -0,0 +1,504 @@
+import { execFileSync } from 'node:child_process';
+import {
+  cpSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readlinkSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+import { loadProjectContext } from './config.js';
+import { writeDispatchBundle } from './dispatch-bundle.js';
+import { getActiveTurn, initializeGovernedRun, assignGovernedTurn, readTurnCostUsd } from './governed-state.js';
+import { dispatchApiProxy } from './adapters/api-proxy-adapter.js';
+import { dispatchLocalCli, saveDispatchLogs } from './adapters/local-cli-adapter.js';
+import { dispatchMcp } from './adapters/mcp-adapter.js';
+import { dispatchRemoteAgent } from './adapters/remote-agent-adapter.js';
+import { getDispatchPromptPath, getTurnStagingResultPath } from './turn-paths.js';
+import { validateStagedTurnResult } from './turn-result-validator.js';
+
+const VALIDATABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
+const DEFAULT_VALIDATE_TIMEOUT_MS = 120_000;
+
+export async function validateConfiguredConnector(sourceRoot, options = {}) {
+  const sourceContext = loadProjectContext(sourceRoot);
+  if (!sourceContext) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: 'No governed agentxchain.json found.',
+    };
+  }
+
+  if (sourceContext.config.protocol_mode !== 'governed') {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: 'connector validate only supports governed projects.',
+    };
+  }
+
+  const runtimeId = typeof options.runtimeId === 'string' ? options.runtimeId.trim() : '';
+  if (!runtimeId) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: 'Runtime id is required. Usage: agentxchain connector validate <runtime_id>',
+    };
+  }
+
+  const timeoutMs = Number.parseInt(options.timeoutMs ?? DEFAULT_VALIDATE_TIMEOUT_MS, 10);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: 'Timeout must be a positive integer.',
+    };
+  }
+
+  const runtime = sourceContext.config.runtimes?.[runtimeId];
+  if (!runtime) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: `Unknown connector runtime "${runtimeId}"`,
+    };
+  }
+  if (runtime.type === 'manual') {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: `Runtime "${runtimeId}" is manual. connector validate only supports automated runtimes.`,
+    };
+  }
+  if (!VALIDATABLE_RUNTIME_TYPES.has(runtime.type)) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: `Runtime "${runtimeId}" of type "${runtime.type}" cannot be validated by connector validate.`,
+    };
+  }
+
+  const roleSelection = resolveValidationRole(sourceContext.config, runtimeId, options.roleId);
+  if (!roleSelection.ok) {
+    return {
+      ok: false,
+      exitCode: 2,
+      overall: 'error',
+      error: roleSelection.error,
+    };
+  }
+
+  const tempBase = mkdtempSync(join(tmpdir(), 'axc-connector-validate-'));
+  const scratchRoot = join(tempBase, 'workspace');
+  const warnings = [...roleSelection.warnings];
+  let keepArtifacts = options.keepArtifacts === true;
+  let dispatch = null;
+  let validation = null;
+  let costUsd = null;
+
+  try {
+    copyRepoForValidation(sourceRoot, scratchRoot);
+    initializeScratchGit(scratchRoot);
+
+    const scratchContext = loadProjectContext(scratchRoot);
+    if (!scratchContext) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: 'Failed to load governed config inside scratch workspace.',
+        scratch_root: scratchRoot,
+      };
+    }
+
+    const initResult = initializeGovernedRun(scratchRoot, scratchContext.config, {
+      provenance: {
+        trigger: 'connector_validate',
+        runtime_id: runtimeId,
+        role_id: roleSelection.roleId,
+      },
+    });
+    if (!initResult.ok) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: initResult.error,
+        scratch_root: scratchRoot,
+      };
+    }
+
+    const assignResult = assignGovernedTurn(scratchRoot, scratchContext.config, roleSelection.roleId);
+    if (!assignResult.ok) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: assignResult.error,
+        scratch_root: scratchRoot,
+      };
+    }
+
+    const state = assignResult.state;
+    const turn = getActiveTurn(state);
+    if (!turn) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: 'Synthetic validation turn was not assigned.',
+        scratch_root: scratchRoot,
+      };
+    }
+
+    const bundleResult = writeDispatchBundle(scratchRoot, state, scratchContext.config, { turnId: turn.turn_id });
+    if (!bundleResult.ok) {
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        error: bundleResult.error,
+        scratch_root: scratchRoot,
+      };
+    }
+    if (Array.isArray(bundleResult.warnings)) {
+      warnings.push(...bundleResult.warnings);
+    }
+
+    appendValidationPrompt(scratchRoot, scratchContext.config, state, turn);
+    configureRuntimeValidationTimeout(scratchContext.config, runtimeId, timeoutMs);
+
+    const signal = AbortSignal.timeout(timeoutMs);
+    const adapterResult = await dispatchValidationTurn(
+      scratchRoot,
+      state,
+      scratchContext.config,
+      runtimeId,
+      { turnId: turn.turn_id, signal },
+    );
+
+    dispatch = {
+      ok: adapterResult.ok,
+      error: adapterResult.error || null,
+      timed_out: adapterResult.timedOut === true,
+      aborted: adapterResult.aborted === true,
+      log_count: Array.isArray(adapterResult.logs) ? adapterResult.logs.length : 0,
+    };
+
+    if (Array.isArray(adapterResult.logs) && adapterResult.logs.length > 0) {
+      saveDispatchLogs(scratchRoot, turn.turn_id, adapterResult.logs);
+    }
+
+    if (!adapterResult.ok) {
+      keepArtifacts = true;
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        dispatch,
+        validation: null,
+        scratch_root: scratchRoot,
+      };
+    }
+
+    validation = validateStagedTurnResult(scratchRoot, state, scratchContext.config, {
+      stagingPath: getTurnStagingResultPath(turn.turn_id),
+    });
+    costUsd = validation?.turnResult ? readTurnCostUsd(validation.turnResult) : null;
+
+    if (!validation.ok) {
+      keepArtifacts = true;
+      return {
+        ok: false,
+        exitCode: 1,
+        overall: 'fail',
+        runtime_id: runtimeId,
+        runtime_type: runtime.type,
+        role_id: roleSelection.roleId,
+        timeout_ms: timeoutMs,
+        warnings,
+        dispatch,
+        validation: {
+          ok: false,
+          stage: validation.stage,
+          error_class: validation.error_class,
+          errors: validation.errors,
+          warnings: validation.warnings,
+        },
+        cost_usd: costUsd,
+        scratch_root: scratchRoot,
+      };
+    }
+
+    return {
+      ok: true,
+      exitCode: 0,
+      overall: 'pass',
+      runtime_id: runtimeId,
+      runtime_type: runtime.type,
+      role_id: roleSelection.roleId,
+      timeout_ms: timeoutMs,
+      warnings,
+      dispatch,
+      validation: {
+        ok: true,
+        stage: null,
+        error_class: null,
+        errors: [],
+        warnings: validation.warnings,
+      },
+      cost_usd: costUsd,
+      scratch_root: keepArtifacts ? scratchRoot : null,
+    };
+  } catch (error) {
+    keepArtifacts = true;
+    return {
+      ok: false,
+      exitCode: 1,
+      overall: 'fail',
+      runtime_id: runtimeId,
+      runtime_type: runtime.type,
+      role_id: roleSelection.roleId,
+      timeout_ms: timeoutMs,
+      warnings,
+      dispatch,
+      validation,
+      error: error.message,
+      scratch_root: scratchRoot,
+    };
+  } finally {
+    if (!keepArtifacts) {
+      try {
+        rmSync(tempBase, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+}
+
+function resolveValidationRole(config, runtimeId, requestedRoleId) {
+  const matchingRoles = Object.entries(config.roles || {})
+    .filter(([, role]) => (role.runtime_id || role.runtime) === runtimeId)
+    .map(([roleId]) => roleId)
+    .sort((a, b) => a.localeCompare(b, 'en'));
+
+  if (matchingRoles.length === 0) {
+    return { ok: false, error: `No roles are bound to runtime "${runtimeId}".` };
+  }
+
+  if (requestedRoleId) {
+    if (!config.roles?.[requestedRoleId]) {
+      return { ok: false, error: `Unknown role "${requestedRoleId}".` };
+    }
+    const boundRuntimeId = config.roles[requestedRoleId].runtime_id || config.roles[requestedRoleId].runtime;
+    if (boundRuntimeId !== runtimeId) {
+      return {
+        ok: false,
+        error: `Role "${requestedRoleId}" is not bound to runtime "${runtimeId}".`,
+      };
+    }
+    return { ok: true, roleId: requestedRoleId, warnings: [] };
+  }
+
+  const warnings = [];
+  if (matchingRoles.length > 1) {
+    warnings.push(
+      `Runtime "${runtimeId}" is shared by multiple roles (${matchingRoles.join(', ')}). ` +
+      `Validated the first binding "${matchingRoles[0]}". Use --role to target another binding.`,
+    );
+  }
+
+  return {
+    ok: true,
+    roleId: matchingRoles[0],
+    warnings,
+  };
+}
+
+function copyRepoForValidation(sourceRoot, scratchRoot) {
+  mkdirSync(scratchRoot, { recursive: true });
+  copyTree(sourceRoot, scratchRoot);
+}
+
+function copyTree(sourcePath, destPath) {
+  mkdirSync(destPath, { recursive: true });
+  for (const entry of readdirSync(sourcePath, { withFileTypes: true })) {
+    if (entry.name === '.git' || entry.name === '.agentxchain') {
+      continue;
+    }
+
+    const sourceEntry = join(sourcePath, entry.name);
+    const destEntry = join(destPath, entry.name);
+    const stats = lstatSync(sourceEntry);
+
+    if (stats.isSymbolicLink()) {
+      symlinkSync(readlinkSync(sourceEntry), destEntry);
+      continue;
+    }
+
+    if (stats.isDirectory()) {
+      if (entry.name === 'node_modules') {
+        symlinkSync(sourceEntry, destEntry, 'dir');
+        continue;
+      }
+      copyTree(sourceEntry, destEntry);
+      continue;
+    }
+
+    mkdirSync(dirname(destEntry), { recursive: true });
+    cpSync(sourceEntry, destEntry, { force: true, preserveTimestamps: true });
+  }
+}
+
+function initializeScratchGit(root) {
+  execFileSync('git', ['init', '-q'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['checkout', '-q', '-b', 'main'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['add', '-A'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['commit', '-q', '-m', 'connector validation baseline'], {
+    cwd: root,
+    stdio: 'ignore',
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'AgentXchain Validator',
+      GIT_AUTHOR_EMAIL: 'noreply@agentxchain.dev',
+      GIT_COMMITTER_NAME: 'AgentXchain Validator',
+      GIT_COMMITTER_EMAIL: 'noreply@agentxchain.dev',
+    },
+  });
+}
+
+function appendValidationPrompt(root, config, state, turn) {
+  const promptPath = join(root, getDispatchPromptPath(turn.turn_id));
+  const role = config.roles?.[turn.assigned_role];
+  const reviewOnly = role?.write_authority === 'review_only';
+  const validationTurn = {
+    schema_version: '1.0',
+    run_id: state.run_id,
+    turn_id: turn.turn_id,
+    role: turn.assigned_role,
+    runtime_id: turn.runtime_id,
+    status: 'completed',
+    summary: 'Connector validation synthetic turn completed without modifying product files.',
+    decisions: [
+      {
+        id: 'DEC-900',
+        category: 'process',
+        statement: 'The runtime emitted a schema-valid connector validation result.',
+        rationale: 'Synthetic dispatch completed and staged a governed turn result.',
+      },
+    ],
+    objections: reviewOnly ? [
+      {
+        id: 'OBJ-900',
+        severity: 'low',
+        statement: 'Validation objection: this is a synthetic proof turn, not delivery work.',
+        status: 'acknowledged',
+      },
+    ] : [],
+    files_changed: [],
+    verification: {
+      status: 'skipped',
+      evidence_summary: 'Synthetic connector validation turn; no repo work requested.',
+    },
+    artifact: {
+      type: 'review',
+      ref: null,
+    },
+    proposed_next_role: 'human',
+  };
+
+  const lines = [
+    '',
+    '## Connector Validation Override',
+    '',
+    'This dispatch is a connector-validation proof turn, not real product work.',
+    '',
+    'You must follow these extra constraints:',
+    '',
+    '1. Do not edit any product files.',
+    '2. Write exactly one governed turn result to the staged result path already provided in ASSIGNMENT.json.',
+    '3. Use `files_changed: []` and `artifact.type: "review"`.',
+    '4. Do not request a phase transition or run completion.',
+    '5. Set `proposed_next_role: "human"`.',
+    reviewOnly ? '6. Include at least one objection because this role is review_only.' : '6. Objections may be empty because this role is not review_only.',
+    '',
+    'Use this JSON shape as your starting point and replace nothing except if you need equivalent wording:',
+    '',
+    '```json',
+    JSON.stringify(validationTurn, null, 2),
+    '```',
+    '',
+  ];
+
+  writeFileSync(promptPath, lines.join('\n'), { flag: 'a' });
+}
+
+function configureRuntimeValidationTimeout(config, runtimeId, timeoutMs) {
+  if (config?.runtimes?.[runtimeId] && config.runtimes[runtimeId].type === 'remote_agent') {
+    config.runtimes[runtimeId] = {
+      ...config.runtimes[runtimeId],
+      timeout_ms: timeoutMs,
+    };
+  }
+}
+
+async function dispatchValidationTurn(root, state, config, runtimeId, options = {}) {
+  const runtime = config.runtimes?.[runtimeId];
+  switch (runtime?.type) {
+    case 'local_cli':
+      return dispatchLocalCli(root, state, config, options);
+    case 'api_proxy':
+      return dispatchApiProxy(root, state, config, options);
+    case 'mcp':
+      return dispatchMcp(root, state, config, options);
+    case 'remote_agent':
+      return dispatchRemoteAgent(root, state, config, options);
+    default:
+      return { ok: false, error: `Unsupported runtime type "${runtime?.type || 'unknown'}"` };
+  }
+}
+
+export { DEFAULT_VALIDATE_TIMEOUT_MS, VALIDATABLE_RUNTIME_TYPES };

package/src/lib/dashboard/timeout-status.js

@@ -9,7 +9,7 @@
 
 import { join } from 'path';
 import { loadProjectContext, loadProjectState } from '../config.js';
-import { evaluateTimeouts } from '../timeout-evaluator.js';
+import { evaluateTimeouts, computeTimeoutBudget } from '../timeout-evaluator.js';
 import { readJsonlFile } from './state-reader.js';
 
 /**
@@ -209,7 +209,15 @@ export function readTimeoutStatus(workspacePath) {
   const configSummary = buildTimeoutConfigSummary(timeouts, config.routing);
 
   // Live timeout evaluation — only meaningful when the run is active
-  const live = evaluateDashboardTimeoutPressure(config, state, new Date());
+  const nowDate = new Date();
+  const live = evaluateDashboardTimeoutPressure(config, state, nowDate);
+
+  // Compute remaining budget for all configured scopes
+  const activeTurnsList = getActiveTurns(state);
+  const primaryTurn = activeTurnsList.length === 1 ? activeTurnsList[0] : null;
+  const budget = (state?.status === 'active' || Boolean(state?.pending_phase_transition || state?.pending_run_completion))
+    ? computeTimeoutBudget({ config, state, turn: primaryTurn, now: nowDate })
+    : [];
 
   // Persisted timeout events from the decision ledger
   const ledger = readJsonlFile(agentxchainDir, 'decision-ledger.jsonl');
@@ -223,6 +231,7 @@ export function readTimeoutStatus(workspacePath) {
         configured: true,
         config: configSummary,
         live,
+        budget,
         live_context: buildLiveContext(state),
         events,
       },

package/src/lib/run-loop.js

@@ -12,7 +12,7 @@
  *   - Never calls process dot exit
  *   - No stdout/stderr
  *   - No adapter dispatch (caller provides dispatch callback)
- *   - Imports only from runner-interface.js
+ *   - Governed lifecycle operations import through runner-interface.js
  */
 
 import {
@@ -21,6 +21,7 @@ import {
   assignTurn,
   acceptTurn,
   rejectTurn,
+  markRunBlocked,
   writeDispatchBundle,
   getTurnStagingResultPath,
   approvePhaseGate,
@@ -33,10 +34,11 @@ import {
 } from './runner-interface.js';
 
 import { runAdmissionControl } from './admission-control.js';
-import { mkdirSync, writeFileSync } from 'fs';
+import { appendFileSync, mkdirSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { evaluateApprovalSlaReminders } from './notification-runner.js';
 import { readPreemptionMarker } from './intake.js';
+import { buildTimeoutBlockedReason, evaluateTimeouts } from './timeout-evaluator.js';
 
 const DEFAULT_MAX_TURNS = 50;
 
@@ -214,6 +216,7 @@ async function executeSequentialTurn(root, config, state, callbacks, emit, error
 async function executeParallelTurns(root, config, state, maxConcurrent, callbacks, emit, errors) {
   const history = [];
   let acceptedCount = 0;
+  const timedOutDispatches = [];
 
   // ── Collect active turns that need dispatch (retries) ────────────────
   const activeTurns = getActiveTurns(state);
@@ -332,7 +335,7 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
   const dispatchResults = await Promise.allSettled(
     contexts.map(async (ctx) => {
       try {
-        return { ctx, result: await callbacks.dispatch(ctx) };
+        return { ctx, result: await dispatchWithTimeout(ctx, config, callbacks.dispatch) };
       } catch (err) {
         return { ctx, result: { accept: false, reason: `dispatch threw: ${err.message}` } };
       }
@@ -350,6 +353,11 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
     const { turn } = ctx;
     const roleId = turn.assigned_role;
 
+    if (dispatchResult?.timed_out === true) {
+      timedOutDispatches.push({ ctx, dispatchResult });
+      continue;
+    }
+
     if (dispatchResult.accept) {
       const absStaging = join(root, ctx.stagingPath);
       mkdirSync(dirname(absStaging), { recursive: true });
@@ -405,6 +413,13 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
     }
   }
 
+  if (timedOutDispatches.length > 0) {
+    const timedOut = timedOutDispatches[0];
+    const blocked = persistDispatchTimeout(root, config, timedOut.ctx.turn, timedOut.dispatchResult.timeout_result, errors);
+    emit({ type: 'blocked', state: blocked.state, reason: 'timeout:turn' });
+    return { terminal: true, ok: false, stop_reason: 'blocked', history, acceptedCount };
+  }
+
   // ── Stall detection: if no turns were accepted and no new roles were ──
   // ── assignable, terminate to avoid infinite re-dispatch loops. ────────
   if (acceptedCount === 0 && history.length > 0) {
@@ -445,12 +460,18 @@ async function dispatchAndProcess(root, config, turn, assignState, callbacks, em
 
   let dispatchResult;
   try {
-    dispatchResult = await callbacks.dispatch(context);
+    dispatchResult = await dispatchWithTimeout(context, config, callbacks.dispatch);
   } catch (err) {
     errors.push(`dispatch threw for ${roleId}: ${err.message}`);
     return { terminal: true, ok: false, stop_reason: 'dispatch_error', history };
   }
 
+  if (dispatchResult?.timed_out === true) {
+    const blocked = persistDispatchTimeout(root, config, turn, dispatchResult.timeout_result, errors);
+    emit({ type: 'blocked', state: blocked.state, reason: 'timeout:turn' });
+    return { terminal: true, ok: false, stop_reason: 'blocked', history };
+  }
+
   if (dispatchResult.accept) {
     const absStaging = join(root, stagingPath);
     mkdirSync(dirname(absStaging), { recursive: true });
@@ -574,3 +595,107 @@ function makeResult(ok, stop_reason, state, turns_executed, turn_history, gates_
 function noop() {}
 
 export { DEFAULT_MAX_TURNS };
+
+function buildTimeoutLedgerEntry(timeoutResult, timestamp, turnId, phase) {
+  return {
+    type: 'timeout',
+    scope: timeoutResult.scope,
+    phase: timeoutResult.phase || phase || null,
+    turn_id: turnId || null,
+    limit_minutes: timeoutResult.limit_minutes,
+    elapsed_minutes: timeoutResult.elapsed_minutes,
+    exceeded_by_minutes: timeoutResult.exceeded_by_minutes,
+    action: timeoutResult.action,
+    timestamp,
+  };
+}
+
+function appendJsonl(root, relPath, value) {
+  appendFileSync(join(root, relPath), `${JSON.stringify(value)}\n`);
+}
+
+function getDispatchTimeoutResult(config, state, turn, now = new Date()) {
+  const evaluation = evaluateTimeouts({ config, state, turn, now });
+  return evaluation.exceeded.find((entry) => entry.scope === 'turn' && entry.action === 'escalate') || null;
+}
+
+async function dispatchWithTimeout(context, config, dispatchFn) {
+  const timeoutResult = getDispatchTimeoutResult(config, context.state, context.turn);
+  if (!timeoutResult) {
+    return await dispatchFn(context);
+  }
+
+  const remainingMs = Math.max(
+    0,
+    timeoutResult.limit_minutes * 60 * 1000
+      - Math.max(0, new Date() - new Date(context.turn.started_at || context.turn.assigned_at || new Date())),
+  );
+  const abortController = new AbortController();
+  if (remainingMs === 0) {
+    abortController.abort(new Error(`Turn timeout exceeded after ${timeoutResult.limit_minutes}m`));
+    return {
+      timed_out: true,
+      timeout_result: timeoutResult,
+    };
+  }
+  const enrichedContext = {
+    ...context,
+    dispatchTimeoutMs: remainingMs,
+    dispatchDeadlineAt: new Date(Date.now() + remainingMs).toISOString(),
+    dispatchAbortSignal: abortController.signal,
+  };
+
+  let timer = null;
+  const dispatchPromise = Promise.resolve(dispatchFn(enrichedContext))
+    .then((result) => ({ kind: 'result', result }))
+    .catch((error) => ({ kind: 'error', error }));
+  const timeoutPromise = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      abortController.abort(new Error(`Turn timeout exceeded after ${timeoutResult.limit_minutes}m`));
+      resolve({ kind: 'timeout', timeoutResult });
+    }, remainingMs);
+  });
+
+  const winner = await Promise.race([dispatchPromise, timeoutPromise]);
+  clearTimeout(timer);
+
+  if (winner.kind === 'timeout') {
+    return {
+      timed_out: true,
+      timeout_result: winner.timeoutResult,
+    };
+  }
+
+  if (winner.kind === 'error') {
+    throw winner.error;
+  }
+
+  return winner.result;
+}
+
+function persistDispatchTimeout(root, config, turn, timeoutResult, errors) {
+  const blockedAt = new Date().toISOString();
+  const blockedReason = buildTimeoutBlockedReason(timeoutResult, { turnRetained: true });
+  const blocked = markRunBlocked(root, {
+    blockedOn: `timeout:${timeoutResult.scope}`,
+    category: blockedReason.category,
+    recovery: blockedReason.recovery,
+    turnId: turn.turn_id,
+    blockedAt,
+    notificationConfig: config,
+  });
+
+  if (!blocked.ok) {
+    errors.push(`markRunBlocked(timeout): ${blocked.error}`);
+    return { state: loadState(root, config) };
+  }
+
+  try {
+    appendJsonl(root, '.agentxchain/decision-ledger.jsonl', buildTimeoutLedgerEntry(timeoutResult, blockedAt, turn.turn_id, blocked.state?.phase));
+  } catch (err) {
+    errors.push(`timeout ledger append failed: ${err.message}`);
+  }
+
+  errors.push(`dispatch timed out for ${turn.assigned_role} after ${timeoutResult.limit_minutes}m`);
+  return blocked;
+}

package/src/lib/timeout-evaluator.js

@@ -210,6 +210,93 @@ export function validateTimeoutsConfig(timeouts, routing) {
   return { ok: errors.length === 0, errors };
 }
 
+/**
+ * Compute remaining timeout budget for an active turn/phase/run.
+ *
+ * Unlike evaluateTimeouts() which only returns items when exceeded,
+ * this returns budget info for ALL configured timeout scopes regardless
+ * of whether the deadline has passed.
+ *
+ * @param {object} options
+ * @param {object} options.config - Normalized config with optional `timeouts` section
+ * @param {object} options.state - Current governed state
+ * @param {object} [options.turn] - Active turn metadata
+ * @param {Date|string} [options.now] - Override for current time (testing)
+ * @returns {Array<TimeoutBudget>} Array of { scope, limit_minutes, elapsed_minutes, remaining_minutes, deadline_iso, exceeded, action }
+ */
+export function computeTimeoutBudget({ config, state, turn = null, now = new Date() }) {
+  const timeouts = config?.timeouts;
+  if (!timeouts) return [];
+
+  const nowMs = typeof now === 'string' ? new Date(now).getTime() : now.getTime();
+  const budgets = [];
+
+  // Per-turn budget
+  if (timeouts.per_turn_minutes && turn) {
+    const startedAt = turn.started_at || turn.assigned_at;
+    if (startedAt) {
+      const dispatchMs = new Date(startedAt).getTime();
+      const limitMs = timeouts.per_turn_minutes * 60 * 1000;
+      const elapsedMs = nowMs - dispatchMs;
+      const remainingMs = limitMs - elapsedMs;
+      budgets.push({
+        scope: 'turn',
+        limit_minutes: timeouts.per_turn_minutes,
+        elapsed_minutes: Math.round(elapsedMs / 60000),
+        remaining_minutes: Math.max(0, Math.round(remainingMs / 60000)),
+        remaining_seconds: Math.max(0, Math.round(remainingMs / 1000)),
+        deadline_iso: new Date(dispatchMs + limitMs).toISOString(),
+        exceeded: elapsedMs > limitMs,
+        action: resolveAction(timeouts.action, 'turn'),
+      });
+    }
+  }
+
+  // Per-phase budget
+  const phaseLimit = resolvePhaseLimit(timeouts, config.routing, state.phase);
+  const phaseAction = resolvePhaseAction(timeouts, config.routing, state.phase);
+  if (phaseLimit) {
+    const phaseEnteredAt = findPhaseEntryTime(state);
+    if (phaseEnteredAt) {
+      const entryMs = new Date(phaseEnteredAt).getTime();
+      const limitMs = phaseLimit * 60 * 1000;
+      const elapsedMs = nowMs - entryMs;
+      const remainingMs = limitMs - elapsedMs;
+      budgets.push({
+        scope: 'phase',
+        phase: state.phase,
+        limit_minutes: phaseLimit,
+        elapsed_minutes: Math.round(elapsedMs / 60000),
+        remaining_minutes: Math.max(0, Math.round(remainingMs / 60000)),
+        remaining_seconds: Math.max(0, Math.round(remainingMs / 1000)),
+        deadline_iso: new Date(entryMs + limitMs).toISOString(),
+        exceeded: elapsedMs > limitMs,
+        action: phaseAction,
+      });
+    }
+  }
+
+  // Per-run budget
+  if (timeouts.per_run_minutes && state.created_at) {
+    const createMs = new Date(state.created_at).getTime();
+    const limitMs = timeouts.per_run_minutes * 60 * 1000;
+    const elapsedMs = nowMs - createMs;
+    const remainingMs = limitMs - elapsedMs;
+    budgets.push({
+      scope: 'run',
+      limit_minutes: timeouts.per_run_minutes,
+      elapsed_minutes: Math.round(elapsedMs / 60000),
+      remaining_minutes: Math.max(0, Math.round(remainingMs / 60000)),
+      remaining_seconds: Math.max(0, Math.round(remainingMs / 1000)),
+      deadline_iso: new Date(createMs + limitMs).toISOString(),
+      exceeded: elapsedMs > limitMs,
+      action: resolveAction(timeouts.action, 'run'),
+    });
+  }
+
+  return budgets;
+}
+
 /**
  * Build a blocked_reason descriptor for a timeout.
  */