@moretea-labs/forge 1.7.1 → 1.8.0

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

@@ -10,8 +10,27 @@ import {
 } from 'fs';
 import { 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 { 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';
 
 function numericSetting(value: string | undefined, fallback: number, minimum: number): number {
   const parsed = Number(value);
@@ -129,27 +148,81 @@ export interface RuntimeCleanupOptions {
   maxEntries?: number;
   /** Global removal budget for one cycle; automatic cleanup defaults to 50. */
   maxRemovals?: number;
+  /** Scheduler cleanup generation used to rotate removal priority without adding durable state. */
+  periodicSequence?: number;
   /** Minimum age before an unreferenced finalized release/backup can be reclaimed. */
   releaseRetentionGraceMs?: number;
   /** Minimum age before an abandoned runtime .staging-* directory can be reclaimed. */
   stagingReleaseRetentionGraceMs?: number;
+  /** Minimum age before a proven-redundant terminal Work preservation bundle can be reclaimed. */
+  cleanupArtifactRetentionGraceMs?: number;
+  /** Maximum age for terminal EditSession artifacts once no active Work owns them. */
+  editSessionRetentionMs?: number;
+  /** Count cap for newest terminal EditSession artifacts retained for local review/debugging. */
+  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. */
+  sqliteVacuumMinReclaimableBytes?: number;
+  /** Minimum reclaimable SQLite free-page ratio before physical VACUUM is eligible. */
+  sqliteVacuumMinReclaimableRatio?: number;
   inspectProcess?: (pid: number) => RuntimeProcessSnapshot;
 }
 
+export interface RuntimeCleanupLifecycleClassMetrics {
+  count: number;
+  bytes: number;
+  unknownByteCount: number;
+}
+
+export interface RuntimeCleanupLifecycleMetrics {
+  /** Physical disposable resources actually reclaimed by this cleanup authority. */
+  reclaimedCount: number;
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  reclaimedByClass: Record<string, RuntimeCleanupLifecycleClassMetrics>;
+  /** Semantic/execution authority records retired in place rather than physically deleted. */
+  logicalRetiredCount: number;
+  logicalRetiredByClass: Record<string, number>;
+  protectedActiveCount: number;
+  protectedByReason: Record<string, number>;
+  blockerReasons: Record<string, number>;
+}
+
 export interface RuntimeCleanupReport {
+  policyVersion: typeof RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION;
   at: string;
   reason: 'startup' | 'periodic' | 'manual';
   removedPidFiles: string[];
   skippedPidFiles: string[];
   removedWorktrees: string[];
+  migratedDependencyPaths: string[];
   removedTemporaryPaths: string[];
+  removedCleanupArtifactPaths: string[];
   removedReleasePaths: string[];
+  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[];
   inspectedPaths: number;
   budgetExhausted: boolean;
   errors: string[];
   logPath: string;
   cycle: CleanupCycleSummary;
+  lifecycleMetrics: RuntimeCleanupLifecycleMetrics;
 }
 
 export interface CleanupCycleSummary {
@@ -180,6 +253,33 @@ interface RemovalBudget {
   exhausted: boolean;
 }
 
+interface MutableReclaimMetrics {
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+}
+
+function emptyReclaimMetrics(): MutableReclaimMetrics {
+  return { reclaimedBytes: 0, unknownReclaimedByteCount: 0 };
+}
+
+function addReclaimMeasurement(metrics: MutableReclaimMetrics, path: string): void {
+  const measurement = measureReclaimablePath(path);
+  if (measurement.complete) metrics.reclaimedBytes += measurement.bytes;
+  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'];
+
+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
+  // cleanup retains the complete all-phase contract.
+  return [REMOVAL_PHASES[offset]!];
+}
+
 interface WorktreeReferences {
   referenced: Set<string>;
   unsafeRepositories: Set<string>;
@@ -271,9 +371,10 @@ function cleanupDaemonPidFile(
   options: RuntimeCleanupOptions,
   errors: string[],
   removalBudget: RemovalBudget,
-): { removed: string[]; skipped: string[] } {
+): { removed: string[]; skipped: string[]; reclaim: MutableReclaimMetrics } {
+  const reclaim = emptyReclaimMetrics();
   const pidPath = join(controllerHome, 'daemon', 'controller.pid');
-  if (!existsSync(pidPath)) return { removed: [], skipped: [] };
+  if (!existsSync(pidPath)) return { removed: [], skipped: [], reclaim };
   let parsedPid: number | undefined;
   try {
     const candidate = Number.parseInt(readFileSync(pidPath, 'utf8').trim(), 10);
@@ -284,32 +385,33 @@ function cleanupDaemonPidFile(
 
   if (removalBudget.remaining <= 0) {
     removalBudget.exhausted = true;
-    return { removed: [], skipped: [relativeHomePath(controllerHome, pidPath)] };
+    return { removed: [], skipped: [relativeHomePath(controllerHome, pidPath)], reclaim };
   }
 
   if (parsedPid) {
     const snapshot = (options.inspectProcess ?? inspectProcessDefault)(parsedPid);
     if (snapshot.alive) {
       if (parsedPid === options.protectedControllerPid || expectedDaemonCommand(controllerHome, snapshot.commandLine)) {
-        return { removed: [], skipped: [relativeHomePath(controllerHome, pidPath)] };
+        return { removed: [], skipped: [relativeHomePath(controllerHome, pidPath)], reclaim };
       }
       if (!snapshot.commandLine) {
         errors.push(`daemon/controller.pid: live PID ${parsedPid} command identity is unavailable`);
-        return { removed: [], skipped: [relativeHomePath(controllerHome, pidPath)] };
+        return { removed: [], skipped: [relativeHomePath(controllerHome, pidPath)], reclaim };
       }
       // PID reuse or an unrelated live process: remove only the stale reference.
       // Never signal a process whose daemon identity is not proven.
     }
   }
 
+  addReclaimMeasurement(reclaim, pidPath);
   try {
     removalBudget.remaining -= 1;
     rmSync(pidPath, { force: true });
     updateDaemonStateForStalePid(controllerHome, parsedPid, nowIso);
-    return { removed: [relativeHomePath(controllerHome, pidPath)], skipped: [] };
+    return { removed: [relativeHomePath(controllerHome, pidPath)], skipped: [], reclaim };
   } catch (error) {
     errors.push(errorText('daemon/controller.pid removal failed', error));
-    return { removed: [], skipped: [] };
+    return { removed: [], skipped: [], reclaim: emptyReclaimMetrics() };
   }
 }
 
@@ -501,9 +603,10 @@ function cleanupOrphanWorktrees(
   nowMs: number,
   errors: string[],
   removalBudget: RemovalBudget,
-): { removed: string[]; skippedActive: string[]; skippedByReason: Record<string, number> } {
+): { removed: string[]; skippedActive: string[]; skippedByReason: Record<string, number>; reclaim: MutableReclaimMetrics } {
   const removed: string[] = [];
   const skippedActive: string[] = [];
+  const reclaim = emptyReclaimMetrics();
   const skippedByReason: Record<string, number> = {};
   const skip = (reason: string): void => { skippedByReason[reason] = (skippedByReason[reason] ?? 0) + 1; };
   const repositoriesRoot = join(controllerHome, 'repositories');
@@ -532,15 +635,74 @@ function cleanupOrphanWorktrees(
           return;
         }
         removalBudget.remaining -= 1;
+        const measurement = measureReclaimablePath(path);
         if (removeOrphanWorktreeDirectory(path, errors, relativePath)) {
           removed.push(relativePath);
+          if (measurement.complete) reclaim.reclaimedBytes += measurement.bytes;
+          else reclaim.unknownReclaimedByteCount += 1;
         }
       } catch (error) {
         errors.push(errorText(`worktree cleanup ${relativePath}`, error));
       }
     });
   });
-  return { removed, skippedActive, skippedByReason };
+  return { removed, skippedActive, skippedByReason, reclaim };
+}
+
+function cleanupManagedWorktreeDependencyCopies(
+  controllerHome: string,
+  budget: ScanBudget,
+  errors: string[],
+  removalBudget: RemovalBudget,
+): { migrated: string[]; skippedByReason: Record<string, number> } {
+  const migrated: string[] = [];
+  const skippedByReason: Record<string, number> = {};
+  const skip = (reason: string): void => { skippedByReason[reason] = (skippedByReason[reason] ?? 0) + 1; };
+  let repositories;
+  try {
+    repositories = listRepositories(controllerHome, { includeRemoved: true });
+  } catch (error) {
+    errors.push(errorText('managed dependency repository inventory', error));
+    return { migrated, skippedByReason };
+  }
+  let storageRoot: string;
+  try {
+    storageRoot = managedWorktreeStorageRoot(controllerHome, repositories);
+  } catch (error) {
+    errors.push(errorText('managed dependency storage authority', error));
+    return { migrated, skippedByReason };
+  }
+  for (const repository of repositories) {
+    const activeLeases = listActiveLeases(controllerHome, repository.repoId);
+    for (const checkout of repository.checkouts) {
+      if (budget.remaining <= 0) { budget.exhausted = true; return { migrated, skippedByReason }; }
+      budget.remaining -= 1;
+      budget.inspected += 1;
+      if (!checkout.worktree || checkout.lifecycle === 'removed' || checkout.lifecycle === 'archived') continue;
+      const root = checkout.canonicalRoot;
+      if (!existsSync(root) || !managedPathInside(storageRoot, root)) { skip('dependency_outside_managed_authority'); continue; }
+      const dependencyPath = join(root, 'node_modules');
+      if (!existsSync(dependencyPath)) continue;
+      let dependencyStats;
+      try { dependencyStats = lstatSync(dependencyPath); } catch (error) { errors.push(errorText(`managed dependency stat ${root}`, error)); continue; }
+      if (dependencyStats.isSymbolicLink()) continue;
+      if (!dependencyStats.isDirectory()) { skip('dependency_path_not_directory'); continue; }
+      if (activeLeases.some((lease) => lease.checkoutId === checkout.checkoutId || lease.resourceKey === `workspace:${checkout.checkoutId}`)) {
+        skip('dependency_active_owner');
+        continue;
+      }
+      if (removalBudget.remaining <= 0) { removalBudget.exhausted = true; skip('cleanup_budget_exhausted'); continue; }
+      try {
+        const result = migrateManagedWorkspacePhysicalDependenciesToCanonical(root);
+        if (!result) { skip('dependency_not_reusable'); continue; }
+        removalBudget.remaining -= 1;
+        migrated.push(relativeHomePath(controllerHome, dependencyPath));
+      } catch (error) {
+        errors.push(errorText(`managed dependency migration ${root}`, error));
+      }
+    }
+  }
+  return { migrated, skippedByReason };
 }
 
 function worktreeContentPath(relativePath: string): boolean {
@@ -557,6 +719,7 @@ function removeStaleTempEntry(
   errors: string[],
   removalBudget: RemovalBudget,
   skippedByReason: Record<string, number>,
+  reclaim: MutableReclaimMetrics,
 ): void {
   if (nowMs - mtimeMs < TEMP_STATE_TTL_MS) {
     skippedByReason.ttl_not_expired = (skippedByReason.ttl_not_expired ?? 0) + 1;
@@ -567,10 +730,13 @@ function removeStaleTempEntry(
     skippedByReason.cleanup_budget_exhausted = (skippedByReason.cleanup_budget_exhausted ?? 0) + 1;
     return;
   }
+  const measurement = measureReclaimablePath(path);
   try {
     removalBudget.remaining -= 1;
     rmSync(path, { recursive: isDirectory, force: true });
     removed.push(relativePath);
+    if (measurement.complete) reclaim.reclaimedBytes += measurement.bytes;
+    else reclaim.unknownReclaimedByteCount += 1;
   } catch (error) {
     errors.push(errorText(`temp-state cleanup ${relativePath}`, error));
   }
@@ -583,8 +749,9 @@ function cleanupTemporaryStatePaths(
   errors: string[],
   removalBudget: RemovalBudget,
   skippedByReason: Record<string, number>,
-): string[] {
+): { removed: string[]; reclaim: MutableReclaimMetrics } {
   const removed: string[] = [];
+  const reclaim = emptyReclaimMetrics();
   const visit = (directory: string, depth: number, leafOnly = false): void => {
     if (budget.exhausted || depth > TEMP_SCAN_MAX_DEPTH) return;
     visitDirectoryEntries(directory, budget, errors, (entry) => {
@@ -602,7 +769,7 @@ function cleanupTemporaryStatePaths(
       }
 
       if (entry.name.endsWith('.tmp')) {
-        removeStaleTempEntry(path, relativePath, entry.isDirectory(), stats.mtimeMs, nowMs, removed, errors, removalBudget, skippedByReason);
+        removeStaleTempEntry(path, relativePath, entry.isDirectory(), stats.mtimeMs, nowMs, removed, errors, removalBudget, skippedByReason, reclaim);
         return;
       }
 
@@ -622,7 +789,7 @@ function cleanupTemporaryStatePaths(
   // burn its entire budget walking historical job records.
   visit(join(controllerHome, 'daemon'), 0);
   visit(join(controllerHome, 'repositories'), 0);
-  return removed;
+  return { removed, reclaim };
 }
 
 function shouldPersistCleanupAudit(report: RuntimeCleanupReport): boolean {
@@ -631,8 +798,17 @@ function shouldPersistCleanupAudit(report: RuntimeCleanupReport): boolean {
   const hadMutations = Boolean(
     report.removedPidFiles.length
     || report.removedWorktrees.length
+    || report.migratedDependencyPaths.length
     || report.removedTemporaryPaths.length
-    || report.removedReleasePaths.length,
+    || report.removedCleanupArtifactPaths.length
+    || report.removedReleasePaths.length
+    || report.removedCodegraphLocatorPaths.length
+    || report.removedCodegraphCachePaths.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;
   // Startup/manual may record defensive skips (live PID protected, budget).
@@ -656,51 +832,412 @@ export function cleanupControllerRuntimeState(
   // worktree reference collection or orphan worktree removal.
   const referenceBudget = createScanBudget(maxEntries);
   const worktreeBudget = createScanBudget(maxEntries);
+  const dependencyBudget = createScanBudget(maxEntries);
   const tempBudget = createScanBudget(maxEntries);
+  const schedulerBudget = createScanBudget(maxEntries);
+  const editSessionBudget = createScanBudget(maxEntries);
   const errors: string[] = [];
   const skippedByReason: Record<string, number> = {};
+  const sequence = options.periodicSequence ?? Math.floor(nowMs / 60_000);
+  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,
+        nowMs,
+        graceMs: options.ownerlessWorkAuthorityGraceMs,
+      });
+      retiredOwnerlessWorkAuthorities.push(...ownerless.workIds.map((workId) => `${repository.repoId}:${workId}`));
+      Object.entries(ownerless.skippedByReason).forEach(([key, value]) => {
+        skippedByReason[`ownerless_work_${key}`] = (skippedByReason[`ownerless_work_${key}`] ?? 0) + value;
+      });
+    }
+  } catch (error) {
+    errors.push(errorText('Work authority reconciliation', error));
+  }
   const pidFiles = cleanupDaemonPidFile(home, nowIso, options, errors, removalBudget);
-  const references = collectReferencedWorktrees(home, referenceBudget, errors, nowMs);
-  const worktrees = cleanupOrphanWorktrees(home, references, worktreeBudget, nowMs, errors, removalBudget);
-  Object.entries(worktrees.skippedByReason).forEach(([key, value]) => { skippedByReason[key] = (skippedByReason[key] ?? 0) + value; });
-  const removedTemporaryPaths = cleanupTemporaryStatePaths(home, tempBudget, nowMs, errors, removalBudget, skippedByReason).sort();
-  const releaseRetention = cleanupControllerReleaseHistory(home, {
-    nowMs,
-    graceMs: options.releaseRetentionGraceMs,
-    stagingGraceMs: options.stagingReleaseRetentionGraceMs,
-    maxRemovals: removalBudget.remaining,
-  });
-  removalBudget.remaining = Math.max(0, removalBudget.remaining - releaseRetention.attempted);
-  if (releaseRetention.budgetExhausted) removalBudget.exhausted = true;
-  Object.entries(releaseRetention.skippedByReason).forEach(([key, value]) => {
-    skippedByReason[key] = (skippedByReason[key] ?? 0) + value;
-  });
-  errors.push(...releaseRetention.errors);
-  const removedReleasePaths = releaseRetention.removedPaths;
-  const inspectedPaths = referenceBudget.inspected + worktreeBudget.inspected + tempBudget.inspected + releaseRetention.inspected;
-  const budgetExhausted = referenceBudget.exhausted || worktreeBudget.exhausted || tempBudget.exhausted || removalBudget.exhausted;
+  const references: WorktreeReferences = (!periodic || removalPhases.includes('worktrees'))
+    ? collectReferencedWorktrees(home, referenceBudget, errors, nowMs)
+    : { referenced: new Set<string>(), unsafeRepositories: new Set<string>(), complete: true };
+  let worktrees: ReturnType<typeof cleanupOrphanWorktrees> | undefined;
+  let dependencyCleanup: ReturnType<typeof cleanupManagedWorktreeDependencyCopies> | undefined;
+  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 repositoryNamespaceRetention: ReturnType<typeof cleanupRetiredRepositoryNamespaces> | undefined;
+  const removedCodegraphLocatorPaths: string[] = [];
+  let codegraphLocatorInspected = 0;
+  let codegraphLocatorRetained = 0;
+  const schedulerHistory = {
+    removedOccurrencePaths: [] as string[],
+    removedDecisionPaths: [] as string[],
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+    inspected: 0,
+    eligible: 0,
+    attempted: 0,
+    retained: 0,
+    errors: [] as string[],
+  };
+  const editSessionHistory = {
+    removedPaths: [] as string[],
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+    inspected: 0,
+    eligible: 0,
+    attempted: 0,
+    retained: 0,
+    errors: [] as string[],
+  };
+  for (const phase of removalPhases) {
+    if (phase === 'worktrees') {
+      dependencyCleanup = cleanupManagedWorktreeDependencyCopies(home, dependencyBudget, errors, removalBudget);
+      Object.entries(dependencyCleanup.skippedByReason).forEach(([key, value]) => { skippedByReason[key] = (skippedByReason[key] ?? 0) + value; });
+      worktrees = cleanupOrphanWorktrees(home, references, worktreeBudget, nowMs, errors, removalBudget);
+      Object.entries(worktrees.skippedByReason).forEach(([key, value]) => { skippedByReason[key] = (skippedByReason[key] ?? 0) + value; });
+      continue;
+    }
+    if (phase === 'temporary') {
+      temporaryCleanup = cleanupTemporaryStatePaths(home, tempBudget, nowMs, errors, removalBudget, skippedByReason);
+      continue;
+    }
+    if (phase === 'artifacts') {
+      if (removalBudget.remaining > 0) {
+        try {
+          const removed = cleanupExpiredExperiences(home, new Date(nowMs).toISOString(), Math.min(100, removalBudget.remaining));
+          removalBudget.remaining -= removed;
+        } catch (error) { errors.push(`experience-retention: ${error instanceof Error ? error.message : 'failed'}`); }
+      }
+      artifactRetention = cleanupWorkPreservationArtifacts(home, {
+        nowMs,
+        graceMs: options.cleanupArtifactRetentionGraceMs,
+        maxEntries,
+        maxRemovals: removalBudget.remaining,
+      });
+      removalBudget.remaining = Math.max(0, removalBudget.remaining - artifactRetention.attempted);
+      if (artifactRetention.budgetExhausted) removalBudget.exhausted = true;
+      Object.entries(artifactRetention.skippedByReason).forEach(([key, value]) => {
+        skippedByReason[`cleanup_artifact_${key}`] = (skippedByReason[`cleanup_artifact_${key}`] ?? 0) + value;
+      });
+      errors.push(...artifactRetention.errors.map((error) => `cleanup-artifact ${error}`));
+      continue;
+    }
+    if (phase === 'scheduler') {
+      for (const repository of listRepositories(home, { includeRemoved: true })) {
+        if (schedulerBudget.remaining <= 0 || removalBudget.remaining <= 0) {
+          if (schedulerBudget.remaining <= 0) schedulerBudget.exhausted = true;
+          if (removalBudget.remaining <= 0) removalBudget.exhausted = true;
+          break;
+        }
+        const retained = cleanupScheduleOccurrenceHistory(home, repository.repoId, {
+          maxEntries: schedulerBudget.remaining,
+          maxRemovals: removalBudget.remaining,
+        });
+        schedulerBudget.remaining = Math.max(0, schedulerBudget.remaining - retained.inspected);
+        schedulerBudget.inspected += retained.inspected;
+        if (retained.budgetExhausted && schedulerBudget.remaining <= 0) schedulerBudget.exhausted = true;
+        removalBudget.remaining = Math.max(0, removalBudget.remaining - retained.attempted);
+        if (retained.budgetExhausted && removalBudget.remaining <= 0) removalBudget.exhausted = true;
+        schedulerHistory.inspected += retained.inspected;
+        schedulerHistory.eligible += retained.eligible;
+        schedulerHistory.attempted += retained.attempted;
+        schedulerHistory.retained += retained.retained;
+        schedulerHistory.reclaimedBytes += retained.reclaimedBytes;
+        schedulerHistory.unknownReclaimedByteCount += retained.unknownReclaimedByteCount;
+        schedulerHistory.removedOccurrencePaths.push(...retained.removedOccurrencePaths.map((path) => `repositories/${repository.repoId}/schedules/${path}`));
+        schedulerHistory.removedDecisionPaths.push(...retained.removedDecisionPaths.map((path) => `repositories/${repository.repoId}/schedules/${path}`));
+        Object.entries(retained.skippedByReason).forEach(([key, value]) => {
+          skippedByReason[`scheduler_${key}`] = (skippedByReason[`scheduler_${key}`] ?? 0) + value;
+        });
+        schedulerHistory.errors.push(...retained.errors.map((error) => `${repository.repoId}:${error}`));
+      }
+      errors.push(...schedulerHistory.errors.map((error) => `scheduler-history ${error}`));
+      continue;
+    }
+    if (phase === 'edit_sessions') {
+      for (const repository of listRepositories(home, { includeRemoved: true })) {
+        if (editSessionBudget.remaining <= 0 || removalBudget.remaining <= 0) {
+          if (editSessionBudget.remaining <= 0) editSessionBudget.exhausted = true;
+          if (removalBudget.remaining <= 0) removalBudget.exhausted = true;
+          break;
+        }
+        let protectedWorkIds: string[];
+        try {
+          protectedWorkIds = readWorkContractStore({ controllerHome: home, repoId: repository.repoId }).contracts
+            .filter((contract) => !isTerminalWorkContractStatus(contract.status))
+            .map((contract) => contract.workId);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          skippedByReason.edit_session_work_authority_unavailable = (skippedByReason.edit_session_work_authority_unavailable ?? 0) + 1;
+          editSessionHistory.errors.push(`${repository.repoId}:work_authority_unavailable:${message}`);
+          continue;
+        }
+        const retained = cleanupTerminalEditSessionRecords(repository.canonicalRoot, {
+          nowMs,
+          retentionMs: options.editSessionRetentionMs,
+          maxRetained: options.editSessionMaxRetained,
+          maxEntries: editSessionBudget.remaining,
+          maxRemovals: removalBudget.remaining,
+          sequence,
+          protectedWorkIds,
+        });
+        editSessionBudget.remaining = Math.max(0, editSessionBudget.remaining - retained.inspected);
+        editSessionBudget.inspected += retained.inspected;
+        if (retained.budgetExhausted && editSessionBudget.remaining <= 0) editSessionBudget.exhausted = true;
+        removalBudget.remaining = Math.max(0, removalBudget.remaining - retained.attempted);
+        if (retained.budgetExhausted && removalBudget.remaining <= 0) removalBudget.exhausted = true;
+        editSessionHistory.inspected += retained.inspected;
+        editSessionHistory.eligible += retained.eligible;
+        editSessionHistory.attempted += retained.attempted;
+        editSessionHistory.retained += retained.retained;
+        editSessionHistory.reclaimedBytes += retained.reclaimedBytes;
+        editSessionHistory.unknownReclaimedByteCount += retained.unknownReclaimedByteCount;
+        editSessionHistory.removedPaths.push(...retained.removedSessionIds.map((sessionId) => `repositories/${repository.repoId}/edit-sessions/${sessionId}`));
+        Object.entries(retained.skippedByReason).forEach(([key, value]) => {
+          skippedByReason[`edit_session_${key}`] = (skippedByReason[`edit_session_${key}`] ?? 0) + value;
+        });
+        editSessionHistory.errors.push(...retained.errors.map((error) => `${repository.repoId}:${error}`));
+      }
+      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,
+        graceMs: options.repositoryNamespaceRetentionMs,
+        maxEntries,
+        maxRemovals: removalBudget.remaining,
+      });
+      removalBudget.remaining = Math.max(0, removalBudget.remaining - repositoryNamespaceRetention.attempted);
+      if (repositoryNamespaceRetention.budgetExhausted && removalBudget.remaining <= 0) removalBudget.exhausted = true;
+      Object.entries(repositoryNamespaceRetention.skippedByReason).forEach(([key, value]) => {
+        skippedByReason[`repository_namespace_${key}`] = (skippedByReason[`repository_namespace_${key}`] ?? 0) + value;
+      });
+      errors.push(...repositoryNamespaceRetention.errors.map((error) => `repository-namespace ${error}`));
+      continue;
+    }
+    releaseRetention = cleanupControllerReleaseHistory(home, {
+      nowMs,
+      graceMs: options.releaseRetentionGraceMs,
+      stagingGraceMs: options.stagingReleaseRetentionGraceMs,
+      maxRemovals: removalBudget.remaining,
+    });
+    removalBudget.remaining = Math.max(0, removalBudget.remaining - releaseRetention.attempted);
+    if (releaseRetention.budgetExhausted) removalBudget.exhausted = true;
+    Object.entries(releaseRetention.skippedByReason).forEach(([key, value]) => {
+      skippedByReason[key] = (skippedByReason[key] ?? 0) + value;
+    });
+    errors.push(...releaseRetention.errors);
+  }
+  if (periodic) {
+    worktrees ??= { removed: [], skippedActive: [], skippedByReason: {}, reclaim: emptyReclaimMetrics() } as ReturnType<typeof cleanupOrphanWorktrees>;
+    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>;
+  }
+  if (!worktrees || !dependencyCleanup || !temporaryCleanup || !artifactRetention || !codegraphRetention || !repositoryNamespaceRetention || !releaseRetention) {
+    throw new Error('RUNTIME_CLEANUP_PHASE_INCOMPLETE');
+  }
+  const removedTemporaryPaths = temporaryCleanup.removed.sort();
+  const removedCleanupArtifactPaths = artifactRetention.removedPaths.sort();
+  const removedReleasePaths = releaseRetention.removedPaths.sort();
+  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 {
+    sqliteMaintenance = maintainControlPlaneDatabase(home, {
+      minimumReclaimableBytes: options.sqliteVacuumMinReclaimableBytes,
+      minimumReclaimableRatio: options.sqliteVacuumMinReclaimableRatio,
+    });
+    if (sqliteMaintenance.skippedReason === 'database_busy') {
+      skippedByReason.sqlite_maintenance_busy = (skippedByReason.sqlite_maintenance_busy ?? 0) + 1;
+    }
+  } 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;
   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> = {
+    managed_workspace_checkout: {
+      count: worktrees.removed.length,
+      bytes: worktrees.reclaim.reclaimedBytes,
+      unknownByteCount: worktrees.reclaim.unknownReclaimedByteCount,
+    },
+    runtime_temp: {
+      count: pidFiles.removed.length + removedTemporaryPaths.length + removedCodegraphLocatorPaths.length,
+      bytes: pidFiles.reclaim.reclaimedBytes + temporaryCleanup.reclaim.reclaimedBytes,
+      unknownByteCount: pidFiles.reclaim.unknownReclaimedByteCount + temporaryCleanup.reclaim.unknownReclaimedByteCount + removedCodegraphLocatorPaths.length,
+    },
+    work: {
+      count: removedCleanupArtifactPaths.length,
+      bytes: artifactRetention.reclaimedBytes,
+      unknownByteCount: artifactRetention.unknownReclaimedByteCount,
+    },
+    release_artifact: {
+      count: Math.max(0, removedReleasePaths.length - releaseRetention.removedBackupPaths.length),
+      bytes: Math.max(0, releaseRetention.reclaimedBytes - releaseRetention.reclaimedBackupBytes),
+      unknownByteCount: Math.max(0, releaseRetention.unknownReclaimedByteCount - releaseRetention.unknownReclaimedBackupByteCount),
+    },
+    recovery_backup: {
+      count: releaseRetention.removedBackupPaths.length,
+      bytes: releaseRetention.reclaimedBackupBytes,
+      unknownByteCount: releaseRetention.unknownReclaimedBackupByteCount,
+    },
+    scheduler_occurrence_history: {
+      count: removedScheduleOccurrencePaths.length + removedScheduleDecisionPaths.length,
+      bytes: schedulerHistory.reclaimedBytes,
+      unknownByteCount: schedulerHistory.unknownReclaimedByteCount,
+    },
+    edit_session: {
+      count: removedEditSessionPaths.length,
+      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,
+      unknownByteCount: repositoryNamespaceRetention.unknownReclaimedByteCount,
+    },
+    sqlite_control_plane: {
+      count: sqliteMaintenance?.vacuumed ? 1 : 0,
+      bytes: sqliteMaintenance?.reclaimedBytes ?? 0,
+      unknownByteCount: 0,
+    },
+  };
+  const protectedByReason = Object.fromEntries(
+    Object.entries(skippedByReason)
+      .filter(([reason, count]) => count > 0 && (reason.includes('active') || reason.includes('authority') || reason.includes('protected')))
+      .sort(([left], [right]) => left.localeCompare(right)),
+  );
+  const blockerReasons = Object.fromEntries(
+    Object.entries(skippedByReason)
+      .filter(([reason, count]) => count > 0 && (reason.includes('unknown') || reason.includes('budget') || reason.includes('unsafe') || reason.includes('unavailable') || reason.includes('busy')))
+      .sort(([left], [right]) => left.localeCompare(right)),
+  );
+  const lifecycleMetrics: RuntimeCleanupLifecycleMetrics = {
+    reclaimedCount: Object.values(physicalReclaimedByClass).reduce((total, entry) => total + entry.count, 0),
+    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 },
+    protectedActiveCount: Object.values(protectedByReason).reduce((total, count) => total + count, 0),
+    protectedByReason,
+    blockerReasons,
+  };
   const report: RuntimeCleanupReport = {
+    policyVersion: RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION,
     at: nowIso,
     reason: options.reason ?? 'manual',
     removedPidFiles: pidFiles.removed.sort(),
     skippedPidFiles: pidFiles.skipped.sort(),
     removedWorktrees: worktrees.removed.sort(),
+    migratedDependencyPaths: dependencyCleanup.migrated.sort(),
     removedTemporaryPaths,
+    removedCleanupArtifactPaths,
     removedReleasePaths,
+    removedScheduleOccurrencePaths,
+    removedScheduleDecisionPaths,
+    removedEditSessionPaths,
+    removedCodegraphLocatorPaths,
+    removedCodegraphCachePaths,
+    removedRepositoryNamespacePaths,
+    sqliteMaintenance,
+    retiredPlanBoundWorkAuthorities: retiredPlanBoundWorkAuthorities.sort(),
+    retiredOwnerlessWorkAuthorities: retiredOwnerlessWorkAuthorities.sort(),
     skippedActiveWorktrees: worktrees.skippedActive.sort(),
     inspectedPaths,
     budgetExhausted,
     errors: errors.sort(),
     logPath: runtimeCleanupLogPath(home),
+    lifecycleMetrics,
     cycle: {
       scanned: inspectedPaths,
-      eligible: pidFiles.removed.length + worktrees.removed.length + removedTemporaryPaths.length + releaseRetention.eligible,
-      attempted: pidFiles.removed.length + worktrees.removed.length + removedTemporaryPaths.length + releaseRetention.attempted + errors.length,
-      removed: pidFiles.removed.length + worktrees.removed.length + removedTemporaryPaths.length + removedReleasePaths.length,
-      retained: pidFiles.skipped.length + worktrees.skippedActive.length + releaseRetention.retained,
-      skipped: Math.max(0, inspectedPaths - pidFiles.removed.length - worktrees.removed.length - removedTemporaryPaths.length - removedReleasePaths.length - errors.length),
+      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),
       failed: errors.length,
       truncated: budgetExhausted,
       budgetExhausted,