@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/control-plane/runtime-cleanup.ts

@@ -8,29 +8,33 @@ import {
   rmSync,
   type Dirent,
 } from 'fs';
-import { join, relative, resolve } from 'path';
+import { basename, dirname, join, relative, resolve } from 'path';
 import { ensureControllerHome } from '../../cli/repositories/controller-home';
 import { cleanupTerminalEditSessionRecords } from '../../cli/editing/edit-session';
 import { listRepositories } from '../../cli/repositories/registry';
 import { managedPathInside, managedWorktreeStorageRoot } from '../../cli/repositories/worktree-storage';
 import { migrateManagedWorkspacePhysicalDependenciesToCanonical } from '../execution/managed-workspace';
-import { cleanupStaleCodegraphLocators } from '../context/codegraph-cache-boundary';
 import { listActiveLeases } from '../resources/leases/store';
 import { cleanupScheduleOccurrenceHistory } from '../../../packages/kernel/scheduler/api/index';
-import { isTerminalWorkContractStatus, readWorkContractStore } from '../../../packages/kernel/work/api/index';
+import { isTerminalSemanticWorkState, readWorkContractStore } from '../../../packages/kernel/work/api/index';
+import { assertOwnedResourceCleanupTarget, listOwnedResources, markOwnedResourceCleaned, type OwnedResource } from '../../../packages/kernel/identity/api/index';
 import { appendJsonLine, readJsonFile, writeJsonAtomic } from '../shared/json-files';
 import { cleanupControllerReleaseHistory } from './release-retention';
 import { cleanupWorkPreservationArtifacts } from './cleanup-artifact-retention';
-import { cleanupCodegraphCaches, CODEGRAPH_CACHE_RETENTION_POLICY_VERSION } from './codegraph-cache-retention';
 import { cleanupRetiredRepositoryNamespaces } from './repository-namespace-retention';
 import { maintainControlPlaneDatabase, type ControlPlaneDatabaseMaintenanceReport } from './persistence/sqlite-store';
 import { cleanupExpiredExperiences } from './persistence/experience-store';
-import { retireTerminalPlanBoundWorkAuthorities } from './facade/plan-contract-store';
 import { reconcileOwnerlessWorkAuthorities } from './execution/work-authority-reconciler';
 import {
   measureReclaimablePath,
   RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION,
 } from './lifecycle-retention-metrics';
