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

package/src/git.ts

@@ -0,0 +1,183 @@
+import { spawnSync } from 'node:child_process';
+import { WorkflowError } from './errors.js';
+import { runCheckCommands, type CheckExecutionOptions } from './checks/runner.js';
+import { changedFiles, currentBranch, headCommit, isClean, runGit } from './repository.js';
+import { pathAllowed } from './domain/validation.js';
+import type { TaskState } from './contracts.js';
+
+const PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'staging', 'production']);
+
+export function startLocalTaskBranch(
+  repositoryRoot: string,
+  branch: string,
+  baseBranch: string,
+  expectedBaseCommit: string | null = null,
+): string {
+  if (!isClean(repositoryRoot)) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Task start requires a clean checkout.', {
+      changedFiles: changedFiles(repositoryRoot),
+    });
+  }
+  if (PROTECTED_BRANCHES.has(branch)) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Task branch is protected: ${branch}`);
+  }
+  const baseCommit = runGit(repositoryRoot, ['rev-parse', baseBranch]);
+  if (expectedBaseCommit !== null && baseCommit !== expectedBaseCommit) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Task start base moved after execution authorization.', {
+      baseBranch,
+      authorizedBaseCommit: expectedBaseCommit,
+      currentBaseCommit: baseCommit,
+    });
+  }
+  runGit(repositoryRoot, ['switch', '-c', branch, baseBranch]);
+  return baseCommit;
+}
+
+export interface CheckResult {
+  command: string;
+  passed: boolean;
+  exitCode: number;
+  output: string;
+}
+
+/** Only ordinary exited checks can enter product failure/remediation evidence. */
+export function runChecks(repositoryRoot: string, commands: string[], options: CheckExecutionOptions = {}): CheckResult[] {
+  const configured: CheckExecutionOptions = { ...options };
+  const envNumber = (name: string): number | undefined => {
+    const value = process.env[name];
+    if (value === undefined) return undefined;
+    const parsed = Number(value);
+    if (!value.trim() || !Number.isSafeInteger(parsed) || parsed <= 0) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${name} must be a positive integer.`);
+    }
+    return parsed;
+  };
+  if (configured.timeoutMs === undefined) {
+    const value = envNumber('CODEX_WORKFLOW_CHECK_TIMEOUT_MS');
+    if (value !== undefined) configured.timeoutMs = value;
+  }
+  if (configured.totalTimeoutMs === undefined) {
+    const value = envNumber('CODEX_WORKFLOW_CHECK_TOTAL_TIMEOUT_MS');
+    if (value !== undefined) configured.totalTimeoutMs = value;
+  }
+  if (configured.cancellationFile === undefined && process.env.CODEX_WORKFLOW_CHECK_CANCEL_FILE !== undefined) {
+    configured.cancellationFile = process.env.CODEX_WORKFLOW_CHECK_CANCEL_FILE;
+  }
+  const results = runCheckCommands(repositoryRoot, commands, configured);
+  if (results.some(result => result.outcome === 'infra')) {
+    throw new WorkflowError('CHECK_INFRASTRUCTURE_FAILED',
+      'Check execution ended with an infrastructure failure. Product failure and corrective replanning were not inferred.', {
+        checks: results,
+        retryRequiresFreshObservation: true,
+        automaticRetry: false,
+      });
+  }
+  return results.map(result => {
+    if (result.exitCode === null || result.signal !== null || result.error !== null || !result.cleanupComplete) {
+      throw new WorkflowError('CHECK_INFRASTRUCTURE_FAILED', 'Check result lacks a verified ordinary exit.', { checks: results });
+    }
+    return { command: result.command, passed: result.outcome === 'passed', exitCode: result.exitCode, output: result.output };
+  });
+}
+
+export function commitStep(
+  repositoryRoot: string,
+  taskId: string,
+  stepId: string,
+  title: string,
+  allowedWrites: string[],
+): { commitSha: string; files: string[] } {
+  const files = changedFiles(repositoryRoot);
+  if (files.length === 0) throw new WorkflowError('TRANSITION_BLOCKED', `${stepId} has no changed files.`);
+  const unexpected = files.filter((file) => !pathAllowed(file, allowedWrites));
+  if (unexpected.length > 0) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `${stepId} changed files outside allowedWrites.`, { unexpected });
+  }
+  runGit(repositoryRoot, ['add', '--', ...files]);
+  runGit(repositoryRoot, [
+    'commit',
+    '-m',
+    `${taskId}/${stepId}: ${title}`,
+    '-m',
+    `Task: ${taskId}\nStep: ${stepId}`,
+  ]);
+  return { commitSha: headCommit(repositoryRoot), files };
+}
+
+export function mergeTaskBranch(repositoryRoot: string, taskBranch: string, baseBranch: string): string {
+  if (!isClean(repositoryRoot)) throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Merge requires a clean checkout.');
+  if (currentBranch(repositoryRoot) !== taskBranch) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Expected current task branch ${taskBranch}.`);
+  }
+  runGit(repositoryRoot, ['switch', baseBranch]);
+  const result = spawnSync('git', ['-C', repositoryRoot, 'merge', '--no-ff', taskBranch, '-m', `${taskBranch}: merge task`], {
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    spawnSync('git', ['-C', repositoryRoot, 'merge', '--abort'], { encoding: 'utf8' });
+    runGit(repositoryRoot, ['switch', taskBranch]);
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Merge conflict while merging ${taskBranch}.`, {
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+    });
+  }
+  return headCommit(repositoryRoot);
+}
+
+export function syncBaseIntoTask(
+  repositoryRoot: string,
+  taskBranch: string,
+  baseBranch: string,
+): { baseCommit: string; syncCommit: string } {
+  if (!isClean(repositoryRoot)) throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Base sync requires a clean checkout.');
+  if (currentBranch(repositoryRoot) !== taskBranch) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Expected current task branch ${taskBranch}.`);
+  }
+  const result = spawnSync('git', ['-C', repositoryRoot, 'merge', '--no-edit', baseBranch], { encoding: 'utf8' });
+  if (result.status !== 0) {
+    const abort = spawnSync('git', ['-C', repositoryRoot, 'merge', '--abort'], { encoding: 'utf8' });
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Base sync conflict from ${baseBranch}.`, {
+      cleanAbortVerified: abort.status === 0 && isClean(repositoryRoot),
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+    });
+  }
+  return {
+    baseCommit: runGit(repositoryRoot, ['rev-parse', baseBranch]),
+    syncCommit: headCommit(repositoryRoot),
+  };
+}
+
+export function validateTaskHistory(
+  repositoryRoot: string,
+  task: TaskState,
+  historyBoundary = 'HEAD',
+): void {
+  if (!task.baseCommit) throw new WorkflowError('STATE_CORRUPT', `Task ${task.id} has no base commit.`);
+  const boundaryCommit = runGit(repositoryRoot, ['rev-parse', historyBoundary]);
+  const actualOutput = runGit(repositoryRoot, ['rev-list', '--reverse', `${task.baseCommit}..${boundaryCommit}`]);
+  const actual = actualOutput ? actualOutput.split('\n') : [];
+  const expected = [...new Set([
+    ...task.steps.flatMap((step) => (step.evidence ? [step.evidence.commitSha] : [])),
+    ...task.systemCommits,
+    ...(task.invalidatedStepCommits ?? []),
+    ...(task.historicalStepProvenanceRecoveries ?? []).map((recovery) => recovery.commitSha),
+    ...(task.dependencyProvenanceRecoveries ?? []).flatMap((recovery) => recovery.retainedHistoricalCommits ?? []),
+  ])];
+  const missing = expected.filter((commit) => !actual.includes(commit));
+  const unexpected = actual.filter((commit) => !expected.includes(commit));
+  if (missing.length > 0 || unexpected.length > 0 || actual.length !== expected.length) {
+    throw new WorkflowError(
+      'GIT_PRECONDITION_FAILED',
+      'Task branch history contains commits not recorded by Workflow V2. Workers must leave Step changes uncommitted and let task step-complete create the commit. Stop and request coordinator-led Git recovery; do not create another commit or edit workflow state.',
+      {
+        missing,
+        unexpected,
+        baseCommit: task.baseCommit,
+        headCommit: headCommit(repositoryRoot),
+        historyBoundary: boundaryCommit,
+        recovery: 'Restore the pre-commit working changes under coordinator control, then invoke task step-complete.',
+      },
+    );
+  }
+}

