agentxchain 2.141.1 → 2.142.0

package/package.json

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

package/src/lib/governed-state.js

@@ -36,8 +36,10 @@ import {
   compareDeclaredVsObserved,
   deriveAcceptedRef,
   checkCleanBaseline,
+  detectDirtyFilesOutsideAllowed,
   isOperationalPath,
   isBaselineExemptPath,
+  normalizeCheckpointableFiles,
 } from './repo-observer.js';
 import { getMaxConcurrentTurns } from './normalized-config.js';
 import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir, getReviewArtifactPath } from './turn-paths.js';
@@ -65,6 +67,8 @@ import {
 } from './repo-decisions.js';
 import {
   replayVerificationMachineEvidence,
+  normalizeVerificationProducedFiles,
+  cleanupIgnoredVerificationFiles,
   summarizeVerificationReplay,
 } from './verification-replay.js';
 import { executeGateActions } from './gate-actions.js';
@@ -3205,7 +3209,16 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     };
   }
 
-  const turnResult = validation.turnResult;
+  const rawTurnResult = validation.turnResult;
+  const verificationProducedFiles = normalizeVerificationProducedFiles(rawTurnResult.verification);
+  const effectiveFilesChanged = normalizeCheckpointableFiles([
+    ...(rawTurnResult.files_changed || []),
+    ...verificationProducedFiles.artifact_files,
+  ]);
+  const turnResult = {
+    ...rawTurnResult,
+    files_changed: effectiveFilesChanged,
+  };
 
   // Validate cross-run decision overrides against repo-decisions.jsonl
   if (turnResult.decisions && turnResult.decisions.length > 0) {
@@ -3231,6 +3244,35 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const stagingFile = join(root, resolvedStagingPath);
   const now = new Date().toISOString();
   const baseline = currentTurn.baseline || null;
+  const ignoredVerificationCleanup = cleanupIgnoredVerificationFiles({
+    root,
+    baseline,
+    ignoredFiles: verificationProducedFiles.ignored_files,
+  });
+  if (ignoredVerificationCleanup.ok === false) {
+    const cleanupError = ignoredVerificationCleanup.cleanup_error
+      || 'Ignored verification-produced files could not be restored safely.';
+    transitionToFailedAcceptance(root, state, currentTurn, cleanupError, {
+      error_code: 'verification_produced_files_cleanup',
+      stage: 'artifact_observation',
+      extra: {
+        ignored_files: verificationProducedFiles.ignored_files,
+        restored_files: ignoredVerificationCleanup.restored_files || [],
+      },
+    });
+    return {
+      ok: false,
+      error: cleanupError,
+      validation: {
+        ...validation,
+        ok: false,
+        stage: 'artifact_observation',
+        error_class: 'artifact_error',
+        errors: [cleanupError],
+        warnings: validation.warnings,
+      },
+    };
+  }
   const rawObservation = observeChanges(root, baseline);
   const historyEntries = readJsonlEntries(root, HISTORY_PATH);
   const pendingConcurrentSiblingDeclarations = collectPendingConcurrentSiblingDeclarations(
@@ -3268,9 +3310,76 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const concurrentIds = new Set(
     Array.isArray(currentTurn.concurrent_with) ? currentTurn.concurrent_with : [],
   );
+  const concurrentAllowedDirtyFiles = [];
+  for (const declaration of pendingConcurrentSiblingDeclarations) {
+    concurrentIds.add(declaration?.turn_id);
+    for (const filePath of Array.isArray(declaration?.files_changed) ? declaration.files_changed : []) {
+      concurrentAllowedDirtyFiles.push(filePath);
+    }
+  }
+  for (const historyEntry of historyEntries) {
+    const isConcurrentSibling = concurrentIds.has(historyEntry?.turn_id)
+      || (Array.isArray(historyEntry?.concurrent_with) && historyEntry.concurrent_with.includes(currentTurn.turn_id));
+    if (!isConcurrentSibling) {
+      continue;
+    }
+    const siblingFiles = Array.isArray(historyEntry?.observed_artifact?.files_changed)
+      ? historyEntry.observed_artifact.files_changed
+      : historyEntry?.files_changed;
+    for (const filePath of Array.isArray(siblingFiles) ? siblingFiles : []) {
+      concurrentAllowedDirtyFiles.push(filePath);
+    }
+  }
   const acceptedTurnIds = new Set(historyEntries.map(h => h.turn_id));
   const hasUnacceptedConcurrentSiblings = [...concurrentIds].some(id => !acceptedTurnIds.has(id));
 
+  // Files from accepted-but-uncheckpointed prior turns are expected to be
+  // dirty in the working tree until `checkpoint-turn` commits them.  These
+  // must not block the current turn's acceptance — they are known accepted
+  // mutations, not undeclared agent writes.
+  const uncheckpointedPriorFiles = [];
+  for (const historyEntry of historyEntries) {
+    if (historyEntry.checkpoint_sha) continue; // already committed
+    const priorFiles = Array.isArray(historyEntry?.files_changed)
+      ? historyEntry.files_changed
+      : [];
+    for (const filePath of priorFiles) {
+      uncheckpointedPriorFiles.push(filePath);
+    }
+  }
+
+  const dirtyParity = detectDirtyFilesOutsideAllowed(
+    root,
+    writeAuthority,
+    [
+      ...(turnResult.files_changed || []),
+      ...concurrentAllowedDirtyFiles,
+      ...uncheckpointedPriorFiles,
+    ],
+  );
+  if (!dirtyParity.clean) {
+    transitionToFailedAcceptance(root, state, currentTurn, dirtyParity.reason, {
+      error_code: 'artifact_dirty_tree_mismatch',
+      stage: 'artifact_observation',
+      extra: {
+        unexpected_dirty_files: dirtyParity.unexpected_dirty_files,
+        dirty_files: dirtyParity.dirty_files,
+      },
+    });
+    return {
+      ok: false,
+      error: dirtyParity.reason,
+      validation: {
+        ...validation,
+        ok: false,
+        stage: 'artifact_observation',
+        error_class: 'artifact_error',
+        errors: [dirtyParity.reason],
+        warnings: validation.warnings,
+      },
+    };
+  }
+
   const diffComparison = compareDeclaredVsObserved(
     turnResult.files_changed || [],
     observation.files_changed,
@@ -3433,6 +3542,41 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const observedArtifact = buildObservedArtifact(observation, baseline);
   const normalizedVerification = normalizeVerification(turnResult.verification, runtimeType);
   const artifactType = turnResult.artifact?.type || 'review';
+
+  // BUG-46 fix requirement #6: workspace artifact with empty files_changed is a
+  // protocol violation for authoritative completed turns. A workspace artifact
+  // declares "I mutated repo files" — if files_changed is empty, the declaration
+  // is incoherent and must be rejected before replay or history persistence.
+  if (artifactType === 'workspace'
+    && writeAuthority === 'authoritative'
+    && turnResult.status === 'completed'
+    && (turnResult.files_changed || []).length === 0
+    && (observation.files_changed || []).length === 0) {
+    const emptyWsError = 'Turn declared artifact.type: "workspace" but files_changed is empty. '
+      + 'Either declare the files modified, or set artifact.type: "review" if no repo mutations were intended.';
+    transitionToFailedAcceptance(root, state, currentTurn, emptyWsError, {
+      error_code: 'empty_workspace_artifact',
+      stage: 'artifact_validation',
+      extra: {
+        artifact_type: artifactType,
+        write_authority: writeAuthority,
+        turn_status: turnResult.status,
+      },
+    });
+    return {
+      ok: false,
+      error: emptyWsError,
+      validation: {
+        ...validation,
+        ok: false,
+        stage: 'artifact_validation',
+        error_class: 'artifact_error',
+        errors: [emptyWsError],
+        warnings: validation.warnings,
+      },
+    };
+  }
+
   const derivedRef = deriveAcceptedRef(observation, artifactType, state.accepted_integration_ref);
   const verificationReplay = (config.policies || []).some((policy) => policy?.rule === 'require_reproducible_verification')
     ? replayVerificationMachineEvidence({ root, verification: turnResult.verification })
@@ -3740,7 +3884,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     summary: turnResult.summary,
     decisions: turnResult.decisions || [],
     objections: turnResult.objections || [],
-    files_changed: turnResult.files_changed || [],
+    files_changed: normalizeCheckpointableFiles(turnResult.files_changed),
     artifacts_created: turnResult.artifacts_created || [],
     verification: turnResult.verification || {},
     normalized_verification: normalizedVerification,

package/src/lib/repo-observer.js

@@ -79,6 +79,16 @@ export function isBaselineExemptPath(filePath) {
     || BASELINE_EXEMPT_PATH_PREFIXES.some(prefix => filePath.startsWith(prefix));
 }
 
+export function normalizeCheckpointableFiles(filesChanged) {
+  return [...new Set(
+    (Array.isArray(filesChanged) ? filesChanged : [])
+      .filter((value) => typeof value === 'string')
+      .map((value) => value.trim())
+      .filter(Boolean)
+      .filter((value) => !isOperationalPath(value)),
+  )];
+}
+
 // ── Baseline Capture ────────────────────────────────────────────────────────
 
 /**
@@ -631,6 +641,43 @@ export function checkCleanBaseline(root, writeAuthority) {
   };
 }
 
+export function detectDirtyFilesOutsideAllowed(root, writeAuthority, allowedFiles = []) {
+  const cleanCheck = checkCleanBaseline(root, writeAuthority);
+  if (cleanCheck.clean) {
+    return {
+      clean: true,
+      dirty_files: [],
+      unexpected_dirty_files: [],
+      reason: null,
+    };
+  }
+
+  const allowedSet = new Set(
+    (Array.isArray(allowedFiles) ? allowedFiles : [])
+      .filter((value) => typeof value === 'string')
+      .map((value) => value.trim())
+      .filter(Boolean),
+  );
+  const dirtyFiles = Array.isArray(cleanCheck.dirty_files) ? cleanCheck.dirty_files : [];
+  const unexpectedDirtyFiles = dirtyFiles.filter((filePath) => !allowedSet.has(filePath));
+
+  if (unexpectedDirtyFiles.length === 0) {
+    return {
+      clean: true,
+      dirty_files: dirtyFiles,
+      unexpected_dirty_files: [],
+      reason: null,
+    };
+  }
+
+  return {
+    clean: false,
+    dirty_files: dirtyFiles,
+    unexpected_dirty_files: unexpectedDirtyFiles,
+    reason: `Working tree has uncommitted changes in actor-owned files outside the accepted turn contract: ${unexpectedDirtyFiles.slice(0, 5).join(', ')}${unexpectedDirtyFiles.length > 5 ? '...' : ''}. Resume would block on the same files. Declare them in files_changed, classify verification outputs under verification.produced_files, or clean them before acceptance.`,
+  };
+}
+
 // ── Git Primitives ──────────────────────────────────────────────────────────
 
 function isGitRepo(root) {

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

@@ -165,6 +165,20 @@
               "exit_code": { "type": "integer" }
             }
           }
+        },
+        "produced_files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path"],
+            "additionalProperties": false,
+            "properties": {
+              "path": { "type": "string" },
+              "disposition": {
+                "enum": ["artifact", "ignore"]
+              }
+            }
+          }
         }
       }
     },

package/src/lib/turn-checkpoint.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { resolveAcceptedTurnHistoryReference } from './accepted-turn-history.js';
 import { emitRunEvent } from './run-events.js';
 import { safeWriteJson } from './safe-write.js';
+import { normalizeCheckpointableFiles } from './repo-observer.js';
 
 const STATE_PATH = '.agentxchain/state.json';
 const HISTORY_PATH = '.agentxchain/history.jsonl';
@@ -52,25 +53,8 @@ function isGitRepo(root) {
   }
 }
 
-// BUG-43: Staging and dispatch dirs are ephemeral — cleaned up after acceptance.
-// They must never appear in checkpoint git-add paths.
-const EPHEMERAL_PATH_PREFIXES = [
-  '.agentxchain/staging/',
-  '.agentxchain/dispatch/',
-];
-
-function isEphemeralPath(filePath) {
-  return EPHEMERAL_PATH_PREFIXES.some((prefix) => filePath.startsWith(prefix));
-}
-
 function normalizeFilesChanged(filesChanged) {
-  return [...new Set(
-    (Array.isArray(filesChanged) ? filesChanged : [])
-      .filter((value) => typeof value === 'string')
-      .map((value) => value.trim())
-      .filter(Boolean)
-      .filter((value) => !isEphemeralPath(value)),
-  )];
+  return normalizeCheckpointableFiles(filesChanged);
 }
 
 function extractGitError(err) {

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

@@ -624,6 +624,40 @@ function validateVerification(tr) {
     }
   }
 
+  if (Array.isArray(v.produced_files)) {
+    const seenProducedPaths = new Map();
+    const declaredFiles = new Set(Array.isArray(tr.files_changed) ? tr.files_changed : []);
+    for (let i = 0; i < v.produced_files.length; i++) {
+      const entry = v.produced_files[i];
+      if (typeof entry !== 'object' || entry === null) {
+        errors.push(`verification.produced_files[${i}] must be an object.`);
+        continue;
+      }
+
+      const rawPath = typeof entry.path === 'string' ? entry.path : '';
+      const path = rawPath.trim();
+      if (!path) {
+        errors.push(`verification.produced_files[${i}].path must be a non-empty string.`);
+      }
+
+      const disposition = entry.disposition == null ? 'artifact' : entry.disposition;
+      if (!['artifact', 'ignore'].includes(disposition)) {
+        errors.push(`verification.produced_files[${i}].disposition must be "artifact" or "ignore".`);
+      }
+
+      if (path) {
+        if (seenProducedPaths.has(path)) {
+          errors.push(`verification.produced_files[${i}].path duplicates "${path}" from verification.produced_files[${seenProducedPaths.get(path)}].`);
+        } else {
+          seenProducedPaths.set(path, i);
+        }
+        if (disposition === 'ignore' && declaredFiles.has(path)) {
+          errors.push(`verification.produced_files[${i}] marks "${path}" as ignore, but it is also listed in files_changed.`);
+        }
+      }
+    }
+  }
+
   return { errors, warnings };
 }
 

package/src/lib/verification-replay.js

@@ -81,6 +81,93 @@ export function summarizeVerificationReplay(payload) {
   };
 }
 
+export function normalizeVerificationProducedFiles(verification) {
+  const artifactFiles = new Set();
+  const ignoredFiles = new Set();
+  const producedFiles = Array.isArray(verification?.produced_files)
+    ? verification.produced_files
+    : [];
+
+  for (const entry of producedFiles) {
+    if (!entry || typeof entry !== 'object') {
+      continue;
+    }
+    const path = typeof entry.path === 'string' ? entry.path.trim() : '';
+    if (!path || isOperationalPath(path)) {
+      continue;
+    }
+    if (entry.disposition === 'ignore') {
+      ignoredFiles.add(path);
+    } else {
+      artifactFiles.add(path);
+    }
+  }
+
+  return {
+    artifact_files: [...artifactFiles].sort(),
+    ignored_files: [...ignoredFiles].sort(),
+  };
+}
+
+export function cleanupIgnoredVerificationFiles({ root, baseline, ignoredFiles }) {
+  const targetFiles = [...new Set(Array.isArray(ignoredFiles) ? ignoredFiles : [])]
+    .filter((filePath) => typeof filePath === 'string' && filePath && !isOperationalPath(filePath))
+    .sort();
+
+  if (targetFiles.length === 0 || !isGitRepo(root)) {
+    return { ok: true, restored_files: [], cleanup_error: null };
+  }
+
+  const restoredFiles = [];
+  const baselineSnapshot = baseline?.dirty_snapshot && typeof baseline.dirty_snapshot === 'object' && !Array.isArray(baseline.dirty_snapshot)
+    ? baseline.dirty_snapshot
+    : {};
+
+  try {
+    for (const filePath of targetFiles) {
+      const baselineMarker = baselineSnapshot[filePath];
+      const currentMarker = getWorkspaceFileMarker(root, filePath);
+
+      if (baselineMarker && currentMarker !== baselineMarker) {
+        return {
+          ok: false,
+          restored_files: restoredFiles.sort(),
+          cleanup_error: `verification.produced_files declared "${filePath}" as ignore, but that path was already dirty at dispatch and cannot be restored safely.`,
+        };
+      }
+
+      if (baselineMarker) {
+        continue;
+      }
+
+      restoreCleanPath(root, filePath);
+      restoredFiles.push(filePath);
+    }
+
+    const remainingDirty = new Set(collectDirtyActorFiles(root));
+    const stranded = targetFiles.filter((filePath) => remainingDirty.has(filePath));
+    if (stranded.length > 0) {
+      return {
+        ok: false,
+        restored_files: restoredFiles.sort(),
+        cleanup_error: `Ignored verification-produced files remain dirty after cleanup: ${stranded.join(', ')}`,
+      };
+    }
+
+    return {
+      ok: true,
+      restored_files: restoredFiles.sort(),
+      cleanup_error: null,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      restored_files: restoredFiles.sort(),
+      cleanup_error: err?.message || String(err),
+    };
+  }
+}
+
 function createReplayWorkspaceGuard(root) {
   if (!isGitRepo(root)) {
     return {