@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/control-plane/facade/work-state-machine.ts

@@ -0,0 +1,250 @@
+import {
+  isDirectEditWorkCompletionReceipt,
+  isReadOnlyReviewCompletionReceipt,
+  isRemoteEffectCompletionReceipt,
+  isRepositoryCompletionReceipt,
+  type DispatchState,
+  type EvidenceRef,
+  type EvidenceState,
+  type SuggestedNextAction,
+  type WorkContract,
+  type WorkContractStatus,
+  type WorkPhase,
+  type WorkPhaseEvidence,
+  type WorkPhaseEvidenceMap,
+} from './types';
+
+export function phaseIndex(phase: WorkPhase): number {
+  return ['implementation', 'verification', 'delivery', 'cleanup'].indexOf(phase);
+}
+
+export function transitionPhaseEvidence(
+  current: Pick<WorkContract, 'phaseEvidence' | 'evidenceRefs'>,
+  targetPhase: WorkPhase,
+  input: {
+    status: WorkContractStatus;
+    summary: string;
+    evidenceRefs?: EvidenceRef[];
+    recordedAt: string;
+    source?: WorkPhaseEvidence['source'];
+  },
+): WorkPhaseEvidenceMap {
+  const targetIndex = phaseIndex(targetPhase);
+  const evidenceRefs = (input.evidenceRefs ?? current.evidenceRefs).slice(0, 20);
+  const source = input.source ?? 'recorded';
+  const phaseEvidence = { ...current.phaseEvidence };
+  for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
+    const index = phaseIndex(phase);
+    if (index < targetIndex) {
+      phaseEvidence[phase] = {
+        state: ['satisfied', 'skipped'].includes(phaseEvidence[phase].state) ? phaseEvidence[phase].state : 'satisfied',
+        source,
+        summary: `Advanced to ${targetPhase}: ${input.summary}`.slice(0, 1_000),
+        evidenceRefs,
+        recordedAt: input.recordedAt,
+      };
+    } else if (index > targetIndex) {
+      phaseEvidence[phase] = {
+        state: 'pending',
+        source,
+        summary: `Waiting for Work phase ${phase}.`,
+        evidenceRefs: [],
+        recordedAt: input.recordedAt,
+      };
+    }
+  }
+  phaseEvidence[targetPhase] = {
+    state: input.status === 'failed'
+      ? 'failed'
+      : input.status === 'cancelled'
+        ? 'skipped'
+        : input.status === 'blocked' || input.status === 'ready'
+          ? 'blocked'
+          : 'active',
+    source,
+    summary: input.summary.trim().slice(0, 1_000) || `Work entered ${targetPhase}.`,
+    evidenceRefs,
+    recordedAt: input.recordedAt,
+  };
+  return phaseEvidence;
+}
+
+export function validateWorkSemantics(contract: WorkContract): WorkContract {
+  if (!contract.objective.trim()) throw new Error('WORK_OBJECTIVE_REQUIRED');
+  if (contract.status === 'completed' && !contract.completionReceipt) {
+    throw new Error('WORK_COMPLETION_RECEIPT_REQUIRED');
+  }
+  const currentPhaseIndex = phaseIndex(contract.phase);
+  for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
+    const checkpoint = contract.phaseEvidence?.[phase];
+    if (!checkpoint) throw new Error(`WORK_PHASE_EVIDENCE_REQUIRED: ${phase}`);
+    const index = phaseIndex(phase);
+    if (index < currentPhaseIndex && !['satisfied', 'skipped'].includes(checkpoint.state)) {
+      throw new Error(`WORK_PHASE_EVIDENCE_PREVIOUS_NOT_SATISFIED: ${phase}`);
+    }
+    if (index === currentPhaseIndex && checkpoint.state === 'pending') {
+      throw new Error(`WORK_PHASE_EVIDENCE_REQUIRED: ${phase}`);
+    }
+    if (index > currentPhaseIndex && checkpoint.state !== 'pending') {
+      throw new Error(`WORK_PHASE_EVIDENCE_FUTURE_NOT_PENDING: ${phase}`);
+    }
+  }
+  if (contract.completionReceipt) {
+    const receipt = contract.completionReceipt;
+    if (receipt.workId !== contract.workId) throw new Error('WORK_COMPLETION_RECEIPT_IDENTITY_MISMATCH');
+    if (isRepositoryCompletionReceipt(receipt)) {
+      if (!receipt.targetBranch.trim() || !receipt.targetRevision.trim()) throw new Error('WORK_COMPLETION_RECEIPT_TARGET_REQUIRED');
+      if (receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('WORK_COMPLETION_RECEIPT_DELIVERY_NOT_PROVEN');
+      if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('WORK_COMPLETION_RECEIPT_CLEANUP_NOT_PROVEN');
+    } else if (isDirectEditWorkCompletionReceipt(receipt)) {
+      const directEditAuthorityCount = Number(Boolean(receipt.editSessionId?.trim())) + Number(Boolean(receipt.reconciliationId?.trim()));
+      if (directEditAuthorityCount !== 1) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_AUTHORITY_REQUIRED');
+      if (!receipt.targetBranch.trim() || !receipt.targetRevision.trim()) throw new Error('WORK_COMPLETION_RECEIPT_TARGET_REQUIRED');
+      if (receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('WORK_COMPLETION_RECEIPT_DELIVERY_NOT_PROVEN');
+      if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('WORK_COMPLETION_RECEIPT_CLEANUP_NOT_PROVEN');
+      if (!['repository_change', 'completed_no_change'].includes(contract.workKind)) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_KIND_REQUIRED');
+      const expectedOutcome = contract.workKind === 'completed_no_change' ? 'completed_no_change' : 'completed_changed';
+      if (contract.completionOutcome !== expectedOutcome) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_OUTCOME_REQUIRED');
+    } else if (isReadOnlyReviewCompletionReceipt(receipt)) {
+      if (contract.workKind !== 'read_only_review') throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_no_change') throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_OUTCOME_REQUIRED');
+      if (!receipt.baseRevision.trim() || receipt.baseRevision !== receipt.sourceRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_SOURCE_REQUIRED');
+      if (contract.baseRevision && receipt.baseRevision !== contract.baseRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_BASE_MISMATCH');
+      if (receipt.workspaceChangedPaths.length !== 0) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_WORKSPACE_CHANGED');
+      const reviewEvidence = contract.readOnlyReviewEvidence;
+      if (!reviewEvidence || reviewEvidence.sourceRevision !== receipt.sourceRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_EVIDENCE_REQUIRED');
+      if (reviewEvidence.findings.length !== 0 || receipt.findingCount !== 0 || receipt.inspectedPaths.length === 0) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_CLEAN_SCOPE_REQUIRED');
+      const evidencePaths = [...new Set(reviewEvidence.inspectedPaths)].sort();
+      const receiptPaths = [...new Set(receipt.inspectedPaths)].sort();
+      if (evidencePaths.length !== receiptPaths.length || evidencePaths.some((path, index) => path !== receiptPaths[index])) {
+        throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_SCOPE_MISMATCH');
+      }
+      if (reviewEvidence.workspaceFingerprint && receipt.workspaceFingerprint && reviewEvidence.workspaceFingerprint !== receipt.workspaceFingerprint) {
+        throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_WORKSPACE_MISMATCH');
+      }
+    } else if (isRemoteEffectCompletionReceipt(receipt)) {
+      if (contract.workKind !== 'remote_effect') throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_remote') throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_OUTCOME_REQUIRED');
+      const authority = receipt.authority ?? 'plugin_action';
+      if (!receipt.actionId.trim() || !receipt.requestId.trim() || !receipt.semanticKey.trim() || !receipt.resultDigest.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_IDENTITY_REQUIRED');
+      }
+      if (authority === 'plugin_action' && !receipt.pluginId?.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_PLUGIN_IDENTITY_REQUIRED');
+      }
+      if (authority === 'repository_process' && !receipt.processId?.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_PROCESS_IDENTITY_REQUIRED');
+      }
+    } else {
+      if (contract.workKind !== 'local_effect') throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_local') throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_OUTCOME_REQUIRED');
+      if (!receipt.operation.trim() || !receipt.target.id.trim()) throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_TARGET_REQUIRED');
+    }
+    if (contract.status !== 'completed') throw new Error('WORK_COMPLETION_RECEIPT_REQUIRES_COMPLETED_WORK');
+    for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
+      if (!['satisfied', 'skipped'].includes(contract.phaseEvidence[phase].state)) {
+        throw new Error(`WORK_COMPLETION_PHASE_NOT_SATISFIED: ${phase}`);
+      }
+    }
+    for (const phase of ['delivery', 'cleanup'] as WorkPhase[]) {
+      if (contract.phaseEvidence[phase].receiptId !== receipt.receiptId) {
+        throw new Error(`WORK_COMPLETION_PHASE_RECEIPT_MISMATCH: ${phase}`);
+      }
+    }
+  }
+  const outcome = contract.completionOutcome;
+  if (!outcome) return contract;
+  if (contract.status !== 'completed' || !contract.completionReceipt) {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires a completed Work receipt`);
+  }
+  if (contract.dispatchState !== 'terminal') {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires terminal dispatch`);
+  }
+  if (contract.evidenceState !== 'valid') {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires valid evidence`);
+  }
+  if (outcome === 'completed_changed' && contract.workKind !== 'repository_change') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_changed requires repository_change WorkKind');
+  }
+  if (outcome === 'completed_no_change' && !['completed_no_change', 'read_only_review'].includes(contract.workKind)) {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_no_change requires completed_no_change or read_only_review WorkKind');
+  }
+  if (outcome === 'completed_no_change' && contract.workKind === 'read_only_review' && contract.completionReceipt?.source !== 'read_only_review') {
+    throw new Error('WORK_SEMANTICS_INVALID: read_only_review completed_no_change requires a read_only_review completion receipt');
+  }
+  if (outcome === 'completed_local' && contract.workKind !== 'local_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_local requires local_effect WorkKind');
+  }
+  if (outcome === 'completed_local' && contract.completionReceipt?.source !== 'local_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_local requires a local_effect completion receipt');
+  }
+  if (outcome === 'completed_remote' && contract.workKind !== 'remote_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_remote requires remote_effect WorkKind');
+  }
+  if (outcome === 'completed_remote' && contract.completionReceipt?.source !== 'remote_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_remote requires a remote_effect completion receipt');
+  }
+  if (outcome === 'superseded' && contract.workKind !== 'superseded') {
+    throw new Error('WORK_SEMANTICS_INVALID: superseded requires superseded WorkKind');
+  }
+  return contract;
+}
+
+const DISPATCH_TRANSITIONS: Readonly<Record<DispatchState, readonly DispatchState[]>> = {
+  not_dispatched: ['not_dispatched', 'claimed', 'launching', 'running', 'blocked', 'terminal'],
+  claimed: ['claimed', 'launching', 'running', 'blocked', 'terminal'],
+  launching: ['launching', 'running', 'blocked', 'terminal'],
+  running: ['running', 'blocked', 'terminal'],
+  blocked: ['blocked', 'claimed', 'launching', 'running', 'terminal'],
+  terminal: ['terminal'],
+};
+
+const EVIDENCE_TRANSITIONS: Readonly<Record<EvidenceState, readonly EvidenceState[]>> = {
+  none: ['none', 'partial', 'valid', 'failed'],
+  partial: ['partial', 'valid', 'stale', 'contradictory', 'failed'],
+  valid: ['valid', 'stale', 'contradictory', 'failed'],
+  stale: ['stale', 'partial', 'valid', 'contradictory', 'failed'],
+  contradictory: ['contradictory', 'partial', 'valid', 'failed'],
+  failed: ['failed', 'partial', 'valid', 'contradictory'],
+};
+
+export function validateWorkSemanticTransition(
+  current: WorkContract,
+  next: WorkContract,
+  options: { allowRetainedCancelledResume?: boolean } = {},
+): WorkContract {
+  const retryingFailedWork = current.status === 'failed'
+    && !current.completionOutcome
+    && ['claimed', 'launching', 'running', 'blocked'].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)) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: evidence ${current.evidenceState} -> ${next.evidenceState}`);
+  }
+  if (current.completionOutcome && current.completionOutcome !== next.completionOutcome) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: completion outcome ${current.completionOutcome} is immutable`);
+  }
+  if ((current.lifecycleRole ?? 'primary') !== (next.lifecycleRole ?? 'primary')) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: lifecycleRole is immutable');
+  }
+  if (current.parentWorkId !== next.parentWorkId) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: parentWorkId is immutable');
+  }
+  return next;
+}
+
+export function suggestedActionsForStatus(status: WorkContractStatus, actions: readonly SuggestedNextAction[]): SuggestedNextAction[] {
+  if (status === 'completed' || status === 'cancelled') return [];
+  return actions.slice(0, 8);
+}

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) };
+  }
+}

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

@@ -0,0 +1,44 @@
+export interface SchedulerConfig {
+  maxWorkers: number;
+  maxConcurrentRepositories: number;
+  pollIntervalMs: number;
+  idleBackoffMaxMs: number;
+  heartbeatIntervalMs: number;
+  heartbeatTimeoutMs: number;
+  maxHeavyChecks: number;
+  maxAgentProcesses: number;
+  maxCodexProcesses: number;
+  maxClaudeProcesses: number;
+  maxGitHubProcesses: number;
+  minFreeMemoryMb: number;
+  maxLoadPerCpu: number;
+}
+
+export function normalizeSchedulerConfig(
+  config: Partial<SchedulerConfig> = {},
+  env: NodeJS.ProcessEnv = process.env,
+): SchedulerConfig {
+  const pollIntervalMs = Math.max(50, config.pollIntervalMs ?? 250);
+  const idleBackoffMaxMs = Math.max(250, config.idleBackoffMaxMs ?? Number(env.FORGE_IDLE_BACKOFF_MAX_MS ?? 2_000));
+  const heartbeatIntervalMs = Math.max(25, config.heartbeatIntervalMs ?? Number(env.FORGE_SCHEDULER_HEARTBEAT_INTERVAL_MS ?? 1_000));
+  const heartbeatTimeoutMs = Math.max(
+    heartbeatIntervalMs * 4,
+    idleBackoffMaxMs * 4,
+    config.heartbeatTimeoutMs ?? Number(env.FORGE_SCHEDULER_HEARTBEAT_TIMEOUT_MS ?? 60_000),
+  );
+  return {
+    maxWorkers: Math.max(1, config.maxWorkers ?? Number(env.FORGE_MAX_WORKERS ?? 4)),
+    maxConcurrentRepositories: Math.max(1, config.maxConcurrentRepositories ?? Number(env.FORGE_MAX_ACTIVE_REPOS ?? 4)),
+    pollIntervalMs,
+    idleBackoffMaxMs,
+    heartbeatIntervalMs,
+    heartbeatTimeoutMs,
+    maxHeavyChecks: Math.max(1, config.maxHeavyChecks ?? Number(env.FORGE_MAX_HEAVY_CHECKS ?? 2)),
+    maxAgentProcesses: Math.max(1, config.maxAgentProcesses ?? Number(env.FORGE_MAX_AGENT_PROCESSES ?? 4)),
+    maxCodexProcesses: Math.max(1, config.maxCodexProcesses ?? Number(env.FORGE_MAX_CODEX_PROCESSES ?? 3)),
+    maxClaudeProcesses: Math.max(1, config.maxClaudeProcesses ?? Number(env.FORGE_MAX_CLAUDE_PROCESSES ?? 2)),
+    maxGitHubProcesses: Math.max(1, config.maxGitHubProcesses ?? Number(env.FORGE_MAX_GITHUB_PROCESSES ?? 2)),
+    minFreeMemoryMb: Math.max(64, config.minFreeMemoryMb ?? Number(env.FORGE_MIN_FREE_MEMORY_MB ?? 512)),
+    maxLoadPerCpu: Math.max(0.25, config.maxLoadPerCpu ?? Number(env.FORGE_MAX_LOAD_PER_CPU ?? 1.5)),
+  };
+}

package/src/runtime/control-plane/global-scheduler/dispatch-capacity.ts

@@ -0,0 +1,80 @@
+import type { ExecutionJob } from '../../execution/jobs/types';
+
+export type SchedulerAgentProvider = 'codex' | 'claude' | 'github-copilot';
+
+export interface SchedulerDispatchLimits {
+  maxWorkers: number;
+  maxHeavyChecks: number;
+  maxAgentProcesses: number;
+  maxCodexProcesses: number;
+  maxClaudeProcesses: number;
+  maxGitHubProcesses: number;
+}
+
+export interface SchedulerDispatchCapacity {
+  reservedJobs: ExecutionJob[];
+  workers: number;
+  heavyChecks: number;
+  agents: number;
+  providers: Map<SchedulerAgentProvider, number>;
+}
+
+export function schedulerAgentProvider(
+  job: Pick<ExecutionJob, 'payload'>,
+): SchedulerAgentProvider {
+  const agent = job.payload.arguments?.agent;
+  if (agent === 'claude' || agent === 'github-copilot') return agent;
+  return 'codex';
+}
+
+export function createSchedulerDispatchCapacity(
+  activeJobs: readonly ExecutionJob[],
+  limits: SchedulerDispatchLimits,
+  pressured: boolean,
+): SchedulerDispatchCapacity {
+  const reservedJobs = activeJobs.filter((job) => job.status === 'running' || job.status === 'dispatched');
+  const reservedAgents = reservedJobs.filter((job) => job.type === 'agent-run' || job.type === 'dispatch-task');
+  let workers = limits.maxWorkers - reservedJobs.length;
+  let heavyChecks = limits.maxHeavyChecks
+    - reservedJobs.filter((job) => job.type === 'check' || job.type === 'verify-edit').length;
+  let agents = limits.maxAgentProcesses - reservedAgents.length;
+  const providers = new Map<SchedulerAgentProvider, number>([
+    ['codex', limits.maxCodexProcesses - reservedAgents.filter((job) => schedulerAgentProvider(job) === 'codex').length],
+    ['claude', limits.maxClaudeProcesses - reservedAgents.filter((job) => schedulerAgentProvider(job) === 'claude').length],
+    ['github-copilot', limits.maxGitHubProcesses - reservedAgents.filter((job) => schedulerAgentProvider(job) === 'github-copilot').length],
+  ]);
+  if (pressured) {
+    workers = Math.min(workers, 1);
+    heavyChecks = Math.min(heavyChecks, 1);
+    agents = 0;
+    providers.set('codex', 0);
+    providers.set('claude', 0);
+    providers.set('github-copilot', 0);
+  }
+  return { reservedJobs, workers, heavyChecks, agents, providers };
+}
+
+export function schedulerDispatchCapacityAllows(
+  capacity: SchedulerDispatchCapacity,
+  job: Pick<ExecutionJob, 'type' | 'payload'>,
+): boolean {
+  if ((job.type === 'check' || job.type === 'verify-edit') && capacity.heavyChecks <= 0) return false;
+  if (job.type === 'agent-run' || job.type === 'dispatch-task') {
+    if (capacity.agents <= 0) return false;
+    if ((capacity.providers.get(schedulerAgentProvider(job)) ?? 0) <= 0) return false;
+  }
+  return true;
+}
+
+export function consumeSchedulerDispatchCapacity(
+  capacity: SchedulerDispatchCapacity,
+  job: Pick<ExecutionJob, 'type' | 'payload'>,
+): void {
+  capacity.workers -= 1;
+  if (job.type === 'check' || job.type === 'verify-edit') capacity.heavyChecks -= 1;
+  if (job.type === 'agent-run' || job.type === 'dispatch-task') {
+    capacity.agents -= 1;
+    const provider = schedulerAgentProvider(job);
+    capacity.providers.set(provider, (capacity.providers.get(provider) ?? 0) - 1);
+  }
+}