agentxchain 2.103.0 → 2.105.0

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

@@ -0,0 +1,50 @@
+import { loadCoordinatorConfig } from '../coordinator-config.js';
+import { buildCoordinatorRepoStatusRows } from '../coordinator-repo-status-presentation.js';
+import { loadCoordinatorState } from '../coordinator-state.js';
+
+function getConfigErrorResponse(errors) {
+  const issueList = Array.isArray(errors) ? errors : [];
+  const missing = issueList.some((error) => typeof error === 'string' && error.startsWith('config_missing:'));
+
+  return {
+    ok: false,
+    status: missing ? 404 : 422,
+    body: {
+      ok: false,
+      code: missing ? 'coordinator_config_missing' : 'coordinator_config_invalid',
+      error: missing
+        ? 'Coordinator config not found. Run `agentxchain multi init` first.'
+        : 'Coordinator config is invalid.',
+      errors: issueList,
+    },
+  };
+}
+
+export function readCoordinatorRepoStatusRows(workspacePath) {
+  const configResult = loadCoordinatorConfig(workspacePath);
+  if (!configResult.ok) {
+    return getConfigErrorResponse(configResult.errors);
+  }
+
+  const state = loadCoordinatorState(workspacePath);
+  if (!state) {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'coordinator_state_missing',
+        error: 'Coordinator state not found. Run `agentxchain multi init` first.',
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: 200,
+    body: buildCoordinatorRepoStatusRows({
+      config: configResult.config,
+      coordinatorRepoRuns: state.repo_runs || {},
+    }),
+  };
+}

package/src/lib/dashboard/coordinator-timeout-status.js

@@ -1,6 +1,7 @@
 import { join } from 'path';
 import { loadProjectContext, loadProjectState } from '../config.js';
 import { loadCoordinatorConfig } from '../coordinator-config.js';
+import { buildCoordinatorRepoStatusRows } from '../coordinator-repo-status-presentation.js';
 import { loadCoordinatorState } from '../coordinator-state.js';
 import { readJsonlFile } from './state-reader.js';
 import { buildTimeoutConfigSummary, evaluateDashboardTimeoutPressure, extractTimeoutEvents } from './timeout-status.js';
@@ -27,15 +28,26 @@ function emptyLiveTimeouts() {
   return { exceeded: [], warnings: [] };
 }
 
