@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/recovery/maintenance-executor.ts

@@ -1,18 +1,20 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
 import { basename, dirname, join, relative, resolve } from 'path';
 import { tmpdir } from 'os';
+import { assertStorageHeadroom } from '../shared/storage-capacity';
 import { runProcess } from '../../effects/process-runner';
-import { cleanupEditSession, getEditSession, listEditSessions, reconcileEditSession } from '../../cli/editing/edit-session';
+import { cleanupEditSession, getEditSession, listEditSessions } from '../../cli/editing/edit-session';
 import { ensureRepositoryRuntimeStorage, type RepositoryRuntimeStorageReport } from '../../cli/repositories/runtime-storage';
+import { getRepository, selectRepositoryCheckout, setRepositoryCheckoutLifecycle } from '../../cli/repositories/registry';
 import type { RepositoryRecord } from '../../cli/repositories/types';
 import { rebuildRepositoryProjection } from '../projections/materialized-view';
-import { getWorkContract, readWorkContractStore, transitionWorkContractPhase } from '../control-plane/facade/work-contract-store';
-import { getControllerSession, withControllerSessionTerminalizationFence } from '../control-plane/facade/controller-session-store';
+import { cancelWorkContract, getWorkContract, readWorkContractStore, updateWorkContract } from '../../../packages/kernel/work/api/index';
+import { getControllerSession, listControllerSessions, withControllerSessionTerminalizationFence } from '../../../packages/kernel/controller/api/index';
 import { listPlanContracts } from '../control-plane/facade/plan-contract-store';
 import { readRequirement } from '../control-plane/persistence/requirement-store';
 import { listControlPlaneRecords, type ControlPlaneRecord } from '../control-plane/persistence/sqlite-store';
 import { isTerminalWorkContractStatus, type WorkContract } from '../control-plane/facade/types';
-import { listSchedules } from '../workflow/schedules/store';
+import { listSchedules } from '../../../packages/kernel/scheduler/api/index';
 import {
   collectRuntimeProcesses,
   removeRuntimeTempEntry,
@@ -26,6 +28,16 @@ import {
   type RuntimeStorageRepairPreview,
 } from './local-jobs-repair';
 import { gcTerminalProcesses, type ProcessGcResult } from '../execution/process-runtime/gc';
+import { cleanupStaleWorkVerificationSnapshots, type WorkVerificationSnapshotRetentionReport } from '../control-plane/execution/work-verification-snapshot';
+import {
+  cleanupRuntimeQuarantine,
+  quarantineRuntimePath,
+  runtimeLegacyCheckQuarantineRoot,
+  type RuntimeQuarantineRetentionReport,
+} from './quarantine-retention';
+import { readWorkHandle, resolveWorkDeliveryTargetBranch } from '../control-plane/execution/work-handle-store';
+import { listRecoverableProcessRecords } from '../execution/process-runtime/store';
+import { isManagedProcessActive } from '../execution/process-runtime/types';
 
 export type RuntimeMaintenanceActionId =
   | 'local_jobs_reconcile'
@@ -137,6 +149,8 @@ export interface RuntimeMaintenanceApplyResult extends Omit<RuntimeMaintenanceSt
   runtimeStorageRepairApply?: RuntimeStorageRepairApplyResult;
   /** Existing bounded terminal-process retention, run only during explicit full maintenance. */
   processGc?: ProcessGcResult;
+  verificationSnapshotGc?: WorkVerificationSnapshotRetentionReport;
+  quarantineGc?: RuntimeQuarantineRetentionReport;
   projection?: unknown;
 }
 
