@moretea-labs/forge 1.8.1 → 1.8.2

package/src/runtime/control-plane/generated-cache-retention.ts

@@ -26,6 +26,7 @@ export interface GeneratedCacheRetentionOptions {
   maxRemovals?: number;
   processCommands?: string[];
   rootStartIndex?: number;
+  scanStartIndex?: number;
 }
 
 export interface GeneratedCacheRetentionReport {
@@ -95,6 +96,7 @@ export interface XCTestDeviceCleanupReport {
 
 interface Candidate {
   path: string;
+  cacheRoot?: string;
   kind:
     | 'forge_ios_derived_data'
     | 'harness_derived_data'
@@ -119,7 +121,7 @@ function pathInside(root: string, path: string): boolean {
   return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`);
 }
 
-function collectProcessCommands(): string[] {
+function collectProcessCommands(): string[] | undefined {
   try {
     return execFileSync('ps', ['-axo', 'command='], {
       encoding: 'utf8',
@@ -127,7 +129,8 @@ function collectProcessCommands(): string[] {
       maxBuffer: 2 * 1024 * 1024,
     }).split('\n').map((line) => line.trim()).filter(Boolean);
   } catch {
-    return [];
+    // Missing process evidence is not proof that a cache is idle.
+    return undefined;
   }
 }
 
@@ -142,6 +145,19 @@ function commandReferencesPath(commands: readonly string[], repoRoot: string, pa
     || (canonicalRelative && command.includes(canonicalRelative)));
 }
 
+function hasSymlinkAncestor(root: string, path: string): boolean {
+  const rel = relative(resolve(root), resolve(path));
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`)) return true;
+  let current = resolve(root);
+  try {
+    for (const part of rel.split(sep)) {
+      current = join(current, part);
+      if (lstatSync(current).isSymbolicLink()) return true;
+    }
+    return false;
+  } catch { return true; }
+}
+
 function containsTrackedFiles(repoRoot: string, path: string): boolean {
   const rel = relative(resolve(repoRoot), resolve(path));
   if (!rel || rel === '..' || rel.startsWith(`..${sep}`)) return true;
@@ -158,92 +174,106 @@ function containsTrackedFiles(repoRoot: string, path: string): boolean {
   }
 }
 
-function directChildDirectories(root: string, predicate: (name: string) => boolean, budget: { remaining: number }): string[] {
-  if (!existsSync(root) || budget.remaining <= 0) return [];
+const REBUILDABLE_XCODE_CHILDREN = [
+  'Build', 'ModuleCache.noindex', 'Index.noindex', 'CompilationCache.noindex',
+  'SDKExplicitPrecompiledModules', 'SDKStatCaches.noindex',
+] as const;
+
+function rotatedEntries(root: string, round: number) {
+  try {
+    const entries = readdirSync(root, { withFileTypes: true }).sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    if (entries.length > 1) {
+      const offset = ((Math.trunc(round) % entries.length) + entries.length) % entries.length;
+      entries.push(...entries.splice(0, offset));
+    }
+    return entries;
+  } catch { return []; }
+}
+
+function directChildDirectories(root: string, predicate: (name: string) => boolean, budget: { remaining: number }, round = 0): string[] {
   const found: string[] = [];
-  let entries;
-  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return found; }
-  for (const entry of entries) {
+  if (budget.remaining <= 0) return found;
+  for (const entry of rotatedEntries(root, round)) {
     if (budget.remaining <= 0) break;
     budget.remaining -= 1;
-    const name = String(entry.name);
-    if (entry.isDirectory() && predicate(name)) found.push(join(root, name));
+    if (entry.isDirectory() && predicate(String(entry.name))) found.push(join(root, String(entry.name)));
   }
   return found;
 }
 
 function directChildFiles(root: string, budget: { remaining: number }): string[] {
-  if (!existsSync(root) || budget.remaining <= 0) return [];
   const found: string[] = [];
-  let entries;
-  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return found; }
-  for (const entry of entries) {
+  if (budget.remaining <= 0) return found;
+  for (const entry of rotatedEntries(root, 0)) {
     if (budget.remaining <= 0) break;
     budget.remaining -= 1;
-    if (entry.isFile()) found.push(join(root, entry.name));
+    if (entry.isFile()) found.push(join(root, String(entry.name)));
   }
   return found;
 }
 
-function isDerivedDataDirectoryName(name: string): boolean {
-  return name === 'DerivedData' || name.startsWith('DerivedData-');
+function isXcodeCacheRoot(root: string): boolean {
+  try {
+    const info = lstatSync(join(root, 'info.plist'));
+    return info.isFile() && !info.isSymbolicLink() && REBUILDABLE_XCODE_CHILDREN.some((name) => {
+      try { const stat = lstatSync(join(root, name)); return stat.isDirectory() && !stat.isSymbolicLink(); } catch { return false; }
+    });
+  } catch { return false; }
 }
 
-function nestedDerivedDataDirectories(root: string, maxDepth: number, budget: { remaining: number }): string[] {
-  if (!existsSync(root) || budget.remaining <= 0) return [];
+function nestedDerivedDataDirectories(root: string, maxDepth: number, budget: { remaining: number }, round: number): string[] {
   const found: string[] = [];
-  const visit = (dir: string, depth: number): void => {
+  const visit = (dir: string, depth: number, visitRound: number): void => {
     if (depth > maxDepth || budget.remaining <= 0) return;
-    let entries;
-    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    const entries = rotatedEntries(dir, visitRound);
+    // Divide at each level rather than correlating parent/child rotations.
+    const childRound = Math.floor(visitRound / Math.max(1, entries.length));
     for (const entry of entries) {
       if (budget.remaining <= 0) return;
       budget.remaining -= 1;
-      if (!entry.isDirectory()) continue;
-      const path = join(dir, String(entry.name));
-      if (isDerivedDataDirectoryName(String(entry.name))) {
-        found.push(path);
-        continue;
-      }
-      visit(path, depth + 1);
+      const name = String(entry.name);
+      if (!entry.isDirectory() || ['.git', 'node_modules', 'SourcePackages', 'Logs', ...REBUILDABLE_XCODE_CHILDREN].includes(name) || name.endsWith('.xcresult')) continue;
+      const path = join(dir, name);
+      if (isXcodeCacheRoot(path)) found.push(path);
+      else visit(path, depth + 1, childRound);
     }
   };
-  visit(root, 0);
+  visit(root, 0, round);
   return found;
 }
 
-function discoverCandidates(repoRoot: string, maxEntries: number): { candidates: Candidate[]; inspected: number; truncated: boolean } {
+function discoverCandidates(repoRoot: string, maxEntries: number, scanRound: number): { candidates: Candidate[]; inspected: number; truncated: boolean } {
   const root = resolve(repoRoot);
   const budget = { remaining: Math.max(1, maxEntries) };
   const initial = budget.remaining;
   const candidates: Candidate[] = [];
-
-  // Browser artifacts are direct children of small, explicitly owned roots.
-  // Scan them before recursively walking potentially high-cardinality cache
-  // trees so cache history cannot starve their retention policy.
-  for (const path of directChildFiles(join(root, '.forge', 'browser', 'uploads'), budget)) {
-    candidates.push({ path, kind: 'forge_browser_upload' });
-  }
-  for (const path of directChildFiles(join(root, '.forge', 'browser', 'screenshots'), budget)) {
-    candidates.push({ path, kind: 'forge_browser_screenshot' });
-  }
-  for (const path of directChildDirectories(join(root, '.forge', 'ios', 'DerivedData'), () => true, budget)) {
-    candidates.push({ path, kind: 'forge_ios_derived_data' });
-  }
-  for (const path of directChildDirectories(join(root, '.ai', 'harness'), (name) => name.startsWith('deriveddata-'), budget)) {
-    candidates.push({ path, kind: 'harness_derived_data' });
-  }
-  for (const path of nestedDerivedDataDirectories(join(root, '.repo-harness'), 5, budget)) {
-    candidates.push({ path, kind: 'repo_harness_derived_data' });
-  }
-  for (const path of nestedDerivedDataDirectories(join(root, '.tmp'), 6, budget)) {
-    candidates.push({ path, kind: 'tmp_derived_data' });
+  // Preserve browser staging priority. Cache namespace and nested entry rotations
+  // use independent visit ordinals, so protected early entries cannot starve peers.
+  for (const path of directChildFiles(join(root, '.forge', 'browser', 'uploads'), budget)) candidates.push({ path, kind: 'forge_browser_upload' });
+  for (const path of directChildFiles(join(root, '.forge', 'browser', 'screenshots'), budget)) candidates.push({ path, kind: 'forge_browser_screenshot' });
+  const namespaces: Array<{ root: string; kind: Candidate['kind']; depth?: number }> = [
+    { root: join(root, '.forge', 'ios', 'DerivedData'), kind: 'forge_ios_derived_data' },
+    { root: join(root, '.ai', 'harness'), kind: 'harness_derived_data' },
+    { root: join(root, '.repo-harness'), kind: 'repo_harness_derived_data', depth: 5 },
+    { root: join(root, '.tmp'), kind: 'tmp_derived_data', depth: 6 },
+  ];
+  const offset = ((Math.trunc(scanRound) % namespaces.length) + namespaces.length) % namespaces.length;
+  namespaces.push(...namespaces.splice(0, offset));
+  const entryRound = Math.floor(scanRound / namespaces.length);
+  for (const namespace of namespaces) {
+    const cacheRoots = namespace.depth === undefined
+      ? directChildDirectories(namespace.root, () => true, budget, entryRound).filter(isXcodeCacheRoot)
+      : nestedDerivedDataDirectories(namespace.root, namespace.depth, budget, entryRound);
+    for (const cacheRoot of cacheRoots) {
+      // Never remove the bucket: Logs, results, SourcePackages and unknown files
+      // are evidence/dependencies, not disposable build cache.
+      for (const name of REBUILDABLE_XCODE_CHILDREN) {
+        const path = join(cacheRoot, name);
+        if (existsSync(path)) candidates.push({ path, kind: namespace.kind, cacheRoot });
+      }
+    }
   }
-  return {
-    candidates: candidates.filter((candidate, index, values) => values.findIndex((item) => resolve(item.path) === resolve(candidate.path)) === index),
-    inspected: initial - budget.remaining,
-    truncated: budget.remaining <= 0,
-  };
+  return { candidates, inspected: initial - budget.remaining, truncated: budget.remaining <= 0 };
 }
 
 function retentionGraceMs(candidate: Candidate, explicitGraceMs: number | undefined): number {
@@ -279,7 +309,7 @@ export function cleanupGeneratedRepositoryCaches(
   const maxEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_SCAN_BUDGET));
   let remainingRemovals = Math.max(1, Math.floor(options.maxRemovals ?? DEFAULT_REMOVAL_BUDGET));
   const commands = options.processCommands ?? collectProcessCommands();
-  const discovered = discoverCandidates(repoRoot, maxEntries);
+  const discovered = discoverCandidates(repoRoot, maxEntries, options.scanStartIndex ?? 0);
   const report: GeneratedCacheRetentionReport = {
     inspected: discovered.inspected,
     eligible: 0,
@@ -290,26 +320,34 @@ export function cleanupGeneratedRepositoryCaches(
     budgetExhausted: discovered.truncated,
   };
 
+  if (commands === undefined) {
+    report.errors.push('process_inventory_unavailable: generated-cache reclamation skipped');
+    report.skippedByReason.process_inventory_unavailable = 1;
+    return report;
+  }
   for (const candidate of discovered.candidates) {
     const ownedRoot = candidateOwnedRoot(repoRoot, candidate);
     const fileCandidate = candidate.kind === 'forge_browser_upload' || candidate.kind === 'forge_browser_screenshot';
     try {
       const stat = lstatSync(candidate.path);
-      if ((fileCandidate ? !stat.isFile() : !stat.isDirectory()) || stat.isSymbolicLink() || !pathInside(ownedRoot, candidate.path)) {
+      if ((fileCandidate ? !stat.isFile() : !stat.isDirectory()) || stat.isSymbolicLink() || hasSymlinkAncestor(repoRoot, candidate.path) || !pathInside(ownedRoot, candidate.path)) {
         increment(report.skippedByReason, 'ownership_unproven');
         report.retainedPaths.push(relative(repoRoot, candidate.path));
         continue;
       }
-      if (nowMs - stat.mtimeMs < retentionGraceMs(candidate, options.graceMs)) {
+      const usedAt = candidate.cacheRoot ? Math.max(stat.mtimeMs, lstatSync(candidate.cacheRoot).mtimeMs) : stat.mtimeMs;
+      if (nowMs - usedAt < retentionGraceMs(candidate, options.graceMs)) {
         increment(report.skippedByReason, 'retention_grace');
         continue;
       }
-      if (commandReferencesPath(commands, repoRoot, candidate.path)) {
+      if (commandReferencesPath(commands, repoRoot, candidate.cacheRoot ?? candidate.path)
+        || (candidate.cacheRoot && commands.some((command) => /(?:^|[/\s])xcodebuild(?:\s|$)/.test(command)
+          && !/(?:^|\s)-derivedDataPath(?:\s|=)/.test(command)))) {
         increment(report.skippedByReason, 'active_process');
         report.retainedPaths.push(relative(repoRoot, candidate.path));
         continue;
       }
-      if (containsTrackedFiles(repoRoot, candidate.path)) {
+      if (containsTrackedFiles(repoRoot, candidate.cacheRoot ?? candidate.path)) {
         increment(report.skippedByReason, 'tracked_content');
         report.retainedPaths.push(relative(repoRoot, candidate.path));
         continue;
@@ -320,6 +358,12 @@ export function cleanupGeneratedRepositoryCaches(
         increment(report.skippedByReason, 'cleanup_budget_exhausted');
         continue;
       }
+      // Recheck last-use immediately before removal: discovery and Git probes
+      // may overlap a cache reuse that refreshed the bucket after our first stat.
+      if (candidate.cacheRoot && lstatSync(candidate.cacheRoot).mtimeMs !== usedAt && nowMs - lstatSync(candidate.cacheRoot).mtimeMs < retentionGraceMs(candidate, options.graceMs)) {
+        increment(report.skippedByReason, 'retention_grace');
+        continue;
+      }
       remainingRemovals -= 1;
       rmSync(candidate.path, { recursive: true, force: true });
       report.removedPaths.push(relative(repoRoot, candidate.path).replace(/\\/g, '/'));
@@ -358,10 +402,10 @@ export function cleanupGeneratedRepositoryCheckoutCaches(
   }
   const rawRoots = roots.map((root) => resolve(root));
   const canonicalRoots = roots.map((root) => canonical(root));
-  const processCommandsForRoot = (root: string): string[] => {
+  const processCommandsForRoot = (root: string): string[] | undefined => {
     const rawRoot = resolve(root);
     const canonicalRoot = canonical(root);
-    return processCommands.filter((command) => {
+    return processCommands?.filter((command) => {
       const referencedRootIndexes = rawRoots
         .map((candidate, index) => command.includes(candidate) || command.includes(canonicalRoots[index]!) ? index : -1)
         .filter((index) => index >= 0);
@@ -381,6 +425,11 @@ export function cleanupGeneratedRepositoryCheckoutCaches(
     budgetExhausted: false,
   };
 
+  if (processCommands === undefined) {
+    aggregate.errors.push('process_inventory_unavailable: generated-cache reclamation skipped');
+    aggregate.skippedByReason.process_inventory_unavailable = 1;
+    return aggregate;
+  }
   for (const root of roots) {
     if (remainingEntries <= 0 || remainingRemovals <= 0) {
       aggregate.budgetExhausted = true;
@@ -389,6 +438,7 @@ export function cleanupGeneratedRepositoryCheckoutCaches(
     const report = cleanupGeneratedRepositoryCaches(root, {
       ...options,
       processCommands: processCommandsForRoot(root),
+      scanStartIndex: options.scanStartIndex ?? Math.floor((options.rootStartIndex ?? 0) / Math.max(1, roots.length)),
       maxEntries: remainingEntries,
       maxRemovals: remainingRemovals,
     });
@@ -565,6 +615,7 @@ export function cleanupIdleXCTestDevices(controllerHome: string): XCTestDeviceCl
   if (deviceDirectories <= 4) return { attempted: false, removedDevices: 0, skippedReason: 'below_cleanup_threshold' };
 
   const commands = collectProcessCommands();
+  if (commands === undefined) return { attempted: false, removedDevices: 0, skippedReason: 'process_inventory_unavailable' };
   if (commands.some((command) => /(?:^|\/)(?:xcodebuild|xctest|swiftc)(?:\s|$)/.test(command))) {
     return { attempted: false, removedDevices: 0, skippedReason: 'active_xcode_process' };
   }

package/src/runtime/control-plane/global-scheduler/maintenance.ts

@@ -80,6 +80,8 @@ export function planSchedulerPeriodicMaintenance(input: {
 }): {
   periodicSequence: number;
   deepRetentionSequence: number;
+  generatedCacheRepositoryIndex?: number;
+  generatedCacheRootStartIndex: number;
   runRetention: boolean;
   runDeepRetention: boolean;
   processGcRepositoryIndex?: number;
@@ -94,6 +96,9 @@ export function planSchedulerPeriodicMaintenance(input: {
   return {
     periodicSequence,
     deepRetentionSequence,
+    generatedCacheRepositoryIndex: repositoryCount > 0 && periodicSequence % retentionEvery === 0
+      ? Math.floor(periodicSequence / retentionEvery) % repositoryCount : undefined,
+    generatedCacheRootStartIndex: repositoryCount > 0 ? Math.floor(periodicSequence / retentionEvery / repositoryCount) : 0,
     runRetention: periodicSequence % retentionEvery === 0,
     runDeepRetention: periodicSequence % deepRetentionEvery === 0,
     processGcRepositoryIndex: repositoryCount > 0 ? periodicSequence % repositoryCount : undefined,
@@ -271,6 +276,21 @@ export async function runSchedulerPeriodicCleanup(input: {
     }
   }
 
+  // Cache production is much faster than evidence retention. Reuse the existing
+  // five-minute pass, one repository and one bounded budget per pass. The root
+  // ordinal advances per repository visit, not by the correlated global index.
+  if (plan.generatedCacheRepositoryIndex !== undefined) {
+    if (!runtimeMaintenanceAuthorityCurrent(input.controllerHome)) return;
+    const cacheRepo = input.repositories[plan.generatedCacheRepositoryIndex]!;
+    try {
+      const generated = cleanupGeneratedRepositoryCheckoutCaches(cacheRepo, {
+        nowMs: input.nowMs, rootStartIndex: plan.generatedCacheRootStartIndex,
+      });
+      if (generated.errors.length > 0) console.error(`[forge cleanup] generated-cache retention reported ${generated.errors.length} error(s) for ${cacheRepo.repoId}`);
+    } catch (error) {
+      console.error(`[forge cleanup] generated-cache retention failed for ${cacheRepo.repoId}:`, error);
+    }
+  }
   if (!plan.runDeepRetention) return;
   if (!runtimeMaintenanceAuthorityCurrent(input.controllerHome)) return;
 
@@ -285,14 +305,6 @@ export async function runSchedulerPeriodicCleanup(input: {
   }
   if (plan.deepRetentionRepositoryIndex === undefined) return;
   const repo = input.repositories[plan.deepRetentionRepositoryIndex]!;
-  try {
-    const generated = cleanupGeneratedRepositoryCheckoutCaches(repo, { nowMs: input.nowMs, rootStartIndex: plan.deepRetentionSequence });
-    if (generated.errors.length > 0) {
-      console.error(`[forge cleanup] generated-cache retention reported ${generated.errors.length} error(s) for ${repo.repoId}`);
-    }
-  } catch (error) {
-    console.error(`[forge cleanup] generated-cache retention failed for ${repo.repoId}:`, error);
-  }
   try {
     const browserArtifacts = cleanupControllerHomeBrowserArtifacts(input.controllerHome, repo.repoId, { nowMs: input.nowMs });
     if (browserArtifacts.errors.length > 0 || Object.values(browserArtifacts.classes).some((item) => item.overCapacity)) {

package/src/runtime/control-plane/global-scheduler/reconciliation.ts

@@ -8,7 +8,7 @@ import {
   childReferenceFromJob,
   childReferenceFromReceipt,
   hasDurableChildReference,
-  isAgentDelegationOperation,
+  isAgentDelegationJob,
   mergeChildReferences,
   buildDelegatedExecutionResult,
 } from '../../execution/jobs/child-reference';
@@ -34,16 +34,6 @@ function canAutomaticallyReplay(job: ExecutionJob): boolean {
   return !hasPotentialSideEffects(job);
 }
 
-function isAgentDelegationJob(job: ExecutionJob): boolean {
-  return isAgentDelegationOperation(job.payload.operation)
-    || job.type === 'agent-run'
-    || job.type === 'dispatch-task'
-    || job.payload.arguments?.agentDelegation === true
-    || (job.payload.operation === 'legacy-local-job'
-      && typeof job.payload.arguments?.localAction === 'string'
-      && ['launch-task', 'quick-agent-session'].includes(String(job.payload.arguments.localAction)));
-}
-
 function ambiguousStartedOperation(controllerHome: string, job: ExecutionJob): boolean {
   const receipt = readOperationReceipt(controllerHome, job.repoId, job.jobId);
   if (!receipt || !operationReceiptMatchesJobOwnership(receipt, job)) return false;

package/src/runtime/control-plane/governance/external-effects.ts

@@ -3,7 +3,7 @@ const EXPLICIT_AUTHORIZATION_OPERATIONS = new Set([
   'close_github_issue',
   'repository_remove',
   'repository_disable',
-  'repository_command_execute',
+  'execute_command',
   'configure_github_plugin',
 ]);
 

package/src/runtime/control-plane/launcher/chatgpt-work-continuation.ts

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from 'crypto';
+
 import { isWslWindowsRuntime } from '../../../cli/chatgpt-browser/bridge-provider';
 import { createChatgptBrowserDeliveryHost } from '../../../../adapters/chatgpt/browser-delivery-host';
 import { createChatgptWslBridgeDeliveryHost } from '../../../../adapters/chatgpt/wsl-bridge-delivery-host';

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

@@ -14,7 +14,6 @@ import { cleanupTerminalEditSessionRecords } from '../../cli/editing/edit-sessio
 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 { isTerminalSemanticWorkState, readWorkContractStore } from '../../../packages/kernel/work/api/index';
@@ -22,7 +21,6 @@ import { assertOwnedResourceCleanupTarget, listOwnedResources, markOwnedResource
 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';
@@ -168,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. */
@@ -243,8 +239,6 @@ export interface RuntimeCleanupReport {
   removedScheduleOccurrencePaths: string[];
   removedScheduleDecisionPaths: string[];
   removedEditSessionPaths: string[];
-  removedCodegraphLocatorPaths: string[];
-  removedCodegraphCachePaths: string[];
   removedRepositoryNamespacePaths: string[];
   /** Physical SQLite checkpoint/compaction receipt; row lifecycle remains domain-owned. */
   sqliteMaintenance?: ControlPlaneDatabaseMaintenanceReport;
@@ -302,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]!];
 }
@@ -1058,8 +1052,6 @@ function shouldPersistCleanupAudit(report: RuntimeCleanupReport): boolean {
     || report.removedCleanupArtifactPaths.length
     || report.removedReleasePaths.length
     || report.releaseSessionCandidates.removedPaths.length
-    || report.removedCodegraphLocatorPaths.length
-    || report.removedCodegraphCachePaths.length
     || report.removedRepositoryNamespacePaths.length
     || report.sqliteMaintenance?.vacuumed
     || report.sqliteMaintenance?.skippedReason === 'database_busy'
@@ -1124,11 +1116,7 @@ export function cleanupControllerRuntimeState(
   let artifactRetention: ReturnType<typeof cleanupWorkPreservationArtifacts> | undefined;
   let releaseRetention: ReturnType<typeof cleanupControllerReleaseHistory> | undefined;
   let releaseSessionCandidates: ReleaseSessionCandidateRetentionReport | 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[],
@@ -1263,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,
@@ -1363,12 +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 || !releaseSessionCandidates) {
+  if (!worktrees || !dependencyCleanup || !temporaryCleanup || !artifactRetention || !repositoryNamespaceRetention || !releaseRetention || !releaseSessionCandidates) {
     throw new Error('RUNTIME_CLEANUP_PHASE_INCOMPLETE');
   }
   const removedTemporaryPaths = temporaryCleanup.removed.sort();
@@ -1377,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 {
@@ -1392,7 +1318,7 @@ 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 + releaseSessionCandidates.inspected;
+  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;
@@ -1403,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,
@@ -1437,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,
@@ -1489,8 +1410,6 @@ export function cleanupControllerRuntimeState(
     removedScheduleOccurrencePaths,
     removedScheduleDecisionPaths,
     removedEditSessionPaths,
-    removedCodegraphLocatorPaths,
-    removedCodegraphCachePaths,
     removedRepositoryNamespacePaths,
     sqliteMaintenance,
     retiredOwnerlessWorkAuthorities: retiredOwnerlessWorkAuthorities.sort(),
@@ -1502,11 +1421,11 @@ export function cleanupControllerRuntimeState(
     lifecycleMetrics,
     cycle: {
       scanned: inspectedPaths,
-      eligible: 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 + releaseSessionCandidates.eligible,
-      attempted: 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 + 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 + removedCodegraphLocatorPaths.length + removedCodegraphCachePaths.length + removedRepositoryNamespacePaths.length + removedReleasePaths.length + releaseSessionCandidates.removedPaths.length,
-      retained: pidFiles.skipped.length + worktrees.skippedActive.length + artifactRetention.retained + schedulerHistory.retained + editSessionHistory.retained + codegraphLocatorRetained + codegraphRetention.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 - removedCodegraphLocatorPaths.length - removedCodegraphCachePaths.length - removedRepositoryNamespacePaths.length - removedReleasePaths.length - releaseSessionCandidates.removedPaths.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,