@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/control-plane/execution/retained-work-resume.ts

@@ -8,10 +8,11 @@ import { listRepositories, repositoryCheckoutLifecycle, selectRepositoryCheckout
 import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
 import { ensureManagedWorkspace } from '../../execution/managed-workspace';
 import { getControllerSession } from '../../../../packages/kernel/controller/api/index';
-import { getWorkContract, recordWorkEvidenceState, resumeRetainedCancelledWorkContract, transitionWorkContractPhase, updateWorkContract } from '../../../../packages/kernel/work/api/index';
+import { getWorkContract, recordWorkEvidenceState, transitionWorkContractPhase, updateWorkContract } from '../../../../packages/kernel/work/api/index';
 import { gitCommitAtRef, gitWorktreeSnapshot } from './work-lifecycle-audit';
-import { findWorkPathScopeViolation } from './work-path-scope';
 import { readWorkHandle, writeWorkHandle, type WorkHandleState } from './work-handle-store';
+import { rearmFailedPreservedWorkHandle } from './work-handle-authority';
+import { hasSettledWorkDeliveryReceipt } from './work-completion-authority';
 
 export interface RetainedWorkResumeIdentity {
   principalId: string;
@@ -19,16 +20,6 @@ export interface RetainedWorkResumeIdentity {
   controllerInstanceId: string;
 }
 
-export interface ReauthorizeRetainedCancelledWorkInput {
-  controllerHome: string;
-  repository: RepositoryRecord;
-  workId: string;
-  identity: RetainedWorkResumeIdentity;
-  requestedBy?: string;
-  approvalConfirmed?: boolean;
-  prepareDependencies?: boolean;
-}
-
 export interface EnsureRunningRepositoryWorkCheckoutInput {
   controllerHome: string;
   repository: RepositoryRecord;
@@ -72,7 +63,7 @@ function restoreArchivedBlockedDeliveryCheckout(input: {
   const { controllerHome, repository, work, handle, identity } = input;
   const receipt = handle.cleanupReceipt;
   if (handle.state !== 'cleaned' || receipt?.terminalOutcome !== 'blocked_terminal') return undefined;
-  if (work.completionReceipt || work.completionOutcome || work.status !== 'blocked' || work.phase !== 'delivery') {
+  if (work.completionReceipt || work.completionOutcome || work.dispatchState !== 'blocked' || work.phase !== 'delivery') {
     throw new Error(`WORK_CONTINUE_ARCHIVED_DELIVERY_LIFECYCLE_CONFLICT: ${work.workId}`);
   }
   if (!['none', 'partial', 'valid', 'stale'].includes(work.evidenceState)) {
@@ -150,10 +141,6 @@ function restoreArchivedBlockedDeliveryCheckout(input: {
   if (!changed.ok) throw new Error(`WORK_CONTINUE_ARCHIVED_DELIVERY_DIFF_UNAVAILABLE: ${work.workId}`);
   const changedPaths = normalizedPaths(changed.stdout.split(/\r?\n/));
   if (changedPaths.length === 0) throw new Error(`WORK_CONTINUE_ARCHIVED_DELIVERY_ZERO_DELTA: ${work.workId}`);
-  const scopeViolation = findWorkPathScopeViolation(work, changedPaths);
-  if (scopeViolation) {
-    throw new Error(`WORK_CONTINUE_ARCHIVED_DELIVERY_SCOPE_VIOLATION: ${scopeViolation.kind}:${scopeViolation.path}`);
-  }
   const recordedChangedPaths = normalizedPaths(work.scopeEvidence?.actualChangedPaths ?? []);
   if (recordedChangedPaths.length > 0 && JSON.stringify(recordedChangedPaths) !== JSON.stringify(changedPaths)) {
     throw new Error(`WORK_CONTINUE_ARCHIVED_DELIVERY_PATH_IDENTITY_MISMATCH: ${work.workId}`);
@@ -167,6 +154,7 @@ function restoreArchivedBlockedDeliveryCheckout(input: {
   const workspace = ensureManagedWorkspace(controllerHome, repository, {
     requestId: `${work.workId}:archived-delivery-recovery:${candidateRevision}`,
     title: `${work.objective} archived delivery recovery`,
+    associatedWorkId: work.workId,
     branchName,
     baseRef: candidateRevision,
     prepareDependencies: input.prepareDependencies === true,
@@ -193,7 +181,6 @@ function restoreArchivedBlockedDeliveryCheckout(input: {
   });
   transitionWorkContractPhase(store, work.workId, {
     phase: 'verification',
-    status: 'running',
     state: 'active',
     dispatchState: 'running',
     summary: `Archived candidate ${candidateRevision} was rehydrated from verified blocked-terminal preservation; fresh verification is required before delivery.`,
@@ -225,114 +212,145 @@ function restoreArchivedBlockedDeliveryCheckout(input: {
 }
 
 /**
- * Re-establish the checkout binding for a still-running isolated Work only
- * when durable and Git evidence prove that the missing checkout carried no
- * repository delta. Any dirty, divergent, committed, or cleaned evidence
- * fails closed so recovery never becomes permission to discard source.
+ * Rehydrate a committed candidate whose validation process disappeared before
+ * delivery/cleanup. The candidate is safe to revisit only when the durable
+ * WorkHandle, Git object database, and recorded changed-path identity all agree.
+ * A missing cleanup receipt is intentional here: this is a pre-delivery
+ * recovery, not a second delivery authority.
  */
-export function ensureRunningRepositoryWorkCheckout(
-  input: EnsureRunningRepositoryWorkCheckoutInput,
-): { reconstructedCheckout: boolean } {
-  const { controllerHome, repository, workId, identity } = input;
-  const store = { controllerHome, repoId: repository.repoId };
-  const work = getWorkContract(store, workId);
-  if (!work || ['cancelled', 'completed', 'failed'].includes(work.status)) return { reconstructedCheckout: false };
-  if (work.workKind !== 'repository_change' || work.worktreePolicy.required !== true) return { reconstructedCheckout: false };
-
-  const recordedCheckoutId = work.checkoutId?.trim();
-  const recordedWorktree = work.worktreeRef?.trim();
-  if (!recordedCheckoutId || !recordedWorktree) return { reconstructedCheckout: false };
-
-  const registryRepository = listRepositories(controllerHome, { includeRemoved: true })
-    .find((candidate) => candidate.repoId === repository.repoId);
-  if (!registryRepository) throw new Error(`WORK_CONTINUE_REPOSITORY_MISSING: ${workId}`);
-  const checkoutRecord = registryRepository.checkouts.find((candidate) => candidate.checkoutId === recordedCheckoutId);
-  const checkoutActive = checkoutRecord ? repositoryCheckoutLifecycle(checkoutRecord) === 'active' : false;
-  const worktreePresent = existsSync(recordedWorktree);
-  if (checkoutActive && worktreePresent) return { reconstructedCheckout: false };
-  if (checkoutActive) throw new Error(`WORK_CONTINUE_CHECKOUT_PRESERVATION_AMBIGUOUS: ${workId}`);
+function restoreArchivedPendingCandidateCheckout(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  work: NonNullable<ReturnType<typeof getWorkContract>>;
+  handle: WorkHandleState;
+  identity: RetainedWorkResumeIdentity;
+}): { reconstructedCheckout: boolean } | undefined {
+  const { controllerHome, repository, work, handle, identity } = input;
+  if (work.semanticState !== 'open') return undefined;
+  if (work.phase !== 'verification' || work.workKind !== 'repository_change') return undefined;
+  if (handle.state !== 'failed'
+    || handle.finalization.validation !== 'failed'
+    || handle.finalization.commit !== 'done'
+    || handle.finalization.merge !== 'pending'
+    || handle.finalization.branchCleanup !== 'pending'
+    || handle.finalization.worktreeCleanup !== 'pending'
+    || handle.cleanupReceipt
+    || work.completionReceipt
+    || work.completionOutcome) return undefined;
 
-  const handle = readWorkHandle(controllerHome, repository.repoId, workId);
-  if (!handle) throw new Error(`WORK_CONTINUE_HANDLE_REQUIRED: ${workId}`);
-  if (handle.repositoryId !== repository.repoId || (handle.workContractId && handle.workContractId !== workId)) {
-    throw new Error(`WORK_CONTINUE_HANDLE_IDENTITY_MISMATCH: ${workId}`);
+  const candidateRevision = handle.expectedHead?.trim();
+  const baseRevisionRaw = work.baseRevision?.trim() || handle.baseCommit?.trim();
+  const recordedChangedPaths = normalizedPaths(work.scopeEvidence?.actualChangedPaths ?? []);
+  if (!candidateRevision || !baseRevisionRaw || recordedChangedPaths.length === 0) {
+    return undefined;
   }
-  if (handle.principalId !== identity.principalId) throw new Error(`WORK_CONTINUE_HANDLE_PRINCIPAL_MISMATCH: ${workId}`);
-  if (handle.checkoutId !== recordedCheckoutId || resolve(handle.worktreePath) !== resolve(recordedWorktree)) {
-    throw new Error(`WORK_CONTINUE_CHECKOUT_OWNERSHIP_MISMATCH: ${workId}`);
+
+  const candidateCommit = gitCommitAtRef(repository.canonicalRoot, candidateRevision);
+  if (candidateCommit !== candidateRevision) {
+    throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_MISSING: ${work.workId}`);
   }
-  const archivedDelivery = restoreArchivedBlockedDeliveryCheckout({
-    controllerHome, repository, work, handle, identity, prepareDependencies: input.prepareDependencies,
-  });
-  if (archivedDelivery) return archivedDelivery;
-  if (['committed', 'merged', 'cleaned', 'failed_terminal_cleanup'].includes(handle.state)
-    || handle.finalization.commit === 'done'
-    || handle.finalization.merge === 'done'
-    || handle.cleanupReceipt?.complete === true) {
-    throw new Error(`WORK_CONTINUE_DELIVERY_OR_CLEANUP_CONFLICT: ${workId}`);
+  const baseRevision = gitCommitAtRef(repository.canonicalRoot, baseRevisionRaw);
+  if (!baseRevision) throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_BASE_MISSING: ${work.workId}`);
+  if (!git(repository.canonicalRoot, ['merge-base', '--is-ancestor', baseRevision, candidateRevision]).ok) {
+    throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_REVISION_AMBIGUOUS: ${work.workId}`);
   }
 
-  const actualChangedPaths = work.scopeEvidence?.actualChangedPaths;
-  if (!actualChangedPaths || actualChangedPaths.length !== 0
-    || work.checks.length !== 0
-    || work.checkRefs.length !== 0
-    || work.evidenceState !== 'none') {
-    throw new Error(`WORK_CONTINUE_ZERO_DELTA_PROOF_REQUIRED: ${workId}`);
-  }
-  const recordedBase = work.baseRevision?.trim();
-  if (!recordedBase) throw new Error(`WORK_CONTINUE_BASE_REVISION_REQUIRED: ${workId}`);
-  const baseRevision = gitCommitAtRef(repository.canonicalRoot, recordedBase);
-  if (!baseRevision) throw new Error(`WORK_CONTINUE_BASE_REVISION_MISSING: ${workId}`);
-  const handleBase = handle.baseCommit ? gitCommitAtRef(repository.canonicalRoot, handle.baseCommit) : undefined;
-  const handleHead = handle.expectedHead ? gitCommitAtRef(repository.canonicalRoot, handle.expectedHead) : undefined;
-  if ((handle.baseCommit && handleBase !== baseRevision) || (handle.expectedHead && handleHead !== baseRevision)) {
-    throw new Error(`WORK_CONTINUE_REVISION_AMBIGUOUS: ${workId}`);
+  const targetBranch = handle.deliveryTargetBranch?.trim() || repository.defaultBranch?.trim();
+  if (!targetBranch) throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_TARGET_REQUIRED: ${work.workId}`);
+  if (git(repository.canonicalRoot, ['merge-base', '--is-ancestor', candidateRevision, targetBranch]).ok) {
+    throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_ALREADY_INTEGRATED: ${work.workId}`);
   }
-  if (handle.branch) {
-    const historicalBranchHead = gitCommitAtRef(repository.canonicalRoot, `refs/heads/${handle.branch}`);
-    if (historicalBranchHead && historicalBranchHead !== baseRevision) {
-      throw new Error(`WORK_CONTINUE_UNIQUE_COMMIT_CONFLICT: ${workId}`);
+  const changed = git(repository.canonicalRoot, ['diff', '--name-only', `${baseRevision}..${candidateRevision}`]);
+  if (!changed.ok) throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_DIFF_UNAVAILABLE: ${work.workId}`);
+  const candidateChangedPaths = normalizedPaths(changed.stdout.split(/\r?\n/));
+  if (candidateChangedPaths.length === 0) throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_ZERO_DELTA: ${work.workId}`);
+
+  // A delivery candidate can contain a canonical target advancement as a
+  // merge parent. Only the unique parent already reachable from the current
+  // target branch may be treated as target history; the Work-owned delta is
+  // then measured from that parent to the candidate. This keeps unrelated
+  // target changes out of Work scope evidence while still requiring the exact
+  // candidate tree and recorded path identity to agree.
+  let workOwnedChangedPaths = candidateChangedPaths;
+  let deliveryBaseCommit = baseRevision;
+  const parents = git(repository.canonicalRoot, ['rev-list', '--parents', '-n', '1', candidateRevision]);
+  if (parents.ok) {
+    const parentRevisions = parents.stdout.split(/\s+/).slice(1).filter(Boolean);
+    const targetParents = parentRevisions.filter((parent) =>
+      git(repository.canonicalRoot, ['merge-base', '--is-ancestor', parent, targetBranch]).ok,
+    );
+    if (parentRevisions.length === 2 && targetParents.length === 1 && targetParents[0] !== baseRevision) {
+      const targetParent = targetParents[0];
+      const targetRelative = git(repository.canonicalRoot, ['diff', '--name-only', `${targetParent}..${candidateRevision}`]);
+      if (!targetRelative.ok) throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_TARGET_RELATIVE_DIFF_UNAVAILABLE: ${work.workId}`);
+      workOwnedChangedPaths = normalizedPaths(targetRelative.stdout.split(/\r?\n/));
+      if (workOwnedChangedPaths.length === 0) throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_ZERO_WORK_DELTA: ${work.workId}`);
+      deliveryBaseCommit = targetParent;
+      const expectedRecordedPaths = normalizedPaths([...workOwnedChangedPaths, ...normalizedPaths(
+        git(repository.canonicalRoot, ['diff', '--name-only', `${baseRevision}..${targetParent}`]).stdout.split(/\r?\n/),
+      )]);
+      if (JSON.stringify(recordedChangedPaths) !== JSON.stringify(candidateChangedPaths)
+        && JSON.stringify(recordedChangedPaths) !== JSON.stringify(workOwnedChangedPaths)
+        && JSON.stringify(recordedChangedPaths) !== JSON.stringify(expectedRecordedPaths)) {
+        throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_PATH_IDENTITY_MISMATCH: ${work.workId}`);
+      }
     }
   }
-  if (worktreePresent) {
-    const retainedSnapshot = gitWorktreeSnapshot(recordedWorktree);
-    if (!retainedSnapshot || !retainedSnapshot.clean || retainedSnapshot.head !== baseRevision || (handle.branch && retainedSnapshot.branch !== handle.branch)) {
-      throw new Error(`WORK_CONTINUE_ZERO_DELTA_PHYSICAL_CONFLICT: ${workId}`);
-    }
+  if (deliveryBaseCommit === baseRevision && JSON.stringify(recordedChangedPaths) !== JSON.stringify(candidateChangedPaths)) {
+    throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_PATH_IDENTITY_MISMATCH: ${work.workId}`);
   }
 
-  const branchName = `work/resume-${workId.replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 42)}-${baseRevision.slice(0, 12)}`;
+  const branchName = `work/resume-pending-candidate-${work.workId.replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 34)}-${candidateRevision.slice(0, 12)}`;
   const existingResumeBranch = gitCommitAtRef(repository.canonicalRoot, `refs/heads/${branchName}`);
-  if (existingResumeBranch && existingResumeBranch !== baseRevision) {
-    throw new Error(`WORK_CONTINUE_RECONSTRUCTION_BRANCH_CONFLICT: ${workId}`);
+  if (existingResumeBranch && existingResumeBranch !== candidateRevision) {
+    throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_BRANCH_CONFLICT: ${work.workId}`);
   }
   const workspace = ensureManagedWorkspace(controllerHome, repository, {
-    requestId: `${workId}:active-checkout-recovery:${baseRevision}`,
-    title: `${work.objective} checkout recovery`,
+    requestId: `${work.workId}:pending-candidate-recovery:${candidateRevision}`,
+    title: `${work.objective} pending candidate recovery`,
+    associatedWorkId: work.workId,
     branchName,
-    baseRef: baseRevision,
-    prepareDependencies: input.prepareDependencies === true,
+    baseRef: candidateRevision,
   });
   if (!workspace.managed || !workspace.checkoutId || !workspace.root || !workspace.branch) {
-    throw new Error(`WORK_CONTINUE_RECONSTRUCTION_FAILED: ${workId}`);
+    throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_RECONSTRUCTION_FAILED: ${work.workId}`);
   }
   const refreshedRepository = listRepositories(controllerHome, { includeRemoved: true })
     .find((candidate) => candidate.repoId === repository.repoId);
-  if (!refreshedRepository) throw new Error(`WORK_CONTINUE_REPOSITORY_MISSING: ${workId}`);
+  if (!refreshedRepository) throw new Error(`WORK_CONTINUE_REPOSITORY_MISSING: ${work.workId}`);
   const reconstructed = selectRepositoryCheckout(refreshedRepository, workspace.checkoutId);
   const reconstructedStatus = repositoryGitStatus(reconstructed);
-  if (!reconstructedStatus.clean || reconstructedStatus.head !== baseRevision || reconstructedStatus.branch !== workspace.branch) {
-    throw new Error(`WORK_CONTINUE_RECONSTRUCTION_REVISION_MISMATCH: ${workId}`);
+  if (!reconstructedStatus.clean || reconstructedStatus.head !== candidateRevision || reconstructedStatus.branch !== workspace.branch) {
+    throw new Error(`WORK_CONTINUE_COMMITTED_CANDIDATE_RECONSTRUCTION_REVISION_MISMATCH: ${work.workId}`);
   }
 
-  updateWorkContract(store, workId, {
+  const at = new Date().toISOString();
+  const store = { controllerHome, repoId: repository.repoId };
+  updateWorkContract(store, work.workId, {
     checkoutId: workspace.checkoutId,
     worktreeRef: workspace.root,
-    baseRevision,
     controllerInstanceId: identity.controllerInstanceId,
-    continuationPrompt: `Continue work ${repository.repoId}: ${work.objective.slice(0, 500)}. The prior managed checkout was absent; Forge reconstructed an exact zero-delta checkout at ${baseRevision}.`,
+    ...(deliveryBaseCommit !== baseRevision
+      ? {
+          scopeEvidence: {
+            initialLikelyPaths: work.scopeEvidence?.initialLikelyPaths ?? [],
+            inspectedPaths: work.scopeEvidence?.inspectedPaths ?? [],
+            actualChangedPaths: workOwnedChangedPaths,
+            recordedAt: at,
+          },
+        }
+      : {}),
+    continuationPrompt: `Continue work ${repository.repoId}: ${work.objective.slice(0, 500)}. Forge rehydrated exact pending candidate ${candidateRevision}; rerun verification before delivery.`,
   });
-  const updatedAt = new Date().toISOString();
+  transitionWorkContractPhase(store, work.workId, {
+    phase: 'verification',
+    state: 'active',
+    dispatchState: 'running',
+    summary: `Pending candidate ${candidateRevision} was rehydrated after validation-process loss; fresh verification is required before delivery.`,
+  });
+  if (work.evidenceState === 'partial' || work.evidenceState === 'valid') {
+    recordWorkEvidenceState(store, work.workId, 'stale');
+  }
   writeWorkHandle(controllerHome, {
     ...handle,
     principalId: identity.principalId,
@@ -341,169 +359,165 @@ export function ensureRunningRepositoryWorkCheckout(
     worktreePath: workspace.root,
     branch: workspace.branch,
     sourceCheckoutId: repository.activeCheckoutId,
+    deliveryTargetBranch: targetBranch,
     managedWorktree: true,
     baseCommit: baseRevision,
-    deliveryBaseCommit: baseRevision,
-    expectedHead: baseRevision,
-    state: 'prepared',
+    deliveryBaseCommit,
+    expectedHead: candidateRevision,
+    state: 'validating',
     validatedInputFingerprint: undefined,
     failureReason: undefined,
     cleanupReceipt: undefined,
-    finalization: { validation: 'pending', commit: 'pending', merge: 'pending', branchCleanup: 'pending', worktreeCleanup: 'pending' },
-    updatedAt,
+    updatedAt: at,
+    finalization: {
+      validation: 'pending',
+      commit: 'done',
+      merge: 'pending',
+      branchCleanup: 'pending',
+      worktreeCleanup: 'pending',
+    },
   });
   return { reconstructedCheckout: true };
 }
 
 /**
- * Canonical orchestration authority for explicitly re-authorizing the exact
- * retained cancelled repository Work. Transport adapters provide authenticated
- * identity and typed user intent only; they must not duplicate these lifecycle,
- * ownership, zero-delta, or reconstruction rules.
+ * Re-establish the checkout binding for a still-running isolated Work only
+ * when durable and Git evidence prove that the missing checkout carried no
+ * repository delta. Any dirty, divergent, committed, or cleaned evidence
+ * fails closed so recovery never becomes permission to discard source.
  */
-export function reauthorizeRetainedCancelledRepositoryWork(
-  input: ReauthorizeRetainedCancelledWorkInput,
+export function ensureRunningRepositoryWorkCheckout(
+  input: EnsureRunningRepositoryWorkCheckoutInput,
 ): { reconstructedCheckout: boolean } {
   const { controllerHome, repository, workId, identity } = input;
   const store = { controllerHome, repoId: repository.repoId };
-  let work = getWorkContract(store, workId);
-  if (!work || work.status !== 'cancelled') return { reconstructedCheckout: false };
-  if (input.approvalConfirmed !== true || input.requestedBy !== 'user') {
-    throw new Error(`WORK_CANCELLED_RESUME_REAUTHORIZATION_REQUIRED: ${workId}; use exact work_id with requested_by=user and approval_confirmed=true`);
-  }
-  if (!work.principalId?.trim() || work.principalId.trim() !== identity.principalId) {
-    throw new Error(`WORK_CANCELLED_RESUME_PRINCIPAL_MISMATCH: ${workId}`);
-  }
-  const owner = getControllerSession(store, workId);
-  if (owner && (owner.principalId?.trim() || owner.controllerId) !== identity.principalId) {
-    throw new Error(`WORK_CANCELLED_RESUME_CONTROLLER_OWNERSHIP_MISMATCH: ${workId}`);
-  }
-  if (work.completionReceipt || work.completionOutcome) throw new Error(`WORK_CANCELLED_RESUME_COMPLETION_CONFLICT: ${workId}`);
-  if (work.reconciliations.length > 0) throw new Error(`WORK_CANCELLED_RESUME_DELIVERY_HISTORY_AMBIGUOUS: ${workId}`);
-  if (work.phase !== 'cleanup' || work.phaseEvidence.cleanup.state !== 'skipped' || work.phaseEvidence.cleanup.source !== 'recorded') {
-    throw new Error(`WORK_CANCELLED_RESUME_HISTORY_AMBIGUOUS: ${workId}`);
-  }
-  if (work.workKind !== 'repository_change' || work.worktreePolicy.required !== true) {
-    throw new Error(`WORK_CANCELLED_RESUME_ISOLATED_REPOSITORY_WORK_REQUIRED: ${workId}`);
-  }
+  const work = getWorkContract(store, workId);
+  if (!work || work.semanticState !== 'open') return { reconstructedCheckout: false };
+  if (work.workKind !== 'repository_change') return { reconstructedCheckout: false };
+  const handle = readWorkHandle(controllerHome, repository.repoId, workId);
+  const hasManagedPlacement = handle?.managedWorktree === true
+    && Boolean(handle.checkoutId?.trim())
+    && Boolean(handle.worktreePath?.trim());
+  if (work.worktreePolicy.required !== true && !hasManagedPlacement) return { reconstructedCheckout: false };
+  // A settled physical delivery may intentionally outlive its managed checkout
+  // while semantic Work remains open. Do not reconstruct or reject source that
+  // the finalizer has already integrated and cleaned; Controller semantic
+  // judgment is the only remaining authority.
+  if (hasSettledWorkDeliveryReceipt(work)) return { reconstructedCheckout: false };
 
-  let handle = readWorkHandle(controllerHome, repository.repoId, workId);
-  if (handle) {
-    if (handle.repositoryId !== repository.repoId || (handle.workContractId && handle.workContractId !== workId)) {
-      throw new Error(`WORK_CANCELLED_RESUME_HANDLE_IDENTITY_MISMATCH: ${workId}`);
-    }
-    if (handle.principalId !== identity.principalId) throw new Error(`WORK_CANCELLED_RESUME_HANDLE_PRINCIPAL_MISMATCH: ${workId}`);
-    if (['committed', 'merged', 'cleaned', 'failed_terminal_cleanup'].includes(handle.state)
-      || handle.finalization.commit === 'done'
-      || handle.finalization.merge === 'done'
-      || handle.cleanupReceipt?.complete === true) {
-      throw new Error(`WORK_CANCELLED_RESUME_DELIVERY_OR_CLEANUP_CONFLICT: ${workId}`);
-    }
-  }
+  const recordedCheckoutId = handle?.checkoutId?.trim() || work.checkoutId?.trim();
+  const recordedWorktree = handle?.worktreePath?.trim() || work.worktreeRef?.trim();
+  if (!recordedCheckoutId || !recordedWorktree) return { reconstructedCheckout: false };
 
   const registryRepository = listRepositories(controllerHome, { includeRemoved: true })
     .find((candidate) => candidate.repoId === repository.repoId);
-  if (!registryRepository) throw new Error(`WORK_CANCELLED_RESUME_REPOSITORY_MISSING: ${workId}`);
-  const recordedCheckoutId = work.checkoutId?.trim();
-  const recordedWorktree = work.worktreeRef?.trim();
-  const checkoutRecord = recordedCheckoutId
-    ? registryRepository.checkouts.find((candidate) => candidate.checkoutId === recordedCheckoutId)
-    : undefined;
-  const checkoutActive = checkoutRecord?.lifecycle === 'active';
-  const worktreePresent = Boolean(recordedWorktree && existsSync(recordedWorktree));
-
-  if (checkoutActive && worktreePresent && recordedCheckoutId && recordedWorktree) {
-    const retained = selectRepositoryCheckout(registryRepository, recordedCheckoutId);
-    if (resolve(retained.canonicalRoot) !== resolve(recordedWorktree)) {
-      throw new Error(`WORK_CANCELLED_RESUME_CHECKOUT_REUSED: ${workId}`);
-    }
-    if (!handle) throw new Error(`WORK_CANCELLED_RESUME_HANDLE_REQUIRED: ${workId}`);
-    if (handle.checkoutId !== recordedCheckoutId || resolve(handle.worktreePath) !== resolve(recordedWorktree)) {
-      throw new Error(`WORK_CANCELLED_RESUME_CHECKOUT_OWNERSHIP_MISMATCH: ${workId}`);
-    }
-    const status = repositoryGitStatus(retained);
-    if (!status.branch || status.branch !== handle.branch) throw new Error(`WORK_CANCELLED_RESUME_BRANCH_OWNERSHIP_MISMATCH: ${workId}`);
-    writeWorkHandle(controllerHome, {
-      ...handle,
+  if (!registryRepository) throw new Error(`WORK_CONTINUE_REPOSITORY_MISSING: ${workId}`);
+  const checkoutRecord = registryRepository.checkouts.find((candidate) => candidate.checkoutId === recordedCheckoutId);
+  const checkoutActive = checkoutRecord ? repositoryCheckoutLifecycle(checkoutRecord) === 'active' : false;
+  const worktreePresent = existsSync(recordedWorktree);
+  if (checkoutActive && worktreePresent) {
+    if (!handle || handle.state !== 'failed') return { reconstructedCheckout: false };
+    rearmFailedPreservedWorkHandle({
+      controllerHome,
+      repository,
+      workId,
+      contract: work,
+      handle,
       principalId: identity.principalId,
       sessionId: identity.sessionId,
-      updatedAt: new Date().toISOString(),
-    });
-    resumeRetainedCancelledWorkContract(store, workId, {
-      principalId: identity.principalId,
-      controllerInstanceId: identity.controllerInstanceId,
-      summary: 'Explicit current user re-authorized the same retained cancelled Work; exact managed checkout ownership was revalidated.',
     });
     return { reconstructedCheckout: false };
   }
+  if (checkoutActive) throw new Error(`WORK_CONTINUE_CHECKOUT_PRESERVATION_AMBIGUOUS: ${workId}`);
 
-  if (checkoutActive) throw new Error(`WORK_CANCELLED_RESUME_PRESERVATION_AMBIGUOUS: ${workId}`);
-  if (!recordedCheckoutId || !recordedWorktree || !handle) throw new Error(`WORK_CANCELLED_RESUME_HANDLE_REQUIRED: ${workId}`);
+  if (!handle) throw new Error(`WORK_CONTINUE_HANDLE_REQUIRED: ${workId}`);
+  if (handle.repositoryId !== repository.repoId || (handle.workContractId && handle.workContractId !== workId)) {
+    throw new Error(`WORK_CONTINUE_HANDLE_IDENTITY_MISMATCH: ${workId}`);
+  }
+  if (handle.principalId !== identity.principalId) throw new Error(`WORK_CONTINUE_HANDLE_PRINCIPAL_MISMATCH: ${workId}`);
+  if (handle.checkoutId !== recordedCheckoutId || resolve(handle.worktreePath) !== resolve(recordedWorktree)) {
+    throw new Error(`WORK_CONTINUE_CHECKOUT_OWNERSHIP_MISMATCH: ${workId}`);
+  }
+  const archivedDelivery = restoreArchivedBlockedDeliveryCheckout({
+    controllerHome, repository, work, handle, identity, prepareDependencies: input.prepareDependencies,
+  });
+  if (archivedDelivery) return archivedDelivery;
+  const pendingCandidate = restoreArchivedPendingCandidateCheckout({
+    controllerHome, repository, work, handle, identity,
+  });
+  if (pendingCandidate) return pendingCandidate;
+  if (['committed', 'merged', 'cleaned', 'failed_terminal_cleanup'].includes(handle.state)
+    || handle.finalization.commit === 'done'
+    || handle.finalization.merge === 'done'
+    || handle.cleanupReceipt?.complete === true) {
+    throw new Error(`WORK_CONTINUE_DELIVERY_OR_CLEANUP_CONFLICT: ${workId}`);
+  }
 
   const actualChangedPaths = work.scopeEvidence?.actualChangedPaths;
+  // `work.checks` is a declaration of verification obligations, not evidence
+  // that any verification or repository mutation already occurred. Only
+  // durable checkRefs participate in the zero-delta recovery proof.
   if (!actualChangedPaths || actualChangedPaths.length !== 0
-    || work.checks.length !== 0
     || work.checkRefs.length !== 0
     || work.evidenceState !== 'none') {
-    throw new Error(`WORK_CANCELLED_RESUME_ZERO_DELTA_PROOF_REQUIRED: ${workId}`);
+    throw new Error(`WORK_CONTINUE_ZERO_DELTA_PROOF_REQUIRED: ${workId}`);
   }
   const recordedBase = work.baseRevision?.trim();
-  if (!recordedBase) throw new Error(`WORK_CANCELLED_RESUME_BASE_REVISION_REQUIRED: ${workId}`);
+  if (!recordedBase) throw new Error(`WORK_CONTINUE_BASE_REVISION_REQUIRED: ${workId}`);
   const baseRevision = gitCommitAtRef(repository.canonicalRoot, recordedBase);
-  if (!baseRevision) throw new Error(`WORK_CANCELLED_RESUME_BASE_REVISION_MISSING: ${workId}`);
+  if (!baseRevision) throw new Error(`WORK_CONTINUE_BASE_REVISION_MISSING: ${workId}`);
   const handleBase = handle.baseCommit ? gitCommitAtRef(repository.canonicalRoot, handle.baseCommit) : undefined;
   const handleHead = handle.expectedHead ? gitCommitAtRef(repository.canonicalRoot, handle.expectedHead) : undefined;
   if ((handle.baseCommit && handleBase !== baseRevision) || (handle.expectedHead && handleHead !== baseRevision)) {
-    throw new Error(`WORK_CANCELLED_RESUME_REVISION_AMBIGUOUS: ${workId}`);
-  }
-  if (handle.checkoutId !== recordedCheckoutId || resolve(handle.worktreePath) !== resolve(recordedWorktree)) {
-    throw new Error(`WORK_CANCELLED_RESUME_CHECKOUT_OWNERSHIP_MISMATCH: ${workId}`);
+    throw new Error(`WORK_CONTINUE_REVISION_AMBIGUOUS: ${workId}`);
   }
   if (handle.branch) {
     const historicalBranchHead = gitCommitAtRef(repository.canonicalRoot, `refs/heads/${handle.branch}`);
     if (historicalBranchHead && historicalBranchHead !== baseRevision) {
-      throw new Error(`WORK_CANCELLED_RESUME_UNIQUE_COMMIT_CONFLICT: ${workId}`);
+      throw new Error(`WORK_CONTINUE_UNIQUE_COMMIT_CONFLICT: ${workId}`);
     }
   }
   if (worktreePresent) {
     const retainedSnapshot = gitWorktreeSnapshot(recordedWorktree);
     if (!retainedSnapshot || !retainedSnapshot.clean || retainedSnapshot.head !== baseRevision || (handle.branch && retainedSnapshot.branch !== handle.branch)) {
-      throw new Error(`WORK_CANCELLED_RESUME_ZERO_DELTA_PHYSICAL_CONFLICT: ${workId}`);
+      throw new Error(`WORK_CONTINUE_ZERO_DELTA_PHYSICAL_CONFLICT: ${workId}`);
     }
   }
 
   const branchName = `work/resume-${workId.replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 42)}-${baseRevision.slice(0, 12)}`;
   const existingResumeBranch = gitCommitAtRef(repository.canonicalRoot, `refs/heads/${branchName}`);
   if (existingResumeBranch && existingResumeBranch !== baseRevision) {
-    throw new Error(`WORK_CANCELLED_RESUME_RECONSTRUCTION_BRANCH_CONFLICT: ${workId}`);
+    throw new Error(`WORK_CONTINUE_RECONSTRUCTION_BRANCH_CONFLICT: ${workId}`);
   }
   const workspace = ensureManagedWorkspace(controllerHome, repository, {
-    requestId: `${workId}:explicit-user-resume:${baseRevision}`,
-    title: `${work.objective} explicit user resume`,
+    requestId: `${workId}:active-checkout-recovery:${baseRevision}`,
+    title: `${work.objective} checkout recovery`,
+    associatedWorkId: workId,
     branchName,
     baseRef: baseRevision,
     prepareDependencies: input.prepareDependencies === true,
   });
   if (!workspace.managed || !workspace.checkoutId || !workspace.root || !workspace.branch) {
-    throw new Error(`WORK_CANCELLED_RESUME_RECONSTRUCTION_FAILED: ${workId}`);
+    throw new Error(`WORK_CONTINUE_RECONSTRUCTION_FAILED: ${workId}`);
   }
   const refreshedRepository = listRepositories(controllerHome, { includeRemoved: true })
     .find((candidate) => candidate.repoId === repository.repoId);
-  if (!refreshedRepository) throw new Error(`WORK_CANCELLED_RESUME_REPOSITORY_MISSING: ${workId}`);
+  if (!refreshedRepository) throw new Error(`WORK_CONTINUE_REPOSITORY_MISSING: ${workId}`);
   const reconstructed = selectRepositoryCheckout(refreshedRepository, workspace.checkoutId);
   const reconstructedStatus = repositoryGitStatus(reconstructed);
   if (!reconstructedStatus.clean || reconstructedStatus.head !== baseRevision || reconstructedStatus.branch !== workspace.branch) {
-    throw new Error(`WORK_CANCELLED_RESUME_RECONSTRUCTION_REVISION_MISMATCH: ${workId}`);
+    throw new Error(`WORK_CONTINUE_RECONSTRUCTION_REVISION_MISMATCH: ${workId}`);
   }
 
-  work = updateWorkContract(store, workId, {
+  updateWorkContract(store, workId, {
     checkoutId: workspace.checkoutId,
     worktreeRef: workspace.root,
     baseRevision,
     controllerInstanceId: identity.controllerInstanceId,
+    continuationPrompt: `Continue work ${repository.repoId}: ${work.objective.slice(0, 500)}. The prior managed checkout was absent; Forge reconstructed an exact zero-delta checkout at ${baseRevision}.`,
   });
-  const now = new Date().toISOString();
-  handle = writeWorkHandle(controllerHome, {
+  const updatedAt = new Date().toISOString();
+  writeWorkHandle(controllerHome, {
     ...handle,
     principalId: identity.principalId,
     sessionId: identity.sessionId,
@@ -520,14 +534,7 @@ export function reauthorizeRetainedCancelledRepositoryWork(
     failureReason: undefined,
     cleanupReceipt: undefined,
     finalization: { validation: 'pending', commit: 'pending', merge: 'pending', branchCleanup: 'pending', worktreeCleanup: 'pending' },
-    updatedAt: now,
-  });
-  resumeRetainedCancelledWorkContract(store, workId, {
-    principalId: identity.principalId,
-    controllerInstanceId: identity.controllerInstanceId,
-    summary: 'Explicit current user re-authorized the same cancelled Work; prior managed checkout was absent and a fresh isolated checkout was reconstructed at the exact zero-delta base revision.',
-    checkoutId: workspace.checkoutId,
-    worktreeRef: workspace.root,
+    updatedAt,
   });
   return { reconstructedCheckout: true };
 }

package/src/runtime/control-plane/execution/session-store.ts

@@ -4,7 +4,12 @@ import { join } from 'path';
 import { ensureControllerHome } from '../../../cli/repositories/controller-home';
 import { readJsonFile, sanitizeFileComponent } from '../../shared/json-files';
 import type { GoalDelegation } from '../governance/authorization';
-import { readOrImportControlPlaneRecord, writeControlPlaneRecord } from '../persistence/sqlite-store';
+import {
+  readControlPlaneRecordWithinTransaction,
+  readOrImportControlPlaneRecord,
+  writeControlPlaneRecord,
+  type SqliteDatabase,
+} from '../persistence/sqlite-store';
 
 export interface ExecutionSessionContext {
   schemaVersion: 1;
@@ -71,6 +76,31 @@ export function peekExecutionSession(controllerHome: string, sessionId: string):
   return session.sessionId === normalizedSessionId ? session : undefined;
 }
 
+/**
+ * Transaction-safe execution-session projection. It never imports legacy
+ * state while another control-plane write transaction is open. A legacy JSON
+ * file may still be read as evidence and is imported later by the ordinary
+ * non-transactional session path.
+ */
+export function peekExecutionSessionWithinTransaction(
+  database: SqliteDatabase,
+  controllerHome: string,
+  sessionId: string,
+): ExecutionSessionContext | undefined {
+  const normalizedSessionId = sessionId.trim();
+  if (!normalizedSessionId) return undefined;
+  const stored = readControlPlaneRecordWithinTransaction<ExecutionSessionContext>(
+    database,
+    'execution_session',
+    'controller',
+    sanitizeFileComponent(normalizedSessionId),
+  )?.value;
+  const legacyPath = sessionPath(controllerHome, normalizedSessionId);
+  const session = stored ?? (existsSync(legacyPath) ? readJsonFile<ExecutionSessionContext>(legacyPath) : undefined);
+  if (!session) return undefined;
+  return session.sessionId === normalizedSessionId ? session : undefined;
+}
+
 export function readExecutionSession(controllerHome: string, identity: SessionIdentity): ExecutionSessionContext | undefined {
   const sessionId = identity.sessionId?.trim();
   if (!sessionId) return undefined;