@moretea-labs/forge 1.7.1 → 1.8.0

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

@@ -1,12 +1,25 @@
 import { createHash } from 'crypto';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
 import { getEditSession, listEditSessions, type EditSession } from '../../../cli/editing/edit-session';
+import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
 import { runProcess } from '../../../effects/process-runner';
-import { getWorkContract, updateWorkContract } from '../facade/work-contract-store';
+import { getWorkContract, implementationReviewChangedPathDigest, updateWorkContract } from '../../../../packages/kernel/work/api/index';
 import { completeWorkWithReceipt } from './work-completion-authority';
-import { isDirectEditWorkCompletionReceipt, isTerminalWorkContractStatus, type DirectEditWorkCompletionReceipt, type WorkReconciliationRecord } from '../facade/types';
-import { historicalVerificationEvidenceAtRevision } from './verification-evidence';
-import { readWorkHandle } from './work-handle-store';
+import { isDirectEditWorkCompletionReceipt, isTerminalWorkContractStatus, type DirectEditWorkCompletionReceipt, type WorkContract, type WorkReconciliationRecord } from '../facade/types';
+import { historicalVerificationEvidenceAtRevision, workspaceValidationFingerprint } from './verification-evidence';
+import { readWorkHandle, transitionWorkHandle, type WorkHandleState } from './work-handle-store';
 import { assertWorkPathsWithinScope, findWorkPathScopeViolation } from './work-path-scope';
