@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/control-plane/execution/work-evidence-policy.ts

@@ -0,0 +1,200 @@
+import { reconcileVerificationHistory } from '../facade/check-normalization';
+import type { VerificationRecord, WorkContract } from '../facade/types';
+
+type ReconciledVerificationHistory = ReturnType<typeof reconcileVerificationHistory>;
+
+export interface WorkCompletionEvidenceEvaluation {
+  status: 'complete' | 'failed' | 'incomplete';
+  history: ReconciledVerificationHistory;
+  missingChecks: string[];
+  durableResultEvidence: boolean;
+  semanticAcceptanceComplete: boolean;
+  missingSemanticAcceptanceCriteria: string[];
+  reasons: string[];
+}
+
+export function verificationRecordAppliesToCurrentWorkspace(
+  record: VerificationRecord,
+  currentRevision?: string,
+  currentWorkspaceFingerprint?: string,
+): boolean {
+  if (currentRevision && record.sourceRevision && record.sourceRevision !== currentRevision) return false;
+  if (
+    currentWorkspaceFingerprint
+    && record.workspaceFingerprint
+    && record.workspaceFingerprint !== currentWorkspaceFingerprint
+  ) return false;
+  return true;
+}
+
+function isAuthoritativeCurrentWorkVerification(
+  work: WorkContract,
+  record: VerificationRecord,
+  currentRevision?: string,
+): boolean {
+  const receipt = record.receipt;
+  return Boolean(
+    currentRevision
+    && record.outcome === 'valid_pass'
+    && record.sourceRevision === currentRevision
+    && receipt
+    && receipt.repoId === work.repoId
+    && receipt.workId === work.workId
+    && receipt.checkId === record.checkId
+    && receipt.ok === true
+    && receipt.timedOut === false
+    && receipt.cancelled === false,
+  );
+}
+
+export interface WorkImplementationEvidenceEvaluation {
+  status: 'complete' | 'incomplete';
+  changedPaths: string[];
+  reasons: string[];
+}
+
+export function evaluateWorkImplementationEvidence(
+  work: WorkContract,
+  currentWorkspaceChangedPaths: readonly string[] = [],
+): WorkImplementationEvidenceEvaluation {
+  if (work.workKind !== 'repository_change') {
+    return { status: 'complete', changedPaths: [], reasons: [] };
+  }
+
+  const changedPaths = [...new Set(currentWorkspaceChangedPaths.map((path) => path.trim()).filter(Boolean))].sort();
+  if (changedPaths.length > 0) {
+    return { status: 'complete', changedPaths, reasons: [] };
+  }
+
+  return {
+    status: 'incomplete',
+    changedPaths: [],
+    reasons: ['Repository-change Work has no current net source changes relative to its base revision. Verification evidence cannot substitute for implementation evidence.'],
+  };
+}
+
+export function evaluateReadOnlyReviewSourceIdentity(
+  work: WorkContract,
+  currentRevision?: string,
+  currentWorkspaceChangedPaths?: readonly string[],
+): { status: 'complete' | 'incomplete'; reasons: string[] } {
+  if (work.workKind !== 'read_only_review') return { status: 'complete', reasons: [] };
+  const reasons: string[] = [];
+  if (!work.baseRevision?.trim()) reasons.push('Read-only review has no frozen base revision.');
+  if (!currentRevision?.trim()) reasons.push('Current source revision is unavailable, so unchanged-source proof is incomplete.');
+  if (work.baseRevision && currentRevision && work.baseRevision !== currentRevision) {
+    reasons.push(`Read-only review source drifted from frozen base ${work.baseRevision} to ${currentRevision}.`);
+  }
+  if (currentWorkspaceChangedPaths === undefined) {
+    reasons.push('Current workspace changed-path proof is unavailable for read-only review.');
+  } else if (currentWorkspaceChangedPaths.length > 0) {
+    reasons.push(`Read-only review workspace is not unchanged: ${[...new Set(currentWorkspaceChangedPaths)].slice(0, 12).join(', ')}.`);
+  }
+  return { status: reasons.length === 0 ? 'complete' : 'incomplete', reasons };
+}
+
+export function evaluateWorkCompletionEvidence(
+  work: WorkContract,
+  currentRevision?: string,
+  currentWorkspaceFingerprint?: string,
+  workBoundProcessEvidenceIds: readonly string[] = [],
+  currentWorkspaceChangedPaths?: readonly string[],
+): WorkCompletionEvidenceEvaluation {
+  const applicableCheckRefs = work.checkRefs.filter((record) =>
+    verificationRecordAppliesToCurrentWorkspace(record, currentRevision, currentWorkspaceFingerprint));
+  const history = reconcileVerificationHistory(
+    applicableCheckRefs.map((record) => ({ checkId: record.checkId, outcome: record.outcome, recordedAt: record.recordedAt })),
+  );
+  const missingChecks = work.checks.filter((checkId) => !history.validPasses.includes(checkId));
+  const readOnlySourceIdentity = evaluateReadOnlyReviewSourceIdentity(work, currentRevision, currentWorkspaceChangedPaths);
+  const readOnlyEvidence = work.readOnlyReviewEvidence;
+  const readOnlyEvidenceMatchesCurrentSource = Boolean(
+    work.workKind === 'read_only_review'
+    && readOnlyEvidence
+    && currentRevision
+    && readOnlyEvidence.sourceRevision === currentRevision
+    && (readOnlyEvidence.workspaceFingerprint === undefined
+      || currentWorkspaceFingerprint === undefined
+      || readOnlyEvidence.workspaceFingerprint === currentWorkspaceFingerprint),
+  );
+  const cleanReadOnlyReviewEvidence = Boolean(
+    readOnlyEvidenceMatchesCurrentSource
+    && readOnlySourceIdentity.status === 'complete'
+    && (readOnlyEvidence?.inspectedPaths.length ?? 0) > 0
+    && (readOnlyEvidence?.findings.length ?? 0) === 0,
+  );
+  const workEvidenceIds = work.evidenceRefs.flatMap((evidence) => [evidence.evidenceId, evidence.artifactId])
+    .map((value) => value?.trim())
+    .filter((value): value is string => Boolean(value));
+  const availableDurableEvidenceIds = new Set([
+    ...workEvidenceIds,
+    ...workBoundProcessEvidenceIds.map((value) => value.trim()).filter(Boolean),
+  ]);
+  const durableResultEvidence = availableDurableEvidenceIds.size > 0
+    || applicableCheckRefs.some((record) => isAuthoritativeCurrentWorkVerification(work, record, currentRevision))
+    || cleanReadOnlyReviewEvidence;
+  const requiresSemanticAcceptance = work.workKind === 'local_effect' && work.checks.length === 0;
+  const acceptedCriteria = new Set((work.semanticAcceptanceEvidence ?? [])
+    .filter((review) => review.evidenceIds.length > 0 && review.evidenceIds.every((evidenceId) => availableDurableEvidenceIds.has(evidenceId)))
+    .map((review) => review.criterion));
+  const missingSemanticAcceptanceCriteria = requiresSemanticAcceptance
+    ? work.acceptanceCriteria.filter((criterion) => !acceptedCriteria.has(criterion))
+    : [];
+  const semanticAcceptanceComplete = !requiresSemanticAcceptance
+    || (work.acceptanceCriteria.length > 0 && missingSemanticAcceptanceCriteria.length === 0);
+  const reasons: string[] = [];
+
+  if (history.acceptanceFailures.length > 0) {
+    reasons.push(`Acceptance checks failed: ${history.acceptanceFailures.join(', ')}.`);
+    return { status: 'failed', history, missingChecks, durableResultEvidence, semanticAcceptanceComplete, missingSemanticAcceptanceCriteria, reasons };
+  }
+  if (history.infrastructureIssues.length > 0) {
+    reasons.push(`Infrastructure issues remain: ${history.infrastructureIssues.join(', ')}.`);
+  }
+  if (history.invalidCheckIds.length > 0) {
+    reasons.push(`Invalid check ids remain: ${history.invalidCheckIds.join(', ')}.`);
+  }
+  if (missingChecks.length > 0) {
+    reasons.push(`Declared checks are missing valid_pass evidence: ${missingChecks.join(', ')}.`);
+  }
+  if (work.workKind === 'read_only_review') {
+    reasons.push(...readOnlySourceIdentity.reasons);
+    if (!readOnlyEvidence || readOnlyEvidence.inspectedPaths.length === 0) {
+      reasons.push('Read-only review has no persisted inspected-path evidence.');
+    } else if (!readOnlyEvidenceMatchesCurrentSource) {
+      reasons.push('Persisted read-only review evidence is stale for the current source/workspace identity.');
+    }
+    if ((readOnlyEvidence?.findings.length ?? 0) > 0) {
+      reasons.push(`Read-only review has unresolved semantic findings (${readOnlyEvidence!.findings.length}); clean no-change completion is not allowed.`);
+    }
+  }
+  if (work.checks.length === 0 && !durableResultEvidence) {
+    const staleWorkVerification = work.checkRefs.some((record) =>
+      Boolean(record.receipt)
+      && !verificationRecordAppliesToCurrentWorkspace(record, currentRevision, currentWorkspaceFingerprint));
+    reasons.push(staleWorkVerification
+      ? 'Work-bound verification evidence is stale for the current source/workspace identity.'
+      : 'No durable result evidence (evidenceId, artifactId, or current Work-bound verification receipt) was recorded for this no-check WorkContract.');
+  }
+  if (requiresSemanticAcceptance && !semanticAcceptanceComplete) {
+    reasons.push(work.acceptanceCriteria.length === 0
+      ? 'No-check local-effect Work has no declared acceptance criteria to review.'
+      : `Controller-reviewed semantic acceptance evidence is incomplete; missing criteria: ${missingSemanticAcceptanceCriteria.join(' | ')}.`);
+  }
+
+  const complete = history.infrastructureIssues.length === 0
+    && history.invalidCheckIds.length === 0
+    && missingChecks.length === 0
+    && (work.checks.length > 0 || durableResultEvidence)
+    && semanticAcceptanceComplete
+    && (work.workKind !== 'read_only_review' || cleanReadOnlyReviewEvidence);
+  return {
+    status: complete ? 'complete' : 'incomplete',
+    history,
+    missingChecks,
+    durableResultEvidence,
+    semanticAcceptanceComplete,
+    missingSemanticAcceptanceCriteria,
+    reasons,
+  };
+}