+import {
+  listReleaseSessions,
+  releaseSessionCandidateIsRetired,
+} from '../release/release-session';
+import { removeRetiredCandidateExecutionLane } from '../root/runtime-lane';
+import { observeRuntimeStatus } from '../root/status';
 
 function numericSetting(value: string | undefined, fallback: number, minimum: number): number {
   const parsed = Number(value);
@@ -162,8 +166,6 @@ export interface RuntimeCleanupOptions {
   editSessionMaxRetained?: number;
   /** Grace period before a non-Plan Work with no exact durable owner loses execution authority. */
   ownerlessWorkAuthorityGraceMs?: number;
-  /** Minimum age before an unprotected Forge-owned CodeGraph cache can be rebuilt on demand and reclaimed. */
-  codegraphCacheRetentionMs?: number;
   /** Grace before a removed repository may shed only explicit disposable Controller Home children. */
   repositoryNamespaceRetentionMs?: number;
   /** Minimum reclaimable SQLite free-page bytes before physical VACUUM is eligible. */
@@ -193,6 +195,35 @@ export interface RuntimeCleanupLifecycleMetrics {
   blockerReasons: Record<string, number>;
 }
 
+export interface ReleaseSessionCandidatePhaseMetrics {
+  observedCount: number;
+  observedBytes: number;
+  unknownObservedByteCount: number;
+  retainedCount: number;
+  reclaimableCount: number;
+  removedCount: number;
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+}
+
+export interface ReleaseSessionCandidateRetentionReport {
+  inspected: number;
+  observedCount: number;
+  observedBytes: number;
+  unknownObservedByteCount: number;
+  retainedCount: number;
+  eligible: number;
+  attempted: number;
+  removedPaths: string[];
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  orphanDirectoryCount: number;
+  invalidSessionFiles: string[];
+  byPhase: Record<string, ReleaseSessionCandidatePhaseMetrics>;
+  errors: string[];
+  truncated: boolean;
+}
+
 export interface RuntimeCleanupReport {
   policyVersion: typeof RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION;
   at: string;
@@ -204,16 +235,13 @@ export interface RuntimeCleanupReport {
   removedTemporaryPaths: string[];
   removedCleanupArtifactPaths: string[];
   removedReleasePaths: string[];
+  releaseSessionCandidates: ReleaseSessionCandidateRetentionReport;
   removedScheduleOccurrencePaths: string[];
   removedScheduleDecisionPaths: string[];
   removedEditSessionPaths: string[];
-  removedCodegraphLocatorPaths: string[];
-  removedCodegraphCachePaths: string[];
   removedRepositoryNamespacePaths: string[];
   /** Physical SQLite checkpoint/compaction receipt; row lifecycle remains domain-owned. */
   sqliteMaintenance?: ControlPlaneDatabaseMaintenanceReport;
-  /** Historical non-terminal Work whose owning Plan was already terminal. Records remain for retention/audit. */
-  retiredPlanBoundWorkAuthorities: string[];
   /** Work retired only after exact per-Work liveness proved no durable continuation owner remains. */
   retiredOwnerlessWorkAuthorities: string[];
   skippedActiveWorktrees: string[];
@@ -268,14 +296,14 @@ function addReclaimMeasurement(metrics: MutableReclaimMetrics, path: string): vo
   else metrics.unknownReclaimedByteCount += 1;
 }
 
-type RemovalPhase = 'worktrees' | 'temporary' | 'artifacts' | 'scheduler' | 'edit_sessions' | 'caches' | 'repository_namespaces' | 'releases';
-const REMOVAL_PHASES: readonly RemovalPhase[] = ['worktrees', 'temporary', 'artifacts', 'scheduler', 'edit_sessions', 'caches', 'repository_namespaces', 'releases'];
+type RemovalPhase = 'worktrees' | 'temporary' | 'artifacts' | 'scheduler' | 'edit_sessions' | 'repository_namespaces' | 'releases';
+const REMOVAL_PHASES: readonly RemovalPhase[] = ['worktrees', 'temporary', 'artifacts', 'scheduler', 'edit_sessions', 'repository_namespaces', 'releases'];
 
 export function cleanupRemovalPhaseOrder(reason: RuntimeCleanupReport['reason'], sequence = 0): RemovalPhase[] {
   if (reason !== 'periodic') return [...REMOVAL_PHASES];
   const offset = ((Math.trunc(sequence) % REMOVAL_PHASES.length) + REMOVAL_PHASES.length) % REMOVAL_PHASES.length;
   // Periodic maintenance is a bounded shard, not a reordered full sweep.
-  // Eight one-minute generations cover every removal class once while startup/manual
+  // Seven one-minute generations cover every removal class once while startup/manual
   // cleanup retains the complete all-phase contract.
   return [REMOVAL_PHASES[offset]!];
 }
@@ -456,6 +484,203 @@ function createScanBudget(maxEntries: number): ScanBudget {
   };
 }
 
+function emptyReleaseSessionCandidatePhaseMetrics(): ReleaseSessionCandidatePhaseMetrics {
+  return {
+    observedCount: 0,
+    observedBytes: 0,
+    unknownObservedByteCount: 0,
+    retainedCount: 0,
+    reclaimableCount: 0,
+    removedCount: 0,
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+  };
+}
+
+function emptyReleaseSessionCandidateRetentionReport(): ReleaseSessionCandidateRetentionReport {
+  return {
+    inspected: 0,
+    observedCount: 0,
+    observedBytes: 0,
+    unknownObservedByteCount: 0,
+    retainedCount: 0,
+    eligible: 0,
+    attempted: 0,
+    removedPaths: [],
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+    orphanDirectoryCount: 0,
+    invalidSessionFiles: [],
+    byPhase: {},
+    errors: [],
+    truncated: false,
+  };
+}
+
+function candidatePhaseMetrics(
+  report: ReleaseSessionCandidateRetentionReport,
+  phase: string,
+): ReleaseSessionCandidatePhaseMetrics {
+  return report.byPhase[phase] ??= emptyReleaseSessionCandidatePhaseMetrics();
+}
+
+/**
+ * Physical retention only. ReleaseSession phase transitions and Candidate
+ * service retirement remain owned by standalone Recovery under its operation
+ * lock. Maintenance consumes durable phase evidence and the live Runtime owner
+ * projection, then applies the existing path-fenced Candidate removal.
+ */
+function cleanupReleaseSessionCandidateLanes(
+  controllerHome: string,
+  input: {
+    maxEntries: number;
+    sequence: number;
+    removalBudget: RemovalBudget;
+    skippedByReason: Record<string, number>;
+  },
+): ReleaseSessionCandidateRetentionReport {
+  const report = emptyReleaseSessionCandidateRetentionReport();
+  const candidateRoot = resolve(dirname(controllerHome), 'candidate-runtime-lanes');
+  const inventory = listReleaseSessions(controllerHome, { maxEntries: input.maxEntries });
+  report.invalidSessionFiles = [...inventory.invalidSessionFiles].sort();
+  report.inspected += inventory.inspected;
+  report.truncated = inventory.truncated;
+  if (inventory.truncated) {
+    input.skippedByReason.release_session_candidate_inventory_truncated =
+      (input.skippedByReason.release_session_candidate_inventory_truncated ?? 0) + 1;
+  }
+  if (inventory.invalidSessionFiles.length > 0) {
+    input.skippedByReason.release_session_candidate_authority_invalid =
+      (input.skippedByReason.release_session_candidate_authority_invalid ?? 0) + inventory.invalidSessionFiles.length;
+    report.errors.push(...inventory.invalidSessionFiles.map((name) => `invalid ReleaseSession authority: ${name}`));
+  }
+
+  const measurementBudget = createScanBudget(input.maxEntries);
+  const knownCandidateHomes = new Set<string>();
+  const sessions = [...inventory.sessions].sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+  if (sessions.length > 1) {
+    const offset = ((Math.trunc(input.sequence) % sessions.length) + sessions.length) % sessions.length;
+    sessions.push(...sessions.splice(0, offset));
+  }
+
+  for (const session of sessions) {
+    const candidateHome = resolve(session.candidate.controllerHome);
+    if (resolve(dirname(candidateHome)) !== candidateRoot || basename(candidateHome) !== session.sessionId) {
+      input.skippedByReason.release_session_candidate_path_invalid =
+        (input.skippedByReason.release_session_candidate_path_invalid ?? 0) + 1;
+      report.errors.push(`${session.sessionId}: RUNTIME_CANDIDATE_CLEANUP_PATH_INVALID`);
+      continue;
+    }
+    knownCandidateHomes.add(candidateHome);
+    if (!existsSync(candidateHome)) continue;
+
+    const phase = candidatePhaseMetrics(report, session.phase);
+    report.observedCount += 1;
+    phase.observedCount += 1;
+
+    let measuredBytes: number | undefined;
+    let measurementComplete = false;
+    if (measurementBudget.remaining > 0) {
+      const measurement = measureReclaimablePath(candidateHome, Math.min(256, measurementBudget.remaining));
+      measurementBudget.remaining = Math.max(0, measurementBudget.remaining - measurement.entries);
+      measurementBudget.inspected += measurement.entries;
+      measuredBytes = measurement.bytes;
+      measurementComplete = measurement.complete;
+    }
+    if (measurementComplete && measuredBytes !== undefined) {
+      report.observedBytes += measuredBytes;
+      phase.observedBytes += measuredBytes;
+    } else {
+      report.unknownObservedByteCount += 1;
+      phase.unknownObservedByteCount += 1;
+    }
+
+    if (!releaseSessionCandidateIsRetired(session)) {
+      report.retainedCount += 1;
+      phase.retainedCount += 1;
+      input.skippedByReason.release_session_candidate_resumable =
+        (input.skippedByReason.release_session_candidate_resumable ?? 0) + 1;
+      continue;
+    }
+
+    report.eligible += 1;
+    phase.reclaimableCount += 1;
+    try {
+      if (observeRuntimeStatus(candidateHome).running) {
+        report.retainedCount += 1;
+        phase.retainedCount += 1;
+        input.skippedByReason.release_session_candidate_active_owner =
+          (input.skippedByReason.release_session_candidate_active_owner ?? 0) + 1;
+        continue;
+      }
+    } catch (error) {
+      report.retainedCount += 1;
+      phase.retainedCount += 1;
+      report.errors.push(errorText(`${session.sessionId} Candidate Runtime observation`, error));
+      input.skippedByReason.release_session_candidate_owner_unknown =
+        (input.skippedByReason.release_session_candidate_owner_unknown ?? 0) + 1;
+      continue;
+    }
+
+    if (input.removalBudget.remaining <= 0) {
+      input.removalBudget.exhausted = true;
+      report.retainedCount += 1;
+      phase.retainedCount += 1;
+      input.skippedByReason.release_session_candidate_cleanup_budget_exhausted =
+        (input.skippedByReason.release_session_candidate_cleanup_budget_exhausted ?? 0) + 1;
+      continue;
+    }
+
+    report.attempted += 1;
+    input.removalBudget.remaining -= 1;
+    try {
+      removeRetiredCandidateExecutionLane(session.stable, session.candidate);
+      const relativePath = `candidate-runtime-lanes/${session.sessionId}`;
+      report.removedPaths.push(relativePath);
+      phase.removedCount += 1;
+      if (measurementComplete && measuredBytes !== undefined) {
+        report.reclaimedBytes += measuredBytes;
+        phase.reclaimedBytes += measuredBytes;
+      } else {
+        report.unknownReclaimedByteCount += 1;
+        phase.unknownReclaimedByteCount += 1;
+      }
+    } catch (error) {
+      report.retainedCount += 1;
+      phase.retainedCount += 1;
+      report.errors.push(errorText(`${session.sessionId} Candidate lane removal`, error));
+    }
+  }
+
+  // A directory without readable ReleaseSession authority is visible debt, not
+  // deletion authority. Keep it and report it so Recovery can reconcile it.
+  if (!inventory.truncated && existsSync(candidateRoot)) {
+    const rootBudget = createScanBudget(input.maxEntries);
+    visitDirectoryEntries(candidateRoot, rootBudget, report.errors, (entry) => {
+      if (!entry.isDirectory()) return;
+      const path = resolve(candidateRoot, entry.name);
+      if (knownCandidateHomes.has(path)) return;
+      report.observedCount += 1;
+      report.retainedCount += 1;
+      report.orphanDirectoryCount += 1;
+      report.unknownObservedByteCount += 1;
+      const phase = candidatePhaseMetrics(report, 'authority_missing');
+      phase.observedCount += 1;
+      phase.retainedCount += 1;
+      phase.unknownObservedByteCount += 1;
+      input.skippedByReason.release_session_candidate_authority_missing =
+        (input.skippedByReason.release_session_candidate_authority_missing ?? 0) + 1;
+    });
+    report.inspected += rootBudget.inspected;
+    if (rootBudget.exhausted) report.truncated = true;
+  }
+
+  report.inspected += measurementBudget.inspected;
+  report.removedPaths.sort();
+  report.errors.sort();
+  return report;
+}
+
 function shouldProtectWorktreeReference(meta: AgentRunSnapshot, nowMs: number): boolean {
   if (meta.executionMode !== 'worktree' || meta.worktreeCleanedAt) return false;
   const status = typeof meta.status === 'string' ? meta.status.trim().toLowerCase() : '';
@@ -609,6 +834,11 @@ function cleanupOrphanWorktrees(
   const reclaim = emptyReclaimMetrics();
   const skippedByReason: Record<string, number> = {};
   const skip = (reason: string): void => { skippedByReason[reason] = (skippedByReason[reason] ?? 0) + 1; };
+  const ownedWorktreesByPath = new Map<string, OwnedResource>();
+  for (const resource of listOwnedResources(controllerHome, { kind: 'worktree', status: 'active' })) {
+    if (resource.cleanupCapable !== true || !resource.targetRef?.trim()) continue;
+    ownedWorktreesByPath.set(canonicalPath(resource.targetRef), resource);
+  }
   const repositoriesRoot = join(controllerHome, 'repositories');
   visitDirectoryEntries(repositoriesRoot, budget, errors, (repoEntry) => {
     if (!repoEntry.isDirectory()) return;
@@ -624,7 +854,25 @@ function cleanupOrphanWorktrees(
         skip(references.referenced.has(canonical) ? 'active_owner' : 'unknown_ownership');
         return;
       }
+      const ownedResource = ownedWorktreesByPath.get(canonical);
+      if (!ownedResource) {
+        skippedActive.push(relativePath);
+        skip('owned_resource_missing');
+        return;
+      }
       try {
+        try {
+          assertOwnedResourceCleanupTarget(controllerHome, {
+            resourceId: ownedResource.resourceId,
+            kind: 'worktree',
+            targetRef: path,
+          });
+        } catch (error) {
+          skippedActive.push(relativePath);
+          skip('owned_resource_identity_mismatch');
+          errors.push(errorText(`owned worktree cleanup fence ${relativePath}`, error));
+          return;
+        }
         if (nowMs - lstatSync(path).mtimeMs < ORPHAN_WORKTREE_TTL_MS) {
           skip('ttl_not_expired');
           return;
@@ -638,6 +886,7 @@ function cleanupOrphanWorktrees(
         const measurement = measureReclaimablePath(path);
         if (removeOrphanWorktreeDirectory(path, errors, relativePath)) {
           removed.push(relativePath);
+          markOwnedResourceCleaned(controllerHome, ownedResource.resourceId, 'forge:runtime-orphan-worktree-cleanup');
           if (measurement.complete) reclaim.reclaimedBytes += measurement.bytes;
           else reclaim.unknownReclaimedByteCount += 1;
         }
@@ -802,12 +1051,10 @@ function shouldPersistCleanupAudit(report: RuntimeCleanupReport): boolean {
     || report.removedTemporaryPaths.length
     || report.removedCleanupArtifactPaths.length
     || report.removedReleasePaths.length
-    || report.removedCodegraphLocatorPaths.length
-    || report.removedCodegraphCachePaths.length
+    || report.releaseSessionCandidates.removedPaths.length
     || report.removedRepositoryNamespacePaths.length
     || report.sqliteMaintenance?.vacuumed
     || report.sqliteMaintenance?.skippedReason === 'database_busy'
-    || report.retiredPlanBoundWorkAuthorities.length
     || report.retiredOwnerlessWorkAuthorities.length,
   );
   if (hadMutations || report.errors.length) return true;
@@ -839,14 +1086,12 @@ export function cleanupControllerRuntimeState(
   const errors: string[] = [];
   const skippedByReason: Record<string, number> = {};
   const sequence = options.periodicSequence ?? Math.floor(nowMs / 60_000);
+  const removalCycleSequence = Math.floor(sequence / REMOVAL_PHASES.length);
   const removalPhases = cleanupRemovalPhaseOrder(options.reason ?? 'manual', sequence);
   const periodic = (options.reason ?? 'manual') === 'periodic';
-  const retiredPlanBoundWorkAuthorities: string[] = [];
   const retiredOwnerlessWorkAuthorities: string[] = [];
   if (!periodic || removalPhases.includes('repository_namespaces')) try {
     for (const repository of listRepositories(home, { includeRemoved: true })) {
-      const retired = retireTerminalPlanBoundWorkAuthorities({ controllerHome: home, repoId: repository.repoId });
-      retiredPlanBoundWorkAuthorities.push(...retired.map((workId) => `${repository.repoId}:${workId}`));
       const ownerless = reconcileOwnerlessWorkAuthorities({
         controllerHome: home,
         repoId: repository.repoId,
@@ -870,11 +1115,8 @@ export function cleanupControllerRuntimeState(
   let temporaryCleanup: ReturnType<typeof cleanupTemporaryStatePaths> | undefined;
   let artifactRetention: ReturnType<typeof cleanupWorkPreservationArtifacts> | undefined;
   let releaseRetention: ReturnType<typeof cleanupControllerReleaseHistory> | undefined;
-  let codegraphRetention: ReturnType<typeof cleanupCodegraphCaches> | undefined;
+  let releaseSessionCandidates: ReleaseSessionCandidateRetentionReport | undefined;
   let repositoryNamespaceRetention: ReturnType<typeof cleanupRetiredRepositoryNamespaces> | undefined;
-  const removedCodegraphLocatorPaths: string[] = [];
-  let codegraphLocatorInspected = 0;
-  let codegraphLocatorRetained = 0;
   const schedulerHistory = {
     removedOccurrencePaths: [] as string[],
     removedDecisionPaths: [] as string[],
@@ -920,6 +1162,7 @@ export function cleanupControllerRuntimeState(
         graceMs: options.cleanupArtifactRetentionGraceMs,
         maxEntries,
         maxRemovals: removalBudget.remaining,
+        scanSequence: removalCycleSequence,
       });
       removalBudget.remaining = Math.max(0, removalBudget.remaining - artifactRetention.attempted);
       if (artifactRetention.budgetExhausted) removalBudget.exhausted = true;
@@ -971,7 +1214,7 @@ export function cleanupControllerRuntimeState(
         let protectedWorkIds: string[];
         try {
           protectedWorkIds = readWorkContractStore({ controllerHome: home, repoId: repository.repoId }).contracts
-            .filter((contract) => !isTerminalWorkContractStatus(contract.status))
+            .filter((contract) => !isTerminalSemanticWorkState(contract.semanticState))
             .map((contract) => contract.workId);
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
@@ -1008,65 +1251,6 @@ export function cleanupControllerRuntimeState(
       errors.push(...editSessionHistory.errors.map((error) => `edit-session-history ${error}`));
       continue;
     }
-    if (phase === 'caches') {
-      const registered = listRepositories(home, { includeRemoved: true });
-      const repositoryRoots = new Set<string>();
-      for (const repository of registered) {
-        repositoryRoots.add(resolve(repository.canonicalRoot));
-        repositoryRoots.add(resolve(repository.localRoot));
-        for (const checkout of repository.checkouts) {
-          repositoryRoots.add(resolve(checkout.canonicalRoot));
-          repositoryRoots.add(resolve(checkout.localRoot));
-        }
-      }
-      const protectedRepositoryRoots = new Set<string>();
-      let locatorScanRemaining = maxEntries;
-      for (const repositoryRoot of [...repositoryRoots].sort()) {
-        if (!existsSync(repositoryRoot)) continue;
-        if (locatorScanRemaining <= 0) {
-          protectedRepositoryRoots.add(repositoryRoot);
-          skippedByReason.codegraph_locator_scan_budget_exhausted = (skippedByReason.codegraph_locator_scan_budget_exhausted ?? 0) + 1;
-          continue;
-        }
-        const locatorReport = cleanupStaleCodegraphLocators(
-          repositoryRoot,
-          home,
-          locatorScanRemaining,
-          removalBudget.remaining,
-        );
-        locatorScanRemaining = Math.max(0, locatorScanRemaining - locatorReport.inspected);
-        removalBudget.remaining = Math.max(0, removalBudget.remaining - locatorReport.attempted);
-        if (locatorReport.budgetExhausted && removalBudget.remaining <= 0) removalBudget.exhausted = true;
-        codegraphLocatorInspected += locatorReport.inspected;
-        codegraphLocatorRetained += Math.max(0, locatorReport.inspected - locatorReport.removed.length);
-        removedCodegraphLocatorPaths.push(...locatorReport.removed.map((name) => join(repositoryRoot, name)));
-        Object.entries(locatorReport.skippedByReason).forEach(([key, value]) => {
-          skippedByReason[`codegraph_locator_${key}`] = (skippedByReason[`codegraph_locator_${key}`] ?? 0) + value;
-        });
-        const protectionUncertain = locatorReport.budgetExhausted
-          || locatorReport.errors.length > 0
-          || (locatorReport.skippedByReason.locator_identity_unproven ?? 0) > 0;
-        if (locatorReport.active.length > 0 || protectionUncertain) protectedRepositoryRoots.add(repositoryRoot);
-        if (locatorReport.budgetExhausted) {
-          skippedByReason.codegraph_locator_scan_budget_exhausted = (skippedByReason.codegraph_locator_scan_budget_exhausted ?? 0) + 1;
-        }
-        errors.push(...locatorReport.errors.map((error) => `codegraph-locator ${repositoryRoot}: ${error}`));
-      }
-      codegraphRetention = cleanupCodegraphCaches(home, {
-        nowMs,
-        retentionMs: options.codegraphCacheRetentionMs,
-        maxEntries,
-        maxRemovals: removalBudget.remaining,
-        protectedRepositoryRoots: [...protectedRepositoryRoots],
-      });
-      removalBudget.remaining = Math.max(0, removalBudget.remaining - codegraphRetention.attempted);
-      if (codegraphRetention.budgetExhausted) removalBudget.exhausted = true;
-      Object.entries(codegraphRetention.skippedByReason).forEach(([key, value]) => {
-        skippedByReason[`codegraph_cache_${key}`] = (skippedByReason[`codegraph_cache_${key}`] ?? 0) + value;
-      });
-      errors.push(...codegraphRetention.errors.map((error) => `codegraph-cache ${error}`));
-      continue;
-    }
     if (phase === 'repository_namespaces') {
       repositoryNamespaceRetention = cleanupRetiredRepositoryNamespaces(home, {
         nowMs,
@@ -1082,6 +1266,14 @@ export function cleanupControllerRuntimeState(
       errors.push(...repositoryNamespaceRetention.errors.map((error) => `repository-namespace ${error}`));
       continue;
     }
+    releaseSessionCandidates = cleanupReleaseSessionCandidateLanes(home, {
+      maxEntries,
+      sequence,
+      removalBudget,
+      skippedByReason,
+    });
+    errors.push(...releaseSessionCandidates.errors.map((error) => `release-session-candidate ${error}`));
+
     releaseRetention = cleanupControllerReleaseHistory(home, {
       nowMs,
       graceMs: options.releaseRetentionGraceMs,
@@ -1100,11 +1292,11 @@ export function cleanupControllerRuntimeState(
     dependencyCleanup ??= { migrated: [], skippedByReason: {} } as ReturnType<typeof cleanupManagedWorktreeDependencyCopies>;
     temporaryCleanup ??= { removed: [], reclaim: emptyReclaimMetrics() } as ReturnType<typeof cleanupTemporaryStatePaths>;
     artifactRetention ??= { removedPaths: [], attempted: 0, budgetExhausted: false, skippedByReason: {}, errors: [], inspected: 0, eligible: 0, retained: 0, skipped: 0, reclaimedBytes: 0, unknownReclaimedByteCount: 0 } as ReturnType<typeof cleanupWorkPreservationArtifacts>;
-    codegraphRetention ??= { policyVersion: CODEGRAPH_CACHE_RETENTION_POLICY_VERSION, removedPaths: [], attempted: 0, budgetExhausted: false, skippedByReason: {}, errors: [], inspected: 0, eligible: 0, retained: 0, reclaimedBytes: 0, unknownReclaimedByteCount: 0, observedBytes: 0, unknownObservedByteCount: 0, protected: 0, protectedOverCapacity: 0, truncated: false } as ReturnType<typeof cleanupCodegraphCaches>;
     repositoryNamespaceRetention ??= { policyVersion: 'repository-namespace-retention-v1', removedPaths: [], attempted: 0, budgetExhausted: false, skippedByReason: {}, errors: [], inspected: 0, eligible: 0, retained: 0, reclaimedBytes: 0, unknownReclaimedByteCount: 0 } as ReturnType<typeof cleanupRetiredRepositoryNamespaces>;
     releaseRetention ??= { removedPaths: [], removedBackupPaths: [], attempted: 0, budgetExhausted: false, skippedByReason: {}, errors: [], inspected: 0, eligible: 0, retained: 0, skipped: 0, reclaimedBytes: 0, unknownReclaimedByteCount: 0, reclaimedBackupBytes: 0, unknownReclaimedBackupByteCount: 0 } as ReturnType<typeof cleanupControllerReleaseHistory>;
+    releaseSessionCandidates ??= emptyReleaseSessionCandidateRetentionReport();
   }
-  if (!worktrees || !dependencyCleanup || !temporaryCleanup || !artifactRetention || !codegraphRetention || !repositoryNamespaceRetention || !releaseRetention) {
+  if (!worktrees || !dependencyCleanup || !temporaryCleanup || !artifactRetention || !repositoryNamespaceRetention || !releaseRetention || !releaseSessionCandidates) {
     throw new Error('RUNTIME_CLEANUP_PHASE_INCOMPLETE');
   }
   const removedTemporaryPaths = temporaryCleanup.removed.sort();
@@ -1113,8 +1305,6 @@ export function cleanupControllerRuntimeState(
   const removedScheduleOccurrencePaths = schedulerHistory.removedOccurrencePaths.sort();
   const removedScheduleDecisionPaths = schedulerHistory.removedDecisionPaths.sort();
   const removedEditSessionPaths = editSessionHistory.removedPaths.sort();
-  removedCodegraphLocatorPaths.sort();
-  const removedCodegraphCachePaths = codegraphRetention.removedPaths.sort();
   const removedRepositoryNamespacePaths = repositoryNamespaceRetention.removedPaths.sort();
   let sqliteMaintenance: ControlPlaneDatabaseMaintenanceReport | undefined;
   if (!periodic || removalPhases.includes('releases')) try {
@@ -1128,8 +1318,8 @@ export function cleanupControllerRuntimeState(
   } catch (error) {
     errors.push(errorText('SQLite maintenance', error));
   }
-  const inspectedPaths = referenceBudget.inspected + worktreeBudget.inspected + dependencyBudget.inspected + tempBudget.inspected + schedulerBudget.inspected + editSessionBudget.inspected + artifactRetention.inspected + codegraphLocatorInspected + codegraphRetention.inspected + repositoryNamespaceRetention.inspected + releaseRetention.inspected;
-  const budgetExhausted = referenceBudget.exhausted || worktreeBudget.exhausted || dependencyBudget.exhausted || tempBudget.exhausted || schedulerBudget.exhausted || editSessionBudget.exhausted || removalBudget.exhausted;
+  const inspectedPaths = referenceBudget.inspected + worktreeBudget.inspected + dependencyBudget.inspected + tempBudget.inspected + schedulerBudget.inspected + editSessionBudget.inspected + artifactRetention.inspected + repositoryNamespaceRetention.inspected + releaseRetention.inspected + releaseSessionCandidates.inspected;
+  const budgetExhausted = referenceBudget.exhausted || worktreeBudget.exhausted || dependencyBudget.exhausted || tempBudget.exhausted || schedulerBudget.exhausted || editSessionBudget.exhausted || removalBudget.exhausted || releaseSessionCandidates.truncated;
   if (pidFiles.skipped.length > 0 && removalBudget.exhausted) skippedByReason.cleanup_budget_exhausted = (skippedByReason.cleanup_budget_exhausted ?? 0) + pidFiles.skipped.length;
   if (pidFiles.skipped.length > 0 && !removalBudget.exhausted) skippedByReason.active_owner = (skippedByReason.active_owner ?? 0) + pidFiles.skipped.length;
   const physicalReclaimedByClass: Record<string, RuntimeCleanupLifecycleClassMetrics> = {
@@ -1139,9 +1329,9 @@ export function cleanupControllerRuntimeState(
       unknownByteCount: worktrees.reclaim.unknownReclaimedByteCount,
     },
     runtime_temp: {
-      count: pidFiles.removed.length + removedTemporaryPaths.length + removedCodegraphLocatorPaths.length,
+      count: pidFiles.removed.length + removedTemporaryPaths.length,
       bytes: pidFiles.reclaim.reclaimedBytes + temporaryCleanup.reclaim.reclaimedBytes,
-      unknownByteCount: pidFiles.reclaim.unknownReclaimedByteCount + temporaryCleanup.reclaim.unknownReclaimedByteCount + removedCodegraphLocatorPaths.length,
+      unknownByteCount: pidFiles.reclaim.unknownReclaimedByteCount + temporaryCleanup.reclaim.unknownReclaimedByteCount,
     },
     work: {
       count: removedCleanupArtifactPaths.length,
@@ -1158,6 +1348,11 @@ export function cleanupControllerRuntimeState(
       bytes: releaseRetention.reclaimedBackupBytes,
       unknownByteCount: releaseRetention.unknownReclaimedBackupByteCount,
     },
+    release_session_candidate: {
+      count: releaseSessionCandidates.removedPaths.length,
+      bytes: releaseSessionCandidates.reclaimedBytes,
+      unknownByteCount: releaseSessionCandidates.unknownReclaimedByteCount,
+    },
     scheduler_occurrence_history: {
       count: removedScheduleOccurrencePaths.length + removedScheduleDecisionPaths.length,
       bytes: schedulerHistory.reclaimedBytes,
@@ -1168,11 +1363,6 @@ export function cleanupControllerRuntimeState(
       bytes: editSessionHistory.reclaimedBytes,
       unknownByteCount: editSessionHistory.unknownReclaimedByteCount,
     },
-    codegraph_cache: {
-      count: removedCodegraphCachePaths.length,
-      bytes: codegraphRetention.reclaimedBytes,
-      unknownByteCount: codegraphRetention.unknownReclaimedByteCount,
-    },
     repository_controller_home_namespace: {
       count: removedRepositoryNamespacePaths.length,
       bytes: repositoryNamespaceRetention.reclaimedBytes,
@@ -1199,8 +1389,8 @@ export function cleanupControllerRuntimeState(
     reclaimedBytes: Object.values(physicalReclaimedByClass).reduce((total, entry) => total + entry.bytes, 0),
     unknownReclaimedByteCount: Object.values(physicalReclaimedByClass).reduce((total, entry) => total + entry.unknownByteCount, 0),
     reclaimedByClass: physicalReclaimedByClass,
-    logicalRetiredCount: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length,
-    logicalRetiredByClass: { work: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length },
+    logicalRetiredCount: retiredOwnerlessWorkAuthorities.length,
+    logicalRetiredByClass: { work: retiredOwnerlessWorkAuthorities.length },
     protectedActiveCount: Object.values(protectedByReason).reduce((total, count) => total + count, 0),
     protectedByReason,
     blockerReasons,
@@ -1216,14 +1406,12 @@ export function cleanupControllerRuntimeState(
     removedTemporaryPaths,
     removedCleanupArtifactPaths,
     removedReleasePaths,
+    releaseSessionCandidates,
     removedScheduleOccurrencePaths,
     removedScheduleDecisionPaths,
     removedEditSessionPaths,
-    removedCodegraphLocatorPaths,
-    removedCodegraphCachePaths,
     removedRepositoryNamespacePaths,
     sqliteMaintenance,
-    retiredPlanBoundWorkAuthorities: retiredPlanBoundWorkAuthorities.sort(),
     retiredOwnerlessWorkAuthorities: retiredOwnerlessWorkAuthorities.sort(),
     skippedActiveWorktrees: worktrees.skippedActive.sort(),
     inspectedPaths,
@@ -1233,11 +1421,11 @@ export function cleanupControllerRuntimeState(
     lifecycleMetrics,
     cycle: {
       scanned: inspectedPaths,
-      eligible: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + artifactRetention.eligible + schedulerHistory.eligible + editSessionHistory.eligible + removedCodegraphLocatorPaths.length + codegraphRetention.eligible + repositoryNamespaceRetention.eligible + releaseRetention.eligible,
-      attempted: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + artifactRetention.attempted + schedulerHistory.attempted + editSessionHistory.attempted + removedCodegraphLocatorPaths.length + codegraphRetention.attempted + repositoryNamespaceRetention.attempted + releaseRetention.attempted + errors.length,
-      removed: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + removedCleanupArtifactPaths.length + removedScheduleOccurrencePaths.length + removedScheduleDecisionPaths.length + removedEditSessionPaths.length + removedCodegraphLocatorPaths.length + removedCodegraphCachePaths.length + removedRepositoryNamespacePaths.length + removedReleasePaths.length,
-      retained: pidFiles.skipped.length + worktrees.skippedActive.length + artifactRetention.retained + schedulerHistory.retained + editSessionHistory.retained + codegraphLocatorRetained + codegraphRetention.retained + repositoryNamespaceRetention.retained + releaseRetention.retained,
-      skipped: Math.max(0, inspectedPaths - pidFiles.removed.length - worktrees.removed.length - dependencyCleanup.migrated.length - removedTemporaryPaths.length - removedCleanupArtifactPaths.length - removedScheduleOccurrencePaths.length - removedScheduleDecisionPaths.length - removedEditSessionPaths.length - removedCodegraphLocatorPaths.length - removedCodegraphCachePaths.length - removedRepositoryNamespacePaths.length - removedReleasePaths.length - errors.length),
+      eligible: retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + artifactRetention.eligible + schedulerHistory.eligible + editSessionHistory.eligible + repositoryNamespaceRetention.eligible + releaseRetention.eligible + releaseSessionCandidates.eligible,
+      attempted: retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + artifactRetention.attempted + schedulerHistory.attempted + editSessionHistory.attempted + repositoryNamespaceRetention.attempted + releaseRetention.attempted + releaseSessionCandidates.attempted + errors.length,
+      removed: retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + removedCleanupArtifactPaths.length + removedScheduleOccurrencePaths.length + removedScheduleDecisionPaths.length + removedEditSessionPaths.length + removedRepositoryNamespacePaths.length + removedReleasePaths.length + releaseSessionCandidates.removedPaths.length,
+      retained: pidFiles.skipped.length + worktrees.skippedActive.length + artifactRetention.retained + schedulerHistory.retained + editSessionHistory.retained + repositoryNamespaceRetention.retained + releaseRetention.retained + releaseSessionCandidates.retainedCount,
+      skipped: Math.max(0, inspectedPaths - pidFiles.removed.length - worktrees.removed.length - dependencyCleanup.migrated.length - removedTemporaryPaths.length - removedCleanupArtifactPaths.length - removedScheduleOccurrencePaths.length - removedScheduleDecisionPaths.length - removedEditSessionPaths.length - removedRepositoryNamespacePaths.length - removedReleasePaths.length - releaseSessionCandidates.removedPaths.length - errors.length),
       failed: errors.length,
       truncated: budgetExhausted,
       budgetExhausted,