@moretea-labs/forge 1.6.0 → 1.7.0

package/docs/operations/features.md

@@ -26,8 +26,8 @@ These features are part of the default local setup:
 | Tailscale / Cloudflare | Stable HTTPS endpoint for ChatGPT MCP | Tunnel client and appropriate account/domain configuration. |
 | Browser | Playwright navigation, screenshots, and bounded browser evidence | Browser binaries and HTTP(S) URL scheme validation. |
 | CodeGraph | Additional code relationships and impact navigation | CodeGraph CLI; native Windows automatic setup is not yet enabled. |
-| Google Workspace | Gmail and Calendar assistant actions | Explicit OAuth setup and plugin permission. |
-| Schedules and findings | Supervised recurring checks and candidate findings | Canonical Forge Runtime running; live actions remain policy-gated. |
+| Google Workspace | Gmail and Calendar plugin actions | Explicit OAuth setup and plugin permission. |
+| Schedules | Supervised recurring checks | Canonical Forge Runtime running; live actions remain policy-gated. |
 
 ## Tool exposure
 

package/docs/operations/github-repository.md

@@ -42,7 +42,7 @@ Use Issues for reproducible defects and scoped feature requests. Use Discussions
 
 ## Documentation ownership
 
-The GitHub Wiki is a presentation target. Versioned source lives under `docs/wiki/`. Deeper engineering detail remains under `docs/architecture/current/` and `docs/operations/`.
+The GitHub Wiki is a presentation target. Versioned source lives under `docs/wiki/`. Deeper engineering detail remains under `docs/architecture/CURRENT.md` and `docs/operations/`.
 
 Public documentation must distinguish current facts from historical evidence. Avoid hard-coding “next release” versions in operational runbooks; derive versions from `package.json` so routine releases do not leave stale docs behind.
 

package/docs/operations/homebrew.md

@@ -6,8 +6,8 @@ Homebrew is planned as a convenience layer after the first stable npm/GitHub rel
 
 Do not publish a formula until all of the following are true:
 
-- `@moretea-labs/forge@1.6.0` exists on npm;
-- Git tag and GitHub Release `v1.6.0` exist and point to the tested commit;
+- `@moretea-labs/forge@1.7.0` exists on npm;
+- Git tag and GitHub Release `v1.7.0` exist and point to the tested commit;
 - the npm tarball has an immutable checksum;
 - macOS installation and `forge --version` / `forge doctor` tests pass;
 - upgrade and uninstall behavior is documented.

package/docs/operations/mcp-tool-exposure.md

@@ -6,8 +6,9 @@ Controller MCP uses one stable default schema so ChatGPT can reliably read, edit
 
 | Toolset | CLI | Behavior |
 | --- | --- | --- |
-| **advanced** (default) | `--toolset advanced` | Stable repair-capable surface, capped at 128 tools. Includes the five `rh_*` facades plus high-value repository, Direct Edit, command, Git, Work/Job, Agent, Goal/Work, plugin, browser, iOS, artifact, and recovery tools. |
-| **core** | `--toolset core` | Compatibility label for the same stable default schema. It does not reduce capability or require reconnecting. |
+| **facade** (opt-in) | `--toolset facade` | Five-tool ChatGPT orchestration surface: `rh_access`, `rh_status`, `rh_inbox`, `rh_context`, `rh_work`. Internal handlers and capabilities remain registered; only MCP discovery is reduced. Intended for latency/tool-selection A/B before any default migration. |
+| **advanced** (default) | `--toolset advanced` | Current stable 19-tool controller surface. Includes the five `rh_*` facades plus repository, Direct Edit, command, check, plugin-dispatch, Process, and result/evidence tools. |
+| **core** | `--toolset core` | Compatibility label for the same stable default 19-tool schema. It does not reduce capability or require reconnecting. |
 | **full** | `--toolset full` | Every historical legacy and runtime definition. Use only for old integrations or deep compatibility diagnosis because the much larger schema can reduce tool-selection quality. |
 
 Configure via CLI flags, `FORGE_MCP_TOOLSET`, or Controller Home MCP config. Empty/default controller configuration resolves to `advanced`.
