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

package/src/operational-contract.ts

@@ -0,0 +1,125 @@
+import { createHash } from 'node:crypto';
+import { changedFiles, runGit } from './repository.js';
+
+const HEX_64 = /^[a-f0-9]{64}$/;
+
+export interface AppOwnedPreflightBase {
+  contract: 'codex-workflow-app-owned-preflight-v1';
+  authority: 'diagnostic-only';
+  owner: 'codex-app';
+  packageMutatesAppState: false;
+  atomicAppEffectClaimed: false;
+}
+
+export function watchdogPreflight(input: {
+  previousRouteFingerprint: string | null;
+  currentRouteFingerprint: string;
+  lastSuccessfulPollAt: string | null;
+  lastSignificantObservationAt: string | null;
+}): AppOwnedPreflightBase & Record<string, unknown> {
+  const valid = HEX_64.test(input.currentRouteFingerprint)
+    && (input.previousRouteFingerprint === null || HEX_64.test(input.previousRouteFingerprint));
+  return {
+    ...appOwnedBase(),
+    eligible: valid,
+    routeChanged: input.previousRouteFingerprint !== input.currentRouteFingerprint,
+    schedulingPerformed: false,
+    checkpoint: {
+      lastSuccessfulPollAt: input.lastSuccessfulPollAt,
+      lastSignificantObservationAt: input.lastSignificantObservationAt,
+    },
+    blockers: valid ? [] : ['Route fingerprints must be exact SHA-256 values.'],
+  };
+}
+
+export function coordinatorReplacementPreflight(input: {
+  previousCoordinatorTerminal: boolean;
+  replacementCoordinatorId: string;
+  activeSupervisorIds: string[];
+  coreReadbackFingerprint: string;
+}): AppOwnedPreflightBase & Record<string, unknown> {
+  const supervisors = [...new Set(input.activeSupervisorIds)];
+  const eligible = input.previousCoordinatorTerminal
+    && input.replacementCoordinatorId.trim().length > 0
+    && supervisors.length === 1
+    && supervisors[0] === input.replacementCoordinatorId
+    && HEX_64.test(input.coreReadbackFingerprint);
+  return {
+    ...appOwnedBase(),
+    eligibleToRequestReplacement: eligible,
+    replacementPerformed: false,
+    activeSupervisorIds: supervisors,
+    blockers: eligible
+      ? []
+      : ['Terminal predecessor, one replacement supervisor, and exact Core readback are required.'],
+  };
+}
+
+export function appConsentPreflight(input: {
+  requestedTaskId: string;
+  presentedTaskId: string | null;
+  presentedTaskRevision: number | null;
+  consentReceiptHash: string | null;
+}): AppOwnedPreflightBase & Record<string, unknown> {
+  const receiptStructurallyValid = input.presentedTaskId === input.requestedTaskId
+    && Number.isInteger(input.presentedTaskRevision)
+    && (input.presentedTaskRevision ?? -1) >= 0
+    && typeof input.consentReceiptHash === 'string'
+    && HEX_64.test(input.consentReceiptHash);
+  return {
+    ...appOwnedBase(),
+    receiptStructurallyValid,
+    consentGrantedByPackage: false,
+    semanticAuthorityEstablished: false,
+    requiredAppReadback: receiptStructurallyValid ? 'verify-consent-with-host' : 'obtain-current-consent-receipt',
+  };
+}
+
+export function worktreeObservationPreflight(
+  repositoryRoot: string,
+  limit = 32,
+): AppOwnedPreflightBase & Record<string, unknown> {
+  const boundedLimit = Number.isInteger(limit) && limit > 0 ? Math.min(limit, 32) : 32;
+  const blocks = runGit(repositoryRoot, ['worktree', 'list', '--porcelain'])
+    .split(/\n\n+/)
+    .filter(Boolean);
+  const records = blocks.slice(0, boundedLimit).map((block) => {
+    const fields = new Map<string, string>();
+    for (const line of block.split('\n')) {
+      const separator = line.indexOf(' ');
+      if (separator > 0) fields.set(line.slice(0, separator), line.slice(separator + 1));
+    }
+    const worktree = fields.get('worktree') ?? '';
+    const dirty = changedFiles(worktree).sort();
+    return {
+      worktree,
+      head: fields.get('HEAD') ?? null,
+      branch: fields.get('branch')?.replace(/^refs\/heads\//, '') ?? null,
+      dirtyCount: dirty.length,
+      dirtyFingerprint: sha256(dirty.join('\n')),
+    };
+  });
+  return {
+    ...appOwnedBase(),
+    bounded: true,
+    limit: boundedLimit,
+    truncated: blocks.length > boundedLimit,
+    records,
+    observationFingerprint: sha256(JSON.stringify(records)),
+    worktreeSelectionPerformed: false,
+  };
+}
+
+function appOwnedBase(): AppOwnedPreflightBase {
+  return {
+    contract: 'codex-workflow-app-owned-preflight-v1',
+    authority: 'diagnostic-only',
+    owner: 'codex-app',
+    packageMutatesAppState: false,
+    atomicAppEffectClaimed: false,
+  };
+}
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}

