agentxchain 2.155.36 → 2.155.38

package/package.json

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

package/scripts/release-bump.sh

@@ -89,6 +89,7 @@ ALLOWED_RELEASE_PATHS=(
   "website-v2/docs/getting-started.mdx"
   "website-v2/docs/quickstart.mdx"
   "website-v2/docs/five-minute-tutorial.mdx"
+  "website-v2/docs/releases/v2-147-0.mdx"
   "cli/test/hn-launch-surface-content.test.js"
   "cli/homebrew/agentxchain.rb"
   "cli/homebrew/README.md"

package/src/lib/dispatch-bundle.js

@@ -499,6 +499,7 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   lines.push('- `verification.status`: one of `pass`, `fail`, `skipped`');
   lines.push('- `verification.status: "pass"` is valid only when every `verification.machine_evidence[].exit_code` is `0`');
   lines.push('- Expected-failure checks must be wrapped in a verifier that exits `0` when the failure occurs as expected; do not list raw non-zero negative-case commands on a passing turn');
+  lines.push('- If verification commands produce side-effect files (e.g., `.tusq/plan.json`, `coverage/`, `.cache/`), declare each in `verification.produced_files` with `disposition: "ignore"` (temporary output to clean up) or `disposition: "artifact"` (output to checkpoint as a turn deliverable). Undeclared dirty files with declared verification will be auto-cleaned but declaring them is preferred.');
   lines.push('- `artifact.type`: one of `workspace`, `patch`, `commit`, `review`');
   lines.push('- If you make zero repo file edits, set `artifact.type` to `"review"` and `files_changed` to `[]`.');
   lines.push('- Only set `artifact.type` to `"workspace"` when you actually modified repo files and listed every changed path in `files_changed`.');

package/src/lib/export-verifier.js

@@ -98,6 +98,49 @@ function verifyFileEntry(relPath, entry, errors) {
     addError(errors, path, 'sha256 must be a 64-character lowercase hex digest');
   }
 
+  if (entry.content_base64 === null) {
+    const isTruncated = entry.truncated === true;
+    const isSkipped = entry.content_base64_skipped === true;
+    if (!isTruncated && !isSkipped) {
+      addError(errors, path, 'content_base64 may be null only when truncated or content_base64_skipped is true');
+      return;
+    }
+    if (isTruncated) {
+      if (entry.format !== 'jsonl') {
+        addError(errors, path, 'truncated file entries must use jsonl format');
+      }
+      if (!Array.isArray(entry.data)) {
+        addError(errors, path, 'truncated JSONL data must be an array');
+      }
+      if (!Number.isInteger(entry.total_entries) || entry.total_entries < 0) {
+        addError(errors, path, 'total_entries must be a non-negative integer when truncated');
+      }
+      if (!Number.isInteger(entry.retained_entries) || entry.retained_entries < 0) {
+        addError(errors, path, 'retained_entries must be a non-negative integer when truncated');
+      }
+      if (Array.isArray(entry.data) && entry.retained_entries !== entry.data.length) {
+        addError(errors, path, 'retained_entries must match truncated data length');
+      }
+      if (
+        Number.isInteger(entry.total_entries)
+        && Number.isInteger(entry.retained_entries)
+        && entry.retained_entries > entry.total_entries
+      ) {
+        addError(errors, path, 'retained_entries must not exceed total_entries');
+      }
+      return;
+    }
+    if (entry.format === 'jsonl' && !Array.isArray(entry.data)) {
+      addError(errors, path, 'skipped JSONL data must be an array');
+      return;
+    }
+    if (entry.format === 'text' && typeof entry.data !== 'string') {
+      addError(errors, path, 'skipped text data must be a string');
+      return;
+    }
+    return;
+  }
+
   if (typeof entry.content_base64 !== 'string') {
     addError(errors, path, 'content_base64 must be a string');
     return;

package/src/lib/governed-state.js

@@ -4531,39 +4531,97 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       && 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.`;
+    // ── BUG-87: Auto-normalize undeclared verification outputs ──────────
+    // When verification was declared and unexpected dirty files exist,
+    // attempt to clean them up as ignored verification outputs before
+    // hard-erroring. This covers tool-generated side-effect files (e.g.,
+    // .tusq/plan.json, coverage/) that the agent failed to declare in
+    // verification.produced_files. cleanupIgnoredVerificationFiles already
+    // respects the dispatch baseline: only files NOT dirty at dispatch
+    // time are cleaned; pre-existing dirty files are left untouched.
+    if (verificationWasDeclared && Array.isArray(dirtyParity.unexpected_dirty_files) && dirtyParity.unexpected_dirty_files.length > 0) {
+      const autoClassifyAttempt = cleanupIgnoredVerificationFiles({
+        root,
+        baseline,
+        ignoredFiles: dirtyParity.unexpected_dirty_files,
+      });
+      if (autoClassifyAttempt.ok) {
+        // Re-check dirty parity after cleanup
+        const recheckParity = detectDirtyFilesOutsideAllowed(
+          root,
+          writeAuthority,
+          [
+            ...(turnResult.files_changed || []),
+            ...concurrentAllowedDirtyFiles,
+            ...uncheckpointedPriorFiles,
+          ],
+        );
+        if (recheckParity.clean) {
+          const autoClassifiedFiles = dirtyParity.unexpected_dirty_files;
+          // Auto-normalization succeeded — emit audit event and continue
+          emitRunEvent(root, 'verification_output_auto_normalized', {
+            run_id: state.run_id,
+            phase: state.phase,
+            status: state.status,
+            turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+            intent_id: currentTurn.intake_context?.intent_id || null,
+            payload: {
+              auto_classified_files: autoClassifiedFiles,
+              restored_files: autoClassifyAttempt.restored_files || [],
+              disposition: 'ignore',
+              rationale: 'undeclared_verification_output_auto_normalized',
+            },
+          });
+          // Remove auto-classified files from the observation so
+          // compareDeclaredVsObserved does not re-flag them as undeclared.
+          const autoSet = new Set(autoClassifiedFiles);
+          if (Array.isArray(observation.files_changed)) {
+            observation.files_changed = observation.files_changed.filter(
+              (f) => !autoSet.has(f),
+            );
+          }
+          // Fall through to the rest of acceptance (skip the error block)
+          dirtyParity.clean = true;
+        }
+      }
     }
+    // ── End BUG-87 ──────────────────────────────────────────────────────
+
+    if (!dirtyParity.clean) {
+      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,
-        dirty_files: dirtyParity.dirty_files,
-      },
-    });
-    return {
-      ok: false,
-      error: failureReason,
-      error_code: failureErrorCode,
-      validation: {
-        ...validation,
-        ok: false,
+      transitionToFailedAcceptance(root, state, currentTurn, failureReason, {
+        error_code: failureErrorCode,
         stage: 'artifact_observation',
-        error_class: 'artifact_error',
-        errors: [failureReason],
-        warnings: validation.warnings,
-      },
-    };
+        extra: {
+          unexpected_dirty_files: dirtyParity.unexpected_dirty_files,
+          dirty_files: dirtyParity.dirty_files,
+        },
+      });
+      return {
+        ok: false,
+        error: failureReason,
+        error_code: failureErrorCode,
+        validation: {
+          ...validation,
+          ok: false,
+          stage: 'artifact_observation',
+          error_class: 'artifact_error',
+          errors: [failureReason],
+          warnings: validation.warnings,
+        },
+      };
+    }
   }
 
   const diffComparison = compareDeclaredVsObserved(