agentxchain 2.140.0 → 2.142.0

package/package.json

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

package/scripts/release-preflight.sh

@@ -153,7 +153,7 @@ if [[ "$PUBLISH_GATE" -eq 1 ]]; then
     test/release-notes-gate.test.js
     test/release-identity-hardening.test.js
     test/normalized-config.test.js
-    test/conformance.test.js
+    test/protocol-conformance.test.js
     test/beta-scenario-emission-guard.test.js
     test/claim-reality-preflight.test.js
     test/beta-tester-scenarios/*.test.js

package/src/lib/governed-state.js

@@ -36,7 +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';
@@ -64,6 +67,8 @@ import {
 } from './repo-decisions.js';
 import {
   replayVerificationMachineEvidence,
+  normalizeVerificationProducedFiles,
+  cleanupIgnoredVerificationFiles,
   summarizeVerificationReplay,
 } from './verification-replay.js';
 import { executeGateActions } from './gate-actions.js';
@@ -106,6 +111,34 @@ function buildInitialPhaseGateStatus(config) {
   );
 }
 
+function buildObservationDrift(beforeObservation, afterObservation) {
+  const beforeFiles = (Array.isArray(beforeObservation?.files_changed) ? beforeObservation.files_changed : [])
+    .filter((filePath) => !isBaselineExemptPath(filePath));
+  const afterFiles = (Array.isArray(afterObservation?.files_changed) ? afterObservation.files_changed : [])
+    .filter((filePath) => !isBaselineExemptPath(filePath));
+  const beforeSet = new Set(beforeFiles);
+  const afterSet = new Set(afterFiles);
+  const beforeMarkers = beforeObservation?.file_markers && typeof beforeObservation.file_markers === 'object'
+    ? beforeObservation.file_markers
+    : {};
+  const afterMarkers = afterObservation?.file_markers && typeof afterObservation.file_markers === 'object'
+    ? afterObservation.file_markers
+    : {};
+
+  const added = afterFiles.filter((filePath) => !beforeSet.has(filePath));
+  const removed = beforeFiles.filter((filePath) => !afterSet.has(filePath));
+  const markerChanged = beforeFiles.filter((filePath) => (
+    afterSet.has(filePath) && beforeMarkers[filePath] !== afterMarkers[filePath]
+  ));
+
+  return {
+    added,
+    removed,
+    marker_changed: markerChanged,
+    drifted_files: [...new Set([...added, ...removed, ...markerChanged])].sort(),
+  };
+}
+
 function listIntakeIntentFiles(root) {
   const intentsDir = join(root, INTAKE_INTENTS_DIR);
   if (!existsSync(intentsDir)) return [];
@@ -3176,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) {
@@ -3202,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(
@@ -3210,11 +3281,17 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     currentTurn,
     historyEntries,
   );
-  const observation = attributeObservedChangesToTurn(rawObservation, currentTurn, historyEntries, {
+  const observationAttributionOptions = {
     currentDeclaredFiles: turnResult.files_changed || [],
     concurrentSiblingIds: pendingConcurrentSiblingDeclarations.map((entry) => entry.turn_id),
     pendingConcurrentSiblingDeclarations,
-  });
+  };
+  const observation = attributeObservedChangesToTurn(
+    rawObservation,
+    currentTurn,
+    historyEntries,
+    observationAttributionOptions,
+  );
   const role = config.roles?.[turnResult.role];
   const runtimeId = turnResult.runtime_id;
   const runtime = config.runtimes?.[runtimeId];
@@ -3233,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,
@@ -3398,11 +3542,70 @@ 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 })
     : null;
 
+  if (verificationReplay?.workspace_guard?.ok === false) {
+    const replayError = verificationReplay.workspace_guard.cleanup_error
+      || 'Verification replay mutated actor-owned workspace files and cleanup failed.';
+    transitionToFailedAcceptance(root, state, currentTurn, replayError, {
+      error_code: 'verification_replay_drift',
+      stage: 'verification_replay',
+      extra: {
+        replay_side_effect_files: verificationReplay.workspace_guard.restored_files || [],
+      },
+    });
+    return {
+      ok: false,
+      error: replayError,
+      validation: {
+        ...validation,
+        ok: false,
+        stage: 'verification_replay',
+        error_class: 'verification_replay_error',
+        errors: [replayError],
+        warnings: validation.warnings,
+      },
+    };
+  }
+
   // Policy evaluation — declarative governance rules (spec: POLICY_ENGINE_SPEC.md)
   const policyResult = evaluatePolicies(config.policies || [], {
     currentPhase: state.phase,
@@ -3638,6 +3841,38 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }
   }
 
+  const finalObservation = attributeObservedChangesToTurn(
+    observeChanges(root, baseline),
+    currentTurn,
+    historyEntries,
+    observationAttributionOptions,
+  );
+  const observationDrift = buildObservationDrift(observation, finalObservation);
+  if (observationDrift.drifted_files.length > 0) {
+    const driftError = `Acceptance mutated actor-owned workspace after artifact observation: ${observationDrift.drifted_files.join(', ')}`;
+    transitionToFailedAcceptance(root, state, currentTurn, driftError, {
+      error_code: 'acceptance_drift',
+      stage: 'artifact_observation',
+      extra: {
+        added_files: observationDrift.added,
+        removed_files: observationDrift.removed,
+        marker_changed_files: observationDrift.marker_changed,
+      },
+    });
+    return {
+      ok: false,
+      error: driftError,
+      validation: {
+        ...validation,
+        ok: false,
+        stage: 'artifact_observation',
+        error_class: 'artifact_error',
+        errors: [driftError],
+        warnings: validation.warnings,
+      },
+    };
+  }
+
   const acceptedSequence = (state.turn_sequence || 0) + 1;
   const historyEntry = {
     turn_id: turnResult.turn_id,
@@ -3649,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

@@ -29,6 +29,8 @@ const OPERATIONAL_PATH_PREFIXES = [
   '.agentxchain/intake/',
   '.agentxchain/locks/',
   '.agentxchain/transactions/',
+  '.agentxchain/missions/',
+  '.agentxchain/multirepo/',
 ];
 
 // Orchestrator-owned state files that agents must never be blamed for modifying.
@@ -38,6 +40,7 @@ const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/session.json',
   '.agentxchain/history.jsonl',
   '.agentxchain/decision-ledger.jsonl',
+  '.agentxchain/repo-decisions.jsonl',
   '.agentxchain/lock.json',
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
@@ -71,11 +74,21 @@ export function isOperationalPath(filePath) {
     || ORCHESTRATOR_STATE_FILES.includes(filePath);
 }
 
-function isBaselineExemptPath(filePath) {
+export function isBaselineExemptPath(filePath) {
   return isOperationalPath(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 ────────────────────────────────────────────────────────
 
 /**
@@ -628,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

@@ -1,4 +1,10 @@
-import { spawnSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { isOperationalPath } from './repo-observer.js';
 
 export const DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS = 30_000;
 
@@ -22,10 +28,15 @@ export function replayVerificationMachineEvidence({ root, verification, timeoutM
     return payload;
   }
 
-  payload.commands = machineEvidence.map((entry, index) => replayEvidenceCommand(root, entry, index, timeoutMs));
-  payload.replayed_commands = payload.commands.length;
-  payload.matched_commands = payload.commands.filter((entry) => entry.matched).length;
-  payload.overall = payload.commands.every((entry) => entry.matched) ? 'match' : 'mismatch';
+  const workspaceGuard = createReplayWorkspaceGuard(root);
+  try {
+    payload.commands = machineEvidence.map((entry, index) => replayEvidenceCommand(root, entry, index, timeoutMs));
+    payload.replayed_commands = payload.commands.length;
+    payload.matched_commands = payload.commands.filter((entry) => entry.matched).length;
+    payload.overall = payload.commands.every((entry) => entry.matched) ? 'match' : 'mismatch';
+  } finally {
+    payload.workspace_guard = workspaceGuard.cleanup();
+  }
 
   return payload;
 }
@@ -69,3 +80,273 @@ export function summarizeVerificationReplay(payload) {
     ...(payload.reason ? { reason: payload.reason } : {}),
   };
 }
+
+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 {
+      cleanup() {
+        return { ok: true, restored_files: [], cleanup_error: null };
+      },
+    };
+  }
+
+  const backupDir = mkdtempSync(join(tmpdir(), 'axc-verification-replay-'));
+  const beforeState = captureDirtyWorkspaceState(root, backupDir);
+
+  return {
+    cleanup() {
+      const restoredFiles = new Set();
+
+      try {
+        const afterFiles = collectDirtyActorFiles(root);
+        const candidateFiles = new Set([...beforeState.files.keys(), ...afterFiles]);
+
+        for (const filePath of candidateFiles) {
+          const beforeInfo = beforeState.files.get(filePath);
+          const currentMarker = getWorkspaceFileMarker(root, filePath);
+
+          if (beforeInfo) {
+            if (currentMarker !== beforeInfo.marker) {
+              restorePreReplayPath(root, filePath, beforeInfo);
+              restoredFiles.add(filePath);
+            }
+            continue;
+          }
+
+          restoreCleanPath(root, filePath);
+          restoredFiles.add(filePath);
+        }
+
+        const remainingDrift = detectWorkspaceDrift(root, beforeState.files);
+        if (remainingDrift.length > 0) {
+          return {
+            ok: false,
+            restored_files: [...restoredFiles].sort(),
+            cleanup_error: `Verification replay left actor-owned workspace drift after cleanup: ${remainingDrift.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),
+        };
+      } finally {
+        rmSync(backupDir, { recursive: true, force: true });
+      }
+    },
+  };
+}
+
+function captureDirtyWorkspaceState(root, backupDir) {
+  const files = new Map();
+  for (const filePath of collectDirtyActorFiles(root)) {
+    const absPath = join(root, filePath);
+    const backupPath = join(backupDir, filePath);
+    const existed = existsSync(absPath);
+    const marker = getWorkspaceFileMarker(root, filePath);
+
+    if (existed) {
+      mkdirSync(dirname(backupPath), { recursive: true });
+      cpSync(absPath, backupPath, { force: true, recursive: true });
+    }
+
+    files.set(filePath, { existed, marker, backupPath });
+  }
+  return { files };
+}
+
+function detectWorkspaceDrift(root, beforeFiles) {
+  const afterFiles = collectDirtyActorFiles(root);
+  const candidates = new Set([...beforeFiles.keys(), ...afterFiles]);
+  const drift = [];
+
+  for (const filePath of candidates) {
+    const beforeInfo = beforeFiles.get(filePath);
+    const currentMarker = getWorkspaceFileMarker(root, filePath);
+    if (beforeInfo) {
+      if (currentMarker !== beforeInfo.marker) {
+        drift.push(filePath);
+      }
+      continue;
+    }
+    drift.push(filePath);
+  }
+
+  return drift.sort();
+}
+
+function restorePreReplayPath(root, filePath, beforeInfo) {
+  const absPath = join(root, filePath);
+  if (!beforeInfo.existed) {
+    rmSync(absPath, { recursive: true, force: true });
+    return;
+  }
+
+  rmSync(absPath, { recursive: true, force: true });
+  mkdirSync(dirname(absPath), { recursive: true });
+  cpSync(beforeInfo.backupPath, absPath, { force: true, recursive: true });
+}
+
+function restoreCleanPath(root, filePath) {
+  const absPath = join(root, filePath);
+  if (isTrackedPath(root, filePath)) {
+    execFileSync('git', ['restore', '--source=HEAD', '--staged', '--worktree', '--', filePath], {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return;
+  }
+
+  rmSync(absPath, { recursive: true, force: true });
+}
+
+function collectDirtyActorFiles(root) {
+  return [...new Set([
+    ...readGitLines(root, ['diff', '--name-only', 'HEAD']),
+    ...readGitLines(root, ['diff', '--name-only', '--cached']),
+    ...readGitLines(root, ['ls-files', '--others', '--exclude-standard']),
+  ])]
+    .filter((filePath) => filePath && !isOperationalPath(filePath))
+    .sort();
+}
+
+function readGitLines(root, args) {
+  try {
+    const output = execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    return output ? output.split('\n').filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+
+function isTrackedPath(root, filePath) {
+  try {
+    execFileSync('git', ['ls-files', '--error-unmatch', '--', filePath], {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isGitRepo(root) {
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getWorkspaceFileMarker(root, filePath) {
+  const absPath = join(root, filePath);
+  if (!existsSync(absPath)) {
+    return '__deleted__';
+  }
+
+  const content = readFileSync(absPath);
+  return createHash('sha1').update(content).digest('hex');
+}