agentxchain 2.13.0 → 2.15.0

package/src/commands/intake-workspace.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, parse as pathParse, resolve } from 'node:path';
+import { findProjectRoot } from '../lib/config.js';
+import { COORDINATOR_CONFIG_FILE } from '../lib/coordinator-config.js';
+
+function findCoordinatorWorkspaceRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  const { root: fsRoot } = pathParse(dir);
+
+  while (true) {
+    if (existsSync(join(dir, COORDINATOR_CONFIG_FILE))) {
+      return dir;
+    }
+    if (dir === fsRoot) {
+      return null;
+    }
+    dir = join(dir, '..');
+  }
+}
+
+function listCoordinatorChildRepos(coordinatorRoot) {
+  const configPath = join(coordinatorRoot, COORDINATOR_CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    return [];
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+    return Object.keys(raw?.repos || {});
+  } catch {
+    return [];
+  }
+}
+
+export function requireIntakeWorkspaceOrExit(opts, startDir = process.cwd()) {
+  const projectRoot = findProjectRoot(startDir);
+  if (projectRoot) {
+    return projectRoot;
+  }
+
+  const coordinatorRoot = findCoordinatorWorkspaceRoot(startDir);
+  const childRepos = coordinatorRoot ? listCoordinatorChildRepos(coordinatorRoot) : [];
+  const repoHint = childRepos.length > 0
+    ? ` Available child repos: ${childRepos.join(', ')}.`
+    : '';
+  const error = coordinatorRoot
+    ? `intake commands are repo-local only. Found coordinator workspace at ${coordinatorRoot} (${COORDINATOR_CONFIG_FILE}). Run intake inside a child governed repo (agentxchain.json).${repoHint} Then use \`agentxchain multi step\` for cross-repo coordination.`
+    : 'agentxchain.json not found';
+
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: false, error }, null, 2));
+  } else {
+    console.log(chalk.red(error));
+  }
+
+  process.exit(2);
+}

package/src/commands/multi.js

@@ -5,6 +5,7 @@
  *   multi init         — bootstrap a multi-repo coordinator run
  *   multi status       — show coordinator status and repo-run snapshots
  *   multi step         — reconcile repo truth, then dispatch or request the next coordinator gate
+ *   multi resume       — clear coordinator blocked state after operator recovery
  *   multi approve-gate — approve a pending phase transition or completion gate
  *   multi resync       — detect divergence and rebuild coordinator state from repo authority
  */
@@ -26,7 +27,11 @@ import {
   requestCoordinatorCompletion,
   requestPhaseTransition,
 } from '../lib/coordinator-gates.js';
