agentxchain 2.104.0 → 2.105.0

package/src/lib/coordinator-next-actions.js

@@ -0,0 +1,128 @@
+import { buildCoordinatorRepoStatusEntries } from './coordinator-repo-status-presentation.js';
+
+function collectCoordinatorRunIdMismatches(repoStatusEntries) {
+  return repoStatusEntries
+    .filter((entry) => entry?.run_id_mismatch)
+    .map((entry) => entry.run_id_mismatch);
+}
+
+function collectCoordinatorStatusDrift(repoStatusEntries) {
+  return repoStatusEntries
+    .filter((entry) => entry?.status_drift)
+    .map((entry) => entry.status_drift);
+}
+
+export function detectCoordinatorRunIdMismatches(repos, coordinatorRepoRuns) {
+  return collectCoordinatorRunIdMismatches(
+    buildCoordinatorRepoStatusEntries({
+      coordinatorRepoRuns,
+      repoSnapshots: repos,
+    }),
+  );
+}
+
+export function detectCoordinatorRepoStatusDrift(repos, coordinatorRepoRuns) {
+  return collectCoordinatorStatusDrift(
+    buildCoordinatorRepoStatusEntries({
+      coordinatorRepoRuns,
+      repoSnapshots: repos,
+    }),
+  );
+}
+
+export function deriveCoordinatorNextActions({
+  status,
+  blockedReason,
+  pendingGate,
+  repos,
+  coordinatorRepoRuns,
+  runIdMismatches,
+}) {
+  const nextActions = [];
+  if (status === 'completed') {
+    return nextActions;
+  }
+
+  const repoStatusEntries = buildCoordinatorRepoStatusEntries({
+    coordinatorRepoRuns,
+    repoSnapshots: repos,
+  });
+  const mismatches = Array.isArray(runIdMismatches)
+    ? runIdMismatches
+    : collectCoordinatorRunIdMismatches(repoStatusEntries);
+  const statusDrift = collectCoordinatorStatusDrift(repoStatusEntries);
+
+  if (mismatches.length > 0) {
+    nextActions.push({
+      code: 'repo_run_id_mismatch',
+      command: 'agentxchain multi resume',
+      reason: `Coordinator run identity drift detected${blockedReason ? `: ${blockedReason}` : ''}. Resume after reconciling the affected child repos.`,
+    });
+    for (const mismatch of mismatches) {
+      nextActions.push({
+        code: 'repo_run_id_mismatch',
+        command: 'agentxchain multi resume',
+        reason: `Repo "${mismatch.repo_id}" run identity drifted: coordinator expects "${mismatch.expected_run_id}" but repo has "${mismatch.actual_run_id}". Re-link the correct child run, then resume.`,
+      });
+    }
+    if (pendingGate) {
+      nextActions.push({
+        code: 'pending_gate',
+        command: 'agentxchain multi approve-gate',
+        reason: `After resume succeeds, approve pending gate "${pendingGate.gate}" (${pendingGate.gate_type}).`,
+      });
+    }
+    return nextActions;
+  }
+
+  if (statusDrift.length > 0) {
+    nextActions.push({
+      code: 'resync',
+      command: 'agentxchain multi resync',
+      reason: `Coordinator state disagrees with repo authority for: ${statusDrift.map((entry) => entry.repo_id).join(', ')}.`,
+    });
+    if (pendingGate) {
+      nextActions.push({
+        code: 'pending_gate',
+        command: 'agentxchain multi approve-gate',
+        reason: `If resync preserves gate "${pendingGate.gate}", approve it afterward.`,
+      });
+    }
+    return nextActions;
+  }
+
+  if (status === 'blocked') {
+    nextActions.push({
+      code: 'resume',
+      command: 'agentxchain multi resume',
+      reason: `Coordinator is blocked${blockedReason ? `: ${blockedReason}` : ''}. Resume after fixing the underlying issue.`,
+    });
+    if (pendingGate) {
+      nextActions.push({
+        code: 'pending_gate',
+        command: 'agentxchain multi approve-gate',
+        reason: `After resume succeeds, approve pending gate "${pendingGate.gate}" (${pendingGate.gate_type}).`,
+      });
+    }
+    return nextActions;
+  }
+
+  if (pendingGate) {
+    nextActions.push({
+      code: 'pending_gate',
+      command: 'agentxchain multi approve-gate',
+      reason: `Coordinator is waiting on pending gate "${pendingGate.gate}" (${pendingGate.gate_type}).`,
+    });
+    return nextActions;
+  }
+
+  if (status === 'active' || status === 'paused') {
+    nextActions.push({
+      code: 'step',
+      command: 'agentxchain multi step',
+      reason: 'Coordinator has no blocked state or pending gate and can continue.',
+    });
+  }
+
+  return nextActions;
+}

