faberun 0.27.0 → 0.28.0

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";
 }

package/src/host/environment-report.mjs

@@ -0,0 +1,85 @@
+/**
+ * The `doctor --env` report: which controller variables each runtime's child
+ * would carry, which it would not, and which excluded names look like
+ * credentials. Only names cross this boundary, never values. Separate from
+ * `preflight.mjs` because it is a listing built from the worker environment
+ * builder, not a readiness check, and it took that module past its 800-line
+ * ceiling (measured 2026-09-27: 840 lines).
+ */
+import { DISCOVERY_RUNTIME_DEFINITIONS } from "../engine/runtime-discovery.mjs";
+import { workerEnvironment } from "../engine/worker-env.mjs";
+
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("./preflight.mjs").ReachableRuntimes} ReachableRuntimes */
+
+/**
+ * The name shapes that mark a controller variable as a credential. An excluded
+ * name matching one of these is reported as retained: the operator reads that
+ * the secret exists on the controller and is kept out of every worker, and
+ * never reads its value.
+ *
+ * `*_KEY`, `*_TOKEN`, `*_SECRET`, `*_PASSWORD`, `AWS_*` and `GITHUB_*` are the
+ * six shapes R3 names; they are a warning about the name, not a claim about the
+ * value, so a `GITHUB_ACTIONS` is retained too.
+ */
+const SECRET_ENV_NAME_PATTERNS = Object.freeze([
+  /_KEY$/u,
+  /_TOKEN$/u,
+  /_SECRET$/u,
+  /_PASSWORD$/u,
+  /^AWS_/u,
+  /^GITHUB_/u,
+]);
+
+/** @param {string} name @returns {boolean} */
+export function isSecretEnvName(name) {
+  return SECRET_ENV_NAME_PATTERNS.some((pattern) => pattern.test(name));
+}
+
+/**
+ * @param {Record<string, string|undefined>} source
+ * @returns {string[]}
+ */
+function presentEnvironmentNames(source) {
+  return Object.keys(source).filter((name) => source[name] !== undefined).sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * One runtime's side of the `doctor --env` report: the controller variable
+ * names it would carry and the names it would not, with every excluded
+ * credential-shaped name also listed under `retained`.
+ *
+ * Values never cross this boundary. The allowlist is computed from the same
+ * `workerEnvironment` the dispatch gate spawns with, and only its keys are
+ * read; the source is consulted for presence, never copied into the result.
+ *
+ * @param {{id?: string, harness?: string, config?: Record<string, unknown>, envPassthrough?: string[]}|null|undefined} runtime
+ * @param {{envPassthrough?: string[]}|null|undefined} [contract]
+ * @param {Record<string, string|undefined>} [source]
+ * @returns {{runtime: string, harness: string, passed: string[], excluded: string[], retained: string[]}}
+ */
+export function runtimeEnvironmentReport(runtime, contract, source = process.env) {
+  const allowed = new Set(Object.keys(workerEnvironment(runtime, contract, source)));
+  const present = presentEnvironmentNames(source);
+  const passed = present.filter((name) => allowed.has(name));
+  const excluded = present.filter((name) => !allowed.has(name));
+  const retained = excluded.filter((name) => isSecretEnvName(name));
+  return { runtime: runtime?.id ?? "", harness: runtime?.harness ?? "", passed, excluded, retained };
+}
+
+/**
+ * The per-runtime listings behind `doctor --env`. A contract narrows the report
+ * to the reachable runtimes the run committed to; without one the report covers
+ * the discovery catalogue, because there is no routed runtime to name.
+ *
+ * @param {ReachableRuntimes} [runtimes]
+ * @param {ValidatedContract} [contract]
+ * @param {Record<string, string|undefined>} [source]
+ * @returns {{runtime: string, harness: string, passed: string[], excluded: string[], retained: string[]}[]}
+ */
+export function environmentListings(runtimes, contract, source = process.env) {
+  const entries = runtimes && runtimes.size
+    ? [...runtimes.entries()].map(([id, { runtime }]) => ({ ...runtime, id }))
+    : Object.entries(DISCOVERY_RUNTIME_DEFINITIONS).map(([id, runtime]) => ({ ...runtime, id }));
+  return entries.map((runtime) => runtimeEnvironmentReport(runtime, contract, source));
+}

package/src/host/home.mjs

@@ -27,6 +27,33 @@ export function faberunHome(env = process.env) {
   return join(homedir(), ".faberun");
 }
 
+/**
+ * The home directory the *injected* environment names, or null when it names
+ * none. Unlike `faberunHome`, this never consults `os.homedir()`.
+ *
+ * The distinction matters for exactly one caller: `faberun uninstall` derives
+ * the roots it may delete from the environment it was handed, and
+ * `src/host/uninstall-roots.mjs` refuses every removal when that environment
+ * names neither root. A fallback to the operator's real home would aim a delete
+ * at it when the caller meant to scope the operation to a throwaway one, which
+ * is the accident the isolation requirement exists to stop. `HOME` is the POSIX
+ * name and `USERPROFILE` the Windows one; `HOMEDRIVE`+`HOMEPATH` is the last
+ * spelling `os.homedir()` itself accepts there.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null}
+ */
+export function effectiveHome(env = process.env) {
+  for (const name of ["HOME", "USERPROFILE"]) {
+    const value = env[name];
+    if (typeof value === "string" && value) return value;
+  }
+  const drive = env.HOMEDRIVE;
+  const path = env.HOMEPATH;
+  if (typeof drive === "string" && drive && typeof path === "string" && path) return `${drive}${path}`;
+  return null;
+}
+
 /** @param {string} home @returns {string} */
 export function versionsDir(home) {
   return join(home, "versions");