agentxchain 2.24.2 → 2.25.0

package/dashboard/app.js

@@ -12,6 +12,7 @@ import { render as renderBlocked } from './components/blocked.js';
 import { render as renderGate } from './components/gate.js';
 import { render as renderInitiative } from './components/initiative.js';
 import { render as renderCrossRepo } from './components/cross-repo.js';
+import { render as renderBlockers } from './components/blockers.js';
 
 const VIEWS = {
   timeline: { fetch: ['state', 'history', 'audit', 'annotations'], render: renderTimeline },
@@ -19,8 +20,9 @@ const VIEWS = {
   hooks: { fetch: ['audit', 'annotations'], render: renderHooks },
   blocked: { fetch: ['state', 'audit', 'coordinatorState', 'coordinatorAudit'], render: renderBlocked },
   gate: { fetch: ['state', 'history', 'coordinatorState', 'coordinatorHistory', 'coordinatorBarriers'], render: renderGate },
-  initiative: { fetch: ['coordinatorState', 'coordinatorBarriers', 'barrierLedger'], render: renderInitiative },
+  initiative: { fetch: ['coordinatorState', 'coordinatorBarriers', 'barrierLedger', 'coordinatorBlockers'], render: renderInitiative },
   'cross-repo': { fetch: ['coordinatorState', 'coordinatorHistory'], render: renderCrossRepo },
+  blockers: { fetch: ['coordinatorBlockers'], render: renderBlockers },
 };
 
 const API_MAP = {
@@ -34,6 +36,7 @@ const API_MAP = {
   coordinatorBarriers: '/api/coordinator/barriers',
   barrierLedger: '/api/coordinator/barrier-ledger',
   coordinatorAudit: '/api/coordinator/hooks/audit',
+  coordinatorBlockers: '/api/coordinator/blockers',
 };
 
 const viewState = {

package/dashboard/components/blockers.js

@@ -0,0 +1,268 @@
+/**
+ * Coordinator Blockers view — renders computed coordinator gate blockers.
+ *
+ * Pure render function: takes data from /api/coordinator/blockers, returns HTML.
+ * All blocker semantics are server-side (coordinator-blockers.js). This view
+ * renders the snapshot without reimplementing gate logic.
+ *
+ * Per DEC-DASH-COORD-BLOCKERS-002: blocker evaluation must come from the same
+ * server-side gate evaluators used by `multi step` and `multi approve-gate`.
+ */
+
+function esc(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function badge(label, color = 'var(--text-dim)') {
+  return `<span class="badge" style="color:${color};border-color:${color}">${esc(label)}</span>`;
+}
+
+function modeColor(mode) {
+  const colors = {
+    pending_gate: 'var(--yellow)',
+    phase_transition: 'var(--accent)',
+    run_completion: 'var(--green)',
+  };
+  return colors[mode] || 'var(--text-dim)';
+}
+
+function blockerColor(code) {
+  if (code === 'repo_run_id_mismatch') return 'var(--red)';
+  if (code === 'no_next_phase') return 'var(--text-dim)';
+  return 'var(--yellow)';
+}
+
+function renderBlockerRow(blocker) {
+  const code = blocker.code || 'unknown';
+  const color = blockerColor(code);
+  let html = `<div class="turn-card" style="border-left: 3px solid ${color}">
+    <div class="turn-header">
+      ${badge(code, color)}
+    </div>`;
+
+  if (blocker.message) {
+    html += `<div class="turn-summary">${esc(blocker.message)}</div>`;
+  }
+
+  if (code === 'repo_run_id_mismatch' && blocker.repo_id) {
+    html += `<dl class="detail-list">
+      <dt>Repo</dt><dd class="mono">${esc(blocker.repo_id)}</dd>`;
+    if (blocker.expected_run_id) {
+      html += `<dt>Expected</dt><dd class="mono">${esc(blocker.expected_run_id)}</dd>`;
+    }
+    if (blocker.actual_run_id) {
+      html += `<dt>Actual</dt><dd class="mono">${esc(blocker.actual_run_id)}</dd>`;
+    }
+    html += `</dl>`;
+  }
+
+  if (code === 'repo_not_ready' && blocker.repo_id) {
+    html += `<dl class="detail-list">
+      <dt>Repo</dt><dd class="mono">${esc(blocker.repo_id)}</dd>`;
+    if (blocker.current_phase) {
+      html += `<dt>Current Phase</dt><dd>${esc(blocker.current_phase)}</dd>`;
+    }
+    if (blocker.required_phase) {
+      html += `<dt>Required Phase</dt><dd>${esc(blocker.required_phase)}</dd>`;
+    }
+    html += `</dl>`;
+  }
+
+  html += `</div>`;
+  return html;
+}
+
+function renderActiveGate(active) {
+  if (!active) return '';
+
+  let html = `<div class="gate-card">
+    <h3>Active Gate</h3>
+    <dl class="detail-list">
+      <dt>Type</dt><dd>${esc(active.gate_type)}</dd>`;
+
+  if (active.gate_id) {
+    html += `<dt>Gate</dt><dd class="mono">${esc(active.gate_id)}</dd>`;
+  }
+  if (active.current_phase) {
+    html += `<dt>Current Phase</dt><dd>${esc(active.current_phase)}</dd>`;
+  }
+  if (active.target_phase) {
+    html += `<dt>Target Phase</dt><dd>${esc(active.target_phase)}</dd>`;
+  }
+  if (typeof active.ready === 'boolean') {
+    html += `<dt>Ready</dt><dd>${active.ready ? 'Yes' : 'No'}</dd>`;
+  }
+  if (active.pending === true) {
+    html += `<dt>Pending Approval</dt><dd>Yes</dd>`;
+  }
+  if (Array.isArray(active.required_repos) && active.required_repos.length > 0) {
+    html += `<dt>Required Repos</dt><dd>${esc(active.required_repos.join(', '))}</dd>`;
+  }
+  if (Array.isArray(active.human_barriers) && active.human_barriers.length > 0) {
+    html += `<dt>Human Barriers</dt><dd>${esc(active.human_barriers.join(', '))}</dd>`;
+  }
+
+  html += `</dl>`;
+
+  if (Array.isArray(active.blockers) && active.blockers.length > 0) {
+    html += `<div class="section" style="margin-top:12px"><h3>Blockers (${active.blockers.length})</h3>
+      <div class="turn-list">`;
+    for (const blocker of active.blockers) {
+      html += renderBlockerRow(blocker);
+    }
+    html += `</div></div>`;
+  }
+
+  html += `</div>`;
+  return html;
+}
+
+function renderRecoveryCommand(data) {
+  if (data.mode === 'pending_gate') {
+    return `<div class="section"><h3>Recovery</h3>
+      <p class="recovery-hint">Approve the pending gate:</p>
+      <pre class="recovery-command mono" data-copy="agentxchain multi approve-gate">agentxchain multi approve-gate</pre>
+    </div>`;
+  }
+
+  const hasRunIdMismatch = Array.isArray(data.active?.blockers)
+    && data.active.blockers.some(b => b.code === 'repo_run_id_mismatch');
+
+  if (hasRunIdMismatch) {
+    return `<div class="section"><h3>Recovery</h3>
+      <p class="recovery-hint">Run identity drift detected. Investigate child repos before resuming:</p>
+      <pre class="recovery-command mono" data-copy="agentxchain multi resume">agentxchain multi resume</pre>
+    </div>`;
+  }
+
+  return '';
+}
+
+export function render({ coordinatorBlockers }) {
+  if (!coordinatorBlockers) {
+    return `<div class="placeholder"><h2>Coordinator Blockers</h2><p>No coordinator blocker data available. Ensure a coordinator run is active.</p></div>`;
+  }
+
+  if (coordinatorBlockers.ok === false) {
+    return `<div class="placeholder"><h2>Coordinator Blockers</h2><p>${esc(coordinatorBlockers.error || 'Failed to load coordinator blockers.')}</p></div>`;
+  }
+
+  const data = coordinatorBlockers;
+  const blockers = data.active?.blockers || [];
+  const hasBlockers = blockers.length > 0 && !blockers.every(b => b.code === 'no_next_phase');
+
+  let html = `<div class="blockers-view">`;
+
+  // Header
+  html += `<div class="run-header">
+    <div class="run-meta">`;
+  if (data.super_run_id) {
+    html += `<span class="mono run-id">${esc(data.super_run_id)}</span>`;
+  }
+  if (data.status) {
+    const statusColors = { active: 'var(--green)', blocked: 'var(--red)', completed: 'var(--accent)', paused: 'var(--yellow)' };
+    html += badge(data.status, statusColors[data.status] || 'var(--text-dim)');
+  }
+  html += `${badge(data.mode, modeColor(data.mode))}`;
+  if (data.phase) {
+    html += `<span class="phase-label">Phase: <strong>${esc(data.phase)}</strong></span>`;
+  }
+  html += `</div></div>`;
+
+  // Blocked reason
+  if (data.blocked_reason) {
+    html += `<div class="blocked-banner">
+      <div class="blocked-icon">BLOCKED</div>
+      <div class="blocked-reason">${esc(
+        typeof data.blocked_reason === 'string'
+          ? data.blocked_reason
+          : JSON.stringify(data.blocked_reason)
+      )}</div>
+    </div>`;
+  }
+
+  // Status summary
+  if (!hasBlockers && data.mode === 'pending_gate') {
+    html += `<div class="gate-card"><h3>Awaiting Approval</h3>
+      <p class="turn-summary">All prerequisites are satisfied. The coordinator is waiting for human gate approval.</p></div>`;
+  } else if (!hasBlockers) {
+    html += `<div class="gate-card"><h3>No Blockers</h3>
+      <p class="turn-summary">The coordinator gate has no outstanding blockers.</p></div>`;
+  }
+
+  // Active gate detail
+  html += renderActiveGate(data.active);
+
+  // Recovery
+  html += renderRecoveryCommand(data);
+
+  // Evaluations summary (collapsed detail for deeper inspection)
+  if (data.evaluations) {
+    html += `<div class="section"><h3>Gate Evaluations</h3>`;
+    const { phase_transition, run_completion } = data.evaluations;
+
+    if (phase_transition) {
+      html += `<div class="turn-card" data-turn-expand>
+        <div class="turn-header">
+          <span>Phase Transition</span>
+          ${badge(phase_transition.ready ? 'ready' : 'not ready', phase_transition.ready ? 'var(--green)' : 'var(--yellow)')}
+        </div>
+        <div class="turn-detail-panel">
+          <dl class="detail-list">`;
+      if (phase_transition.current_phase) html += `<dt>Current</dt><dd>${esc(phase_transition.current_phase)}</dd>`;
+      if (phase_transition.target_phase) html += `<dt>Target</dt><dd>${esc(phase_transition.target_phase)}</dd>`;
+      if (phase_transition.gate_id) html += `<dt>Gate</dt><dd class="mono">${esc(phase_transition.gate_id)}</dd>`;
+      html += `<dt>Blockers</dt><dd>${phase_transition.blockers?.length || 0}</dd>`;
+      html += `</dl>`;
+      if (phase_transition.blockers?.length > 0) {
+        html += `<div class="annotation-list" style="margin-top:8px">`;
+        for (const b of phase_transition.blockers) {
+          html += `<div class="annotation-card">
+            <span class="mono">${esc(b.code || 'unknown')}</span>
+            <span>${esc(b.message || '')}</span>
+          </div>`;
+        }
+        html += `</div>`;
+      }
+      html += `</div></div>`;
+    }
+
+    if (run_completion) {
+      html += `<div class="turn-card" data-turn-expand>
+        <div class="turn-header">
+          <span>Run Completion</span>
+          ${badge(run_completion.ready ? 'ready' : 'not ready', run_completion.ready ? 'var(--green)' : 'var(--yellow)')}
+        </div>
+        <div class="turn-detail-panel">
+          <dl class="detail-list">`;
+      if (run_completion.gate_id) html += `<dt>Gate</dt><dd class="mono">${esc(run_completion.gate_id)}</dd>`;
+      html += `<dt>Blockers</dt><dd>${run_completion.blockers?.length || 0}</dd>`;
+      if (typeof run_completion.requires_human_approval === 'boolean') {
+        html += `<dt>Human Approval</dt><dd>${run_completion.requires_human_approval ? 'Required' : 'Not required'}</dd>`;
+      }
+      html += `</dl>`;
+      if (run_completion.blockers?.length > 0) {
+        html += `<div class="annotation-list" style="margin-top:8px">`;
+        for (const b of run_completion.blockers) {
+          html += `<div class="annotation-card">
+            <span class="mono">${esc(b.code || 'unknown')}</span>
+            <span>${esc(b.message || '')}</span>
+          </div>`;
+        }
+        html += `</div>`;
+      }
+      html += `</div></div>`;
+    }
+
+    html += `</div>`;
+  }
+
+  html += `</div>`;
+  return html;
+}

package/dashboard/components/initiative.js

@@ -37,7 +37,86 @@ function summarizeBarriers(barriers) {
   return counts;
 }
 
-export function render({ coordinatorState, coordinatorBarriers = {}, barrierLedger = [] }) {
+function renderCoordinatorAttentionSnapshot(coordinatorBlockers) {
+  if (!coordinatorBlockers || coordinatorBlockers.ok === false) {
+    return '';
+  }
+
+  const active = coordinatorBlockers.active || {};
+  const blockers = Array.isArray(active.blockers)
+    ? active.blockers.filter((blocker) => blocker?.code !== 'no_next_phase')
+    : [];
+  const hasBlockers = blockers.length > 0;
+  const title = coordinatorBlockers.mode === 'pending_gate' ? 'Approval Snapshot' : 'Blocker Snapshot';
+
+  let html = `<div class="gate-card">
+    <h3>${title}</h3>
+    <dl class="detail-list">`;
+  if (coordinatorBlockers.mode) {
+    html += `<dt>Mode</dt><dd>${esc(coordinatorBlockers.mode)}</dd>`;
+  }
+  if (active.gate_type) {
+    html += `<dt>Type</dt><dd>${esc(active.gate_type)}</dd>`;
+  }
+  if (active.gate_id) {
+    html += `<dt>Gate</dt><dd class="mono">${esc(active.gate_id)}</dd>`;
+  }
+  if (active.current_phase) {
+    html += `<dt>Current</dt><dd>${esc(active.current_phase)}</dd>`;
+  }
+  if (active.target_phase) {
+    html += `<dt>Target</dt><dd>${esc(active.target_phase)}</dd>`;
+  }
+  if (hasBlockers) {
+    html += `<dt>Blockers</dt><dd>${blockers.length}</dd>`;
+  }
+  html += `</dl>`;
+
+  if (coordinatorBlockers.mode === 'pending_gate') {
+    html += `<p class="turn-summary">All coordinator prerequisites are satisfied. Human approval is the remaining action.</p>`;
+  } else if (hasBlockers) {
+    html += `<div class="turn-list">`;
+    for (const blocker of blockers) {
+      html += `<div class="turn-card">
+        <div class="turn-header"><span class="mono">${esc(blocker.code || 'unknown')}</span></div>`;
+      if (blocker.message) {
+        html += `<div class="turn-summary">${esc(blocker.message)}</div>`;
+      }
+      if (blocker.repo_id || blocker.expected_run_id || blocker.actual_run_id) {
+        html += `<dl class="detail-list">`;
+        if (blocker.repo_id) html += `<dt>Repo</dt><dd class="mono">${esc(blocker.repo_id)}</dd>`;
+        if (blocker.expected_run_id) html += `<dt>Expected</dt><dd class="mono">${esc(blocker.expected_run_id)}</dd>`;
+        if (blocker.actual_run_id) html += `<dt>Actual</dt><dd class="mono">${esc(blocker.actual_run_id)}</dd>`;
+        if (blocker.current_phase) html += `<dt>Current Phase</dt><dd>${esc(blocker.current_phase)}</dd>`;
+        if (blocker.required_phase) html += `<dt>Required Phase</dt><dd>${esc(blocker.required_phase)}</dd>`;
+        html += `</dl>`;
+      }
+      html += `</div>`;
+    }
+    html += `</div>`;
+  } else if (coordinatorBlockers.blocked_reason) {
+    html += `<p class="turn-summary">${esc(
+      typeof coordinatorBlockers.blocked_reason === 'string'
+        ? coordinatorBlockers.blocked_reason
+        : JSON.stringify(coordinatorBlockers.blocked_reason)
+    )}</p>`;
+  }
+
+  html += `<div class="gate-action">
+    <p>Inspect full diagnostics:</p>
+    <p><a href="#blockers">Open Blockers view</a></p>
+  </div>
+</div>`;
+
+  return html;
+}
+
+export function render({
+  coordinatorState,
+  coordinatorBarriers = {},
+  barrierLedger = [],
+  coordinatorBlockers = null,
+}) {
   if (!coordinatorState) {
     return `<div class="placeholder"><h2>No Initiative</h2><p>No coordinator run found. Start one with <code class="mono">agentxchain multi init</code></p></div>`;
   }
@@ -80,7 +159,10 @@ export function render({ coordinatorState, coordinatorBarriers = {}, barrierLedg
         </div>
       </div>`;
     }
-    if (coordinatorState.blocked_reason) {
+    const blockerSnapshot = renderCoordinatorAttentionSnapshot(coordinatorBlockers);
+    if (blockerSnapshot) {
+      html += blockerSnapshot;
+    } else if (coordinatorState.blocked_reason) {
       html += `<div class="gate-card">
         <h3>Blocked State</h3>
         <p class="turn-summary">${esc(

package/dashboard/index.html

@@ -381,6 +381,7 @@
     <a href="#hooks">Hooks</a>
     <a href="#blocked">Blocked</a>
     <a href="#gate">Gates</a>
+    <a href="#blockers">Blockers</a>
   </nav>
   <main id="view-container">
     <div class="placeholder">

package/package.json

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

package/src/commands/init.js

@@ -681,6 +681,7 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.dim('└──')} TALK.md`);
   console.log('');
   console.log(`  ${chalk.dim('Roles:')} pm, dev, qa, eng_director`);
+  console.log(`  ${chalk.dim('Phases:')} planning → implementation → qa ${chalk.dim('(default; extend via routing in agentxchain.json)')}`);
   console.log(`  ${chalk.dim('Template:')} ${templateId}`);
   console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);

package/src/commands/multi.js

@@ -257,7 +257,12 @@ export async function multiStepCommand(options) {
     if (gate.blockers.length > 0) {
       console.error(`Coordinator ${gate.type === 'phase_transition' ? 'phase' : 'completion'} gate is not ready:`);
       for (const blocker of gate.blockers) {
-        console.error(`  - ${blocker.message}`);
+        const codeTag = blocker.code ? `[${blocker.code}] ` : '';
+        console.error(`  - ${codeTag}${blocker.message}`);
+        if (blocker.code === 'repo_run_id_mismatch') {
+          console.error(`    expected: ${blocker.expected_run_id}`);
+          console.error(`    actual:   ${blocker.actual_run_id}`);
+        }
       }
     }
     process.exitCode = 1;

package/src/lib/coordinator-config.js

@@ -6,7 +6,8 @@ import { safeParseJson } from './schema.js';
 export const COORDINATOR_CONFIG_FILE = 'agentxchain-multi.json';
 
 const VALID_ID = /^[a-z0-9_-]+$/;
-const VALID_PHASES = new Set(['planning', 'implementation', 'qa']);
+const DEFAULT_PHASES = new Set(['planning', 'implementation', 'qa']);
+const VALID_PHASE_NAME = /^[a-z][a-z0-9_-]*$/;
 const VALID_BARRIER_TYPES = new Set([
   'all_repos_accepted',
   'interface_alignment',
@@ -88,11 +89,14 @@ function validateWorkstreams(raw, repoIds, errors) {
       continue;
     }
 
-    if (!VALID_PHASES.has(workstream.phase)) {
+    // Derive valid phases from routing keys when present; fall back to defaults
+    const validPhases = raw.routing ? new Set(Object.keys(raw.routing)) : DEFAULT_PHASES;
+    if (!validPhases.has(workstream.phase)) {
+      const phaseList = [...validPhases].join(', ');
       pushError(
         errors,
         'workstream_phase_invalid',
-        `workstream "${workstreamId}" phase must be one of: planning, implementation, qa`,
+        `workstream "${workstreamId}" phase must be one of: ${phaseList}`,
       );
     }
 
@@ -279,8 +283,8 @@ function validateRouting(raw, workstreamIds, errors) {
 
   const workstreamIdSet = new Set(workstreamIds);
   for (const [phase, route] of Object.entries(raw.routing)) {
-    if (!VALID_PHASES.has(phase)) {
-      pushError(errors, 'routing_phase_invalid', `routing phase "${phase}" must be one of: planning, implementation, qa`);
+    if (!VALID_PHASE_NAME.test(phase)) {
+      pushError(errors, 'routing_phase_invalid', `routing phase "${phase}" must be lowercase alphanumeric starting with a letter (hyphens and underscores allowed)`);
     }
 
     if (!route || typeof route !== 'object' || Array.isArray(route)) {

package/src/lib/coordinator-gates.js

@@ -21,6 +21,26 @@ function loadRepoState(repoPath) {
   }
 }
 
+function buildRunIdMismatchBlocker(state, repoId, repoState) {
+  const expectedRunId = state?.repo_runs?.[repoId]?.run_id ?? null;
+  if (!expectedRunId) {
+    return null;
+  }
+
+  const actualRunId = repoState?.run_id ?? null;
+  if (actualRunId === expectedRunId) {
+    return null;
+  }
+
+  return {
+    code: 'repo_run_id_mismatch',
+    repo_id: repoId,
+    expected_run_id: expectedRunId,
+    actual_run_id: actualRunId,
+    message: `Repo "${repoId}" run identity drifted: coordinator expects "${expectedRunId}" but repo has "${actualRunId ?? 'null'}"`,
+  };
+}
+
 function getActiveTurnCount(repoState) {
   if (!repoState?.active_turns || typeof repoState.active_turns !== 'object' || Array.isArray(repoState.active_turns)) {
     return 0;
@@ -68,7 +88,7 @@ function getRequiredReposForPhase(state, config) {
   return [...required];
 }
 
-function buildRepoBlockers(config, repoIds) {
+function buildRepoBlockers(state, config, repoIds) {
   const blockers = [];
 
   for (const repoId of repoIds) {
@@ -84,6 +104,12 @@ function buildRepoBlockers(config, repoIds) {
       continue;
     }
 
+    const runIdMismatch = buildRunIdMismatchBlocker(state, repoId, repoState);
+    if (runIdMismatch) {
+      blockers.push(runIdMismatch);
+      continue;
+    }
+
     if (repoState.status === 'blocked') {
       blockers.push({
         code: 'repo_blocked',
@@ -234,7 +260,7 @@ export function evaluatePhaseGate(workspacePath, state, config, targetPhase) {
   }
 
   const repoIds = getRequiredReposForPhase(state, config);
-  blockers.push(...buildRepoBlockers(config, repoIds));
+  blockers.push(...buildRepoBlockers(state, config, repoIds));
 
   const barriers = readBarriers(workspacePath);
   const barrierState = buildPhaseBarrierState(state, config, barriers);
@@ -391,6 +417,12 @@ export function evaluateCompletionGate(workspacePath, state, config) {
       continue;
     }
 
+    const runIdMismatch = buildRunIdMismatchBlocker(state, repoId, repoState);
+    if (runIdMismatch) {
+      blockers.push(runIdMismatch);
+      continue;
+    }
+
     if (repoState.status === 'blocked') {
       blockers.push({
         code: 'repo_blocked',

package/src/lib/coordinator-recovery.js

@@ -83,6 +83,10 @@ function isAcceptedRepoHistoryEntry(entry) {
   return Boolean(entry.accepted_at) || entry.status === 'accepted';
 }
 
+function buildRunIdMismatchReason(repoId, expectedRunId, actualRunId) {
+  return `Repo "${repoId}" run identity drifted: coordinator expects "${expectedRunId}" but repo has "${actualRunId ?? 'null'}"`;
+}
+
 // ── Divergence Detection ────────────────────────────────────────────────────
 
 /**
@@ -124,13 +128,13 @@ export function detectDivergence(workspacePath, state, config) {
     }
 
     // Run ID mismatch
-    if (repoRun.run_id && repoState.run_id && repoRun.run_id !== repoState.run_id) {
+    if (repoRun.run_id && repoRun.run_id !== (repoState.run_id ?? null)) {
       mismatches.push({
         type: 'run_id_mismatch',
         repo_id: repoId,
         coordinator_run_id: repoRun.run_id,
-        repo_run_id: repoState.run_id,
-        detail: `Coordinator expects run "${repoRun.run_id}" but repo has "${repoState.run_id}"`,
+        repo_run_id: repoState.run_id ?? null,
+        detail: buildRunIdMismatchReason(repoId, repoRun.run_id, repoState.run_id ?? null),
       });
     }
 
@@ -238,6 +242,7 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
 
   // Step 1: Refresh repo_runs from repo-local authority
   const updatedRepoRuns = { ...state.repo_runs };
+  const runIdMismatches = [];
 
   for (const [repoId, repoRun] of Object.entries(state.repo_runs || {})) {
     const repo = config.repos?.[repoId];
@@ -254,9 +259,11 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
 
     const changes = {};
 
-    // Update run_id if it changed (e.g., repo was re-initialized outside coordinator)
-    if (repoState.run_id && repoState.run_id !== repoRun.run_id) {
-      changes.run_id = repoState.run_id;
+    if (repoRun.run_id && repoRun.run_id !== (repoState.run_id ?? null)) {
+      const reason = buildRunIdMismatchReason(repoId, repoRun.run_id, repoState.run_id ?? null);
+      runIdMismatches.push(reason);
+      errors.push(reason);
+      continue;
     }
 
     // Update status from repo-local authority
@@ -395,7 +402,11 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
   let blockedReason = null;
   const pendingGate = state.pending_gate;
 
-  if (pendingGate) {
+  if (runIdMismatches.length > 0) {
+    blockedReason = runIdMismatches.join('; ');
+  }
+
+  if (!blockedReason && pendingGate) {
     const gateCoherent = validatePendingGateCoherence(pendingGate, updatedRepoRuns, config);
     if (!gateCoherent.ok) {
       blockedReason = gateCoherent.reason;

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

@@ -17,6 +17,7 @@ import { join, extname, resolve, sep } from 'path';
 import { readResource } from './state-reader.js';
 import { FileWatcher } from './file-watcher.js';
 import { approvePendingDashboardGate } from './actions.js';
+import { readCoordinatorBlockerSnapshot } from './coordinator-blockers.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -208,6 +209,7 @@ function resolveDashboardAssetPath(dashboardDir, pathname) {
 // ── Bridge Server ───────────────────────────────────────────────────────────
 
 export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }) {
+  const workspacePath = resolve(agentxchainDir, '..');
   const wsClients = new Set();
   const watcher = new FileWatcher(agentxchainDir);
   const mutationToken = randomBytes(24).toString('hex');
@@ -271,6 +273,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       return;
     }
 
+    if (pathname === '/api/coordinator/blockers') {
+      const result = readCoordinatorBlockerSnapshot(workspacePath);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     // API routes
     if (pathname.startsWith('/api/')) {
       const result = readResource(agentxchainDir, pathname);

package/src/lib/dashboard/coordinator-blockers.js

@@ -0,0 +1,168 @@
+import { evaluateCompletionGate, evaluatePhaseGate } from '../coordinator-gates.js';
+import { loadCoordinatorConfig } from '../coordinator-config.js';
+import { loadCoordinatorState } from '../coordinator-state.js';
+
+function normalizePendingGate(pendingGate) {
+  if (!pendingGate || typeof pendingGate !== 'object' || Array.isArray(pendingGate)) {
+    return null;
+  }
+
+  if (typeof pendingGate.gate !== 'string' || pendingGate.gate.length === 0) {
+    return null;
+  }
+
+  if (typeof pendingGate.gate_type !== 'string' || pendingGate.gate_type.length === 0) {
+    return null;
+  }
+
+  const normalized = {
+    gate: pendingGate.gate,
+    gate_type: pendingGate.gate_type,
+  };
+
+  if (typeof pendingGate.from === 'string' && pendingGate.from.length > 0) {
+    normalized.from = pendingGate.from;
+  }
+
+  if (typeof pendingGate.to === 'string' && pendingGate.to.length > 0) {
+    normalized.to = pendingGate.to;
+  }
+
+  if (Array.isArray(pendingGate.required_repos)) {
+    normalized.required_repos = pendingGate.required_repos;
+  }
+
+  if (Array.isArray(pendingGate.human_barriers)) {
+    normalized.human_barriers = pendingGate.human_barriers;
+  }
+
+  if (typeof pendingGate.requested_at === 'string' && pendingGate.requested_at.length > 0) {
+    normalized.requested_at = pendingGate.requested_at;
+  }
+
+  return normalized;
+}
+
+function normalizePhaseEvaluation(evaluation) {
+  return {
+    ready: Boolean(evaluation?.ready),
+    gate_id: evaluation?.gate_id ?? null,
+    current_phase: evaluation?.current_phase ?? null,
+    target_phase: evaluation?.target_phase ?? null,
+    required_repos: Array.isArray(evaluation?.required_repos) ? evaluation.required_repos : [],
+    workstreams: Array.isArray(evaluation?.workstreams) ? evaluation.workstreams : [],
+    human_barriers: Array.isArray(evaluation?.human_barriers) ? evaluation.human_barriers : [],
+    blockers: Array.isArray(evaluation?.blockers) ? evaluation.blockers : [],
+  };
+}
+
+function normalizeCompletionEvaluation(evaluation) {
+  return {
+    ready: Boolean(evaluation?.ready),
+    gate_id: evaluation?.gate_id ?? null,
+    required_repos: Array.isArray(evaluation?.required_repos) ? evaluation.required_repos : [],
+    human_barriers: Array.isArray(evaluation?.human_barriers) ? evaluation.human_barriers : [],
+    requires_human_approval: evaluation?.requires_human_approval !== false,
+    blockers: Array.isArray(evaluation?.blockers) ? evaluation.blockers : [],
+  };
+}
+
+function buildPendingGateSnapshot(pendingGate) {
+  return {
+    gate_type: pendingGate.gate_type,
+    gate_id: pendingGate.gate,
+    ready: true,
+    current_phase: pendingGate.from ?? null,
+    target_phase: pendingGate.to ?? null,
+    required_repos: Array.isArray(pendingGate.required_repos) ? pendingGate.required_repos : [],
+    human_barriers: Array.isArray(pendingGate.human_barriers) ? pendingGate.human_barriers : [],
+    blockers: [],
+    pending: true,
+  };
+}
+
+function phaseIsFinal(phaseEvaluation) {
+  return phaseEvaluation.blockers.length === 1
+    && phaseEvaluation.blockers[0]?.code === 'no_next_phase';
+}
+
+function getConfigErrorResponse(errors) {
+  const issueList = Array.isArray(errors) ? errors : [];
+  const missing = issueList.some((error) => typeof error === 'string' && error.startsWith('config_missing:'));
+
+  return {
+    ok: false,
+    status: missing ? 404 : 422,
+    body: {
+      ok: false,
+      code: missing ? 'coordinator_config_missing' : 'coordinator_config_invalid',
+      error: missing
+        ? 'Coordinator config not found. Run `agentxchain multi init` first.'
+        : 'Coordinator config is invalid.',
+      errors: issueList,
+    },
+  };
+}
+
+export function readCoordinatorBlockerSnapshot(workspacePath) {
+  const configResult = loadCoordinatorConfig(workspacePath);
+  if (!configResult.ok) {
+    return getConfigErrorResponse(configResult.errors);
+  }
+
+  const state = loadCoordinatorState(workspacePath);
+  if (!state) {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'coordinator_state_missing',
+        error: 'Coordinator state not found. Run `agentxchain multi init` first.',
+      },
+    };
+  }
+
+  const phaseEvaluation = normalizePhaseEvaluation(
+    evaluatePhaseGate(workspacePath, state, configResult.config),
+  );
+  const completionEvaluation = normalizeCompletionEvaluation(
+    evaluateCompletionGate(workspacePath, state, configResult.config),
+  );
+  const pendingGate = normalizePendingGate(state.pending_gate);
+
+  let mode = 'phase_transition';
+  let active = {
+    gate_type: 'phase_transition',
+    ...phaseEvaluation,
+  };
+
+  if (pendingGate) {
+    mode = 'pending_gate';
+    active = buildPendingGateSnapshot(pendingGate);
+  } else if (phaseIsFinal(phaseEvaluation)) {
+    mode = 'run_completion';
+    active = {
+      gate_type: 'run_completion',
+      ...completionEvaluation,
+    };
+  }
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      mode,
+      super_run_id: state.super_run_id ?? null,
+      status: state.status ?? null,
+      phase: state.phase ?? null,
+      blocked_reason: state.blocked_reason ?? null,
+      pending_gate: pendingGate,
+      active,
+      evaluations: {
+        phase_transition: phaseEvaluation,
+        run_completion: completionEvaluation,
+      },
+    },
+  };
+}

package/src/lib/gate-evaluator.js

@@ -73,6 +73,15 @@ export function evaluatePhaseExit({ state, config, acceptedTurn, root }) {
     };
   }
 
+  const invalidOrderReason = getInvalidPhaseTransitionReason(currentPhase, transitionRequest, routing);
+  if (invalidOrderReason) {
+    return {
+      ...baseResult,
+      action: 'gate_failed',
+      reasons: [invalidOrderReason],
+    };
+  }
+
   // Find the exit gate for the current phase
   const currentRouting = routing[currentPhase];
   if (!currentRouting || !currentRouting.exit_gate) {
@@ -285,6 +294,43 @@ export function getPhaseOrder(routing) {
   return Object.keys(routing || {});
 }
 
+/**
+ * Return the next declared phase after the current phase, or null when the
+ * current phase is final or not part of the routing config.
+ *
+ * @param {string} currentPhase
+ * @param {object} routing
+ * @returns {string|null}
+ */
+export function getNextPhase(currentPhase, routing) {
+  const phases = getPhaseOrder(routing || {});
+  const currentIndex = phases.indexOf(currentPhase);
+  if (currentIndex === -1 || currentIndex >= phases.length - 1) {
+    return null;
+  }
+  return phases[currentIndex + 1];
+}
+
+/**
+ * Validate that a requested phase transition follows the declared routing
+ * order. Returns null when the request is valid.
+ *
+ * @param {string} currentPhase
+ * @param {string} requestedPhase
+ * @param {object} routing
+ * @returns {string|null}
+ */
+export function getInvalidPhaseTransitionReason(currentPhase, requestedPhase, routing) {
+  const nextPhase = getNextPhase(currentPhase, routing);
+  if (!nextPhase) {
+    return `phase_transition_request "${requestedPhase}" is invalid in final phase "${currentPhase}"; use run_completion_request instead.`;
+  }
+  if (requestedPhase !== nextPhase) {
+    return `phase_transition_request "${requestedPhase}" is invalid from phase "${currentPhase}"; next phase is "${nextPhase}".`;
+  }
+  return null;
+}
+
 /**
  * Check if a phase is the final phase in the routing config.
  *

package/src/lib/normalized-config.js

@@ -21,7 +21,8 @@ const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp'];
 const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai'];
 export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
-const VALID_PHASES = ['planning', 'implementation', 'qa'];
+const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];
+const VALID_PHASE_NAME = /^[a-z][a-z0-9_-]*$/;
 const VALID_API_PROXY_RETRY_JITTER = ['none', 'full'];
 const VALID_API_PROXY_RETRY_CLASSES = [
   'rate_limited',
@@ -400,10 +401,11 @@ export function validateV4Config(data, projectRoot) {
   }
 
   // Routing (optional but validated if present)
+  // Phase names are derived from routing keys when present; fall back to defaults
   if (data.routing) {
     for (const [phase, route] of Object.entries(data.routing)) {
-      if (!VALID_PHASES.includes(phase)) {
-        errors.push(`Routing references unknown phase: "${phase}"`);
+      if (!VALID_PHASE_NAME.test(phase)) {
+        errors.push(`Routing phase name "${phase}" must be lowercase alphanumeric starting with a letter (hyphens and underscores allowed)`);
       }
       if (route.entry_role && data.roles && !data.roles[route.entry_role]) {
         errors.push(`Routing "${phase}": entry_role "${route.entry_role}" is not a defined role`);

package/src/lib/report.js

@@ -299,6 +299,23 @@ function normalizeCoordinatorBlockedReason(blockedReason) {
   return null;
 }
 
+function detectRunIdMismatches(repos, coordinatorRepoRuns) {
+  const mismatches = [];
+  for (const repo of repos) {
+    if (!repo.ok || !repo.run_id) continue;
+    const expected = coordinatorRepoRuns[repo.repo_id]?.run_id;
+    if (!expected) continue;
+    if (expected !== repo.run_id) {
+      mismatches.push({
+        repo_id: repo.repo_id,
+        expected_run_id: expected,
+        actual_run_id: repo.run_id,
+      });
+    }
+  }
+  return mismatches;
+}
+
 function normalizePendingGate(pendingGate) {
   if (!pendingGate || typeof pendingGate !== 'object' || Array.isArray(pendingGate)) return null;
   if (typeof pendingGate.gate !== 'string' || pendingGate.gate.length === 0) return null;
@@ -317,7 +334,7 @@ function normalizePendingGate(pendingGate) {
   return normalized;
 }
 
-function deriveCoordinatorNextActions({ status, blockedReason, pendingGate, repos, coordinatorRepoRuns }) {
+function deriveCoordinatorNextActions({ status, blockedReason, pendingGate, repos, coordinatorRepoRuns, runIdMismatches }) {
   const nextActions = [];
 
   if (status === 'blocked') {
@@ -325,6 +342,14 @@ function deriveCoordinatorNextActions({ status, blockedReason, pendingGate, repo
       command: 'agentxchain multi resume',
       reason: `Coordinator is blocked${blockedReason ? `: ${blockedReason}` : ''}. Resume after fixing the underlying issue.`,
     });
+    if (runIdMismatches && runIdMismatches.length > 0) {
+      for (const m of runIdMismatches) {
+        nextActions.push({
+          command: `# repo_run_id_mismatch: ${m.repo_id}`,
+          reason: `Repo "${m.repo_id}" run identity drifted: coordinator expects "${m.expected_run_id}" but repo has "${m.actual_run_id}". Re-initialize the child repo with the correct run or use multi resume after investigation.`,
+        });
+      }
+    }
     if (pendingGate) {
       nextActions.push({
         command: 'agentxchain multi approve-gate',
@@ -574,12 +599,14 @@ function buildCoordinatorSubject(artifact) {
   const timing = computeCoordinatorTiming(artifact, coordinatorTimeline);
   const blockedReason = normalizeCoordinatorBlockedReason(coordinatorState.blocked_reason);
   const pendingGate = normalizePendingGate(coordinatorState.pending_gate);
+  const runIdMismatches = detectRunIdMismatches(repos, coordinatorState.repo_runs || {});
   const nextActions = deriveCoordinatorNextActions({
     status: artifact.summary?.status || null,
     blockedReason,
     pendingGate,
     repos,
     coordinatorRepoRuns: coordinatorState.repo_runs || {},
+    runIdMismatches,
   });
 
   return {
@@ -597,6 +624,7 @@ function buildCoordinatorSubject(artifact) {
       phase: artifact.summary?.phase || null,
       blocked_reason: blockedReason,
       pending_gate: pendingGate,
+      run_id_mismatches: runIdMismatches,
       next_actions: nextActions,
       created_at: timing.created_at,
       completed_at: timing.completed_at,
@@ -797,6 +825,16 @@ export function formatGovernanceReportText(report) {
     `Status: ${run.status || 'unknown'}`,
     `Phase: ${run.phase || 'unknown'}`,
     `Blocked reason: ${run.blocked_reason || 'none'}`,
+  ];
+
+  if (run.run_id_mismatches && run.run_id_mismatches.length > 0) {
+    lines.push(`Run ID mismatches: ${run.run_id_mismatches.length}`);
+    for (const m of run.run_id_mismatches) {
+      lines.push(`  - ${m.repo_id}: expected ${m.expected_run_id}, actual ${m.actual_run_id}`);
+    }
+  }
+
+  lines.push(
     `Started: ${run.created_at || 'n/a'}`,
     `Repos: ${coordinator.repo_count} total, ${run.repo_ok_count} exported cleanly, ${run.repo_error_count} failed`,
     `Workstreams: ${coordinator.workstream_count}`,
@@ -804,7 +842,7 @@ export function formatGovernanceReportText(report) {
     `Repo statuses: ${formatStatusCounts(run.repo_status_counts)}`,
     `History entries: ${artifacts.history_entries}`,
     `Decision entries: ${artifacts.decision_entries}`,
-  ];
+  );
 
   if (run.completed_at) {
     lines.push(`Completed: ${run.completed_at}`);
@@ -1044,6 +1082,16 @@ export function formatGovernanceReportMarkdown(report) {
     `- Status: \`${run.status || 'unknown'}\``,
     `- Phase: \`${run.phase || 'unknown'}\``,
     `- Blocked reason: \`${run.blocked_reason || 'none'}\``,
+  ];
+
+  if (run.run_id_mismatches && run.run_id_mismatches.length > 0) {
+    mdLines.push(`- **Run ID mismatches: ${run.run_id_mismatches.length}**`);
+    for (const m of run.run_id_mismatches) {
+      mdLines.push(`  - \`${m.repo_id}\`: expected \`${m.expected_run_id}\`, actual \`${m.actual_run_id}\``);
+    }
+  }
+
+  mdLines.push(
     `- Started: \`${run.created_at || 'n/a'}\``,
     `- Repos: ${coordinator.repo_count} total, ${run.repo_ok_count} exported cleanly, ${run.repo_error_count} failed`,
     `- Workstreams: ${coordinator.workstream_count}`,
@@ -1051,7 +1099,7 @@ export function formatGovernanceReportMarkdown(report) {
     `- Repo statuses: ${formatStatusCounts(run.repo_status_counts)}`,
     `- History entries: ${artifacts.history_entries}`,
     `- Decision entries: ${artifacts.decision_entries}`,
-  ];
+  );
 
   if (run.completed_at) {
     mdLines.push(`- Completed: \`${run.completed_at}\``);

package/src/lib/turn-result-validator.js

@@ -15,6 +15,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getActiveTurn } from './governed-state.js';
+import { getInvalidPhaseTransitionReason } from './gate-evaluator.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -519,6 +520,15 @@ function validateProtocol(tr, state, config) {
       errors.push(
         `phase_transition_request "${tr.phase_transition_request}" is not a defined phase in routing.`
       );
+    } else if (config.routing && state?.phase) {
+      const invalidOrderReason = getInvalidPhaseTransitionReason(
+        state.phase,
+        tr.phase_transition_request,
+        config.routing
+      );
+      if (invalidOrderReason) {
+        errors.push(invalidOrderReason);
+      }
     }
   }