package/src/lib/coordinator-pending-gate-presentation.js

@@ -0,0 +1,79 @@
+import { pushDetail } from './coordinator-presentation-detail.js';
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function pickString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return null;
+}
+
+function pickArray(...values) {
+  for (const value of values) {
+    if (Array.isArray(value) && value.length > 0) {
+      return value.map((item) => String(item));
+    }
+  }
+  return [];
+}
+
+export function getCoordinatorPendingGateSnapshot({ pendingGate = null, active = null } = {}) {
+  const hasPendingGate = isObject(pendingGate);
+  const hasActive = isObject(active);
+  if (!hasPendingGate && !hasActive) {
+    return null;
+  }
+
+  const gateType = pickString(pendingGate?.gate_type, active?.gate_type);
+  const gateId = pickString(pendingGate?.gate, active?.gate_id);
+  if (!gateType && !gateId) {
+    return null;
+  }
+
+  return {
+    gate_type: gateType,
+    gate_id: gateId,
+    current_phase: pickString(pendingGate?.from, active?.current_phase),
+    target_phase: pickString(pendingGate?.to, active?.target_phase),
+    required_repos: pickArray(pendingGate?.required_repos, active?.required_repos),
+    human_barriers: pickArray(pendingGate?.human_barriers, active?.human_barriers),
+    approval_state: 'Awaiting human approval',
+  };
+}
+
+export function getCoordinatorPendingGateDetails({
+  pendingGate = null,
+  active = null,
+  includeType = true,
+  includeApprovalState = true,
+  includeHumanBarriers = true,
+} = {}) {
+  const snapshot = getCoordinatorPendingGateSnapshot({ pendingGate, active });
+  if (!snapshot) {
+    return [];
+  }
+
+  const details = [];
+  if (includeType) {
+    pushDetail(details, 'Type', snapshot.gate_type);
+  }
+  pushDetail(details, 'Gate', snapshot.gate_id, { mono: true });
+  pushDetail(details, 'Current Phase', snapshot.current_phase);
+  pushDetail(details, 'Target Phase', snapshot.target_phase);
+  if (snapshot.required_repos.length > 0) {
+    pushDetail(details, 'Required Repos', snapshot.required_repos.join(', '));
+  }
+  if (includeApprovalState) {
+    pushDetail(details, 'Approval State', snapshot.approval_state);
+  }
+  if (includeHumanBarriers && snapshot.human_barriers.length > 0) {
+    pushDetail(details, 'Human Barriers', snapshot.human_barriers.join(', '));
+  }
+
+  return details;
+}

package/src/lib/coordinator-presentation-detail.js

@@ -0,0 +1,11 @@
+export function pushDetail(details, label, value, options = {}) {
+  if (value == null || value === '') {
+    return;
+  }
+
+  details.push({
+    label,
+    value: String(value),
+    mono: options.mono === true,
+  });
+}