package/src/graph.ts

@@ -0,0 +1,342 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STATE_SCHEMA_VERSION, PROTOCOL_VERSION } from './contracts.js';
+import type {
+  GraphBinding,
+  GraphBindingSnapshot,
+  GraphKind,
+  GraphMode,
+  GraphRefreshEvidence,
+  GraphRefreshRequest,
+} from './contracts.js';
+import { WorkflowError } from './errors.js';
+import { writeJsonAtomic } from './fs-utils.js';
+import { headCommit } from './repository.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+
+export interface GraphManifest {
+  packageName: string;
+  packageVersion: string;
+  protocolVersion: number;
+  stateSchemaVersion: number;
+  createdAt: string;
+  files: Array<{ path: string; sha256: string }>;
+}
+
+const WORKFLOW_GRAPH_SOURCE_ROOTS = ['src', 'roles', 'references', 'schemas', 'plugins/codex-workflow-gateway'] as const;
+
+export function graphViewRoot(): string {
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(codexHome, 'workflow-cache', 'codex-workflow', PACKAGE_VERSION);
+}
+
+export function prepareGraphView(target = graphViewRoot()): { root: string; manifest: GraphManifest } {
+  const packageRoot = resolvePackageRoot();
+  const temporary = `${target}.tmp-${randomUUID()}`;
+  rmSync(temporary, { recursive: true, force: true });
+  mkdirSync(temporary, { recursive: true, mode: 0o700 });
+  try {
+    for (const relative of ['dist/src', 'roles', 'references', 'schemas']) {
+      const source = path.join(packageRoot, relative);
+      if (!existsSync(source)) {
+        throw new WorkflowError('NOT_FOUND', `Graph source is missing from package: ${relative}`);
+      }
+      copyTreeWithoutSymlinks(source, path.join(temporary, relative));
+    }
+    const files = listFiles(temporary).map((file) => ({
+      path: path.relative(temporary, file).replaceAll('\\', '/'),
+      sha256: createHash('sha256').update(readFileSync(file)).digest('hex'),
+    }));
+    const manifest: GraphManifest = {
+      packageName: PACKAGE_NAME,
+      packageVersion: PACKAGE_VERSION,
+      protocolVersion: PROTOCOL_VERSION,
+      stateSchemaVersion: STATE_SCHEMA_VERSION,
+      createdAt: new Date().toISOString(),
+      files,
+    };
+    writeJsonAtomic(path.join(temporary, 'manifest.json'), manifest);
+    rmSync(target, { recursive: true, force: true });
+    mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    renameSync(temporary, target);
+    return { root: target, manifest };
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+export function inspectGraphView(target = graphViewRoot()): { present: boolean; current: boolean; root: string } {
+  const manifestFile = path.join(target, 'manifest.json');
+  if (!existsSync(manifestFile)) return { present: false, current: false, root: target };
+  try {
+    const manifest = JSON.parse(readFileSync(manifestFile, 'utf8')) as GraphManifest;
+    return {
+      present: true,
+      current:
+        manifest.packageName === PACKAGE_NAME &&
+        manifest.packageVersion === PACKAGE_VERSION &&
+        manifest.protocolVersion === PROTOCOL_VERSION &&
+        manifest.stateSchemaVersion === STATE_SCHEMA_VERSION,
+      root: target,
+    };
+  } catch {
+    return { present: true, current: false, root: target };
+  }
+}
+
+export function createGraphRefreshRequest(
+  repositoryRoot: string,
+  projectId: string,
+  graphKind: GraphKind,
+  mode: GraphMode = 'moderate',
+  now: Date = new Date(),
+): GraphRefreshRequest {
+  if (graphKind === 'product') {
+    const sourceRoot = path.resolve(repositoryRoot);
+    return {
+      protocolVersion: PROTOCOL_VERSION,
+      requestId: randomUUID(),
+      projectId,
+      graphKind,
+      sourceRoot,
+      rootFingerprint: createHash('sha256').update(`${projectId}\0${sourceRoot}`).digest('hex'),
+      indexedHead: headCommit(sourceRoot),
+      packageVersion: null,
+      manifestHash: null,
+      mode,
+      persistence: false,
+      issuedAt: now.toISOString(),
+    };
+  }
+  const packageRoot = resolvePackageRoot();
+  const manifest = workflowPackageGraphManifest(packageRoot, now);
+  const manifestHash = hashGraphManifest(manifest);
+  return {
+    protocolVersion: PROTOCOL_VERSION,
+    requestId: randomUUID(),
+    projectId,
+    graphKind,
+    sourceRoot: packageRoot,
+    rootFingerprint: createHash('sha256').update(`${PACKAGE_NAME}\0${PACKAGE_VERSION}\0${manifestHash}`).digest('hex'),
+    indexedHead: null,
+    packageVersion: PACKAGE_VERSION,
+    manifestHash,
+    mode,
+    persistence: false,
+    issuedAt: now.toISOString(),
+  };
+}
+
+function workflowPackageGraphManifest(packageRoot: string, now: Date): GraphManifest {
+  const files = WORKFLOW_GRAPH_SOURCE_ROOTS.flatMap((relative) => {
+    const source = path.join(packageRoot, relative);
+    if (!existsSync(source)) {
+      throw new WorkflowError('NOT_FOUND', `Workflow graph source is missing from package: ${relative}`);
+    }
+    return listFiles(source).map((file) => ({
+      path: path.relative(packageRoot, file).replaceAll('\\', '/'),
+      sha256: createHash('sha256').update(readFileSync(file)).digest('hex'),
+    }));
+  }).sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    packageName: PACKAGE_NAME,
+    packageVersion: PACKAGE_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    stateSchemaVersion: STATE_SCHEMA_VERSION,
+    createdAt: now.toISOString(),
+    files,
+  };
+}
+
+export function bindGraphEvidence(
+  projectId: string,
+  request: GraphRefreshRequest,
+  evidence: GraphRefreshEvidence,
+  existing: GraphBinding | null,
+  now: Date = new Date(),
+): GraphBinding {
+  validateGraphEvidence(request, evidence);
+  const timestamp = now.toISOString();
+  const snapshot: GraphBindingSnapshot = {
+    projectKey: evidence.projectKey,
+    rootFingerprint: evidence.rootFingerprint,
+    indexedHead: evidence.indexedHead,
+    packageVersion: evidence.packageVersion,
+    manifestHash: evidence.manifestHash,
+    mode: evidence.mode,
+    status: evidence.status,
+    nodeCount: evidence.nodeCount,
+    edgeCount: evidence.edgeCount,
+    observedAt: evidence.observedAt,
+    evidenceHash: createHash('sha256').update(JSON.stringify(evidence)).digest('hex'),
+    fallbackReason: null,
+  };
+  const retainPrevious = request.graphKind === 'workflow' && existing?.packageVersion !== snapshot.packageVersion;
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    revision: existing?.revision ?? 0,
+    id: `GRAPH-${request.graphKind}`,
+    projectId,
+    createdAt: existing?.createdAt ?? timestamp,
+    updatedAt: timestamp,
+    kind: 'graph-binding',
+    graphKind: request.graphKind,
+    provider: 'codebase-memory-mcp',
+    ...snapshot,
+    previous: retainPrevious && existing ? graphSnapshot(existing) : existing?.previous ?? null,
+  };
+}
+
+export function fallbackGraphBinding(
+  projectId: string,
+  request: GraphRefreshRequest,
+  reason: string,
+  existing: GraphBinding | null,
+  now: Date = new Date(),
+): GraphBinding {
+  if (!reason.trim()) throw new WorkflowError('INVALID_ARGUMENT', 'Graph fallback requires a reason.');
+  const timestamp = now.toISOString();
+  const evidenceHash = createHash('sha256')
+    .update(JSON.stringify({ requestId: request.requestId, reason: reason.trim(), observedAt: timestamp }))
+    .digest('hex');
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    revision: existing?.revision ?? 0,
+    id: `GRAPH-${request.graphKind}`,
+    projectId,
+    createdAt: existing?.createdAt ?? timestamp,
+    updatedAt: timestamp,
+    kind: 'graph-binding',
+    graphKind: request.graphKind,
+    provider: 'codebase-memory-mcp',
+    projectKey: existing?.projectKey ?? null,
+    rootFingerprint: request.rootFingerprint,
+    indexedHead: request.indexedHead,
+    packageVersion: request.packageVersion,
+    manifestHash: request.manifestHash,
+    mode: request.mode,
+    status: 'fallback',
+    nodeCount: existing?.nodeCount ?? null,
+    edgeCount: existing?.edgeCount ?? null,
+    observedAt: timestamp,
+    evidenceHash,
+    fallbackReason: reason.trim(),
+    previous: existing?.previous ?? null,
+  };
+}
+
+export function inspectGraphBinding(binding: GraphBinding, request: GraphRefreshRequest): GraphBinding {
+  const stale =
+    binding.rootFingerprint !== request.rootFingerprint ||
+    binding.mode !== request.mode ||
+    binding.indexedHead !== request.indexedHead ||
+    binding.packageVersion !== request.packageVersion ||
+    binding.manifestHash !== request.manifestHash;
+  return stale && binding.status === 'ready' ? { ...binding, status: 'stale' } : binding;
+}
+
+export function validateGraphRequestCurrent(request: GraphRefreshRequest, current: GraphRefreshRequest): void {
+  const fields: Array<keyof GraphRefreshRequest> = [
+    'projectId',
+    'graphKind',
+    'sourceRoot',
+    'rootFingerprint',
+    'indexedHead',
+    'packageVersion',
+    'manifestHash',
+    'mode',
+    'persistence',
+  ];
+  const stale = fields.filter((field) => request[field] !== current[field]);
+  if (request.protocolVersion !== PROTOCOL_VERSION || stale.length > 0) {
+    throw new WorkflowError('STATE_CONFLICT', 'Graph refresh request is stale or incompatible.', { stale });
+  }
+}
+
+export function hashGraphManifest(manifest: GraphManifest): string {
+  return createHash('sha256').update(JSON.stringify({
+    packageName: manifest.packageName,
+    packageVersion: manifest.packageVersion,
+    protocolVersion: manifest.protocolVersion,
+    stateSchemaVersion: manifest.stateSchemaVersion,
+    files: manifest.files,
+  })).digest('hex');
+}
+
+function validateGraphEvidence(request: GraphRefreshRequest, evidence: GraphRefreshEvidence): void {
+  const invalid =
+    evidence.requestId !== request.requestId ||
+    evidence.provider !== 'codebase-memory-mcp' ||
+    evidence.rootFingerprint !== request.rootFingerprint ||
+    evidence.indexedHead !== request.indexedHead ||
+    evidence.packageVersion !== request.packageVersion ||
+    evidence.manifestHash !== request.manifestHash ||
+    evidence.mode !== request.mode;
+  if (invalid || !evidence.projectKey.trim()) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Graph evidence does not match the refresh request.');
+  }
+}
+
+function graphSnapshot(binding: GraphBinding): GraphBindingSnapshot {
+  return {
+    projectKey: binding.projectKey,
+    rootFingerprint: binding.rootFingerprint,
+    indexedHead: binding.indexedHead,
+    packageVersion: binding.packageVersion,
+    manifestHash: binding.manifestHash,
+    mode: binding.mode,
+    status: binding.status,
+    nodeCount: binding.nodeCount,
+    edgeCount: binding.edgeCount,
+    observedAt: binding.observedAt,
+    evidenceHash: binding.evidenceHash,
+    fallbackReason: binding.fallbackReason,
+  };
+}
+
+function resolvePackageRoot(): string {
+  let cursor = path.dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 4; depth += 1) {
+    const packageFile = path.join(cursor, 'package.json');
+    if (existsSync(packageFile)) {
+      const parsed = JSON.parse(readFileSync(packageFile, 'utf8')) as { name?: string };
+      if (parsed.name === PACKAGE_NAME) return cursor;
+    }
+    cursor = path.dirname(cursor);
+  }
+  throw new WorkflowError('NOT_FOUND', `Cannot resolve installed ${PACKAGE_NAME} package root.`);
+}
+
+function copyTreeWithoutSymlinks(source: string, destination: string): void {
+  const metadata = lstatSync(source);
+  if (metadata.isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Graph source must not be a symlink: ${source}`);
+  }
+  if (metadata.isDirectory()) {
+    mkdirSync(destination, { recursive: true, mode: 0o700 });
+    for (const entry of readdirSync(source)) {
+      copyTreeWithoutSymlinks(path.join(source, entry), path.join(destination, entry));
+    }
+    return;
+  }
+  copyFileSync(source, destination);
+}
+
+function listFiles(root: string): string[] {
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const target = path.join(root, entry.name);
+    return entry.isDirectory() ? listFiles(target) : [target];
+  }).sort();
+}

package/src/historical-step-provenance.ts

@@ -0,0 +1,136 @@
+import type {
+  HistoricalStepProvenanceRecoveryPreflight,
+  TaskState,
+} from './contracts.js';
+import { changedFiles, currentBranch, headCommit, runGit } from './repository.js';
+
+export interface HistoricalStepProvenanceEnvironment {
+  activeLeaseCount: number;
+  staleLeaseCount: number;
+  pendingTransactionCount: number;
+  corruptTransactionCount: number;
+  coreOperationCount: number;
+  verifiedHistoricalStepBindings: Array<{
+    stepId: string;
+    commitSha: string;
+    planHash: string;
+    recordedAt: string;
+  }>;
+}
+
+export interface HistoricalStepProvenanceInspectionOptions {
+  historyBoundary?: string;
+  preservedHeadCommit?: string;
+}
+
+export function omittedStepEvidenceCommits(
+  task: TaskState,
+  nextSteps: ReadonlyArray<Pick<TaskState['steps'][number], 'evidence'>>,
+): string[] {
+  const retainedByCurrentPlan = new Set(nextSteps.flatMap((step) =>
+    step.evidence ? [step.evidence.commitSha] : []));
+  return [...new Set(task.steps.flatMap((step) =>
+    step.evidence && !retainedByCurrentPlan.has(step.evidence.commitSha)
+      ? [step.evidence.commitSha]
+      : []))];
+}
+
+export function inspectHistoricalStepProvenanceRecovery(
+  repositoryRoot: string,
+  task: TaskState,
+  environment: HistoricalStepProvenanceEnvironment,
+  options: HistoricalStepProvenanceInspectionOptions = {},
+): HistoricalStepProvenanceRecoveryPreflight {
+  const blockers: string[] = [];
+  const dirty = changedFiles(repositoryRoot);
+  const historyBoundary = options.historyBoundary ?? 'HEAD';
+  const head = options.preservedHeadCommit ?? headCommit(repositoryRoot);
+  const activeSteps = task.steps.filter((step) => step.status === 'in_progress');
+  const activeStep = activeSteps.length === 1 ? activeSteps[0]! : null;
+
+  if (task.status !== 'in_progress') blockers.push('The Task must be in progress.');
+  if (activeSteps.length !== 1) blockers.push('Exactly one Step must be in progress.');
+  if (activeStep && dirty.some((file) => !activeStep.allowedWrites.includes(file))) {
+    blockers.push('Dirty files must remain confined to the active Step allowedWrites.');
+  }
+  if (task.workspaceOwner !== 'local') blockers.push('Recovery is limited to a local Task workspace.');
+  if (!task.taskBranch || currentBranch(repositoryRoot) !== task.taskBranch) {
+    blockers.push('The current branch must be the recorded Task branch.');
+  }
+  if (!task.baseCommit) blockers.push('The Task must have a recorded base commit.');
+  if (!task.planHash) blockers.push('The Task must have a current Plan hash.');
+  if (environment.activeLeaseCount > 0) blockers.push('No active writer lease may exist.');
+  if (environment.staleLeaseCount > 0) blockers.push('No stale writer lease may exist.');
+  if (environment.pendingTransactionCount > 0) blockers.push('No pending Workflow transaction may exist.');
+  if (environment.corruptTransactionCount > 0) blockers.push('No corrupt Workflow transaction may exist.');
+  if (environment.coreOperationCount > 0) blockers.push('No Core Task operation may exist.');
+
+  let candidate: string | null = null;
+  let sourceFinalAcceptanceRecordedAt: string | null = null;
+  if (task.baseCommit) {
+    try {
+      const output = runGit(repositoryRoot, ['rev-list', '--reverse', `${task.baseCommit}..${historyBoundary}`]);
+      const actual = output ? output.split('\n') : [];
+      const expected = [...new Set([
+        ...task.steps.flatMap((step) => (step.evidence ? [step.evidence.commitSha] : [])),
+        ...task.systemCommits,
+        ...(task.invalidatedStepCommits ?? []),
+        ...(task.dependencyProvenanceRecoveries ?? []).flatMap((recovery) => recovery.retainedHistoricalCommits ?? []),
+      ])];
+      const missing = expected.filter((commit) => !actual.includes(commit));
+      const unexpected = actual.filter((commit) => !expected.includes(commit));
+      if (missing.length > 0) blockers.push('Recorded Task history contains missing commits.');
+      if (unexpected.length !== 1) blockers.push('Recovery requires exactly one unregistered historical commit.');
+      candidate = unexpected.length === 1 ? unexpected[0]! : null;
+      const verifiedBindings = candidate
+        ? environment.verifiedHistoricalStepBindings.filter((binding) => binding.commitSha === candidate)
+        : [];
+      if (verifiedBindings.length === 0) {
+        blockers.push('The historical commit lacks a complete passed strict Step Review chain.');
+      }
+      const finalAcceptance = candidate
+        ? task.authorizations.find((authorization) =>
+            authorization.kind === 'final_acceptance'
+            && ['approved', 'superseded'].includes(authorization.decision)
+            && authorization.headCommit === candidate
+            && authorization.planHash
+            && authorization.resultHash
+            && authorization.evidenceHash)
+        : null;
+      if (!finalAcceptance) {
+        blockers.push('The historical commit lacks a hash-bound prior final acceptance.');
+      } else {
+        sourceFinalAcceptanceRecordedAt = finalAcceptance.recordedAt;
+        if (!verifiedBindings.some((binding) =>
+          binding.planHash === finalAcceptance.planHash
+          && binding.recordedAt <= finalAcceptance.recordedAt)) {
+          blockers.push('The prior final acceptance does not bind the passed historical Step Review Plan.');
+        }
+      }
+      if (candidate) {
+        const subject = runGit(repositoryRoot, ['show', '-s', '--format=%s', candidate]);
+        if (!subject.startsWith(`${task.id}/STEP-`)) {
+          blockers.push('The historical commit subject is not bound to this Task and a Step.');
+        }
+      }
+    } catch {
+      blockers.push('The Task history could not be inspected.');
+    }
+  }
+
+  return {
+    eligible: blockers.length === 0,
+    action: blockers.length === 0 ? 'task historical-step-provenance-recover' : null,
+    projectId: task.projectId,
+    taskId: task.id,
+    taskRevision: task.revision,
+    briefHash: task.briefHash,
+    planHash: task.planHash,
+    headCommit: head,
+    activeStepId: activeStep?.id ?? null,
+    dirtyFiles: dirty,
+    commitSha: blockers.length === 0 ? candidate : null,
+    sourceFinalAcceptanceRecordedAt: blockers.length === 0 ? sourceFinalAcceptanceRecordedAt : null,
+    blockers,
+  };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export * from './contracts.js';
+export * from './errors.js';
+export * from './diagnostics.js';
+export * from './delegation.js';
+export * from './graph.js';
+export * from './memory.js';
+export * from './migration.js';
+export * from './repository.js';
+export * from './reviewer.js';
+export * from './observed-routes.js';
+export * from './operational-contract.js';
+export * from './state/store.js';
+export * from './workflow.js';
+export * from './version.js';
+export * from './lifecycle/index.js';
+export * from './alpha7/autonomy.js';
+export * from './alpha6/mechanical-feasibility.js';
+export { defaultTaskWorkerActor } from './alpha6/handoff.js';
+export { defaultCorrectiveAuditorActor } from './alpha6/remediation.js';
+export type { AdoptionPreparation } from './alpha6/adoption.js';
+export type { RecordPlanRiskAuditInput } from './alpha6/plan-risk.js';
+
+export type { CheckExecutionOptions } from './checks/runner.js';