faberun 0.27.0 → 0.29.0

package/src/engine/worker-env.mjs

@@ -0,0 +1,179 @@
+/**
+ * The environment a worker, a judge, or an availability probe may receive.
+ *
+ * A controller variable reaches a child only when something named it. The
+ * names a child may see are the union of:
+ *
+ *   - the base operating-system names below,
+ *   - the names the selected adapter declares in its `declaredEnvironment`,
+ *   - the runtime's `*.env_key` names, and
+ *   - the explicit `envPassthrough` names on the runtime or the contract.
+ *
+ * Everything else the controller holds -- an `AWS_*`, a `GITHUB_TOKEN`, a
+ * `DATABASE_URL` exported in a shell profile -- is dropped. Verification
+ * commands are not workers and keep the full controller environment
+ * (`judge-gate.mjs`); only worker, judge, and availability-probe spawns route
+ * through here.
+ *
+ * The adapter lists are imported from each adapter directly instead of through
+ * `harnesses/catalogue.mjs`: the registry imports this module for its probe, so
+ * reaching the catalogue from here would close a runtime import cycle the repo
+ * forbids. The catalogue keeps its own copy of the same names for R2, and both
+ * read the same adapter exports.
+ */
+import { declaredEnvironment as claudeEnvironment } from "../harnesses/claude/index.mjs";
+import { declaredEnvironment as codexEnvironment } from "../harnesses/codex/index.mjs";
+import { declaredEnvironment as agyEnvironment } from "../harnesses/agy/index.mjs";
+import { declaredEnvironment as dshEnvironment } from "../harnesses/dsh/index.mjs";
+import { declaredEnvironment as fxEnvironment } from "../harnesses/fx/index.mjs";
+import { declaredEnvironment as zcodeEnvironment } from "../harnesses/zcode/index.mjs";
+import { declaredEnvironment as execJsonlEnvironment } from "../harnesses/exec-jsonl/index.mjs";
+import { declaredEnvironment as replayEnvironment } from "../harnesses/replay/index.mjs";
+import { NOTIFY_ENV_NAMES } from "../notify/index.mjs";
+
+/**
+ * The base operating-system names every child needs to resolve a binary, find
+ * its home, and speak the locale. `LC_*` is a family, matched by prefix; the
+ * Windows entries are listed on every platform because the machine that reads
+ * them is the machine that has them.
+ *
+ * @type {readonly string[]}
+ */
+export const BASE_ENV_NAMES = Object.freeze([
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "LANG",
+  "TERM",
+  "TMPDIR",
+  "TZ",
+  "SYSTEMROOT",
+  "USERPROFILE",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "COMSPEC",
+  "PATHEXT",
+]);
+
+/** @type {ReadonlySet<string>} */
+const BASE_NAME_SET = new Set(BASE_ENV_NAMES);
+
+/**
+ * The adapter-declared names, keyed by harness. Values never travel here.
+ *
+ * A `Map` rather than the catalogue's frozen object on purpose: the repo
+ * forbids the same top-level body defined twice, and the registry owns the
+ * catalogue copy.
+ *
+ * @type {Map<string, readonly string[]>}
+ */
+const ADAPTER_ENVIRONMENTS = new Map([
+  ["claude", claudeEnvironment],
+  ["codex", codexEnvironment],
+  ["agy", agyEnvironment],
+  ["dsh", dshEnvironment],
+  ["fx", fxEnvironment],
+  ["zcode", zcodeEnvironment],
+  ["exec-jsonl", execJsonlEnvironment],
+  ["replay", replayEnvironment],
+]);
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isBaseName(name) {
+  return BASE_NAME_SET.has(name) || name.startsWith("LC_");
+}
+
+/**
+ * The `*.env_key` names a runtime's config declares. A config value there is
+ * the environment-variable name, never the value, so this reads names alone.
+ *
+ * @param {{config?: Record<string, unknown>}|null|undefined} runtime
+ * @returns {string[]}
+ */
+function envKeyNames(runtime) {
+  /** @type {string[]} */
+  const names = [];
+  for (const [key, value] of Object.entries(runtime?.config ?? {})) {
+    if (key.endsWith(".env_key") && typeof value === "string" && value.length > 0) names.push(value);
+  }
+  return names;
+}
+
+/**
+ * The non-base names one runtime may carry: what its adapter declares, what
+ * its `*.env_key` config entries name, and what the runtime or the contract
+ * explicitly passes through. The notification transport is never one of them,
+ * whatever an author writes.
+ *
+ * @param {{harness?: string, config?: Record<string, unknown>, envPassthrough?: string[]}|null|undefined} runtime
+ * @param {{envPassthrough?: string[]}|null|undefined} [contract]
+ * @returns {string[]}
+ */
+export function declaredEnvironmentNames(runtime, contract) {
+  const names = new Set(ADAPTER_ENVIRONMENTS.get(runtime?.harness ?? "") ?? []);
+  for (const name of envKeyNames(runtime)) names.add(name);
+  for (const name of Array.isArray(runtime?.envPassthrough) ? runtime.envPassthrough : []) names.add(name);
+  for (const name of Array.isArray(contract?.envPassthrough) ? contract.envPassthrough : []) names.add(name);
+  for (const name of NOTIFY_ENV_NAMES) names.delete(name);
+  return [...names];
+}
+
+/**
+ * The base names present in `source`, including every `LC_*` member.
+ *
+ * @param {Record<string, string|undefined>} [source]
+ * @returns {Record<string, string>}
+ */
+export function baseEnvironment(source = process.env) {
+  /** @type {Record<string, string>} */
+  const env = {};
+  // Look the base names up rather than filtering source keys: Windows exposes
+  // `Path`, not `PATH`, and `source[name]` is the case-insensitive read there.
+  for (const name of BASE_ENV_NAMES) {
+    const value = source[name];
+    if (value !== undefined) env[name] = value;
+  }
+  for (const [name, value] of Object.entries(source)) {
+    if (value !== undefined && name.startsWith("LC_")) env[name] = value;
+  }
+  return env;
+}
+
+/**
+ * The non-base allowlisted names present in `source`, with their controller
+ * values. This is the overlay a caller hands the gate: the gate already holds
+ * the base set in its own environment, so it only needs what the runtime adds
+ * on top.
+ *
+ * @param {{harness?: string, config?: Record<string, unknown>, envPassthrough?: string[]}|null|undefined} runtime
+ * @param {{envPassthrough?: string[]}|null|undefined} [contract]
+ * @param {Record<string, string|undefined>} [source]
+ * @returns {Record<string, string>}
+ */
+export function passthroughEnvironment(runtime, contract, source = process.env) {
+  /** @type {Record<string, string>} */
+  const env = {};
+  for (const name of declaredEnvironmentNames(runtime, contract)) {
+    if (isBaseName(name)) continue;
+    const value = source[name];
+    if (value !== undefined) env[name] = value;
+  }
+  return env;
+}
+
+/**
+ * The complete environment a worker, judge, or availability probe receives.
+ *
+ * @param {{harness?: string, config?: Record<string, unknown>, envPassthrough?: string[]}|null|undefined} runtime
+ * @param {{envPassthrough?: string[]}|null|undefined} [contract]
+ * @param {Record<string, string|undefined>} [source]
+ * @returns {Record<string, string>}
+ */
+export function workerEnvironment(runtime, contract, source = process.env) {
+  return { ...baseEnvironment(source), ...passthroughEnvironment(runtime, contract, source) };
+}

