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

package/src/navigation-update-artifact.ts

@@ -0,0 +1,198 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pendingReviewRunnerFingerprint } from './pending-review-update.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+
+const MAX_COMPRESSED = 32 * 1024 * 1024;
+const MAX_EXPANDED = 128 * 1024 * 1024;
+const MAX_FILE = 32 * 1024 * 1024;
+const MAX_ENTRIES = 10_000;
+const BLOCK = 512;
+const decoder = new TextDecoder('utf-8', { fatal: true });
+
+function reject(message: string): never {
+  throw new Error(`NAVIGATION_UPDATE_ARTIFACT_INVALID: ${message}`);
+}
+
+function digest(bytes: Buffer): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function readRegular(file: string, maximum: number): Buffer {
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const before = fstatSync(descriptor);
+    if (!before.isFile() || before.size > maximum) reject('A required file is nonregular or exceeds its size limit.');
+    const bounded = Buffer.alloc(before.size + 1);
+    let length = 0;
+    while (length < bounded.length) {
+      const read = readSync(descriptor, bounded, length, bounded.length - length, null);
+      if (read === 0) break;
+      length += read;
+    }
+    const bytes = bounded.subarray(0, length);
+    const after = fstatSync(descriptor);
+    if (bytes.length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs
+      || after.ctimeMs !== before.ctimeMs) reject('A required file changed while being inspected.');
+    return bytes;
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+function textField(field: Buffer): string {
+  const nul = field.indexOf(0);
+  if (nul >= 0 && field.subarray(nul).some(byte => byte !== 0)) reject('Noncanonical tar string field.');
+  return decoder.decode(nul < 0 ? field : field.subarray(0, nul));
+}
+
+function octal(field: Buffer): number {
+  const value = field.toString('ascii').replace(/[\0 ]+$/g, '').trim();
+  if (value && !/^[0-7]+$/.test(value)) reject('Unsupported or invalid tar numeric field.');
+  const number = value ? Number.parseInt(value, 8) : 0;
+  if (!Number.isSafeInteger(number) || number < 0) reject('Tar numeric field exceeds the supported range.');
+  return number;
+}
+
+function safeName(name: string, directory: boolean): string {
+  const normalized = directory && name.endsWith('/') ? name.slice(0, -1) : name;
+  if (!normalized || normalized.length > 4096 || normalized.startsWith('/')
+    || /[\\\x00-\x1f\x7f]/.test(normalized)
+    || normalized.split('/').some(part => !part || part === '.' || part === '..')) {
+    reject('Tar entry has an unsafe or noncanonical path.');
+  }
+  return normalized;
+}
+
+function paxFields(bytes: Buffer): Record<string, string> {
+  if (bytes.length > 64 * 1024) reject('PAX metadata exceeds its size limit.');
+  const result: Record<string, string> = Object.create(null) as Record<string, string>;
+  let offset = 0;
+  while (offset < bytes.length) {
+    const space = bytes.indexOf(32, offset);
+    if (space < 0 || space - offset > 8) reject('Malformed PAX record length.');
+    const digits = bytes.subarray(offset, space).toString('ascii');
+    if (!/^[1-9][0-9]*$/.test(digits)) reject('Malformed PAX record length.');
+    const length = Number(digits);
+    const end = offset + length;
+    if (end > bytes.length || end <= space + 2 || bytes[end - 1] !== 10) reject('Truncated PAX record.');
+    const record = decoder.decode(bytes.subarray(space + 1, end - 1));
+    const separator = record.indexOf('=');
+    const key = record.slice(0, separator);
+    if (separator < 1 || !['path', 'size', 'mtime', 'atime', 'ctime', 'uid', 'gid', 'uname', 'gname', 'charset'].includes(key)
+      || Object.hasOwn(result, key)) reject('Unsupported or duplicate PAX metadata.');
+    result[key] = record.slice(separator + 1);
+    offset = end;
+  }
+  return result;
+}
+
+function unpack(bytes: Buffer): Map<string, Buffer> {
+  const files = new Map<string, Buffer>();
+  const names = new Set<string>();
+  let offset = 0;
+  let count = 0;
+  let pendingPax: Record<string, string> | null = null;
+  while (offset + BLOCK <= bytes.length) {
+    const header = bytes.subarray(offset, offset + BLOCK);
+    if (header.every(byte => byte === 0)) {
+      if (pendingPax || offset + 2 * BLOCK > bytes.length || bytes.subarray(offset).some(byte => byte !== 0)) {
+        reject('Tar end marker is incomplete or followed by unexpected data.');
+      }
+      return files;
+    }
+    if (++count > MAX_ENTRIES) reject('Tar entry count exceeds its limit.');
+    const expectedChecksum = octal(header.subarray(148, 156));
+    const checksum = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+    if (checksum !== expectedChecksum) reject('Tar header checksum does not match.');
+    if (textField(header.subarray(257, 263)).trim() !== 'ustar') reject('Only USTAR/PAX package archives are supported.');
+    const type = header[156];
+    if (![0, 48, 53, 120].includes(type!)) reject('Tar links, special files and unsupported metadata are forbidden.');
+    if (textField(header.subarray(157, 257))) reject('Tar link targets are forbidden.');
+    const prefix = textField(header.subarray(345, 500));
+    const baseName = textField(header.subarray(0, 100));
+    const headerName = safeName(prefix ? `${prefix}/${baseName}` : baseName, type === 53);
+    const size = octal(header.subarray(124, 136));
+    if (size > MAX_FILE) reject('Tar entry exceeds its size limit.');
+    const start = offset + BLOCK;
+    const end = start + size;
+    const paddedEnd = start + Math.ceil(size / BLOCK) * BLOCK;
+    if (paddedEnd > bytes.length) reject('Tar entry data is truncated.');
+    if (bytes.subarray(end, paddedEnd).some(byte => byte !== 0)) reject('Tar entry padding is not zero.');
+    offset = paddedEnd;
+    if (type === 120) {
+      if (pendingPax) reject('Consecutive PAX headers are ambiguous.');
+      pendingPax = paxFields(bytes.subarray(start, end));
+      continue;
+    }
+    const name = safeName(pendingPax?.path ?? headerName, type === 53);
+    if (pendingPax?.size !== undefined && (!/^(0|[1-9][0-9]*)$/.test(pendingPax.size)
+      || Number(pendingPax.size) !== size)) reject('PAX size does not match the bounded tar entry.');
+    pendingPax = null;
+    if (name !== 'package' && !name.startsWith('package/')) reject('Tar entries must stay under package/.');
+    if (names.has(name)) reject('Duplicate tar paths are forbidden.');
+    names.add(name);
+    if (type === 53) {
+      if (size !== 0) reject('Tar directory entries cannot contain data.');
+    } else {
+      if (name === 'package') reject('The package root must be a directory.');
+      files.set(name.slice('package/'.length), bytes.subarray(start, end));
+    }
+  }
+  reject('Tar archive is missing its complete end marker.');
+}
+
+/** Inspect an exact local package; no install, extraction, network or authority mutation. */
+export function verifyNavigationUpdateArtifact(tarball: string, installedPackageRoot?: string): { sha256: string; runtimeHash: string } {
+  try {
+    if (!tarball.trim()) reject('An explicit local tarball path is required.');
+    const compressed = readRegular(path.resolve(tarball), MAX_COMPRESSED);
+    if (compressed[0] !== 0x1f || compressed[1] !== 0x8b) reject('The artifact must be a gzip tarball.');
+    // Isolate synchronous decompression so a corrupt archive has an enforced deadline.
+    const expanded = execFileSync(process.execPath, ['--input-type=module', '--eval',
+      `import{readFileSync}from'node:fs';import{gunzipSync}from'node:zlib';process.stdout.write(gunzipSync(readFileSync(0),{maxOutputLength:${MAX_EXPANDED}}));`], {
+      input: compressed, timeout: 10_000, killSignal: 'SIGKILL', maxBuffer: MAX_EXPANDED + 1024,
+      stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, NODE_OPTIONS: '' },
+    });
+    if (expanded.length > MAX_EXPANDED) reject('Expanded tarball exceeds its size limit.');
+    const files = unpack(expanded);
+    const manifestBytes = files.get('package.json');
+    const buildBytes = files.get('dist/reviewer-runtime-build.json');
+    if (!manifestBytes || !buildBytes) reject('Package identity or runtime build evidence is missing.');
+    const pkg = JSON.parse(manifestBytes.toString('utf8')) as { name?: unknown; version?: unknown };
+    if (pkg.name !== PACKAGE_NAME || pkg.version !== PACKAGE_VERSION) reject('Tarball package/version differs from the running Workflow.');
+    const build = JSON.parse(buildBytes.toString('utf8')) as { files?: Array<{ path?: unknown }> };
+    if (!Array.isArray(build.files) || build.files.length === 0
+      || build.files.some(entry => typeof entry.path !== 'string' || !files.has(entry.path))
+      || !files.has('dist/src/navigation-update-artifact.js')) reject('The tarball omits required runtime files.');
+    const packageRoot = realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'));
+    if (installedPackageRoot !== undefined && !installedPackageRoot.trim()) reject('Installed package root must be explicit and nonempty.');
+    const roots = [
+      { root: packageRoot, label: 'running' },
+      ...(installedPackageRoot === undefined ? [] : [{ root: realpathSync(installedPackageRoot), label: 'installed' }]),
+    ];
+    for (const { root, label } of roots) {
+      for (const [relative, content] of files) {
+        let current = root;
+        const parts = relative.split('/');
+        for (let index = 0; index < parts.length; index++) {
+          current = path.join(current, parts[index]!);
+          const stat = lstatSync(current);
+          if (stat.isSymbolicLink() || (index < parts.length - 1 && !stat.isDirectory())) {
+            reject(`The ${label} package path is not a regular confined path: ${relative}`);
+          }
+        }
+        if (!readRegular(current, MAX_FILE).equals(content)) reject(`Tarball bytes differ from the ${label} package: ${relative}`);
+      }
+    }
+    const runtimeHash = pendingReviewRunnerFingerprint();
+    return { sha256: digest(compressed), runtimeHash };
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('NAVIGATION_UPDATE_ARTIFACT_INVALID:')) throw error;
+    reject(error instanceof Error ? error.message : 'Artifact inspection failed.');
+  }
+}

