@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/control-plane/execution/work-terminal-cleanup.ts

@@ -12,14 +12,21 @@ import { repoLocalNoIndexControllerHome, repositoryControllerRoot } from '../../
 import {
   getRepository,
   listRepositories,
+  RepositoryCheckoutSelectionError,
   selectRepositoryCheckout,
   setRepositoryCheckoutLifecycle,
 } from '../../../cli/repositories/registry';
 import { managedPathInside, managedWorktreeStorageRoot } from '../../../cli/repositories/worktree-storage';
 import { markRepositoryProjectionDirty } from '../../projections/invalidation';
 import { listControlPlaneRecords } from '../persistence/sqlite-store';
-import { getWorkContract } from '../facade/work-contract-store';
-import { getControllerSession, releaseObservedControllerSession } from '../facade/controller-session-store';
+import { getWorkContract } from '../../../../packages/kernel/work/api/index';
+import {
+  controllerTerminalizationAuthorityFromSession,
+  getControllerSession,
+  releaseControllerSessionWithAuthority,
+  releaseObservedControllerSession,
+  type ControllerTerminalizationAuthority,
+} from '../../../../packages/kernel/controller/api/index';
 import { isRepositoryCompletionReceipt, isTerminalWorkContractStatus, type WorkContract } from '../facade/types';
 import {
   cancelProcess,
@@ -33,12 +40,14 @@ import { getProcessRecord, listProcessRecords } from '../../execution/process-ru
 import {
   listWorkHandles,
   readWorkHandle,
+  resolveWorkDeliveryTargetBranch,
   transitionWorkHandle,
   writeWorkHandle,
   type WorkCleanupReceipt,
   type WorkHandleState,
   type WorkTerminalOutcome,
 } from './work-handle-store';
+import { proveWorkPreservationContained } from '../cleanup-artifact-retention';
 
 const CHECKPOINT_MESSAGE = 'chore(checkpoint): preserve terminal work before cleanup';
 
@@ -383,8 +392,9 @@ function selectTerminalCleanupTarget(repository: ReturnType<typeof getRepository
     try {
       return selectRepositoryCheckout(repository, sourceCheckoutId, { allowArchived: true });
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (!message.startsWith('CHECKOUT_NOT_ACTIVE:') && !message.startsWith('checkout not found for ')) throw error;
+      const unavailable = error instanceof RepositoryCheckoutSelectionError
+        && (error.code === 'CHECKOUT_NOT_FOUND' || (error.code === 'CHECKOUT_NOT_ACTIVE' && error.lifecycle === 'removed'));
+      if (!unavailable) throw error;
     }
   }
   // Terminal cleanup only performs repository-common Git administration after
@@ -482,7 +492,10 @@ export function recoverTerminalWorkHandle(
 
   const head = git(worktreePath, ['rev-parse', 'HEAD']);
   if (!head.ok || !head.stdout) return undefined;
-  const targetBranch = repository.defaultBranch || 'main';
+  const receiptTargetBranch = contract.completionReceipt && isRepositoryCompletionReceipt(contract.completionReceipt)
+    ? contract.completionReceipt.targetBranch?.trim()
+    : undefined;
+  const targetBranch = receiptTargetBranch || repository.defaultBranch || 'main';
   const targetExists = branchExists(repository.canonicalRoot, targetBranch);
   const contained = targetExists
     ? git(repository.canonicalRoot, ['merge-base', '--is-ancestor', head.stdout, `refs/heads/${targetBranch}`]).ok
@@ -499,6 +512,7 @@ export function recoverTerminalWorkHandle(
     repositoryId,
     checkoutId,
     sourceCheckoutId: repository.activeCheckoutId,
+    ...(receiptTargetBranch ? { deliveryTargetBranch: receiptTargetBranch } : {}),
     worktreePath,
     branch,
     managedWorktree: true,
@@ -529,13 +543,229 @@ function cleanupRetainedByRequest(contract: WorkContract, handle: WorkHandleStat
   // completion-receipt warning as the delivery authority.
   if (
     handle.terminalResourceDisposition?.mode === 'retained_by_request'
-    && handle.terminalResourceDisposition.retainWorktree === true
+    && (handle.terminalResourceDisposition.retainWorktree === true
+      || handle.terminalResourceDisposition.retainBranch === true)
   ) return true;
   const receipt = contract.completionReceipt;
   if (!receipt || !isRepositoryCompletionReceipt(receipt)) return false;
   return receipt.cleanup.warnings.some((warning) => warning.code === 'cleanup_retained_by_request');
 }
 
+function cleanedManagedBranchRetirementCandidate(
+  repository: ReturnType<typeof getRepository>,
+  contract: WorkContract,
+  handle: WorkHandleState,
+  targetBranch: string,
+  deleteBranch: boolean,
+): boolean {
+  const receipt = handle.cleanupReceipt;
+  if (
+    handle.state !== 'cleaned'
+    || !handle.managedWorktree
+    || !deleteBranch
+    || !receipt
+    || receipt.targetBranch !== targetBranch
+    || cleanupRetainedByRequest(contract, handle)
+  ) return false;
+  if (!['removed', 'already_removed'].includes(receipt.worktree.status)
+    || !['removed', 'already_removed'].includes(receipt.checkoutRegistry.status)
+    || receipt.prune.status !== 'done'
+    || !['retained', 'failed', 'pending'].includes(receipt.branchCleanup.status)) return false;
+  // A crash may occur after branch deletion but before the final cleanup receipt
+  // is persisted. The unsettled branchCleanup status is sufficient residue to
+  // re-enter cleanup; applyManagedBranchCleanup will converge an absent branch
+  // to already_deleted without reopening semantic Work state.
+  return handle.branch !== targetBranch;
+}
+
+function prepareManagedBranchPreservation(
+  input: TerminalWorkCleanupInput,
+  receipt: WorkCleanupReceipt,
+  current: WorkHandleState,
+  target: ReturnType<typeof getRepository>,
+  targetBranch: string,
+): { uniqueCommits: number; branchPreserved: boolean } {
+  let uniqueCommits = 0;
+  if (branchExists(target.canonicalRoot, current.branch)) {
+    if (!branchExists(target.canonicalRoot, targetBranch)) {
+      addBlocker(receipt, `TARGET_BRANCH_MISSING: ${targetBranch}`);
+    } else {
+      const unique = git(target.canonicalRoot, ['rev-list', '--count', `refs/heads/${targetBranch}..refs/heads/${current.branch}`]);
+      if (!unique.ok || !/^\d+$/.test(unique.stdout)) addBlocker(receipt, `BRANCH_UNIQUENESS_UNKNOWN: ${unique.stderr || unique.stdout}`);
+      else uniqueCommits = Number(unique.stdout);
+    }
+  }
+  receipt.branchCleanup.uniqueCommits = uniqueCommits;
+
+  let branchPreserved = Boolean(
+    receipt.preservation.bundleRetirement?.status === 'not_needed'
+    || receipt.preservation.bundleRetirement?.status === 'removed',
+  );
+  if (receipt.preservation.bundlePath && !branchPreserved) {
+    try {
+      const bundle = createVerifiedBundle(input.controllerHome, current, target.canonicalRoot);
+      if (receipt.preservation.bundleSha256 && receipt.preservation.bundleSha256 !== bundle.sha256) {
+        throw new Error(`stored bundle digest ${receipt.preservation.bundleSha256} does not match ${bundle.sha256}`);
+      }
+      receipt.preservation.bundleSha256 = bundle.sha256;
+      branchPreserved = true;
+    } catch (error) {
+      addBlocker(receipt, `BRANCH_BUNDLE_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (uniqueCommits > 0 && !branchPreserved && receipt.blockers.length === 0) {
+    const proof = proveWorkPreservationContained(target.canonicalRoot, { ...current, cleanupReceipt: receipt }, targetBranch);
+    if (proof.contained) {
+      receipt.preservation.bundleRetirement = {
+        status: 'not_needed',
+        reason: proof.reason === 'no_source_delta' ? 'no_source_delta' : 'target_and_remote_content_contained',
+        protectedRevision: proof.protectedRevision!,
+        targetRevision: proof.targetRevision,
+        remoteRevision: proof.remoteRevision,
+        comparedPaths: proof.comparedPaths,
+        provedAt: nowIso(),
+      };
+      receipt.preservation.recoveryInstructions = `Branch bundle not created after ${proof.reason}; exact proof is stored in cleanupReceipt.preservation.bundleRetirement.`;
+      branchPreserved = true;
+    } else {
+      try {
+        const bundle = createVerifiedBundle(input.controllerHome, current, target.canonicalRoot);
+        receipt.preservation.bundlePath = bundle.path;
+        receipt.preservation.bundleSha256 = bundle.sha256;
+        receipt.preservation.recoveryInstructions = [
+          receipt.preservation.recoveryInstructions,
+          `Recover branch commits with: git fetch ${bundle.path} refs/heads/${current.branch}:refs/heads/${current.branch}`,
+        ].filter(Boolean).join(' ');
+        branchPreserved = true;
+      } catch (error) {
+        addBlocker(receipt, `BRANCH_BUNDLE_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+  return { uniqueCommits, branchPreserved };
+}
+
+function applyManagedBranchCleanup(
+  target: ReturnType<typeof getRepository>,
+  current: WorkHandleState,
+  targetBranch: string,
+  deleteBranch: boolean,
+  receipt: WorkCleanupReceipt,
+  uniqueCommits: number,
+  branchPreserved: boolean,
+): void {
+  if (!deleteBranch) {
+    receipt.branchCleanup.status = 'retained';
+    receipt.branchCleanup.reason = 'Branch retention was explicitly requested.';
+  } else if (!branchExists(target.canonicalRoot, current.branch)) {
+    receipt.branchCleanup.status = 'already_deleted';
+    receipt.branchCleanup.reason = undefined;
+  } else if (current.branch === targetBranch) {
+    receipt.branchCleanup.status = 'retained';
+    receipt.branchCleanup.reason = 'Refusing to delete the target branch.';
+    addBlocker(receipt, `BRANCH_IS_TARGET: ${targetBranch}`);
+  } else if (branchUsedByAnotherWorktree(target.canonicalRoot, current.branch, current.worktreePath)) {
+    receipt.branchCleanup.status = 'retained';
+    receipt.branchCleanup.reason = 'Branch is checked out by another worktree.';
+    addBlocker(receipt, `BRANCH_IN_USE: ${current.branch}`);
+  } else if (uniqueCommits > 0 && !branchPreserved) {
+    receipt.branchCleanup.status = 'retained';
+    receipt.branchCleanup.reason = 'Unique commits are not archived.';
+    addBlocker(receipt, `BRANCH_UNPRESERVED: ${current.branch}`);
+  } else {
+    // We already proved the exact branch relation against targetBranch above.
+    // `git branch -d` instead consults the checkout's current HEAD, which may be
+    // an older/stale source checkout and can falsely reject a branch that is
+    // fully contained in the explicit target branch. After that target-branch
+    // proof (or a verified archive for unique commits), delete the ref directly.
+    const deleted = git(target.canonicalRoot, ['branch', '-D', current.branch]);
+    if (!deleted.ok && branchExists(target.canonicalRoot, current.branch)) {
+      receipt.branchCleanup.status = 'failed';
+      receipt.branchCleanup.reason = deleted.stderr || 'branch delete failed';
+      addBlocker(receipt, `BRANCH_DELETE_FAILED: ${receipt.branchCleanup.reason}`);
+    } else {
+      receipt.branchCleanup.status = uniqueCommits > 0 && receipt.preservation.bundlePath ? 'archived' : 'deleted';
+      receipt.branchCleanup.reason = undefined;
+    }
+  }
+}
+
+function cleanupReceiptComplete(receipt: WorkCleanupReceipt, deleteBranch: boolean): boolean {
+  return receipt.blockers.length === 0
+    && ['removed', 'already_removed'].includes(receipt.worktree.status)
+    && ['removed', 'already_removed'].includes(receipt.checkoutRegistry.status)
+    && (deleteBranch
+      ? ['deleted', 'already_deleted', 'archived'].includes(receipt.branchCleanup.status)
+      : receipt.branchCleanup.status === 'retained');
+}
+
+function reconcileCleanedManagedBranchRetirement(
+  input: TerminalWorkCleanupInput,
+  repository: ReturnType<typeof getRepository>,
+  targetBranch: string,
+  deleteBranch: boolean,
+  current: WorkHandleState,
+  receipt: WorkCleanupReceipt,
+): TerminalWorkCleanupResult | undefined {
+  const workId = current.workContractId ?? current.workId;
+  const contract = getWorkContract({ controllerHome: input.controllerHome, repoId: current.repositoryId }, workId);
+  if (!contract || !isTerminalWorkContractStatus(contract.status)
+    || !cleanedManagedBranchRetirementCandidate(repository, contract, current, targetBranch, deleteBranch)) return undefined;
+
+  const target = selectTerminalCleanupTarget(repository, current);
+  receipt.blockers = [];
+  receipt.partial = false;
+  receipt.complete = false;
+  receipt.completedAt = undefined;
+  receipt.branchCleanup.status = 'pending';
+  receipt.branchCleanup.reason = undefined;
+
+  const preservation = prepareManagedBranchPreservation(input, receipt, current, target, targetBranch);
+  current = persist(input.controllerHome, current, receipt);
+  if (receipt.blockers.length === 0) {
+    applyManagedBranchCleanup(
+      target,
+      current,
+      targetBranch,
+      deleteBranch,
+      receipt,
+      preservation.uniqueCommits,
+      preservation.branchPreserved,
+    );
+  } else if (receipt.branchCleanup.status === 'pending') {
+    receipt.branchCleanup.status = 'retained';
+    receipt.branchCleanup.reason = 'Branch retirement proof could not be re-established.';
+  }
+
+  const pruned = git(target.canonicalRoot, ['worktree', 'prune']);
+  receipt.prune.status = pruned.ok ? 'done' : 'failed';
+  if (!pruned.ok) {
+    receipt.prune.reason = pruned.stderr || 'git worktree prune failed';
+    addBlocker(receipt, `WORKTREE_PRUNE_FAILED: ${receipt.prune.reason}`);
+  } else {
+    receipt.prune.reason = undefined;
+  }
+
+  receipt.complete = cleanupReceiptComplete(receipt, deleteBranch);
+  receipt.partial = !receipt.complete;
+  if (receipt.complete) receipt.completedAt = nowIso();
+  const finalization = {
+    ...current.finalization,
+    branchCleanup: receipt.complete ? 'done' as const : 'failed' as const,
+    worktreeCleanup: 'done' as const,
+  };
+  current = writeWorkHandle(input.controllerHome, {
+    ...current,
+    state: 'cleaned',
+    cleanupReceipt: receipt,
+    finalization,
+  });
+  if (receipt.complete) {
+    markRepositoryProjectionDirty(input.controllerHome, current.repositoryId, `cleanup:${current.workId}:terminal-branch-retirement`);
+  }
+  return { handle: current, receipt };
+}
+
 function reconcileLegacyTerminalBranchDrift(
   controllerHome: string,
   repository: ReturnType<typeof getRepository>,
@@ -585,7 +815,7 @@ function reconcileLegacyTerminalBranchDrift(
 
 export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Promise<TerminalWorkCleanupResult> {
   const repository = getRepository(input.handle.repositoryId, input.controllerHome, { includeRemoved: true });
-  const targetBranch = input.targetBranch?.trim() || repository.defaultBranch || 'main';
+  const targetBranch = resolveWorkDeliveryTargetBranch(input.handle, repository.defaultBranch, input.targetBranch);
   const deleteBranch = input.deleteBranch !== false;
   let current = input.handle;
   const landed = current.state === 'merged' || current.finalization.merge === 'done';
@@ -598,7 +828,44 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
     || receipt.workId !== current.workId
   ) throw new Error('WORK_CLEANUP_RECEIPT_IDENTITY_MISMATCH');
 
-  if (current.state === 'cleaned' && receipt.complete) return { handle: current, receipt };
+  if (current.state === 'cleaned') {
+    const branchRetirement = reconcileCleanedManagedBranchRetirement(
+      input,
+      repository,
+      targetBranch,
+      deleteBranch,
+      current,
+      receipt,
+    );
+    if (branchRetirement) return branchRetirement;
+    if (!receipt.complete) {
+      receipt.complete = true;
+      receipt.partial = false;
+      receipt.completedAt = receipt.completedAt ?? current.updatedAt ?? nowIso();
+      receipt.blockers = [];
+      receipt.processes.allTerminal = true;
+      if (receipt.ownership.controllerLease === 'pending') receipt.ownership.controllerLease = 'already_released';
+      if (receipt.ownership.processLeases === 'pending') receipt.ownership.processLeases = 'released';
+      if (receipt.worktree.status === 'pending' || receipt.worktree.status === 'failed') {
+        receipt.worktree.status = 'already_removed';
+        receipt.worktree.reason = 'Reconciled from durable cleaned WorkHandle state.';
+      }
+      if (receipt.checkoutRegistry.status === 'pending' || receipt.checkoutRegistry.status === 'failed') {
+        receipt.checkoutRegistry.status = 'already_removed';
+        receipt.checkoutRegistry.reason = 'Reconciled from durable cleaned WorkHandle state.';
+      }
+      if (receipt.prune.status === 'pending' || receipt.prune.status === 'failed') {
+        receipt.prune.status = 'done';
+        receipt.prune.reason = 'Reconciled from durable cleaned WorkHandle state.';
+      }
+      if (receipt.branchCleanup.status === 'pending' || receipt.branchCleanup.status === 'failed') {
+        receipt.branchCleanup.status = 'retained';
+        receipt.branchCleanup.reason = 'Historical cleaned state does not prove branch deletion; branch is conservatively retained.';
+      }
+      current = writeWorkHandle(input.controllerHome, { ...current, cleanupReceipt: receipt });
+    }
+    return { handle: current, receipt };
+  }
 
   // Retryable blockers are observations, not permanent vetoes. Recompute them
   // from durable Work/Process/Git state after a controller restart or retry.
@@ -649,7 +916,11 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
   }
 
   await settleProcesses(input, receipt);
-  assertNoOtherLiveWork(input, receipt);
+  // The selected/current repository checkout is shared infrastructure, not a
+  // disposable Work-owned resource. Other live Works may legitimately share it;
+  // only a managed Work checkout requires exclusive lifecycle ownership before
+  // physical removal.
+  if (current.managedWorktree) assertNoOtherLiveWork(input, receipt);
   current = persist(input.controllerHome, current, receipt);
   if (receipt.blockers.length > 0) return { handle: current, receipt };
 
@@ -732,31 +1003,13 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
     receipt.worktree.status = 'already_removed';
   }
 
-  let uniqueCommits = 0;
-  if (branchExists(target.canonicalRoot, current.branch)) {
-    if (!branchExists(target.canonicalRoot, targetBranch)) {
-      addBlocker(receipt, `TARGET_BRANCH_MISSING: ${targetBranch}`);
-    } else {
-      const unique = git(target.canonicalRoot, ['rev-list', '--count', `refs/heads/${targetBranch}..refs/heads/${current.branch}`]);
-      if (!unique.ok || !/^\d+$/.test(unique.stdout)) addBlocker(receipt, `BRANCH_UNIQUENESS_UNKNOWN: ${unique.stderr || unique.stdout}`);
-      else uniqueCommits = Number(unique.stdout);
-    }
-  }
-  receipt.branchCleanup.uniqueCommits = uniqueCommits;
-
-  if (uniqueCommits > 0 && !receipt.preservation.bundlePath) {
-    try {
-      const bundle = createVerifiedBundle(input.controllerHome, current, target.canonicalRoot);
-      receipt.preservation.bundlePath = bundle.path;
-      receipt.preservation.bundleSha256 = bundle.sha256;
-      receipt.preservation.recoveryInstructions = [
-        receipt.preservation.recoveryInstructions,
-        `Recover branch commits with: git fetch ${bundle.path} refs/heads/${current.branch}:refs/heads/${current.branch}`,
-      ].filter(Boolean).join(' ');
-    } catch (error) {
-      addBlocker(receipt, `BRANCH_BUNDLE_FAILED: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
+  const { uniqueCommits, branchPreserved } = prepareManagedBranchPreservation(
+    input,
+    receipt,
+    current,
+    target,
+    targetBranch,
+  );
   current = persist(input.controllerHome, current, receipt);
   if (receipt.blockers.length > 0) {
     receipt.worktree.status = existsSync(current.worktreePath) ? 'retained' : receipt.worktree.status;
@@ -802,38 +1055,15 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
     receipt.checkoutRegistry.reason = 'Checkout metadata was absent after Controller Home migration; canonical managed-worktree and Git identity checks passed before cleanup.';
   }
 
-  if (!deleteBranch) {
-    receipt.branchCleanup.status = 'retained';
-    receipt.branchCleanup.reason = 'Branch retention was explicitly requested.';
-  } else if (!branchExists(target.canonicalRoot, current.branch)) {
-    receipt.branchCleanup.status = 'already_deleted';
-  } else if (current.branch === targetBranch) {
-    receipt.branchCleanup.status = 'retained';
-    receipt.branchCleanup.reason = 'Refusing to delete the target branch.';
-    addBlocker(receipt, `BRANCH_IS_TARGET: ${targetBranch}`);
-  } else if (branchUsedByAnotherWorktree(target.canonicalRoot, current.branch, current.worktreePath)) {
-    receipt.branchCleanup.status = 'retained';
-    receipt.branchCleanup.reason = 'Branch is checked out by another worktree.';
-    addBlocker(receipt, `BRANCH_IN_USE: ${current.branch}`);
-  } else if (uniqueCommits > 0 && !receipt.preservation.bundlePath) {
-    receipt.branchCleanup.status = 'retained';
-    receipt.branchCleanup.reason = 'Unique commits are not archived.';
-    addBlocker(receipt, `BRANCH_UNPRESERVED: ${current.branch}`);
-  } else {
-    // We already proved the exact branch relation against targetBranch above.
-    // `git branch -d` instead consults the checkout's current HEAD, which may be
-    // an older/stale source checkout and can falsely reject a branch that is
-    // fully contained in the explicit target branch. After that target-branch
-    // proof (or a verified archive for unique commits), delete the ref directly.
-    const deleted = git(target.canonicalRoot, ['branch', '-D', current.branch]);
-    if (!deleted.ok && branchExists(target.canonicalRoot, current.branch)) {
-      receipt.branchCleanup.status = 'failed';
-      receipt.branchCleanup.reason = deleted.stderr || 'branch delete failed';
-      addBlocker(receipt, `BRANCH_DELETE_FAILED: ${receipt.branchCleanup.reason}`);
-    } else {
-      receipt.branchCleanup.status = uniqueCommits > 0 ? 'archived' : 'deleted';
-    }
-  }
+  applyManagedBranchCleanup(
+    target,
+    current,
+    targetBranch,
+    deleteBranch,
+    receipt,
+    uniqueCommits,
+    branchPreserved,
+  );
 
   const pruned = git(target.canonicalRoot, ['worktree', 'prune']);
   receipt.prune.status = pruned.ok ? 'done' : 'failed';
@@ -842,12 +1072,7 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
     addBlocker(receipt, `WORKTREE_PRUNE_FAILED: ${receipt.prune.reason}`);
   }
 
-  receipt.complete = receipt.blockers.length === 0
-    && ['removed', 'already_removed'].includes(receipt.worktree.status)
-    && ['removed', 'already_removed'].includes(receipt.checkoutRegistry.status)
-    && (deleteBranch
-      ? ['deleted', 'already_deleted', 'archived'].includes(receipt.branchCleanup.status)
-      : receipt.branchCleanup.status === 'retained');
+  receipt.complete = cleanupReceiptComplete(receipt, deleteBranch);
   receipt.partial = !receipt.complete;
   if (receipt.complete) receipt.completedAt = receipt.completedAt ?? nowIso();
 
@@ -880,6 +1105,91 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
   return { handle: current, receipt };
 }
 
+export interface SingleTerminalWorkCleanupResult {
+  status: 'cleaned' | 'retained' | 'blocked' | 'no_handle' | 'not_terminal';
+  workId: string;
+  handle?: WorkHandleState;
+  receipt?: WorkCleanupReceipt;
+  reason?: string;
+}
+
+/**
+ * Reconcile physical resources for one already-terminal Work without reviving its
+ * historical execution principal. WorkContract remains the terminal outcome
+ * authority; this path owns only resource cleanup and refuses unproven active
+ * Controller ownership or unsafe branch drift. A caller proving the exact
+ * leftover owner epoch may release it before physical cleanup.
+ */
+export async function reconcileSingleTerminalWorkCleanup(
+  controllerHome: string,
+  repositoryId: string,
+  workId: string,
+  options: {
+    targetBranch?: string;
+    deleteBranch?: boolean;
+    /** Recovery authority for the narrow crash window after semantic terminalization but before owner release. */
+    controllerAuthority?: ControllerTerminalizationAuthority;
+  } = {},
+): Promise<SingleTerminalWorkCleanupResult> {
+  const repository = getRepository(repositoryId, controllerHome, { includeRemoved: true });
+  const contract = getWorkContract({ controllerHome, repoId: repositoryId }, workId);
+  if (!contract || !isTerminalWorkContractStatus(contract.status)) {
+    return { status: 'not_terminal', workId, reason: 'Work is not terminal.' };
+  }
+  let controllerLease: WorkCleanupReceipt['ownership']['controllerLease'] = 'already_released';
+  const owner = getControllerSession({ controllerHome, repoId: repositoryId }, workId);
+  if (owner) {
+    const authority = options.controllerAuthority;
+    if (!authority) return { status: 'blocked', workId, reason: 'Active Controller ownership still exists.' };
+    const ownerAuthority = controllerTerminalizationAuthorityFromSession(owner);
+    if (!ownerAuthority
+      || ownerAuthority.controllerId !== authority.controllerId
+      || ownerAuthority.controllerType !== authority.controllerType
+      || ownerAuthority.principalId !== authority.principalId
+      || ownerAuthority.controllerInstanceId !== authority.controllerInstanceId
+      || ownerAuthority.claimGeneration !== authority.claimGeneration) {
+      return { status: 'blocked', workId, reason: 'Active Controller ownership does not match the cleanup authority.' };
+    }
+    const released = releaseControllerSessionWithAuthority(
+      { controllerHome, repoId: repositoryId },
+      { workId, actor: `terminal-cleanup:${workId}`, authority },
+    );
+    if (!released.allowed) {
+      return { status: 'blocked', workId, reason: `Active Controller ownership release fenced: ${released.reason}.` };
+    }
+    controllerLease = 'released';
+  }
+  const originalHandle = readWorkHandle(controllerHome, repositoryId, workId)
+    ?? recoverTerminalWorkHandle(controllerHome, repositoryId, workId);
+  if (!originalHandle) return { status: 'no_handle', workId };
+  if (cleanupRetainedByRequest(contract, originalHandle)) {
+    return { status: 'retained', workId, handle: originalHandle, receipt: originalHandle.cleanupReceipt };
+  }
+  const targetBranch = resolveWorkDeliveryTargetBranch(originalHandle, repository.defaultBranch, options.targetBranch);
+  const drift = reconcileLegacyTerminalBranchDrift(controllerHome, repository, originalHandle, targetBranch);
+  if (drift.blocker) return { status: 'blocked', workId, handle: drift.handle, reason: drift.blocker };
+  const cleaned = await cleanupTerminalWork({
+    controllerHome,
+    handle: drift.handle,
+    targetBranch,
+    deleteBranch: options.deleteBranch !== false,
+    terminalOutcome: terminalOutcomeForContract(contract),
+    failureReason: drift.handle.failureReason ?? drift.handle.finalization.lastError,
+  });
+  cleaned.receipt.ownership.controllerLease = controllerLease;
+  const persisted = writeWorkHandle(controllerHome, { ...cleaned.handle, cleanupReceipt: cleaned.receipt });
+  if (!cleaned.receipt.complete) {
+    return {
+      status: 'blocked',
+      workId,
+      handle: persisted,
+      receipt: cleaned.receipt,
+      reason: cleaned.receipt.blockers.join('; ') || cleaned.receipt.worktree.reason || cleaned.receipt.branchCleanup.reason || 'terminal cleanup incomplete',
+    };
+  }
+  return { status: 'cleaned', workId, handle: persisted, receipt: cleaned.receipt };
+}
+
 export async function reconcileTerminalWorkCleanups(
   controllerHome: string,
   options: TerminalWorkCleanupReconcileOptions = {},
@@ -915,7 +1225,13 @@ export async function reconcileTerminalWorkCleanups(
       const contract = record.value;
       if (knownWorkIds.has(contract.workId) || !isTerminalWorkContractStatus(contract.status)) continue;
       if (!contract.worktreeRef?.trim() || !existsSync(contract.worktreeRef)) continue;
-      const recovered = recoverTerminalWorkHandle(controllerHome, repository.repoId, contract.workId);
+      let recovered: WorkHandleState | undefined;
+      try {
+        recovered = recoverTerminalWorkHandle(controllerHome, repository.repoId, contract.workId);
+      } catch (error) {
+        report.errors.push({ workId: contract.workId, error: error instanceof Error ? error.message : String(error) });
+        continue;
+      }
       if (!recovered) continue;
       handles.push(recovered);
       knownWorkIds.add(recovered.workId);
@@ -924,16 +1240,31 @@ export async function reconcileTerminalWorkCleanups(
     handles.sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
     for (const originalHandle of handles) {
       report.scanned += 1;
-      const contract = getWorkContract({ controllerHome, repoId: repository.repoId }, originalHandle.workContractId ?? originalHandle.workId);
+      let contract: WorkContract | undefined;
+      try {
+        contract = getWorkContract({ controllerHome, repoId: repository.repoId }, originalHandle.workContractId ?? originalHandle.workId);
+      } catch (error) {
+        report.errors.push({ workId: originalHandle.workId, error: error instanceof Error ? error.message : String(error) });
+        continue;
+      }
       if (!contract || !isTerminalWorkContractStatus(contract.status)) {
         report.skippedNonTerminal.push(originalHandle.workId);
         continue;
       }
-      if (originalHandle.state === 'cleaned' && originalHandle.cleanupReceipt?.complete === true) continue;
       if (cleanupRetainedByRequest(contract, originalHandle)) {
         report.skippedRetained.push(originalHandle.workId);
         continue;
       }
+      if (originalHandle.state === 'cleaned' && originalHandle.cleanupReceipt?.complete === true) {
+        const targetBranch = resolveWorkDeliveryTargetBranch(originalHandle, repository.defaultBranch);
+        if (!cleanedManagedBranchRetirementCandidate(
+          repository,
+          contract,
+          originalHandle,
+          targetBranch,
+          true,
+        )) continue;
+      }
       // Reconstructing a missing handle is metadata recovery, not new Work activity.
       // Do not let that write reset the terminal-age grace period indefinitely.
       const terminalAt = recoveredWorkIds.has(originalHandle.workId)
@@ -950,7 +1281,7 @@ export async function reconcileTerminalWorkCleanups(
       }
       report.attempted += 1;
       try {
-        const targetBranch = repository.defaultBranch || 'main';
+        const targetBranch = resolveWorkDeliveryTargetBranch(originalHandle, repository.defaultBranch);
         const drift = reconcileLegacyTerminalBranchDrift(controllerHome, repository, originalHandle, targetBranch);
         if (drift.blocker) {
           report.blocked.push({ workId: originalHandle.workId, reason: drift.blocker });