@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/execution/managed-workspace.ts

@@ -1,5 +1,5 @@
-import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from 'fs';
+import { createHash, randomUUID } from 'crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import type { RepositoryRecord } from '../../cli/repositories/types';
@@ -16,10 +16,13 @@ import { resolveGitExecutable } from '../../effects/git-executable';
 import { runProcess } from '../../effects/process-runner';
 import { repositoryChildProcessEnvironment, resolveBunExecutable } from '../shared/process-environment';
 import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
+import { ensureForgeInstanceIdentity, getOwnedResource, ownedResourceLocatorFingerprint, recordOwnedResource, type OwnedResourceLocator } from '../../../packages/kernel/identity/api/index';
 
 export interface EnsureManagedWorkspaceInput {
   requestId: string;
   title: string;
+  /** Semantic Work provenance for durable ownership; never an execution mutex. */
+  associatedWorkId?: string;
   baseRef?: string;
   branchName?: string;
   /** Explicitly materialize lockfile-backed Node dependencies in this isolated worktree. */
@@ -65,6 +68,21 @@ function suffix(repoId: string, requestId: string): string {
   return createHash('sha256').update(`${repoId}:${requestId}`).digest('hex').slice(0, 12);
 }
 
+export function managedWorkspaceOwnedResourceId(repoId: string, checkoutId: string): string {
+  return `managed-worktree:${repoId}:${checkoutId}`;
+}
+
+export function managedBranchOwnedResourceId(repoId: string, checkoutId: string): string {
+  return `managed-branch:${repoId}:${checkoutId}`;
+}
+
+export function managedBranchOwnedResourceLocator(repositoryRoot: string, checkoutId: string, branch: string): OwnedResourceLocator {
+  return {
+    kind: 'git_ref',
+    value: `${realpathSync(repositoryRoot)}\0${checkoutId.trim()}\0refs/heads/${branch.trim()}`,
+  };
+}
+
 function git(root: string, args: string[], timeoutMs = 30_000): string {
   const result = runProcess(resolveGitExecutable(), ['-C', root, ...args], {
     timeoutMs,
@@ -92,8 +110,8 @@ function assertBranch(root: string, branch: string): string {
   return normalized;
 }
 
-export function managedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWorkspaceDependencyBootstrap | undefined {
-  if (!existsSync(join(repoRoot, 'package.json')) || existsSync(join(repoRoot, 'node_modules'))) return undefined;
+function detectManagedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWorkspaceDependencyBootstrap | undefined {
+  if (!existsSync(join(repoRoot, 'package.json'))) return undefined;
   const lockCandidates = [
     ['bun', 'bun.lock', ['bun', 'install', '--frozen-lockfile']],
     ['bun', 'bun.lockb', ['bun', 'install', '--frozen-lockfile']],
@@ -106,6 +124,11 @@ export function managedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWo
   return { packageManager: detected[0], lockfile: detected[1], command: [...detected[2]] };
 }
 
+export function managedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWorkspaceDependencyBootstrap | undefined {
+  if (existsSync(join(repoRoot, 'node_modules'))) return undefined;
+  return detectManagedWorkspaceDependencyBootstrap(repoRoot);
+}
+
 const DEPENDENCY_REUSE_CONFIG_PATHS = [
   '.npmrc',
   'bunfig.toml',
@@ -151,7 +174,7 @@ export function resolveManagedWorkspaceCanonicalDependencies(repoRoot: string):
   canonicalRoot: string;
   nodeModulesRoot: string;
 } | undefined {
-  const bootstrap = managedWorkspaceDependencyBootstrap(repoRoot);
+  const bootstrap = detectManagedWorkspaceDependencyBootstrap(repoRoot);
   if (!bootstrap) return undefined;
   const canonicalRoot = linkedWorkspaceCanonicalRoot(repoRoot);
   if (!canonicalRoot) return undefined;
@@ -162,6 +185,51 @@ export function resolveManagedWorkspaceCanonicalDependencies(repoRoot: string):
   return { canonicalRoot, nodeModulesRoot: realpathSync(nodeModulesRoot) };
 }
 
+/**
+ * Replace a legacy physical dependency copy with the already-authoritative
+ * canonical dependency tree. The caller must hold repository maintenance
+ * ownership and prove there is no active workspace lease before invoking this
+ * filesystem mutation. A temporary rename gives the operation an exact rollback
+ * point; any link/removal failure restores the original physical directory.
+ */
+export function migrateManagedWorkspacePhysicalDependenciesToCanonical(
+  repoRoot: string,
+): ManagedWorkspaceDependencyPreparation | undefined {
+  const nodeModulesRoot = join(repoRoot, 'node_modules');
+  if (!existsSync(nodeModulesRoot)) return undefined;
+  const stats = lstatSync(nodeModulesRoot);
+  if (stats.isSymbolicLink()) return undefined;
+  if (!stats.isDirectory()) throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_PATH_INVALID: ${nodeModulesRoot}`);
+  const reusable = resolveManagedWorkspaceCanonicalDependencies(repoRoot);
+  if (!reusable) return undefined;
+
+  const backupRoot = join(repoRoot, `.forge-node-modules-migration-${process.pid}-${randomUUID().slice(0, 8)}`);
+  renameSync(nodeModulesRoot, backupRoot);
+  try {
+    symlinkSync(reusable.nodeModulesRoot, nodeModulesRoot, process.platform === 'win32' ? 'junction' : 'dir');
+    rmSync(backupRoot, { recursive: true, force: true });
+  } catch (error) {
+    let rollbackError: unknown;
+    try {
+      if (existsSync(nodeModulesRoot)) rmSync(nodeModulesRoot, { recursive: true, force: true });
+      if (existsSync(backupRoot)) renameSync(backupRoot, nodeModulesRoot);
+    } catch (rollback) {
+      rollbackError = rollback;
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    if (rollbackError) {
+      const rollbackDetail = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+      throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_MIGRATION_ROLLBACK_FAILED: ${detail}; rollback=${rollbackDetail}`);
+    }
+    throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_MIGRATION_FAILED: ${detail}`);
+  }
+  return {
+    mode: 'canonical_reuse',
+    nodeModulesRoot: realpathSync(nodeModulesRoot),
+    canonicalRoot: reusable.canonicalRoot,
+  };
+}
+
 function packageManifestRequiresDependencyMaterialization(repoRoot: string): boolean {
   const packagePath = join(repoRoot, 'package.json');
   if (!existsSync(packagePath)) return false;
@@ -335,6 +403,10 @@ export function ensureManagedWorkspace(
         throw new Error(`MANAGED_WORKSPACE_REQUEST_CONFLICT: ${requestId}`);
       }
       const branch = manifest?.branch ?? requestedBranch;
+      // Persisted manifests are Forge provenance. Without one, an already-existing
+      // branch/worktree is never adopted as cleanup-owned merely because its name/path matches.
+      let workspaceOwnedByForge = Boolean(manifest);
+      let branchOwnedByForge = Boolean(manifest);
       // Persisted manifests are authoritative evidence; never move an active worktree in place.
       const path = manifest?.path ? resolve(manifest.path) : requestedPath;
       const baseRevision = manifest?.baseRevision ?? git(sourceRoot, ['rev-parse', '--verify', `${requestedBaseRef}^{commit}`]);
@@ -346,8 +418,11 @@ export function ensureManagedWorkspace(
           // A daemon crash may leave stale worktree administration behind even after the directory is gone.
           git(sourceRoot, ['worktree', 'prune', '--expire', 'now'], 120_000);
           git(sourceRoot, ['worktree', 'add', path, branch], 120_000);
+          workspaceOwnedByForge = true;
         } else {
           git(sourceRoot, ['worktree', 'add', '-b', branch, path, baseRevision], 120_000);
+          workspaceOwnedByForge = true;
+          branchOwnedByForge = true;
         }
       }
       if (!repositoryCheckoutRootMatches(repository, path)) {
@@ -375,6 +450,38 @@ export function ensureManagedWorkspace(
       );
       if (!checkout) throw new Error(`MANAGED_WORKSPACE_CHECKOUT_NOT_REGISTERED: ${path}`);
       const selected = selectRepositoryCheckout(record, checkout.checkoutId);
+      const ownerForgeInstanceId = ensureForgeInstanceIdentity({ controllerHome }).instanceId;
+      const workspaceResourceId = managedWorkspaceOwnedResourceId(repository.repoId, checkout.checkoutId);
+      const branchResourceId = managedBranchOwnedResourceId(repository.repoId, checkout.checkoutId);
+      const existingWorkspaceResource = getOwnedResource(controllerHome, workspaceResourceId);
+      const existingBranchResource = getOwnedResource(controllerHome, branchResourceId);
+      if (existingWorkspaceResource?.cleanupCapable === false) workspaceOwnedByForge = false;
+      if (existingBranchResource?.cleanupCapable === false) branchOwnedByForge = false;
+      recordOwnedResource(controllerHome, {
+        resourceId: workspaceResourceId,
+        kind: 'worktree',
+        targetRef: selected.canonicalRoot,
+        cleanupCapable: workspaceOwnedByForge,
+        creator: 'forge:managed-workspace',
+        ownerForgeInstanceId,
+        associatedWorkId: input.associatedWorkId,
+        repoId: repository.repoId,
+        retentionIntent: 'temporary',
+      });
+      const branchLocator = managedBranchOwnedResourceLocator(repository.canonicalRoot, checkout.checkoutId, branch);
+      recordOwnedResource(controllerHome, {
+        resourceId: branchResourceId,
+        kind: 'git_branch',
+        targetRef: branch,
+        locator: branchLocator,
+        identityFingerprint: ownedResourceLocatorFingerprint(ownerForgeInstanceId, branchLocator),
+        cleanupCapable: branchOwnedByForge,
+        creator: 'forge:managed-workspace',
+        ownerForgeInstanceId,
+        associatedWorkId: input.associatedWorkId,
+        repoId: repository.repoId,
+        retentionIntent: 'retain_on_failure',
+      });
       if (!manifest) {
         writeJsonAtomic(statePath, {
           schemaVersion: 1,

package/src/runtime/execution/process-runtime/canary.ts

@@ -1,26 +1,40 @@
 import { resolve } from 'path';
 
 /**
- * Private child mode used only by the immutable release execution canary.
+ * Private child mode used only by immutable Runtime execution canaries.
  *
  * The canary must not use the parent process' process.execPath: inside a
  * compiled immutable Forge release that path is the packaged Runtime executable,
  * so spawning it would start a second Supervisor and collide on its control
- * port. Reusing the candidate Process Runner with an explicit no-op child mode
- * keeps the probe self-contained and portable.
+ * port. Reusing the candidate Process/Check Runner with an explicit no-op child
+ * mode keeps the probe self-contained and portable.
  */
-export const PROCESS_RUNNER_RELEASE_CANARY_CHILD_ARG = '--forge-release-canary-child';
+export const PROCESS_RUNTIME_RELEASE_CANARY_ARG = '--forge-release-canary-child';
+/** Compatibility name retained for the Process Runner entrypoint and existing callers. */
+export const PROCESS_RUNNER_RELEASE_CANARY_CHILD_ARG = PROCESS_RUNTIME_RELEASE_CANARY_ARG;
 
 export interface ProcessRunnerReleaseCanaryChildCommand {
   executable: string;
   args: string[];
 }
 
+export interface ProcessRuntimeReleaseCanaryCommand extends ProcessRunnerReleaseCanaryChildCommand {
+  name: 'process_runner' | 'check_runner';
+}
+
 export function processRunnerReleaseCanaryChildCommand(
   runnerPath: string,
 ): ProcessRunnerReleaseCanaryChildCommand {
   return {
     executable: resolve(runnerPath),
-    args: [PROCESS_RUNNER_RELEASE_CANARY_CHILD_ARG],
+    args: [PROCESS_RUNTIME_RELEASE_CANARY_ARG],
   };
 }
+
+export function processRuntimeReleaseCanaryCommands(releaseRoot: string): ProcessRuntimeReleaseCanaryCommand[] {
+  const root = resolve(releaseRoot);
+  return [
+    { name: 'process_runner', executable: resolve(root, 'process-runner.js'), args: [PROCESS_RUNTIME_RELEASE_CANARY_ARG] },
+    { name: 'check_runner', executable: resolve(root, 'forge-check-runner'), args: [PROCESS_RUNTIME_RELEASE_CANARY_ARG] },
+  ];
+}

package/src/runtime/execution/process-runtime/check-classification.ts

@@ -0,0 +1,48 @@
+import {
+  controllerCheckSelection,
+  type ControllerCheck,
+} from '../../../cli/controller/check-runner';
+
+export type ControllerCheckExecutionClass = 'ordinary' | 'release' | 'live_controller_home';
+
+export interface ControllerCheckExecutionClassification {
+  executionClass: ControllerCheckExecutionClass;
+  requiresDurableWorkflow: boolean;
+  reason: 'ordinary_process_check' | 'release_phase' | 'live_controller_home';
+}
+
+/**
+ * Single semantic authority for Check execution placement.
+ *
+ * A caller must supply a registered ControllerCheck. Human-readable ids and
+ * descriptions are not lifecycle authority here. Compatibility inference, when
+ * unavoidable at repository ingress, must already have been normalized into
+ * the ControllerCheck contract before classification reaches this layer.
+ */
+export function classifyControllerCheckExecution(check: ControllerCheck): ControllerCheckExecutionClassification {
+  if (check.executionAuthority === 'live_controller_home') {
+    return {
+      executionClass: 'live_controller_home',
+      requiresDurableWorkflow: true,
+      reason: 'live_controller_home',
+    };
+  }
+
+  if (controllerCheckSelection(check).phases.includes('release')) {
+    return {
+      executionClass: 'release',
+      requiresDurableWorkflow: true,
+      reason: 'release_phase',
+    };
+  }
+
+  return {
+    executionClass: 'ordinary',
+    requiresDurableWorkflow: false,
+    reason: 'ordinary_process_check',
+  };
+}
+
+export function registeredCheckRequiresDurableWorkflow(check?: ControllerCheck): boolean {
+  return check ? classifyControllerCheckExecution(check).requiresDurableWorkflow : false;
+}

package/src/runtime/execution/process-runtime/check-facade.ts

@@ -8,6 +8,7 @@
  */
 
 import {
+  controllerCheckEnvironmentFingerprint,
   controllerCheckExecutionIdentity,
   listControllerChecks,
   snapshotControllerCheck,
@@ -15,6 +16,7 @@ import {
   type ControllerCheckSnapshot,
 } from '../../../cli/controller/check-runner';
 import { claimsForCheck, scopeResourceClaims, toProcessClaims } from './resource-claims';
+import { resolveCheckCompletionGraceWaitMs } from '../../control-plane/persistence/operational-prior-store';
 import { spawnManagedProcess, waitForProcess, getProcessHandle } from './runtime';
 import {
   getLightweightProcessHandle,
@@ -26,6 +28,7 @@ import type { ProcessHandle } from './types';
 import { DEFAULT_INTERACTIVE_WAIT_MS } from './types';
 import { durationAwareInteractiveWaitMs } from './interactive-admission';
 import type { ResolvedExecutionIdentity } from '../../control-plane/execution/execution-identity';
+import { registeredCheckRequiresDurableWorkflow } from './check-classification';
 
 export type CheckExecutionMode = 'direct' | 'managed' | 'durable';
 
@@ -99,15 +102,17 @@ export interface RunCheckFacadeResult {
   };
 }
 
-const DURABLE_CHECK_ID = /(?:^|:)(?:release|migration|integrate|public-export|deploy)(?:$|:)/i;
 /**
- * True when a check requires external Controller handling (multi-phase / release).
- * Ordinary typecheck / lint / package test / focused validation stay on Process Runtime.
+ * Compatibility entry point while older internal callers still pass
+ * (checkId, registeredCheck). The id is deliberately ignored: lifecycle
+ * authority comes only from the registered ControllerCheck contract.
  */
-export function checkRequiresDurableWorkflow(checkId: string, check?: ControllerCheck): boolean {
-  if (DURABLE_CHECK_ID.test(checkId)) return true;
-  if (check && /release|rollback|blue.?green|migrate/i.test(check.description)) return true;
-  return false;
+export function checkRequiresDurableWorkflow(
+  checkOrLegacyId: ControllerCheck | string | undefined,
+  registeredCheck?: ControllerCheck,
+): boolean {
+  const check = typeof checkOrLegacyId === 'string' ? registeredCheck : checkOrLegacyId;
+  return registeredCheckRequiresDurableWorkflow(check);
 }
 
 function resolveCheck(repoRoot: string, checkId: string): ControllerCheck | undefined {
@@ -141,14 +146,14 @@ export async function runCheckViaProcessRuntime(
     };
   }
 
-  if (input.forceDurable || checkRequiresDurableWorkflow(input.checkId, check)) {
+  if (input.forceDurable || checkRequiresDurableWorkflow(check)) {
     return {
       mode: 'durable',
       checkId: input.checkId,
       check,
       durable: {
         reason: 'multi_phase_or_release_check_requires_durable_workflow',
-        suggestedOperation: 'Claim the related WorkContract and run this check through an external Controller.',
+        suggestedOperation: 'Run this check through a Work-bound durable verification workflow.',
       },
       durableSideEffects: emptyEffects,
     };
@@ -157,9 +162,17 @@ export async function runCheckViaProcessRuntime(
   // The wait budget is an interaction preference, not a persistence reason.
   // Ordinary checks stay in memory; only a real durable evidence consumer may
   // allocate Process/Lease state.
+  const learnedCompletionGraceMs = input.interactiveWaitMs === undefined
+    ? resolveCheckCompletionGraceWaitMs({
+        controllerHome: input.controllerHome,
+        repoId: input.repoId,
+        checkId: input.checkId,
+        environmentFingerprint: controllerCheckEnvironmentFingerprint(check),
+      })
+    : undefined;
   const interactiveWaitMs = durationAwareInteractiveWaitMs(
     check.command,
-    input.interactiveWaitMs,
+    input.interactiveWaitMs ?? learnedCompletionGraceMs,
     Math.min(250, DEFAULT_INTERACTIVE_WAIT_MS),
   );
   const timeoutMs = Math.min(
@@ -218,6 +231,7 @@ export async function runCheckViaProcessRuntime(
       executionIdentity.repositoryId,
       executionIdentity.checkoutId,
       check.effects,
+      check.executionAuthority,
     ),
     executionIdentity.repositoryId,
     executionIdentity.checkoutId,

package/src/runtime/execution/process-runtime/check-receipt.ts

@@ -43,7 +43,7 @@ function artifactSlug(id: string): string {
 }
 
 export function processCheckArtifactPath(checkId: string): string {
-  return `.ai/harness/checks/controller/latest-${artifactSlug(checkId)}.json`;
+  return `controller-home://checks/controller/latest-${artifactSlug(checkId)}.json`;
 }
 
 function receiptStatus(status: ProcessRuntimeStatus): ProcessCheckReceiptStatus {

package/src/runtime/execution/process-runtime/check-result-retention.ts

@@ -0,0 +1,132 @@
+import { existsSync, lstatSync, opendirSync, statSync, unlinkSync } from 'fs';
+import { join, relative } from 'path';
+import { isTerminalSemanticWorkState, type WorkContract } from '../../../../packages/kernel/work/api/index';
+import { listControlPlaneRecords } from '../../control-plane/persistence/sqlite-store';
+import { processLogDir } from './store';
+import { readPersistedCheckResultReceipt } from './check-result';
+
+const DEFAULT_CHECK_RESULT_TTL_MS = 30 * 24 * 60 * 60_000;
+const DEFAULT_MAX_RETAINED_CHECK_RESULTS = 500;
+const DEFAULT_MAX_REMOVALS = 50;
+
+export interface CheckResultRetentionReport {
+  policyVersion: 'check-result-retention-v1';
+  inspected: number;
+  eligible: number;
+  attempted: number;
+  removed: number;
+  retained: number;
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  removedPaths: string[];
+  blockers: string[];
+  budgetExhausted: boolean;
+  scanTruncated: boolean;
+}
+
+export function cleanupPersistedCheckResults(
+  controllerHome: string,
+  repoId: string,
+  options: { nowMs?: number; ttlMs?: number; maxRetained?: number; maxRemovals?: number; maxScan?: number } = {},
+): CheckResultRetentionReport {
+  const report: CheckResultRetentionReport = {
+    policyVersion: 'check-result-retention-v1', inspected: 0, eligible: 0, attempted: 0, removed: 0, retained: 0,
+    reclaimedBytes: 0, unknownReclaimedByteCount: 0, removedPaths: [], blockers: [], budgetExhausted: false, scanTruncated: false,
+  };
+  const root = join(processLogDir(controllerHome, repoId), 'check-results');
+  if (!existsSync(root)) return report;
+  const nowMs = options.nowMs ?? Date.now();
+  const ttlMs = Math.max(60_000, Math.floor(options.ttlMs ?? DEFAULT_CHECK_RESULT_TTL_MS));
+  const maxRetained = Math.max(1, Math.floor(options.maxRetained ?? DEFAULT_MAX_RETAINED_CHECK_RESULTS));
+  let remaining = Math.max(0, Math.floor(options.maxRemovals ?? DEFAULT_MAX_REMOVALS));
+  const maxScan = Math.max(1, Math.min(Math.floor(options.maxScan ?? 5_000), 5_000));
+
+  const protectedCacheKeys = new Set<string>();
+  const workRecords = listControlPlaneRecords<WorkContract>(controllerHome, { namespace: 'work_contract', scope: repoId, limit: 5_000 });
+  if (workRecords.length >= 5_000) {
+    report.scanTruncated = true;
+    report.blockers.push('work_scan_truncated');
+    return report;
+  }
+  for (const record of workRecords) {
+    const work = record.value;
+    if (isTerminalSemanticWorkState(work.semanticState)) continue;
+    for (const verification of work.checkRefs ?? []) {
+      const key = verification.receipt?.checkCacheKey?.trim();
+      if (key) protectedCacheKeys.add(key);
+    }
+  }
+
+  const candidates: Array<{ path: string; name: string; cacheKey: string; executedAtMs: number; bytes?: number }> = [];
+  let directory: ReturnType<typeof opendirSync>;
+  try { directory = opendirSync(root); } catch { return report; }
+  try {
+    for (;;) {
+      const entry = directory.readSync();
+      if (!entry) break;
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      if (report.inspected >= maxScan) { report.scanTruncated = true; break; }
+      const name = entry.name;
+      report.inspected += 1;
+      const path = join(root, name);
+    try {
+      if (lstatSync(path).isSymbolicLink()) {
+        report.blockers.push(`symlink:${name}`);
+        continue;
+      }
+      const receipt = readPersistedCheckResultReceipt(path);
+      if (!receipt) {
+        report.blockers.push(`invalid_receipt:${name}`);
+        continue;
+      }
+      const executedAtMs = Date.parse(receipt.originalExecutedAt ?? receipt.executedAt);
+      if (!Number.isFinite(executedAtMs)) {
+        report.blockers.push(`invalid_time:${name}`);
+        continue;
+      }
+      let bytes: number | undefined;
+      try { bytes = statSync(path).size; } catch { /* retained if removal succeeds but size is unknown */ }
+      candidates.push({ path, name, cacheKey: receipt.cacheKey, executedAtMs, bytes });
+      } catch {
+        report.blockers.push(`inspect_failed:${name}`);
+      }
+    }
+  } finally {
+    directory.closeSync();
+  }
+
+  candidates.sort((left, right) => right.executedAtMs - left.executedAtMs || left.name.localeCompare(right.name));
+  let unprotectedRank = 0;
+  for (const candidate of candidates) {
+    if (protectedCacheKeys.has(candidate.cacheKey)) {
+      report.retained += 1;
+      continue;
+    }
+    const overCount = !report.scanTruncated && unprotectedRank >= maxRetained;
+    unprotectedRank += 1;
+    const ageExpired = nowMs - candidate.executedAtMs >= ttlMs;
+    if (!overCount && !ageExpired) {
+      report.retained += 1;
+      continue;
+    }
+    report.eligible += 1;
+    if (remaining <= 0) {
+      report.budgetExhausted = true;
+      report.retained += 1;
+      continue;
+    }
+    report.attempted += 1;
+    try {
+      unlinkSync(candidate.path);
+      remaining -= 1;
+      report.removed += 1;
+      report.removedPaths.push(relative(controllerHome, candidate.path));
+      if (candidate.bytes === undefined) report.unknownReclaimedByteCount += 1;
+      else report.reclaimedBytes += candidate.bytes;
+    } catch {
+      report.blockers.push(`remove_failed:${candidate.name}`);
+      report.retained += 1;
+    }
+  }
+  return report;
+}