@moretea-labs/forge 1.6.0 → 1.7.1

package/scripts/benchmark-background-check-overlap.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env bun
+
+/**
+ * Executable goal-drift guard for the managed-check controller path.
+ *
+ * It deliberately performs useful rh_context work after run_check returns and
+ * before its one final dependency join. A future change that turns this into
+ * periodic process_wait polling, re-executes the check, or blocks the initial
+ * handle return fails the benchmark rather than only a local Process test.
+ */
+
+import { execFileSync } from 'child_process';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { performance } from 'perf_hooks';
+import { createMcpToolContext } from '../src/cli/mcp/server';
+import { registerRepository } from '../src/cli/repositories/registry';
+import { callRuntimeTool } from '../src/runtime/gateway/mcp/runtime-tools';
+import { callProcessTool } from '../src/runtime/gateway/mcp/process-tools';
+import { routeDurableMcpCall } from '../src/runtime/gateway/mcp/router';
+import { getProcessRecord } from '../src/runtime/execution/process-runtime/store';
+import {
+  clearGitIdentityCacheForTest,
+  clearGitSnapshotCacheForTest,
+  gitSnapshotPerformanceSnapshot,
+} from '../src/cli/repository/inspector';
+
+const CHECK_DURATION_MS = 1_200;
+const MAX_INITIAL_HANDLE_LATENCY_MS = 700;
+const MAX_TERMINAL_OBSERVATION_LATENCY_MS = 1_000;
+const root = mkdtempSync(join(tmpdir(), 'forge-background-check-overlap-'));
+const controllerHome = join(root, 'controller');
+const repoRoot = join(root, 'repo');
+
+const behavioralContract = {
+  originalUserFacingGoal: 'A long focused check must run in the background while Forge continues useful independent work, then synchronize once at the true dependency boundary.',
+  invariants: {
+    backgroundCheck: 'long_check_returns_a_managed_handle_promptly',
+    noPollingWhileUsefulWorkExists: 'zero_process_wait_calls_before_independent_work_finishes',
+    dependencyDrivenJoin: 'one_final_process_wait_after_the_dependency_boundary',
+    exactlyOnce: 'one_physical_check_execution',
+    resultCorrectness: 'terminal_result_matches_the_returned_process_id',
+    noAdditionalOrchestration: 'no_execution_job_created_for_the_fast_check_route',
+    sourceRetrievalStaysFocused: 'ordinary_rh_context_search_skips_execution_preflight',
+    summaryStaysCheap: 'rh_status_summary_avoids_detail_diagnostics',
+  },
+  antiGoals: [
+    'periodic_process_wait_polling',
+    'synchronous_wait_before_independent_work',
+    'duplicate_check_execution',
+    'source_retrieval_building_unrequested_check_readiness',
+    'summary_status_triggering_detail_diagnostics',
+  ],
+  validation: 'Runs a real managed check, performs rh_context work before the sole join, and separately asserts the rh_status summary hot path.',
+};
+
+function percentile(values: number[], ratio: number): number {
+  const sorted = [...values].sort((left, right) => left - right);
+  return Math.round((sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * ratio))] ?? 0) * 100) / 100;
+}
+
+try {
+  mkdirSync(join(repoRoot, 'src'), { recursive: true });
+  mkdirSync(join(repoRoot, '.forge'), { recursive: true });
+  execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: repoRoot });
+  execFileSync('git', ['config', 'user.email', 'benchmark@example.test'], { cwd: repoRoot });
+  execFileSync('git', ['config', 'user.name', 'Forge Benchmark'], { cwd: repoRoot });
+  writeFileSync(join(repoRoot, 'src', 'fixture.ts'), 'export const backgroundFixture = true;\n');
+  const executionMarker = join(root, 'physical-check-executions.txt');
+  writeFileSync(join(repoRoot, '.forge', 'checks.json'), JSON.stringify({
+    version: 1,
+    checks: {
+      background: {
+        description: 'Synthetic long check for controller overlap behavior.',
+        command: [
+          process.execPath,
+          '-e',
+          [
+            `require('fs').appendFileSync(${JSON.stringify(executionMarker)}, '1');`,
+            `setTimeout(() => { process.stdout.write('BACKGROUND_CHECK_DONE\\n'); process.exit(0); }, ${CHECK_DURATION_MS});`,
+          ].join(' '),
+        ],
+        timeoutMs: 10_000,
+      },
+    },
+  }, null, 2));
+  execFileSync('git', ['add', '.'], { cwd: repoRoot });
+  execFileSync('git', ['commit', '-qm', 'fixture'], { cwd: repoRoot });
+
+  const repository = registerRepository({ path: repoRoot, controllerHome, displayName: 'background-check-overlap' });
+  const ctx = createMcpToolContext({ controllerHome, profile: 'controller', repo: repoRoot });
+
+  const startedAt = performance.now();
+  const started = await routeDurableMcpCall(ctx, 'run_check', {
+    repo_id: repository.repoId,
+    check_id: 'background',
+    interactive_wait_ms: 0,
+  });
+  const initialHandleLatencyMs = performance.now() - startedAt;
+  const startPayload = started?.structuredContent as Record<string, unknown> | undefined;
+  const processId = typeof startPayload?.processId === 'string' ? startPayload.processId : '';
+
+  const independentStartedAt = performance.now();
+  const independent = await callRuntimeTool(ctx, 'rh_context', {
+    repo_id: repository.repoId,
+    operation: 'search',
+    query: 'backgroundFixture',
+    known_paths: ['src/fixture.ts'],
+    structural_context: 'off',
+  });
+  const independentOperationLatencyMs = performance.now() - independentStartedAt;
+  const independentPayload = independent?.structuredContent as { data?: Record<string, unknown> } | undefined;
+  const independentData = independentPayload?.data;
+  const independentRetrievalPolicy = independentData?.retrievalPolicy as Record<string, unknown> | undefined;
+  const sourceRetrievalSkippedExecutionPreflight = independentData?.executionReadiness === undefined
+    && independentData?.registeredChecks === undefined
+    && independentRetrievalPolicy?.executionReadiness === 'requested_check_ids_only';
+  const processWaitCallsBeforeDependencyBoundary = 0;
+
+  const joinStartedAtMs = Date.now();
+  const joined = processId
+    ? await callProcessTool(ctx, 'process_wait', {
+      repo_id: repository.repoId,
+      process_id: processId,
+      timeout_ms: 10_000,
+    })
+    : undefined;
+  const resultObservedAtMs = Date.now();
+  const finalSynchronizationCount = processId ? 1 : 0;
+  const joinedPayload = joined?.structuredContent as { process?: { processId?: string; completed?: boolean; ok?: boolean } } | undefined;
+  const record = processId ? getProcessRecord(controllerHome, repository.repoId, processId) : undefined;
+  const finishedAtMs = record?.finishedAt ? Date.parse(record.finishedAt) : NaN;
+  const completionToObservationLatencyMs = Number.isFinite(finishedAtMs)
+    ? Math.max(0, resultObservedAtMs - finishedAtMs)
+    : undefined;
+  const physicalExecutionCount = readFileSync(executionMarker, 'utf8').length;
+
+  // Summary is a separate hot path: it must answer readiness without falling
+  // into the full Git status/diff-stat or maintenance/detail projection.
+  clearGitIdentityCacheForTest();
+  clearGitSnapshotCacheForTest();
+  const statusSummaryDurations: number[] = [];
+  let summaryPayload: Record<string, unknown> | undefined;
+  for (let iteration = 0; iteration < 7; iteration += 1) {
+    const statusStartedAt = performance.now();
+    const status = await callRuntimeTool(ctx, 'rh_status', { repo_id: repository.repoId, detail_level: 'summary' });
+    statusSummaryDurations.push(performance.now() - statusStartedAt);
+    summaryPayload = status?.structuredContent as Record<string, unknown> | undefined;
+  }
+  // Snapshot this before the intentional detail call below: detail is allowed
+  // to build the full Git projection, while summary is not.
+  const summaryGitSnapshot = gitSnapshotPerformanceSnapshot();
+  const detailStartedAt = performance.now();
+  const detail = await callRuntimeTool(ctx, 'rh_status', { repo_id: repository.repoId, detail_level: 'detail' });
+  const detailElapsedMs = performance.now() - detailStartedAt;
+  const detailPayload = detail?.structuredContent as Record<string, unknown> | undefined;
+  const detailMeta = detailPayload?.responseMeta as Record<string, unknown> | undefined;
+  const summaryData = summaryPayload?.data as Record<string, unknown> | undefined;
+  const summaryRepositoryState = summaryData?.repositoryState as Record<string, unknown> | undefined;
+  const summaryUsesCompactPayload = Boolean(summaryData)
+    && summaryData?.access === undefined
+    && summaryData?.pendingHandoffCount === undefined
+    && summaryData?.activeWorkCount === undefined
+    && summaryData?.activeProcessCount === undefined
+    && summaryRepositoryState?.status === undefined
+    && summaryRepositoryState?.diffStat === undefined;
+
+  const assertions = {
+    initialManagedHandle: Boolean(processId) && startPayload?.path === 'process_managed' && initialHandleLatencyMs <= MAX_INITIAL_HANDLE_LATENCY_MS,
+    independentUsefulOperation: independent?.isError !== true,
+    sourceRetrievalSkipsExecutionPreflight: sourceRetrievalSkippedExecutionPreflight,
+    noPollingBeforeDependencyBoundary: processWaitCallsBeforeDependencyBoundary === 0,
+    oneDependencyJoin: finalSynchronizationCount === 1,
+    exactlyOnce: physicalExecutionCount === 1,
+    terminalResultCorrect: joinedPayload?.process?.processId === processId && joinedPayload?.process?.completed === true && joinedPayload?.process?.ok === true,
+    promptResultObservation: completionToObservationLatencyMs === undefined || completionToObservationLatencyMs <= MAX_TERMINAL_OBSERVATION_LATENCY_MS,
+    statusSummaryUsesCompactProjection: Boolean(summaryPayload?.data)
+      && summaryGitSnapshot.refreshes === 0
+      && summaryGitSnapshot.subprocesses === 0
+      && summaryUsesCompactPayload,
+  };
+  const output = {
+    schemaVersion: 1,
+    behavioralContract,
+    check: {
+      configuredDurationMs: CHECK_DURATION_MS,
+      initialManagedHandleLatencyMs: Number(initialHandleLatencyMs.toFixed(2)),
+      processWaitCallsBeforeDependencyBoundary,
+      independentOperation: {
+        tool: 'rh_context.search',
+        latencyMs: Number(independentOperationLatencyMs.toFixed(2)),
+        completed: independent?.isError !== true,
+        executionPreflight: sourceRetrievalSkippedExecutionPreflight ? 'not_requested' : 'unexpected',
+      },
+      finalSynchronizationCount,
+      finalJoinDurationMs: resultObservedAtMs - joinStartedAtMs,
+      physicalExecutionCount,
+      terminalCompletionToObservationLatencyMs: completionToObservationLatencyMs,
+      processId,
+    },
+    status: {
+      summaryP50Ms: percentile(statusSummaryDurations, 0.5),
+      summaryP95Ms: percentile(statusSummaryDurations, 0.95),
+      detailElapsedMs: Number(detailElapsedMs.toFixed(2)),
+      detailServerDurationMs: detailMeta?.serverDurationMs,
+      detailPhaseTimingsMs: detailMeta?.phaseTimingsMs,
+      fullGitSnapshot: summaryGitSnapshot,
+      summaryOmissions: {
+        maintenance: true,
+        plugins: true,
+        workState: true,
+        accessPolicy: true,
+        gitStatusAndDiffStat: true,
+      },
+    },
+    thresholds: {
+      initialManagedHandleLatencyMs: MAX_INITIAL_HANDLE_LATENCY_MS,
+      terminalCompletionToObservationLatencyMs: MAX_TERMINAL_OBSERVATION_LATENCY_MS,
+    },
+    assertions,
+    passed: Object.values(assertions).every(Boolean),
+  };
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+  if (!output.passed) process.exitCode = 1;
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}