package/src/lib/coordinator-repo-snapshots.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+function readRepoStateSnapshot(repo) {
+  const statePath = join(repo.resolved_path, '.agentxchain', 'state.json');
+  if (!existsSync(statePath)) {
+    return {
+      repo_id: repo.repo_id,
+      ok: false,
+      status: null,
+      run_id: null,
+      phase: null,
+    };
+  }
+
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    return {
+      repo_id: repo.repo_id,
+      ok: true,
+      status: state?.status ?? null,
+      run_id: state?.run_id ?? null,
+      phase: state?.phase ?? null,
+    };
+  } catch {
+    return {
+      repo_id: repo.repo_id,
+      ok: false,
+      status: null,
+      run_id: null,
+      phase: null,
+    };
+  }
+}
+
+export function collectCoordinatorRepoSnapshots(config) {
+  return (config?.repo_order || []).map((repoId) => {
+    const repo = config?.repos?.[repoId];
+    if (!repo?.resolved_path) {
+      return {
+        repo_id: repoId,
+        ok: false,
+        status: null,
+        run_id: null,
+        phase: null,
+      };
+    }
+    return readRepoStateSnapshot({
+      repo_id: repoId,
+      resolved_path: repo.resolved_path,
+    });
+  });
+}

package/src/lib/coordinator-repo-status-presentation.js

@@ -0,0 +1,134 @@
+import { collectCoordinatorRepoSnapshots } from './coordinator-repo-snapshots.js';
+
+export function normalizeCoordinatorRepoStatus(status) {
+  if (status === 'linked' || status === 'initialized') {
+    return 'active';
+  }
+  return status || null;
+}
+
+function resolveCoordinatorRepoOrder({ config, coordinatorRepoRuns, repoSnapshots }) {
+  if (Array.isArray(config?.repo_order) && config.repo_order.length > 0) {
+    return config.repo_order;
+  }
+
+  const repoOrder = [];
+  const seen = new Set();
+
+  for (const repoId of Object.keys(coordinatorRepoRuns || {})) {
+    if (!seen.has(repoId)) {
+      seen.add(repoId);
+      repoOrder.push(repoId);
+    }
+  }
+
+  for (const snapshot of Array.isArray(repoSnapshots) ? repoSnapshots : []) {
+    const repoId = snapshot?.repo_id;
+    if (typeof repoId === 'string' && repoId.length > 0 && !seen.has(repoId)) {
+      seen.add(repoId);
+      repoOrder.push(repoId);
+    }
+  }
+
+  return repoOrder;
+}
+
+export function buildCoordinatorRepoStatusEntries({
+  config,
+  coordinatorRepoRuns,
+  repoSnapshots,
+}) {
+  const resolvedRepoSnapshots = Array.isArray(repoSnapshots)
+    ? repoSnapshots
+    : (config ? collectCoordinatorRepoSnapshots(config) : []);
+  const repoOrder = resolveCoordinatorRepoOrder({
+    config,
+    coordinatorRepoRuns,
+    repoSnapshots: resolvedRepoSnapshots,
+  });
+  const snapshotByRepoId = new Map(
+    resolvedRepoSnapshots
+      .filter((entry) => typeof entry?.repo_id === 'string' && entry.repo_id.length > 0)
+      .map((entry) => [entry.repo_id, entry]),
+  );
+
+  return repoOrder.map((repoId) => {
+    const coordinatorRepoRun = coordinatorRepoRuns?.[repoId] || {};
+    const repoSnapshot = snapshotByRepoId.get(repoId) || null;
+    const repoAuthorityAvailable = repoSnapshot?.ok === true;
+    const coordinatorStatus = coordinatorRepoRun.status || null;
+    const normalizedCoordinatorStatus = normalizeCoordinatorRepoStatus(coordinatorStatus);
+    const repoAuthorityStatus = repoAuthorityAvailable ? (repoSnapshot.status || null) : null;
+    const repoAuthorityRunId = repoAuthorityAvailable ? (repoSnapshot.run_id ?? null) : null;
+    const runIdMismatch = (
+      repoAuthorityAvailable
+      && coordinatorRepoRun.run_id
+      && repoAuthorityRunId
+      && coordinatorRepoRun.run_id !== repoAuthorityRunId
+    )
+      ? {
+        repo_id: repoId,
+        expected_run_id: coordinatorRepoRun.run_id,
+        actual_run_id: repoAuthorityRunId,
+      }
+      : null;
+    const statusDrift = (
+      repoAuthorityAvailable
+      && normalizedCoordinatorStatus
+      && repoAuthorityStatus
+      && normalizedCoordinatorStatus !== repoAuthorityStatus
+    )
+      ? {
+        repo_id: repoId,
+        coordinator_status: coordinatorStatus,
+        repo_status: repoAuthorityStatus,
+      }
+      : null;
+    const details = [];
+
+    if (coordinatorStatus === 'linked' || coordinatorStatus === 'initialized') {
+      details.push({
+        label: 'coordinator',
+        value: coordinatorStatus,
+      });
+    }
+
+    if (runIdMismatch) {
+      details.push({
+        label: 'expected run',
+        value: runIdMismatch.expected_run_id,
+        mono: true,
+      });
+    }
+
+    return {
+      repo_id: repoId,
+      run_id: repoAuthorityAvailable
+        ? (repoAuthorityRunId ?? coordinatorRepoRun.run_id ?? null)
+        : (coordinatorRepoRun.run_id ?? null),
+      status: repoAuthorityAvailable
+        ? (repoAuthorityStatus || 'unknown')
+        : (normalizedCoordinatorStatus || 'unknown'),
+      phase: repoAuthorityAvailable
+        ? (repoSnapshot.phase ?? coordinatorRepoRun.phase ?? null)
+        : (coordinatorRepoRun.phase ?? null),
+      details,
+      coordinator_status: coordinatorStatus,
+      normalized_coordinator_status: normalizedCoordinatorStatus,
+      repo_authority_available: repoAuthorityAvailable,
+      run_id_mismatch: runIdMismatch,
+      status_drift: statusDrift,
+    };
+  });
+}
+
+export function buildCoordinatorRepoStatusRows({ config, coordinatorRepoRuns, repoSnapshots }) {
+  return buildCoordinatorRepoStatusEntries({ config, coordinatorRepoRuns, repoSnapshots })
+    .map((entry) => ({
+      repo_id: entry.repo_id,
+      run_id: entry.run_id,
+      status: entry.status,
+      phase: entry.phase,
+      details: entry.details,
+    }));
+}