package/src/navigation-update.ts

@@ -0,0 +1,121 @@
+import { 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 { assessNavigationDirtyCarryover } from './alpha6/navigation-dirty-carryover.js';
+import { canonicalJsonStringify, sha256Hex } from './alpha6/store-sidecars.js';
+import { inspectBoundedWorkflowDependencyCommit } from './dependency-provenance.js';
+import { inspectWorkflowVersions } from './diagnostics.js';
+import { currentBranch, headCommit, runGit } from './repository.js';
+import { PACKAGE_VERSION } from './version.js';
+
+const SOURCE_VERSION: string = '2.0.0-beta.13.16';
+export interface NavigationUpdateReceipt {
+  protocol: 'navigation-update-source-v1';
+  issuedAt: string;
+  projectId: string;
+  taskId: string;
+  revision: number;
+  taskHash: string;
+  artifactsHash: string;
+  knowledgeHash: string;
+  milestoneHash: string | null;
+  taskBranch: string;
+  baseBranch: string;
+  sourceHead: string;
+  sourceBaseHead: string;
+  sourceVersion: string;
+  targetVersion: string;
+  artifact: { sha256: string; runtimeHash: string };
+  actor: string;
+  dirtyHash: string;
+}
+function require(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(`NAVIGATION_UPDATE_BLOCKED: ${message}`);
+}
+const hash = (value: unknown) => sha256Hex(canonicalJsonStringify(value));
+function hashFiles(root: string): string {
+  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(), 'Task artifacts must not contain symlinks.');
+    require(info.isDirectory() || info.isFile(), 'Task artifacts must be regular files or directories.');
+    return info.isDirectory() ? visit(file) : [[path.relative(root, file), sha256Hex(readFileSync(file))]];
+  });
+  return hash(visit(root));
+}
+function sourcePin(repository: string, commit: 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'] === SOURCE_VERSION
+    && !manifest.dependencies?.['codex-workflow-v2']
+    && lock.packages?.['']?.devDependencies?.['codex-workflow-v2'] === SOURCE_VERSION
+    && !lock.packages?.['']?.dependencies?.['codex-workflow-v2']
+    && lock.packages?.['node_modules/codex-workflow-v2']?.version === SOURCE_VERSION,
+  'Source manifest and lock must bind the exact supported source version.');
+}
+
+/** Recompute source proof even after transport. The virtual record classifies Git only;
+ * it neither writes state nor manufactures execution authority. */
+export function navigationUpdateSource(
+  repository: string, store: FileStateStore, task: TaskState,
+  artifact: NavigationUpdateReceipt['artifact'], issuedAt: string,
+  sourceHead = headCommit(repository), sourceBaseHead = runGit(repository, ['rev-parse', task.baseBranch]),
+): NavigationUpdateReceipt {
+  require(PACKAGE_VERSION !== SOURCE_VERSION, 'Target must differ from source.');
+  require(issuedAt === task.updatedAt && Number.isFinite(Date.parse(issuedAt)), 'Receipt timestamp must bind the stored Task update.');
+  require(task.taskBranch && currentBranch(repository) === task.taskBranch, 'Expected owned Task branch.');
+  sourcePin(repository, sourceHead); sourcePin(repository, sourceBaseHead);
+  const dependency = inspectBoundedWorkflowDependencyCommit(repository, sourceHead);
+  require(dependency?.packageVersion === SOURCE_VERSION && !task.systemCommits.includes(sourceHead),
+    'Source HEAD must be the one unregistered source dependency commit.');
+  require(runGit(repository, ['rev-list', '--parents', '-n', '1', sourceHead]).split(' ').length === 2,
+    'Source dependency commit must have one parent.');
+  const virtual: TaskState = { ...task, systemCommits: [...task.systemCommits, sourceHead],
+    dependencyProvenanceRecoveries: [...(task.dependencyProvenanceRecoveries ?? []), {
+      ...dependency, packageName: 'codex-workflow-v2', files: ['package-lock.json', 'package.json'],
+      actor: 'source-proof', reason: 'Read-only Git classification.', recordedAt: issuedAt,
+    }] };
+  const proof = assessNavigationDirtyCarryover(store, repository, virtual, undefined, sourceHead, sourceHead);
+  require(proof.eligible && proof.compatibility && proof.requiredActor, proof.blockers.join(' '));
+  return { protocol: 'navigation-update-source-v1', issuedAt, projectId: task.projectId, taskId: task.id,
+    revision: task.revision, taskHash: hash(task), artifactsHash: hashFiles(store.taskRoot(task.projectId, task.id)),
+    knowledgeHash: hash(store.readKnowledgeMap(task.projectId)),
+    milestoneHash: task.milestoneId ? hash(store.readMilestone(task.projectId, task.milestoneId)) : null,
+    taskBranch: task.taskBranch, baseBranch: task.baseBranch, sourceHead, sourceBaseHead,
+    sourceVersion: SOURCE_VERSION, targetVersion: PACKAGE_VERSION, artifact,
+    actor: proof.requiredActor, dirtyHash: proof.compatibility.dirtyWorktreeHash };
+}
+
+export function assertNavigationSourceInstalled(repository: string, task: TaskState): void {
+  const versions = inspectWorkflowVersions(repository, [task.baseBranch]);
+  require([versions.declared, versions.locked, versions.installed, versions.currentBranch,
+    ...versions.milestoneBases.map(base => base.version)].every(version => version === SOURCE_VERSION),
+  'All source version surfaces must agree before transport.');
+}
+
+export function inspectNavigationTransport(
+  repository: string, store: FileStateStore, task: TaskState, receipt: NavigationUpdateReceipt,
+  artifact: NavigationUpdateReceipt['artifact'], _now: Date,
+) {
+  require(receipt?.protocol === 'navigation-update-source-v1', 'Missing or foreign source receipt.');
+  const head = headCommit(repository);
+  const base = runGit(repository, ['rev-parse', task.baseBranch]);
+  const target = inspectBoundedWorkflowDependencyCommit(repository, head);
+  const baseTransport = inspectBoundedWorkflowDependencyCommit(repository, base);
+  require([head, base].every(commit => runGit(repository, ['rev-list', '--parents', '-n', '1', commit]).split(' ').length === 2),
+    'Transport commits must have one parent.');
+  require(target?.parentCommitSha === receipt.sourceHead && target?.packageVersion === PACKAGE_VERSION,
+    'Expected exactly one target dependency transport on the source HEAD.');
+  require(baseTransport?.parentCommitSha === receipt.sourceBaseHead && baseTransport?.packageVersion === PACKAGE_VERSION,
+    'Expected exactly one target dependency transport on the source base HEAD.');
+  const recomputed = navigationUpdateSource(repository, store, task, artifact, receipt.issuedAt,
+    target.parentCommitSha, baseTransport.parentCommitSha);
+  require(canonicalJsonStringify(receipt) === canonicalJsonStringify(recomputed),
+    'Receipt does not match independently recomputed source evidence, state or target artifact.');
+  const versions = inspectWorkflowVersions(repository, [task.baseBranch]);
+  require([versions.declared, versions.locked, versions.installed, versions.currentBranch,
+    ...versions.milestoneBases.map(item => item.version)].every(version => version === PACKAGE_VERSION),
+  'All installed target version surfaces must agree.');
+  const source = inspectBoundedWorkflowDependencyCommit(repository, receipt.sourceHead)!;
+  return { receipt: recomputed, commits: [source, target], baseTransport: base, targetHead: head };
+}

