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

package/src/domain/discovery.ts

@@ -0,0 +1,27 @@
+import type { DiscoveryState } from '../contracts.js';
+
+export interface DiscoveryReadiness {
+  ready: boolean;
+  status: 'needs_discovery' | 'needs_clarification' | 'ready_to_materialize';
+  missing: string[];
+}
+
+export function assessDiscovery(discovery: DiscoveryState): DiscoveryReadiness {
+  const missing: string[] = [];
+  if (!discovery.goal.trim()) missing.push('goal');
+  if (!discovery.outcome?.trim()) missing.push('observable outcome');
+  if (discovery.scope.length === 0) missing.push('scope');
+  if (discovery.acceptance.length === 0) missing.push('acceptance scenario');
+  if (discovery.blockingUnknowns.length > 0) missing.push('resolved blocking unknowns');
+  if (missing.length === 0) return { ready: true, status: 'ready_to_materialize', missing };
+  const hasInitialUnderstanding = Boolean(discovery.goal.trim() && (discovery.outcome || discovery.scope.length > 0));
+  return {
+    ready: false,
+    status: hasInitialUnderstanding ? 'needs_clarification' : 'needs_discovery',
+    missing,
+  };
+}
+
+export function mergeUnique(current: string[], additions: string[]): string[] {
+  return [...new Set([...current, ...additions].map((value) => value.trim()).filter(Boolean))];
+}

