@moretea-labs/forge 1.7.1 → 1.8.0

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

@@ -3,7 +3,7 @@ import { spawnSync } from 'child_process';
 import { getRepository, selectRepositoryCheckout, validateRepository } from '../../../cli/repositories/registry';
 import type { RepositoryRecord } from '../../../cli/repositories/types';
 import { readRepositoryAccessPolicy } from '../governance/access-policy';
-import { getWorkContract } from '../facade/work-contract-store';
+import { getWorkContract } from '../../../../packages/kernel/work/api/index';
 import type { WorkContract } from '../facade/types';
 import { requireExecutionSession, type ExecutionSessionContext, type SessionIdentity } from './session-store';
 import type { WorkHandleState } from './work-handle-store';
@@ -36,8 +36,33 @@ function gitSucceeds(root: string, args: string[]): boolean {
   return spawnSync('git', ['-C', root, ...args], { stdio: 'ignore', timeout: 10_000 }).status === 0;
 }
 
-function fail(code: string, message: string): never {
-  throw new Error(`${code}: ${message}`);
+export type WorkHandleValidationErrorCode =
+  | 'CHECKOUT_NOT_REGISTERED'
+  | 'REPOSITORY_NOT_EXECUTABLE'
+  | 'REPOSITORY_VALIDATION_FAILED'
+  | 'WORKTREE_INVALID'
+  | 'WORKTREE_MISSING'
+  | 'WORKTREE_PATH_MISMATCH'
+  | 'WORK_CONTRACT_MISSING'
+  | 'WORK_CONTRACT_REPOSITORY_MISMATCH'
+  | 'WORK_HANDLE_BRANCH_CHANGED'
+  | 'WORK_HANDLE_HEAD_CHANGED'
+  | 'WORK_HANDLE_LIFECYCLE_INVALID'
+  | 'WORK_HANDLE_PRINCIPAL_MISMATCH'
+  | 'WORK_HANDLE_STALE_PERMISSION';
+
+export class WorkHandleValidationError extends Error {
+  readonly code: WorkHandleValidationErrorCode;
+
+  constructor(code: WorkHandleValidationErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'WorkHandleValidationError';
+    this.code = code;
+  }
+}
+
+function fail(code: WorkHandleValidationErrorCode, message: string): never {
+  throw new WorkHandleValidationError(code, message);
 }
 
 export function currentPermissionSnapshotVersion(controllerHome: string, repoId: string): number {

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

@@ -0,0 +1,116 @@
+import { listControllerSessions } from '../../../../packages/kernel/controller/api/index';
+import { listSchedules, listActiveOccurrences } from '../../../../packages/kernel/scheduler/api/index';
+import { listWorkContracts, transitionWorkContractPhase, updateWorkContract } from '../../../../packages/kernel/work/api/index';
+import { listActiveLeases } from '../../resources/leases/store';
+import { listProcessRecords } from '../../execution/process-runtime/store';
+import { isManagedProcessActive } from '../../execution/process-runtime/types';
+import { listPlanContracts } from '../facade/plan-contract-store';
+import { listWorkHandles, type WorkHandleState } from './work-handle-store';
+
+const DEFAULT_OWNERLESS_WORK_GRACE_MS = 2 * 60 * 60_000;
+const TERMINAL_HANDLE_STATES = new Set<WorkHandleState['state']>(['cleaned', 'failed', 'failed_terminal_cleanup']);
+
+export interface OwnerlessWorkAuthorityReconcileOptions {
+  controllerHome: string;
+  repoId: string;
+  nowMs?: number;
+  graceMs?: number;
+}
+
+export interface OwnerlessWorkAuthorityReconcileResult {
+  scanned: number;
+  retired: number;
+  workIds: string[];
+  skippedByReason: Record<string, number>;
+}
+
+function scheduleOwnsWork(schedule: ReturnType<typeof listSchedules>[number], workId: string): boolean {
+  if (schedule.action.resourceClaims?.some((claim) => claim.workId === workId)) return true;
+  const args = schedule.action.arguments ?? {};
+  return args.workId === workId || args.work_id === workId;
+}
+
+function skip(counts: Record<string, number>, reason: string): void {
+  counts[reason] = (counts[reason] ?? 0) + 1;
+}
+
+/**
+ * Retire only exact Work authority that has lost every durable continuation owner.
+ *
+ * This deliberately does not resurrect the retired repository-wide stale Work
+ * reconciler. Liveness is evaluated per Work. Current Plan authority, an active
+ * Controller session, Work-bound lease, Schedule/occurrence, or active Process
+ * protects the Work. Blocked Work is also retained unless its WorkHandle is
+ * already terminal, because blocked may be an intentional user/dependency wait.
+ *
+ * Retiring authority cancels the Work but keeps its SQLite history. Filesystem
+ * cleanup and later physical retention/GC remain separate phases.
+ */
+export function reconcileOwnerlessWorkAuthorities(
+  options: OwnerlessWorkAuthorityReconcileOptions,
+): OwnerlessWorkAuthorityReconcileResult {
+  const nowMs = options.nowMs ?? Date.now();
+  const graceMs = Math.max(5 * 60_000, Math.trunc(options.graceMs ?? DEFAULT_OWNERLESS_WORK_GRACE_MS));
+  const works = listWorkContracts({ controllerHome: options.controllerHome, repoId: options.repoId, status: 'active', limit: 100 });
+  const currentPlanIds = new Set(listPlanContracts({ controllerHome: options.controllerHome, repoId: options.repoId, status: 'active', limit: 100 }).map((plan) => plan.planId));
+  const activeSessionWorkIds = new Set(listControllerSessions({ controllerHome: options.controllerHome, repoId: options.repoId }).map((session) => session.workId));
+  const activeLeaseWorkIds = new Set(listActiveLeases(options.controllerHome, options.repoId).map((lease) => lease.workId).filter((workId): workId is string => Boolean(workId)));
+  const schedules = listSchedules(options.controllerHome, options.repoId);
+  const activeOccurrenceScheduleIds = new Set(listActiveOccurrences(options.controllerHome, options.repoId).map((occurrence) => occurrence.scheduleId));
+  const liveScheduledWorkIds = new Set(schedules
+    .filter((schedule) => schedule.enabled || activeOccurrenceScheduleIds.has(schedule.scheduleId))
+    .flatMap((schedule) => works.filter((work) => scheduleOwnsWork(schedule, work.workId)).map((work) => work.workId)));
+  const activeProcessWorkIds = new Set(listProcessRecords(options.controllerHome, options.repoId, 5_000)
+    .filter((record) => record.workId && isManagedProcessActive(record))
+    .map((record) => record.workId!));
+  const handles = new Map(listWorkHandles(options.controllerHome, options.repoId, 5_000)
+    .map((handle) => [handle.workContractId ?? handle.workId, handle] as const));
+
+  const skippedByReason: Record<string, number> = {};
+  const retired: string[] = [];
+  for (const work of works) {
+    if (work.planId && currentPlanIds.has(work.planId)) { skip(skippedByReason, 'current_plan'); continue; }
+    if (activeSessionWorkIds.has(work.workId)) { skip(skippedByReason, 'active_controller_session'); continue; }
+    if (activeLeaseWorkIds.has(work.workId)) { skip(skippedByReason, 'active_lease'); continue; }
+    if (liveScheduledWorkIds.has(work.workId)) { skip(skippedByReason, 'active_schedule'); continue; }
+    if (activeProcessWorkIds.has(work.workId)) { skip(skippedByReason, 'active_process'); continue; }
+
+    const handle = handles.get(work.workId);
+    const terminalHandleMismatch = Boolean(handle && TERMINAL_HANDLE_STATES.has(handle.state));
+    if (work.status === 'blocked' && !terminalHandleMismatch) { skip(skippedByReason, 'blocked_wait'); continue; }
+    const updatedMs = Date.parse(work.updatedAt);
+    if (!Number.isFinite(updatedMs)) { skip(skippedByReason, 'invalid_updated_at'); continue; }
+    if (!terminalHandleMismatch && nowMs - updatedMs < graceMs) { skip(skippedByReason, 'grace_period'); continue; }
+
+    const reason = terminalHandleMismatch
+      ? `WorkHandle is already ${handle!.state} while Work remained ${work.status}.`
+      : `Work has no current Plan, Controller session, Work-bound lease, Schedule/occurrence, or active Process after ${Math.round(graceMs / 60_000)} minutes.`;
+    transitionWorkContractPhase(
+      { controllerHome: options.controllerHome, repoId: options.repoId },
+      work.workId,
+      {
+        phase: 'cleanup',
+        status: 'cancelled',
+        state: 'skipped',
+        dispatchState: 'terminal',
+        summary: reason,
+        evidenceRefs: [{
+          title: 'ownerless Work authority retired',
+          summary: reason,
+          detailLevel: 'summary',
+        }, ...work.evidenceRefs],
+      },
+    );
+    updateWorkContract({ controllerHome: options.controllerHome, repoId: options.repoId }, work.workId, {
+      continuationPrompt: `Runtime maintenance retired ownerless Work authority ${work.workId}. Historical evidence is retained; create or continue current Requirement/Plan authority instead of reviving stale execution state.`,
+    });
+    retired.push(work.workId);
+  }
+
+  return {
+    scanned: works.length,
+    retired: retired.length,
+    workIds: retired.sort(),
+    skippedByReason,
+  };
+}

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

@@ -3,8 +3,9 @@ import {
   appendWorkEvidence,
   recordWorkCompletionReceipt,
   type WorkContractStoreOptions,
-} from '../facade/work-contract-store';
+} from '../../../../packages/kernel/work/api/index';
 import type { WorkContract, WorkKind } from '../facade/types';
+import { completePlanStepForWork } from '../facade/plan-contract-store';
 
 export interface WorkRequirementProjectionResult {
   attempted: boolean;
@@ -12,6 +13,12 @@ export interface WorkRequirementProjectionResult {
   warning?: string;
 }
 
+export interface WorkPlanProjectionResult {
+  attempted: boolean;
+  ok: boolean;
+  warning?: string;
+}
+
 /**
  * Project one already-terminal Work receipt into Requirement semantic review.
  * Work completion remains authoritative; Requirement projection is downstream
@@ -44,7 +51,41 @@ export function projectRequirementDeliveryFromCompletedWork(
   }
 }
 
-/** Record the canonical Work completion fact, then update downstream Requirement review state. */
+/**
+ * Project one already-terminal Work receipt into Plan semantic validation.
+ * Work completion remains authoritative; Plan projection is downstream and
+ * must never turn a durable completion receipt back into a failed Work.
+ */
+export function projectPlanDeliveryFromCompletedWork(
+  options: WorkContractStoreOptions,
+  work: WorkContract,
+): WorkPlanProjectionResult {
+  if (!work.planId?.trim() || !work.planStepId?.trim() || !options.controllerHome || !options.repoId) {
+    return { attempted: false, ok: true };
+  }
+  try {
+    completePlanStepForWork(
+      { controllerHome: options.controllerHome, repoId: options.repoId },
+      { planId: work.planId, stepId: work.planStepId, work },
+    );
+    return { attempted: true, ok: true };
+  } catch (error) {
+    const warning = `Work completion remains authoritative; Plan projection could not be applied: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2_000);
+    try {
+      appendWorkEvidence(options, work.workId, {
+        title: 'plan step delivery projection pending',
+        summary: warning,
+        detailLevel: 'summary',
+      });
+    } catch {
+      // The completion receipt is already canonical and durable. Diagnostic
+      // persistence is downstream and cannot invalidate terminal Work state.
+    }
+    return { attempted: true, ok: false, warning };
+  }
+}
+
+/** Record the canonical Work completion fact, then update downstream semantic review state. */
 export function completeWorkWithReceipt(
   options: WorkContractStoreOptions,
   workId: string,
@@ -54,5 +95,6 @@ export function completeWorkWithReceipt(
 ): WorkContract {
   const recorded = recordWorkCompletionReceipt(options, workId, receipt, completionOutcome, completionWorkKind);
   projectRequirementDeliveryFromCompletedWork(options, recorded);
+  projectPlanDeliveryFromCompletedWork(options, recorded);
   return recorded;
 }

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

@@ -47,6 +47,30 @@ function isAuthoritativeCurrentWorkVerification(
   );
 }
 
+function verificationRecordHasExactInputIdentity(record: VerificationRecord): boolean {
+  return Boolean(record.sourceRevision && record.workspaceFingerprint && record.verificationInputFingerprint);
+}
+
+export function effectiveCurrentWorkVerificationRecords(
+  work: WorkContract,
+  currentRevision?: string,
+  currentWorkspaceFingerprint?: string,
+): VerificationRecord[] {
+  const applicable = work.checkRefs.filter((record) =>
+    verificationRecordAppliesToCurrentWorkspace(record, currentRevision, currentWorkspaceFingerprint));
+  const authoritativePasses = new Set(
+    applicable
+      .filter((record) => verificationRecordHasExactInputIdentity(record)
+        && isAuthoritativeCurrentWorkVerification(work, record, currentRevision))
+      .map((record) => record.checkId),
+  );
+  return applicable.filter((record) => !(
+    record.outcome === 'infrastructure_failure'
+    && authoritativePasses.has(record.checkId)
+    && !verificationRecordHasExactInputIdentity(record)
+  ));
+}
+
 export interface WorkImplementationEvidenceEvaluation {
   status: 'complete' | 'incomplete';
   changedPaths: string[];
@@ -100,8 +124,11 @@ export function evaluateWorkCompletionEvidence(
   workBoundProcessEvidenceIds: readonly string[] = [],
   currentWorkspaceChangedPaths?: readonly string[],
 ): WorkCompletionEvidenceEvaluation {
-  const applicableCheckRefs = work.checkRefs.filter((record) =>
-    verificationRecordAppliesToCurrentWorkspace(record, currentRevision, currentWorkspaceFingerprint));
+  const applicableCheckRefs = effectiveCurrentWorkVerificationRecords(
+    work,
+    currentRevision,
+    currentWorkspaceFingerprint,
+  );
   const history = reconcileVerificationHistory(
     applicableCheckRefs.map((record) => ({ checkId: record.checkId, outcome: record.outcome, recordedAt: record.recordedAt })),
   );
@@ -133,7 +160,11 @@ export function evaluateWorkCompletionEvidence(
   const durableResultEvidence = availableDurableEvidenceIds.size > 0
     || applicableCheckRefs.some((record) => isAuthoritativeCurrentWorkVerification(work, record, currentRevision))
     || cleanReadOnlyReviewEvidence;
-  const requiresSemanticAcceptance = work.workKind === 'local_effect' && work.checks.length === 0;
+  const sourceDeltaRequiresImplementationReview = work.workKind === 'local_effect'
+    && (currentWorkspaceChangedPaths?.length ?? 0) > 0;
+  const requiresSemanticAcceptance = work.workKind === 'local_effect'
+    && work.checks.length === 0
+    && !sourceDeltaRequiresImplementationReview;
   const acceptedCriteria = new Set((work.semanticAcceptanceEvidence ?? [])
     .filter((review) => review.evidenceIds.length > 0 && review.evidenceIds.every((evidenceId) => availableDurableEvidenceIds.has(evidenceId)))
     .map((review) => review.criterion));

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

@@ -1,8 +1,8 @@
-import type { MultiRepositoryMcpToolContext } from '../../../cli/mcp/multi-repository';
-import { getRepository, listRepositories, selectRepositoryCheckout } from '../../../cli/repositories/registry';
+import type { McpExecutionContext } from '../../../../packages/protocols/mcp/execution-context';
+import { getRepository, listRepositories, RepositoryCheckoutSelectionError, 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 { assertControllerOwnershipAuthority, claimControllerSession, controllerSessionPrincipalId, getControllerSession, releaseControllerSessionWithAuthority, resumeControllerSession } from '../../../../packages/kernel/controller/api/index';
+import { appendWorkEvidence, getWorkContract, transitionWorkContractPhase } from '../../../../packages/kernel/work/api/index';
 import { resolveLegacyWorkContractIdentity } from './execution-identity';
 import type { ExecutionSessionContext, SessionIdentity } from './session-store';
 import { currentControllerInstanceId, requireExecutionSession, updateExecutionSession } from './session-store';
@@ -15,7 +15,7 @@ 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> {
+export function makeBoundedWorkResult(ctx: McpExecutionContext, 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();
@@ -30,11 +30,11 @@ export function makeBoundedWorkResult(ctx: MultiRepositoryMcpToolContext, sessio
   };
 }
 
-export function principalFor(ctx: MultiRepositoryMcpToolContext): string {
+export function principalFor(ctx: McpExecutionContext): string {
   return ctx.principalId?.trim() || `controller-issued:${ctx.controllerInstanceId ?? currentControllerInstanceId()}`;
 }
 
-export function identityFor(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): SessionIdentity {
+export function identityFor(ctx: McpExecutionContext, 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),
@@ -42,14 +42,14 @@ export function identityFor(ctx: MultiRepositoryMcpToolContext, args: Record<str
   };
 }
 
-export function requireSession(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): ExecutionSessionContext {
+export function requireSession(ctx: McpExecutionContext, 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,
+    worktreePath: handle.worktreePath, branch: handle.branch, sourceCheckoutId: handle.sourceCheckoutId, deliveryTargetBranch: handle.deliveryTargetBranch, 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,
@@ -108,19 +108,20 @@ export function selectWorkFinalizationTarget(
     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;
+      // repository-common operations, so fall back only for a typed missing or
+      // removed source checkout; all other errors fail closed.
+      const unavailable = error instanceof RepositoryCheckoutSelectionError
+        && (error.code === 'CHECKOUT_NOT_FOUND' || (error.code === 'CHECKOUT_NOT_ACTIVE' && error.lifecycle === 'removed'));
+      if (!unavailable) throw error;
     }
   }
   return repository;
 }
 
 export function workReturnCheckoutId(
-  ctx: MultiRepositoryMcpToolContext,
+  ctx: McpExecutionContext,
   handle: Pick<WorkHandleState, 'repositoryId' | 'sourceCheckoutId' | 'checkoutId'>,
   fallbackCheckoutId?: string,
 ): string | undefined {
@@ -129,7 +130,7 @@ export function workReturnCheckoutId(
   return target.activeCheckoutId ?? repository.activeCheckoutId ?? fallbackCheckoutId;
 }
 
-export function contractFor(ctx: MultiRepositoryMcpToolContext, handle: WorkHandleState) {
+export function contractFor(ctx: McpExecutionContext, 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
@@ -140,7 +141,7 @@ export function contractFor(ctx: MultiRepositoryMcpToolContext, handle: WorkHand
 }
 
 export function findWorkHandle(
-  ctx: MultiRepositoryMcpToolContext,
+  ctx: McpExecutionContext,
   session: ExecutionSessionContext,
   args: Record<string, unknown>,
 ): WorkHandleState {
@@ -178,7 +179,7 @@ export function findWorkHandle(
 }
 
 function currentControllerClaimAuthorizesTerminalCleanup(
-  ctx: MultiRepositoryMcpToolContext,
+  ctx: McpExecutionContext,
   session: ExecutionSessionContext,
   handle: WorkHandleState,
 ): boolean {
@@ -191,7 +192,7 @@ function currentControllerClaimAuthorizesTerminalCleanup(
 }
 
 export function workForSession(
-  ctx: MultiRepositoryMcpToolContext,
+  ctx: McpExecutionContext,
   session: ExecutionSessionContext,
   args: Record<string, unknown>,
   options: { reconcileValidation?: boolean; allowClaimedTerminalCleanup?: boolean } = {},
@@ -219,7 +220,7 @@ export function workForSession(
 }
 
 export function assertWorkControllerOwnership(
-  ctx: MultiRepositoryMcpToolContext,
+  ctx: McpExecutionContext,
   session: ExecutionSessionContext,
   handle: WorkHandleState,
   args: Record<string, unknown>,
@@ -273,7 +274,7 @@ export function assertWorkControllerOwnership(
 }
 
 export function releasePreparedWorkOwnership(
-  ctx: MultiRepositoryMcpToolContext,
+  ctx: McpExecutionContext,
   handle: WorkHandleState,
 ): 'released' | 'already_released' {
   const workIdValue = handle.workContractId ?? handle.workId;
@@ -313,7 +314,7 @@ export function releasePreparedWorkOwnership(
 }
 
 export function terminalCleanupOutcome(
-  ctx: MultiRepositoryMcpToolContext,
+  ctx: McpExecutionContext,
   handle: WorkHandleState,
 ): WorkTerminalOutcome | undefined {
   if (handle.cleanupReceipt) return handle.cleanupReceipt.terminalOutcome;
@@ -337,7 +338,7 @@ export function terminalCleanupOutcome(
 }
 
 export async function reconcileTerminalCleanup(
-  ctx: MultiRepositoryMcpToolContext,
+  ctx: McpExecutionContext,
   session: ExecutionSessionContext,
   handle: WorkHandleState,
   args: Record<string, unknown>,
@@ -373,6 +374,25 @@ export async function reconcileTerminalCleanup(
       },
     );
   }
+  if (cleaned.receipt.complete) {
+    const terminalContract = getWorkContract(
+      { controllerHome: ctx.controllerHome, repoId: persisted.repositoryId },
+      persisted.workContractId ?? persisted.workId,
+    );
+    if (terminalContract && (terminalContract.status === 'cancelled' || terminalContract.status === 'failed') && terminalContract.phase !== 'cleanup') {
+      transitionWorkContractPhase(
+        { controllerHome: ctx.controllerHome, repoId: persisted.repositoryId },
+        terminalContract.workId,
+        {
+          phase: 'cleanup',
+          status: terminalContract.status,
+          state: 'satisfied',
+          summary: `Terminal cleanup ${cleaned.receipt.receiptId} completed; terminal Work status ${terminalContract.status} was preserved.`,
+          evidenceRefs: terminalContract.evidenceRefs,
+        },
+      );
+    }
+  }
   return {
     work: compactHandle(persisted),
     stages: persisted.finalization,