@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/diagnostics/incident-repair.ts

@@ -0,0 +1,406 @@
+import { createHash } from 'crypto';
+import { closeSync, existsSync, openSync, readSync, realpathSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { spawnSync } from 'child_process';
+import { listRepositories, selectRepositoryCheckout } from '../../cli/repositories/registry';
+import { withControllerLock } from '../../cli/repositories/locks';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import { loadRuntimeReleaseManifest } from '../root/release-manifest';
+import { appendWorkEvidence, getWorkContract, listWorkContracts } from '../../../packages/kernel/work/api/index';
+import { routeWorkStart } from '../control-plane/facade/goal-workloop';
+import { createWorkContinuationSchedule } from '../workflow/schedules/work-continuation';
+import { touchSchedulerWakeSignal } from '../control-plane/global-scheduler/wake-signal';
+import { recentMcpIncidents, type McpIncident } from './mcp-timing';
+
+const RECURRENCE_WINDOW_MS = 30 * 60_000;
+const RECURRENCE_THRESHOLD = 3;
+const INCIDENT_TAIL_BYTES = 256 * 1024;
+const INCIDENT_WORK_PREFIX = 'forge-incident-repair';
+const TERMINAL_WORK_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+
+export interface ForgeIncidentRepairClassification {
+  eligible: boolean;
+  rootCode?: string;
+  fingerprint?: string;
+  reason: string;
+}
+
+export interface ForgeIncidentRepairRegistration {
+  eligible: boolean;
+  recurrent: boolean;
+  occurrenceCount: number;
+  fingerprint?: string;
+  rootCode?: string;
+  repairRepoId?: string;
+  workId?: string;
+  reusedExistingWork?: boolean;
+  scheduleId?: string;
+  reason: string;
+}
+
+interface PersistedMcpIncident extends McpIncident {
+  schemaVersion?: number;
+  at?: string;
+}
+
+function transportFailureMessage(message: string): boolean {
+  const transportFailure = /(?:ECONNREFUSED|ECONNRESET|EPIPE|socket hang up|connection failed|fetch failed|network error|timed? out|timeout)/i.test(message);
+  const forgeTransport = /(?:canonical runtime|runtime mcp|mcp transport|forge gateway|forge tunnel)/i.test(message);
+  return transportFailure && forgeTransport;
+}
+
+/**
+ * Conservative product-defect classifier. Expected policy, scope, admission,
+ * user-code acceptance, and ordinary contention failures are intentionally not
+ * auto-promoted into Forge source Work.
+ */
+export function classifyForgeIncidentForRepair(incident: McpIncident): ForgeIncidentRepairClassification {
+  const code = incident.code.trim().toUpperCase();
+  if (!code) return { eligible: false, reason: 'incident code is empty' };
+
+  const rootCode = (() => {
+    if (code === 'MCP_REQUEST_EXCEPTION' && transportFailureMessage(incident.message)) return 'MCP_TRANSPORT_UNAVAILABLE';
+    if (code === 'CONTROLLER_AUTHENTICATED_SESSION_REQUIRED') return code;
+    if (code === 'WORK_CONTROLLER_SCOPE_MISMATCH') return code;
+    if (code.startsWith('CANONICAL_RUNTIME_')) return code;
+    if (code.startsWith('RECOVERY_')) return code;
+    if (code.startsWith('CONTROLLER_RELAY_')) return code;
+    if (code.startsWith('PROCESS_RUNTIME_')) return code;
+    if (/^PLUGIN_[A-Z0-9_]+_(?:UNAVAILABLE|MISSING|MISMATCH)$/.test(code)) return code;
+    if (/^RUNTIME_(?:SERVICE|RELEASE|OWNER|WRITE|PROCESS|GATEWAY)_[A-Z0-9_]+$/.test(code)) return code;
+    return undefined;
+  })();
+  if (!rootCode) return { eligible: false, reason: `expected/non-product incident class ${code}` };
+
+  const fingerprint = createHash('sha256').update(`forge-infrastructure:${rootCode}`).digest('hex').slice(0, 24);
+  return { eligible: true, rootCode, fingerprint, reason: `eligible Forge infrastructure root ${rootCode}` };
+}
+
+function incidentAuditPath(controllerHome: string): string {
+  return join(resolve(controllerHome), 'audit', 'mcp-incidents.jsonl');
+}
+
+function readBoundedIncidentTail(controllerHome: string): PersistedMcpIncident[] {
+  const path = incidentAuditPath(controllerHome);
+  if (!existsSync(path)) return [];
+  let fd: number | undefined;
+  try {
+    const size = statSync(path).size;
+    const length = Math.min(size, INCIDENT_TAIL_BYTES);
+    const start = Math.max(0, size - length);
+    const buffer = Buffer.alloc(length);
+    fd = openSync(path, 'r');
+    const read = readSync(fd, buffer, 0, length, start);
+    let text = buffer.subarray(0, read).toString('utf8');
+    if (start > 0) {
+      const newline = text.indexOf('\n');
+      text = newline >= 0 ? text.slice(newline + 1) : '';
+    }
+    return text.split(/\r?\n/).filter(Boolean).flatMap((line) => {
+      try {
+        const parsed = JSON.parse(line) as PersistedMcpIncident;
+        return parsed && typeof parsed === 'object' ? [parsed] : [];
+      } catch {
+        return [];
+      }
+    });
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function recentRootIncidents(
+  controllerHome: string,
+  classification: ForgeIncidentRepairClassification,
+  nowMs: number,
+): PersistedMcpIncident[] {
+  if (!classification.eligible || !classification.rootCode) return [];
+  const unique = new Map<string, PersistedMcpIncident>();
+  for (const candidate of [...readBoundedIncidentTail(controllerHome), ...recentMcpIncidents(controllerHome)]) {
+    const at = Date.parse(candidate.at ?? '');
+    if (!Number.isFinite(at) || at < nowMs - RECURRENCE_WINDOW_MS || at > nowMs + 60_000) continue;
+    if (classifyForgeIncidentForRepair(candidate).rootCode !== classification.rootCode) continue;
+    if (!candidate.traceId?.trim()) continue;
+    unique.set(candidate.traceId.trim(), candidate);
+  }
+  return [...unique.values()];
+}
+
+function gitContainsCommit(root: string, commit: string): boolean {
+  const exists = spawnSync('git', ['-C', root, 'cat-file', '-e', `${commit}^{commit}`], {
+    encoding: 'utf8', stdio: ['ignore', 'ignore', 'ignore'], timeout: 10_000,
+  });
+  if (exists.status !== 0) return false;
+  const ancestor = spawnSync('git', ['-C', root, 'merge-base', '--is-ancestor', commit, 'HEAD'], {
+    encoding: 'utf8', stdio: ['ignore', 'ignore', 'ignore'], timeout: 10_000,
+  });
+  return ancestor.status === 0;
+}
+
+function gitHead(root: string): string | undefined {
+  const result = spawnSync('git', ['-C', root, 'rev-parse', '--verify', 'HEAD'], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000,
+  });
+  const head = result.status === 0 ? result.stdout.trim() : '';
+  return /^[a-f0-9]{40}$/i.test(head) ? head : undefined;
+}
+
+function samePath(left: string, right: string): boolean {
+  try { return realpathSync(left) === realpathSync(right); } catch { return resolve(left) === resolve(right); }
+}
+
+/**
+ * Resolve the registered Forge source authority. A user/business repository
+ * affected by a Runtime defect is never treated as the repair repository.
+ * Source-mode Runtime uses exact checkout path identity; immutable/package mode
+ * must prove its release sourceCommit exists in exactly one enabled repo.
+ */
+export function resolveRuntimeSourceRepairRepository(
+  controllerHome: string,
+  runtimeSourceRoot: string | undefined,
+): RepositoryRecord | undefined {
+  const root = runtimeSourceRoot?.trim();
+  if (!root) return undefined;
+  const repositories = listRepositories(controllerHome).filter((repository) => repository.enabled && !repository.removedAt);
+  const exact = repositories.filter((repository) => repository.checkouts.some((checkout) => (
+    checkout.lifecycle !== 'removed' && samePath(checkout.canonicalRoot, root)
+  )));
+  if (exact.length === 1) return selectRepositoryCheckout(exact[0]!, exact[0]!.activeCheckoutId);
+  if (exact.length > 1) return undefined;
+
+  const manifestPath = join(resolve(root), 'manifest.json');
+  if (!existsSync(manifestPath)) return undefined;
+  let sourceCommit: string | undefined;
+  try {
+    sourceCommit = loadRuntimeReleaseManifest(manifestPath, controllerHome).sourceCommit;
+  } catch {
+    return undefined;
+  }
+  if (!sourceCommit || !/^[a-f0-9]{40}$/i.test(sourceCommit)) return undefined;
+  const containing = repositories.filter((repository) => {
+    const selected = selectRepositoryCheckout(repository, repository.activeCheckoutId);
+    return gitContainsCommit(selected.canonicalRoot, sourceCommit!);
+  });
+  if (containing.length !== 1) return undefined;
+  return selectRepositoryCheckout(containing[0]!, containing[0]!.activeCheckoutId);
+}
+
+function requestBase(fingerprint: string): string {
+  return `${INCIDENT_WORK_PREFIX}:${fingerprint}`;
+}
+
+function requestGeneration(requestId: string | undefined, base: string): number | undefined {
+  if (!requestId?.startsWith(`${base}:g`)) return undefined;
+  const value = Number.parseInt(requestId.slice(`${base}:g`.length), 10);
+  return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function incidentEvidence(incident: PersistedMcpIncident, rootCode: string, ordinal: number) {
+  return {
+    evidenceId: `MCPINC-${incident.traceId}`.slice(0, 160),
+    title: `recurrent Forge incident ${rootCode}`,
+    summary: [
+      `Occurrence ${ordinal} for ${rootCode}.`,
+      `tool=${incident.tool}`,
+      `trace=${incident.traceId}`,
+      ...(incident.repoId ? [`affectedRepo=${incident.repoId}`] : []),
+    ].join(' ').slice(0, 1_000),
+    detailLevel: 'summary' as const,
+  };
+}
+
+function ensureAutomaticContinuation(
+  controllerHome: string,
+  repoId: string,
+  workId: string,
+  rootCode: string,
+): string | undefined {
+  try {
+    const { schedule } = createWorkContinuationSchedule(controllerHome, repoId, {
+      workId,
+      scheduleMode: 'continuation',
+      controllerType: 'chatgpt',
+      scheduleName: `Repair recurrent Forge incident ${rootCode}`,
+      requestId: `incident-repair-continuation:${workId}`,
+      triggerType: 'interval',
+      everyMinutes: 5,
+      shadowMode: false,
+      maxFailures: 5,
+      cooldownMinutes: 15,
+      dailyBudgetMinutes: 180,
+      backoffBaseMinutes: 5,
+      backoffMaxMinutes: 60,
+      continuationPrompt: `Continue automatically registered Forge repair Work ${workId}. Reproduce root incident ${rootCode}, deduplicate against current source/lifecycle evidence, repair the canonical root cause in Forge source, verify, and finalize. Do not bypass Runtime/Recovery/Controller authority.`,
+      stopConditions: ['work_terminal', 'human_review_required', 'external_blocker'],
+    });
+    touchSchedulerWakeSignal(controllerHome, `automatic incident repair schedule ${schedule.scheduleId} for ${workId}`);
+    return schedule.scheduleId;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Promote only recurrent, source-authority-proven Forge infrastructure incidents
+ * into canonical primary Work. The JSONL incident log remains evidence only;
+ * WorkContract + existing continuation Schedule are the sole durable authorities.
+ */
+export function maybeRegisterMcpIncidentRepair(input: {
+  controllerHome: string;
+  runtimeSourceRoot?: string;
+  incident: McpIncident;
+  now?: () => number;
+}): ForgeIncidentRepairRegistration {
+  const classification = classifyForgeIncidentForRepair(input.incident);
+  if (!classification.eligible || !classification.fingerprint || !classification.rootCode) {
+    return { eligible: false, recurrent: false, occurrenceCount: 0, reason: classification.reason };
+  }
+  const nowMs = input.now?.() ?? Date.now();
+  const occurrences = recentRootIncidents(input.controllerHome, classification, nowMs);
+  if (occurrences.length < RECURRENCE_THRESHOLD) {
+    return {
+      eligible: true,
+      recurrent: false,
+      occurrenceCount: occurrences.length,
+      fingerprint: classification.fingerprint,
+      rootCode: classification.rootCode,
+      reason: `waiting for ${RECURRENCE_THRESHOLD} occurrences within ${RECURRENCE_WINDOW_MS / 60_000} minutes`,
+    };
+  }
+
+  const repairRepository = resolveRuntimeSourceRepairRepository(input.controllerHome, input.runtimeSourceRoot);
+  if (!repairRepository) {
+    return {
+      eligible: true,
+      recurrent: true,
+      occurrenceCount: occurrences.length,
+      fingerprint: classification.fingerprint,
+      rootCode: classification.rootCode,
+      reason: 'runtime source authority could not be mapped unambiguously to one registered repository',
+    };
+  }
+
+  const base = requestBase(classification.fingerprint);
+  const lockResource = `incident-repair-${classification.fingerprint}`;
+  return withControllerLock(input.controllerHome, { scope: 'global', resource: lockResource }, lockResource, () => {
+    const store = { controllerHome: input.controllerHome, repoId: repairRepository.repoId };
+    const matching = listWorkContracts({ ...store, status: 'all', limit: 500 })
+      .filter((work) => requestGeneration(work.requestId, base) !== undefined)
+      .sort((left, right) => (requestGeneration(left.requestId, base) ?? 0) - (requestGeneration(right.requestId, base) ?? 0));
+    const active = [...matching].reverse().find((work) => !TERMINAL_WORK_STATUSES.has(work.status));
+    const recentEvidence = occurrences.slice(-RECURRENCE_THRESHOLD);
+    if (active) {
+      for (const [index, occurrence] of recentEvidence.entries()) {
+        if (active.evidenceRefs.some((entry) => entry.evidenceId === `MCPINC-${occurrence.traceId}`)) continue;
+        appendWorkEvidence(store, active.workId, incidentEvidence(occurrence, classification.rootCode!, occurrences.length - recentEvidence.length + index + 1));
+      }
+      const scheduleId = ensureAutomaticContinuation(input.controllerHome, repairRepository.repoId, active.workId, classification.rootCode!);
+      return {
+        eligible: true,
+        recurrent: true,
+        occurrenceCount: occurrences.length,
+        fingerprint: classification.fingerprint,
+        rootCode: classification.rootCode,
+        repairRepoId: repairRepository.repoId,
+        workId: active.workId,
+        reusedExistingWork: true,
+        scheduleId,
+        reason: 'reused active canonical incident-repair Work',
+      };
+    }
+
+    const predecessor = matching.at(-1);
+    const generation = (predecessor ? (requestGeneration(predecessor.requestId, base) ?? 0) : 0) + 1;
+    const requestId = `${base}:g${generation}`;
+    const head = gitHead(repairRepository.canonicalRoot);
+    if (!head) {
+      return {
+        eligible: true,
+        recurrent: true,
+        occurrenceCount: occurrences.length,
+        fingerprint: classification.fingerprint,
+        rootCode: classification.rootCode,
+        repairRepoId: repairRepository.repoId,
+        reason: 'repair repository HEAD could not be proven',
+      };
+    }
+    const routed = routeWorkStart({
+      workStore: store,
+      handoffStore: store,
+      repoId: repairRepository.repoId,
+      sourceRevision: head,
+      checkoutId: repairRepository.activeCheckoutId,
+    }, {
+      objective: `Repair recurrent Forge infrastructure incident ${classification.rootCode} automatically registered after ${occurrences.length} occurrences within ${RECURRENCE_WINDOW_MS / 60_000} minutes.`,
+      acceptanceCriteria: [
+        `Reproduce and eliminate root incident ${classification.rootCode} without bypassing canonical Runtime/Recovery/Controller authority.`,
+        'Preserve fail-closed behavior for expected policy, ownership, user-code, and approval failures.',
+        'Run focused affected checks and live verification before terminalizing the Work.',
+      ],
+      allowedPaths: ['src/**', 'tests/**', 'scripts/**', 'package.json'],
+      initialLikelyPaths: [],
+      forbiddenPaths: ['node_modules/**', '_ops/**'],
+      constraints: { workspaceMode: 'auto', requireHandoffOnAmbiguity: true },
+      modeInput: {
+        scopeClear: false,
+        mutation: true,
+        requiresInvestigation: true,
+        requiresRecovery: true,
+        risk: 'workspace_write',
+      },
+      requestedBy: 'system',
+      requestId,
+      relatedWorkId: predecessor?.workId,
+      workRelation: 'new_goal',
+      workKind: 'repository_change',
+    });
+    if (routed.status !== 'ok') {
+      return {
+        eligible: true,
+        recurrent: true,
+        occurrenceCount: occurrences.length,
+        fingerprint: classification.fingerprint,
+        rootCode: classification.rootCode,
+        repairRepoId: repairRepository.repoId,
+        reason: `canonical Work admission did not create repair Work: ${routed.summary}`,
+      };
+    }
+    const created = listWorkContracts({ ...store, status: 'all', limit: 500 }).find((work) => work.requestId === requestId);
+    if (!created) {
+      return {
+        eligible: true,
+        recurrent: true,
+        occurrenceCount: occurrences.length,
+        fingerprint: classification.fingerprint,
+        rootCode: classification.rootCode,
+        repairRepoId: repairRepository.repoId,
+        reason: 'canonical Work admission succeeded without a request-bound readable Work',
+      };
+    }
+    if (predecessor) {
+      appendWorkEvidence(store, created.workId, {
+        title: 'incident repair predecessor',
+        summary: `Recurrent root ${classification.rootCode} created successor generation ${generation} after terminal Work ${predecessor.workId} (${predecessor.status}).`,
+        detailLevel: 'summary',
+      });
+    }
+    for (const [index, occurrence] of recentEvidence.entries()) {
+      appendWorkEvidence(store, created.workId, incidentEvidence(occurrence, classification.rootCode!, occurrences.length - recentEvidence.length + index + 1));
+    }
+    const scheduleId = ensureAutomaticContinuation(input.controllerHome, repairRepository.repoId, created.workId, classification.rootCode!);
+    return {
+      eligible: true,
+      recurrent: true,
+      occurrenceCount: occurrences.length,
+      fingerprint: classification.fingerprint,
+      rootCode: classification.rootCode,
+      repairRepoId: repairRepository.repoId,
+      workId: created.workId,
+      reusedExistingWork: false,
+      scheduleId,
+      reason: 'created canonical recurrent-incident repair Work',
+    };
+  }, 10_000);
+}

package/src/runtime/diagnostics/mcp-timing.ts

@@ -1,6 +1,5 @@
-import { appendFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { ensureControllerHome } from '../../cli/repositories/controller-home';
+import { appendFile, mkdir, rename, rm, stat } from 'fs/promises';
+import { join, resolve } from 'path';
 
 export interface McpTimingTrace {
   tool: string;
@@ -56,10 +55,107 @@ export interface McpIncident {
   details?: Record<string, unknown>;
 }
 
+const MCP_DIAGNOSTIC_MAX_BYTES = 32 * 1024 * 1024;
+const MCP_DIAGNOSTIC_MAX_PENDING_ENTRIES = 4_096;
+const MCP_DIAGNOSTIC_MAX_BATCH_BYTES = 256 * 1024;
+const MCP_INCIDENT_MEMORY_WINDOW_LIMIT = 1_024;
+const MCP_INCIDENT_MEMORY_LEDGER_LIMIT = 64;
+
+interface PendingDiagnosticLedger {
+  readonly root: string;
+  readonly fileName: string;
+  pending: string[];
+  pendingBytes: number;
+  drain?: Promise<void>;
+}
+
+const diagnosticLedgers = new Map<string, PendingDiagnosticLedger>();
+const recentIncidents = new Map<string, Array<McpIncident & { at: string }>>();
+
+function ledgerFor(controllerHome: string, fileName: string): PendingDiagnosticLedger {
+  const root = join(resolve(controllerHome), 'audit');
+  const key = `${root}\0${fileName}`;
+  let ledger = diagnosticLedgers.get(key);
+  if (!ledger) {
+    ledger = { root, fileName, pending: [], pendingBytes: 0 };
+    diagnosticLedgers.set(key, ledger);
+  }
+  return ledger;
+}
+
+async function existingSize(path: string): Promise<number> {
+  try {
+    return (await stat(path)).size;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 0;
+    throw error;
+  }
+}
+
+async function rotateLedger(path: string): Promise<void> {
+  const previous = `${path}.previous`;
+  // This is diagnostic evidence, not a control-plane authority. Keep one bounded
+  // previous segment so a stalled disk cannot turn unbounded telemetry into MCP
+  // dispatch latency.
+  await rm(previous, { force: true });
+  await rename(path, previous);
+}
+
+async function drainLedger(ledger: PendingDiagnosticLedger): Promise<void> {
+  const path = join(ledger.root, ledger.fileName);
+  await mkdir(ledger.root, { recursive: true, mode: 0o700 });
+  let size = await existingSize(path);
+  while (ledger.pending.length > 0) {
+    const records: string[] = [];
+    let bytes = 0;
+    while (ledger.pending.length > 0 && (records.length === 0 || bytes < MCP_DIAGNOSTIC_MAX_BATCH_BYTES)) {
+      const record = ledger.pending.shift()!;
+      ledger.pendingBytes -= Buffer.byteLength(record);
+      records.push(record);
+      bytes += Buffer.byteLength(record);
+    }
+    if (size > 0 && size + bytes > MCP_DIAGNOSTIC_MAX_BYTES) {
+      await rotateLedger(path);
+      size = 0;
+    }
+    const batch = records.join('');
+    await appendFile(path, batch, 'utf-8');
+    size += bytes;
+  }
+}
+
+function scheduleLedgerDrain(ledger: PendingDiagnosticLedger): void {
+  if (ledger.drain) return;
+  ledger.drain = drainLedger(ledger)
+    // Observability is deliberately best-effort. A write failure must not turn
+    // into a failed tool request or retain an unbounded queue in memory.
+    .catch(() => {
+      ledger.pending.length = 0;
+      ledger.pendingBytes = 0;
+    })
+    .finally(() => {
+      ledger.drain = undefined;
+      if (ledger.pending.length > 0) scheduleLedgerDrain(ledger);
+    });
+}
+
 function appendDiagnostic(controllerHome: string, fileName: string, value: Record<string, unknown>): void {
-  const root = join(ensureControllerHome(controllerHome), 'audit');
-  mkdirSync(root, { recursive: true, mode: 0o700 });
-  appendFileSync(join(root, fileName), `${JSON.stringify(value)}\n`, 'utf-8');
+  const ledger = ledgerFor(controllerHome, fileName);
+  if (ledger.pending.length >= MCP_DIAGNOSTIC_MAX_PENDING_ENTRIES) return;
+  const record = `${JSON.stringify(value)}\n`;
+  ledger.pending.push(record);
+  ledger.pendingBytes += Buffer.byteLength(record);
+  scheduleLedgerDrain(ledger);
+}
+
+/** Wait for queued diagnostic evidence in tests and explicit diagnostic consumers. */
+export async function flushMcpDiagnostics(controllerHome?: string): Promise<void> {
+  const ledgers = controllerHome
+    ? [...diagnosticLedgers.values()].filter((ledger) => ledger.root === join(resolve(controllerHome), 'audit'))
+    : [...diagnosticLedgers.values()];
+  await Promise.all(ledgers.map(async (ledger) => {
+    while (ledger.drain) await ledger.drain;
+  }));
 }
 
 export function recordMcpTiming(controllerHome: string, trace: McpTimingTrace): void {
@@ -71,6 +167,20 @@ export function recordMcpTiming(controllerHome: string, trace: McpTimingTrace):
 }
 
 export function recordMcpIncident(controllerHome: string, incident: McpIncident): void {
+  const root = resolve(controllerHome);
+  let remembered = recentIncidents.get(root);
+  if (!remembered) {
+    if (recentIncidents.size >= MCP_INCIDENT_MEMORY_LEDGER_LIMIT) {
+      const oldest = recentIncidents.keys().next().value;
+      if (oldest) recentIncidents.delete(oldest);
+    }
+    remembered = [];
+    recentIncidents.set(root, remembered);
+  }
+  remembered.push({ ...incident, at: new Date().toISOString() });
+  if (remembered.length > MCP_INCIDENT_MEMORY_WINDOW_LIMIT) {
+    remembered.splice(0, remembered.length - MCP_INCIDENT_MEMORY_WINDOW_LIMIT);
+  }
   try {
     appendDiagnostic(controllerHome, 'mcp-incidents.jsonl', {
       schemaVersion: 1,
@@ -81,3 +191,12 @@ export function recordMcpIncident(controllerHome: string, incident: McpIncident)
     // Incident recording is diagnostic evidence; it must never change the tool result.
   }
 }
+
+/**
+ * The repair classifier needs to count immediately repeated incidents before an
+ * asynchronous diagnostic batch reaches disk. This bounded volatile view is
+ * supplemental evidence only; the JSONL ledger remains the restart-safe history.
+ */
+export function recentMcpIncidents(controllerHome: string): Array<McpIncident & { at: string }> {
+  return [...(recentIncidents.get(resolve(controllerHome)) ?? [])];
+}

package/src/runtime/diagnostics/performance.ts

@@ -1,7 +1,8 @@
 import { execFileSync } from 'child_process';
-import { existsSync, lstatSync, readdirSync, rmSync, statfsSync } from 'fs';
+import { existsSync, lstatSync, readdirSync, rmSync } from 'fs';
 import { tmpdir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
+import { readStorageCapacity } from '../shared/storage-capacity';
 
 export interface RuntimeProcessSample {
   pid: number;
@@ -323,19 +324,10 @@ export function collectRuntimePerformanceDiagnostics(input: DiagnosticsInput): R
   const temp = input.includeTempDirs === false
     ? { roots: [] as string[], entries: [] as RuntimeTempEntry[] }
     : scanRuntimeTempEntries(processes);
-  let availableBytes: number | undefined;
-  try {
-    const fs = statfsSync(input.repoRoot);
-    availableBytes = Number(fs.bavail) * Number(fs.bsize);
-  } catch {}
-  const availableGiB = availableBytes === undefined ? undefined : Math.round((availableBytes / (1024 ** 3)) * 10) / 10;
-  const storagePressure: RuntimePerformanceDiagnostics['storage']['pressure'] = availableGiB === undefined
-    ? 'unknown'
-    : availableGiB < 30
-      ? 'critical'
-      : availableGiB < 50
-        ? 'warning'
-        : 'normal';
+  const storage = readStorageCapacity(input.repoRoot);
+  const availableBytes = storage.availableBytes;
+  const availableGiB = storage.availableGiB;
+  const storagePressure: RuntimePerformanceDiagnostics['storage']['pressure'] = storage.pressure;
   const managedCacheRoots = [
     join(input.repoRoot, '.forge', 'ios', 'DerivedData'),
     join(input.repoRoot, '.ai', 'harness'),

package/src/runtime/diagnostics/read-only-tool.ts

@@ -1,5 +1,5 @@
 import type { RepositoryRecord } from '../../cli/repositories/types';
-import { loadMcpRuntimeState } from '../../cli/mcp/auth';
+import { loadMcpRuntimeState } from '../../../adapters/mcp/auth';
 import { listControllerChecks } from '../../cli/controller/check-runner';
 import { listLocalBridgeJobSnapshots } from '../../cli/local-bridge/job-store';
 import { ensureRepositoryRuntimeStorage } from '../../cli/repositories/runtime-storage';

package/src/runtime/evidence/artifact-store.ts

@@ -1,9 +1,9 @@
 import { randomUUID } from 'crypto';
-import { closeSync, mkdirSync, openSync, readSync, statSync } from 'fs';
+import { closeSync, existsSync, mkdirSync, opendirSync, openSync, readSync, statSync } from 'fs';
 import { join } from 'path';
 import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import type { ExecutionJob } from '../execution/jobs/types';
-import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+import { readJsonFile, removeFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
 
 export interface ExecutionArtifactRecord {
   schemaVersion: 1;
@@ -55,6 +55,69 @@ export function writeExecutionArtifact(
   return record;
 }
 
+export interface ExecutionArtifactJobCleanupReport {
+  policyVersion: 'execution-artifact-job-cleanup-v1';
+  inspected: number;
+  matched: number;
+  removed: number;
+  scanTruncated: boolean;
+  blockers: string[];
+}
+
+/**
+ * Reclaim only artifacts whose immutable metadata names the exact retired Job.
+ * Stored path strings are never followed; metadata/data paths are re-derived
+ * from the validated artifact id under this repository's Controller Home.
+ */
+export function cleanupExecutionArtifactsForJob(
+  controllerHome: string,
+  repoId: string,
+  jobId: string,
+  options: { maxScan?: number } = {},
+): ExecutionArtifactJobCleanupReport {
+  const report: ExecutionArtifactJobCleanupReport = {
+    policyVersion: 'execution-artifact-job-cleanup-v1', inspected: 0, matched: 0, removed: 0, scanTruncated: false, blockers: [],
+  };
+  const root = join(repositoryControllerRoot(controllerHome, repoId), 'artifacts');
+  const recordsRoot = join(root, 'records');
+  if (!existsSync(recordsRoot)) return report;
+  const maxScan = Math.max(1, Math.min(Math.trunc(options.maxScan ?? 5_000), 5_000));
+  const directory = opendirSync(recordsRoot);
+  try {
+    for (;;) {
+      const entry = directory.readSync();
+      if (!entry) break;
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      if (report.inspected >= maxScan) { report.scanTruncated = true; break; }
+      report.inspected += 1;
+      const recordPath = join(recordsRoot, entry.name);
+      let record: ExecutionArtifactRecord;
+      try { record = readJsonFile<ExecutionArtifactRecord>(recordPath); } catch {
+        report.blockers.push(`invalid_metadata:${entry.name}`);
+        continue;
+      }
+      if (record.schemaVersion !== 1 || record.repoId !== repoId || !record.artifactId || !record.jobId) {
+        report.blockers.push(`identity_mismatch:${entry.name}`);
+        continue;
+      }
+      const expectedName = `${sanitizeFileComponent(record.artifactId)}.json`;
+      if (entry.name !== expectedName) {
+        report.blockers.push(`artifact_key_mismatch:${entry.name}`);
+        continue;
+      }
+      if (record.jobId !== jobId) continue;
+      report.matched += 1;
+      removeFile(join(root, 'data', expectedName));
+      removeFile(recordPath);
+      report.removed += 1;
+    }
+  } finally {
+    directory.closeSync();
+  }
+  report.blockers = report.blockers.slice(0, 16);
+  return report;
+}
+
 export function readExecutionArtifact(
   controllerHome: string,
   repoId: string,