agentxchain 2.83.0 → 2.85.0

package/builtin-plugins/plugin-github-issues/README.md

@@ -2,7 +2,14 @@
 
 Built-in AgentXchain plugin that mirrors governed run status into a configured GitHub issue.
 
-Install from this repo:
+Install by short name (recommended):
+
+```bash
+agentxchain plugin install github-issues \
+  --config '{"repo":"owner/name","issue_number":42}'
+```
+
+Install from local path:
 
 ```bash
 agentxchain plugin install ./plugins/plugin-github-issues
@@ -29,3 +36,8 @@ Scope notes:
 - One plugin-owned comment per run, updated in place
 - Managed labels track phase or blocked state only
 - This plugin does **not** close issues or claim post-gate approval state because the hook surface does not provide post-gate truth
+
+Proof surfaces:
+
+- Continuous subprocess proof: `cli/test/e2e-builtin-github-issues.test.js`
+- Live product-example proof: `examples/governed-todo-app/run-github-issues-proof.mjs`

package/builtin-plugins/plugin-json-report/README.md

@@ -2,7 +2,13 @@
 
 Built-in AgentXchain plugin that writes structured lifecycle report artifacts into `.agentxchain/reports/`.
 
-Install from this repo:
+Install by built-in short name (recommended):
+
+```bash
+agentxchain plugin install json-report
+```
+
+Install from a repo-local path:
 
 ```bash
 agentxchain plugin install ./plugins/plugin-json-report
