@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/recovery/quarantine-retention.ts

@@ -0,0 +1,256 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { assertStorageHeadroom } from '../shared/storage-capacity';
+import { measureReclaimablePath } from '../control-plane/lifecycle-retention-metrics';
+
+export const RUNTIME_QUARANTINE_RETENTION_POLICY_VERSION = 'runtime-quarantine-retention-v1';
+export const DEFAULT_RUNTIME_QUARANTINE_RETENTION_MS = 30 * 24 * 60 * 60_000;
+export const DEFAULT_RUNTIME_QUARANTINE_MAX_ENTRIES = 200;
+export const DEFAULT_RUNTIME_QUARANTINE_MAX_BYTES = 256 * 1024 * 1024;
+const DEFAULT_RUNTIME_QUARANTINE_SCAN_BUDGET = 1_000;
+const DEFAULT_RUNTIME_QUARANTINE_REMOVAL_BUDGET = 50;
+
+export interface RuntimeQuarantineRetentionOptions {
+  nowMs?: number;
+  retentionMs?: number;
+  maxRetainedEntries?: number;
+  maxRetainedBytes?: number;
+  maxEntries?: number;
+  maxRemovals?: number;
+  /** Additional Controller-Home quarantine namespaces sharing this GC budget. */
+  additionalRoots?: readonly string[];
+}
+
+export interface RuntimeQuarantineRetentionReport {
+  schemaVersion: 1;
+  policyVersion: typeof RUNTIME_QUARANTINE_RETENTION_POLICY_VERSION;
+  root: string;
+  roots: string[];
+  inspected: number;
+  migratedLegacyCount: number;
+  eligible: number;
+  removedCount: number;
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  retained: number;
+  protectedActiveCount: 0;
+  blockerReasons: Record<string, number>;
+  errors: string[];
+  budgetExhausted: boolean;
+}
+
+export function runtimeQuarantineRoot(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'quarantine', 'local-jobs');
+}
+
+export function runtimeLegacyCheckQuarantineRoot(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'quarantine', 'legacy-checks');
+}
+
+export function runtimeQuarantinePath(controllerHome: string, repoId: string, id: string, at = new Date()): string {
+  const safeId = id.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 120) || 'unknown';
+  const stamp = at.toISOString().replace(/[:.]/g, '-');
+  return join(runtimeQuarantineRoot(controllerHome, repoId), `${stamp}-${safeId}`);
+}
+
+function legacyQuarantineRoots(repoRoot: string): string[] {
+  return [
+    join(repoRoot, '.ai', 'harness', 'local-jobs-quarantine'),
+    join(repoRoot, '.ai', 'harness', 'quarantine', 'local-jobs'),
+  ];
+}
+
+function nextAvailablePath(root: string, name: string): string {
+  const base = join(root, name);
+  if (!existsSync(base)) return base;
+  for (let index = 1; index <= 1_000; index += 1) {
+    const candidate = join(root, `${name}-${index}`);
+    if (!existsSync(candidate)) return candidate;
+  }
+  throw new Error(`RUNTIME_QUARANTINE_DESTINATION_EXHAUSTED: ${name}`);
+}
+
+function movePreservingEvidence(source: string, destination: string): void {
+  mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+  try {
+    renameSync(source, destination);
+    return;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EXDEV') throw error;
+  }
+  const measurement = measureReclaimablePath(source);
+  assertStorageHeadroom(destination, {
+    operation: 'runtime_quarantine_cross_device_relocation',
+    requiredBytes: measurement.complete ? measurement.bytes : undefined,
+    reserveBytes: 16 * 1024 * 1024,
+  });
+  cpSync(source, destination, {
+    recursive: true,
+    dereference: false,
+    preserveTimestamps: true,
+    force: false,
+    errorOnExist: true,
+  });
+  rmSync(source, { recursive: true, force: true });
+}
+
+
+export function quarantineRuntimePath(controllerHome: string, repoId: string, source: string, id: string): string {
+  const root = runtimeQuarantineRoot(controllerHome, repoId);
+  const proposed = runtimeQuarantinePath(controllerHome, repoId, id);
+  const destination = nextAvailablePath(root, basename(proposed));
+  movePreservingEvidence(source, destination);
+  return destination;
+}
+
+function removeEmptyLegacyRoot(root: string): void {
+  if (!existsSync(root)) return;
+  try {
+    if (readdirSync(root).length === 0) rmSync(root, { recursive: true, force: true });
+  } catch {
+    // A concurrent writer or unreadable legacy directory is preserved fail-closed.
+  }
+}
+
+export function cleanupRuntimeQuarantine(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  options: RuntimeQuarantineRetentionOptions = {},
+): RuntimeQuarantineRetentionReport {
+  const nowMs = options.nowMs ?? Date.now();
+  const retentionMs = Math.max(60_000, Math.floor(options.retentionMs ?? DEFAULT_RUNTIME_QUARANTINE_RETENTION_MS));
+  const maxRetainedEntries = Math.max(1, Math.floor(options.maxRetainedEntries ?? DEFAULT_RUNTIME_QUARANTINE_MAX_ENTRIES));
+  const maxRetainedBytes = Math.max(1, Math.floor(options.maxRetainedBytes ?? DEFAULT_RUNTIME_QUARANTINE_MAX_BYTES));
+  const maxEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_RUNTIME_QUARANTINE_SCAN_BUDGET));
+  let remainingRemovals = Math.max(1, Math.floor(options.maxRemovals ?? DEFAULT_RUNTIME_QUARANTINE_REMOVAL_BUDGET));
+  const root = runtimeQuarantineRoot(controllerHome, repoId);
+  const roots = [...new Set([root, ...(options.additionalRoots ?? [])])];
+  const report: RuntimeQuarantineRetentionReport = {
+    schemaVersion: 1,
+    policyVersion: RUNTIME_QUARANTINE_RETENTION_POLICY_VERSION,
+    root,
+    roots,
+    inspected: 0,
+    migratedLegacyCount: 0,
+    eligible: 0,
+    removedCount: 0,
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+    retained: 0,
+    protectedActiveCount: 0,
+    blockerReasons: {},
+    errors: [],
+    budgetExhausted: false,
+  };
+  const block = (reason: string): void => { report.blockerReasons[reason] = (report.blockerReasons[reason] ?? 0) + 1; };
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+
+  let migrationBudget = maxEntries;
+  for (const legacyRoot of legacyQuarantineRoots(repoRoot)) {
+    if (!existsSync(legacyRoot)) continue;
+    try {
+      const legacyStat = lstatSync(legacyRoot);
+      if (!legacyStat.isDirectory() || legacyStat.isSymbolicLink()) {
+        if (migrationBudget <= 0) {
+          report.budgetExhausted = true;
+          block('legacy_migration_scan_budget_exhausted');
+          continue;
+        }
+        migrationBudget -= 1;
+        movePreservingEvidence(legacyRoot, nextAvailablePath(root, `legacy-root-${basename(legacyRoot)}`));
+        report.migratedLegacyCount += 1;
+        continue;
+      }
+    } catch (error) {
+      report.errors.push(`legacy quarantine inspect ${legacyRoot}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    let entries;
+    try {
+      entries = readdirSync(legacyRoot, { withFileTypes: true });
+    } catch (error) {
+      report.errors.push(`legacy quarantine read ${legacyRoot}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    for (const entry of entries) {
+      if (migrationBudget <= 0) {
+        report.budgetExhausted = true;
+        block('legacy_migration_scan_budget_exhausted');
+        break;
+      }
+      migrationBudget -= 1;
+      const source = join(legacyRoot, entry.name);
+      try {
+        movePreservingEvidence(source, nextAvailablePath(root, `legacy-${entry.name}`));
+        report.migratedLegacyCount += 1;
+      } catch (error) {
+        report.errors.push(`legacy quarantine migrate ${source}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    removeEmptyLegacyRoot(legacyRoot);
+  }
+
+  const entries: Array<{ name: string; path: string; mtimeMs: number }> = [];
+  for (const currentRoot of roots) {
+    if (currentRoot !== root && !existsSync(currentRoot)) continue;
+    try {
+      for (const entry of readdirSync(currentRoot, { withFileTypes: true })) {
+        const path = join(currentRoot, entry.name);
+        let mtimeMs = nowMs;
+        try { mtimeMs = lstatSync(path).mtimeMs; } catch { /* concurrent removal is handled during the scan */ }
+        entries.push({ name: `${basename(currentRoot)}:${entry.name}`, path, mtimeMs });
+      }
+    } catch (error) {
+      report.errors.push(`quarantine root read ${currentRoot}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  entries.sort((left, right) => right.mtimeMs - left.mtimeMs || left.name.localeCompare(right.name));
+
+  let retainedBytes = 0;
+  const scanned = entries.slice(0, maxEntries);
+  if (entries.length > scanned.length) {
+    report.budgetExhausted = true;
+    block('scan_budget_exhausted');
+  }
+  for (let index = 0; index < scanned.length; index += 1) {
+    const entry = scanned[index];
+    report.inspected += 1;
+    let stat;
+    try {
+      stat = lstatSync(entry.path);
+    } catch {
+      block('entry_disappeared');
+      continue;
+    }
+    const measurement = measureReclaimablePath(entry.path);
+    const expired = nowMs - stat.mtimeMs > retentionMs;
+    const overCount = index >= maxRetainedEntries;
+    const overBytes = measurement.complete && retainedBytes + measurement.bytes > maxRetainedBytes;
+    const eligible = expired || overCount || overBytes;
+    if (!eligible) {
+      report.retained += 1;
+      if (measurement.complete) retainedBytes += measurement.bytes;
+      else block('retained_size_unknown');
+      continue;
+    }
+    report.eligible += 1;
+    if (remainingRemovals <= 0) {
+      report.budgetExhausted = true;
+      block('removal_budget_exhausted');
+      report.retained += 1;
+      continue;
+    }
+    try {
+      remainingRemovals -= 1;
+      rmSync(entry.path, { recursive: true, force: true });
+      report.removedCount += 1;
+      if (measurement.complete) report.reclaimedBytes += measurement.bytes;
+      else report.unknownReclaimedByteCount += 1;
+    } catch (error) {
+      report.errors.push(`quarantine remove ${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return report;
+}

package/src/runtime/release/identity.ts

@@ -8,6 +8,7 @@ export interface ReleaseIdentityBinding {
   releaseId?: string;
   releaseRevision?: string;
   sourceCommit?: string;
+  sourceRepositoryId?: string;
   cleanWorkspace: boolean;
 }
 
@@ -15,6 +16,7 @@ interface ReleaseManifestIdentity {
   releaseId?: string;
   releaseRevision?: string;
   sourceCommit?: string;
+  sourceRepositoryId?: string;
   cleanWorkspace?: boolean;
 }
 
@@ -31,6 +33,7 @@ function readManifest(releasePath: string): ReleaseManifestIdentity | undefined
       releaseId: text(manifest.releaseId),
       releaseRevision: text(manifest.releaseRevision),
       sourceCommit: text(manifest.sourceCommit),
+      sourceRepositoryId: text(manifest.sourceRepositoryId),
       cleanWorkspace: typeof manifest.cleanWorkspace === 'boolean' ? manifest.cleanWorkspace : undefined,
     };
   } catch {
@@ -48,6 +51,7 @@ export function readReleaseIdentityBindingFromEnv(env: NodeJS.ProcessEnv = proce
     releaseId: env.FORGE_RELEASE_ID?.trim() || manifest?.releaseId,
     releaseRevision: env.FORGE_RELEASE_REVISION?.trim() || manifest?.releaseRevision || env.FORGE_RELEASE_ID?.trim(),
     sourceCommit: env.FORGE_RELEASE_SOURCE_COMMIT?.trim() || manifest?.sourceCommit,
+    sourceRepositoryId: manifest?.sourceRepositoryId,
     cleanWorkspace: env.FORGE_RELEASE_CLEAN_WORKSPACE
       ? env.FORGE_RELEASE_CLEAN_WORKSPACE !== 'false'
       : manifest?.cleanWorkspace !== false,
@@ -65,6 +69,7 @@ export function resolveManagedRuntimeSourceIdentity(options: {
   branch: null;
   commit?: string;
   releaseRevision?: string;
+  sourceRepositoryId?: string;
   defaultBranch: string;
   defaultBranchCommit?: string;
   dirty: boolean;
@@ -93,6 +98,7 @@ export function resolveManagedRuntimeSourceIdentity(options: {
     branch: null,
     commit: binding.sourceCommit,
     releaseRevision: binding.releaseRevision,
+    ...(binding.sourceRepositoryId ? { sourceRepositoryId: binding.sourceRepositoryId } : {}),
     defaultBranch: 'main',
     defaultBranchCommit: binding.sourceCommit,
     dirty: !binding.cleanWorkspace,

package/src/runtime/resources/leases/store.ts

@@ -142,7 +142,7 @@ export function resetLeaseSideEffectMetrics(): void {
 export function listActiveLeases(controllerHome: string, repoId: string): ExecutionLease[] {
   try {
     const leases: ExecutionLease[] = [];
-    for (const name of readdirSync(activeRoot(controllerHome, repoId)).filter((entry) => entry.endsWith('.json')).slice(0, 5000)) {
+    for (const name of readdirSync(activeRoot(controllerHome, repoId)).filter((entry) => entry.endsWith('.json'))) {
       const path = join(activeRoot(controllerHome, repoId), name);
       try {
         const lease = readJsonFile<ExecutionLease>(path);

package/src/runtime/root/active-execution-power-assertion.ts

@@ -0,0 +1,139 @@
+import { spawn, type ChildProcess } from 'child_process';
+import { listActiveExecutionJobs } from '../execution/jobs/store';
+import { hasActiveLightweightProcesses } from '../execution/process-runtime/lightweight-managed';
+
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_IDLE_GRACE_MS = 5 * 60_000;
+const CAFFEINATE_TIMEOUT_SECONDS = 10 * 60;
+
+export interface RuntimePowerAssertionHandle {
+  refresh(): void;
+  stop(): void;
+  isHeld(): boolean;
+}
+
+export interface RuntimePowerAssertionInput {
+  controllerHome: string;
+  runtimePid: number;
+  pollIntervalMs?: number;
+  idleGraceMs?: number;
+}
+
+interface RuntimePowerAssertionDependencies {
+  platform?: NodeJS.Platform;
+  now?: () => number;
+  hasActiveExecution?: (controllerHome: string) => boolean;
+  spawnAssertion?: (runtimePid: number) => ChildProcess;
+  setIntervalFn?: typeof setInterval;
+  clearIntervalFn?: typeof clearInterval;
+}
+
+function controllerHasActiveExecution(controllerHome: string): boolean {
+  return hasActiveLightweightProcesses(controllerHome)
+    || listActiveExecutionJobs(controllerHome).length > 0;
+}
+
+function spawnMacOsCaffeinate(runtimePid: number): ChildProcess {
+  return spawn('/usr/bin/caffeinate', [
+    '-d',
+    '-i',
+    '-u',
+    '-t', String(CAFFEINATE_TIMEOUT_SECONDS),
+    '-w', String(runtimePid),
+  ], {
+    stdio: 'ignore',
+  });
+}
+
+function noOpHandle(): RuntimePowerAssertionHandle {
+  return {
+    refresh: () => undefined,
+    stop: () => undefined,
+    isHeld: () => false,
+  };
+}
+
+/**
+ * macOS idle-sleep/display-lock guard owned by the Canonical Runtime process.
+ *
+ * The assertion is deliberately non-durable: it is acquired only while Forge
+ * has active execution and is released after a short idle grace. `caffeinate`
+ * is additionally fenced to the Runtime PID and bounded by its own timeout, so
+ * a Runtime crash cannot leave an indefinite host-wide assertion behind.
+ */
+export function startActiveExecutionPowerAssertion(
+  input: RuntimePowerAssertionInput,
+  dependencies: RuntimePowerAssertionDependencies = {},
+): RuntimePowerAssertionHandle {
+  if ((dependencies.platform ?? process.platform) !== 'darwin') return noOpHandle();
+
+  const pollIntervalMs = Math.max(500, Math.min(Math.trunc(input.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS), 30_000));
+  const idleGraceMs = Math.max(5_000, Math.min(Math.trunc(input.idleGraceMs ?? DEFAULT_IDLE_GRACE_MS), 30 * 60_000));
+  const now = dependencies.now ?? Date.now;
+  const hasActiveExecution = dependencies.hasActiveExecution ?? controllerHasActiveExecution;
+  const spawnAssertion = dependencies.spawnAssertion ?? spawnMacOsCaffeinate;
+  const setIntervalFn = dependencies.setIntervalFn ?? setInterval;
+  const clearIntervalFn = dependencies.clearIntervalFn ?? clearInterval;
+
+  let assertion: ChildProcess | undefined;
+  let lastActiveAt: number | undefined;
+  let stopped = false;
+
+  const releaseAssertion = () => {
+    const current = assertion;
+    assertion = undefined;
+    if (!current) return;
+    try { current.kill('SIGTERM'); } catch { /* assertion cleanup is best effort */ }
+  };
+
+  const ensureAssertion = () => {
+    if (assertion || stopped) return;
+    try {
+      const next = spawnAssertion(input.runtimePid);
+      assertion = next;
+      const clear = () => {
+        if (assertion === next) assertion = undefined;
+      };
+      next.once('exit', clear);
+      next.once('error', clear);
+    } catch {
+      // Host power-management support is best-effort. Runtime execution must
+      // continue even when caffeinate is absent or temporarily unavailable.
+    }
+  };
+
+  const refresh = () => {
+    if (stopped) return;
+    let active: boolean;
+    try {
+      active = hasActiveExecution(input.controllerHome);
+    } catch {
+      // Ambiguous activity must never release a currently-held assertion.
+      return;
+    }
+    const observedAt = now();
+    if (active) {
+      lastActiveAt = observedAt;
+      ensureAssertion();
+      return;
+    }
+    if (assertion && lastActiveAt !== undefined && observedAt - lastActiveAt >= idleGraceMs) {
+      releaseAssertion();
+    }
+  };
+
+  refresh();
+  const timer = setIntervalFn(refresh, pollIntervalMs);
+  timer.unref?.();
+
+  return {
+    refresh,
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      clearIntervalFn(timer);
+      releaseAssertion();
+    },
+    isHeld: () => assertion !== undefined,
+  };
+}

package/src/runtime/root/assistant-learning-loop.ts

@@ -0,0 +1,45 @@
+import { createHash } from 'crypto';
+import type { WorkflowJsonValue, WorkflowPublicationReceipt } from '../../../packages/workflow-runtime/api/index';
+import { createWorkContinuationSchedule } from '../workflow/schedules/work-continuation';
+
+const DAY_MS = 86_400_000;
+
+/** External-observation orchestration only. Semantic Memory writes live in the context adapter. */
+export function schedulePublicationOutcomeCollection(input: {
+  controllerHome: string;
+  repoId: string;
+  workId: string;
+  publication: WorkflowPublicationReceipt;
+  workflowInputs?: Record<string, WorkflowJsonValue>;
+}) {
+  const publishedAtMs = Date.parse(input.publication.publishedAt);
+  if (!Number.isFinite(publishedAtMs)) throw new Error('OUTCOME_COLLECTION_PUBLICATION_TIME_INVALID');
+  const browserSessionId = typeof input.workflowInputs?.session_id === 'string' ? input.workflowInputs.session_id.trim() : '';
+  if (!browserSessionId) throw new Error('OUTCOME_COLLECTION_BROWSER_SESSION_REQUIRED');
+  const dueAt = new Date(publishedAtMs + DAY_MS).toISOString();
+  const semanticId = createHash('sha256').update(JSON.stringify([
+    input.repoId, input.workId, input.publication.receiptId, input.publication.postId, input.publication.postUrl, dueAt,
+  ])).digest('hex').slice(0, 24);
+  const continuationPrompt = [
+    `Publication outcome observation is due for receipt ${input.publication.receiptId}.`,
+    `Use the same Work lineage. Execute the versioned metrics Workflow for channel=${input.publication.channel}, account=${input.publication.account}, post_id=${input.publication.postId}, post_url=${input.publication.postUrl}.`,
+    'Then record an evidence-backed OutcomeObservation through rh_work outcome_record. Never infer or zero-fill a metric that the real page contract did not observe.',
+    'If real metrics exist, the Controller may record a bounded Experience and must allow the next ControllerRound to classify that recalled experience as used or rejected with a reason.',
+  ].join(' ');
+  return createWorkContinuationSchedule(input.controllerHome, input.repoId, {
+    workId: input.workId,
+    scheduleMode: 'browser_watch',
+    controllerType: 'chatgpt',
+    probeUrl: input.publication.postUrl,
+    probeBrowserSessionId: browserSessionId,
+    wakeOnFirstObservation: true,
+    wakeOnAuthRequired: true,
+    continuationPrompt,
+    scheduleName: `Observe publication ${input.publication.postId} after 24h`,
+    requestId: `publication-outcome:${semanticId}`,
+    triggerType: 'calendar',
+    calendarAt: dueAt,
+    catchUpMinutes: 24 * 60,
+    stopConditions: ['work_terminal', 'human_review_required', 'external_blocker'],
+  }).schedule;
+}

package/src/runtime/root/browser-session-composition.ts

@@ -0,0 +1,59 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type {
+  BrowserSessionAuthorityContext,
+  BrowserSessionExecutionContext,
+  BrowserSessionLegacyCutoverRepository,
+  BrowserSessionLegacyCutoverReport,
+  BrowserSessionTombstoneCleanupReport,
+} from '../../../packages/plugin-runtime/browser/session-authority';
+
+const browserSessionExecutionContext = new AsyncLocalStorage<BrowserSessionExecutionContext>();
+
+export function withRuntimeBrowserSessionExecutionContext<T>(
+  context: BrowserSessionExecutionContext,
+  operation: () => T,
+): T {
+  return browserSessionExecutionContext.run(context, operation);
+}
+
+export function currentRuntimeBrowserSessionExecutionContext(): BrowserSessionExecutionContext | undefined {
+  return browserSessionExecutionContext.getStore();
+}
+
+/** @deprecated Frozen-call compatibility alias. No Browser authority is constructed here. */
+export function withRuntimeBrowserSessionAuthorityContext<T>(
+  context: BrowserSessionAuthorityContext,
+  operation: () => T,
+): T {
+  return withRuntimeBrowserSessionExecutionContext(context, operation);
+}
+
+/** @deprecated Frozen-call compatibility alias. This returns execution scope only. */
+export function currentRuntimeBrowserSessionAuthorityContext(): BrowserSessionAuthorityContext | undefined {
+  return currentRuntimeBrowserSessionExecutionContext();
+}
+
+/** @deprecated Browser no longer owns legacy-import cutover state; Computer per-repository migration markers are authoritative. */
+export function closeRuntimeBrowserSessionLegacyImportCutover(
+  _controllerHome: string,
+  repositories: readonly BrowserSessionLegacyCutoverRepository[],
+): BrowserSessionLegacyCutoverReport {
+  return { closed: true, alreadyClosed: true, repositoryCount: repositories.length, migratedRecordCount: 0 };
+}
+
+/** @deprecated Browser no longer owns tombstone retention; scheduler separately invokes Computer target cleanup. */
+export function cleanupRuntimeBrowserSessionTombstones(
+  _controllerHome: string,
+  _options?: { nowMs?: number; ttlMs?: number; maxTombstones?: number; maxRemovals?: number },
+): BrowserSessionTombstoneCleanupReport {
+  return {
+    policyVersion: 'browser-session-tombstone-retention-v1',
+    cutoverClosed: true,
+    inspected: 0,
+    eligible: 0,
+    removed: 0,
+    retained: 0,
+    blockers: [],
+    budgetExhausted: false,
+  };
+}