agentxchain 2.130.0 → 2.130.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.130.0",
+  "version": "2.130.1",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -24,7 +24,8 @@
     "dev": "node bin/agentxchain.js",
     "test": "npm run test:vitest && npm run test:node",
     "test:vitest": "vitest run --reporter=verbose",
-    "test:node": "node --test test/*.test.js",
+    "test:beta": "node --test test/beta-tester-scenarios/*.test.js",
+    "test:node": "node --test test/*.test.js test/beta-tester-scenarios/*.test.js",
     "preflight:release": "bash scripts/release-preflight.sh",
     "preflight:release:strict": "bash scripts/release-preflight.sh --strict",
     "check:release-alignment": "node scripts/check-release-alignment.mjs",

package/scripts/release-preflight.sh

@@ -110,24 +110,37 @@ if [[ "$PUBLISH_GATE" -eq 1 ]]; then
   echo "[3/7] Release-gate tests (targeted subset)"
   # In publish-gate mode, run only release-critical tests to avoid CI hangs.
   # The full test suite is a pre-tag responsibility, not a publish-time gate.
-  GATE_TESTS=(
+  GATE_TEST_PATTERNS=(
     test/release-preflight.test.js
     test/release-docs-content.test.js
     test/release-notes-gate.test.js
     test/release-identity-hardening.test.js
     test/normalized-config.test.js
     test/conformance.test.js
+    test/beta-tester-scenarios/*.test.js
   )
   GATE_TEST_ARGS=()
-  for t in "${GATE_TESTS[@]}"; do
-    if [[ -f "$t" ]]; then
+  shopt -s nullglob
+  for pattern in "${GATE_TEST_PATTERNS[@]}"; do
+    for t in $pattern; do
       GATE_TEST_ARGS+=("$t")
-    fi
+    done
   done
+  shopt -u nullglob
   if [[ ${#GATE_TEST_ARGS[@]} -eq 0 ]]; then
     fail "No release-gate test files found"
   else
-    if run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 node --test "${GATE_TEST_ARGS[@]}"; then
+    BETA_TEST_COUNT=0
+    for t in "${GATE_TEST_ARGS[@]}"; do
+      if [[ "$t" == test/beta-tester-scenarios/*.test.js ]]; then
+        BETA_TEST_COUNT=$((BETA_TEST_COUNT + 1))
+      fi
+    done
+    if [[ "$BETA_TEST_COUNT" -eq 0 ]]; then
+      fail "No beta-tester scenario tests found for release-gate verification"
+      TEST_OUTPUT=""
+      TEST_STATUS=1
+    elif run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 node --test "${GATE_TEST_ARGS[@]}"; then
       TEST_STATUS=0
     else
       TEST_STATUS=$?

package/src/commands/connector.js

@@ -105,6 +105,7 @@ export async function connectorCheckCommand(runtimeId, options = {}) {
   const result = await probeConfiguredConnectors(context.config, {
     runtimeId: runtimeId || null,
     timeoutMs,
+    root: context.root,
     onProbeStart: options.json ? null : (probeRuntimeId, runtime) => {
       console.log(`  ${chalk.dim('…')} Probing ${chalk.bold(probeRuntimeId)} ${chalk.dim(`(${runtime.type})`)}`);
     },

package/src/commands/doctor.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'fs';
-import { execFileSync, execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, findProjectRoot, loadProjectState } from '../lib/config.js';
@@ -20,6 +20,7 @@ import {
 import { detectActiveTurnBindingDrift, detectStateBundleDesync } from '../lib/governed-state.js';
 import { findPendingApprovedIntents } from '../lib/intake.js';
 import { checkCleanBaseline } from '../lib/repo-observer.js';
+import { probeRuntimeSpawnContext } from '../lib/runtime-spawn-context.js';
 
 export async function doctorCommand(opts = {}) {
   const root = findProjectRoot(process.cwd());
@@ -90,7 +91,7 @@ function governedDoctor(root, rawConfig, opts) {
   const runtimes = (normalized && normalized.runtimes) || rawConfig.runtimes || {};
   const rolesByRuntime = buildRolesByRuntime(normalized?.roles || {});
   for (const [rtId, rt] of Object.entries(runtimes)) {
-    const check = checkRuntimeReachable(rtId, rt, rolesByRuntime[rtId] || []);
+    const check = checkRuntimeReachable(root, rtId, rt, rolesByRuntime[rtId] || []);
     checks.push(check);
   }
   const connectorProbe = getConnectorProbeRecommendation(runtimes);
@@ -484,7 +485,7 @@ function buildCliVersionCheck(cliVersionHealth) {
   };
 }
 
-function checkRuntimeReachable(rtId, rt, boundRoleEntries = []) {
+function checkRuntimeReachable(root, rtId, rt, boundRoleEntries = []) {
   const base = { id: `runtime_${rtId}`, name: `Runtime: ${rtId}` };
 
   if (!rt || !rt.type) {
@@ -496,14 +497,8 @@ function checkRuntimeReachable(rtId, rt, boundRoleEntries = []) {
       return attachRuntimeContract({ ...base, level: 'pass', detail: 'Manual runtime (no binary needed)' }, rtId, rt, boundRoleEntries);
 
     case 'local_cli': {
-      const cmd = Array.isArray(rt.command) ? rt.command[0] : (typeof rt.command === 'string' ? rt.command.split(/\s+/)[0] : null);
-      if (!cmd) return attachRuntimeContract({ ...base, level: 'warn', detail: 'No command configured' }, rtId, rt, boundRoleEntries);
-      try {
-        execSync(`command -v ${cmd}`, { stdio: 'ignore' });
-        return attachRuntimeContract({ ...base, level: 'pass', detail: `${cmd} binary found` }, rtId, rt, boundRoleEntries);
-      } catch {
-        return attachRuntimeContract({ ...base, level: 'fail', detail: `${cmd} not found in PATH` }, rtId, rt, boundRoleEntries);
-      }
+      const probe = probeRuntimeSpawnContext(root, rt, { runtimeId: rtId });
+      return attachRuntimeContract({ ...base, level: probe.ok ? 'pass' : 'fail', detail: probe.detail }, rtId, rt, boundRoleEntries);
     }
 
     case 'api_proxy': {
@@ -523,14 +518,8 @@ function checkRuntimeReachable(rtId, rt, boundRoleEntries = []) {
       if (transport === 'streamable_http') {
         return attachRuntimeContract({ ...base, level: 'warn', detail: 'Remote MCP endpoint (cannot verify at doctor time)' }, rtId, rt, boundRoleEntries);
       }
-      const cmd = Array.isArray(rt.command) ? rt.command[0] : (typeof rt.command === 'string' ? rt.command.split(/\s+/)[0] : null);
-      if (!cmd) return attachRuntimeContract({ ...base, level: 'warn', detail: 'No MCP command configured' }, rtId, rt, boundRoleEntries);
-      try {
-        execSync(`command -v ${cmd}`, { stdio: 'ignore' });
-        return attachRuntimeContract({ ...base, level: 'pass', detail: `${cmd} binary found` }, rtId, rt, boundRoleEntries);
-      } catch {
-        return attachRuntimeContract({ ...base, level: 'fail', detail: `${cmd} not found in PATH` }, rtId, rt, boundRoleEntries);
-      }
+      const probe = probeRuntimeSpawnContext(root, rt, { runtimeId: rtId });
+      return attachRuntimeContract({ ...base, level: probe.ok ? 'pass' : 'fail', detail: probe.detail }, rtId, rt, boundRoleEntries);
     }
 
     case 'remote_agent':

package/src/lib/connector-probe.js

@@ -1,10 +1,9 @@
-import { execFileSync } from 'node:child_process';
-
 import {
   buildProviderHeaders,
   buildProviderRequest,
   PROVIDER_ENDPOINTS,
 } from './adapters/api-proxy-adapter.js';
+import { probeRuntimeSpawnContext } from './runtime-spawn-context.js';
 
 const PROBEABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
 const DEFAULT_TIMEOUT_MS = 8_000;
@@ -35,8 +34,8 @@ const KNOWN_CLI_AUTHORITY_FLAGS = [
  * Maps binary name to expected transport.
  */
 const KNOWN_CLI_TRANSPORTS = {
-  claude: 'stdin',
-  codex: 'argv',
+  claude: ['stdin'],
+  codex: ['argv', 'stdin'],
 };
 
 function formatCommand(command, args = []) {
@@ -78,11 +77,6 @@ function commandHead(runtime) {
   return null;
 }
 
-function resolveBinary(command) {
-  const resolver = process.platform === 'win32' ? 'where' : 'which';
-  execFileSync(resolver, [command], { stdio: 'ignore' });
-}
-
 function resolveProviderEndpoint(runtime) {
   if (typeof runtime?.base_url === 'string' && runtime.base_url.trim()) {
     return runtime.base_url.trim();
@@ -153,7 +147,7 @@ async function probeHttp({ url, method = 'GET', headers = {}, body, timeoutMs })
   }
 }
 
-async function probeLocalCommand(runtimeId, runtime, probeKindLabel) {
+async function probeLocalCommand(runtimeId, runtime, probeKindLabel, options = {}) {
   const head = commandHead(runtime);
   const base = {
     runtime_id: runtimeId,
@@ -170,22 +164,22 @@ async function probeLocalCommand(runtimeId, runtime, probeKindLabel) {
     };
   }
 
-  try {
-    resolveBinary(head);
+  const spawnProbe = probeRuntimeSpawnContext(options.root || process.cwd(), runtime, { runtimeId });
+  if (spawnProbe.ok) {
     return {
       ...base,
       level: 'pass',
-      command: head,
-      detail: `${head} is available on PATH`,
-    };
-  } catch {
-    return {
-      ...base,
-      level: 'fail',
-      command: head,
-      detail: `${head} was not found on PATH`,
+      command: spawnProbe.command || head,
+      detail: spawnProbe.detail,
     };
   }
+
+  return {
+    ...base,
+    level: 'fail',
+    command: spawnProbe.command || head,
+    detail: spawnProbe.detail,
+  };
 }
 
 async function probeApiProxy(runtimeId, runtime, timeoutMs) {
@@ -331,6 +325,27 @@ function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
   if (boundRoles.length === 0) return { warnings };
 
   const authoritativeRoles = boundRoles.filter((r) => r.write_authority === 'authoritative');
+  const isCodex = binaryName === 'codex' || binaryName.endsWith('/codex');
+
+  if (isCodex) {
+    if (commandTokens[1] !== 'exec') {
+      warnings.push({
+        probe_kind: 'command_intent',
+        level: 'warn',
+        detail: 'OpenAI Codex CLI governed local runs should use the non-interactive "exec" subcommand. Top-level "codex" is the interactive entrypoint.',
+        fix: 'Use ["codex", "exec", "--dangerously-bypass-approvals-and-sandbox", "{prompt}"]',
+      });
+    }
+
+    if (commandTokens.includes('--quiet')) {
+      warnings.push({
+        probe_kind: 'command_intent',
+        level: 'warn',
+        detail: 'OpenAI Codex CLI rejects "--quiet" in governed local_cli commands on the current CLI. The command exits before the turn starts.',
+        fix: 'Remove "--quiet" and use ["codex", "exec", "--dangerously-bypass-approvals-and-sandbox", "{prompt}"]',
+      });
+    }
+  }
 
   // Check known CLI authority flags
   const knownCli = KNOWN_CLI_AUTHORITY_FLAGS.find((entry) => binaryName === entry.binary || binaryName.endsWith(`/${entry.binary}`));
@@ -359,7 +374,7 @@ function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
 
   // Prompt transport validation
   const transport = runtime.prompt_transport || 'dispatch_bundle_only';
-  const knownTransport = KNOWN_CLI_TRANSPORTS[binaryName];
+  const knownTransports = KNOWN_CLI_TRANSPORTS[binaryName];
 
   if (transport === 'argv' && !commandTokens.some((token) => token.includes('{prompt}'))) {
     warnings.push({
@@ -370,13 +385,13 @@ function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
     });
   }
 
-  if (knownTransport && transport !== knownTransport && transport !== 'dispatch_bundle_only') {
+  if (knownTransports && !knownTransports.includes(transport) && 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"`,
+      detail: `${transportLabel} typically uses ${knownTransports.map((value) => `"${value}"`).join(' or ')} transport, but this runtime is configured with "${transport}"`,
+      fix: `Set prompt_transport to ${knownTransports.map((value) => `"${value}"`).join(' or ')} or "dispatch_bundle_only"`,
     });
   }
 
@@ -414,7 +429,7 @@ export async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
   }
 
   if (runtime.type === 'local_cli') {
-    const result = await probeLocalCommand(runtimeId, runtime, 'command_presence');
+    const result = await probeLocalCommand(runtimeId, runtime, 'command_presence', options);
     // Add authority-intent and transport analysis when roles are available
     if (roles) {
       const { warnings } = analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles);
@@ -437,7 +452,7 @@ export async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
     if (runtime.transport === 'streamable_http') {
       return probeHttpRuntime(runtimeId, runtime, timeoutMs);
     }
-    return probeLocalCommand(runtimeId, runtime, 'command_presence');
+    return probeLocalCommand(runtimeId, runtime, 'command_presence', options);
   }
 
   return probeHttpRuntime(runtimeId, runtime, timeoutMs);

package/src/lib/connector-validate.js

@@ -22,6 +22,7 @@ import { dispatchMcp } from './adapters/mcp-adapter.js';
 import { dispatchRemoteAgent } from './adapters/remote-agent-adapter.js';
 import { getDispatchPromptPath, getTurnStagingResultPath } from './turn-paths.js';
 import { validateStagedTurnResult } from './turn-result-validator.js';
+import { probeRuntimeSpawnContext } from './runtime-spawn-context.js';
 
 const VALIDATABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
 const DEFAULT_VALIDATE_TIMEOUT_MS = 120_000;
@@ -130,6 +131,26 @@ export async function validateConfiguredConnector(sourceRoot, options = {}) {
       };
     }
 
+    if (runtime.type === 'local_cli' || (runtime.type === 'mcp' && (runtime.transport || 'stdio') !== 'streamable_http')) {
+      const spawnProbe = probeRuntimeSpawnContext(scratchRoot, scratchContext.config.runtimes[runtimeId], { runtimeId });
+      if (!spawnProbe.ok) {
+        return {
+          ok: false,
+          exitCode: 1,
+          overall: 'fail',
+          runtime_id: runtimeId,
+          runtime_type: runtime.type,
+          role_id: roleSelection.roleId,
+          timeout_ms: timeoutMs,
+          warnings,
+          dispatch: null,
+          validation: null,
+          error: spawnProbe.detail,
+          scratch_root: scratchRoot,
+        };
+      }
+    }
+
     const initResult = initializeGovernedRun(scratchRoot, scratchContext.config, {
       provenance: {
         trigger: 'connector_validate',

package/src/lib/governed-state.js

@@ -2488,7 +2488,8 @@ export function reissueTurn(root, config, opts = {}) {
   const oldRuntimeId = oldTurn.runtime_id;
 
   // Resolve current runtime binding (may have changed in config)
-  const currentRuntimeId = role.runtime;
+  // BUG-25 fix: normalized config uses runtime_id, raw config uses runtime
+  const currentRuntimeId = role.runtime_id || role.runtime;
   const currentRuntime = config.runtimes?.[currentRuntimeId];
   if (!currentRuntime) {
     return { ok: false, error: `Runtime "${currentRuntimeId}" not found in config for role "${roleId}"` };

package/src/lib/runtime-spawn-context.js

@@ -0,0 +1,163 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const DEFAULT_PROBE_TIMEOUT_MS = 500;
+const PROMPT_PLACEHOLDER = 'AgentXchain spawn-context probe';
+
+function resolveLocalCliPromptTransport(runtime) {
+  const valid = new Set(['argv', 'stdin', 'dispatch_bundle_only']);
+  if (valid.has(runtime?.prompt_transport)) {
+    return runtime.prompt_transport;
+  }
+
+  const parts = Array.isArray(runtime?.command)
+    ? runtime.command
+    : [runtime?.command, ...(Array.isArray(runtime?.args) ? runtime.args : [])];
+  const hasPrompt = parts.some((part) => typeof part === 'string' && part.includes('{prompt}'));
+  return hasPrompt ? 'argv' : 'dispatch_bundle_only';
+}
+
+function resolveLocalCliInvocation(runtime) {
+  if (!runtime?.command) {
+    return { command: null, args: [] };
+  }
+
+  const transport = resolveLocalCliPromptTransport(runtime);
+
+  if (Array.isArray(runtime.command)) {
+    const first = runtime.command[0] || '';
+    const headParts = typeof first === 'string' && first.includes(' ') ? first.split(/\s+/) : [first];
+    const [command, ...headArgs] = headParts;
+    const rest = [...headArgs, ...runtime.command.slice(1)];
+    const args = transport === 'argv'
+      ? rest.map((arg) => arg === '{prompt}' ? PROMPT_PLACEHOLDER : arg)
+      : rest.filter((arg) => arg !== '{prompt}');
+    return { command, args };
+  }
+
+  const args = transport === 'argv'
+    ? (runtime.args || []).map((arg) => arg === '{prompt}' ? PROMPT_PLACEHOLDER : arg)
+    : (runtime.args || []).filter((arg) => arg !== '{prompt}');
+  return { command: runtime.command, args };
+}
+
+function resolveMcpInvocation(runtime) {
+  if (!runtime?.command) {
+    return { command: null, args: [] };
+  }
+
+  if (Array.isArray(runtime.command)) {
+    const [command, ...args] = runtime.command;
+    return { command, args };
+  }
+
+  return {
+    command: runtime.command,
+    args: Array.isArray(runtime.args) ? runtime.args : [],
+  };
+}
+
+function resolveInvocation(runtime) {
+  if (runtime?.type === 'local_cli') {
+    return resolveLocalCliInvocation(runtime);
+  }
+  return resolveMcpInvocation(runtime);
+}
+
+function buildResolutionFix(command) {
+  const commandValue = String(command || '');
+  const commandBase = basename(commandValue);
+
+  if (commandBase === 'codex' || commandBase === 'codex.exe') {
+    return 'Set "command" to the absolute path, e.g. "/Applications/Codex.app/Contents/Resources/codex", or add Codex to PATH in the dispatch spawn context.';
+  }
+  if (commandValue.includes('~')) {
+    return 'Expand "~" to an absolute path in "command". Shell expansion does not apply to governed dispatch.';
+  }
+  return 'Set "command" to an absolute path or add it to PATH in the dispatch spawn context.';
+}
+
+export function probeRuntimeSpawnContext(root, runtime, options = {}) {
+  const runtimeId = options.runtimeId || null;
+  const cwd = runtime?.cwd ? join(root, runtime.cwd) : root;
+  const { command, args } = resolveInvocation(runtime);
+
+  if (!command) {
+    return {
+      ok: false,
+      runtime_id: runtimeId,
+      command: null,
+      cwd,
+      detail: 'No command configured for the dispatch spawn context.',
+    };
+  }
+
+  if (!existsSync(cwd)) {
+    return {
+      ok: false,
+      runtime_id: runtimeId,
+      command,
+      cwd,
+      detail: `Runtime cwd "${runtime.cwd}" does not exist in the dispatch spawn context.`,
+    };
+  }
+
+  const probe = spawnSync(command, args, {
+    cwd,
+    env: { ...process.env, AGENTXCHAIN_SPAWN_PROBE: '1' },
+    stdio: 'ignore',
+    timeout: options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
+    windowsHide: true,
+  });
+
+  if (probe.error) {
+    const errorCode = probe.error.code || 'spawn_error';
+    if (errorCode === 'ETIMEDOUT') {
+      return {
+        ok: true,
+        runtime_id: runtimeId,
+        command,
+        cwd,
+        timed_out: true,
+        detail: `"${command}" launched in the dispatch spawn context but exceeded the short probe timeout. Treating this as resolvable.`,
+      };
+    }
+    if (errorCode === 'ENOENT') {
+      return {
+        ok: false,
+        runtime_id: runtimeId,
+        command,
+        cwd,
+        error_code: errorCode,
+        detail: `"${command}" is not resolvable in the dispatch spawn context. ${buildResolutionFix(command)}`,
+      };
+    }
+    if (errorCode === 'EACCES') {
+      return {
+        ok: false,
+        runtime_id: runtimeId,
+        command,
+        cwd,
+        error_code: errorCode,
+        detail: `"${command}" exists but is not executable in the dispatch spawn context. Mark it executable or point "command" at the real executable path.`,
+      };
+    }
+    return {
+      ok: false,
+      runtime_id: runtimeId,
+      command,
+      cwd,
+      error_code: errorCode,
+      detail: `Dispatch spawn probe failed for "${command}": ${probe.error.message}`,
+    };
+  }
+
+  return {
+    ok: true,
+    runtime_id: runtimeId,
+    command,
+    cwd,
+    detail: `"${command}" is resolvable in the dispatch spawn context.`,
+  };
+}