-function readRepoTimeoutSnapshot(repoId, repo, repoRun) {
+function getRepoStatusPresentation(repoStatusRow) {
+  return {
+    run_id: repoStatusRow?.run_id ?? null,
+    status: repoStatusRow?.status ?? null,
+    phase: repoStatusRow?.phase ?? null,
+    details: Array.isArray(repoStatusRow?.details) ? repoStatusRow.details : [],
+  };
+}
+
+function readRepoTimeoutSnapshot(repoId, repo, repoStatusRow) {
+  const presentation = getRepoStatusPresentation(repoStatusRow);
   const context = loadProjectContext(repo.resolved_path);
   if (!context) {
     return {
       repo_id: repoId,
       path: repo.path,
-      run_id: repoRun?.run_id ?? null,
-      status: repoRun?.status ?? null,
-      phase: repoRun?.phase ?? null,
+      run_id: presentation.run_id,
+      status: presentation.status,
+      phase: presentation.phase,
+      details: presentation.details,
       configured: false,
       config: null,
       live: null,
@@ -56,9 +68,10 @@ function readRepoTimeoutSnapshot(repoId, repo, repoRun) {
     return {
       repo_id: repoId,
       path: repo.path,
-      run_id: repoRun?.run_id ?? null,
-      status: repoRun?.status ?? null,
-      phase: repoRun?.phase ?? null,
+      run_id: presentation.run_id,
+      status: presentation.status,
+      phase: presentation.phase,
+      details: presentation.details,
       configured,
       config: buildTimeoutConfigSummary(context.config.timeouts, context.config.routing),
       live: configured ? emptyLiveTimeouts() : null,
@@ -77,9 +90,10 @@ function readRepoTimeoutSnapshot(repoId, repo, repoRun) {
   return {
     repo_id: repoId,
     path: repo.path,
-    run_id: state.run_id ?? repoRun?.run_id ?? null,
-    status: state.status ?? repoRun?.status ?? null,
-    phase: state.phase ?? repoRun?.phase ?? null,
+    run_id: presentation.run_id,
+    status: presentation.status,
+    phase: presentation.phase,
+    details: presentation.details,
     configured,
     config: buildTimeoutConfigSummary(context.config.timeouts, context.config.routing),
     live,
@@ -109,8 +123,17 @@ export function readCoordinatorTimeoutStatus(workspacePath) {
 
   const coordinatorDir = join(workspacePath, '.agentxchain', 'multirepo');
   const coordinatorEvents = extractTimeoutEvents(readJsonlFile(coordinatorDir, 'decision-ledger.jsonl'));
+  const repoStatusRows = buildCoordinatorRepoStatusRows({
+    config: configResult.config,
+    coordinatorRepoRuns: coordinatorState.repo_runs || {},
+  });
+  const repoStatusById = new Map(repoStatusRows.map((row) => [row.repo_id, row]));
   const repos = configResult.config.repo_order.map((repoId) => (
-    readRepoTimeoutSnapshot(repoId, configResult.config.repos[repoId], coordinatorState.repo_runs?.[repoId] ?? null)
+    readRepoTimeoutSnapshot(
+      repoId,
+      configResult.config.repos[repoId],
+      repoStatusById.get(repoId) ?? null,
+    )
   ));
 
   const summary = {

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

@@ -8,13 +8,20 @@
 
 import { readFileSync, existsSync } from 'fs';
 import { join, normalize, resolve } from 'path';
+import {
+  deriveGovernedRunNextActions,
+  deriveRuntimeBlockedGuidance,
+} from '../blocked-state.js';
+import { loadProjectContext } from '../config.js';
 import { getContinuityStatus } from '../continuity-status.js';
+import { readRepoDecisions, summarizeRepoDecisions } from '../repo-decisions.js';
 
 const STATE_FILE = 'state.json';
 const SESSION_FILE = 'session.json';
 const SESSION_RECOVERY_FILE = 'SESSION_RECOVERY.md';
 const HISTORY_FILE = 'history.jsonl';
 const LEDGER_FILE = 'decision-ledger.jsonl';
+const REPO_DECISIONS_FILE = 'repo-decisions.jsonl';
 const HOOK_AUDIT_FILE = 'hook-audit.jsonl';
 const HOOK_ANNOTATIONS_FILE = 'hook-annotations.jsonl';
 const EVENTS_FILE = 'events.jsonl';
@@ -50,6 +57,7 @@ export const FILE_TO_RESOURCE = Object.fromEntries(
 );
 FILE_TO_RESOURCE[normalizeRelativePath(SESSION_RECOVERY_FILE)] = '/api/continuity';
 FILE_TO_RESOURCE[normalizeRelativePath('run-history.jsonl')] = '/api/run-history';
+FILE_TO_RESOURCE[normalizeRelativePath(REPO_DECISIONS_FILE)] = '/api/repo-decisions-summary';
 
 export const WATCH_DIRECTORIES = [
   '',
@@ -88,6 +96,24 @@ export function readJsonlFile(agentxchainDir, filename) {
   return content.split('\n').filter(line => line.trim()).map(line => JSON.parse(line));
 }
 
+function enrichGovernedState(agentxchainDir, state) {
+  if (!state || typeof state !== 'object') {
+    return state;
+  }
+
+  const workspacePath = resolve(agentxchainDir, '..');
+  const context = loadProjectContext(workspacePath);
+  if (!context || context.config?.protocol_mode !== 'governed') {
+    return state;
+  }
+
+  return {
+    ...state,
+    runtime_guidance: deriveRuntimeBlockedGuidance(state, context.config),
+    next_actions: deriveGovernedRunNextActions(state, context.config),
+  };
+}
+
 /**
  * Read a resource by its API path. Returns { data, format } or null.
  */
@@ -98,6 +124,12 @@ export function readResource(agentxchainDir, resourcePath) {
     const data = getContinuityStatus(root, state);
     return { data, format: 'json' };
   }
+  if (resourcePath === '/api/repo-decisions-summary') {
+    const root = resolve(agentxchainDir, '..');
+    const context = loadProjectContext(root);
+    const data = summarizeRepoDecisions(readRepoDecisions(root), context?.config || null);
+    return { data, format: 'json' };
+  }
 
   const filename = RESOURCE_MAP[resourcePath];
   if (!filename) return null;
@@ -106,6 +138,9 @@ export function readResource(agentxchainDir, resourcePath) {
     const data = readJsonlFile(agentxchainDir, filename);
     return data !== null ? { data, format: 'jsonl' } : null;
   }
-  const data = readJsonFile(agentxchainDir, filename);
+  let data = readJsonFile(agentxchainDir, filename);
+  if (resourcePath === '/api/state') {
+    data = enrichGovernedState(agentxchainDir, data);
+  }
   return data !== null ? { data, format: 'json' } : null;
 }

package/src/lib/dispatch-bundle.js

@@ -29,6 +29,7 @@ import {
   getDispatchTurnDir,
   getTurnStagingResultPath,
 } from './turn-paths.js';
+import { getRoleRuntimeCapabilityContract } from './runtime-capabilities.js';
 
 const HISTORY_PATH = '.agentxchain/history.jsonl';
 const LEDGER_PATH = '.agentxchain/decision-ledger.jsonl';
@@ -183,6 +184,7 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   }
 
   const lines = [];
+  const runtimeContract = getRoleRuntimeCapabilityContract(roleId, role, runtime);
 
   // Identity block
   lines.push(`# Turn Assignment: ${role.title} (${roleId})`);
@@ -511,6 +513,8 @@ function getWorkflowPromptResponsibilities(config, phase, roleId, root) {
 function renderContext(state, config, root, turn, role) {
   const warnings = [];
   const lines = [];
+  const runtime = config.runtimes?.[turn.runtime_id];
+  const runtimeContract = getRoleRuntimeCapabilityContract(turn.assigned_role, role, runtime);
 
   lines.push('# Execution Context');
   lines.push('');
@@ -616,6 +620,25 @@ function renderContext(state, config, root, turn, role) {
     lines.push('');
   }
 
+  lines.push('## Runtime Capability Contract');
+  lines.push('');
+  lines.push(`- **Runtime:** ${turn.runtime_id} (${runtimeContract.runtime_contract.runtime_type})`);
+  lines.push(`- **Transport:** ${runtimeContract.runtime_contract.transport}`);
+  lines.push(`- **Can write files:** ${runtimeContract.runtime_contract.can_write_files}`);
+  lines.push(`- **Review/manual behavior:** ${runtimeContract.runtime_contract.review_only_behavior}`);
+  lines.push(`- **Proposal support:** ${runtimeContract.runtime_contract.proposal_support}`);
+  lines.push(`- **Requires local binary:** ${runtimeContract.runtime_contract.requires_local_binary ? 'yes' : 'no'}`);
+  lines.push(`- **Workflow artifact ownership:** ${runtimeContract.runtime_contract.workflow_artifact_ownership}`);
+  lines.push(`- **Effective write path for this role:** ${runtimeContract.effective_write_path}`);
+  lines.push(`- **Effective workflow artifact ownership for this role:** ${runtimeContract.workflow_artifact_ownership}`);
+  if (runtimeContract.notes.length > 0) {
+    lines.push('- **Notes:**');
+    for (const note of runtimeContract.notes) {
+      lines.push(`  - ${note}`);
+    }
+  }
+  lines.push('');
+
   // Repo-level decisions that persist across runs
   if (state.repo_decisions && state.repo_decisions.length > 0) {
     const repoDecMd = renderRepoDecisionsMarkdown(state.repo_decisions, config);

package/src/lib/export-diff.js

@@ -1,7 +1,9 @@
 import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
+import { buildCoordinatorRepoStatusEntries } from './coordinator-repo-status-presentation.js';
 
 const FAILED_STATUSES = new Set(['failed', 'error', 'crashed']);
+const BLOCKED_OR_FAILED_STATUSES = new Set(['blocked', 'failed', 'error', 'crashed']);
 
 const RUN_EXPORT_SCALAR_FIELDS = [
   ['run_id', 'Run ID'],
@@ -151,7 +153,7 @@ function buildCoordinatorExportDiff(leftArtifact, rightArtifact, refs) {
     repo_ids: buildListChange('Repos', left.repo_ids, right.repo_ids),
     repos_with_events: buildListChange('Repos with events', left.repos_with_events, right.repos_with_events),
   };
-  const repo_status_changes = buildMapChanges('Repo status', left.repo_run_statuses, right.repo_run_statuses);
+  const repo_status_changes = buildMapChanges('Repo status', left.repo_statuses, right.repo_statuses);
   const repo_export_changes = buildBooleanMapChanges('Repo export ok', left.repo_export_status, right.repo_export_status);
   const event_type_changes = buildNumericMapChanges('Event type', left.event_type_counts, right.event_type_counts);
 
@@ -221,8 +223,8 @@ function normalizeRunExport(artifact) {
 function normalizeCoordinatorExport(artifact) {
   const summary = artifact.summary || {};
   const aggregatedEvents = summary.aggregated_events || {};
-  const repoRunStatuses = summary.repo_run_statuses || {};
   const repos = artifact.repos || {};
+  const repoStatusEntries = buildCoordinatorExportRepoStatusEntries(artifact);
 
   return {
     export_kind: artifact.export_kind,
@@ -235,9 +237,16 @@ function normalizeCoordinatorExport(artifact) {
     history_entries: toNumber(summary.history_entries),
     decision_entries: toNumber(summary.decision_entries),
     total_events: toNumber(aggregatedEvents.total_events),
-    repo_ids: normalizeStringArray(Object.keys(repos)),
+    repo_ids: normalizeStringArray(repoStatusEntries.map((entry) => entry.repo_id)),
     repos_with_events: normalizeStringArray(aggregatedEvents.repos_with_events),
-    repo_run_statuses: normalizeStringMap(repoRunStatuses),
+    repo_statuses: normalizeStringMap(Object.fromEntries(
+      repoStatusEntries.map((entry) => [entry.repo_id, entry.status]),
+    )),
+    coordinator_repo_statuses: normalizeStringMap(Object.fromEntries(
+      repoStatusEntries
+        .filter((entry) => entry.coordinator_status != null)
+        .map((entry) => [entry.repo_id, entry.coordinator_status]),
+    )),
     repo_export_status: normalizeBooleanMap(Object.fromEntries(
       Object.entries(repos).map(([repoId, repoEntry]) => [repoId, repoEntry?.ok === true]),
     )),
@@ -245,6 +254,26 @@ function normalizeCoordinatorExport(artifact) {
   };
 }
 
+function buildCoordinatorExportRepoStatusEntries(artifact) {
+  const summaryRepoStatuses = artifact.summary?.repo_run_statuses || {};
+  const coordinatorRepoRuns = Object.fromEntries(
+    Object.entries(summaryRepoStatuses).map(([repoId, status]) => [repoId, { status: status || null }]),
+  );
+  const repoSnapshots = Object.entries(artifact.repos || {}).map(([repoId, repoEntry]) => ({
+    repo_id: repoId,
+    ok: repoEntry?.ok === true,
+    status: repoEntry?.ok ? (repoEntry.export?.summary?.status ?? null) : null,
+    run_id: repoEntry?.ok ? (repoEntry.export?.summary?.run_id ?? null) : null,
+    phase: repoEntry?.ok ? (repoEntry.export?.summary?.phase ?? null) : null,
+  }));
+
+  return buildCoordinatorRepoStatusEntries({
+    config: artifact.config,
+    coordinatorRepoRuns,
+    repoSnapshots,
+  });
+}
+
 function buildFieldChanges(left, right, fields) {
   return Object.fromEntries(
     fields.map(([field, label]) => [field, {
@@ -402,8 +431,8 @@ function detectRunRegressions(left, right) {
   const regressions = [];
   let counter = 0;
 
-  // Status regression: completed/active -> failed/error/crashed
-  if (left.status && right.status && !FAILED_STATUSES.has(left.status) && FAILED_STATUSES.has(right.status)) {
+  // Status regression: successful/non-terminal -> blocked/failed/error/crashed
+  if (left.status && right.status && !BLOCKED_OR_FAILED_STATUSES.has(left.status) && BLOCKED_OR_FAILED_STATUSES.has(right.status)) {
     regressions.push({
       id: `REG-STATUS-${String(++counter).padStart(3, '0')}`,
       category: 'status',
@@ -553,40 +582,43 @@ function detectCoordinatorRegressions(left, right) {
   // Start with the run-level regressions that apply to coordinator summaries
   const regressions = detectRunRegressions(left, right);
   let counter = regressions.length;
-
-  // Repo status regressions: child repo completed -> failed
-  const allRepoIds = new Set([...Object.keys(left.repo_run_statuses || {}), ...Object.keys(right.repo_run_statuses || {})]);
-  for (const repoId of allRepoIds) {
-    const leftStatus = (left.repo_run_statuses || {})[repoId] || null;
-    const rightStatus = (right.repo_run_statuses || {})[repoId] || null;
-    if (leftStatus && rightStatus && !FAILED_STATUSES.has(leftStatus) && FAILED_STATUSES.has(rightStatus)) {
-      regressions.push({
-        id: `REG-REPO-STATUS-${String(++counter).padStart(3, '0')}`,
-        category: 'repo_status',
-        severity: 'error',
-        message: `Child repo "${repoId}" status regressed from ${leftStatus} to ${rightStatus}`,
-        field: `repo_run_statuses.${repoId}`,
-        left: leftStatus,
-        right: rightStatus,
-      });
+  const terminalComparison = left.status === 'completed' && right.status === 'completed';
+
+  // Repo status regressions: child repo success/non-terminal -> blocked/failed
+  if (!terminalComparison) {
+    const allRepoIds = new Set([...Object.keys(left.repo_statuses || {}), ...Object.keys(right.repo_statuses || {})]);
+    for (const repoId of allRepoIds) {
+      const leftStatus = (left.repo_statuses || {})[repoId] || null;
+      const rightStatus = (right.repo_statuses || {})[repoId] || null;
+      if (leftStatus && rightStatus && !BLOCKED_OR_FAILED_STATUSES.has(leftStatus) && BLOCKED_OR_FAILED_STATUSES.has(rightStatus)) {
+        regressions.push({
+          id: `REG-REPO-STATUS-${String(++counter).padStart(3, '0')}`,
+          category: 'repo_status',
+          severity: 'error',
+          message: `Child repo "${repoId}" status regressed from ${leftStatus} to ${rightStatus}`,
+          field: `repo_statuses.${repoId}`,
+          left: leftStatus,
+          right: rightStatus,
+        });
+      }
     }
-  }
 
-  // Repo export regressions: ok true -> false
-  const allExportRepoIds = new Set([...Object.keys(left.repo_export_status || {}), ...Object.keys(right.repo_export_status || {})]);
-  for (const repoId of allExportRepoIds) {
-    const leftOk = (left.repo_export_status || {})[repoId];
-    const rightOk = (right.repo_export_status || {})[repoId];
-    if (leftOk === true && rightOk === false) {
-      regressions.push({
-        id: `REG-REPO-EXPORT-${String(++counter).padStart(3, '0')}`,
-        category: 'repo_export',
-        severity: 'error',
-        message: `Child repo "${repoId}" export regressed from ok to failed`,
-        field: `repo_export_status.${repoId}`,
-        left: true,
-        right: false,
-      });
+    // Repo export regressions: ok true -> false
+    const allExportRepoIds = new Set([...Object.keys(left.repo_export_status || {}), ...Object.keys(right.repo_export_status || {})]);
+    for (const repoId of allExportRepoIds) {
+      const leftOk = (left.repo_export_status || {})[repoId];
+      const rightOk = (right.repo_export_status || {})[repoId];
+      if (leftOk === true && rightOk === false) {
+        regressions.push({
+          id: `REG-REPO-EXPORT-${String(++counter).padStart(3, '0')}`,
+          category: 'repo_export',
+          severity: 'error',
+          message: `Child repo "${repoId}" export regressed from ok to failed`,
+          field: `repo_export_status.${repoId}`,
+          left: true,
+          right: false,
+        });
+      }
     }
   }
 

package/src/lib/export-verifier.js

@@ -420,6 +420,9 @@ function verifyRepoDecisionsSummary(artifact, errors) {
   if (!isDeepStrictEqual(summary.overridden, expected.overridden)) {
     addError(errors, 'summary.repo_decisions.overridden', 'must match reconstructed overridden decisions from repo-decisions.jsonl');
   }
+  if (!isDeepStrictEqual(summary.operator_summary, expected.operator_summary)) {
+    addError(errors, 'summary.repo_decisions.operator_summary', 'must match reconstructed repo decision operator summary');
+  }
 }
 
 const VALID_DASHBOARD_STATUSES = new Set(['running', 'pid_only', 'stale', 'not_running']);