agentxchain 2.130.1 → 2.132.0

package/package.json

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

package/scripts/check-release-alignment.mjs

@@ -12,12 +12,13 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = join(__dirname, '..', '..');
 
 function usage() {
-  console.error('Usage: node cli/scripts/check-release-alignment.mjs [--target-version <semver>] [--scope prebump|current] [--json]');
+  console.error('Usage: node cli/scripts/check-release-alignment.mjs [--target-version <semver>] [--scope prebump|current] [--json|--report]');
 }
 
 let targetVersion = null;
 let scope = RELEASE_ALIGNMENT_SCOPES.CURRENT;
 let json = false;
+let report = false;
 
 for (let index = 2; index < process.argv.length; index += 1) {
   const arg = process.argv[index];
@@ -45,15 +46,40 @@ for (let index = 2; index < process.argv.length; index += 1) {
     json = true;
     continue;
   }
+  if (arg === '--report') {
+    report = true;
+    continue;
+  }
   console.error(`Error: unknown argument "${arg}"`);
   usage();
   process.exit(1);
 }
 
+if (json && report) {
+  console.error('Error: --json and --report are mutually exclusive');
+  usage();
+  process.exit(1);
+}
+
 const result = validateReleaseAlignment(REPO_ROOT, { targetVersion, scope });
 
 if (json) {
   console.log(JSON.stringify(result, null, 2));
+} else if (report) {
+  const readyCount = result.surfaceResults.filter((surface) => surface.ok).length;
+  const needsUpdateCount = result.surfaceResults.length - readyCount;
+  console.log(
+    `Release alignment report for ${result.targetVersion} (${result.scope}, ${result.checkedSurfaceCount} surfaces).`,
+  );
+  for (const surface of result.surfaceResults) {
+    console.log(`- [${surface.ok ? 'ready' : 'needs update'}] (${surface.surface_id}) ${surface.label}`);
+    for (const error of surface.errors) {
+      console.log(`  - ${error}`);
+    }
+  }
+  console.log(
+    `Summary: ${readyCount} ready, ${needsUpdateCount} need update.`,
+  );
 } else if (result.ok) {
   console.log(`Release alignment OK for ${result.targetVersion} (${result.scope}, ${result.checkedSurfaceCount} surfaces).`);
 } else {

package/scripts/release-bump.sh

@@ -82,6 +82,9 @@ ALLOWED_RELEASE_PATHS=(
   ".planning/MARKETING/REDDIT_POSTS.md"
   ".planning/MARKETING/HN_SUBMISSION.md"
   "website-v2/static/llms.txt"
+  "website-v2/docs/getting-started.mdx"
+  "website-v2/docs/quickstart.mdx"
+  "website-v2/docs/five-minute-tutorial.mdx"
   "cli/homebrew/agentxchain.rb"
   "cli/homebrew/README.md"
 )

package/scripts/release-preflight.sh

@@ -10,11 +10,13 @@ cd "$CLI_DIR"
 
 STRICT_MODE=0
 PUBLISH_GATE=0
+DRY_RUN=0
 TARGET_VERSION="2.0.0"
 
 usage() {
-  echo "Usage: bash scripts/release-preflight.sh [--strict] [--publish-gate] [--target-version <semver>]" >&2
+  echo "Usage: bash scripts/release-preflight.sh [--strict] [--publish-gate] [--dry-run] [--target-version <semver>]" >&2
   echo "  --publish-gate  Run only release-critical checks (no full test suite). Use in CI publish workflows." >&2
+  echo "  --dry-run       Preview manual release-alignment surfaces without running the full gate." >&2
 }
 
 while [[ $# -gt 0 ]]; do
@@ -28,6 +30,10 @@ while [[ $# -gt 0 ]]; do
       STRICT_MODE=1
       shift
       ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
     --target-version)
       if [[ -z "${2:-}" ]]; then
         echo "Error: --target-version requires a semver argument" >&2
@@ -49,6 +55,12 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+if [[ "$DRY_RUN" -eq 1 && "$STRICT_MODE" -eq 1 ]]; then
+  echo "Error: --dry-run cannot be combined with --strict or --publish-gate" >&2
+  usage
+  exit 1
+fi
+
 PASS=0
 FAIL=0
 WARN=0
@@ -84,6 +96,31 @@ else
 fi
 echo ""
 
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  echo "Release Preflight Preview"
+  echo "========================="
+  echo "Mode: DRY RUN (manual release-alignment surfaces only; no git/npm gate checks executed)"
+  echo ""
+  ALIGNMENT_SCRIPT="${SCRIPT_DIR}/check-release-alignment.mjs"
+  if [[ ! -f "$ALIGNMENT_SCRIPT" ]]; then
+    echo "Error: release alignment preview requires ${ALIGNMENT_SCRIPT}" >&2
+    exit 1
+  fi
+  if run_and_capture ALIGNMENT_REPORT node "$ALIGNMENT_SCRIPT" --scope prebump --target-version "$TARGET_VERSION" --report; then
+    ALIGNMENT_STATUS=0
+  else
+    ALIGNMENT_STATUS=$?
+  fi
+  printf '%s\n' "$ALIGNMENT_REPORT"
+  echo ""
+  if [[ "$ALIGNMENT_STATUS" -eq 0 ]]; then
+    echo "PREVIEW COMPLETE: manual release-alignment surfaces are ready for ${TARGET_VERSION}."
+  else
+    echo "PREVIEW COMPLETE: manual release-alignment surfaces still need updates before a real preflight/tag push."
+  fi
+  exit 0
+fi
+
 # 1. Clean working tree
 echo "[1/7] Git status"
 if git diff --quiet HEAD 2>/dev/null && [ -z "$(git ls-files --others --exclude-standard 2>/dev/null)" ]; then

package/src/commands/events.js

@@ -65,6 +65,9 @@ function printEvent(evt) {
   const conflictDetail = evt.event_type === 'turn_conflicted'
     ? ` — ${formatConflictDetail(evt)}`
     : '';
+  const conflictResolvedDetail = evt.event_type === 'conflict_resolved'
+    ? ` — ${formatConflictResolvedDetail(evt)}`
+    : '';
   const rejectionDetail = evt.event_type === 'turn_rejected' && evt.payload?.reason
     ? ` — ${evt.payload.reason}${evt.payload.failed_stage ? ` (${evt.payload.failed_stage})` : ''}`
     : '';
@@ -82,7 +85,10 @@ function printEvent(evt) {
     : evt.event_type === 'human_escalation_resolved' && evt.payload?.escalation_id
       ? ` ${evt.payload.escalation_id} via ${evt.payload.resolved_via || '?'}`
       : '';
-  console.log(`${chalk.dim(ts)}  ${type}  ${chalk.cyan(runId)}  ${phase}${turnInfo}${intentInfo}${conflictDetail}${rejectionDetail}${acceptanceFailedDetail}${phaseTransitionDetail}${gateFailedDetail}${humanEscalationDetail}`);
+  const coordinatorRetryDetail = evt.event_type === 'coordinator_retry' && evt.payload
+    ? ` — ws ${evt.payload.workstream_id || '?'} repo ${evt.payload.repo_id || '?'} (retry of ${evt.payload.failed_turn_id || '?'})`
+    : '';
+  console.log(`${chalk.dim(ts)}  ${type}  ${chalk.cyan(runId)}  ${phase}${turnInfo}${intentInfo}${conflictDetail}${conflictResolvedDetail}${rejectionDetail}${acceptanceFailedDetail}${phaseTransitionDetail}${gateFailedDetail}${humanEscalationDetail}${coordinatorRetryDetail}`);
 }
 
 function formatConflictDetail(evt) {
@@ -105,6 +111,16 @@ function formatConflictDetail(evt) {
   return parts.filter(Boolean).join(' | ');
 }
 
+function formatConflictResolvedDetail(evt) {
+  const payload = evt.payload || {};
+  const fileSummary = summarizeList(payload.conflicting_files, 3) || 'resolved conflict';
+  const resolvedVia = payload.resolution ? `via ${payload.resolution}` : null;
+  const overlapRatio = typeof payload.overlap_ratio === 'number'
+    ? `${Math.round(payload.overlap_ratio * 100)}% overlap`
+    : null;
+  return [fileSummary, resolvedVia, overlapRatio].filter(Boolean).join(' | ');
+}
+
 function summarizeList(items, limit) {
   if (!Array.isArray(items) || items.length === 0) return '';
   const shown = items.slice(0, limit).join(', ');
@@ -123,6 +139,7 @@ function colorEventType(type) {
     acceptance_failed: chalk.red.bold,
     turn_reissued: chalk.cyan,
     turn_conflicted: chalk.redBright,
+    conflict_resolved: chalk.greenBright,
     phase_entered: chalk.magenta,
     escalation_raised: chalk.red.bold,
     escalation_resolved: chalk.green,
@@ -132,6 +149,9 @@ function colorEventType(type) {
     gate_approved: chalk.green,
     gate_failed: chalk.red,
     budget_exceeded_warn: chalk.yellowBright,
+    coordinator_retry: chalk.cyan.bold,
+    turn_checkpointed: chalk.green,
+    dispatch_progress: chalk.blue.dim,
   };
   const colorFn = colors[type] || chalk.white;
   return colorFn(pad(type, 22));

package/src/commands/mission.js

@@ -22,6 +22,7 @@ import {
   getWorkstreamStatusSummary,
   launchCoordinatorWorkstream,
   launchWorkstream,
+  retryCoordinatorWorkstream,
   retryWorkstream,
   markWorkstreamOutcome,
   loadAllPlans,
@@ -541,11 +542,6 @@ export async function missionPlanLaunchCommand(planTarget, opts) {
   }
 
   if (mission.coordinator && plan.coordinator_scope) {
-    if (opts.retry) {
-      console.error(chalk.red('--retry is not supported for coordinator-bound mission plans yet.'));
-      process.exit(1);
-    }
-
     const coordinatorConfigResult = loadCoordinatorConfig(mission.coordinator.workspace_path);
     if (!coordinatorConfigResult.ok) {
       console.error(chalk.red('Coordinator config validation failed:'));
@@ -565,6 +561,113 @@ export async function missionPlanLaunchCommand(planTarget, opts) {
       process.exit(1);
     }
 
+    if (opts.retry) {
+      const retry = retryCoordinatorWorkstream(
+        root,
+        mission,
+        plan.plan_id,
+        opts.workstream,
+        coordinatorConfigResult.config,
+        {
+          reason: `mission plan retry ${opts.workstream}`,
+        },
+      );
+      if (!retry.ok) {
+        console.error(chalk.red(retry.error));
+        process.exit(1);
+      }
+
+      const executor = opts._executeGovernedRun || executeGovernedRun;
+      const repoContext = loadProjectContext(retry.retryResult.repo_path);
+      if (!repoContext) {
+        console.error(chalk.red(`Cannot load project context for retried repo at ${retry.retryResult.repo_path}.`));
+        process.exit(1);
+      }
+
+      const runOpts = {
+        autoApprove: !!opts.autoApprove,
+        provenance: {
+          trigger: 'manual',
+          created_by: 'operator',
+          trigger_reason: `mission:${mission.mission_id} workstream:${opts.workstream} coordinator-retry:${retry.retryResult.repo_id}`,
+        },
+      };
+
+      let execution;
+      try {
+        execution = await executor(repoContext, runOpts);
+      } catch (error) {
+        const syncedRetryFailure = synchronizeCoordinatorPlanState(root, mission, retry.plan);
+        console.error(chalk.red(`Coordinator retry execution failed: ${error.message}`));
+        if (opts.json) {
+          console.log(JSON.stringify({
+            dispatch_mode: 'coordinator',
+            retry: true,
+            mission_id: mission.mission_id,
+            plan_id: retry.plan.plan_id,
+            workstream_id: opts.workstream,
+            repo_id: retry.retryResult.repo_id,
+            retried_repo_turn_id: retry.retryResult.failed_turn_id,
+            repo_turn_id: retry.retryResult.reissued_turn_id,
+            workstream_status: syncedRetryFailure.ok
+              ? syncedRetryFailure.plan.workstreams.find((ws) => ws.workstream_id === opts.workstream)?.launch_status || 'needs_attention'
+              : 'needs_attention',
+            launch_record: retry.launchRecord,
+            error: error.message,
+          }, null, 2));
+        }
+        process.exit(1);
+      }
+
+      const syncedRetry = synchronizeCoordinatorPlanState(root, mission, retry.plan);
+      const retriedPlan = syncedRetry.ok ? syncedRetry.plan : retry.plan;
+      const retriedWorkstream = retriedPlan.workstreams.find((ws) => ws.workstream_id === opts.workstream);
+      const retriedLaunchRecord = retriedPlan.launch_records.find(
+        (record) => record.workstream_id === opts.workstream && record.dispatch_mode === 'coordinator',
+      ) || retry.launchRecord;
+
+      if (opts.json) {
+        console.log(JSON.stringify({
+          dispatch_mode: 'coordinator',
+          retry: true,
+          mission_id: mission.mission_id,
+          plan_id: retriedPlan.plan_id,
+          workstream_id: opts.workstream,
+          super_run_id: mission.coordinator.super_run_id,
+          repo_id: retry.retryResult.repo_id,
+          retried_repo_turn_id: retry.retryResult.failed_turn_id,
+          repo_turn_id: retry.retryResult.reissued_turn_id,
+          role: retry.retryResult.role,
+          bundle_path: retry.retryResult.bundle_path,
+          context_ref: retry.retryResult.context_ref,
+          workstream_status: retriedWorkstream?.launch_status || 'launched',
+          launch_record: retriedLaunchRecord,
+          exit_code: execution?.exitCode ?? 0,
+        }, null, 2));
+        if ((execution?.exitCode ?? 0) !== 0) {
+          process.exit(execution.exitCode);
+        }
+        return;
+      }
+
+      console.log(chalk.green(`Retried coordinator workstream ${chalk.bold(opts.workstream)} in ${chalk.bold(retry.retryResult.repo_id)}`));
+      console.log('');
+      console.log(chalk.dim(`  Mission:      ${mission.mission_id}`));
+      console.log(chalk.dim(`  Plan:         ${retriedPlan.plan_id}`));
+      console.log(chalk.dim(`  Super Run:    ${mission.coordinator.super_run_id}`));
+      console.log(chalk.dim(`  Repo:         ${retry.retryResult.repo_id}`));
+      console.log(chalk.dim(`  Old Turn:     ${retry.retryResult.failed_turn_id}`));
+      console.log(chalk.dim(`  New Turn:     ${retry.retryResult.reissued_turn_id}`));
+      console.log(chalk.dim(`  Workstream:   ${retriedWorkstream?.launch_status || 'launched'}`));
+      console.log('');
+      renderPlan(retriedPlan);
+      if ((execution?.exitCode ?? 0) !== 0) {
+        console.error(chalk.red(`Coordinator retry execution ended with exit code ${execution.exitCode}.`));
+        process.exit(execution.exitCode);
+      }
+      return;
+    }
+
     const assignment = selectAssignmentForWorkstream(
       mission.coordinator.workspace_path,
       coordinatorState,

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

@@ -85,6 +85,17 @@ function buildPlanSummary(plan) {
       completed_at: lr.completed_at || null,
       status: lr.status,
       terminal_reason: lr.terminal_reason || null,
+      dispatch_mode: lr.dispatch_mode || null,
+      ...(lr.dispatch_mode === 'coordinator' && Array.isArray(lr.repo_dispatches) ? {
+        repo_dispatches: lr.repo_dispatches.map((rd) => ({
+          repo_id: rd.repo_id,
+          repo_turn_id: rd.repo_turn_id,
+          role: rd.role,
+          dispatched_at: rd.dispatched_at,
+          ...(rd.is_retry ? { is_retry: true, retry_of: rd.retry_of } : {}),
+          ...(rd.retried_at ? { retried_at: rd.retried_at, retry_reason: rd.retry_reason } : {}),
+        })),
+      } : {}),
     })),
   };
 }

package/src/lib/governed-state.js

@@ -1088,15 +1088,63 @@ function cleanupTurnArtifacts(root, turnId) {
   } catch { /* best-effort */ }
 }
 
-function detectAcceptanceConflict(targetTurn, conflictFiles, historyEntries) {
+function getWorkflowArtifactOwners(config, filePath) {
+  const owners = new Set();
+  const phases = config?.workflow_kit?.phases;
+  if (!phases || typeof phases !== 'object') {
+    return owners;
+  }
+
+  for (const phaseConfig of Object.values(phases)) {
+    const artifacts = Array.isArray(phaseConfig?.artifacts) ? phaseConfig.artifacts : [];
+    for (const artifact of artifacts) {
+      if (artifact?.path !== filePath) {
+        continue;
+      }
+      if (typeof artifact.owned_by === 'string' && artifact.owned_by.length > 0) {
+        owners.add(artifact.owned_by);
+      }
+    }
+  }
+
+  return owners;
+}
+
+function isForwardRevisionFile(targetTurn, historyEntry, filePath, config) {
+  if (!targetTurn || !historyEntry) {
+    return false;
+  }
+  if (historyEntry.role !== targetTurn.assigned_role) {
+    return false;
+  }
+
+  const explicitOwners = getWorkflowArtifactOwners(config, filePath);
+  if (explicitOwners.size > 0) {
+    return explicitOwners.size === 1 && explicitOwners.has(targetTurn.assigned_role);
+  }
+
+  if (!filePath.startsWith('.planning/')) {
+    return false;
+  }
+
+  return config?.routing?.planning?.entry_role === targetTurn.assigned_role;
+}
+
+function classifyAcceptanceOverlap(targetTurn, conflictFiles, historyEntries, config) {
   const observedFiles = [...new Set(Array.isArray(conflictFiles) ? conflictFiles : [])];
   if (observedFiles.length === 0) {
-    return null;
+    return {
+      conflict: null,
+      forward_revision_files: [],
+      forward_revision_turns: [],
+    };
   }
 
   const observedFileSet = new Set(observedFiles);
   const acceptedSince = [];
   const conflictingFiles = new Set();
+  const forwardRevisionFiles = new Set();
+  const forwardRevisionTurns = new Map();
 
   for (const entry of historyEntries) {
     if ((entry.accepted_sequence || 0) <= (targetTurn.assigned_sequence || 0)) {
@@ -1108,35 +1156,77 @@ function detectAcceptanceConflict(targetTurn, conflictFiles, historyEntries) {
       continue;
     }
 
-    overlap.forEach(file => conflictingFiles.add(file));
-    acceptedSince.push({
-      turn_id: entry.turn_id,
-      role: entry.role,
-      accepted_sequence: entry.accepted_sequence,
-      files_changed: overlap,
-    });
+    const destructiveFiles = [];
+    const forwardFiles = [];
+    for (const file of overlap) {
+      if (isForwardRevisionFile(targetTurn, entry, file, config)) {
+        forwardFiles.push(file);
+      } else {
+        destructiveFiles.push(file);
+      }
+    }
+
+    if (destructiveFiles.length > 0) {
+      destructiveFiles.forEach(file => conflictingFiles.add(file));
+      acceptedSince.push({
+        turn_id: entry.turn_id,
+        role: entry.role,
+        accepted_sequence: entry.accepted_sequence,
+        files_changed: destructiveFiles,
+      });
+    }
+
+    if (forwardFiles.length > 0) {
+      forwardFiles.forEach(file => forwardRevisionFiles.add(file));
+      const existing = forwardRevisionTurns.get(entry.turn_id) || {
+        turn_id: entry.turn_id,
+        role: entry.role,
+        accepted_sequence: entry.accepted_sequence,
+        files_changed: [],
+      };
+      existing.files_changed = [...new Set([...existing.files_changed, ...forwardFiles])];
+      forwardRevisionTurns.set(entry.turn_id, existing);
+    }
   }
 
+  const forwardRevisionContext = {
+    files: [...forwardRevisionFiles],
+    accepted_since_turn_ids: [...forwardRevisionTurns.values()].map((entry) => entry.turn_id),
+    accepted_since: [...forwardRevisionTurns.values()],
+  };
+
   if (acceptedSince.length === 0) {
-    return null;
+    return {
+      conflict: null,
+      forward_revision_files: forwardRevisionContext.files,
+      forward_revision_turns: forwardRevisionContext.accepted_since,
+    };
   }
 
   const conflicting = [...conflictingFiles];
   const overlapRatio = observedFiles.length > 0 ? conflicting.length / observedFiles.length : 0;
 
   return {
-    type: 'file_conflict',
-    conflicting_turn: {
-      turn_id: targetTurn.turn_id,
-      role: targetTurn.assigned_role,
-      attempt: targetTurn.attempt,
-      files_changed: observedFiles,
+    conflict: {
+      type: 'file_conflict',
+      conflicting_turn: {
+        turn_id: targetTurn.turn_id,
+        role: targetTurn.assigned_role,
+        attempt: targetTurn.attempt,
+        files_changed: observedFiles,
+      },
+      accepted_since: acceptedSince,
+      conflicting_files: conflicting,
+      non_conflicting_files: observedFiles.filter(
+        (file) => !conflictingFiles.has(file) && !forwardRevisionFiles.has(file),
+      ),
+      forward_revision_files: forwardRevisionContext.files,
+      forward_revision_turns: forwardRevisionContext.accepted_since,
+      overlap_ratio: overlapRatio,
+      suggested_resolution: overlapRatio < 0.5 ? 'reject_and_reassign' : 'human_merge',
     },
-    accepted_since: acceptedSince,
-    conflicting_files: conflicting,
-    non_conflicting_files: observedFiles.filter(file => !conflictingFiles.has(file)),
-    overlap_ratio: overlapRatio,
-    suggested_resolution: overlapRatio < 0.5 ? 'reject_and_reassign' : 'human_merge',
+    forward_revision_files: forwardRevisionContext.files,
+    forward_revision_turns: forwardRevisionContext.accepted_since,
   };
 }
 
@@ -2749,40 +2839,6 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         error_code: 'protocol_error',
       };
     }
-
-    if (currentTurn.conflict_state.status !== 'human_merging') {
-      appendJsonl(root, LEDGER_PATH, {
-        timestamp: new Date().toISOString(),
-        decision: 'conflict_resolution_selected',
-        turn_id: currentTurn.turn_id,
-        attempt: currentTurn.attempt,
-        role: currentTurn.assigned_role,
-        phase: state.phase,
-        conflict: {
-          conflicting_files: currentTurn.conflict_state.conflict_error?.conflicting_files || [],
-          accepted_since_turn_ids: (currentTurn.conflict_state.conflict_error?.accepted_since || []).map((entry) => entry.turn_id),
-          overlap_ratio: currentTurn.conflict_state.conflict_error?.overlap_ratio ?? 0,
-        },
-        resolution_chosen: 'human_merge',
-      });
-
-      state = {
-        ...state,
-        active_turns: {
-          ...getActiveTurns(state),
-          [currentTurn.turn_id]: {
-            ...currentTurn,
-            status: 'conflicted',
-            conflict_state: {
-              ...currentTurn.conflict_state,
-              status: 'human_merging',
-            },
-          },
-        },
-      };
-      writeState(root, state);
-      currentTurn = state.active_turns[currentTurn.turn_id];
-    }
   }
 
   const turnStagingPath = getTurnStagingResultPath(currentTurn.turn_id);
@@ -3142,11 +3198,29 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     };
   }
 
-  const conflict = detectAcceptanceConflict(
+  const overlapClassification = classifyAcceptanceOverlap(
     currentTurn,
     buildConflictCandidateFiles(rawObservation, observation, turnResult.files_changed || []),
     historyEntries,
+    config,
   );
+  const forwardRevision = overlapClassification.forward_revision_files.length > 0
+    ? {
+        files: overlapClassification.forward_revision_files,
+        accepted_since_turn_ids: overlapClassification.forward_revision_turns.map((entry) => entry.turn_id),
+        accepted_since: overlapClassification.forward_revision_turns,
+      }
+    : null;
+  const conflict = resolutionMode === 'human_merge' ? null : overlapClassification.conflict;
+  const conflictResolution = resolutionMode === 'human_merge'
+    ? {
+        mode: 'human_merge',
+        merge_strategy: 'operator_authoritative_staged_result',
+        conflicting_files: currentTurn.conflict_state?.conflict_error?.conflicting_files || [],
+        accepted_since_turn_ids: (currentTurn.conflict_state?.conflict_error?.accepted_since || []).map((entry) => entry.turn_id),
+        overlap_ratio: currentTurn.conflict_state?.conflict_error?.overlap_ratio ?? 0,
+      }
+    : null;
 
   if (conflict) {
     const detectionCount = (currentTurn.conflict_state?.detection_count || 0) + 1;
@@ -3301,6 +3375,8 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     assigned_sequence: Number.isInteger(currentTurn.assigned_sequence) ? currentTurn.assigned_sequence : acceptedSequence,
     accepted_sequence: acceptedSequence,
     concurrent_with: Array.isArray(currentTurn.concurrent_with) ? currentTurn.concurrent_with : [],
+    ...(forwardRevision ? { forward_revision: forwardRevision } : {}),
+    ...(conflictResolution ? { conflict_resolution: conflictResolution } : {}),
     cost: turnResult.cost || {},
     ...(currentTurn.started_at ? { started_at: currentTurn.started_at } : {}),
     accepted_at: now,
@@ -3357,6 +3433,49 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       });
     }
   }
+  if (forwardRevision) {
+    ledgerEntries.push({
+      timestamp: now,
+      decision: 'forward_revision_accepted',
+      turn_id: currentTurn.turn_id,
+      attempt: currentTurn.attempt,
+      role: currentTurn.assigned_role,
+      phase: state.phase,
+      forward_revision: {
+        files: forwardRevision.files,
+        accepted_since_turn_ids: forwardRevision.accepted_since_turn_ids,
+      },
+    });
+  }
+  if (conflictResolution) {
+    const conflictSummary = {
+      conflicting_files: conflictResolution.conflicting_files,
+      accepted_since_turn_ids: conflictResolution.accepted_since_turn_ids,
+      overlap_ratio: conflictResolution.overlap_ratio,
+    };
+    ledgerEntries.push({
+      timestamp: now,
+      decision: 'conflict_resolution_selected',
+      turn_id: currentTurn.turn_id,
+      attempt: currentTurn.attempt,
+      role: currentTurn.assigned_role,
+      phase: state.phase,
+      conflict: conflictSummary,
+      resolution_chosen: conflictResolution.mode,
+      merge_strategy: conflictResolution.merge_strategy,
+    });
+    ledgerEntries.push({
+      timestamp: now,
+      decision: 'conflict_resolved',
+      turn_id: currentTurn.turn_id,
+      attempt: currentTurn.attempt,
+      role: currentTurn.assigned_role,
+      phase: state.phase,
+      conflict: conflictSummary,
+      resolution_chosen: conflictResolution.mode,
+      merge_strategy: conflictResolution.merge_strategy,
+    });
+  }
 
   const turnNumber = turnResult.turn_id.replace(/^turn_/, '').slice(0, 8);
   const talkSection = `## Turn ${turnNumber} — ${turnResult.role} (${state.phase})\n\n- **Status:** ${turnResult.status}\n- **Summary:** ${turnResult.summary}\n${turnResult.decisions?.length ? turnResult.decisions.map(d => `- **Decision ${d.id}:** ${d.statement}`).join('\n') + '\n' : ''}${turnResult.objections?.length ? turnResult.objections.map(o => `- **Objection ${o.id} (${o.severity}):** ${o.statement}`).join('\n') + '\n' : ''}- **Proposed next:** ${turnResult.proposed_next_role || 'human'}\n\n---\n`;
@@ -4107,6 +4226,22 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     intent_id: currentTurn.intake_context?.intent_id || null,
     payload: turnAcceptedPayload,
   });
+  if (conflictResolution) {
+    emitRunEvent(root, 'conflict_resolved', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      intent_id: currentTurn.intake_context?.intent_id || null,
+      payload: {
+        resolution: conflictResolution.mode,
+        merge_strategy: conflictResolution.merge_strategy,
+        conflicting_files: conflictResolution.conflicting_files,
+        accepted_since_turn_ids: conflictResolution.accepted_since_turn_ids,
+        overlap_ratio: conflictResolution.overlap_ratio,
+      },
+    });
+  }
 
   if (updatedState.status === 'blocked') {
     // DEC-RHTR-SPEC: Record blocked outcome in cross-run history (non-fatal)

package/src/lib/mission-plans.js

@@ -6,11 +6,15 @@
  * Plans are NOT protocol-normative.
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
 import { randomUUID } from 'crypto';
 import { join } from 'path';
 import { loadChainReport } from './chain-reports.js';
-import { readBarriers, readCoordinatorHistory } from './coordinator-state.js';
+import { writeDispatchBundle } from './dispatch-bundle.js';
+import { loadProjectContext, loadProjectState } from './config.js';
+import { reissueTurn } from './governed-state.js';
+import { emitRunEvent } from './run-events.js';
+import { readBarriers, readCoordinatorHistory, recordCoordinatorDecision } from './coordinator-state.js';
 import { loadCoordinatorConfig } from './coordinator-config.js';
 
 // ── Plan artifact directory ──────────────────────────────────────────────────
@@ -486,6 +490,7 @@ function isAcceptedRepoHistoryEntry(entry) {
 }
 
 const REPO_FAILURE_STATUSES = new Set(['failed_acceptance', 'failed', 'rejected', 'retrying', 'conflicted']);
+const RETRYABLE_COORDINATOR_FAILURE_STATUSES = new Set(['failed', 'failed_acceptance']);
 
 function getLatestRepoDispatches(launchRecord) {
   const latestByRepo = new Map();
@@ -554,6 +559,76 @@ function buildCoordinatorRepoFailures(coordinatorConfig, launchRecord) {
   return failures;
 }
 
+function appendCoordinatorHistoryEntry(workspacePath, entry) {
+  const historyPath = join(workspacePath, '.agentxchain', 'multirepo', 'history.jsonl');
+  mkdirSync(join(workspacePath, '.agentxchain', 'multirepo'), { recursive: true });
+  appendFileSync(historyPath, `${JSON.stringify(entry)}\n`);
+}
+
+function findDependentDispatchAfter(plan, workstreamId, timestamp) {
+  const since = new Date(timestamp || 0).getTime();
+  if (Number.isNaN(since)) return null;
+
+  for (const candidate of plan.workstreams || []) {
+    if (!Array.isArray(candidate.depends_on) || !candidate.depends_on.includes(workstreamId)) {
+      continue;
+    }
+
+    for (const record of plan.launch_records || []) {
+      if (record?.workstream_id !== candidate.workstream_id) {
+        continue;
+      }
+
+      if (record.dispatch_mode === 'coordinator') {
+        for (const dispatch of record.repo_dispatches || []) {
+          const dispatchedAt = new Date(dispatch?.dispatched_at || 0).getTime();
+          if (!Number.isNaN(dispatchedAt) && dispatchedAt > since) {
+            return {
+              workstream_id: candidate.workstream_id,
+              repo_id: dispatch.repo_id || null,
+              dispatched_at: dispatch.dispatched_at || null,
+            };
+          }
+        }
+        continue;
+      }
+
+      const launchedAt = new Date(record.launched_at || 0).getTime();
+      if (!Number.isNaN(launchedAt) && launchedAt > since) {
+        return {
+          workstream_id: candidate.workstream_id,
+          repo_id: null,
+          dispatched_at: record.launched_at || null,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+function loadRepoTurnForRetry(repoPath, repoTurnId) {
+  const context = loadProjectContext(repoPath);
+  if (!context) {
+    return { ok: false, error: `Repo at "${repoPath}" is not a loadable governed project.` };
+  }
+
+  const state = loadProjectState(context.root, context.config);
+  if (!state) {
+    return { ok: false, error: `Repo at "${repoPath}" has no governed state.` };
+  }
+
+  const activeTurn = state.active_turns?.[repoTurnId] || null;
+  if (!activeTurn) {
+    return {
+      ok: false,
+      error: `Repo turn "${repoTurnId}" is no longer active. Use repo-local recovery instead of coordinator --retry.`,
+    };
+  }
+
+  return { ok: true, root: context.root, config: context.config, state, activeTurn };
+}
+
 function buildCoordinatorWorkstreamProgress(coordinatorConfig, history, barriers, workstreamId) {
   const coordinatorWorkstream = coordinatorConfig?.workstreams?.[workstreamId];
   if (!coordinatorWorkstream) {
@@ -904,6 +979,188 @@ export function launchCoordinatorWorkstream(root, mission, planId, workstreamId,
   return { ok: true, plan: synced.ok ? synced.plan : plan, workstream: ws, launchRecord };
 }
 
+export function retryCoordinatorWorkstream(root, mission, planId, workstreamId, coordinatorConfig, options = {}) {
+  const plan = loadPlan(root, mission.mission_id, planId);
+  if (!plan) {
+    return { ok: false, error: `Plan not found: ${planId}` };
+  }
+  if (!mission?.coordinator?.workspace_path || !mission?.coordinator?.super_run_id) {
+    return { ok: false, error: 'Mission is not bound to a coordinator run.' };
+  }
+
+  const synced = synchronizeCoordinatorPlanState(root, mission, plan);
+  const workingPlan = synced.ok ? synced.plan : plan;
+  const ws = workingPlan.workstreams.find((candidate) => candidate.workstream_id === workstreamId);
+  if (!ws) {
+    return { ok: false, error: `Workstream not found: ${workstreamId}` };
+  }
+  if (ws.launch_status !== 'needs_attention') {
+    return {
+      ok: false,
+      error: `Workstream ${workstreamId} is not in needs_attention state. Nothing to retry.`,
+    };
+  }
+
+  const launchRecord = getLatestCoordinatorLaunchRecord(workingPlan, workstreamId);
+  if (!launchRecord) {
+    return { ok: false, error: `No coordinator launch record found for workstream ${workstreamId}.` };
+  }
+
+  const latestDispatchesByRepo = new Map(
+    getLatestRepoDispatches(launchRecord).map((dispatch) => [dispatch.repo_id, dispatch]),
+  );
+  const repoFailures = buildCoordinatorRepoFailures(coordinatorConfig, launchRecord);
+  launchRecord.repo_failures = repoFailures;
+
+  if (repoFailures.length === 0) {
+    return { ok: false, error: `Workstream ${workstreamId} has no retryable repo failures.` };
+  }
+
+  const retryableFailures = [];
+  const blockedFailures = [];
+
+  for (const failure of repoFailures) {
+    if (!RETRYABLE_COORDINATOR_FAILURE_STATUSES.has(failure.failure_status)) {
+      blockedFailures.push(`${failure.repo_id} (${failure.failure_status})`);
+      continue;
+    }
+    retryableFailures.push(failure);
+  }
+
+  if (retryableFailures.length === 0) {
+    return {
+      ok: false,
+      error: `No retryable repo failures in workstream ${workstreamId}. Manual intervention required: ${blockedFailures.join(', ')}`,
+    };
+  }
+
+  if (retryableFailures.length > 1) {
+    return {
+      ok: false,
+      error: `Workstream ${workstreamId} has multiple retryable repo failures. Recover them repo-locally one at a time before relaunching the coordinator workstream.`,
+    };
+  }
+
+  const failure = retryableFailures[0];
+  const failedDispatch = latestDispatchesByRepo.get(failure.repo_id);
+  if (!failedDispatch) {
+    return { ok: false, error: `Missing launch metadata for failed repo ${failure.repo_id}.` };
+  }
+
+  const downstreamBlocker = findDependentDispatchAfter(workingPlan, workstreamId, failedDispatch.dispatched_at);
+  if (downstreamBlocker) {
+    return {
+      ok: false,
+      error: `Cannot retry workstream ${workstreamId}: dependent workstream "${downstreamBlocker.workstream_id}" has already dispatched since the failed repo turn.`,
+    };
+  }
+
+  const repoPath = coordinatorConfig?.repos?.[failure.repo_id]?.resolved_path;
+  if (!repoPath) {
+    return { ok: false, error: `Coordinator config has no resolved_path for repo "${failure.repo_id}".` };
+  }
+
+  const repoTurn = loadRepoTurnForRetry(repoPath, failure.repo_turn_id);
+  if (!repoTurn.ok) {
+    return repoTurn;
+  }
+
+  const reason = options.reason || `coordinator retry: ${workstreamId}/${failure.repo_id}`;
+  const reissued = reissueTurn(repoTurn.root, repoTurn.config, {
+    turnId: failure.repo_turn_id,
+    reason,
+  });
+  if (!reissued.ok) {
+    return { ok: false, error: reissued.error };
+  }
+
+  const bundleResult = writeDispatchBundle(repoTurn.root, reissued.state, repoTurn.config, {
+    turnId: reissued.newTurn.turn_id,
+  });
+  if (!bundleResult.ok) {
+    return { ok: false, error: `Turn reissued but dispatch bundle failed: ${bundleResult.error}` };
+  }
+
+  const now = new Date().toISOString();
+  failedDispatch.retried_at = now;
+  failedDispatch.retry_reason = failure.failure_status;
+  launchRecord.repo_dispatches.push({
+    repo_id: failure.repo_id,
+    repo_turn_id: reissued.newTurn.turn_id,
+    role: reissued.newTurn.assigned_role,
+    dispatched_at: now,
+    bundle_path: bundleResult.bundlePath,
+    context_ref: failedDispatch.context_ref || null,
+    is_retry: true,
+    retry_of: failure.repo_turn_id,
+  });
+  launchRecord.status = 'launched';
+  launchRecord.repo_failures = [];
+  ws.launch_status = 'launched';
+
+  const otherNeedsAttention = (workingPlan.workstreams || []).some(
+    (candidate) => candidate.workstream_id !== workstreamId && candidate.launch_status === 'needs_attention',
+  );
+  workingPlan.status = otherNeedsAttention ? 'needs_attention' : 'approved';
+  workingPlan.updated_at = now;
+  writePlanArtifact(root, mission.mission_id, workingPlan);
+
+  appendCoordinatorHistoryEntry(mission.coordinator.workspace_path, {
+    type: 'coordinator_retry',
+    timestamp: now,
+    super_run_id: mission.coordinator.super_run_id,
+    workstream_id: workstreamId,
+    repo_id: failure.repo_id,
+    failed_turn_id: failure.repo_turn_id,
+    reissued_turn_id: reissued.newTurn.turn_id,
+    retry_reason: failure.failure_status,
+  });
+  recordCoordinatorDecision(mission.coordinator.workspace_path, {
+    super_run_id: mission.coordinator.super_run_id,
+    phase: coordinatorConfig?.workstreams?.[workstreamId]?.phase || null,
+  }, {
+    category: 'retry',
+    statement: `Retried ${failure.repo_id} for workstream ${workstreamId}`,
+    repo_id: failure.repo_id,
+    repo_turn_id: reissued.newTurn.turn_id,
+    workstream_id: workstreamId,
+    reason: failure.failure_status,
+    context_ref: failedDispatch.context_ref || null,
+  });
+  emitRunEvent(mission.coordinator.workspace_path, 'coordinator_retry', {
+    run_id: mission.coordinator.super_run_id,
+    phase: coordinatorConfig?.workstreams?.[workstreamId]?.phase || null,
+    status: 'active',
+    turn: { turn_id: reissued.newTurn.turn_id, role_id: reissued.newTurn.assigned_role },
+    payload: {
+      workstream_id: workstreamId,
+      repo_id: failure.repo_id,
+      failed_turn_id: failure.repo_turn_id,
+      reissued_turn_id: reissued.newTurn.turn_id,
+      retry_reason: failure.failure_status,
+      retry_count: launchRecord.repo_dispatches.filter((dispatch) => dispatch.repo_id === failure.repo_id && dispatch.is_retry).length,
+    },
+  });
+
+  const afterRetry = synchronizeCoordinatorPlanState(root, mission, workingPlan);
+  return {
+    ok: true,
+    plan: afterRetry.ok ? afterRetry.plan : workingPlan,
+    workstream: ws,
+    launchRecord,
+    retryResult: {
+      repo_id: failure.repo_id,
+      failed_turn_id: failure.repo_turn_id,
+      reissued_turn_id: reissued.newTurn.turn_id,
+      role: reissued.newTurn.assigned_role,
+      repo_path: repoTurn.root,
+      bundle_path: bundleResult.bundlePath,
+      context_ref: failedDispatch.context_ref || null,
+      retry_reason: failure.failure_status,
+    },
+  };
+}
+
 /**
  * Record the outcome of a launched workstream after its chain completes.
  *

package/src/lib/recent-event-summary.js

@@ -36,6 +36,21 @@ function describeEvent(eventType, entry) {
     case 'gate_approved':
     case 'gate_failed':
       return `${prefix}${eventType}${gateId ? ` (${gateId})` : ''}`;
+    case 'turn_conflicted':
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
+    case 'conflict_resolved': {
+      const resolution = trimToNull(entry.payload?.resolution);
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}${resolution ? ` via ${resolution}` : ''}`;
+    }
+    case 'coordinator_retry': {
+      const wsId = trimToNull(entry.payload?.workstream_id);
+      const retryRepo = trimToNull(entry.payload?.repo_id);
+      return `${prefix}${eventType}${wsId ? ` ${wsId}` : ''}${retryRepo ? ` (${retryRepo})` : ''}`;
+    }
+    case 'turn_checkpointed':
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
+    case 'dispatch_progress':
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
     case 'run_blocked':
     case 'run_completed':
     case 'run_started':

package/src/lib/release-alignment.js

@@ -22,6 +22,12 @@ export function formatCount(value) {
   return new Intl.NumberFormat('en-US').format(value);
 }
 
+const ONBOARDING_PREREQ_DOCS = [
+  'website-v2/docs/getting-started.mdx',
+  'website-v2/docs/quickstart.mdx',
+  'website-v2/docs/five-minute-tutorial.mdx',
+];
+
 function normalizeEvidenceText(value) {
   return value
     .replace(/^\s*-\s*/, '')
@@ -137,6 +143,28 @@ function validateTextIncludesVersionAndEvidence(relativePath, label) {
   };
 }
 
+function validateOnboardingPrereqs(ctx, repoRoot) {
+  const errors = [];
+  const requiredTokens = [
+    `Minimum CLI version: \`agentxchain ${ctx.targetVersion}\` or newer`,
+    'agentxchain --version',
+    'npm install -g agentxchain@latest',
+    'brew upgrade agentxchain',
+    'npx --yes -p agentxchain@latest -c "agentxchain <command>"',
+  ];
+
+  for (const relativePath of ONBOARDING_PREREQ_DOCS) {
+    const content = read(repoRoot, relativePath);
+    for (const token of requiredTokens) {
+      if (!content.includes(token)) {
+        errors.push(`${relativePath} must include: ${token}`);
+      }
+    }
+  }
+
+  return errors;
+}
+
 export const RELEASE_ALIGNMENT_SURFACES = [
   {
     id: 'changelog',
@@ -274,6 +302,12 @@ export const RELEASE_ALIGNMENT_SURFACES = [
         : [`website-v2/static/llms.txt must list ${ctx.releaseRoute}`];
     },
   },
+  {
+    id: 'onboarding_prereqs',
+    label: 'onboarding docs CLI-version prerequisites',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check: validateOnboardingPrereqs,
+  },
   {
     id: 'homebrew_formula_url',
     label: 'homebrew mirror formula url',
@@ -311,9 +345,23 @@ export function validateReleaseAlignment(repoRoot, { targetVersion, scope = RELE
   const context = getReleaseAlignmentContext(repoRoot, { targetVersion });
   const surfaces = RELEASE_ALIGNMENT_SURFACES.filter((surface) => surface.scopes.includes(scope));
   const errors = [];
+  const surfaceResults = [];
 
   for (const surface of surfaces) {
-    const surfaceErrors = surface.check(context, repoRoot) || [];
+    let surfaceErrors = [];
+    try {
+      surfaceErrors = surface.check(context, repoRoot) || [];
+    } catch (error) {
+      surfaceErrors = [
+        error instanceof Error ? error.message : String(error),
+      ];
+    }
+    surfaceResults.push({
+      surface_id: surface.id,
+      label: surface.label,
+      ok: surfaceErrors.length === 0,
+      errors: surfaceErrors,
+    });
     for (const error of surfaceErrors) {
       errors.push({
         surface_id: surface.id,
@@ -331,6 +379,12 @@ export function validateReleaseAlignment(repoRoot, { targetVersion, scope = RELE
     aggregateEvidenceLine: context.aggregateEvidenceLine,
     checkedSurfaceCount: surfaces.length,
     checkedSurfaceIds: surfaces.map((surface) => surface.id),
+    checkedSurfaces: surfaces.map((surface) => ({
+      id: surface.id,
+      label: surface.label,
+      scopes: [...surface.scopes],
+    })),
+    surfaceResults,
     errors,
   };
 }

package/src/lib/run-events.js

@@ -18,9 +18,11 @@ export const VALID_RUN_EVENTS = [
   'turn_accepted',
   'turn_rejected',
   'turn_conflicted',
+  'conflict_resolved',
   'acceptance_failed',
   'turn_reissued',
   'turn_checkpointed',
+  'coordinator_retry',
   'run_blocked',
   'run_completed',
   'escalation_raised',