@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/control-plane/execution/work-remote-delivery.ts

@@ -0,0 +1,215 @@
+import { spawnSync } from 'child_process';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import { getWorkContract } from '../facade/work-contract-store';
+import { isTerminalWorkContractStatus } from '../facade/types';
+import { executeRepositoryCommandViaProcessRuntime, waitRepositoryCommandProcess } from '../../execution/process-runtime/command-facade';
+import { executionIdentityForRepository } from './execution-identity';
+
+export interface WorkRemoteDeliveryReceipt {
+  targetBranch: string;
+  targetRevision: string;
+  remoteRevisionBefore: string;
+  remoteRevisionAfter: string;
+  pushed: boolean;
+}
+
+function gitText(root: string, args: string[], timeoutMs = 30_000): string {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: timeoutMs,
+  });
+  if (result.status !== 0 || result.error || typeof result.stdout !== 'string') {
+    throw new Error(`WORK_REMOTE_DELIVERY_GIT_FAILED: git ${args[0] ?? 'command'} failed`);
+  }
+  return result.stdout.trim();
+}
+
+function gitSucceeds(root: string, args: string[]): boolean {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 15_000,
+  });
+  return result.status === 0 && !result.error;
+}
+
+function exactRevision(root: string, revision: string, label: string): string {
+  const value = gitText(root, ['rev-parse', '--verify', `${revision}^{commit}`]);
+  if (!/^[a-f0-9]{40}$/i.test(value)) throw new Error(`WORK_REMOTE_DELIVERY_${label}_INVALID`);
+  return value;
+}
+
+function assertTargetBranch(root: string, targetBranch: string): void {
+  if (!targetBranch.trim() || !gitSucceeds(root, ['check-ref-format', '--branch', targetBranch])) {
+    throw new Error(`WORK_REMOTE_DELIVERY_TARGET_BRANCH_INVALID: ${targetBranch || 'missing'}`);
+  }
+}
+
+function assertActiveWork(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+}): void {
+  const contract = getWorkContract(
+    { controllerHome: input.controllerHome, repoId: input.repository.repoId },
+    input.workId,
+  );
+  if (
+    !contract
+    || contract.repoId !== input.repository.repoId
+    || (contract.checkoutId && contract.checkoutId !== input.repository.activeCheckoutId)
+    || isTerminalWorkContractStatus(contract.status)
+    || Boolean(contract.completionReceipt)
+  ) {
+    throw new Error(`WORK_REMOTE_DELIVERY_ACTIVE_AUTHORITY_REQUIRED: ${input.workId}`);
+  }
+}
+
+function remoteHead(root: string, targetBranch: string): string {
+  const line = gitText(root, ['ls-remote', '--heads', 'origin', `refs/heads/${targetBranch}`])
+    .split(/\r?\n/)
+    .find(Boolean);
+  const revision = line?.split(/\s+/)[0] ?? '';
+  if (!/^[a-f0-9]{40}$/i.test(revision)) {
+    throw new Error(`WORK_REMOTE_DELIVERY_REMOTE_BRANCH_MISSING: origin/${targetBranch}`);
+  }
+  return revision;
+}
+
+async function executeGit(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  command: string[];
+  timeoutMs: number;
+  commandId: string;
+}): Promise<{ ok: boolean; detail: string }> {
+  const result = await executeRepositoryCommandViaProcessRuntime({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    command: input.command,
+    timeoutMs: input.timeoutMs,
+    interactiveWaitMs: Math.min(5_000, input.timeoutMs),
+    maxOutputBytes: 256 * 1024,
+    workId: input.workId,
+    commandId: input.commandId,
+    executionIdentity: executionIdentityForRepository(input.repository, { workId: input.workId }),
+  });
+  if (result.route === 'reject' || result.route === 'durable') {
+    return { ok: false, detail: result.reason ?? result.route };
+  }
+  if (result.process && !result.process.completed) {
+    const waited = await waitRepositoryCommandProcess(
+      input.controllerHome,
+      input.repository.repoId,
+      result.process.processId,
+      { timeoutMs: input.timeoutMs },
+    );
+    return { ok: waited.ok === true, detail: waited.stderr ?? waited.stdout ?? '' };
+  }
+  return {
+    ok: result.ok === true || result.process?.ok === true,
+    detail: result.stderr ?? result.stdout ?? result.process?.stderr ?? result.process?.stdout ?? '',
+  };
+}
+
+async function fetchRemoteTipObject(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  targetBranch: string;
+  timeoutMs: number;
+}): Promise<void> {
+  const fetched = await executeGit({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    workId: input.workId,
+    command: ['git', 'fetch', '--no-tags', '--no-write-fetch-head', 'origin', `refs/heads/${input.targetBranch}`],
+    timeoutMs: input.timeoutMs,
+    commandId: `work-remote-delivery-fetch:${input.workId}:${input.targetBranch}`,
+  });
+  if (!fetched.ok) {
+    throw new Error(`WORK_REMOTE_DELIVERY_FETCH_FAILED: ${fetched.detail || `origin/${input.targetBranch}`}`);
+  }
+}
+
+async function observedRemoteContainsTarget(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  targetBranch: string;
+  targetRevision: string;
+  remoteRevision: string;
+  timeoutMs: number;
+}): Promise<boolean> {
+  await fetchRemoteTipObject(input);
+  if (!gitSucceeds(input.repository.canonicalRoot, ['cat-file', '-e', `${input.remoteRevision}^{commit}`])) {
+    throw new Error(`WORK_REMOTE_DELIVERY_REMOTE_OBJECT_UNAVAILABLE: ${input.remoteRevision}`);
+  }
+  return gitSucceeds(
+    input.repository.canonicalRoot,
+    ['merge-base', '--is-ancestor', input.targetRevision, input.remoteRevision],
+  );
+}
+
+export async function pushExactWorkRemoteDelivery(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  targetBranch: string;
+  targetRevision: string;
+  timeoutMs?: number;
+}): Promise<WorkRemoteDeliveryReceipt> {
+  assertTargetBranch(input.repository.canonicalRoot, input.targetBranch);
+  assertActiveWork(input);
+  const targetRevision = exactRevision(input.repository.canonicalRoot, input.targetRevision, 'TARGET_REVISION');
+  const timeoutMs = Math.min(Math.max(input.timeoutMs ?? 120_000, 5_000), 120_000);
+  const remoteRevisionBefore = remoteHead(input.repository.canonicalRoot, input.targetBranch);
+
+  if (await observedRemoteContainsTarget({ ...input, targetRevision, remoteRevision: remoteRevisionBefore, timeoutMs })) {
+    return {
+      targetBranch: input.targetBranch,
+      targetRevision,
+      remoteRevisionBefore,
+      remoteRevisionAfter: remoteRevisionBefore,
+      pushed: false,
+    };
+  }
+  if (!gitSucceeds(input.repository.canonicalRoot, ['merge-base', '--is-ancestor', remoteRevisionBefore, targetRevision])) {
+    throw new Error(`WORK_REMOTE_DELIVERY_REMOTE_DIVERGED: ${remoteRevisionBefore} is not an ancestor of ${targetRevision}`);
+  }
+
+  // Re-read durable authority immediately before the only remote mutation. A
+  // terminal Work may be inspected/reconciled, but it can never be reused as
+  // authority for an arbitrary post-finalize push.
+  assertActiveWork(input);
+  const pushed = await executeGit({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    workId: input.workId,
+    command: ['git', 'push', '--porcelain', 'origin', `${targetRevision}:refs/heads/${input.targetBranch}`],
+    timeoutMs,
+    commandId: `work-remote-delivery-push:${input.workId}:${targetRevision}`,
+  });
+
+  const remoteRevisionAfter = remoteHead(input.repository.canonicalRoot, input.targetBranch);
+  const delivered = await observedRemoteContainsTarget({
+    ...input,
+    targetRevision,
+    remoteRevision: remoteRevisionAfter,
+    timeoutMs,
+  });
+  if (!delivered) {
+    throw new Error(
+      `WORK_REMOTE_DELIVERY_PUSH_FAILED: ${pushed.detail || `${targetRevision} is not reachable from origin/${input.targetBranch}`}`,
+    );
+  }
+  return {
+    targetBranch: input.targetBranch,
+    targetRevision,
+    remoteRevisionBefore,
+    remoteRevisionAfter,
+    pushed: pushed.ok,
+  };
+}

