@moretea-labs/forge 1.7.2 → 1.8.0

package/scripts/benchmark-computer-hotpath.ts

@@ -0,0 +1,255 @@
+#!/usr/bin/env bun
+
+/**
+ * Repeatable Computer semantic hot-path benchmark.
+ *
+ * Uses an isolated controller home and a local Unix JSONL provider fixture. It
+ * measures the real Computer product dispatch path without touching the live
+ * Desktop Operator or the repository checkout.
+ */
+import { randomUUID } from 'crypto';
+import { mkdtempSync, rmSync } from 'fs';
+import { createServer, type Server } from 'net';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { computerPluginAdapter } from '../src/runtime/plugins/computer-registration';
+import { createDesktopOperatorRegistrationInput } from '../src/runtime/plugins/desktop-operator-registration';
+import { installExternalPluginRegistration } from '../src/runtime/plugins/external-registration';
+import { disposeRuntimeComputerComposition } from '../src/runtime/root/computer-composition';
+import { setComputerPlatformForTest } from '../src/runtime/platform/computer-platform';
+import type { AssistantPluginActionExecutionInput } from '../src/runtime/plugins/types';
+
+const WARMUP = 5;
+const SAMPLES = Math.max(10, Number(process.env.FORGE_COMPUTER_BENCH_SAMPLES ?? 50));
+
+interface Counters {
+  connections: number;
+  handshakes: number;
+  manifests: number;
+  statuses: number;
+  sessionOpens: number;
+  observes: number;
+}
+
+function percentile(values: number[], quantile: number): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * quantile))] ?? 0;
+}
+
+function rounded(value: number): number {
+  return Math.round(value * 1000) / 1000;
+}
+
+function actionInput(
+  controllerHome: string,
+  actionId: string,
+  args: Record<string, unknown>,
+  requestId: string,
+): AssistantPluginActionExecutionInput {
+  return {
+    controllerHome,
+    repoId: '__controller__',
+    repoRoot: controllerHome,
+    pluginId: 'computer',
+    actionId,
+    requestId,
+    args,
+    origin: { surface: 'system', actor: 'computer-hotpath-benchmark' },
+  };
+}
+
+function counterDelta(after: Counters, before: Counters): Counters {
+  return {
+    connections: after.connections - before.connections,
+    handshakes: after.handshakes - before.handshakes,
+    manifests: after.manifests - before.manifests,
+    statuses: after.statuses - before.statuses,
+    sessionOpens: after.sessionOpens - before.sessionOpens,
+    observes: after.observes - before.observes,
+  };
+}
+
+async function closeServer(server: Server): Promise<void> {
+  if (!server.listening) return;
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+}
+
+async function main(): Promise<void> {
+  const controllerHome = mkdtempSync(join(tmpdir(), 'forge-computer-hotpath-'));
+  const socketPath = process.platform === 'win32'
+    ? `\\\\.\\pipe\\forge-computer-hotpath-${randomUUID()}`
+    : join(controllerHome, 'desktop.sock');
+  // Benchmark the macOS provider contract with a local transport fixture on
+  // every host. This is not a production platform fallback: it keeps the
+  // measured path identical while Windows still fails native calls without a
+  // registered Windows provider.
+  setComputerPlatformForTest('darwin');
+  const registration = installExternalPluginRegistration(controllerHome, createDesktopOperatorRegistrationInput({
+    socketPath,
+    pluginVersion: '0.3.2',
+    protocolVersion: '1.0',
+  }));
+  const sessions = new Map<string, Record<string, unknown>>();
+  const counters: Counters = {
+    connections: 0,
+    handshakes: 0,
+    manifests: 0,
+    statuses: 0,
+    sessionOpens: 0,
+    observes: 0,
+  };
+
+  const server = createServer((socket) => {
+    counters.connections += 1;
+    let buffer = '';
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      while (true) {
+        const newline = buffer.indexOf('\n');
+        if (newline < 0) return;
+        const raw = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        const request = JSON.parse(raw) as { id: string; method: string; params?: Record<string, unknown> };
+        const envelopeParams = request.params ?? {};
+        const actionId = request.method === 'execute' && typeof envelopeParams.action === 'string'
+          ? envelopeParams.action
+          : request.method;
+        const params = request.method === 'execute' && envelopeParams.arguments && typeof envelopeParams.arguments === 'object'
+          ? envelopeParams.arguments as Record<string, unknown>
+          : envelopeParams;
+        let result: Record<string, unknown>;
+        if (actionId === 'handshake') {
+          counters.handshakes += 1;
+          result = {
+            pluginId: registration.providerPluginId,
+            protocolVersion: registration.protocolVersion,
+            processId: 9001,
+            startedAt: '2026-09-09T00:00:00.000Z',
+            computerCapabilities: [],
+          };
+        } else if (actionId === 'manifest') {
+          counters.manifests += 1;
+          result = {
+            id: registration.providerPluginId,
+            name: registration.displayName,
+            version: registration.pluginVersion,
+            protocolVersion: registration.protocolVersion,
+            mode: 'external',
+            scope: registration.scope,
+            provider: registration.provider,
+            capabilities: registration.capabilities.map((capability) => capability.capabilityId),
+            actions: registration.actions.map((action) => action.actionId),
+          };
+        } else if (actionId === 'health') {
+          result = { state: 'ready', warnings: [] };
+        } else if (actionId === 'desktop_status') {
+          counters.statuses += 1;
+          result = { sessions: [...sessions.values()] };
+        } else if (actionId === 'desktop_session_open') {
+          counters.sessionOpens += 1;
+          const interactionId = `bench_session_${counters.sessionOpens}`;
+          const session = {
+            interactionId,
+            bundleIdentifier: typeof params.bundle_id === 'string' ? params.bundle_id : 'com.example.Benchmark',
+            appName: 'Benchmark',
+          };
+          sessions.set(interactionId, session);
+          result = session;
+        } else if (actionId === 'desktop_observe') {
+          if (typeof params.interaction_id !== 'string' || !sessions.has(params.interaction_id)) {
+            socket.write(`${JSON.stringify({ id: request.id, ok: false, error: { code: 'SESSION_NOT_FOUND', message: 'missing', retryable: false, domain: 'session' } })}\n`);
+            continue;
+          }
+          counters.observes += 1;
+          result = { observed: true, interactionId: params.interaction_id };
+        } else {
+          result = { ok: true };
+        }
+        socket.write(`${JSON.stringify({ id: request.id, ok: true, result })}\n`);
+      }
+    });
+  });
+
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(socketPath, () => {
+        server.off('error', reject);
+        resolve();
+      });
+    });
+
+    const opened = await computerPluginAdapter.executeAction(actionInput(
+      controllerHome,
+      'desktop_target_open',
+      { bundle_id: 'com.example.Benchmark', launch: false, activate: false },
+      'benchmark-target-open',
+    ));
+    const targetId = String(opened.targetId);
+
+    const coldBefore = { ...counters };
+    const coldStartedAt = performance.now();
+    await computerPluginAdapter.executeAction(actionInput(
+      controllerHome,
+      'desktop_observe',
+      { target_id: targetId, max_depth: 1, max_nodes: 5 },
+      'benchmark-cold-observe',
+    ));
+    const coldMs = performance.now() - coldStartedAt;
+    const coldDelta = counterDelta(counters, coldBefore);
+
+    for (let index = 0; index < WARMUP; index += 1) {
+      await computerPluginAdapter.executeAction(actionInput(
+        controllerHome,
+        'desktop_observe',
+        { target_id: targetId, max_depth: 1, max_nodes: 5 },
+        `benchmark-warmup-${index}`,
+      ));
+    }
+
+    const warmBefore = { ...counters };
+    const samples: number[] = [];
+    for (let index = 0; index < SAMPLES; index += 1) {
+      const startedAt = performance.now();
+      await computerPluginAdapter.executeAction(actionInput(
+        controllerHome,
+        'desktop_observe',
+        { target_id: targetId, max_depth: 1, max_nodes: 5 },
+        `benchmark-sample-${index}`,
+      ));
+      samples.push(performance.now() - startedAt);
+    }
+    const warmDelta = counterDelta(counters, warmBefore);
+
+    console.log(JSON.stringify({
+      benchmark: 'computer-hotpath',
+      samples: SAMPLES,
+      warmup: WARMUP,
+      cold: {
+        ms: rounded(coldMs),
+        provider: coldDelta,
+      },
+      warm: {
+        p50Ms: rounded(percentile(samples, 0.50)),
+        p95Ms: rounded(percentile(samples, 0.95)),
+        maxMs: rounded(Math.max(...samples)),
+        provider: warmDelta,
+        providerRpcsPerAction: rounded(warmDelta.observes / SAMPLES),
+      },
+      contract: {
+        warmHandshakePerAction: 0,
+        warmManifestPreflightPerAction: 0,
+        warmStatusPreflightPerAction: 0,
+        retainedConnectionsDuringSamples: 0,
+        removedLegacyStatusPreflightRpcsPerWarmAction: 1,
+      },
+    }, null, 2));
+  } finally {
+    disposeRuntimeComputerComposition();
+    setComputerPlatformForTest(undefined);
+    await closeServer(server);
+    rmSync(controllerHome, { recursive: true, force: true });
+  }
+}
+
+await main();