-import { detectDivergence, resyncFromRepoAuthority } from '../lib/coordinator-recovery.js';
+import {
+  detectDivergence,
+  resyncFromRepoAuthority,
+  resumeCoordinatorFromBlockedState,
+} from '../lib/coordinator-recovery.js';
 import {
   fireCoordinatorHook,
   buildAssignmentPayload,
@@ -154,7 +159,7 @@ export async function multiStepCommand(options) {
     // Fire on_escalation hook (advisory — cannot block, only notifies)
     fireEscalationHook(workspacePath, configResult.config, state, state.blocked_reason || 'unknown reason');
     console.error(`Coordinator is blocked: ${state.blocked_reason || 'unknown reason'}`);
-    console.error('Resolve the blocked state before stepping.');
+    console.error('Resolve the blocked state, then run `agentxchain multi resume` before stepping again.');
     process.exitCode = 1;
     return;
   }
@@ -362,6 +367,57 @@ function maybeRequestCoordinatorGate(workspacePath, state, config) {
   return { ok: false, type: 'run_completion', blockers: completionEvaluation.blockers };
 }
 
+// ── multi resume ───────────────────────────────────────────────────────────
+
+export async function multiResumeCommand(options) {
+  const workspacePath = process.cwd();
+  const configResult = loadCoordinatorConfig(workspacePath);
+
+  if (!configResult.ok) {
+    console.error('Coordinator config error:');
+    for (const err of configResult.errors || []) {
+      console.error(`  - ${typeof err === 'string' ? err : err.message || JSON.stringify(err)}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const state = loadCoordinatorState(workspacePath);
+  if (!state) {
+    console.error('No coordinator state found. Run `agentxchain multi init` first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = resumeCoordinatorFromBlockedState(workspacePath, state, configResult.config);
+
+  if (!result.ok) {
+    console.error(result.error || 'Coordinator recovery failed.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      ok: true,
+      previous_status: 'blocked',
+      resumed_status: result.resumed_status,
+      blocked_reason: result.blocked_reason,
+      pending_gate: result.state?.pending_gate || null,
+      resync: result.resync,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`Coordinator resumed: ${result.resumed_status}`);
+  console.log(`Previous block: ${result.blocked_reason}`);
+  if (result.resumed_status === 'paused' && result.state?.pending_gate) {
+    console.log(`Next action: agentxchain multi approve-gate (${result.state.pending_gate.gate})`);
+  } else {
+    console.log('Next action: agentxchain multi step');
+  }
+}
+
 // ── multi approve-gate ─────────────────────────────────────────────────────
 
 export async function multiApproveGateCommand(options) {

package/src/lib/coordinator-acceptance.js

@@ -17,6 +17,11 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } fr
 import { isAbsolute, join, dirname, relative, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { readBarriers, readCoordinatorHistory, saveCoordinatorState } from './coordinator-state.js';
+import {
+  computeBarrierStatus as computeCoordinatorBarrierStatus,
+  getAcceptedReposForWorkstream,
+  getAlignedReposForBarrier,
+} from './coordinator-barriers.js';
 
 // ── Paths ───────────────────────────────────────────────────────────────────
 
@@ -238,100 +243,8 @@ export function recordBarrierTransition(workspacePath, barrierId, previousStatus
   });
 }
 
-// ── Internal barrier logic ──────────────────────────────────────────────────
-
-function getAcceptedReposForWorkstream(history, workstreamId, requiredRepos) {
-  const accepted = new Set();
-  for (const entry of history) {
-    if (entry?.type === 'acceptance_projection' && entry.workstream_id === workstreamId) {
-      if (requiredRepos.includes(entry.repo_id)) {
-        accepted.add(entry.repo_id);
-      }
-    }
-  }
-  return [...accepted];
-}
-
 function computeBarrierStatus(barrier, history, config) {
-  switch (barrier.type) {
-    case 'all_repos_accepted':
-      return computeAllReposAccepted(barrier, history);
-
-    case 'ordered_repo_sequence':
-      return computeOrderedRepoSequence(barrier, history, config);
-
-    case 'interface_alignment':
-      return computeInterfaceAlignment(barrier, history);
-
-    case 'shared_human_gate':
-      // Never auto-satisfied — requires explicit human approval
-      return barrier.status;
-
-    default:
-      return barrier.status;
-  }
-}
-
-function computeAllReposAccepted(barrier, history) {
-  const required = new Set(barrier.required_repos);
-  const satisfied = new Set();
-
-  for (const entry of history) {
-    if (entry?.type === 'acceptance_projection' && entry.workstream_id === barrier.workstream_id) {
-      if (required.has(entry.repo_id)) {
-        satisfied.add(entry.repo_id);
-      }
-    }
-  }
-
-  if (satisfied.size === required.size) return 'satisfied';
-  if (satisfied.size > 0) return 'partially_satisfied';
-  return 'pending';
-}
-
-function computeOrderedRepoSequence(barrier, history, config) {
-  const workstream = config.workstreams?.[barrier.workstream_id];
-  if (!workstream) return barrier.status;
-
-  // Upstream is entry_repo. The barrier is satisfied when entry_repo has an accepted turn.
-  const entryRepo = workstream.entry_repo;
-  const hasUpstreamAcceptance = history.some(
-    entry => entry?.type === 'acceptance_projection'
-      && entry.workstream_id === barrier.workstream_id
-      && entry.repo_id === entryRepo
-  );
-
-  if (hasUpstreamAcceptance) return 'satisfied';
-
-  // Check if any non-entry repos have been accepted (partial)
-  const anyDownstreamAccepted = history.some(
-    entry => entry?.type === 'acceptance_projection'
-      && entry.workstream_id === barrier.workstream_id
-      && entry.repo_id !== entryRepo
-  );
-
-  if (anyDownstreamAccepted) return 'partially_satisfied';
-  return 'pending';
-}
-
-function computeInterfaceAlignment(barrier, history) {
-  const required = new Set(barrier.required_repos);
-  const repoDecisions = {};
-
-  for (const entry of history) {
-    if (entry?.type === 'acceptance_projection' && entry.workstream_id === barrier.workstream_id) {
-      if (required.has(entry.repo_id)) {
-        repoDecisions[entry.repo_id] = entry.decisions ?? [];
-      }
-    }
-  }
-
-  const acceptedRepos = Object.keys(repoDecisions);
-  if (acceptedRepos.length === 0) return 'pending';
-  if (acceptedRepos.length < required.size) return 'partially_satisfied';
-
-  // All repos accepted — check for DEC-* alignment (heuristic)
-  return 'satisfied';
+  return computeCoordinatorBarrierStatus(barrier, history, config);
 }
 
 // ── Barrier effects from a single acceptance ────────────────────────────────
@@ -340,19 +253,32 @@ function evaluateBarrierEffects(workspacePath, state, config, repoId, workstream
   const barriers = readBarriers(workspacePath);
   const history = readCoordinatorHistory(workspacePath);
   const effects = [];
+  let snapshotChanged = false;
 
   for (const [barrierId, barrier] of Object.entries(barriers)) {
     if (barrier.status === 'satisfied') continue;
     if (barrier.workstream_id !== workstreamId) continue;
 
     const newStatus = computeBarrierStatus(barrier, history, config);
+    if (barrier.type === 'all_repos_accepted') {
+      const satisfiedRepos = getAcceptedReposForWorkstream(history, workstreamId, barrier.required_repos);
+      if (JSON.stringify(barrier.satisfied_repos || []) !== JSON.stringify(satisfiedRepos)) {
+        barrier.satisfied_repos = satisfiedRepos;
+        snapshotChanged = true;
+      }
+    }
+    if (barrier.type === 'interface_alignment') {
+      const satisfiedRepos = getAlignedReposForBarrier(barrier, history);
+      if (JSON.stringify(barrier.satisfied_repos || []) !== JSON.stringify(satisfiedRepos)) {
+        barrier.satisfied_repos = satisfiedRepos;
+        snapshotChanged = true;
+      }
+    }
+
     if (newStatus !== barrier.status) {
       const previousStatus = barrier.status;
       barrier.status = newStatus;
-
-      if (barrier.type === 'all_repos_accepted') {
-        barrier.satisfied_repos = getAcceptedReposForWorkstream(history, workstreamId, barrier.required_repos);
-      }
+      snapshotChanged = true;
 
       effects.push({
         barrier_id: barrierId,
@@ -370,7 +296,7 @@ function evaluateBarrierEffects(workspacePath, state, config, repoId, workstream
   }
 
   // Persist updated barrier snapshot
-  if (effects.length > 0) {
+  if (snapshotChanged) {
     writeFileSync(barriersPath(workspacePath), JSON.stringify(barriers, null, 2) + '\n');
   }
 

package/src/lib/coordinator-barriers.js

@@ -0,0 +1,116 @@
+function isProjectionEntry(entry, workstreamId) {
+  return entry?.type === 'acceptance_projection' && entry.workstream_id === workstreamId;
+}
+
+function normalizeDecisionId(decision) {
+  if (typeof decision === 'string') return decision;
+  if (decision && typeof decision === 'object' && typeof decision.id === 'string') return decision.id;
+  return null;
+}
+
+function collectAcceptedDecisionIds(history, workstreamId, requiredRepos = []) {
+  const required = new Set(requiredRepos);
+  const repoDecisionIds = {};
+  const acceptedRepos = new Set();
+
+  for (const entry of history) {
+    if (!isProjectionEntry(entry, workstreamId)) continue;
+    if (required.size > 0 && !required.has(entry.repo_id)) continue;
+
+    acceptedRepos.add(entry.repo_id);
+    if (!repoDecisionIds[entry.repo_id]) {
+      repoDecisionIds[entry.repo_id] = new Set();
+    }
+
+    for (const decision of Array.isArray(entry.decisions) ? entry.decisions : []) {
+      const id = normalizeDecisionId(decision);
+      if (id) {
+        repoDecisionIds[entry.repo_id].add(id);
+      }
+    }
+  }
+
+  return { acceptedRepos, repoDecisionIds };
+}
+
+export function getAcceptedReposForWorkstream(history, workstreamId, requiredRepos = []) {
+  return [
+    ...collectAcceptedDecisionIds(history, workstreamId, requiredRepos).acceptedRepos,
+  ];
+}
+
+export function getAlignedReposForBarrier(barrier, history) {
+  const requiredRepos = Array.isArray(barrier.required_repos) ? barrier.required_repos : [];
+  const alignmentDecisionIds = barrier.alignment_decision_ids || {};
+  const { repoDecisionIds } = collectAcceptedDecisionIds(history, barrier.workstream_id, requiredRepos);
+  const alignedRepos = [];
+
+  for (const repoId of requiredRepos) {
+    const requiredIds = Array.isArray(alignmentDecisionIds[repoId]) ? alignmentDecisionIds[repoId] : [];
+    if (requiredIds.length === 0) continue;
+
+    const acceptedIds = repoDecisionIds[repoId] || new Set();
+    if (requiredIds.every((decisionId) => acceptedIds.has(decisionId))) {
+      alignedRepos.push(repoId);
+    }
+  }
+
+  return alignedRepos;
+}
+
+export function computeAllReposAcceptedStatus(barrier, history) {
+  const requiredRepos = Array.isArray(barrier.required_repos) ? barrier.required_repos : [];
+  const acceptedRepos = getAcceptedReposForWorkstream(history, barrier.workstream_id, requiredRepos);
+
+  if (acceptedRepos.length === requiredRepos.length && requiredRepos.length > 0) return 'satisfied';
+  if (acceptedRepos.length > 0) return 'partially_satisfied';
+  return 'pending';
+}
+
+export function computeOrderedRepoSequenceStatus(barrier, history, config) {
+  const workstream = config.workstreams?.[barrier.workstream_id];
+  if (!workstream) return barrier.status;
+
+  const entryRepo = workstream.entry_repo;
+  const hasUpstreamAcceptance = history.some(
+    (entry) => isProjectionEntry(entry, barrier.workstream_id) && entry.repo_id === entryRepo,
+  );
+
+  if (hasUpstreamAcceptance) return 'satisfied';
+
+  const anyDownstreamAccepted = history.some(
+    (entry) => isProjectionEntry(entry, barrier.workstream_id) && entry.repo_id !== entryRepo,
+  );
+
+  if (anyDownstreamAccepted) return 'partially_satisfied';
+  return 'pending';
+}
+
+export function computeInterfaceAlignmentStatus(barrier, history) {
+  const requiredRepos = Array.isArray(barrier.required_repos) ? barrier.required_repos : [];
+  const alignedRepos = getAlignedReposForBarrier(barrier, history);
+  const acceptedRepos = getAcceptedReposForWorkstream(history, barrier.workstream_id, requiredRepos);
+
+  if (alignedRepos.length === requiredRepos.length && requiredRepos.length > 0) return 'satisfied';
+  if (acceptedRepos.length > 0) return 'partially_satisfied';
+  return 'pending';
+}
+
+export function computeBarrierStatus(barrier, history, config) {
+  switch (barrier.type) {
+    case 'all_repos_accepted':
+      return computeAllReposAcceptedStatus(barrier, history);
+
+    case 'ordered_repo_sequence':
+      return computeOrderedRepoSequenceStatus(barrier, history, config);
+
+    case 'interface_alignment':
+      return computeInterfaceAlignmentStatus(barrier, history);
+
+    case 'shared_human_gate':
+      return barrier.status;
+
+    default:
+      return barrier.status;
+  }
+}

package/src/lib/coordinator-config.js

@@ -146,12 +146,95 @@ function validateWorkstreams(raw, repoIds, errors) {
         `workstream "${workstreamId}" completion_barrier must be one of: ${Array.from(VALID_BARRIER_TYPES).join(', ')}`,
       );
     }
+
+    validateInterfaceAlignment(workstreamId, workstream, errors);
   }
 
   detectWorkstreamCycles(raw.workstreams, errors);
   return workstreamIds;
 }
 
+function validateInterfaceAlignment(workstreamId, workstream, errors) {
+  if (workstream.completion_barrier !== 'interface_alignment') {
+    return;
+  }
+
+  const alignment = workstream.interface_alignment;
+  if (!alignment || typeof alignment !== 'object' || Array.isArray(alignment)) {
+    pushError(
+      errors,
+      'workstream_interface_alignment_invalid',
+      `workstream "${workstreamId}" with completion_barrier "interface_alignment" must declare interface_alignment.decision_ids_by_repo`,
+    );
+    return;
+  }
+
+  const byRepo = alignment.decision_ids_by_repo;
+  if (!byRepo || typeof byRepo !== 'object' || Array.isArray(byRepo)) {
+    pushError(
+      errors,
+      'workstream_interface_alignment_decisions_invalid',
+      `workstream "${workstreamId}" interface_alignment.decision_ids_by_repo must be an object`,
+    );
+    return;
+  }
+
+  const repoIds = Array.isArray(workstream.repos) ? workstream.repos : [];
+  const repoIdSet = new Set(repoIds);
+
+  for (const repoId of repoIds) {
+    if (!(repoId in byRepo)) {
+      pushError(
+        errors,
+        'workstream_interface_alignment_repo_missing',
+        `workstream "${workstreamId}" must declare interface_alignment.decision_ids_by_repo["${repoId}"]`,
+      );
+      continue;
+    }
+
+    const decisionIds = byRepo[repoId];
+    if (!Array.isArray(decisionIds) || decisionIds.length === 0) {
+      pushError(
+        errors,
+        'workstream_interface_alignment_repo_invalid',
+        `workstream "${workstreamId}" interface_alignment.decision_ids_by_repo["${repoId}"] must be a non-empty array`,
+      );
+      continue;
+    }
+
+    const seen = new Set();
+    for (const decisionId of decisionIds) {
+      if (typeof decisionId !== 'string' || !/^DEC-\d+$/.test(decisionId)) {
+        pushError(
+          errors,
+          'workstream_interface_alignment_decision_invalid',
+          `workstream "${workstreamId}" interface_alignment decision "${decisionId}" for repo "${repoId}" must match DEC-NNN`,
+        );
+        continue;
+      }
+      if (seen.has(decisionId)) {
+        pushError(
+          errors,
+          'workstream_interface_alignment_decision_duplicate',
+          `workstream "${workstreamId}" interface_alignment decision "${decisionId}" is duplicated for repo "${repoId}"`,
+        );
+        continue;
+      }
+      seen.add(decisionId);
+    }
+  }
+
+  for (const repoId of Object.keys(byRepo)) {
+    if (!repoIdSet.has(repoId)) {
+      pushError(
+        errors,
+        'workstream_interface_alignment_repo_unknown',
+        `workstream "${workstreamId}" interface_alignment references undeclared repo "${repoId}"`,
+      );
+    }
+  }
+}
+
 function detectWorkstreamCycles(workstreams, errors) {
   const visiting = new Set();
   const visited = new Set();
@@ -344,6 +427,16 @@ export function normalizeCoordinatorConfig(raw) {
           entry_repo: workstream.entry_repo,
           depends_on: Array.isArray(workstream.depends_on) ? [...new Set(workstream.depends_on)] : [],
           completion_barrier: workstream.completion_barrier,
+          interface_alignment: workstream.interface_alignment?.decision_ids_by_repo
+            ? {
+                decision_ids_by_repo: Object.fromEntries(
+                  Object.entries(workstream.interface_alignment.decision_ids_by_repo).map(([repoId, decisionIds]) => [
+                    repoId,
+                    Array.isArray(decisionIds) ? [...new Set(decisionIds)] : [],
+                  ]),
+                ),
+              }
+            : null,
         },
       ]),
     ),