@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/control-plane/facade/work-contract-store.ts

@@ -18,10 +18,10 @@ import {
   type DispatchState,
   type EvidenceState,
   type PolicyDecision,
-  type SubmittedWorkOperation,
   type SuggestedNextAction,
   type VerificationRecord,
   type WorkReconciliationRecord,
+  type SubmittedWorkOperation,
   type WorkContract,
   type WorkContractStatus,
   type WorkRisk,
@@ -370,11 +370,25 @@ const EVIDENCE_TRANSITIONS: Readonly<Record<EvidenceState, readonly EvidenceStat
   failed: ['failed', 'partial', 'valid', 'contradictory'],
 };
 
-function validateWorkSemanticTransition(current: WorkContract, next: WorkContract): WorkContract {
+function validateWorkSemanticTransition(
+  current: WorkContract,
+  next: WorkContract,
+  options: { allowRetainedCancelledResume?: boolean } = {},
+): WorkContract {
   const retryingFailedWork = current.status === 'failed'
     && !current.completionOutcome
     && ['claimed', 'launching', 'running', 'blocked'].includes(next.dispatchState);
-  if (!retryingFailedWork && !DISPATCH_TRANSITIONS[current.dispatchState].includes(next.dispatchState)) {
+  const resumingRetainedCancelledWork = options.allowRetainedCancelledResume === true
+    && current.status === 'cancelled'
+    && current.dispatchState === 'terminal'
+    && current.phase === 'cleanup'
+    && current.phaseEvidence.cleanup.state === 'skipped'
+    && !current.completionReceipt
+    && !current.completionOutcome
+    && next.status === 'running'
+    && next.dispatchState === 'running'
+    && next.phase === 'implementation';
+  if (!retryingFailedWork && !resumingRetainedCancelledWork && !DISPATCH_TRANSITIONS[current.dispatchState].includes(next.dispatchState)) {
     throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: dispatch ${current.dispatchState} -> ${next.dispatchState}`);
   }
   if (!EVIDENCE_TRANSITIONS[current.evidenceState].includes(next.evidenceState)) {
@@ -392,6 +406,11 @@ function validateWorkSemanticTransition(current: WorkContract, next: WorkContrac
   return next;
 }
 
+function suggestedActionsForStatus(status: WorkContractStatus, actions: readonly SuggestedNextAction[]): SuggestedNextAction[] {
+  if (status === 'completed' || status === 'cancelled') return [];
+  return actions.slice(0, 8);
+}
+
 function sqliteBacked(options: WorkContractStoreOptions): options is WorkContractStoreOptions & { controllerHome: string; repoId: string } {
   // A caller-provided root is a test/portable compatibility store.  Runtime
   // controller state always carries controllerHome + repoId and is SQLite.
@@ -429,6 +448,7 @@ function normalizeWorkContractStore(store: WorkContractStore): WorkContractStore
         workKind: legacy.workKind ?? 'repository_change',
         dispatchState: legacy.dispatchState ?? inferredDispatchState(status),
         evidenceState: legacy.evidenceState ?? inferredEvidenceState(status),
+        suggestedNextActions: suggestedActionsForStatus(status, legacy.suggestedNextActions ?? []),
         reconciliations: legacy.reconciliations ?? [],
         driver: (legacy.driver as unknown as { preferred?: string } | undefined)?.preferred === 'codex_worker'
           ? { ...legacy.driver, preferred: 'external_controller', allowWorker: false }
@@ -541,7 +561,7 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
   if (input.status === 'completed' || input.completionReceipt || input.completionOutcome) {
     throw new Error('WORK_COMPLETION_REQUIRES_RECORD_API');
   }
-  return withWorkContractStoreWrite(options, () => {
+  const create = (): WorkContract => {
     const at = input.createdAt ?? input.updatedAt ?? nowIso(options);
     const workId = sanitizeFileComponent(input.workId);
     const contract: WorkContract = validateWorkSemantics({
@@ -585,6 +605,12 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
       planStepId: input.planStepId,
       planSourceRevision: input.planSourceRevision,
       scopeSummary: input.scopeSummary?.slice(0, 1_000),
+      scopeEvidence: input.scopeEvidence ? {
+        initialLikelyPaths: [...new Set(input.scopeEvidence.initialLikelyPaths)].slice(0, 100),
+        inspectedPaths: [...new Set(input.scopeEvidence.inspectedPaths)].slice(0, 500),
+        actualChangedPaths: [...new Set(input.scopeEvidence.actualChangedPaths)].slice(0, 500),
+        recordedAt: input.scopeEvidence.recordedAt,
+      } : undefined,
       allowedPaths: (input.allowedPaths ?? []).slice(0, 50),
       forbiddenPaths: (input.forbiddenPaths ?? []).slice(0, 50),
       checks: (input.checks ?? []).slice(0, 30),
@@ -618,6 +644,23 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
       submittedOperation: input.submittedOperation,
     });
 
+    if (sqliteBacked(options)) {
+      withControlPlaneTransaction(options.controllerHome, (database) => {
+        if (readControlPlaneRecordWithinTransaction<WorkContract>(database, 'work_contract', options.repoId, contract.workId)) {
+          throw new Error(`work contract already exists: ${contract.workId}`);
+        }
+        writeControlPlaneRecordWithinTransaction(database, {
+          namespace: 'work_contract',
+          scope: options.repoId,
+          key: contract.workId,
+          schemaVersion: 2,
+          value: contract,
+          action: 'work_contract_created',
+          expectedRevision: null,
+        });
+      });
+      return contract;
+    }
     const store = readWorkContractStore(options);
     if (store.contracts.some((existing) => existing.workId === contract.workId)) {
       throw new Error(`work contract already exists: ${contract.workId}`);
@@ -629,7 +672,8 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
     };
     writeWorkContractStore(options, nextStore);
     return contract;
-  });
+  };
+  return create();
 }
 
 interface WorkRequestIndexRecord {
@@ -647,26 +691,6 @@ function workRequestIndexPath(controllerHome: string, requestId: string): string
   return join(root, `${hash}.json`);
 }
 
-export interface AcceptSubmittedWorkInput {
-  requestId: string;
-  repoId: string;
-  parentWorkId?: string;
-  semanticKey: string;
-  operation: SubmittedWorkOperation;
-  objective?: string;
-  mode?: WorkContract['mode'];
-  requestedBy?: WorkContract['requestedBy'];
-  principalId?: string;
-  controllerInstanceId?: string;
-  workKind?: WorkKind;
-  risk?: WorkRisk;
-  allowedPaths?: string[];
-  forbiddenPaths?: string[];
-  checks?: string[];
-  acceptanceCriteria?: string[];
-  constraints?: WorkContract['constraints'];
-}
-
 export function getWorkContractByRequestId(
   controllerHome: string,
   requestId: string,
@@ -687,8 +711,8 @@ export function getWorkContractByRequestId(
 }
 
 /**
- * Accept one work_submit operation as a WorkContract without creating ExecutionJobs.
- * Same controllerHome + requestId + semanticKey returns the original contract.
+ * Create or reuse the execution-child Work used by typed callers. This is not
+ * a generic MCP submission authority and never creates an ExecutionJob.
  */
 export function acceptSubmittedWorkContract(
   controllerHome: string,
@@ -696,20 +720,12 @@ export function acceptSubmittedWorkContract(
   options: WorkContractStoreOptions = {},
 ): { contract: WorkContract; deduplicated: boolean } {
   const home = ensureControllerHome(controllerHome);
-  const normalizedRequestId = input.requestId.trim();
-  if (!normalizedRequestId) {
-    throw new Error('INVALID_ARGUMENT: work_submit is missing required argument(s): request_id');
-  }
-  const normalizedSemanticKey = input.semanticKey.trim();
-  if (!normalizedSemanticKey) {
-    throw new Error('INVALID_ARGUMENT: work_submit requires a semantic operation key');
-  }
-  if (!input.repoId.trim()) {
-    throw new Error('INVALID_ARGUMENT: work_submit is missing required argument(s): repo_id');
-  }
-  if (!input.operation?.name?.trim()) {
-    throw new Error('INVALID_ARGUMENT: work_submit is missing required argument(s): operation');
-  }
+  const requestId = input.requestId.trim();
+  const semanticKey = input.semanticKey.trim();
+  if (!requestId) throw new Error('INVALID_ARGUMENT: typed execution is missing request_id');
+  if (!semanticKey) throw new Error('INVALID_ARGUMENT: typed execution requires a semantic operation key');
+  if (!input.repoId.trim()) throw new Error('INVALID_ARGUMENT: typed execution is missing repo_id');
+  if (!input.operation?.name?.trim()) throw new Error('INVALID_ARGUMENT: typed execution is missing operation');
   const parentWorkId = input.parentWorkId?.trim() || undefined;
   if (parentWorkId) {
     const parent = getWorkContract({ controllerHome: home, repoId: input.repoId, now: options.now }, parentWorkId);
@@ -717,25 +733,17 @@ export function acceptSubmittedWorkContract(
     if (isTerminalWorkContractStatus(parent.status)) throw new Error(`PARENT_WORK_TERMINAL: ${parentWorkId}:${parent.status}`);
     if ((parent.lifecycleRole ?? 'primary') !== 'primary') throw new Error(`PARENT_WORK_NOT_PRIMARY: ${parentWorkId}`);
   }
-
-  const requestLockId = createHash('sha256').update(normalizedRequestId).digest('hex').slice(0, 24);
-  return withControllerLock(home, { scope: 'global', resource: `work-request-${requestLockId}` }, `accept-work:${normalizedRequestId}`, () => {
-    const recordPath = workRequestIndexPath(home, normalizedRequestId);
+  const lockId = createHash('sha256').update(requestId).digest('hex').slice(0, 24);
+  return withControllerLock(home, { scope: 'global', resource: `work-request-${lockId}` }, `accept-work:${requestId}`, () => {
+    const recordPath = workRequestIndexPath(home, requestId);
     if (existsSync(recordPath)) {
       const record = readJsonFile<WorkRequestIndexRecord>(recordPath);
-      if (record.repoId !== input.repoId) {
-        throw new Error(`REQUEST_ID_REPO_CONFLICT: ${normalizedRequestId} already belongs to repository ${record.repoId}`);
-      }
-      if (record.semanticKey !== normalizedSemanticKey) {
-        throw new Error(`REQUEST_ID_CONFLICT: ${normalizedRequestId} already belongs to ${record.semanticKey}`);
-      }
+      if (record.repoId !== input.repoId) throw new Error(`REQUEST_ID_REPO_CONFLICT: ${requestId} already belongs to repository ${record.repoId}`);
+      if (record.semanticKey !== semanticKey) throw new Error(`REQUEST_ID_CONFLICT: ${requestId} already belongs to ${record.semanticKey}`);
       const existing = getWorkContract({ controllerHome: home, repoId: record.repoId, now: options.now }, record.workId);
-      if (!existing) {
-        throw new Error(`WORK_ACCEPTANCE_LOST: request ${normalizedRequestId} is indexed without a readable WorkContract`);
-      }
+      if (!existing) throw new Error(`WORK_ACCEPTANCE_LOST: request ${requestId} is indexed without a readable WorkContract`);
       return { contract: existing, deduplicated: true };
     }
-
     const contract = createWorkContract({ controllerHome: home, repoId: input.repoId, now: options.now }, {
       workId: `WORK-${Date.now()}-${randomUUID().slice(0, 8)}`,
       repoId: input.repoId,
@@ -744,7 +752,7 @@ export function acceptSubmittedWorkContract(
       mode: input.mode ?? 'direct_control',
       lifecycleRole: 'execution_child',
       parentWorkId,
-      objective: (input.objective ?? `Accepted operation ${input.operation.name}`).slice(0, 2_000),
+      objective: (input.objective ?? `Typed operation ${input.operation.name}`).slice(0, 2_000),
       acceptanceCriteria: input.acceptanceCriteria ?? [],
       workKind: input.workKind,
       risk: input.risk,
@@ -754,13 +762,9 @@ export function acceptSubmittedWorkContract(
       checks: input.checks ?? [],
       requestedBy: input.requestedBy ?? 'chatgpt',
       status: 'open',
-      requestId: normalizedRequestId,
+      requestId,
       submittedOperation: input.operation,
-      driver: {
-        preferred: 'external_controller',
-        allowWorker: false,
-        allowDirectEdit: input.operation.mode === 'readonly' || input.operation.mode === 'mutating',
-      },
+      driver: { preferred: 'external_controller', allowWorker: false, allowDirectEdit: input.operation.mode === 'readonly' || input.operation.mode === 'mutating' },
       suggestedNextActions: [{
         label: 'Claim controller ownership',
         tool: 'rh_work',
@@ -770,15 +774,7 @@ export function acceptSubmittedWorkContract(
         reason: 'Claim this Work before launching an external SuperController or Process Runtime command.',
       }],
     });
-
-    writeJsonAtomic(recordPath, {
-      requestId: normalizedRequestId,
-      repoId: input.repoId,
-      workId: contract.workId,
-      semanticKey: normalizedSemanticKey,
-      createdAt: contract.createdAt,
-    } satisfies WorkRequestIndexRecord);
-
+    writeJsonAtomic(recordPath, { requestId, repoId: input.repoId, workId: contract.workId, semanticKey, createdAt: contract.createdAt } satisfies WorkRequestIndexRecord);
     return { contract, deduplicated: false };
   });
 }
@@ -965,6 +961,7 @@ function updateWorkContractInternal(
   patch: Partial<Omit<WorkContract, 'schemaVersion' | 'workId' | 'repoId' | 'createdAt'>>,
   allowCompletionWrite: boolean,
   allowPhaseWrite = false,
+  allowRetainedCancelledResume = false,
 ): WorkContract {
   return withWorkContractStoreWrite(options, () => {
     const sanitizedId = sanitizeFileComponent(workId);
@@ -1022,13 +1019,13 @@ function updateWorkContractInternal(
     completionOutcome: patch.completionOutcome ?? current.completionOutcome,
     evidenceRefs: (patch.evidenceRefs ?? current.evidenceRefs).slice(0, current.evidencePolicy.maxEvidenceRefs),
     handoffRefs: (patch.handoffRefs ?? current.handoffRefs).slice(0, 20),
-    suggestedNextActions: (patch.suggestedNextActions ?? current.suggestedNextActions).slice(0, 8),
+    suggestedNextActions: suggestedActionsForStatus(patch.status ?? current.status, patch.suggestedNextActions ?? current.suggestedNextActions),
     policyDecisions: (patch.policyDecisions ?? current.policyDecisions).slice(0, 20),
     checkRefs: (patch.checkRefs ?? current.checkRefs).slice(0, 50),
     reconciliations: (patch.reconciliations ?? current.reconciliations ?? []).slice(0, 20),
     objective: (patch.objective ?? current.objective).slice(0, 2_000),
     continuationPrompt: (patch.continuationPrompt ?? current.continuationPrompt)?.slice(0, 2_000),
-    }));
+    }), { allowRetainedCancelledResume });
     const contracts = [...store.contracts];
     contracts[index] = next;
     writeWorkContractStore(options, { schemaVersion: 2, updatedAt: at, contracts });
@@ -1044,6 +1041,83 @@ export function updateWorkContract(
   return updateWorkContractInternal(options, workId, patch, false);
 }
 
+/**
+ * Reopen one explicitly retained cancelled repository Work after the facade has
+ * reauthenticated the same principal and revalidated physical Work ownership.
+ * Generic mutation APIs intentionally cannot perform terminal -> running.
+ */
+export function resumeRetainedCancelledWorkContract(
+  options: WorkContractStoreOptions,
+  workId: string,
+  input: {
+    principalId: string;
+    controllerInstanceId: string;
+    summary: string;
+    checkoutId?: string;
+    worktreeRef?: string;
+  },
+): WorkContract {
+  const current = getWorkContract(options, workId);
+  if (!current) throw new Error(`work contract not found: ${workId}`);
+  if (current.status !== 'cancelled' || current.dispatchState !== 'terminal' || current.phase !== 'cleanup') {
+    throw new Error(`WORK_CANCELLED_RESUME_STATUS_INVALID: ${workId}`);
+  }
+  if (current.workKind !== 'repository_change') throw new Error(`WORK_CANCELLED_RESUME_KIND_INVALID: ${workId}`);
+  if (current.completionReceipt || current.completionOutcome) throw new Error(`WORK_CANCELLED_RESUME_COMPLETION_CONFLICT: ${workId}`);
+  if (current.phaseEvidence.cleanup.state !== 'skipped' || current.phaseEvidence.cleanup.source !== 'recorded') {
+    throw new Error(`WORK_CANCELLED_RESUME_HISTORY_AMBIGUOUS: ${workId}`);
+  }
+  const originalPrincipal = current.principalId?.trim();
+  if (!originalPrincipal || originalPrincipal !== input.principalId.trim()) {
+    throw new Error(`WORK_CANCELLED_RESUME_PRINCIPAL_MISMATCH: ${workId}`);
+  }
+  const at = nowIso(options);
+  const evidenceRefs = [...current.evidenceRefs, {
+    title: 'explicit current-user Work reauthorization',
+    summary: input.summary.trim().slice(0, 1_000),
+    detailLevel: 'summary' as const,
+  }].slice(-current.evidencePolicy.maxEvidenceRefs);
+  const phaseEvidence = transitionPhaseEvidence({ ...current, evidenceRefs }, 'implementation', {
+    status: 'running',
+    summary: input.summary,
+    evidenceRefs,
+    recordedAt: at,
+    source: 'recorded',
+  });
+  return updateWorkContractInternal(options, workId, {
+    status: 'running',
+    phase: 'implementation',
+    phaseEvidence,
+    dispatchState: 'running',
+    evidenceRefs,
+    checkoutId: input.checkoutId ?? current.checkoutId,
+    worktreeRef: input.worktreeRef ?? current.worktreeRef,
+    controllerInstanceId: input.controllerInstanceId,
+    continuationPrompt: input.summary,
+  }, false, true, true);
+}
+
+/** Merge non-authoritative discovery/change evidence without changing policy fences. */
+export function recordWorkScopeEvidence(
+  options: WorkContractStoreOptions,
+  workId: string,
+  input: { initialLikelyPaths?: string[]; inspectedPaths?: string[]; actualChangedPaths?: string[] },
+): WorkContract {
+  const current = getWorkContract(options, workId);
+  if (!current) throw new Error(`work contract not found: ${workId}`);
+  const previous = current.scopeEvidence ?? {
+    initialLikelyPaths: [], inspectedPaths: [], actualChangedPaths: [], recordedAt: current.createdAt,
+  };
+  return updateWorkContract(options, workId, {
+    scopeEvidence: {
+      initialLikelyPaths: [...new Set([...previous.initialLikelyPaths, ...(input.initialLikelyPaths ?? [])])].slice(0, 100),
+      inspectedPaths: [...new Set([...previous.inspectedPaths, ...(input.inspectedPaths ?? [])])].slice(0, 500),
+      actualChangedPaths: [...new Set([...previous.actualChangedPaths, ...(input.actualChangedPaths ?? [])])].slice(0, 500),
+      recordedAt: nowIso(options),
+    },
+  });
+}
+
 export function transitionWorkContractPhase(
   options: WorkContractStoreOptions,
   workId: string,
@@ -1126,6 +1200,9 @@ export function recordWorkCompletionReceipt(
     return current;
   }
   const recordedAt = receipt.recordedAt;
+  const receiptChangedPaths = isRepositoryCompletionReceipt(receipt) || isDirectEditWorkCompletionReceipt(receipt)
+    ? receipt.changedPaths
+    : [];
   const phaseEvidence = Object.fromEntries((['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]).map((phase) => [phase, {
     state: 'satisfied',
     source: 'recorded',
@@ -1143,5 +1220,30 @@ export function recordWorkCompletionReceipt(
     completionOutcome,
     ...(completionWorkKind ? { workKind: completionWorkKind } : {}),
     completionReceipt: receipt,
+    scopeEvidence: {
+      initialLikelyPaths: current.scopeEvidence?.initialLikelyPaths ?? current.allowedPaths,
+      inspectedPaths: current.scopeEvidence?.inspectedPaths ?? [],
+      actualChangedPaths: [...new Set(receiptChangedPaths)].slice(0, 500),
+      recordedAt,
+    },
   }, true, true);
 }
+export interface AcceptSubmittedWorkInput {
+  requestId: string;
+  repoId: string;
+  parentWorkId?: string;
+  semanticKey: string;
+  operation: SubmittedWorkOperation;
+  objective?: string;
+  mode?: WorkContract['mode'];
+  requestedBy?: WorkContract['requestedBy'];
+  principalId?: string;
+  controllerInstanceId?: string;
+  workKind?: WorkKind;
+  risk?: WorkRisk;
+  allowedPaths?: string[];
+  forbiddenPaths?: string[];
+  checks?: string[];
+  acceptanceCriteria?: string[];
+  constraints?: WorkContract['constraints'];
+}

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

@@ -0,0 +1,271 @@
+import { execFileSync } from 'child_process';
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+} from 'fs';
+import { homedir } from 'os';
+import { basename, join, relative, resolve, sep } from 'path';
+
+const DEFAULT_GENERATED_CACHE_GRACE_MS = 6 * 60 * 60_000;
+const DEFAULT_SCAN_BUDGET = 1_000;
+const DEFAULT_REMOVAL_BUDGET = 8;
+
+export interface GeneratedCacheRetentionOptions {
+  nowMs?: number;
+  graceMs?: number;
+  maxEntries?: number;
+  maxRemovals?: number;
+  processCommands?: string[];
+}
+
+export interface GeneratedCacheRetentionReport {
+  inspected: number;
+  eligible: number;
+  removedPaths: string[];
+  retainedPaths: string[];
+  skippedByReason: Record<string, number>;
+  errors: string[];
+  budgetExhausted: boolean;
+}
+
+export interface XCTestDeviceCleanupReport {
+  attempted: boolean;
+  removedDevices: number;
+  skippedReason?: string;
+  error?: string;
+}
+
+interface Candidate {
+  path: string;
+  kind: 'forge_ios_derived_data' | 'harness_derived_data' | 'repo_harness_derived_data' | 'tmp_derived_data';
+}
+
+function increment(counts: Record<string, number>, reason: string): void {
+  counts[reason] = (counts[reason] ?? 0) + 1;
+}
+
+function canonical(path: string): string {
+  try { return realpathSync(path); } catch { return resolve(path); }
+}
+
+function pathInside(root: string, path: string): boolean {
+  const base = canonical(root);
+  const target = canonical(path);
+  const rel = relative(base, target);
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`);
+}
+
+function collectProcessCommands(): string[] {
+  try {
+    return execFileSync('ps', ['-axo', 'command='], {
+      encoding: 'utf8',
+      timeout: 2_000,
+      maxBuffer: 2 * 1024 * 1024,
+    }).split('\n').map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function commandReferencesPath(commands: readonly string[], repoRoot: string, path: string): boolean {
+  const absolute = canonical(path);
+  const rel = relative(resolve(repoRoot), absolute).replace(/\\/g, '/');
+  return commands.some((command) => command.includes(absolute) || (rel && command.includes(rel)));
+}
+
+function containsTrackedFiles(repoRoot: string, path: string): boolean {
+  const rel = relative(resolve(repoRoot), resolve(path));
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`)) return true;
+  try {
+    const output = execFileSync('git', ['-C', repoRoot, 'ls-files', '--', rel], {
+      encoding: 'utf8',
+      timeout: 2_000,
+      maxBuffer: 256 * 1024,
+    });
+    return output.trim().length > 0;
+  } catch {
+    // If repository identity cannot be proven, fail closed.
+    return true;
+  }
+}
+
+function directChildDirectories(root: string, predicate: (name: string) => boolean, 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) break;
+    budget.remaining -= 1;
+    const name = String(entry.name);
+    if (entry.isDirectory() && predicate(name)) found.push(join(root, name));
+  }
+  return found;
+}
+
+function nestedDerivedDataDirectories(root: string, maxDepth: number, budget: { remaining: number }): string[] {
+  if (!existsSync(root) || budget.remaining <= 0) return [];
+  const found: string[] = [];
+  const visit = (dir: string, depth: number): void => {
+    if (depth > maxDepth || budget.remaining <= 0) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    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 (String(entry.name) === 'DerivedData') {
+        found.push(path);
+        continue;
+      }
+      visit(path, depth + 1);
+    }
+  };
+  visit(root, 0);
+  return found;
+}
+
+function discoverCandidates(repoRoot: string, maxEntries: 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[] = [];
+
+  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' });
+  }
+
+  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,
+  };
+}
+
+/**
+ * Reclaim only rebuildable Xcode DerivedData under Forge/repo-harness-owned
+ * namespaces. Result bundles, logs, edit-session metadata, and all tracked files
+ * are deliberately outside this cleanup surface.
+ */
+export function cleanupGeneratedRepositoryCaches(
+  repoRoot: string,
+  options: GeneratedCacheRetentionOptions = {},
+): GeneratedCacheRetentionReport {
+  const nowMs = options.nowMs ?? Date.now();
+  const graceMs = Math.max(60_000, Math.floor(options.graceMs ?? DEFAULT_GENERATED_CACHE_GRACE_MS));
+  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 report: GeneratedCacheRetentionReport = {
+    inspected: discovered.inspected,
+    eligible: 0,
+    removedPaths: [],
+    retainedPaths: [],
+    skippedByReason: {},
+    errors: [],
+    budgetExhausted: discovered.truncated,
+  };
+
+  for (const candidate of discovered.candidates) {
+    const ownedRoot = candidate.kind === 'forge_ios_derived_data'
+      ? join(repoRoot, '.forge', 'ios', 'DerivedData')
+      : candidate.kind === 'harness_derived_data'
+        ? join(repoRoot, '.ai', 'harness')
+        : candidate.kind === 'repo_harness_derived_data'
+          ? join(repoRoot, '.repo-harness')
+          : join(repoRoot, '.tmp');
+    try {
+      const stat = lstatSync(candidate.path);
+      if (!stat.isDirectory() || stat.isSymbolicLink() || !pathInside(ownedRoot, candidate.path)) {
+        increment(report.skippedByReason, 'ownership_unproven');
+        report.retainedPaths.push(relative(repoRoot, candidate.path));
+        continue;
+      }
+      if (nowMs - stat.mtimeMs < graceMs) {
+        increment(report.skippedByReason, 'retention_grace');
+        continue;
+      }
+      if (commandReferencesPath(commands, repoRoot, candidate.path)) {
+        increment(report.skippedByReason, 'active_process');
+        report.retainedPaths.push(relative(repoRoot, candidate.path));
+        continue;
+      }
+      if (containsTrackedFiles(repoRoot, candidate.path)) {
+        increment(report.skippedByReason, 'tracked_content');
+        report.retainedPaths.push(relative(repoRoot, candidate.path));
+        continue;
+      }
+      report.eligible += 1;
+      if (remainingRemovals <= 0) {
+        report.budgetExhausted = true;
+        increment(report.skippedByReason, 'cleanup_budget_exhausted');
+        continue;
+      }
+      remainingRemovals -= 1;
+      rmSync(candidate.path, { recursive: true, force: true });
+      report.removedPaths.push(relative(repoRoot, candidate.path).replace(/\\/g, '/'));
+    } catch (error) {
+      report.errors.push(`${candidate.kind}:${relative(repoRoot, candidate.path)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  return report;
+}
+
+/**
+ * XCTest's private device set is separate from the user's normal CoreSimulator
+ * devices. When Forge is idle, delete only that dedicated set through simctl so
+ * XCTest clones cannot accumulate indefinitely. Never rm the device set.
+ */
+export function cleanupIdleXCTestDevices(controllerHome: string): XCTestDeviceCleanupReport {
+  if (process.platform !== 'darwin') return { attempted: false, removedDevices: 0, skippedReason: 'not_darwin' };
+  const normalizedControllerHome = resolve(controllerHome).replace(/\\/g, '/');
+  if (!normalizedControllerHome.includes('/.forge/controller')) {
+    return { attempted: false, removedDevices: 0, skippedReason: 'nonstandard_controller_home' };
+  }
+  const deviceSet = join(homedir(), 'Library', 'Developer', 'XCTestDevices');
+  if (!existsSync(deviceSet)) return { attempted: false, removedDevices: 0, skippedReason: 'device_set_missing' };
+  let deviceDirectories = 0;
+  try {
+    deviceDirectories = readdirSync(deviceSet, { withFileTypes: true }).filter((entry) => entry.isDirectory()).length;
+  } catch (error) {
+    return { attempted: false, removedDevices: 0, error: error instanceof Error ? error.message : String(error) };
+  }
+  if (deviceDirectories <= 4) return { attempted: false, removedDevices: 0, skippedReason: 'below_cleanup_threshold' };
+
+  const commands = collectProcessCommands();
+  if (commands.some((command) => /(?:^|\/)(?:xcodebuild|xctest|swiftc)(?:\s|$)/.test(command))) {
+    return { attempted: false, removedDevices: 0, skippedReason: 'active_xcode_process' };
+  }
+  try {
+    const listed = execFileSync('xcrun', ['simctl', '--set', deviceSet, 'list', 'devices', '--json'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      maxBuffer: 2 * 1024 * 1024,
+    });
+    const parsed = JSON.parse(listed) as { devices?: Record<string, Array<{ state?: string }>> };
+    const devices = Object.values(parsed.devices ?? {}).flat();
+    if (devices.some((device) => device.state === 'Booted')) {
+      return { attempted: false, removedDevices: 0, skippedReason: 'booted_xctest_device' };
+    }
+    execFileSync('xcrun', ['simctl', '--set', deviceSet, 'shutdown', 'all'], { timeout: 15_000, stdio: 'ignore' });
+    execFileSync('xcrun', ['simctl', '--set', deviceSet, 'delete', 'all'], { timeout: 30_000, stdio: 'ignore' });
+    return { attempted: true, removedDevices: devices.length };
+  } catch (error) {
+    return { attempted: true, removedDevices: 0, error: error instanceof Error ? error.message : String(error) };
+  }
+}