package/scripts/benchmark-controller-round2.ts

@@ -77,7 +77,34 @@ async function main(): Promise<void> {
     const concurrent = await Promise.all(Array.from({ length: 30 }, () => call(context, 'controller_context', { repo_id: repository.repoId })));
     const timings = concurrent.map((item) => item.elapsedMs);
     const readiness = await call(context, 'controller_ready', { repo_id: repository.repoId });
-    const performance = await call(context, 'runtime_performance_diagnostics', {
+    const statusSummary = await call(context, 'rh_status', { repo_id: repository.repoId, operation: 'get', detail_level: 'summary' });
+    const statusDetail = await call(context, 'rh_status', { repo_id: repository.repoId, operation: 'get', detail_level: 'detail' });
+    const replacementContext = createMcpToolContext({
+      repo: repoRoot,
+      controllerHome,
+      profile: 'controller',
+      toolset: 'advanced',
+      sessionId: `benchmark-round2-replacement-${Date.now()}`,
+    });
+    const replacementSessionContext = await call(replacementContext, 'controller_context', { repo_id: repository.repoId });
+    const checkpointStartedAt = performance.now();
+    const checkpointStatus = await call(context, 'rh_status', { repo_id: repository.repoId, operation: 'get', detail_level: 'summary' });
+    const checkpointContext = await call(context, 'controller_context', { repo_id: repository.repoId });
+    const checkpointElapsedMs = Math.round((performance.now() - checkpointStartedAt) * 100) / 100;
+    const checkpointCalls = [checkpointStatus, checkpointContext];
+    const checkpointStatuses = checkpointCalls.map((entry) => {
+      const facadeStatus = typeof entry.value.status === 'string' ? entry.value.status : undefined;
+      const contextHealth = entry.value?.health && typeof entry.value.health === 'object' ? entry.value.health as Record<string, unknown> : undefined;
+      const status = facadeStatus ?? (contextHealth ? (contextHealth.ready === true ? 'ok' : 'blocked') : 'unknown');
+      const facadeReasons = entry.value?.data?.readiness?.reasonCodes;
+      const contextReasons = contextHealth?.reasonCodes;
+      const reasonCodes = Array.isArray(facadeReasons)
+        ? facadeReasons.map(String)
+        : Array.isArray(contextReasons) ? contextReasons.map(String) : [];
+      return { status, reasonCodes };
+    });
+    const checkpointNonOk = checkpointStatuses.filter((entry) => entry.status !== 'ok');
+    const performanceDiagnostics = await call(context, 'runtime_performance_diagnostics', {
       repo_id: repository.repoId,
       include_processes: false,
       include_temp_dirs: false,
@@ -117,12 +144,37 @@ async function main(): Promise<void> {
           },
         },
         readiness: { elapsedMs: readiness.elapsedMs, bytes: bytes(readiness.value) },
+        status: {
+          summary: { elapsedMs: statusSummary.elapsedMs, bytes: bytes(statusSummary.value), responseMeta: responseMeta(statusSummary.value) },
+          detail: { elapsedMs: statusDetail.elapsedMs, bytes: bytes(statusDetail.value), responseMeta: responseMeta(statusDetail.value) },
+        },
+        replacementSessionContext: {
+          elapsedMs: replacementSessionContext.elapsedMs,
+          bytes: bytes(replacementSessionContext.value),
+          responseMeta: responseMeta(replacementSessionContext.value),
+          interpretation: 'persistent projection reuse across controller-session replacement; not a Runtime restart measurement',
+        },
+        controllerCheckpoint: {
+          elapsedMs: checkpointElapsedMs,
+          toolRoundTrips: checkpointCalls.length,
+          nonOkCount: checkpointNonOk.length,
+          nonOkRate: checkpointCalls.length > 0 ? checkpointNonOk.length / checkpointCalls.length : 0,
+          statuses: checkpointStatuses,
+          statusMs: checkpointStatus.elapsedMs,
+          contextMs: checkpointContext.elapsedMs,
+          usable: checkpointNonOk.length === 0,
+          environment: generatedHome ? 'synthetic_controller_home' : 'supplied_controller_home',
+        },
+        runtimeRestartContextClosure: {
+          status: 'not_measured',
+          reason: 'This local benchmark does not own Runtime restart authority; Mac Recovery certification must bind restart-to-first-usable-context latency to the activated revision.',
+        },
       },
       transportPhases: {
         local: { status: 'measured', path: 'direct multi-repository runtime tool' },
         external: { status: 'unavailable', reason: 'No external endpoint was supplied to this local benchmark.' },
       },
-      resourceCost: performance.value.resourceCost ?? {},
+      resourceCost: performanceDiagnostics.value.resourceCost ?? {},
       toolSurface,
       budgets: {
         controllerContextSummaryBytes: 32 * 1024,

package/scripts/benchmark-ios-agent-device.ts

@@ -22,6 +22,7 @@
 import { performance } from 'perf_hooks';
 import { resolve } from 'path';
 import { executeIosAgentDeviceAction } from '../src/runtime/plugins/ios-agent-device';
+import { resolveControllerHome } from '../src/cli/repositories/controller-home';
 
 type EvidenceTier = 'exact_wait' | 'scoped_snapshot' | 'full_snapshot' | 'unknown';
 export type BenchmarkProfile = 'fresh_session' | 'reused_session';
@@ -302,7 +303,7 @@ function usage(): string {
     '  --profile <fresh|warm|both> Profiles to measure, default both',
     '  --runs <3..20>              Measured runs per profile after one warmup, default 3',
     '  --timeout-ms <ms>           Absolute timeout per action, default 60000',
-    '  --controller-home <path>    Defaults to FORGE_CONTROLLER_HOME or _ops/controller-home',
+    '  --controller-home <path>    Defaults to FORGE_CONTROLLER_HOME/XDG state or ~/.forge/controller',
     '  --repo-root <path>          Defaults to current working directory',
     '  --relaunch                  Relaunch JD for each fresh run and the warm-profile setup open',
     '  --json                      Emit machine-readable JSON',
@@ -428,11 +429,7 @@ export async function runBenchmark(): Promise<Record<string, unknown>> {
   const timeoutMs = integerOption('timeout-ms', 60_000, 1_000, 600_000);
   const snapshotDepth = integerOption('snapshot-depth', 8, 1, 20);
   const repoRoot = resolve(option('repo-root') ?? process.cwd());
-  const controllerHome = resolve(
-    option('controller-home')
-      ?? process.env.FORGE_CONTROLLER_HOME
-      ?? resolve(repoRoot, '_ops/controller-home'),
-  );
+  const controllerHome = resolveControllerHome(option('controller-home'));
   const baseArgs: Record<string, unknown> = { device, query, snapshot_depth: snapshotDepth };
   for (const [flag, key] of [
     ['search-selector', 'search_selector'],

package/scripts/benchmark-mcp-transport.ts

@@ -1,9 +1,8 @@
 #!/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 { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { readMcpServiceBearerToken } from '../adapters/mcp/auth';
 import { resolveRepoPreferredControllerHome } from '../src/cli/repositories/controller-home';
 import {
   aggregateMcpTransportLatencySamples,
@@ -116,7 +115,7 @@ async function probe(): Promise<McpTransportLatencySample[]> {
     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 });
+      const response = await connection.client.callTool({ name: tool, arguments: args }, { timeout: timeoutMs });
       return { response, totalMs: performance.now() - started };
     } finally {
       if (includeConnect) await connection.client.close().catch(() => undefined);

package/scripts/benchmark-operational-memory-activation.ts

@@ -0,0 +1,235 @@
+#!/usr/bin/env bun
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import {
+  evaluateOperationalMemoryActivation,
+  freezeOperationalMemoryActivationProtocol,
+  type OperationalMemoryActivationMeasurement,
+  type OperationalMemoryActivationPair,
+} from '../evaluation/lib/operational-memory-activation';
+import { controllerCheckEnvironmentFingerprint, listControllerChecks } from '../src/cli/controller/check-runner';
+import {
+  OPERATIONAL_MEMORY_NAMESPACE,
+  ingestCheckCompletionGraceProcess,
+  resolveCheckCompletionGraceWaitMs,
+} from '../src/runtime/control-plane/persistence/operational-prior-store';
+import { listControlPlaneRecords } from '../src/runtime/control-plane/persistence/sqlite-store';
+import { createProcessRecord } from '../src/runtime/execution/process-runtime/store';
+import { startLightweightControllerCheck, waitForLightweightProcess } from '../src/runtime/execution/process-runtime/lightweight-managed';
+import type { ManagedProcessRecord, ProcessHandle } from '../src/runtime/execution/process-runtime/types';
+
+interface Scenario {
+  id: string;
+  kind: 'eligible' | 'guard';
+  delayMs: number;
+  historicalDurationMs: number;
+}
+
+const scenarios: readonly Scenario[] = [
+  { id: 'check-grace-eligible-150ms', kind: 'eligible', delayMs: 150, historicalDurationMs: 150 },
+  { id: 'check-grace-eligible-180ms', kind: 'eligible', delayMs: 180, historicalDurationMs: 180 },
+  { id: 'check-grace-guard-400ms', kind: 'guard', delayMs: 400, historicalDurationMs: 400 },
+];
+const SAMPLES_PER_ARM = 3;
+const CHECK_ID = 'package:check:fixture';
+const CANONICAL_WAIT_MS = 100;
+
+function bytes(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+
+function median(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)]!;
+}
+
+function fixture(delayMs: number, label: string): { root: string; controllerHome: string; repoId: string } {
+  const root = mkdtempSync(join(tmpdir(), `forge-stage7f-${label}-repo-`));
+  const controllerHome = mkdtempSync(join(tmpdir(), `forge-stage7f-${label}-home-`));
+  writeFileSync(join(root, 'package.json'), JSON.stringify({ scripts: { 'check:fixture': `sleep ${delayMs / 1000}` } }, null, 2));
+  execFileSync('git', ['init', '-q'], { cwd: root });
+  execFileSync('git', ['config', 'user.email', 'stage7f@example.invalid'], { cwd: root });
+  execFileSync('git', ['config', 'user.name', 'Stage7F Fixture'], { cwd: root });
+  execFileSync('git', ['add', '.'], { cwd: root });
+  execFileSync('git', ['commit', '-qm', 'fixture'], { cwd: root });
+  return { root, controllerHome, repoId: `repo-stage7f-${label}` };
+}
+
+function historicalProcess(input: {
+  controllerHome: string;
+  repoId: string;
+  root: string;
+  processId: string;
+  environmentFingerprint: string;
+  durationMs: number;
+  index: number;
+}): ManagedProcessRecord {
+  const finishMs = Date.now() - (10_000 - input.index * 1_000);
+  const startMs = finishMs - input.durationMs;
+  return {
+    schemaVersion: 1,
+    processId: input.processId,
+    repoId: input.repoId,
+    checkoutId: 'historical-checkout',
+    commandId: `historical-command-${input.index}`,
+    controllerHome: input.controllerHome,
+    status: 'succeeded',
+    route: 'direct',
+    command: { kind: 'argv', executable: 'sleep', args: [String(input.durationMs / 1000)], cwd: input.root },
+    resourceClaims: [],
+    leaseRefs: [],
+    leasesReleased: true,
+    interactiveWaitMs: 0,
+    timeoutMs: 5_000,
+    maxOutputBytes: 4_096,
+    startedAt: new Date(startMs).toISOString(),
+    updatedAt: new Date(finishMs).toISOString(),
+    finishedAt: new Date(finishMs).toISOString(),
+    exitCode: 0,
+    timedOut: false,
+    cancelled: false,
+    terminalFenceToken: input.index + 1,
+    terminalWritten: true,
+    checkExecution: {
+      schemaVersion: 1,
+      checkId: CHECK_ID,
+      cacheKey: `historical-cache-${input.index}`,
+      revision: 'historical-revision',
+      definitionDigest: 'historical-definition',
+      environmentFingerprint: input.environmentFingerprint,
+      timeoutMs: 5_000,
+      reuseScope: 'repository',
+      scopeKey: 'repository',
+    },
+    origin: {
+      surface: 'check',
+      checkId: CHECK_ID,
+      requestId: `historical-request-${input.index}`,
+    },
+  };
+}
+
+function seedOperationalMemory(input: {
+  controllerHome: string;
+  repoId: string;
+  root: string;
+  historicalDurationMs: number;
+}): { learnedWaitMs?: number; lookupMs: number; recordBytes: number } {
+  const check = listControllerChecks(input.root).find((entry) => entry.id === CHECK_ID);
+  if (!check) throw new Error(`STAGE7F_BENCHMARK_CHECK_MISSING:${CHECK_ID}`);
+  const environmentFingerprint = controllerCheckEnvironmentFingerprint(check);
+  for (let index = 0; index < 3; index += 1) {
+    const processId = `proc_stage7f_history_${index}`;
+    createProcessRecord(historicalProcess({ ...input, processId, environmentFingerprint, durationMs: input.historicalDurationMs, index }));
+    const ingested = ingestCheckCompletionGraceProcess({ controllerHome: input.controllerHome, repoId: input.repoId, processId });
+    if (!ingested.stored) throw new Error(`STAGE7F_BENCHMARK_INGEST_FAILED:${processId}`);
+  }
+  const lookupStart = performance.now();
+  const learnedWaitMs = resolveCheckCompletionGraceWaitMs({
+    controllerHome: input.controllerHome,
+    repoId: input.repoId,
+    checkId: CHECK_ID,
+    environmentFingerprint,
+  });
+  const lookupMs = performance.now() - lookupStart;
+  const records = listControlPlaneRecords(input.controllerHome, { namespace: OPERATIONAL_MEMORY_NAMESPACE, scope: input.repoId, limit: 16 });
+  return { learnedWaitMs, lookupMs, recordBytes: bytes(records) };
+}
+
+async function runOne(input: {
+  scenario: Scenario;
+  active: boolean;
+  sample: number;
+}): Promise<OperationalMemoryActivationMeasurement> {
+  const label = `${input.scenario.id}-${input.active ? 'active' : 'cold'}-${input.sample}`;
+  const fx = fixture(input.scenario.delayMs, label);
+  try {
+    const memory = input.active
+      ? seedOperationalMemory({ controllerHome: fx.controllerHome, repoId: fx.repoId, root: fx.root, historicalDurationMs: input.scenario.historicalDurationMs })
+      : { learnedWaitMs: undefined, lookupMs: 0, recordBytes: 0 };
+    const appliedWaitMs = memory.learnedWaitMs ?? CANONICAL_WAIT_MS;
+    const started = performance.now();
+    const first = await startLightweightControllerCheck({
+      controllerHome: fx.controllerHome,
+      repoId: fx.repoId,
+      repoRoot: fx.root,
+      checkId: CHECK_ID,
+      interactiveWaitMs: appliedWaitMs,
+      timeoutMs: 5_000,
+      commandId: label,
+    });
+    const firstReturnMs = performance.now() - started;
+    const firstHandle: ProcessHandle = first.handle;
+    let finalHandle = firstHandle;
+    let toolRoundTrips = 1;
+    if (!finalHandle.completed) {
+      toolRoundTrips += 1;
+      finalHandle = await waitForLightweightProcess(fx.controllerHome, fx.repoId, finalHandle.processId, { timeoutMs: 5_000 });
+    }
+    const terminalLatencyMs = performance.now() - started + memory.lookupMs;
+    return {
+      toolRoundTrips,
+      firstReturnMs,
+      terminalLatencyMs,
+      completedInOrigin: firstHandle.completed === true,
+      controllerVisibleBytes: bytes(firstHandle) + (toolRoundTrips > 1 ? bytes(finalHandle) : 0),
+      controllerMemoryPayloadBytes: 0,
+      memoryLookupMs: memory.lookupMs,
+      memoryRecordBytes: memory.recordBytes,
+      appliedWaitMs,
+      ...(memory.learnedWaitMs === undefined ? {} : { learnedWaitMs: memory.learnedWaitMs }),
+      correctnessPassed: finalHandle.completed === true && finalHandle.ok === true,
+    };
+  } finally {
+    rmSync(fx.root, { recursive: true, force: true });
+    rmSync(fx.controllerHome, { recursive: true, force: true });
+  }
+}
+
+function aggregate(samples: OperationalMemoryActivationMeasurement[]): OperationalMemoryActivationMeasurement {
+  const learned = samples.map((sample) => sample.learnedWaitMs).filter((value): value is number => value !== undefined);
+  return {
+    toolRoundTrips: median(samples.map((sample) => sample.toolRoundTrips)),
+    firstReturnMs: median(samples.map((sample) => sample.firstReturnMs)),
+    terminalLatencyMs: median(samples.map((sample) => sample.terminalLatencyMs)),
+    completedInOrigin: samples.filter((sample) => sample.completedInOrigin).length >= Math.ceil(samples.length / 2),
+    controllerVisibleBytes: median(samples.map((sample) => sample.controllerVisibleBytes)),
+    controllerMemoryPayloadBytes: median(samples.map((sample) => sample.controllerMemoryPayloadBytes)),
+    memoryLookupMs: median(samples.map((sample) => sample.memoryLookupMs)),
+    memoryRecordBytes: median(samples.map((sample) => sample.memoryRecordBytes)),
+    appliedWaitMs: median(samples.map((sample) => sample.appliedWaitMs)),
+    ...(learned.length === 0 ? {} : { learnedWaitMs: median(learned) }),
+    correctnessPassed: samples.every((sample) => sample.correctnessPassed),
+  };
+}
+
+export async function runOperationalMemoryActivationBenchmark(candidateIdentity: string) {
+  const protocol = freezeOperationalMemoryActivationProtocol({ candidateIdentity });
+  const pairs: OperationalMemoryActivationPair[] = [];
+  for (const scenario of scenarios) {
+    const cold: OperationalMemoryActivationMeasurement[] = [];
+    const active: OperationalMemoryActivationMeasurement[] = [];
+    for (let sample = 0; sample < SAMPLES_PER_ARM; sample += 1) {
+      cold.push(await runOne({ scenario, active: false, sample }));
+      active.push(await runOne({ scenario, active: true, sample }));
+    }
+    pairs.push({ scenarioId: scenario.id, kind: scenario.kind, candidateIdentity, cold: aggregate(cold), active: aggregate(active) });
+  }
+  return { schemaVersion: 1 as const, protocol, pairs, report: evaluateOperationalMemoryActivation(protocol, pairs) };
+}
+
+function candidateArg(): string | undefined {
+  const index = process.argv.indexOf('--candidate');
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+if (import.meta.main) {
+  const candidate = candidateArg();
+  if (!candidate) throw new Error('Usage: bun scripts/benchmark-operational-memory-activation.ts --candidate <frozen-candidate-identity>');
+  const result = await runOperationalMemoryActivationBenchmark(candidate);
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.report.passed) process.exitCode = 1;
+}

package/scripts/benchmark-operational-shadow.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+import { performance } from 'node:perf_hooks';
+import { rankOperationalShadowPriors, reduceOperationalObservations, type OperationalObservation, type OperationalShadowPrior } from '../packages/kernel/memory/api/index';
+import { evaluateOperationalShadowPairs, freezeOperationalShadowProtocol, type OperationalShadowPair } from '../evaluation/lib/shadow-operational-prior';
+
+interface Fixture { id:string; domainKind:'engineering'|'non_engineering'; operation:string; environment:string; expectedAction:'candidate' }
+const fixtures:readonly Fixture[]=[
+  {id:'engineering-check-ordering',domainKind:'engineering',operation:'check_ordering',environment:'portable-fixture-v1',expectedAction:'candidate'},
+  {id:'research-source-ordering',domainKind:'non_engineering',operation:'source_ordering',environment:'portable-fixture-v1',expectedAction:'candidate'},
+];
+const asOf='2026-09-04T00:00:00.000Z',retainedUntil='2026-09-20T00:00:00.000Z';
+function obs(f:Fixture,action:'baseline'|'candidate',index:number,value:number,outcome:'executed_success'|'contention_wait'='executed_success'):OperationalObservation{
+ const requestId=`${f.id}:${action}:${index}`,observedAt=`2026-09-03T00:${String(index).padStart(2,'0')}:00.000Z`;
+ return{schemaVersion:1,observationId:`obs:${requestId}:${outcome}`,signalId:'execution_job.terminal_mechanical',targetId:'mechanical_candidate_ordering',actionId:action,metricId:'latency_ms',scope:{schemaVersion:1,kind:'project',id:`fixture:${f.id}`},source:{schema:'execution_job/v1',sourceId:`source:${requestId}`,eventKind:outcome==='contention_wait'?'waiting_for_workspace':'succeeded',evidenceRef:`evidence:${requestId}`,requestId,observedAt,retainedUntil},attribution:{kind:'exact',consumerId:'shadow_evaluation',requestId,sourceId:`source:${requestId}`},outcomeClass:outcome,value,compatibility:{operation:f.operation,environment:f.environment}};
+}
+function fixtureObservations(f:Fixture){return[obs(f,'baseline',1,900),obs(f,'baseline',2,880),obs(f,'baseline',3,920),obs(f,'candidate',4,520),obs(f,'candidate',5,500),obs(f,'candidate',6,510),obs(f,'candidate',7,0,'contention_wait')]}
+function retained(priors:readonly OperationalShadowPrior[]){return new Set(priors.flatMap(p=>p.supportEvidenceRefs))}
+function select(priors:readonly OperationalShadowPrior[],f:Fixture){return rankOperationalShadowPriors({priors,compatibility:{operation:f.operation,environment:f.environment},retainedEvidenceRefs:retained(priors),asOf})[0]?.prior.actionId}
+function benchmark(fn:()=>unknown,iterations=1200){for(let i=0;i<60;i++)fn();const start=performance.now();for(let i=0;i<iterations;i++)fn();return Math.max((performance.now()-start)/iterations,0.000001)}
+function bytes(value:unknown){return Buffer.byteLength(JSON.stringify(value),'utf8')}
+function pair(f:Fixture,candidateRevision:string):OperationalShadowPair{
+ const observations=fixtureObservations(f);const shadowReduction=reduceOperationalObservations({observations,asOf});const priors=shadowReduction.priors;const coldSelect=()=>{const reduction=reduceOperationalObservations({observations,asOf});return select(reduction.priors,f)};const shadowSelect=()=>select(priors,f);const coldChoice=coldSelect(),shadowChoice=shadowSelect();
+ const context={operation:f.operation,candidates:['baseline','candidate'],scope:`fixture:${f.id}`};const contextBytes=bytes(context),rawEvidenceBytes=bytes(observations),shadowBytes=bytes(priors);
+ return{scenarioId:f.id,domainKind:f.domainKind,candidateRevision,cold:{controllerVisibleBytes:contextBytes+rawEvidenceBytes,contextBytes,shadowBytes:0,rhContextEvidenceBytes:rawEvidenceBytes,mechanicalRereads:observations.length,toolRoundTrips:observations.length,latencyMs:benchmark(coldSelect),staleNoValueRetrievals:shadowReduction.rejected.length,correctnessPassed:coldChoice===f.expectedAction},shadow:{controllerVisibleBytes:contextBytes+shadowBytes,contextBytes,shadowBytes,rhContextEvidenceBytes:0,mechanicalRereads:0,toolRoundTrips:1,latencyMs:benchmark(shadowSelect),staleNoValueRetrievals:0,correctnessPassed:shadowChoice===f.expectedAction}};
+}
+export function runOperationalShadowBenchmark(candidateRevision:string){const protocol=freezeOperationalShadowProtocol({candidateRevision,heldOutScenarioIds:fixtures.map(f=>f.id)});const pairs=fixtures.map(f=>pair(f,candidateRevision));const report=evaluateOperationalShadowPairs(protocol,pairs);return{schemaVersion:1 as const,protocol,pairs,report}}
+function candidateArg(){const i=process.argv.indexOf('--candidate');return i>=0?process.argv[i+1]:undefined}
+if(import.meta.main){const candidate=candidateArg();if(!candidate)throw new Error('Usage: bun scripts/benchmark-operational-shadow.ts --candidate <exact-revision>');const result=runOperationalShadowBenchmark(candidate);console.log(JSON.stringify(result,null,2));if(!result.report.passed)process.exitCode=1}

package/scripts/bootstrap-runtime-maintenance-recovery.sh

@@ -5,7 +5,10 @@ REPO_ROOT="${1:-$PWD}"
 REPO_ID="${FORGE_REPO_ID:-}"
 MIN_AGE_MINUTES="${FORGE_RECOVERY_MIN_AGE_MINUTES:-0}"
 CANCEL_PENDING="${FORGE_RECOVERY_CANCEL_PENDING_APPROVALS:-false}"
-CONTROLLER_HOME="${FORGE_CONTROLLER_HOME:-$REPO_ROOT/_ops/controller-home}"
+CONTROLLER_HOME="${FORGE_CONTROLLER_HOME:-${XDG_STATE_HOME:-${HOME:?HOME is required}/.local/state}/forge/controller}"
+if [[ -z "${FORGE_CONTROLLER_HOME:-}" && -z "${XDG_STATE_HOME:-}" ]]; then
+  CONTROLLER_HOME="${HOME:?HOME is required}/.forge/controller"
+fi
 
 cd "$REPO_ROOT"