@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/control-plane/dispatch-priority.ts

@@ -0,0 +1,67 @@
+import type {
+  ExecutionJob,
+  ExecutionJobPriority,
+  ExecutionJobStatus,
+} from '../execution/jobs/types';
+
+const PRIORITY_WEIGHT: Record<ExecutionJobPriority, number> = {
+  P0: 0,
+  P1: 1,
+  P2: 2,
+  P3: 3,
+  P4: 4,
+};
+
+const DISPATCHABLE_JOB_STATUSES = new Set<ExecutionJobStatus>([
+  'queued',
+  'waiting_for_dependency',
+  'waiting_for_workspace',
+  'waiting_for_heavy_check',
+  'waiting_for_integration',
+  'waiting_for_release_barrier',
+]);
+
+export const PRIORITY_AGING_WINDOW_MS = 30 * 60_000;
+
+export type DispatchPriorityCandidate = Pick<ExecutionJob, 'priority' | 'queuedAt' | 'createdAt' | 'jobId'>;
+
+export interface ExecutionJobDispatchRank {
+  effectivePriority: number;
+  queuedAtMs: number;
+  jobId: string;
+}
+
+function parseTimestamp(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function isExecutionJobDispatchCandidate(job: Pick<ExecutionJob, 'status'>): boolean {
+  return DISPATCHABLE_JOB_STATUSES.has(job.status);
+}
+
+export function rankExecutionJobForDispatch(
+  job: DispatchPriorityCandidate,
+  scheduleNow: number,
+): ExecutionJobDispatchRank {
+  const queuedAtMs = parseTimestamp(job.queuedAt)
+    ?? parseTimestamp(job.createdAt)
+    ?? scheduleNow;
+  const age = Math.max(0, scheduleNow - queuedAtMs);
+  const promotions = Math.floor(age / PRIORITY_AGING_WINDOW_MS);
+  return {
+    effectivePriority: Math.max(0, PRIORITY_WEIGHT[job.priority] - promotions),
+    queuedAtMs,
+    jobId: job.jobId,
+  };
+}
+
+export function compareExecutionJobDispatchRanks(
+  left: ExecutionJobDispatchRank,
+  right: ExecutionJobDispatchRank,
+): number {
+  return left.effectivePriority - right.effectivePriority
+    || left.queuedAtMs - right.queuedAtMs
+    || left.jobId.localeCompare(right.jobId);
+}

package/src/runtime/control-plane/execution/direct-edit-work-completion.ts

@@ -0,0 +1,151 @@
+import { createHash } from 'crypto';
+import { getEditSession, listEditSessions, type EditSession } from '../../../cli/editing/edit-session';
+import { runProcess } from '../../../effects/process-runner';
+import { getWorkContract, recordWorkCompletionReceipt } from '../facade/work-contract-store';
+import { isTerminalWorkContractStatus, type DirectEditWorkCompletionReceipt } from '../facade/types';
+
+export interface DirectEditWorkCompletionReconciliation {
+  completedWorkIds: string[];
+  examinedSessionIds: string[];
+  skipped: Array<{ sessionId: string; workId?: string; reason: string }>;
+  targetBranch?: string;
+  targetRevision?: string;
+}
+
+function git(repoRoot: string, args: string[]): { ok: boolean; stdout: string; stderr: string } {
+  const result = runProcess('git', args, { cwd: repoRoot, timeoutMs: 10_000, maxOutputBytes: 4 * 1024 * 1024 });
+  return { ok: result.ok, stdout: result.stdout, stderr: result.stderr || result.error || '' };
+}
+
+function changedPaths(session: EditSession): string[] {
+  return Array.from(new Set(session.operations.map((operation) => operation.path).filter(Boolean)))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function latestOperations(session: EditSession): Map<string, EditSession['operations'][number]> {
+  const latest = new Map<string, EditSession['operations'][number]>();
+  for (const operation of session.operations) latest.set(operation.path, operation);
+  return latest;
+}
+
+function revisionMismatches(repoRoot: string, revision: string, session: EditSession): string[] {
+  const mismatches: string[] = [];
+  for (const operation of latestOperations(session).values()) {
+    const object = `${revision}:${operation.path}`;
+    if (operation.type === 'delete') {
+      if (git(repoRoot, ['cat-file', '-e', object]).ok) mismatches.push(operation.path);
+      continue;
+    }
+    const content = git(repoRoot, ['show', object]);
+    if (!content.ok || !operation.afterSha256 || createHash('sha256').update(content.stdout).digest('hex') !== operation.afterSha256) {
+      mismatches.push(operation.path);
+    }
+  }
+  return mismatches;
+}
+
+function requestedChecksPassed(session: EditSession): boolean {
+  return session.requestedChecks.every((checkId) => session.checkResults.some((result) => result.checkId === checkId && result.ok));
+}
+
+export function reconcileFinalizedDirectEditWorksAfterCommit(input: {
+  controllerHome: string;
+  repoId: string;
+  checkoutId: string;
+  repoRoot: string;
+  committedPaths: string[];
+  fallbackBranch?: string;
+  limit?: number;
+}): DirectEditWorkCompletionReconciliation {
+  const committedPathSet = new Set(input.committedPaths);
+  const targetRevisionResult = git(input.repoRoot, ['rev-parse', '--verify', 'HEAD']);
+  if (!targetRevisionResult.ok) {
+    return { completedWorkIds: [], examinedSessionIds: [], skipped: [], targetRevision: undefined, targetBranch: undefined };
+  }
+  const targetRevision = targetRevisionResult.stdout.trim();
+  const branchResult = git(input.repoRoot, ['branch', '--show-current']);
+  const targetBranch = branchResult.ok && branchResult.stdout.trim()
+    ? branchResult.stdout.trim()
+    : input.fallbackBranch?.trim();
+  if (!targetBranch) {
+    return { completedWorkIds: [], examinedSessionIds: [], skipped: [], targetRevision, targetBranch: undefined };
+  }
+  const reachable = git(input.repoRoot, ['merge-base', '--is-ancestor', targetRevision, targetBranch]).ok;
+  if (!reachable) {
+    return { completedWorkIds: [], examinedSessionIds: [], skipped: [], targetRevision, targetBranch };
+  }
+
+  const completedWorkIds: string[] = [];
+  const examinedSessionIds: string[] = [];
+  const skipped: DirectEditWorkCompletionReconciliation['skipped'] = [];
+  const summaries = listEditSessions(input.repoRoot, input.limit ?? 200);
+  for (const summary of summaries) {
+    const session = getEditSession(input.repoRoot, summary.sessionId);
+    if (session.status !== 'finalized' || !session.workId) continue;
+    if (session.repoId && session.repoId !== input.repoId) continue;
+    if (session.checkoutId && session.checkoutId !== input.checkoutId) continue;
+    const paths = changedPaths(session);
+    if (paths.length === 0 || !paths.every((path) => committedPathSet.has(path))) continue;
+    examinedSessionIds.push(session.sessionId);
+
+    const work = getWorkContract({ controllerHome: input.controllerHome, repoId: input.repoId }, session.workId);
+    if (!work) {
+      skipped.push({ sessionId: session.sessionId, workId: session.workId, reason: 'work_not_found' });
+      continue;
+    }
+    if (isTerminalWorkContractStatus(work.status)) continue;
+    if (!requestedChecksPassed(session)) {
+      skipped.push({ sessionId: session.sessionId, workId: session.workId, reason: 'configured_checks_not_passed' });
+      continue;
+    }
+    const status = git(input.repoRoot, ['status', '--porcelain=v1', '--', ...paths]);
+    if (!status.ok || status.stdout.trim()) {
+      skipped.push({ sessionId: session.sessionId, workId: session.workId, reason: 'owned_paths_not_clean' });
+      continue;
+    }
+    const mismatches = revisionMismatches(input.repoRoot, targetRevision, session);
+    if (mismatches.length > 0) {
+      skipped.push({ sessionId: session.sessionId, workId: session.workId, reason: `revision_mismatch:${mismatches.join(',')}` });
+      continue;
+    }
+
+    const recordedAt = new Date().toISOString();
+    const receipt: DirectEditWorkCompletionReceipt = {
+      schemaVersion: 1,
+      receiptId: `REC-direct-edit-work-${createHash('sha256').update(`${input.repoId}\0${session.workId}\0${session.sessionId}\0${targetRevision}`).digest('hex').slice(0, 20)}`,
+      source: 'direct_edit_work',
+      workId: session.workId,
+      editSessionId: session.sessionId,
+      targetBranch,
+      targetRevision,
+      sourceRevision: targetRevision,
+      baseRevision: session.baseRevision,
+      changedPaths: paths,
+      delivery: {
+        kind: 'commit',
+        status: 'integrated',
+        strategy: 'edit_session_commit',
+        reachable: true,
+        recordedAt,
+      },
+      cleanup: {
+        status: 'complete',
+        warnings: [],
+        blockers: [],
+        recordedAt,
+      },
+      verifiedAt: session.verifiedAt ?? session.finalizedAt ?? recordedAt,
+      recordedAt,
+    };
+    recordWorkCompletionReceipt(
+      { controllerHome: input.controllerHome, repoId: input.repoId },
+      session.workId,
+      receipt,
+      'completed_changed',
+      'repository_change',
+    );
+    completedWorkIds.push(session.workId);
+  }
+
+  return { completedWorkIds, examinedSessionIds, skipped, targetBranch, targetRevision };
+}

package/src/runtime/control-plane/execution/execution-identity.ts

@@ -0,0 +1,456 @@
+import { spawnSync } from 'child_process';
+import { existsSync, realpathSync, statSync } from 'fs';
+import { isAbsolute, relative, resolve } from 'path';
+import {
+  getRepository,
+  selectRepositoryCheckout,
+} from '../../../cli/repositories/registry';
+import { resolveGitExecutable } from '../../../effects/git-executable';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import type { WorkHandleState } from './work-handle-store';
+
+export type ExecutionIdentityErrorCode =
+  | 'EXECUTION_IDENTITY_MISMATCH'
+  | 'EXECUTION_IDENTITY_REQUIRED'
+  | 'CHECKOUT_ROUTE_MISMATCH'
+  | 'CHECKOUT_NOT_REGISTERED'
+  | 'CHECKOUT_NOT_ACTIVE'
+  | 'WORK_HANDLE_CHECKOUT_DRIFT'
+  | 'WORK_HANDLE_BRANCH_CHANGED'
+  | 'WORK_HANDLE_HEAD_CHANGED'
+  | 'GIT_TOPLEVEL_MISMATCH'
+  | 'GIT_COMMON_DIR_MISMATCH'
+  | 'WORKTREE_MISSING'
+  | 'WORKTREE_PATH_MISMATCH'
+  | 'REPOSITORY_NOT_EXECUTABLE'
+  | 'LEGACY_WORK_IDENTITY_AMBIGUOUS'
+  | 'LEGACY_WORK_IDENTITY_REJECTED'
+  | 'WORKSPACE_SCOPE_MISMATCH';
+
+export interface ResolvedExecutionIdentity {
+  readonly schemaVersion: 1;
+  readonly authority?: 'repository' | 'ephemeral_workspace';
+  readonly repositoryId: string;
+  readonly checkoutId: string;
+  readonly canonicalRoot: string;
+  readonly workId?: string;
+  readonly worktreePath?: string;
+  readonly branch?: string;
+  readonly expectedHead?: string;
+  readonly allowArchived?: boolean;
+}
+
+export interface GuardedExecutionIdentity extends ResolvedExecutionIdentity {
+  readonly resolvedCwd: string;
+  readonly gitTopLevel?: string;
+  readonly gitCommonDirectory?: string;
+  readonly currentBranch?: string;
+  readonly currentHead?: string;
+}
+
+export type GitCommonDirectoryDriftKind =
+  | 'missing_actual_common_dir'
+  | 'missing_registered_checkout_common_dir'
+  | 'missing_repository_common_dir'
+  | 'registered_checkout_common_dir_drift'
+  | 'repository_common_dir_drift';
+
+export interface GitCommonDirectoryDriftEvidence {
+  readonly kind: GitCommonDirectoryDriftKind;
+  readonly repoId: string;
+  readonly checkoutId: string;
+  readonly actualCommonDirectory?: string;
+  readonly registeredCheckoutCommonDirectory?: string;
+  readonly repositoryCommonDirectory?: string;
+  readonly registeredRoot: string;
+  readonly identityRoot: string;
+  readonly resolvedCwd: string;
+  readonly safeAutomaticRepair: boolean;
+}
+
+export class ExecutionIdentityError extends Error {
+  readonly code: ExecutionIdentityErrorCode;
+  readonly details: Record<string, string | undefined>;
+
+  constructor(code: ExecutionIdentityErrorCode, message: string, details: Record<string, string | undefined> = {}) {
+    const summary = Object.entries(details)
+      .filter(([, value]) => value !== undefined && value !== '')
+      .map(([key, value]) => `${key}=${value}`)
+      .join(' ');
+    super(summary ? `${code}: ${message} (${summary})` : `${code}: ${message}`);
+    this.name = 'ExecutionIdentityError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function fail(
+  code: ExecutionIdentityErrorCode,
+  message: string,
+  details: Record<string, string | undefined> = {},
+): never {
+  throw new ExecutionIdentityError(code, message, details);
+}
+
+function comparablePath(value: string): string {
+  const normalized = value.replace(/\\/g, '/').replace(/\/$/, '');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+function samePath(left: string, right: string): boolean {
+  return comparablePath(left) === comparablePath(right);
+}
+
+function realpathOrFail(path: string, code: ExecutionIdentityErrorCode, label: string): string {
+  if (!existsSync(path)) fail(code, `${label} does not exist`, { path });
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    fail(code, `${label} cannot be resolved`, {
+      path,
+      reason: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function gitText(root: string, args: string[]): string | undefined {
+  const result = spawnSync(resolveGitExecutable(), ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 10_000,
+  });
+  return result.status === 0 && typeof result.stdout === 'string' && result.stdout.trim()
+    ? result.stdout.trim()
+    : undefined;
+}
+
+function gitPath(root: string, args: string[]): string | undefined {
+  const value = gitText(root, args);
+  if (!value) return undefined;
+  try {
+    return realpathSync(isAbsolute(value) ? value : resolve(root, value));
+  } catch {
+    return undefined;
+  }
+}
+
+export function classifyGitCommonDirectoryDrift(input: {
+  repoId: string;
+  checkoutId: string;
+  actualCommonDirectory?: string;
+  registeredCheckoutCommonDirectory?: string;
+  repositoryCommonDirectory?: string;
+  registeredRoot: string;
+  identityRoot: string;
+  resolvedCwd: string;
+}): GitCommonDirectoryDriftEvidence | undefined {
+  const { actualCommonDirectory, registeredCheckoutCommonDirectory, repositoryCommonDirectory } = input;
+  if (!actualCommonDirectory) return { ...input, kind: 'missing_actual_common_dir', safeAutomaticRepair: false };
+  if (!registeredCheckoutCommonDirectory) return { ...input, kind: 'missing_registered_checkout_common_dir', safeAutomaticRepair: false };
+  if (!repositoryCommonDirectory) return { ...input, kind: 'missing_repository_common_dir', safeAutomaticRepair: false };
+  if (!samePath(actualCommonDirectory, registeredCheckoutCommonDirectory)) {
+    return { ...input, kind: 'registered_checkout_common_dir_drift', safeAutomaticRepair: false };
+  }
+  if (!samePath(actualCommonDirectory, repositoryCommonDirectory)) {
+    return { ...input, kind: 'repository_common_dir_drift', safeAutomaticRepair: false };
+  }
+  return undefined;
+}
+
+export function executionIdentityForRepository(
+  repository: RepositoryRecord,
+  patch: Partial<Pick<ResolvedExecutionIdentity, 'workId' | 'worktreePath' | 'branch' | 'expectedHead' | 'allowArchived'>> = {},
+): ResolvedExecutionIdentity {
+  return Object.freeze({
+    schemaVersion: 1 as const,
+    repositoryId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+    canonicalRoot: repository.canonicalRoot,
+    ...patch,
+  });
+}
+
+export function executionIdentityForWork(
+  repository: RepositoryRecord,
+  handle: WorkHandleState,
+): ResolvedExecutionIdentity {
+  if (repository.repoId !== handle.repositoryId) {
+    fail('EXECUTION_IDENTITY_MISMATCH', 'validated repository does not match WorkHandle', {
+      expectedRepoId: handle.repositoryId,
+      actualRepoId: repository.repoId,
+      workId: handle.workId,
+    });
+  }
+
+  // Once a Work exists, its immutable coordinates are the execution authority.
+  // Repository.activeCheckoutId/canonicalRoot are mutable UI/session projection
+  // fields and must never veto or rewrite an explicit Work-bound invocation.
+  return Object.freeze({
+    schemaVersion: 1 as const,
+    repositoryId: handle.repositoryId,
+    checkoutId: handle.checkoutId,
+    canonicalRoot: handle.worktreePath,
+    workId: handle.workId,
+    worktreePath: handle.worktreePath,
+    branch: handle.branch,
+    expectedHead: handle.expectedHead,
+  });
+}
+
+export function executionIdentityFromCoordinates(input: {
+  repositoryId: string;
+  checkoutId: string;
+  canonicalRoot: string;
+  workId?: string;
+  worktreePath?: string;
+  branch?: string;
+  expectedHead?: string;
+  allowArchived?: boolean;
+  authority?: 'repository' | 'ephemeral_workspace';
+}): ResolvedExecutionIdentity {
+  if (!input.repositoryId.trim() || !input.checkoutId.trim() || !input.canonicalRoot.trim()) {
+    fail('EXECUTION_IDENTITY_REQUIRED', 'repositoryId, checkoutId, and canonicalRoot are required');
+  }
+  return Object.freeze({ schemaVersion: 1 as const, ...input });
+}
+
+/**
+ * Resolve legacy WorkContract identity only through a unique exact WorkHandle match.
+ * Ambiguous or incomplete identity fails closed — never falls back to Session/main.
+ */
+export function resolveLegacyWorkContractIdentity(input: {
+  workId: string;
+  repoId?: string;
+  checkoutId?: string;
+  canonicalRoot?: string;
+  branch?: string;
+  head?: string;
+  candidates: readonly WorkHandleState[];
+}): WorkHandleState {
+  const exact = input.candidates.filter((handle) => {
+    if (handle.workId !== input.workId) return false;
+    if (input.repoId && handle.repositoryId !== input.repoId) return false;
+    if (input.checkoutId && handle.checkoutId !== input.checkoutId) return false;
+    if (input.canonicalRoot) {
+      try {
+        if (!samePath(realpathSync(handle.worktreePath), realpathSync(input.canonicalRoot))) return false;
+      } catch {
+        return false;
+      }
+    }
+    if (input.branch && handle.branch !== input.branch) return false;
+    if (input.head && handle.expectedHead && handle.expectedHead !== input.head) return false;
+    return true;
+  });
+  if (exact.length === 1) return exact[0];
+  if (exact.length > 1) {
+    fail('LEGACY_WORK_IDENTITY_AMBIGUOUS', 'legacy WorkContract matches multiple WorkHandles', {
+      workId: input.workId,
+      repoId: input.repoId,
+      checkoutId: input.checkoutId,
+      matchCount: String(exact.length),
+    });
+  }
+  fail('LEGACY_WORK_IDENTITY_REJECTED', 'legacy WorkContract has no unique exact WorkHandle match', {
+    workId: input.workId,
+    repoId: input.repoId,
+    checkoutId: input.checkoutId,
+    candidateCount: String(input.candidates.length),
+  });
+}
+
+export function assertExecutionIdentity(input: {
+  controllerHome: string;
+  identity: ResolvedExecutionIdentity;
+  cwd: string;
+  requestedRepoId?: string;
+  requestedCheckoutId?: string;
+}): GuardedExecutionIdentity {
+  const { identity } = input;
+  if (input.requestedRepoId && input.requestedRepoId !== identity.repositoryId) {
+    fail('EXECUTION_IDENTITY_MISMATCH', 'requested repository differs from execution identity', {
+      expectedRepoId: identity.repositoryId,
+      actualRepoId: input.requestedRepoId,
+      checkoutId: identity.checkoutId,
+      workId: identity.workId,
+    });
+  }
+  if (input.requestedCheckoutId && input.requestedCheckoutId !== identity.checkoutId) {
+    fail('CHECKOUT_ROUTE_MISMATCH', 'requested checkout differs from execution identity', {
+      expectedCheckoutId: identity.checkoutId,
+      actualCheckoutId: input.requestedCheckoutId,
+      repoId: identity.repositoryId,
+      workId: identity.workId,
+    });
+  }
+
+  if (identity.authority === 'ephemeral_workspace') {
+    const workspaceRoot = realpathOrFail(identity.canonicalRoot, 'WORKTREE_MISSING', 'ephemeral workspace root');
+    const requestedCwd = isAbsolute(input.cwd) ? input.cwd : resolve(workspaceRoot, input.cwd);
+    const resolvedCwd = realpathOrFail(requestedCwd, 'WORKTREE_MISSING', 'process cwd');
+    if (!statSync(resolvedCwd).isDirectory()) {
+      fail('WORKSPACE_SCOPE_MISMATCH', 'process cwd is not a directory', {
+        repoId: identity.repositoryId,
+        checkoutId: identity.checkoutId,
+        actual: resolvedCwd,
+      });
+    }
+    const cwdRelative = relative(workspaceRoot, resolvedCwd);
+    if (cwdRelative === '..' || cwdRelative.startsWith('../') || cwdRelative.startsWith('..\\')) {
+      fail('WORKSPACE_SCOPE_MISMATCH', 'process cwd escapes ephemeral workspace root', {
+        repoId: identity.repositoryId,
+        checkoutId: identity.checkoutId,
+        expected: workspaceRoot,
+        actual: resolvedCwd,
+      });
+    }
+    const gitTopLevel = gitPath(resolvedCwd, ['rev-parse', '--show-toplevel']);
+    const gitCommonDirectory = gitPath(resolvedCwd, ['rev-parse', '--git-common-dir']);
+    const currentBranch = gitTopLevel ? gitText(gitTopLevel, ['branch', '--show-current']) : undefined;
+    const currentHead = gitTopLevel ? gitText(gitTopLevel, ['rev-parse', '--verify', 'HEAD']) : undefined;
+    return Object.freeze({
+      ...identity,
+      canonicalRoot: workspaceRoot,
+      resolvedCwd,
+      gitTopLevel,
+      gitCommonDirectory,
+      currentBranch,
+      currentHead,
+    });
+  }
+
+  const registered = getRepository(identity.repositoryId, input.controllerHome, { includeRemoved: true });
+  if (registered.removedAt || registered.enabled === false) {
+    fail('REPOSITORY_NOT_EXECUTABLE', `repository ${identity.repositoryId} is disabled or removed`, {
+      repoId: identity.repositoryId,
+    });
+  }
+  const checkout = registered.checkouts.find((entry) => entry.checkoutId === identity.checkoutId);
+  if (!checkout) {
+    fail('CHECKOUT_NOT_REGISTERED', 'checkout is not registered on the repository', {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+    });
+  }
+  const lifecycle = checkout.lifecycle ?? 'active';
+  if (lifecycle !== 'active' && !(identity.allowArchived && lifecycle === 'archived')) {
+    fail('CHECKOUT_NOT_ACTIVE', `checkout is ${lifecycle}`, {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+      lifecycle,
+    });
+  }
+  const selected = selectRepositoryCheckout(registered, identity.checkoutId, {
+    allowArchived: identity.allowArchived === true,
+  });
+  const registeredRoot = realpathOrFail(selected.canonicalRoot, 'WORKTREE_MISSING', 'registered checkout root');
+  const identityRoot = realpathOrFail(identity.canonicalRoot, 'WORKTREE_MISSING', 'execution identity root');
+  if (!samePath(registeredRoot, identityRoot)) {
+    fail('CHECKOUT_ROUTE_MISMATCH', 'identity root differs from registered checkout', {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+      expected: registeredRoot,
+      actual: identityRoot,
+    });
+  }
+  if (identity.worktreePath) {
+    const worktreePath = realpathOrFail(identity.worktreePath, 'WORKTREE_MISSING', 'WorkHandle worktree');
+    if (!samePath(worktreePath, registeredRoot)) {
+      fail('WORKTREE_PATH_MISMATCH', 'WorkHandle path differs from registered checkout', {
+        repoId: identity.repositoryId,
+        checkoutId: identity.checkoutId,
+        expected: registeredRoot,
+        actual: worktreePath,
+        workId: identity.workId,
+      });
+    }
+  }
+  const requestedCwd = isAbsolute(input.cwd) ? input.cwd : resolve(registeredRoot, input.cwd);
+  const resolvedCwd = realpathOrFail(requestedCwd, 'WORKTREE_MISSING', 'process cwd');
+  const cwdRelative = relative(registeredRoot, resolvedCwd);
+  if (cwdRelative === '..' || cwdRelative.startsWith('../') || cwdRelative.startsWith('..\\')) {
+    fail('CHECKOUT_ROUTE_MISMATCH', 'process cwd escapes checkout root', {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+      expected: registeredRoot,
+      actual: resolvedCwd,
+    });
+  }
+
+  const gitTopLevel = gitPath(resolvedCwd, ['rev-parse', '--show-toplevel']);
+  if (!gitTopLevel || !samePath(gitTopLevel, registeredRoot)) {
+    fail('GIT_TOPLEVEL_MISMATCH', 'Git top-level differs from expected checkout root', {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+      expected: registeredRoot,
+      actual: gitTopLevel ?? 'missing',
+    });
+  }
+
+  const gitCommonDirectory = gitPath(resolvedCwd, ['rev-parse', '--git-common-dir']);
+  const registeredCommonDirectory = gitPath(registeredRoot, ['rev-parse', '--git-common-dir']);
+  const repositoryCommonDirectory = gitPath(registered.canonicalRoot, ['rev-parse', '--git-common-dir']);
+  const commonDirectoryDrift = classifyGitCommonDirectoryDrift({
+    repoId: identity.repositoryId,
+    checkoutId: identity.checkoutId,
+    actualCommonDirectory: gitCommonDirectory,
+    registeredCheckoutCommonDirectory: registeredCommonDirectory,
+    repositoryCommonDirectory,
+    registeredRoot,
+    identityRoot,
+    resolvedCwd,
+  });
+  if (commonDirectoryDrift) {
+    fail('GIT_COMMON_DIR_MISMATCH', 'Git common directory does not match registered repository ownership; quarantine or audited reconciliation is required', {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+      driftKind: commonDirectoryDrift.kind,
+      expected: repositoryCommonDirectory ?? 'missing',
+      registeredCheckoutCommonDirectory: registeredCommonDirectory ?? 'missing',
+      actual: gitCommonDirectory ?? 'missing',
+      registeredRoot,
+      identityRoot,
+      resolvedCwd,
+      safeAutomaticRepair: String(commonDirectoryDrift.safeAutomaticRepair),
+    });
+  }
+  const verifiedGitCommonDirectory = gitCommonDirectory;
+  if (!verifiedGitCommonDirectory) {
+    fail('GIT_COMMON_DIR_MISMATCH', 'Git common directory disappeared after successful reconciliation classification', {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+      actual: 'missing',
+    });
+  }
+
+  const currentBranch = gitText(registeredRoot, ['branch', '--show-current']);
+  const currentHead = gitText(registeredRoot, ['rev-parse', '--verify', 'HEAD']);
+  if (identity.branch && currentBranch !== identity.branch) {
+    fail('WORK_HANDLE_BRANCH_CHANGED', 'branch drifted from execution identity', {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+      expected: identity.branch,
+      actual: currentBranch ?? 'detached',
+      workId: identity.workId,
+    });
+  }
+  if (identity.expectedHead && currentHead !== identity.expectedHead) {
+    fail('WORK_HANDLE_HEAD_CHANGED', 'HEAD drifted from execution identity; re-prepare required', {
+      repoId: identity.repositoryId,
+      checkoutId: identity.checkoutId,
+      expected: identity.expectedHead,
+      actual: currentHead ?? 'missing',
+      workId: identity.workId,
+    });
+  }
+
+  return Object.freeze({
+    ...identity,
+    canonicalRoot: registeredRoot,
+    resolvedCwd,
+    gitTopLevel,
+    gitCommonDirectory: verifiedGitCommonDirectory,
+    currentBranch,
+    currentHead,
+  });
+}