@@ -189,10 +203,16 @@ function readJson(path: string): unknown {
 }
 
 function writeJsonAtomic(path: string, value: unknown): void {
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  assertStorageHeadroom(path, {
+    operation: 'runtime_maintenance_state_write',
+    requiredBytes: Buffer.byteLength(content),
+    reserveBytes: 16 * 1024 * 1024,
+  });
   mkdirSync(dirname(path), { recursive: true });
   const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
   try {
-    writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    writeFileSync(temporaryPath, content, { encoding: 'utf8', mode: 0o600 });
     renameSync(temporaryPath, path);
   } finally {
     rmSync(temporaryPath, { force: true });
@@ -484,10 +504,117 @@ interface StaleWorkSourceInspection {
   detail: string;
 }
 
+interface StaleWorkDeliveryTargetResolution {
+  targetBranch: string;
+  handle?: NonNullable<ReturnType<typeof readWorkHandle>>;
+  identityMismatch: boolean;
+}
+
+function resolveStaleWorkDeliveryTarget(
+  repository: RuntimeMaintenanceRepository,
+  controllerHome: string,
+  contract: WorkContract,
+): StaleWorkDeliveryTargetResolution {
+  const handle = readWorkHandle(controllerHome, repository.repoId, contract.workId);
+  if (!handle) {
+    return { targetBranch: repository.defaultBranch?.trim() || 'main', identityMismatch: false };
+  }
+  if (!contract.checkoutId || handle.checkoutId !== contract.checkoutId) {
+    return {
+      targetBranch: repository.defaultBranch?.trim() || 'main',
+      handle,
+      identityMismatch: true,
+    };
+  }
+  return {
+    targetBranch: resolveWorkDeliveryTargetBranch(handle, repository.defaultBranch),
+    handle,
+    identityMismatch: false,
+  };
+}
+
+function isLegacyImplicitRemoteEffectPlacement(contract: WorkContract): boolean {
+  if (contract.workKind !== 'remote_effect' || contract.worktreePolicy.required !== true || !contract.worktreeRef || !contract.checkoutId) return false;
+  if (contract.routeDecision?.requiresIsolation === true) return false;
+  const reason = contract.worktreePolicy.reason?.trim() ?? '';
+  if (/Typed placement|Route Policy requires isolated execution/i.test(reason)) return false;
+  return true;
+}
+
+interface LegacyRemoteEffectPlacementInspection {
+  safe: boolean;
+  path?: string;
+  detail: string;
+  checkoutId?: string;
+  canonicalCheckoutId?: string;
+  branch?: string;
+  canonicalBranch?: string;
+}
+
+function inspectLegacyRemoteEffectPlacement(
+  repository: RuntimeMaintenanceRepository,
+  controllerHome: string,
+  contract: WorkContract,
+): LegacyRemoteEffectPlacementInspection | undefined {
+  if (!isLegacyImplicitRemoteEffectPlacement(contract)) return undefined;
+  const recordedPath = contract.worktreeRef?.trim();
+  if (!recordedPath) return undefined;
+  const path = resolve(recordedPath);
+  if (!looksLikeForgeManagedWorktree(path)) return { safe: false, path, detail: 'Legacy remote_effect placement is outside Forge-managed worktree storage; automatic resource detachment is forbidden.' };
+  if (readWorkHandle(controllerHome, repository.repoId, contract.workId)) return { safe: false, path, detail: 'Legacy remote_effect placement unexpectedly has a WorkHandle; repository source authority must be reconciled explicitly.' };
+  let registered;
+  try { registered = getRepository(repository.repoId, controllerHome, { includeRemoved: true }); } catch (error) {
+    return { safe: false, path, detail: `Repository registry could not be read for legacy remote_effect placement: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const checkout = registered.checkouts.find((candidate) => candidate.checkoutId === contract.checkoutId);
+  if (!checkout) return { safe: false, path, detail: 'Legacy remote_effect checkout identity is missing from the Repository Registry.' };
+  if ((checkout.lifecycle ?? 'active') !== 'active' || checkout.worktree !== true) return { safe: false, path, detail: `Legacy remote_effect checkout ${checkout.checkoutId} is not an active registered worktree.` };
+  const registeredPath = resolve(checkout.canonicalRoot);
+  if (registeredPath !== path && resolve(checkout.localRoot) !== path) return { safe: false, path, detail: 'Legacy remote_effect WorkContract path does not match its registered checkout identity.' };
+  const otherOwner = readWorkContractStore({ controllerHome, repoId: repository.repoId }).contracts.find((candidate) =>
+    candidate.workId !== contract.workId
+    && !isTerminalWorkContractStatus(candidate.status)
+    && candidate.worktreeRef
+    && resolve(candidate.worktreeRef) === path);
+  if (otherOwner) return { safe: false, path, detail: `Managed worktree is also owned by active Work ${otherOwner.workId}; resource detachment is fenced.` };
+  if (!existsSync(path)) return { safe: false, path, detail: 'Legacy remote_effect managed worktree path is absent; registry/source reconciliation is required before detachment.' };
+  const status = runProcess('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: path, timeoutMs: 10_000, maxOutputBytes: 500_000 });
+  if (!status.ok || status.stdout.trim()) return { safe: false, path, detail: status.ok ? 'Legacy remote_effect managed worktree is dirty; live source must be preserved.' : 'Legacy remote_effect managed worktree status could not be read.' };
+  const head = runProcess('git', ['rev-parse', 'HEAD'], { cwd: path, timeoutMs: 10_000, maxOutputBytes: 100_000 });
+  const baseRevision = contract.baseRevision?.trim();
+  if (!head.ok || !head.stdout.trim() || !baseRevision || head.stdout.trim() !== baseRevision) return { safe: false, path, detail: 'Legacy remote_effect worktree HEAD does not exactly equal the Work base revision; repository delta ownership is ambiguous.' };
+  const branch = runProcess('git', ['branch', '--show-current'], { cwd: path, timeoutMs: 10_000, maxOutputBytes: 100_000 });
+  if (!branch.ok || !branch.stdout.trim()) return { safe: false, path, detail: 'Legacy remote_effect managed worktree branch could not be resolved.' };
+  let canonical;
+  try { canonical = selectRepositoryCheckout(registered, registered.activeCheckoutId); } catch (error) {
+    return { safe: false, path, detail: `Canonical repository checkout could not be resolved: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (canonical.activeCheckoutId === checkout.checkoutId) return { safe: false, path, detail: 'Legacy remote_effect placement unexpectedly points at the canonical active checkout; automatic detachment is forbidden.' };
+  const canonicalBranch = runProcess('git', ['branch', '--show-current'], { cwd: canonical.canonicalRoot, timeoutMs: 10_000, maxOutputBytes: 100_000 });
+  if (!canonicalBranch.ok || !canonicalBranch.stdout.trim()) return { safe: false, path, detail: 'Canonical integration branch could not be resolved for legacy remote_effect detachment.' };
+  const contained = runProcess('git', ['merge-base', '--is-ancestor', baseRevision, `refs/heads/${canonicalBranch.stdout.trim()}`], { cwd: canonical.canonicalRoot, timeoutMs: 10_000, maxOutputBytes: 100_000 });
+  if (!contained.ok) return { safe: false, path, detail: `Legacy remote_effect base revision ${baseRevision} is not contained in canonical branch ${canonicalBranch.stdout.trim()}; source preservation remains required.` };
+  return {
+    safe: true, path, checkoutId: checkout.checkoutId, canonicalCheckoutId: canonical.activeCheckoutId,
+    branch: branch.stdout.trim(), canonicalBranch: canonicalBranch.stdout.trim(),
+    detail: `Legacy remote_effect owns a clean no-delta managed worktree at base revision ${baseRevision}, which is already contained in canonical branch ${canonicalBranch.stdout.trim()}; repository placement may be detached without changing Work semantics.`,
+  };
+}
+
 function inspectStaleWorkRepositorySource(
   repository: RuntimeMaintenanceRepository,
+  controllerHome: string,
   contract: WorkContract,
 ): StaleWorkSourceInspection {
+  const legacyRemoteEffect = inspectLegacyRemoteEffectPlacement(repository, controllerHome, contract);
+  if (legacyRemoteEffect) {
+    return {
+      safeToCancel: legacyRemoteEffect.safe,
+      state: legacyRemoteEffect.safe ? 'clean_integrated' : 'source_state_unknown',
+      path: legacyRemoteEffect.path,
+      detail: legacyRemoteEffect.detail,
+    };
+  }
   const recordedPath = contract.worktreeRef?.trim();
   if (!recordedPath) {
     return {
@@ -506,11 +633,62 @@ function inspectStaleWorkRepositorySource(
     };
   }
   if (!existsSync(path)) {
+    const deliveryTarget = resolveStaleWorkDeliveryTarget(repository, controllerHome, contract);
+    const handle = deliveryTarget.handle;
+    const expectedHead = handle?.expectedHead?.trim();
+    if (deliveryTarget.identityMismatch || !handle || !expectedHead) {
+      return {
+        safeToCancel: false,
+        state: 'source_state_unknown',
+        path,
+        detail: 'Recorded managed worktree path is absent and no identity-matched durable WorkHandle head can prove source preservation; destructive stale-Work cancellation is fenced.',
+      };
+    }
+    const targetBranch = deliveryTarget.targetBranch;
+    const head = runProcess('git', ['rev-parse', '--verify', `${expectedHead}^{commit}`], {
+      cwd: repository.canonicalRoot,
+      timeoutMs: 10_000,
+      maxOutputBytes: 100_000,
+    });
+    const target = runProcess('git', ['rev-parse', '--verify', `refs/heads/${targetBranch}`], {
+      cwd: repository.canonicalRoot,
+      timeoutMs: 10_000,
+      maxOutputBytes: 100_000,
+    });
+    if (!head.ok || !head.stdout.trim() || !target.ok || !target.stdout.trim()) {
+      return {
+        safeToCancel: false,
+        state: 'source_state_unknown',
+        path,
+        detail: `Recorded managed worktree path is absent and durable source head/target ${targetBranch} could not be resolved; destructive stale-Work cancellation is fenced.`,
+      };
+    }
+    const unique = runProcess('git', ['rev-list', '--count', `${target.stdout.trim()}..${head.stdout.trim()}`], {
+      cwd: repository.canonicalRoot,
+      timeoutMs: 10_000,
+      maxOutputBytes: 100_000,
+    });
+    if (!unique.ok || !/^\d+$/.test(unique.stdout.trim())) {
+      return {
+        safeToCancel: false,
+        state: 'source_state_unknown',
+        path,
+        detail: 'Durable WorkHandle source head could not be compared with its delivery target; destructive stale-Work cancellation is fenced.',
+      };
+    }
+    if (Number(unique.stdout.trim()) > 0) {
+      return {
+        safeToCancel: false,
+        state: 'unintegrated_commits',
+        path,
+        detail: `Managed worktree is absent, but durable WorkHandle head ${expectedHead} has ${unique.stdout.trim()} commit(s) not reachable from ${targetBranch}; exact source remains preserved in Git and requires explicit adoption or cleanup authority.`,
+      };
+    }
     return {
-      safeToCancel: false,
-      state: 'source_state_unknown',
+      safeToCancel: true,
+      state: 'clean_integrated',
       path,
-      detail: 'Recorded managed worktree path is absent, so maintenance cannot prove that no unique branch/source remains recoverable through Git or checkout metadata; destructive stale-Work cancellation is fenced.',
+      detail: `Managed worktree is absent, but its identity-matched durable WorkHandle head ${expectedHead} is already reachable from ${targetBranch}; no unique source is being discarded.`,
     };
   }
 
@@ -541,7 +719,16 @@ function inspectStaleWorkRepositorySource(
     timeoutMs: 10_000,
     maxOutputBytes: 100_000,
   });
-  const targetBranch = repository.defaultBranch?.trim() || 'main';
+  const deliveryTarget = resolveStaleWorkDeliveryTarget(repository, controllerHome, contract);
+  if (deliveryTarget.identityMismatch) {
+    return {
+      safeToCancel: false,
+      state: 'source_state_unknown',
+      path,
+      detail: 'Managed worktree has a durable WorkHandle whose checkout identity does not match the WorkContract; source containment cannot be proven against that handle and destructive stale-Work cancellation is fenced.',
+    };
+  }
+  const targetBranch = deliveryTarget.targetBranch;
   const target = runProcess('git', ['rev-parse', '--verify', `refs/heads/${targetBranch}`], {
     cwd: repository.canonicalRoot,
     timeoutMs: 10_000,
@@ -701,26 +888,68 @@ function normalizedOptions(options: RuntimeMaintenanceOptions = {}): Required<Ru
   };
 }
 
-function activeWorkAuthorityRefs(
+interface RuntimeMaintenanceAuthoritySnapshot {
+  contracts: WorkContract[];
+  workById: Map<string, WorkContract>;
+  controllerWorkIds: Set<string>;
+  planByWorkId: Map<string, string>;
+  activeRequirementStateById: Map<string, string>;
+  scheduleByWorkId: Map<string, string>;
+  processByWorkId: Map<string, string>;
+}
+
+/**
+ * Build one bounded read snapshot for a maintenance status pass. Discovery must
+ * never turn N candidate Works/EditSessions into N full Plan/Schedule/Process
+ * scans. Process liveness comes from Process Runtime's recovery index instead of
+ * enumerating terminal process history. This snapshot is advisory only; mutation
+ * paths still re-read current authority before terminalization.
+ */
+function buildRuntimeMaintenanceAuthoritySnapshot(
   repository: RuntimeMaintenanceRepository,
   controllerHome: string,
-  contract: WorkContract,
-): string[] {
+): RuntimeMaintenanceAuthoritySnapshot {
+  const contracts = readWorkContractStore({ controllerHome, repoId: repository.repoId }).contracts;
+  const workById = new Map(contracts.map((contract) => [contract.workId, contract]));
+  const controllerWorkIds = new Set(listControllerSessions({ controllerHome, repoId: repository.repoId }).map((session) => session.workId));
+  const planByWorkId = new Map<string, string>();
+  for (const plan of listPlanContracts({ controllerHome, repoId: repository.repoId, status: 'active', limit: 100 })) {
+    for (const step of plan.steps) if (step.workId) planByWorkId.set(step.workId, plan.planId);
+    if (plan.planId) {
+      for (const contract of contracts) if (contract.planId === plan.planId) planByWorkId.set(contract.workId, plan.planId);
+    }
+  }
+  const activeRequirementStateById = new Map<string, string>();
+  for (const requirementId of new Set(contracts.flatMap((contract) => contract.requirementId ? [contract.requirementId] : []))) {
+    const requirement = readRequirement({ controllerHome }, requirementId)?.value;
+    if (requirement && !['done', 'cancelled'].includes(requirement.state)) activeRequirementStateById.set(requirementId, requirement.state);
+  }
+  const scheduleByWorkId = new Map<string, string>();
+  for (const schedule of listSchedules(controllerHome, repository.repoId)) {
+    if (!schedule.enabled) continue;
+    const workId = String((schedule.action.arguments as Record<string, unknown> | undefined)?.work_id ?? '').trim();
+    if (workId && !scheduleByWorkId.has(workId)) scheduleByWorkId.set(workId, schedule.scheduleId);
+  }
+  const processByWorkId = new Map<string, string>();
+  for (const process of listRecoverableProcessRecords(controllerHome, repository.repoId)) {
+    if (process.workId && isManagedProcessActive(process) && !processByWorkId.has(process.workId)) processByWorkId.set(process.workId, process.processId);
+  }
+  return { contracts, workById, controllerWorkIds, planByWorkId, activeRequirementStateById, scheduleByWorkId, processByWorkId };
+}
+
+function activeWorkAuthorityRefs(contract: WorkContract, snapshot: RuntimeMaintenanceAuthoritySnapshot): string[] {
   const refs: string[] = [];
-  if (getControllerSession({ controllerHome, repoId: repository.repoId }, contract.workId)) refs.push('controller_session');
-  const activePlans = listPlanContracts({ controllerHome, repoId: repository.repoId, status: 'active', limit: 100 });
-  const plan = activePlans.find((candidate) => candidate.planId === contract.planId || candidate.steps.some((step) => step.workId === contract.workId));
-  if (plan) refs.push(`plan:${plan.planId}`);
+  if (snapshot.controllerWorkIds.has(contract.workId)) refs.push('controller_session');
+  const planId = snapshot.planByWorkId.get(contract.workId);
+  if (planId) refs.push(`plan:${planId}`);
   if (contract.requirementId) {
-    const requirement = readRequirement({ controllerHome }, contract.requirementId)?.value;
-    if (requirement && !['done', 'cancelled'].includes(requirement.state)) refs.push(`requirement:${requirement.requirementId}:${requirement.state}`);
+    const state = snapshot.activeRequirementStateById.get(contract.requirementId);
+    if (state) refs.push(`requirement:${contract.requirementId}:${state}`);
   }
-  const boundSchedule = listSchedules(controllerHome, repository.repoId).find((schedule) => {
-    if (!schedule.enabled) return false;
-    const args = schedule.action.arguments as Record<string, unknown> | undefined;
-    return args?.work_id === contract.workId;
-  });
-  if (boundSchedule) refs.push(`schedule:${boundSchedule.scheduleId}`);
+  const scheduleId = snapshot.scheduleByWorkId.get(contract.workId);
+  if (scheduleId) refs.push(`schedule:${scheduleId}`);
+  const processId = snapshot.processByWorkId.get(contract.workId);
+  if (processId) refs.push(`process:${processId}`);
   return refs;
 }
 
@@ -728,9 +957,10 @@ function scanStaleWorkContractCandidates(
   repository: RuntimeMaintenanceRepository,
   controllerHome: string,
   options: Required<RuntimeMaintenanceOptions>,
+  snapshot: RuntimeMaintenanceAuthoritySnapshot,
 ): RuntimeMaintenanceCandidate[] {
   const nowMs = Date.now();
-  return readWorkContractStore({ controllerHome, repoId: repository.repoId }).contracts
+  return snapshot.contracts
     .filter((contract) => !isTerminalWorkContractStatus(contract.status))
     .map((contract) => {
       const updatedMs = Date.parse(contract.updatedAt);
@@ -738,38 +968,80 @@ function scanStaleWorkContractCandidates(
       return { contract, ageMinutes };
     })
     .filter(({ ageMinutes }) => ageMinutes >= options.minAgeMinutes)
-    .flatMap(({ contract, ageMinutes }) => {
-      const authorityRefs = activeWorkAuthorityRefs(repository, controllerHome, contract);
-      // A live Plan/Requirement/Schedule/Controller reference is lifecycle authority,
-      // not maintenance debt. Keep the Work fenced until that authority disappears;
-      // if it later becomes unowned, the next scan will surface it as stale.
-      if (authorityRefs.length > 0) return [];
-      return [{ contract, ageMinutes, source: inspectStaleWorkRepositorySource(repository, contract) }];
+    .filter(({ contract }) => {
+      // A live Plan/Requirement/Schedule/Controller/Process reference is lifecycle authority,
+      // not maintenance debt. The authority inventory was read once for this status pass.
+      return activeWorkAuthorityRefs(contract, snapshot).length === 0;
     })
     .sort((left, right) => right.ageMinutes - left.ageMinutes)
+    // Expensive Git source inspection belongs after the visible candidate budget.
     .slice(0, options.maxCandidates)
+    .map(({ contract, ageMinutes }) => ({
+      contract, ageMinutes, source: inspectStaleWorkRepositorySource(repository, controllerHome, contract),
+    }))
     .map(({ contract, ageMinutes, source }) => {
+      const legacyRemotePlacement = isLegacyImplicitRemoteEffectPlacement(contract);
       const semanticReady = staleWorkSemanticTerminalizationReady(contract);
       return {
         kind: 'stale_work_contract' as const,
         id: contract.workId,
         path: source.path,
         status: contract.status,
-        safe: source.safeToCancel && semanticReady,
-        reason: staleWorkCandidateReason(source, semanticReady),
+        safe: legacyRemotePlacement ? source.safeToCancel : source.safeToCancel && semanticReady,
+        reason: legacyRemotePlacement ? source.detail : staleWorkCandidateReason(source, semanticReady),
         ageMinutes,
         suggestedAction: 'full_maintenance_pass' as const,
         ownershipStatus: 'explicit' as const,
         sourceState: source.state,
         disposition: !source.safeToCancel
           ? ('source_preservation_required' as const)
-          : !semanticReady
+          : !legacyRemotePlacement && !semanticReady
             ? ('semantic_completion_required' as const)
             : undefined,
       };
     });
 }
 
+function detachLegacyRemoteEffectPlacement(
+  repository: RuntimeMaintenanceRepository,
+  controllerHome: string,
+  current: WorkContract,
+  candidate: RuntimeMaintenanceCandidate,
+): RuntimeMaintenanceCandidate & { applied: boolean; result: string } {
+  const inspection = inspectLegacyRemoteEffectPlacement(repository, controllerHome, current);
+  if (!inspection || !inspection.safe || !inspection.path || !inspection.checkoutId || !inspection.canonicalCheckoutId || !inspection.branch || !inspection.canonicalBranch) {
+    return { ...candidate, safe: false, reason: inspection?.detail ?? 'Legacy remote_effect placement is no longer eligible for resource detachment.', sourceState: 'source_state_unknown', disposition: 'source_preservation_required', applied: false, result: 'legacy_remote_effect_placement_preserved' };
+  }
+  const store = { controllerHome, repoId: repository.repoId };
+  const previous = { checkoutId: current.checkoutId, worktreeRef: current.worktreeRef, constraints: current.constraints, driver: current.driver, worktreePolicy: current.worktreePolicy };
+  updateWorkContract(store, current.workId, {
+    checkoutId: inspection.canonicalCheckoutId,
+    worktreeRef: undefined,
+    constraints: { ...current.constraints, workspaceMode: 'auto', requireWorktree: false },
+    driver: { ...current.driver, preferred: 'direct_edit', allowDirectEdit: true },
+    worktreePolicy: { required: false, reason: 'Legacy pure remote_effect repository placement detached by explicit runtime maintenance; external-effect execution has no repository source authority.' },
+  });
+  try {
+    setRepositoryCheckoutLifecycle({ controllerHome, repoId: repository.repoId, checkoutId: inspection.checkoutId, lifecycle: 'removed', reason: `Legacy remote_effect placement detached for ${current.workId}.` });
+    const removed = runProcess('git', ['worktree', 'remove', '--force', inspection.path], { cwd: repository.canonicalRoot, timeoutMs: 60_000, maxOutputBytes: 500_000 });
+    if (!removed.ok && existsSync(inspection.path)) throw new Error(`LEGACY_REMOTE_EFFECT_WORKTREE_REMOVE_FAILED: ${removed.stderr || removed.stdout}`);
+    if (inspection.branch !== inspection.canonicalBranch) {
+      const deleted = runProcess('git', ['branch', '--delete', inspection.branch], { cwd: repository.canonicalRoot, timeoutMs: 10_000, maxOutputBytes: 100_000 });
+      if (!deleted.ok) {
+        const forced = runProcess('git', ['branch', '--delete', '--force', inspection.branch], { cwd: repository.canonicalRoot, timeoutMs: 10_000, maxOutputBytes: 100_000 });
+        if (!forced.ok) return { ...candidate, safe: true, reason: inspection.detail, sourceState: 'clean_integrated', disposition: undefined, applied: true, result: `legacy_remote_effect_placement_detached_branch_retained:${inspection.branch}` };
+      }
+    }
+    return { ...candidate, safe: true, reason: inspection.detail, sourceState: 'clean_integrated', disposition: undefined, applied: true, result: 'legacy_remote_effect_placement_detached' };
+  } catch (error) {
+    if (existsSync(inspection.path)) {
+      try { setRepositoryCheckoutLifecycle({ controllerHome, repoId: repository.repoId, checkoutId: inspection.checkoutId, lifecycle: 'active', reason: `Rollback failed legacy remote_effect detach for ${current.workId}.` }); } catch { /* preserve primary failure */ }
+      try { updateWorkContract(store, current.workId, previous); } catch { /* preserve primary failure */ }
+    }
+    throw error;
+  }
+}
+
 export function applyStaleWorkContractMaintenanceCandidate(
   repository: RuntimeMaintenanceRepository,
   controllerHome: string,
@@ -793,7 +1065,7 @@ export function applyStaleWorkContractMaintenanceCandidate(
       if (!current || isTerminalWorkContractStatus(current.status)) {
         return { ...candidate, applied: false, result: 'already_terminal' };
       }
-      const authorityRefs = activeWorkAuthorityRefs(repository, controllerHome, current);
+      const authorityRefs = activeWorkAuthorityRefs(current, buildRuntimeMaintenanceAuthoritySnapshot(repository, controllerHome));
       if (authorityRefs.length > 0) {
         return {
           ...candidate,
@@ -805,19 +1077,22 @@ export function applyStaleWorkContractMaintenanceCandidate(
       // Re-probe the live worktree while the canonical ControllerSession fence is
       // held so neither a newer Controller claim nor a late source write can be
       // raced by stale maintenance terminalization.
-      const source = inspectStaleWorkRepositorySource(repository, current);
+      const source = inspectStaleWorkRepositorySource(repository, controllerHome, current);
       if (!source.safeToCancel) {
         return {
           ...candidate,
           path: source.path ?? candidate.path,
           safe: false,
-          reason: staleWorkCandidateReason(source, staleWorkSemanticTerminalizationReady(current)),
+          reason: isLegacyImplicitRemoteEffectPlacement(current) ? source.detail : staleWorkCandidateReason(source, staleWorkSemanticTerminalizationReady(current)),
           sourceState: source.state,
           disposition: 'source_preservation_required' as const,
           applied: false,
           result: `work_source_preserved:${source.state}`,
         };
       }
+      if (isLegacyImplicitRemoteEffectPlacement(current)) {
+        return detachLegacyRemoteEffectPlacement(repository, controllerHome, current, candidate);
+      }
       const semanticReady = staleWorkSemanticTerminalizationReady(current);
       if (!semanticReady) {
         return {
@@ -831,13 +1106,14 @@ export function applyStaleWorkContractMaintenanceCandidate(
           result: 'work_semantic_completion_required',
         };
       }
-      transitionWorkContractPhase({ controllerHome, repoId: repository.repoId }, current.workId, {
-        phase: 'cleanup',
-        status: 'cancelled',
-        state: 'skipped',
-        summary: 'Cancelled by explicit full maintenance after the Work had already reached cleanup with prior semantic phases satisfied and no unique live repository source remained; durable evidence retained.',
-        evidenceRefs: current.evidenceRefs,
-      });
+      cancelWorkContract(
+        { controllerHome, repoId: repository.repoId },
+        current.workId,
+        {
+          summary: 'Cancelled by explicit full maintenance after the Work had already reached cleanup with prior semantic phases satisfied and no unique live repository source remained; durable evidence retained.',
+          evidenceRefs: current.evidenceRefs,
+        },
+      );
       return {
         ...candidate,
         path: source.path ?? candidate.path,
@@ -863,35 +1139,26 @@ export function applyStaleWorkContractMaintenanceCandidate(
 
 function scanStaleEditSessionCandidates(
   repository: RuntimeMaintenanceRepository,
-  controllerHome: string,
   options: Required<RuntimeMaintenanceOptions>,
+  snapshot: RuntimeMaintenanceAuthoritySnapshot,
 ): RuntimeMaintenanceCandidate[] {
   const nowMs = Date.now();
   return listEditSessions(repository.canonicalRoot, Math.min(options.maxCandidates * 3, 500))
     .filter((summary) => ['open', 'dirty', 'checked', 'check_failed'].includes(summary.status))
-    .flatMap((summary) => {
-      try {
-        const session = reconcileEditSession(repository.canonicalRoot, summary.sessionId, {
-          reviewer: 'runtime-maintenance',
-          note: 'Reconciled during maintenance discovery; source files were not modified.',
-        });
-        if (['finalized', 'superseded', 'rolled_back'].includes(session.status)) return [];
-        const updatedMs = Date.parse(session.updatedAt);
-        const ageMinutes = Number.isFinite(updatedMs) ? Math.max(0, Math.floor((nowMs - updatedMs) / 60_000)) : 0;
-        return [{ session, ageMinutes }];
-      } catch {
-        return [];
-      }
+    // Status discovery is read-only. Workspace hashing/Git reconciliation belongs
+    // exclusively to explicit full maintenance for the selected candidate.
+    .map((session) => {
+      const updatedMs = Date.parse(session.updatedAt);
+      const ageMinutes = Number.isFinite(updatedMs) ? Math.max(0, Math.floor((nowMs - updatedMs) / 60_000)) : 0;
+      return { session, ageMinutes };
     })
     .filter(({ ageMinutes }) => ageMinutes >= options.minAgeMinutes)
     .sort((left, right) => right.ageMinutes - left.ageMinutes)
     .slice(0, options.maxCandidates)
     .flatMap(({ session, ageMinutes }) => {
-      const work = session.workId
-        ? getWorkContract({ controllerHome, repoId: repository.repoId }, session.workId)
-        : undefined;
+      const work = session.workId ? snapshot.workById.get(session.workId) : undefined;
       const terminalWork = Boolean(work && isTerminalWorkContractStatus(work.status));
-      if (work && !terminalWork && activeWorkAuthorityRefs(repository, controllerHome, work).length > 0) {
+      if (work && !terminalWork && activeWorkAuthorityRefs(work, snapshot).length > 0) {
         // The Edit Session inherits the live Work lifecycle authority. Reporting it
         // as stale maintenance debt while that authority is active would duplicate
         // ownership and can permanently block release readiness for valid long work.
@@ -952,7 +1219,10 @@ export function buildRuntimeMaintenanceStatus(
   options: RuntimeMaintenanceOptions = {},
 ): RuntimeMaintenanceStatus {
   const normalized = normalizedOptions(options);
+  // Runtime-storage binding is the compatibility cutover authority for legacy test/
+  // migrated repositories. Read lifecycle owners only after that binding is resolved.
   const storage = safeRuntimeStorage(repository, controllerHome);
+  const authoritySnapshot = buildRuntimeMaintenanceAuthoritySnapshot(repository, controllerHome);
   const runtimeStorageRepair = previewRuntimeStorageRepair(coerceRepository(repository), controllerHome, {
     minAgeMinutes: normalized.minAgeMinutes,
     maxCandidates: normalized.maxCandidates,
@@ -960,8 +1230,8 @@ export function buildRuntimeMaintenanceStatus(
   const localJobCandidates = scanLocalJobCandidates(repository.canonicalRoot, normalized);
   const storageCandidates = runtimeStorageCandidates(storage.report);
   const tempCandidates = scanRuntimeTempCandidates(repository, normalized.maxCandidates);
-  const staleWorkCandidates = scanStaleWorkContractCandidates(repository, controllerHome, normalized);
-  const staleEditCandidates = scanStaleEditSessionCandidates(repository, controllerHome, normalized);
+  const staleWorkCandidates = scanStaleWorkContractCandidates(repository, controllerHome, normalized, authoritySnapshot);
+  const staleEditCandidates = scanStaleEditSessionCandidates(repository, normalized, authoritySnapshot);
   const retainedWorktreeCandidates = scanRetainedWorktreeCandidates(repository, controllerHome, normalized.maxCandidates);
   const candidates = [...localJobCandidates, ...storageCandidates, ...staleWorkCandidates, ...staleEditCandidates, ...retainedWorktreeCandidates, ...tempCandidates].slice(0, normalized.maxCandidates);
   const summary = summarize(candidates);
@@ -1110,11 +1380,6 @@ export function previewAutomaticRuntimeMaintenance(
   };
 }
 
-function quarantinePath(repoRoot: string, id: string): string {
-  const stamp = now().replace(/[:.]/g, '-');
-  return join(repoRoot, '.ai', 'harness', 'local-jobs-quarantine', `${stamp}-${safeId(id)}`);
-}
-
 function terminalizeLocalJob(candidate: RuntimeMaintenanceCandidate, status: 'orphaned' | 'cancelled' = 'orphaned'): string {
   if (!candidate.path) throw new Error('LOCAL_JOB_PATH_MISSING');
   const jobPath = join(candidate.path, 'job.json');
@@ -1132,14 +1397,11 @@ function terminalizeLocalJob(candidate: RuntimeMaintenanceCandidate, status: 'or
   return status;
 }
 
-function quarantineLocalJob(repoRoot: string, candidate: RuntimeMaintenanceCandidate): string {
+function quarantineLocalJob(controllerHome: string, repoId: string, repoRoot: string, candidate: RuntimeMaintenanceCandidate): string {
   if (!candidate.path) throw new Error('LOCAL_JOB_PATH_MISSING');
   const root = localJobsRoot(repoRoot);
   if (!isWithin(root, candidate.path)) throw new Error('LOCAL_JOB_PATH_OUTSIDE_ROOT');
-  const destination = quarantinePath(repoRoot, candidate.id);
-  mkdirSync(dirname(destination), { recursive: true });
-  renameSync(candidate.path, destination);
-  return destination;
+  return quarantineRuntimePath(controllerHome, repoId, candidate.path, candidate.id);
 }
 
 function rebuildActiveIndex(repoRoot: string): void {
@@ -1204,7 +1466,7 @@ export function applyRuntimeMaintenance(
         return { ...candidate, applied: true, result: terminalizeLocalJob(candidate, 'cancelled') };
       }
       if (candidate.kind === 'unreadable_local_job' || candidate.kind === 'missing_job_metadata') {
-        return { ...candidate, applied: true, result: quarantineLocalJob(repository.canonicalRoot, candidate) };
+        return { ...candidate, applied: true, result: quarantineLocalJob(controllerHome, repository.repoId, repository.canonicalRoot, candidate) };
       }
       if (candidate.kind === 'stale_runtime_temp_entry') {
         if (!candidate.path) throw new Error('RUNTIME_TEMP_PATH_MISSING');
@@ -1242,6 +1504,24 @@ export function applyRuntimeMaintenance(
   const processGc = options.actionId === 'full_maintenance_pass'
     ? gcTerminalProcesses({ controllerHome, repoId: repository.repoId })
     : undefined;
+  const currentWork = readWorkContractStore({ controllerHome, repoId: repository.repoId }).contracts;
+  const protectedWorkIds = currentWork
+    .filter((contract) => !isTerminalWorkContractStatus(contract.status))
+    .map((contract) => contract.workId);
+  const verificationSnapshotGc = options.actionId === 'full_maintenance_pass'
+    ? cleanupStaleWorkVerificationSnapshots(controllerHome, repository.repoId, {
+      protectedWorkIds,
+      maxEntries: Math.max(100, (options.maxCandidates ?? 50) * 3),
+      maxRemovals: Math.max(1, options.maxCandidates ?? 50),
+    })
+    : undefined;
+  const quarantineGc = options.actionId === 'full_maintenance_pass'
+    ? cleanupRuntimeQuarantine(controllerHome, repository.repoId, repository.canonicalRoot, {
+      maxEntries: Math.max(100, (options.maxCandidates ?? 50) * 3),
+      maxRemovals: Math.max(1, options.maxCandidates ?? 50),
+      additionalRoots: [runtimeLegacyCheckQuarantineRoot(controllerHome, repository.repoId)],
+    })
+    : undefined;
 
   if (options.actionId === 'runtime_storage_finalize_relocation' || options.actionId === 'full_maintenance_pass' || applied.some((candidate) => candidate.applied) || runtimeStorageRepairApply) {
     rebuildActiveIndex(repository.canonicalRoot);
@@ -1259,6 +1539,8 @@ export function applyRuntimeMaintenance(
     applied,
     runtimeStorageRepairApply,
     processGc,
+    verificationSnapshotGc,
+    quarantineGc,
     projection,
   };
 }