faberun 0.24.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/skills/faberun/references/contract.md

@@ -25,7 +25,6 @@ typecheck`). Schema version is `3`.
     "sol": { "harness": "codex", "model": "gpt-5.6-sol", "reasoning": "xhigh", "vendor": "openai-sol" },
     "opus": { "harness": "claude", "model": "opus", "permissionMode": "acceptEdits" },
     "zcode-flash": { "harness": "zcode", "model": "glm-5.3-flash", "vendor": "zhipu-flash", "permissionMode": "edit" },
-    "zcode-pro": { "harness": "zcode", "model": "glm-5.3", "vendor": "zhipu-pro", "permissionMode": "plan" },
     "agy-flash": { "harness": "agy", "model": "gemini-3.8-flash-low" }
   },
   "nodes": [
@@ -141,8 +140,10 @@ missing something, never repository-wide exploration. Bounded: 32 KiB total,
 4 KiB summary, 32 entries each in `changedFiles`/`verification`/`artifacts`
 (16 in `missingContext`), 2 KiB per entry (16 KiB per artifact). Unknown
 provider-added fields are dropped; missing/malformed canonical fields are
-rejected (`worker-result.mjs`). A discovery node returns `done` with exactly
-one `artifacts` entry: the execution packet for the next node.
+rejected (`worker-result.mjs`). A discovery node without `readFiles` returns
+`done` with one `artifacts` entry, the next node's execution packet; one closed
+to its `readFiles` (every planning stage) delivers through `output`, `artifacts`
+`[]`.
 
 ## Runtimes and routing
 

package/src/campaign/index.mjs

@@ -10,6 +10,7 @@ import { writeJsonAtomic } from "../run/store.mjs";
 import { projectIdForRunsDir, repositoryForRunsDir } from "../run/paths.mjs";
 import { requireId, requirePacketHash, requireString, requireTimestamp } from "../contract/assert.mjs";
 import { promoteRun } from "../repo/integrate.mjs";
+import { releaseRunWorktrees } from "../repo/worktree.mjs";
 import { CAMPAIGN_FILE, GOAL_TEXT_BYTES, PROJECTION_FILE, campaignDir, campaignsDir } from "./layout.mjs";
 import { readCampaign } from "./record.mjs";
 import { appendJournal, normalizeText, readJournalForDedupe } from "./journal.mjs";
@@ -130,7 +131,7 @@ export function resolveCampaign(runsDir, campaignId) {
 /**
  * @param {string} campaignPath
  * @param {{at?: string, eventId?: string}} options
- * @returns {{path: string, campaign: Campaign, ledgerFiles: string[], ledgerSkipped: {runId: string, source: string}[]}}
+ * @returns {{path: string, campaign: Campaign, ledgerFiles: string[], ledgerSkipped: {runId: string, source: string}[], worktrees: {removed: number, archived: string[]}}}
  */
 export function closeCampaign(campaignPath, { at = new Date().toISOString(), eventId = randomUUID() } = {}) {
   requireTimestamp(at, "at");
@@ -154,7 +155,16 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   // Preserve after the closed record exists: the ledger is the recomputable
   // closed record, including requirements used by the north-star projector.
   const ledger = preserveCampaignLedger(campaignPath, campaignRepoRoot(campaignPath));
-  return { path: campaignPath, campaign: closed, ledgerFiles: ledger.written, ledgerSkipped: ledger.skipped };
+  // A closed campaign resumes nothing, so the attempt worktrees its runs left
+  // go now, each archived under a ref first (releaseRunWorktrees).
+  const runsDir = resolve(campaignPath, "..", "..");
+  const worktrees = { removed: 0, archived: /** @type {string[]} */ ([]) };
+  for (const runId of campaign.linkedRunIds) {
+    const released = releaseRunWorktrees(campaignRepoRoot(campaignPath), join(runsDir, runId), runId);
+    worktrees.removed += released.removed;
+    worktrees.archived.push(...released.archived);
+  }
+  return { path: campaignPath, campaign: closed, ledgerFiles: ledger.written, ledgerSkipped: ledger.skipped, worktrees };
 }
 
 /**

package/src/cli/campaign.mjs

@@ -320,6 +320,7 @@ function close(campaignId, values) {
     process.stdout.write(`[campaign] ledger skipped · ${skipped.runId}/${skipped.source}\n`);
   }
   reportRequirementClosure(closed.campaign.requirements ?? []);
+  if (closed.worktrees.removed > 0) process.stdout.write(`[campaign] worktrees released · ${closed.worktrees.removed} · archived under refs/faberun-archive/\n`);
   if (syncAgentSignal(runsDir)) process.stdout.write(`[campaign] AGENTS.md signal updated\n`);
 }
 

package/src/contract/task-packet.mjs

@@ -426,8 +426,11 @@ function pathInside(path, root) {
  * @returns {string}
  */
 function renderDiscoveryPrompt(packet, nodeId) {
+  // The closed variant says what settlement accepts (engine/lifecycle.mjs):
+  // only a discovery packet with no read files owes an execution packet in
+  // artifacts[0]; one closed to its read files delivers through `output`.
   const closedContext = packet.readFiles.length
-    ? "This discovery context is read-only and closed to the listed read files. Inspect only those files and do not perform repository-wide exploration. Return the worker-result JSON object below; put exactly one execution task packet JSON string in artifacts[0]."
+    ? "This discovery context is read-only and closed to the listed read files. Inspect only those files and do not perform repository-wide exploration. Return the worker-result JSON object below; deliver your result in `output` and send `artifacts` as []."
     : "This discovery context is read-only and is the one exception to closed inspection: no read files were pre-supplied, so you may inspect the repository read-only only as needed to produce the packet. Do not edit the repository. Return the worker-result JSON object below; put exactly one execution task packet JSON string in artifacts[0].";
   const lines = [
     `# Node ${nodeId} (discovery)`,