package/scripts/benchmark-mcp-host.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BUN_BIN="${BUN_BIN:-bun}"
+LABEL="${FORGE_MCP_BENCH_LABEL:-host-runtime-direct}"
+PORT="${FORGE_MCP_BENCH_PORT:-18765}"
+ITERATIONS="${FORGE_MCP_BENCH_ITERATIONS:-50}"
+CONNECT_ITERATIONS="${FORGE_MCP_BENCH_CONNECT_ITERATIONS:-30}"
+
+for value in "$PORT" "$ITERATIONS" "$CONNECT_ITERATIONS"; do
+  if ! [[ "$value" =~ ^[0-9]+$ ]] || [[ "$value" == "0" ]]; then
+    echo "benchmark:mcp-host requires positive integer port/iteration values" >&2
+    exit 2
+  fi
+done
+if (( PORT < 1024 || PORT > 65535 )); then
+  echo "FORGE_MCP_BENCH_PORT must be between 1024 and 65535" >&2
+  exit 2
+fi
+
+TMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/forge-mcp-host-bench.XXXXXX")"
+CONTROLLER_HOME="$TMP_ROOT/controller-home"
+REGISTER_JSON="$TMP_ROOT/repository.json"
+INSTALL_JSON="$TMP_ROOT/runtime-install.json"
+READY_JSON="$TMP_ROOT/runtime-ready.json"
+STEADY_JSON="$TMP_ROOT/steady.json"
+CONNECT_JSON="$TMP_ROOT/connect.json"
+RUNTIME_PID=""
+
+cleanup() {
+  if [[ -n "$RUNTIME_PID" ]] && kill -0 "$RUNTIME_PID" 2>/dev/null; then
+    kill "$RUNTIME_PID" 2>/dev/null || true
+    for _ in $(seq 1 20); do
+      kill -0 "$RUNTIME_PID" 2>/dev/null || break
+      sleep 0.1
+    done
+    kill -9 "$RUNTIME_PID" 2>/dev/null || true
+  fi
+  for _ in $(seq 1 5); do
+    rm -rf "$TMP_ROOT" 2>/dev/null && return 0
+    sleep 0.1
+  done
+  rm -rf "$TMP_ROOT" 2>/dev/null || true
+}
+trap cleanup EXIT INT TERM
+
+TOKEN="$(node -e "process.stdout.write(require('crypto').randomBytes(32).toString('hex'))")"
+export FORGE_MCP_TOKEN="$TOKEN"
+export FORGE_MCP_BENCH_TOKEN="$TOKEN"
+
+cd "$ROOT"
+"$BUN_BIN" bin/forge.mjs repo register "$ROOT" \
+  --controller-home "$CONTROLLER_HOME" \
+  --json > "$REGISTER_JSON"
+REPO_ID="$(node -e "const x=require(process.argv[1]); const id=x?.repository?.repoId; if(!id) process.exit(2); process.stdout.write(id)" "$REGISTER_JSON")"
+
+"$BUN_BIN" bin/forge.mjs runtime service install-package \
+  --controller-home "$CONTROLLER_HOME" \
+  --host 127.0.0.1 \
+  --port "$PORT" \
+  --portable > "$INSTALL_JSON"
+RUNTIME_PID="$(node -e "const x=require(process.argv[1]); const pid=x?.pid; if(!Number.isInteger(pid)||pid<=0) process.exit(2); process.stdout.write(String(pid))" "$INSTALL_JSON")"
+
+curl --fail --silent --show-error \
+  --retry 30 --retry-delay 1 --retry-connrefused \
+  "http://127.0.0.1:${PORT}/ready" > "$READY_JSON"
+
+"$BUN_BIN" run benchmark:mcp-transport -- \
+  --endpoint "http://127.0.0.1:${PORT}/mcp" \
+  --label "$LABEL" \
+  --repo-id "$REPO_ID" \
+  --tool rh_status \
+  --iterations "$ITERATIONS" \
+  --warmup 3 \
+  --timing-log "$CONTROLLER_HOME/audit/mcp-timings.jsonl" > "$STEADY_JSON"
+
+"$BUN_BIN" run benchmark:mcp-transport -- \
+  --endpoint "http://127.0.0.1:${PORT}/mcp" \
+  --label "$LABEL" \
+  --repo-id "$REPO_ID" \
+  --tool rh_status \
+  --iterations "$CONNECT_ITERATIONS" \
+  --warmup 0 \
+  --include-connect \
+  --timing-log "$CONTROLLER_HOME/audit/mcp-timings.jsonl" > "$CONNECT_JSON"
+
+node - "$STEADY_JSON" "$CONNECT_JSON" "$READY_JSON" <<'NODE'
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const [steadyPath, connectPath, readyPath] = process.argv.slice(2);
+const steady = JSON.parse(fs.readFileSync(steadyPath, 'utf8'));
+const connect = JSON.parse(fs.readFileSync(connectPath, 'utf8'));
+const ready = JSON.parse(fs.readFileSync(readyPath, 'utf8'));
+const report = {
+  schemaVersion: 1,
+  generatedAt: new Date().toISOString(),
+  host: {
+    platform: process.platform,
+    arch: process.arch,
+    cpuCount: os.cpus().length,
+    totalMemoryBytes: os.totalmem(),
+  },
+  ready,
+  steady,
+  connectInclusive: connect,
+};
+const text = `${JSON.stringify(report, null, 2)}\n`;
+const output = process.env.FORGE_MCP_BENCH_OUTPUT?.trim();
+if (output) {
+  const target = path.resolve(output);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, text, 'utf8');
+}
+process.stdout.write(text);
+NODE

