agentxchain 2.128.0 → 2.130.0

package/src/commands/mission.js

@@ -4,6 +4,7 @@ import { resolve } from 'path';
 import { findProjectRoot, loadProjectContext } from '../lib/config.js';
 import {
   attachChainToMission,
+  bindCoordinatorToMission,
   buildMissionListSummary,
   buildMissionSnapshot,
   createMission,
@@ -12,11 +13,14 @@ import {
   loadMissionArtifact,
   loadMissionSnapshot,
 } from '../lib/missions.js';
+import { loadCoordinatorConfig } from '../lib/coordinator-config.js';
+import { initializeCoordinatorRun } from '../lib/coordinator-state.js';
 import {
   approvePlanArtifact,
   createPlanArtifact,
   getReadyWorkstreams,
   getWorkstreamStatusSummary,
+  launchCoordinatorWorkstream,
   launchWorkstream,
   retryWorkstream,
   markWorkstreamOutcome,
@@ -25,10 +29,13 @@ import {
   loadPlan,
   buildPlannerPrompt,
   parsePlannerResponse,
+  synchronizeCoordinatorPlanState,
   validatePlannerOutput,
 } from '../lib/mission-plans.js';
 import { executeChainedRun } from '../lib/run-chain.js';
 import { executeGovernedRun } from './run.js';
+import { dispatchCoordinatorTurn, selectAssignmentForWorkstream } from '../lib/coordinator-dispatch.js';
+import { loadCoordinatorState } from '../lib/coordinator-state.js';
 
 export async function missionStartCommand(opts) {
   const root = findProjectRoot(opts.dir || process.cwd());
@@ -48,6 +55,22 @@ export async function missionStartCommand(opts) {
     process.exit(1);
   }
 
+  // Multi-repo: validate coordinator config before creating mission (fail-fast)
+  let coordinatorConfig = null;
+  let coordinatorWorkspacePath = null;
+  if (opts.multi) {
+    coordinatorWorkspacePath = resolve(opts.coordinatorWorkspace || opts.coordinatorConfig || root);
+    coordinatorConfig = loadCoordinatorConfig(coordinatorWorkspacePath);
+    if (!coordinatorConfig.ok) {
+      console.error(chalk.red('Coordinator config validation failed:'));
+      console.error(chalk.dim(`  Expected agentxchain-multi.json at: ${coordinatorWorkspacePath}`));
+      for (const err of coordinatorConfig.errors || []) {
+        console.error(chalk.red(`  ${err}`));
+      }
+      process.exit(1);
+    }
+  }
+
   const result = createMission(root, {
     missionId: opts.id,
     title,
@@ -58,6 +81,37 @@ export async function missionStartCommand(opts) {
     process.exit(1);
   }
 
+  // Multi-repo: initialize coordinator and bind to mission
+  if (opts.multi && coordinatorConfig) {
+    const initResult = initializeCoordinatorRun(coordinatorWorkspacePath, coordinatorConfig.config);
+    if (!initResult.ok) {
+      // Atomic rollback: delete the mission artifact
+      const { getMissionsDir } = await import('../lib/missions.js');
+      const { unlinkSync, existsSync: fileExists } = await import('fs');
+      const { join: joinPath } = await import('path');
+      const missionFile = joinPath(getMissionsDir(root), `${result.mission.mission_id}.json`);
+      if (fileExists(missionFile)) {
+        try { unlinkSync(missionFile); } catch { /* best effort */ }
+      }
+      console.error(chalk.red('Coordinator initialization failed:'));
+      for (const err of initResult.errors || []) {
+        console.error(chalk.red(`  ${err}`));
+      }
+      process.exit(1);
+    }
+
+    const bindResult = bindCoordinatorToMission(root, result.mission.mission_id, {
+      super_run_id: initResult.super_run_id,
+      config_path: opts.coordinatorConfig || null,
+      workspace_path: coordinatorWorkspacePath,
+    });
+    if (!bindResult.ok) {
+      console.error(chalk.yellow(`Mission created but coordinator binding failed: ${bindResult.error}`));
+    } else {
+      result.mission = bindResult.mission;
+    }
+  }
+
   const snapshot = buildMissionSnapshot(root, result.mission);
   if (opts.plan) {
     try {
@@ -275,7 +329,7 @@ export async function missionPlanShowCommand(planTarget, opts) {
   }
 
   // Resolve plan target
-  const plan = planTarget && planTarget !== 'latest'
+  let plan = planTarget && planTarget !== 'latest'
     ? loadPlan(root, mission.mission_id, planTarget)
     : loadLatestPlan(root, mission.mission_id);
 
@@ -289,6 +343,15 @@ export async function missionPlanShowCommand(planTarget, opts) {
     return;
   }
 
+  if (mission.coordinator && plan.coordinator_scope) {
+    const synced = synchronizeCoordinatorPlanState(root, mission, plan);
+    if (!synced.ok) {
+      console.error(chalk.red(synced.error));
+      process.exit(1);
+    }
+    plan = synced.plan;
+  }
+
   if (opts.json) {
     console.log(JSON.stringify(plan, null, 2));
     return;
@@ -454,7 +517,7 @@ export async function missionPlanLaunchCommand(planTarget, opts) {
     process.exit(1);
   }
 
-  const plan = planTarget && planTarget !== 'latest'
+  let plan = planTarget && planTarget !== 'latest'
     ? loadPlan(root, mission.mission_id, planTarget)
     : loadLatestPlan(root, mission.mission_id);
 
@@ -468,6 +531,113 @@ export async function missionPlanLaunchCommand(planTarget, opts) {
     process.exit(1);
   }
 
+  if (mission.coordinator && plan.coordinator_scope) {
+    const synced = synchronizeCoordinatorPlanState(root, mission, plan);
+    if (!synced.ok) {
+      console.error(chalk.red(synced.error));
+      process.exit(1);
+    }
+    plan = synced.plan;
+  }
+
+  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:'));
+      for (const err of coordinatorConfigResult.errors || []) {
+        console.error(chalk.red(`  ${err}`));
+      }
+      process.exit(1);
+    }
+
+    const coordinatorState = loadCoordinatorState(mission.coordinator.workspace_path);
+    if (!coordinatorState) {
+      console.error(chalk.red(`Coordinator state not found at ${mission.coordinator.workspace_path}.`));
+      process.exit(1);
+    }
+    if (coordinatorState.status !== 'active') {
+      console.error(chalk.red(`Coordinator run ${coordinatorState.super_run_id} is not active (status: "${coordinatorState.status}").`));
+      process.exit(1);
+    }
+
+    const assignment = selectAssignmentForWorkstream(
+      mission.coordinator.workspace_path,
+      coordinatorState,
+      coordinatorConfigResult.config,
+      opts.workstream,
+    );
+    if (!assignment.ok) {
+      console.error(chalk.red(`Coordinator launch blocked: ${assignment.detail || assignment.reason}`));
+      process.exit(1);
+    }
+
+    const dispatch = dispatchCoordinatorTurn(
+      mission.coordinator.workspace_path,
+      coordinatorState,
+      coordinatorConfigResult.config,
+      assignment,
+    );
+    if (!dispatch.ok) {
+      console.error(chalk.red(`Coordinator dispatch failed: ${dispatch.error}`));
+      process.exit(1);
+    }
+
+    const launch = launchCoordinatorWorkstream(
+      root,
+      mission,
+      plan.plan_id,
+      opts.workstream,
+      {
+        ...dispatch,
+        role: assignment.role,
+      },
+      coordinatorConfigResult.config,
+    );
+    if (!launch.ok) {
+      console.error(chalk.red(launch.error));
+      process.exit(1);
+    }
+
+    const syncedWorkstream = launch.plan.workstreams.find((ws) => ws.workstream_id === opts.workstream);
+    const jsonPayload = {
+      dispatch_mode: 'coordinator',
+      mission_id: mission.mission_id,
+      plan_id: launch.plan.plan_id,
+      workstream_id: opts.workstream,
+      super_run_id: mission.coordinator.super_run_id,
+      repo_id: dispatch.repo_id,
+      repo_turn_id: dispatch.turn_id,
+      role: assignment.role,
+      bundle_path: dispatch.bundle_path,
+      context_ref: dispatch.context_ref || null,
+      workstream_status: syncedWorkstream?.launch_status || 'launched',
+      launch_record: launch.launchRecord,
+    };
+
+    if (opts.json) {
+      console.log(JSON.stringify(jsonPayload, null, 2));
+      return;
+    }
+
+    console.log(chalk.green(`Dispatched coordinator workstream ${chalk.bold(opts.workstream)} to ${chalk.bold(dispatch.repo_id)}`));
+    console.log('');
+    console.log(chalk.dim(`  Mission:      ${mission.mission_id}`));
+    console.log(chalk.dim(`  Plan:         ${launch.plan.plan_id}`));
+    console.log(chalk.dim(`  Super Run:    ${mission.coordinator.super_run_id}`));
+    console.log(chalk.dim(`  Repo:         ${dispatch.repo_id}`));
+    console.log(chalk.dim(`  Repo Turn:    ${dispatch.turn_id}`));
+    console.log(chalk.dim(`  Role:         ${assignment.role}`));
+    console.log(chalk.dim(`  Workstream:   ${syncedWorkstream?.launch_status || 'launched'}`));
+    console.log('');
+    renderPlan(launch.plan);
+    return;
+  }
+
   const launch = opts.retry
     ? retryWorkstream(root, mission.mission_id, plan.plan_id, opts.workstream)
     : launchWorkstream(root, mission.mission_id, plan.plan_id, opts.workstream);
@@ -566,6 +736,10 @@ async function missionPlanLaunchAllReady(planTarget, opts, context) {
     process.exit(1);
   }
 
+  if (mission.coordinator) {
+    return coordinatorLaunchAllReady(planTarget, opts, context, mission);
+  }
+
   const plan = planTarget && planTarget !== 'latest'
     ? loadPlan(root, mission.mission_id, planTarget)
     : loadLatestPlan(root, mission.mission_id);
@@ -760,6 +934,10 @@ export async function missionPlanAutopilotCommand(planTarget, opts) {
     process.exit(1);
   }
 
+  if (mission.coordinator) {
+    return coordinatorAutopilot(planTarget, opts, context, mission);
+  }
+
   const plan = planTarget && planTarget !== 'latest'
     ? loadPlan(root, mission.mission_id, planTarget)
     : loadLatestPlan(root, mission.mission_id);
@@ -1067,6 +1245,509 @@ function deriveAutopilotIdleOutcome(plan, continueOnFailure) {
   return 'no_ready_workstreams';
 }
 
+function getCoordinatorWaveWorkstreams(plan) {
+  if (!plan || !Array.isArray(plan.workstreams)) {
+    return [];
+  }
+
+  return plan.workstreams.filter((ws) => {
+    if (ws.launch_status === 'ready') {
+      return true;
+    }
+
+    if (ws.launch_status !== 'launched') {
+      return false;
+    }
+
+    const progress = ws.coordinator_progress;
+    if (!progress || !Array.isArray(progress.pending_repo_ids) || progress.pending_repo_ids.length === 0) {
+      return false;
+    }
+
+    if ((progress.repo_failure_count || 0) > 0) {
+      return false;
+    }
+
+    return true;
+  });
+}
+
+// ── Coordinator wave execution ──────────────────────────────────────────────
+
+/**
+ * Dispatch a single coordinator workstream, execute the repo-local turn,
+ * and synchronize plan state. Returns { ok, status, repo_id, turn_id, error }.
+ */
+async function dispatchAndExecuteCoordinatorWorkstream(
+  root, mission, plan, workstreamId, coordinatorConfig, coordinatorState, opts,
+) {
+  const executor = opts._executeGovernedRun || executeGovernedRun;
+  const logger = opts._log || console.log;
+
+  // 1. Select assignment
+  const assignment = selectAssignmentForWorkstream(
+    mission.coordinator.workspace_path,
+    coordinatorState,
+    coordinatorConfig,
+    workstreamId,
+  );
+  if (!assignment.ok) {
+    return { ok: false, status: 'assignment_blocked', error: assignment.detail || assignment.reason };
+  }
+
+  // 2. Dispatch coordinator turn (writes bundle, does not execute)
+  const dispatch = dispatchCoordinatorTurn(
+    mission.coordinator.workspace_path,
+    coordinatorState,
+    coordinatorConfig,
+    assignment,
+  );
+  if (!dispatch.ok) {
+    return { ok: false, status: 'dispatch_error', error: dispatch.error };
+  }
+
+  // 3. Record launch in plan
+  const launch = launchCoordinatorWorkstream(
+    root,
+    mission,
+    plan.plan_id,
+    workstreamId,
+    { ...dispatch, role: assignment.role },
+    coordinatorConfig,
+  );
+  if (!launch.ok) {
+    return { ok: false, status: 'launch_record_error', error: launch.error };
+  }
+
+  // 4. Execute the repo-local turn in the target repo
+  const repoPath = coordinatorConfig.repos?.[dispatch.repo_id]?.resolved_path;
+  if (!repoPath) {
+    return { ok: false, status: 'repo_path_error', error: `No resolved_path for repo "${dispatch.repo_id}"` };
+  }
+
+  const repoContext = loadProjectContext(repoPath);
+  if (!repoContext) {
+    return { ok: false, status: 'repo_context_error', error: `Cannot load project context for repo "${dispatch.repo_id}" at "${repoPath}"` };
+  }
+
+  const runOpts = {
+    autoApprove: !!opts.autoApprove,
+    log: logger,
+    provenance: {
+      trigger: opts.trigger || 'manual',
+      created_by: 'operator',
+      trigger_reason: `mission:${mission.mission_id} workstream:${workstreamId} coordinator:${mission.coordinator.super_run_id} repo:${dispatch.repo_id}`,
+    },
+  };
+
+  let execution;
+  try {
+    execution = await executor(repoContext, runOpts);
+  } catch (error) {
+    return {
+      ok: false,
+      status: 'needs_attention',
+      repo_id: dispatch.repo_id,
+      turn_id: dispatch.turn_id,
+      error: error.message,
+    };
+  }
+
+  // 5. Sync plan state from coordinator (updates barriers, accepted repos, failures)
+  const synced = synchronizeCoordinatorPlanState(root, mission, launch.plan);
+
+  const exitCode = execution?.exitCode || 0;
+  const wsStatus = exitCode === 0 ? 'dispatched' : 'needs_attention';
+
+  return {
+    ok: true,
+    status: wsStatus,
+    repo_id: dispatch.repo_id,
+    turn_id: dispatch.turn_id,
+    exit_code: exitCode,
+    plan: synced.ok ? synced.plan : launch.plan,
+  };
+}
+
+/**
+ * Load coordinator config and state for a mission. Returns { ok, config, state, error }.
+ */
+function loadCoordinatorForMission(mission) {
+  const coordinatorConfigResult = loadCoordinatorConfig(mission.coordinator.workspace_path);
+  if (!coordinatorConfigResult.ok) {
+    return { ok: false, error: `Coordinator config validation failed: ${(coordinatorConfigResult.errors || []).join(', ')}` };
+  }
+
+  const coordinatorState = loadCoordinatorState(mission.coordinator.workspace_path);
+  if (!coordinatorState) {
+    return { ok: false, error: `Coordinator state not found at ${mission.coordinator.workspace_path}` };
+  }
+  if (coordinatorState.status !== 'active') {
+    return { ok: false, error: `Coordinator run ${coordinatorState.super_run_id} is not active (status: "${coordinatorState.status}")` };
+  }
+
+  return { ok: true, config: coordinatorConfigResult.config, state: coordinatorState };
+}
+
+/**
+ * Coordinator-aware --all-ready: dispatches all ready workstreams sequentially,
+ * executing each repo-local turn and syncing barrier state between dispatches.
+ */
+async function coordinatorLaunchAllReady(planTarget, opts, context, mission) {
+  const { root } = context;
+
+  let plan = planTarget && planTarget !== 'latest'
+    ? loadPlan(root, mission.mission_id, planTarget)
+    : loadLatestPlan(root, mission.mission_id);
+
+  if (!plan) {
+    console.error(chalk.red('No plan found.'));
+    process.exit(1);
+  }
+
+  // Sync plan state first
+  const synced = synchronizeCoordinatorPlanState(root, mission, plan);
+  if (synced.ok) plan = synced.plan;
+
+  if (plan.status !== 'approved') {
+    console.error(chalk.red(`Plan ${plan.plan_id} is not approved (status: "${plan.status}").`));
+    process.exit(1);
+  }
+
+  const coord = loadCoordinatorForMission(mission);
+  if (!coord.ok) {
+    console.error(chalk.red(coord.error));
+    process.exit(1);
+  }
+
+  const readyWorkstreams = getReadyWorkstreams(plan);
+  if (readyWorkstreams.length === 0) {
+    const summary = getWorkstreamStatusSummary(plan);
+    const parts = Object.entries(summary).map(([status, count]) => `${count} ${status}`);
+    console.error(chalk.red(`No ready workstreams. Distribution: ${parts.join(', ')}.`));
+    process.exit(1);
+  }
+
+  if (!opts.json) {
+    console.log(chalk.bold(`Coordinator --all-ready: launching ${readyWorkstreams.length} workstream(s) from plan ${plan.plan_id}...\n`));
+  }
+
+  const results = [];
+  let hadFailure = false;
+
+  for (let i = 0; i < readyWorkstreams.length; i++) {
+    const ws = readyWorkstreams[i];
+    const prefix = `[${i + 1}/${readyWorkstreams.length}]`;
+
+    if (hadFailure) {
+      results.push({ workstream_id: ws.workstream_id, status: 'skipped', skip_reason: 'prior workstream failed' });
+      if (!opts.json) {
+        console.log(`${prefix} ${chalk.dim(ws.workstream_id)} — ${chalk.dim('skipped (prior workstream failed)')}`);
+      }
+      continue;
+    }
+
+    if (!opts.json) {
+      process.stdout.write(`${prefix} ${chalk.cyan(ws.workstream_id)} ... `);
+    }
+
+    const result = await dispatchAndExecuteCoordinatorWorkstream(
+      root, mission, plan, ws.workstream_id, coord.config, coord.state, { ...opts, trigger: 'manual' },
+    );
+
+    if (!result.ok) {
+      hadFailure = true;
+      results.push({ workstream_id: ws.workstream_id, status: 'needs_attention', error: result.error });
+      if (!opts.json) {
+        console.log(chalk.red(`needs_attention ✗ (${result.error})`));
+      }
+      continue;
+    }
+
+    // Update plan reference for subsequent dispatches
+    if (result.plan) plan = result.plan;
+
+    const wsStatus = result.status === 'needs_attention' ? 'needs_attention' : 'dispatched';
+    if (wsStatus === 'needs_attention') hadFailure = true;
+
+    results.push({
+      workstream_id: ws.workstream_id,
+      status: wsStatus,
+      repo_id: result.repo_id,
+      turn_id: result.turn_id,
+      exit_code: result.exit_code,
+    });
+
+    if (!opts.json) {
+      if (wsStatus === 'needs_attention') {
+        console.log(chalk.red('needs_attention ✗'));
+      } else {
+        console.log(chalk.green(`→ ${result.repo_id} ✓`));
+      }
+    }
+  }
+
+  // Summary
+  const dispatched = results.filter((r) => r.status === 'dispatched').length;
+  const failed = results.filter((r) => r.status === 'needs_attention').length;
+  const skipped = results.filter((r) => r.status === 'skipped').length;
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      plan_id: plan.plan_id,
+      mission_id: mission.mission_id,
+      dispatch_mode: 'coordinator',
+      results,
+      summary: { total: results.length, dispatched, failed, skipped },
+    }, null, 2));
+  } else {
+    console.log('');
+    console.log(chalk.bold(`Summary: ${dispatched} dispatched, ${failed} failed, ${skipped} skipped`));
+    if (hadFailure) {
+      console.log(chalk.dim('  Inspect plan state with `agentxchain mission plan show latest`'));
+    }
+  }
+
+  if (hadFailure) process.exit(1);
+}
+
+/**
+ * Coordinator-aware autopilot: wave-based unattended execution for coordinator-bound missions.
+ * Each wave dispatches all ready workstreams, executes repo-local turns, and syncs barrier state.
+ */
+async function coordinatorAutopilot(planTarget, opts, context, mission) {
+  const { root } = context;
+
+  let plan = planTarget && planTarget !== 'latest'
+    ? loadPlan(root, mission.mission_id, planTarget)
+    : loadLatestPlan(root, mission.mission_id);
+
+  if (!plan) {
+    console.error(chalk.red('No plan found.'));
+    process.exit(1);
+  }
+
+  const continueOnFailure = !!opts.continueOnFailure;
+
+  // Sync plan state
+  const initialSync = synchronizeCoordinatorPlanState(root, mission, plan);
+  if (initialSync.ok) plan = initialSync.plan;
+
+  if (plan.status === 'completed') {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        plan_id: plan.plan_id,
+        mission_id: mission.mission_id,
+        dispatch_mode: 'coordinator',
+        waves: [],
+        summary: { total_waves: 0, total_launched: 0, completed: 0, failed: 0, terminal_reason: 'plan_completed' },
+      }, null, 2));
+    } else {
+      console.log(chalk.green(`Plan ${plan.plan_id} is already completed. Nothing to do.`));
+    }
+    return;
+  }
+
+  if (plan.status !== 'approved' && !(plan.status === 'needs_attention' && continueOnFailure)) {
+    console.error(chalk.red(`Plan ${plan.plan_id} status is "${plan.status}". Autopilot requires an approved plan${continueOnFailure ? ' (or needs_attention with --continue-on-failure)' : ''}.`));
+    process.exit(1);
+  }
+
+  const coord = loadCoordinatorForMission(mission);
+  if (!coord.ok) {
+    console.error(chalk.red(coord.error));
+    process.exit(1);
+  }
+
+  const maxWaves = Math.max(1, parseInt(opts.maxWaves, 10) || 10);
+  const cooldownSeconds = Math.max(0, parseInt(opts.cooldown, 10) || 5);
+  const sleep = opts._sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+
+  const waves = [];
+  let totalLaunched = 0;
+  let totalCompleted = 0;
+  let totalFailed = 0;
+  let terminalReason = null;
+  let interrupted = false;
+
+  const onSigint = () => { interrupted = true; };
+  process.on('SIGINT', onSigint);
+
+  try {
+    for (let waveNum = 1; waveNum <= maxWaves; waveNum++) {
+      if (interrupted) {
+        terminalReason = 'interrupted';
+        break;
+      }
+
+      // Re-sync plan from disk + coordinator state
+      const currentPlan = loadPlan(root, mission.mission_id, plan.plan_id);
+      if (!currentPlan) {
+        terminalReason = 'plan_read_error';
+        break;
+      }
+      const coordSync = synchronizeCoordinatorPlanState(root, mission, currentPlan);
+      plan = coordSync.ok ? coordSync.plan : currentPlan;
+
+      if (plan.status === 'completed') {
+        terminalReason = 'plan_completed';
+        break;
+      }
+
+      const readyWorkstreams = getCoordinatorWaveWorkstreams(plan);
+      if (readyWorkstreams.length === 0) {
+        terminalReason = deriveAutopilotIdleOutcome(plan, continueOnFailure);
+        break;
+      }
+
+      if (!opts.json) {
+        console.log(chalk.bold(`\n━━━ Wave ${waveNum} — coordinator: ${readyWorkstreams.length} workstream(s) ━━━\n`));
+      }
+
+      const waveResults = [];
+      let waveHadFailure = false;
+
+      for (let i = 0; i < readyWorkstreams.length; i++) {
+        if (interrupted) break;
+
+        const ws = readyWorkstreams[i];
+        const prefix = `[${i + 1}/${readyWorkstreams.length}]`;
+
+        if (waveHadFailure && !continueOnFailure) {
+          waveResults.push({ workstream_id: ws.workstream_id, status: 'skipped', skip_reason: 'prior workstream failed' });
+          if (!opts.json) {
+            console.log(`${prefix} ${chalk.dim(ws.workstream_id)} — ${chalk.dim('skipped (prior workstream failed)')}`);
+          }
+          continue;
+        }
+
+        if (!opts.json) {
+          process.stdout.write(`${prefix} ${chalk.cyan(ws.workstream_id)} ... `);
+        }
+
+        const result = await dispatchAndExecuteCoordinatorWorkstream(
+          root, mission, plan, ws.workstream_id, coord.config, coord.state, { ...opts, trigger: 'autopilot' },
+        );
+
+        if (!result.ok) {
+          waveHadFailure = true;
+          totalFailed++;
+          waveResults.push({ workstream_id: ws.workstream_id, status: 'needs_attention', error: result.error });
+          if (!opts.json) {
+            console.log(chalk.red(`needs_attention ✗ (${result.error})`));
+          }
+          continue;
+        }
+
+        if (result.plan) plan = result.plan;
+        totalLaunched++;
+
+        if (result.status === 'needs_attention') {
+          waveHadFailure = true;
+          totalFailed++;
+          waveResults.push({ workstream_id: ws.workstream_id, status: 'needs_attention', repo_id: result.repo_id, turn_id: result.turn_id });
+          if (!opts.json) {
+            console.log(chalk.red(`→ ${result.repo_id} needs_attention ✗`));
+          }
+        } else {
+          totalCompleted++;
+          waveResults.push({ workstream_id: ws.workstream_id, status: 'dispatched', repo_id: result.repo_id, turn_id: result.turn_id });
+          if (!opts.json) {
+            console.log(chalk.green(`→ ${result.repo_id} ✓`));
+          }
+        }
+      }
+
+      waves.push({ wave: waveNum, results: waveResults });
+
+      if (interrupted) {
+        terminalReason = 'interrupted';
+        break;
+      }
+
+      // Re-sync and check plan completion
+      const afterSync = synchronizeCoordinatorPlanState(root, mission, plan);
+      if (afterSync.ok) plan = afterSync.plan;
+
+      if (plan.status === 'completed') {
+        terminalReason = 'plan_completed';
+        break;
+      }
+
+      if (waveHadFailure && !continueOnFailure) {
+        terminalReason = 'failure_stopped';
+        break;
+      }
+
+      if (waveNum === maxWaves) {
+        terminalReason = 'wave_limit_reached';
+        break;
+      }
+
+      // Cooldown between waves
+      if (cooldownSeconds > 0 && !interrupted) {
+        if (!opts.json) {
+          console.log(chalk.dim(`\nCooldown: ${cooldownSeconds}s before next wave...\n`));
+        }
+        await sleep(cooldownSeconds * 1000);
+      }
+    }
+  } finally {
+    process.removeListener('SIGINT', onSigint);
+  }
+
+  if (!terminalReason) {
+    terminalReason = totalFailed > 0
+      ? (continueOnFailure ? 'plan_incomplete' : 'failure_stopped')
+      : 'plan_completed';
+  }
+
+  const jsonOutput = {
+    plan_id: plan.plan_id,
+    mission_id: mission.mission_id,
+    dispatch_mode: 'coordinator',
+    waves,
+    summary: {
+      total_waves: waves.length,
+      total_launched: totalLaunched,
+      completed: totalCompleted,
+      failed: totalFailed,
+      terminal_reason: terminalReason,
+    },
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(jsonOutput, null, 2));
+  } else {
+    console.log('');
+    console.log(chalk.bold('━━━ Coordinator Autopilot Summary ━━━'));
+    console.log(`  Waves:      ${waves.length}`);
+    console.log(`  Launched:   ${totalLaunched}`);
+    console.log(`  Completed:  ${totalCompleted}`);
+    console.log(`  Failed:     ${totalFailed}`);
+    console.log(`  Outcome:    ${formatTerminalReason(terminalReason)}`);
+    if (terminalReason === 'plan_completed') {
+      console.log(chalk.green('\n  Plan completed successfully.'));
+    } else if (terminalReason === 'deadlock') {
+      console.log(chalk.red('\n  Deadlock: remaining workstreams are blocked with unsatisfiable dependencies.'));
+      console.log(chalk.dim('  Inspect with `agentxchain mission plan show latest`.'));
+    } else if (terminalReason === 'wave_limit_reached') {
+      console.log(chalk.yellow(`\n  Wave limit reached. Run autopilot again to continue.`));
+    } else if (terminalReason === 'failure_stopped') {
+      console.log(chalk.red('\n  Stopped due to workstream failure.'));
+      console.log(chalk.dim('  Use --continue-on-failure to skip failures, or resolve the issue and rerun autopilot.'));
+    } else if (terminalReason === 'plan_incomplete') {
+      console.log(chalk.yellow('\n  Autopilot exhausted all launchable work, but failed workstreams still need attention.'));
+    } else if (terminalReason === 'interrupted') {
+      console.log(chalk.yellow('\n  Interrupted by operator.'));
+    }
+  }
+
+  if (terminalReason !== 'plan_completed') {
+    process.exit(1);
+  }
+}
+
 // ── Plan rendering ───────────────────────────────────────────────────────────
 
 function renderPlan(plan) {
@@ -1085,6 +1766,10 @@ function renderPlan(plan) {
     console.log(`  Approved:     ${plan.approved_at}`);
   }
   console.log(`  Created:      ${plan.created_at || '—'}`);
+  if (plan.coordinator_scope) {
+    const cs = plan.coordinator_scope;
+    console.log(`  Coordinator:  ${chalk.cyan('bound')} (${(cs.repo_ids || []).length} repos, phases: ${(cs.phases || []).join(', ')})`);
+  }
   console.log('');
 
   if (!plan.workstreams || plan.workstreams.length === 0) {
@@ -1127,9 +1812,17 @@ function renderPlan(plan) {
     console.log(chalk.bold('  Launch records:'));
     for (const rec of plan.launch_records) {
       const statusTag = rec.status === 'completed' ? chalk.green('completed')
-        : rec.status === 'failed' ? chalk.red('failed')
+        : (rec.status === 'failed' || rec.status === 'needs_attention') ? chalk.red('needs_attention')
         : chalk.cyan('launched');
-      console.log(`    ${chalk.cyan(rec.workstream_id)} → ${rec.chain_id} [${statusTag}]`);
+      if (rec.dispatch_mode === 'coordinator') {
+        const dispatchCount = rec.repo_dispatches?.length || 0;
+        const progress = rec.coordinator_progress;
+        const accepted = progress ? `${progress.accepted_repo_count}/${progress.repo_count}` : '—';
+        const failures = rec.repo_failures?.length || progress?.repo_failure_count || 0;
+        console.log(`    ${chalk.cyan(rec.workstream_id)} → coordinator ${rec.super_run_id || '—'} [${statusTag}] dispatches=${dispatchCount} accepted=${accepted} failed=${failures}`);
+      } else {
+        console.log(`    ${chalk.cyan(rec.workstream_id)} → ${rec.chain_id} [${statusTag}]`);
+      }
     }
   }
 
@@ -1212,11 +1905,22 @@ async function callPlannerLLM(config, systemPrompt, userPrompt) {
 
 async function createMissionPlan(root, mission, opts = {}) {
   const { constraints, roleHints } = normalizePlannerOptions(opts);
-  const plannerOutput = await resolvePlannerOutput(root, mission, constraints, roleHints, opts);
+
+  // Load coordinator config when mission is coordinator-bound
+  let coordinatorConfig = null;
+  if (mission.coordinator && mission.coordinator.workspace_path) {
+    const coordResult = loadCoordinatorConfig(mission.coordinator.workspace_path);
+    if (coordResult.ok) {
+      coordinatorConfig = coordResult.config;
+    }
+  }
+
+  const plannerOutput = await resolvePlannerOutput(root, mission, constraints, roleHints, opts, coordinatorConfig);
   const result = createPlanArtifact(root, mission, {
     constraints,
     roleHints,
     plannerOutput,
+    coordinatorConfig,
   });
 
   if (!result.ok) {
@@ -1235,8 +1939,8 @@ function normalizePlannerOptions(opts = {}) {
   };
 }
 
-async function resolvePlannerOutput(root, mission, constraints, roleHints, opts = {}) {
-  const { systemPrompt, userPrompt } = buildPlannerPrompt(mission, constraints, roleHints);
+async function resolvePlannerOutput(root, mission, constraints, roleHints, opts = {}, coordinatorConfig = null) {
+  const { systemPrompt, userPrompt } = buildPlannerPrompt(mission, constraints, roleHints, coordinatorConfig);
 
   if (opts._plannerOutput) {
     return opts._plannerOutput;
@@ -1288,6 +1992,54 @@ function renderMissionPlanError(error) {
   }
 }
 
+// ── Mission Bind-Coordinator Command ───────────────────────────────────────
+
+export async function missionBindCoordinatorCommand(missionId, opts) {
+  const root = findProjectRoot(opts.dir || process.cwd());
+  if (!root) {
+    console.error(chalk.red('No AgentXchain project found. Run this inside a governed project.'));
+    process.exit(1);
+  }
+
+  const superRunId = String(opts.superRunId || '').trim();
+  const configPath = String(opts.coordinatorConfig || '').trim();
+  if (!superRunId) {
+    console.error(chalk.red('--super-run-id is required.'));
+    process.exit(1);
+  }
+
+  const mission = missionId
+    ? loadMissionArtifact(root, missionId)
+    : loadLatestMissionArtifact(root);
+  if (!mission) {
+    console.error(chalk.red(missionId ? `Mission not found: ${missionId}` : 'No mission found.'));
+    process.exit(1);
+  }
+
+  const workspacePath = resolve(opts.coordinatorWorkspace || root);
+  const result = bindCoordinatorToMission(root, mission.mission_id, {
+    super_run_id: superRunId,
+    config_path: configPath || null,
+    workspace_path: workspacePath,
+  });
+
+  if (!result.ok) {
+    console.error(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  const snapshot = buildMissionSnapshot(root, result.mission);
+  if (opts.json) {
+    console.log(JSON.stringify(snapshot, null, 2));
+    return;
+  }
+
+  console.log(chalk.green(`Bound coordinator ${superRunId} to ${snapshot.mission_id}`));
+  renderMissionSnapshot(snapshot);
+}
+
+// ── Rendering ──────────────────────────────────────────────────────────────
+
 function renderMissionSnapshot(snapshot) {
   const latestPlan = snapshot.latest_plan || null;
 
@@ -1309,6 +2061,36 @@ function renderMissionSnapshot(snapshot) {
     console.log(`  Missing chains:        ${snapshot.missing_chain_ids.join(', ')}`);
   }
 
+  // Coordinator (multi-repo) section
+  if (snapshot.coordinator_status) {
+    const cs = snapshot.coordinator_status;
+    console.log('');
+    console.log(chalk.bold('  Coordinator (multi-repo):'));
+    if (cs.unreachable) {
+      console.log(`    Super Run:           ${cs.super_run_id || '—'}`);
+      console.log(`    Status:              ${chalk.red('unreachable')}`);
+    } else {
+      console.log(`    Super Run:           ${cs.super_run_id || '—'}`);
+      console.log(`    Status:              ${formatCoordinatorStatus(cs.status)}`);
+      console.log(`    Phase:               ${cs.phase || '—'}`);
+      if (cs.repo_runs && Object.keys(cs.repo_runs).length > 0) {
+        console.log('    Repos:');
+        for (const [repoId, repo] of Object.entries(cs.repo_runs)) {
+          console.log(`      ${pad(repoId, 16)} ${pad(repo.status || '—', 14)} ${pad(repo.phase || '—', 18)} ${repo.run_id || '—'}`);
+        }
+      }
+      if (cs.pending_barriers && cs.pending_barriers.length > 0) {
+        console.log('    Barriers:');
+        for (const barrier of cs.pending_barriers) {
+          console.log(`      ${pad(barrier.id, 28)} ${pad(barrier.type || '—', 24)} ${barrier.status || '—'}`);
+        }
+      }
+      if (cs.blocked_reason) {
+        console.log(`    Blocked:             ${chalk.yellow(cs.blocked_reason)}`);
+      }
+    }
+  }
+
   if (latestPlan) {
     console.log('');
     console.log(chalk.bold('  Latest plan:'));
@@ -1374,6 +2156,20 @@ function formatMissionStatus(status) {
   }
 }
 
+function formatCoordinatorStatus(status) {
+  if (!status) return '—';
+  switch (status) {
+    case 'active':
+      return chalk.green('active');
+    case 'blocked':
+      return chalk.red('blocked');
+    case 'completed':
+      return chalk.cyan('completed');
+    default:
+      return status;
+  }
+}
+
 function formatTimestamp(value) {
   if (!value) return '—';
   try {