package/src/contract/worker-result.mjs

@@ -25,6 +25,23 @@ const RESULT_LIMITS = Object.freeze({
  */
 export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
 
+/**
+ * A worker result that is well-formed JSON but breaks one of the byte
+ * ceilings above. Typed, not a plain TypeError, so the repair prompt can name
+ * the ceiling that was broken: observed 2026-09-25, a planning draft that
+ * copied its 38 KiB plan into `artifacts[0]` was told twice to drop markdown
+ * fences it never wrote, and repeated the copy.
+ */
+export class WorkerResultSizeError extends TypeError {
+  /** @param {string} field @param {number} limit */
+  constructor(field, limit) {
+    super(`${field} exceeds ${limit} bytes`);
+    this.name = "WorkerResultSizeError";
+    this.field = field;
+    this.limit = limit;
+  }
+}
+
 /** @typedef {"done"|"blocked_context"} WorkerResultStatus */
 
 /**
@@ -37,6 +54,20 @@ export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
  * @typedef {{status: WorkerResultStatus, summary: string, verification: string[], artifacts: string[], missingContext: string[], output?: Record<string, unknown>}} WorkerResult
  */
 
+/**
+ * The repair instruction for an invalid worker result: a broken byte ceiling
+ * is named, since re-emitting the same object without fences cannot fix it.
+ *
+ * @param {unknown} cause
+ * @returns {string}
+ */
+export function invalidResultRepair(cause) {
+  if (cause instanceof WorkerResultSizeError) {
+    return `the result breaks a size ceiling: ${cause.field} exceeds ${cause.limit} bytes. Keep every field within its ceiling; a node that delivers through \`output\` sends \`artifacts\` as [] and never copies \`output\` into \`artifacts\`.`;
+  }
+  return "the entire final message must be exactly the required JSON object: no markdown fences, no prose before or after it. Return it as the only content of the final message.";
+}
+
 /**
  * @param {string} value
  * @returns {WorkerResult}
@@ -45,7 +76,7 @@ export function parseWorkerResult(value) {
   if (typeof value !== "string") throw new TypeError("worker result must be JSON text");
   const maxRawBytes = RESULT_LIMITS.bytes + RESULT_LIMITS.outputBytes;
   if (Buffer.byteLength(value, "utf8") > maxRawBytes) {
-    throw new TypeError(`worker result exceeds ${maxRawBytes} bytes`);
+    throw new WorkerResultSizeError("worker result", maxRawBytes);
   }
   let parsed;
   try {
@@ -100,7 +131,7 @@ export function validateWorkerResult(value) {
   if (Object.hasOwn(record, "output") && record.output !== undefined) {
     assertObject(record.output, "worker result.output");
     if (Buffer.byteLength(JSON.stringify(record.output), "utf8") > RESULT_LIMITS.outputBytes) {
-      throw new TypeError(`worker result.output exceeds ${RESULT_LIMITS.outputBytes} bytes`);
+      throw new WorkerResultSizeError("worker result.output", RESULT_LIMITS.outputBytes);
     }
     output = /** @type {Record<string, unknown>} */ (record.output);
   }
@@ -115,7 +146,7 @@ export function validateWorkerResult(value) {
   // it is a discovery node's deliverable, not incidental prose competing with
   // summary/verification for the same 32 KiB budget.
   if (Buffer.byteLength(JSON.stringify(envelope), "utf8") > RESULT_LIMITS.bytes) {
-    throw new TypeError(`worker result exceeds ${RESULT_LIMITS.bytes} bytes`);
+    throw new WorkerResultSizeError("worker result", RESULT_LIMITS.bytes);
   }
   return output === undefined ? envelope : { ...envelope, output };
 }
@@ -165,6 +196,6 @@ function requireList(value, label, maxItems, itemBytes) {
   if (!Array.isArray(value) || value.length > maxItems) throw new TypeError(`${label} must be an array with at most ${maxItems} items`);
   for (const [index, item] of value.entries()) {
     if (typeof item !== "string") throw new TypeError(`${label}[${index}] must be a string`);
-    if (Buffer.byteLength(item, "utf8") > itemBytes) throw new TypeError(`${label}[${index}] exceeds ${itemBytes} bytes`);
+    if (Buffer.byteLength(item, "utf8") > itemBytes) throw new WorkerResultSizeError(`${label}[${index}]`, itemBytes);
   }
 }

package/src/engine/lifecycle.mjs

@@ -33,9 +33,11 @@ import {
   upsertTierExhaustionCandidate,
 } from "./backoff.mjs";
 import { exhaustedUntilOf } from "./runtime-discovery.mjs";
+import { getHarness, normalizeProviderAvailability } from "../harnesses/index.mjs";
+import { availabilityKey, recordRefusal, refusalOfAvailability } from "../run/availability.mjs";
 
 import { acquire as acquireLock } from "../run/lock.mjs";
-import { parseDiscoveryResult } from "../contract/worker-result.mjs";
+import { invalidResultRepair, parseDiscoveryResult } from "../contract/worker-result.mjs";
 import { boundedUtf8, errorCode, errorMessage, excerpt } from "../util.mjs";
 import { readJson, writeJsonAtomic } from "../run/store.mjs";
 import { invocationAlive } from "./process.mjs";
@@ -441,7 +443,7 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
     // path fails it today.
     if (workerResultError) {
       if (envelope.status === "done") {
-        await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, errorMessage(workerResultError), states, campaignPath);
+        await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, workerResultError, states, campaignPath);
         continue;
       }
       adoptedWorkerResult = null;
@@ -547,7 +549,7 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
           }, lock);
           continue;
         }
-        await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, errorMessage(error), states, campaignPath);
+        await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, error, states, campaignPath);
         continue;
       }
       // The artifact demand follows the documented discovery contract, not the
