@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/control-plane/facade/work-implementation-review.ts

@@ -0,0 +1,2 @@
+/** @deprecated Kernel V2 compatibility shim. Canonical authority is packages/kernel/work/domain/implementation-review. */
+export * from '../../../../packages/kernel/work/domain/implementation-review';

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

@@ -1,250 +1,2 @@
-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);
-}
+/** @deprecated Kernel V2 compatibility shim. Canonical authority is packages/kernel/work/domain/state-machine. */
+export * from '../../../../packages/kernel/work/domain/state-machine';

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

@@ -8,10 +8,16 @@ import {
 } from 'fs';
 import { homedir } from 'os';
 import { basename, join, relative, resolve, sep } from 'path';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 
 const DEFAULT_GENERATED_CACHE_GRACE_MS = 6 * 60 * 60_000;
+const DEFAULT_BROWSER_UPLOAD_GRACE_MS = 24 * 60 * 60_000;
+const DEFAULT_BROWSER_SCREENSHOT_GRACE_MS = 7 * 24 * 60 * 60_000;
+const DEFAULT_BROWSER_ARTIFACT_ACTIVE_GRACE_MS = 60 * 60_000;
 const DEFAULT_SCAN_BUDGET = 1_000;
 const DEFAULT_REMOVAL_BUDGET = 8;