package/src/harnesses/agy/index.mjs

@@ -1,5 +1,16 @@
 import { normalizeAgyResult, parseVersion } from "../protocol.mjs";
 
+/**
+ * The environment names the agy adapter reads to authenticate and configure the
+ * CLI. agy signs in through its own CLI configuration, so the only name read
+ * here is the binary override `executable()` honours. Values never travel here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "FABERUN_AGY_BIN",
+]);
+
 /**
  * @type {import("../index.mjs").HarnessAdapter}
  */

package/src/harnesses/catalogue.mjs

@@ -5,6 +5,14 @@ import { canonicalProvider } from "../contract/provider.mjs";
 import { errorMessage } from "../util.mjs";
 import { ANTHROPIC_MODEL_TIERS } from "./model-tiers.mjs";
 import { spawnInvocation } from "../host/platform.mjs";
+import { declaredEnvironment as claudeEnvironment } from "./claude/index.mjs";
+import { declaredEnvironment as codexEnvironment } from "./codex/index.mjs";
+import { declaredEnvironment as agyEnvironment } from "./agy/index.mjs";
+import { declaredEnvironment as dshEnvironment } from "./dsh/index.mjs";
+import { declaredEnvironment as fxEnvironment } from "./fx/index.mjs";
+import { declaredEnvironment as zcodeEnvironment } from "./zcode/index.mjs";
+import { declaredEnvironment as execJsonlEnvironment } from "./exec-jsonl/index.mjs";
+import { declaredEnvironment as replayEnvironment } from "./replay/index.mjs";
 
 /**
  * Model catalogue report: which models each registered harness can run, the
@@ -38,6 +46,27 @@ export const MODEL_HARNESS_ORDER = Object.freeze([
   "replay",
 ]);
 
+/**
+ * The environment names each registered adapter reads to authenticate and
+ * configure itself, keyed by harness in `MODEL_HARNESS_ORDER`. Each list is the
+ * adapter's own frozen `declaredEnvironment` export, and only bare names ever
+ * travel here, never values. The worker/judge environment builder unions these
+ * names with the base operating-system set and the runtime's env keys, so a
+ * name missing from this catalogue is a name the child process never receives.
+ *
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const DECLARED_HARNESS_ENVIRONMENTS = Object.freeze({
+  claude: claudeEnvironment,
+  codex: codexEnvironment,
+  agy: agyEnvironment,
+  dsh: dshEnvironment,
+  fx: fxEnvironment,
+  zcode: zcodeEnvironment,
+  "exec-jsonl": execJsonlEnvironment,
+  replay: replayEnvironment,
+});
+
 const CLAUDE_EFFORTS = Object.freeze(["low", "medium", "high", "max"]);
 const CODEX_EFFORTS = Object.freeze(["low", "medium", "high", "xhigh"]);
 const AGY_EFFORTS = Object.freeze(["low", "medium", "high"]);

package/src/harnesses/claude/index.mjs

@@ -1,6 +1,18 @@
 import { normalizeClaudeResult, parseVersion } from "../protocol.mjs";
 import { hookSettings } from "../../host/tool-policy-hook.mjs";
 
+/**
+ * The environment names the Claude adapter reads to authenticate and configure
+ * the CLI: the provider credential the CLI resolves for API-key sign-in and the
+ * binary override `executable()` honours. Values never travel here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "ANTHROPIC_API_KEY",
+  "FABERUN_CLAUDE_BIN",
+]);
+
 /** Built-in tools a closed-packet worker needs; every other tool is preamble. */
 export const DEFAULT_CLAUDE_TOOLS = ["Read", "Edit", "Write", "Bash", "Glob", "Grep"];
 
