faberun 0.26.3 → 0.28.0

package/src/engine/run-command.mjs

@@ -16,10 +16,35 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { processStartToken } from "../run/lock.mjs";
 import { randomUUID } from "node:crypto";
 import { runMutation } from "./mutation.mjs";
+import { SANDBOX_BLOCKED_WRITE } from "../contract/worker-result.mjs";
+import { isAbsolute, resolve } from "node:path";
+import { isContained } from "../util.mjs";
 import { spawn } from "node:child_process";
 import { killTarget, spawnInvocation } from "../host/platform.mjs";
 /** @typedef {import("../contract/verification.mjs").VerificationOptions} VerificationOptions */
 
+/**
+ * The run-level options plus the sandbox mode the caller knows. The mode is not
+ * part of the shared verification contract: it is controller environment, read
+ * here only to name a refusal the command itself cannot.
+ *
+ * @typedef {VerificationOptions & {sandboxMode?: string|null}} RunVerificationOptions
+ */
+
+/**
+ * The named classification of a `workspace-write` refusal outside the worktree,
+ * carrying the mode that caused it and the path that was denied.
+ *
+ * @typedef {{classification: "sandbox_blocked_write", mode: string, path: string}} SandboxBlockedWrite
+ */
+
+/**
+ * A bounded attempt result plus the controller's sandbox classification, which
+ * rides beside the captured output only when a refusal was recognized.
+ *
+ * @typedef {VerificationAttemptResult & {attempt: number, sandboxBlockedWrite?: SandboxBlockedWrite}} SandboxAwareAttemptResult
+ */
+
 /** @typedef {import("node:child_process").ChildProcess} ChildProcess */
 /** @typedef {import("../contract/verification.mjs").VerificationAttempt} VerificationAttempt */
 /** @typedef {import("../contract/verification.mjs").VerificationAttemptResult} VerificationAttemptResult */
@@ -62,12 +87,51 @@ function verificationEnv(command) {
   }
   return env;
 }
