faberun 0.26.3 → 0.28.0

package/src/harnesses/runner-io.mjs

@@ -0,0 +1,25 @@
+/**
+ * The process half every Faberun harness runner shares: one prompt read from
+ * stdin, one JSONL transcript written to fd 1. Kept apart from
+ * `runner-transcript.mjs` because that module runs inside the controller and
+ * this one inside the spawned runner process.
+ */
+
+import { writeSync } from "node:fs";
+
+/**
+ * Whole-line writes to fd 1: `process.exit` cannot lose an unfinished write.
+ *
+ * @param {Record<string, unknown>} event
+ */
+export function emit(event) {
+  const line = Buffer.from(`${JSON.stringify(event)}\n`, "utf8");
+  for (let written = 0; written < line.length; ) written += writeSync(1, line, written);
+}
+
+/** @returns {Promise<string>} */
+export async function readPrompt() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}

package/src/harnesses/runner-transcript.mjs

@@ -0,0 +1,127 @@
+/**
+ * The adapter half of Faberun's own harness clients. `dsh` and `fx` are
+ * driven by a runner this repository ships (a JSON-RPC client per harness),
+ * and both runners write the same transcript: `<prefix>.started`,
+ * `<prefix>.tool`, `<prefix>.message`, then exactly one `<prefix>.completed`
+ * or `<prefix>.failed` carrying the session usage. Folding that transcript
+ * into an envelope is one job whatever harness sits behind the runner, so it
+ * lives here instead of in either adapter.
+ */
+
+import { canonicalUsage, extractJson, failed, isQuotaText, isVerdictCandidate, parseJsonLines } from "./protocol.mjs";
+
+/**
+ * @param {string} prefix the runner's event namespace, `dsh` or `fx`
+ * @param {string} stdout
+ * @param {number|null} exitCode
+ * @param {string|null} signal
+ * @param {import("./index.mjs").NormalizeOptions} [options]
+ * @returns {import("./index.mjs").ProviderEnvelope}
+ */
+export function normalizeRunnerTranscript(prefix, stdout, exitCode, signal, options = {}) {
+  if (signal) return failed("canceled", `provider ended after ${signal}`, "canceled");
+  let events;
+  try {
+    events = parseJsonLines(stdout, prefix);
+  } catch (error) {
+    return failed("invalid_protocol", error instanceof Error ? error.message : String(error));
+  }
+  const terminal = events.findLast((event) => event.type === `${prefix}.completed` || event.type === `${prefix}.failed`);
+  if (!terminal) {
+    const detail = options.stderr?.trim();
+    return failed(
+      "incomplete_stream",
+      `${prefix} emitted no terminal event${detail ? `: ${detail.slice(-512)}` : ""}${exitCode === null ? "" : ` (exit ${exitCode})`}`,
+    );
+  }
+  const usage = canonicalUsage(terminal.usage);
+  if (terminal.type === `${prefix}.completed`) {
+    const text = typeof terminal.result === "string" ? terminal.result : null;
+    const result = options.preferStructured ? extractJson(text) ?? text : text;
+    const verdicts = options.preferStructured
+      ? events.filter((event) => event.type === `${prefix}.message` && isVerdictCandidate(event.text)).length
+      : null;
+    return {
+      status: result?.trim() ? "done" : "no-op",
+      result,
+      continuationId: null,
+      usage,
+      costUsd: null,
+      error: null,
+      ...(verdicts === null ? {} : { judgeCandidates: verdicts }),
+    };
+  }
+  const error = terminal.error && typeof terminal.error === "object" ? /** @type {Record<string, unknown>} */ (terminal.error) : {};
+  const kind = typeof terminal.kind === "string" ? terminal.kind : "error";
+  const code = typeof error.code === "string" && error.code ? error.code : kind;
+  const message = typeof error.message === "string" && error.message ? error.message : code;
+  const resetAt = resetTimestamp(error.retryAfterMs);
+  return {
+    status: statusFor(kind, `${code} ${message}`),
+    result: null,
+    continuationId: null,
+    usage,
+    costUsd: null,
+    error: { code, message, ...(resetAt ? { resetAt } : {}) },
+    ...(resetAt ? { exhaustedUntil: resetAt } : {}),
+  };
+}
+
+/**
+ * Append the output schema the judge prompt refers to. Codex and Claude receive
+ * it through a native flag; neither runner-driven harness has one, so it
+ * travels in the prompt.
+ *
+ * @param {string} prompt
+ * @param {object|undefined} schema
+ * @returns {string}
+ */
+export function withSchema(prompt, schema) {
+  if (!schema) return prompt;
+  return `${prompt}\n\nOutput schema (the JSON object must validate against it):\n${JSON.stringify(schema)}`;
+}
+
+/**
+ * The environment overlay every runner turn spawns with. The Claude Code shell
+ * exports `GIT_CONFIG_COUNT` with the VALUE half of each `GIT_CONFIG_{KEY,VALUE}_<n>`
+ * pair but not the key half, so `git init` inside the worker fails with status
+ * 128; the overlay removes the whole family. `GIT_TERMINAL_PROMPT=0` takes over
+ * the prompting that family was for. A null value removes the ambient variable
+ * when the gate merges the overlay over the runner environment.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {Record<string, string|null>}
+ */
+export function runnerEnvironmentOverlay(env) {
+  /** @type {Record<string, string|null>} */
+  const overlay = { GIT_TERMINAL_PROMPT: "0" };
+  for (const key of Object.keys(env)) {
+    if (key === "GIT_CONFIG_COUNT" || /^GIT_CONFIG_(?:KEY|VALUE)_\d+$/u.test(key)) overlay[key] = null;
+  }
+  return overlay;
+}
+
+/**
+ * @param {string} kind
+ * @param {string} text
+ * @returns {"done"|"no-op"|"blocked"|"failed"|"exhausted"|"stalled"|"canceled"}
+ */
+function statusFor(kind, text) {
+  if (kind === "aborted") return "canceled";
+  if (kind === "blocked") return "blocked";
+  if (isQuotaText(text) || /insufficient balance/iu.test(text)) return "exhausted";
+  if (/permission|approval|sandbox/iu.test(text)) return "blocked";
+  return "failed";
+}
+
+/**
+ * Turn the harness's relative retry hint into the absolute instant the
+ * controller needs; without one it takes the failover edge instead of waiting.
+ *
+ * @param {unknown} retryAfterMs
+ * @returns {string|null}
+ */
+function resetTimestamp(retryAfterMs) {
+  if (typeof retryAfterMs !== "number" || !Number.isFinite(retryAfterMs) || retryAfterMs <= 0) return null;
+  return new Date(Date.now() + retryAfterMs).toISOString();
+}

