faberun 0.26.3 → 0.28.0

package/src/harnesses/fx/runner.mjs

@@ -0,0 +1,350 @@
+/**
+ * Faberun's fx client: one prompt on stdin, one JSONL transcript on stdout,
+ * no interactive surface. The adapter runs this file under
+ * `process.execPath`, so spawning it never depends on a shebang, an
+ * executable bit, or `node` being on the provider's PATH.
+ *
+ * Why ACP instead of `fx ask --json`: `ask` prints its JSON once, at exit, so
+ * the controller's stall detector would see a silent worker for the whole
+ * turn, and its only permission choices are "everything" or "let the model
+ * review itself". `fx acp` streams every tool call as it happens and, in
+ * `ask` mode, sends each shell command and file mutation to this client as
+ * `session/request_permission`, so the file-effect boundary the contract
+ * names is decided here, per path. Measured 2026-09-24 against
+ * api.deepseek.com: seven permission requests for one parseDuration turn,
+ * every file mutation carrying its `path` in `rawInput`.
+ *
+ * Usage and provider failures come from the loopback relay in
+ * `usage-proxy.mjs`, never from fx: fx's usage omits the cache split and its
+ * provider errors arrive as prose.
+ *
+ * Transcript, the only thing this process writes to stdout:
+ *   {"type":"fx.started","sessionId":string}
+ *   {"type":"fx.tool","name":string,"target":string|null}      one per tool call
+ *   {"type":"fx.request","status":number,"usage":Usage|null}   one per provider request
+ *   {"type":"fx.message","text":string}                        one per non-empty assistant message
+ *   {"type":"fx.completed","sessionId":string,"result":string,"usage":Usage|null}
+ *   {"type":"fx.failed","sessionId":string|null,"kind":string,"error":{...},"usage":Usage|null}
+ * where Usage is `{inputTokens, outputTokens, cacheReadInputTokens}` with
+ * `inputTokens` excluding the cached prefix, matching `canonicalUsage`.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnInvocation } from "../../host/platform.mjs";
+import { emit, readPrompt } from "../runner-io.mjs";
+import { prepareFxHome } from "./home.mjs";
+import { permissionVerdict } from "./permissions.mjs";
+import { startUsageProxy } from "./usage-proxy.mjs";
+
+/** The provider name the generated settings give the relay connection. */
+const PROVIDER = "faberun";
+/**
+ * fx's built-in ChatGPT-subscription provider, and the Responses endpoint it
+ * posts to; the relay stands in for the host.
+ */
+const CODEX_PROVIDER = "codex";
+const CODEX_UPSTREAM = "https://chatgpt.com/backend-api/codex";
+/**
+ * Which of fx's provider paths the worker takes: `openai-compatible` is a
+ * custom Chat Completions connection (DeepSeek, Z.ai) authenticated by a key
+ * in the environment; `codex` is fx's ChatGPT login, which fx-faberun reads
+ * from the operator's real profile through `FX_AUTH_HOME`.
+ */
+const PROVIDER_KINDS = new Set(["openai-compatible", "codex"]);
+/**
+ * Measured: DeepSeek's `max_tokens` ceiling on deepseek-flash; fx needs a
+ * declared value. It is the default, not a law: a runtime may declare
+ * `max_output_tokens` when its provider allows more. Measured 2026-09-27 on
+ * frb-linux2: a `faberun plan` draft node cannot fit in 8,192 output tokens
+ * and died with `OutputTruncated` with no way to raise the ceiling.
+ */
+const MAX_OUTPUT_TOKENS = 8192;
+
+/** @typedef {{fx: string, model: string, sandbox: string, provider: string, baseUrl: string|null, keyEnv: string, contextWindow: number, maxOutputTokens: number}} RunnerOptions */
+
+/**
+ * @param {string[]} argv
+ * @returns {RunnerOptions}
+ */
+function parseArgs(argv) {
+  /** @type {RunnerOptions} */
+  const options = {
+    fx: "fx",
+    model: "",
+    sandbox: "workspace-write",
+    provider: "openai-compatible",
+    baseUrl: null,
+    keyEnv: "DEEPSEEK_API_KEY",
+    contextWindow: 1_000_000,
+    maxOutputTokens: MAX_OUTPUT_TOKENS,
+  };
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (typeof value !== "string") throw new Error(`${flag} needs a value`);
+    if (flag === "--fx") options.fx = value;
+    else if (flag === "--model") options.model = value;
+    else if (flag === "--sandbox") options.sandbox = value;
+    else if (flag === "--provider") {
+      if (!PROVIDER_KINDS.has(value)) throw new Error(`unknown provider: ${value}`);
+      options.provider = value;
+    } else if (flag === "--base-url") options.baseUrl = value;
+    else if (flag === "--key-env") options.keyEnv = value;
+    else if (flag === "--context-window") options.contextWindow = Number(value);
+    else if (flag === "--max-output-tokens") options.maxOutputTokens = Number(value);
+    else throw new Error(`unknown argument: ${flag}`);
+  }
+  if (!options.model) throw new Error("--model is required");
+  return options;
+}
+
+/**
+ * @param {Record<string, any>} toolCall
+ * @returns {string|null}
+ */
+function toolTarget(toolCall) {
+  const input = toolCall.rawInput && typeof toolCall.rawInput === "object" ? toolCall.rawInput : {};
+  const value = input.path ?? input.command ?? input.pattern ?? input.url ?? null;
+  return typeof value === "string" ? value.slice(0, 200) : null;
+}
+
+/** @param {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number}} totals @param {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number}} usage */
+function addUsage(totals, usage) {
+  totals.inputTokens += usage.inputTokens;
+  totals.outputTokens += usage.outputTokens;
+  totals.cacheReadInputTokens += usage.cacheReadInputTokens;
+}
+
+/**
+ * The failure a provider status means. 402 is DeepSeek's "Insufficient
+ * Balance" and 429 its rate limit; both name the exhaustion the declared
+ * failover edge exists for.
+ *
+ * @param {{status: number, error: string|null, retryAfterMs: number|null}} request
+ * @returns {{kind: string, error: {code: string, message: string, retryAfterMs?: number}}}
+ */
+function providerFailure(request) {
+  const code = request.status === 429 ? "RATE_LIMIT" : request.status === 402 ? "QUOTA" : `http_${request.status}`;
+  const message = `${request.status} ${request.error ?? ""}`.trim().slice(0, 512);
+  return { kind: "error", error: { code, message, ...(request.retryAfterMs ? { retryAfterMs: request.retryAfterMs } : {}) } };
+}
+
+const options = parseArgs(process.argv.slice(2));
+const prompt = await readPrompt();
+const workspace = realpathSync(process.cwd());
+const home = mkdtempSync(join(tmpdir(), "faberun-fx-home-"));
+const usage = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 };
+let sawUsage = false;
+/** @type {{status: number, error: string|null, retryAfterMs: number|null}|null} */
+let lastFailure = null;
+/** @type {string[]} */
+const texts = [];
+let segment = "";
+let sessionId = /** @type {string|null} */ (null);
+let settled = false;
+
+const codex = options.provider === "codex";
+const proxy = await startUsageProxy({
+  upstream: options.baseUrl ?? (codex ? CODEX_UPSTREAM : "https://api.deepseek.com"),
+  onRequest(request) {
+    if (request.usage) {
+      addUsage(usage, request.usage);
+      sawUsage = true;
+    }
+    lastFailure = request.status >= 400 ? request : null;
+    emit({ type: "fx.request", status: request.status, usage: request.usage });
+  },
+});
+
+prepareFxHome(homedir(), home, codex ? {
+  provider: CODEX_PROVIDER,
+  models: { [CODEX_PROVIDER]: options.model },
+  permission_mode: "ask",
+} : {
+  provider: PROVIDER,
+  models: { [PROVIDER]: options.model },
+  permission_mode: "ask",
+  providers: {
+    [PROVIDER]: {
+      protocol: "openai-chat-completions",
+      base_url: proxy.url,
+      auth: { type: "bearer", env: options.keyEnv },
+      model_metadata: {
+        [options.model]: { context_window: options.contextWindow, max_output_tokens: options.maxOutputTokens, supports_tool_use: true },
+      },
+    },
+  },
+});
+
+// FX_SOUND: fx plays a sound on every send and response, which a detached
+// campaign of parallel workers turns into noise on the operator's machine.
+const env = {
+  ...process.env,
+  HOME: home,
+  FX_PROVIDER: codex ? CODEX_PROVIDER : PROVIDER,
+  FX_PERMISSION_MODE: "ask",
+  FX_AUTO_UPGRADE: "0",
+  FX_SOUND: "0",
+  // The ChatGPT session stays in the operator's profile: a copy would diverge
+  // on the first token refresh (fx-faberun only). fx accepts a loopback
+  // override of the Responses endpoint, which is how the relay meters it.
+  ...(codex ? { FX_AUTH_HOME: homedir(), FX_E2E_OPENAI_CODEX_RESPONSES_URL: `${proxy.url}/responses` } : {}),
+};
+const invocation = spawnInvocation(options.fx, ["acp"]);
+const child = spawn(invocation.command, invocation.args, { cwd: workspace, env, stdio: ["pipe", "pipe", "pipe"], ...invocation.options });
+
+function flushSegment() {
+  if (!segment.trim()) return;
+  texts.push(segment);
+  emit({ type: "fx.message", text: segment });
+  segment = "";
+}
+
+/** @param {Record<string, unknown>} event @param {number} exitCode */
+async function settle(event, exitCode) {
+  if (settled) return;
+  settled = true;
+  emit({ ...event, usage: sawUsage ? usage : null });
+  child.kill("SIGTERM");
+  await proxy.close();
+  rmSync(home, { recursive: true, force: true });
+  process.exit(exitCode);
+}
+
+/** @param {string} kind @param {{code: string, message: string, retryAfterMs?: number}} error */
+function fail(kind, error) {
+  flushSegment();
+  // A provider status beats fx's prose about it: it is the fact failover keys on.
+  const failure = lastFailure ? providerFailure(lastFailure) : { kind, error };
+  return settle({ type: "fx.failed", sessionId, ...failure }, 1);
+}
+
+let nextId = 0;
+/** @type {Map<number, (message: Record<string, any>) => void>} */
+const pending = new Map();
+/** @param {string} method @param {Record<string, unknown>} params @returns {Promise<Record<string, any>>} */
+function request(method, params) {
+  const id = ++nextId;
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+  return new Promise((resolveReply) => pending.set(id, resolveReply));
+}
+/** @param {number|string} id @param {Record<string, unknown>} body */
+function reply(id, body) {
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, ...body })}\n`);
+}
+
+/** @param {Record<string, any>} message */
+function onServerRequest(message) {
+  if (message.method !== "session/request_permission") {
+    reply(message.id, { error: { code: -32601, message: `faberun does not serve ${message.method}` } });
+    return;
+  }
+  const toolCall = message.params?.toolCall ?? {};
+  const verdict = permissionVerdict(options.sandbox, workspace, toolCall);
+  const wanted = verdict.allow ? "allow_once" : "reject_once";
+  const option = (message.params?.options ?? []).find((/** @type {{kind: string}} */ candidate) => candidate.kind === wanted);
+  if (!verdict.allow) process.stderr.write(`faberun denied ${toolCall.title ?? "a tool call"}: ${verdict.reason}\n`);
+  reply(message.id, { result: { outcome: option ? { outcome: "selected", optionId: option.optionId } : { outcome: "cancelled" } } });
+}
+
+/** @param {Record<string, any>} update */
+function onUpdate(update) {
+  if (update.sessionUpdate === "agent_message_chunk" && typeof update.content?.text === "string") {
+    segment += update.content.text;
+  } else if (update.sessionUpdate === "tool_call") {
+    // A tool call ends the message before it, the boundary a judge's
+    // verdicts are counted on.
+    flushSegment();
+    emit({ type: "fx.tool", name: typeof update.kind === "string" ? update.kind : "tool", target: toolTarget(update) });
+  }
+}
+
+let buffered = "";
+let stderrTail = "";
+child.stdout.setEncoding("utf8");
+child.stdout.on("data", (chunk) => {
+  buffered += chunk;
+  const lines = buffered.split("\n");
+  buffered = lines.pop() ?? "";
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      // stdout carries the JSON-RPC transport only; a non-JSON line is a
+      // harness defect, not provider prose, and must not be silently dropped.
+      fail("invalid_protocol", { code: "invalid_protocol", message: `fx wrote a non-JSON line: ${line.slice(0, 200)}` });
+      return;
+    }
+    if (message.method && message.id !== undefined) onServerRequest(message);
+    else if (message.method === "session/update") onUpdate(message.params?.update ?? {});
+    else if (message.id !== undefined && pending.has(message.id)) {
+      const resolveReply = pending.get(message.id);
+      pending.delete(message.id);
+      resolveReply?.(message);
+    }
+  }
+});
+child.stderr.setEncoding("utf8");
+child.stderr.on("data", (chunk) => {
+  stderrTail = `${stderrTail}${chunk}`.slice(-4096);
+  process.stderr.write(chunk);
+});
+child.on("error", (error) => {
+  fail("harness_exit", { code: "harness_exit", message: `cannot start ${options.fx}: ${error.message}` });
+});
+child.on("close", (code) => {
+  const detail = stderrTail.trim() ? `: ${stderrTail.trim().slice(-512)}` : "";
+  fail("harness_exit", { code: "harness_exit", message: `fx exited with code ${code ?? 1} before the turn ended${detail}` });
+});
+for (const signal of ["SIGTERM", "SIGINT"]) {
+  process.on(signal, () => {
+    child.kill(/** @type {NodeJS.Signals} */ (signal));
+    rmSync(home, { recursive: true, force: true });
+    process.exit(1);
+  });
+}
+process.on("exit", () => {
+  if (!settled) child.kill("SIGKILL");
+});
+
+const initialized = await request("initialize", {
+  protocolVersion: 1,
+  clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+});
+if (initialized.error) {
+  await fail("initialize_failed", { code: "initialize_failed", message: JSON.stringify(initialized.error).slice(0, 512) });
+}
+const session = await request("session/new", { cwd: workspace, mcpServers: [] });
+if (session.error || typeof session.result?.sessionId !== "string") {
+  await fail("session_failed", { code: "session_failed", message: JSON.stringify(session.error ?? session.result).slice(0, 512) });
+}
+sessionId = session.result.sessionId;
+emit({ type: "fx.started", sessionId });
+const turn = await request("session/prompt", { sessionId, prompt: [{ type: "text", text: prompt }] });
+flushSegment();
+if (turn.error) {
+  await fail("prompt_failed", { code: "prompt_failed", message: JSON.stringify(turn.error).slice(0, 512) });
+}
+const stopReason = turn.result?.stopReason;
+if (stopReason === "end_turn") {
+  if (!sawUsage) {
+    // No request reached the relay with usage; fx's own totals are the
+    // fallback, without the cache split it cannot report.
+    const reported = turn.result?.usage;
+    if (reported && typeof reported === "object") {
+      usage.inputTokens = Number(reported.inputTokens) || 0;
+      usage.outputTokens = Number(reported.outputTokens) || 0;
+      sawUsage = true;
+    }
+  }
+  await settle({ type: "fx.completed", sessionId, result: texts.at(-1) ?? "" }, 0);
+}
+await fail(stopReason === "cancelled" ? "aborted" : String(stopReason ?? "unknown"), {
+  code: String(stopReason ?? "unknown"),
+  message: `the turn ended: ${stopReason}`,
+});

package/src/harnesses/fx/usage-proxy.mjs

@@ -0,0 +1,176 @@
+/**
+ * A loopback relay between one fx worker and its OpenAI-compatible provider.
+ * fx 0.0.11 keeps only prompt and completion totals from a Chat Completions
+ * response, so the cache counters the provider returns never reach its JSON
+ * or its ACP usage. The relay forwards every byte unchanged and reads the
+ * `usage` object on the way back: measured 2026-09-24 over 24 fx requests to
+ * api.deepseek.com, 268,288 of 283,372 input tokens (94.7%) were cache hits
+ * that fx reported as ordinary input. It also sees the HTTP status fx turns
+ * into prose, which is the only reliable quota and rate-limit signal.
+ *
+ * One relay per runner, bound to 127.0.0.1 on an ephemeral port, so parallel
+ * workers never share a meter.
+ */
+
+import { createServer } from "node:http";
+
+/** Bytes of an error body kept for classification; the rest is the provider's prose. */
+const ERROR_BODY_LIMIT = 2048;
+
+/**
+ * @typedef {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number}} RequestUsage
+ * @typedef {{status: number, usage: RequestUsage|null, error: string|null, retryAfterMs: number|null}} RelayedRequest
+ */
+
+/**
+ * @param {{upstream: string, onRequest: (request: RelayedRequest) => void}} options
+ * @returns {Promise<{url: string, close: () => Promise<void>}>}
+ */
+export async function startUsageProxy({ upstream, onRequest }) {
+  const base = upstream.replace(/\/+$/u, "");
+  const server = createServer((req, res) => {
+    relay(base, req, res).then(onRequest, (error) => {
+      if (!res.headersSent) res.writeHead(502, { "content-type": "text/plain" });
+      res.end("faberun usage proxy: upstream unreachable");
+      onRequest({ status: 502, usage: null, error: error instanceof Error ? error.message : String(error), retryAfterMs: null });
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve(undefined));
+  });
+  const address = /** @type {import("node:net").AddressInfo} */ (server.address());
+  return {
+    url: `http://127.0.0.1:${address.port}`,
+    close: () => new Promise((resolve) => {
+      server.closeAllConnections();
+      server.close(() => resolve(undefined));
+    }),
+  };
+}
+
+/**
+ * @param {string} base
+ * @param {import("node:http").IncomingMessage} req
+ * @param {import("node:http").ServerResponse} res
+ * @returns {Promise<RelayedRequest>}
+ */
+async function relay(base, req, res) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (value === undefined || ["host", "connection", "content-length", "accept-encoding"].includes(name)) continue;
+    headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+  }
+  const response = await fetch(`${base}${req.url ?? ""}`, {
+    method: req.method,
+    headers,
+    body: chunks.length ? Buffer.concat(chunks) : undefined,
+    redirect: "manual",
+  });
+  /** @type {Record<string, string>} */
+  const outgoing = {};
+  for (const name of ["content-type", "retry-after", "x-request-id"]) {
+    const value = response.headers.get(name);
+    if (value) outgoing[name] = value;
+  }
+  res.writeHead(response.status, outgoing);
+  const decoder = new TextDecoder();
+  let text = "";
+  let pending = "";
+  /** @type {unknown} */
+  let usage = null;
+  const contentType = response.headers.get("content-type");
+  // Measured 2026-09-26: the Codex endpoint streams SSE with no content-type
+  // at all, so a missing header is decided by the first bytes.
+  let streaming = (contentType ?? "").includes("text/event-stream");
+  let sniffed = contentType !== null;
+  if (response.body) {
+    for await (const chunk of response.body) {
+      res.write(chunk);
+      const decoded = decoder.decode(chunk, { stream: true });
+      if (!sniffed) {
+        sniffed = true;
+        streaming = /^\s*(data:|event:|:)/u.test(decoded);
+      }
+      if (!streaming) {
+        text += decoded;
+        continue;
+      }
+      pending += decoded;
+      const lines = pending.split("\n");
+      pending = lines.pop() ?? "";
+      for (const line of lines) usage = streamedUsage(line) ?? usage;
+    }
+  }
+  usage = streamedUsage(pending) ?? usage;
+  res.end();
+  if (!streaming && response.ok) usage = parsedUsage(text);
+  return {
+    status: response.status,
+    usage: canonicalRequestUsage(usage),
+    error: response.ok ? null : text.slice(0, ERROR_BODY_LIMIT) || response.statusText,
+    retryAfterMs: retryAfter(response.headers.get("retry-after")),
+  };
+}
+
+/** @param {string} line @returns {unknown} */
+function streamedUsage(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("data:")) return null;
+  const payload = trimmed.slice(5).trim();
+  if (payload === "[DONE]") return null;
+  return parsedUsage(payload);
+}
+
+/** @param {string} text @returns {unknown} */
+function parsedUsage(text) {
+  try {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== "object") return null;
+    // A Responses stream reports usage once, on `response.completed`, inside
+    // the response object.
+    return value.usage ?? value.response?.usage ?? null;
+  } catch {
+    // A partial or non-JSON frame carries no usage; the next frame might.
+    return null;
+  }
+}
+
+/**
+ * Reduce the provider's usage object to the ledger's shape, where
+ * `inputTokens` excludes the cached prefix. DeepSeek reports the split
+ * directly (`prompt_cache_hit_tokens`, `prompt_cache_miss_tokens`); OpenAI,
+ * vLLM and Z.ai report `prompt_tokens_details.cached_tokens` inside
+ * `prompt_tokens`; the Responses API (fx's Codex provider) reports
+ * `input_tokens_details.cached_tokens` inside `input_tokens`.
+ *
+ * @param {unknown} usage
+ * @returns {RequestUsage|null}
+ */
+export function canonicalRequestUsage(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const record = /** @type {Record<string, any>} */ (usage);
+  const number = (/** @type {unknown} */ value) => (typeof value === "number" && Number.isFinite(value) ? value : null);
+  const input = number(record.input_tokens);
+  if (input !== null) {
+    const cached = number(record.input_tokens_details?.cached_tokens) ?? 0;
+    return { inputTokens: Math.max(0, input - cached), outputTokens: number(record.output_tokens) ?? 0, cacheReadInputTokens: cached };
+  }
+  const prompt = number(record.prompt_tokens);
+  const output = number(record.completion_tokens) ?? 0;
+  const hit = number(record.prompt_cache_hit_tokens) ?? number(record.prompt_tokens_details?.cached_tokens) ?? 0;
+  const miss = number(record.prompt_cache_miss_tokens);
+  if (prompt === null && miss === null) return null;
+  return { inputTokens: miss ?? Math.max(0, (prompt ?? 0) - hit), outputTokens: output, cacheReadInputTokens: hit };
+}
+
+/** @param {string|null} header @returns {number|null} */
+function retryAfter(header) {
+  if (!header) return null;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds > 0) return seconds * 1000;
+  const at = Date.parse(header);
+  return Number.isFinite(at) && at > Date.now() ? at - Date.now() : null;
+}