@@ -31,7 +32,7 @@ The current implementation separates orchestration from capability without delet
 2. **Typed atomic tools:** repository inspection, Direct Edit, command, Git, Work/Job, Issue/Task, Goal/Work, plugin, browser, iOS, artifact, and recovery handlers remain public because their schemas preserve operation-specific validation and evidence.
 3. **Internal handlers and capability registry:** capabilities are grouped as `controller`, `repository-core`, `git`, `issue-task`, `browser`, `ios`, `plugin`, `evidence`, and `runtime-maintenance`. `rh_status`, `rh_context`, and `controller_capabilities` expose this metadata.
 
-The MCP transport currently publishes a static stable schema. It does **not** support loading a domain schema only after ChatGPT selects that domain. Therefore capability grouping improves selection and documentation, but it must not be described as dynamic tool loading. A future transport-level implementation may reduce the discovered schema while retaining the same internal handlers.
+The MCP transport publishes a static schema for each selected toolset. It does **not** dynamically load a domain schema after ChatGPT selects that domain. The opt-in `facade` toolset reduces initial discovery to five facade tools while retaining the same internal handlers; `core`/`advanced` keep the current 19-tool stable schema and `full` keeps the exhaustive compatibility schema.
 
 Capability metadata changes do not change `tools/list`; restart the Controller to load new code, but reconnect/rescan ChatGPT only when tool names or input schemas change.
 
@@ -45,6 +46,7 @@ Remote writes, destructive actions, outside-repository paths, and secret access
 
 - Prefer `rh_status`, `rh_access`, `rh_context`, `rh_work`, and `rh_inbox` for normal orchestration.
 - Use first-class Direct Edit, command, Git, `quick_agent_session`, Goal/Work, iOS, plugin, and artifact tools when the facade is not the shortest reliable path.
+- Use `--toolset facade` only for explicit experiments/clients until latency and workflow coverage are validated; the default remains the stable 19-tool surface.
 - Keep the stable surface unique and at or below 128 tools.
 - Add new public tools only when they unlock a real end-to-end workflow; otherwise route capabilities through an existing facade or plugin action.
 

package/docs/wiki/Architecture.md

@@ -75,11 +75,11 @@ One Canonical Runtime owns the active local execution authority and one whole-re
 
 ## Authoritative documents
 