+
+// `workspace-write` denies a toolchain's cache in `$HOME` and the tool reports
+// a read-only filesystem: observed 2026-09-22 with Zig under `dsh`,
+// `manifest_create ReadOnlyFileSystem` before its first source file. The
+// sandbox, not the command, is the cause, so the controller names it. `EROFS`
+// and the POSIX message cover the same refusal from other runners.
+const SANDBOX_READ_ONLY_PATTERN = /ReadOnlyFileSystem|EROFS|read-only file system/iu;
+// A denied path is usually quoted (`unable to load '/path': ReadOnlyFileSystem`)
+// or bare after the operation name; either way it is absolute, since only an
+// effect outside the worktree gets refused.
+const ABSOLUTE_PATH_PATTERNS = Object.freeze([/['"]((?:[A-Za-z]:[\\/]|\/)[^'"]+)['"]/gu, /((?:[A-Za-z]:[\\/]|\/)[^\s'",;:)\]]+)/gu]);
+
+/**
+ * Classify a failed command whose output names a read-only-filesystem refusal
+ * outside the worktree, under `workspace-write`. Returns null for any other
+ * mode, a refusal inside the worktree, or output with no path to name.
+ *
+ * @param {{text?: string, workspace: string, mode?: string|null}} args
+ * @returns {SandboxBlockedWrite|null}
+ */
+export function classifySandboxBlockedWrite({ text, workspace, mode }) {
+  if (mode !== "workspace-write" || typeof text !== "string") return null;
+  const lines = text.split(/\r?\n/u);
+  const markerLines = lines.filter((line) => SANDBOX_READ_ONLY_PATTERN.test(line));
+  if (markerLines.length === 0) return null;
+  // Prefer a path the refusal line itself names; fall back to any path in the
+  // output, since `manifest_create ReadOnlyFileSystem` can put the path on a
+  // neighbouring line.
+  for (const line of [...markerLines, ...lines]) {
+    for (const pattern of ABSOLUTE_PATH_PATTERNS) {
+      for (const match of line.matchAll(pattern)) {
+        const candidate = match[1];
+        const path = isAbsolute(candidate) ? candidate : resolve(workspace, candidate);
+        if (!isContained(workspace, path)) return { classification: SANDBOX_BLOCKED_WRITE, mode, path };
+      }
+    }
+  }
+  return null;
+}
 /**
  * Run every declared command `repeat` times inside the workspace.
  *
  * @param {unknown} commands
  * @param {string} baseCwd
- * @param {VerificationOptions} options
+ * @param {RunVerificationOptions} options
  * @returns {Promise<VerificationResult>}
  */
 export async function runVerification(commands, baseCwd, options = {}) {
@@ -92,7 +156,7 @@ export async function runVerification(commands, baseCwd, options = {}) {
  * @param {VerificationCommand} command
  * @param {string} baseCwd
  * @param {number} commandIndex
- * @param {VerificationOptions} options
+ * @param {RunVerificationOptions} options
  * @returns {Promise<VerificationCommandResult>}
  */
 async function runRepeatedCommand(command, baseCwd, commandIndex, options) {
@@ -132,7 +196,7 @@ function signalDeathRetry(result, signal) {
  * @param {VerificationCommand} command
  * @param {string} baseCwd
  * @param {number} commandIndex
- * @param {VerificationOptions} options
+ * @param {RunVerificationOptions} options
  * @returns {Promise<VerificationCommandResult>}
  */
 async function runMutationCommand(command, baseCwd, commandIndex, options) {
@@ -149,7 +213,7 @@ async function runMutationCommand(command, baseCwd, commandIndex, options) {
  * @param {string} commandCwd
  * @param {number} attempt
  * @param {AbortSignal|undefined} signal
- * @param {VerificationOptions} options
+ * @param {RunVerificationOptions} options
  * @param {number} commandIndex
  * @returns {Promise<VerificationAttemptResult>}
  */
@@ -181,6 +245,7 @@ function runCommand(command, baseCwd, commandCwd, attempt, signal, options, comm
       if (abortHandler) signal?.removeEventListener("abort", abortHandler);
       if (child?.pid && !error && !signalName && !timedOut) terminateGroup(child);
       const durationMs = Number(process.hrtime.bigint() - started) / 1e6;
+      /** @type {SandboxAwareAttemptResult} */
       const result = {
         attempt,
         stdout: stdout.value(),
@@ -192,6 +257,17 @@ function runCommand(command, baseCwd, commandCwd, attempt, signal, options, comm
         error: error ? String(error.message ?? error) : null,
         passed: !error && !timedOut && exitCode === 0 && !signalName,
       };
+      // The controller's own sandbox mode bounds where a toolchain may write;
+      // a caller may name it, and a controller launched under `dsh` inherits it
+      // in `DSH_PERMISSION_MODE`. Only `workspace-write` classifies.
+      if (!result.passed) {
+        const sandboxBlockedWrite = classifySandboxBlockedWrite({
+          text: `${result.stdout}\n${result.stderr}`,
+          workspace: resolve(baseCwd, commandCwd),
+          mode: options?.sandboxMode ?? process.env.DSH_PERMISSION_MODE ?? null,
+        });
+        if (sandboxBlockedWrite) result.sandboxBlockedWrite = sandboxBlockedWrite;
+      }
       if (!completionReported && identity) {
         completionReported = true;
         try { options?.onAttemptComplete?.({ ...identity, status: result.passed ? "closed" : "failed", completedAt: new Date().toISOString(), result }); } catch {

package/src/engine/run-identity.mjs

@@ -21,7 +21,7 @@ import { createHash } from "node:crypto";
 import { lstatSync, readFileSync, readdirSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { stableJson } from "../util.mjs";
+import { stableJson, errorCode } from "../util.mjs";
 import { validateRunMetadata } from "../contract/snapshot.mjs";
 import { contractDigest } from "../contract/index.mjs";
 import { RUNS_DIR_NAME, runDirectory } from "../run/paths.mjs";
@@ -97,6 +97,26 @@ function runDirFor(sourceIdentity) {
   return runDirectory(sourceIdentity.cwd, sourceIdentity.contractId);
 }
 
+/**
+ * Whether a run directory never materialized a node. The directory, its
+ * frozen contract and its empty `nodes/` folder are written before runtime
+ * assignment and identity capture; node states are written after. A launch
+ * refused in that window leaves a directory that never held a node, so
+ * nothing can resume it and it would refuse the next attempt as an existing
+ * run.
+ *
+ * @param {string} runDir
+ * @returns {boolean}
+ */
+export function runNeverHeldNode(runDir) {
+  try {
+    return readdirSync(join(runDir, "nodes")).every((name) => !name.endsWith(".json"));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return true;
+    throw error;
+  }
+}
+
 /**
  * The records a prior run.json already froze, when one exists. On creation
  * this is empty; on every later metadata rewrite it is the source of truth.
@@ -506,14 +526,10 @@ export async function assertEnvironmentReady(contract, runDir, sourceIdentity) {
   // state reads done, this launch replays an accepted transaction, starts no
   // worker and no judge, and can spend no availability.
   if (blocking === null && launchMayDispatch(runDir)) {
-    // measured 2026-09-22: asking four routed runtimes in parallel took about
-    // 18s, so no runtime is given less than 60s here; a runtime at high
-    // reasoning effort gets its longer default (defaultLivePreflightTimeout).
-    // FABERUN_PREFLIGHT_TIMEOUT_SEC stays the operator override for every
-    // runtime; preflightContract validates it, so only a valid number is lifted.
-    const override = Number(process.env.FABERUN_PREFLIGHT_TIMEOUT_SEC);
-    const timeoutSec = process.env.FABERUN_PREFLIGHT_TIMEOUT_SEC !== undefined && Number.isFinite(override) && override > 0 ? override : undefined;
-    const probes = await livePreflightProbes(contract, runDir, sourceIdentity, timeoutSec);
+    // The live budget is `live-preflight.mjs`'s measured default (60s, 180s at xhigh;
+    // `FABERUN_PREFLIGHT_TIMEOUT_SEC` the operator override). It is not
+    // restated here: a second copy is a second default to keep honest.
+    const probes = await livePreflightProbes(contract, runDir, sourceIdentity);
     const silent = probes.filter((probe) => liveSilenceCause(probe) !== null);
     writeJsonAtomic(join(runDir, "env-preflight.json"), evidence(silent.length === 0, probes));
     if (silent.length > 0) {
@@ -537,8 +553,6 @@ export async function assertEnvironmentReady(contract, runDir, sourceIdentity) {
   throw Object.assign(new Error(`env_preflight_failed: ${blocking} · the run stays resumable: fix the environment and resume ${runDir}`), { code: "env_preflight_failed" });
 }
 
-/** No routed runtime is given less than this by the dispatch gate. */
-const GATE_MINIMUM_PREFLIGHT_SEC = 60;
 /**
  * The live half of the gate for one launch. Every routed runtime either holds
  * a verdict this machine recorded inside its freshness window -- reused, the
@@ -555,10 +569,9 @@ const GATE_MINIMUM_PREFLIGHT_SEC = 60;
  * @param {ValidatedContract} contract
  * @param {string} runDir
  * @param {SourceIdentity|undefined} sourceIdentity
- * @param {number|undefined} timeoutSec
  * @returns {Promise<ProbeResult[]>}
  */
-async function livePreflightProbes(contract, runDir, sourceIdentity, timeoutSec) {
+async function livePreflightProbes(contract, runDir, sourceIdentity) {
   const routed = reachableRuntimes(contract);
   /** @type {Map<string, RuntimeAvailability>} */
   const fresh = new Map();
@@ -631,7 +644,7 @@ async function livePreflightProbes(contract, runDir, sourceIdentity, timeoutSec)
       };
     });
   }
-  const probes = await preflightContract(join(runDir, "contract.json"), { ...(timeoutSec === undefined ? {} : { liveTimeoutSec: timeoutSec }), minimumTimeoutSec: GATE_MINIMUM_PREFLIGHT_SEC, persisted: true });
+  const probes = await preflightContract(join(runDir, "contract.json"), { persisted: true });
   // What this launch bought is durable from here on: every ask that reached a
   // provider -- a refusal included, an answer being an answer -- is recorded
   // under the provider's own identity. Silence and a command that never

package/src/engine/runtime-discovery.mjs

@@ -1,6 +1,6 @@
 import { normalizeProviderAvailability, probeRuntime } from "../harnesses/index.mjs";
 import { effectiveProvider } from "../contract/provider.mjs";
-import { SAME_VENDOR_REVIEW_MODE, sameVendorTierRefusal } from "../contract/judge-independence.mjs";
+import { SAME_VENDOR_REVIEW_MODE, effectiveJudgeIndependence, sameVendorTierRefusal } from "../contract/judge-independence.mjs";
 
 // Availability normalization belongs to the adapter registry, which is where
 // each provider's own exhaustion, balance, and authentication wording is
@@ -56,6 +56,18 @@ export { exhaustedUntilOf, normalizeProviderAvailability } from "../harnesses/in
  * @type {Readonly<Record<string, DiscoveryRuntime>>}
  */
 export const DISCOVERY_RUNTIME_DEFINITIONS = Object.freeze({
+  // Every vendor this harness reaches is declared ahead of the older harness
+  // for the same models, so fx wins each tie-break. Measured on the
+  // parseDuration benchmark (2026-09-25): 22-27 MB per fx worker against
+  // 362-422 MB for dsh, with the same scope and hidden-test results.
+  "fx-deepseek": {
+    harness: "fx",
+    model: "deepseek-flash",
+    vendor: "deepseek",
+    config: { "api_key.env_key": "DEEPSEEK_API_KEY" },
+    tier: 1,
+    costRank: 1,
+  },
   // `dsh` defaults no vendor and no provider route, so both are declared here
   // or nothing can build a command from this entry.
   "dsh-deepseek": {
@@ -66,6 +78,32 @@ export const DISCOVERY_RUNTIME_DEFINITIONS = Object.freeze({
     tier: 1,
     costRank: 1,
   },
+  // GLM 5.3 on fx through the Z.ai Coding Plan's Chat Completions endpoint.
+  // The operator chose this default knowing the plan's usage policy lists
+  // Claude Code and ZCode, not fx, and restricts or bans an account for
+  // detected third-party use; `claude-glm` below is the supported route.
+  // Measured 2026-09-26: the tiny-text campaign with a GLM worker and a
+  // DeepSeek judge, both on fx, peaked at 283 MB.
+  "fx-glm": {
+    harness: "fx",
+    model: "glm-5.3",
+    vendor: "zhipu",
+    config: { base_url: "https://api.z.ai/api/coding/paas/v4", "api_key.env_key": "ZAI_API_KEY", context_window: 200_000 },
+    tier: 1,
+    costRank: 1,
+  },
+  // GLM through Claude Code, which the Z.ai Coding Plan lists as a supported
+  // tool. Declared before zcode-glm so it wins the tie-break: measured
+  // 2026-09-25 on one review prompt, 384-392 MB per turn against 0.9-1.0 GB
+  // for zcode, and the tiny-text campaign peaked at 865 MB against 1,575 MB.
+  "claude-glm": {
+    harness: "claude",
+    model: "glm-5.3",
+    vendor: "zhipu",
+    config: { base_url: "https://api.z.ai/api/anthropic", "auth_token.env_key": "ZAI_API_KEY" },
+    tier: 1,
+    costRank: 1,
+  },
   // The flash tier, not the unsuffixed pro: measured 2026-09-24 in the judge
   // canary, glm-5.3 recalled 0.79 against glm-5.3-flash's 0.85 at about nine
   // times the price, which the owner confirmed matches the public benchmarks.
@@ -78,15 +116,19 @@ export const DISCOVERY_RUNTIME_DEFINITIONS = Object.freeze({
     costRank: 1,
   },
   "agy-gemini": { harness: "agy", model: "gemini-3.8-flash-low", vendor: "google", tier: 1, costRank: 1 },
+  // GPT on fx through fx's own ChatGPT login, which fx-faberun reads from the
+  // operator's profile (`FX_AUTH_HOME`). Measured 2026-09-26: one review turn
+  // peaked at 35-47 MB for the runner and fx together.
+  "fx-gpt": { harness: "fx", model: "gpt-5.6-sol", vendor: "openai", config: { provider: "codex" }, tier: 2, costRank: 2 },
   // Three codex rows, because the harness declares three models and an
   // account is entitled to only some of them: measured 2026-09-21 on the
   // owner's ChatGPT account, plain `gpt-5.6` answers HTTP 400 while
   // `gpt-5.6-sol` answers normally. One row meant `setup` could offer only the
   // model that account cannot use, and the operator's only way out was to hand
-  // every contract its own catalogue through `--runtimes`. Declaration order is
-  // unchanged, so the composed default is still `codex-gpt`: which of the three
-  // an account can reach is not something this file can know, and the live
-  // preflight is what reports it per id.
+  // every contract its own catalogue through `--runtimes`. `fx-gpt` above is
+  // declared first, so it is the composed tier-2 default; among these three,
+  // which an account can reach is not something this file can know, and the
+  // live preflight is what reports it per id.
   "codex-gpt": { harness: "codex", model: "gpt-5.6", vendor: "openai", tier: 2, costRank: 2 },
   "codex-sol": { harness: "codex", model: "gpt-5.6-sol", vendor: "openai", tier: 2, costRank: 2 },
   "codex-luna": { harness: "codex", model: "gpt-5.6-luna", vendor: "openai", tier: 2, costRank: 2 },
@@ -134,10 +176,12 @@ export function availableCandidates(runtimes, availability = {}) {
  * copied exactly; callers persist the returned pair in run state.
  *
  * An optional `options.config` narrows the candidate set to the harnesses the
- * operator enabled and prefers its named worker and judge. An empty narrowed
- * set falls back to the unrestricted candidates and is reported through
- * `options.onWarning`; config never overrides an explicit node, gate or
- * runtime-default declaration, and the cross-vendor judge rule still applies.
+ * operator enabled, prefers its named worker and judge, and -- when the
+ * contract declares none (R36) -- supplies the machine-wide
+ * `judgeIndependence` opt-in. An empty narrowed set falls back to the
+ * unrestricted candidates and is reported through `options.onWarning`; config
+ * never overrides an explicit node, gate or runtime-default declaration, and
+ * the cross-vendor judge rule still applies.
  *
  * `options.listJudge` (R18) is asked for an omitted judge before the single
  * `config.judge` preference and the strongest-candidate default: it is the
@@ -152,7 +196,7 @@ export function availableCandidates(runtimes, availability = {}) {
  * @param {RuntimeContract} contract
  * @param {Record<string, RuntimeAvailability>} availability
  * @param {ComposeOptions} [options]
- * @returns {Record<string, {worker: string, judge: string}>}
+ * @returns {Record<string, {worker: string, judge: string, judgeIndependence?: "same-vendor"}>}
  */
 export function composeAssignments(contract, availability = {}, options = {}) {
   const allCandidates = availableCandidates(contract.runtimes, availability);
@@ -164,7 +208,7 @@ export function composeAssignments(contract, availability = {}, options = {}) {
     if (restricted.length) candidates = restricted;
     else if (allCandidates.length) options.onWarning?.(`config harnesses · none of ${config.harnesses.join(", ")} is available · using all available runtimes`);
   }
-  /** @type {Record<string, {worker: string, judge: string}>} */
+  /** @type {Record<string, {worker: string, judge: string, judgeIndependence?: "same-vendor"}>} */
   const assignments = {};
   for (const node of contract.nodes ?? []) {
     const workerOmitted = node.runtime === undefined && contract.runtimeDefaults?.worker === undefined;
@@ -193,7 +237,11 @@ export function composeAssignments(contract, availability = {}, options = {}) {
     // R20: in same-vendor mode a judge of the worker's own provider is
     // admissible when it is another model at an equal or higher declared tier;
     // the strongest such candidate is the default only when no other vendor has one.
-    const sameVendorMode = contract.judgeIndependence === SAME_VENDOR_REVIEW_MODE;
+    // R36: a contract that declares no mode inherits the machine config's, and
+    // the effective mode is recorded on the assignment so the launch decision
+    // survives in the run snapshot.
+    const judgeIndependence = effectiveJudgeIndependence(contract, config);
+    const sameVendorMode = judgeIndependence === SAME_VENDOR_REVIEW_MODE;
     const judge = declaredJudge
       ?? judgeListPick?.chosen
       ?? (preferredJudge && effectiveProvider(preferredJudge.runtime) !== workerProvider ? preferredJudge.id : undefined)
@@ -209,7 +257,7 @@ export function composeAssignments(contract, availability = {}, options = {}) {
       const refusal = sameVendorTierRefusal(/** @type {{harness: string, model: string}} */ (workerRuntime), /** @type {{harness: string, model: string}} */ (judgeRuntime));
       if (refusal) throw new Error(`runtime_assignment_judge_unavailable: ${refusal.message} for node ${node.id}`);
     }
-    assignments[node.id] = { worker, judge: judge ?? worker };
+    assignments[node.id] = { worker, judge: judge ?? worker, ...(judgeIndependence === undefined ? {} : { judgeIndependence }) };
   }
   return assignments;
 }

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}
  */