package/src/runtime/control-plane/execution/work-execution-support.ts

@@ -0,0 +1,386 @@
+import type { MultiRepositoryMcpToolContext } from '../../../cli/mcp/multi-repository';
+import { getRepository, listRepositories, selectRepositoryCheckout } from '../../../cli/repositories/registry';
+import { reconcileWorkValidation } from './work-validation-reconciler';
+import { assertControllerOwnershipAuthority, claimControllerSession, controllerSessionPrincipalId, getControllerSession, releaseControllerSessionWithAuthority, resumeControllerSession } from '../facade/controller-session-store';
+import { appendWorkEvidence, getWorkContract } from '../facade/work-contract-store';
+import { resolveLegacyWorkContractIdentity } from './execution-identity';
+import type { ExecutionSessionContext, SessionIdentity } from './session-store';
+import { currentControllerInstanceId, requireExecutionSession, updateExecutionSession } from './session-store';
+import type { WorkHandleState, WorkTerminalOutcome } from './work-handle-store';
+import { readWorkHandle, writeWorkHandle } from './work-handle-store';
+import { cleanupTerminalWork } from './work-terminal-cleanup';
+import { spawnSync } from 'child_process';
+import { writeControllerResult } from '../../evidence/result-store';
+
+
+const MAX_INLINE_RESULT_BYTES = 64 * 1024;
+
+export function makeBoundedWorkResult(ctx: MultiRepositoryMcpToolContext, session: ExecutionSessionContext, repoId: string, workIdValue: string | undefined, kind: 'inspection' | 'command' | 'validation' | 'finalization' | 'generic', value: Record<string, unknown>): Record<string, unknown> {
+  const serialized = JSON.stringify(value);
+  if (Buffer.byteLength(serialized, 'utf8') <= MAX_INLINE_RESULT_BYTES) return value;
+  const started = performance.now();
+  const stored = writeControllerResult({ controllerHome: ctx.controllerHome, repoId, sessionId: session.sessionId, principalId: session.principalId, workId: workIdValue, kind, value });
+  return {
+    summary: { itemCount: Array.isArray(value.items) ? value.items.length : undefined, truncated: true, warnings: ['Full result is available through the secure result reference.'] },
+    items: Array.isArray(value.items) ? value.items.slice(0, 25) : { preview: serialized.slice(0, 16_384) },
+    resultRef: stored.resultRef,
+    resultId: stored.resultId,
+    byteLength: stored.byteLength,
+    _resultPersistenceMs: Math.round((performance.now() - started) * 100) / 100,
+  };
+}
+
+export function principalFor(ctx: MultiRepositoryMcpToolContext): string {
+  return ctx.principalId?.trim() || `controller-issued:${ctx.controllerInstanceId ?? currentControllerInstanceId()}`;
+}
+
+export function identityFor(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): SessionIdentity {
+  return {
+    sessionId: typeof args.session_id === 'string' && args.session_id.trim() ? args.session_id.trim() : ctx.sessionId,
+    principalId: principalFor(ctx),
+    controllerInstanceId: ctx.controllerInstanceId ?? currentControllerInstanceId(),
+  };
+}
+
+export function requireSession(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): ExecutionSessionContext {
+  return requireExecutionSession(ctx.controllerHome, identityFor(ctx, args));
+}
+
+export function compactHandle(handle: WorkHandleState): Record<string, unknown> {
+  return {
+    workId: handle.workId, sessionId: handle.sessionId, repoId: handle.repositoryId, checkoutId: handle.checkoutId,
+    worktreePath: handle.worktreePath, branch: handle.branch, sourceCheckoutId: handle.sourceCheckoutId, goalId: handle.goalId, delegationVersion: handle.delegationVersion,
+    workContractId: handle.workContractId, baseCommit: handle.baseCommit, deliveryBaseCommit: handle.deliveryBaseCommit, expectedHead: handle.expectedHead,
+    permissionSnapshotVersion: handle.permissionSnapshotVersion, state: handle.state, managedWorktree: handle.managedWorktree,
+    createdAt: handle.createdAt, updatedAt: handle.updatedAt, finalization: handle.finalization,
+    ...(handle.failureReason ? { failureReason: handle.failureReason } : {}),
+    ...(handle.cleanupResponsibility ? { cleanupResponsibility: handle.cleanupResponsibility } : {}),
+    ...(handle.terminalResourceDisposition ? { terminalResourceDisposition: handle.terminalResourceDisposition } : {}),
+    ...(handle.cleanupReceipt ? { cleanupReceipt: handle.cleanupReceipt } : {}),
+  };
+}
+
+export function gitRevision(root: string, revision: string): string | undefined {
+  const output = spawnSync('git', ['-C', root, 'rev-parse', '--verify', `${revision}^{commit}`], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000 });
+  return output.status === 0 && typeof output.stdout === 'string' && output.stdout.trim() ? output.stdout.trim() : undefined;
+}
+
+export function gitHead(root: string): string | undefined {
+  return gitRevision(root, 'HEAD');
+}
+
+export function gitCommit(root: string, revision: string, label: string): string {
+  const output = spawnSync('git', ['-C', root, 'rev-parse', '--verify', `${revision}^{commit}`], {
+    encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000,
+  });
+  if (output.status !== 0 || output.error || typeof output.stdout !== 'string' || !output.stdout.trim()) {
+    throw new Error(`WORK_HEAD_ADOPTION_${label}_INVALID: ${revision}`);
+  }
+  return output.stdout.trim();
+}
+
+export function gitChangedPaths(root: string, previousHead: string, candidateHead: string): string[] {
+  const output = spawnSync('git', ['-C', root, 'diff', '--name-only', '-z', previousHead, candidateHead], {
+    encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000, maxBuffer: 8 * 1024 * 1024,
+  });
+  if (output.status !== 0 || output.error || typeof output.stdout !== 'string') {
+    throw new Error('WORK_HEAD_ADOPTION_CHANGED_PATHS_UNAVAILABLE');
+  }
+  return [...new Set(output.stdout.split('\0').filter(Boolean))].sort((left, right) => left.localeCompare(right));
+}
+
+export function gitMergeBase(root: string, leftHead: string, rightHead: string): string {
+  const output = spawnSync('git', ['-C', root, 'merge-base', leftHead, rightHead], {
+    encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000,
+  });
+  if (output.status !== 0 || output.error || typeof output.stdout !== 'string' || !output.stdout.trim()) {
+    throw new Error('WORK_HEAD_ADOPTION_SCOPE_BASE_UNAVAILABLE');
+  }
+  return output.stdout.trim();
+}
+
+export function selectWorkFinalizationTarget(
+  repository: ReturnType<typeof getRepository>,
+  handle: Pick<WorkHandleState, 'sourceCheckoutId' | 'checkoutId'>,
+) {
+  const preferredCheckoutId = handle.sourceCheckoutId?.trim();
+  if (preferredCheckoutId) {
+    try {
+      return selectRepositoryCheckout(repository, preferredCheckoutId, { allowArchived: true });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      // Legacy Work can outlive the registry entry for the source checkout after
+      // an earlier partial cleanup. Git refs/worktree administration are
+      // repository-common operations, so fall back only for a positively
+      // identified missing/removed source checkout; all other errors fail closed.
+      if (!message.startsWith('CHECKOUT_NOT_ACTIVE:') && !message.startsWith('checkout not found for ')) throw error;
+    }
+  }
+  return repository;
+}
+
+export function workReturnCheckoutId(
+  ctx: MultiRepositoryMcpToolContext,
+  handle: Pick<WorkHandleState, 'repositoryId' | 'sourceCheckoutId' | 'checkoutId'>,
+  fallbackCheckoutId?: string,
+): string | undefined {
+  const repository = getRepository(handle.repositoryId, ctx.controllerHome, { includeRemoved: true });
+  const target = selectWorkFinalizationTarget(repository, handle);
+  return target.activeCheckoutId ?? repository.activeCheckoutId ?? fallbackCheckoutId;
+}
+
+export function contractFor(ctx: MultiRepositoryMcpToolContext, handle: WorkHandleState) {
+  // WorkContract is the semantic lifecycle authority. Legacy WorkHandles can
+  // predate the explicit workContractId binding, but their exact workId is the
+  // same stable authority key inside the same repository. Falling back only to
+  // that exact id keeps cleanup fail-closed without inventing a second lookup or
+  // fuzzy ownership rule.
+  const workContractId = handle.workContractId?.trim() || handle.workId;
+  return getWorkContract({ controllerHome: ctx.controllerHome, repoId: handle.repositoryId }, workContractId);
+}
+
+export function findWorkHandle(
+  ctx: MultiRepositoryMcpToolContext,
+  session: ExecutionSessionContext,
+  args: Record<string, unknown>,
+): WorkHandleState {
+  const requested = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  const workIdValue = requested || session.activeWorkId || '';
+  if (!workIdValue) throw new Error('WORK_ID_REQUIRED: provide work_id or call work_prepare first');
+  const requestedRepoId = typeof args.repo_id === 'string' && args.repo_id.trim() ? args.repo_id.trim() : undefined;
+  const requestedCheckoutId = typeof args.checkout_id === 'string' && args.checkout_id.trim()
+    ? args.checkout_id.trim()
+    : undefined;
+  const repoCandidates = [
+    requestedRepoId,
+    session.activeRepositoryId,
+  ].filter((value, index, values): value is string => Boolean(value) && values.indexOf(value) === index);
+  for (const repositoryId of repoCandidates) {
+    const handle = readWorkHandle(ctx.controllerHome, repositoryId, workIdValue);
+    if (!handle) continue;
+    if (requestedCheckoutId && handle.checkoutId !== requestedCheckoutId) {
+      throw new Error(
+        `WORK_HANDLE_CHECKOUT_DRIFT: work ${workIdValue} is bound to checkout ${handle.checkoutId}, not ${requestedCheckoutId}`,
+      );
+    }
+    return handle;
+  }
+  const matches = listRepositories(ctx.controllerHome, { includeRemoved: true })
+    .map((repository) => readWorkHandle(ctx.controllerHome, repository.repoId, workIdValue))
+    .filter((handle): handle is WorkHandleState => Boolean(handle));
+  // Legacy incomplete identity: only a unique exact WorkHandle match may execute.
+  return resolveLegacyWorkContractIdentity({
+    workId: workIdValue,
+    repoId: requestedRepoId,
+    checkoutId: requestedCheckoutId,
+    candidates: matches,
+  });
+}
+
+function currentControllerClaimAuthorizesTerminalCleanup(
+  ctx: MultiRepositoryMcpToolContext,
+  session: ExecutionSessionContext,
+  handle: WorkHandleState,
+): boolean {
+  if (!terminalCleanupOutcome(ctx, handle)) return false;
+  const workIdValue = handle.workContractId ?? handle.workId;
+  const owner = getControllerSession({ controllerHome: ctx.controllerHome, repoId: handle.repositoryId }, workIdValue);
+  if (!owner) return false;
+  return controllerSessionPrincipalId(owner) === session.principalId
+    && owner.controllerInstanceId === session.controllerInstanceId;
+}
+
+export function workForSession(
+  ctx: MultiRepositoryMcpToolContext,
+  session: ExecutionSessionContext,
+  args: Record<string, unknown>,
+  options: { reconcileValidation?: boolean; allowClaimedTerminalCleanup?: boolean } = {},
+): WorkHandleState {
+  let handle = findWorkHandle(ctx, session, args);
+  if (
+    handle.principalId !== session.principalId
+    && !(options.allowClaimedTerminalCleanup === true && currentControllerClaimAuthorizesTerminalCleanup(ctx, session, handle))
+  ) throw new Error('WORK_HANDLE_PRINCIPAL_MISMATCH: work handle belongs to another principal');
+  if (options.reconcileValidation !== false) handle = reconcileWorkValidation(ctx.controllerHome, handle).handle;
+  if (
+    session.activeRepositoryId !== handle.repositoryId
+    || session.activeCheckoutId !== handle.checkoutId
+    || session.activeWorkId !== handle.workId
+  ) {
+    updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), {
+      activeRepositoryId: handle.repositoryId,
+      activeCheckoutId: handle.checkoutId,
+      activeWorkId: handle.workId,
+      permissionSnapshotVersion: handle.permissionSnapshotVersion,
+      lastValidatedAt: new Date().toISOString(),
+    });
+  }
+  return handle;
+}
+
+export function assertWorkControllerOwnership(
+  ctx: MultiRepositoryMcpToolContext,
+  session: ExecutionSessionContext,
+  handle: WorkHandleState,
+  args: Record<string, unknown>,
+) {
+  const workIdValue = handle.workContractId ?? handle.workId;
+  const options = { controllerHome: ctx.controllerHome, repoId: handle.repositoryId };
+  const owner = getControllerSession(options, workIdValue);
+  const controllerId = typeof args.controller_id === 'string' && args.controller_id.trim()
+    ? args.controller_id.trim()
+    : session.principalId;
+  if (controllerId !== session.principalId) {
+    throw new Error('WORK_CONTROLLER_IDENTITY_MISMATCH: controller_id must match the authenticated principal');
+  }
+  if (owner) {
+    const authority = assertControllerOwnershipAuthority(owner, {
+      workId: workIdValue,
+      controllerId,
+      principalId: session.principalId,
+      controllerInstanceId: session.controllerInstanceId,
+    });
+    const resumed = resumeControllerSession(options, {
+      workId: workIdValue,
+      controllerId,
+      controllerType: authority.controllerType,
+      sessionId: session.sessionId,
+      principalId: session.principalId,
+      controllerInstanceId: session.controllerInstanceId,
+      expectedClaimGeneration: authority.claimGeneration,
+      leaseMs: 3_600_000,
+    });
+    if (
+      resumed.controllerId !== authority.controllerId
+      || controllerSessionPrincipalId(resumed) !== authority.principalId
+      || resumed.controllerInstanceId !== authority.controllerInstanceId
+      || resumed.claimGeneration !== authority.claimGeneration
+    ) {
+      throw new Error(`WORK_CONTROLLER_OWNER_MISMATCH: ${workIdValue} ownership epoch changed during resume`);
+    }
+    return resumed;
+  }
+  return claimControllerSession(options, {
+    workId: workIdValue,
+    controllerId,
+    controllerType: 'chatgpt',
+    sessionId: session.sessionId,
+    principalId: session.principalId,
+    controllerInstanceId: session.controllerInstanceId,
+    expectedClaimGeneration: 0,
+    leaseMs: 3_600_000,
+  });
+}
+
+export function releasePreparedWorkOwnership(
+  ctx: MultiRepositoryMcpToolContext,
+  handle: WorkHandleState,
+): 'released' | 'already_released' {
+  const workIdValue = handle.workContractId ?? handle.workId;
+  const options = { controllerHome: ctx.controllerHome, repoId: handle.repositoryId };
+  const current = getControllerSession(options, workIdValue);
+  if (!current) return 'already_released';
+
+  const callerPrincipal = principalFor(ctx);
+  const callerInstanceId = ctx.controllerInstanceId ?? currentControllerInstanceId();
+  const ownerPrincipal = current.principalId?.trim() || current.controllerId;
+  const ownerInstanceId = current.controllerInstanceId?.trim() || '';
+  if (ownerPrincipal !== callerPrincipal) {
+    throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${workIdValue}`);
+  }
+  if (!ownerInstanceId || ownerInstanceId !== callerInstanceId) {
+    throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${workIdValue}`);
+  }
+  if (typeof current.claimGeneration !== 'number' || current.claimGeneration < 1) {
+    throw new Error(`WORK_CONTROLLER_CLAIM_GENERATION_REQUIRED: ${workIdValue}`);
+  }
+
+  const released = releaseControllerSessionWithAuthority(options, {
+    workId: workIdValue,
+    actor: `legacy-work-release:${callerPrincipal}:${callerInstanceId}`,
+    authority: {
+      controllerId: current.controllerId,
+      controllerType: current.controllerType,
+      principalId: ownerPrincipal,
+      controllerInstanceId: ownerInstanceId,
+      claimGeneration: current.claimGeneration,
+    },
+  });
+  if (!released.allowed) {
+    throw new Error(`WORK_CONTROLLER_RELEASE_FENCED: ${workIdValue}:${released.reason}`);
+  }
+  return 'released';
+}
+
+export function terminalCleanupOutcome(
+  ctx: MultiRepositoryMcpToolContext,
+  handle: WorkHandleState,
+): WorkTerminalOutcome | undefined {
+  if (handle.cleanupReceipt) return handle.cleanupReceipt.terminalOutcome;
+  const contract = contractFor(ctx, handle);
+  if (contract?.status === 'cancelled') return 'cancelled';
+  if (contract?.status === 'completed') return 'completed_cleanup';
+  const reason = `${handle.failureReason ?? ''} ${handle.finalization.lastError ?? ''}`.toLowerCase();
+  if (contract?.status === 'blocked' && reason.includes('terminal')) return 'blocked_terminal';
+  // `failed` is a retryable execution-handle state (its transition table allows
+  // failed -> validating/editing). Do not reinterpret it as terminal cleanup
+  // unless the durable Work itself is terminal. `failed_terminal_cleanup` is
+  // the explicit point of no return for resource cleanup reconciliation.
+  if (contract?.status === 'failed' || handle.state === 'failed_terminal_cleanup') {
+    if (reason.includes('infrastructure') || reason.includes('timed out') || reason.includes('unavailable')) {
+      return 'infrastructure_failed';
+    }
+    if (handle.finalization.validation === 'failed') return 'validation_failed';
+    return 'failed';
+  }
+  return undefined;
+}
+
+export async function reconcileTerminalCleanup(
+  ctx: MultiRepositoryMcpToolContext,
+  session: ExecutionSessionContext,
+  handle: WorkHandleState,
+  args: Record<string, unknown>,
+  outcome: WorkTerminalOutcome,
+): Promise<Record<string, unknown>> {
+  const wasComplete = handle.cleanupReceipt?.complete === true;
+  const cleaned = await cleanupTerminalWork({
+    controllerHome: ctx.controllerHome,
+    handle,
+    targetBranch: typeof args.target_branch === 'string' ? args.target_branch : undefined,
+    deleteBranch: args.delete_branch !== false,
+    terminalOutcome: outcome,
+    failureReason: handle.failureReason ?? handle.finalization.lastError,
+  });
+  const ownership = releasePreparedWorkOwnership(ctx, cleaned.handle);
+  cleaned.receipt.ownership.controllerLease = ownership;
+  const persisted = writeWorkHandle(ctx.controllerHome, {
+    ...cleaned.handle,
+    cleanupReceipt: cleaned.receipt,
+  });
+  updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), {
+    activeWorkId: undefined,
+    activeCheckoutId: workReturnCheckoutId(ctx, persisted, session.activeCheckoutId),
+  });
+  if (cleaned.receipt.complete && !wasComplete) {
+    appendWorkEvidence(
+      { controllerHome: ctx.controllerHome, repoId: persisted.repositoryId },
+      persisted.workContractId ?? persisted.workId,
+      {
+        title: 'terminal cleanup receipt',
+        summary: `Cleanup ${cleaned.receipt.receiptId} completed for ${outcome}; Work outcome was preserved and no completion receipt was fabricated.`,
+        detailLevel: 'summary',
+      },
+    );
+  }
+  return {
+    work: compactHandle(persisted),
+    stages: persisted.finalization,
+    completed: false,
+    cleanupCompleted: cleaned.receipt.complete,
+    cleanupPartial: cleaned.receipt.partial,
+    failurePreserved: true,
+    cleanupReceipt: cleaned.receipt,
+    idempotent: wasComplete,
+  };
+}