package/src/lib/dashboard/actions.js

@@ -1,7 +1,12 @@
 import { dirname } from 'path';
 import { loadProjectContext } from '../config.js';
 import { approvePhaseTransition, approveRunCompletion } from '../governed-state.js';
-import { deriveRecoveryDescriptor } from '../blocked-state.js';
+import { deriveGovernedRunNextActions, deriveRecoveryDescriptor } from '../blocked-state.js';
+import {
+  deriveCoordinatorGateNextActions,
+  normalizeCoordinatorGateApprovalFailure,
+  normalizeCoordinatorGateApprovalSuccess,
+} from '../coordinator-gate-approval.js';
 import { loadCoordinatorConfig } from '../coordinator-config.js';
 import { loadCoordinatorState } from '../coordinator-state.js';
 import { buildGatePayload, fireCoordinatorHook } from '../coordinator-hooks.js';
@@ -21,6 +26,16 @@ function buildError(status, code, error, extra = {}) {
 }
 
 function normalizeRepoSuccess(result, gateType) {
+  const nextActions = gateType === 'phase_transition'
+    ? [
+        {
+          command: 'agentxchain step',
+          reason: `Run is active in phase "${result.state?.phase || 'unknown'}" and can continue.`,
+        },
+      ]
+    : [];
+  const nextAction = nextActions[0]?.command ?? null;
+
   if (gateType === 'phase_transition') {
     return {
       status: 200,
@@ -28,8 +43,11 @@ function normalizeRepoSuccess(result, gateType) {
         ok: true,
         scope: 'repo',
         gate_type: 'phase_transition',
+        status: result.state?.status || null,
+        phase: result.state?.phase || null,
         message: `Phase transition approved: ${result.transition.from} -> ${result.transition.to}`,
-        next_action: 'agentxchain step',
+        next_action: nextAction,
+        next_actions: nextActions,
       },
     };
   }
@@ -40,17 +58,59 @@ function normalizeRepoSuccess(result, gateType) {
       ok: true,
       scope: 'repo',
       gate_type: 'run_completion',
+      status: result.state?.status || null,
+      phase: result.state?.phase || null,
       message: 'Run completion approved. Run is now completed.',
-      next_action: null,
+      next_action: nextAction,
+      next_actions: nextActions,
     },
   };
 }
 
