@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/control-plane/facade/self-healing-loop.ts

@@ -325,7 +325,7 @@ export function runSelfHealingLoop(ctx: SelfHealingContext, input: SelfHealingIn
   if (operation === 'verify') {
     return buildFacadeResult({
       status: 'ok',
-      summary: 'Self-healing verification suggestion only; run real registered checks via rh_work verify or rh_status.',
+      summary: 'Self-healing verification is a maintenance observation; run registered repository checks through run_check when code verification is needed.',
       data: {
         operation: 'verify',
         dryRun,
@@ -333,64 +333,29 @@ export function runSelfHealingLoop(ctx: SelfHealingContext, input: SelfHealingIn
       },
       suggestedNextActions: validateSuggestedNextActions([
         verificationSuggestion(input.workId),
-        {
-          label: 'Run work verify if work_id known',
-          tool: 'rh_work',
-          operation: 'verify',
-          payload: { work_id: input.workId },
-          risk: 'workspace_write',
-          confidence: input.workId ? 'medium' : 'low',
-        },
       ]).actions,
     });
   }
 
   if (operation === 'handoff') {
-    const handoff = createHandoffItem(ctx.handoffStore, {
-      id: `hnd-heal-${randomUUID().slice(0, 8)}`,
-      repoId: ctx.repoId,
-      workId: input.workId,
-      title: 'Self-healing needs judgement',
-      severity: 'needs_review',
-      creationReason: 'repeated_infrastructure_failure',
-      reason: 'Self-healing could not safely complete without ChatGPT or user decision.',
-      summary: issues.map((issue) => issue.summary).join(' | ').slice(0, 500) || 'Manual recovery decision required.',
-      currentState: {
-        repoId: ctx.repoId,
-        workId: input.workId,
-        statusSummary: 'self-healing handoff pending',
-      },
-      attemptedActions: ['self_healing_diagnose', 'self_healing_repair'],
-      evidenceRefs: [],
-      blockingDecision: 'Choose bounded metadata repair, external lifecycle handoff, retry later, or re-scope work.',
-      recommendedDecision: 'Prefer safe dry-run repairs; Runtime lifecycle changes belong to the external lifecycle owner.',
-      recommendedPrompt: 'Review self-healing handoff and choose repair or stop.',
-      suggestedNextActions: [
-        {
-          label: 'Diagnose again (dry-run)',
-          tool: 'rh_work',
-          operation: 'repair',
-          payload: { repair_operation: 'diagnose', dry_run: true },
-          risk: 'readonly',
-        },
-      ],
-    });
-
+    // Infrastructure recovery is internal execution state. Escalate only when a
+    // concrete user authorization or product decision has actually been found.
     return buildFacadeResult({
       status: 'blocked',
-      summary: `Self-healing handoff ${handoff.id} created.`,
+      summary: 'Self-healing could not safely complete automatically; keep the exact Work blocked for bounded internal recovery rather than escalating infrastructure failure to the user.',
       data: {
         operation: 'handoff',
-        handoffId: handoff.id,
+        internalRecoveryRequired: true,
         isAcceptanceFailure: false,
       },
       suggestedNextActions: [
         {
-          label: 'Get handoff',
-          tool: 'rh_inbox',
-          operation: 'get',
-          payload: { handoff_id: handoff.id },
-          risk: 'readonly',
+          label: 'Diagnose again (dry-run)',
+          tool: 'rh_work',
+          operation: 'repair',
+          payload: { repair_operation: 'diagnose', dry_run: true, work_id: input.workId },
+          risk: 'workspace_write',
+          confidence: 'low',
         },
       ],
     });
@@ -541,14 +506,14 @@ export function runSelfHealingLoop(ctx: SelfHealingContext, input: SelfHealingIn
     },
     suggestedNextActions: validateSuggestedNextActions([
       verificationSuggestion(input.workId),
-      {
-        label: 'Continue work if applicable',
-        tool: 'rh_work',
-        operation: 'continue',
+      ...(input.workId ? [{
+        label: 'Read current Work semantic state',
+        tool: 'rh_work' as const,
+        operation: 'get',
         payload: { work_id: input.workId },
-        risk: 'readonly',
-        confidence: input.workId ? 'medium' : 'low',
-      },
+        risk: 'readonly' as const,
+        confidence: 'medium' as const,
+      }] : []),
     ]).actions,
     rawAvailable: false,
   });

package/src/runtime/control-plane/facade/suggested-actions.ts

@@ -1,42 +1,38 @@
-import { RH_WORK_OPERATIONS } from './rh-work-operation-contract';
+import { RH_WORK_MODEL_OPERATIONS } from './rh-work-operation-contract';
 import { FACADE_TOOLS, type EvidenceRef, type FacadeTool, type SuggestedNextAction } from './types';
 
 function expectedActionRisk(action: SuggestedNextAction): SuggestedNextAction['risk'] | undefined {
   if (action.tool !== 'rh_work') return undefined;
   switch (action.operation) {
     case 'start':
-    case 'continue':
-    case 'verify':
-    case 'review':
     case 'repair':
-    case 'stop':
-    case 'delegate':
-    case 'controller_claim':
-    case 'controller_release':
-    case 'controller_disposition':
     case 'launcher_start':
     case 'requirement_create':
-    case 'requirement_continue':
+    case 'requirement_promote_candidate':
     case 'schedule_create':
     case 'schedule_pause':
     case 'schedule_resume':
     case 'schedule_delete':
     case 'schedule_trigger':
       return 'workspace_write';
-    case 'controller_get_owner':
     case 'schedule_list':
     case 'schedule_get':
       return 'readonly';
     case 'plan_create':
+    case 'plan_revise':
+    case 'revise':
+    case 'complete':
+    case 'workflow_execute':
+    case 'workflow_reconcile':
+    case 'learning_record':
+    case 'learning_feedback':
+    case 'outcome_record':
+    case 'experience_record':
+      return 'workspace_write';
     case 'plan_get':
     case 'plan_list':
+    case 'get':
       return 'readonly';
-    case 'plan_approve':
-    case 'plan_accept_step':
-    case 'plan_supersede':
-      return 'workspace_write';
-    case 'finalize':
-      return 'local_repo_write';
     default:
       return undefined;
   }
@@ -47,7 +43,8 @@ const ALLOWED_FACADE_OPERATIONS: Record<FacadeTool, readonly string[]> = {
   rh_status: ['list', 'get', 'repair'],
   rh_inbox: ['list', 'get', 'ack', 'accept', 'resolve', 'dismiss', 'create'],
   rh_context: ['list', 'get', 'search'],
-  rh_work: RH_WORK_OPERATIONS,
+  rh_work: RH_WORK_MODEL_OPERATIONS,
+  capability_execute: ['execute'],
 };
 
 export interface SuggestedActionValidationOptions {

package/src/runtime/control-plane/facade/types.ts

@@ -1,20 +1,17 @@
 import type {
   WorkContract,
   VerificationOutcome,
-  ExecutionMode,
   FacadeDetailLevel,
   EvidenceRef,
   SuggestedNextAction,
   PolicyDecision,
 } from '../../../../packages/kernel/work/domain/types';
 export type {
-  ExecutionMode,
   FacadeDetailLevel,
   EvidenceRef,
   SuggestedNextAction,
   PolicyDecision,
 } from '../../../../packages/kernel/work/domain/types';
-import { applyRouteContextHints, decideRoute, type ExplicitTaskMode, type RouteContextHints, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
 import {
   TERMINAL_PLAN_CONTRACT_STATUSES,
   type PlanContractStatus,
@@ -28,10 +25,7 @@ export {
   type PlanStepStatus,
 } from '../../../../packages/kernel/goal/api/index';
 
-export const EXECUTION_MODES = ['direct_control', 'goal_workloop', 'handoff_only'] as const;
-const _executionModesTypeCheck: readonly ExecutionMode[] = EXECUTION_MODES;
-
-export const FACADE_TOOLS = ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work'] as const;
+export const FACADE_TOOLS = ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work', 'capability_execute'] as const;
 export type FacadeTool = (typeof FACADE_TOOLS)[number];
 export type CapabilityExecutionSurface = FacadeTool | 'plugin_action_execute';
 
@@ -84,11 +78,11 @@ import type { HandoffStatus } from '../../../../packages/protocols/handoff/index
 
 // Kernel V2: Work domain contracts are owned by packages/kernel/work/domain.
 export {
-  WORK_CONTRACT_STATUSES,
+  SEMANTIC_WORK_STATES,
   WORK_PHASES,
   WORK_PHASE_EVIDENCE_STATES,
   WORK_RISKS,
-  TERMINAL_WORK_CONTRACT_STATUSES,
+  TERMINAL_SEMANTIC_WORK_STATES,
   WORK_KINDS,
   DISPATCH_STATES,
   EVIDENCE_STATES,
@@ -100,10 +94,10 @@ export {
   isReadOnlyReviewCompletionReceipt,
   isRemoteEffectCompletionReceipt,
   isDirectEditWorkCompletionReceipt,
-  isTerminalWorkContractStatus,
+  isTerminalSemanticWorkState,
 } from '../../../../packages/kernel/work/domain/types';
 export type {
-  WorkContractStatus,
+  SemanticWorkState,
   WorkPhase,
   WorkPhaseEvidenceState,
   WorkPhaseEvidence,
@@ -124,7 +118,6 @@ export type {
   WorkReconciliationOutcome,
   VerificationOutcome,
   WorkContractConstraints,
-  WorkContractDriverPolicy,
   WorktreePolicy,
   EvidencePolicy,
   ApprovalPolicy,
@@ -140,8 +133,6 @@ export const HANDOFF_CREATION_REASONS = [
   'ambiguous_outcome',
   'missing_authorization',
   'invalid_objective',
-  'repeated_infrastructure_failure',
-  'codex_worker_requires_review',
   'destructive_action_requires_confirmation',
 ] as const;
 export type HandoffCreationReason = (typeof HANDOFF_CREATION_REASONS)[number];
@@ -163,13 +154,12 @@ export interface HandoffCurrentState {
   issueId?: string;
   taskId?: string;
   workId?: string;
-  mode?: ExecutionMode;
   statusSummary: string;
   blockedBy?: string[];
   changedFiles?: string[];
   checks?: Array<{ checkId: string; ok: boolean; summary?: string; outcome?: VerificationOutcome }>;
   /** Bounded durable Work semantics for a fresh controller session. */
-  workSemantics?: Pick<WorkContract, 'phase' | 'status' | 'workKind' | 'dispatchState' | 'evidenceState' | 'completionOutcome'>;
+  workSemantics?: Pick<WorkContract, 'semanticState' | 'phase' | 'workKind' | 'dispatchState' | 'evidenceState' | 'completionOutcome'>;
   reconciliationRequired?: boolean;
   nextSafeAction?: string;
 }
@@ -187,6 +177,8 @@ export interface HandoffItem {
   id: string;
   repoId: string;
   workId?: string;
+  /** Canonical person-only blocker/decision authority when this legacy Handoff projects one. */
+  canonicalUserRequestId?: string;
   issueId?: string;
   taskId?: string;
   title: string;
@@ -226,6 +218,26 @@ export type {
   ControllerLease,
   ControllerRoundContext,
 } from '../../../../packages/kernel/controller/domain/types';
+export interface PlanSemanticItem {
+  id: string;
+  objective: string;
+  dependencies: string[];
+}
+
+export interface PlanSemanticContext {
+  /** Requirement semantic revision used as planning provenance; never an execution gate. */
+  requirementBasisRevision?: number;
+  sourceBasisRevision: string;
+  goal: string;
+  nonGoals: string[];
+  assumptions: string[];
+  resolvedDecisions: string[];
+  stopConditions: string[];
+  replanConditions: string[];
+  integrationStrategy?: string;
+  items: PlanSemanticItem[];
+}
+
 export interface PlanStep {
   id: string;
   objective: string;
@@ -297,7 +309,8 @@ export interface PlanRevisionDraft {
  * never own active scope, Work, scheduling, or admission authority. */
 export interface PlanRevisionRecord {
   schemaVersion: 1;
-  repoId: string;
+  /** Node-local placement provenance; absent for a ForgeInstance-scoped Plan. */
+  repoId?: string;
   planId: string;
   revision: number;
   requirementId?: string;
@@ -323,9 +336,16 @@ export interface PlanRevisionRecord {
 export interface PlanContract {
   schemaVersion: 1;
   planId: string;
-  /** Current committed semantic revision. Legacy rows without this field normalize to revision 1. */
+  /** Legacy PlanContract lifecycle revision retained during authority migration. */
   revision?: number;
-  repoId: string;
+  /** Thin model-authored Plan revision, independent from lifecycle/step execution updates. */
+  semanticRevision?: number;
+  /** Timestamp of the model-authored Plan content; lifecycle/step updates must not change it. */
+  semanticUpdatedAt?: string;
+  /** Thin model-authored working memory. Once present, legacy steps/status cannot rewrite semantic Plan content. */
+  semanticContext?: PlanSemanticContext;
+  /** @deprecated Node-local placement compatibility field; absent for a ForgeInstance-scoped Plan. */
+  repoId?: string;
   /** Stable Requirement owner. Legacy plans may omit this until portfolio migration. */
   requirementId?: string;
   scopeKey: string;
@@ -389,27 +409,18 @@ export interface CapabilityGroupSummary {
   schemaExposures: CapabilitySchemaExposure[];
 }
 
-export interface ExecutionModeSelectionInput {
+/**
+ * Concrete mechanical facts about one Work start request. Forge validates and
+ * persists these; it never derives engineering method, worker/provider choice,
+ * verification, review, or completion from them. Choosing durable Work at all
+ * is the caller's explicit decision to invoke this capability.
+ */
+export interface WorkStartFacts {
   objective?: string;
-  expectedFiles?: number;
-  expectedChangedLines?: number;
   scopeClear: boolean;
-  knownPaths?: string[];
-  workspaceDirty?: boolean;
-  workspaceFingerprint?: string;
-  checkoutId?: string;
-  /** Canonical typed placement constraint; never inferred from objective text. */
-  workspacePlacement?: 'current' | 'isolated' | 'auto';
-  /** Admission fence that has precedence over explicit Direct routing. */
-  directMainProhibited?: boolean;
-  requiresInvestigation?: boolean;
-  requiresLongRunningChecks?: boolean;
-  requiresParallelism?: boolean;
-  explicitMode?: ExplicitTaskMode;
-  needsDependencies?: boolean;
+  mutation?: boolean;
   requiresRecovery?: boolean;
-  /** True only when the user explicitly requested an agent/worker executor. Complexity alone must not enable workers. */
-  requiresWorker?: boolean;
+  /** True when the request causes an effect outside the checkout (plugin action, remote publish). */
   requiresExternalEffect?: boolean;
   requiresApproval?: boolean;
   requiresUserApproval?: boolean;
@@ -417,76 +428,6 @@ export interface ExecutionModeSelectionInput {
   destructive?: boolean;
   remoteWrite?: boolean;
   secretAccess?: boolean;
-  mutation?: boolean;
   risk?: CapabilityRisk;
-  /** Advisory Context Plane routing hints. Explicit request fields still win. */
-  contextRouteHints?: RouteContextHints;
-  /** Migration/testing escape hatch: adapters must return this exact policy decision. */
-  routePolicyInput?: RoutePolicyInput;
-}
-
-export interface ExecutionModeSelection {
-  mode: ExecutionMode;
-  reason: string;
-  missingContractFields: string[];
-  createWorkContract: boolean;
-  createHandoff: boolean;
-  requiresWork: boolean;
-  routeDecision: RouteDecision;
-}
-
-/** @deprecated Compatibility adapter. Route Policy is the sole routing authority. */
-export function selectExecutionMode(input: ExecutionModeSelectionInput): ExecutionModeSelection {
-  const missingContractFields: string[] = [];
-  if (!input.scopeClear) missingContractFields.push('scopeSummary', 'acceptanceCriteria', 'allowedPaths');
-  if (input.objective !== undefined && input.objective.trim().length === 0) missingContractFields.push('objective');
-  const baseRoutePolicyInput: RoutePolicyInput = input.routePolicyInput ?? {
-    intent: {
-      objective: input.objective ?? (input.scopeClear ? 'bounded repository work' : ''),
-      scopeClear: input.scopeClear,
-      mutation: input.mutation ?? input.risk !== 'readonly',
-      expectedFiles: input.expectedFiles,
-      expectedChangedLines: input.expectedChangedLines,
-      requiresInvestigation: input.requiresInvestigation,
-      requiresLongRunningChecks: input.requiresLongRunningChecks,
-      requiresParallelism: input.requiresParallelism,
-      explicitMode: input.explicitMode,
-      needsDependencies: input.needsDependencies,
-      agentRequested: input.requiresWorker,
-    },
-    workspace: {
-      knownPaths: input.knownPaths,
-      dirty: input.workspaceDirty,
-      checkoutId: input.checkoutId,
-      fingerprint: input.workspaceFingerprint,
-      placement: input.workspacePlacement,
-      directMainProhibited: input.directMainProhibited,
-    },
-    policy: {
-      risk: input.risk,
-      requiresApproval: input.requiresApproval,
-      requiresUserApproval: input.requiresUserApproval,
-      approvalConfirmed: input.approvalConfirmed,
-      destructive: input.destructive,
-      remoteWrite: input.remoteWrite,
-      secretAccess: input.secretAccess,
-    },
-    capabilities: {
-      requiresWorker: input.requiresWorker,
-      requiresExternalEffect: input.requiresExternalEffect,
-    },
-    recovery: {
-      required: input.requiresRecovery,
-    },
-  };
-  const routeDecision = decideRoute(applyRouteContextHints(baseRoutePolicyInput, input.contextRouteHints));
-  return {
-    mode: routeDecision.executionMode,
-    reason: routeDecision.reasons.map((reason) => reason.message).join(' '),
-    missingContractFields: routeDecision.executionMode === 'handoff_only' && missingContractFields.length > 0 ? missingContractFields : [],
-    createWorkContract: routeDecision.requiresWork,
-    createHandoff: routeDecision.createHandoff,
-    requiresWork: routeDecision.requiresWork,
-    routeDecision,
-  };
+  workspaceDirty?: boolean;
 }

package/src/runtime/control-plane/facade/work-continuation.ts

@@ -14,8 +14,8 @@ export interface WorkContinuationSnapshot {
     worktreeRef?: string;
   };
   semantics: {
+    state: WorkContract['semanticState'];
     phase: WorkContract['phase'];
-    status: WorkContract['status'];
     workKind: WorkContract['workKind'];
     dispatchState: WorkContract['dispatchState'];
     evidenceState: WorkContract['evidenceState'];
@@ -43,16 +43,16 @@ function boundedText(value: string | undefined, maximum: number): string | undef
 function nextSafeAction(contract: WorkContract, reconciliationRequired: boolean): string {
   if (reconciliationRequired) return 'Inspect the recorded reconciliation and decide whether to accept, reject, or supersede it; do not infer completion.';
   if (contract.evidenceState === 'stale' || contract.evidenceState === 'contradictory') return 'Re-run required validation against the current bound revision before finalization.';
-  if (contract.status === 'open' || contract.status === 'ready') return 'Claim controller ownership before starting mutating execution.';
-  if (contract.status === 'running') return 'Inspect the bound Work and its durable process/check evidence; do not resubmit the same request ID.';
-  if (contract.status === 'completed') return 'Read the completion receipt and retain the exact revision evidence; no further mutation is implied.';
-  if (contract.status === 'failed') return 'Inspect failure evidence and choose an explicit repair, reconciliation, or stop action.';
-  return 'Inspect retained evidence before any further action.';
+  if (contract.semanticState === 'completed') return 'Read retained result/evidence references; no further mutation is implied.';
+  if (contract.semanticState === 'cancelled') return 'This Work is cancelled and cannot be reopened; create an explicit successor Work if the objective must continue.';
+  if (contract.dispatchState === 'running' || contract.dispatchState === 'launching' || contract.dispatchState === 'claimed') return 'Inspect the bound Work and its durable process/check evidence; do not resubmit the same request ID.';
+  if (contract.evidenceState === 'failed' || contract.phaseEvidence[contract.phase].state === 'failed') return 'Inspect failure evidence and choose an explicit repair, reconciliation, or stop action.';
+  return 'Execute the next authorized step within this Work scope; inspect existing writer and process conflicts before mutating shared resources.';
 }
 
 /**
  * Redacted, bounded state needed by a fresh controller session. This is a
- * projection only: it never upgrades a status or interprets a reconciliation
+ * projection only: it never changes semantic state or interprets a reconciliation
  * as completion.
  */
 export function buildWorkContinuationSnapshot(contract: WorkContract): WorkContinuationSnapshot {
@@ -82,8 +82,8 @@ export function buildWorkContinuationSnapshot(contract: WorkContract): WorkConti
       worktreeRef: contract.worktreeRef,
     },
     semantics: {
+      state: contract.semanticState,
       phase: contract.phase,
-      status: contract.status,
       workKind: contract.workKind,
       dispatchState: contract.dispatchState,
       evidenceState: contract.evidenceState,

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

@@ -25,6 +25,7 @@ export interface GeneratedCacheRetentionOptions {
   maxEntries?: number;
   maxRemovals?: number;
   processCommands?: string[];
+  rootStartIndex?: number;
 }
 
 export interface GeneratedCacheRetentionReport {
@@ -37,6 +38,19 @@ export interface GeneratedCacheRetentionReport {
   budgetExhausted: boolean;
 }
 
+export interface GeneratedCacheRepositoryRootSet {
+  canonicalRoot: string;
+  checkouts: ReadonlyArray<{
+    localRoot: string;
+    worktree: boolean;
+    lifecycle?: 'active' | 'removed' | 'archived';
+  }>;
+}
+
+export interface RepositoryGeneratedCacheRetentionReport extends GeneratedCacheRetentionReport {
+  rootsInspected: number;
+}
+
 export type BrowserDisposableArtifactKind = 'screenshots' | 'downloads' | 'diagnostics';
 
 export interface BrowserArtifactRetentionOptions {
@@ -171,6 +185,10 @@ function directChildFiles(root: string, budget: { remaining: number }): string[]
   return found;
 }
 
+function isDerivedDataDirectoryName(name: string): boolean {
+  return name === 'DerivedData' || name.startsWith('DerivedData-');
+}
+
 function nestedDerivedDataDirectories(root: string, maxDepth: number, budget: { remaining: number }): string[] {
   if (!existsSync(root) || budget.remaining <= 0) return [];
   const found: string[] = [];
@@ -183,7 +201,7 @@ function nestedDerivedDataDirectories(root: string, maxDepth: number, budget: {
       budget.remaining -= 1;
       if (!entry.isDirectory()) continue;
       const path = join(dir, String(entry.name));
-      if (String(entry.name) === 'DerivedData') {
+      if (isDerivedDataDirectoryName(String(entry.name))) {
         found.push(path);
         continue;
       }
@@ -313,6 +331,84 @@ export function cleanupGeneratedRepositoryCaches(
   return report;
 }
 
+/**
+ * Apply the same generated-cache policy to the canonical checkout and every
+ * active managed worktree, sharing one scan/removal budget across the whole
+ * repository. Work lifecycle is intentionally not cache authority: stale but
+ * recoverable Work may keep its source checkout while rebuildable caches age
+ * out independently. Active build/test processes are still protected by
+ * cleanupGeneratedRepositoryCaches().
+ */
+export function cleanupGeneratedRepositoryCheckoutCaches(
+  repository: GeneratedCacheRepositoryRootSet,
+  options: GeneratedCacheRetentionOptions = {},
+): RepositoryGeneratedCacheRetentionReport {
+  let remainingEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_SCAN_BUDGET));
+  let remainingRemovals = Math.max(1, Math.floor(options.maxRemovals ?? DEFAULT_REMOVAL_BUDGET));
+  const processCommands = options.processCommands ?? collectProcessCommands();
+  const roots = [
+    repository.canonicalRoot,
+    ...repository.checkouts
+      .filter((checkout) => checkout.worktree && (checkout.lifecycle ?? 'active') === 'active')
+      .map((checkout) => checkout.localRoot),
+  ].filter((root, index, values) => values.findIndex((item) => canonical(item) === canonical(root)) === index);
+  if (roots.length > 1) {
+    const offset = ((Math.trunc(options.rootStartIndex ?? 0) % roots.length) + roots.length) % roots.length;
+    roots.push(...roots.splice(0, offset));
+  }
+  const rawRoots = roots.map((root) => resolve(root));
+  const canonicalRoots = roots.map((root) => canonical(root));
+  const processCommandsForRoot = (root: string): string[] => {
+    const rawRoot = resolve(root);
+    const canonicalRoot = canonical(root);
+    return processCommands.filter((command) => {
+      const referencedRootIndexes = rawRoots
+        .map((candidate, index) => command.includes(candidate) || command.includes(canonicalRoots[index]!) ? index : -1)
+        .filter((index) => index >= 0);
+      if (referencedRootIndexes.length === 0) return true;
+      return referencedRootIndexes.some((index) => rawRoots[index] === rawRoot || canonicalRoots[index] === canonicalRoot);
+    });
+  };
+
+  const aggregate: RepositoryGeneratedCacheRetentionReport = {
+    rootsInspected: 0,
+    inspected: 0,
+    eligible: 0,
+    removedPaths: [],
+    retainedPaths: [],
+    skippedByReason: {},
+    errors: [],
+    budgetExhausted: false,
+  };
+
+  for (const root of roots) {
+    if (remainingEntries <= 0 || remainingRemovals <= 0) {
+      aggregate.budgetExhausted = true;
+      break;
+    }
+    const report = cleanupGeneratedRepositoryCaches(root, {
+      ...options,
+      processCommands: processCommandsForRoot(root),
+      maxEntries: remainingEntries,
+      maxRemovals: remainingRemovals,
+    });
+    aggregate.rootsInspected += 1;
+    aggregate.inspected += report.inspected;
+    aggregate.eligible += report.eligible;
+    aggregate.removedPaths.push(...report.removedPaths.map((path) => `${root}:${path}`));
+    aggregate.retainedPaths.push(...report.retainedPaths.map((path) => `${root}:${path}`));
+    for (const [reason, count] of Object.entries(report.skippedByReason)) {
+      aggregate.skippedByReason[reason] = (aggregate.skippedByReason[reason] ?? 0) + count;
+    }
+    aggregate.errors.push(...report.errors.map((error) => `${root}:${error}`));
+    remainingEntries = Math.max(0, remainingEntries - report.inspected);
+    remainingRemovals = Math.max(0, remainingRemovals - report.removedPaths.length);
+    aggregate.budgetExhausted ||= report.budgetExhausted;
+  }
+  if (remainingEntries <= 0 || remainingRemovals <= 0) aggregate.budgetExhausted = true;
+  return aggregate;
+}
+
 function emptyBrowserArtifactClassReport(): BrowserArtifactClassRetentionReport {
   return {
     inspected: 0,