package/scripts/benchmark-mcp-transport.ts

@@ -0,0 +1,170 @@
+#!/usr/bin/env bun
+import { readFileSync } from 'fs';
+import { performance } from 'perf_hooks';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { readMcpServiceBearerToken } from '../src/cli/mcp/auth';
+import { resolveRepoPreferredControllerHome } from '../src/cli/repositories/controller-home';
+import {
+  aggregateMcpTransportLatencySamples,
+  extractForgeServerDuration,
+  normalizeMcpTransportLatencySample,
+  type McpTransportLatencySample,
+} from '../src/runtime/diagnostics/mcp-transport-benchmark';
+
+function option(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+function integerAtLeast(name: string, fallback: number, minimum: number): number {
+  const raw = option(name);
+  if (!raw) return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < minimum) {
+    const requirement = minimum === 0 ? 'a non-negative integer' : `an integer >= ${minimum}`;
+    throw new Error(`${name} must be ${requirement}`);
+  }
+  return value;
+}
+
+function positiveInteger(name: string, fallback: number): number {
+  return integerAtLeast(name, fallback, 1);
+}
+
+function readSamples(path: string): McpTransportLatencySample[] {
+  const text = readFileSync(path, 'utf8').trim();
+  if (!text) return [];
+  if (text.startsWith('[')) {
+    const values = JSON.parse(text);
+    if (!Array.isArray(values)) throw new Error('--input JSON must be an array or JSONL');
+    return values.map(normalizeMcpTransportLatencySample);
+  }
+  return text.split(/\r?\n/).filter(Boolean).map((line) => normalizeMcpTransportLatencySample(JSON.parse(line)));
+}
+
+export function timingLedgerServerDuration(
+  path: string | undefined,
+  tool: string,
+  meta: Record<string, unknown>,
+): number | undefined {
+  if (!path) return undefined;
+  const traceId = typeof meta.traceId === 'string' ? meta.traceId : undefined;
+  const requestId = typeof meta.requestId === 'string' ? meta.requestId : undefined;
+  if (!traceId && !requestId) return undefined;
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return undefined;
+    const lines = text.split(/\r?\n/).filter(Boolean);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      let value: Record<string, unknown>;
+      try {
+        value = JSON.parse(lines[index]!) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (value.tool !== tool) continue;
+      if (traceId && value.traceId !== traceId) continue;
+      if (requestId && value.requestId !== requestId) continue;
+      const duration = value.totalToolDurationMs;
+      if (typeof duration === 'number' && Number.isFinite(duration) && duration >= 0) return duration;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+async function probe(): Promise<McpTransportLatencySample[]> {
+  const endpointRaw = option('--endpoint');
+  if (!endpointRaw) throw new Error('--endpoint is required unless --input is used');
+  const endpoint = new URL(endpointRaw);
+  const label = option('--label')?.trim() || endpoint.hostname;
+  const tool = option('--tool')?.trim() || 'rh_status';
+  const iterations = positiveInteger('--iterations', 30);
+  const warmup = integerAtLeast('--warmup', 3, 0);
+  const timeoutMs = positiveInteger('--timeout-ms', 120_000);
+  const timingLog = option('--timing-log')?.trim();
+  const includeConnect = process.argv.includes('--include-connect');
+  const timingScope = includeConnect ? 'connect_and_tool_call' as const : 'tool_call' as const;
+  const tokenEnv = option('--token-env')?.trim() || 'FORGE_MCP_BENCH_TOKEN';
+  const localServiceAuth = process.argv.includes('--local-service-auth');
+  const token = process.env[tokenEnv]?.trim()
+    || (localServiceAuth
+      ? readMcpServiceBearerToken(resolveRepoPreferredControllerHome(process.cwd()))?.trim()
+      : undefined);
+  if (!token) {
+    throw new Error(localServiceAuth
+      ? 'MCP_BENCH_LOCAL_SERVICE_TOKEN_UNAVAILABLE: no local Forge service bearer credential was found'
+      : `${tokenEnv} is not set; use --local-service-auth on the Forge host or keep benchmark bearer credentials in the environment, never CLI args`);
+  }
+  const argumentsRaw = option('--arguments');
+  const args = argumentsRaw ? JSON.parse(argumentsRaw) as Record<string, unknown> : {};
+  const repoId = option('--repo-id')?.trim();
+  if (repoId && args.repo_id === undefined) args.repo_id = repoId;
+
+  const createClient = () => {
+    const transport = new StreamableHTTPClientTransport(endpoint, {
+      requestInit: { headers: { Authorization: `Bearer ${token}` } },
+    });
+    const client = new Client({ name: 'forge-mcp-transport-benchmark', version: '1.0.0' });
+    return { client, transport };
+  };
+  const steadyState = includeConnect ? undefined : createClient();
+  const call = async (): Promise<{ response: unknown; totalMs: number }> => {
+    const connection = steadyState ?? createClient();
+    const started = performance.now();
+    try {
+      if (includeConnect) await connection.client.connect(connection.transport);
+      const response = await connection.client.callTool({ name: tool, arguments: args }, undefined, { timeout: timeoutMs });
+      return { response, totalMs: performance.now() - started };
+    } finally {
+      if (includeConnect) await connection.client.close().catch(() => undefined);
+    }
+  };
+  const samples: McpTransportLatencySample[] = [];
+  try {
+    if (steadyState) await steadyState.client.connect(steadyState.transport);
+    for (let index = 0; index < warmup; index += 1) await call();
+    for (let index = 0; index < iterations; index += 1) {
+      const { response, totalMs } = await call();
+      const structured = response && typeof response === 'object' && !Array.isArray(response)
+        ? (response as Record<string, unknown>).structuredContent
+        : undefined;
+      const responseMeta = structured && typeof structured === 'object' && !Array.isArray(structured)
+        ? (structured as Record<string, unknown>).responseMeta
+        : undefined;
+      const meta = responseMeta && typeof responseMeta === 'object' && !Array.isArray(responseMeta)
+        ? responseMeta as Record<string, unknown>
+        : {};
+      const serverDurationMs = extractForgeServerDuration(response)
+        ?? timingLedgerServerDuration(timingLog, tool, meta);
+      if (serverDurationMs === undefined) {
+        throw new Error('MCP_SERVER_DURATION_MISSING: target must return Forge responseMeta.serverDurationMs or expose a matching --timing-log ledger entry');
+      }
+      samples.push({
+        label,
+        tool,
+        timingScope,
+        clientTotalMs: totalMs,
+        serverDurationMs,
+        ...(typeof meta.traceId === 'string' ? { traceId: meta.traceId } : {}),
+        ...(typeof meta.requestId === 'string' ? { requestId: meta.requestId } : {}),
+        observedAt: new Date().toISOString(),
+      });
+    }
+  } finally {
+    if (steadyState) await steadyState.client.close().catch(() => undefined);
+  }
+  return samples;
+}
+
+if (import.meta.main) {
+  const input = option('--input');
+  const samples = input ? readSamples(input) : await probe();
+  const report = aggregateMcpTransportLatencySamples(samples);
+  console.log(JSON.stringify({
+    generatedAt: new Date().toISOString(),
+    ...report,
+  }, null, 2));
+}

package/scripts/benchmark-quality-harness.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env bun
+
+import { execFileSync, spawn } from 'child_process';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { performance } from 'perf_hooks';
+import { buildControllerContextPackAsync } from '../src/cli/controller/context-pack';
+import { getMcpPolicy } from '../src/cli/mcp/policy';
+import { closeCodeGraphReadProviderSessions } from '../src/runtime/context/codegraph-read-provider';
+import { clearAllSessionCachesForTest } from '../src/cli/repository/session-cache';
+import { startLightweightRepositoryCommand } from '../src/runtime/execution/process-runtime/lightweight-managed';
+import { registerRepository } from '../src/cli/repositories/registry';
+
+function percentile(values: number[], ratio: number): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return Math.round((sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * ratio))] ?? 0) * 100) / 100;
+}
+async function rawGitStatus(root: string): Promise<number> {
+  const started = performance.now();
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn('git', ['status', '--short'], { cwd: root, stdio: 'ignore' });
+    child.on('error', reject); child.on('close', () => resolve());
+  });
+  return performance.now() - started;
+}
+
+const iterationsIndex = process.argv.indexOf('--iterations');
+const iterations = Math.max(2, Number(iterationsIndex >= 0 ? process.argv[iterationsIndex + 1] : 7) || 7);
+const structuralIndex = process.argv.indexOf('--structural');
+const structuralContext = process.argv[structuralIndex + 1] === 'off' ? 'off' as const : 'auto' as const;
+const sandboxRoot = mkdtempSync(join(tmpdir(), 'forge-quality-harness-benchmark-'));
+const root = join(sandboxRoot, 'repo');
+const controllerHome = join(sandboxRoot, 'controller');
+try {
+  mkdirSync(root, { recursive: true });
+  execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: root });
+  execFileSync('git', ['config', 'user.email', 'benchmark@example.test'], { cwd: root });
+  execFileSync('git', ['config', 'user.name', 'Forge Benchmark'], { cwd: root });
+  mkdirSync(join(root, 'src'), { recursive: true });
+  for (let index = 0; index < 120; index += 1) {
+    writeFileSync(join(root, 'src', `module-${index}.ts`), `export function symbol${index}(value: number) {\n  return value + ${index};\n}\n`);
+  }
+  writeFileSync(join(root, 'src', 'target.ts'), 'export function benchmarkTarget(value: number) {\n  const next = value + 1;\n  return next;\n}\n');
+  writeFileSync(join(root, 'src', 'consumer.ts'), "import { benchmarkTarget } from './target';\nexport function consumeBenchmarkTarget(value: number) {\n  return benchmarkTarget(value) * 2;\n}\n");
+  execFileSync('git', ['add', '.'], { cwd: root }); execFileSync('git', ['commit', '-qm', 'fixture'], { cwd: root });
+  const repository = registerRepository({ path: root, controllerHome, displayName: 'quality-harness-benchmark' });
+
+  const contextCold: number[] = [];
+  const contextHot: number[] = [];
+  const structuralProcess: number[] = [];
+  const structuralOpen: number[] = [];
+  const structuralQuery: number[] = [];
+  let hotCacheEvidence: unknown;
+  let contextAccuracyEvidence: { selected: string[]; required: string[]; recall: number; precision: number } | undefined;
+  const requiredContextPaths = ['src/target.ts', 'src/consumer.ts'];
+  for (let index = 0; index < iterations; index += 1) {
+    clearAllSessionCachesForTest();
+    const session = { sessionId: `benchmark-${index}`, repoId: repository.repoId, checkoutId: repository.activeCheckoutId };
+    let started = performance.now();
+    const cold = await buildControllerContextPackAsync(root, getMcpPolicy('controller'), { description: 'benchmarkTarget implementation and impact', searchTerms: ['benchmarkTarget'], knownPaths: ['src/target.ts'], structuralContext, session });
+    contextCold.push(performance.now() - started);
+    const structuralTimings = cold.structuralContext?.timingsMs;
+    if (typeof structuralTimings?.process === 'number') structuralProcess.push(structuralTimings.process);
+    if (typeof structuralTimings?.open === 'number') structuralOpen.push(structuralTimings.open);
+    if (typeof structuralTimings?.query === 'number') structuralQuery.push(structuralTimings.query);
+    started = performance.now();
+    const hot = await buildControllerContextPackAsync(root, getMcpPolicy('controller'), { description: 'benchmarkTarget implementation and impact', searchTerms: ['benchmarkTarget'], knownPaths: ['src/target.ts'], structuralContext, session });
+    contextHot.push(performance.now() - started);
+    hotCacheEvidence = hot.cache;
+    const selected = [...new Set(hot.files.map((file) => file.path))].sort();
+    const requiredHits = requiredContextPaths.filter((path) => selected.includes(path)).length;
+    contextAccuracyEvidence = {
+      selected,
+      required: requiredContextPaths,
+      recall: requiredHits / requiredContextPaths.length,
+      precision: selected.length === 0 ? 0 : requiredHits / selected.length,
+    };
+  }
+
+  const rawChild: number[] = [];
+  const harnessTotal: number[] = [];
+  const preSpawnHarness: number[] = [];
+  for (let index = 0; index < iterations; index += 1) {
+    rawChild.push(await rawGitStatus(root));
+    const started = performance.now();
+    const run = await startLightweightRepositoryCommand({
+      controllerHome, repository, interactiveWaitMs: 5_000, timeoutMs: 30_000,
+      execution: {
+        command: ['git', 'status', '--short'],
+        authorizationDecision: { decision: 'allow', source: 'full_access', reason: 'benchmark fixture' },
+      },
+    });
+    harnessTotal.push(performance.now() - started);
+    if (run.metrics.preSpawnHarnessMs !== undefined) preSpawnHarness.push(run.metrics.preSpawnHarnessMs);
+  }
+
+  const steadyContextCold = contextCold.slice(1);
+  const output = {
+    schemaVersion: 1,
+    iterations,
+    context: {
+      structuralContext,
+      coldP50Ms: percentile(contextCold, 0.5), coldP95Ms: percentile(contextCold, 0.95),
+      startupColdMs: Math.round((contextCold[0] ?? 0) * 100) / 100,
+      steadyColdP50Ms: percentile(steadyContextCold, 0.5),
+      steadyColdP95Ms: percentile(steadyContextCold, 0.95),
+      coldSamplesMs: contextCold.map((value) => Math.round(value * 100) / 100),
+      structuralProcessP50Ms: percentile(structuralProcess, 0.5),
+      structuralProcessP95Ms: percentile(structuralProcess, 0.95),
+      structuralOpenP50Ms: percentile(structuralOpen, 0.5),
+      structuralQueryP50Ms: percentile(structuralQuery, 0.5),
+      hotP50Ms: percentile(contextHot, 0.5), hotP95Ms: percentile(contextHot, 0.95),
+      hotToColdRatio: Math.round((percentile(contextHot, 0.5) / Math.max(0.01, percentile(contextCold, 0.5))) * 1_000) / 1_000,
+      cacheEvidence: hotCacheEvidence,
+      accuracy: contextAccuracyEvidence,
+    },
+    command: {
+      rawChildP50Ms: percentile(rawChild, 0.5), lightweightTotalP50Ms: percentile(harnessTotal, 0.5),
+      preSpawnHarnessP50Ms: percentile(preSpawnHarness, 0.5),
+      preSpawnHarnessP95Ms: percentile(preSpawnHarness, 0.95),
+      durableProcessWrites: 0, leaseOperations: 0,
+    },
+    thresholds: {
+      hotContextToColdP50MaxRatio: 0.9,
+      contextRecallMin: 1,
+      contextPrecisionMin: 1,
+      lightweightPreSpawnHarnessP95MaxMs: 750,
+      durableProcessWritesMax: 0,
+      leaseOperationsMax: 0,
+    },
+  };
+  const assertions = {
+    hotContextReuse: output.context.hotToColdRatio <= output.thresholds.hotContextToColdP50MaxRatio,
+    completeRequiredContext: (output.context.accuracy?.recall ?? 0) >= output.thresholds.contextRecallMin,
+    boundedContextNoise: (output.context.accuracy?.precision ?? 0) >= output.thresholds.contextPrecisionMin,
+    boundedPreSpawnHarness: output.command.preSpawnHarnessP95Ms <= output.thresholds.lightweightPreSpawnHarnessP95MaxMs,
+    zeroDurableWrites: output.command.durableProcessWrites <= output.thresholds.durableProcessWritesMax,
+    zeroLeaseOperations: output.command.leaseOperations <= output.thresholds.leaseOperationsMax,
+  };
+  process.stdout.write(`${JSON.stringify({ ...output, assertions, passed: Object.values(assertions).every(Boolean) }, null, 2)}\n`);
+  if (!Object.values(assertions).every(Boolean)) process.exitCode = 1;
+} finally {
+  await closeCodeGraphReadProviderSessions();
+  rmSync(sandboxRoot, { recursive: true, force: true });
+}