package/src/harnesses/index.mjs

@@ -3,10 +3,11 @@ import { claudeHarness } from "./claude/index.mjs";
 import { codexHarness } from "./codex/index.mjs";
 import { agyHarness } from "./agy/index.mjs";
 import { dshHarness } from "./dsh/index.mjs";
+import { fxHarness } from "./fx/index.mjs";
 import { zcodeHarness } from "./zcode/index.mjs";
 import { execJsonlHarness } from "./exec-jsonl/index.mjs";
 import { replayHarness } from "./replay/index.mjs";
-import { withoutNotifyEnv } from "../notify/index.mjs";
+import { passthroughEnvironment, workerEnvironment } from "../engine/worker-env.mjs";
 import { spawnInvocation } from "../host/platform.mjs";
 
 /** Current wire-contract version for runner protocol artifacts. */
@@ -20,6 +21,7 @@ const HARNESSES = new Map([
   ["codex", codexHarness],
   ["agy", agyHarness],
   ["dsh", dshHarness],
+  ["fx", fxHarness],
   ["zcode", zcodeHarness],
   ["exec-jsonl", execJsonlHarness],
   ["replay", replayHarness],
@@ -65,12 +67,12 @@ const CAPABILITY_NAMES = new Set([
 
 /**
  * One declared runtime. `harness` names a registered adapter (`claude`,
- * `codex`, `agy`, `dsh`, `zcode`, `exec-jsonl`, or `replay`) and `model` names
+ * `codex`, `agy`, `dsh`, `fx`, `zcode`, `exec-jsonl`, or `replay`) and `model` names
  * what that harness asks; the two are independent. replay requires
  * `config["replay.recording"]` for commands, and dsh requires
  * `config.provider` for the provider route every attempt runs on.
  *
- * @typedef {{id?: string, harness: string, model: string, reasoning?: string, sandbox?: string, permissionMode?: string, config?: Record<string, unknown>, printTimeout?: string, tools?: string[], executable?: string, args?: string[], versionArgs?: string[], maxArgvPromptBytes?: number, requiredCapabilities?: CapabilityRequirements, tier?: number|string, vendor?: string}} HarnessRuntime
+ * @typedef {{id?: string, harness: string, model: string, reasoning?: string, sandbox?: string, permissionMode?: string, config?: Record<string, unknown>, printTimeout?: string, tools?: string[], executable?: string, args?: string[], versionArgs?: string[], maxArgvPromptBytes?: number, requiredCapabilities?: CapabilityRequirements, envPassthrough?: string[], tier?: number|string, vendor?: string}} HarnessRuntime
  */
 
 /**
@@ -106,7 +108,7 @@ export const READ_BYTE_LIMIT = 32 * 1024;
  * One provider adapter: capabilities plus executable, version, command, and
  * result-normalization behavior.
  *
- * @typedef {{capabilities: HarnessCapabilities, permissionExecution: PermissionExecutionPolicy, executable: (runtime: HarnessRuntime) => string, versionArgs: (runtime: HarnessRuntime) => string[], parseVersion: (stdout: string, stderr?: string) => string|null, command: (runtime: HarnessRuntime, prompt: string, options: CommandOptions) => HarnessCommand, normalize: (stdout: string, exitCode: number|null, signal: string|null, options?: NormalizeOptions) => ProviderEnvelope}} HarnessAdapter
+ * @typedef {{capabilities: HarnessCapabilities, permissionExecution: PermissionExecutionPolicy, executable: (runtime: HarnessRuntime) => string, versionArgs: (runtime: HarnessRuntime) => string[], parseVersion: (stdout: string, stderr?: string) => string|null, command: (runtime: HarnessRuntime, prompt: string, options: CommandOptions) => HarnessCommand, normalize: (stdout: string, exitCode: number|null, signal: string|null, options?: NormalizeOptions) => ProviderEnvelope, reportsCost?: (runtime: {harness: string, config?: Record<string, unknown>}) => boolean}} HarnessAdapter
  */
 
 /**
@@ -214,10 +216,14 @@ export function resolveVendor(runtime) {
 
 /**
  * Build one provider invocation. Prompt transport is explicit in the result:
- * stdin adapters return `input`, while argv adapters append the prompt. An
- * optional `env` overlay is merged over the runner environment at spawn time;
- * a null value removes the ambient variable. A caller-supplied `options.env`
- * merges over the adapter's own overlay here, once, for every harness.
+ * stdin adapters return `input`, while argv adapters append the prompt.
+ *
+ * The returned `env` is the runtime-specific allowlist overlay (adapter
+ * declarations, `*.env_key` names, and the runtime's `envPassthrough`) merged
+ * over the adapter's own overlay; a null value removes the ambient variable.
+ * The spawn gate unions it with the base operating-system names, so no other
+ * controller variable reaches the child. A caller-supplied `options.env`
+ * merges over everything here, once, for every harness.
  *
  * @param {HarnessRuntime} runtime
  * @param {string} prompt
@@ -227,6 +233,12 @@ export function resolveVendor(runtime) {
 export function providerCommand(runtime, prompt, options = {}) {
   const harness = getHarness(runtime.harness);
   const command = harness.command(runtime, prompt, options);
+  // The runtime-specific allowlist travels to the gate as an overlay. The gate
+  // unions it with the base operating-system names and nothing else, so a
+  // controller variable no adapter, `*.env_key`, or envPassthrough named never
+  // reaches the child. It is deliberately not the whole environment: the
+  // caller's overlay stays an overlay, and the base set stays the gate's job.
+  command.env = { ...passthroughEnvironment(runtime, undefined, process.env), ...command.env };
   if (options.env) command.env = { ...command.env, ...options.env };
   if (command.promptTransport === "argv") {
     const limit = runtime.maxArgvPromptBytes ?? harness.capabilities.maxArgvPromptBytes;
@@ -245,7 +257,7 @@ export function providerCommand(runtime, prompt, options = {}) {
 }
 
 /**
- * @param {string|{harness: string}} runtimeOrHarness
+ * @param {string|{harness: string, model?: string, config?: Record<string, unknown>}} runtimeOrHarness
  * @param {string} stdout
  * @param {number|null} exitCode
  * @param {string|null} signal
@@ -255,7 +267,9 @@ export function providerCommand(runtime, prompt, options = {}) {
 export function normalizeProviderResult(runtimeOrHarness, stdout, exitCode, signal, options = {}) {
   const runtime = typeof runtimeOrHarness === "string" ? { harness: runtimeOrHarness } : runtimeOrHarness;
   const harness = getHarness(runtime.harness);
-  return harness.normalize(stdout, exitCode, signal, options);
+  const envelope = harness.normalize(stdout, exitCode, signal, options);
+  // A cost the harness reports in another vendor's rates is not a bill.
+  return harness.reportsCost?.(runtime) === false ? { ...envelope, costUsd: null } : envelope;
 }
 
 /**
@@ -503,10 +517,11 @@ export function probeRuntime(runtime, options = {}) {
       const invocation = spawnInvocation(executable, args, { cwd: options.cwd });
       child = spawn(invocation.command, invocation.args, {
         cwd: options.cwd,
-        // A worker or judge never delivers a notification; the controller does.
-        // In this repository a worker runs the test suite, whose fixture
-        // controllers would otherwise inherit a live transport and deliver.
-        env: withoutNotifyEnv(process.env),
+        // A probe is a worker-class spawn: it receives only the base names,
+        // the adapter's declared names, the runtime's `*.env_key` names, and
+        // any envPassthrough the runtime carries. It never delivers a
+        // notification; the controller does.
+        env: workerEnvironment(runtime),
         stdio: ["ignore", "pipe", "pipe"],
         ...invocation.options,
       });

package/src/harnesses/replay/index.mjs

@@ -2,6 +2,18 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseVersion } from "../protocol.mjs";
 
+/**
+ * The environment names the replay adapter reads to authenticate and configure
+ * the recording: only the binary override `executable()` honours. A recording
+ * carries no credential of its own, and `replay/bin.mjs` reads no environment
+ * name at all. Values never travel here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "FABERUN_REPLAY_BIN",
+]);
+
 /** Envelope statuses a recording may carry. */
 const REPLAY_STATUSES = Object.freeze(new Set([
   "done",