agentxchain 2.128.0 → 2.130.0

package/src/commands/validate.js

@@ -1,34 +1,96 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
 import chalk from 'chalk';
-import { loadConfig, loadProjectContext } from '../lib/config.js';
+import { findProjectRoot, loadConfig, loadProjectContext } from '../lib/config.js';
 import { validateGovernedProject, validateProject } from '../lib/validation.js';
 import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
+import { detectConfigVersion, loadNormalizedConfig } from '../lib/normalized-config.js';
 
 export async function validateCommand(opts) {
+  const root = findProjectRoot(process.cwd());
+  if (!root) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const mode = opts.mode || 'full';
+  let rawConfig;
+  try {
+    rawConfig = JSON.parse(readFileSync(join(root, 'agentxchain.json'), 'utf8'));
+  } catch (err) {
+    console.log(chalk.red(`agentxchain.json is invalid JSON: ${err.message}`));
+    process.exit(1);
+  }
+
+  if (detectConfigVersion(rawConfig) === 4) {
+    const normalized = loadNormalizedConfig(rawConfig, root);
+    const validation = normalized.ok
+      ? validateGovernedProject(root, rawConfig, normalized.normalized, {
+          mode,
+          expectedAgent: opts.agent || null,
+        })
+      : {
+          ok: false,
+          mode,
+          errors: normalized.errors,
+          warnings: normalized.warnings || [],
+        };
+    const governedVersionSurface = getGovernedVersionSurface(rawConfig);
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ...validation,
+        protocol_mode: 'governed',
+        ...governedVersionSurface,
+        version: 4,
+      }, null, 2));
+    } else {
+      console.log('');
+      console.log(chalk.bold(`  AgentXchain Validate (${mode})`));
+      console.log(chalk.dim('  ' + '─'.repeat(44)));
+      console.log(chalk.dim(`  Root: ${root}`));
+      console.log(chalk.dim(`  Protocol: governed (${formatGovernedVersionLabel(rawConfig)})`));
+      console.log('');
+
+      if (validation.ok) {
+        console.log(chalk.green('  ✓ Validation passed.'));
+      } else {
+        console.log(chalk.red(`  ✗ Validation failed (${validation.errors.length} errors).`));
+      }
+
+      if (validation.errors.length > 0) {
+        console.log('');
+        console.log(chalk.red('  Errors:'));
+        for (const e of validation.errors) console.log(`    - ${e}`);
+      }
+
+      if (validation.warnings.length > 0) {
+        console.log('');
+        console.log(chalk.yellow('  Warnings:'));
+        for (const w of validation.warnings) console.log(`    - ${w}`);
+      }
+      console.log('');
+    }
+
+    if (!validation.ok) process.exit(1);
+    return;
+  }
+
   const context = loadProjectContext();
   if (!context) {
     console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
     process.exit(1);
   }
 
