agentxchain 2.149.1 → 2.149.2

package/README.md

@@ -89,7 +89,7 @@ agentxchain step --role pm
 
 If you skipped `--goal` during scaffold, run `agentxchain config --set project.goal "Build an API change planner for release teams"` before the first governed turn instead of re-running init in place.
 
-The default governed dev runtime is `claude --print --dangerously-skip-permissions` with stdin prompt delivery. The non-interactive governed path needs write access, so do not pretend bare `claude --print` is sufficient for unattended implementation turns. If your local coding agent uses a different launch contract, set it during scaffold creation:
+The default governed dev runtime is `claude --print --dangerously-skip-permissions --bare` with stdin prompt delivery. The non-interactive governed path needs write access and env-based auth, so do not pretend plain `claude --print` is sufficient for unattended implementation turns. If your local coding agent uses a different launch contract, set it during scaffold creation:
 
 ```bash
 agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y

package/package.json

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

package/src/commands/doctor.js

@@ -59,7 +59,7 @@ export async function doctorCommand(opts = {}) {
 
 // ── Governed (v4) Doctor ────────────────────────────────────────────────────
 
-function governedDoctor(root, rawConfig, opts) {
+async function governedDoctor(root, rawConfig, opts) {
   const checks = [];
   const cliVersionHealth = getCliVersionHealth();
   let stateRunId = null;
@@ -93,7 +93,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(root, rtId, rt, rolesByRuntime[rtId] || []);
+    const check = await checkRuntimeReachable(root, rtId, rt, rolesByRuntime[rtId] || []);
     checks.push(check);
   }
   const connectorProbe = getConnectorProbeRecommendation(runtimes);
@@ -488,7 +488,7 @@ function buildCliVersionCheck(cliVersionHealth) {
   };
 }
 
-function checkRuntimeReachable(root, rtId, rt, boundRoleEntries = []) {
+async function checkRuntimeReachable(root, rtId, rt, boundRoleEntries = []) {
   const base = { id: `runtime_${rtId}`, name: `Runtime: ${rtId}` };
 
   if (!rt || !rt.type) {
@@ -502,7 +502,7 @@ function checkRuntimeReachable(root, rtId, rt, boundRoleEntries = []) {
     case 'local_cli': {
       const probe = probeRuntimeSpawnContext(root, rt, { runtimeId: rtId });
       if (probe.ok) {
-        const claudeAuthIssue = getClaudeSubprocessAuthIssue(rt);
+        const claudeAuthIssue = await getClaudeSubprocessAuthIssue(rt);
         if (claudeAuthIssue) {
           return attachRuntimeContract({
             ...base,

package/src/commands/init.js

@@ -98,7 +98,7 @@ const GOVERNED_ROLES = {
 
 const DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME = Object.freeze({
   type: 'local_cli',
-  command: ['claude', '--print', '--dangerously-skip-permissions'],
+  command: ['claude', '--print', '--dangerously-skip-permissions', '--bare'],
   cwd: '.',
   prompt_transport: 'stdin',
 });

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

@@ -128,13 +128,14 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
   const spawnEnv = { ...process.env, AGENTXCHAIN_TURN_ID: turn.turn_id };
   const stdinBytes = transport === 'stdin' ? Buffer.byteLength(fullPrompt, 'utf8') : 0;
   const diagnosticArgs = redactPromptArgs(args, fullPrompt, transport);
-  const claudeAuthIssue = getClaudeSubprocessAuthIssue(runtime, spawnEnv);
+  const claudeAuthIssue = await getClaudeSubprocessAuthIssue(runtime, spawnEnv);
 
   if (claudeAuthIssue) {
     appendDiagnostic(logs, 'claude_auth_preflight_failed', {
       runtime_id: runtimeId,
       turn_id: turn.turn_id,
       auth_env_present: claudeAuthIssue.auth_env_present,
+      smoke_probe: claudeAuthIssue.smoke_probe,
       recommendation: claudeAuthIssue.fix,
     });
     return {

package/src/lib/claude-local-auth.js

@@ -1,3 +1,5 @@
+import { spawn } from 'node:child_process';
+
 const CLAUDE_ENV_AUTH_KEYS = [
   'ANTHROPIC_API_KEY',
   'CLAUDE_API_KEY',
@@ -6,6 +8,9 @@ const CLAUDE_ENV_AUTH_KEYS = [
   'CLAUDE_CODE_USE_BEDROCK',
 ];
 
+const DEFAULT_SMOKE_PROBE_TIMEOUT_MS = 10_000;
+const DEFAULT_SMOKE_PROBE_STDIN = 'ok';
+
 function normalizeCommandTokens(runtime) {
   if (Array.isArray(runtime?.command)) {
     return runtime.command.flatMap((element) =>
@@ -41,7 +46,26 @@ export function hasClaudeEnvAuth(env = process.env) {
   return Object.values(getClaudeEnvAuthPresence(env)).some(Boolean);
 }
 
-export function getClaudeSubprocessAuthIssue(runtime, env = process.env) {
+function buildClaudeSubprocessAuthIssue(env, smokeProbe = null) {
+  const auth_env_present = getClaudeEnvAuthPresence(env);
+  return {
+    auth_env_present,
+    smoke_probe: smokeProbe,
+    detail: 'Claude local_cli runtime has no env-based auth and is missing "--bare"; non-interactive subprocesses can hang on macOS keychain reads.',
+    fix: 'Export ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN before running AgentXchain, or add "--bare" to the Claude command if you intentionally want env-only auth.',
+  };
+}
+
+function resolveSmokeProbeTimeoutMs(env, options = {}) {
+  if (Number.isFinite(options?.timeoutMs) && options.timeoutMs > 0) {
+    return options.timeoutMs;
+  }
+  const raw = env?.AGENTXCHAIN_CLAUDE_AUTH_PROBE_TIMEOUT_MS;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_SMOKE_PROBE_TIMEOUT_MS;
+}
+
+export async function getClaudeSubprocessAuthIssue(runtime, env = process.env, options = {}) {
   if (!isClaudeLocalCliRuntime(runtime)) {
     return null;
   }
@@ -50,12 +74,164 @@ export function getClaudeSubprocessAuthIssue(runtime, env = process.env) {
     return null;
   }
 
-  const auth_env_present = getClaudeEnvAuthPresence(env);
-  return {
-    auth_env_present,
-    detail: 'Claude local_cli runtime has no env-based auth and is missing "--bare"; non-interactive subprocesses can hang on macOS keychain reads.',
-    fix: 'Export ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN before running AgentXchain, or add "--bare" to the Claude command if you intentionally want env-only auth.',
-  };
+  const smokeProbe = await runClaudeSmokeProbe({
+    runtime,
+    env,
+    timeoutMs: resolveSmokeProbeTimeoutMs(env, options),
+    stdinPayload: options?.stdinPayload,
+    spawnImpl: options?.spawnImpl,
+  });
+
+  if (smokeProbe.kind === 'stdout_observed' || smokeProbe.kind === 'spawn_error' || smokeProbe.kind === 'skipped') {
+    return null;
+  }
+
+  if (smokeProbe.kind === 'hang' || smokeProbe.kind === 'exit_nonzero' || smokeProbe.kind === 'stderr_only') {
+    return buildClaudeSubprocessAuthIssue(env, smokeProbe);
+  }
+
+  return null;
+}
+
+/**
+ * Bounded smoke probe that spawns the runtime's actual Claude command with a
+ * tiny prompt on stdin and a watchdog. Returns a classification:
+ *
+ *   { kind: 'stdout_observed' }      — real stdout arrived before watchdog;
+ *                                      the setup is NOT hanging on auth.
+ *   { kind: 'hang', elapsed_ms }     — watchdog fired with no stdout/stderr
+ *                                      bytes; the keychain-hang shape (BUG-54).
+ *   { kind: 'stderr_only', ... }     — process wrote stderr but no stdout
+ *                                      before watchdog (auth error or similar).
+ *   { kind: 'exit_nonzero', ... }    — process exited non-zero with no stdout
+ *                                      (explicit auth failure — not a hang).
+ *   { kind: 'spawn_error', ... }     — spawn itself failed (ENOENT / EPERM).
+ *   { kind: 'skipped', reason }      — probe disabled or unavailable.
+ *
+ * This is the positive-case-testable alternative to the static shape-check in
+ * `getClaudeSubprocessAuthIssue`: it observes what the subprocess actually
+ * does rather than predicting what it *might* do from config shape alone.
+ *
+ * Added 2026-04-21 for the BUG-56 false-positive fix. See
+ * `.planning/BUG_56_FALSE_POSITIVE_RETRO.md` for the decision trail.
+ *
+ * @param {{ runtime: object, env?: object, timeoutMs?: number, stdinPayload?: string, spawnImpl?: Function }} opts
+ * @returns {Promise<object>}
+ */
+export async function runClaudeSmokeProbe(opts) {
+  const runtime = opts?.runtime ?? null;
+  const env = opts?.env ?? process.env;
+  const timeoutMs = Number.isFinite(opts?.timeoutMs) ? opts.timeoutMs : DEFAULT_SMOKE_PROBE_TIMEOUT_MS;
+  const stdinPayload = typeof opts?.stdinPayload === 'string' ? opts.stdinPayload : DEFAULT_SMOKE_PROBE_STDIN;
+  const spawnImpl = typeof opts?.spawnImpl === 'function' ? opts.spawnImpl : spawn;
+
+  if (!isClaudeLocalCliRuntime(runtime)) {
+    return { kind: 'skipped', reason: 'not_claude_local_cli' };
+  }
+
+  const tokens = normalizeCommandTokens(runtime);
+  if (tokens.length === 0) {
+    return { kind: 'skipped', reason: 'empty_command' };
+  }
+  const [command, ...args] = tokens;
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl(command, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env,
+      });
+    } catch (error) {
+      resolve({
+        kind: 'spawn_error',
+        errno: error?.errno ?? null,
+        code: error?.code ?? null,
+        message: error?.message ?? String(error),
+      });
+      return;
+    }
+
+    if (!child || typeof child.on !== 'function') {
+      resolve({ kind: 'spawn_error', code: 'NO_CHILD_HANDLE', message: 'spawn returned no child handle' });
+      return;
+    }
+
+    const start = Date.now();
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stderrBuf = '';
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      try { child.kill('SIGTERM'); } catch { /* ignore */ }
+      resolve(result);
+    };
+
+    const watchdog = setTimeout(() => {
+      const elapsed_ms = Date.now() - start;
+      if (stdoutBytes > 0) {
+        finish({ kind: 'stdout_observed', elapsed_ms });
+      } else if (stderrBytes > 0) {
+        finish({ kind: 'stderr_only', elapsed_ms, stderr_snippet: stderrBuf.slice(0, 500) });
+      } else {
+        finish({ kind: 'hang', elapsed_ms });
+      }
+    }, timeoutMs);
+    if (typeof watchdog.unref === 'function') watchdog.unref();
+
+    child.stdout?.on('data', (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > 0 && !settled) {
+        clearTimeout(watchdog);
+        finish({ kind: 'stdout_observed', elapsed_ms: Date.now() - start });
+      }
+    });
+
+    child.stderr?.on('data', (chunk) => {
+      stderrBytes += chunk.length;
+      stderrBuf += chunk.toString('utf8');
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(watchdog);
+      finish({
+        kind: 'spawn_error',
+        errno: error?.errno ?? null,
+        code: error?.code ?? null,
+        message: error?.message ?? String(error),
+      });
+    });
+
+    child.on('exit', (code, signal) => {
+      if (settled) return;
+      clearTimeout(watchdog);
+      const elapsed_ms = Date.now() - start;
+      if (stdoutBytes > 0) {
+        finish({ kind: 'stdout_observed', elapsed_ms });
+      } else if (code !== 0) {
+        finish({
+          kind: 'exit_nonzero',
+          elapsed_ms,
+          exit_code: code,
+          exit_signal: signal,
+          stderr_snippet: stderrBuf.slice(0, 500),
+        });
+      } else if (stderrBytes > 0) {
+        finish({ kind: 'stderr_only', elapsed_ms, stderr_snippet: stderrBuf.slice(0, 500) });
+      } else {
+        finish({ kind: 'hang', elapsed_ms });
+      }
+    });
+
+    try {
+      child.stdin?.end(`${stdinPayload}\n`);
+    } catch {
+      // best-effort; error will surface via 'error' event if real
+    }
+  });
 }
 
 export { CLAUDE_ENV_AUTH_KEYS, normalizeCommandTokens };

package/src/lib/connector-probe.js

@@ -165,30 +165,30 @@ async function probeLocalCommand(runtimeId, runtime, probeKindLabel, options = {
     };
   }
 
-  const spawnProbe = probeRuntimeSpawnContext(options.root || process.cwd(), runtime, { runtimeId });
-  const claudeAuthIssue = getClaudeSubprocessAuthIssue(runtime);
-
-  // DEC-BUG54-CLAUDE-AUTH-PREFLIGHT-001 / DEC-BUG54-VALIDATE-AUTH-PREFLIGHT-001
-  // Auth-preflight is a config-shape defect that must fire regardless of whether
-  // the binary currently resolves on PATH. Matches connector-validate.js:108-138
-  // ordering: a Claude local_cli runtime with no env auth and no --bare is a
-  // deterministic hang-on-spawn shape the operator must fix before anything
-  // else. If they fix auth (or add --bare) but still do not have claude
-  // installed, the next connector check surfaces command_presence after they
-  // fix the config — that is the correct operator progression.
+  const claudeAuthIssue = await getClaudeSubprocessAuthIssue(runtime, process.env, {
+    timeoutMs: options.claudeAuthProbeTimeoutMs,
+  });
+
+  // DEC-BUG56-PREFLIGHT-PROBE-OVER-SHAPE-CHECK-001
+  // Auth-preflight is observation-based: a no-env/no-bare Claude runtime is
+  // only refused when a bounded smoke probe actually hangs or fails without
+  // stdout. Working Claude Max keychain setups must pass this gate.
   if (claudeAuthIssue) {
     return {
       ...base,
       level: 'fail',
       probe_kind: 'auth_preflight',
-      command: spawnProbe.command || head,
+      command: formatTarget(runtime) || head,
       error_code: 'claude_auth_preflight_failed',
       detail: claudeAuthIssue.detail,
       fix: claudeAuthIssue.fix,
       auth_env_present: claudeAuthIssue.auth_env_present,
+      smoke_probe: claudeAuthIssue.smoke_probe,
     };
   }
 
+  const spawnProbe = probeRuntimeSpawnContext(options.root || process.cwd(), runtime, { runtimeId });
+
   if (!spawnProbe.ok) {
     return {
       ...base,
@@ -401,8 +401,6 @@ function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
   // Prompt transport validation
   const transport = runtime.prompt_transport || 'dispatch_bundle_only';
   const knownTransports = KNOWN_CLI_TRANSPORTS[binaryName];
-  const claudeAuthIssue = getClaudeSubprocessAuthIssue(runtime);
-
   if (transport === 'argv' && !commandTokens.some((token) => token.includes('{prompt}'))) {
     warnings.push({
       probe_kind: 'transport_intent',
@@ -422,15 +420,6 @@ function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
     });
   }
 
-  if (claudeAuthIssue) {
-    warnings.push({
-      probe_kind: 'auth_preflight',
-      level: 'warn',
-      detail: claudeAuthIssue.detail,
-      fix: claudeAuthIssue.fix,
-    });
-  }
-
   return { warnings };
 }
 

package/src/lib/connector-validate.js

@@ -105,11 +105,10 @@ export async function validateConfiguredConnector(sourceRoot, options = {}) {
     };
   }
 
-  // DEC-BUG54-CLAUDE-AUTH-PREFLIGHT-001 — refuse the known-hanging Claude
-  // local_cli shape before burning the scratch-workspace + synthetic-dispatch
-  // ceremony. The adapter also refuses this shape via `claude_auth_preflight_failed`,
-  // but the operator gets a faster, identical-fix message if we catch it here.
-  const claudeAuthIssue = getClaudeSubprocessAuthIssue(runtime);
+  // DEC-BUG56-PREFLIGHT-PROBE-OVER-SHAPE-CHECK-001 — refuse Claude local_cli
+  // auth-hang shapes only after a bounded smoke probe observes no stdout.
+  // Working Claude Max keychain setups must pass instead of false-positive.
+  const claudeAuthIssue = await getClaudeSubprocessAuthIssue(runtime);
   if (claudeAuthIssue) {
     return {
       ok: false,
@@ -131,6 +130,7 @@ export async function validateConfiguredConnector(sourceRoot, options = {}) {
       error_code: 'claude_auth_preflight_failed',
       error: claudeAuthIssue.detail,
       auth_env_present: claudeAuthIssue.auth_env_present,
+      smoke_probe: claudeAuthIssue.smoke_probe,
       fix: claudeAuthIssue.fix,
       dispatch: null,
       validation: null,

package/src/templates/governed/enterprise-app.json

@@ -80,7 +80,7 @@
       "manual-pm": { "type": "manual" },
       "local-dev": {
         "type": "local_cli",
-        "command": ["claude", "--print", "--dangerously-skip-permissions"],
+        "command": ["claude", "--print", "--dangerously-skip-permissions", "--bare"],
         "cwd": ".",
         "prompt_transport": "stdin"
       },

package/src/templates/governed/full-local-cli.json

@@ -44,25 +44,25 @@
     "runtimes": {
       "local-pm": {
         "type": "local_cli",
-        "command": ["claude", "--print", "--dangerously-skip-permissions"],
+        "command": ["claude", "--print", "--dangerously-skip-permissions", "--bare"],
         "cwd": ".",
         "prompt_transport": "stdin"
       },
       "local-dev": {
         "type": "local_cli",
-        "command": ["claude", "--print", "--dangerously-skip-permissions"],
+        "command": ["claude", "--print", "--dangerously-skip-permissions", "--bare"],
         "cwd": ".",
         "prompt_transport": "stdin"
       },
       "local-qa": {
         "type": "local_cli",
-        "command": ["claude", "--print", "--dangerously-skip-permissions"],
+        "command": ["claude", "--print", "--dangerously-skip-permissions", "--bare"],
         "cwd": ".",
         "prompt_transport": "stdin"
       },
       "local-director": {
         "type": "local_cli",
-        "command": ["claude", "--print", "--dangerously-skip-permissions"],
+        "command": ["claude", "--print", "--dangerously-skip-permissions", "--bare"],
         "cwd": ".",
         "prompt_transport": "stdin"
       }