package/src/domain/plan-semantics.ts

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { WorkflowError } from '../errors.js';
+
+const HASH64 = /^[a-f0-9]{64}$/;
+const KNOWLEDGE_LINE = /^- Knowledge map: revision ([1-9]\d*), hash ([a-f0-9]{64})$/gm;
+const KNOWLEDGE_SENTINEL = '- Knowledge map: revision <context>, hash <context>';
+
+export interface NormalizedPlanSemantics {
+  normalized: string;
+  semanticHash: string;
+  binding: { revision: number; hash: string };
+}
+
+export function normalizePlanKnowledgeBinding(content: string, label: string): NormalizedPlanSemantics {
+  const matches = [...content.matchAll(KNOWLEDGE_LINE)];
+  if (matches.length !== 1) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} Plan must contain exactly one canonical Knowledge Map binding line.`, {
+      matchCount: matches.length,
+    });
+  }
+  const match = matches[0]!;
+  const normalized = content.slice(0, match.index) + KNOWLEDGE_SENTINEL + content.slice(match.index! + match[0].length);
+  return {
+    normalized,
+    semanticHash: sha256Hex(normalized),
+    binding: { revision: Number(match[1]), hash: match[2]! },
+  };
+}
+
+export function assertKnowledgeBindingOnlyPlanChange(historical: string, current: string): string {
+  const source = normalizePlanKnowledgeBinding(historical, 'historical');
+  const target = normalizePlanKnowledgeBinding(current, 'current');
+  if (source.normalized !== target.normalized) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective recovery permits only the Knowledge Map binding line to change.');
+  }
+  return source.semanticHash;
+}
+
+export function readVerifiedPlanArtifact(taskRoot: string, planHash: string, currentPlanHash: string): string {
+  if (!HASH64.test(planHash)) throw new WorkflowError('STATE_CORRUPT', 'Plan hash is malformed.', { planHash });
+  const file = planHash === currentPlanHash
+    ? path.join(taskRoot, 'plan.md')
+    : path.join(taskRoot, '.versions', `plan.md.${planHash}`);
+  if (!existsSync(file)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Plan artifact required by lifecycle evidence is missing.', { planHash, file });
+  }
+  const content = readFileSync(file, 'utf8');
+  if (sha256Hex(content) !== planHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Plan artifact content does not match its recorded hash.', { planHash, file });
+  }
+  return content;
+}
+
+function sha256Hex(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}

package/src/domain/step-start-admission.ts

@@ -0,0 +1,10 @@
+import type { StepStatus } from '../contracts.js';
+
+export type StepStartPhase = 'planned-clean' | 'planned-dirty' | 'failed-retry' | 'not-startable';
+
+/** Replacement carryover admits a first start; a retry uses its current write scope. */
+export function stepStartPhase(status: StepStatus | undefined, hasDirtyFiles: boolean): StepStartPhase {
+  if (status === 'planned') return hasDirtyFiles ? 'planned-dirty' : 'planned-clean';
+  if (status === 'failed') return 'failed-retry';
+  return 'not-startable';
+}

package/src/domain/validation.ts

@@ -0,0 +1,177 @@
+import type {
+  PlanRiskAuditStepClassification,
+  TaskPlanInput,
+  TaskState,
+} from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+
+export function validatePlan(plan: TaskPlanInput): void {
+  const issues: string[] = [];
+  if (!plan.objective.trim()) issues.push('Plan objective is required.');
+  if (plan.requirements.length === 0) issues.push('At least one requirement is required.');
+  if (plan.acceptance.length === 0) issues.push('At least one acceptance scenario is required.');
+  if (plan.steps.length === 0) issues.push('At least one STEP-* is required.');
+  if (!plan.knowledgeImpactReason.trim()) issues.push('knowledgeImpactReason is required.');
+  if (!Number.isInteger(plan.knowledgeMapRevision) || plan.knowledgeMapRevision < 1) {
+    issues.push('knowledgeMapRevision must be a positive integer.');
+  }
+  if (!/^[a-f0-9]{64}$/.test(plan.knowledgeMapHash)) issues.push('knowledgeMapHash must be a SHA-256 hash.');
+  if (plan.knowledgeImpact === 'none' && plan.knowledgeTargets.length > 0) {
+    issues.push('knowledgeImpact none cannot declare knowledgeTargets.');
+  }
+  if (plan.knowledgeImpact !== 'none' && plan.knowledgeTargets.length === 0) {
+    issues.push(`knowledgeImpact ${plan.knowledgeImpact} requires at least one knowledgeTarget.`);
+  }
+  for (const target of plan.knowledgeTargets) {
+    if (!target.reason.trim()) issues.push(`Knowledge target ${target.path} requires a reason.`);
+    if (target.requirementIds.length === 0) issues.push(`Knowledge target ${target.path} requires requirementIds.`);
+  }
+
+  const ids = new Set<string>();
+  for (const step of plan.steps) {
+    if (!/^STEP-[0-9]{3}(?:-[A-Z0-9-]+)?$/.test(step.id)) issues.push(`Invalid Step id: ${step.id}`);
+    if (ids.has(step.id)) issues.push(`Duplicate Step id: ${step.id}`);
+    ids.add(step.id);
+    if (!step.title.trim() || !step.objective.trim()) issues.push(`${step.id} requires title and objective.`);
+    if (step.requirements.length === 0) issues.push(`${step.id} must cover at least one requirement.`);
+    if (step.allowedWrites.length === 0) issues.push(`${step.id} must declare allowedWrites.`);
+    if (step.expectedOutputs.length === 0) issues.push(`${step.id} must declare expectedOutputs.`);
+    if (step.checks.length === 0) issues.push(`${step.id} must declare at least one executable check.`);
+  }
+
+  for (const step of plan.steps) {
+    for (const dependency of step.dependencies) {
+      if (!ids.has(dependency)) issues.push(`${step.id} depends on missing ${dependency}.`);
+      if (dependency === step.id) issues.push(`${step.id} cannot depend on itself.`);
+    }
+  }
+
+  const covered = new Set(plan.steps.flatMap((step) => step.requirements));
+  for (const requirement of plan.requirements) {
+    if (!covered.has(requirement)) issues.push(`Requirement is not covered by any Step: ${requirement}`);
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const byId = new Map(plan.steps.map((step) => [step.id, step]));
+  const visit = (stepId: string): void => {
+    if (visited.has(stepId)) return;
+    if (visiting.has(stepId)) {
+      issues.push(`Step dependency cycle includes ${stepId}.`);
+      return;
+    }
+    visiting.add(stepId);
+    for (const dependency of byId.get(stepId)?.dependencies ?? []) visit(dependency);
+    visiting.delete(stepId);
+    visited.add(stepId);
+  };
+  for (const step of plan.steps) visit(step.id);
+
+  const productionEdges = plan.productionEdges ?? [];
+  if (plan.requiresProductionEdges && productionEdges.length === 0) {
+    issues.push('Plan requiresProductionEdges but declares no explicit production edge.');
+  }
+  if (!plan.requiresProductionEdges && productionEdges.length > 0) {
+    issues.push('Plan declares productionEdges without the explicit requiresProductionEdges boundary.');
+  }
+  const edgeKeys = new Set<string>();
+  for (const edge of productionEdges) {
+    const key = `${edge.ownerStepId}\0${edge.consumerStepId}\0${edge.checkRef}`;
+    if (edgeKeys.has(key)) issues.push(`Duplicate production edge: ${edge.ownerStepId} -> ${edge.consumerStepId}.`);
+    edgeKeys.add(key);
+    const owner = byId.get(edge.ownerStepId);
+    const consumer = byId.get(edge.consumerStepId);
+    if (!owner) issues.push(`Production edge owner is missing: ${edge.ownerStepId}.`);
+    if (!consumer) issues.push(`Production edge consumer is missing: ${edge.consumerStepId}.`);
+    if (owner && consumer && owner.id === consumer.id) issues.push(`Production edge cannot self-reference ${owner.id}.`);
+    if (owner && consumer && !transitiveDependencies(consumer.id, byId).has(owner.id)) {
+      issues.push(`Production edge owner ${owner.id} is not a transitive dependency of consumer ${consumer.id}.`);
+    }
+    if (consumer && !consumer.checks.includes(edge.checkRef)) {
+      issues.push(`Production edge ${edge.ownerStepId} -> ${edge.consumerStepId} names a check not executed by its consumer.`);
+    }
+  }
+
+  if (issues.length > 0) throw new WorkflowError('TRANSITION_BLOCKED', 'Plan is not execution-ready.', { issues });
+}
+
+/**
+ * Derive the narrow beta.13 structural integration obligation from the independent
+ * Plan Risk Audit rather than trusting the planner-owned opt-in flag. This is not
+ * semantic output-to-evidence authority (P02): it only proves that a multi-Step
+ * runtime-composition Plan names an inbound production hand-off and executes its
+ * exact check in the consumer Step.
+ */
+export function validateStructuralProductionEdgeAuthority(
+  task: Pick<TaskState, 'id' | 'steps' | 'productionEdges' | 'requiresProductionEdges'>,
+  classifications: readonly PlanRiskAuditStepClassification[],
+): void {
+  if (task.steps.length < 2) return;
+  const integrationConsumerIds = classifications
+    .filter((classification) => classification.categories.includes('runtime-composition'))
+    .map((classification) => classification.stepId)
+    .sort();
+  if (integrationConsumerIds.length === 0) return;
+
+  const edges = task.productionEdges ?? [];
+  const byId = new Map(task.steps.map((step) => [step.id, step]));
+  const missingConsumerEdgeIds = integrationConsumerIds.filter((consumerStepId) =>
+    !edges.some((edge) => edge.consumerStepId === consumerStepId));
+  const blockingGuardIds = [
+    ...(task.requiresProductionEdges === true ? [] : ['task.production-edge.explicit-boundary']),
+    ...(edges.length > 0 ? [] : ['task.production-edge.non-empty']),
+    ...(missingConsumerEdgeIds.length > 0 ? ['task.production-edge.runtime-consumer-covered'] : []),
+  ];
+  for (const edge of edges) {
+    const consumer = byId.get(edge.consumerStepId);
+    const owner = byId.get(edge.ownerStepId);
+    if (!consumer || !owner || !transitiveDependencies(consumer.id, byId).has(owner.id)
+      || !consumer.checks.includes(edge.checkRef)) {
+      blockingGuardIds.push('task.production-edge.executable-predecessor-binding');
+      break;
+    }
+  }
+  if (blockingGuardIds.length === 0) return;
+  throw new WorkflowError(
+    'TRANSITION_BLOCKED',
+    `Runtime-composition authority for Task ${task.id} requires explicit production-edge coverage.`,
+    {
+      diagnosticCode: 'STRUCTURAL_PRODUCTION_EDGE_REQUIRED',
+      triggerAuthority: 'plan-risk-audit.runtime-composition',
+      integrationConsumerStepIds: integrationConsumerIds,
+      missingConsumerEdgeIds,
+      blockingGuardIds: [...new Set(blockingGuardIds)],
+      semanticAuthorityClaimed: false,
+      requiredAction: 'Declare requiresProductionEdges=true and bind each runtime-composition consumer to a transitive owner and one exact consumer check.',
+    },
+  );
+}
+
+function transitiveDependencies(
+  stepId: string,
+  byId: ReadonlyMap<string, TaskPlanInput['steps'][number]>,
+): Set<string> {
+  const result = new Set<string>();
+  const visit = (candidateId: string): void => {
+    for (const dependency of byId.get(candidateId)?.dependencies ?? []) {
+      if (result.has(dependency)) continue;
+      result.add(dependency);
+      visit(dependency);
+    }
+  };
+  visit(stepId);
+  return result;
+}
+
+export function pathAllowed(file: string, patterns: string[]): boolean {
+  const normalized = file.replaceAll('\\', '/').replace(/^\.\//, '');
+  return patterns.some((pattern) => {
+    const candidate = pattern.replaceAll('\\', '/').replace(/^\.\//, '');
+    if (candidate.endsWith('/**')) return normalized === candidate.slice(0, -3) || normalized.startsWith(candidate.slice(0, -2));
+    if (candidate.endsWith('/*')) {
+      const prefix = candidate.slice(0, -1);
+      return normalized.startsWith(prefix) && !normalized.slice(prefix.length).includes('/');
+    }
+    return normalized === candidate;
+  });
+}

package/src/domain/virgin-registration.ts

@@ -0,0 +1,46 @@
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import type { RepositoryIdentity } from '../repository.js';
+import { isVirginProjectRegistrationContent } from '../alpha6/adoption.js';
+import { assertNoSymlinkPathComponents } from '../alpha6/store-sidecars.js';
+
+/** Read-only bootstrap admission. Retained or unrecognized state is never bootstrap. */
+export function isVirginRegistrationRoot(projectRoot: string, trustedRoot: string, identity: RepositoryIdentity, packageVersion: string): boolean {
+  try {
+    const relative = path.relative(path.resolve(trustedRoot), path.resolve(projectRoot));
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return false;
+    // The trusted state home itself can be absent on first use. Do not create it
+    // during observation, and do not confuse that case with invalid retained data.
+    try { lstatSync(trustedRoot); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return true;
+      throw error;
+    }
+    assertNoSymlinkPathComponents(projectRoot, { label: 'Bootstrap project root', trustedRoot });
+    let root;
+    try { root = lstatSync(projectRoot); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return true;
+      throw error;
+    }
+    if (!root.isDirectory() || root.isSymbolicLink()) return false;
+    const validFile = (file: string, hash?: string) => {
+      const stat = lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024) return false;
+      const bytes = readFileSync(file);
+      return (!hash || createHash('sha256').update(bytes).digest('hex') === hash)
+        && isVirginProjectRegistrationContent(bytes.toString('utf8'), identity, packageVersion);
+    };
+    for (const entry of readdirSync(projectRoot, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) return false;
+      if (entry.name === 'adoption-posture.jsonl') {
+        if (!validFile(path.join(projectRoot, entry.name))) return false;
+      } else if (entry.name === '.versions' && entry.isDirectory()) {
+        for (const snapshot of readdirSync(path.join(projectRoot, '.versions'))) {
+          const match = /^adoption-posture\.jsonl\.([a-f0-9]{64})$/.exec(snapshot);
+          if (!match || !validFile(path.join(projectRoot, '.versions', snapshot), match[1])) return false;
+        }
+      } else return false;
+    }
+    return true;
+  } catch { return false; }
+}

package/src/errors.ts

@@ -0,0 +1,24 @@
+export type WorkflowErrorCode =
+  | 'INVALID_ARGUMENT'
+  | 'NOT_FOUND'
+  | 'STATE_CONFLICT'
+  | 'STATE_CORRUPT'
+  | 'LOCKED'
+  | 'LOCK_TOKEN_INVALID'
+  | 'TASK_RECOVERY_REQUIRED'
+  | 'TRANSITION_BLOCKED'
+  | 'GIT_PRECONDITION_FAILED'
+  | 'COMMAND_FAILED'
+  | 'CHECK_INFRASTRUCTURE_FAILED';
+
+export class WorkflowError extends Error {
+  readonly code: WorkflowErrorCode;
+  readonly details: Record<string, unknown>;
+
+  constructor(code: WorkflowErrorCode, message: string, details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = 'WorkflowError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/src/failed-checkpoint-update.ts

@@ -0,0 +1,203 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import type { TaskState } from './contracts.js';
+import type { FileStateStore } from './state/store.js';
+import { canonicalJsonStringify, sha256Hex } from './alpha6/store-sidecars.js';
+import { readCorrectiveDecisionEvents, readRemediationEvents } from './alpha6/remediation.js';
+import { readTaskC1Posture, readTaskHandoffEvents } from './alpha6/handoff.js';
+import { readPlanRiskAuditEvents } from './alpha6/plan-risk.js';
+import { verifiedHistoricalStepReviewBindings } from './alpha6/review.js';
+import { readVerifiedPlanArtifact } from './domain/plan-semantics.js';
+import { pathAllowed } from './domain/validation.js';
+import { validateTaskHistory } from './git.js';
+import { inspectBoundedWorkflowDependencyCommit, workflowDependencyVersionAt } from './dependency-provenance.js';
+import { inspectWorkflowVersions } from './diagnostics.js';
+import { changedFiles, currentBranch, headCommit, runGit } from './repository.js';
+import { PACKAGE_VERSION } from './version.js';
+
+export const FAILED_CHECKPOINT_SOURCE = '2.0.0-beta.14';
+export const FAILED_CHECKPOINT_TARGET = '2.0.0-beta.14.1';
+const hash = (value: unknown) => sha256Hex(canonicalJsonStringify(value));
+function require(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(`FAILED_CHECKPOINT_UPDATE_BLOCKED: ${message}`);
+}
+export interface FailedCheckpointUpdateReceipt {
+  protocol: 'failed-checkpoint-update-source-v1';
+  projectId: string; taskId: string; revision: number; issuedAt: string;
+  taskHash: string; artifactsHash: string; knowledgeHash: string; milestoneHash: string | null;
+  sourceHead: string; sourceBaseHead: string; taskBranch: string; baseBranch: string;
+  sourceVersion: string; targetVersion: string; actor: string; stepId: string;
+  dirtyFiles: string[]; sourceDirtyHash: string; remediationEventId: string; remediationEventHash: string;
+  artifact: { sha256: string; runtimeHash: string };
+}
+export interface FailedCheckpointUpdateBinding {
+  protocol: 'failed-checkpoint-update-v1';
+  sourceHead: string; sourcePlanHash: string; stepId: string;
+  sourceDirtyHash: string; targetDirtyHash: string; dirtyFiles: string[];
+  remediationEventId: string; remediationEventHash: string;
+  sourceReceiptHash: string; artifactHash: string;
+}
+function filesHash(root: string): string {
+  if (!existsSync(root)) return hash([]);
+  const visit = (directory: string): Array<[string, string]> => readdirSync(directory).sort().flatMap(name => {
+    const file = path.join(directory, name); const info = lstatSync(file);
+    require(!info.isSymbolicLink() && (info.isFile() || info.isDirectory()), 'State artifacts must be regular files.');
+    return info.isDirectory() ? visit(file) : [[path.relative(root, file), sha256Hex(readFileSync(file))]];
+  });
+  return hash(visit(root));
+}
+/** Reverse only the dependency string, retaining every other byte (including whitespace and product scripts). */
+function sourceManifestBytes(content: Buffer): Buffer {
+  const text = content.toString('utf8'); const manifest = JSON.parse(text);
+  require(manifest.devDependencies?.['codex-workflow-v2'] === FAILED_CHECKPOINT_TARGET
+    && !manifest.dependencies?.['codex-workflow-v2'], 'Target working manifest must have one exact dev dependency.');
+  const key = /("codex-workflow-v2"\s*:\s*)"2\.0\.0-beta\.14\.1"/g;
+  require([...text.matchAll(key)].length === 1, 'Working manifest must have one unambiguous literal target pin.');
+  return Buffer.from(text.replace(key, `$1"${FAILED_CHECKPOINT_SOURCE}"`));
+}
+/** Same byte framing as native failure evidence; no normalization of product content. */
+export function failedCheckpointDirtyHash(repository: string, files: readonly string[], transported = false): string {
+  const digest = createHash('sha256');
+  for (const file of [...files].sort()) {
+    const absolute = path.resolve(repository, file); const relative = path.relative(repository, absolute);
+    require(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'Dirty path escapes checkout.');
+    require(existsSync(absolute) && lstatSync(absolute).isFile() && !lstatSync(absolute).isSymbolicLink(),
+      'This checkpoint supports retained regular files only.');
+    let bytes: Buffer = readFileSync(absolute);
+    if (transported && file === 'package.json') bytes = sourceManifestBytes(bytes);
+    digest.update(`path\0${file}\0file\0`); digest.update(bytes); digest.update('\0');
+  }
+  return digest.digest('hex');
+}
+function assertPins(repository: string, commit: string, version: string): void {
+  const manifest = JSON.parse(runGit(repository, ['show', `${commit}:package.json`]));
+  const lock = JSON.parse(runGit(repository, ['show', `${commit}:package-lock.json`]));
+  require(manifest.devDependencies?.['codex-workflow-v2'] === version && !manifest.dependencies?.['codex-workflow-v2']
+    && workflowDependencyVersionAt(repository, commit) === version
+    && lock.packages?.['']?.devDependencies?.['codex-workflow-v2'] === version
+    && !lock.packages?.['']?.dependencies?.['codex-workflow-v2']
+    && lock.packages?.['node_modules/codex-workflow-v2']?.version === version,
+    'Exact source manifest and lock bindings are required.');
+}
+export function assertFailedCheckpointInstalled(repository: string, task: TaskState, version: string): void {
+  const versions = inspectWorkflowVersions(repository, [task.baseBranch]);
+  require([versions.declared, versions.locked, versions.installed, versions.currentBranch,
+    ...versions.milestoneBases.map(item => item.version)].every(value => value === version),
+    `Every installed and Git version surface must equal ${version}.`);
+}
+export function failedCheckpointUpdateSource(repository: string, store: FileStateStore, task: TaskState,
+  artifact: FailedCheckpointUpdateReceipt['artifact'],
+  sourceHead = headCommit(repository), sourceBaseHead = runGit(repository, ['rev-parse', task.baseBranch]),
+  transported = false): FailedCheckpointUpdateReceipt {
+  require(PACKAGE_VERSION === FAILED_CHECKPOINT_TARGET, 'Only the beta.14 to beta.14.1 repair is supported.');
+  require(task.status === 'awaiting_execution_authorization' && task.workspaceOwner === 'external',
+    'Expected an external failed Task awaiting its new Plan audit.');
+  require(readCorrectiveDecisionEvents(store, task).length === 0,
+    'A checkpoint with corrective decision history requires its own supported boundary.');
+  require(task.taskBranch && currentBranch(repository) === task.taskBranch, 'Expected the recorded Task branch.');
+  const failed = task.steps.filter(step => step.status === 'failed');
+  require(failed.length === 1 && !task.steps.some(step => step.status === 'in_progress'), 'Exactly one paused failed Step is required.');
+  const step = failed[0]!;
+  require(step.failurePause && step.evidence === null, 'Native failed-check evidence is required.');
+  require(task.planHash && task.briefHash, 'Current Brief and Plan are required.');
+  const taskRoot = store.taskRoot(task.projectId, task.id);
+  require(store.hashArtifact(taskRoot, 'brief.md') === task.briefHash && store.hashArtifact(taskRoot, 'plan.md') === task.planHash,
+    'Brief and Plan artifacts must match state.');
+  readVerifiedPlanArtifact(taskRoot, task.planHash, task.planHash);
+  const currentAudit = readPlanRiskAuditEvents(store, task).at(-1);
+  require(!currentAudit || currentAudit.planHash !== task.planHash
+    || currentAudit.decision === 'stop-escalate', 'The checkpoint must await its audit or retain a planning obstruction.');
+  assertPins(repository, sourceHead, FAILED_CHECKPOINT_SOURCE); assertPins(repository, sourceBaseHead, FAILED_CHECKPOINT_SOURCE);
+  validateTaskHistory(repository, task, sourceHead);
+  const completed = task.steps.filter(item => item.status === 'completed');
+  const reviews = verifiedHistoricalStepReviewBindings(store, task);
+  require(completed.length > 0 && completed.every(item => item.evidence
+    && reviews.some(review => review.stepId === item.id && review.commitSha === item.evidence!.commitSha)),
+    'Every retained completed Step must have immutable execution and independent review evidence.');
+  require(step.dependencies.every(id => completed.some(item => item.id === id)), 'Failed Step dependencies must be complete.');
+  const events = readRemediationEvents(store, task).filter(event => event.stepId === step.id && event.failureKind === 'checks-failed');
+  require(events.length === 1, 'This checkpoint supports exactly the first native check failure.');
+  const terminal = events.at(-1);
+  require(terminal && terminal.failureEvidence.completionCommit === sourceHead
+    && terminal.failureEvidence.dirtyWorktreeHash === step.failurePause.dirtyWorktreeHash,
+    'Native terminal failure must bind source HEAD and retained dirty bytes.');
+  const dirtyFiles = changedFiles(repository).sort();
+  require(dirtyFiles.length > 0 && !dirtyFiles.includes('package-lock.json')
+    && JSON.stringify(dirtyFiles) === JSON.stringify([...step.failurePause.dirtyFiles].sort()),
+    'Dirty paths must equal the native failure; dirty lockfile transport is unsupported.');
+  require(dirtyFiles.every(file => pathAllowed(file, step.allowedWrites) && !pathAllowed(file, step.forbiddenScope)),
+    'Retained dirty files must be inside the failed Step scope.');
+  const sourceDirtyHash = failedCheckpointDirtyHash(repository, dirtyFiles, transported);
+  require(sourceDirtyHash === terminal.failureEvidence.dirtyWorktreeHash, 'Product bytes changed since native failure.');
+  const posture = readTaskC1Posture(store, task);
+  const claim = readTaskHandoffEvents(store, task).filter(event => event.eventType === 'claim').at(-1);
+  require(posture.state === 'claimed' && claim && posture.claimant === claim.actor && claim.briefHash === task.briefHash,
+    'Original immutable Worker claim is required.');
+  return { protocol: 'failed-checkpoint-update-source-v1', projectId: task.projectId, taskId: task.id,
+    revision: task.revision, issuedAt: task.updatedAt, taskHash: hash(task), artifactsHash: filesHash(taskRoot),
+    knowledgeHash: hash(store.readKnowledgeMap(task.projectId)),
+    milestoneHash: task.milestoneId ? hash(store.readMilestone(task.projectId, task.milestoneId)) : null,
+    sourceHead, sourceBaseHead, taskBranch: task.taskBranch, baseBranch: task.baseBranch,
+    sourceVersion: FAILED_CHECKPOINT_SOURCE, targetVersion: FAILED_CHECKPOINT_TARGET, actor: claim.actor,
+    stepId: step.id, dirtyFiles, sourceDirtyHash, remediationEventId: terminal.eventId,
+    remediationEventHash: terminal.eventHash, artifact };
+}
+export function inspectFailedCheckpointTransport(repository: string, store: FileStateStore, task: TaskState,
+  receipt: FailedCheckpointUpdateReceipt, artifact: FailedCheckpointUpdateReceipt['artifact']) {
+  require(receipt?.protocol === 'failed-checkpoint-update-source-v1', 'Missing or foreign source receipt.');
+  const targetHead = headCommit(repository); const base = runGit(repository, ['rev-parse', task.baseBranch]);
+  const target = inspectBoundedWorkflowDependencyCommit(repository, targetHead);
+  const baseTransport = inspectBoundedWorkflowDependencyCommit(repository, base);
+  require([targetHead, base].every(commit => runGit(repository, ['rev-list', '--parents', '-n', '1', commit]).split(' ').length === 2),
+    'Transport commits must have exactly one parent.');
+  require(target?.parentCommitSha === receipt.sourceHead && target.packageVersion === FAILED_CHECKPOINT_TARGET
+    && baseTransport?.parentCommitSha === receipt.sourceBaseHead && baseTransport.packageVersion === FAILED_CHECKPOINT_TARGET,
+    'Exactly one dependency-only transport is required on each bound branch.');
+  const reconstructed = failedCheckpointUpdateSource(repository, store, task, artifact,
+    target.parentCommitSha, baseTransport.parentCommitSha, true);
+  require(canonicalJsonStringify(receipt) === canonicalJsonStringify(reconstructed),
+    'Source receipt no longer matches state, artifacts, product bytes, history or tarball.');
+  assertFailedCheckpointInstalled(repository, task, FAILED_CHECKPOINT_TARGET);
+  const binding: FailedCheckpointUpdateBinding = { protocol: 'failed-checkpoint-update-v1',
+    sourceHead: receipt.sourceHead, sourcePlanHash: task.planHash!, stepId: receipt.stepId,
+    sourceDirtyHash: receipt.sourceDirtyHash, targetDirtyHash: failedCheckpointDirtyHash(repository, receipt.dirtyFiles),
+    dirtyFiles: receipt.dirtyFiles, remediationEventId: receipt.remediationEventId,
+    remediationEventHash: receipt.remediationEventHash, sourceReceiptHash: hash(receipt), artifactHash: artifact.sha256 };
+  return { receipt: reconstructed, target, baseTransport: base, targetHead, binding };
+}
+
+/** Revalidate the registered byte-preserving transport when a later corrective gate reads native failure evidence.
+ * Returns no authority and never changes the original failure record or its hash. */
+export function readFailedCheckpointDirtyTransport(store: FileStateStore, repository: string, task: TaskState,
+  stepId: string, sourceHead: string, sourceDirtyHash: string) {
+  const records = (task.dependencyProvenanceRecoveries ?? []).filter(record => {
+    const binding = (record as typeof record & { failedCheckpoint?: FailedCheckpointUpdateBinding }).failedCheckpoint;
+    return binding?.stepId === stepId && binding.sourceHead === sourceHead && binding.sourceDirtyHash === sourceDirtyHash;
+  });
+  if (records.length === 0) return null;
+  require(records.length === 1, 'Registered failed checkpoint is ambiguous.');
+  const record = records[0]!;
+  const binding = (record as typeof record & { failedCheckpoint: FailedCheckpointUpdateBinding }).failedCheckpoint;
+  require(task.planHash, 'Current Plan is required to validate the historical checkpoint.');
+  readVerifiedPlanArtifact(store.taskRoot(task.projectId, task.id), binding.sourcePlanHash, task.planHash);
+  require(binding.protocol === 'failed-checkpoint-update-v1' && task.systemCommits.includes(record.commitSha)
+    && record.packageVersion === FAILED_CHECKPOINT_TARGET && record.packageName === 'codex-workflow-v2'
+    && record.parentCommitSha === sourceHead && JSON.stringify(record.files) === JSON.stringify(['package-lock.json','package.json']),
+    'Registered failed checkpoint dependency record is invalid.');
+  const inspected = inspectBoundedWorkflowDependencyCommit(repository, record.commitSha);
+  require(inspected?.parentCommitSha === sourceHead && inspected.packageVersion === FAILED_CHECKPOINT_TARGET,
+    'Registered failed checkpoint no longer identifies a dependency-only commit.');
+  require(headCommit(repository) === record.commitSha, 'Dirty checkpoint requires its exact transported HEAD.');
+  const terminal = readRemediationEvents(store, task).filter(event => event.stepId === stepId && event.failureKind === 'checks-failed').at(-1);
+  require(terminal?.eventId === binding.remediationEventId && terminal.eventHash === binding.remediationEventHash
+    && terminal.failureEvidence.completionCommit === sourceHead && terminal.failureEvidence.dirtyWorktreeHash === sourceDirtyHash,
+    'Registered failed checkpoint does not bind the terminal native failure.');
+  const dirty = changedFiles(repository).sort();
+  require(JSON.stringify(dirty) === JSON.stringify(binding.dirtyFiles)
+    && failedCheckpointDirtyHash(repository, dirty, true) === sourceDirtyHash
+    && failedCheckpointDirtyHash(repository, dirty) === binding.targetDirtyHash,
+    'Retained product bytes changed after the registered dependency transport.');
+  return { sourceHead, sourceDirtyHash, targetHead: record.commitSha, targetDirtyHash: binding.targetDirtyHash,
+    dirtyFiles: [...dirty], sourceReceiptHash: binding.sourceReceiptHash };
+}

package/src/fs-utils.ts

@@ -0,0 +1,61 @@
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { WorkflowError } from './errors.js';
+
+export function ensureDirectory(directory: string): void {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (lstatSync(directory).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `State directory must not be a symlink: ${directory}`);
+  }
+}
+
+export function readJson<T>(file: string): T {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as T;
+  } catch (error) {
+    throw new WorkflowError('STATE_CORRUPT', `Cannot read JSON state: ${file}`, {
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+export function writeJsonAtomic(file: string, value: unknown): void {
+  const directory = path.dirname(file);
+  ensureDirectory(directory);
+  if (existsSync(file) && lstatSync(file).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Refusing to replace state symlink: ${file}`);
+  }
+  const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+export function writeTextAtomic(file: string, content: string): void {
+  const directory = path.dirname(file);
+  ensureDirectory(directory);
+  const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, content.endsWith('\n') ? content : `${content}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}