@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/diagnostics/process-facade.ts

@@ -0,0 +1,350 @@
+import { executionIdentityForRepository } from '../control-plane/execution/execution-identity';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import {
+  currentCliRuntimeTarget,
+  resolveCliChildInvocation,
+  type CliChildInvocation,
+  type CliChildInvocationOptions,
+  type CliRuntimeTarget,
+} from '../../cli/runtime-invocation';
+import { readRuntimeGeneration, resolveControllerRuntimeSourceRoot } from '../control-plane/runtime-generation';
+import {
+  effectiveProcessStatus,
+  processContractStatus,
+  readProcessLogs,
+  spawnManagedProcess,
+  waitForProcess,
+  type ProcessHandle,
+} from '../execution/process-runtime';
+import { isReadOnlyDiagnosticTool, type ReadOnlyDiagnosticTool } from './read-only-tool';
+
+const DEFAULT_DIAGNOSTIC_INTERACTIVE_WAIT_MS = 0;
+const DEFAULT_DIAGNOSTIC_TIMEOUT_MS = 120_000;
+const DEFAULT_DIAGNOSTIC_INLINE_MAX_BYTES = 16 * 1024;
+const DEFAULT_DIAGNOSTIC_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+const ROUTING_ONLY_ARGUMENTS = new Set([
+  'repo_id',
+  'checkout_id',
+  'request_id',
+  'apply_mode',
+  'wait',
+  'wait_ms',
+  'admission_timeout_ms',
+  'queue_timeout_ms',
+  'execution_timeout_ms',
+  'interactive_wait_ms',
+]);
+
+function runtimeCliTarget(controllerHome: string): CliRuntimeTarget {
+  const moduleSourceRoot = resolve(import.meta.dir, '..', '..', '..');
+  const moduleEntryExists = existsSync(resolve(moduleSourceRoot, 'src', 'cli', 'index.ts'));
+  const source = resolveControllerRuntimeSourceRoot({
+    explicitRoot: moduleEntryExists ? moduleSourceRoot : undefined,
+  });
+  const generation = readRuntimeGeneration(controllerHome);
+  const sourceRevision = generation?.source.releaseRevision
+    ?? generation?.source.commit
+    ?? process.env.FORGE_ACTIVE_RUNTIME_REVISION;
+  return currentCliRuntimeTarget({
+    env: process.env,
+    argv: process.env.FORGE_RUNTIME_EXECUTION === 'standalone-binary' ? process.argv : [],
+    moduleUrl: import.meta.url,
+    sourceRoot: source.root,
+    cwd: source.root ?? moduleSourceRoot,
+    sourceRevision,
+  });
+}
+
+export function resolveDiagnosticCliInvocation(
+  entry: string,
+  args: readonly string[],
+  options: CliChildInvocationOptions = {},
+): CliChildInvocation {
+  return resolveCliChildInvocation(entry, args, options);
+}
+
+function diagnosticArguments(args: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(args).filter(([key]) => !ROUTING_ONLY_ARGUMENTS.has(key)));
+}
+
+function boundedNumber(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(Math.trunc(value), max));
+}
+
+function processPointers(repoId: string, processId: string): Record<string, unknown> {
+  return {
+    get: { tool: 'process_get', arguments: { repo_id: repoId, process_id: processId } },
+    wait: { tool: 'process_wait', arguments: { repo_id: repoId, process_id: processId } },
+    logs: { tool: 'process_logs', arguments: { repo_id: repoId, process_id: processId } },
+  };
+}
+
+function processSummary(handle: ProcessHandle): Record<string, unknown> {
+  const effective = effectiveProcessStatus(handle, handle.completed === true);
+  const status = handle.completed === true && handle.ok === false && (effective === 'starting' || effective === 'running' || effective === 'running_recovered')
+    ? 'failed'
+    : effective;
+  return {
+    processId: handle.processId,
+    commandId: handle.commandId,
+    status,
+    contractStatus: processContractStatus(status),
+    route: handle.route,
+    startedAt: handle.startedAt,
+    completed: handle.completed === true,
+    ok: handle.ok,
+    exitCode: handle.exitCode,
+    timedOut: handle.timedOut,
+    cancelled: handle.cancelled,
+  };
+}
+
+function readDiagnosticOutput(
+  controllerHome: string,
+  repoId: string,
+  handle: ProcessHandle,
+): { output: string; bytes: number } {
+  const persisted = readProcessLogs(controllerHome, repoId, handle.processId, DEFAULT_DIAGNOSTIC_MAX_OUTPUT_BYTES);
+  const output = handle.stdout || handle.stdoutTail || persisted?.stdout || '';
+  return {
+    output,
+    bytes: persisted?.stdoutBytes ?? Buffer.byteLength(output, 'utf8'),
+  };
+}
+
+function parseDiagnosticResult(handle: ProcessHandle, output: string): Record<string, unknown> {
+  if (!output.trim()) {
+    throw new Error(`DIAGNOSTIC_PROCESS_EMPTY_OUTPUT: ${handle.processId}`);
+  }
+  try {
+    const parsed = JSON.parse(output) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('diagnostic output is not an object');
+    }
+    return parsed as Record<string, unknown>;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`DIAGNOSTIC_PROCESS_INVALID_JSON: ${handle.processId}: ${detail}`);
+  }
+}
+
+export function isProcessIsolatedReadDiagnostic(name: string): name is ReadOnlyDiagnosticTool {
+  return isReadOnlyDiagnosticTool(name);
+}
+
+export async function runReadOnlyDiagnosticViaProcessRuntime(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  tool: ReadOnlyDiagnosticTool;
+  args: Record<string, unknown>;
+  /** Internal test/embedding override; MCP callers use the fixed 16KiB budget. */
+  inlineMaxBytes?: number;
+  /** Internal test/embedding override for deterministic runtime launch fixtures. */
+  cliInvocation?: { entry: string; options?: CliChildInvocationOptions };
+}): Promise<Record<string, unknown>> {
+  let invocation: CliChildInvocation;
+  let target: CliRuntimeTarget | undefined;
+  let resolutionFailure: string | undefined;
+  try {
+    if (input.cliInvocation) {
+      invocation = resolveDiagnosticCliInvocation(
+        input.cliInvocation.entry,
+        [],
+        input.cliInvocation.options,
+      );
+    } else {
+      target = runtimeCliTarget(input.controllerHome);
+      invocation = resolveDiagnosticCliInvocation(target.entry, [], {
+        runtimeExecutable: target.runtimeKind === 'compiled_bun_release' ? target.entry : process.execPath,
+        runtimeKind: target.runtimeKind,
+        sourceRevision: target.sourceRevision,
+        immutable: target.immutable,
+        ...(target.runtimeKind === 'package_launcher' ? { launcherEntry: target.entry } : {}),
+      });
+    }
+  } catch (error) {
+    resolutionFailure = error instanceof Error ? error.message : String(error);
+    invocation = resolveDiagnosticCliInvocation('<runtime-resolution-failure>', [], {
+      runtimeExecutable: process.execPath,
+      runtimeKind: process.versions.bun ? 'bun_source' : 'node_source',
+      sourceRevision: 'resolution-failure',
+    });
+  }
+  const semanticArgs = diagnosticArguments(input.args);
+  const encodedArgs = Buffer.from(JSON.stringify(semanticArgs), 'utf8').toString('base64url');
+  const returnHandleImmediately = input.args.apply_mode === 'async';
+  const interactiveWaitMs = returnHandleImmediately
+    ? 0
+    : boundedNumber(
+      input.args.interactive_wait_ms,
+      DEFAULT_DIAGNOSTIC_INTERACTIVE_WAIT_MS,
+      0,
+      5_000,
+    );
+  const inlineMaxBytes = boundedNumber(
+    input.inlineMaxBytes,
+    DEFAULT_DIAGNOSTIC_INLINE_MAX_BYTES,
+    1,
+    DEFAULT_DIAGNOSTIC_MAX_OUTPUT_BYTES,
+  );
+  const timeoutMs = boundedNumber(
+    input.args.execution_timeout_ms,
+    DEFAULT_DIAGNOSTIC_TIMEOUT_MS,
+    interactiveWaitMs + 1,
+    24 * 60 * 60_000,
+  );
+  const requestId = typeof input.args.request_id === 'string' ? input.args.request_id.trim() || undefined : undefined;
+  const spawned = await spawnManagedProcess({
+    controllerHome: input.controllerHome,
+    repoId: input.repository.repoId,
+    checkoutId: input.repository.activeCheckoutId,
+    executionIdentity: executionIdentityForRepository(input.repository),
+    commandId: `diagnostic:${input.tool}`,
+    command: {
+      kind: 'argv',
+      ...(resolutionFailure
+        ? {
+          executable: process.execPath,
+          args: ['-e', `console.error(${JSON.stringify(resolutionFailure)}); process.exit(78);`],
+        }
+        : resolveDiagnosticCliInvocation(
+          target?.entry ?? input.cliInvocation!.entry,
+          [
+            'runtime',
+            'diagnostic-read',
+            '--controller-home',
+            input.controllerHome,
+            '--repo-id',
+            input.repository.repoId,
+            '--tool',
+            input.tool,
+            '--args-base64',
+            encodedArgs,
+          ],
+          target
+            ? {
+              runtimeExecutable: target.runtimeKind === 'compiled_bun_release' ? target.entry : invocation.executable,
+              runtimeKind: target.runtimeKind,
+              sourceRevision: target.sourceRevision,
+              immutable: target.immutable,
+              ...(target.runtimeKind === 'package_launcher' ? { launcherEntry: target.entry } : {}),
+            }
+            : input.cliInvocation?.options,
+        )),
+      // The executable entry may live in the forge runtime source tree,
+      // but execution ownership belongs to the selected repository checkout.
+      // Keeping cwd inside that checkout preserves fail-closed route identity.
+      cwd: input.repository.canonicalRoot,
+    },
+    interactiveWaitMs,
+    timeoutMs,
+    maxOutputBytes: DEFAULT_DIAGNOSTIC_MAX_OUTPUT_BYTES,
+    resourceClaims: [],
+    returnHandleImmediately,
+    origin: {
+      surface: 'mcp',
+      toolName: input.tool,
+      requestId,
+    },
+  });
+
+  const handle = spawned.completed === true
+    ? await waitForProcess(input.controllerHome, input.repository.repoId, spawned.processId, { timeoutMs: 1_000 }).catch(() => spawned)
+    : spawned;
+  const pointers = processPointers(input.repository.repoId, handle.processId);
+  if (handle.completed === true) {
+    if (handle.ok !== true) {
+      return {
+        accepted: false,
+        mode: 'process_direct',
+        path: 'process_direct',
+        error: {
+          code: resolutionFailure ? 'DIAGNOSTIC_RUNTIME_UNRESOLVED' : 'DIAGNOSTIC_PROCESS_FAILED',
+          message: handle.stderr || handle.stderrTail || `diagnostic process ${handle.processId} failed`,
+        },
+        process: processSummary(handle),
+        processPointers: pointers,
+        diagnosticRuntime: {
+          runtimeKind: target?.runtimeKind ?? invocation.runtimeKind,
+          sourceRevision: target?.sourceRevision ?? invocation.sourceRevision,
+          immutable: target?.immutable ?? invocation.immutable,
+          explanation: resolutionFailure ?? target?.explanation ?? invocation.diagnostic,
+        },
+        durableSideEffects: handle.durableSideEffects,
+      };
+    }
+    const { output, bytes } = readDiagnosticOutput(input.controllerHome, input.repository.repoId, handle);
+    if (returnHandleImmediately || bytes > inlineMaxBytes) {
+      return {
+        accepted: true,
+        mode: 'process_managed',
+        path: 'process_managed',
+        processId: handle.processId,
+        deduplicated: handle.deduplicated === true,
+        process: processSummary(handle),
+        processPointers: pointers,
+        result: {
+          available: true,
+          inline: false,
+          bytes,
+          inlineLimitBytes: inlineMaxBytes,
+          reason: returnHandleImmediately ? 'caller_requested_async' : 'result_exceeds_inline_limit',
+        },
+        diagnosticRuntime: {
+          runtimeKind: target?.runtimeKind ?? invocation.runtimeKind,
+          sourceRevision: target?.sourceRevision ?? invocation.sourceRevision,
+          immutable: target?.immutable ?? invocation.immutable,
+          explanation: target?.explanation ?? invocation.diagnostic,
+        },
+        durableSideEffects: handle.durableSideEffects,
+      };
+    }
+    const diagnostic = parseDiagnosticResult(handle, output);
+    return {
+      ...diagnostic,
+      diagnosticExecution: {
+        accepted: true,
+        mode: 'process_direct',
+        path: 'process_direct',
+        processId: handle.processId,
+        deduplicated: handle.deduplicated === true,
+        resultBytes: bytes,
+        inlineLimitBytes: inlineMaxBytes,
+        durableSideEffects: handle.durableSideEffects,
+        processPointers: pointers,
+        runtime: {
+          runtimeKind: target?.runtimeKind ?? invocation.runtimeKind,
+          sourceRevision: target?.sourceRevision ?? invocation.sourceRevision,
+          immutable: target?.immutable ?? invocation.immutable,
+          explanation: target?.explanation ?? invocation.diagnostic,
+        },
+      },
+    };
+  }
+
+  return {
+    accepted: true,
+    mode: 'process_managed',
+    path: 'process_managed',
+    processId: handle.processId,
+    deduplicated: handle.deduplicated === true,
+    process: processSummary(handle),
+    processPointers: pointers,
+    result: {
+      available: false,
+      inline: false,
+      reason: returnHandleImmediately ? 'caller_requested_async' : 'interactive_wait_expired',
+    },
+    diagnosticRuntime: {
+      runtimeKind: target?.runtimeKind ?? invocation.runtimeKind,
+      sourceRevision: target?.sourceRevision ?? invocation.sourceRevision,
+      immutable: target?.immutable ?? invocation.immutable,
+      explanation: target?.explanation ?? invocation.diagnostic,
+    },
+    durableSideEffects: handle.durableSideEffects,
+  };
+}

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

