codex-workflow-v2 2.0.0-beta.13.9 → 2.0.0-beta.14

package/src/alpha6/captured-check-evidence.ts

@@ -0,0 +1,132 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import type { StepFailurePause, TaskState } from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import type { CheckResult } from '../git.js';
+import type { FileStateStore } from '../state/store.js';
+import { canonicalJsonStringify, sha256Hex } from './store-sidecars.js';
+
+const KIND = 'captured-checks/v1' as const;
+const HASH = /^[a-f0-9]{64}$/;
+function corrupt(): never {
+  // Never include captured output or parsing errors in public diagnostics.
+  throw new WorkflowError('STATE_CORRUPT', 'Captured check evidence is missing, unsafe, or does not match its binding.');
+}
+function inspect(file: string) {
+  try { return lstatSync(file); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    return corrupt();
+  }
+}
+function artifactFile(store: FileStateStore, task: TaskState, checksHash: string): string {
+  if (!HASH.test(checksHash)) corrupt();
+  const root = store.taskRoot(task.projectId, task.id);
+  const directory = path.join(root, 'check-results');
+  for (const item of [root, directory]) {
+    const stat = inspect(item);
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0)) corrupt();
+  }
+  return path.join(directory, `${checksHash}.json`);
+}
+function readBytes(file: string, maxBytes: number): string | null {
+  const stat = inspect(file);
+  if (!stat) return null;
+  if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || stat.size > maxBytes) corrupt();
+  try { return readFileSync(file, 'utf8'); } catch { return corrupt(); }
+}
+function validateChecks(value: unknown): asserts value is CheckResult[] {
+  if (!Array.isArray(value) || value.length === 0) corrupt();
+  for (const item of value) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)
+      || Object.keys(item).sort().join(',') !== 'command,exitCode,output,passed'
+      || typeof item.command !== 'string' || typeof item.output !== 'string' || item.output.length > 12_000
+      || typeof item.passed !== 'boolean' || !Number.isInteger(item.exitCode)
+      || item.passed !== (item.exitCode === 0)) corrupt();
+  }
+  if (!value.some(item => !item.passed)) corrupt();
+}
+
+/** Prepare one target for the existing failed-Step transaction. Performs no writes. */
+export function prepareCapturedCheckEvidence(store: FileStateStore, task: TaskState, checks: CheckResult[]) {
+  validateChecks(checks);
+  const canonical = canonicalJsonStringify(checks);
+  const checksHash = sha256Hex(canonical);
+  const content = `${canonical}\n`;
+  const file = artifactFile(store, task, checksHash);
+  const previous = readBytes(file, Buffer.byteLength(content));
+  if (previous !== null && previous !== content) corrupt();
+  return {
+    checksHash,
+    reference: { kind: KIND, artifactHash: sha256Hex(content) },
+    target: previous === null
+      ? { path: path.relative(store.projectRoot(task.projectId), file).split(path.sep).join('/'), content }
+      : null,
+  };
+}
+
+/** Exact readback for the transaction; captured bytes never escape in its return value. */
+export function assertCapturedCheckEvidence(
+  store: FileStateStore, task: TaskState, pause: StepFailurePause, expected: CheckResult[],
+): void {
+  const checks = readVerifiedChecks(store, task, pause, expected.map(check => check.command));
+  if (!checks || canonicalJsonStringify(checks) !== canonicalJsonStringify(expected)) corrupt();
+}
+
+function readVerifiedChecks(store: FileStateStore, task: TaskState, pause: StepFailurePause, commands: string[]): CheckResult[] | null {
+  if (pause.checksEvidence === undefined) return null;
+  const ref = pause.checksEvidence;
+  if (!ref || Object.keys(ref).sort().join(',') !== 'artifactHash,kind'
+    || ref.kind !== KIND || !HASH.test(ref.artifactHash)) corrupt();
+  // JSON escaping can expand each captured character to six bytes.
+  const maxBytes = commands.reduce((size, command) => size + command.length * 6 + 12_000 * 6 + 256, 2);
+  const content = readBytes(artifactFile(store, task, pause.checksHash), maxBytes);
+  if (content === null || sha256Hex(content) !== ref.artifactHash) corrupt();
+  let value: unknown;
+  try { value = JSON.parse(content); } catch { return corrupt(); }
+  validateChecks(value);
+  const canonical = canonicalJsonStringify(value);
+  if (content !== `${canonical}\n` || sha256Hex(canonical) !== pause.checksHash
+    || JSON.stringify(value.map(check => check.command)) !== JSON.stringify(commands)) corrupt();
+  return value;
+}
+
+/** Verify native saved check evidence for admission without deriving authority from display diagnostics. */
+export function assertCurrentCapturedCheckEvidence(store: FileStateStore, task: TaskState, stepId: string): void {
+  const step = task.steps.find(candidate => candidate.id === stepId);
+  if (!step?.failurePause || !readVerifiedChecks(store, task, step.failurePause, step.checks)) corrupt();
+}
+
+/** Best-effort diagnostic display only. Never used in cause bindings, scope, or navigation. */
+export function capturedCheckExcerpt(output: string, sensitiveValues: readonly string[] = []): string[] {
+  let text = output.replace(/\u001b\[[0-9;]*m/g, '');
+  for (const value of sensitiveValues.filter(Boolean)) text = text.replaceAll(value, '[REDACTED]');
+  const lines = text.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+  const errors = lines.filter(line => /\b(?:error|failed|failure|exception|assertion|fatal|panic)\b|\bTS\d{3,5}\b/i.test(line));
+  return (errors.length ? errors : lines).slice(-8).map(line => {
+    // Prefer hiding the whole secret-bearing line over preserving surrounding error text.
+    if (/\b(?:authorization|bearer|password|passwd|secret|token|api[_-]?key|private[_-]?key)\b|-----BEGIN .*PRIVATE KEY/i.test(line)) {
+      return '[REDACTED sensitive diagnostic line]';
+    }
+    return line
+      .replace(/\b[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s]+/g, '[REDACTED_URL]')
+      .replace(/\b(?:CREF|DGT|WLT|CLAIM)-[^\s]+/g, '[REDACTED]')
+      .replace(/[A-Za-z0-9_+/=-]{40,}/g, '[REDACTED_VALUE]')
+      .slice(0, 240);
+  });
+}
+
+/** Read-only inspection of a current saved failure; no raw logs enter Task/status JSON. */
+export function readCapturedCheckDiagnostics(store: FileStateStore, task: TaskState, stepId: string) {
+  const step = task.steps.find(candidate => candidate.id === stepId);
+  if (!step?.failurePause) return { state: 'unavailable' as const, reason: 'no-current-failure' as const };
+  const checks = readVerifiedChecks(store, task, step.failurePause, step.checks);
+  if (!checks) return { state: 'unavailable' as const, reason: 'legacy-not-captured' as const };
+  return {
+    state: 'verified' as const,
+    checksHash: step.failurePause.checksHash,
+    artifactHash: step.failurePause.checksEvidence!.artifactHash,
+    authority: 'diagnostic-only' as const,
+    capture: 'bounded-output-tail-last-12000-characters' as const,
+    failures: checks.flatMap((check, index) => check.passed ? [] : [{ index, exitCode: check.exitCode, excerpt: capturedCheckExcerpt(check.output) }]),
+  };
+}

package/src/alpha6/check-support-anchor.ts

@@ -0,0 +1,128 @@
+import path from 'node:path';
+import type { PlanStepInput } from '../contracts.js';
+import { pathAllowed } from '../domain/validation.js';
+import { parseNpmRunCheck } from './npm-check-contract.js';
+
+const SAFE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+const RUNNER = /(?:^|[;&|]\s*|\s)(?:node|tsx)\s+([A-Za-z0-9._/-]+\.(?:cjs|js|mjs|ts|tsx))(?=\s|$)/g;
+const IMPORT = /(?:\bfrom\s*|\bimport\s*)['"](\.[^'"]+)['"]/g;
+const HASH_64 = /\b[a-f0-9]{64}\b/g;
+const MIGRATION_NAME = /\b[0-9]{4}_[a-z0-9_]+\.sql\b/g;
+const MIGRATION_BASENAME = /^[0-9]{4}_[a-z0-9_]+\.sql$/;
+
+export interface CheckSupportAnchorConflict {
+  readonly reasonCode: 'CHECK_SUPPORT_ANCHOR_OUTSIDE_ALLOWED_WRITES';
+  readonly script: string;
+  readonly command: string;
+  readonly scriptCommand: string;
+  readonly runnerPath: string;
+  readonly runnerHash: string;
+  readonly supportPath: string;
+  readonly supportHash: string;
+  readonly importSpecifier: string;
+  readonly expectedOutputPaths: readonly string[];
+  readonly anchoredMigrationNames: readonly string[];
+}
+
+export interface CheckSupportAnchorInspectionInput {
+  readonly step: Pick<PlanStepInput, 'checks' | 'expectedOutputs' | 'allowedWrites'>;
+  readonly scripts: ReadonlyMap<string, string>;
+  readonly readFile: (relativePath: string) => { content: string | null; hash: string | null };
+  readonly pathExists: (relativePath: string) => boolean;
+}
+
+export function inspectCheckSupportAnchors(
+  input: CheckSupportAnchorInspectionInput,
+): CheckSupportAnchorConflict[] {
+  const absentOutputs = input.step.expectedOutputs
+    .map(decodeDeclaredPath)
+    .filter((value): value is string => value !== null)
+    .filter((value) => pathAllowed(value, input.step.allowedWrites) && !input.pathExists(value));
+  const absentMigrationOutputs = absentOutputs.filter((value) => MIGRATION_BASENAME.test(path.posix.basename(value)));
+  if (absentMigrationOutputs.length === 0) return [];
+
+  const conflicts: CheckSupportAnchorConflict[] = [];
+  for (const check of input.step.checks) {
+    const invocation = parseNpmRunCheck(check);
+    if (!invocation) continue;
+    const scriptCommand = input.scripts.get(invocation.script);
+    if (!scriptCommand) continue;
+    for (const runnerPath of extractRunnerPaths(scriptCommand)) {
+      const runner = input.readFile(runnerPath);
+      if (!runner.content || !runner.hash) continue;
+      for (const importSpecifier of extractImports(runner.content)) {
+        const resolved = resolveImport(input.readFile, runnerPath, importSpecifier);
+        if (!resolved || pathAllowed(resolved.path, input.step.allowedWrites)) continue;
+        const anchoredMigrationNames = [...new Set(resolved.content.match(MIGRATION_NAME) ?? [])].sort();
+        if (
+          (resolved.content.match(HASH_64) ?? []).length === 0
+          || anchoredMigrationNames.length === 0
+          || !/(?:approved|expected|manifest|checksum|sha256|catalog)/i.test(resolved.content)
+        ) continue;
+        const expectedOutputPaths = absentMigrationOutputs.filter((output) => {
+          const basename = path.posix.basename(output);
+          return !anchoredMigrationNames.includes(basename)
+            && anchoredMigrationNames.some((name) => name.slice(-4) === basename.slice(-4));
+        });
+        if (expectedOutputPaths.length === 0) continue;
+        conflicts.push({
+          reasonCode: 'CHECK_SUPPORT_ANCHOR_OUTSIDE_ALLOWED_WRITES',
+          script: invocation.script,
+          command: check.trim(),
+          scriptCommand,
+          runnerPath,
+          runnerHash: runner.hash,
+          supportPath: resolved.path,
+          supportHash: resolved.hash,
+          importSpecifier,
+          expectedOutputPaths: [...expectedOutputPaths].sort(),
+          anchoredMigrationNames,
+        });
+      }
+    }
+  }
+  return conflicts.sort((left, right) => left.command.localeCompare(right.command)
+    || left.supportPath.localeCompare(right.supportPath));
+}
+
+function decodeDeclaredPath(value: string): string | null {
+  const candidate = value.startsWith('path:') ? value.slice(5) : value;
+  if (!SAFE_PATH.test(candidate) || candidate.split('/').some((segment) => segment === '.' || segment === '..')) {
+    return null;
+  }
+  return candidate;
+}
+
+function extractRunnerPaths(command: string): string[] {
+  const result = new Set<string>();
+  for (const match of command.matchAll(RUNNER)) {
+    const candidate = match[1]!;
+    if (!path.posix.isAbsolute(candidate) && !candidate.split('/').some((segment) => segment === '..')) {
+      result.add(candidate);
+    }
+  }
+  return [...result].sort();
+}
+
+function extractImports(content: string): string[] {
+  return [...new Set([...content.matchAll(IMPORT)].map((match) => match[1]!))].sort();
+}
+
+function resolveImport(
+  readFile: CheckSupportAnchorInspectionInput['readFile'],
+  runnerPath: string,
+  specifier: string,
+): { path: string; content: string; hash: string } | null {
+  const direct = path.posix.normalize(path.posix.join(path.posix.dirname(runnerPath), specifier));
+  if (direct.startsWith('../') || path.posix.isAbsolute(direct)) return null;
+  const candidates = [direct];
+  if (/\.js$/.test(direct)) candidates.push(direct.slice(0, -3) + '.ts');
+  if (!path.posix.extname(direct)) candidates.push(`${direct}.ts`, `${direct}.js`, `${direct}.mjs`);
+  for (const candidate of candidates) {
+    const inspected = readFile(candidate);
+    if (inspected.content !== null && inspected.hash !== null) {
+      return { path: candidate, content: inspected.content, hash: inspected.hash };
+    }
+  }
+  return null;
+}

package/src/alpha6/component-owner.ts

@@ -0,0 +1,168 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import type { PlanStepInput, StepFailurePause } from '../contracts.js';
+import { pathAllowed } from '../domain/validation.js';
+import { literalMigrationCatalogNames, literalVitestInvocations } from './literal-test-invocation.js';
+import { parseNpmRunCheck } from './npm-check-contract.js';
+
+const RUNNER = /(?:^|[;&|]\s*|\s)(?:node|tsx)\s+([A-Za-z0-9._/-]+\.(?:cjs|js|mjs|ts|tsx))(?=\s|$)/g;
+const IMPORT = /(?:\bfrom\s*|\bimport\s*)['"](\.[^'"]+)['"]/g;
+
+export interface FailedCheckComponentOwnerConflict {
+  reasonCode: 'FAILED_CHECK_COMPONENT_OWNER_OUTSIDE_ALLOWED_WRITES';
+  command: string;
+  runnerPath: string;
+  ownerPath: string;
+  ownerHash: string;
+  importChain: string[];
+  diagnosticPath: string;
+  componentRoot: string;
+  causeFingerprint: string;
+  testInvocation?: { kind: 'literal-vitest-catalog'; runnerHash: string; argv: string[]; migrationOutputs: string[]; catalogNames: string[] };
+}
+
+export function inspectFailedCheckComponentOwners(input: {
+  step: Pick<PlanStepInput, 'checks' | 'allowedWrites' | 'forbiddenScope'> & Partial<Pick<PlanStepInput, 'expectedOutputs'>> & { failurePause?: StepFailurePause | null };
+  scripts: ReadonlyMap<string, string>;
+  readFile: (relativePath: string) => { content: string | null; hash: string | null };
+  isTracked?: (relativePath: string) => boolean;
+}): FailedCheckComponentOwnerConflict[] {
+  const failures = input.step.failurePause?.failedChecks ?? [];
+  const conflicts: FailedCheckComponentOwnerConflict[] = [];
+  for (const failure of failures) {
+    const invocation = parseNpmRunCheck(failure.command);
+    if (!invocation) continue;
+    const scriptCommand = input.scripts.get(invocation.script);
+    if (!scriptCommand) continue;
+    for (const runnerPath of extractRunnerPaths(scriptCommand)) {
+      const graph = buildImportGraph(runnerPath, input.readFile);
+      for (const diagnosticPath of failure.diagnosticPaths) {
+        let node = graph.get(diagnosticPath);
+        let testInvocation: FailedCheckComponentOwnerConflict['testInvocation'];
+        if (!node && /^(?:node|tsx) [A-Za-z0-9._/-]+\.(?:cjs|js|mjs|ts|tsx)$/.test(scriptCommand.trim())
+          && input.isTracked?.(runnerPath) && input.isTracked(diagnosticPath)
+          && !pathAllowed(diagnosticPath, input.step.forbiddenScope)) {
+          const runner = input.readFile(runnerPath), spec = input.readFile(diagnosticPath);
+          const argv = runner.content && literalVitestInvocations(runner.content).find(args => args.slice(2).includes(diagnosticPath));
+          const catalogNames = literalMigrationCatalogNames(spec.content ?? '');
+          const migrationOutputs = (input.step.expectedOutputs ?? []).map(value => value.startsWith('path:') ? value.slice(5) : value)
+            .filter(value => /^[A-Za-z0-9._/-]+$/.test(value) && !value.split('/').some(part => part === '..' || part === '.')
+              && /^[0-9]{4}_[a-z0-9_]+\.sql$/.test(path.posix.basename(value))
+              && componentBoundary(value) === componentBoundary(diagnosticPath)
+              && pathAllowed(value, input.step.allowedWrites)
+              && !catalogNames.includes(path.posix.basename(value))).sort();
+          if (argv && runner.hash && spec.hash && catalogNames.length && migrationOutputs.length) {
+            testInvocation = { kind: 'literal-vitest-catalog', runnerHash: runner.hash, argv, migrationOutputs, catalogNames };
+            node = { hash: spec.hash, chain: [runnerPath] };
+          }
+        }
+        if (!node || pathAllowed(diagnosticPath, input.step.allowedWrites)) continue;
+        const componentRoot = componentBoundary(diagnosticPath);
+        if (!input.step.allowedWrites.some((owned) => componentBoundary(owned) === componentRoot)) continue;
+        conflicts.push({
+          reasonCode: 'FAILED_CHECK_COMPONENT_OWNER_OUTSIDE_ALLOWED_WRITES',
+          command: failure.command,
+          runnerPath,
+          ownerPath: diagnosticPath,
+          ownerHash: node.hash,
+          importChain: node.chain,
+          diagnosticPath,
+          componentRoot,
+          causeFingerprint: failure.causeFingerprint,
+          ...(testInvocation ? { testInvocation } : {}),
+        });
+      }
+    }
+  }
+  // A diagnostic list may include passing suites. Only a unique missing-catalog
+  // anchor for this failed command qualifies; ambiguity grants no new scope.
+  const unambiguous = conflicts.filter(conflict => !conflict.testInvocation
+    || conflicts.filter(other => other.command === conflict.command && other.testInvocation).length === 1);
+  return unambiguous.sort((left, right) => left.command.localeCompare(right.command)
+    || left.ownerPath.localeCompare(right.ownerPath));
+}
+
+function buildImportGraph(
+  runnerPath: string,
+  readFile: (relativePath: string) => { content: string | null; hash: string | null },
+): Map<string, { hash: string; chain: string[] }> {
+  const result = new Map<string, { hash: string; chain: string[] }>();
+  const queue: Array<{ file: string; chain: string[] }> = [{ file: runnerPath, chain: [runnerPath] }];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (result.has(current.file) || current.chain.length > 6) continue;
+    const inspected = readFile(current.file);
+    if (!inspected.content || !inspected.hash) continue;
+    result.set(current.file, { hash: inspected.hash, chain: current.chain });
+    for (const specifier of extractImports(inspected.content)) {
+      const resolved = resolveImport(current.file, specifier, readFile);
+      if (resolved && !result.has(resolved)) queue.push({ file: resolved, chain: [...current.chain, resolved] });
+    }
+  }
+  return result;
+}
+
+function extractRunnerPaths(command: string): string[] {
+  return [...new Set([...command.matchAll(RUNNER)].map((match) => match[1]!))].sort();
+}
+
+function extractImports(content: string): string[] {
+  return [...new Set([...content.matchAll(IMPORT)].map((match) => match[1]!))].sort();
+}
+
+function resolveImport(
+  importer: string,
+  specifier: string,
+  readFile: (relativePath: string) => { content: string | null; hash: string | null },
+): string | null {
+  const direct = path.posix.normalize(path.posix.join(path.posix.dirname(importer), specifier));
+  if (direct.startsWith('../') || path.posix.isAbsolute(direct)) return null;
+  const candidates = [direct];
+  if (/\.js$/.test(direct)) candidates.push(direct.slice(0, -3) + '.ts');
+  if (!path.posix.extname(direct)) candidates.push(`${direct}.ts`, `${direct}.tsx`, `${direct}.js`, `${direct}.mjs`);
+  return candidates.find((candidate) => readFile(candidate).content !== null) ?? null;
+}
+
+function componentBoundary(relativePath: string): string {
+  const segments = relativePath.split('/');
+  if (segments.length >= 2 && ['apps', 'libs', 'packages', 'services', 'tools'].includes(segments[0]!)) {
+    return segments.slice(0, 2).join('/');
+  }
+  return segments[0]!;
+}
+
+export function semanticBoundaryHash(task: {
+  planObjective: string | null;
+  requirements: string[];
+  acceptance: string[];
+  risks: string[];
+}): string {
+  const material = JSON.stringify({
+    objective: task.planObjective,
+    requirements: [...task.requirements].sort(),
+    acceptance: [...task.acceptance].sort(),
+    securityBoundary: task.risks.filter((risk) => /security|auth|secret|credential|permission/i.test(risk)).sort(),
+  });
+  return createHash('sha256').update(material).digest('hex');
+}
+
+/** Stored invocation evidence is structurally distinct from an import chain. The
+ * containing conflict hash binds it; fresh recovery rederives it from tracked bytes. */
+export function validLiteralTestInvocationEvidence(conflict: {
+  ownerPath: string; testInvocation?: FailedCheckComponentOwnerConflict['testInvocation'];
+}): boolean {
+  const proof = conflict.testInvocation;
+  if (!proof || proof.kind !== 'literal-vitest-catalog' || !/^[a-f0-9]{64}$/.test(proof.runnerHash)) return false;
+  const paths = proof.argv.slice(2).filter(arg => !arg.startsWith('--'));
+  return proof.argv[0] === 'vitest' && proof.argv[1] === 'run'
+    && paths.includes(conflict.ownerPath)
+    && paths.every(value => /^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_.-]+\.(?:spec|test)\.[cm]?[jt]sx?$/.test(value))
+    && proof.argv.slice(2 + paths.length).every(arg => /^--maxWorkers=[1-9][0-9]*$/.test(arg))
+    && proof.argv.length - paths.length <= 3
+    && proof.catalogNames.length > 0 && proof.catalogNames.every(value => /^[0-9]{4}_[a-z0-9_]+\.sql$/.test(value))
+    && proof.migrationOutputs.length > 0 && proof.migrationOutputs.every(value =>
+      /^[A-Za-z0-9._/-]+$/.test(value) && !value.split('/').some(part => part === '..' || part === '.')
+      && /^[0-9]{4}_[a-z0-9_]+\.sql$/.test(path.posix.basename(value))
+      && componentBoundary(value) === componentBoundary(conflict.ownerPath)
+      && !proof.catalogNames.includes(path.posix.basename(value)));
+}

