agentxchain 2.91.0 → 2.92.0

package/package.json

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

package/src/commands/doctor.js

@@ -5,6 +5,7 @@ import chalk from 'chalk';
 import { loadConfig, loadLock, findProjectRoot } from '../lib/config.js';
 import { validateProject } from '../lib/validation.js';
 import { getWatchPid } from './watch.js';
+import { getDashboardPid, getDashboardSession } from './dashboard.js';
 import { loadNormalizedConfig, detectConfigVersion } from '../lib/normalized-config.js';
 import { readDaemonState, evaluateDaemonStatus } from '../lib/run-schedule.js';
 import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
@@ -219,6 +220,21 @@ function governedDoctor(root, rawConfig, opts) {
     }
   }
 
+  // 9. Dashboard session health (unconditional — dashboard is a general operator surface)
+  {
+    const dashPid = getDashboardPid(root);
+    const dashSession = getDashboardSession(root);
+    if (dashPid && dashSession) {
+      checks.push({ id: 'dashboard_session', name: 'Dashboard session', level: 'pass', detail: `Dashboard running at ${dashSession.url} (PID: ${dashPid})` });
+    } else if (dashPid && !dashSession) {
+      checks.push({ id: 'dashboard_session', name: 'Dashboard session', level: 'warn', detail: `Dashboard PID ${dashPid} alive but session file missing` });
+    } else if (!dashPid && dashSession) {
+      checks.push({ id: 'dashboard_session', name: 'Dashboard session', level: 'warn', detail: `Stale dashboard session files (PID ${dashSession.pid || '?'} not running)` });
+    } else {
+      checks.push({ id: 'dashboard_session', name: 'Dashboard session', level: 'info', detail: 'No dashboard session' });
+    }
+  }
+
   // Compute summary
   const failCount = checks.filter(c => c.level === 'fail').length;
   const warnCount = checks.filter(c => c.level === 'warn').length;
@@ -253,7 +269,9 @@ function governedDoctor(root, rawConfig, opts) {
         ? chalk.green('PASS')
         : c.level === 'warn'
           ? chalk.yellow('WARN')
-          : chalk.red('FAIL');
+          : c.level === 'info'
+            ? chalk.dim('INFO')
+            : chalk.red('FAIL');
       console.log(`  ${badge}  ${c.name.padEnd(24)} ${chalk.dim(c.detail)}`);
     }
 

package/src/commands/status.js

@@ -9,6 +9,7 @@ import { getConnectorHealth } from '../lib/connector-health.js';
 import { deriveWorkflowKitArtifacts } from '../lib/workflow-kit-artifacts.js';
 import { evaluateTimeouts } from '../lib/timeout-evaluator.js';
 import { summarizeRunProvenance } from '../lib/run-provenance.js';
