agentxchain 2.24.1 → 2.24.3

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.1",
+  "version": "2.24.3",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/scripts/release-postflight.sh

@@ -101,6 +101,27 @@ trim_last_line() {
   printf '%s\n' "$1" | awk 'NF { line=$0 } END { gsub(/^[[:space:]]+|[[:space:]]+$/, "", line); print line }'
 }
 
+extract_matching_line() {
+  local output="$1"
+  local expected="$2"
+  printf '%s\n' "$output" | awk -v expected="$expected" '
+    {
+      line=$0
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", line)
+      if (line == expected) {
+        print line
+        found=1
+        exit
+      }
+    }
+    END {
+      if (!found) {
+        exit 1
+      }
+    }
+  '
+}
+
 run_install_smoke() {
   if [[ -z "$TARBALL_URL" ]]; then
     echo "registry tarball metadata unavailable for install smoke" >&2
@@ -147,18 +168,21 @@ run_npx_smoke() {
   local npx_status
 
   smoke_root="$(mktemp -d "${TMPDIR:-/tmp}/agentxchain-npx-postflight.XXXXXX")"
-  mkdir -p "${smoke_root}/home" "${smoke_root}/cache" "${smoke_root}/npm-cache"
+  mkdir -p "${smoke_root}/home" "${smoke_root}/cache" "${smoke_root}/npm-cache" "${smoke_root}/workspace"
 
   smoke_npmrc="${smoke_root}/.npmrc"
   echo "registry=https://registry.npmjs.org/" > "$smoke_npmrc"
 
   npx_output="$(
-    env -u NODE_AUTH_TOKEN \
-      HOME="${smoke_root}/home" \
-      XDG_CACHE_HOME="${smoke_root}/cache" \
-      NPM_CONFIG_CACHE="${smoke_root}/npm-cache" \
-      NPM_CONFIG_USERCONFIG="$smoke_npmrc" \
-      npx --yes "${PACKAGE_NAME}@${TARGET_VERSION}" --version 2>&1
+    (
+      cd "${smoke_root}/workspace" || exit 1
+      env -u NODE_AUTH_TOKEN \
+        HOME="${smoke_root}/home" \
+        XDG_CACHE_HOME="${smoke_root}/cache" \
+        NPM_CONFIG_CACHE="${smoke_root}/npm-cache" \
+        NPM_CONFIG_USERCONFIG="$smoke_npmrc" \
+        npx --yes -p "${PACKAGE_NAME}@${TARGET_VERSION}" -c "${PACKAGE_BIN_NAME} --version" 2>&1
+    )
   )"
   npx_status=$?
 
@@ -342,7 +366,7 @@ fi
 
 echo "[5/7] npx smoke"
 if run_with_retry NPX_OUTPUT "npx smoke" nonempty "" run_npx_smoke; then
-  NPX_VERSION="$(trim_last_line "$NPX_OUTPUT")"
+  NPX_VERSION="$(extract_matching_line "$NPX_OUTPUT" "$TARGET_VERSION" 2>/dev/null || trim_last_line "$NPX_OUTPUT")"
   if [[ "$NPX_VERSION" == "$TARGET_VERSION" ]]; then
     pass "published npx command resolves and reports ${TARGET_VERSION}"
   else

package/src/commands/demo.js

@@ -605,7 +605,7 @@ All acceptance criteria met. OBJ-002 (clock skew) noted for follow-up. OBJ-003 (
       console.log(chalk.dim('  ─'.repeat(26)));
       console.log('');
       console.log(`  ${chalk.bold('Try it for real:')}  agentxchain init --governed`);
-      console.log(`  ${chalk.bold('Step by step:')}    https://agentxchain.dev/docs/first-turn`);
+      console.log(`  ${chalk.bold('Step by step:')}    https://agentxchain.dev/docs/getting-started`);
       console.log(`  ${chalk.bold('Read more:')}       https://agentxchain.dev/docs/quickstart`);
       console.log('');
     }

package/src/commands/init.js

@@ -105,6 +105,7 @@ const GOVERNED_RUNTIMES = {
   'manual-pm': { type: 'manual' },
   'local-dev': DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME,
   'api-qa': { type: 'api_proxy', provider: 'anthropic', model: 'claude-sonnet-4-6', auth_env: 'ANTHROPIC_API_KEY' },
+  'manual-qa': { type: 'manual' },
   'manual-director': { type: 'manual' }
 };
 
@@ -684,6 +685,29 @@ async function initGoverned(opts) {
   console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);
   console.log('');
+
+  // Readiness hint: tell user which roles work immediately vs which need API keys
+  const allRuntimes = { ...GOVERNED_RUNTIMES, 'local-dev': localDevRuntime };
+  const needsKey = Object.entries(allRuntimes)
+    .filter(([, rt]) => rt.auth_env)
+    .map(([id, rt]) => ({ id, env: rt.auth_env }));
+  if (needsKey.length > 0) {
+    const envVars = [...new Set(needsKey.map(r => r.env))];
+    const roleNames = needsKey.map(r => r.id);
+    const hasKeys = envVars.every(v => process.env[v]);
+    if (hasKeys) {
+      console.log(`  ${chalk.green('Ready:')} all runtimes configured (${envVars.join(', ')} detected)`);
+    } else {
+      console.log(`  ${chalk.yellow('Mixed-mode:')} pm and eng_director work immediately (manual).`);
+      console.log(`  ${chalk.yellow('  ')}${roleNames.join(', ')} need ${chalk.bold(envVars.join(', '))} to dispatch automatically.`);
+      console.log(`  ${chalk.yellow('  ')}Without it, those turns fall back to manual input.`);
+      if (allRuntimes['manual-qa']) {
+        console.log(`  ${chalk.yellow('  ')}No-key QA path: change ${chalk.bold('roles.qa.runtime')} from ${chalk.bold('"api-qa"')} to ${chalk.bold('"manual-qa"')} in ${chalk.bold('agentxchain.json')}.`);
+      }
+    }
+    console.log('');
+  }
+
   console.log(`  ${chalk.cyan('Next:')}`);
   if (dir !== process.cwd()) {
     console.log(`    ${chalk.bold(`cd ${targetLabel}`)}`);
@@ -691,6 +715,8 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.bold('agentxchain step')} ${chalk.dim('# run the first governed turn')}`);
   console.log(`    ${chalk.bold('agentxchain status')} ${chalk.dim('# inspect phase, gate, and turn state')}`);
   console.log('');
+  console.log(`  ${chalk.dim('Guide:')} https://agentxchain.dev/docs/getting-started`);
+  console.log('');
 }
 
 export async function initCommand(opts) {

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/commands/run.js

@@ -47,7 +47,7 @@ export async function runCommand(opts) {
     process.exit(1);
   }
 
-  const { root, config } = context;
+  const { root, config, rawConfig } = context;
 
   if (config.protocol_mode !== 'governed') {
     console.log(chalk.red('The run command is only available for governed projects.'));
@@ -112,6 +112,7 @@ export async function runCommand(opts) {
 
   // ── Track first-call for --role override ────────────────────────────────
   let firstSelectRole = true;
+  let qaMissingCredentialsFallback = null;
 
   // ── Callbacks ───────────────────────────────────────────────────────────
   const callbacks = {
@@ -134,6 +135,7 @@ export async function runCommand(opts) {
       const runtime = cfg.runtimes?.[runtimeId];
       const runtimeType = runtime?.type || role?.runtime_class || 'manual';
       const hooksConfig = cfg.hooks || {};
+      qaMissingCredentialsFallback = null;
 
       // Manual adapter is not supported in run mode
       if (runtimeType === 'manual') {
@@ -219,6 +221,18 @@ export async function runCommand(opts) {
 
       // Adapter failure
       if (!adapterResult.ok) {
+        if (shouldPrintManualQaFallback({
+          roleId,
+          runtimeId,
+          classified: adapterResult.classified,
+          rawConfig,
+        })) {
+          qaMissingCredentialsFallback = {
+            roleId,
+            runtimeId,
+            errorClass: adapterResult.classified.error_class,
+          };
+        }
         const errorDetail = adapterResult.classified
           ? `${adapterResult.classified.error_class}: ${adapterResult.classified.recovery}`
           : adapterResult.error;
@@ -317,6 +331,10 @@ export async function runCommand(opts) {
     }
   }
 
+  if (qaMissingCredentialsFallback) {
+    printManualQaFallback();
+  }
+
   // Recovery guidance for blocked/rejected states
   if (result.state && (result.stop_reason === 'blocked' || result.stop_reason === 'reject_exhausted' || result.stop_reason === 'dispatch_error')) {
     const recovery = deriveRecoveryDescriptor(result.state);
@@ -391,3 +409,18 @@ function promptUser(question) {
     rl.on('close', () => resolve(''));
   });
 }
+
+function shouldPrintManualQaFallback({ roleId, runtimeId, classified, rawConfig }) {
+  return classified?.error_class === 'missing_credentials'
+    && roleId === 'qa'
+    && runtimeId === 'api-qa'
+    && rawConfig?.runtimes?.['manual-qa']?.type === 'manual';
+}
+
+function printManualQaFallback() {
+  console.log('');
+  console.log(chalk.dim('  No-key QA fallback:'));
+  console.log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
+  console.log(chalk.dim('  - Then recover the retained QA turn with: agentxchain step --resume'));
+  console.log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
+}

package/src/commands/step.js

@@ -71,7 +71,7 @@ export async function stepCommand(opts) {
     process.exit(1);
   }
 
-  const { root, config } = context;
+  const { root, config, rawConfig } = context;
 
   if (config.protocol_mode !== 'governed') {
     console.log(chalk.red('The step command is only available for governed projects.'));
@@ -422,6 +422,18 @@ export async function stepCommand(opts) {
         console.log(chalk.dim(`  Retry trace: ${apiResult.retry_trace_path}`));
       }
 
+      if (
+        apiResult.classified?.error_class === 'missing_credentials'
+        && roleId === 'qa'
+        && config.roles?.qa?.runtime_id === 'api-qa'
+        && rawConfig?.runtimes?.['manual-qa']?.type === 'manual'
+      ) {
+        console.log(chalk.dim('  No-key QA fallback:'));
+        console.log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
+        console.log(chalk.dim('  - Then rerun: agentxchain step --resume'));
+        console.log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
+      }
+
       console.log(chalk.dim('The turn remains assigned. You can:'));
       console.log(chalk.dim('  - Fix the issue and retry: agentxchain step --resume'));
       console.log(chalk.dim('  - Complete manually: edit .agentxchain/staging/turn-result.json'));

package/src/lib/adapters/manual-adapter.js

@@ -30,31 +30,100 @@ export function printManualDispatchInstructions(state, config, options = {}) {
   const role = config.roles?.[turn.assigned_role];
   const promptPath = getDispatchPromptPath(turn.turn_id);
   const stagingPath = getTurnStagingResultPath(turn.turn_id);
+  const phase = state.phase || 'planning';
+  const roleId = turn.assigned_role;
 
   const lines = [];
   lines.push('');
   lines.push('  +---------------------------------------------------------+');
   lines.push('  |  MANUAL TURN REQUIRED                                    |');
   lines.push('  |                                                          |');
-  lines.push(`  |  Role:    ${pad(turn.assigned_role, 46)}|`);
+  lines.push(`  |  Role:    ${pad(roleId, 46)}|`);
   lines.push(`  |  Turn:    ${pad(turn.turn_id, 46)}|`);
-  lines.push(`  |  Phase:   ${pad(state.phase, 46)}|`);
+  lines.push(`  |  Phase:   ${pad(phase, 46)}|`);
   lines.push(`  |  Attempt: ${pad(String(turn.attempt), 46)}|`);
   lines.push('  |                                                          |');
   lines.push(`  |  Prompt:  ${pad(promptPath, 46)}|`);
   lines.push(`  |  Result:  ${pad(stagingPath, 46)}|`);
-  lines.push('  |                                                          |');
-  lines.push('  |  1. Read the prompt at the path above                    |');
-  lines.push('  |  2. Complete the work described in the prompt             |');
-  lines.push('  |  3. Write your turn result JSON to the result path       |');
-  lines.push('  |                                                          |');
-  lines.push('  |  The step command will detect the file and proceed.      |');
   lines.push('  +---------------------------------------------------------+');
   lines.push('');
+  lines.push('  Steps:');
+  lines.push(`    1. Read the prompt:   cat ${promptPath}`);
+  lines.push('    2. Do the work described in the prompt');
+  lines.push(`    3. Write turn-result.json to:  ${stagingPath}`);
+  lines.push('    4. The step command will detect the file and proceed');
+  lines.push('');
+
+  // Phase-aware guidance
+  const gateHints = getPhaseGateHints(phase, roleId, config);
+  if (gateHints.length > 0) {
+    lines.push('  Gate files to update this phase:');
+    for (const hint of gateHints) {
+      lines.push(`    - ${hint}`);
+    }
+    lines.push('');
+  }
+
+  // Minimal turn-result example
+  lines.push('  Minimal turn-result.json:');
+  lines.push('  {');
+  lines.push('    "schema_version": "1.0",');
+  lines.push(`    "run_id": "${state.run_id || 'run_...'}",`);
+  lines.push(`    "turn_id": "${turn.turn_id}",`);
+  lines.push(`    "role": "${roleId}",`);
+  lines.push(`    "runtime_id": "${role?.runtime || 'manual'}",`);
+  lines.push('    "status": "completed",');
+  lines.push('    "summary": "...",');
+  lines.push('    "decisions": [{"id":"DEC-001","category":"scope","statement":"...","rationale":"..."}],');
+  lines.push('    "objections": [{"id":"OBJ-001","severity":"medium","statement":"...","status":"raised"}],');
+  lines.push('    "files_changed": [],');
+  lines.push('    "verification": {"status":"skipped","commands":[],"evidence_summary":"..."},');
+  lines.push('    "artifact": {"type":"review","ref":null},');
+  lines.push(`    "proposed_next_role": "${getDefaultNextRole(roleId, config)}",`);
+  lines.push('    "phase_transition_request": null,');
+  lines.push('    "run_completion_request": null');
+  lines.push('  }');
+  lines.push('');
+  lines.push('  Docs: https://agentxchain.dev/docs/getting-started');
+  lines.push('');
 
   return lines.join('\n');
 }
 
+/**
+ * Return gate-file hints relevant to the current phase and role.
+ */
+function getPhaseGateHints(phase, roleId, config) {
+  const hints = [];
+  const gates = config.gates || {};
+
+  if (phase === 'planning' && (roleId === 'pm' || roleId === 'human')) {
+    hints.push('.planning/PM_SIGNOFF.md — change "Approved: NO" → "Approved: YES" when ready');
+    hints.push('.planning/ROADMAP.md — define phases and acceptance criteria');
+    hints.push('.planning/SYSTEM_SPEC.md — define ## Purpose, ## Interface, ## Acceptance Tests');
+  } else if (phase === 'implementation' && (roleId === 'dev' || roleId === 'human')) {
+    hints.push('.planning/IMPLEMENTATION_NOTES.md — record what you built and how to verify');
+  } else if (phase === 'qa' && (roleId === 'qa' || roleId === 'human')) {
+    hints.push('.planning/acceptance-matrix.md — mark each requirement PASS/FAIL');
+    hints.push('.planning/ship-verdict.md — change "## Verdict: PENDING" → "## Verdict: SHIP"');
+    hints.push('.planning/RELEASE_NOTES.md — user impact, verification summary, upgrade notes');
+  }
+
+  return hints;
+}
+
+/**
+ * Suggest a reasonable next role based on current role.
+ */
+function getDefaultNextRole(roleId, config) {
+  const routing = config.routing || {};
+  if (routing[roleId]?.default_next) return routing[roleId].default_next;
+  if (roleId === 'pm') return 'dev';
+  if (roleId === 'dev') return 'qa';
+  if (roleId === 'qa') return 'human';
+  return 'human';
+}
+
 /**
  * Wait for the staged turn result file to appear.
  *

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/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}\``);