-  const mode = opts.mode || 'full';
-  const validation = context.config.protocol_mode === 'governed'
-    ? validateGovernedProject(context.root, context.rawConfig, context.config, {
-        mode,
-        expectedAgent: opts.agent || null,
-      })
-    : validateProject(context.root, loadConfig()?.config || context.rawConfig, {
-        mode,
-        expectedAgent: opts.agent || null,
-      });
+  const validation = validateProject(context.root, loadConfig()?.config || context.rawConfig, {
+    mode,
+    expectedAgent: opts.agent || null,
+  });
 
   if (opts.json) {
-    const governedVersionSurface = context.config.protocol_mode === 'governed'
-      ? getGovernedVersionSurface(context.rawConfig)
-      : {};
     console.log(JSON.stringify({
       ...validation,
       protocol_mode: context.config.protocol_mode,
-      ...governedVersionSurface,
       version: context.version,
     }, null, 2));
   } else {
@@ -36,11 +98,7 @@ export async function validateCommand(opts) {
     console.log(chalk.bold(`  AgentXchain Validate (${mode})`));
     console.log(chalk.dim('  ' + '─'.repeat(44)));
     console.log(chalk.dim(`  Root: ${context.root}`));
-    if (context.config.protocol_mode === 'governed') {
-      console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (${formatGovernedVersionLabel(context.rawConfig)})`));
-    } else {
-      console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (v${context.version})`));
-    }
+    console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (v${context.version})`));
     console.log('');
 
     if (validation.ok) {

package/src/lib/cli-version.js

@@ -0,0 +1,106 @@
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'));
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
+
+export const CURRENT_CLI_VERSION = pkg.version;
+
+export function normalizeCliVersion(version) {
+  if (typeof version !== 'string') return null;
+  const trimmed = version.trim();
+  const match = SEMVER_RE.exec(trimmed);
+  if (!match) return null;
+  return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
+}
+
+export function compareCliVersions(left, right) {
+  const a = normalizeCliVersion(left);
+  const b = normalizeCliVersion(right);
+  if (!a || !b) return null;
+
+  const aParts = a.split('.').map(Number);
+  const bParts = b.split('.').map(Number);
+
+  for (let i = 0; i < 3; i += 1) {
+    if (aParts[i] > bParts[i]) return 1;
+    if (aParts[i] < bParts[i]) return -1;
+  }
+  return 0;
+}
+
+export function getPublishedDocsMinimumCliVersion() {
+  const envOverride = normalizeCliVersion(process.env.AGENTXCHAIN_DOCS_MIN_VERSION || '');
+  if (envOverride) {
+    return {
+      version: envOverride,
+      source: 'env',
+    };
+  }
+
+  try {
+    const stdout = execFileSync('npm', ['view', 'agentxchain', 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 3000,
+    }).trim();
+    const published = normalizeCliVersion(stdout);
+    if (!published) return null;
+    return {
+      version: published,
+      source: 'npm',
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function getCliVersionHealth() {
+  const current = normalizeCliVersion(CURRENT_CLI_VERSION);
+  const docsFloor = getPublishedDocsMinimumCliVersion();
+  if (!docsFloor) {
+    return {
+      current_version: current,
+      docs_min_cli_version: null,
+      status: 'unknown',
+      source: null,
+      stale: false,
+      detail: 'Could not verify the published docs CLI floor.',
+    };
+  }
+
+  const compare = compareCliVersions(current, docsFloor.version);
+  if (compare === null) {
+    return {
+      current_version: current,
+      docs_min_cli_version: docsFloor.version,
+      status: 'unknown',
+      source: docsFloor.source,
+      stale: false,
+      detail: 'Could not compare CLI versions.',
+    };
+  }
+
+  if (compare < 0) {
+    return {
+      current_version: current,
+      docs_min_cli_version: docsFloor.version,
+      status: 'stale',
+      source: docsFloor.source,
+      stale: true,
+      detail: `Public docs target agentxchain >= ${docsFloor.version}, but this CLI is ${current}. Upgrade with npm/Homebrew or use npx --yes -p agentxchain@latest -c "agentxchain doctor".`,
+    };
+  }
+
+  return {
+    current_version: current,
+    docs_min_cli_version: docsFloor.version,
+    status: 'ok',
+    source: docsFloor.source,
+    stale: false,
+    detail: `Running ${current}; published docs floor is ${docsFloor.version}.`,
+  };
+}

package/src/lib/connector-probe.js

@@ -9,6 +9,36 @@ import {
 const PROBEABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
 const DEFAULT_TIMEOUT_MS = 8_000;
 
+/**
+ * Known local CLI tools and their authoritative-mode flags.
+ * Each entry maps a binary name pattern to the flag required for true
+ * unattended authoritative writes and any flags that look similar but
+ * do NOT grant full authority.
+ */
+const KNOWN_CLI_AUTHORITY_FLAGS = [
+  {
+    binary: 'claude',
+    authoritative_flag: '--dangerously-skip-permissions',
+    weak_flags: [],
+    label: 'Claude Code',
+  },
+  {
+    binary: 'codex',
+    authoritative_flag: '--dangerously-bypass-approvals-and-sandbox',
+    weak_flags: ['--full-auto'],
+    label: 'OpenAI Codex CLI',
+  },
+];
+
+/**
+ * Known prompt transport requirements per CLI binary.
+ * Maps binary name to expected transport.
+ */
+const KNOWN_CLI_TRANSPORTS = {
+  claude: 'stdin',
+  codex: 'argv',
+};
+
 function formatCommand(command, args = []) {
   if (Array.isArray(command)) {
     return command.join(' ');
@@ -274,8 +304,103 @@ async function probeHttpRuntime(runtimeId, runtime, timeoutMs) {
   };
 }
 
+/**
+ * Analyze a local_cli runtime's command shape for authority-intent alignment.
+ * Returns an array of warnings (may be empty).
+ *
+ * @param {string} runtimeId
+ * @param {object} runtime - runtime config entry
+ * @param {object} roles - map of roleId → role config (to determine write_authority)
+ * @returns {{ warnings: Array<{probe_kind: string, level: string, detail: string, fix?: string}> }}
+ */
+function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
+  const warnings = [];
+  if (runtime?.type !== 'local_cli') return { warnings };
+
+  const commandTokens = normalizeCommandTokens(runtime);
+  if (commandTokens.length === 0) return { warnings };
+
+  const binaryName = commandTokens[0].toLowerCase();
+  const allFlags = commandTokens.slice(1).join(' ');
+
+  // Find roles that use this runtime
+  const boundRoles = Object.entries(roles || {})
+    .filter(([, role]) => role?.runtime === runtimeId)
+    .map(([roleId, role]) => ({ roleId, write_authority: role.write_authority }));
+
+  if (boundRoles.length === 0) return { warnings };
+
+  const authoritativeRoles = boundRoles.filter((r) => r.write_authority === 'authoritative');
+
+  // Check known CLI authority flags
+  const knownCli = KNOWN_CLI_AUTHORITY_FLAGS.find((entry) => binaryName === entry.binary || binaryName.endsWith(`/${entry.binary}`));
+  if (knownCli && authoritativeRoles.length > 0) {
+    const hasAuthFlag = commandTokens.some((token) => token === knownCli.authoritative_flag);
+    if (!hasAuthFlag) {
+      const usesWeakFlag = knownCli.weak_flags.find((wf) => commandTokens.some((token) => token === wf));
+      const roleNames = authoritativeRoles.map((r) => r.roleId).join(', ');
+      if (usesWeakFlag) {
+        warnings.push({
+          probe_kind: 'authority_intent',
+          level: 'warn',
+          detail: `${knownCli.label} uses "${usesWeakFlag}" which does NOT grant full unattended authority — role(s) [${roleNames}] require authoritative writes`,
+          fix: `Replace "${usesWeakFlag}" with "${knownCli.authoritative_flag}" in the command array`,
+        });
+      } else {
+        warnings.push({
+          probe_kind: 'authority_intent',
+          level: 'warn',
+          detail: `${knownCli.label} command is missing "${knownCli.authoritative_flag}" — role(s) [${roleNames}] require authoritative writes but the subprocess may block on approval prompts`,
+          fix: `Add "${knownCli.authoritative_flag}" to the command array`,
+        });
+      }
+    }
+  }
+
+  // Prompt transport validation
+  const transport = runtime.prompt_transport || 'dispatch_bundle_only';
+  const knownTransport = KNOWN_CLI_TRANSPORTS[binaryName];
+
+  if (transport === 'argv' && !commandTokens.some((token) => token.includes('{prompt}'))) {
+    warnings.push({
+      probe_kind: 'transport_intent',
+      level: 'warn',
+      detail: `prompt_transport is "argv" but no {prompt} placeholder found in command — the prompt will not be delivered`,
+      fix: `Add a "{prompt}" placeholder to the command array, e.g. ["${binaryName}", ..., "{prompt}"]`,
+    });
+  }
+
+  if (knownTransport && transport !== knownTransport && transport !== 'dispatch_bundle_only') {
+    const transportLabel = knownCli ? knownCli.label : binaryName;
+    warnings.push({
+      probe_kind: 'transport_intent',
+      level: 'warn',
+      detail: `${transportLabel} typically uses "${knownTransport}" transport, but this runtime is configured with "${transport}"`,
+      fix: `Set prompt_transport to "${knownTransport}" or "dispatch_bundle_only"`,
+    });
+  }
+
+  return { warnings };
+}
+
+/**
+ * Normalize a runtime's command field into an array of tokens.
+ */
+function normalizeCommandTokens(runtime) {
+  if (Array.isArray(runtime?.command)) {
+    return runtime.command.flatMap((element) =>
+      typeof element === 'string' ? element.trim().split(/\s+/).filter(Boolean) : []
+    );
+  }
+  if (typeof runtime?.command === 'string' && runtime.command.trim()) {
+    return runtime.command.trim().split(/\s+/).filter(Boolean);
+  }
+  return [];
+}
+
 export async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const roles = options.roles || null;
 
   if (!runtime || !PROBEABLE_RUNTIME_TYPES.has(runtime.type)) {
     return {
@@ -289,7 +414,19 @@ export async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
   }
 
   if (runtime.type === 'local_cli') {
-    return probeLocalCommand(runtimeId, runtime, 'command_presence');
+    const result = await probeLocalCommand(runtimeId, runtime, 'command_presence');
+    // Add authority-intent and transport analysis when roles are available
+    if (roles) {
+      const { warnings } = analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles);
+      if (warnings.length > 0) {
+        result.authority_warnings = warnings;
+        // Promote result level to 'warn' if binary is present but authority intent is wrong
+        if (result.level === 'pass') {
+          result.level = 'warn';
+        }
+      }
+    }
+    return result;
   }
 
   if (runtime.type === 'api_proxy') {
@@ -310,6 +447,7 @@ export async function probeConfiguredConnectors(config, options = {}) {
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
   const requestedRuntimeId = options.runtimeId || null;
   const onProbeStart = typeof options.onProbeStart === 'function' ? options.onProbeStart : null;
+  const roles = config?.roles || null;
 
   const runtimeEntries = Object.entries(config?.runtimes || {})
     .filter(([, runtime]) => PROBEABLE_RUNTIME_TYPES.has(runtime?.type))
@@ -326,30 +464,33 @@ export async function probeConfiguredConnectors(config, options = {}) {
     }
     const [runtimeId, runtime] = match;
     onProbeStart?.(runtimeId, runtime);
-    const connector = await probeConnectorRuntime(runtimeId, runtime, { timeoutMs });
+    const connector = await probeConnectorRuntime(runtimeId, runtime, { timeoutMs, roles });
     return summarizeResults([connector], timeoutMs);
   }
 
   const connectors = [];
   for (const [runtimeId, runtime] of runtimeEntries) {
     onProbeStart?.(runtimeId, runtime);
-    connectors.push(await probeConnectorRuntime(runtimeId, runtime, { timeoutMs }));
+    connectors.push(await probeConnectorRuntime(runtimeId, runtime, { timeoutMs, roles }));
   }
   return summarizeResults(connectors, timeoutMs);
 }
 
 function summarizeResults(connectors, timeoutMs) {
   const failCount = connectors.filter((item) => item.level === 'fail').length;
+  const warnCount = connectors.filter((item) => item.level === 'warn').length;
   const passCount = connectors.filter((item) => item.level === 'pass').length;
+  const overall = failCount > 0 ? 'fail' : warnCount > 0 ? 'warn' : 'pass';
   return {
     ok: failCount === 0,
     exitCode: failCount === 0 ? 0 : 1,
-    overall: failCount === 0 ? 'pass' : 'fail',
+    overall,
     timeout_ms: timeoutMs,
     pass_count: passCount,
+    warn_count: warnCount,
     fail_count: failCount,
     connectors,
   };
 }
 
-export { DEFAULT_TIMEOUT_MS, PROBEABLE_RUNTIME_TYPES };
+export { DEFAULT_TIMEOUT_MS, PROBEABLE_RUNTIME_TYPES, KNOWN_CLI_AUTHORITY_FLAGS, KNOWN_CLI_TRANSPORTS, analyzeLocalCliAuthorityIntent, normalizeCommandTokens };

package/src/lib/continuous-run.js

@@ -9,7 +9,7 @@
  * Decision: DEC-VISION-CONTINUOUS-001
  */
 
-import { existsSync, readFileSync, readdirSync, mkdirSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { resolveVisionPath, deriveVisionCandidates } from './vision-reader.js';
@@ -17,8 +17,9 @@ import {
   recordEvent,
   triageIntent,
   approveIntent,
-  planIntent,
-  startIntent,
+  findNextDispatchableIntent,
+  prepareIntentForDispatch,
+  consumeNextApprovedIntent,
   resolveIntent,
 } from './intake.js';
 import { loadProjectState } from './config.js';
@@ -112,40 +113,6 @@ function isBlockedContinuousExecution(execution) {
 // Intake queue check
 // ---------------------------------------------------------------------------
 
-/**
- * Find the next approved or planned intent in the intake queue.
- *
- * @param {string} root
- * @returns {{ ok: boolean, intentId?: string, status?: string }}
- */
-export function findNextQueuedIntent(root) {
-  const intentsDir = join(root, '.agentxchain', 'intake', 'intents');
-  if (!existsSync(intentsDir)) return { ok: false };
-
-  const files = readdirSync(intentsDir).filter(f => f.endsWith('.json') && !f.startsWith('.tmp-'));
-
-  // Priority order: planned > approved (planned is closer to execution)
-  let bestPlanned = null;
-  let bestApproved = null;
-
-  for (const file of files) {
-    try {
-      const intent = JSON.parse(readFileSync(join(intentsDir, file), 'utf8'));
-      if (intent.status === 'planned' && !bestPlanned) {
-        bestPlanned = { intentId: intent.intent_id, status: 'planned' };
-      } else if (intent.status === 'approved' && !bestApproved) {
-        bestApproved = { intentId: intent.intent_id, status: 'approved' };
-      }
-    } catch {
-      // skip corrupt
-    }
-  }
-
-  if (bestPlanned) return { ok: true, ...bestPlanned };
-  if (bestApproved) return { ok: true, ...bestApproved };
-  return { ok: false };
-}
-
 function readIntent(root, intentId) {
   const intentPath = join(root, '.agentxchain', 'intake', 'intents', `${intentId}.json`);
   if (!existsSync(intentPath)) return null;
@@ -166,50 +133,8 @@ function buildContinuousProvenance(intentId, options = {}) {
   };
 }
 
-function prepareIntentForRun(root, intentId, options = {}) {
-  let intent = readIntent(root, intentId);
-  if (!intent) {
-    return { ok: false, error: `intent ${intentId} not found` };
-  }
-
-  if (intent.status === 'approved') {
-    const planned = planIntent(root, intentId);
-    if (!planned.ok) {
-      return { ok: false, error: `plan failed: ${planned.error}` };
-    }
-    intent = planned.intent;
-  }
-
-  if (intent.status === 'planned') {
-    const started = startIntent(root, intentId, {
-      allowTerminalRestart: true,
-      provenance: options.provenance,
-    });
-    if (!started.ok) {
-      return { ok: false, error: `start failed: ${started.error}` };
-    }
-    intent = started.intent;
-    return {
-      ok: true,
-      intent,
-      runId: started.run_id,
-      turnId: started.turn_id,
-    };
-  }
-
-  if (intent.status === 'executing') {
-    return {
-      ok: true,
-      intent,
-      runId: intent.target_run || null,
-      turnId: intent.target_turn || null,
-    };
-  }
-
-  return {
-    ok: false,
-    error: `intent ${intentId} is in unsupported status "${intent.status}" for continuous execution`,
-  };
+export function findNextQueuedIntent(root) {
+  return findNextDispatchableIntent(root);
 }
 
 // ---------------------------------------------------------------------------
@@ -314,6 +239,7 @@ export function resolveContinuousOptions(opts, config) {
     triageApproval: opts.triageApproval ?? configCont.triage_approval ?? 'auto',
     cooldownSeconds: opts.cooldownSeconds ?? configCont.cooldown_seconds ?? 5,
     perSessionMaxUsd: opts.sessionBudget ?? configCont.per_session_max_usd ?? null,
+    autoCheckpoint: opts.autoCheckpoint ?? configCont.auto_checkpoint ?? true,
   };
 }
 
@@ -382,7 +308,12 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
 
     let execution;
     try {
-      execution = await executeGovernedRun(context, { autoApprove: true, report: true, log });
+      execution = await executeGovernedRun(context, {
+        autoApprove: true,
+        autoCheckpoint: contOpts.autoCheckpoint,
+        report: true,
+        log,
+      });
     } catch (err) {
       session.status = 'failed';
       writeContinuousSession(root, session);
@@ -420,7 +351,7 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
   }
 
   // Step 1: Check intake queue for pending work
-  const queued = findNextQueuedIntent(root);
+  const queued = findNextDispatchableIntent(root);
   let targetIntentId = null;
   let visionObjective = null;
 
@@ -467,7 +398,10 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
     trigger: visionObjective ? 'vision_scan' : 'intake',
     triggerReason: visionObjective || readIntent(root, targetIntentId)?.charter || null,
   });
-  const preparedIntent = prepareIntentForRun(root, targetIntentId, { provenance });
+  const preparedIntent = prepareIntentForDispatch(root, targetIntentId, {
+    allowTerminalRestart: true,
+    provenance,
+  });
   if (!preparedIntent.ok) {
     log(`Continuous start error: ${preparedIntent.error}`);
     session.status = 'failed';
@@ -476,7 +410,7 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
   }
 
   // Execute the governed run
-  session.current_run_id = preparedIntent.runId;
+  session.current_run_id = preparedIntent.run_id;
   session.current_vision_objective = visionObjective || preparedIntent.intent?.charter || null;
   session.status = 'running';
   writeContinuousSession(root, session);
@@ -485,6 +419,7 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
   try {
     execution = await executeGovernedRun(context, {
       autoApprove: true,
+      autoCheckpoint: contOpts.autoCheckpoint,
       report: true,
       log,
     });
@@ -497,12 +432,12 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
       status: 'failed',
       action: 'run_failed',
       stop_reason: err.message,
-      run_id: preparedIntent.runId || null,
+      run_id: preparedIntent.run_id || null,
       intent_id: targetIntentId,
     };
   }
 
-  session.current_run_id = execution.result?.state?.run_id || preparedIntent.runId || null;
+  session.current_run_id = execution.result?.state?.run_id || preparedIntent.run_id || null;
   session.cumulative_spent_usd = (session.cumulative_spent_usd || 0) + getExecutionRunSpentUsd(execution);
 
   const stopReason = execution.result?.stop_reason;

package/src/lib/coordinator-dispatch.js

@@ -213,6 +213,31 @@ export function selectNextAssignment(workspacePath, state, config) {
   return firstFailure || { ok: false, reason: 'no_assignable_workstream', detail: 'No workstream is assignable in the current phase' };
 }
 
+export function selectAssignmentForWorkstream(workspacePath, state, config, workstreamId) {
+  const workstream = config.workstreams?.[workstreamId];
+  if (!workstream) {
+    return {
+      ok: false,
+      reason: 'workstream_missing',
+      detail: `Unknown workstream "${workstreamId}"`,
+      workstream_id: workstreamId,
+    };
+  }
+
+  if (workstream.phase !== state.phase) {
+    return {
+      ok: false,
+      reason: 'phase_mismatch',
+      detail: `Workstream "${workstreamId}" is in phase "${workstream.phase}", but coordinator is currently in phase "${state.phase}"`,
+      workstream_id: workstreamId,
+    };
+  }
+
+  const history = readCoordinatorHistory(workspacePath);
+  const barriers = readBarriers(workspacePath);
+  return evaluateWorkstream(workspacePath, state, config, workstreamId, history, barriers);
+}
+
 export function dispatchCoordinatorTurn(workspacePath, state, config, assignment) {
   if (!assignment?.ok) {
     return { ok: false, error: 'Assignment is required before dispatch' };