@@ -15,6 +21,12 @@ agentxchain plugin install ./plugins/plugin-json-report \
   --config '{"report_dir":".agentxchain/custom-reports"}'
 ```
 
+Live proof command:
+
+```bash
+node examples/governed-todo-app/run-json-report-proof.mjs --json
+```
+
 Hook phases:
 
 - `after_acceptance`
@@ -28,3 +40,4 @@ Outputs:
 - `latest-<hook_phase>.json`
 - default output path `.agentxchain/reports`
 - `report_dir` may override the path, but it must stay inside the governed project root
+- `latest.json` reflects the most recent hook invocation

package/package.json

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

package/scripts/model-compatibility-probe.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+/**
+ * Model Compatibility Probe — api_proxy + proposed write authority
+ *
+ * Dispatches a lightweight governed turn to each target model and records
+ * whether the model can produce a well-formed turn result with proposed_changes.
+ *
+ * Usage:
+ *   node cli/scripts/model-compatibility-probe.mjs
+ *   node cli/scripts/model-compatibility-probe.mjs --json
+ *
+ * Requires ANTHROPIC_API_KEY in the environment.
+ */
+
+const ANTHROPIC_ENDPOINT = 'https://api.anthropic.com/v1/messages';
+
+const SYSTEM_PROMPT = [
+  'You are acting as a governed agent in an AgentXchain protocol run.',
+  'Your task and rules are described in the user message.',
+  'You MUST respond with a valid JSON object matching the turn result schema provided in the prompt.',
+  'Do NOT wrap the JSON in markdown code fences. Respond with raw JSON only.',
+].join('\n');
+
+const PROBE_PROMPT = `You are a governed agent with write_authority: "proposed".
+
+Your task: create a single file called \`probe-result.txt\` containing the text "model compatibility probe passed".
+
+Respond with a single raw JSON object (no markdown fences) matching this exact schema:
+
+{
+  "schema_version": "1.0",
+  "run_id": "probe_run",
+  "turn_id": "probe_turn_001",
+  "role": "dev",
+  "runtime_id": "probe_runtime",
+  "status": "completed",
+  "summary": "Created probe-result.txt for model compatibility verification.",
+  "decisions": [],
+  "objections": [],
+  "files_changed": ["probe-result.txt"],
+  "verification": { "status": "pass", "evidence": "File created successfully." },
+  "artifact": { "type": "patch", "ref": null },
+  "proposed_next_role": "human",
+  "proposed_changes": [
+    {
+      "path": "probe-result.txt",
+      "action": "create",
+      "content": "model compatibility probe passed"
+    }
+  ]
+}
+
+Return ONLY the JSON object. No explanation, no markdown fences, no extra text.`;
+
+const MODELS = [
+  { id: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5', maxTokens: 2048, costInput: 1.00, costOutput: 5.00 },
+  { id: 'claude-sonnet-4-6', label: 'Sonnet 4.6', maxTokens: 2048, costInput: 3.00, costOutput: 15.00 },
+];
+
+function extractTurnResult(text) {
+  if (typeof text !== 'string' || !text.trim()) {
+    return { ok: false, error: 'Empty response text' };
+  }
+  const trimmed = text.trim();
+
+  // Direct JSON parse
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+      return { ok: true, turnResult: parsed, method: 'direct' };
+    }
+  } catch { /* not pure JSON */ }
+
+  // Markdown fence extraction
+  const fenceMatch = trimmed.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+  if (fenceMatch) {
+    try {
+      const parsed = JSON.parse(fenceMatch[1].trim());
+      if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+        return { ok: true, turnResult: parsed, method: 'fence' };
+      }
+    } catch { /* invalid JSON inside fence */ }
+  }
+
+  // Substring extraction
+  const jsonStart = trimmed.indexOf('{');
+  const jsonEnd = trimmed.lastIndexOf('}');
+  if (jsonStart >= 0 && jsonEnd > jsonStart) {
+    try {
+      const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd + 1));
+      if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+        return { ok: true, turnResult: parsed, method: 'substring' };
+      }
+    } catch { /* not valid JSON */ }
+  }
+
+  return { ok: false, error: 'Could not extract structured turn result JSON' };
+}
+
+function validateProposedChanges(turnResult) {
+  const changes = turnResult?.proposed_changes;
+  if (!Array.isArray(changes) || changes.length === 0) {
+    return { present: false, wellFormed: false, reason: 'proposed_changes missing or empty' };
+  }
+  for (const c of changes) {
+    if (!c.path || typeof c.path !== 'string') {
+      return { present: true, wellFormed: false, reason: `entry missing path` };
+    }
+    if (!['create', 'modify', 'delete'].includes(c.action)) {
+      return { present: true, wellFormed: false, reason: `invalid action: ${c.action}` };
+    }
+    if ((c.action === 'create' || c.action === 'modify') && (!c.content || typeof c.content !== 'string')) {
+      return { present: true, wellFormed: false, reason: `${c.action} entry missing content for ${c.path}` };
+    }
+  }
+  return { present: true, wellFormed: true, count: changes.length };
+}
+
+async function probeModel(model, apiKey) {
+  const startMs = Date.now();
+  const body = {
+    model: model.id,
+    max_tokens: model.maxTokens,
+    system: SYSTEM_PROMPT,
+    messages: [{ role: 'user', content: PROBE_PROMPT }],
+  };
+
+  let responseData;
+  let rawError = null;
+
+  try {
+    const res = await fetch(ANTHROPIC_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const errorBody = await res.text().catch(() => '');
+      rawError = `HTTP ${res.status}: ${errorBody.slice(0, 500)}`;
+      return {
+        model: model.id,
+        label: model.label,
+        extraction_success: false,
+        schema_valid: false,
+        proposed_changes_present: false,
+        proposed_changes_well_formed: false,
+        latency_ms: Date.now() - startMs,
+        cost_usd: 0,
+        classification: 'unsupported',
+        raw_error: rawError,
+      };
+    }
+
+    responseData = await res.json();
+  } catch (err) {
+    return {
+      model: model.id,
+      label: model.label,
+      extraction_success: false,
+      schema_valid: false,
+      proposed_changes_present: false,
+      proposed_changes_well_formed: false,
+      latency_ms: Date.now() - startMs,
+      cost_usd: 0,
+      classification: 'unsupported',
+      raw_error: err.message,
+    };
+  }
+
+  const latencyMs = Date.now() - startMs;
+
+  // Extract text from Anthropic response
+  const textBlock = responseData?.content?.find(b => b.type === 'text');
+  const responseText = textBlock?.text || '';
+
+  // Extract turn result
+  const extraction = extractTurnResult(responseText);
+
+  // Calculate cost
+  const usage = responseData?.usage || {};
+  const inputTokens = usage.input_tokens || 0;
+  const outputTokens = usage.output_tokens || 0;
+  const costUsd = (inputTokens / 1_000_000) * model.costInput + (outputTokens / 1_000_000) * model.costOutput;
+
+  if (!extraction.ok) {
+    return {
+      model: model.id,
+      label: model.label,
+      extraction_success: false,
+      extraction_method: null,
+      schema_valid: false,
+      proposed_changes_present: false,
+      proposed_changes_well_formed: false,
+      latency_ms: latencyMs,
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      cost_usd: Math.round(costUsd * 1_000_000) / 1_000_000,
+      classification: 'unsupported',
+      raw_error: extraction.error,
+      response_preview: responseText.slice(0, 300),
+    };
+  }
+
+  const tr = extraction.turnResult;
+  const schemaValid = typeof tr.schema_version === 'string' && tr.schema_version === '1.0';
+  const pcValidation = validateProposedChanges(tr);
+
+  let classification;
+  if (schemaValid && pcValidation.present && pcValidation.wellFormed) {
+    classification = 'reliable';
+  } else if (extraction.ok && (!pcValidation.present || !pcValidation.wellFormed)) {
+    classification = 'inconsistent';
+  } else {
+    classification = 'unsupported';
+  }
+
+  return {
+    model: model.id,
+    label: model.label,
+    extraction_success: true,
+    extraction_method: extraction.method,
+    schema_valid: schemaValid,
+    proposed_changes_present: pcValidation.present,
+    proposed_changes_well_formed: pcValidation.wellFormed,
+    proposed_changes_count: pcValidation.count || 0,
+    latency_ms: latencyMs,
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cost_usd: Math.round(costUsd * 1_000_000) / 1_000_000,
+    classification,
+    raw_error: pcValidation.reason || null,
+    status_returned: tr.status,
+    summary_returned: typeof tr.summary === 'string' ? tr.summary.slice(0, 100) : null,
+  };
+}
+
+async function main() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    console.error('ANTHROPIC_API_KEY not set');
+    process.exit(1);
+  }
+
+  const jsonMode = process.argv.includes('--json');
+
+  if (!jsonMode) {
+    console.log('AgentXchain Model Compatibility Probe');
+    console.log('Provider: Anthropic | Write Authority: proposed');
+    console.log('─'.repeat(60));
+  }
+
+  const results = [];
+
+  for (const model of MODELS) {
+    if (!jsonMode) {
+      process.stdout.write(`Probing ${model.label} (${model.id})... `);
+    }
+
+    const result = await probeModel(model, apiKey);
+    results.push(result);
+
+    if (!jsonMode) {
+      const icon = result.classification === 'reliable' ? '✓' : result.classification === 'inconsistent' ? '~' : '✗';
+      console.log(`${icon} ${result.classification} (${result.latency_ms}ms, $${result.cost_usd})`);
+      if (result.raw_error) {
+        console.log(`  └─ ${result.raw_error}`);
+      }
+    }
+  }
+
+  const output = {
+    probe_version: '1.0',
+    timestamp: new Date().toISOString(),
+    provider: 'anthropic',
+    write_authority: 'proposed',
+    models: results,
+    total_cost_usd: results.reduce((s, r) => s + r.cost_usd, 0),
+  };
+
+  if (jsonMode) {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log('─'.repeat(60));
+    console.log(`Total cost: $${output.total_cost_usd.toFixed(6)}`);
+    console.log();
+    console.log('Matrix:');
+    for (const r of results) {
+      console.log(`  ${r.label.padEnd(12)} ${r.classification.padEnd(14)} extraction=${r.extraction_success} schema=${r.schema_valid} proposed=${r.proposed_changes_well_formed}`);
+    }
+  }
+
+  // Write results to .planning/ for durable reference
+  const { writeFileSync, mkdirSync } = await import('node:fs');
+  const { dirname, join } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const outPath = join(repoRoot, '.planning', 'MODEL_COMPATIBILITY_RESULTS.json');
+  writeFileSync(outPath, JSON.stringify(output, null, 2) + '\n');
+  if (!jsonMode) {
+    console.log(`\nResults written to: .planning/MODEL_COMPATIBILITY_RESULTS.json`);
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/release-bump.sh

@@ -62,7 +62,6 @@ ALLOWED_RELEASE_PATHS=(
   "website-v2/docs/protocol-implementor-guide.mdx"
   ".planning/LAUNCH_EVIDENCE_REPORT.md"
   "website-v2/static/llms.txt"
-  "website-v2/static/sitemap.xml"
   "cli/homebrew/agentxchain.rb"
   "cli/homebrew/README.md"
 )
@@ -148,9 +147,9 @@ if [[ ! -f "${REPO_ROOT}/${RELEASE_DOC_PATH}" ]]; then
   SURFACE_ERRORS+=("release notes page missing: ${RELEASE_DOC_PATH}")
 fi
 
-# 4c. Docs sidebar links the release page
-if ! grep -q "'releases/${RELEASE_DOC_ID}'" "${REPO_ROOT}/website-v2/sidebars.ts" 2>/dev/null; then
-  SURFACE_ERRORS+=("sidebars.ts does not link 'releases/${RELEASE_DOC_ID}'")
+# 4c. Docs sidebar auto-generates releases from dirName (release doc existence is sufficient)
+if ! grep -q "dirName.*releases" "${REPO_ROOT}/website-v2/sidebars.ts" 2>/dev/null; then
+  SURFACE_ERRORS+=("sidebars.ts does not auto-generate releases (missing dirName: 'releases')")
 fi
 
 # 4d. Homepage hero badge shows target version
@@ -181,10 +180,7 @@ if ! grep -q "${CURRENT_RELEASE_ROUTE}" "${REPO_ROOT}/website-v2/static/llms.txt
   SURFACE_ERRORS+=("website-v2/static/llms.txt does not list '${CURRENT_RELEASE_ROUTE}'")
 fi
 
-# 4i. sitemap.xml must list the current release notes route
-if ! grep -q "${CURRENT_RELEASE_ROUTE}" "${REPO_ROOT}/website-v2/static/sitemap.xml" 2>/dev/null; then
-  SURFACE_ERRORS+=("website-v2/static/sitemap.xml does not list '${CURRENT_RELEASE_ROUTE}'")
-fi
+# 4i. sitemap.xml is now auto-generated by Docusaurus at build time — no static file check needed
 
 if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
   echo "FAIL: ${#SURFACE_ERRORS[@]} version-surface(s) not aligned to ${TARGET_VERSION}:" >&2
@@ -194,7 +190,7 @@ if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
   echo "create release identity when governed surfaces are stale." >&2
   exit 1
 fi
-echo "  OK: all 9 governed version surfaces reference ${TARGET_VERSION}"
+echo "  OK: all 8 governed version surfaces reference ${TARGET_VERSION}"
 
 # 5. Auto-align Homebrew mirror to target version
 # The formula URL and README version/tarball are updated automatically.

package/src/commands/config.js

@@ -219,6 +219,12 @@ function setSetting(config, configPath, keyValPair, context) {
   console.log('');
   console.log(chalk.green(`  ✓ Set ${chalk.bold(key)} = ${val}`));
   if (oldVal !== undefined) console.log(chalk.dim(`    (was: ${oldVal})`));
+  if ((validation.warnings || []).length > 0) {
+    console.log(chalk.yellow('  Warnings:'));
+    for (const warning of validation.warnings) {
+      console.log(chalk.dim(`    - ${warning}`));
+    }
+  }
   console.log('');
 }
 

package/src/commands/doctor.js

@@ -51,8 +51,11 @@ function governedDoctor(root, rawConfig, opts) {
 
   // 1. Config validation
   const configResult = loadNormalizedConfig(rawConfig, root);
-  if (configResult.ok) {
+  if (configResult.ok && (configResult.warnings || []).length === 0) {
     checks.push({ id: 'config_valid', name: 'Config validation', level: 'pass', detail: 'Config loads and validates' });
+  } else if (configResult.ok) {
+    const warningSummary = configResult.warnings.slice(0, 2).join('; ');
+    checks.push({ id: 'config_valid', name: 'Config validation', level: 'warn', detail: warningSummary });
   } else {
     const errorSummary = configResult.errors.slice(0, 3).join('; ');
     checks.push({ id: 'config_valid', name: 'Config validation', level: 'fail', detail: errorSummary });

package/src/commands/run.js

@@ -270,6 +270,7 @@ export async function executeGovernedRun(context, opts = {}) {
         signal: controller.signal,
         onStatus: (msg) => log(chalk.dim(`  ${msg}`)),
         verifyManifest: true,
+        turnId: turn.turn_id,
       };
 
       if (verbose) {

package/src/lib/normalized-config.js

@@ -330,9 +330,10 @@ export function detectConfigVersion(raw) {
  */
 export function validateV4Config(data, projectRoot) {
   const errors = [];
+  const warnings = [];
 
   if (!data || typeof data !== 'object') {
-    return { ok: false, errors: ['Config must be a JSON object'] };
+    return { ok: false, errors: ['Config must be a JSON object'], warnings };
   }
 
   // Top-level required sections
@@ -555,7 +556,80 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...timeoutValidation.errors);
   }
 
-  return { ok: errors.length === 0, errors };
+  warnings.push(...collectRemoteReviewOnlyGateWarnings(data));
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+export function collectRemoteReviewOnlyGateWarnings(data) {
+  const warnings = [];
+  const routing = data?.routing;
+  const gates = data?.gates;
+  const roles = data?.roles;
+  const runtimes = data?.runtimes;
+
+  if (!routing || !gates || !roles || !runtimes) {
+    return warnings;
+  }
+
+  for (const [phase, route] of Object.entries(routing)) {
+    const exitGateId = route?.exit_gate;
+    if (!exitGateId || !gates[exitGateId]) {
+      continue;
+    }
+
+    const requiredFiles = Array.isArray(gates[exitGateId]?.requires_files)
+      ? gates[exitGateId].requires_files.filter(filePath => typeof filePath === 'string' && filePath.trim())
+      : [];
+    if (requiredFiles.length === 0) {
+      continue;
+    }
+
+    const candidateRoleIds = [
+      route?.entry_role,
+      ...(Array.isArray(route?.allowed_next_roles) ? route.allowed_next_roles : []),
+    ].filter((roleId) => roleId && roleId !== 'human');
+
+    if (candidateRoleIds.length === 0) {
+      continue;
+    }
+
+    const candidateRoles = [...new Set(candidateRoleIds)]
+      .map((roleId) => {
+        const role = roles[roleId];
+        const runtime = role?.runtime ? runtimes[role.runtime] : null;
+        if (!role || !runtime) {
+          return null;
+        }
+        return { roleId, role, runtime };
+      })
+      .filter(Boolean);
+
+    if (candidateRoles.length === 0) {
+      continue;
+    }
+
+    const hasFileProducingRole = candidateRoles.some(({ role }) =>
+      role.write_authority === 'authoritative' || role.write_authority === 'proposed');
+    if (hasFileProducingRole) {
+      continue;
+    }
+
+    const allRemoteReviewOnly = candidateRoles.every(({ role, runtime }) =>
+      role.write_authority === 'review_only' && (runtime.type === 'api_proxy' || runtime.type === 'remote_agent'));
+    if (!allRemoteReviewOnly) {
+      continue;
+    }
+
+    const roleSummary = candidateRoles
+      .map(({ roleId, runtime }) => `${roleId}:${runtime.type}`)
+      .join(', ');
+    warnings.push(
+      `Routing "${phase}" exits through gate "${exitGateId}" with requires_files (${requiredFiles.join(', ')}) but all participating roles are review_only remote runtimes (${roleSummary}). Those files cannot be produced through governed turns; add a proposed/authoritative writer, remove the gate files, or expect operator-managed out-of-band artifacts.`,
+    );
+  }
+
+  return warnings;
 }
 
 export function validateBudgetConfig(budget) {
@@ -1133,6 +1207,7 @@ export function loadNormalizedConfig(raw, projectRoot) {
       ok: false,
       normalized: null,
       errors: ['Unrecognized config format. Expected version: 3 or schema_version: "1.0" / 4'],
+      warnings: [],
       version: null,
     };
   }
@@ -1152,17 +1227,17 @@ export function loadNormalizedConfig(raw, projectRoot) {
       }
     }
     if (errors.length > 0) {
-      return { ok: false, normalized: null, errors, version: 3 };
+      return { ok: false, normalized: null, errors, warnings: [], version: 3 };
     }
-    return { ok: true, normalized: normalizeV3(raw), errors: [], version: 3 };
+    return { ok: true, normalized: normalizeV3(raw), errors: [], warnings: [], version: 3 };
   }
 
   if (version === 4) {
     const validation = validateV4Config(raw, projectRoot || null);
     if (!validation.ok) {
-      return { ok: false, normalized: null, errors: validation.errors, version: 4 };
+      return { ok: false, normalized: null, errors: validation.errors, warnings: validation.warnings || [], version: 4 };
     }
-    return { ok: true, normalized: normalizeV4(raw), errors: [], version: 4 };
+    return { ok: true, normalized: normalizeV4(raw), errors: [], warnings: validation.warnings || [], version: 4 };
   }
 }
 

package/src/lib/run-loop.js

@@ -5,6 +5,9 @@
  * well-defined pause points. Any runner (CLI, CI, hosted, custom) composes
  * this to implement continuous governed delivery.
  *
+ * Supports parallel turn dispatch when max_concurrent_turns > 1 is configured
+ * for the current phase (DEC-PARALLEL-RUN-LOOP-001).
+ *
  * Design rules:
  *   - Never calls process dot exit
  *   - No stdout/stderr
@@ -24,6 +27,8 @@ import {
   approveCompletionGate,
   getActiveTurn,
   getActiveTurnCount,
+  getActiveTurns,
+  getMaxConcurrentTurns,
   RUNNER_INTERFACE_VERSION,
 } from './runner-interface.js';
 
@@ -35,6 +40,10 @@ const DEFAULT_MAX_TURNS = 50;
 /**
  * Drive governed turns to a terminal state.
  *
+ * When max_concurrent_turns > 1 for the current phase, the loop fills
+ * available concurrency slots and dispatches all active turns concurrently.
+ * Acceptance is serialized by the existing lock mechanism.
+ *
  * @param {string} root - project root directory
  * @param {object} config - normalized governed config
  * @param {object} callbacks - { selectRole, dispatch, approveGate, onEvent? }
@@ -110,107 +119,307 @@ export async function runLoop(root, config, callbacks, options = {}) {
       return makeResult(false, 'max_turns_reached', state, turnsExecuted, turnHistory, gatesApproved, errors);
     }
 
-    // ── Check for active turn (retry after rejection) ──────────────────��
-    let turn;
-    let assignState;
-    const activeTurn = getActiveTurn(state);
+    // ── Determine concurrency mode ────────────────────────────────────────
+    const maxConcurrent = getMaxConcurrentTurns(config, state.phase);
 
-    if (activeTurn && (activeTurn.status === 'running' || activeTurn.status === 'retrying')) {
-      // Re-dispatch an existing active turn (retry after rejection)
-      turn = activeTurn;
-      assignState = state;
+    if (maxConcurrent <= 1) {
+      // ── Sequential mode (original behavior) ──────────────────────────
+      const seqResult = await executeSequentialTurn(root, config, state, callbacks, emit, errors);
+      if (seqResult.terminal) {
+        return makeResult(seqResult.ok, seqResult.stop_reason, loadState(root, config), turnsExecuted, turnHistory, gatesApproved, errors);
+      }
+      if (seqResult.accepted) {
+        turnsExecuted++;
+      }
+      turnHistory.push(...seqResult.history);
     } else {
-      // ── Role selection ────────────────────────────────────────────────
-      let roleId;
-      try {
-        roleId = callbacks.selectRole(state, config);
-      } catch (err) {
-        errors.push(`selectRole threw: ${err.message}`);
-        return makeResult(false, 'dispatch_error', state, turnsExecuted, turnHistory, gatesApproved, errors);
+      // ── Parallel mode ────────────────────────────────────────────────
+      const parResult = await executeParallelTurns(root, config, state, maxConcurrent, callbacks, emit, errors);
+      if (parResult.terminal) {
+        return makeResult(parResult.ok, parResult.stop_reason, loadState(root, config), turnsExecuted, turnHistory, gatesApproved, errors);
       }
+      turnsExecuted += parResult.acceptedCount;
+      turnHistory.push(...parResult.history);
+    }
+  }
+}
 
-      if (roleId === null || roleId === undefined) {
-        emit({ type: 'caller_stopped', state });
-        return makeResult(false, 'caller_stopped', state, turnsExecuted, turnHistory, gatesApproved, errors);
-      }
+/**
+ * Execute a single turn (sequential mode — original behavior preserved).
+ */
+async function executeSequentialTurn(root, config, state, callbacks, emit, errors) {
+  let turn;
+  let assignState;
+  const activeTurn = getActiveTurn(state);
 
-      // ── Turn assignment ───────────────────────────────────────────────
-      const assignResult = assignTurn(root, config, roleId);
-      if (!assignResult.ok) {
-        errors.push(`assignTurn(${roleId}): ${assignResult.error}`);
-        return makeResult(false, 'blocked', loadState(root, config), turnsExecuted, turnHistory, gatesApproved, errors);
-      }
-      turn = assignResult.turn;
-      assignState = assignResult.state;
-      emit({ type: 'turn_assigned', turn, role: roleId, state: assignState });
+  if (activeTurn && (activeTurn.status === 'running' || activeTurn.status === 'retrying')) {
+    turn = activeTurn;
+    assignState = state;
+  } else {
+    let roleId;
+    try {
+      roleId = callbacks.selectRole(state, config);
+    } catch (err) {
+      errors.push(`selectRole threw: ${err.message}`);
+      return { terminal: true, ok: false, stop_reason: 'dispatch_error', history: [] };
     }
 
-    const roleId = turn.assigned_role;
+    if (roleId === null || roleId === undefined) {
+      emit({ type: 'caller_stopped', state });
+      return { terminal: true, ok: false, stop_reason: 'caller_stopped', history: [] };
+    }
 
-    // ── Dispatch bundle ─────────────────────────────────────────────────
-    const bundleResult = writeDispatchBundle(root, assignState, config);
-    if (!bundleResult.ok) {
-      errors.push(`writeDispatchBundle(${roleId}): ${bundleResult.error}`);
-      return makeResult(false, 'blocked', loadState(root, config), turnsExecuted, turnHistory, gatesApproved, errors);
+    const assignResult = assignTurn(root, config, roleId);
+    if (!assignResult.ok) {
+      errors.push(`assignTurn(${roleId}): ${assignResult.error}`);
+      return { terminal: true, ok: false, stop_reason: 'blocked', history: [] };
     }
+    turn = assignResult.turn;
+    assignState = assignResult.state;
+    emit({ type: 'turn_assigned', turn, role: roleId, state: assignState });
+  }
+
+  return await dispatchAndProcess(root, config, turn, assignState, callbacks, emit, errors);
+}
+
+/**
+ * Fill concurrency slots and dispatch all active turns concurrently.
+ */
+async function executeParallelTurns(root, config, state, maxConcurrent, callbacks, emit, errors) {
+  const history = [];
+  let acceptedCount = 0;
+
+  // ── Collect active turns that need dispatch (retries) ────────────────
+  const activeTurns = getActiveTurns(state);
+  const turnsToDispatch = [];
+  for (const turn of Object.values(activeTurns)) {
+    if (turn.status === 'running' || turn.status === 'retrying') {
+      turnsToDispatch.push({ turn, state });
+    }
+  }
+
+  // ── Fill concurrency slots with new assignments ──────────────────────
+  let activeCount = getActiveTurnCount(state);
+  const triedRoles = new Set();
+  while (activeCount < maxConcurrent) {
+    let roleId;
+    try {
+      roleId = callbacks.selectRole(state, config);
+    } catch (err) {
+      errors.push(`selectRole threw: ${err.message}`);
+      break;
+    }
+
+    if (roleId === null || roleId === undefined) {
+      // No more roles to assign — dispatch what we have
+      break;
+    }
+
+    // If selectRole returns a role we already tried (or assigned), try
+    // other eligible roles from the routing before giving up.
+    if (triedRoles.has(roleId)) {
+      const phase = state.phase;
+      const allowed = config?.routing?.[phase]?.allowed_next_roles || [];
+      const alternateFound = allowed.some((alt) => {
+        if (alt === 'human' || triedRoles.has(alt) || !config?.roles?.[alt]) return false;
+        const altResult = assignTurn(root, config, alt);
+        if (altResult.ok) {
+          triedRoles.add(alt);
+          turnsToDispatch.push({ turn: altResult.turn, state: altResult.state });
+          emit({ type: 'turn_assigned', turn: altResult.turn, role: alt, state: altResult.state });
+          state = loadState(root, config);
+          activeCount = getActiveTurnCount(state);
+          return true;
+        }
+        triedRoles.add(alt);
+        return false;
+      });
+      if (!alternateFound) break;
+      continue;
+    }
+
+    triedRoles.add(roleId);
+    const assignResult = assignTurn(root, config, roleId);
+    if (!assignResult.ok) {
+      // Cannot assign — try other eligible roles before giving up
+      continue;
+    }
+
+    turnsToDispatch.push({ turn: assignResult.turn, state: assignResult.state });
+    emit({ type: 'turn_assigned', turn: assignResult.turn, role: roleId, state: assignResult.state });
+
+    // Reload state after assignment to get accurate active count
+    state = loadState(root, config);
+    activeCount = getActiveTurnCount(state);
+  }
+
+  // ── Nothing to dispatch? ─────────────────────────────────────────────
+  if (turnsToDispatch.length === 0) {
+    // selectRole returned null with no active turns — caller is done
+    emit({ type: 'caller_stopped', state });
+    return { terminal: true, ok: false, stop_reason: 'caller_stopped', history: [] };
+  }
 
+  // ── Build dispatch contexts ──────────────────────────────────────────
+  const contexts = [];
+  for (const { turn, state: turnState } of turnsToDispatch) {
+    const bundleResult = writeDispatchBundle(root, turnState, config, { turnId: turn.turn_id });
+    if (!bundleResult.ok) {
+      errors.push(`writeDispatchBundle(${turn.assigned_role}): ${bundleResult.error}`);
+      continue;
+    }
     const stagingPath = getTurnStagingResultPath(turn.turn_id);
-    const context = {
+    contexts.push({
       turn,
-      state: assignState,
+      state: turnState,
       bundlePath: bundleResult.bundlePath,
       stagingPath,
       config,
       root,
-    };
+    });
+  }
 
-    // ── Dispatch ────────────────────────────────────────────────────────
-    let dispatchResult;
-    try {
-      dispatchResult = await callbacks.dispatch(context);
-    } catch (err) {
-      errors.push(`dispatch threw for ${roleId}: ${err.message}`);
-      return makeResult(false, 'dispatch_error', loadState(root, config), turnsExecuted, turnHistory, gatesApproved, errors);
-    }
+  if (contexts.length === 0) {
+    errors.push('All dispatch bundles failed to write');
+    return { terminal: true, ok: false, stop_reason: 'blocked', history: [] };
+  }
+
+  // ── Dispatch concurrently ────────────────────────────────────────────
+  emit({ type: 'parallel_dispatch', count: contexts.length, turns: contexts.map(c => c.turn.turn_id) });
+
+  const dispatchResults = await Promise.allSettled(
+    contexts.map(async (ctx) => {
+      try {
+        return { ctx, result: await callbacks.dispatch(ctx) };
+      } catch (err) {
+        return { ctx, result: { accept: false, reason: `dispatch threw: ${err.message}` } };
+      }
+    })
+  );
+
+  // ── Process results sequentially (acceptance is lock-serialized) ─────
+  for (const settled of dispatchResults) {
+    const { ctx, result: dispatchResult } = settled.status === 'fulfilled'
+      ? settled.value
+      : { ctx: null, result: { accept: false, reason: `Promise rejected: ${settled.reason}` } };
+
+    if (!ctx) continue;
+
+    const { turn } = ctx;
+    const roleId = turn.assigned_role;
 
     if (dispatchResult.accept) {
-      // Stage the turn result
-      const absStaging = join(root, stagingPath);
+      const absStaging = join(root, ctx.stagingPath);
       mkdirSync(dirname(absStaging), { recursive: true });
       writeFileSync(absStaging, JSON.stringify(dispatchResult.turnResult, null, 2));
 
-      // Accept
-      const acceptResult = acceptTurn(root, config);
+      const acceptResult = acceptTurn(root, config, { turnId: turn.turn_id });
       if (!acceptResult.ok) {
         errors.push(`acceptTurn(${roleId}): ${acceptResult.error}`);
-        const postState = loadState(root, config);
-        return makeResult(false, 'blocked', postState, turnsExecuted, turnHistory, gatesApproved, errors);
+        // Record failure but try other turns
+        history.push({ role: roleId, turn_id: turn.turn_id, accepted: false, accept_error: acceptResult.error });
+        continue;
       }
 
-      turnsExecuted++;
-      turnHistory.push({ role: roleId, turn_id: turn.turn_id, accepted: true });
+      acceptedCount++;
+      history.push({ role: roleId, turn_id: turn.turn_id, accepted: true });
       emit({ type: 'turn_accepted', turn, role: roleId, state: acceptResult.state });
-
     } else {
-      // Rejection
       const validationResult = {
         stage: 'dispatch',
         errors: [dispatchResult.reason || 'Dispatch callback rejected the turn'],
       };
-      rejectTurn(root, config, validationResult, dispatchResult.reason || 'Dispatch rejection');
-      turnHistory.push({ role: roleId, turn_id: turn.turn_id, accepted: false });
+      rejectTurn(root, config, validationResult, dispatchResult.reason || 'Dispatch rejection', { turnId: turn.turn_id });
+      history.push({ role: roleId, turn_id: turn.turn_id, accepted: false });
       emit({ type: 'turn_rejected', turn, role: roleId, reason: dispatchResult.reason });
 
-      // Check if retries exhausted → run blocked
+      // Check if rejection blocked the run
       const postRejectState = loadState(root, config);
       if (postRejectState?.status === 'blocked') {
         errors.push(`Turn rejected for ${roleId}, retries exhausted`);
         emit({ type: 'blocked', state: postRejectState });
-        return makeResult(false, 'reject_exhausted', postRejectState, turnsExecuted, turnHistory, gatesApproved, errors);
+        return { terminal: true, ok: false, stop_reason: 'reject_exhausted', history, acceptedCount };
       }
-      // Otherwise continue — loop will detect the active turn and re-dispatch
     }
   }
+
+  // ── Stall detection: if no turns were accepted and no new roles were ──
+  // ── assignable, terminate to avoid infinite re-dispatch loops. ────────
+  if (acceptedCount === 0 && history.length > 0) {
+    const allFailed = history.every(h => !h.accepted);
+    if (allFailed) {
+      errors.push('All parallel turns failed acceptance — stalled');
+      return { terminal: true, ok: false, stop_reason: 'blocked', history, acceptedCount };
+    }
+  }
+
+  return { terminal: false, history, acceptedCount };
+}
+
+/**
+ * Dispatch a single turn and process its result.
+ */
+async function dispatchAndProcess(root, config, turn, assignState, callbacks, emit, errors) {
+  const roleId = turn.assigned_role;
+  const history = [];
+
+  const bundleResult = writeDispatchBundle(root, assignState, config);
+  if (!bundleResult.ok) {
+    errors.push(`writeDispatchBundle(${roleId}): ${bundleResult.error}`);
+    return { terminal: true, ok: false, stop_reason: 'blocked', history };
+  }
+
+  const stagingPath = getTurnStagingResultPath(turn.turn_id);
+  const context = {
+    turn,
+    state: assignState,
+    bundlePath: bundleResult.bundlePath,
+    stagingPath,
+    config,
+    root,
+  };
+
+  let dispatchResult;
+  try {
+    dispatchResult = await callbacks.dispatch(context);
+  } catch (err) {
+    errors.push(`dispatch threw for ${roleId}: ${err.message}`);
+    return { terminal: true, ok: false, stop_reason: 'dispatch_error', history };
+  }
+
+  if (dispatchResult.accept) {
+    const absStaging = join(root, stagingPath);
+    mkdirSync(dirname(absStaging), { recursive: true });
+    writeFileSync(absStaging, JSON.stringify(dispatchResult.turnResult, null, 2));
+
+    const acceptResult = acceptTurn(root, config);
+    if (!acceptResult.ok) {
+      errors.push(`acceptTurn(${roleId}): ${acceptResult.error}`);
+      return { terminal: true, ok: false, stop_reason: 'blocked', history };
+    }
+
+    history.push({ role: roleId, turn_id: turn.turn_id, accepted: true });
+    emit({ type: 'turn_accepted', turn, role: roleId, state: acceptResult.state });
+    return { terminal: false, accepted: true, history };
+  }
+
+  // Rejection
+  const validationResult = {
+    stage: 'dispatch',
+    errors: [dispatchResult.reason || 'Dispatch callback rejected the turn'],
+  };
+  rejectTurn(root, config, validationResult, dispatchResult.reason || 'Dispatch rejection');
+  history.push({ role: roleId, turn_id: turn.turn_id, accepted: false });
+  emit({ type: 'turn_rejected', turn, role: roleId, reason: dispatchResult.reason });
+
+  const postRejectState = loadState(root, config);
+  if (postRejectState?.status === 'blocked') {
+    errors.push(`Turn rejected for ${roleId}, retries exhausted`);
+    emit({ type: 'blocked', state: postRejectState });
+    return { terminal: true, ok: false, stop_reason: 'reject_exhausted', history };
+  }
+
+  return { terminal: false, accepted: false, history };
 }
 
 /**

package/src/lib/validation.js

@@ -9,6 +9,7 @@ import {
   validateAcceptanceHintCompletion,
   validateGovernedWorkflowKit,
 } from './governed-templates.js';
+import { collectRemoteReviewOnlyGateWarnings } from './normalized-config.js';
 
 const DEFAULT_REQUIRED_FILES = [
   '.planning/PROJECT.md',
@@ -115,6 +116,9 @@ export function validateGovernedProject(root, rawConfig, config, opts = {}) {
   errors.push(...workflowKit.errors);
   warnings.push(...workflowKit.warnings);
 
+  // Config-shape warnings (dead-end gates, etc.) — mirrors doctor/config --set surfaces
+  warnings.push(...collectRemoteReviewOnlyGateWarnings(rawConfig));
+
   const mustExist = [
     config.files?.state || '.agentxchain/state.json',
     config.files?.history || '.agentxchain/history.jsonl',