@@ -560,7 +562,7 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
         try {
           parseDiscoveryResult(workerResult, attemptWorkspace(state) ?? contract.cwd);
         } catch (error) {
-          await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, errorMessage(error), states, campaignPath);
+          await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, error, states, campaignPath);
           continue;
         }
       }
@@ -635,6 +637,10 @@ export function handleProviderExhaustion(contract, runDir, node, state, role, en
     now,
   });
   const exhaustedUntil = exhaustedUntilOf(envelope);
+  // Every other process on this machine learns the refusal now, not from its own failed call.
+  const runtime = contract.runtimes?.[current];
+  const refusal = runtime ? refusalOfAvailability(normalizeProviderAvailability(runtime, envelope)) : null;
+  if (runtime && refusal) recordRefusal(availabilityKey({ harness: runtime.harness, model: runtime.model, executable: getHarness(runtime.harness).executable(runtime) }), refusal);
   const plan = planRoute(contract, node, state, role, error, current, schedule, now, exhaustedUntil);
   const status = envelope.status === "failed" ? "failed" : "exhausted";
   if (plan.blocked) {
@@ -731,19 +737,21 @@ function applyRoute(contract, runDir, state, lock, { role, error, current, plan,
  * told to return. A second one is evidence about the provider rather than the
  * packet, so the node records a protocol_failure and takes its failover edge —
  * and when no edge remains, it blocks and raises attention rather than filing
- * a quiet exhaustion nobody reads.
+ * a quiet exhaustion nobody reads. The repair names what was wrong
+ * (invalidResultRepair), so a broken byte ceiling is not told about fences.
  *
- * @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {Map<string, Job>|null} running @param {LockHandle} lock @param {string} message @param {Map<string, NodeSnapshot>} states @param {string} campaignPath
+ * @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {Map<string, Job>|null} running @param {LockHandle} lock @param {unknown} cause @param {Map<string, NodeSnapshot>} states @param {string} campaignPath
  */
-export async function applyInvalidWorkerResult(contract, node, state, runDir, running, lock, message, states, campaignPath) {
+export async function applyInvalidWorkerResult(contract, node, state, runDir, running, lock, cause, states, campaignPath) {
   clearTierExhaustion(state);
+  const message = errorMessage(cause);
   const verdict = /** @type {JudgeVerdict} */ ({
     verdict: "fail",
     maxSeverity: "critical",
     summary: "worker result did not match the structured result protocol",
     findings: [{
       severity: "critical",
-      description: "the entire final message must be exactly the required JSON object: no markdown fences, no prose before or after it. Return it as the only content of the final message.",
+      description: invalidResultRepair(cause),
       evidence: boundedUtf8(message, 4 * 1024),
     }],
   });

package/src/engine/live-preflight.mjs

@@ -16,7 +16,7 @@ import { emptyUsage } from "../run/usage.mjs";
 import { errorMessage } from "../util.mjs";
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { normalizeProviderResult, probeRuntime, providerCommand } from "../harnesses/index.mjs";
+import { normalizeProviderAvailability, normalizeProviderResult, probeRuntime, providerCommand } from "../harnesses/index.mjs";
 import { killTarget, spawnInvocation } from "../host/platform.mjs";
 import { reachableRuntimes } from "../host/preflight.mjs";
 import { spawn } from "node:child_process";
@@ -106,6 +106,9 @@ export async function preflightRuntimes(entries, options = {}) {
         liveStatus: live.status,
         usage: live.usage,
         costUsd: live.costUsd,
+        // A failed ask carries its classified cause (quota, balance, model) and
+        // reset instant, so a refusal can be recorded as one instead of as an answer.
+        ...(live.status === "done" ? {} : { availability: normalizeProviderAvailability(/** @type {any} */ (runtimes[index]), live) }),
         detail: `${check.detail ?? "static probe failed"} · ${liveDetail}`,
       };
     }));

package/src/engine/resume.mjs

@@ -284,7 +284,7 @@ export async function resumeRun(runDirPath, options = {}) {
             ? recoverWorkerResult(runDir, state, contract, node)
             : canonicalWorkerResultText(runDir, node.id) ?? recovery.result;
         } catch (error) {
-          await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, errorMessage(error), states, campaign.path);
+          await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, error, states, campaign.path);
           continue;
         }
         if (recovery.phase === "worker" && workerResult !== null && workerResult !== undefined) {
@@ -301,7 +301,7 @@ export async function resumeRun(runDirPath, options = {}) {
           try {
             parsedWorkerResult = parseWorkerResult(String(extractJson(workerResult) ?? workerResult));
           } catch (error) {
-            await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, errorMessage(error), states, campaign.path);
+            await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, error, states, campaign.path);
             continue;
           }
           // Same discriminator as lifecycle.mjs: the artifact is owed only by
@@ -311,7 +311,7 @@ export async function resumeRun(runDirPath, options = {}) {
             try {
               parseDiscoveryResult(parsedWorkerResult, attemptWorkspace(state) ?? contract.cwd);
             } catch (error) {
-              await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, errorMessage(error), states, campaign.path);
+              await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, error, states, campaign.path);
               continue;
             }
           }

package/src/engine/run-identity.mjs

@@ -13,7 +13,7 @@
  */
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, getHarness, harnessCapabilities, probeRuntime } from "../harnesses/index.mjs";
 import { appendJsonl, writeJsonAtomic } from "../run/store.mjs";
-import { availabilityKey, readAvailability, recordAvailability } from "../run/availability.mjs";
+import { availabilityKey, readAvailability, readRefusal, recordProbeVerdicts } from "../run/availability.mjs";
 import { blockingChecks, environmentPreflight, reachableRuntimes } from "../host/preflight.mjs";
 import { captureSourceIdentity } from "../repo/source-identity.mjs";
 import { boundedGitSync } from "../repo/worktree.mjs";