-- [System overview](https://github.com/moretea-labs/forge/blob/main/docs/architecture/current/system-overview.md)
-- [Architecture invariants](https://github.com/moretea-labs/forge/blob/main/docs/architecture/current/architecture-invariants.md)
-- [Multi-repository execution](https://github.com/moretea-labs/forge/blob/main/docs/architecture/current/multi-repository-execution.md)
-- [Verification and release gates](https://github.com/moretea-labs/forge/blob/main/docs/architecture/current/verification-and-release-gates.md)
-- [Implementation status](https://github.com/moretea-labs/forge/blob/main/docs/architecture/current/implementation-status.md)
-- [Runtime directory map](https://github.com/moretea-labs/forge/blob/main/docs/architecture/current/runtime-directory-map.md)
+- [System overview](https://github.com/moretea-labs/forge/blob/main/docs/architecture/../architecture/CURRENT.md)
+- [Architecture invariants](https://github.com/moretea-labs/forge/blob/main/docs/architecture/../architecture/CURRENT.md)
+- [Multi-repository execution](https://github.com/moretea-labs/forge/blob/main/docs/architecture/../architecture/CURRENT.md)
+- [Verification and release gates](https://github.com/moretea-labs/forge/blob/main/docs/architecture/../architecture/CURRENT.md)
+- [Implementation status](https://github.com/moretea-labs/forge/blob/main/docs/architecture/../architecture/CURRENT.md)
+- [Runtime directory map](https://github.com/moretea-labs/forge/blob/main/docs/architecture/../architecture/CURRENT.md)
 
 Historical snapshots explain previous designs but are not current Runtime contracts.

package/docs/wiki/Implementation.md

@@ -143,8 +143,8 @@ Primary code and docs:
 ```text
 src/runtime/root/release-store.ts
 src/runtime/health/
-docs/architecture/current/failure-recovery.md
-docs/architecture/current/verification-and-release-gates.md
+docs/architecture/../architecture/CURRENT.md
+docs/architecture/../architecture/CURRENT.md
 ```
 
 The primary Runtime cannot be the only authority deciding its own recovery. Standalone Recovery observes the Runtime independently and may perform bounded whole-release restart/rollback only under its own evidence and lock contract.

package/docs/wiki/Integrations.md

@@ -18,9 +18,9 @@ GitHub operations cover issues, pull requests, checks, repository settings, Wiki
 
 Browser and local-system plugins are optional controller capabilities. They use separate grants and do not turn repository access into unrestricted machine access.
 
-## Google Workspace and personal workflows
+## Google Workspace
 
-Gmail, Calendar, Contacts, and related assistant routines remain connector-specific. Credentials and personal data are not stored in repository source.
+Gmail, Calendar, Contacts, and other Workspace integrations remain connector-specific. Credentials and personal data are not stored in repository source.
 
 ## Apple tooling
 

package/docs/wiki/Work-Lifecycle.md

@@ -28,4 +28,4 @@ Commit explicit paths, merge through the intended strategy, and record the integ
 
 Update task evidence, delete merged branches and temporary worktrees, and verify the target branch is clean. Blocked or failed states remain recoverable; they are not treated as immutable terminal truth.
 
-For detailed lifecycle contracts, see [Job and Run Lifecycle](https://github.com/moretea-labs/forge/blob/main/docs/architecture/current/job-and-run-lifecycle.md).
+For detailed lifecycle contracts, see [Job and Run Lifecycle](https://github.com/moretea-labs/forge/blob/main/docs/architecture/../architecture/CURRENT.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moretea-labs/forge",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Local-first action assistant for software work with resumable execution, bounded tools, and reviewable evidence",
   "license": "MIT",
   "author": "Moretea Labs contributors",
@@ -54,8 +54,6 @@
     "docs/forge-chatgpt-mcp-setup.md",
     "docs/forge-github-issue-launcher.md",
     "docs/forge-runtime-self-healing-loop.md",
-    "docs/forge-autonomous-goal-loop.md",
-    "docs/forge-provider-configuration.md",
     "docs/forge-plugin-management.md",
     "README.en.md",
     "README.zh-CN.md",
@@ -83,7 +81,21 @@
     "check:controller-ui": "bun scripts/build-controller-ui.ts --check",
     "check:design": "npx -y @google/design.md@0.4.0 lint DESIGN.md",
     "benchmark:skills": "bun scripts/run-skill-evals.ts",
+    "benchmark:controller-hotpath": "bun scripts/benchmark-controller-hotpath.ts",
+    "benchmark:thin-harness-mcp-e2e": "bun scripts/benchmark-thin-harness-mcp-e2e.ts --json",
+    "benchmark:mcp-transport": "bun scripts/benchmark-mcp-transport.ts",
+    "benchmark:mcp-host": "bash scripts/benchmark-mcp-host.sh",
+    "benchmark:work-efficiency": "bun scripts/benchmark-work-efficiency.ts",
     "benchmark:route-session-concurrency": "bun scripts/benchmark-route-session-concurrency.ts",
+    "benchmark:quality-harness": "bun scripts/benchmark-quality-harness.ts",
+    "benchmark:background-check-overlap": "bun scripts/benchmark-background-check-overlap.ts",
+    "check:quality-harness": "bun scripts/benchmark-quality-harness.ts",
+    "check:evaluation-framework": "bun test tests/evaluation-framework.test.ts",
+    "check:background-check-overlap": "bun scripts/benchmark-background-check-overlap.ts",
+    "check:typescript-navigation": "bun scripts/benchmark-typescript-navigation.ts",
+    "check:semantic-navigation-providers": "bun test tests/runtime/semantic-navigation-provider.test.ts",
+    "check:check-scheduling": "bun test tests/runtime/check-scheduling.test.ts",
+    "check:bootstrap-files": "bun test tests/bootstrap-files.test.ts",
     "test": "bun scripts/test-governance.ts affected",
     "test:browser-live": "bun tests/live/browser-native-silent.e2e.ts",
     "test:core": "bun scripts/test-governance.ts core",
@@ -106,6 +118,7 @@
     "check:main": "bun scripts/run-governed-gate.ts main",
     "check:ci": "bun run check:main",
     "check:release": "bun scripts/run-governed-gate.ts release",
+    "check:stable-baseline": "bun scripts/check-stable-baseline.ts",
     "check:release-surface": "bash scripts/check-public-release-surface.sh",
     "check:release-readiness": "bash scripts/check-release-readiness.sh",
     "check:open-source-surface": "bash scripts/check-open-source-tracked-surface.sh",
@@ -125,8 +138,8 @@
     "check:context-files": "forge run check-context-files",
     "check:deploy-sql": "forge run check-deploy-sql-order",
     "check:architecture-sync": "forge run check-architecture-sync",
-    "check:task-sync": "node bin/forge.mjs run check-task-sync",
-    "check:task-workflow": "bash scripts/check-task-workflow.sh --strict",
+    "check:task-sync": "forge run check-task-sync",
+    "check:task-workflow": "forge run check-task-workflow --strict",
     "runtime:activate-source-baseline": "bun scripts/activate-source-baseline.ts request",
     "plugin:install-desktop-operator": "bun scripts/install-desktop-operator-registration.ts",
     "sync:brain-docs": "forge run sync-brain-docs --all",
@@ -143,10 +156,10 @@
   "devDependencies": {
     "@colbymchenry/codegraph": "1.0.1",
     "@types/bun": "latest",
-    "@types/cors": "^2.8.17",
-    "@types/express": "^5.0.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
     "@vitejs/plugin-react": "^5.2.0",
     "vite": "^7.3.0"
   },
@@ -156,11 +169,17 @@
     "express": "^5.2.1",
     "playwright": "^1.54.1",
     "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "react-dom": "^19.2.8",
     "typescript": "^6.0.3"
   },
   "packageManager": "npm@10.0.0",
   "optionalDependencies": {
+    "@colbymchenry/codegraph-darwin-arm64": "1.0.1",
+    "@colbymchenry/codegraph-darwin-x64": "1.0.1",
+    "@colbymchenry/codegraph-linux-arm64": "1.0.1",
+    "@colbymchenry/codegraph-linux-x64": "1.0.1",
+    "@colbymchenry/codegraph-win32-arm64": "1.0.1",
+    "@colbymchenry/codegraph-win32-x64": "1.0.1",
     "agent-device": "0.20.2"
   }
 }

package/scripts/activate-source-baseline.ts

@@ -64,19 +64,17 @@ interface CheckDefinition {
 const CHECKS: readonly CheckDefinition[] = [
   { id: 'package:check:type', args: ['run', 'check:type'], timeoutMs: 10 * 60_000 },
   { id: 'package:check:runtime-architecture', args: ['run', 'check:runtime-architecture'], timeoutMs: 3 * 60_000 },
-  {
-    id: 'focused:runtime-architecture-replacement',
-    args: [
-      'test',
-      'tests/runtime/process-runtime.test.ts',
-      'tests/runtime/work-terminal-cleanup.test.ts',
-      'tests/runtime/canonical-single-runtime.test.ts',
-      'tests/cli/runtime-command.test.ts',
-      'tests/runtime/stable-state-and-bootstrap.test.ts',
-      'tests/cli/mcp-controller.test.ts',
-    ],
-    timeoutMs: 15 * 60_000,
-  },
+  ...[
+    'tests/runtime/process-runtime.test.ts',
+    'tests/runtime/work-terminal-cleanup.test.ts',
+    'tests/runtime/canonical-single-runtime.test.ts',
+    'tests/cli/runtime-command.test.ts',
+    'tests/cli/mcp-http.test.ts',
+  ].map((path) => ({
+    id: `focused:runtime-architecture-replacement:${path}`,
+    args: ['test', '--max-concurrency', '1', `./${path}`],
+    timeoutMs: 5 * 60_000,
+  })),
   { id: 'package:test:core', args: ['run', 'test:core'], timeoutMs: 30 * 60_000 },
 ];
 
@@ -172,6 +170,12 @@ function terminalOutcome(handle: ReturnType<typeof listWorkHandles>[number]): Wo
 
 function cleanupSafety(repoRoot: string, worktreePath: string): { safe: boolean; reason?: string } {
   if (!existsSync(worktreePath)) return { safe: true };
+  const repository = runProcess('git', ['rev-parse', '--is-inside-work-tree'], {
+    cwd: worktreePath,
+    timeoutMs: 10_000,
+    maxOutputBytes: 100_000,
+  });
+  if (!repository.ok || repository.stdout.trim() !== 'true') return { safe: false, reason: 'WORKTREE_NOT_GIT_REPOSITORY' };
   const status = git(worktreePath, ['status', '--porcelain']);
   if (status) return { safe: false, reason: 'WORKTREE_DIRTY' };
   const head = git(worktreePath, ['rev-parse', 'HEAD']);

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