+import { implementationReviewContentFingerprint, implementationReviewIndexFingerprint } from './implementation-review-content';
+import { transferReviewedWorkAuthorityAcrossContentEquivalentCommit } from './content-equivalent-commit-authority';
+import {
+  assertImplementationReviewPreDeliveryBoundary,
+  authoritativeImplementationReviewVerificationEvidence,
+  latestImplementationReview,
+  normalizeImplementationReviewChangedPaths,
+  type ImplementationReviewCandidateIdentity,
+} from '../../../../packages/kernel/work/api/index';
 
 export interface DirectEditWorkCompletionReconciliation {
   completedWorkIds: string[];
@@ -52,6 +65,176 @@ function requestedChecksPassed(session: EditSession): boolean {
   return session.requestedChecks.every((checkId) => session.checkResults.some((result) => result.checkId === checkId && result.ok));
 }
 
+
+function samePaths(left: readonly string[], right: readonly string[]): boolean {
+  const a = normalizeImplementationReviewChangedPaths(left);
+  const b = normalizeImplementationReviewChangedPaths(right);
+  return a.length === b.length && a.every((path, index) => path === b[index]);
+}
+
+export interface ReviewedDirectEditWorkCommitPlan {
+  workId: string;
+  editSessionId: string;
+  changedPaths: string[];
+  preCommitCandidate: ImplementationReviewCandidateIdentity;
+  preCommitContentFingerprint: string;
+}
+
+/**
+ * Resolve and gate the only Work-bound Direct Edit candidate whose complete
+ * reviewed path set is staged. This runs from selected-paths' beforeCommitGuard,
+ * after exact index discovery and before the first physical commit side effect.
+ */
+export function prepareReviewedDirectEditWorkCommit(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  stagedPaths: string[];
+  currentHead: string | null;
+}): ReviewedDirectEditWorkCommitPlan | undefined {
+  const stagedPaths = normalizeImplementationReviewChangedPaths(input.stagedPaths);
+  const overlapping = listEditSessions(input.repository.canonicalRoot, 200)
+    .map((summary) => getEditSession(input.repository.canonicalRoot, summary.sessionId))
+    .filter((session) => session.status === 'finalized' && Boolean(session.workId))
+    .filter((session) => changedPaths(session).some((path) => stagedPaths.includes(path)));
+  if (overlapping.length === 0) return undefined;
+  if (overlapping.length !== 1) {
+    throw new Error(`DIRECT_EDIT_WORK_COMMIT_AMBIGUOUS: staged paths overlap ${overlapping.length} finalized Work-bound Edit Sessions`);
+  }
+  const session = overlapping[0]!;
+  const paths = changedPaths(session);
+  if (!samePaths(paths, stagedPaths)) {
+    throw new Error('DIRECT_EDIT_WORK_COMMIT_SCOPE_MISMATCH: commit must materialize the complete reviewed Work path set with no mixed paths');
+  }
+  if (session.repoId && session.repoId !== input.repository.repoId) throw new Error('DIRECT_EDIT_WORK_COMMIT_REPOSITORY_MISMATCH');
+  if (session.checkoutId && session.checkoutId !== input.repository.activeCheckoutId) throw new Error('DIRECT_EDIT_WORK_COMMIT_CHECKOUT_MISMATCH');
+  const workId = session.workId!;
+  const work = getWorkContract({ controllerHome: input.controllerHome, repoId: input.repository.repoId }, workId);
+  if (!work || work.completionReceipt || isTerminalWorkContractStatus(work.status)) throw new Error(`DIRECT_EDIT_WORK_COMMIT_WORK_NOT_ACTIVE: ${workId}`);
+  if (work.checkoutId && work.checkoutId !== input.repository.activeCheckoutId) throw new Error('DIRECT_EDIT_WORK_COMMIT_WORK_CHECKOUT_MISMATCH');
+  assertWorkPathsWithinScope(work, paths, {
+    forbidden: 'DIRECT_EDIT_WORK_COMMIT_FORBIDDEN_PATH',
+    outOfScope: 'DIRECT_EDIT_WORK_COMMIT_PATH_OUT_OF_SCOPE',
+  });
+  const status = repositoryGitStatus(input.repository);
+  const sourceRevision = status.head?.trim();
+  if (!sourceRevision) throw new Error('DIRECT_EDIT_WORK_COMMIT_SOURCE_REVISION_REQUIRED');
+  if (!input.currentHead?.trim() || sourceRevision !== input.currentHead.trim()) {
+    throw new Error('DIRECT_EDIT_WORK_COMMIT_SOURCE_REVISION_CHANGED');
+  }
+  const latestReview = latestImplementationReview(work.implementationReviews);
+  if (!latestReview) throw new Error(`WORK_IMPLEMENTATION_REVIEW_REQUIRED: ${workId}`);
+  const contentFingerprint = implementationReviewContentFingerprint(input.repository.canonicalRoot, paths);
+  const indexFingerprint = implementationReviewIndexFingerprint(input.repository.canonicalRoot, paths);
+  if (contentFingerprint !== indexFingerprint) {
+    throw new Error('DIRECT_EDIT_WORK_COMMIT_INDEX_CONTENT_MISMATCH: staged index must equal the exact approved review content');
+  }
+  const verification = authoritativeImplementationReviewVerificationEvidence({
+    repoId: input.repository.repoId,
+    workId,
+    requiredCheckIds: work.checks,
+    records: work.checkRefs,
+    sourceRevision,
+    workspaceFingerprint: latestReview.verificationWorkspaceFingerprint,
+  });
+  if (verification.missingCheckIds.length > 0) {
+    throw new Error(`WORK_IMPLEMENTATION_REVIEW_VERIFICATION_REQUIRED: ${verification.missingCheckIds.join(', ')}`);
+  }
+  const candidate: ImplementationReviewCandidateIdentity = {
+    sourceRevision,
+    workspaceFingerprint: contentFingerprint,
+    verificationWorkspaceFingerprint: latestReview.verificationWorkspaceFingerprint,
+    changedPaths: paths,
+    verificationEvidence: verification.evidence,
+    architectureEvidence: latestReview.architectureEvidence,
+  };
+  assertImplementationReviewPreDeliveryBoundary({
+    repoId: input.repository.repoId,
+    workId,
+    workKind: work.workKind,
+    reviews: work.implementationReviews,
+    candidate,
+    requiredCheckIds: work.checks,
+    verificationRecords: work.checkRefs,
+  });
+  return { workId, editSessionId: session.sessionId, changedPaths: paths, preCommitCandidate: candidate, preCommitContentFingerprint: contentFingerprint };
+}
+
+/** Complete the exact pre-gated Direct Edit Work after the physical commit. */
+export function completeReviewedDirectEditWorkAfterCommit(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  plan: ReviewedDirectEditWorkCommitPlan;
+  fallbackBranch?: string;
+}): DirectEditWorkCompletionReconciliation {
+  const work = getWorkContract({ controllerHome: input.controllerHome, repoId: input.repository.repoId }, input.plan.workId);
+  if (!work || work.completionReceipt || isTerminalWorkContractStatus(work.status)) {
+    throw new Error(`DIRECT_EDIT_WORK_COMMIT_WORK_NOT_ACTIVE: ${input.plan.workId}`);
+  }
+  const postStatus = repositoryGitStatus(input.repository);
+  const targetRevision = postStatus.head?.trim();
+  if (!targetRevision || targetRevision === input.plan.preCommitCandidate.sourceRevision) {
+    throw new Error('DIRECT_EDIT_WORK_COMMIT_TARGET_REVISION_REQUIRED');
+  }
+  const actualCommittedPaths = comparedRevisionPaths(input.repository.canonicalRoot, input.plan.preCommitCandidate.sourceRevision, targetRevision);
+  if (!samePaths(actualCommittedPaths, input.plan.changedPaths)) {
+    throw new Error('DIRECT_EDIT_WORK_COMMIT_RESULT_SCOPE_MISMATCH');
+  }
+  const targetBranch = postStatus.branch?.trim() || input.fallbackBranch?.trim();
+  if (!targetBranch) throw new Error('DIRECT_EDIT_WORK_COMMIT_TARGET_BRANCH_REQUIRED');
+  const postVerificationWorkspaceFingerprint = workspaceValidationFingerprint(input.repository.canonicalRoot, postStatus);
+  const postContentFingerprint = implementationReviewContentFingerprint(input.repository.canonicalRoot, input.plan.changedPaths);
+  const transfer = transferReviewedWorkAuthorityAcrossContentEquivalentCommit({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    workId: input.plan.workId,
+    preCommitCandidate: input.plan.preCommitCandidate,
+    preCommitDirtyPaths: input.plan.changedPaths,
+    committedPaths: actualCommittedPaths,
+    preCommitContentDigest: input.plan.preCommitContentFingerprint,
+    postCommitSourceRevision: targetRevision,
+    postCommitContentDigest: postContentFingerprint,
+    postCommitVerificationWorkspaceFingerprint: postVerificationWorkspaceFingerprint,
+    postCommitChangedPaths: input.plan.changedPaths,
+  });
+  if (transfer.invalidatedCheckIds.length > 0) {
+    throw new Error(`DIRECT_EDIT_WORK_COMMIT_REVALIDATION_REQUIRED: ${transfer.invalidatedCheckIds.join(', ')}`);
+  }
+  if (!transfer.transferred || !transfer.derivedReview) {
+    throw new Error('DIRECT_EDIT_WORK_COMMIT_AUTHORITY_TRANSFER_REQUIRED');
+  }
+  const recordedAt = transfer.recordedAt;
+  const receipt: DirectEditWorkCompletionReceipt = {
+    schemaVersion: 1,
+    receiptId: `REC-direct-edit-work-${createHash('sha256').update(`${input.repository.repoId}\0${input.plan.workId}\0${input.plan.editSessionId}\0${targetRevision}`).digest('hex').slice(0, 20)}`,
+    source: 'direct_edit_work',
+    workId: input.plan.workId,
+    editSessionId: input.plan.editSessionId,
+    targetBranch,
+    targetRevision,
+    sourceRevision: targetRevision,
+    baseRevision: input.plan.preCommitCandidate.sourceRevision,
+    changedPaths: input.plan.changedPaths,
+    delivery: { kind: 'commit', status: 'integrated', strategy: 'edit_session_commit', reachable: true, recordedAt },
+    cleanup: { status: 'complete', warnings: [], blockers: [], recordedAt },
+    verifiedAt: recordedAt,
+    recordedAt,
+  };
+  completeWorkWithReceipt(
+    { controllerHome: input.controllerHome, repoId: input.repository.repoId },
+    input.plan.workId,
+    receipt,
+    'completed_changed',
+    'repository_change',
+  );
+  return {
+    completedWorkIds: [input.plan.workId],
+    examinedSessionIds: [input.plan.editSessionId],
+    skipped: [],
+    targetBranch,
+    targetRevision,
+  };
+}
+
 export function reconcileFinalizedDirectEditWorksAfterCommit(input: {
   controllerHome: string;
   repoId: string;
@@ -61,106 +244,35 @@ export function reconcileFinalizedDirectEditWorksAfterCommit(input: {
   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 targetRevision = targetRevisionResult.ok ? targetRevisionResult.stdout.trim() : undefined;
   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 committedPathSet = new Set(input.committedPaths);
   const examinedSessionIds: string[] = [];
   const skipped: DirectEditWorkCompletionReconciliation['skipped'] = [];
-  const summaries = listEditSessions(input.repoRoot, input.limit ?? 200);
-  for (const summary of summaries) {
+  for (const summary of listEditSessions(input.repoRoot, input.limit ?? 200)) {
     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;
+    if (paths.length === 0 || !paths.some((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 scopeViolation = findWorkPathScopeViolation(work, paths);
-    if (scopeViolation) {
-      skipped.push({
-        sessionId: session.sessionId,
-        workId: session.workId,
-        reason: `${scopeViolation.kind === 'forbidden' ? 'work_scope_forbidden' : 'work_scope_out_of_scope'}:${scopeViolation.path}`,
-      });
-      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',
+    skipped.push({
+      sessionId: session.sessionId,
       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,
-    };
-    completeWorkWithReceipt(
-      { controllerHome: input.controllerHome, repoId: input.repoId },
-      session.workId,
-      receipt,
-      'completed_changed',
-      'repository_change',
-    );
-    completedWorkIds.push(session.workId);
+      reason: 'postcommit_completion_authority_retired_use_precommit_review_gate_or_explicit_historical_reconciliation',
+    });
   }
-
-  return { completedWorkIds, examinedSessionIds, skipped, targetBranch, targetRevision };
+  // Historical helper intentionally never completes new Work. New delivery must
+  // pass prepareReviewedDirectEditWorkCommit() before commit and
+  // completeReviewedDirectEditWorkAfterCommit() afterward. Already-delivered
+  // recovery remains explicit through acceptReviewedDirectEditWorkReconciliation,
+  // whose completion receipt is cross-bound to a durable reconciliationId.
+  return { completedWorkIds: [], examinedSessionIds, skipped, targetBranch, targetRevision };
 }
 
 export interface ReviewedDirectEditWorkReconciliationInput {
@@ -184,6 +296,21 @@ function exactCommit(repoRoot: string, revision: string, label: string): string
   return result.stdout.trim();
 }
 
+function assertRemoteContainmentIfApplicable(repoRoot: string, targetBranch: string, targetRevision: string): void {
+  const remoteResult = git(repoRoot, ['config', '--get', `branch.${targetBranch}.remote`]);
+  const remote = remoteResult.ok ? remoteResult.stdout.trim() : '';
+  if (!remote || remote === '.') return;
+  const mergeResult = git(repoRoot, ['config', '--get', `branch.${targetBranch}.merge`]);
+  const mergeRef = mergeResult.ok ? mergeResult.stdout.trim() : '';
+  if (!mergeRef.startsWith('refs/heads/')) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_REMOTE_TRACKING_REQUIRED');
+  const remoteRef = `refs/remotes/${remote}/${mergeRef.slice('refs/heads/'.length)}`;
+  const remoteRevision = git(repoRoot, ['rev-parse', '--verify', `${remoteRef}^{commit}`]);
+  if (!remoteRevision.ok || !remoteRevision.stdout.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_REMOTE_TRACKING_REQUIRED');
+  if (!git(repoRoot, ['merge-base', '--is-ancestor', targetRevision, remoteRevision.stdout.trim()]).ok) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_REMOTE_CONTAINMENT_REQUIRED');
+  }
+}
+
 function comparedRevisionPaths(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
   const result = git(repoRoot, ['diff', '--name-only', '-z', baseRevision, targetRevision]);
   if (!result.ok) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_CHANGED_PATHS_UNAVAILABLE');
@@ -198,6 +325,139 @@ function normalizedComparedPaths(paths: string[]): string[] {
   return normalized;
 }
 
+function unresolvedRepositorySourcePaths(repoRoot: string): string[] {
+  const tracked = [
+    git(repoRoot, ['diff', '--name-only', '-z']),
+    git(repoRoot, ['diff', '--cached', '--name-only', '-z']),
+  ];
+  if (tracked.some((result) => !result.ok)) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_EFFECT_SOURCE_STATUS_UNAVAILABLE');
+  const untracked = git(repoRoot, ['ls-files', '--others', '--exclude-standard', '-z']);
+  if (!untracked.ok) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_EFFECT_SOURCE_STATUS_UNAVAILABLE');
+  return [...new Set([
+    ...tracked.flatMap((result) => result.stdout.split('\0').filter(Boolean)),
+    ...untracked.stdout.split('\0').filter((path) => path && !path.startsWith('.ai/harness/')),
+  ])].sort((left, right) => left.localeCompare(right));
+}
+
+export function isFailedReviewedDirectEditWorkRecovery(
+  work: WorkContract,
+  handle?: WorkHandleState,
+): handle is WorkHandleState {
+  return work.workKind === 'repository_change'
+    && work.status === 'failed'
+    && handle?.managedWorktree === false
+    && handle.state === 'failed'
+    && handle.finalization.validation === 'failed'
+    && handle.finalization.failureCode === 'WORK_HANDLE_HEAD_CHANGED';
+}
+
+function isStalePreMutationDirectOwnershipRecovery(
+  work: WorkContract,
+  handle: WorkHandleState | undefined,
+  input: { repoRoot: string; checkoutId: string; targetBranch: string; targetRevision: string },
+): handle is WorkHandleState {
+  const baseRevision = work.baseRevision?.trim();
+  const target = input.targetRevision.trim();
+  const targetBranch = input.targetBranch.trim();
+  if (
+    work.workKind !== 'repository_change'
+    || isTerminalWorkContractStatus(work.status)
+    || !baseRevision
+    || !target
+    || !targetBranch
+    || !handle
+    || handle.managedWorktree
+    || handle.state !== 'prepared'
+    || handle.repositoryId !== work.repoId
+    || handle.checkoutId !== input.checkoutId
+    || resolve(handle.worktreePath) !== resolve(input.repoRoot)
+    || handle.branch !== targetBranch
+    || (handle.deliveryTargetBranch !== undefined && handle.deliveryTargetBranch !== targetBranch)
+  ) return false;
+
+  const handleBase = handle.baseCommit?.trim();
+  const deliveryBase = (handle.deliveryBaseCommit ?? handle.baseCommit)?.trim();
+  const expectedHead = handle.expectedHead?.trim();
+  if (!handleBase || handleBase !== baseRevision || deliveryBase !== baseRevision || expectedHead !== baseRevision) return false;
+
+  const review = latestImplementationReview(work.implementationReviews);
+  return review?.decision === 'approved' && review.sourceRevision.trim() === target;
+}
+
+
+function reviewedMaterializedDirectOwnershipRecovery(
+  work: WorkContract,
+  handle: WorkHandleState | undefined,
+  input: { repoRoot: string; checkoutId: string; targetBranch: string; targetRevision: string },
+): { comparisonBaseRevision: string } | undefined {
+  const originalBase = work.baseRevision?.trim();
+  const target = input.targetRevision.trim();
+  const targetBranch = input.targetBranch.trim();
+  if (
+    work.workKind !== 'repository_change'
+    || isTerminalWorkContractStatus(work.status)
+    || !originalBase
+    || !target
+    || !targetBranch
+    || !handle
+    || handle.managedWorktree
+    || !['prepared', 'editing'].includes(handle.state)
+    || handle.repositoryId !== work.repoId
+    || handle.checkoutId !== input.checkoutId
+    || resolve(handle.worktreePath) !== resolve(input.repoRoot)
+    || handle.branch !== targetBranch
+    || (handle.deliveryTargetBranch !== undefined && handle.deliveryTargetBranch !== targetBranch)
+  ) return undefined;
+
+  const handleBase = handle.baseCommit?.trim();
+  const deliveryBase = (handle.deliveryBaseCommit ?? handle.baseCommit)?.trim();
+  const expectedHead = handle.expectedHead?.trim();
+  if (
+    !handleBase
+    || handleBase !== originalBase
+    || !deliveryBase
+    || deliveryBase === originalBase
+    || expectedHead !== deliveryBase
+    || deliveryBase === target
+  ) return undefined;
+  if (!git(input.repoRoot, ['merge-base', '--is-ancestor', originalBase, deliveryBase]).ok) return undefined;
+  if (!git(input.repoRoot, ['merge-base', '--is-ancestor', deliveryBase, target]).ok) return undefined;
+
+  const materializedPaths = comparedRevisionPaths(input.repoRoot, deliveryBase, target);
+  if (materializedPaths.length === 0) return undefined;
+  const materializedPathDigest = implementationReviewChangedPathDigest(materializedPaths);
+  for (const review of work.implementationReviews) {
+    if (review.decision !== 'approved' || review.sourceRevision.trim() !== deliveryBase) continue;
+    const reviewedPaths = normalizeImplementationReviewChangedPaths(review.changedPaths);
+    if (review.changedPathDigest !== implementationReviewChangedPathDigest(reviewedPaths)) continue;
+    if (review.changedPathDigest !== materializedPathDigest) continue;
+    if (reviewedPaths.length !== materializedPaths.length || reviewedPaths.some((path, index) => path !== materializedPaths[index])) continue;
+    let currentContentFingerprint: string;
+    try {
+      currentContentFingerprint = implementationReviewContentFingerprint(input.repoRoot, reviewedPaths);
+    } catch {
+      continue;
+    }
+    if (currentContentFingerprint !== review.workspaceFingerprint) continue;
+    return { comparisonBaseRevision: deliveryBase };
+  }
+  return undefined;
+}
+
+export function hasReviewedDirectEditReconciliationOwnership(input: {
+  work: WorkContract;
+  handle?: WorkHandleState;
+  activeOwnerPrincipal?: string;
+  callerPrincipal: string;
+}): boolean {
+  const callerPrincipal = input.callerPrincipal.trim();
+  if (!callerPrincipal) return false;
+  const activeOwnerPrincipal = input.activeOwnerPrincipal?.trim();
+  if (activeOwnerPrincipal) return activeOwnerPrincipal === callerPrincipal;
+  return isFailedReviewedDirectEditWorkRecovery(input.work, input.handle)
+    && input.handle.principalId.trim() === callerPrincipal;
+}
+
 /**
  * Explicitly close a historically delivered Direct Edit Work whose original
  * edit-session binding was missed. This is never inferred: the caller must
@@ -219,18 +479,30 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
     }
     throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_WORK_TERMINAL: ${input.workId}`);
   }
-  const failedHandle = work.status === 'failed'
-    ? readWorkHandle(input.controllerHome, input.repoId, input.workId)
-    : undefined;
-  const failedReviewedRecovery = work.workKind === 'repository_change'
-    && work.status === 'failed'
-    && failedHandle?.managedWorktree === false
-    && failedHandle.state === 'failed'
-    && failedHandle.finalization.validation === 'failed'
-    && String(failedHandle.finalization.lastError ?? failedHandle.failureReason ?? '').includes('WORK_HANDLE_HEAD_CHANGED');
-  if ((isTerminalWorkContractStatus(work.status) && !failedReviewedRecovery) || work.workKind !== 'repository_change') {
+  const currentHandle = readWorkHandle(input.controllerHome, input.repoId, input.workId);
+  const failedReviewedRecovery = isFailedReviewedDirectEditWorkRecovery(work, currentHandle);
+  const stalePreMutationOwnershipRecovery = isStalePreMutationDirectOwnershipRecovery(work, currentHandle, {
+    repoRoot: input.repoRoot,
+    checkoutId: input.checkoutId,
+    targetBranch: input.targetBranch,
+    targetRevision: input.targetRevision,
+  });
+  const materializedReviewedRecovery = reviewedMaterializedDirectOwnershipRecovery(work, currentHandle, {
+    repoRoot: input.repoRoot,
+    checkoutId: input.checkoutId,
+    targetBranch: input.targetBranch,
+    targetRevision: input.targetRevision,
+  });
+  const historicalEffectRecovery = !currentHandle
+    && !isTerminalWorkContractStatus(work.status)
+    && (work.workKind === 'local_effect' || work.workKind === 'remote_effect');
+  if ((isTerminalWorkContractStatus(work.status) && !failedReviewedRecovery)
+    || (work.workKind !== 'repository_change' && !historicalEffectRecovery)) {
     throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_WORK_NOT_ELIGIBLE: ${input.workId}`);
   }
+  if ((historicalEffectRecovery || stalePreMutationOwnershipRecovery) && work.checks.length === 0) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_CHECK_EVIDENCE_REQUIRED');
+  }
   if (!work.baseRevision?.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_BASE_REVISION_MISSING');
 
   const baseRevision = exactCommit(input.repoRoot, work.baseRevision, 'BASE_REVISION');
@@ -243,10 +515,19 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
   if (!git(input.repoRoot, ['merge-base', '--is-ancestor', targetRevision, targetBranch]).ok) {
     throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_TARGET_UNREACHABLE');
   }
+  // Ordinary historical reconciliation must prove remote containment. The stale
+  // pre-mutation ownership repair is different: it repairs an active Direct Work
+  // already contained by the current local target branch, matching normal local
+  // finalize semantics without turning push state into a second ownership gate.
+  if (!stalePreMutationOwnershipRecovery && !materializedReviewedRecovery) {
+    assertRemoteContainmentIfApplicable(input.repoRoot, targetBranch, targetRevision);
+  }
 
   const comparedPaths = normalizedComparedPaths(input.comparedPaths);
   let comparisonBaseRevision = baseRevision;
-  if (failedReviewedRecovery) {
+  if (materializedReviewedRecovery) {
+    comparisonBaseRevision = materializedReviewedRecovery.comparisonBaseRevision;
+  } else if (failedReviewedRecovery || stalePreMutationOwnershipRecovery) {
     const targetParent = exactCommit(input.repoRoot, `${targetRevision}^`, 'TARGET_PARENT_REVISION');
     if (!git(input.repoRoot, ['merge-base', '--is-ancestor', baseRevision, targetParent]).ok) {
       throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_TARGET_PARENT_NOT_DESCENDANT');
@@ -263,6 +544,15 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
   });
   const dirty = git(input.repoRoot, ['status', '--porcelain=v1', '--', ...comparedPaths]);
   if (!dirty.ok || dirty.stdout.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_OWNED_PATHS_DIRTY');
+  if (historicalEffectRecovery) {
+    const separateOwnedWorktree = Boolean(work.worktreeRef?.trim())
+      && resolve(work.worktreeRef!) !== resolve(input.repoRoot)
+      && existsSync(work.worktreeRef!);
+    if (separateOwnedWorktree) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_EFFECT_CLEANUP_REQUIRED');
+    if (unresolvedRepositorySourcePaths(input.repoRoot).length > 0) {
+      throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_EFFECT_SOURCE_DELTA_UNRESOLVED');
+    }
+  }
 
   let verifiedAt = new Date().toISOString();
   for (const checkId of work.checks) {
@@ -334,5 +624,32 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
     'completed_changed',
     'repository_change',
   );
+
+  // WorkHandle is the physical repository-delivery projection of the same
+  // accepted reconciliation. Keep that projection inside this completion
+  // authority so MCP adapters cannot independently infer or persist lifecycle
+  // state after the semantic completion receipt is durable.
+  if (currentHandle && currentHandle.state !== 'cleaned') {
+    const finalization: WorkHandleState['finalization'] = currentHandle.managedWorktree
+      ? currentHandle.finalization
+      : { validation: 'done', commit: 'done', merge: 'skipped', branchCleanup: 'skipped', worktreeCleanup: 'skipped' };
+    const delivered = currentHandle.state === 'committed' || currentHandle.state === 'merged' || currentHandle.state === 'failed_terminal_cleanup'
+      ? currentHandle
+      : transitionWorkHandle(input.controllerHome, currentHandle, 'committed', {
+          expectedHead: receipt.targetRevision,
+          finalization,
+          failureReason: undefined,
+        });
+    // Managed reconciliation records semantic delivery first, then ordinary
+    // terminal cleanup removes the exact owned checkout. Direct/canonical Work
+    // has no separate managed cleanup resource and may close the projection now.
+    if (!currentHandle.managedWorktree) {
+      transitionWorkHandle(input.controllerHome, delivered, 'cleaned', {
+        expectedHead: receipt.targetRevision,
+        finalization,
+        failureReason: undefined,
+      });
+    }
+  }
   return { workId: input.workId, reconciliation, receipt };
 }