@@ -26,6 +38,88 @@ function claudePreambleArgs(runtime) {
   ];
 }
 
+/**
+ * The envelope this adapter returns: the shared provider envelope plus the
+ * top-level reset instant a session limit names. The field has to live here
+ * rather than in `error` so that `exhaustedUntilOf` keeps parsing the sentence
+ * against the caller's clock.
+ *
+ * @typedef {import("../index.mjs").ProviderEnvelope & {resetAt?: string}} ClaudeEnvelope
+ */
+
+/**
+ * The reset sentence a Claude quota stop writes into its error message, e.g.
+ * "You've hit your session limit · resets 6:40pm (America/Sao_Paulo)". The
+ * wall-clock form names a time and a zone but no date; an absolute form names
+ * the instant directly ("Your limit will reset at 2026-09-08 20:30:00").
+ */
+const SESSION_RESET_SENTENCE = /resets?(?:\s+at)?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*\(([A-Za-z_]+(?:\/[A-Za-z0-9_+-]+)+|UTC|GMT)\)/iu;
+const ABSOLUTE_RESET_SENTENCE = /reset(?:s| at| on)?\s+(\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:Z|[+-]\d{2}:?\d{2})?)/iu;
+
+/**
+ * The instant a Claude quota stop names, or null when its message names none.
+ *
+ * The generic availability classifier (`harnesses/index.mjs`'s
+ * `exhaustedUntilOf`) parses the same sentence for the durable refusal store,
+ * but the node's own wait decision (`engine/backoff.mjs`'s
+ * `quotaResetSchedule`) reads only a structured `resetAt`. This adapter is the
+ * protocol boundary and cannot import `harnesses/index.mjs` -- that module
+ * imports this one at load -- so the sentence is parsed here. A zone the
+ * runtime does not know names no instant, and the failover edge is taken as
+ * before.
+ *
+ * @param {string} message
+ * @param {number} [now] the instant a wall-clock sentence is read against
+ * @returns {string|null}
+ */
+function sessionResetAt(message, now = Date.now()) {
+  const absolute = ABSOLUTE_RESET_SENTENCE.exec(message);
+  if (absolute) {
+    const value = absolute[1];
+    const zoned = value.includes("T") || /(?:Z|[+-]\d{2}:?\d{2})$/u.test(value) ? value : `${value.replace(" ", "T")}Z`;
+    const parsed = Date.parse(zoned);
+    if (Number.isFinite(parsed)) return new Date(parsed).toISOString();
+  }
+  const match = SESSION_RESET_SENTENCE.exec(message);
+  if (!match) return null;
+  let hour = Number(match[1]);
+  const minute = Number(match[2] ?? "0");
+  const meridiem = match[3]?.toLowerCase();
+  if (meridiem === "pm" && hour < 12) hour += 12;
+  if (meridiem === "am" && hour === 12) hour = 0;
+  if (hour > 23 || minute > 59) return null;
+  /** @type {Intl.DateTimeFormatPart[]} */
+  let parts;
+  try {
+    parts = new Intl.DateTimeFormat("en-US", { timeZone: match[4], hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" }).formatToParts(new Date(now));
+  } catch {
+    // An unknown zone name is not a reset time; the caller falls back to failover.
+    return null;
+  }
+  const at = (/** @type {Intl.DateTimeFormatPartTypes} */ type) => Number(parts.find((part) => part.type === type)?.value);
+  const offset = Date.UTC(at("year"), at("month") - 1, at("day"), at("hour") % 24, at("minute"), at("second")) - Math.floor(now / 1000) * 1000;
+  let target = Date.UTC(at("year"), at("month") - 1, at("day"), hour, minute) - offset;
+  if (target <= now) target += 86_400_000;
+  return new Date(target).toISOString();
+}
+
+/**
+ * Thread a session-limit reset into the envelope so the node can wait for it.
+ * The instant rides the envelope's top-level `resetAt`, the field the node's
+ * wait decision (`engine/backoff.mjs`'s `quotaResetSchedule`) reads. It is not
+ * written into `error.resetAt`/`exhaustedUntil` on purpose: `exhaustedUntilOf`
+ * must keep parsing the sentence against the clock its caller passes, so a test
+ * or a replayed envelope can re-read the same message at a chosen instant.
+ *
+ * @param {ClaudeEnvelope} envelope
+ * @returns {ClaudeEnvelope}
+ */
+function withSessionReset(envelope) {
+  if (envelope.status !== "exhausted" || envelope.resetAt) return envelope;
+  const resetAt = sessionResetAt(String(envelope.error?.message ?? ""));
+  return resetAt ? { ...envelope, resetAt } : envelope;
+}
+
 /**
  * The environment one runtime's CLI runs under when its contract points it at
  * an Anthropic-compatible endpoint other than Anthropic's own, e.g. GLM on
@@ -174,7 +268,10 @@ export const claudeHarness = {
     return declaredBaseUrl(runtime) === null;
   },
 
-  normalize: normalizeClaudeResult,
+  /** @param {string} stdout @param {number|null} exitCode @param {string|null} signal @param {import("../index.mjs").NormalizeOptions} [options] @returns {import("../index.mjs").ProviderEnvelope} */
+  normalize(stdout, exitCode, signal, options = {}) {
+    return withSessionReset(normalizeClaudeResult(stdout, exitCode, signal, options));
+  },
 };
 
 export const harness = claudeHarness;

package/src/harnesses/codex/index.mjs

@@ -1,5 +1,20 @@
 import { normalizeCodexResult, parseVersion, toml } from "../protocol.mjs";
 
+/**
+ * The environment names the Codex adapter reads to authenticate and configure
+ * the CLI: the provider credential for API-key sign-in, the config home
+ * `codexHome()` reads when it locates the session file its usage windows come
+ * from, and the binary override `executable()` honours. Values never travel
+ * here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "CODEX_HOME",
+  "FABERUN_CODEX_BIN",
+  "OPENAI_API_KEY",
+]);
+
 /**
  * Bound the Codex harness preamble: a closed-packet worker or a read-only judge
  * needs the shell and patch tools, not browser, computer-use, app or sub-agent

package/src/harnesses/dsh/index.mjs

@@ -3,6 +3,20 @@ import { fileURLToPath } from "node:url";
 import { parseVersion } from "../protocol.mjs";
 import { normalizeRunnerTranscript, runnerEnvironmentOverlay, withSchema } from "../runner-transcript.mjs";
 
+/**
+ * The environment names the dsh adapter reads to authenticate and configure the
+ * harness: the provider credential the dsh CLI resolves for the declared
+ * provider and the binary override `executable()` honours. The environment
+ * overlay's `GIT_CONFIG_*` scrub is a generic pass over ambient keys, not a
+ * declared dependency. Values never travel here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "DEEPSEEK_API_KEY",
+  "FABERUN_DSH_BIN",
+]);
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 
 /**

package/src/harnesses/exec-jsonl/index.mjs

@@ -31,6 +31,18 @@ import { finite } from "../../util.mjs";
 
 export { HARNESS_OUTPUT_LIMIT_BYTES } from "../protocol.mjs";
 
+/**
+ * The environment names the exec-jsonl adapter reads to authenticate and
+ * configure the wrapper: only the binary override `executable()` honours.
+ * Credentials belong to the wrapper the contract names, so the adapter reads
+ * none of them. Values never travel here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "FABERUN_EXEC_JSONL_BIN",
+]);
+
 export const EXEC_JSONL_PROTOCOL = Object.freeze({
   schemaVersion: 1,
   requestType: "run.request",

package/src/harnesses/fx/index.mjs

@@ -10,6 +10,19 @@ import { fileURLToPath } from "node:url";
 import { parseVersion } from "../protocol.mjs";
 import { normalizeRunnerTranscript, runnerEnvironmentOverlay, withSchema } from "../runner-transcript.mjs";
 
+/**
+ * The environment names this adapter reads outside the base set and the
+ * runtime's own `*.env_key` names: the provider key the client falls back to
+ * when a runtime names none, and the binary override `executable()` honours.
+ * Values never travel here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "DEEPSEEK_API_KEY",
+  "FABERUN_FX_BIN",
+]);
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 
 /**

package/src/harnesses/index.mjs

@@ -7,7 +7,7 @@ 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. */
@@ -72,7 +72,7 @@ const CAPABILITY_NAMES = new Set([
  * `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
  */
 
 /**
@@ -216,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
@@ -229,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;
@@ -507,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",

package/src/harnesses/zcode/index.mjs

@@ -3,6 +3,25 @@ import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { normalizeZcodeResult, parseVersion } from "../protocol.mjs";
 
+/**
+ * The environment names the zcode adapter reads to authenticate and configure
+ * the CLI: the credential the CLI resolves (`auth_token.env_key`, default
+ * `ZAI_API_KEY`, with `ANTHROPIC_AUTH_TOKEN` as its fallback), the app install
+ * directory `zcodeBundle()` reads, and the binary override `executable()`
+ * honours. The `ZCODE_MODEL`, `ZCODE_BASE_URL`, `ANTHROPIC_API_KEY` and
+ * `ZCODE_LOG_*` names this adapter writes into the child environment are
+ * configuration it supplies, not dependencies it reads. Values never travel
+ * here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "ANTHROPIC_AUTH_TOKEN",
+  "FABERUN_ZCODE_APP_DIR",
+  "FABERUN_ZCODE_BIN",
+  "ZAI_API_KEY",
+]);
+
 /** Default Z.ai Anthropic-compatible endpoint serving GLM models. */
 const ZCODE_DEFAULT_BASE_URL = "https://api.z.ai/api/anthropic";
 

package/src/host/config.mjs

@@ -3,7 +3,9 @@
  * enabled, which runtime is the default worker and judge, the machine's own
  * ordered `judges` list (R18) -- read only when a contract declares none --
  * and its ordered `reviewers` list (R19), `faberun plan`'s own machine
- * default, read only when `--reviewers` names none.
+ * default, read only when `--reviewers` names none. Its `judgeIndependence`
+ * (R36) is the machine-wide same-vendor opt-in, read only when a contract
+ * declares none.
  *
  * It is separate from `host/home.mjs`, which owns the path, because reading a
  * config is a validation problem and writing it is an atomic-write problem;
@@ -13,8 +15,9 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { configPath, faberunHome } from "./home.mjs";
+import { SAME_VENDOR_REVIEW_MODE } from "../contract/judge-independence.mjs";
 
-/** @typedef {{schemaVersion: 1, harnesses: string[], worker?: string, judge?: string, judges?: string[], reviewers?: string[], updatedAt: string}} UserConfig */
+/** @typedef {{schemaVersion: 1, harnesses: string[], worker?: string, judge?: string, judges?: string[], reviewers?: string[], judgeIndependence?: "same-vendor", updatedAt: string}} UserConfig */
 
 /** Paths already reported malformed, so a process that reads twice warns once. */
 const warned = new Set();
@@ -88,5 +91,8 @@ function isUserConfig(value) {
   if (record.judge !== undefined && typeof record.judge !== "string") return false;
   if (record.judges !== undefined && (!Array.isArray(record.judges) || !record.judges.every((id) => typeof id === "string"))) return false;
   if (record.reviewers !== undefined && (!Array.isArray(record.reviewers) || !record.reviewers.every((id) => typeof id === "string"))) return false;
+  // The machine's same-vendor opt-in shares the contract field's single
+  // accepted value; anything else is malformed, not silently ignored.
+  if (record.judgeIndependence !== undefined && record.judgeIndependence !== SAME_VENDOR_REVIEW_MODE) return false;
   return typeof record.updatedAt === "string";
 }