@linzumi/cli 1.0.118 → 1.0.119

package/scripts/build-forwarding-parity-oracle.mjs

@@ -0,0 +1,1390 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 14, forwarding).
+// Relationship: Builds the TS-side PARITY ORACLE for the forwarding area of
+// the ReScript commander port. The oracle bundles the REAL TS forwarding
+// modules - forwardTunnelProtocol.ts (the binary frame codec),
+// portForwardApproval.ts (the pure approval policy), portForwardWatcher.ts
+// (the diff core + the real watcher), portScanScheduler.ts (parsers + the
+// scheduling/backoff decision core), localForwarding.ts (the legacy channel
+// plane + the raw TCP bridge), and forwardTunnel.ts (the streaming tunnel
+// state machine) - behind the standard one-shot BATCH driver (a JSON array
+// of cases on stdin, a JSON array of results on stdout).
+//
+// PROCESS MODE `tunnel-serve`: the oracle becomes the scripted server-side
+// tunnel endpoint (a real `ws` WebSocketServer) plus real loopback target
+// servers (node http + a ws echo). Each incoming tunnel connection replays
+// the same scripted frame choreography and prints ONE normalized transcript
+// line - so the ReScript connectForwardTunnel (dialing from the conformance
+// process) and the REAL TS connectForwardTunnel (dialed in-process on the
+// "run-ts" stdin command) are recorded by the SAME scripted server and must
+// produce byte-equal transcripts. Volatile material (Date headers, the
+// generation uuid, chunk boundaries) normalizes; body BYTES stay exact
+// (coalesced per stream).
+//
+// SECRETS: synthetic case payloads only; .differential/ is gitignored.
+import { mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const driverSource = `
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:http';
+import { gzipSync } from 'node:zlib';
+import { WebSocketServer, WebSocket as WsWebSocket } from 'ws';
+import {
+  decodeForwardTunnelBytes,
+  encodeForwardTunnelFrame,
+  forwardTunnelChunkBytes,
+} from './src/forwardTunnelProtocol';
+import {
+  approvedTargetFromRequest,
+  forwardPreviewPath,
+  pendingRequestFromCandidate,
+  portForwardPromptLabel,
+  portForwardPromptReason,
+  reviewPortForwardCandidate,
+  revocationCapabilities,
+} from './src/portForwardApproval';
+import {
+  changedForwardCandidates,
+  commandLabel,
+  debouncedForwardCandidateChanges,
+  descendantPidSet,
+  detectedForwardCandidates,
+  sameForwardCandidate,
+  stableForwardCandidates,
+  startPortForwardWatcher,
+} from './src/portForwardWatcher';
+import {
+  createPortScanScheduler,
+  parseLsofCwdRows,
+  parseLsofListenRows,
+  parseProcessRows,
+} from './src/portScanScheduler';
+import {
+  clientAcceptsGzipForTest,
+  compressibleResponseForTest,
+  createForwardTcpManager,
+  decodeBase64BodyForTest,
+  forwardRequestHeadersForTest,
+  forwardResponseHeadersForTest,
+  handleForwardHttpRequest,
+  localForwardUrlForTest,
+  patchForwardBodyForTest,
+  shouldGzipResponseForTest,
+} from './src/localForwarding';
+import {
+  connectForwardTunnel,
+  forwardTunnelUrl,
+  localForwardWebSocketUrl,
+  openForwardRequestForTest,
+  rawResponseHeadersForTest,
+  tunnelFetchResponseHeadersForTest,
+  tunnelRequestHeadersForTest,
+  webSocketProtocolsForTest,
+} from './src/forwardTunnel';
+
+function outcome(run) {
+  try {
+    const value = run();
+    return value === undefined ? { defined: false } : { defined: true, value };
+  } catch (error) {
+    return {
+      threw: true,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+async function drainMicrotasks() {
+  for (let turn = 0; turn < 12; turn += 1) {
+    await Promise.resolve();
+  }
+}
+
+function sha256Hex(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+// --- byte/frame specs (shared vocabulary with the ReScript conformance) --------------
+
+function bytesOfSpec(spec) {
+  if (spec.kind === 'utf8') {
+    return new TextEncoder().encode(spec.text);
+  }
+  if (spec.kind === 'hex') {
+    return Uint8Array.from(Buffer.from(spec.hex, 'hex'));
+  }
+  if (spec.kind === 'fill') {
+    const bytes = new Uint8Array(spec.length);
+    bytes.fill(spec.byte ?? 0);
+    return bytes;
+  }
+  if (spec.kind === 'pattern') {
+    // Deterministic non-constant payload: byte i = (seed + i * 31) % 256.
+    const bytes = new Uint8Array(spec.length);
+    for (let i = 0; i < spec.length; i += 1) {
+      bytes[i] = (spec.seed + i * 31) % 256;
+    }
+    return bytes;
+  }
+  if (spec.kind === 'headerBody') {
+    // Hand-built frame: raw header hex + a generated body (for decode-side
+    // refusals the encoder itself refuses to produce).
+    const header = Uint8Array.from(Buffer.from(spec.headerHex, 'hex'));
+    const body = bytesOfSpec(spec.body);
+    const bytes = new Uint8Array(header.byteLength + body.byteLength);
+    bytes.set(header, 0);
+    bytes.set(body, header.byteLength);
+    return bytes;
+  }
+  throw new Error('unknown bytes spec kind ' + String(spec.kind));
+}
+
+function frameOfSpec(spec) {
+  const base = { type: spec.type, streamId: spec.streamId };
+  if (spec.type === 'request_body_end' || spec.type === 'response_end') {
+    return base;
+  }
+  if (spec.type === 'request_body_chunk' || spec.type === 'response_body_chunk') {
+    return { ...base, payload: bytesOfSpec(spec.payload) };
+  }
+  if (spec.type === 'websocket_message') {
+    return { ...base, opcode: spec.opcode, payload: bytesOfSpec(spec.payload) };
+  }
+  return { ...base, payload: spec.payload };
+}
+
+function frameVerdict(frame) {
+  const base = { type: frame.type, streamId: frame.streamId };
+  if (frame.type === 'request_body_end' || frame.type === 'response_end') {
+    return base;
+  }
+  if (frame.type === 'request_body_chunk' || frame.type === 'response_body_chunk') {
+    return {
+      ...base,
+      payloadByteLength: frame.payload.byteLength,
+      payloadSha256: sha256Hex(frame.payload),
+    };
+  }
+  if (frame.type === 'websocket_message') {
+    return {
+      ...base,
+      opcode: frame.opcode,
+      payloadByteLength: frame.payload.byteLength,
+      payloadSha256: sha256Hex(frame.payload),
+    };
+  }
+  return { ...base, payload: frame.payload };
+}
+
+function handleEncodeFrame(testCase) {
+  try {
+    const encoded = encodeForwardTunnelFrame(frameOfSpec(testCase.frame));
+    return {
+      ok: true,
+      byteLength: encoded.byteLength,
+      sha256: sha256Hex(encoded),
+      headHex: Buffer.from(encoded.subarray(0, 64)).toString('hex'),
+    };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function decodeInputOfSpec(spec) {
+  if (spec.kind === 'frame') {
+    return encodeForwardTunnelFrame(frameOfSpec(spec.frame));
+  }
+  if (spec.kind === 'mutate') {
+    const bytes = Uint8Array.from(encodeForwardTunnelFrame(frameOfSpec(spec.frame)));
+    bytes[spec.index] = bytes[spec.index] ^ spec.xor;
+    return bytes;
+  }
+  return bytesOfSpec(spec);
+}
+
+function handleDecodeFrame(testCase) {
+  const decoded = decodeForwardTunnelBytes(decodeInputOfSpec(testCase.bytes));
+  return decoded.ok
+    ? { ok: true, frame: frameVerdict(decoded.frame) }
+    : { ok: false, error: decoded.error };
+}
+
+// --- approval -------------------------------------------------------------------------
+
+function candidateOfJson(value) {
+  return {
+    port: value.port,
+    pid: value.pid,
+    command: value.command,
+    ...(value.portKind === undefined ? {} : { portKind: value.portKind }),
+    ...(value.cwd === undefined ? {} : { cwd: value.cwd }),
+  };
+}
+
+function handleApprovalReview(testCase) {
+  return outcome(() =>
+    reviewPortForwardCandidate({
+      candidate: candidateOfJson(testCase.candidate),
+      threadBound: testCase.threadBound,
+      ...(testCase.suppressedPorts === undefined
+        ? {}
+        : { suppressedPorts: new Set(testCase.suppressedPorts) }),
+      approvedPorts: new Set(testCase.approvedPorts),
+      approvedTargets: new Map(
+        (testCase.approvedTargets ?? []).map(([port, target]) => [
+          port,
+          candidateOfJson(target),
+        ])
+      ),
+      ...(testCase.dismissedTargets === undefined
+        ? {}
+        : {
+            dismissedTargets: new Map(
+              testCase.dismissedTargets.map(([port, target]) => [
+                port,
+                candidateOfJson(target),
+              ])
+            ),
+          }),
+      pendingRequests: testCase.pendingRequests ?? [],
+    })
+  );
+}
+
+function handleApprovalHelpers(testCase) {
+  if (testCase.helper === 'pendingFromCandidate') {
+    return outcome(() =>
+      pendingRequestFromCandidate({
+        requestId: testCase.requestId,
+        sourceSeq: testCase.sourceSeq,
+        candidate: candidateOfJson(testCase.candidate),
+      })
+    );
+  }
+  if (testCase.helper === 'targetFromRequest') {
+    return outcome(() => approvedTargetFromRequest(testCase.request));
+  }
+  if (testCase.helper === 'promptLabel') {
+    return outcome(() => portForwardPromptLabel(candidateOfJson(testCase.candidate)));
+  }
+  if (testCase.helper === 'promptReason') {
+    return outcome(() => portForwardPromptReason(candidateOfJson(testCase.candidate)));
+  }
+  if (testCase.helper === 'previewPath') {
+    return outcome(() => forwardPreviewPath(testCase.runnerId, testCase.port));
+  }
+  if (testCase.helper === 'revocationCapabilities') {
+    return outcome(() => revocationCapabilities(testCase.capabilities, testCase.port));
+  }
+  return { threw: true, message: 'unknown approval helper' };
+}
+
+// --- watcher pure core ------------------------------------------------------------------
+
+function portMapOfEntries(entries) {
+  return new Map(entries.map(([port, value]) => [port, value]));
+}
+
+function portMapJson(map) {
+  return Array.from(map.entries());
+}
+
+function handleWatchPure(testCase) {
+  if (testCase.fn === 'parseProcessRows') {
+    return outcome(() => parseProcessRows(testCase.text));
+  }
+  if (testCase.fn === 'parseLsofListenRows') {
+    return outcome(() => parseLsofListenRows(testCase.text));
+  }
+  if (testCase.fn === 'parseLsofCwdRows') {
+    return outcome(() => Array.from(parseLsofCwdRows(testCase.text).entries()));
+  }
+  if (testCase.fn === 'descendantPidSet') {
+    return outcome(() => Array.from(descendantPidSet(testCase.rows, testCase.rootPid)));
+  }
+  if (testCase.fn === 'commandLabel') {
+    return outcome(() => commandLabel(testCase.command));
+  }
+  if (testCase.fn === 'sameForwardCandidate') {
+    return outcome(() =>
+      sameForwardCandidate(candidateOfJson(testCase.left), candidateOfJson(testCase.right))
+    );
+  }
+  if (testCase.fn === 'detectedForwardCandidates') {
+    return outcome(() =>
+      detectedForwardCandidates(
+        testCase.sockets,
+        new Set(testCase.descendantPids),
+        new Map(testCase.processCwds ?? []),
+        new Set(testCase.commanderBoundPids ?? []),
+        new Set(testCase.commanderBoundPorts ?? []),
+        new Set(testCase.watchPorts ?? [])
+      )
+    );
+  }
+  if (testCase.fn === 'stableSchedule') {
+    // Chained scans through stableForwardCandidates.
+    let observed = new Map();
+    const trace = [];
+    for (const scan of testCase.scans) {
+      const result = stableForwardCandidates(
+        observed,
+        scan.candidates.map(candidateOfJson),
+        scan.nowMs,
+        testCase.debounceMs
+      );
+      observed = result.nextObservedByPort;
+      trace.push({
+        stable: result.stableCandidates,
+        observed: portMapJson(result.nextObservedByPort),
+      });
+    }
+    return { trace };
+  }
+  if (testCase.fn === 'debouncedSchedule') {
+    let observed = portMapOfEntries(testCase.initialObserved ?? []);
+    let missing = new Map(
+      (testCase.initialMissing ?? []).map(([port, entry]) => [port, entry])
+    );
+    const trace = [];
+    for (const scan of testCase.scans) {
+      const result = debouncedForwardCandidateChanges(
+        observed,
+        missing,
+        scan.candidates.map(candidateOfJson),
+        scan.nowMs,
+        testCase.lostDebounceMs
+      );
+      observed = result.nextObservedByPort;
+      missing = result.nextMissingByPort;
+      trace.push({
+        changed: result.changedCandidates,
+        lost: result.lostCandidates,
+        observed: portMapJson(result.nextObservedByPort),
+        missing: portMapJson(result.nextMissingByPort),
+      });
+    }
+    return { trace };
+  }
+  if (testCase.fn === 'changedSchedule') {
+    let observed = new Map();
+    const trace = [];
+    for (const scan of testCase.scans) {
+      const result = changedForwardCandidates(observed, scan.candidates.map(candidateOfJson));
+      observed = result.nextObservedByPort;
+      trace.push({
+        changed: result.changedCandidates,
+        lost: result.lostCandidates,
+        observed: portMapJson(result.nextObservedByPort),
+      });
+    }
+    return { trace };
+  }
+  return { threw: true, message: 'unknown watch fn' };
+}
+
+// --- http/tunnel pure seams -------------------------------------------------------------
+
+function headersEntries(headers) {
+  return Array.from(headers.entries());
+}
+
+function handleHttpPure(testCase) {
+  if (testCase.fn === 'decodeBase64Body') {
+    return outcome(() => {
+      const decoded = decodeBase64BodyForTest(testCase.value);
+      return decoded === undefined
+        ? { decoded: false }
+        : { decoded: true, byteLength: decoded.byteLength, sha256: sha256Hex(decoded) };
+    });
+  }
+  if (testCase.fn === 'forwardRequestHeaders') {
+    return outcome(() => headersEntries(forwardRequestHeadersForTest(testCase.headers)));
+  }
+  if (testCase.fn === 'forwardResponseHeaders') {
+    return outcome(() => {
+      const headers = new Headers();
+      for (const [name, value] of testCase.entries) {
+        headers.set(name, value);
+      }
+      return forwardResponseHeadersForTest(headers);
+    });
+  }
+  if (testCase.fn === 'patchForwardBody') {
+    return outcome(() => {
+      const headers = new Headers();
+      for (const [name, value] of testCase.entries) {
+        headers.set(name, value);
+      }
+      return patchForwardBodyForTest(
+        testCase.path,
+        headers,
+        Buffer.from(testCase.bodyUtf8, 'utf8')
+      ).toString('utf8');
+    });
+  }
+  if (testCase.fn === 'shouldGzipResponse') {
+    return outcome(() => {
+      const headers = new Headers();
+      for (const [name, value] of testCase.entries) {
+        headers.set(name, value);
+      }
+      return shouldGzipResponseForTest(
+        testCase.control,
+        headers,
+        Buffer.from(bytesOfSpec(testCase.body))
+      );
+    });
+  }
+  if (testCase.fn === 'clientAcceptsGzip') {
+    return outcome(() => clientAcceptsGzipForTest(testCase.headers));
+  }
+  if (testCase.fn === 'compressibleResponse') {
+    return outcome(() => {
+      const headers = new Headers();
+      for (const [name, value] of testCase.entries) {
+        headers.set(name, value);
+      }
+      return compressibleResponseForTest(testCase.path, headers);
+    });
+  }
+  if (testCase.fn === 'localForwardUrl') {
+    return outcome(() =>
+      localForwardUrlForTest(
+        testCase.scheme,
+        testCase.port,
+        testCase.path,
+        testCase.queryString ?? undefined
+      )
+    );
+  }
+  if (testCase.fn === 'forwardTunnelUrl') {
+    return outcome(() =>
+      forwardTunnelUrl(testCase.baseUrl, testCase.runnerId, testCase.token, testCase.generation)
+    );
+  }
+  if (testCase.fn === 'localForwardWebSocketUrl') {
+    return outcome(() =>
+      localForwardWebSocketUrl(
+        testCase.scheme,
+        testCase.port,
+        testCase.path,
+        testCase.queryString ?? undefined
+      )
+    );
+  }
+  if (testCase.fn === 'openForwardRequest') {
+    return outcome(() => {
+      const request = openForwardRequestForTest(testCase.payload);
+      return request === undefined
+        ? { parsed: false }
+        : {
+            parsed: true,
+            port: request.port,
+            method: request.method,
+            path: request.path,
+            queryString: request.queryString ?? null,
+            headerEntries: headersEntries(request.headers),
+          };
+    });
+  }
+  if (testCase.fn === 'tunnelRequestHeaders') {
+    return outcome(() => headersEntries(tunnelRequestHeadersForTest(testCase.headers)));
+  }
+  if (testCase.fn === 'tunnelFetchResponseHeaders') {
+    return outcome(() => {
+      const headers = new Headers();
+      for (const [name, value] of testCase.entries) {
+        headers.set(name, value);
+      }
+      return tunnelFetchResponseHeadersForTest(headers);
+    });
+  }
+  if (testCase.fn === 'rawResponseHeaders') {
+    return outcome(() => rawResponseHeadersForTest(testCase.headers));
+  }
+  if (testCase.fn === 'webSocketProtocols') {
+    return outcome(() => {
+      const headers = new Headers();
+      for (const [name, value] of testCase.entries) {
+        headers.set(name, value);
+      }
+      return webSocketProtocolsForTest(headers) ?? null;
+    });
+  }
+  return { threw: true, message: 'unknown http fn' };
+}
+
+// --- TCP manager flow ---------------------------------------------------------------------
+
+async function handleTcpFlow(testCase) {
+  const pushed = [];
+  const sockets = [];
+  const manager = createForwardTcpManager(
+    {
+      push: (topic, event, payload) => {
+        pushed.push({ topic, event, payload });
+        if (testCase.pushRejects === true) {
+          return Promise.reject(new Error('scripted push failure'));
+        }
+        return Promise.resolve({ ok: true });
+      },
+    },
+    testCase.topic,
+    () => testCase.allowedPorts,
+    (port) => {
+      const listeners = new Map();
+      const record = {
+        port,
+        writes: [],
+        ended: false,
+        destroyed: false,
+        writable: true,
+        emit: (event, ...args) => {
+          for (const listener of listeners.get(event) ?? []) {
+            listener(...args);
+          }
+        },
+      };
+      const socket = {
+        get destroyed() {
+          return record.destroyed;
+        },
+        get writable() {
+          return record.writable;
+        },
+        on: (event, listener) => {
+          listeners.set(event, [...(listeners.get(event) ?? []), listener]);
+          return socket;
+        },
+        write: (data) => {
+          record.writes.push(Buffer.from(data).toString('base64'));
+          return true;
+        },
+        end: () => {
+          record.ended = true;
+          record.writable = false;
+        },
+        destroy: () => {
+          record.destroyed = true;
+          record.writable = false;
+        },
+      };
+      record.socket = socket;
+      sockets.push(record);
+      return socket;
+    }
+  );
+  for (const step of testCase.script ?? []) {
+    if (step.step === 'open') {
+      manager.handle({ type: 'forward_tcp_open', socketId: step.socketId, port: step.port });
+    } else if (step.step === 'send') {
+      manager.handle({
+        type: 'forward_tcp_send',
+        socketId: step.socketId,
+        bodyBase64: step.bodyBase64,
+      });
+    } else if (step.step === 'close') {
+      manager.handle({ type: 'forward_tcp_close', socketId: step.socketId });
+    } else if (step.step === 'closeAll') {
+      manager.close();
+    } else if (step.step === 'socketEvent') {
+      const record = sockets[step.index];
+      if (step.event === 'data') {
+        record?.emit('data', Buffer.from(step.bodyBase64, 'base64'));
+      } else {
+        record?.emit(step.event);
+      }
+    } else if (step.step === 'setWritable') {
+      const record = sockets[step.index];
+      if (record) {
+        record.writable = step.value;
+      }
+    }
+    await drainMicrotasks();
+  }
+  return {
+    pushed,
+    sockets: sockets.map((record) => ({
+      port: record.port,
+      writes: record.writes,
+      ended: record.ended,
+      destroyed: record.destroyed,
+    })),
+  };
+}
+
+// --- legacy HTTP forward (real handler, real loopback server) --------------------------------
+
+function bodyOfRouteSpec(spec) {
+  if (spec.kind === 'gzip-utf8') {
+    return gzipSync(Buffer.from(spec.text, 'utf8'));
+  }
+  if (spec.kind === 'utf8') {
+    return Buffer.from(spec.text, 'utf8');
+  }
+  if (spec.kind === 'repeat') {
+    return Buffer.from(spec.text.repeat(spec.count), 'utf8');
+  }
+  return Buffer.from(bytesOfSpec(spec));
+}
+
+function startScriptedHttpServer(spec) {
+  return new Promise((resolve) => {
+    const observed = [];
+    const server = createServer((request, response) => {
+      const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+      observed.push({
+        method: request.method,
+        path: url.pathname,
+        search: url.search,
+        host: request.headers.host ?? null,
+      });
+      const route = (spec.routes ?? []).find((entry) => entry.path === url.pathname);
+      if (route === undefined) {
+        response.writeHead(404, { 'content-type': 'text/plain' });
+        response.end('unscripted route');
+        return;
+      }
+      response.writeHead(route.status ?? 200, Object.fromEntries(route.headers ?? []));
+      response.end(bodyOfRouteSpec(route.body ?? { kind: 'utf8', text: '' }));
+    });
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: server.address().port,
+        observed,
+        stop: () => new Promise((resolveStop) => server.close(() => resolveStop())),
+      });
+    });
+  });
+}
+
+function substitutePort(value, port) {
+  if (value === '$PORT') {
+    return port;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => substitutePort(entry, port));
+  }
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, substitutePort(entry, port)])
+    );
+  }
+  return value;
+}
+
+async function handleHttpForward(testCase) {
+  let server;
+  let port = testCase.targetPort;
+  if (testCase.server !== undefined) {
+    server = await startScriptedHttpServer(testCase.server);
+    port = server.port;
+  }
+  try {
+    const control = substitutePort(testCase.control, port);
+    const allowedPorts = substitutePort(testCase.allowedPorts, port);
+    const reply = await handleForwardHttpRequest(control, allowedPorts);
+    return { reply, observed: server?.observed ?? [] };
+  } finally {
+    await server?.stop();
+  }
+}
+
+// --- watcher flow over a scripted scheduler ------------------------------------------------------
+
+async function handleWatcherFlow(testCase) {
+  const events = [];
+  let currentNow = 0;
+  let subscriberRef;
+  const scheduler = {
+    subscribe: (subscriber) => {
+      subscriberRef = subscriber;
+      return { unsubscribe: () => events.push({ t: 'unsubscribed' }) };
+    },
+    subscriberCount: () => (subscriberRef === undefined ? 0 : 1),
+    isRunning: () => subscriberRef !== undefined,
+  };
+  const extraScript = [...(testCase.extraWatchPortsScript ?? [])];
+  let watcher;
+  try {
+    watcher = startPortForwardWatcher({
+      rootPid: testCase.rootPid ?? undefined,
+      ...(testCase.debounceMs === undefined ? {} : { debounceMs: testCase.debounceMs }),
+      ...(testCase.lostDebounceMs === undefined
+        ? {}
+        : { lostDebounceMs: testCase.lostDebounceMs }),
+      ...(testCase.intervalMs === undefined ? {} : { intervalMs: testCase.intervalMs }),
+      ...(testCase.commanderBoundPids === undefined
+        ? {}
+        : { commanderBoundPids: testCase.commanderBoundPids }),
+      ...(testCase.commanderBoundPorts === undefined
+        ? {}
+        : { commanderBoundPorts: testCase.commanderBoundPorts }),
+      ...(testCase.watchPorts === undefined ? {} : { watchPorts: testCase.watchPorts }),
+      ...(testCase.extraWatchPortsScript === undefined
+        ? {}
+        : {
+            extraWatchPorts: () => {
+              const entry = extraScript.length > 1 ? extraScript.shift() : extraScript[0];
+              events.push({ t: 'extraWatchPortsRead' });
+              if (entry === 'throw') {
+                throw new Error('scripted registry failure');
+              }
+              return entry ?? [];
+            },
+          }),
+      scheduler,
+      nowMs: () => currentNow,
+      onCandidate: (candidate) => {
+        events.push({ t: 'candidate', candidate });
+      },
+      onCandidateLost: (candidate) => {
+        events.push({ t: 'lost', candidate });
+      },
+      onListenersObserved: (listeners) => {
+        events.push({ t: 'listeners', listeners });
+      },
+      onError: (error) => {
+        events.push({ t: 'error', message: error.message });
+      },
+    });
+  } catch (error) {
+    return { threw: error instanceof Error ? error.message : String(error), events };
+  }
+  for (const scan of testCase.scans ?? []) {
+    currentNow = scan.nowMs;
+    if (scan.backoff !== undefined) {
+      subscriberRef.onBackoff?.({
+        consecutiveFailures: scan.backoff.consecutiveFailures,
+        intervalMs: scan.backoff.intervalMs,
+        error: new Error(scan.backoff.message),
+      });
+      await drainMicrotasks();
+      continue;
+    }
+    if (scan.recovered !== undefined) {
+      subscriberRef.onRecovered?.({ failedScans: scan.recovered.failedScans });
+      await drainMicrotasks();
+      continue;
+    }
+    // Fresh array identities per scan, exactly like the real scheduler.
+    const processRows = (scan.processRows ?? []).map((row) => ({ ...row }));
+    const sockets = (scan.sockets ?? []).map((row) => ({ ...row }));
+    const pids = subscriberRef.candidatePids(processRows, sockets);
+    events.push({ t: 'candidatePids', pids });
+    await subscriberRef.deliver({
+      processRows,
+      listenSockets: sockets,
+      processCwds: new Map(scan.cwds ?? []),
+      scannedAtMs: scan.nowMs,
+    });
+    await drainMicrotasks();
+  }
+  watcher.close();
+  return { events };
+}
+
+// --- scheduler flow with gated probes ---------------------------------------------------------------
+
+async function handleSchedulerFlow(testCase) {
+  const events = [];
+  const ticks = [...testCase.ticks];
+  let nowIndex = 0;
+  const nows = testCase.nows ?? [];
+  let cwdProbeCalls = 0;
+  let scanCalls = 0;
+  let currentTick;
+  let resolveDone;
+  const done = new Promise((resolve) => {
+    resolveDone = resolve;
+  });
+  const scheduler = createPortScanScheduler({
+    intervalMs: testCase.intervalMs,
+    backoffIntervalsMs: testCase.backoffIntervalsMs,
+    ...(testCase.scanBudgetMs === undefined ? {} : { scanBudgetMs: testCase.scanBudgetMs }),
+    nowMs: () => {
+      const value = nows.length === 0 ? 0 : nows[Math.min(nowIndex, nows.length - 1)];
+      nowIndex += 1;
+      return value;
+    },
+    probes: {
+      scanProcesses: () => {
+        const tick = ticks.shift();
+        if (tick === undefined) {
+          // Script exhausted: the (N+1)th scan is the completion signal;
+          // park forever, the driver unsubscribes.
+          resolveDone();
+          return new Promise(() => undefined);
+        }
+        events.push({ t: 'scan', index: scanCalls });
+        scanCalls += 1;
+        if (tick.processes === 'throw') {
+          currentTick = undefined;
+          return Promise.reject(new Error(tick.errorMessage ?? 'scripted ps failure'));
+        }
+        if (tick.processes === 'never') {
+          currentTick = undefined;
+          return new Promise(() => undefined);
+        }
+        currentTick = tick;
+        return Promise.resolve(tick.processes ?? []);
+      },
+      scanListenSockets: () => Promise.resolve(currentTick?.sockets ?? []),
+      scanProcessCwds: (_pids) => {
+        cwdProbeCalls += 1;
+        return Promise.resolve(new Map(currentTick?.cwds ?? []));
+      },
+    },
+  });
+  const subscription = scheduler.subscribe({
+    candidatePids: (_rows, sockets) => sockets.map((socket) => socket.pid),
+    deliver: (snapshot) => {
+      events.push({
+        t: 'deliver',
+        pids: snapshot.processRows.map((row) => row.pid),
+        sockets: snapshot.listenSockets.map((socket) => socket.port),
+        cwds: Array.from(snapshot.processCwds.entries()),
+      });
+    },
+    onError: (error) => {
+      events.push({ t: 'error', message: error.message });
+    },
+    onBackoff: (info) => {
+      events.push({
+        t: 'backoff',
+        consecutiveFailures: info.consecutiveFailures,
+        intervalMs: info.intervalMs,
+        message: info.error.message,
+      });
+    },
+    onRecovered: (info) => {
+      events.push({ t: 'recovered', failedScans: info.failedScans });
+    },
+  });
+  const guard = setTimeout(() => resolveDone(), 10_000);
+  await done;
+  clearTimeout(guard);
+  await drainMicrotasks();
+  subscription.unsubscribe();
+  events.push({
+    t: 'final',
+    cwdProbeCalls,
+    subscriberCount: scheduler.subscriberCount(),
+    isRunning: scheduler.isRunning(),
+  });
+  return { events };
+}
+
+// --- streaming tunnel: scripted-socket flow ---------------------------------------------------------
+
+class ScriptedSocket extends EventTarget {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+
+  constructor(url, protocols) {
+    super();
+    this.url = String(url);
+    this.protocols =
+      protocols === undefined ? null : Array.isArray(protocols) ? protocols : [protocols];
+    this.readyState = ScriptedSocket.CONNECTING;
+    this.sent = [];
+    this.binaryType = 'blob';
+  }
+
+  send(message) {
+    if (typeof message === 'string') {
+      this.sent.push({ kind: 'text', text: message });
+      return;
+    }
+    const bytes =
+      message instanceof ArrayBuffer ? new Uint8Array(message) : Uint8Array.from(message);
+    this.sent.push({ kind: 'binary', hex: Buffer.from(bytes).toString('hex') });
+  }
+
+  close() {
+    if (this.readyState === ScriptedSocket.CLOSED) {
+      return;
+    }
+    this.readyState = ScriptedSocket.CLOSED;
+    this.sent.push({ kind: 'closed_by_client' });
+  }
+
+  scriptOpen() {
+    if (this.readyState !== ScriptedSocket.CONNECTING) {
+      return;
+    }
+    this.readyState = ScriptedSocket.OPEN;
+    this.dispatchEvent(new Event('open'));
+  }
+
+  scriptFail() {
+    this.dispatchEvent(new Event('error'));
+  }
+
+  scriptClose(code, reason) {
+    this.readyState = ScriptedSocket.CLOSED;
+    this.dispatchEvent(Object.assign(new Event('close'), { code, reason }));
+  }
+
+  scriptMessage(data) {
+    this.dispatchEvent(Object.assign(new Event('message'), { data }));
+  }
+}
+
+async function handleTunnelFlow(testCase) {
+  const originalWebSocket = globalThis.WebSocket;
+  const localSockets = [];
+  const tunnelSockets = [];
+
+  class ScriptedLocalWebSocket extends ScriptedSocket {
+    constructor(url, protocols) {
+      super(url, protocols);
+      localSockets.push(this);
+    }
+  }
+
+  globalThis.WebSocket = ScriptedLocalWebSocket;
+  try {
+    const tunnel = await (async () => {
+      const connectPromise = connectForwardTunnel({
+        kandanUrl: testCase.serviceUrl ?? 'ws://scripted.test',
+        token: 'synthetic-token',
+        runnerId: 'commander-1',
+        allowedPorts: () => testCase.allowedPorts ?? [],
+        socketFactory: (url) => {
+          const socket = new ScriptedSocket(url);
+          tunnelSockets.push(socket);
+          queueMicrotask(() => socket.scriptOpen());
+          return socket;
+        },
+      });
+      return connectPromise;
+    })();
+    const trace = [];
+    const tunnelSocket = tunnelSockets[0];
+    for (const step of testCase.script ?? []) {
+      if (step.step === 'deliver') {
+        const bytes = encodeForwardTunnelFrame(frameOfSpec(step.frame));
+        tunnelSocket.scriptMessage(
+          bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)
+        );
+      } else if (step.step === 'deliverRepeat') {
+        for (let i = 0; i < step.count; i += 1) {
+          const bytes = encodeForwardTunnelFrame(frameOfSpec(step.frame));
+          tunnelSocket.scriptMessage(
+            bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)
+          );
+        }
+      } else if (step.step === 'localOpen') {
+        localSockets[step.index]?.scriptOpen();
+      } else if (step.step === 'localFail') {
+        localSockets[step.index]?.scriptFail();
+      } else if (step.step === 'localClose') {
+        localSockets[step.index]?.scriptClose(step.code, step.reason);
+      } else if (step.step === 'localMessage') {
+        const socket = localSockets[step.index];
+        if (step.text !== undefined) {
+          socket?.scriptMessage(step.text);
+        } else {
+          const bytes = Buffer.from(step.base64, 'base64');
+          socket?.scriptMessage(
+            bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)
+          );
+        }
+      } else if (step.step === 'closeTunnel') {
+        tunnel.close();
+      } else if (step.step === 'note') {
+        trace.push({ t: 'note', note: step.note });
+      }
+      await drainMicrotasks();
+    }
+    tunnel.close();
+    await drainMicrotasks();
+    return {
+      trace,
+      tunnelFrames: tunnelSocket.sent.map((entry) =>
+        entry.kind === 'binary'
+          ? (() => {
+              const decoded = decodeForwardTunnelBytes(
+                Uint8Array.from(Buffer.from(entry.hex, 'hex'))
+              );
+              return decoded.ok
+                ? { frame: frameVerdict(decoded.frame), hexSha256: sha256Hex(entry.hex) }
+                : { undecodable: true, hex: entry.hex };
+            })()
+          : entry
+      ),
+      localSockets: localSockets.map((socket) => ({
+        url: socket.url,
+        protocols: socket.protocols,
+        sent: socket.sent,
+      })),
+    };
+  } finally {
+    globalThis.WebSocket = originalWebSocket;
+  }
+}
+
+// --- tunnel-serve process mode ------------------------------------------------------------------------
+
+function normalizeHeaderList(headers) {
+  return headers.map((entry) =>
+    entry.name.toLowerCase() === 'date' ? { name: entry.name, value: '<date>' } : entry
+  );
+}
+
+function normalizeTranscript(frames) {
+  const normalized = [];
+  for (const frame of frames) {
+    if (frame.type === 'response_body_chunk') {
+      const last = normalized[normalized.length - 1];
+      if (last !== undefined && last.type === 'response_body' && last.streamId === frame.streamId) {
+        last.chunksBase64.push(Buffer.from(frame.payload).toString('base64'));
+        continue;
+      }
+      normalized.push({
+        type: 'response_body',
+        streamId: frame.streamId,
+        chunksBase64: [Buffer.from(frame.payload).toString('base64')],
+      });
+      continue;
+    }
+    if (frame.type === 'response_headers') {
+      normalized.push({
+        type: frame.type,
+        streamId: frame.streamId,
+        status: frame.payload.status,
+        headers: normalizeHeaderList(frame.payload.headers ?? []),
+      });
+      continue;
+    }
+    if (frame.type === 'websocket_message') {
+      normalized.push({
+        type: frame.type,
+        streamId: frame.streamId,
+        opcode: frame.opcode,
+        base64: Buffer.from(frame.payload).toString('base64'),
+      });
+      continue;
+    }
+    normalized.push({
+      type: frame.type,
+      streamId: frame.streamId,
+      ...(frame.payload === undefined ? {} : { payload: frame.payload }),
+    });
+  }
+  // Coalesce body chunk lists into one byte-exact base64 (chunk boundaries
+  // are OS timing, not protocol).
+  return normalized.map((entry) =>
+    entry.type === 'response_body'
+      ? {
+          type: entry.type,
+          streamId: entry.streamId,
+          bodyBase64: Buffer.concat(
+            entry.chunksBase64.map((chunk) => Buffer.from(chunk, 'base64'))
+          ).toString('base64'),
+        }
+      : entry
+  );
+}
+
+async function runTunnelServe() {
+  let stdinBuffer = '';
+  const lineWaiters = [];
+  const pendingLines = [];
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    stdinBuffer += chunk;
+    let index = stdinBuffer.indexOf('\\n');
+    while (index >= 0) {
+      const line = stdinBuffer.slice(0, index);
+      stdinBuffer = stdinBuffer.slice(index + 1);
+      const waiter = lineWaiters.shift();
+      if (waiter === undefined) {
+        pendingLines.push(line);
+      } else {
+        waiter(line);
+      }
+      index = stdinBuffer.indexOf('\\n');
+    }
+  });
+  const nextLine = () =>
+    pendingLines.length > 0
+      ? Promise.resolve(pendingLines.shift())
+      : new Promise((resolve) => lineWaiters.push(resolve));
+
+  const spec = JSON.parse(await nextLine());
+
+  // Local scripted HTTP target.
+  const localEventsPerConnection = [];
+  const httpServer = createServer((request, response) => {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const active = localEventsPerConnection[localEventsPerConnection.length - 1];
+    active?.push({ t: 'http_request', method: request.method, path: url.pathname, search: url.search });
+    const route = (spec.localHttp?.routes ?? []).find((entry) => entry.path === url.pathname);
+    if (route === undefined) {
+      response.writeHead(404, { 'content-type': 'text/plain' });
+      response.end('unscripted route');
+      return;
+    }
+    if (route.mode === 'hold-after-first-chunk') {
+      response.writeHead(route.status ?? 200, Object.fromEntries(route.headers ?? []));
+      response.write(bodyOfRouteSpec(route.body ?? { kind: 'utf8', text: 'open' }));
+      request.on('close', () => {
+        active?.push({ t: 'local_abort' });
+      });
+      return;
+    }
+    if (route.method !== undefined && route.method !== request.method) {
+      response.writeHead(405, { 'content-type': 'text/plain' });
+      response.end('wrong method');
+      return;
+    }
+    if (route.echoBody === true) {
+      const chunks = [];
+      request.on('data', (chunk) => chunks.push(chunk));
+      request.on('end', () => {
+        const body = Buffer.concat(chunks);
+        active?.push({ t: 'http_body', base64: body.toString('base64') });
+        response.writeHead(route.status ?? 200, Object.fromEntries(route.headers ?? []));
+        response.end(Buffer.concat([Buffer.from('echo:'), body]));
+      });
+      return;
+    }
+    response.writeHead(route.status ?? 200, Object.fromEntries(route.headers ?? []));
+    response.end(bodyOfRouteSpec(route.body ?? { kind: 'utf8', text: '' }));
+  });
+  await new Promise((resolve) => httpServer.listen(0, '127.0.0.1', resolve));
+  const localHttpPort = httpServer.address().port;
+
+  // Local ws echo target.
+  let wsEchoPort = 0;
+  let wsEchoServer;
+  if (spec.wsEcho === true) {
+    wsEchoServer = new WebSocketServer({
+      host: '127.0.0.1',
+      port: 0,
+      // Accept the first requested subprotocol so subprotocol-carrying
+      // clients (both impls dial with the forwarded header) can open.
+      handleProtocols: (protocols) => protocols.values().next().value ?? false,
+    });
+    wsEchoServer.on('connection', (socket, request) => {
+      const active = localEventsPerConnection[localEventsPerConnection.length - 1];
+      active?.push({
+        t: 'ws_connect',
+        path: request.url,
+        protocol: request.headers['sec-websocket-protocol'] ?? null,
+      });
+      socket.on('message', (data, isBinary) => {
+        if (isBinary) {
+          socket.send(data);
+        } else {
+          socket.send('echo:' + data.toString());
+        }
+      });
+    });
+    await new Promise((resolve) => wsEchoServer.on('listening', resolve));
+    wsEchoPort = wsEchoServer.address().port;
+  }
+
+  const substitute = (value) => {
+    if (value === '$HTTP_PORT') {
+      return localHttpPort;
+    }
+    if (value === '$WS_PORT') {
+      return wsEchoPort;
+    }
+    if (Array.isArray(value)) {
+      return value.map(substitute);
+    }
+    if (typeof value === 'object' && value !== null) {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, entry]) => [key, substitute(entry)])
+      );
+    }
+    return value;
+  };
+
+  // The scripted server-side tunnel endpoint.
+  const tunnelServer = new WebSocketServer({ host: '127.0.0.1', port: 0 });
+  tunnelServer.on('connection', (socket, request) => {
+    const localEvents = [];
+    localEventsPerConnection.push(localEvents);
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const frames = [];
+    let finished = false;
+    const doneOn = spec.doneOn ?? { frameType: 'response_end', count: 1 };
+    const reactions = (spec.reactions ?? []).map((reaction) => ({ ...reaction, fired: false }));
+    let doneSeen = 0;
+    let doneTimer;
+    const finish = () => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      process.stdout.write(
+        JSON.stringify({
+          transcript: {
+            connectPath: url.pathname,
+            token: url.searchParams.get('token'),
+            generation: url.searchParams.get('generation') === null ? null : '<generation>',
+            frames: normalizeTranscript(frames),
+            localEvents,
+          },
+        }) + '\\n'
+      );
+      // The socket deliberately stays OPEN: closing it would trip the
+      // client's 250ms reconnect, replaying the script and interleaving
+      // extra transcript lines. The driver closes its client handle after
+      // reading the transcript.
+    };
+    // A per-connection safety net so a diverging impl still yields a
+    // transcript to compare (with a timeout marker) instead of hanging CI.
+    const safety = setTimeout(() => {
+      frames.push({ type: 'transcript_timeout', streamId: 0 });
+      finish();
+    }, 15_000);
+    safety.unref?.();
+    socket.on('message', (data) => {
+      const bytes = Buffer.isBuffer(data) ? Uint8Array.from(data) : new Uint8Array(data);
+      const decoded = decodeForwardTunnelBytes(bytes);
+      if (!decoded.ok) {
+        frames.push({ type: 'undecodable', streamId: 0 });
+        return;
+      }
+      frames.push(decoded.frame);
+      for (const reaction of reactions) {
+        if (!reaction.fired && decoded.frame.type === reaction.on) {
+          reaction.fired = true;
+          socket.send(encodeForwardTunnelFrame(frameOfSpec(substitute(reaction.frame))));
+        }
+      }
+      if (decoded.frame.type === (doneOn.frameType ?? 'response_end')) {
+        doneSeen += 1;
+        if (doneSeen >= (doneOn.count ?? 1)) {
+          // Small settle window: trailing frames on the wire (e.g. the
+          // response_end after a body) land before the transcript prints.
+          clearTimeout(doneTimer);
+          doneTimer = setTimeout(() => {
+            clearTimeout(safety);
+            finish();
+          }, doneOn.settleMs ?? 150);
+        }
+      }
+    });
+    for (const step of spec.script ?? []) {
+      socket.send(encodeForwardTunnelFrame(frameOfSpec(substitute(step.frame))));
+    }
+  });
+  await new Promise((resolve) => tunnelServer.on('listening', resolve));
+  const tunnelPort = tunnelServer.address().port;
+
+  process.stdout.write(
+    JSON.stringify({ tunnelPort, localHttpPort, wsEchoPort }) + '\\n'
+  );
+
+  const openHandles = [];
+  for (;;) {
+    const command = await nextLine();
+    if (command === 'run-ts') {
+      const allowed = [localHttpPort, wsEchoPort]
+        .filter((port) => port > 0)
+        .concat(spec.extraAllowedPorts ?? []);
+      const handle = await connectForwardTunnel({
+        kandanUrl: 'ws://127.0.0.1:' + tunnelPort,
+        token: 'synthetic-token',
+        runnerId: 'commander-1',
+        allowedPorts: () => allowed,
+      });
+      openHandles.push(handle);
+    } else if (command === 'exit') {
+      break;
+    }
+  }
+  for (const handle of openHandles) {
+    handle.close();
+  }
+  await new Promise((resolve) => tunnelServer.close(resolve));
+  wsEchoServer?.close();
+  await new Promise((resolve) => httpServer.close(resolve));
+  process.exit(0);
+}
+
+// --- batch dispatch --------------------------------------------------------------------------------------
+
+async function handle(testCase) {
+  switch (testCase.op) {
+    case 'encodeFrame':
+      return handleEncodeFrame(testCase);
+    case 'decodeFrame':
+      return handleDecodeFrame(testCase);
+    case 'chunkBytesConstant':
+      return { value: forwardTunnelChunkBytes };
+    case 'approvalReview':
+      return handleApprovalReview(testCase);
+    case 'approvalHelpers':
+      return handleApprovalHelpers(testCase);
+    case 'watchPure':
+      return handleWatchPure(testCase);
+    case 'httpPure':
+      return handleHttpPure(testCase);
+    case 'tcpFlow':
+      return handleTcpFlow(testCase);
+    case 'httpForward':
+      return handleHttpForward(testCase);
+    case 'watcherFlow':
+      return handleWatcherFlow(testCase);
+    case 'schedulerFlow':
+      return handleSchedulerFlow(testCase);
+    case 'tunnelFlow':
+      return handleTunnelFlow(testCase);
+    default:
+      return { threw: true, message: 'unknown op ' + String(testCase.op) };
+  }
+}
+
+if (process.argv[2] === 'tunnel-serve') {
+  await runTunnelServe();
+} else {
+  let stdin = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    stdin += chunk;
+  }
+  const cases = JSON.parse(stdin);
+  const results = [];
+  for (const testCase of cases) {
+    results.push(await handle(testCase));
+  }
+  // No process.exit here: a large result array must fully flush stdout.
+  process.stdout.write(JSON.stringify(results));
+}
+`;
+
+await mkdir(join(packageRoot, '.differential'), { recursive: true });
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'forwarding-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/forwarding-parity-oracle.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});