package/src/pending-review-update.ts

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { TaskState, SidecarEventRecord } from './contracts.js';
+import { requireCurrentStrictStepReview } from './alpha6/review.js';
+import { readCurrentPlanRiskAudit } from './alpha6/plan-risk.js';
+import { canonicalJsonStringify, sha256Hex, readSidecarEvents } from './alpha6/store-sidecars.js';
+import { inspectBoundedWorkflowDependencyCommit } from './dependency-provenance.js';
+import { validateTaskHistory } from './git.js';
+import { currentBranch, headCommit, isClean, runGit } from './repository.js';
+import { FileStateStore } from './state/store.js';
+import { PACKAGE_VERSION } from './version.js';
+
+export const PENDING_REVIEW_SOURCE_VERSION: string = '2.0.0-beta.13.1';
+export interface PendingReviewUpdateBinding {
+  protocol: 'pending-review-update-v1';
+  projectId: string;
+  taskId: string;
+  taskRevision: number;
+  taskBranch: string;
+  baseBranch: string;
+  baseHead: string;
+  planHash: string;
+  briefHash: string;
+  stepId: string;
+  completionCommit: string;
+  pendingEventHash: string;
+  evidenceHash: string;
+  sourceVersion: string;
+  targetVersion: string;
+  targetRuntimeHash: string;
+}
+export interface PendingReviewUpdateTransport {
+  source: PendingReviewUpdateBinding;
+  baseTransportCommit: string;
+}
+export const PENDING_REVIEW_UPDATE_SIDECAR = 'pending-review-updates.jsonl';
+export interface PendingReviewUpdateEvent extends SidecarEventRecord, PendingReviewUpdateTransport {
+  taskTransportCommit: string;
+}
+function requireCondition(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+/** Source inspection never writes state, refreshes Knowledge, or manufactures pending evidence. */
+export function pendingReviewSourceBinding(
+  repository: string, store: FileStateStore, task: TaskState,
+  completionCommit = headCommit(repository), baseHead = runGit(repository, ['rev-parse', task.baseBranch]),
+): PendingReviewUpdateBinding {
+  requireCondition(task.status === 'in_progress' && task.workspaceOwner === 'local', 'Expected a local in-progress Task.');
+  requireCondition(task.taskBranch && currentBranch(repository) === task.taskBranch, 'Expected the exact Task branch.');
+  requireCondition(isClean(repository), 'Expected a clean checkout.');
+  const active = task.steps.filter((step) => step.status === 'in_progress');
+  requireCondition(active.length === 1 && active[0]?.evidence?.commitSha === completionCommit,
+    'Exactly one in-progress Step must have completion evidence at the bound product HEAD.');
+  const step = active[0]!;
+  requireCondition(task.planHash && task.briefHash, 'Missing Plan or Brief binding.');
+  const taskRoot = store.taskRoot(task.projectId, task.id);
+  requireCondition(sha256Hex(readFileSync(path.join(taskRoot, 'plan.md'), 'utf8')) === task.planHash
+    && sha256Hex(readFileSync(path.join(taskRoot, 'brief.md'), 'utf8')) === task.briefHash,
+  'Plan or Brief artifact hash mismatch.');
+  const audit = readCurrentPlanRiskAudit(store, task);
+  requireCondition(audit?.reviewRequiredStepIds.includes(step.id), 'The current Plan audit must require strict review.');
+  const cycle = requireCurrentStrictStepReview(store, task, step.id);
+  requireCondition(cycle.resolution === 'pending' && cycle.pendingEvent, 'Expected a hash-valid pending review chain.');
+  validateTaskHistory(repository, task, completionCommit);
+  for (const revision of [completionCommit, baseHead]) {
+    const manifest = JSON.parse(runGit(repository, ['show', `${revision}:package.json`])) as {
+      devDependencies?: Record<string, string>; dependencies?: Record<string, string> };
+    const lock = JSON.parse(runGit(repository, ['show', `${revision}:package-lock.json`])) as {
+      packages?: Record<string, { version?: string; devDependencies?: Record<string, string>; dependencies?: Record<string, string> }> };
+    requireCondition(manifest.devDependencies?.['codex-workflow-v2'] === PENDING_REVIEW_SOURCE_VERSION
+      && manifest.dependencies?.['codex-workflow-v2'] === undefined
+      && lock.packages?.['']?.devDependencies?.['codex-workflow-v2'] === PENDING_REVIEW_SOURCE_VERSION
+      && lock.packages?.['']?.dependencies?.['codex-workflow-v2'] === undefined
+      && lock.packages?.['node_modules/codex-workflow-v2']?.version === PENDING_REVIEW_SOURCE_VERSION,
+    'Every source manifest and lock root/package entry must bind the exact source devDependency.');
+  }
+  return {
+    protocol: 'pending-review-update-v1', projectId: task.projectId, taskId: task.id,
+    taskRevision: task.revision, taskBranch: task.taskBranch, baseBranch: task.baseBranch, baseHead,
+    planHash: task.planHash, briefHash: task.briefHash, stepId: step.id, completionCommit,
+    pendingEventHash: cycle.pendingEvent.eventHash, evidenceHash: cycle.binding.evidenceHash,
+    sourceVersion: PENDING_REVIEW_SOURCE_VERSION, targetVersion: PACKAGE_VERSION,
+    targetRuntimeHash: pendingReviewRunnerFingerprint(),
+  };
+}
+
+export function assertPendingReviewTransport(
+  repository: string, source: PendingReviewUpdateBinding, taskHead: string, baseHead: string,
+): void {
+  requireCondition(source.protocol === 'pending-review-update-v1'
+    && source.sourceVersion === PENDING_REVIEW_SOURCE_VERSION
+    && source.targetVersion === PACKAGE_VERSION && source.targetVersion !== source.sourceVersion
+    && source.targetRuntimeHash === pendingReviewRunnerFingerprint(),
+  'Unsupported pending review source/target compatibility.');
+  for (const [commit, parent] of [[taskHead, source.completionCommit], [baseHead, source.baseHead]]) {
+    const inspected = inspectBoundedWorkflowDependencyCommit(repository, commit!);
+    requireCondition(inspected !== null && inspected.parentCommitSha === parent && inspected.packageVersion === source.targetVersion,
+      'Expected an exact dependency-only transport on the bound parent.');
+    requireCondition(runGit(repository, ['rev-list', '--parents', '-n', '1', commit!]).split(' ').length === 2,
+      'Dependency transport must have exactly one parent.');
+    const manifest = JSON.parse(runGit(repository, ['show', `${parent}:package.json`])) as { devDependencies?: Record<string, string> };
+    requireCondition(manifest.devDependencies?.['codex-workflow-v2'] === source.sourceVersion,
+      'Dependency transport parent must retain the exact source pin.');
+  }
+  requireCondition(runGit(repository, ['rev-parse', source.baseBranch]) === baseHead,
+    'The bound base branch moved after transport.');
+}
+
+/** This is deliberately only used by external sealed Step review, never generic review/seal logic. */
+export function verifiedPendingReviewTransport(repository: string, task: TaskState, stepId: string, taskRoot: string): PendingReviewUpdateTransport | null {
+  if (!existsSync(path.join(taskRoot, PENDING_REVIEW_UPDATE_SIDECAR))) return null;
+  const head = headCommit(repository);
+  const events = readSidecarEvents<PendingReviewUpdateEvent>(path.join(taskRoot, PENDING_REVIEW_UPDATE_SIDECAR), { trustedRoot: path.resolve(taskRoot, '../../../..') });
+  const matching = events.filter((event) => event.taskTransportCommit === head && event.source?.stepId === stepId);
+  if (matching.length === 0) return null;
+  const store = new FileStateStore({ root: path.resolve(taskRoot, '../../../..') });
+  requireCondition(store.taskRoot(task.projectId, task.id) === path.resolve(taskRoot), 'Unexpected Task sidecar root.');
+  // Review payloads can carry authorized check-support allowedWrites augmentations.
+  // Only canonical stored Step definitions establish the pending evidence hash.
+  const canonical = store.readTask(task.projectId, task.id);
+  requireCondition(canonical.revision === task.revision && canonical.planHash === task.planHash
+    && canonical.briefHash === task.briefHash
+    && canonicalJsonStringify(canonical.steps.find((step) => step.id === stepId)?.evidence ?? null)
+      === canonicalJsonStringify(task.steps.find((step) => step.id === stepId)?.evidence ?? null),
+  'Review payload no longer matches the canonical Task.');
+  task = canonical;
+  requireCondition(events.length === 1 && matching.length === 1, 'Expected one exact pending review update sidecar.');
+  const transport = matching[0]!;
+  const records = (task.dependencyProvenanceRecoveries ?? []).filter((record) => record.commitSha === head);
+  requireCondition(records.length === 1, 'Missing unique dependency registration for the review bridge.');
+  const record = records[0]!;
+  const source = transport.source;
+  const cycle = requireCurrentStrictStepReview(store, task, stepId);
+  requireCondition(cycle.pendingEvent?.eventHash === source.pendingEventHash
+    && cycle.binding.evidenceHash === source.evidenceHash, 'Transported pending review binding changed.');
+  const step = task.steps.find((candidate) => candidate.id === stepId);
+  requireCondition(source.projectId === task.projectId && source.taskId === task.id
+    && source.taskBranch === task.taskBranch && source.baseBranch === task.baseBranch
+    && currentBranch(repository) === source.taskBranch && isClean(repository)
+    && source.planHash === task.planHash && source.briefHash === task.briefHash
+    && source.completionCommit === step?.evidence?.commitSha
+    && source.taskRevision < task.revision && task.systemCommits.includes(head)
+    && record.parentCommitSha === source.completionCommit && record.packageVersion === source.targetVersion,
+  'Pending review transport no longer matches the current Task.');
+  assertPendingReviewTransport(repository, source, head, transport.baseTransportCommit);
+  validateTaskHistory(repository, task);
+  return transport;
+}
+
+/** Verify the exact external runner's published build bytes without installing or writing. */
+export function pendingReviewRunnerFingerprint(): string {
+  const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(moduleDirectory, '../..');
+  const packageContent = readFileSync(path.join(packageRoot, 'package.json'), 'utf8');
+  const pkg = JSON.parse(packageContent) as { name: string; version: string };
+  const manifest = JSON.parse(readFileSync(path.join(packageRoot, 'dist/reviewer-runtime-build.json'), 'utf8')) as {
+    protocol: string; packageName: string; packageVersion: string; packageManifestSha256: string;
+    files: Array<{ path: string; sha256: string }>;
+  };
+  requireCondition(pkg.name === 'codex-workflow-v2' && pkg.version === PACKAGE_VERSION
+    && manifest.protocol === 'codex-workflow-runtime-build-manifest-v1'
+    && manifest.packageName === pkg.name && manifest.packageVersion === pkg.version
+    && manifest.packageManifestSha256 === sha256Hex(packageContent), 'Exact target runner package/build manifest mismatch.');
+  requireCondition(['cli.js', 'workflow.js', 'reviewer.js', 'gateway-handshake.js', 'pending-review-update.js']
+    .every((name) => manifest.files.some((entry) => entry.path === `dist/src/${name}`)), 'Target runner build entrypoints are incomplete.');
+  for (const entry of manifest.files) {
+    requireCondition(/^dist\/src\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]+\.js$/.test(entry.path)
+      && /^[a-f0-9]{64}$/.test(entry.sha256), 'Invalid target build entry.');
+    requireCondition(sha256Hex(readFileSync(path.join(moduleDirectory, entry.path.slice('dist/src/'.length)))) === entry.sha256,
+      'Exact target runner runtime bytes differ from build evidence.');
+  }
+  return sha256Hex(canonicalJsonStringify(manifest));
+}