@@ -0,0 +1,226 @@
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import { loadMcpRuntimeState } from '../../cli/mcp/auth';
+import { listControllerChecks } from '../../cli/controller/check-runner';
+import { listLocalBridgeJobSnapshots } from '../../cli/local-bridge/job-store';
+import { ensureRepositoryRuntimeStorage } from '../../cli/repositories/runtime-storage';
+import { sessionCacheGlobalDiagnostics } from '../../cli/repository/session-cache';
+import {
+  cachedGitIdentity,
+  gitIdentityPerformanceSnapshot,
+  gitSnapshotPerformanceSnapshot,
+} from '../../cli/repository/inspector';
+import { previewRuntimeCleanup } from '../maintenance/cleanup';
+import {
+  buildCapabilityRecoverySnapshot,
+  buildRuntimeMaintenanceStatus,
+  listRecoveryAuditRecords,
+} from '../recovery';
+import { buildWorkflowWatchdogReport } from '../watchdog/workflow-watchdog';
+import {
+  collectRuntimePerformanceDiagnostics,
+  inferLocalControllerProcess,
+} from './performance';
+import { readRepositoryProjectionSnapshot } from '../projections/materialized-view';
+import {
+  controllerContextPerformanceSnapshot,
+  controllerContextProjectionNeedsRefresh,
+  readControllerContextProjection,
+} from '../projections/controller-context';
+import { listExecutionJobs } from '../execution/jobs/store';
+import { processRuntimeResourceDiagnostics } from '../execution/process-runtime';
+import { readSchedulerHealthSnapshot } from '../control-plane/global-scheduler/scheduler';
+import { readForgeRuntimeStatus } from '../control-plane/runtime-status-client';
+import { listAssistantPluginManifests } from '../plugins/store';
+
+export const READ_ONLY_DIAGNOSTIC_TOOLS = [
+  'runtime_maintenance_status',
+  'workflow_watchdog_report',
+  'runtime_cleanup_preview',
+  'runtime_performance_diagnostics',
+  'capability_recovery_probe',
+] as const;
+
+export type ReadOnlyDiagnosticTool = (typeof READ_ONLY_DIAGNOSTIC_TOOLS)[number];
+
+const READ_ONLY_DIAGNOSTIC_TOOL_SET = new Set<string>(READ_ONLY_DIAGNOSTIC_TOOLS);
+
+export function isReadOnlyDiagnosticTool(value: string): value is ReadOnlyDiagnosticTool {
+  return READ_ONLY_DIAGNOSTIC_TOOL_SET.has(value);
+}
+
+function activeExecutionJobs(controllerHome: string, repoId: string) {
+  return listExecutionJobs(controllerHome, repoId, 100)
+    .filter((job) => !['succeeded', 'failed', 'cancelled', 'timed_out', 'orphaned', 'stale'].includes(job.status));
+}
+
+function performanceDiagnostic(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const projection = readRepositoryProjectionSnapshot(controllerHome, repository.repoId).projection;
+  const runtime = loadMcpRuntimeState(repository.canonicalRoot);
+  const inferredLocalBridge = inferLocalControllerProcess(repository.canonicalRoot);
+  const activeJobs = activeExecutionJobs(controllerHome, repository.repoId);
+  const daemon = readForgeRuntimeStatus(controllerHome);
+  return {
+    ...collectRuntimePerformanceDiagnostics({
+      repoId: repository.repoId,
+      repoRoot: repository.canonicalRoot,
+      queueDepth: projection.queueDepth ?? 0,
+      runningWorkers: projection.runningWorkers ?? 0,
+      activeLeases: projection.activeLeases ?? 0,
+      activeJobIds: activeJobs.map((job) => job.jobId),
+      includeProcesses: args.include_processes !== false,
+      includeTempDirs: args.include_temp_dirs !== false,
+      cleanupPreview: args.cleanup_preview === true,
+      localControllerRunning: runtime?.localController?.running === true || inferredLocalBridge?.running === true,
+      localControllerPid: runtime?.localController?.pid ?? inferredLocalBridge?.pid,
+      localControllerEndpoint: runtime?.localController?.endpoint ?? inferredLocalBridge?.endpoint,
+    }),
+    contextPerformance: controllerContextPerformanceSnapshot(),
+    gitPerformance: gitSnapshotPerformanceSnapshot(),
+    gitIdentity: gitIdentityPerformanceSnapshot(),
+    runtimeIdentity: {
+      runtimeCommit: daemon.source?.commit,
+      buildCommit: daemon.source?.releaseRevision,
+      controllerInstanceId: daemon.instanceId,
+      generation: daemon.generation,
+      toolset: typeof args.__diagnostic_toolset === 'string' ? args.__diagnostic_toolset : 'advanced',
+      profile: typeof args.__diagnostic_profile === 'string' ? args.__diagnostic_profile : 'controller',
+    },
+    resourceCost: {
+      processRuntime: processRuntimeResourceDiagnostics(),
+      scheduler: readSchedulerHealthSnapshot(controllerHome),
+      sessionCache: sessionCacheGlobalDiagnostics(),
+    },
+  };
+}
+
+function diagnosticContextProjectionStale(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  args: Record<string, unknown>,
+): boolean {
+  const runtimeSnapshot = readRepositoryProjectionSnapshot(controllerHome, repository.repoId);
+  const sourceRevision = String(runtimeSnapshot.projection.metadata?.contentRevision ?? runtimeSnapshot.projection.revision);
+  const gitIdentity = cachedGitIdentity(repository.canonicalRoot);
+  const sourceIdentity = {
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+    canonicalRoot: repository.canonicalRoot,
+    head: gitIdentity.head,
+    branch: gitIdentity.branch,
+    workingTreeFingerprint: gitIdentity.workingTreeFingerprint,
+    runtimeGeneration: runtimeSnapshot.projection.metadata?.producerGeneration,
+    sourceRevision,
+    variant: 'summary' as const,
+    toolset: typeof args.__diagnostic_toolset === 'string' ? args.__diagnostic_toolset : 'advanced',
+    profile: typeof args.__diagnostic_profile === 'string' ? args.__diagnostic_profile : 'controller',
+  };
+  const projection = readControllerContextProjection(controllerHome, repository.repoId, { sourceIdentity });
+  return controllerContextProjectionNeedsRefresh(projection, sourceRevision, sourceIdentity);
+}
+
+function recoveryProbe(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const daemon = readForgeRuntimeStatus(controllerHome);
+  const scheduler = readSchedulerHealthSnapshot(controllerHome);
+  const projectionSnapshot = readRepositoryProjectionSnapshot(controllerHome, repository.repoId);
+  const projection = projectionSnapshot.projection;
+  const localBridge = loadMcpRuntimeState(repository.canonicalRoot)?.localController;
+  const inferredLocalBridge = inferLocalControllerProcess(repository.canonicalRoot);
+  const activeJobs = activeExecutionJobs(controllerHome, repository.repoId);
+  const heartbeat = scheduler.lastHeartbeatAt ?? scheduler.lastTickAt;
+  const heartbeatAgeMs = heartbeat ? Math.max(0, Date.now() - Date.parse(heartbeat)) : undefined;
+  const heartbeatTimeoutMs = scheduler.heartbeatTimeoutMs ?? 60_000;
+  let runtimeStorageReady = false;
+  let runtimeStorageWarnings: string[] = [];
+  try {
+    const storage = ensureRepositoryRuntimeStorage(repository, controllerHome);
+    runtimeStorageReady = storage.readyForExecution;
+    runtimeStorageWarnings = storage.warnings;
+  } catch (error) {
+    runtimeStorageWarnings = [error instanceof Error ? error.message : String(error)];
+  }
+  const localJobs = listLocalBridgeJobSnapshots(repository.canonicalRoot, 30);
+  const recentErrors = Array.isArray(args.recent_errors) ? args.recent_errors.map(String) : [];
+  const contextProjectionStale = diagnosticContextProjectionStale(controllerHome, repository, args);
+  const plugins = listAssistantPluginManifests(controllerHome, repository, { preferStored: true });
+  const recovery = buildCapabilityRecoverySnapshot({
+    generatedAt: new Date().toISOString(),
+    daemonStatus: daemon.status === 'ready' ? 'ready' : daemon.status,
+    daemonError: daemon.error,
+    schedulerStatus: heartbeatAgeMs !== undefined && heartbeatAgeMs <= heartbeatTimeoutMs ? 'ready' : 'degraded',
+    schedulerHeartbeatAgeMs: heartbeatAgeMs,
+    queueDepth: projection.queueDepth ?? 0,
+    runningWorkers: projection.runningWorkers ?? 0,
+    activeLeases: projection.activeLeases ?? 0,
+    localBridgeRunning: localBridge?.running ?? inferredLocalBridge?.running,
+    localBridgeError: localBridge?.error,
+    runtimeProjectionStale: projectionSnapshot.stale,
+    runtimeProjectionPersisted: projectionSnapshot.persisted,
+    contextProjectionStale,
+    commandPreviewAvailable: args.command_preview_available === undefined ? true : args.command_preview_available === true,
+    commandExecuteAvailable: args.command_execute_available === undefined ? true : args.command_execute_available === true,
+    issueToolsAvailable: args.issue_tools_available === undefined ? true : args.issue_tools_available === true,
+    jobToolsAvailable: args.job_tools_available === undefined ? true : args.job_tools_available === true,
+    checksAvailable: listControllerChecks(repository.canonicalRoot).length > 0,
+    runtimeStorageReady,
+    runtimeStorageWarnings,
+    pluginStates: plugins.map((plugin) => ({
+      pluginId: plugin.pluginId,
+      enabled: plugin.enabled,
+      healthState: plugin.health.state,
+      ready: plugin.health.ready,
+      errors: plugin.health.errors,
+      warnings: plugin.health.warnings,
+    })),
+    recentErrors,
+    localJobs: localJobs.map((job) => ({ status: job.status, error: job.error, updatedAt: job.updatedAt })),
+    executionJobs: activeJobs.map((job) => ({
+      status: job.status,
+      error: job.error,
+      updatedAt: job.updatedAt,
+      operation: job.payload.operation,
+    })),
+  });
+  return { recovery, audit: listRecoveryAuditRecords(controllerHome, repository.repoId, 10) };
+}
+
+export async function executeReadOnlyDiagnostic(
+  tool: ReadOnlyDiagnosticTool,
+  controllerHome: string,
+  repository: RepositoryRecord,
+  args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  switch (tool) {
+    case 'runtime_maintenance_status':
+      return buildRuntimeMaintenanceStatus(repository, controllerHome, {
+        minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+        maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+        cancelPendingApprovals: args.cancel_pending_approvals === true,
+      }) as unknown as Record<string, unknown>;
+    case 'workflow_watchdog_report':
+      return buildWorkflowWatchdogReport(controllerHome, repository, {
+        staleMinutes: args.stale_minutes,
+        includeProcesses: args.include_processes,
+      }) as unknown as Record<string, unknown>;
+    case 'runtime_cleanup_preview':
+      return previewRuntimeCleanup(repository.canonicalRoot, {
+        minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+        includeTempDirs: args.include_temp_dirs !== false,
+        includeTerminalLocalJobs: args.include_terminal_local_jobs === true,
+        includeLegacyRuns: args.include_legacy_runs === true,
+        includeHistoricalAttention: args.include_historical_attention === true,
+        maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+      }) as unknown as Record<string, unknown>;
+    case 'runtime_performance_diagnostics':
+      return performanceDiagnostic(controllerHome, repository, args);
+    case 'capability_recovery_probe':
+      return recoveryProbe(controllerHome, repository, args);
+  }
+}