@@ -569,6 +569,46 @@ async function livePreflightProbes(contract, runDir, sourceIdentity, timeoutSec)
       if (verdict) fresh.set(id, verdict);
     }
   }
+  // A refusal another process met on this machine (quota, balance, model) is
+  // not asked again before its reset: the launch is refused on it, spending
+  // nothing, and the operator is told when the provider is back.
+  if (!pendingFreshPreflight) {
+    const refused = [...routed.entries()].map(([id, { runtime }]) => {
+      const executable = getHarness(runtime.harness).executable(runtime);
+      const held = readRefusal(availabilityKey({ harness: runtime.harness, model: runtime.model, executable }));
+      return held ? {
+        id,
+        harness: runtime.harness,
+        executable,
+        model: runtime.model,
+        version: sourceIdentity?.harnessVersions?.[id] ?? null,
+        capabilities: harnessCapabilities(runtime),
+        requiredCapabilities: {},
+        requiredCapabilitySets: [],
+        ok: false,
+        live: true,
+        liveStatus: "exhausted",
+        availability: { available: false, exhaustedUntil: held.exhaustedUntil, reason: held.reason },
+        detail: `live exhausted · ${held.reason}: refusal recorded on this machine at ${held.observedAt}, back at ${held.exhaustedUntil}`,
+      } : null;
+    });
+    if (refused.some(Boolean)) {
+      return [...routed.entries()].map(([id, { runtime }], index) => refused[index] ?? {
+        id,
+        harness: runtime.harness,
+        executable: getHarness(runtime.harness).executable(runtime),
+        model: runtime.model,
+        version: sourceIdentity?.harnessVersions?.[id] ?? null,
+        capabilities: harnessCapabilities(runtime),
+        requiredCapabilities: {},
+        requiredCapabilitySets: [],
+        ok: true,
+        live: false,
+        liveStatus: "not-asked",
+        detail: "not asked: another routed runtime is refused on this machine",
+      });
+    }
+  }
   if (routed.size > 0 && fresh.size === routed.size) {
     return [...routed.entries()].map(([id, { runtime }]) => {
       const verdict = /** @type {RuntimeAvailability} */ (fresh.get(id));
@@ -594,10 +634,8 @@ async function livePreflightProbes(contract, runDir, sourceIdentity, timeoutSec)
   // under the provider's own identity. Silence and a command that never
   // reached a provider are verdicts of nothing and are never recorded, so the
   // operator who fixes the host is never told the fix "already answered".
-  recordAvailability(
-    probes
-      .filter((probe) => probe.live === true && probe.liveStatus !== "reused" && liveVerdictRecorded(probe))
-      .map((probe) => availabilityKey(probe)),
+  recordProbeVerdicts(
+    probes.filter((probe) => probe.live === true && probe.liveStatus !== "reused" && liveVerdictRecorded(probe)),
     Date.now(),
   );
   return probes;

package/src/engine/runtime-discovery.mjs

@@ -51,9 +51,12 @@ export const DISCOVERY_RUNTIME_DEFINITIONS = Object.freeze({
     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.
   "zcode-glm": {
     harness: "zcode",
-    model: "glm-5.3",
+    model: "glm-5.3-flash",
     vendor: "zhipu",
     config: { "auth_token.env_key": "ZAI_API_KEY" },
     tier: 1,

package/src/harnesses/codex/usage-window.mjs

@@ -0,0 +1,76 @@
+/**
+ * The usage windows a Codex account reports, read from the session file the
+ * CLI writes for every thread. It is separate from the adapter because it is
+ * not part of an invocation's result: `codex exec --json` streams no limits,
+ * while `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*-<thread>.jsonl` carries a
+ * `rate_limits` record on every turn (measured 2026-09-24: `primary` is the
+ * 300-minute window, `secondary` the 10080-minute week, each with
+ * `used_percent` and `resets_at` in epoch seconds).
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** @typedef {{window: string, usedPercent: number, resetsAt: string}} UsageWindow */
+
+/** @param {Record<string, string|undefined>} [env] @returns {string} the account's Codex home */
+export function codexHome(env = process.env) {
+  return env.CODEX_HOME || join(homedir(), ".codex");
+}
+
+/**
+ * The account's windows as the thread's session file last reported them, or
+ * an empty list when the file or the record cannot be found.
+ *
+ * @param {string} threadId
+ * @param {{env?: Record<string, string|undefined>, now?: number}} [options]
+ * @returns {UsageWindow[]}
+ */
+export function codexUsageWindows(threadId, options = {}) {
+  const now = options.now ?? Date.now();
+  const sessions = join(codexHome(options.env), "sessions");
+  for (const day of [0, 1]) {
+    const date = new Date(now - day * 86_400_000);
+    const dir = join(sessions, String(date.getFullYear()), String(date.getMonth() + 1).padStart(2, "0"), String(date.getDate()).padStart(2, "0"));
+    if (!existsSync(dir)) continue;
+    const file = readdirSync(dir).find((name) => name.endsWith(`-${threadId}.jsonl`));
+    if (file) return lastWindows(readFileSync(join(dir, file), "utf8"));
+  }
+  return [];
+}
+
+/** @param {string} text @returns {UsageWindow[]} */
+function lastWindows(text) {
+  const lines = text.split("\n");
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (!lines[index].includes("\"rate_limits\"")) continue;
+    let limits;
+    try {
+      limits = findRateLimits(JSON.parse(lines[index]));
+    } catch {
+      // A line cut by a writer still flushing is skipped; an earlier one answers.
+      continue;
+    }
+    if (!limits) continue;
+    return [["primary", limits.primary], ["secondary", limits.secondary]]
+      .filter(([, entry]) => entry && typeof entry.used_percent === "number" && typeof entry.resets_at === "number")
+      .map(([name, entry]) => ({
+        window: entry.window_minutes === 10080 ? "seven_day" : entry.window_minutes === 300 ? "five_hour" : String(name),
+        usedPercent: entry.used_percent,
+        resetsAt: new Date(entry.resets_at * 1000).toISOString(),
+      }));
+  }
+  return [];
+}
+
+/** @param {unknown} value @returns {any} the first `rate_limits` object anywhere in a record */
+function findRateLimits(value) {
+  if (!value || typeof value !== "object") return null;
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (record.rate_limits && typeof record.rate_limits === "object") return record.rate_limits;
+  for (const child of Object.values(record)) {
+    const found = findRateLimits(child);
+    if (found) return found;
+  }
+  return null;
+}

package/src/harnesses/zcode/index.mjs

@@ -208,7 +208,7 @@ function authToken(runtime) {
  * each one, `doctor` checks binaries), so a permissions or disk failure has to
  * degrade into "not found" — never into an aborted run or a crashed report.
  *
- * @param {{env?: Record<string, string|undefined>, pathDirs?: string[], home?: string, bundle?: {electron: string, cli: string}}} [options]
+ * @param {{env?: Record<string, string|undefined>, pathDirs?: string[], home?: string, bundle?: {electron: string, cli: string}, host?: {arch: string, nodeMajor: number, node: string}}} [options]
  * @returns {void}
  */
 export function ensureZcodeAvailable(options = {}) {
@@ -218,7 +218,7 @@ export function ensureZcodeAvailable(options = {}) {
     if (resolvesOnPath(pathDirs, ZCODE_BIN_NAME)) return;
     const bundle = options.bundle ?? zcodeBundle(env);
     if (!bundle || !existsSync(bundle.electron) || !existsSync(bundle.cli)) return;
-    const body = zcodeShim(bundle);
+    const body = zcodeShim(bundle, options.host);
     for (const dir of shimDirs(options.home ?? homedir())) {
       if (!pathDirs.includes(dir)) continue;
       if (settleShim(join(dir, ZCODE_BIN_NAME), body)) return;
@@ -252,9 +252,23 @@ function zcodeBundle(env) {
  * outlives it.
  *
  * @param {{electron: string, cli: string}} bundle
+ * @param {{arch: string, nodeMajor: number, node: string}} [host]
  * @returns {string}
  */
-function zcodeShim(bundle) {
+function zcodeShim(bundle, host = { arch: process.arch, nodeMajor: Number(process.versions.node.split(".")[0]), node: process.execPath }) {
+  // Measured 2026-09-24 on darwin arm64 with node 26.8.1: the bundled CLI
+  // answers a 3.2 KB response intact under the system node, and every process
+  // it spawns under the app's Electron shows an icon in the macOS Dock. The
+  // Electron path stays for every other host, where the detached-ArrayBuffer
+  // failure (node 24 x64) is the only measurement there is.
+  if (host.arch === "arm64" && host.nodeMajor >= 26) {
+    return `#!/usr/bin/env bash
+set -euo pipefail
+# Written by the faberun zcode harness; the ZCode app owns the CLI path.
+exec ${host.node} \\
+  ${bundle.cli} "$@"
+`;
+  }
   return `#!/usr/bin/env bash
 set -euo pipefail
 # Written by the faberun zcode harness; the ZCode app owns both paths.

package/src/host/preflight.mjs

@@ -43,7 +43,8 @@ import { NOTIFY_SESSION_ENV, sessionWakeNotice } from "../notify/session.mjs";
 import { findExecutable } from "./platform.mjs";
 import { colorLevel, statusToken } from "../cli/brand.mjs";
 import { RUNS_DIR_NAME } from "../run/paths.mjs";
-import { availabilityKey, readAvailability, recordAvailability } from "../run/availability.mjs";
+import { availabilityKey, readAvailability, recordProbeVerdicts } from "../run/availability.mjs";
+import { readUsageWindows, usageAccountOf } from "../run/usage-windows.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 /** @typedef {import("../contract/index.mjs").RuntimeSnapshot} RuntimeSnapshot */
@@ -222,6 +223,35 @@ export function checkRuntimeBinaries(runtimes, harnessVersions, cwd = ".") {
   return pass("runtime binaries", resolved.length ? `${resolved.join(" · ")}${aside}` : "no routed runtime");
 }
 
+/**
+ * How much of each routed account's provider-reported window is spent. A
+ * window at 100% blocks the dispatch until it resets, because every call would
+ * be refused; one at or above 90% is an advisory warning with the reset
+ * instant, so the operator can ration before the wall. The 90% line is a first
+ * guess, not a measurement. No check is added when no routed runtime spends
+ * from an account that reports windows.
+ *
+ * @param {ReachableRuntimes} runtimes
+ * @param {NodeJS.ProcessEnv} env
+ * @param {number} [now]
+ * @returns {EnvCheck[]}
+ */
+export function checkUsageWindows(runtimes, env, now = Date.now()) {
+  const accounts = new Set([...runtimes.values()].filter((entry) => entry.routed).map((entry) => usageAccountOf(entry.runtime, env)).filter((account) => account !== null));
+  /** @type {EnvCheck[]} */
+  const checks = [];
+  for (const account of accounts) {
+    const windows = readUsageWindows(/** @type {string} */ (account), now);
+    if (windows.length === 0) continue;
+    const worst = windows.reduce((a, b) => (b.usedPercent > a.usedPercent ? b : a));
+    const detail = `${account.split(":")[0]} ${windows.map((window) => `${window.window} ${window.usedPercent}% used, resets ${window.resetsAt}`).join(" · ")}`;
+    if (worst.usedPercent >= 100) checks.push(fail("usage window", `${detail}: every call would be refused until ${worst.resetsAt}`));
+    else if (worst.usedPercent >= 90) checks.push(fail("usage window", detail, true));
+    else checks.push(pass("usage window", detail));
+  }
+  return checks;
+}
+
 /**
  * @param {{cwd: string, runtimes: ReachableRuntimes, harnessVersions?: Record<string, string|null>, env?: NodeJS.ProcessEnv}} options
  * @returns {EnvReport}
@@ -234,6 +264,7 @@ export function environmentPreflight(options) {
     checkGit(cwd),
     checkWorktree(cwd, env.FABERUN_REQUIRE_CLEAN_WORKTREE === "1"),
     checkRuntimeBinaries(options.runtimes, options.harnessVersions ?? {}, cwd),
+    ...checkUsageWindows(options.runtimes, env),
   ];
   return { schemaVersion: ENV_PREFLIGHT_SCHEMA_VERSION, ok: checks.every((check) => check.ok || check.advisory), checks };
 }
@@ -517,7 +548,7 @@ async function liveAvailabilityChecks(contractPath, runtimes) {
   const override = Number(process.env.FABERUN_PREFLIGHT_TIMEOUT_SEC);
   const timeoutSec = process.env.FABERUN_PREFLIGHT_TIMEOUT_SEC !== undefined && Number.isFinite(override) && override > 0 ? override : 60;
   const probes = await preflightContract(contractPath, { liveTimeoutSec: timeoutSec });
-  recordAvailability(probes.filter((probe) => liveVerdict(probe).recorded).map((probe) => availabilityKey(probe)));
+  recordProbeVerdicts(probes.filter((probe) => liveVerdict(probe).recorded));
   return probes.map((probe) => {
     const verdict = liveVerdict(probe);
     return {

package/src/plan/pipeline.mjs

@@ -24,7 +24,7 @@ import { campaignCli } from "../cli/campaign.mjs";
 import { appendJsonl, writeJsonAtomic } from "../run/store.mjs";
 import { stableJson } from "../util.mjs";
 import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
-import { askPlanningRuntimes, refusePlanningSilence } from "./preflight.mjs";
+import { askPlanningRuntimes, refusePlanningSilence, refuseUnplannableRuntimes } from "./preflight.mjs";
 import { parseSpec, validateSpec } from "./spec.mjs";
 import { collectRepoFacts } from "./repo-facts.mjs";
 import { RISK_TIERS, TASK_KIND_CATALOGUE_FILE, buildPlanningContract, renderTaskKindCatalogue, validateFindings, validatePlanOutput } from "./template.mjs";
@@ -111,6 +111,7 @@ export async function runPlanningPipeline(options) {
   const campaignPath = campaignTree(cwd, campaignId);
   const campaign = readCampaign(campaignPath);
   if (campaign.status !== "active") throw new Error(`campaign is closed: ${campaignId}`);
+  refuseUnplannableRuntimes(runtimes, runtimeDefaults, packageMode);
   refusePlanningSilence(await ask(runtimes, runtimeDefaults, cwd), cwd);
 
   const relativeSpecPath = repoRelativePath(cwd, specPath, "specPath");

package/src/plan/preflight.mjs

@@ -9,7 +9,7 @@
 import { preflightRuntimes } from "../engine/live-preflight.mjs";
 import { liveSilenceCause } from "../engine/live-silence.mjs";
 import { harnessCapabilities } from "../harnesses/index.mjs";
-import { validateRuntime } from "../contract/runtime.mjs";
+import { assertRuntimeExecutesCommands, validateRuntime } from "../contract/runtime.mjs";
 
 /**
  * The runtimes a planning run will spend, asked once before its first stage.
@@ -75,3 +75,44 @@ export function refusePlanningSilence(checks, cwd) {
     { code: "env_preflight_failed" },
   );
 }
+
+/**
+ * Refuse, before anything is spent, a runtime choice no frozen contract could
+ * carry. Both halves were measured on 2026-09-24 in `choose-the-judges` R5,
+ * where each surfaced only at freeze, after four rounds: a worker whose
+ * permission mode cannot run commands cannot carry an implementation node's
+ * verification (US$ 7.64 and an hour, contested), and a judge that shares the
+ * worker's vendor, or the vendor of any runtime its fallback reaches, is
+ * refused by the vendor rule on every frozen node (`runtime_routing_unmet` in
+ * all four rounds). The pipeline's defaults name both roles, so both are
+ * decidable here.
+ *
+ * @param {Record<string, Record<string, unknown>>} runtimes
+ * @param {{worker?: string, judge?: string}} runtimeDefaults
+ * @param {"implementation"|"exploratory"} packageMode
+ * @returns {void}
+ */
+export function refuseUnplannableRuntimes(runtimes, runtimeDefaults, packageMode) {
+  const worker = runtimeDefaults.worker;
+  if (!worker || !runtimes[worker]) return;
+  if (packageMode === "implementation") {
+    try {
+      assertRuntimeExecutesCommands(/** @type {any} */ (runtimes), worker, 0, "every implementation node", "worker runtime");
+    } catch (error) {
+      throw new Error(`--runtime-defaults worker=${worker} cannot run the verification an implementation plan carries: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const judge = runtimeDefaults.judge;
+  if (!judge || !runtimes[judge]) return;
+  /** @type {Set<string>} */
+  const vendors = new Set();
+  const seen = new Set();
+  for (let id = /** @type {string|undefined} */ (worker); id && runtimes[id] && !seen.has(id); id = /** @type {string|undefined} */ (runtimes[id].fallback)) {
+    seen.add(id);
+    if (typeof runtimes[id].vendor === "string") vendors.add(/** @type {string} */ (runtimes[id].vendor));
+  }
+  const judgeVendor = runtimes[judge].vendor;
+  if (typeof judgeVendor === "string" && vendors.has(judgeVendor)) {
+    throw new Error(`--runtime-defaults judge=${judge} shares vendor ${judgeVendor} with worker ${worker} or its fallback, so no frozen node could route its judge; name a judge of another vendor`);
+  }
+}

package/src/repo/worktree.mjs

@@ -1,8 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { gitArguments } from "../host/platform.mjs";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { RUNS_DIR_NAME, attemptWorktreePath, candidateWorktreePath } from "../run/paths.mjs";
+import { RUNS_DIR_NAME, attemptWorktreePath, candidateWorktreePath, worktreeRoot } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
 
@@ -481,3 +481,50 @@ export function attemptWorkspace(state) {
   const path = state?.worktree?.path;
   return path && state?.worktree?.status !== "removed" && existsSync(path) ? path : null;
 }
+
+/**
+ * Release every attempt worktree a finished run left behind, keeping what it
+ * held. Measured 2026-09-24: attempts that were never accepted (a failed or
+ * blocked try, the first of two, a discovery node) kept their worktree and
+ * branch forever, and one machine held 41 registered and 42 orphaned
+ * worktrees (909 MB) from campaigns long closed. Each worktree's HEAD, and its
+ * uncommitted delta when it has one (`git stash create`, which touches no
+ * file), is kept under `refs/faberun-archive/<run>/<attempt>` before the
+ * worktree and its branch go, so removal loses nothing git can hold.
+ *
+ * @param {string} repo
+ * @param {string} runDir
+ * @param {string} runId
+ * @returns {{removed: number, archived: string[]}}
+ */
+export function releaseRunWorktrees(repo, runDir, runId) {
+  const root = worktreeRoot(runDir, runId);
+  if (!existsSync(root)) return { removed: 0, archived: [] };
+  /** @type {string[]} */
+  const archived = [];
+  let removed = 0;
+  for (const entry of readdirSync(root)) {
+    const path = join(root, entry);
+    /** @param {string[]} args @returns {string} */
+    const inTree = (args) => {
+      try {
+        return git(path, args);
+      } catch {
+        // An orphaned directory git no longer knows answers nothing; it is removed below all the same.
+        return "";
+      }
+    };
+    const branch = inTree(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    const keep = inTree(["stash", "create"]) || inTree(["rev-parse", "HEAD"]);
+    if (keep) {
+      const ref = `refs/faberun-archive/${runId}/${entry}`;
+      runGit(["-C", repo, "update-ref", ref, keep]);
+      archived.push(ref);
+    }
+    removeWorktree(repo, path);
+    if (branch) deleteRef(repo, `refs/heads/${branch}`);
+    removed += 1;
+  }
+  rmSync(root, { recursive: true, force: true });
+  return { removed, archived };
+}

package/src/run/availability.mjs

@@ -25,6 +25,16 @@ import { writeJsonAtomic } from "./store.mjs";
 
 /** @typedef {import("../engine/runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
 
+/**
+ * Answers a provider gives before doing any work that no retry inside their
+ * window can change. Measured 2026-09-24: a probe answered
+ * `quota_exhausted` was stored as "answered", the next launches reused it
+ * without asking, and six processes spent into two exhausted accounts.
+ */
+const REFUSAL_REASONS = new Set(["quota_exhausted", "insufficient_balance", "model_not_supported"]);
+/** How long a refusal that names no reset instant is held. A first guess, not a measurement. */
+const REFUSAL_HOLD_MS = 15 * 60 * 1000;
+
 /** The store shape this module reads and writes; a foreign shape reads as empty. */
 const STORE_SCHEMA_VERSION = 1;
 
@@ -96,6 +106,69 @@ export function recordAvailability(keys, now = Date.now()) {
   writeJsonAtomic(path, store);
 }
 
+/**
+ * The refusal a probe or a provider envelope's classified availability
+ * carries, or null when it is anything else.
+ *
+ * @param {{available?: boolean, exhaustedUntil?: string|null, reason?: string}|null|undefined} availability
+ * @returns {{reason: string, exhaustedUntil: string|null}|null}
+ */
+export function refusalOfAvailability(availability) {
+  if (!availability || availability.available !== false || !REFUSAL_REASONS.has(String(availability.reason))) return null;
+  return { reason: String(availability.reason), exhaustedUntil: availability.exhaustedUntil ?? null };
+}
+
+/**
+ * Record that a provider refused the work, so every process on this machine
+ * knows until the reset: the launch gate asks again instead of reusing an old
+ * answer, and a class that spends one call per case stops before its next.
+ *
+ * @param {string} key
+ * @param {{reason: string, exhaustedUntil: string|null}} refusal
+ * @param {number} [now]
+ * @returns {void}
+ */
+export function recordRefusal(key, refusal, now = Date.now()) {
+  const store = loadStore();
+  store.verdicts[key] = {
+    available: false,
+    exhaustedUntil: refusal.exhaustedUntil ?? new Date(now + REFUSAL_HOLD_MS).toISOString(),
+    reason: refusal.reason,
+    observedAt: new Date(now).toISOString(),
+    window: PREFLIGHT_WINDOW,
+  };
+  const path = availabilityPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeJsonAtomic(path, store);
+}
+
+/**
+ * The refusal recorded for a provider that has not yet reset, or null.
+ *
+ * @param {string} key
+ * @param {number} [now]
+ * @returns {RuntimeAvailability|null}
+ */
+export function readRefusal(key, now = Date.now()) {
+  const record = loadVerdicts()[key];
+  if (!record || record.available !== false || !record.exhaustedUntil) return null;
+  return Date.parse(record.exhaustedUntil) > now ? record : null;
+}
+
+/**
+ * Record what a set of live probes learned: an answer as an answer, a refusal
+ * as a refusal until its reset.
+ *
+ * @param {{harness: string, model: string, executable: string, availability?: {available: boolean, exhaustedUntil: string|null, reason: string}}[]} probes
+ * @param {number} [now]
+ * @returns {void}
+ */
+export function recordProbeVerdicts(probes, now = Date.now()) {
+  const refused = probes.filter((probe) => refusalOfAvailability(probe.availability));
+  recordAvailability(probes.filter((probe) => !refused.includes(probe)).map((probe) => availabilityKey(probe)), now);
+  for (const probe of refused) recordRefusal(availabilityKey(probe), /** @type {{reason: string, exhaustedUntil: string|null}} */ (refusalOfAvailability(probe.availability)), now);
+}
+
 /**
  * @returns {{schemaVersion: number, verdicts: Record<string, RuntimeAvailability>}}
  */

package/src/run/paths.mjs

@@ -147,6 +147,11 @@ export function availabilityPath() {
   return join(faberunHome(), "availability.json");
 }
 
+/** @returns {string} the machine-wide record of each account's provider-reported usage windows */
+export function usageWindowsPath() {
+  return join(faberunHome(), "usage-windows.json");
+}
+
 /**
  * The campaigns directory beneath a runs root: `<runs>/campaigns`.
  * Composes `campaign/layout.mjs`'s `campaignsDir`, which owns the shape given
@@ -173,7 +178,7 @@ export function campaignTree(cwd, campaignId) {
 }
 
 /** @param {string} runDir @param {string} runId @returns {string} */
-function worktreeRoot(runDir, runId) {
+export function worktreeRoot(runDir, runId) {
   return join(dirname(runDir), "worktrees", runId);
 }
 

package/src/run/usage-windows.mjs

@@ -0,0 +1,82 @@
+/**
+ * The machine-wide record of how much of each account's provider-reported
+ * usage window is spent. It is separate from the availability store because
+ * it answers a different question: availability says whether a provider
+ * answered, this says how close the account is to refusing. Measured
+ * 2026-09-24: the Codex week went from 86% to 94% in one afternoon of judge
+ * readings, and nothing read it until the owner looked.
+ */
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { usageWindowsPath } from "./paths.mjs";
+import { writeJsonAtomic } from "./store.mjs";
+import { codexHome, codexUsageWindows } from "../harnesses/codex/usage-window.mjs";
+
+/** @typedef {import("../harnesses/codex/usage-window.mjs").UsageWindow} UsageWindow */
+/** @typedef {{windows: UsageWindow[], observedAt: string}} AccountWindows */
+
+/**
+ * @param {string} account the account key, e.g. `codex:<CODEX_HOME>`
+ * @param {UsageWindow[]} windows
+ * @param {number} [now]
+ * @returns {void}
+ */
+export function recordUsageWindows(account, windows, now = Date.now()) {
+  if (windows.length === 0) return;
+  const store = loadStore();
+  store.accounts[account] = { windows, observedAt: new Date(now).toISOString() };
+  const path = usageWindowsPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeJsonAtomic(path, store);
+}
+
+/**
+ * The account's windows that have not reset yet, or an empty list.
+ *
+ * @param {string} account
+ * @param {number} [now]
+ * @returns {UsageWindow[]}
+ */
+export function readUsageWindows(account, now = Date.now()) {
+  const record = loadStore().accounts[account];
+  if (!record || !Array.isArray(record.windows)) return [];
+  return record.windows.filter((window) => typeof window.usedPercent === "number" && Date.parse(window.resetsAt) > now);
+}
+
+/** @returns {{schemaVersion: number, accounts: Record<string, AccountWindows>}} */
+function loadStore() {
+  try {
+    const parsed = JSON.parse(readFileSync(usageWindowsPath(), "utf8"));
+    if (parsed && parsed.schemaVersion === 1 && parsed.accounts && typeof parsed.accounts === "object") return parsed;
+  } catch {
+    // ENOENT on a machine that never recorded a window, or a store a truncated
+    // write left unreadable: either way nothing is known, which reads as no warning.
+  }
+  return { schemaVersion: 1, accounts: {} };
+}
+
+/**
+ * The account a runtime spends from, when its provider reports windows; null
+ * for every harness that reports none (only Codex is measured to).
+ *
+ * @param {{harness: string}} runtime
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function usageAccountOf(runtime, env = process.env) {
+  return runtime.harness === "codex" ? `codex:${codexHome(env)}` : null;
+}
+
+/**
+ * Record what a finished invocation's provider reported about its account.
+ *
+ * @param {{harness: string}} runtime
+ * @param {string|null|undefined} continuationId the provider's thread id
+ * @param {{env?: Record<string, string|undefined>, now?: number}} [options]
+ * @returns {void}
+ */
+export function recordInvocationWindows(runtime, continuationId, options = {}) {
+  const account = usageAccountOf(runtime, options.env);
+  if (!account || !continuationId) return;
+  recordUsageWindows(account, codexUsageWindows(continuationId, options), options.now);
+}

package/src/run/usage.mjs

@@ -16,6 +16,7 @@ import { priceUsage } from "../engine/process.mjs";
 import { readBoundedTail, sessionLedger } from "../engine/transcript.mjs";
 import { writeNode } from "../engine/state.mjs";
 import { harnessCapabilities, normalizeProviderResult } from "../harnesses/index.mjs";
+import { recordInvocationWindows } from "./usage-windows.mjs";
 
 // `priceUsage` is defined beside `invocationResult`, the second source point,
 // and re-exported here so the ledger's public surface is unchanged. This module
@@ -88,6 +89,12 @@ export function recordInvocationUsage(job, options = {}) {
   // Price only after the backfill has run: the counters this function persists
   // and returns are the ones the price is derived from, and the envelope becomes
   // the single priced object every later copy spreads from.
+  try {
+    recordInvocationWindows(job.runtime, envelope.continuationId);
+  } catch {
+    // The window record is telemetry about the account, never a reason to fail
+    // the invocation it rode on: a missing or unreadable session file means no reading.
+  }
   const priced = priceUsage(job.runtime, envelope.usage, envelope.costUsd);
   envelope = { ...envelope, costUsd: priced.costUsd, costProvenance: priced.costProvenance };
   // The per-request ledger is read here, with the usage, for the same reason