package/src/harnesses/session-metrics.mjs

@@ -26,7 +26,29 @@ import { finite } from "../util.mjs";
  */
 
 /** The harnesses whose streams carry usage per provider request; the others meter turns and tool calls only. */
-const PER_REQUEST_USAGE = new Set(["claude", "dsh", "agy", "exec-jsonl", "replay"]);
+const PER_REQUEST_USAGE = new Set(["claude", "dsh", "fx", "agy", "exec-jsonl", "replay"]);
+
+/**
+ * The transcripts Faberun's own harness clients write (`runner-transcript.mjs`).
+ * `usage` names the event that carries one provider request's usage: dsh
+ * attaches it to each assistant message, while fx's relay reports it per HTTP
+ * request, apart from the message text.
+ */
+const RUNNER_TRANSCRIPTS = Object.freeze({
+  dsh: Object.freeze({ usage: "dsh.message", tool: "dsh.tool", completed: "dsh.completed", failed: "dsh.failed" }),
+  fx: Object.freeze({ usage: "fx.request", tool: "fx.tool", completed: "fx.completed", failed: "fx.failed" }),
+});
+
+/** @param {string} harness */
+function runnerTranscript(harness) {
+  return Object.hasOwn(RUNNER_TRANSCRIPTS, harness) ? RUNNER_TRANSCRIPTS[/** @type {"dsh"|"fx"} */ (harness)] : null;
+}
+
+/** @param {string} harness @param {unknown} type */
+function isRunnerTerminal(harness, type) {
+  const transcript = runnerTranscript(harness);
+  return transcript !== null && (type === transcript.completed || type === transcript.failed);
+}
 
 /**
  * Best-effort input-token meter over a still-growing transcript. The
@@ -90,15 +112,16 @@ export function liveUsage(harness, stdout) {
       cacheReadInputTokens: null,
     };
   }
-  if (harness === "dsh") {
-    // The terminal event carries the harness's own session total; before it
-    // lands, sum the per-message usage the runner forwards.
-    const terminal = events.findLast((event) => event?.type === "dsh.completed" || event?.type === "dsh.failed");
+  const transcript = runnerTranscript(harness);
+  if (transcript) {
+    // The terminal event carries the session total; before it lands, sum the
+    // per-request usage the runner forwards.
+    const terminal = events.findLast((event) => event?.type === transcript.completed || event?.type === transcript.failed);
     const terminalUsage = terminal ? canonicalUsage(terminal.usage) : null;
     if (terminalUsage && terminalUsage.inputTokens !== null) {
       return { inputTokens: terminalUsage.inputTokens, cacheReadInputTokens: terminalUsage.cacheReadInputTokens };
     }
-    return sumRequestUsage(events.filter((event) => event?.type === "dsh.message").map((event) => event.usage));
+    return sumRequestUsage(events.filter((event) => event?.type === transcript.usage).map((event) => event.usage));
   }
   if (harness === "agy") {
     const resultRecord = events.map((event) => agyResult(event)).findLast((result) => result !== null);
@@ -394,7 +417,7 @@ export class SessionMetricsParser {
       }
     } else if (this.harness === "claude" && record.type === "result") {
       totals.completed = true;
-    } else if (this.harness === "dsh" && (record.type === "dsh.completed" || record.type === "dsh.failed")) {
+    } else if (isRunnerTerminal(this.harness, record.type)) {
       totals.completed = true;
     } else if (this.harness === "agy" && record.event === "result") {
       totals.completed = true;
@@ -453,20 +476,22 @@ function foldRecord(harness, totals, record) {
     }
     return;
   }
-  if (harness === "dsh") {
-    // The runner folds the sdk firehose to one `dsh.message` per assistant
-    // message (with that message's usage) and one `dsh.tool` per tool call.
+  const transcript = runnerTranscript(harness);
+  if (transcript) {
+    // The dsh runner folds the sdk firehose to one `dsh.message` per assistant
+    // message (with that message's usage) and one `dsh.tool` per tool call;
+    // the fx runner reports usage per relayed request as `fx.request`.
     // measured 2026-09-20: before this branch a dsh turn metered zero events,
     // so once progress became event-only (668f6c1) the stall detector cut
     // every dsh worker at the contract's stallTimeoutSec regardless of
     // activity -- three kills on 2026-09-16 at 903s against a 900s limit.
-    if (record.type === "dsh.message") {
+    if (record.type === transcript.usage) {
       totals.turns += 1;
       totals.cacheReadInputTokens += canonicalUsage(record.usage).cacheReadInputTokens ?? 0;
       foldRequestUsage(totals, canonicalUsage(record.usage));
-    } else if (record.type === "dsh.tool") {
+    } else if (record.type === transcript.tool) {
       totals.toolCalls += 1;
-    } else if (record.type === "dsh.completed" || record.type === "dsh.failed") {
+    } else if (record.type === transcript.completed || record.type === transcript.failed) {
       const sessionTotal = canonicalUsage(record.usage).cacheReadInputTokens;
       if (sessionTotal !== null) totals.cacheReadInputTokens = sessionTotal;
     }

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