+const DEFAULT_BROWSER_ARTIFACT_SCAN_BUDGET = 1_000;
+const DEFAULT_BROWSER_ARTIFACT_REMOVAL_BUDGET = 16;
 
 export interface GeneratedCacheRetentionOptions {
   nowMs?: number;
@@ -31,6 +37,41 @@ export interface GeneratedCacheRetentionReport {
   budgetExhausted: boolean;
 }
 
+export type BrowserDisposableArtifactKind = 'screenshots' | 'downloads' | 'diagnostics';
+
+export interface BrowserArtifactRetentionOptions {
+  nowMs?: number;
+  activeGraceMs?: number;
+  graceMs?: number;
+  maxEntries?: number;
+  maxRemovals?: number;
+  maxCountPerClass?: number;
+  maxBytesPerClass?: number;
+}
+
+export interface BrowserArtifactClassRetentionReport {
+  inspected: number;
+  eligible: number;
+  removedCount: number;
+  removedBytes: number;
+  retainedCount: number;
+  totalBytesBefore: number;
+  totalBytesAfter: number;
+  overCapacity: boolean;
+  blockers: string[];
+}
+
+export interface BrowserArtifactRetentionReport {
+  policyVersion: 'browser-disposable-artifact-retention-v1';
+  inspected: number;
+  removedPaths: string[];
+  removedBytes: number;
+  skippedByReason: Record<string, number>;
+  errors: string[];
+  budgetExhausted: boolean;
+  classes: Record<BrowserDisposableArtifactKind, BrowserArtifactClassRetentionReport>;
+}
+
 export interface XCTestDeviceCleanupReport {
   attempted: boolean;
   removedDevices: number;
@@ -40,7 +81,13 @@ export interface XCTestDeviceCleanupReport {
 
 interface Candidate {
   path: string;
-  kind: 'forge_ios_derived_data' | 'harness_derived_data' | 'repo_harness_derived_data' | 'tmp_derived_data';
+  kind:
+    | 'forge_ios_derived_data'
+    | 'harness_derived_data'
+    | 'repo_harness_derived_data'
+    | 'tmp_derived_data'
+    | 'forge_browser_upload'
+    | 'forge_browser_screenshot';
 }
 
 function increment(counts: Record<string, number>, reason: string): void {
@@ -71,9 +118,14 @@ function collectProcessCommands(): string[] {
 }
 
 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)));
+  const rawAbsolute = resolve(path);
+  const canonicalAbsolute = canonical(path);
+  const rawRelative = relative(resolve(repoRoot), rawAbsolute).replace(/\\/g, '/');
+  const canonicalRelative = relative(canonical(repoRoot), canonicalAbsolute).replace(/\\/g, '/');
+  return commands.some((command) => command.includes(rawAbsolute)
+    || command.includes(canonicalAbsolute)
+    || (rawRelative && command.includes(rawRelative))
+    || (canonicalRelative && command.includes(canonicalRelative)));
 }
 
 function containsTrackedFiles(repoRoot: string, path: string): boolean {
@@ -106,6 +158,19 @@ function directChildDirectories(root: string, predicate: (name: string) => boole
   return found;
 }
 
+function directChildFiles(root: string, budget: { remaining: number }): string[] {
+  if (!existsSync(root) || budget.remaining <= 0) return [];
+  const found: string[] = [];
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return found; }
+  for (const entry of entries) {
+    if (budget.remaining <= 0) break;
+    budget.remaining -= 1;
+    if (entry.isFile()) found.push(join(root, entry.name));
+  }
+  return found;
+}
+
 function nestedDerivedDataDirectories(root: string, maxDepth: number, budget: { remaining: number }): string[] {
   if (!existsSync(root) || budget.remaining <= 0) return [];
   const found: string[] = [];
@@ -135,6 +200,15 @@ function discoverCandidates(repoRoot: string, maxEntries: number): { candidates:
   const initial = budget.remaining;
   const candidates: Candidate[] = [];
 
+  // Browser artifacts are direct children of small, explicitly owned roots.
+  // Scan them before recursively walking potentially high-cardinality cache
+  // trees so cache history cannot starve their retention policy.
+  for (const path of directChildFiles(join(root, '.forge', 'browser', 'uploads'), budget)) {
+    candidates.push({ path, kind: 'forge_browser_upload' });
+  }
+  for (const path of directChildFiles(join(root, '.forge', 'browser', 'screenshots'), budget)) {
+    candidates.push({ path, kind: 'forge_browser_screenshot' });
+  }
   for (const path of directChildDirectories(join(root, '.forge', 'ios', 'DerivedData'), () => true, budget)) {
     candidates.push({ path, kind: 'forge_ios_derived_data' });
   }
@@ -147,7 +221,6 @@ function discoverCandidates(repoRoot: string, maxEntries: number): { candidates:
   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,
@@ -155,17 +228,36 @@ function discoverCandidates(repoRoot: string, maxEntries: number): { candidates:
   };
 }
 
+function retentionGraceMs(candidate: Candidate, explicitGraceMs: number | undefined): number {
+  if (explicitGraceMs !== undefined) return Math.max(60_000, Math.floor(explicitGraceMs));
+  if (candidate.kind === 'forge_browser_upload') return DEFAULT_BROWSER_UPLOAD_GRACE_MS;
+  if (candidate.kind === 'forge_browser_screenshot') return DEFAULT_BROWSER_SCREENSHOT_GRACE_MS;
+  return DEFAULT_GENERATED_CACHE_GRACE_MS;
+}
+
+function candidateOwnedRoot(repoRoot: string, candidate: Candidate): string {
+  switch (candidate.kind) {
+    case 'forge_ios_derived_data': return join(repoRoot, '.forge', 'ios', 'DerivedData');
+    case 'harness_derived_data': return join(repoRoot, '.ai', 'harness');
+    case 'repo_harness_derived_data': return join(repoRoot, '.repo-harness');
+    case 'tmp_derived_data': return join(repoRoot, '.tmp');
+    case 'forge_browser_upload': return join(repoRoot, '.forge', 'browser', 'uploads');
+    case 'forge_browser_screenshot': return join(repoRoot, '.forge', 'browser', 'screenshots');
+  }
+}
+
 /**
- * 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.
+ * Reclaim only rebuildable DerivedData and bounded browser artifacts under
+ * Forge-owned namespaces. Browser uploads are temporary staging (24 hours);
+ * screenshots remain review evidence for seven days. Result bundles, logs,
+ * profiles, downloads, edit-session metadata, and all tracked files remain
+ * 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();
@@ -181,21 +273,16 @@ export function cleanupGeneratedRepositoryCaches(
   };
 
   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');
+    const ownedRoot = candidateOwnedRoot(repoRoot, candidate);
+    const fileCandidate = candidate.kind === 'forge_browser_upload' || candidate.kind === 'forge_browser_screenshot';
     try {
       const stat = lstatSync(candidate.path);
-      if (!stat.isDirectory() || stat.isSymbolicLink() || !pathInside(ownedRoot, candidate.path)) {
+      if ((fileCandidate ? !stat.isFile() : !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) {
+      if (nowMs - stat.mtimeMs < retentionGraceMs(candidate, options.graceMs)) {
         increment(report.skippedByReason, 'retention_grace');
         continue;
       }
@@ -226,6 +313,140 @@ export function cleanupGeneratedRepositoryCaches(
   return report;
 }
 
+function emptyBrowserArtifactClassReport(): BrowserArtifactClassRetentionReport {
+  return {
+    inspected: 0,
+    eligible: 0,
+    removedCount: 0,
+    removedBytes: 0,
+    retainedCount: 0,
+    totalBytesBefore: 0,
+    totalBytesAfter: 0,
+    overCapacity: false,
+    blockers: [],
+  };
+}
+
+function browserArtifactPolicy(kind: BrowserDisposableArtifactKind): { graceMs: number; maxCount: number; maxBytes: number } {
+  switch (kind) {
+    case 'screenshots': return { graceMs: 7 * 24 * 60 * 60_000, maxCount: 500, maxBytes: 512 * 1024 * 1024 };
+    case 'downloads': return { graceMs: 7 * 24 * 60 * 60_000, maxCount: 200, maxBytes: 2 * 1024 * 1024 * 1024 };
+    case 'diagnostics': return { graceMs: 24 * 60 * 60_000, maxCount: 200, maxBytes: 256 * 1024 * 1024 };
+  }
+}
+
+/**
+ * Bound disposable Browser provider artifacts below the Controller Home repository
+ * namespace. Session/profile authority is deliberately excluded: this cleanup is
+ * only for screenshots, downloads and diagnostics that can disappear without
+ * changing provider-effect or ControllerRound semantics.
+ */
+export function cleanupControllerHomeBrowserArtifacts(
+  controllerHome: string,
+  repoId: string,
+  options: BrowserArtifactRetentionOptions = {},
+): BrowserArtifactRetentionReport {
+  const nowMs = options.nowMs ?? Date.now();
+  const activeGraceMs = Math.max(60_000, Math.floor(options.activeGraceMs ?? DEFAULT_BROWSER_ARTIFACT_ACTIVE_GRACE_MS));
+  let remainingScan = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_BROWSER_ARTIFACT_SCAN_BUDGET));
+  let remainingRemovals = Math.max(0, Math.floor(options.maxRemovals ?? DEFAULT_BROWSER_ARTIFACT_REMOVAL_BUDGET));
+  const browserRoot = join(repositoryControllerRoot(controllerHome, repoId), 'browser');
+  const report: BrowserArtifactRetentionReport = {
+    policyVersion: 'browser-disposable-artifact-retention-v1',
+    inspected: 0,
+    removedPaths: [],
+    removedBytes: 0,
+    skippedByReason: {},
+    errors: [],
+    budgetExhausted: false,
+    classes: {
+      screenshots: emptyBrowserArtifactClassReport(),
+      downloads: emptyBrowserArtifactClassReport(),
+      diagnostics: emptyBrowserArtifactClassReport(),
+    },
+  };
+
+  for (const kind of ['screenshots', 'downloads', 'diagnostics'] as const) {
+    const classReport = report.classes[kind];
+    const root = join(browserRoot, kind);
+    const defaults = browserArtifactPolicy(kind);
+    const graceMs = Math.max(activeGraceMs, Math.floor(options.graceMs ?? defaults.graceMs));
+    const maxCount = Math.max(1, Math.floor(options.maxCountPerClass ?? defaults.maxCount));
+    const maxBytes = Math.max(1, Math.floor(options.maxBytesPerClass ?? defaults.maxBytes));
+    if (!existsSync(root) || remainingScan <= 0) continue;
+
+    let entries;
+    try { entries = readdirSync(root, { withFileTypes: true }); } catch (error) {
+      report.errors.push(`${kind}:scan: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const candidates: Array<{ path: string; mtimeMs: number; size: number; ageMs: number }> = [];
+    for (const entry of entries) {
+      if (remainingScan <= 0) {
+        report.budgetExhausted = true;
+        increment(report.skippedByReason, 'scan_budget_exhausted');
+        break;
+      }
+      remainingScan -= 1;
+      report.inspected += 1;
+      classReport.inspected += 1;
+      const path = join(root, String(entry.name));
+      try {
+        const stat = lstatSync(path);
+        if (!entry.isFile() || !stat.isFile() || stat.isSymbolicLink() || !pathInside(root, path)) {
+          increment(report.skippedByReason, 'ownership_unproven');
+          classReport.blockers.push(`ownership_unproven:${String(entry.name)}`);
+          continue;
+        }
+        const size = Math.max(0, stat.size);
+        candidates.push({ path, mtimeMs: stat.mtimeMs, size, ageMs: Math.max(0, nowMs - stat.mtimeMs) });
+        classReport.totalBytesBefore += size;
+      } catch (error) {
+        report.errors.push(`${kind}:${String(entry.name)}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    candidates.sort((left, right) => left.mtimeMs - right.mtimeMs || left.path.localeCompare(right.path));
+    let projectedCount = candidates.length;
+    let projectedBytes = classReport.totalBytesBefore;
+    for (const candidate of candidates) {
+      const ttlExpired = candidate.ageMs >= graceMs;
+      const countPressure = projectedCount > maxCount;
+      const bytePressure = projectedBytes > maxBytes;
+      if (!ttlExpired && !countPressure && !bytePressure) continue;
+      if (candidate.ageMs < activeGraceMs) {
+        increment(report.skippedByReason, 'active_grace');
+        classReport.blockers.push(`active_grace:${basename(candidate.path)}`);
+        continue;
+      }
+      classReport.eligible += 1;
+      if (remainingRemovals <= 0) {
+        report.budgetExhausted = true;
+        increment(report.skippedByReason, 'cleanup_budget_exhausted');
+        continue;
+      }
+      try {
+        rmSync(candidate.path, { force: true });
+        remainingRemovals -= 1;
+        projectedCount -= 1;
+        projectedBytes = Math.max(0, projectedBytes - candidate.size);
+        classReport.removedCount += 1;
+        classReport.removedBytes += candidate.size;
+        report.removedBytes += candidate.size;
+        report.removedPaths.push(relative(browserRoot, candidate.path).replace(/\\/g, '/'));
+      } catch (error) {
+        report.errors.push(`${kind}:${basename(candidate.path)}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    classReport.retainedCount = projectedCount;
+    classReport.totalBytesAfter = projectedBytes;
+    classReport.overCapacity = projectedCount > maxCount || projectedBytes > maxBytes;
+    if (classReport.overCapacity) classReport.blockers.push('capacity_remains_above_limit');
+  }
+
+  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

package/src/runtime/control-plane/global-scheduler/durable-admission.ts

@@ -3,9 +3,19 @@ import {
   markExecutionJobSchedulerObserved,
 } from '../../execution/jobs/store';
 import { tickSchedules } from '../../workflow/schedules/engine';
+import type { ExecutionJob } from '../../execution/jobs/types';
 
 const SCHEDULE_TICK_INTERVAL_MS = 30_000;
 
+export function schedulerDurableAdmissionRequiresPolicy(input: {
+  activeJobs: readonly ExecutionJob[];
+  nowMs: number;
+  lastScheduleTickAt: number;
+}): boolean {
+  return input.activeJobs.length > 0
+    || input.nowMs - input.lastScheduleTickAt >= SCHEDULE_TICK_INTERVAL_MS;
+}
+
 export interface SchedulerDurableAdmissionDependencies {
   listActiveJobs: typeof listActiveExecutionJobs;
   markSchedulerObserved: typeof markExecutionJobSchedulerObserved;
@@ -23,13 +33,14 @@ export async function runSchedulerDurableAdmission(input: {
   repositoryIds: readonly string[];
   nowMs: number;
   lastScheduleTickAt: number;
+  activeJobs?: readonly ExecutionJob[];
 }, dependencies: SchedulerDurableAdmissionDependencies = DEFAULT_DEPENDENCIES): Promise<{
   scheduleTicked: boolean;
 }> {
   // Observation closes the admission phase for durable Jobs and starts their
   // independent queue budget. Each Job owns its own atomic state transition,
   // so this intentionally remains outside the global dispatch reservation lock.
-  for (const job of dependencies.listActiveJobs(input.controllerHome)) {
+  for (const job of input.activeJobs ?? dependencies.listActiveJobs(input.controllerHome)) {
     if (job.status === 'running' || job.timings?.schedulerObservedAt) continue;
     try {
       dependencies.markSchedulerObserved(input.controllerHome, job.repoId, job.jobId);