faberun 0.27.0 → 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
@@ -176,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
@@ -194,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);
@@ -206,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;
@@ -235,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)
@@ -251,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}
  */

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