+import { getDashboardPid, getDashboardSession } from './dashboard.js';
 
 export async function statusCommand(opts) {
   const context = loadProjectContext();
@@ -87,6 +88,14 @@ function renderGovernedStatus(context, opts) {
   const workflowKitArtifacts = deriveWorkflowKitArtifacts(root, config, state);
 
   if (opts.json) {
+    const dashPid = getDashboardPid(root);
+    const dashSession = getDashboardSession(root);
+    const dashboardSessionObj = dashPid
+      ? { status: 'running', pid: dashPid, url: dashSession?.url || null, started_at: dashSession?.started_at || null }
+      : dashSession
+        ? { status: 'stale', pid: dashSession.pid || null, url: dashSession.url || null, started_at: dashSession.started_at || null }
+        : { status: 'not_running', pid: null, url: null, started_at: null };
+
     console.log(JSON.stringify({
       version,
       protocol_mode: config.protocol_mode,
@@ -99,6 +108,7 @@ function renderGovernedStatus(context, opts) {
       continuity,
       connector_health: connectorHealth,
       workflow_kit_artifacts: workflowKitArtifacts,
+      dashboard_session: dashboardSessionObj,
     }, null, 2));
     return;
   }

package/src/lib/adapters/local-cli-adapter.js

@@ -115,7 +115,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       child = spawn(command, args, {
         cwd: runtime.cwd ? join(root, runtime.cwd) : root,
         stdio: ['pipe', 'pipe', 'pipe'],
-        env: { ...process.env },
+        env: { ...process.env, AGENTXCHAIN_TURN_ID: turn.turn_id },
       });
     } catch (err) {
       resolve({ ok: false, error: `Failed to spawn "${command}": ${err.message}`, logs });

package/src/lib/export.js

@@ -7,6 +7,7 @@ import { loadProjectContext, loadProjectState } from './config.js';
 import { loadCoordinatorConfig, COORDINATOR_CONFIG_FILE } from './coordinator-config.js';
 import { loadCoordinatorState } from './coordinator-state.js';
 import { normalizeRunProvenance } from './run-provenance.js';
+import { getDashboardPid, getDashboardSession } from '../commands/dashboard.js';
 
 const EXPORT_SCHEMA_VERSION = '0.3';
 
@@ -23,6 +24,8 @@ const COORDINATOR_INCLUDED_ROOTS = [
 export const RUN_EXPORT_INCLUDED_ROOTS = [
   'agentxchain.json',
   'TALK.md',
+  '.agentxchain-dashboard.pid',
+  '.agentxchain-dashboard.json',
   '.agentxchain/state.json',
   '.agentxchain/session.json',
   '.agentxchain/history.jsonl',
@@ -166,6 +169,45 @@ function countDirectoryFiles(files, prefix) {
   return Object.keys(files).filter((path) => path.startsWith(`${prefix}/`)).length;
 }
 
+function buildDashboardSessionSummary(root) {
+  const dashPid = getDashboardPid(root);
+  const dashSession = getDashboardSession(root);
+
+  if (dashPid && dashSession) {
+    return {
+      status: 'running',
+      pid: dashPid,
+      url: dashSession.url || null,
+      started_at: dashSession.started_at || null,
+    };
+  }
+
+  if (dashPid && !dashSession) {
+    return {
+      status: 'pid_only',
+      pid: dashPid,
+      url: null,
+      started_at: null,
+    };
+  }
+
+  if (!dashPid && dashSession) {
+    return {
+      status: 'stale',
+      pid: dashSession.pid || null,
+      url: dashSession.url || null,
+      started_at: dashSession.started_at || null,
+    };
+  }
+
+  return {
+    status: 'not_running',
+    pid: null,
+    url: null,
+    started_at: null,
+  };
+}
+
 export function buildDelegationSummary(files) {
   const historyData = files['.agentxchain/history.jsonl']?.data;
   if (!Array.isArray(historyData)) {
@@ -404,6 +446,7 @@ export function buildRunExport(startDir = process.cwd()) {
         staging_artifact_files: countDirectoryFiles(files, '.agentxchain/staging'),
         intake_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/intake/')),
         coordinator_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/multirepo/')),
+        dashboard_session: buildDashboardSessionSummary(root),
         delegation_summary: buildDelegationSummary(files),
       },
       workspace: buildRunWorkspaceMetadata(root),

package/src/lib/governed-state.js

@@ -799,6 +799,61 @@ function readJsonlEntries(root, relPath) {
     .filter(Boolean);
 }
 
+function collectPendingConcurrentSiblingDeclarations(root, state, currentTurn, historyEntries = []) {
+  const concurrentIds = new Set(
+    Array.isArray(currentTurn?.concurrent_with)
+      ? currentTurn.concurrent_with.filter((id) => typeof id === 'string' && id.length > 0)
+      : [],
+  );
+  const activeTurns = getActiveTurns(state);
+  for (const turn of Object.values(activeTurns)) {
+    if (
+      turn?.turn_id !== currentTurn?.turn_id
+      && Array.isArray(turn?.concurrent_with)
+      && turn.concurrent_with.includes(currentTurn?.turn_id)
+    ) {
+      concurrentIds.add(turn.turn_id);
+    }
+  }
+  if (concurrentIds.size === 0) {
+    return [];
+  }
+
+  const acceptedIds = new Set(
+    (Array.isArray(historyEntries) ? historyEntries : [])
+      .map((entry) => entry?.turn_id)
+      .filter((turnId) => typeof turnId === 'string' && turnId.length > 0),
+  );
+  const declarations = [];
+
+  for (const siblingTurnId of concurrentIds) {
+    if (siblingTurnId === currentTurn?.turn_id || acceptedIds.has(siblingTurnId) || !activeTurns[siblingTurnId]) {
+      continue;
+    }
+
+    const stagedSibling = loadHookStagedTurn(root, getTurnStagingResultPath(siblingTurnId));
+    const siblingResult = stagedSibling.turnResult;
+    if (!siblingResult || siblingResult.turn_id !== siblingTurnId) {
+      continue;
+    }
+
+    const siblingFiles = [...new Set(
+      (Array.isArray(siblingResult.files_changed) ? siblingResult.files_changed : [])
+        .filter((filePath) => typeof filePath === 'string' && filePath.length > 0),
+    )];
+    if (siblingFiles.length === 0) {
+      continue;
+    }
+
+    declarations.push({
+      turn_id: siblingTurnId,
+      files_changed: siblingFiles,
+    });
+  }
+
+  return declarations;
+}
+
 function getObservedFiles(entry) {
   if (Array.isArray(entry?.observed_artifact?.files_changed)) {
     return entry.observed_artifact.files_changed;
@@ -2373,7 +2428,17 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const baseline = currentTurn.baseline || null;
   const rawObservation = observeChanges(root, baseline);
   const historyEntries = readJsonlEntries(root, HISTORY_PATH);
-  const observation = attributeObservedChangesToTurn(rawObservation, currentTurn, historyEntries);
+  const pendingConcurrentSiblingDeclarations = collectPendingConcurrentSiblingDeclarations(
+    root,
+    state,
+    currentTurn,
+    historyEntries,
+  );
+  const observation = attributeObservedChangesToTurn(rawObservation, currentTurn, historyEntries, {
+    currentDeclaredFiles: turnResult.files_changed || [],
+    concurrentSiblingIds: pendingConcurrentSiblingDeclarations.map((entry) => entry.turn_id),
+    pendingConcurrentSiblingDeclarations,
+  });
   const role = config.roles?.[turnResult.role];
   const runtimeId = turnResult.runtime_id;
   const runtime = config.runtimes?.[runtimeId];
@@ -2381,11 +2446,28 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   materializeDerivedReviewArtifact(root, turnResult, state, runtimeType, baseline);
   materializeDerivedProposalArtifact(root, turnResult, state, runtimeType);
   const writeAuthority = role?.write_authority || 'review_only';
+
+  // When concurrent siblings exist but have not yet been accepted, the
+  // observation includes their file changes too.  The attribution system
+  // (attributeObservedChangesToTurn) only removes sibling files for
+  // *later*-accepted turns.  For the *first*-accepted concurrent turn,
+  // undeclared files are expected noise from concurrency — downgrade to
+  // warnings so the governance contract is not broken by turn-acceptance
+  // ordering.
+  const concurrentIds = new Set(
+    Array.isArray(currentTurn.concurrent_with) ? currentTurn.concurrent_with : [],
+  );
+  const acceptedTurnIds = new Set(historyEntries.map(h => h.turn_id));
+  const hasUnacceptedConcurrentSiblings = [...concurrentIds].some(id => !acceptedTurnIds.has(id));
+
   const diffComparison = compareDeclaredVsObserved(
     turnResult.files_changed || [],
     observation.files_changed,
     writeAuthority,
-    { observation_available: observation.observation_available },
+    {
+      observation_available: observation.observation_available,
+      has_unaccepted_concurrent_siblings: hasUnacceptedConcurrentSiblings,
+    },
   );
   if (diffComparison.errors.length > 0) {
     return {

package/src/lib/repo-observer.js

@@ -175,7 +175,7 @@ export function observeChanges(root, baseline) {
   };
 }
 
-export function attributeObservedChangesToTurn(observation, currentTurn, historyEntries = []) {
+export function attributeObservedChangesToTurn(observation, currentTurn, historyEntries = [], options = {}) {
   const observedFiles = Array.isArray(observation?.files_changed) ? observation.files_changed : [];
   if (observedFiles.length === 0) {
     return observation;
@@ -184,6 +184,11 @@ export function attributeObservedChangesToTurn(observation, currentTurn, history
   const concurrentIds = new Set(
     Array.isArray(currentTurn?.concurrent_with) ? currentTurn.concurrent_with : [],
   );
+  for (const siblingId of Array.isArray(options.concurrentSiblingIds) ? options.concurrentSiblingIds : []) {
+    if (typeof siblingId === 'string' && siblingId.length > 0) {
+      concurrentIds.add(siblingId);
+    }
+  }
   if (concurrentIds.size === 0) {
     return observation;
   }
@@ -195,11 +200,17 @@ export function attributeObservedChangesToTurn(observation, currentTurn, history
     .filter((entry) => (
       Number.isInteger(entry?.accepted_sequence)
       && entry.accepted_sequence > assignedSequence
-      && concurrentIds.has(entry.turn_id)
+      && (
+        concurrentIds.has(entry.turn_id)
+        || (Array.isArray(entry?.concurrent_with) && entry.concurrent_with.includes(currentTurn?.turn_id))
+      )
     ))
     .sort((left, right) => left.accepted_sequence - right.accepted_sequence);
 
-  if (acceptedConcurrentSiblings.length === 0) {
+  const pendingConcurrentSiblingDeclarations = Array.isArray(options.pendingConcurrentSiblingDeclarations)
+    ? options.pendingConcurrentSiblingDeclarations
+    : [];
+  if (acceptedConcurrentSiblings.length === 0 && pendingConcurrentSiblingDeclarations.length === 0) {
     return observation;
   }
 
@@ -221,7 +232,20 @@ export function attributeObservedChangesToTurn(observation, currentTurn, history
     }
   }
 
-  if (siblingMarkersByFile.size === 0) {
+  const currentDeclaredFiles = new Set(
+    Array.isArray(options.currentDeclaredFiles) ? options.currentDeclaredFiles : [],
+  );
+  const pendingConcurrentSiblingFiles = new Set();
+  for (const declaration of pendingConcurrentSiblingDeclarations) {
+    const siblingFiles = Array.isArray(declaration?.files_changed) ? declaration.files_changed : [];
+    for (const filePath of siblingFiles) {
+      if (typeof filePath === 'string' && filePath.length > 0 && !currentDeclaredFiles.has(filePath)) {
+        pendingConcurrentSiblingFiles.add(filePath);
+      }
+    }
+  }
+
+  if (siblingMarkersByFile.size === 0 && pendingConcurrentSiblingFiles.size === 0) {
     return observation;
   }
 
@@ -239,6 +263,10 @@ export function attributeObservedChangesToTurn(observation, currentTurn, history
       attributedToConcurrentSiblings.push(filePath);
       continue;
     }
+    if (pendingConcurrentSiblingFiles.has(filePath)) {
+      attributedToConcurrentSiblings.push(filePath);
+      continue;
+    }
     nextFiles.push(filePath);
     if (typeof currentMarker === 'string') {
       nextMarkers[filePath] = currentMarker;
@@ -503,7 +531,13 @@ export function compareDeclaredVsObserved(declared, observed, writeAuthority, op
 
   if (writeAuthority === 'authoritative') {
     if (undeclared.length > 0) {
-      errors.push(`Undeclared file changes detected (observed but not in files_changed): ${undeclared.join(', ')}`);
+      if (options.has_unaccepted_concurrent_siblings) {
+        // Concurrent siblings may have written these files; downgrade to warning.
+        // The attribution system will handle later-accepted siblings correctly.
+        warnings.push(`Undeclared file changes detected (likely from concurrent sibling turns): ${undeclared.join(', ')}`);
+      } else {
+        errors.push(`Undeclared file changes detected (observed but not in files_changed): ${undeclared.join(', ')}`);
+      }
     }
     if (phantom.length > 0) {
       warnings.push(`Declared files not observed in actual diff: ${phantom.join(', ')}`);

package/src/lib/report.js

@@ -5,6 +5,7 @@ import { normalizeRunProvenance, summarizeRunProvenance } from './run-provenance
 export const GOVERNANCE_REPORT_VERSION = '0.1';
 
 const VALID_DELEGATION_OUTCOMES = new Set(['completed', 'failed', 'mixed', 'pending']);
+const VALID_DASHBOARD_SESSION_STATUSES = new Set(['running', 'pid_only', 'stale', 'not_running']);
 
 function normalizeDelegationSummary(summary) {
   if (!summary || typeof summary !== 'object' || Array.isArray(summary)) return null;
@@ -58,6 +59,37 @@ function extractDelegationSummary(artifact) {
   return normalizeDelegationSummary(buildDelegationSummary(artifact.files || {}));
 }
 
+function normalizeDashboardSessionSummary(summary) {
+  if (!summary || typeof summary !== 'object' || Array.isArray(summary)) return null;
+  if (!VALID_DASHBOARD_SESSION_STATUSES.has(summary.status)) return null;
+  return {
+    status: summary.status,
+    pid: Number.isInteger(summary.pid) ? summary.pid : null,
+    url: typeof summary.url === 'string' && summary.url.length > 0 ? summary.url : null,
+    started_at: typeof summary.started_at === 'string' && summary.started_at.length > 0 ? summary.started_at : null,
+  };
+}
+
+function extractDashboardSessionSummary(artifact) {
+  return normalizeDashboardSessionSummary(artifact.summary?.dashboard_session);
+}
+
+function formatDashboardSessionLine(session) {
+  if (!session) return null;
+  switch (session.status) {
+    case 'running':
+      return `running at ${session.url || 'unknown url'} (PID: ${session.pid || '?'})`;
+    case 'pid_only':
+      return `pid_only (PID: ${session.pid || '?'}, session metadata missing)`;
+    case 'stale':
+      return `stale session files${session.pid ? ` (PID: ${session.pid})` : ''}${session.url ? ` at ${session.url}` : ''}`;
+    case 'not_running':
+      return 'not_running';
+    default:
+      return null;
+  }
+}
+
 function yesNo(value) {
   return value ? 'yes' : 'no';
 }
@@ -916,6 +948,7 @@ function buildRunSubject(artifact) {
   const continuity = extractContinuityMetadata(artifact);
   const governanceEvents = extractGovernanceEventDigest(artifact);
   const delegationSummary = extractDelegationSummary(artifact);
+  const dashboardSession = extractDashboardSessionSummary(artifact);
 
   return {
     kind: 'governed_run',
@@ -942,6 +975,7 @@ function buildRunSubject(artifact) {
       active_roles: activeRoles,
       budget_status: normalizeBudgetStatus(artifact.state?.budget_status),
       cost_summary: computeCostSummary(turns),
+      dashboard_session: dashboardSession,
       created_at: timing.created_at,
       completed_at: timing.completed_at,
       duration_seconds: timing.duration_seconds,
@@ -1209,6 +1243,9 @@ export function formatGovernanceReportText(report) {
     if (run.inherited_context?.parent_run_id) {
       lines.push(`Inherited from: ${run.inherited_context.parent_run_id} (${run.inherited_context.parent_status || 'unknown'})`);
     }
+    if (run.dashboard_session) {
+      lines.push(`Dashboard session: ${formatDashboardSessionLine(run.dashboard_session)}`);
+    }
 
     lines.push(
       `History entries: ${artifacts.history_entries}`,
@@ -1688,6 +1725,9 @@ export function formatGovernanceReportMarkdown(report) {
     if (run.inherited_context?.parent_run_id) {
       lines.push(`- Inherited from: \`${run.inherited_context.parent_run_id}\` (${run.inherited_context.parent_status || 'unknown'})`);
     }
+    if (run.dashboard_session) {
+      lines.push(`- Dashboard session: \`${formatDashboardSessionLine(run.dashboard_session)}\``);
+    }
 
     lines.push(
       `- History entries: ${artifacts.history_entries}`,

package/src/lib/run-loop.js

@@ -217,7 +217,16 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
 
     // If selectRole returns a role we already tried (or assigned), try
     // other eligible roles from the routing before giving up.
+    // Exception: when delegation queue is driving resolution, do not fill
+    // extra slots with non-delegation roles via the fallback — those roles
+    // would execute without delegation context and corrupt the lifecycle.
     if (triedRoles.has(roleId)) {
+      const hasPendingDelegations = Array.isArray(state?.delegation_queue) &&
+        state.delegation_queue.some(d => d.status === 'pending' || d.status === 'active');
+      const hasPendingReview = !!state?.pending_delegation_review;
+      if (hasPendingDelegations || hasPendingReview) {
+        break;
+      }
       const phase = state.phase;
       const allowed = config?.routing?.[phase]?.allowed_next_roles || [];
       const alternateFound = allowed.some((alt) => {
@@ -248,6 +257,13 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
     turnsToDispatch.push({ turn: assignResult.turn, state: assignResult.state });
     emit({ type: 'turn_assigned', turn: assignResult.turn, role: roleId, state: assignResult.state });
 
+    // Delegation review is a coordination checkpoint — do not fill additional
+    // slots alongside it.  The review must execute alone so it can assess all
+    // delegation results before the run continues.
+    if (assignResult.turn.delegation_review) {
+      break;
+    }
+
     // Reload state after assignment to get accurate active count
     state = loadState(root, config);
     activeCount = getActiveTurnCount(state);