agentxchain 2.126.0 → 2.128.0

package/README.md

@@ -172,7 +172,8 @@ agentxchain step
 | `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
 | `verify turn` | Replay a staged turn's declared machine-evidence commands to confirm reproducibility before acceptance |
 | `replay turn` | Replay an accepted turn's machine-evidence commands from history for audit and drift detection |
-| `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
+| `conformance check` | Preferred front door for the shipped protocol conformance suite |
+| `verify protocol` | Compatibility alias for the shipped protocol conformance suite |
 | `dashboard` | Open the live local governance dashboard in your browser for the current repo/workspace or multi-repo coordinator initiative, including pending gate approvals |
 | `run [--auto-approve] [--max-turns N] [--dry-run]` | Drive a governed run from start to completion — dispatches turns, handles gates, manages rejection/retry |
 
@@ -247,9 +248,11 @@ Partial coordinator artifacts are first-class here too: `audit` and `report` kee
 AgentXchain ships a conformance kit under `.agentxchain-conformance/`. Use it to prove a runner or fork still implements the governed workflow contract:
 
 ```bash
-agentxchain verify protocol --tier 3 --target .
+agentxchain conformance check --tier 3 --target .
 ```
 
+`agentxchain verify protocol` remains available as a compatibility alias.
+
 Useful flags:
 
 - `--tier 1|2|3`: maximum conformance tier to verify

package/bin/agentxchain.js

@@ -542,6 +542,22 @@ program
   .option('-j, --json', 'Output as JSON')
   .action(validateCommand);
 
+const conformanceCmd = program
+  .command('conformance')
+  .description('Run protocol conformance checks against local or remote implementations');
+
+conformanceCmd
+  .command('check')
+  .description('Run the shipped protocol conformance fixture suite against a target implementation')
+  .option('--tier <tier>', 'Conformance tier to verify (1, 2, or 3)', '1')
+  .option('--surface <surface>', 'Restrict verification to a single surface')
+  .option('--target <path>', 'Target root containing .agentxchain-conformance/capabilities.json', '.')
+  .option('--remote <url>', 'Remote HTTP conformance endpoint base URL')
+  .option('--token <token>', 'Bearer token for remote HTTP conformance endpoint')
+  .option('--timeout <ms>', 'Per-fixture remote HTTP timeout in milliseconds', '30000')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .action(verifyProtocolCommand);
+
 const verifyCmd = program
   .command('verify')
   .description('Verify governed turns, export artifacts, and protocol conformance targets');

package/dashboard/components/timeline.js

@@ -95,6 +95,30 @@ function formatPercent(value) {
   return `${Math.round(value * 100)}%`;
 }
 
