agentxchain 2.95.0 → 2.97.0

package/package.json

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

package/src/commands/replay-export.js

@@ -17,6 +17,190 @@ import { createBridgeServer } from '../lib/dashboard/bridge-server.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+function restoreExportFiles(root, files, scopeLabel) {
+  if (!files || typeof files !== 'object') {
+    throw new Error(`${scopeLabel} is missing a valid files object.`);
+  }
+
+  let restored = 0;
+  for (const [relPath, entry] of Object.entries(files)) {
+    const absPath = join(root, relPath);
+    mkdirSync(dirname(absPath), { recursive: true });
+
+    if (typeof entry === 'string') {
+      writeFileSync(absPath, entry);
+      restored++;
+      continue;
+    }
+
+    if (!entry || typeof entry !== 'object' || typeof entry.content_base64 !== 'string') {
+      throw new Error(`${scopeLabel} entry "${relPath}" must provide content_base64.`);
+    }
+
+    writeFileSync(absPath, Buffer.from(entry.content_base64, 'base64'));
+    restored++;
+  }
+
+  return restored;
+}
+
+function restoreCoordinatorRepos(tempRoot, repos) {
+  if (!repos || typeof repos !== 'object') {
+    return 0;
+  }
+
+  let restored = 0;
+  for (const [repoId, repoEntry] of Object.entries(repos)) {
+    if (!repoEntry || repoEntry.ok === false) {
+      continue;
+    }
+
+    if (typeof repoEntry.path !== 'string' || !repoEntry.path.trim()) {
+      throw new Error(`Coordinator repo "${repoId}" is marked ok but has no path.`);
+    }
+
+    const nestedFiles = repoEntry.export?.files;
+    if (!nestedFiles || typeof nestedFiles !== 'object') {
+      throw new Error(`Coordinator repo "${repoId}" is marked ok but has no nested export.files.`);
+    }
+
+    const repoRoot = join(tempRoot, repoEntry.path);
+    mkdirSync(repoRoot, { recursive: true });
+    restored += restoreExportFiles(repoRoot, nestedFiles, `repos.${repoId}.export.files`);
+  }
+
+  return restored;
+}
+
+function readEmbeddedJsonEntry(entry, label) {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error(`${label} is not a valid export file entry.`);
+  }
+
+  if (entry.data && typeof entry.data === 'object') {
+    return entry.data;
+  }
+
+  if (typeof entry.content_base64 !== 'string' || !entry.content_base64) {
+    throw new Error(`${label} must provide content_base64.`);
+  }
+
+  try {
+    return JSON.parse(Buffer.from(entry.content_base64, 'base64').toString('utf8'));
+  } catch (err) {
+    throw new Error(`${label} contains invalid JSON: ${err.message}`);
+  }
+}
+
+function getCoordinatorReplayPhases(exportData) {
+  const coordinatorConfig = exportData?.config
+    || readEmbeddedJsonEntry(exportData?.files?.['agentxchain-multi.json'], 'files["agentxchain-multi.json"]');
+  const routingPhases = Object.keys(coordinatorConfig?.routing || {});
+  if (routingPhases.length > 0) {
+    return routingPhases;
+  }
+
+  const phases = [];
+  for (const workstreamId of Object.keys(coordinatorConfig?.workstreams || {})) {
+    const phase = coordinatorConfig.workstreams?.[workstreamId]?.phase;
+    if (phase && !phases.includes(phase)) {
+      phases.push(phase);
+    }
+  }
+
+  return phases.length > 0 ? phases : ['planning'];
+}
+
+function restoreFailedCoordinatorRepoStubs(tempRoot, exportData) {
+  if (!exportData?.repos || typeof exportData.repos !== 'object') {
+    return 0;
+  }
+
+  const phases = getCoordinatorReplayPhases(exportData);
+  const coordinatorState = exportData?.files?.['.agentxchain/multirepo/state.json']
+    ? readEmbeddedJsonEntry(exportData.files['.agentxchain/multirepo/state.json'], 'files[".agentxchain/multirepo/state.json"]')
+    : null;
+
+  let restored = 0;
+  for (const [repoId, repoEntry] of Object.entries(exportData.repos)) {
+    if (!repoEntry || repoEntry.ok !== false) {
+      continue;
+    }
+
+    if (typeof repoEntry.path !== 'string' || !repoEntry.path.trim()) {
+      throw new Error(`Coordinator repo "${repoId}" failed export but has no path.`);
+    }
+
+    const repoRoot = join(tempRoot, repoEntry.path);
+    const promptPath = '.agentxchain/prompts/replay.md';
+    const repoRun = coordinatorState?.repo_runs?.[repoId] || {};
+    const defaultPhase = repoRun.phase || phases[0] || 'planning';
+    const routing = Object.fromEntries(
+      phases.map((phase) => [
+        phase,
+        {
+          entry_role: 'replay',
+          allowed_next_roles: ['replay', 'human'],
+        },
+      ]),
+    );
+    const config = {
+      schema_version: '1.0',
+      template: 'generic',
+      project: {
+        id: `${repoId}-replay-placeholder`,
+        name: `${repoId} Replay Placeholder`,
+      },
+      roles: {
+        replay: {
+          title: 'Replay Placeholder',
+          mandate: 'Preserve coordinator replay continuity when nested repo export is unavailable.',
+          write_authority: 'review_only',
+          runtime: 'replay-placeholder',
+        },
+      },
+      runtimes: {
+        'replay-placeholder': { type: 'manual' },
+      },
+      routing,
+      gates: {},
+      prompts: {
+        replay: promptPath,
+      },
+      rules: {
+        challenge_required: true,
+        max_turn_retries: 2,
+        max_deadlock_cycles: 2,
+      },
+    };
+    const state = {
+      schema_version: '1.1',
+      run_id: repoRun.run_id || null,
+      status: repoRun.status || 'blocked',
+      phase: defaultPhase,
+      active_turns: {},
+      turn_sequence: 0,
+      retained_turns: {},
+      budget_reservations: {},
+      phase_gate_status: {},
+    };
+
+    mkdirSync(join(repoRoot, '.agentxchain', 'prompts'), { recursive: true });
+    writeFileSync(join(repoRoot, 'agentxchain.json'), `${JSON.stringify(config, null, 2)}\n`);
+    writeFileSync(join(repoRoot, '.agentxchain', 'state.json'), `${JSON.stringify(state, null, 2)}\n`);
+    writeFileSync(join(repoRoot, '.agentxchain', 'history.jsonl'), '');
+    writeFileSync(join(repoRoot, '.agentxchain', 'events.jsonl'), '');
+    writeFileSync(join(repoRoot, '.agentxchain', 'decision-ledger.jsonl'), '');
+    writeFileSync(
+      join(repoRoot, promptPath),
+      '# Replay Placeholder\n\nThis repo export was unavailable in the coordinator artifact. Replay restores a placeholder so coordinator dashboards remain readable.\n',
+    );
+    restored += 6;
+  }
+
+  return restored;
+}
+
 export async function replayExportCommand(exportFile, opts = {}) {
   if (!exportFile) {
     console.error(chalk.red('Usage: agentxchain replay export <export-file>'));
@@ -51,21 +235,22 @@ export async function replayExportCommand(exportFile, opts = {}) {
     mkdirSync(tempRoot, { recursive: true });
     mkdirSync(tempAgentxchainDir, { recursive: true });
 
-    // Write all embedded files from the export
-    let fileCount = 0;
-    for (const [relPath, content] of Object.entries(exportData.files)) {
-      const absPath = join(tempRoot, relPath);
-      mkdirSync(dirname(absPath), { recursive: true });
-      writeFileSync(absPath, typeof content === 'string' ? content : JSON.stringify(content, null, 2));
-      fileCount++;
+    // Restore the real exported bytes for top-level files.
+    let fileCount = restoreExportFiles(tempRoot, exportData.files, 'files');
+
+    // Coordinator exports also need successful nested child repo exports
+    // rehydrated under their declared repo paths for dashboard replay.
+    if (exportData.export_kind === 'agentxchain_coordinator_export') {
+      fileCount += restoreCoordinatorRepos(tempRoot, exportData.repos);
+      fileCount += restoreFailedCoordinatorRepoStubs(tempRoot, exportData);
     }
 
     // Ensure agentxchain.json exists (needed by some dashboard endpoints)
     const configPath = join(tempRoot, 'agentxchain.json');
-    if (!existsSync(configPath)) {
+    if (exportData.export_kind !== 'agentxchain_coordinator_export' && !existsSync(configPath)) {
       // Synthesize a minimal config from export summary
       const minimalConfig = {
-        protocol_version: exportData.summary?.protocol_version || 6,
+        protocol_version: exportData.summary?.protocol_version || null,
         protocol_mode: 'governed',
         version: 4,
         project: { name: exportData.summary?.project_name || 'replay-export' },
@@ -153,6 +338,10 @@ export async function replayExportCommand(exportFile, opts = {}) {
       console.error(chalk.red(`Port ${opts.port || 3847} is already in use. Try --port <number>.`));
       process.exit(1);
     }
+    if (err instanceof Error) {
+      console.error(chalk.red(err.message));
+      process.exit(2);
+    }
     throw err;
   }
 }

package/src/lib/export-verifier.js

@@ -204,6 +204,244 @@ function verifyAggregatedEventsSummary(artifact, errors) {
   }
 }
 
+function buildExpectedDelegationSummary(files) {
+  const historyData = files?.['.agentxchain/history.jsonl']?.data;
+  if (!Array.isArray(historyData)) {
+    return null;
+  }
+
+  const parentTurns = new Map();
+  const childTurns = new Map();
+  const reviewTurns = new Map();
+
+  for (const entry of historyData) {
+    if (entry.delegations_issued && Array.isArray(entry.delegations_issued)) {
+      parentTurns.set(entry.turn_id, {
+        role: entry.role,
+        delegations_issued: entry.delegations_issued,
+      });
+    }
+    if (entry.delegation_context) {
+      childTurns.set(entry.delegation_context.delegation_id, {
+        turn_id: entry.turn_id,
+        status: entry.status || 'completed',
+      });
+    }
+    if (entry.delegation_review) {
+      reviewTurns.set(entry.delegation_review.parent_turn_id, {
+        turn_id: entry.turn_id,
+        results: entry.delegation_review.results || [],
+      });
+    }
+  }
+
+  let totalDelegationsIssued = 0;
+  const delegationChains = [];
+
+  for (const [parentTurnId, parent] of parentTurns) {
+    totalDelegationsIssued += parent.delegations_issued.length;
+
+    const review = reviewTurns.get(parentTurnId);
+    const reviewResultsByDelegation = new Map();
+    if (review) {
+      for (const r of review.results) {
+        if (r.delegation_id) {
+          reviewResultsByDelegation.set(r.delegation_id, r);
+        }
+      }
+    }
+
+    const delegations = parent.delegations_issued.map((del) => {
+      const child = childTurns.get(del.id);
+      const reviewResult = reviewResultsByDelegation.get(del.id);
+      return {
+        delegation_id: del.id,
+        to_role: del.to_role,
+        charter: del.charter,
+        required_decision_ids: Array.isArray(del.required_decision_ids) ? del.required_decision_ids : [],
+        satisfied_decision_ids: Array.isArray(reviewResult?.satisfied_decision_ids) ? reviewResult.satisfied_decision_ids : [],
+        missing_decision_ids: Array.isArray(reviewResult?.missing_decision_ids) ? reviewResult.missing_decision_ids : [],
+        status: reviewResult?.status || child?.status || 'pending',
+        child_turn_id: child?.turn_id || null,
+      };
+    });
+
+    let outcome;
+    if (!review) {
+      outcome = 'pending';
+    } else {
+      const statuses = delegations.map((d) => d.status);
+      const allCompleted = statuses.every((s) => s === 'completed');
+      const allFailed = statuses.every((s) => s === 'failed');
+      if (allCompleted) outcome = 'completed';
+      else if (allFailed) outcome = 'failed';
+      else outcome = 'mixed';
+    }
+
+    delegationChains.push({
+      parent_turn_id: parentTurnId,
+      parent_role: parent.role,
+      delegations,
+      review_turn_id: review?.turn_id || null,
+      outcome,
+    });
+  }
+
+  return {
+    total_delegations_issued: totalDelegationsIssued,
+    delegation_chains: delegationChains,
+  };
+}
+
+function verifyDelegationSummary(artifact, errors) {
+  const summary = artifact.summary?.delegation_summary;
+  const expected = buildExpectedDelegationSummary(artifact.files);
+
+  // Both absent — valid
+  if (summary == null && expected == null) {
+    return;
+  }
+
+  // One present, one absent — mismatch
+  if (summary == null && expected != null) {
+    if (expected.total_delegations_issued > 0) {
+      addError(errors, 'summary.delegation_summary', 'is null but history.jsonl contains delegation entries');
+    }
+    return;
+  }
+  if (summary != null && expected == null) {
+    addError(errors, 'summary.delegation_summary', 'claims delegations but no history.jsonl in export');
+    return;
+  }
+
+  if (summary.total_delegations_issued !== expected.total_delegations_issued) {
+    addError(errors, 'summary.delegation_summary.total_delegations_issued', 'must match reconstructed delegation count');
+  }
+
+  if (!isDeepStrictEqual(summary.delegation_chains, expected.delegation_chains)) {
+    addError(errors, 'summary.delegation_summary.delegation_chains', 'must match reconstructed delegation chains from history.jsonl');
+  }
+}
+
+function buildExpectedRepoDecisionsSummary(files) {
+  const repoDecisionsData = files?.['.agentxchain/repo-decisions.jsonl']?.data;
+  if (!Array.isArray(repoDecisionsData) || repoDecisionsData.length === 0) {
+    return null;
+  }
+
+  const active = repoDecisionsData.filter((d) => d.status === 'active');
+  const overridden = repoDecisionsData.filter((d) => d.status === 'overridden');
+
+  return {
+    total: repoDecisionsData.length,
+    active_count: active.length,
+    overridden_count: overridden.length,
+    active: active.map((d) => ({
+      id: d.id,
+      category: d.category,
+      statement: d.statement,
+      role: d.role,
+      run_id: d.run_id,
+    })),
+    overridden: overridden.map((d) => ({
+      id: d.id,
+      overridden_by: d.overridden_by,
+      statement: d.statement,
+    })),
+  };
+}
+
+function verifyRepoDecisionsSummary(artifact, errors) {
+  const summary = artifact.summary?.repo_decisions;
+  const hasFile = '.agentxchain/repo-decisions.jsonl' in (artifact.files || {});
+  const expected = buildExpectedRepoDecisionsSummary(artifact.files);
+
+  if (summary === null && expected === null) {
+    return;
+  }
+  if (summary === undefined && expected === null) {
+    return;
+  }
+
+  if (summary !== null && summary !== undefined && !hasFile && expected === null) {
+    addError(errors, 'summary.repo_decisions', 'claims repo decisions but no .agentxchain/repo-decisions.jsonl in export');
+    return;
+  }
+
+  if (summary === null && expected !== null) {
+    addError(errors, 'summary.repo_decisions', 'is null but repo-decisions.jsonl contains entries');
+    return;
+  }
+
+  if (summary !== null && expected === null) {
+    addError(errors, 'summary.repo_decisions', 'claims repo decisions but repo-decisions.jsonl is empty');
+    return;
+  }
+
+  if (summary.total !== expected.total) {
+    addError(errors, 'summary.repo_decisions.total', 'must match reconstructed repo decision count');
+  }
+  if (summary.active_count !== expected.active_count) {
+    addError(errors, 'summary.repo_decisions.active_count', 'must match reconstructed active count');
+  }
+  if (summary.overridden_count !== expected.overridden_count) {
+    addError(errors, 'summary.repo_decisions.overridden_count', 'must match reconstructed overridden count');
+  }
+  if (!isDeepStrictEqual(summary.active, expected.active)) {
+    addError(errors, 'summary.repo_decisions.active', 'must match reconstructed active decisions from repo-decisions.jsonl');
+  }
+  if (!isDeepStrictEqual(summary.overridden, expected.overridden)) {
+    addError(errors, 'summary.repo_decisions.overridden', 'must match reconstructed overridden decisions from repo-decisions.jsonl');
+  }
+}
+
+const VALID_DASHBOARD_STATUSES = new Set(['running', 'pid_only', 'stale', 'not_running']);
+
+function verifyDashboardSessionSummary(artifact, errors) {
+  const session = artifact.summary?.dashboard_session;
+  if (session === undefined) {
+    return;
+  }
+
+  if (session === null || typeof session !== 'object' || Array.isArray(session)) {
+    addError(errors, 'summary.dashboard_session', 'must be an object when present');
+    return;
+  }
+
+  if (!VALID_DASHBOARD_STATUSES.has(session.status)) {
+    addError(errors, 'summary.dashboard_session.status', `must be one of: ${[...VALID_DASHBOARD_STATUSES].join(', ')}`);
+    return;
+  }
+
+  if (session.pid !== null && (!Number.isInteger(session.pid) || session.pid <= 0)) {
+    addError(errors, 'summary.dashboard_session.pid', 'must be a positive integer or null');
+  }
+
+  if (session.url !== null && typeof session.url !== 'string') {
+    addError(errors, 'summary.dashboard_session.url', 'must be a string or null');
+  }
+
+  if (session.started_at !== null && (typeof session.started_at !== 'string' || Number.isNaN(Date.parse(session.started_at)))) {
+    addError(errors, 'summary.dashboard_session.started_at', 'must be a valid ISO timestamp or null');
+  }
+
+  if (session.status === 'not_running') {
+    if (session.pid !== null) {
+      addError(errors, 'summary.dashboard_session.pid', 'must be null when status is not_running');
+    }
+    if (session.url !== null) {
+      addError(errors, 'summary.dashboard_session.url', 'must be null when status is not_running');
+    }
+    if (session.started_at !== null) {
+      addError(errors, 'summary.dashboard_session.started_at', 'must be null when status is not_running');
+    }
+  }
+
+  if (session.status === 'running' && (session.pid === null || !Number.isInteger(session.pid) || session.pid <= 0)) {
+    addError(errors, 'summary.dashboard_session.pid', 'must be a positive integer when status is running');
+  }
+}
+
 function countJsonl(files, relPath) {
   return Array.isArray(files?.[relPath]?.data) ? files[relPath].data.length : 0;
 }
@@ -334,6 +572,10 @@ function verifyRunExport(artifact, errors) {
   if (artifact.summary.coordinator_present !== expectedCoordinatorPresent) {
     addError(errors, 'summary.coordinator_present', 'must match multirepo file presence');
   }
+
+  verifyDelegationSummary(artifact, errors);
+  verifyRepoDecisionsSummary(artifact, errors);
+  verifyDashboardSessionSummary(artifact, errors);
 }
 
 function verifyCoordinatorExport(artifact, errors) {

package/src/lib/protocol-version.js

@@ -1,4 +1,4 @@
-export const CURRENT_PROTOCOL_VERSION = 'v6';
+export const CURRENT_PROTOCOL_VERSION = 'v7';
 export const CURRENT_CONFIG_GENERATION = 4;
 
 export function getGovernedConfigSchemaVersion(rawConfig) {

package/src/lib/reference-conformance-adapter.js

@@ -14,6 +14,7 @@ import { finalizeDispatchManifest, verifyDispatchManifest } from './dispatch-man
 import { getDispatchTurnDir } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
 import { validateCoordinatorConfig, normalizeCoordinatorConfig } from './coordinator-config.js';
+import { VALID_RUN_EVENTS, emitRunEvent } from './run-events.js';
 import { projectRepoAcceptance, evaluateBarriers } from './coordinator-acceptance.js';
 import { readBarriers, saveCoordinatorState, readCoordinatorHistory } from './coordinator-state.js';
 
@@ -96,6 +97,11 @@ function validateFixtureConfig(config) {
     if (route.exit_gate && !config.gates?.[route.exit_gate]) {
       errors.push(`Routing references unknown gate: "${route.exit_gate}"`);
     }
+    if ('max_concurrent_turns' in route) {
+      if (!Number.isInteger(route.max_concurrent_turns) || route.max_concurrent_turns < 1 || route.max_concurrent_turns > 4) {
+        errors.push(`Routing "${phase}": max_concurrent_turns must be an integer between 1 and 4`);
+      }
+    }
   }
 
   return errors;
@@ -853,6 +859,75 @@ function executeFixtureOperation(workspace, fixture) {
       };
     }
 
+    // ── Tier 1: Event Lifecycle ──────────────────────────────────────────
+
+    case 'validate_event': {
+      const event = fixture.input.args.event;
+      const errors = [];
+      if (!event || typeof event !== 'object') {
+        return { result: 'error', error_type: 'invalid_event', errors: ['Event must be an object'] };
+      }
+      if (typeof event.event_id !== 'string' || !event.event_id.trim()) {
+        errors.push('event_id must be a non-empty string');
+      }
+      if (!VALID_RUN_EVENTS.includes(event.event_type)) {
+        errors.push(`event_type must be one of: ${VALID_RUN_EVENTS.join(', ')}`);
+      }
+      if (typeof event.timestamp !== 'string' || Number.isNaN(Date.parse(event.timestamp))) {
+        errors.push('timestamp must be a valid ISO-8601 string');
+      }
+      // Turn-scoped events must have turn.turn_id
+      const turnScopedEvents = ['turn_dispatched', 'turn_accepted', 'turn_rejected'];
+      if (turnScopedEvents.includes(event.event_type)) {
+        if (!event.turn?.turn_id || typeof event.turn.turn_id !== 'string' || !event.turn.turn_id.trim()) {
+          errors.push(`${event.event_type} requires a non-empty turn.turn_id`);
+        }
+      }
+      if (errors.length > 0) {
+        return { result: 'error', error_type: 'invalid_event', errors };
+      }
+      return { result: 'success', errors: [] };
+    }
+
+    case 'validate_event_ordering': {
+      const events = fixture.input.args.events;
+      const errors = [];
+      if (!Array.isArray(events) || events.length === 0) {
+        return { result: 'error', error_type: 'invalid_events', errors: ['Events must be a non-empty array'] };
+      }
+      // run_started must be first
+      if (events[0].event_type !== 'run_started') {
+        errors.push('First event must be run_started');
+      }
+      // run_completed must be last (if present)
+      const lastEvent = events[events.length - 1];
+      if (events.some((e) => e.event_type === 'run_completed') && lastEvent.event_type !== 'run_completed') {
+        errors.push('run_completed must be the last event');
+      }
+      // turn_dispatched must precede turn_accepted for same turn
+      const dispatchedTurns = new Map();
+      for (const event of events) {
+        if (event.event_type === 'turn_dispatched' && event.turn?.turn_id) {
+          dispatchedTurns.set(event.turn.turn_id, true);
+        }
+        if (event.event_type === 'turn_accepted' && event.turn?.turn_id) {
+          if (!dispatchedTurns.has(event.turn.turn_id)) {
+            errors.push(`turn_accepted for ${event.turn.turn_id} without preceding turn_dispatched`);
+          }
+        }
+      }
+      // Timestamps must be monotonically non-decreasing
+      for (let i = 1; i < events.length; i++) {
+        if (new Date(events[i].timestamp) < new Date(events[i - 1].timestamp)) {
+          errors.push(`Event ${i} timestamp is before event ${i - 1}`);
+        }
+      }
+      if (errors.length > 0) {
+        return { result: 'error', error_type: 'ordering_violation', errors };
+      }
+      return { result: 'success', errors: [] };
+    }
+
     default:
       return { result: 'error', error_type: 'unsupported_operation', operation };
   }