agentxchain 2.147.0 → 2.148.0

package/package.json

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

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

@@ -31,6 +31,15 @@ import {
 import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
 import { hasMeaningfulStagedResult } from '../staged-result-proof.js';
 
+const DIAGNOSTIC_ENV_KEYS = [
+  'PATH',
+  'HOME',
+  'PWD',
+  'SHELL',
+  'TMPDIR',
+  'AGENTXCHAIN_TURN_ID',
+];
+
 /**
  * Launch a local CLI subprocess for a governed turn.
  *
@@ -112,6 +121,10 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
   // Capture logs for dispatch record
   const logs = [];
+  const runtimeCwd = runtime.cwd ? join(root, runtime.cwd) : root;
+  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);
 
   return new Promise((resolve) => {
     if (signal?.aborted) {
@@ -121,12 +134,23 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
     let child;
     try {
+      appendDiagnostic(logs, 'spawn_prepare', {
+        runtime_id: runtimeId,
+        turn_id: turn.turn_id,
+        command,
+        args: diagnosticArgs,
+        cwd: runtimeCwd,
+        prompt_transport: transport,
+        stdin_bytes: stdinBytes,
+        env: pickDiagnosticEnv(spawnEnv),
+      });
       child = spawn(command, args, {
-        cwd: runtime.cwd ? join(root, runtime.cwd) : root,
+        cwd: runtimeCwd,
         stdio: ['pipe', 'pipe', 'pipe'],
-        env: { ...process.env, AGENTXCHAIN_TURN_ID: turn.turn_id },
+        env: spawnEnv,
       });
     } catch (err) {
+      appendDiagnostic(logs, 'spawn_error', normalizeDiagnosticError(err));
       resolve({
         ok: false,
         startupFailure: true,
@@ -140,9 +164,13 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     let settled = false;
     let firstOutputAt = null;
     let spawnConfirmedAt = null;
+    let spawnConfirmedAtMs = null;
+    let firstOutputLatencyMs = null;
     let startupWatchdog = null;
     let startupTimedOut = false;
     let startupFailureType = null;
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
 
     const settle = (result) => {
       if (settled) return;
@@ -168,8 +196,14 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
         startupTimedOut = true;
         startupFailureType = 'no_subprocess_output';
         logs.push(`[adapter] Startup watchdog fired after ${Math.round(startupWatchdogMs / 1000)}s with no output.`);
-        try {
-          child.kill('SIGTERM');
+      appendDiagnostic(logs, 'startup_watchdog_fired', {
+        startup_watchdog_ms: startupWatchdogMs,
+        pid: child.pid ?? null,
+        spawn_confirmed_at: spawnConfirmedAt,
+        elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
+      });
+      try {
+        child.kill('SIGTERM');
         } catch {}
       }, startupWatchdogMs);
     };
@@ -177,7 +211,14 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     const recordFirstOutput = (stream) => {
       if (firstOutputAt) return;
       firstOutputAt = new Date().toISOString();
+      firstOutputLatencyMs = spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs);
       clearStartupWatchdog();
+      appendDiagnostic(logs, 'first_output', {
+        at: firstOutputAt,
+        stream,
+        pid: child.pid ?? null,
+        startup_latency_ms: firstOutputLatencyMs,
+      });
       if (onFirstOutput) {
         try {
           onFirstOutput({ pid: child.pid ?? null, at: firstOutputAt, stream });
@@ -186,7 +227,13 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     };
 
     child.once('spawn', () => {
+      spawnConfirmedAtMs = Date.now();
       spawnConfirmedAt = new Date().toISOString();
+      appendDiagnostic(logs, 'spawn_attached', {
+        pid: child.pid ?? null,
+        at: spawnConfirmedAt,
+        startup_watchdog_ms: startupWatchdogMs,
+      });
       if (onSpawnAttached) {
         try {
           onSpawnAttached({ pid: child.pid ?? null, at: spawnConfirmedAt });
@@ -197,18 +244,32 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
     // Deliver prompt via stdin if transport is "stdin"; otherwise close immediately
     if (child.stdin) {
+      child.stdin.on('error', (err) => {
+        appendDiagnostic(logs, 'stdin_error', {
+          at: new Date().toISOString(),
+          stdin_bytes: stdinBytes,
+          ...normalizeDiagnosticError(err),
+        });
+      });
       try {
         if (transport === 'stdin') {
           child.stdin.write(fullPrompt);
         }
         child.stdin.end();
-      } catch {}
+      } catch (err) {
+        appendDiagnostic(logs, 'stdin_error', {
+          at: new Date().toISOString(),
+          stdin_bytes: stdinBytes,
+          ...normalizeDiagnosticError(err),
+        });
+      }
     }
 
     // Collect stdout/stderr
     if (child.stdout) {
       child.stdout.on('data', (chunk) => {
         const text = chunk.toString();
+        stdoutBytes += Buffer.byteLength(text);
         recordFirstOutput('stdout');
         logs.push(text);
         if (onStdout) onStdout(text);
@@ -218,6 +279,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     if (child.stderr) {
       child.stderr.on('data', (chunk) => {
         const text = chunk.toString();
+        stderrBytes += Buffer.byteLength(text);
         recordFirstOutput('stderr');
         logs.push('[stderr] ' + text);
         if (onStderr) onStderr(text);
@@ -283,6 +345,28 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       if (hasResult && !firstOutputAt) {
         recordFirstOutput('staged_result');
       }
+      const exitDiagnostic = {
+        pid: child.pid ?? null,
+        exit_code: exitCode,
+        signal: killSignal,
+        spawn_confirmed_at: spawnConfirmedAt,
+        elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
+        first_output_at: firstOutputAt,
+        startup_latency_ms: firstOutputLatencyMs,
+        stdout_bytes: stdoutBytes,
+        stderr_bytes: stderrBytes,
+        staged_result_ready: hasResult,
+      };
+      if (startupTimedOut) {
+        exitDiagnostic.startup_failure_type = startupFailureType || 'no_subprocess_output';
+      } else if (!spawnConfirmedAt) {
+        exitDiagnostic.startup_failure_type = 'runtime_spawn_failed';
+      } else if (timedOut) {
+        exitDiagnostic.timed_out = true;
+      } else if (!firstOutputAt) {
+        exitDiagnostic.startup_failure_type = 'no_subprocess_output';
+      }
+      appendDiagnostic(logs, 'process_exit', exitDiagnostic);
 
       if (hasResult) {
         settle({ ok: true, exitCode, timedOut: false, aborted: false, logs, firstOutputAt });
@@ -344,6 +428,25 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
       if (signal) signal.removeEventListener('abort', onAbort);
+      // BUG-54 hypothesis #1 fix: explicitly release stdio streams on the
+      // error path so Node reclaims pipe handles immediately instead of
+      // waiting for GC. Without this, repeated `runtime_spawn_failed` turns
+      // leak ~4 handles per failure until the next GC sweep, which in a
+      // long-running `run --continuous` session can push the parent process
+      // toward its fd limit and cascade additional spawn failures.
+      try { child.stdin?.destroy(); } catch {}
+      try { child.stdout?.destroy(); } catch {}
+      try { child.stderr?.destroy(); } catch {}
+      appendDiagnostic(logs, 'spawn_error', {
+        pid: child.pid ?? null,
+        spawn_confirmed_at: spawnConfirmedAt,
+        elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
+        first_output_at: firstOutputAt,
+        startup_latency_ms: firstOutputLatencyMs,
+        stdout_bytes: stdoutBytes,
+        stderr_bytes: stderrBytes,
+        ...normalizeDiagnosticError(err),
+      });
       settle({
         ok: false,
         startupFailure: !firstOutputAt,
@@ -458,4 +561,38 @@ function resolveTargetTurn(state, turnId) {
   return state?.current_turn || Object.values(state?.active_turns || {})[0];
 }
 
+function appendDiagnostic(logs, label, payload) {
+  logs.push(`[adapter:diag] ${label} ${JSON.stringify(payload)}\n`);
+}
+
+function pickDiagnosticEnv(env) {
+  return Object.fromEntries(
+    DIAGNOSTIC_ENV_KEYS
+      .filter((key) => typeof env?.[key] === 'string' && env[key].length > 0)
+      .map((key) => [key, env[key]]),
+  );
+}
+
+function redactPromptArgs(args, fullPrompt, transport) {
+  const promptPlaceholder = `<prompt:${Buffer.byteLength(fullPrompt, 'utf8')} bytes>`;
+  return args.map((arg) => {
+    if (typeof arg !== 'string') {
+      return arg;
+    }
+    if (transport === 'argv' && arg === fullPrompt) {
+      return promptPlaceholder;
+    }
+    return arg;
+  });
+}
+
+function normalizeDiagnosticError(err) {
+  return {
+    code: err?.code || null,
+    errno: err?.errno || null,
+    syscall: err?.syscall || null,
+    message: err?.message || String(err),
+  };
+}
+
 export { resolvePromptTransport };

package/src/lib/governed-state.js

@@ -3729,8 +3729,37 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     ],
   );
   if (!dirtyParity.clean) {
-    transitionToFailedAcceptance(root, state, currentTurn, dirtyParity.reason, {
-      error_code: 'artifact_dirty_tree_mismatch',
+    // BUG-55 sub-defect B: when the turn declared verification commands or
+    // machine evidence, undeclared dirty files are most likely verification
+    // outputs that need classification under verification.produced_files
+    // (disposition 'ignore' to clean up, or 'artifact' to include in the
+    // checkpoint). Surface a dedicated error class + message so the agent
+    // knows the correct remediation surface, instead of the generic
+    // files_changed-or-produced_files-or-clean advice that the non-
+    // verification path emits.
+    const verification = turnResult.verification && typeof turnResult.verification === 'object'
+      ? turnResult.verification
+      : {};
+    const declaredVerificationCommands = Array.isArray(verification.commands)
+      && verification.commands.some((c) => typeof c === 'string' && c.trim().length > 0);
+    const declaredMachineEvidence = Array.isArray(verification.machine_evidence)
+      && verification.machine_evidence.some((e) => e && typeof e === 'object' && typeof e.command === 'string' && e.command.trim().length > 0);
+    const verificationWasDeclared = declaredVerificationCommands || declaredMachineEvidence;
+
+    let failureReason = dirtyParity.reason;
+    let failureErrorCode = 'artifact_dirty_tree_mismatch';
+    if (verificationWasDeclared) {
+      failureErrorCode = 'undeclared_verification_outputs';
+      const undeclared = Array.isArray(dirtyParity.unexpected_dirty_files)
+        ? dirtyParity.unexpected_dirty_files
+        : [];
+      const listForMessage = undeclared.slice(0, 5).join(', ')
+        + (undeclared.length > 5 ? '...' : '');
+      failureReason = `Verification was declared (commands or machine_evidence), but these files are dirty and not classified: ${listForMessage}. Classify each under verification.produced_files with disposition "ignore" (the file should be cleaned up after replay) or "artifact" (the file should be checkpointed as part of the turn), OR add it to files_changed if it is a core turn mutation. Acceptance cannot proceed until the declared contract matches the working tree.`;
+    }
+
+    transitionToFailedAcceptance(root, state, currentTurn, failureReason, {
+      error_code: failureErrorCode,
       stage: 'artifact_observation',
       extra: {
         unexpected_dirty_files: dirtyParity.unexpected_dirty_files,
@@ -3739,13 +3768,14 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     });
     return {
       ok: false,
-      error: dirtyParity.reason,
+      error: failureReason,
+      error_code: failureErrorCode,
       validation: {
         ...validation,
         ok: false,
         stage: 'artifact_observation',
         error_class: 'artifact_error',
-        errors: [dirtyParity.reason],
+        errors: [failureReason],
         warnings: validation.warnings,
       },
     };

package/src/lib/schemas/turn-result.schema.json

@@ -148,7 +148,10 @@
         },
         "commands": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string",
+            "pattern": "\\S"
+          },
           "description": "Verification commands that were run."
         },
         "evidence_summary": {
@@ -161,7 +164,10 @@
             "type": "object",
             "required": ["command", "exit_code"],
             "properties": {
-              "command": { "type": "string" },
+              "command": {
+                "type": "string",
+                "pattern": "\\S"
+              },
               "exit_code": { "type": "integer" }
             }
           }

package/src/lib/turn-checkpoint.js

@@ -139,6 +139,53 @@ function buildCheckpointCommit(entry) {
   return { subject, body: bodyLines.join('\n') };
 }
 
+function diffMissingDeclaredPaths(declaredFiles, stagedFiles) {
+  const stagedSet = new Set((Array.isArray(stagedFiles) ? stagedFiles : []).map((value) => value.trim()).filter(Boolean));
+  return (Array.isArray(declaredFiles) ? declaredFiles : []).filter((filePath) => !stagedSet.has(filePath));
+}
+
+/**
+ * Partition paths that were missing from the staged-diff into
+ * (a) paths genuinely absent from git (untracked or dirty without staging)
+ * (b) paths already committed upstream (tracked in HEAD, no pending diff)
+ *
+ * BUG-55A completeness must only fail on (a). An actor that committed a
+ * declared file before `checkpoint-turn` ran (see BUG-23 scenario) is
+ * already-checkpointed-upstream; treating that as "missing from checkpoint"
+ * is a false positive from the completeness gate.
+ */
+function partitionDeclaredPathsByUpstreamPresence(root, missingPaths) {
+  const genuinelyMissing = [];
+  const alreadyCommittedUpstream = [];
+  for (const filePath of missingPaths) {
+    let tracked = false;
+    try {
+      git(root, ['ls-files', '--error-unmatch', '--', filePath]);
+      tracked = true;
+    } catch {
+      tracked = false;
+    }
+    if (!tracked) {
+      genuinelyMissing.push(filePath);
+      continue;
+    }
+    let hasDivergence = false;
+    try {
+      const headDiff = git(root, ['diff', 'HEAD', '--', filePath]);
+      const cachedDiff = git(root, ['diff', '--cached', '--', filePath]);
+      hasDivergence = Boolean(headDiff) || Boolean(cachedDiff);
+    } catch {
+      hasDivergence = true;
+    }
+    if (hasDivergence) {
+      genuinelyMissing.push(filePath);
+    } else {
+      alreadyCommittedUpstream.push(filePath);
+    }
+  }
+  return { genuinelyMissing, alreadyCommittedUpstream };
+}
+
 export function detectPendingCheckpoint(root, dirtyFiles = []) {
   const actorDirtyFiles = normalizeFilesChanged(dirtyFiles);
   if (actorDirtyFiles.length === 0) return { required: false };
@@ -233,12 +280,29 @@ export function checkpointAcceptedTurn(root, opts = {}) {
     };
   }
 
+  const rawMissingFromStage = diffMissingDeclaredPaths(filesChanged, staged);
+  const { genuinelyMissing, alreadyCommittedUpstream } =
+    partitionDeclaredPathsByUpstreamPresence(root, rawMissingFromStage);
+  if (genuinelyMissing.length > 0) {
+    return {
+      ok: false,
+      turn: entry,
+      error: `Checkpoint completeness failure: accepted turn ${entry.turn_id} declared ${filesChanged.length} checkpointable file(s), but Git staged only ${staged.length} and ${genuinelyMissing.length} declared path(s) are absent from git. Missing from checkpoint: ${genuinelyMissing.join(', ')}.`,
+      missing_declared_paths: genuinelyMissing,
+      already_committed_upstream: alreadyCommittedUpstream,
+      staged_paths: staged,
+    };
+  }
+
   if (staged.length === 0) {
     return {
       ok: true,
       skipped: true,
       turn: entry,
-      reason: `Accepted turn ${entry.turn_id} has no staged repo changes to checkpoint.`,
+      reason: alreadyCommittedUpstream.length > 0
+        ? `Accepted turn ${entry.turn_id} has no staged repo changes to checkpoint; all ${alreadyCommittedUpstream.length} declared file(s) already present in HEAD.`
+        : `Accepted turn ${entry.turn_id} has no staged repo changes to checkpoint.`,
+      already_committed_upstream: alreadyCommittedUpstream,
     };
   }
 

package/src/lib/turn-result-validator.js

@@ -600,6 +600,15 @@ function validateVerification(tr) {
     }
   }
 
+  if (Array.isArray(v.commands)) {
+    for (let i = 0; i < v.commands.length; i++) {
+      const command = v.commands[i];
+      if (typeof command !== 'string' || command.trim().length === 0) {
+        errors.push(`verification.commands[${i}] must be a non-empty string.`);
+      }
+    }
+  }
+
   // machine_evidence exit codes should be consistent with status
   if (Array.isArray(v.machine_evidence)) {
     for (let i = 0; i < v.machine_evidence.length; i++) {
@@ -608,8 +617,8 @@ function validateVerification(tr) {
         errors.push(`verification.machine_evidence[${i}] must be an object.`);
         continue;
       }
-      if (typeof entry.command !== 'string') {
-        errors.push(`verification.machine_evidence[${i}].command must be a string.`);
+      if (typeof entry.command !== 'string' || entry.command.trim().length === 0) {
+        errors.push(`verification.machine_evidence[${i}].command must be a non-empty string.`);
       }
       if (typeof entry.exit_code !== 'number' || !Number.isInteger(entry.exit_code)) {
         errors.push(`verification.machine_evidence[${i}].exit_code must be an integer.`);