-function normalizeRepoFailure(result) {
-  const recovery = result.state ? deriveRecoveryDescriptor(result.state) : null;
+function deriveRepoHookName(result) {
+  return result?.hookResults?.blocker?.hook_name
+    || result?.hookResults?.results?.find((entry) => entry?.hook_name)?.hook_name
+    || null;
+}
+
+function buildRecoverySummary(recovery) {
+  if (!recovery || typeof recovery !== 'object') {
+    return null;
+  }
+
+  return {
+    typed_reason: recovery.typed_reason || 'approval_failed',
+    owner: recovery.owner || 'human',
+    recovery_action: recovery.recovery_action || null,
+    detail: recovery.detail ?? null,
+    turn_retained: typeof recovery.turn_retained === 'boolean' ? recovery.turn_retained : false,
+    runtime_guidance: Array.isArray(recovery.runtime_guidance) ? recovery.runtime_guidance : [],
+  };
+}
+
+function normalizeRepoFailure(result, config) {
+  const recovery = result.state ? deriveRecoveryDescriptor(result.state, config) : null;
+  const nextActions = result.state ? deriveGovernedRunNextActions(result.state, config) : [];
+  const nextAction = nextActions[0]?.command || recovery?.recovery_action || null;
   const code = result.error_code || 'approval_failed';
+  const gateType = result.state?.pending_phase_transition
+    ? 'phase_transition'
+    : result.state?.pending_run_completion
+      ? 'run_completion'
+      : null;
+  const gate = result.state?.pending_phase_transition?.gate
+    || result.state?.pending_run_completion?.gate
+    || null;
+  const hookPhase = code.startsWith('hook_') ? 'before_gate' : null;
   return buildError(409, code, result.error || 'Gate approval failed', {
-    next_action: recovery?.recovery_action || null,
+    scope: 'repo',
+    gate,
+    gate_type: gateType,
+    hook_phase: hookPhase,
+    hook_name: hookPhase ? deriveRepoHookName(result) : null,
+    next_action: nextAction,
+    next_actions: nextActions,
+    recovery_summary: buildRecoverySummary(recovery),
   });
 }
 
@@ -61,34 +121,22 @@ function approveRepoGate(root, config, state) {
     : approveRunCompletion(root, config);
 
   if (!result.ok) {
-    return normalizeRepoFailure(result);
+    return normalizeRepoFailure(result, config);
   }
 
   return normalizeRepoSuccess(result, gateType);
 }
 
-function normalizeCoordinatorSuccess(result, gateType) {
-  if (gateType === 'phase_transition') {
-    return {
-      status: 200,
-      body: {
-        ok: true,
-        scope: 'coordinator',
-        gate_type: 'phase_transition',
-        message: `Coordinator phase transition approved: ${result.transition.from} -> ${result.transition.to}`,
-        next_action: 'agentxchain multi step',
-      },
-    };
-  }
-
+function normalizeCoordinatorSuccess(result, gateType, config) {
+  const payload = normalizeCoordinatorGateApprovalSuccess({
+    result: { ...result, config },
+    gateType,
+  });
   return {
     status: 200,
     body: {
-      ok: true,
       scope: 'coordinator',
-      gate_type: 'run_completion',
-      message: 'Coordinator run completion approved. Run is now complete.',
-      next_action: null,
+      ...payload,
     },
   };
 }
@@ -102,11 +150,31 @@ function approveCoordinatorGate(workspacePath, state, config) {
   if (gateHook.blocked) {
     const blocker = gateHook.verdicts.find((entry) => entry.verdict === 'block');
     const reason = blocker?.message || 'before_gate hook blocked approval';
-    return buildError(409, 'hook_blocked', reason);
+    return {
+      status: 409,
+      body: normalizeCoordinatorGateApprovalFailure({
+        state,
+        config,
+        code: 'hook_blocked',
+        error: reason,
+        hookName: blocker?.hook_name || null,
+        hookPhase: 'before_gate',
+      }),
+    };
   }
 
   if (!gateHook.ok) {
-    return buildError(409, 'hook_failed', gateHook.error || 'before_gate hook failed');
+    return {
+      status: 409,
+      body: normalizeCoordinatorGateApprovalFailure({
+        state,
+        config,
+        code: 'hook_failed',
+        error: gateHook.error || 'before_gate hook failed',
+        hookName: gateHook.results?.find((entry) => entry?.hook_name)?.hook_name || null,
+        hookPhase: 'before_gate',
+      }),
+    };
   }
 
   const gateType = state.pending_gate.gate_type;
@@ -121,10 +189,18 @@ function approveCoordinatorGate(workspacePath, state, config) {
   }
 
   if (!result.ok) {
-    return buildError(409, 'approval_failed', result.error || 'Coordinator gate approval failed');
+    return {
+      status: 409,
+      body: normalizeCoordinatorGateApprovalFailure({
+        state,
+        config,
+        code: 'approval_failed',
+        error: result.error || 'Coordinator gate approval failed',
+      }),
+    };
   }
 
-  return normalizeCoordinatorSuccess(result, gateType);
+  return normalizeCoordinatorSuccess(result, gateType, config);
 }
 
 export function approvePendingDashboardGate(agentxchainDir) {

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

@@ -19,6 +19,7 @@ import { FileWatcher } from './file-watcher.js';
 import { readRunEvents, RUN_EVENTS_PATH } from '../run-events.js';
 import { approvePendingDashboardGate } from './actions.js';
 import { readCoordinatorBlockerSnapshot } from './coordinator-blockers.js';
+import { readCoordinatorRepoStatusRows } from './coordinator-repo-status.js';
 import { readCoordinatorTimeoutStatus } from './coordinator-timeout-status.js';
 import { readAggregatedCoordinatorEvents, watchChildRepoEvents } from './coordinator-event-aggregation.js';
 import { readWorkflowKitArtifacts } from './workflow-kit-artifacts.js';
@@ -348,6 +349,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       return;
     }
 
+    if (pathname === '/api/coordinator/repo-status') {
+      const result = readCoordinatorRepoStatusRows(workspacePath);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     if (pathname === '/api/coordinator/timeouts') {
       const result = readCoordinatorTimeoutStatus(workspacePath);
       writeJson(res, result.status, result.body);

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

@@ -1,5 +1,7 @@
 import { evaluateCompletionGate, evaluatePhaseGate } from '../coordinator-gates.js';
 import { loadCoordinatorConfig } from '../coordinator-config.js';
+import { deriveCoordinatorNextActions } from '../coordinator-next-actions.js';
+import { collectCoordinatorRepoSnapshots } from '../coordinator-repo-snapshots.js';
 import { loadCoordinatorState } from '../coordinator-state.js';
 
 function normalizePendingGate(pendingGate) {
@@ -148,6 +150,20 @@ export function readCoordinatorBlockerSnapshot(workspacePath) {
     };
   }
 
+  const repos = collectCoordinatorRepoSnapshots(configResult.config);
+  const nextActions = deriveCoordinatorNextActions({
+    status: state.status ?? null,
+    blockedReason: state.blocked_reason ?? null,
+    pendingGate,
+    repos,
+    coordinatorRepoRuns: state.repo_runs || {},
+    runIdMismatches: active.blockers?.filter((blocker) => blocker?.code === 'repo_run_id_mismatch').map((blocker) => ({
+      repo_id: blocker.repo_id,
+      expected_run_id: blocker.expected_run_id,
+      actual_run_id: blocker.actual_run_id,
+    })),
+  });
+
   return {
     ok: true,
     status: 200,
@@ -159,6 +175,7 @@ export function readCoordinatorBlockerSnapshot(workspacePath) {
       blocked_reason: state.blocked_reason ?? null,
       pending_gate: pendingGate,
       active,
+      next_actions: nextActions,
       evaluations: {
         phase_transition: phaseEvaluation,
         run_completion: completionEvaluation,