package/src/runtime/control-plane/execution/work-task-receipt.ts

@@ -3,8 +3,8 @@ import { spawnSync } from 'child_process';
 import { getIssue, listIssues, recordTaskVerification, acceptVerifiedTask, projectTaskFromWork } from '../../../cli/controller/issue-store';
 import { resolveCompletionTargetBranch } from '../../../cli/controller/completion-target';
 import type { CompletionReceipt, ControllerIssue } from '../../../cli/controller/types';
-import { completeRequirementFromWork } from '../persistence/requirement-store';
-import { getWorkContract, recordWorkCompletionReceipt, updateWorkContract } from '../facade/work-contract-store';
+import { getWorkContract, updateWorkContract } from '../facade/work-contract-store';
+import { completeWorkWithReceipt } from './work-completion-authority';
 import { isRepositoryCompletionReceipt, WORK_RECONCILIATION_METHODS, WORK_RECONCILIATION_OUTCOMES } from '../facade/types';
 import type {
   WorkReconciliationMethod,
@@ -27,7 +27,7 @@ function commitRevision(repoRoot: string, revision: string | undefined, label: s
   return gitText(repoRoot, ['rev-parse', `${revision.trim()}^{commit}`]);
 }
 
-function changedPaths(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
+export function changedPaths(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
   const result = spawnSync('git', ['diff', '--name-only', '-z', baseRevision, targetRevision], {
     cwd: repoRoot,
     encoding: 'utf-8',
@@ -39,6 +39,22 @@ function changedPaths(repoRoot: string, baseRevision: string, targetRevision: st
   return [...new Set(result.stdout.split('\0').filter(Boolean))].sort();
 }
 
+
+function completionReceiptChangedPaths(
+  contract: NonNullable<ReturnType<typeof getWorkContract>>,
+  repoRoot: string,
+  baseRevision: string,
+  targetRevision: string,
+): string[] {
+  const reconciled = contract.reconciliations.find((entry) =>
+    entry.outcome === 'accepted_equivalence'
+    && entry.reachable
+    && entry.baseRevision === baseRevision
+    && entry.observedTargetRevision === targetRevision);
+  if (!reconciled) return changedPaths(repoRoot, baseRevision, targetRevision);
+  return [...new Set(reconciled.comparedPaths.map((path) => path.trim()).filter(Boolean))].sort();
+}
+
 function assertWorkNotBoundElsewhere(repoRoot: string, workId: string, issueId: string, taskId: string): void {
   for (const issue of listIssues(repoRoot)) {
     for (const task of issue.tasks) {
@@ -273,19 +289,13 @@ export function acceptVerifiedTaskFromReviewedWorkReconciliation(input: Controll
     recordedAt,
   };
   const completionOutcome = noChange ? 'completed_no_change' : contract.workKind === 'remote_effect' ? 'completed_remote' : 'completed_changed';
-  const recorded = recordWorkCompletionReceipt(
+  const recorded = completeWorkWithReceipt(
     { controllerHome: input.controllerHome, repoId: input.repoId },
     input.workId,
     receipt,
     completionOutcome,
     contract.workKind,
   );
-  if (recorded.requirementId) {
-    completeRequirementFromWork(
-      { controllerHome: input.controllerHome },
-      { requirementId: recorded.requirementId, work: recorded },
-    );
-  }
   const recordedReceipt = recorded.completionReceipt;
   const projectedReceipt = recordedReceipt && isRepositoryCompletionReceipt(recordedReceipt) ? recordedReceipt : receipt;
   const projectedVerification = { ...task.verification!, completionReceipt: projectedReceipt };
@@ -361,7 +371,7 @@ export function acceptVerifiedTaskFromControllerWork(input: ControllerWorkTaskRe
   }
   assertCurrentRequiredChecks(contract, targetRevision);
   const baseRevision = commitRevision(input.repoRoot, handle.baseCommit, 'BASE_REVISION');
-  const receiptChangedPaths = changedPaths(input.repoRoot, baseRevision, targetRevision);
+  const receiptChangedPaths = completionReceiptChangedPaths(contract, input.repoRoot, baseRevision, targetRevision);
   if (noChange && receiptChangedPaths.length > 0) {
     throw new Error(`CONTROLLER_WORK_RECEIPT_NO_CHANGE_DIRTY: ${input.workId}`);
   }
@@ -409,18 +419,12 @@ export function acceptVerifiedTaskFromControllerWork(input: ControllerWorkTaskRe
   // historical Task write is interrupted, the Work authority is still
   // durable and a retry can safely rebuild the projection.
   const completionOutcome = noChange ? 'completed_no_change' : contract.workKind === 'remote_effect' ? 'completed_remote' : 'completed_changed';
-  const recorded = recordWorkCompletionReceipt(
+  const recorded = completeWorkWithReceipt(
     { controllerHome: input.controllerHome, repoId: input.repoId },
     input.workId,
     receipt,
     completionOutcome,
   );
-  if (recorded.requirementId) {
-    completeRequirementFromWork(
-      { controllerHome: input.controllerHome },
-      { requirementId: recorded.requirementId, work: recorded },
-    );
-  }
   const recordedReceipt = recorded.completionReceipt;
   const projectedReceipt = recordedReceipt && isRepositoryCompletionReceipt(recordedReceipt) ? recordedReceipt : receipt;
   const projectedVerification = {

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

@@ -8,16 +8,18 @@ import {
   writeFileSync,
 } from 'fs';
 import { dirname, join, resolve } from 'path';
-import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { repoLocalNoIndexControllerHome, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import {
   getRepository,
   listRepositories,
   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, releaseControllerSession } from '../facade/controller-session-store';
+import { getControllerSession, releaseObservedControllerSession } from '../facade/controller-session-store';
 import { isRepositoryCompletionReceipt, isTerminalWorkContractStatus, type WorkContract } from '../facade/types';
 import {
   cancelProcess,
@@ -30,6 +32,7 @@ import {
 import { getProcessRecord, listProcessRecords } from '../../execution/process-runtime/store';
 import {
   listWorkHandles,
+  readWorkHandle,
   transitionWorkHandle,
   writeWorkHandle,
   type WorkCleanupReceipt,
@@ -391,6 +394,42 @@ function selectTerminalCleanupTarget(repository: ReturnType<typeof getRepository
   return repository;
 }
 
+function isCurrentControllerManagedWorktree(
+  controllerHome: string,
+  worktreePath: string,
+): boolean {
+  try {
+    const storageRoot = managedWorktreeStorageRoot(
+      controllerHome,
+      listRepositories(controllerHome, { includeRemoved: true }),
+    );
+    if (managedPathInside(storageRoot, worktreePath)) return true;
+    // Older Controller releases used a namespaced sibling of controller/.
+    // Accept only namespaces whose source Home appears in this target's
+    // controlled migration receipt; then let the caller's Git common-dir,
+    // branch, cleanliness, and preservation checks prove the exact Work before
+    // any removal.
+    const sourceHomes = new Set<string>([resolve(controllerHome)]);
+    for (const record of listControlPlaneRecords<{ sourceHome?: unknown; status?: unknown }>(controllerHome, {
+      namespace: 'controller_home_migration',
+      limit: 1_000,
+    })) {
+      if (record.value.status !== 'applied' || typeof record.value.sourceHome !== 'string') continue;
+      const sourceHome = resolve(record.value.sourceHome);
+      sourceHomes.add(sourceHome);
+      const physical = repoLocalNoIndexControllerHome(sourceHome);
+      if (physical) sourceHomes.add(physical);
+    }
+    return [...sourceHomes].some((sourceHome) => {
+      const namespace = createHash('sha256').update(sourceHome).digest('hex').slice(0, 16);
+      const legacyRoot = join(dirname(resolve(controllerHome)), 'managed-worktrees', namespace);
+      return managedPathInside(legacyRoot, worktreePath);
+    });
+  } catch {
+    return false;
+  }
+}
+
 export interface TerminalWorkCleanupReconcileOptions {
   nowMs?: number;
   minAgeMs?: number;
@@ -417,11 +456,81 @@ function terminalOutcomeForContract(contract: WorkContract): WorkTerminalOutcome
   return 'failed';
 }
 
-function cleanupRetainedByRequest(contract: WorkContract, _handle: WorkHandleState): boolean {
+export function recoverTerminalWorkHandle(
+  controllerHome: string,
+  repositoryId: string,
+  workId: string,
+): WorkHandleState | undefined {
+  const existing = readWorkHandle(controllerHome, repositoryId, workId);
+  if (existing) return existing;
+  const contract = getWorkContract({ controllerHome, repoId: repositoryId }, workId);
+  if (!contract || !isTerminalWorkContractStatus(contract.status)) return undefined;
+  const worktreePath = contract.worktreeRef?.trim();
+  const checkoutId = contract.checkoutId?.trim();
+  if (!worktreePath || !checkoutId || !existsSync(worktreePath)) return undefined;
+  if (!isCurrentControllerManagedWorktree(controllerHome, worktreePath)) return undefined;
+
+  const repository = getRepository(repositoryId, controllerHome, { includeRemoved: true });
+  // Reconstruct physical cleanup authority from the recorded checkout entry itself.
+  // selectRepositoryCheckout returns a RepositoryRecord view rooted at a checkout,
+  // not the checkout entry (and terminal cleanup must also tolerate an already
+  // archived/removed registry lifecycle while the physical worktree still exists).
+  const checkout = repository.checkouts.find((candidate) => candidate.checkoutId === checkoutId);
+  if (!checkout || checkout.worktree !== true || resolve(checkout.canonicalRoot) !== resolve(worktreePath)) return undefined;
+  const branch = checkout.branch?.trim();
+  if (!branch) return undefined;
+
+  const head = git(worktreePath, ['rev-parse', 'HEAD']);
+  if (!head.ok || !head.stdout) return undefined;
+  const targetBranch = 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
+    : false;
+  const delivered = contract.status === 'completed' && contained;
+  const session = getControllerSession({ controllerHome, repoId: repositoryId }, workId);
+  const recordedAt = nowIso();
+  return writeWorkHandle(controllerHome, {
+    schemaVersion: 1,
+    workId,
+    workContractId: workId,
+    sessionId: session?.sessionId ?? `terminal-recovery:${workId}`,
+    principalId: contract.principalId?.trim() || session?.principalId || 'terminal-recovery',
+    repositoryId,
+    checkoutId,
+    sourceCheckoutId: repository.activeCheckoutId,
+    worktreePath,
+    branch,
+    managedWorktree: true,
+    baseCommit: contract.baseRevision,
+    expectedHead: head.stdout,
+    permissionSnapshotVersion: 1,
+    state: delivered ? 'merged' : 'failed_terminal_cleanup',
+    failureReason: delivered ? undefined : 'Recovered terminal Work ownership for cleanup; target-branch containment was not proven.',
+    createdAt: contract.createdAt || recordedAt,
+    updatedAt: recordedAt,
+    cleanupResponsibility: { owner: 'work_finalizer', registeredAt: recordedAt },
+    finalization: {
+      validation: contract.status === 'failed' ? 'failed' : 'done',
+      commit: 'skipped',
+      merge: delivered ? 'done' : 'skipped',
+      branchCleanup: 'pending',
+      worktreeCleanup: 'pending',
+      ...(contract.status === 'failed' ? { lastError: 'Recovered failed terminal Work for cleanup.' } : {}),
+    },
+  });
+}
+
+function cleanupRetainedByRequest(contract: WorkContract, handle: WorkHandleState): boolean {
   // `skipped` in old WorkHandle finalization records was also used for legacy
   // no-op/error paths, so it is not sufficient proof of an explicit retention
-  // request. Only the completion receipt's dedicated maintenance warning is
-  // authoritative enough to suppress automatic reconciliation.
+  // request. New cancelled/terminal Work records persist an explicit physical
+  // resource disposition on the WorkHandle. Completed Work keeps the existing
+  // completion-receipt warning as the delivery authority.
+  if (
+    handle.terminalResourceDisposition?.mode === 'retained_by_request'
+    && handle.terminalResourceDisposition.retainWorktree === 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');
@@ -588,7 +697,10 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
     current = persist(input.controllerHome, current, receipt);
     return { handle: current, receipt };
   }
-  if (!registeredPath && existsSync(current.worktreePath)) {
+  const migratedManagedWorktree = !registeredPath
+    && existsSync(current.worktreePath)
+    && isCurrentControllerManagedWorktree(input.controllerHome, current.worktreePath);
+  if (!registeredPath && existsSync(current.worktreePath) && !migratedManagedWorktree) {
     addBlocker(receipt, 'CHECKOUT_NOT_CONTROLLER_REGISTERED');
     current = persist(input.controllerHome, current, receipt);
     return { handle: current, receipt };
@@ -686,6 +798,9 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
       addBlocker(receipt, `CHECKOUT_REGISTRY_REMOVE_FAILED: ${receipt.checkoutRegistry.reason}`);
     }
   }
+  if (!registeredPath && migratedManagedWorktree) {
+    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';
@@ -789,8 +904,24 @@ export async function reconcileTerminalWorkCleanups(
   const repositories = listRepositories(controllerHome).filter((repository) => repository.enabled && !repository.removedAt);
   outer: for (const repository of repositories) {
     const handles = listWorkHandles(controllerHome, repository.repoId, 10_000)
-      .filter((handle) => handle.managedWorktree)
-      .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+      .filter((handle) => handle.managedWorktree);
+    const knownWorkIds = new Set(handles.map((handle) => handle.workId));
+    const recoveredWorkIds = new Set<string>();
+    for (const record of listControlPlaneRecords<WorkContract>(controllerHome, {
+      namespace: 'work_contract',
+      scope: repository.repoId,
+      limit: 10_000,
+    })) {
+      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);
+      if (!recovered) continue;
+      handles.push(recovered);
+      knownWorkIds.add(recovered.workId);
+      recoveredWorkIds.add(recovered.workId);
+    }
+    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);
@@ -803,7 +934,11 @@ export async function reconcileTerminalWorkCleanups(
         report.skippedRetained.push(originalHandle.workId);
         continue;
       }
-      const terminalAt = Math.max(Date.parse(contract.updatedAt) || 0, Date.parse(originalHandle.updatedAt) || 0);
+      // 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)
+        ? (Date.parse(contract.updatedAt) || 0)
+        : Math.max(Date.parse(contract.updatedAt) || 0, Date.parse(originalHandle.updatedAt) || 0);
       if (terminalAt > 0 && nowMs - terminalAt < minAgeMs) {
         report.skippedRecent.push(originalHandle.workId);
         continue;
@@ -833,8 +968,18 @@ export async function reconcileTerminalWorkCleanups(
         const workId = cleaned.handle.workContractId ?? cleaned.handle.workId;
         const controllerSession = getControllerSession({ controllerHome, repoId: repository.repoId }, workId);
         if (controllerSession) {
-          releaseControllerSession({ controllerHome, repoId: repository.repoId }, workId, controllerSession.controllerId);
-          cleaned.receipt.ownership.controllerLease = 'released';
+          const released = releaseObservedControllerSession(
+            { controllerHome, repoId: repository.repoId },
+            { workId, actor: `terminal-cleanup:${originalHandle.workId}`, owner: controllerSession },
+          );
+          if (released.allowed) {
+            cleaned.receipt.ownership.controllerLease = 'released';
+          } else {
+            cleaned.receipt.complete = false;
+            cleaned.receipt.partial = true;
+            cleaned.receipt.completedAt = undefined;
+            cleaned.receipt.blockers = appendUnique(cleaned.receipt.blockers, `controller lease release fenced: ${released.reason}`);
+          }
         } else {
           cleaned.receipt.ownership.controllerLease = 'already_released';
         }

package/src/runtime/control-plane/execution/work-validation-reconciler.ts

@@ -166,27 +166,35 @@ export function reconcileWorkValidation(
     }
 
     try {
-      const currentIdentity = record.checkExecution
-        ? controllerCheckExecutionIdentity(handle.worktreePath, checkId, record.checkExecution.timeoutMs)
-        : undefined;
+      if (binding.checkExecution && binding.checkExecution.checkId !== checkId) {
+        throw new Error(
+          `PROCESS_CHECK_RECEIPT_IDENTITY_MISMATCH: bound check ${binding.checkExecution.checkId} != ${checkId}`,
+        );
+      }
+      const expectedCheckExecution = binding.checkExecution
+        ?? (record.checkExecution
+          ? controllerCheckExecutionIdentity(handle.worktreePath, checkId, record.checkExecution.timeoutMs)
+          : undefined);
       const receipt = processCheckCompletionReceipt(record, {
         repoId: handle.repositoryId,
         checkoutId: handle.checkoutId,
         workId: handle.workId,
         checkId,
         processId: binding.processId,
-        ...(currentIdentity ? {
+        ...(expectedCheckExecution ? {
           checkExecution: {
-            cacheKey: currentIdentity.cacheKey,
-            revision: currentIdentity.revision,
-            definitionDigest: currentIdentity.definitionDigest,
-            environmentFingerprint: currentIdentity.environmentFingerprint,
-            timeoutMs: currentIdentity.timeoutMs,
-            scopeKey: processCheckSemanticScopeKey({
-              checkoutId: handle.checkoutId,
-              workId: handle.workId,
-              verificationBinding: { executionSessionId: handle.sessionId },
-            }, currentIdentity.reuseScope),
+            cacheKey: expectedCheckExecution.cacheKey,
+            revision: expectedCheckExecution.revision,
+            definitionDigest: expectedCheckExecution.definitionDigest,
+            environmentFingerprint: expectedCheckExecution.environmentFingerprint,
+            timeoutMs: expectedCheckExecution.timeoutMs,
+            scopeKey: binding.checkExecution
+              ? binding.checkExecution.scopeKey
+              : processCheckSemanticScopeKey({
+                  checkoutId: handle.checkoutId,
+                  workId: handle.workId,
+                  verificationBinding: { executionSessionId: handle.sessionId },
+                }, expectedCheckExecution.reuseScope),
           },
         } : {}),
       });

package/src/runtime/control-plane/execution/work-verification-context.ts

@@ -0,0 +1,56 @@
+import { listControllerChecks, type ControllerCheck } from '../../../cli/controller/check-runner';
+import { selectRepositoryCheckout } from '../../../cli/repositories/registry';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import { getWorkContract } from '../facade/work-contract-store';
+import type { WorkContract } from '../facade/types';
+
+export interface WorkVerificationContext {
+  store: { controllerHome: string; repoId: string };
+  repository: RepositoryRecord;
+  workContract?: WorkContract;
+  checks: ControllerCheck[];
+}
+
+export type WorkVerificationContextResolution =
+  | { ok: true; context: WorkVerificationContext }
+  | { ok: false; code: 'WORK_VERIFICATION_CHECKOUT_UNAVAILABLE'; detail: string; workContract?: WorkContract };
+
+/**
+ * Resolve the only repository/check-registry context that may be used to verify
+ * a Work. A Work-bound checkout is semantic verification authority: if it can no
+ * longer be resolved, verification must fail closed instead of silently reading
+ * the canonical/main registry.
+ */
+export function resolveWorkVerificationContext(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId?: string;
+}): WorkVerificationContextResolution {
+  const store = { controllerHome: input.controllerHome, repoId: input.repository.repoId };
+  const workId = input.workId?.trim();
+  const workContract = workId ? getWorkContract(store, workId) : undefined;
+  let repository = input.repository;
+
+  if (workContract?.checkoutId) {
+    try {
+      repository = selectRepositoryCheckout(input.repository, workContract.checkoutId, { allowArchived: true });
+    } catch (error) {
+      return {
+        ok: false,
+        code: 'WORK_VERIFICATION_CHECKOUT_UNAVAILABLE',
+        detail: error instanceof Error ? error.message : 'Work checkout could not be resolved',
+        workContract,
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    context: {
+      store,
+      repository,
+      workContract,
+      checks: listControllerChecks(repository.canonicalRoot),
+    },
+  };
+}