package/src/alpha6/corrective-decision-boundary.ts

@@ -0,0 +1,39 @@
+import { lstatSync } from 'node:fs';
+import path from 'node:path';
+import type { TaskState } from '../contracts.js';
+import { pathAllowed } from '../domain/validation.js';
+import { validateTaskHistory } from '../git.js';
+import { changedFiles, currentBranch, headCommit } from '../repository.js';
+import type { FileStateStore } from '../state/store.js';
+import { hashDirtyWorktree } from './downstream-proof.js';
+import { effectiveStepAllowedWrites, readRemediationEvents } from './remediation.js';
+
+/** Checkout eligibility only: never an audit, writer credential, or permission to widen scope. */
+export function correctiveDecisionCheckoutEligible(
+  store: FileStateStore, repository: string, task: TaskState, stepId: string,
+): boolean {
+  if (!task.taskBranch || currentBranch(repository) !== task.taskBranch) return false;
+  // Includes completed Step commits and recorded system/history commits. A new
+  // unrecorded HEAD must not become a corrective audit's implicit baseline.
+  validateTaskHistory(repository, task);
+  const dirty = changedFiles(repository).sort();
+  if (dirty.length === 0) return true;
+  if (task.workspaceOwner !== 'local' || task.steps.some(step => step.status === 'in_progress')) return false;
+  const step = task.steps.find(candidate => candidate.id === stepId);
+  const pause = step?.failurePause;
+  if (step?.status !== 'failed' || !pause) return false;
+  const terminal = readRemediationEvents(store, task).filter(event => event.stepId === stepId).at(-1);
+  if (!terminal || terminal.failureKind !== 'checks-failed'
+    || terminal.failureEvidence.completionCommit !== headCommit(repository)
+    || terminal.failureEvidence.checksHash !== pause.checksHash
+    || terminal.failureEvidence.dirtyWorktreeHash !== pause.dirtyWorktreeHash
+    || JSON.stringify(dirty) !== JSON.stringify([...pause.dirtyFiles].sort())) return false;
+  const allowedWrites = effectiveStepAllowedWrites(store, task, stepId);
+  for (const file of dirty) {
+    if (!pathAllowed(file, allowedWrites) || pathAllowed(file, step.forbiddenScope)) return false;
+    // Do not admit symlinks (including dangling links) or directory substitutions.
+    try { if (!lstatSync(path.join(repository, file)).isFile()) return false; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  }
+  return hashDirtyWorktree(repository, dirty) === pause.dirtyWorktreeHash;
+}