@moretea-labs/forge 1.7.2 → 1.8.0

package/adapters/mcp/runtime-gateway/status-inbox-adapter.ts

@@ -0,0 +1,870 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import { runProcess } from '../../../src/effects/process-runner';
+import type { MultiRepositoryMcpToolContext } from "../multi-repository";
+import { allControllerToolDefinitions, controllerExposureSnapshot, controllerToolSurfaceStatus } from "../toolset";
+import { result } from "./result-adapter";
+import { selected } from "./shared-adapter";
+import { reconcileReadinessProjectionSource } from "../readiness-projection";
+import { listExecutionJobs } from "../../../src/runtime/execution/jobs/store";
+import type { ExecutionJob } from '../../../src/runtime/execution/jobs/types';
+import { getProcessRecord, isManagedProcessActive, processRuntimeResourceDiagnostics } from "../../../src/runtime/execution/process-runtime";
+import { readForgeRuntimeStatus } from "../../../src/runtime/control-plane/runtime-status-client";
+import { readSchedulerHealthSnapshot } from "../../../src/runtime/control-plane/global-scheduler/scheduler";
+import { evaluateActiveRuntimeSourceDrift, formatRuntimeSourceDriftMessage, readRuntimeGeneration, type RuntimeSourceIdentity } from "../../../src/runtime/control-plane/runtime-generation";
+import { projectionObservation, readRepositoryProjectionSnapshot } from "../../../src/runtime/projections/materialized-view";
+import { buildRuntimeOperationalView, classifyRuntimeReadinessSemantics, evaluateRuntimeHealth, RUNTIME_HEALTH_THRESHOLDS, type RuntimeOperationalView, type GradedObservation } from "../../../src/runtime/health";
+import { buildControllerTaskLedgerProjection } from "../../../src/cli/controller/task-ledger";
+import { legacyIssueAuthorityRetired } from "../../../src/cli/controller/legacy-issue-cutover";
+import { listControllerChecks } from "../../../src/cli/controller/check-runner";
+import { buildCheckExecutionSchedule } from "../../../src/runtime/execution/process-runtime/check-scheduling";
+import { FORGE_MCP_SCHEMA_VERSION, FORGE_TOOL_SURFACE, FORGE_VERSION } from "../../../src/cli/controller/runtime-config";
+import { resolveLocalBridgeSurface } from "../../../src/runtime/shared/local-bridge-surface";
+import { listAssistantPluginManifests } from "../../../src/runtime/plugins/store";
+import { cachedGitIdentity, gitSnapshot } from "../../../src/cli/repository/inspector";
+import { buildRuntimeMaintenanceStatus } from "../../../src/runtime/recovery";
+import { allowedFacadeOperations, buildFacadeResult, listCapabilityDescriptors, summarizeCapabilityGroups, listHandoffAttentionItems, listHandoffItems, normalizeCheckIds, buildWorkContinuationSnapshot, listPlanContracts, summarizePlanContract, runHandoffInboxApplication, type FacadeTool } from "../../../src/runtime/control-plane/facade";
+import { buildJobOperationDigest } from '../../../src/runtime/control-plane/facade/operation-digest';
+import { readActiveWorkCandidates, type InvalidActiveWorkCandidate } from "../../../packages/kernel/work/api/index";
+import { observeRuntimeStatus } from "../../../src/runtime/root/status";
+import { getControllerSession } from "../../../packages/kernel/controller/api/index";
+import { summarizeHandoffItem } from '../../../src/runtime/control-plane/facade';
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import { handoffResolvedContinuationEventName, triggerWorkContinuationRepositoryEvent } from '../../../src/runtime/workflow/schedules/work-continuation';
+
+
+export const GIT_IDENTITY_SAMPLE_TTL_MS = Math.max(1_000, Number(process.env.FORGE_GIT_IDENTITY_SAMPLE_TTL_MS ?? 3_000));
+
+export function repositoryRevisionContains(repoRoot: string, ancestorRevision: string, descendantRevision: string): boolean {
+  const ancestor = ancestorRevision.trim();
+  const descendant = descendantRevision.trim();
+  if (!/^[a-f0-9]{40}$/i.test(ancestor) || !/^[a-f0-9]{40}$/i.test(descendant)) return false;
+  if (ancestor === descendant) return true;
+  return runProcess('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
+    cwd: repoRoot,
+    timeoutMs: 10_000,
+    maxOutputBytes: 32_000,
+  }).ok;
+}
+
+export function summarizeInvalidActiveWorkCandidate(entry: InvalidActiveWorkCandidate) {
+  return {
+    workId: entry.workId,
+    updatedAt: entry.updatedAt,
+    requirementId: entry.requirementId,
+    planId: entry.planId,
+    planStepId: entry.planStepId,
+    semanticScopeKeys: entry.semanticScopeKeys.slice(0, 4),
+    isolation: entry.isolation,
+    error: entry.error.slice(0, 160),
+  };
+}
+
+export function summarizeWorkListItem(job: ExecutionJob): Record<string, unknown> {
+  const digest = buildJobOperationDigest(job);
+  return {
+    workId: job.jobId,
+    requestId: job.requestId,
+    kind: 'execution_job',
+    operation: typeof job.payload?.operation === 'string' ? job.payload.operation : job.type,
+    status: job.status,
+    phase: digest.phase,
+    statusLabel: digest.statusLabel,
+    summary: digest.summary,
+    terminal: digest.terminal,
+    resumable: !digest.terminal || digest.phase === 'needs_attention',
+    errorClass: digest.errorClass,
+    changedFileCount: digest.changedFiles?.length ?? 0,
+    evidenceCount: job.evidenceIds.length,
+    createdAt: job.createdAt,
+    updatedAt: job.updatedAt,
+    suggestedNextAction: digest.suggestedNextActions[0],
+    detailPointer: { tool: 'work_get', work_id: job.jobId },
+  };
+}
+
+export function invalidFacadeOperation(tool: FacadeTool, operation: string): CallToolResult {
+  const allowed = allowedFacadeOperations(tool);
+  const facade = buildFacadeResult({
+    status: 'failed',
+    summary: `Invalid ${tool} operation: ${operation || '<empty>'}.`,
+    data: { tool, operation: operation || null, allowedOperations: [...allowed] },
+    warnings: [`invalid_operation: ${tool} does not support "${operation}"`],
+    suggestedNextActions: allowed.slice(0, 4).map((op) => ({
+      label: `Try ${tool}.${op}`,
+      tool,
+      operation: op,
+      risk: 'readonly' as const,
+      confidence: 'high' as const,
+    })),
+    rawAvailable: false,
+  });
+  return result(facade as unknown as Record<string, unknown>, true);
+}
+
+
+export function ageMs(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? Math.max(0, Date.now() - parsed) : undefined;
+}
+
+export async function probeLocalControllerHealth(endpoint: string | undefined): Promise<Record<string, unknown> | null> {
+  if (!endpoint) return null;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1_500);
+  try {
+    const url = new URL(endpoint);
+    url.pathname = '/health';
+    url.search = '';
+    url.hash = '';
+    const response = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } });
+    if (!response.ok) return null;
+    return await response.json() as Record<string, unknown>;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function localControllerDiagnosticMatchesRuntime(
+  payload: Record<string, unknown> | null,
+  expected: { generation?: string } = {},
+): boolean {
+  return payload?.status === 'ok'
+    && payload.toolSurface === FORGE_TOOL_SURFACE
+    && payload.schemaVersion === FORGE_MCP_SCHEMA_VERSION
+    && payload.version === FORGE_VERSION
+    && (expected.generation === undefined || payload.generation === expected.generation);
+}
+
+export interface ControllerReadinessSignals {
+  externalEndpoint?: GradedObservation;
+  mcpHandshake?: GradedObservation;
+  sessionContinuity?: GradedObservation;
+}
+
+export async function controllerReadinessEvidence(
+  ctx: MultiRepositoryMcpToolContext,
+  repository = ctx.explicitRepository,
+  signals: ControllerReadinessSignals = {},
+) {
+  const daemon = readForgeRuntimeStatus(ctx.controllerHome);
+  const scheduler = readSchedulerHealthSnapshot(ctx.controllerHome);
+  const projectionSnapshot = repository ? readRepositoryProjectionSnapshot(ctx.controllerHome, repository.repoId) : undefined;
+  const projection = projectionSnapshot?.projection;
+  const taskLedger = repository && !legacyIssueAuthorityRetired(repository.canonicalRoot)
+    ? buildControllerTaskLedgerProjection(repository.canonicalRoot)
+    : undefined;
+  const projectionReconciliation = projectionSnapshot
+    ? reconcileReadinessProjectionSource(projectionSnapshot, taskLedger)
+    : undefined;
+  const localBridgeSurface = repository
+    ? resolveLocalBridgeSurface({
+      controllerHome: ctx.controllerHome,
+      repoRoot: repository.canonicalRoot,
+      allowProcessScan: false,
+    })
+    : undefined;
+  const localBridgeEndpoint = localBridgeSurface?.endpoint;
+  const shouldProbeLocalBridge = Boolean(
+    localBridgeSurface?.enabled
+    && localBridgeSurface.endpointConfigured
+    && localBridgeEndpoint
+    && localBridgeSurface.mode !== 'disabled',
+  );
+  const localBridgeLiveHealth = shouldProbeLocalBridge
+    ? await probeLocalControllerHealth(localBridgeEndpoint)
+    : null;
+  const localBridgeEndpointReachable = localBridgeLiveHealth !== null;
+  const localBridgeExpectedSurface = shouldProbeLocalBridge
+    ? localControllerDiagnosticMatchesRuntime(localBridgeLiveHealth, {
+      generation: localBridgeSurface?.generation,
+    })
+    : true;
+  const schedulerHeartbeatAgeMs = ageMs(scheduler.lastTickAt);
+  const dispatchHeartbeatAgeMs = ageMs(scheduler.lastDispatchAt);
+  const localBridgeObservation = {
+    enabled: localBridgeSurface?.enabled ?? false,
+    requiredForReadiness: localBridgeSurface?.requiredForReadiness ?? false,
+    mode: localBridgeSurface?.mode ?? ('disabled' as const),
+    endpoint: localBridgeEndpoint,
+    endpointReachable: shouldProbeLocalBridge ? localBridgeEndpointReachable : true,
+    expectedSurface: localBridgeExpectedSurface,
+    processAlive: localBridgeSurface?.processRunning,
+    runtimeStateFresh: localBridgeSurface?.source === 'service-runtime'
+      || localBridgeSurface?.source === 'repo-runtime',
+    error: localBridgeSurface?.error,
+  };
+  const runtimeHealth = evaluateRuntimeHealth({
+    daemon: {
+      status: daemon.status,
+      error: daemon.error,
+      // Scheduler ticks are emitted by the Canonical Forge Runtime process and provide
+      // its continuously refreshed heartbeat without introducing a second timer.
+      heartbeatAgeMs: schedulerHeartbeatAgeMs,
+    },
+    scheduler: {
+      status: daemon.degraded ? 'degraded' : daemon.status,
+      heartbeatAgeMs: schedulerHeartbeatAgeMs,
+      dispatchHeartbeatAgeMs,
+    },
+    workers: {
+      queueDepth: projection?.queueDepth,
+      runningWorkers: projection?.runningWorkers,
+      activeLeases: projection?.activeLeases,
+      activeAttentionCount: projection?.currentAttention.length,
+    },
+    projection: projectionSnapshot ? projectionObservation(projectionSnapshot, projectionReconciliation) : {
+      readable: true,
+      persisted: true,
+    },
+    localBridge: localBridgeObservation,
+    runtimeStorage: { readable: true, ready: true },
+    ...signals,
+  });
+  const operationalView: RuntimeOperationalView = buildRuntimeOperationalView({
+    health: runtimeHealth,
+    handoffs: repository
+      ? listHandoffItems({ controllerHome: ctx.controllerHome, repoId: repository.repoId, status: 'all', limit: 100 })
+      : [],
+    jobs: repository ? listExecutionJobs(ctx.controllerHome, repository.repoId, 100) : [],
+  });
+  const reasons: Array<{ code: string; message: string }> = runtimeHealth.activeBlockers.map((item) => ({
+    code: item.code === 'SCHEDULER_NOT_PROGRESSING'
+      ? 'DISPATCH_LOOP_STALLED'
+      : item.code === 'LEASE_WITHOUT_WORKER' || item.code === 'WORKER_NOT_RUNNING'
+        ? 'WORKER_NOT_RUNNING'
+        : item.code,
+    message: item.message,
+  }));
+  if (
+    reasons.some((item) => item.code === 'WORKER_NOT_RUNNING')
+    && (dispatchHeartbeatAgeMs === undefined || dispatchHeartbeatAgeMs > RUNTIME_HEALTH_THRESHOLDS.queueProgressStaleMs)
+  ) {
+    reasons.push({
+      code: 'QUEUE_NOT_PROGRESSING',
+      message: 'Queued Jobs have not received a recent dispatch heartbeat.',
+    });
+  }
+  const ready = runtimeHealth.ready;
+  return {
+    ready,
+    state: ready ? runtimeHealth.state === 'healthy' ? 'ready' as const : 'degraded' as const : daemon.status === 'ready' ? 'degraded' as const : 'not_ready' as const,
+    reasons,
+    warnings: runtimeHealth.warnings.map((item) => ({ code: item.code, message: item.message })),
+    health: runtimeHealth,
+    operationalView,
+    daemon,
+    durableScheduler: {
+      status: runtimeHealth.components.scheduler.ready ? 'ready' : daemon.status === 'ready' ? 'degraded' : 'not_ready',
+      loopStartedAt: scheduler.loopStartedAt,
+      lastTickAt: scheduler.lastTickAt,
+      lastDispatchAt: scheduler.lastDispatchAt,
+      lastReconcileAt: scheduler.lastReconcileAt,
+      heartbeatAgeMs: schedulerHeartbeatAgeMs,
+      dispatchHeartbeatAgeMs,
+    },
+    workerLoop: {
+      status: projection?.runningWorkers ? 'running' : projection?.queueDepth ? 'idle' : 'ready',
+      queueDepth: projection?.queueDepth ?? 0,
+      runningWorkers: projection?.runningWorkers ?? 0,
+      activeLeases: projection?.activeLeases ?? 0,
+      activeAttentionCount: projection?.currentAttention.length ?? 0,
+      consuming: (projection?.queueDepth ?? 0) === 0 || (projection?.runningWorkers ?? 0) > 0,
+    },
+    localBridge: repository ? {
+      running: Boolean(localBridgeSurface?.enabled)
+        && runtimeHealth.components.localBridge.ready
+        && (!shouldProbeLocalBridge || (localBridgeEndpointReachable && localBridgeExpectedSurface)),
+      endpoint: localBridgeEndpoint,
+      error: localBridgeSurface?.error,
+      inferredPid: localBridgeSurface?.pid,
+      statusSource: localBridgeSurface?.source ?? 'none',
+      health: runtimeHealth.components.localBridge,
+    } : undefined,
+    projection,
+    projectionSnapshot,
+    taskLedger,
+    projectionReconciliation,
+    semantics: classifyRuntimeReadinessSemantics(runtimeHealth),
+  };
+}
+
+export function runtimeSourceSnapshotStatus(
+  active: RuntimeSourceIdentity | undefined,
+  currentRuntimeRoot?: string,
+) {
+  const drift = evaluateActiveRuntimeSourceDrift(active, {
+    currentRuntimeRoot,
+  });
+  return {
+    current: drift.current,
+    restartRequired: drift.restartRequired,
+    reasons: drift.reasons,
+    code: drift.code,
+  };
+}
+
+export function repositoryExecutionReadiness(
+  repoRoot: string,
+  availableChecks: ReturnType<typeof listControllerChecks>,
+  requestedCheckIds: string[] = [],
+  schedulingScope: { repoId?: string; checkoutId?: string } = {},
+): Record<string, unknown> {
+  const git = gitSnapshot(repoRoot);
+  const registeredCheckIds = availableChecks.map((check) => check.id);
+  const normalizedChecks = normalizeCheckIds(requestedCheckIds, availableChecks);
+  const hasPackageJson = existsSync(join(repoRoot, 'package.json'));
+  const nodeModulesReady = !hasPackageJson || existsSync(join(repoRoot, 'node_modules'));
+  const lockCandidates = [
+    ['bun', 'bun.lock'],
+    ['bun', 'bun.lockb'],
+    ['pnpm', 'pnpm-lock.yaml'],
+    ['npm', 'package-lock.json'],
+    ['yarn', 'yarn.lock'],
+  ] as const;
+  const detectedLock = lockCandidates.find(([, path]) => existsSync(join(repoRoot, path)));
+  const packageManager = detectedLock?.[0];
+  const bootstrapCommand = hasPackageJson && !nodeModulesReady
+    ? packageManager === 'bun' ? ['bun', 'install', '--frozen-lockfile']
+      : packageManager === 'pnpm' ? ['pnpm', 'install', '--frozen-lockfile']
+        : packageManager === 'npm' ? ['npm', 'ci']
+          : packageManager === 'yarn' ? ['yarn', 'install', '--frozen-lockfile']
+            : undefined
+    : undefined;
+  const hasPythonManifest = existsSync(join(repoRoot, 'pyproject.toml'))
+    || existsSync(join(repoRoot, 'requirements.txt'))
+    || existsSync(join(repoRoot, 'requirements-dev.txt'));
+  const localPythonReady = !hasPythonManifest
+    || existsSync(join(repoRoot, '.venv', 'bin', 'python'))
+    || existsSync(join(repoRoot, '.venv', 'Scripts', 'python.exe'));
+  const checkScheduling = buildCheckExecutionSchedule({
+    checks: availableChecks,
+    requestedCheckIds,
+    repoId: schedulingScope.repoId?.trim() || 'selected-repository',
+    checkoutId: schedulingScope.checkoutId?.trim() || 'active',
+  });
+  const blockers = [
+    ...(!nodeModulesReady ? [{ code: 'NODE_DEPENDENCIES_MISSING', message: 'package.json is present but node_modules is not materialized in this checkout.' }] : []),
+    ...normalizedChecks.invalidCheckIds.map((checkId) => ({ code: 'CHECK_NOT_REGISTERED', message: `Requested check is not registered: ${checkId}`, checkId })),
+  ];
+  return {
+    readyForFocusedExecution: blockers.length === 0,
+    git: { head: git.head, branch: git.branch, dirty: git.dirty },
+    checks: {
+      registeredCount: registeredCheckIds.length,
+      registeredCheckIds: registeredCheckIds.slice(0, 80),
+      requestedCheckIds: requestedCheckIds.slice(0, 40),
+      normalized: normalizedChecks,
+    },
+    checkScheduling: {
+      waveCount: checkScheduling.waves.length,
+      maxParallel: checkScheduling.maxParallel,
+      waveSummaries: checkScheduling.waves.map((wave) => `wave ${wave.wave}: ${wave.checkIds.join(', ')}`),
+      conflictSummaries: checkScheduling.conflicts.map((conflict) => {
+        const resources = [...new Set(conflict.resources.flatMap(({ left, right }) => [left.resourceKey, right.resourceKey]))];
+        return `${conflict.leftCheckId} <> ${conflict.rightCheckId}: ${resources.join(', ')}`;
+      }),
+      invalidCheckIds: checkScheduling.invalidCheckIds,
+      guidance: checkScheduling.guidance,
+    },
+    dependencies: {
+      node: {
+        applicable: hasPackageJson,
+        ready: nodeModulesReady,
+        packageManager: packageManager ?? null,
+        lockfile: detectedLock?.[1] ?? null,
+        ...(bootstrapCommand ? { bootstrapCommand } : {}),
+      },
+      python: {
+        applicable: hasPythonManifest,
+        localVirtualEnvReady: localPythonReady,
+        advisoryOnly: true,
+      },
+    },
+    blockers,
+    guidance: bootstrapCommand
+      ? [`Materialize checkout dependencies before tests/builds: ${bootstrapCommand.join(' ')}`]
+      : [],
+  };
+}
+
+export interface StatusInboxAdapterPorts {
+  repair(
+    ctx: MultiRepositoryMcpToolContext,
+    repository: ReturnType<typeof selected>,
+    args: Record<string, unknown>,
+  ): Promise<CallToolResult>;
+}
+
+export async function callStatusInboxAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+  ports: StatusInboxAdapterPorts,
+): Promise<CallToolResult | undefined> {
+  if (name === 'rh_status') {
+      const repository = selected(ctx, args);
+      const operation = String(args.operation ?? 'get');
+      if (!allowedFacadeOperations('rh_status').includes(operation)) {
+        return invalidFacadeOperation('rh_status', operation);
+      }
+      const store = {
+        controllerHome: ctx.controllerHome,
+        repoId: repository.repoId,
+        revisionContains: (ancestorRevision: string, descendantRevision: string) =>
+          repositoryRevisionContains(repository.canonicalRoot, ancestorRevision, descendantRevision),
+      };
+      if (operation === 'repair') {
+        return await ports.repair(ctx, repository, args);
+      }
+      const detailLevel = args.detail_level === 'detail' ? 'detail' : 'summary';
+      if (detailLevel === 'summary') {
+        const startedAt = performance.now();
+        let summaryTimingMark = startedAt;
+        const summaryPhaseTimingsMs: Record<string, number> = {};
+        const markSummaryPhase = (phase: string): void => {
+          const now = performance.now();
+          summaryPhaseTimingsMs[phase] = Number((now - summaryTimingMark).toFixed(2));
+          summaryTimingMark = now;
+        };
+        const observation = observeRuntimeStatus(ctx.controllerHome);
+        markSummaryPhase('runtime');
+        // Summary answers only whether this repository can work now. Reuse one
+        // porcelain-v2 sample for branch/HEAD/dirty and avoid the full Git
+        // status/diff-stat, access-policy, and inventory construction paths.
+        const repositoryIdentity = cachedGitIdentity(repository.canonicalRoot);
+        const repositoryIdentityAgeMs = Math.max(0, Date.now() - repositoryIdentity.sampledAt);
+        markSummaryPhase('git');
+        const runtimeGeneration = readRuntimeGeneration(ctx.controllerHome);
+        const runtimeSource = runtimeSourceSnapshotStatus(
+          runtimeGeneration?.source,
+          ctx.runtimeSourceRoot,
+        );
+        const sourceSnapshotStale = runtimeSource.restartRequired;
+        const exposure = controllerToolSurfaceStatus(ctx);
+        markSummaryPhase('source_tool_surface');
+        const toolSurfaceReady = exposure.ready && exposure.missingToolNames.length === 0;
+        const ready = observation.ready && toolSurfaceReady && !sourceSnapshotStale;
+        const reasonCodes = [...observation.reasonCodes];
+        if (!toolSurfaceReady) reasonCodes.push('MCP_TOOL_SURFACE_INCOMPLETE');
+        if (sourceSnapshotStale) reasonCodes.push(runtimeSource.code === 'RUNTIME_SOURCE_SNAPSHOT_MISSING'
+          ? 'RUNTIME_SOURCE_SNAPSHOT_MISSING'
+          : runtimeSource.code === 'RUNTIME_SOURCE_CURRENT_UNAVAILABLE'
+            ? 'RUNTIME_SOURCE_CURRENT_UNAVAILABLE'
+            : 'RUNTIME_SOURCE_SNAPSHOT_STALE');
+        const runtimeReadiness = observation.snapshot?.readiness;
+        const releaseDiagnostic = runtimeReadiness?.diagnostics.releaseCoherence;
+        const activeWorkProjection = readActiveWorkCandidates({ ...store, limit: 3 });
+        const activeWorkSnapshot = activeWorkProjection.contracts.map((entry) => ({
+          workId: entry.workId,
+          status: entry.status,
+          mode: entry.mode,
+          objective: entry.objective.slice(0, 160),
+          semantics: buildWorkContinuationSnapshot(entry).semantics,
+          nextSafeAction: buildWorkContinuationSnapshot(entry).nextSafeAction,
+        }));
+        const activePlanSnapshot = listPlanContracts({ ...store, status: 'active', limit: 3 }).map(summarizePlanContract);
+        const pendingHandoffAttention = listHandoffAttentionItems(store, 100);
+        const pendingHandoffSnapshot = pendingHandoffAttention.slice(0, 4);
+        const pendingHandoffCount = pendingHandoffAttention.length;
+        markSummaryPhase('controller_state');
+        const preferredFacadeTools = ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work'] as const;
+        const facade = buildFacadeResult({
+          status: ready ? 'ok' : 'blocked',
+          summary: ready ? 'Controller and MCP tool surface are ready for bounded work.' : 'Controller or MCP tool surface needs attention before work.',
+          data: {
+            operation,
+            repoId: repository.repoId,
+            readiness: {
+              ready,
+              reasonCodes: [...new Set(reasonCodes)],
+              diagnostics: {
+                runtime: { ready: observation.ready },
+                runtimeReadiness: runtimeReadiness ? {
+                  observedAt: runtimeReadiness.observedAt,
+                  database: runtimeReadiness.diagnostics.database,
+                  scheduler: runtimeReadiness.diagnostics.scheduler,
+                  releaseCoherence: runtimeReadiness.diagnostics.releaseCoherence,
+                  mcpEndToEnd: runtimeReadiness.diagnostics.mcpEndToEnd,
+                } : undefined,
+                toolSurface: {
+                  ready: toolSurfaceReady,
+                  expectedToolCount: exposure.expectedToolNames.length,
+                  actualToolCount: exposure.actualToolNames.length,
+                  observation: 'computed',
+                  missingTools: exposure.missingToolNames,
+                  unexpectedTools: exposure.unexpectedToolNames,
+                  duplicateTools: exposure.duplicateToolNames,
+                  fingerprint: exposure.fingerprint,
+                  schemaStableAcrossAccessModes: exposure.schemaStableAcrossAccessModes,
+                },
+                semantics: {
+                  executionReady: observation.ready,
+                  maintenanceHealthy: null,
+                  maintenanceCandidateCount: 0,
+                  releaseReady: releaseDiagnostic?.outcome === 'pass',
+                  executionBlockers: observation.ready ? [] : observation.reasonCodes,
+                  releaseBlockers: releaseDiagnostic?.outcome === 'fail' && releaseDiagnostic.reasonCode ? [releaseDiagnostic.reasonCode] : [],
+                },
+                sourceCoherence: { ready: !sourceSnapshotStale, reasons: runtimeSource.reasons },
+              },
+              observedAt: observation.observedAt,
+            },
+            repositoryState: {
+              branch: repositoryIdentity.branch,
+              head: repositoryIdentity.head,
+              dirty: repositoryIdentity.dirty,
+              observedAt: new Date(repositoryIdentity.sampledAt).toISOString(),
+              observationAgeMs: repositoryIdentityAgeMs,
+              observationMaxAgeMs: GIT_IDENTITY_SAMPLE_TTL_MS,
+              observationPolicy: 'bounded_sample_with_mutation_invalidation',
+              sourceSnapshotAgeMs: runtimeGeneration?.source.observedAt
+                ? Math.max(0, Date.now() - Date.parse(runtimeGeneration.source.observedAt))
+                : undefined,
+              sourceSnapshotStale,
+              sourceSnapshotReasons: runtimeSource.reasons,
+              runtimeSourceDirty: runtimeSource.current?.dirty === true,
+            },
+            toolArchitecture: {
+              facadeTools: [...preferredFacadeTools],
+              domainSchemaLoading: 'status_summary_runtime_snapshot',
+            },
+            toolSurface: preferredFacadeTools.filter((tool) => exposure.actualToolNames.includes(tool)),
+            toolSurfaceStatus: {
+              ready: toolSurfaceReady,
+              expectedToolCount: exposure.expectedToolNames.length,
+              actualToolCount: exposure.actualToolNames.length,
+              observation: 'computed',
+              missingTools: exposure.missingToolNames,
+              unexpectedTools: exposure.unexpectedToolNames,
+              duplicateTools: exposure.duplicateToolNames,
+              fingerprint: exposure.fingerprint,
+              schemaStableAcrossAccessModes: exposure.schemaStableAcrossAccessModes,
+            },
+            controllerSnapshot: {
+              activeWork: activeWorkSnapshot,
+              invalidActiveWorkCount: activeWorkProjection.invalid.length,
+              invalidActiveWork: activeWorkProjection.invalid.slice(0, 3).map(summarizeInvalidActiveWorkCandidate),
+              activePlans: activePlanSnapshot,
+              pendingHandoffCount,
+              pendingHandoffs: pendingHandoffSnapshot.slice(0, 3).map((item) => ({
+                id: item.id,
+                workId: item.workId,
+                title: item.title.slice(0, 96),
+                severity: item.severity,
+                updatedAt: item.updatedAt,
+              })),
+              bounded: true,
+              nextDetail: 'Use rh_context(work_id=...) or rh_work(plan_get) only when the next decision requires more detail.',
+            },
+          },
+          suggestedNextActions: [{
+            label: 'Read repository context',
+            tool: 'rh_context',
+            operation: 'get',
+            risk: 'readonly',
+            confidence: 'medium',
+          }],
+          rawAvailable: false,
+          detailLevel,
+        });
+        markSummaryPhase('response_build');
+        const payload = facade as unknown as Record<string, unknown>;
+        payload.responseMeta = {
+          serverDurationMs: Number((performance.now() - startedAt).toFixed(2)),
+          phaseTimingsMs: summaryPhaseTimingsMs,
+          structuredPayloadBytes: 0,
+        };
+        (payload.responseMeta as { structuredPayloadBytes: number }).structuredPayloadBytes = Buffer.byteLength(JSON.stringify(payload), 'utf8');
+        return result(payload, facade.status !== 'ok');
+      }
+      const detailTimingStartedAt = performance.now();
+      let detailTimingMark = detailTimingStartedAt;
+      const detailPhaseTimingsMs: Record<string, number> = {};
+      const markDetailPhase = (phase: string): void => {
+        const now = performance.now();
+        detailPhaseTimingsMs[phase] = Number((now - detailTimingMark).toFixed(2));
+        detailTimingMark = now;
+      };
+      const readiness = await controllerReadinessEvidence(ctx, repository);
+      markDetailPhase('readiness');
+      const liveGit = gitSnapshot(repository.canonicalRoot);
+      markDetailPhase('git');
+      // Compare startup Runtime Source against the Controller package authority —
+      // never against the selected execution repository.
+      const runtimeSource = runtimeSourceSnapshotStatus(readiness.daemon.source, ctx.runtimeSourceRoot);
+      const sourceSnapshotStale = runtimeSource.restartRequired;
+      const exposure = controllerExposureSnapshot(ctx);
+      const localRegisteredToolNames = allControllerToolDefinitions(ctx).map((tool) => tool.name).sort();
+      markDetailPhase('tool_surface');
+      const toolSurfaceReady = exposure.ready && exposure.missingToolNames.length === 0;
+      // Ordinary interactive execution depends on the execution axis only.
+      // Maintenance debt / durable queue debt are reported as separate
+      // semantics and must not promote ordinary work into repair flows.
+      const executionReady = readiness.semantics.executionReady;
+      let maintenanceHealthy: boolean | null = null;
+      let maintenanceCandidateCount: number | null = null;
+      let maintenanceObservation: 'not_requested' | 'observed' | 'unavailable' = 'not_requested';
+      // A full maintenance pass traverses runtime storage, retained Work and
+      // temp roots. It is a diagnostic with a dedicated typed tool, not a
+      // prerequisite for an ordinary detailed status read. Do not hide that
+      // cost behind a cross-request cache or represent unobserved debt as
+      // healthy; callers can opt in when that diagnostic changes a decision.
+      if (args.include_maintenance === true) {
+        try {
+          const maintenance = buildRuntimeMaintenanceStatus(repository, ctx.controllerHome, { maxCandidates: 20 });
+          // stale_runtime_temp_entry is non-blocking by design (the executor
+          // excludes it from readyForExecution), so it is not maintenance debt.
+          const blockingCandidates = maintenance.candidates.filter((candidate) => candidate.kind !== 'stale_runtime_temp_entry');
+          maintenanceHealthy = blockingCandidates.length === 0;
+          maintenanceCandidateCount = blockingCandidates.length;
+          maintenanceObservation = 'observed';
+        } catch {
+          maintenanceHealthy = null;
+          maintenanceObservation = 'unavailable';
+        }
+      }
+      markDetailPhase('maintenance');
+      const effectiveReady = executionReady && toolSurfaceReady && !sourceSnapshotStale;
+      const readinessReasons = [...readiness.reasons];
+      if (!toolSurfaceReady) {
+        readinessReasons.push({
+          code: 'MCP_TOOL_SURFACE_INCOMPLETE',
+          message: `MCP schema mismatch: missing=${exposure.missingToolNames.length}, duplicates=${exposure.duplicateToolNames.length}.`,
+        });
+      }
+      if (sourceSnapshotStale) {
+        readinessReasons.push({
+          code: runtimeSource.code === 'RUNTIME_SOURCE_SNAPSHOT_MISSING'
+            ? 'RUNTIME_SOURCE_SNAPSHOT_MISSING'
+            : runtimeSource.code === 'RUNTIME_SOURCE_CURRENT_UNAVAILABLE'
+              ? 'RUNTIME_SOURCE_CURRENT_UNAVAILABLE'
+              : 'RUNTIME_SOURCE_SNAPSHOT_STALE',
+          message: formatRuntimeSourceDriftMessage(runtimeSource),
+        });
+      }
+      const toolSurfaceComputed = exposure.expectedToolNames.length > 0 || exposure.actualToolNames.length > 0 || toolSurfaceReady;
+      const readinessWithToolSurface = {
+        ready: effectiveReady,
+        reasonCodes: [...new Set(
+          readinessReasons
+            .map((reason) => reason.code)
+            .filter((code): code is string => typeof code === 'string' && code.length > 0),
+        )],
+        diagnostics: {
+          runtime: {
+            ready: readiness.ready,
+          },
+          toolSurface: {
+            ready: toolSurfaceReady,
+            // An uncomputed exposure is explicitly unknown, never a false 0/0.
+            expectedToolCount: toolSurfaceComputed ? exposure.expectedToolNames.length : null,
+            actualToolCount: toolSurfaceComputed ? exposure.actualToolNames.length : null,
+            observation: toolSurfaceComputed ? 'computed' : 'unknown',
+            missingTools: exposure.missingToolNames,
+            unexpectedTools: exposure.unexpectedToolNames,
+            duplicateTools: exposure.duplicateToolNames,
+            fingerprint: exposure.fingerprint,
+            schemaStableAcrossAccessModes: exposure.schemaStableAcrossAccessModes,
+          },
+          semantics: {
+            executionReady,
+            maintenanceHealthy,
+            maintenanceCandidateCount,
+            maintenanceObservation,
+            releaseReady: readiness.semantics.releaseReady,
+            executionBlockers: readiness.semantics.reasons.executionReady.map((reason) => reason.code),
+            releaseBlockers: readiness.semantics.reasons.releaseReady.map((reason) => reason.code),
+          },
+          sourceCoherence: {
+            ready: !sourceSnapshotStale,
+            reasons: runtimeSource.reasons,
+          },
+        },
+        observedAt: new Date().toISOString(),
+      };
+      // Always prefer stored plugin manifests on rh_status detail. Live host probes
+      // (Xcode/simctl, etc.) must not stall Managed MCP gateways on reconnect/status.
+      const manifests = listAssistantPluginManifests(ctx.controllerHome, repository, {
+        preferStored: true,
+        // rh_status detail is still a read path. Missing materialized plugin
+        // projections remain unknown until explicit discovery/execution refreshes
+        // them; status must never synchronously probe provider hosts.
+        fallbackToLive: false,
+      });
+      const capabilities = listCapabilityDescriptors(manifests);
+      markDetailPhase('plugins');
+      const pendingHandoffAttention = listHandoffAttentionItems(store, 100);
+      const pendingHandoffs = pendingHandoffAttention.slice(0, 20);
+      const pendingHandoffCount = pendingHandoffAttention.length;
+      const activeWorkProjection = readActiveWorkCandidates({ ...store, limit: 200 });
+      const activeContracts = activeWorkProjection.contracts;
+      markDetailPhase('work_state');
+      const activePrimaryWork = activeContracts.filter((contract) => (contract.lifecycleRole ?? 'primary') === 'primary');
+      const activeExecutionChildren = activeContracts.filter((contract) => contract.lifecycleRole === 'execution_child');
+      // Current Runtime activity is owned by the in-memory Process monitor set.
+      // Do not route an interactive status read through the retired cross-restart
+      // recovery index, which may contain historical starting/running records.
+      const activeProcessRecords = processRuntimeResourceDiagnostics().activeProcessIds
+        .map((processId) => getProcessRecord(ctx.controllerHome, repository.repoId, processId))
+        .filter((process): process is NonNullable<typeof process> => Boolean(process && isManagedProcessActive(process)));
+      markDetailPhase('process_state');
+      const activeProcessWorkIds = new Set(activeProcessRecords.map((process) => process.workId).filter((workId): workId is string => Boolean(workId)));
+      const activeControllerWorkIds = new Set(activePrimaryWork.filter((contract) => Boolean(getControllerSession({ controllerHome: ctx.controllerHome, repoId: repository.repoId }, contract.workId))).map((contract) => contract.workId));
+      const executingPrimaryWorkIds = new Set([...activeProcessWorkIds, ...activeControllerWorkIds].filter((workId) => activePrimaryWork.some((contract) => contract.workId === workId)));
+      markDetailPhase('controller_sessions');
+      const preferredFacadeTools = ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work'] as const;
+      const facade = buildFacadeResult({
+        status: effectiveReady ? 'ok' : 'blocked',
+        summary: effectiveReady ? 'Controller and MCP tool surface are ready for bounded work.' : 'Controller or MCP tool surface needs attention before work.',
+        data: {
+          operation,
+          repoId: repository.repoId,
+          readiness: readinessWithToolSurface,
+          repositoryState: {
+            ...liveGit,
+            observedAt: new Date().toISOString(),
+            sourceSnapshotAgeMs: readiness.daemon.source?.observedAt
+              ? Math.max(0, Date.now() - Date.parse(readiness.daemon.source.observedAt))
+              : undefined,
+            sourceSnapshotStale,
+            sourceSnapshotReasons: runtimeSource.reasons,
+            runtimeSourceDirty: runtimeSource.current?.dirty === true,
+          },
+          capabilityCount: capabilities.length,
+          capabilityGroups: summarizeCapabilityGroups(manifests),
+          toolArchitecture: {
+            facadeTools: [...preferredFacadeTools],
+            atomicTypedToolsRetained: true,
+            internalHandlersRetained: true,
+            domainSchemaLoading: 'static_stable_surface',
+            dynamicDomainSchemaLoadingSupported: false,
+          },
+          pendingHandoffCount,
+          // User-facing Work count means objective-level primary lanes. Low-level
+          // resumable operation handles are reported separately.
+          activeWorkCount: activePrimaryWork.length,
+          activePrimaryWorkCount: activePrimaryWork.length,
+          activeExecutionChildCount: activeExecutionChildren.length,
+          activeProcessCount: activeProcessRecords.length,
+          executingPrimaryWorkCount: executingPrimaryWorkIds.size,
+          waitingPrimaryWorkCount: Math.max(0, activePrimaryWork.length - executingPrimaryWorkIds.size),
+          activeContractCount: activeContracts.length,
+          invalidActiveContractCount: activeWorkProjection.invalid.length,
+          invalidActiveContracts: activeWorkProjection.invalid.slice(0, 10).map(summarizeInvalidActiveWorkCandidate),
+          // Summary keeps the stable facade surface only; detail expands to the full registered schema.
+          toolSurface: detailLevel === 'detail'
+            ? exposure.actualToolNames
+            : preferredFacadeTools.filter((name) => exposure.actualToolNames.includes(name)),
+          toolSurfaceStatus: readinessWithToolSurface.diagnostics.toolSurface,
+          access: exposure.access,
+        },
+        suggestedNextActions: pendingHandoffs.length > 0 ? [{
+          label: 'Review pending handoffs',
+          tool: 'rh_inbox',
+          operation: 'list',
+          risk: 'readonly',
+          confidence: 'high',
+        }] : [{
+          label: 'Read repository context',
+          tool: 'rh_context',
+          operation: 'get',
+          risk: 'readonly',
+          confidence: 'medium',
+        }],
+        rawAvailable: detailLevel === 'detail',
+        detailLevel,
+      });
+      markDetailPhase('response_build');
+      const payload = facade as unknown as Record<string, unknown>;
+      payload.responseMeta = {
+        serverDurationMs: Number((performance.now() - detailTimingStartedAt).toFixed(2)),
+        phaseTimingsMs: detailPhaseTimingsMs,
+      };
+      return result(payload, facade.status !== 'ok');
+  }
+  if (name === 'rh_inbox') {
+    return await callInboxAdapter(ctx, args);
+  }
+  return undefined;
+}
+
+async function callInboxAdapter(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): Promise<CallToolResult> {
+  const repository = selected(ctx, args);
+  const operation = String(args.operation ?? 'list');
+  if (!allowedFacadeOperations('rh_inbox').includes(operation)) return invalidFacadeOperation('rh_inbox', operation);
+  const app = await runHandoffInboxApplication({
+    operation: operation as 'get' | 'list' | 'ack' | 'accept' | 'resolve' | 'dismiss' | 'create',
+    store: { controllerHome: ctx.controllerHome, repoId: repository.repoId },
+    handoffId: typeof args.handoff_id === 'string' ? args.handoff_id : undefined,
+    limit: typeof args.limit === 'number' ? args.limit : undefined,
+    workId: typeof args.work_id === 'string' ? args.work_id : undefined,
+    title: typeof args.title === 'string' ? args.title : undefined,
+    reason: typeof args.reason === 'string' ? args.reason : undefined,
+    summary: typeof args.summary === 'string' ? args.summary : undefined,
+    attemptedActions: Array.isArray(args.attempted_actions) ? args.attempted_actions.map(String) : undefined,
+    blockingDecision: typeof args.blocking_decision === 'string' ? args.blocking_decision : undefined,
+    recommendedDecision: typeof args.recommended_decision === 'string' ? args.recommended_decision : undefined,
+    recommendedPrompt: typeof args.recommended_prompt === 'string' ? args.recommended_prompt : undefined,
+    recommendedContinuationPrompt: typeof args.recommended_continuation_prompt === 'string' ? args.recommended_continuation_prompt : undefined,
+    decision: typeof args.decision === 'string' ? args.decision : undefined,
+    resolver: typeof args.resolver === 'string' ? args.resolver : undefined,
+    controllerIdentity: { principalId: ctx.principalId, sessionId: ctx.sessionId },
+  }, {
+    triggerResolvedContinuation: (item) => triggerWorkContinuationRepositoryEvent(
+      ctx.controllerHome,
+      repository.repoId,
+      handoffResolvedContinuationEventName(item.id),
+      `handoff:${item.id}:${item.updatedAt}`,
+      { workId: item.workId, data: { handoffId: item.id, status: item.status, decision: item.decision } },
+    ),
+  });
+  if (operation === 'get') {
+    const item = 'item' in app ? app.item : undefined;
+    const facade = buildFacadeResult({
+      status: item ? 'ok' : 'not_found',
+      summary: item ? `Handoff ${item.id}.` : 'Handoff item not found.',
+      data: { item },
+      suggestedNextActions: item && item.status === 'pending'
+        ? [{ label: 'Acknowledge handoff', tool: 'rh_inbox', operation: 'ack', payload: { handoff_id: item.id }, risk: 'readonly' }]
+        : [],
+    });
+    return result(facade as unknown as Record<string, unknown>, facade.status === 'not_found');
+  }
+  if (operation === 'list') {
+    const items = 'items' in app && Array.isArray(app.items) ? app.items : [];
+    return result(buildFacadeResult({
+      summary: items.length ? `${items.length} pending handoff item(s).` : 'No pending handoff items.',
+      data: { items: items.map(summarizeHandoffItem) },
+      suggestedNextActions: items.slice(0, 1).map((item) => ({ label: `Read ${item.id}`, tool: 'rh_inbox', operation: 'get', payload: { handoff_id: item.id }, risk: 'readonly' as const })),
+    }) as unknown as Record<string, unknown>);
+  }
+  const item = 'item' in app ? app.item : undefined;
+  if (!item) throw new Error(`HANDOFF_APPLICATION_RESULT_INVALID:${operation}`);
+  if (operation === 'resolve') {
+    return result(buildFacadeResult({
+      summary: `Resolved handoff ${item.id}.`,
+      data: { item: { id: item.id, status: item.status, decision: item.decision, resolver: item.resolver }, continuationOccurrences: 'continuationOccurrences' in app ? app.continuationOccurrences : [] },
+    }) as unknown as Record<string, unknown>);
+  }
+  if (operation === 'dismiss') {
+    return result(buildFacadeResult({
+      summary: `Dismissed handoff ${item.id}.`,
+      data: { item: { id: item.id, status: item.status, decision: item.decision, resolver: item.resolver } },
+    }) as unknown as Record<string, unknown>);
+  }
+  if (operation === 'create') {
+    return result(buildFacadeResult({
+      summary: `Created handoff ${item.id}.`,
+      data: { item: summarizeHandoffItem(item), ownershipReleased: 'ownershipReleased' in app ? app.ownershipReleased : false },
+    }) as unknown as Record<string, unknown>);
+  }
+  return result(buildFacadeResult({
+    summary: `${operation === 'accept' ? 'Accepted' : 'Acknowledged'} handoff ${item.id}.`,
+    data: { item },
+    suggestedNextActions: item.suggestedNextActions,
+  }) as unknown as Record<string, unknown>);
+}