+function formatDispatchActivity(progress) {
+  if (!progress || typeof progress !== 'object') return null;
+  const lastActivityAt = progress.last_activity_at ? new Date(progress.last_activity_at) : null;
+  const agoSec = lastActivityAt && !Number.isNaN(lastActivityAt.getTime())
+    ? Math.round((Date.now() - lastActivityAt.getTime()) / 1000)
+    : null;
+
+  if (progress.activity_type === 'silent') {
+    const silentSince = progress.silent_since ? new Date(progress.silent_since) : null;
+    const silentSec = silentSince && !Number.isNaN(silentSince.getTime())
+      ? Math.round((Date.now() - silentSince.getTime()) / 1000)
+      : agoSec;
+    return `Silent for ${silentSec ?? 0}s (${progress.output_lines || 0} lines total, last output ${agoSec ?? 0}s ago)`;
+  }
+  if (progress.activity_type === 'request') {
+    return `API request in flight (${agoSec ?? 0}s ago)`;
+  }
+  if (progress.activity_type === 'response') {
+    return 'API response received';
+  }
+  const agoLabel = agoSec != null && agoSec > 0 ? `, last ${agoSec}s ago` : '';
+  return `Producing output (${progress.output_lines || 0} lines${agoLabel})`;
+}
+
 function statusBadge(status) {
   const colors = {
     running: 'var(--green)',
@@ -411,6 +435,9 @@ export function render({ state, continuity, history, events = null, annotations,
 
   const turnCount = Array.isArray(history) ? history.length : 0;
   const activeTurns = state.active_turns ? Object.values(state.active_turns) : [];
+  const dispatchProgress = state.dispatch_progress && typeof state.dispatch_progress === 'object'
+    ? state.dispatch_progress
+    : {};
 
   let html = `<div class="timeline-view">`;
 
@@ -436,6 +463,7 @@ export function render({ state, continuity, history, events = null, annotations,
     for (const turn of activeTurns) {
       const elapsedMs = computeElapsed(turn.started_at);
       const elapsedStr = formatDuration(elapsedMs);
+      const activity = formatDispatchActivity(dispatchProgress[turn.turn_id]);
       html += `<div class="turn-card active">
         <div class="turn-header">
           ${roleBadge(getRole(turn))}
@@ -445,6 +473,7 @@ export function render({ state, continuity, history, events = null, annotations,
         </div>
         ${renderDelegationContext(turn.delegation_context)}
         ${renderDelegationReview(turn.delegation_review)}
+        ${activity ? `<div class="turn-detail"><span class="detail-label">Activity:</span> ${esc(activity)}</div>` : ''}
       </div>`;
     }
     html += `</div></div>`;

package/package.json

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

package/src/commands/init.js

@@ -441,10 +441,20 @@ function commandHasPromptPlaceholder(parts = []) {
   return parts.some((part) => typeof part === 'string' && part.includes('{prompt}'));
 }
 
+function normalizeGovernedDevCommand(parts = []) {
+  if (!Array.isArray(parts) || parts.length === 0) {
+    return null;
+  }
+  const [head, ...rest] = parts;
+  const normalizedHead = String(head || '').trim().split(/\s+/).filter(Boolean);
+  const normalizedRest = rest
+    .map((part) => String(part).trim())
+    .filter(Boolean);
+  return [...normalizedHead, ...normalizedRest];
+}
+
 function resolveGovernedLocalDevRuntime(opts = {}) {
-  const customCommand = Array.isArray(opts.devCommand)
-    ? opts.devCommand.map((part) => String(part).trim()).filter(Boolean)
-    : null;
+  const customCommand = normalizeGovernedDevCommand(opts.devCommand);
   const explicitTransport = typeof opts.devPromptTransport === 'string' && opts.devPromptTransport.trim()
     ? opts.devPromptTransport.trim()
     : null;

package/src/commands/run.js

@@ -46,6 +46,8 @@ import {
 } from '../lib/turn-paths.js';
 import { resolveChainOptions, executeChainedRun } from '../lib/run-chain.js';
 import { resolveContinuousOptions, executeContinuousRun } from '../lib/continuous-run.js';
+import { createDispatchProgressTracker } from '../lib/dispatch-progress.js';
+import { emitRunEvent } from '../lib/run-events.js';
 
 export async function runCommand(opts) {
   const context = loadProjectContext();
@@ -191,6 +193,19 @@ export async function executeGovernedRun(context, opts = {}) {
       const supported = rtType !== 'manual';
       log(`  ${supported ? chalk.green('✓') : chalk.red('✗')} ${rid} → ${rtType}${supported ? '' : ' (not supported in run mode)'}`);
     }
+    // Warn if the first-dispatched role in the current phase is manual
+    if (roleId) {
+      const firstRole = config.roles?.[roleId];
+      const firstRtId = firstRole?.runtime;
+      const firstRt = config.runtimes?.[firstRtId];
+      const firstRtType = firstRt?.type || firstRole?.runtime_class || 'manual';
+      if (firstRtType === 'manual') {
+        log('');
+        log(chalk.yellow(`  ⚠ The current phase's first role (${roleId}) is manual.`));
+        log(chalk.yellow(`    "run" will block immediately. Complete manual turns via "agentxchain step" first,`));
+        log(chalk.yellow(`    or configure ${roleId} with an automatable runtime.`));
+      }
+    }
     return { exitCode: 0, result: null };
   }
 
@@ -299,6 +314,10 @@ export async function executeGovernedRun(context, opts = {}) {
       }
 
       // ── Route to adapter ──────────────────────────────────────────────
+      const tracker = createDispatchProgressTracker(projectRoot, turn, {
+        adapter_type: runtimeType,
+      });
+
       const adapterOpts = {
         signal: combineAbortSignals(controller.signal, ctx.dispatchAbortSignal),
         onStatus: (msg) => log(chalk.dim(`  ${msg}`)),
@@ -306,31 +325,103 @@ export async function executeGovernedRun(context, opts = {}) {
         turnId: turn.turn_id,
       };
 
+      const recordOutputActivity = (stream, text) => {
+        const lines = text.split('\n').length - 1 || 1;
+        const wasSilent = tracker.onOutput(stream, lines);
+        if (wasSilent) {
+          const progressState = tracker.getState();
+          emitRunEvent(projectRoot, 'dispatch_progress', {
+            run_id: state.run_id,
+            phase: state.phase,
+            status: state.status,
+            turn: { turn_id: turn.turn_id, assigned_role: roleId },
+            payload: {
+              milestone: 'output_resumed',
+              output_lines: progressState.output_lines,
+              elapsed_seconds: Math.round((Date.now() - new Date(progressState.started_at)) / 1000),
+              silent_seconds: 0,
+            },
+          });
+        }
+      };
+
       if (verbose) {
-        adapterOpts.onStdout = (text) => process.stdout.write(chalk.dim(text));
-        adapterOpts.onStderr = (text) => process.stderr.write(chalk.yellow(text));
+        adapterOpts.onStdout = (text) => {
+          process.stdout.write(chalk.dim(text));
+          recordOutputActivity('stdout', text);
+        };
+        adapterOpts.onStderr = (text) => {
+          process.stderr.write(chalk.yellow(text));
+          recordOutputActivity('stderr', text);
+        };
+      } else {
+        // Even in non-verbose mode, track output activity for progress visibility
+        adapterOpts.onStdout = (text) => {
+          recordOutputActivity('stdout', text);
+        };
+        adapterOpts.onStderr = (text) => {
+          recordOutputActivity('stderr', text);
+        };
       }
 
       let adapterResult;
 
-      if (runtimeType === 'api_proxy') {
-        log(chalk.dim(`  Dispatching to API proxy: ${runtime?.provider || '?'} / ${runtime?.model || '?'}`));
-        adapterResult = await dispatchApiProxy(projectRoot, state, cfg, adapterOpts);
-      } else if (runtimeType === 'mcp') {
-        const transport = resolveMcpTransport(runtime);
-        log(chalk.dim(`  Dispatching to MCP ${transport}: ${describeMcpRuntimeTarget(runtime)}`));
-        adapterResult = await dispatchMcp(projectRoot, state, cfg, adapterOpts);
-      } else if (runtimeType === 'local_cli') {
-        const transport = runtime ? resolvePromptTransport(runtime) : 'dispatch_bundle_only';
-        log(chalk.dim(`  Dispatching to local CLI: ${runtime?.command || '(default)'}  transport: ${transport}`));
-        adapterResult = await dispatchLocalCli(projectRoot, state, cfg, adapterOpts);
-      } else if (runtimeType === 'remote_agent') {
-        log(chalk.dim(`  Dispatching to remote agent: ${describeRemoteAgentTarget(runtime)}`));
-        adapterResult = await dispatchRemoteAgent(projectRoot, state, cfg, adapterOpts);
-      } else {
-        return { accept: false, reason: `unknown runtime type "${runtimeType}"` };
+      // Emit dispatch_progress started event and begin tracking
+      tracker.start();
+      emitRunEvent(projectRoot, 'dispatch_progress', {
+        run_id: state.run_id,
+        phase: state.phase,
+        status: state.status,
+        turn: { turn_id: turn.turn_id, assigned_role: roleId },
+        payload: { milestone: 'started', output_lines: 0, elapsed_seconds: 0, silent_seconds: 0 },
+      });
+
+      try {
+        if (runtimeType === 'api_proxy') {
+          log(chalk.dim(`  Dispatching to API proxy: ${runtime?.provider || '?'} / ${runtime?.model || '?'}`));
+          tracker.requestStarted();
+          adapterResult = await dispatchApiProxy(projectRoot, state, cfg, adapterOpts);
+          if (adapterResult.ok) tracker.responseReceived();
+        } else if (runtimeType === 'mcp') {
+          const transport = resolveMcpTransport(runtime);
+          log(chalk.dim(`  Dispatching to MCP ${transport}: ${describeMcpRuntimeTarget(runtime)}`));
+          tracker.requestStarted();
+          adapterResult = await dispatchMcp(projectRoot, state, cfg, adapterOpts);
+          if (adapterResult.ok) tracker.responseReceived();
+        } else if (runtimeType === 'local_cli') {
+          const transport = runtime ? resolvePromptTransport(runtime) : 'dispatch_bundle_only';
+          log(chalk.dim(`  Dispatching to local CLI: ${runtime?.command || '(default)'}  transport: ${transport}`));
+          adapterResult = await dispatchLocalCli(projectRoot, state, cfg, adapterOpts);
+        } else if (runtimeType === 'remote_agent') {
+          log(chalk.dim(`  Dispatching to remote agent: ${describeRemoteAgentTarget(runtime)}`));
+          tracker.requestStarted();
+          adapterResult = await dispatchRemoteAgent(projectRoot, state, cfg, adapterOpts);
+          if (adapterResult.ok) tracker.responseReceived();
+        } else {
+          tracker.fail();
+          return { accept: false, reason: `unknown runtime type "${runtimeType}"` };
+        }
+      } catch (err) {
+        tracker.fail();
+        emitRunEvent(projectRoot, 'dispatch_progress', {
+          run_id: state.run_id, phase: state.phase, status: state.status,
+          turn: { turn_id: turn.turn_id, assigned_role: roleId },
+          payload: { milestone: 'failed', output_lines: tracker.getState().output_lines, elapsed_seconds: Math.round((Date.now() - new Date(tracker.getState().started_at)) / 1000), silent_seconds: 0 },
+        });
+        throw err;
       }
 
+      // Emit completion/failure progress event and clean up tracker
+      const progressState = tracker.getState();
+      const elapsedSec = Math.round((Date.now() - new Date(progressState.started_at)) / 1000);
+      const milestone = adapterResult.ok ? 'completed' : (adapterResult.timedOut ? 'timed_out' : 'failed');
+      if (adapterResult.ok) { tracker.complete(); } else { tracker.fail(); }
+      emitRunEvent(projectRoot, 'dispatch_progress', {
+        run_id: state.run_id, phase: state.phase, status: state.status,
+        turn: { turn_id: turn.turn_id, assigned_role: roleId },
+        payload: { milestone, output_lines: progressState.output_lines, elapsed_seconds: elapsedSec, silent_seconds: progressState.silent_since ? Math.round((Date.now() - new Date(progressState.silent_since)) / 1000) : 0 },
+      });
+
       // Save adapter logs
       if (adapterResult.logs?.length) {
         saveDispatchLogs(projectRoot, turn.turn_id, adapterResult.logs);

package/src/commands/status.js

@@ -23,6 +23,7 @@ import { findCurrentHumanEscalation } from '../lib/human-escalations.js';
 import { getDashboardPid, getDashboardSession } from './dashboard.js';
 import { readPreemptionMarker } from '../lib/intake.js';
 import { readContinuousSession } from '../lib/continuous-run.js';
+import { readAllDispatchProgress } from '../lib/dispatch-progress.js';
 
 export async function statusCommand(opts) {
   const context = loadStatusContext();
@@ -142,6 +143,9 @@ function renderGovernedStatus(context, opts) {
   // Fire approval SLA reminders as a side effect (webhook-only, no CLI output)
   evaluateApprovalSlaReminders(root, config, state);
 
+  const activeTurns = getActiveTurns(state);
+  const dispatchProgress = filterDispatchProgressForActiveTurns(readAllDispatchProgress(root), activeTurns);
+
   if (opts.json) {
     const dashPid = getDashboardPid(root);
     const dashSession = getDashboardSession(root);
@@ -168,6 +172,7 @@ function renderGovernedStatus(context, opts) {
       next_actions: nextActions,
       connector_health: connectorHealth,
       recent_event_summary: recentEventSummary,
+      dispatch_progress: dispatchProgress,
       human_escalation: humanEscalation,
       preemption_marker: preemptionMarker,
       continuous_session: continuousSession,
@@ -262,7 +267,6 @@ function renderGovernedStatus(context, opts) {
   renderRecentEventSummary(recentEventSummary);
 
   const activeTurnCount = getActiveTurnCount(state);
-  const activeTurns = getActiveTurns(state);
   const singleActiveTurn = getActiveTurn(state);
   const approvalPending = Boolean(state?.pending_phase_transition || state?.pending_run_completion);
   if (activeTurnCount > 1) {
@@ -296,6 +300,10 @@ function renderGovernedStatus(context, opts) {
         }
       }
       console.log(`    ${marker} ${turn.turn_id} — ${chalk.bold(turn.assigned_role)} (${statusLabel}) [attempt ${turn.attempt}]${elapsedTag}${budgetTag}`);
+      const activityLine = formatDispatchActivityLine(dispatchProgress[turn.turn_id]);
+      if (activityLine) {
+        console.log(`      ${chalk.dim('Activity:')} ${activityLine}`);
+      }
       if (turn.status === 'conflicted' && turn.conflict_state) {
         const cs = turn.conflict_state;
         const files = cs.conflict_error?.conflicting_files || [];
@@ -341,6 +349,11 @@ function renderGovernedStatus(context, opts) {
         }
       }
     }
+    // Dispatch progress activity line (DEC-DISPATCH-PROGRESS-001)
+    const activityLine = formatDispatchActivityLine(dispatchProgress[singleActiveTurn.turn_id]);
+    if (activityLine) {
+      console.log(`  ${chalk.dim('Activity:')} ${activityLine}`);
+    }
     if (singleActiveTurn.status === 'conflicted' && singleActiveTurn.conflict_state) {
       const cs = singleActiveTurn.conflict_state;
       const files = cs.conflict_error?.conflicting_files || [];
@@ -743,6 +756,45 @@ function pluralizeRepoDecisionCount(count, singular, plural) {
   return `${count} ${count === 1 ? singular : plural}`;
 }
 
+function filterDispatchProgressForActiveTurns(progressByTurn, activeTurns) {
+  const filtered = {};
+  if (!progressByTurn || typeof progressByTurn !== 'object') {
+    return filtered;
+  }
+  for (const turn of Object.values(activeTurns || {})) {
+    const turnId = turn?.turn_id;
+    if (turnId && progressByTurn[turnId]) {
+      filtered[turnId] = progressByTurn[turnId];
+    }
+  }
+  return filtered;
+}
+
+function formatDispatchActivityLine(progress) {
+  if (!progress || typeof progress !== 'object') return null;
+  const lastAct = progress.last_activity_at ? new Date(progress.last_activity_at) : null;
+  const agoSec = lastAct && !Number.isNaN(lastAct.getTime())
+    ? Math.round((Date.now() - lastAct.getTime()) / 1000)
+    : null;
+
+  if (progress.activity_type === 'silent') {
+    const silentAt = progress.silent_since ? new Date(progress.silent_since) : null;
+    const silentSec = silentAt && !Number.isNaN(silentAt.getTime())
+      ? Math.round((Date.now() - silentAt.getTime()) / 1000)
+      : agoSec;
+    return chalk.yellow(`Silent for ${silentSec}s`) +
+      ` (${progress.output_lines || 0} lines total, last output ${agoSec ?? 0}s ago)`;
+  }
+  if (progress.activity_type === 'request') {
+    return chalk.cyan('API request in flight') + ` (${agoSec ?? 0}s ago)`;
+  }
+  if (progress.activity_type === 'response') {
+    return chalk.green('API response received');
+  }
+  const agoLabel = agoSec != null && agoSec > 0 ? `, last ${agoSec}s ago` : '';
+  return chalk.green('Producing output') + ` (${progress.output_lines || 0} lines${agoLabel})`;
+}
+
 function renderLastGateFailure(failure, config) {
   const entryRole = config?.routing?.[failure.phase]?.entry_role || null;
   const suggestedCommand = entryRole ? `agentxchain step --role ${entryRole}` : 'agentxchain step --role <role>';

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

@@ -278,7 +278,13 @@ function resolveCommand(runtime, fullPrompt) {
 
   // Shape 1: command is an array
   if (Array.isArray(runtime.command)) {
-    const [cmd, ...rest] = runtime.command;
+    // Normalize: if the first element contains spaces (e.g., ["echo test"]), split it
+    // into binary + args. Only the first element is split — later elements may contain
+    // legitimate spaces (e.g., script text for `node -e "..."`).
+    const first = runtime.command[0] || '';
+    const headParts = typeof first === 'string' && first.includes(' ') ? first.split(/\s+/) : [first];
+    const [cmd, ...headArgs] = headParts;
+    const rest = [...headArgs, ...runtime.command.slice(1)];
     const args = transport === 'argv'
       ? rest.map(arg => arg === '{prompt}' ? fullPrompt : arg)
       : rest.filter(arg => arg !== '{prompt}');

package/src/lib/connector-probe.js

@@ -38,7 +38,9 @@ function formatTarget(runtime) {
 
 function commandHead(runtime) {
   if (Array.isArray(runtime?.command)) {
-    return runtime.command[0] || null;
+    const first = runtime.command[0] || null;
+    if (first && first.includes(' ')) return first.split(/\s+/)[0];
+    return first;
   }
   if (typeof runtime?.command === 'string' && runtime.command.trim()) {
     return runtime.command.trim().split(/\s+/)[0];

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

@@ -15,6 +15,7 @@ import {
 import { loadProjectContext } from '../config.js';
 import { getContinuityStatus } from '../continuity-status.js';
 import { readRepoDecisions, summarizeRepoDecisions } from '../repo-decisions.js';
+import { readAllDispatchProgress } from '../dispatch-progress.js';
 
 const STATE_FILE = 'state.json';
 const SESSION_FILE = 'session.json';
@@ -80,6 +81,9 @@ export function normalizeRelativePath(filePath) {
 
 export function resourcesForRelativePath(filePath) {
   const normalized = normalizeRelativePath(filePath);
+  if (/^dispatch-progress-[^/]+\.json$/.test(normalized)) {
+    return ['/api/state'];
+  }
   if (normalized.startsWith('missions/plans/') && normalized.endsWith('.json')) {
     return ['/api/plans', '/api/missions'];
   }
@@ -136,6 +140,7 @@ function enrichGovernedState(agentxchainDir, state) {
     ...state,
     runtime_guidance: deriveRuntimeBlockedGuidance(state, context.config),
     next_actions: deriveGovernedRunNextActions(state, context.config),
+    dispatch_progress: readAllDispatchProgress(workspacePath),
   };
 }
 

package/src/lib/dispatch-progress.js

@@ -0,0 +1,298 @@
+/**
+ * dispatch-progress.js — Real-time adapter dispatch progress tracking.
+ *
+ * Writes `.agentxchain/dispatch-progress.json` during in-flight adapter
+ * dispatch so operators can distinguish "adapter is working" from "adapter
+ * is hung" via `agentxchain status` and the dashboard file-watcher.
+ *
+ * DEC-DISPATCH-PROGRESS-001: progress writes are best-effort and never
+ * block or delay the governed turn.
+ */
+
+import { writeFileSync, unlinkSync, readFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+
+export const LEGACY_DISPATCH_PROGRESS_PATH = '.agentxchain/dispatch-progress.json';
+export const DISPATCH_PROGRESS_FILE_PREFIX = '.agentxchain/dispatch-progress-';
+
+export function getDispatchProgressRelativePath(turnId) {
+  return `${DISPATCH_PROGRESS_FILE_PREFIX}${turnId}.json`;
+}
+
+function getDispatchProgressFilePath(root, turnId) {
+  return join(root, getDispatchProgressRelativePath(turnId));
+}
+
+function listDispatchProgressFiles(root) {
+  const agentxchainDir = join(root, '.agentxchain');
+  if (!existsSync(agentxchainDir)) return [];
+  try {
+    return readdirSync(agentxchainDir)
+      .filter((entry) => entry.startsWith('dispatch-progress-') && entry.endsWith('.json'))
+      .map((entry) => join(agentxchainDir, entry));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Create a dispatch progress tracker for a single turn.
+ *
+ * Usage:
+ *   const tracker = createDispatchProgressTracker(root, turn, runtime);
+ *   tracker.start();
+ *   // ... during dispatch:
+ *   tracker.onOutput('stdout', lineCount);
+ *   tracker.onOutput('stderr', lineCount);
+ *   // ... when done:
+ *   tracker.complete();  // or tracker.fail();
+ *
+ * @param {string} root - project root
+ * @param {object} turn - turn object with turn_id, runtime_id, assigned_role
+ * @param {object} options
+ * @param {string} options.adapter_type - 'local_cli' | 'api_proxy' | 'mcp' | 'remote_agent'
+ * @param {number} [options.pid] - subprocess PID (local_cli only)
+ * @param {number} [options.writeIntervalMs=1000] - min interval between file writes
+ * @param {number} [options.silenceThresholdMs=30000] - silence detection threshold
+ * @returns {DispatchProgressTracker}
+ */
+export function createDispatchProgressTracker(root, turn, options = {}) {
+  const {
+    adapter_type = 'local_cli',
+    pid = null,
+    writeIntervalMs = 1000,
+    silenceThresholdMs = 30000,
+  } = options;
+
+  const filePath = getDispatchProgressFilePath(root, turn.turn_id);
+
+  let state = {
+    turn_id: turn.turn_id,
+    runtime_id: turn.runtime_id || null,
+    adapter_type,
+    started_at: null,
+    last_activity_at: null,
+    activity_type: 'output',
+    activity_summary: 'Dispatch starting',
+    output_lines: 0,
+    stderr_lines: 0,
+    silent_since: null,
+    pid,
+  };
+
+  let lastWriteAt = 0;
+  let silenceTimer = null;
+  let dirty = false;
+
+  function writeProgress() {
+    try {
+      const dir = dirname(filePath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      writeFileSync(filePath, JSON.stringify(state, null, 2) + '\n');
+      lastWriteAt = Date.now();
+      dirty = false;
+    } catch {
+      // Best-effort — never interrupt dispatch.
+    }
+  }
+
+  function maybeWrite() {
+    if (!dirty) return;
+    const now = Date.now();
+    if (now - lastWriteAt >= writeIntervalMs) {
+      writeProgress();
+    }
+  }
+
+  function resetSilenceTimer() {
+    if (silenceTimer) clearTimeout(silenceTimer);
+    silenceTimer = setTimeout(() => {
+      state.activity_type = 'silent';
+      state.silent_since = state.silent_since || new Date().toISOString();
+      state.activity_summary = `No output for ${Math.round(silenceThresholdMs / 1000)}s`;
+      dirty = true;
+      writeProgress();
+    }, silenceThresholdMs);
+  }
+
+  return {
+    /** Start tracking — call once at dispatch start. */
+    start() {
+      const now = new Date().toISOString();
+      state.started_at = now;
+      state.last_activity_at = now;
+      state.activity_type = 'output';
+      state.activity_summary = 'Subprocess started';
+      dirty = true;
+      writeProgress();
+      if (adapter_type === 'local_cli') {
+        resetSilenceTimer();
+      }
+    },
+
+    /** Record output activity from the subprocess. */
+    onOutput(stream, lineCount = 1) {
+      const now = new Date().toISOString();
+      const wasSilent = state.activity_type === 'silent';
+      state.last_activity_at = now;
+      state.activity_type = 'output';
+      state.silent_since = null;
+      if (stream === 'stderr') {
+        state.stderr_lines += lineCount;
+      } else {
+        state.output_lines += lineCount;
+      }
+      state.activity_summary = `Producing output (${state.output_lines} lines)`;
+      dirty = true;
+      maybeWrite();
+      if (adapter_type === 'local_cli') {
+        resetSilenceTimer();
+      }
+      return wasSilent; // caller can use this to emit a "resumed" event
+    },
+
+    /** Mark as API request in flight (api_proxy, mcp, remote_agent). */
+    requestStarted() {
+      state.activity_type = 'request';
+      state.activity_summary = 'API request in flight';
+      state.last_activity_at = new Date().toISOString();
+      dirty = true;
+      writeProgress();
+    },
+
+    /** Mark API response received. */
+    responseReceived() {
+      state.activity_type = 'response';
+      state.activity_summary = 'API response received';
+      state.last_activity_at = new Date().toISOString();
+      dirty = true;
+      writeProgress();
+    },
+
+    /** Update PID after spawn (local_cli). */
+    setPid(newPid) {
+      state.pid = newPid;
+      dirty = true;
+      maybeWrite();
+    },
+
+    /** Get current progress state snapshot. */
+    getState() {
+      return { ...state };
+    },
+
+    /** Clean up — dispatch completed successfully. */
+    complete() {
+      if (silenceTimer) clearTimeout(silenceTimer);
+      deleteProgressFile(root, turn.turn_id);
+    },
+
+    /** Clean up — dispatch failed. */
+    fail() {
+      if (silenceTimer) clearTimeout(silenceTimer);
+      deleteProgressFile(root, turn.turn_id);
+    },
+
+    /** Clean up timers without deleting file (for abort paths). */
+    dispose() {
+      if (silenceTimer) clearTimeout(silenceTimer);
+    },
+  };
+}
+
+/**
+ * Delete the dispatch progress file.
+ * @param {string} root - project root
+ */
+export function deleteProgressFile(root, turnId = null) {
+  try {
+    if (turnId) {
+      const filePath = getDispatchProgressFilePath(root, turnId);
+      if (existsSync(filePath)) {
+        unlinkSync(filePath);
+      }
+      return;
+    }
+
+    const legacyPath = join(root, LEGACY_DISPATCH_PROGRESS_PATH);
+    if (existsSync(legacyPath)) {
+      unlinkSync(legacyPath);
+    }
+    for (const filePath of listDispatchProgressFiles(root)) {
+      if (existsSync(filePath)) {
+        unlinkSync(filePath);
+      }
+    }
+  } catch {
+    // Best-effort.
+  }
+}
+
+/**
+ * Read the current dispatch progress file.
+ * Returns null if no file exists or it's malformed.
+ *
+ * @param {string} root - project root
+ * @returns {object|null}
+ */
+export function readDispatchProgress(root, turnId = null) {
+  try {
+    let filePath;
+    if (turnId) {
+      filePath = getDispatchProgressFilePath(root, turnId);
+      if (!existsSync(filePath)) return null;
+    } else {
+      const files = listDispatchProgressFiles(root);
+      if (files.length === 0) {
+        const legacyPath = join(root, LEGACY_DISPATCH_PROGRESS_PATH);
+        if (!existsSync(legacyPath)) return null;
+        filePath = legacyPath;
+      } else if (files.length === 1) {
+        filePath = files[0];
+      } else {
+        return null;
+      }
+    }
+    const raw = readFileSync(filePath, 'utf8');
+    const data = JSON.parse(raw);
+    if (!data.turn_id || !data.started_at) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read all current per-turn dispatch progress files.
+ *
+ * @param {string} root - project root
+ * @returns {Record<string, object>}
+ */
+export function readAllDispatchProgress(root) {
+  const progressByTurn = {};
+
+  for (const filePath of listDispatchProgressFiles(root)) {
+    try {
+      const raw = readFileSync(filePath, 'utf8');
+      const data = JSON.parse(raw);
+      const turnId = typeof data?.turn_id === 'string' && data.turn_id.length > 0
+        ? data.turn_id
+        : basename(filePath).replace(/^dispatch-progress-/, '').replace(/\.json$/, '');
+      if (!turnId || !data?.started_at) continue;
+      progressByTurn[turnId] = data;
+    } catch {
+      // Ignore malformed files.
+    }
+  }
+
+  if (Object.keys(progressByTurn).length === 0) {
+    const legacy = readDispatchProgress(root);
+    if (legacy?.turn_id) {
+      progressByTurn[legacy.turn_id] = legacy;
+    }
+  }
+
+  return progressByTurn;
+}

package/src/lib/repo-observer.js

@@ -24,6 +24,7 @@ import { join } from 'path';
 
 const OPERATIONAL_PATH_PREFIXES = [
   '.agentxchain/dispatch/',
+  '.agentxchain/dispatch-progress-',
   '.agentxchain/staging/',
   '.agentxchain/intake/',
   '.agentxchain/locks/',

package/src/lib/run-events.js

@@ -28,6 +28,7 @@ export const VALID_RUN_EVENTS = [
   'budget_exceeded_warn',
   'human_escalation_raised',
   'human_escalation_resolved',
+  'dispatch_progress',
 ];
 
 /**