package/src/repository.ts

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { WorkflowError } from './errors.js';
+
+export interface RepositoryIdentity {
+  projectId: string;
+  repositoryRoot: string;
+  gitCommonDir: string;
+}
+
+// Bound memory use while allowing complete multi-megabyte review diffs. Overflow is
+// an explicit failure, including for probes that allow ordinary Git exit failures.
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+const GIT_DIAGNOSTIC_LIMIT = 4096;
+
+export function runGit(repositoryRoot: string, args: string[], allowFailure = false): string {
+  const result = spawnSync('git', ['-C', repositoryRoot, ...args], {
+    encoding: 'utf8',
+    maxBuffer: GIT_MAX_BUFFER,
+  });
+  if (result.error || result.signal || (result.status !== 0 && !allowFailure)) {
+    throw new WorkflowError('COMMAND_FAILED', `git ${args.join(' ')} failed`, {
+      stdout: (result.stdout ?? '').slice(0, GIT_DIAGNOSTIC_LIMIT).trim(),
+      stderr: (result.stderr ?? '').slice(0, GIT_DIAGNOSTIC_LIMIT).trim(),
+      stdoutTruncated: (result.stdout?.length ?? 0) > GIT_DIAGNOSTIC_LIMIT,
+      stderrTruncated: (result.stderr?.length ?? 0) > GIT_DIAGNOSTIC_LIMIT,
+      exitCode: result.status,
+      signal: result.signal,
+      errorCode: (result.error as NodeJS.ErrnoException | undefined)?.code ?? null,
+      maxBufferBytes: GIT_MAX_BUFFER,
+    });
+  }
+  return result.stdout.trim();
+}
+
+export function resolveRepositoryIdentity(repository: string): RepositoryIdentity {
+  const repositoryRoot = realpathSync(runGit(repository, ['rev-parse', '--show-toplevel']));
+  const rawCommonDir = runGit(repositoryRoot, ['rev-parse', '--git-common-dir']);
+  const commonCandidate = path.isAbsolute(rawCommonDir)
+    ? rawCommonDir
+    : path.resolve(repositoryRoot, rawCommonDir);
+  const gitCommonDir = realpathSync(commonCandidate);
+  const projectId = createHash('sha256').update(gitCommonDir).digest('hex').slice(0, 24);
+  return { projectId, repositoryRoot, gitCommonDir };
+}
+
+export function currentBranch(repositoryRoot: string): string | null {
+  const branch = runGit(repositoryRoot, ['branch', '--show-current'], true);
+  return branch || null;
+}
+
+export function headCommit(repositoryRoot: string): string {
+  return runGit(repositoryRoot, ['rev-parse', 'HEAD']);
+}
+
+export function changedFiles(repositoryRoot: string): string[] {
+  const result = spawnSync(
+    'git',
+    ['-C', repositoryRoot, 'status', '--porcelain=v1', '--untracked-files=all'],
+    { encoding: 'utf8' },
+  );
+  if (result.status !== 0) {
+    throw new WorkflowError('COMMAND_FAILED', 'Unable to inspect Git working tree.', {
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+      exitCode: result.status,
+    });
+  }
+  const output = result.stdout.trimEnd();
+  if (!output) return [];
+  return output.split('\n').map((line) => {
+    const entry = line.slice(3).trim();
+    const renameTarget = entry.includes(' -> ') ? entry.split(' -> ').at(-1) : entry;
+    return renameTarget?.replaceAll('\\', '/') ?? entry;
+  });
+}
+
+export function isClean(repositoryRoot: string): boolean {
+  return changedFiles(repositoryRoot).length === 0;
+}
+
+export function gitIsAncestor(repositoryRoot: string, ancestor: string, descendant: string): boolean {
+  const result = spawnSync(
+    'git',
+    ['-C', repositoryRoot, 'merge-base', '--is-ancestor', ancestor, descendant],
+    { encoding: 'utf8' },
+  );
+  if (result.status === 0) return true;
+  if (result.status === 1) return false;
+  throw new WorkflowError('COMMAND_FAILED', 'Unable to verify Git ancestry.', {
+    ancestor,
+    descendant,
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim(),
+    exitCode: result.status,
+  });
+}