package/src/observation.ts

@@ -0,0 +1,225 @@
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import type {
+  AdoptionPostureEvent,
+  ObservationReasonCode,
+  ObservedMilestoneTransaction,
+  ObservedProjectTransaction,
+  PublicWriterLease,
+  ProjectRecord,
+  WorkflowObservation,
+  WriterLease,
+} from './contracts.js';
+import { readCurrentAdoptionPosture } from './alpha6/adoption.js';
+import { listMilestoneTransactionJournals } from './alpha6/journal.js';
+import { assertNoSymlinkPathComponents } from './alpha6/store-sidecars.js';
+import { listProjectTransactions } from './beta1/project-transaction.js';
+import type { RepositoryIdentity } from './repository.js';
+import {
+  listCoreTaskOperationMutexes,
+  listWriterLeases,
+  toPublicCoreTaskOperation,
+  toPublicWriterLease,
+} from './state/lock.js';
+import { inspectCorrectiveReplanTaskTransactions } from './state/corrective-replan-transaction.js';
+import { inspectCorrectiveYieldTaskTransactions } from './state/corrective-yield-transaction.js';
+import type { FileStateStore } from './state/store.js';
+
+export interface WorkflowObservationBoundary {
+  identity: RepositoryIdentity;
+  project: ProjectRecord | null;
+  currentAdoptionPosture: AdoptionPostureEvent | null;
+  leases: WriterLease[];
+  observation: WorkflowObservation;
+}
+
+/**
+ * Reads only the persistence boundary needed to decide whether a coherent lifecycle snapshot can
+ * be loaded. It deliberately does not register a project, recover a journal, initialize adoption,
+ * or construct a WriterLockManager.
+ */
+export function inspectWorkflowObservationBoundary(options: {
+  store: FileStateStore;
+  identity: RepositoryIdentity;
+  now: Date;
+}): WorkflowObservationBoundary {
+  const { store, identity, now } = options;
+  const projectRoot = store.projectRoot(identity.projectId);
+  const projectFile = path.join(projectRoot, 'project.json');
+  const lockRoot = store.lockRoot(identity.projectId);
+  const stateRootPresent = existsSync(store.root);
+  const projectRootPresent = existsSync(projectRoot);
+  const lockRootPresent = existsSync(lockRoot);
+  const missingRegistration = !existsSync(projectFile);
+  const pendingProjectTransactions = observeProjectTransactions(projectRoot, identity.projectId);
+  const pendingMilestoneTransactions = observeMilestoneTransactions(store, identity.projectId);
+  const replanTransactions = inspectCorrectiveReplanTaskTransactions(projectRoot, store.root);
+  const yieldTransactions = inspectCorrectiveYieldTaskTransactions(projectRoot, store.root);
+  const leases = listWriterLeases(lockRoot);
+  const coreTaskOperations = listCoreTaskOperationMutexes(lockRoot, store.root)
+    .map((mutex) => toPublicCoreTaskOperation(mutex, now));
+  const completedTaskTransactions = [...replanTransactions.completed, ...yieldTransactions.completed];
+  const retainedCompletedWithMutex = completedTaskTransactions
+    .filter(transaction => coreTaskOperations.some(operation =>
+      operation.entityId === transaction.taskId && operation.operationId === transaction.transactionId
+      && operation.transitionId === transaction.transitionId));
+  const taskTransactions = {
+    pending: [...replanTransactions.pending, ...yieldTransactions.pending, ...retainedCompletedWithMutex]
+      .sort((left, right) => left.taskId.localeCompare(right.taskId) || left.transactionId.localeCompare(right.transactionId)),
+    corrupt: [...replanTransactions.corrupt, ...yieldTransactions.corrupt]
+      .sort((left, right) => left.taskId.localeCompare(right.taskId) || left.transactionId.localeCompare(right.transactionId)),
+  };
+  // Recover one exact journal at a time; independent Tasks can interrupt different families.
+  const pendingTaskTransaction = taskTransactions.pending[0];
+  const orphanCoreTaskOperations = coreTaskOperations.filter((operation) => !taskTransactions.pending.some(
+    (transaction) => transaction.taskId === operation.entityId && transaction.transactionId === operation.operationId
+      && transaction.transitionId === operation.transitionId,
+  ));
+
+  const activeTaskRecoveryOwner = coreTaskOperations.some(operation => !operation.stale)
+    || taskTransactions.pending.some(transaction => leases.some(lease =>
+      lease.entityId === transaction.taskId && Date.parse(lease.expiresAt) > now.getTime()));
+  const staleOrphanCoreOperations = orphanCoreTaskOperations.filter(operation => operation.stale);
+  const conflictsWithRetainedJournal = (operation: typeof coreTaskOperations[number]) =>
+    taskTransactions.pending.some(transaction => transaction.taskId === operation.entityId)
+    || completedTaskTransactions.some(transaction => transaction.taskId === operation.entityId
+      && transaction.transactionId === operation.operationId);
+  const conflictingOrphanCoreOperations = staleOrphanCoreOperations.filter(conflictsWithRetainedJournal);
+  const repairableOrphanCoreOperation = staleOrphanCoreOperations.find(operation => !conflictsWithRetainedJournal(operation));
+
+  const project = !missingRegistration && pendingProjectTransactions.length === 0
+    ? store.readProject(identity.projectId)
+    : null;
+  const repositoryRootBound = project?.repositoryRoots.includes(identity.repositoryRoot) ?? false;
+  const adoptionAssessed = pendingProjectTransactions.length === 0
+    && pendingMilestoneTransactions.length === 0
+    && taskTransactions.pending.length === 0
+    && taskTransactions.corrupt.length === 0
+    && orphanCoreTaskOperations.length === 0;
+  const currentAdoptionPosture = adoptionAssessed && stateRootPresent
+    ? readCurrentAdoptionPosture(store, identity.projectId)
+    : null;
+  const missingAdoption = adoptionAssessed && currentAdoptionPosture === null;
+  const observedLeases = leases.map((lease) => toPublicWriterLease(lease, now));
+  const activeLeases = observedLeases.filter((lease) => !lease.stale);
+  const staleLeases = observedLeases.filter((lease) => lease.stale);
+
+  const reasonCodes: ObservationReasonCode[] = [];
+  if (missingRegistration) reasonCodes.push('PROJECT_REGISTRATION_MISSING');
+  if (project && !repositoryRootBound) reasonCodes.push('PROJECT_REPOSITORY_ROOT_UNBOUND');
+  if (pendingProjectTransactions.length > 0) reasonCodes.push('PROJECT_RECOVERY_REQUIRED');
+  if (pendingMilestoneTransactions.length > 0) reasonCodes.push('MILESTONE_RECOVERY_REQUIRED');
+  if (taskTransactions.pending.length > 0) reasonCodes.push('TASK_RECOVERY_REQUIRED');
+  if (taskTransactions.corrupt.length > 0) reasonCodes.push('TASK_TRANSACTION_INTEGRITY_FAILED');
+  if (activeTaskRecoveryOwner) reasonCodes.push('TASK_OPERATION_IN_PROGRESS');
+  if (orphanCoreTaskOperations.some((operation) => operation.stale)) reasonCodes.push('STALE_TASK_OPERATION');
+  if (activeLeases.length > 0) reasonCodes.push('ACTIVE_WRITER_LEASE');
+  if (staleLeases.length > 0) reasonCodes.push('STALE_WRITER_LEASE');
+  if (missingAdoption) reasonCodes.push('ADOPTION_MISSING');
+
+  const blocked = missingRegistration
+    || (project !== null && !repositoryRootBound)
+    || pendingProjectTransactions.some(transaction => transaction.ownerActive)
+    || taskTransactions.corrupt.length > 0
+    || activeTaskRecoveryOwner
+    || conflictingOrphanCoreOperations.length > 0;
+  const repairable = repairableOrphanCoreOperation !== undefined
+    || pendingProjectTransactions.length > 0
+    || taskTransactions.pending.length > 0
+    || pendingMilestoneTransactions.length > 0;
+  const kind: WorkflowObservation['kind'] = blocked ? 'blocked' : repairable ? 'repair' : 'assessment';
+  const repair = kind !== 'repair'
+    ? null
+    : repairableOrphanCoreOperation
+      ? {
+          command: 'locks repair' as const,
+          cataloged: false as const,
+          projectId: identity.projectId,
+          entityIds: [repairableOrphanCoreOperation.entityId],
+        }
+    : taskTransactions.pending.length > 0
+      ? {
+          command: pendingTaskTransaction!.transitionId === 'task.coordination.corrective-yield'
+            ? 'task corrective-yield-recover' as const
+            : 'task corrective-replan-recover' as const,
+          cataloged: false as const,
+          available: true as const,
+          projectId: identity.projectId,
+          taskIds: [pendingTaskTransaction!.taskId],
+          transactionIds: [pendingTaskTransaction!.transactionId],
+        }
+      : pendingMilestoneTransactions.length > 0 || pendingProjectTransactions.length > 0
+      ? {
+          command: 'milestone recover' as const,
+          cataloged: false as const,
+          projectId: identity.projectId,
+          milestoneIds: [...new Set(pendingMilestoneTransactions.map((transaction) => transaction.milestoneId))].sort(),
+          transactionIds: [...pendingProjectTransactions, ...pendingMilestoneTransactions]
+            .map((transaction) => transaction.transactionId).sort(),
+        }
+      : {
+          command: 'locks repair' as const,
+          cataloged: false as const,
+          projectId: identity.projectId,
+          entityIds: staleLeases.map((lease) => lease.entityId).sort(),
+        };
+
+  return {
+    identity,
+    project,
+    currentAdoptionPosture,
+    leases,
+    observation: {
+      kind,
+      reasonCodes,
+      stateRootPresent,
+      projectRootPresent,
+      lockRootPresent,
+      missingRegistration,
+      repositoryRootBound,
+      adoptionAssessed,
+      missingAdoption,
+      pendingProjectTransactions,
+      pendingMilestoneTransactions,
+      pendingTaskTransactions: taskTransactions.pending,
+      corruptTaskTransactions: taskTransactions.corrupt,
+      coreTaskOperations,
+      leases: observedLeases,
+      availableRepairTransitionId: null,
+      repair,
+    },
+  };
+}
+
+function observeProjectTransactions(projectRoot: string, projectId: string): ObservedProjectTransaction[] {
+  return listProjectTransactions(projectRoot, projectId)
+    .map((transaction) => ({ ...transaction }))
+    .sort((left, right) => left.preparedAt.localeCompare(right.preparedAt)
+      || left.transactionId.localeCompare(right.transactionId));
+}
+
+function observeMilestoneTransactions(
+  store: FileStateStore,
+  projectId: string,
+): ObservedMilestoneTransaction[] {
+  const milestonesRoot = path.join(store.projectRoot(projectId), 'milestones');
+  if (!existsSync(milestonesRoot)) return [];
+  assertNoSymlinkPathComponents(milestonesRoot, {
+    label: 'Milestones observation root',
+    requireLeaf: true,
+    trustedRoot: store.root,
+  });
+  return readdirSync(milestonesRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .flatMap((entry) => listMilestoneTransactionJournals(realpathSync(path.join(milestonesRoot, entry.name)), {
+      expectedMilestoneId: entry.name,
+    }).map((journal) => ({
+      milestoneId: journal.milestoneId,
+      transactionId: journal.transactionId,
+      phase: journal.phase,
+      preparedAt: journal.preparedAt,
+      updatedAt: journal.updatedAt,
+    })))
+    .sort((left, right) => left.preparedAt.localeCompare(right.preparedAt)
+      || left.transactionId.localeCompare(right.transactionId));
+}