faberun 0.23.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "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": {
@@ -24,7 +24,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "check": "node -e \"const{readdirSync}=require('node:fs');const{spawnSync}=require('node:child_process');const roots=['bin','.claude/hooks','src','evals','test'];const files=roots.flatMap(r=>readdirSync(r,{recursive:true}).map(String).filter(p=>p.endsWith('.mjs')).map(p=>r+'/'+p));for(const f of files)if(spawnSync(process.execPath,['--check',f],{stdio:'inherit'}).status!==0)process.exit(1);console.log(files.length+' files checked')\"",
+    "check": "node -e \"const{readdirSync}=require('node:fs');const{spawnSync}=require('node:child_process');const roots=['bin','.claude/hooks','src','evals','test'];const files=roots.flatMap(r=>readdirSync(r,{recursive:true}).map(String).filter(p=>p.endsWith('.mjs')&&!p.includes('.runs')).map(p=>r+'/'+p));for(const f of files)if(spawnSync(process.execPath,['--check',f],{stdio:'inherit'}).status!==0)process.exit(1);console.log(files.length+' files checked')\"",
     "typecheck": "tsc",
     "check:campaign-brief-render": "node src/report/campaign-brief-html.mjs",
     "test": "node --test --import ./test/scoped-home.mjs --import ./test/git-env.mjs --import ./test/setup.mjs test/*.test.mjs test/*/*.test.mjs",

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": [

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/campaign/metrics.mjs

@@ -51,6 +51,7 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
 /** @typedef {"down"|"up"|"informative"} Direction */
 /** @typedef {{value: number|null, direction: Direction, count: number, numerator?: number, denominator?: number, excludedRunIds?: string[], missingSources?: string[]}} Indicator */
 /** @typedef {Indicator & {unknownCount: number, unknownCountByReason: Record<string, number>, unknownFractionByReason: Record<string, number>}} CostIndicator */
+/** @typedef {Indicator & {unknownCount: number}} JudgeCostShareIndicator */
 /** @typedef {{value: Record<string, number>|null, direction: Direction, count: number, numerator?: Record<string, number>, denominator?: Record<string, number>, excludedRunIds?: string[], missingSources?: string[]}} GroupedIndicator */
 /** @typedef {{atMs: number, index: number, event: JsonObject}} RunEvent */
 /** @typedef {{runId: string, id: string, status: string, attempt?: number|null, revisions?: number|null, review?: string|null}} RunNode */
@@ -79,6 +80,8 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
  *   usageTokensByKind: GroupedIndicator,
  *   usageTokensByKindByRuntime: GroupedIndicator,
  *   usageCostUsd: CostIndicator,
+ *   judgeFindingRate: Indicator,
+ *   judgeCostShare: JudgeCostShareIndicator,
  *   blockingJudgeFirstPassRate: GroupedIndicator,
  *   notifyReceiptRate: Indicator,
  *   silentStallRate: Indicator,
@@ -101,6 +104,10 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
   const excluded = excludedRunIdsFor(campaign, excludedRunIds);
   const eligibleNodes = nodes.filter((node) => !excluded.includes(node.runId));
   const eligibleEvents = eventList.filter((event) => typeof event.runId !== "string" || !excluded.includes(event.runId));
+  const eligibleUsageRecords = usageRecords.filter((record) => {
+    const object = jsonObjectOf(record);
+    return object === null || typeof object.runId !== "string" || !excluded.includes(object.runId);
+  });
   const eligibleNotifications = notifications.filter((record) => {
     const object = jsonObjectOf(record);
     return object === null || typeof object.runId !== "string" || !excluded.includes(object.runId);
@@ -110,6 +117,7 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
   const closedCheckpoints = closedCheckpointsOf(nodes);
   const span = eventSpanOf(eventList);
   const usage = usageTotalsOf(usageRecords);
+  const judgeYield = judgeYieldOf(eligibleEvents, eligibleUsageRecords);
   const gates = blockingJudgeFirstPassRateOf(eligibleNodes, eligibleEvents);
   const notify = notifyReceiptRateOf(eligibleNotifications);
   const stalls = silentStallRateOf(eligibleNodes, eligibleEvents);
@@ -129,6 +137,11 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
       unknownCountByReason: usage.unknownCountByReason,
       unknownFractionByReason: usage.unknownFractionByReason,
     },
+    judgeFindingRate: rate("up", judgeYield.findings, judgeYield.judged, excluded),
+    judgeCostShare: {
+      ...measured("down", usage.costCount, usage.costUsd === null ? null : usage.judgeCostUsd / usage.costUsd),
+      unknownCount: usage.unknownJudgeCount,
+    },
     blockingJudgeFirstPassRate: groupedRate("up", gates, excluded),
     notifyReceiptRate: rate("up", notify.satisfied, notify.count, excluded),
     silentStallRate: rate("down", stalls.stalled, stalls.activeHours, excluded, stalls.activeIntervals),
@@ -162,6 +175,8 @@ function applyMissingSources(metrics, missingSources) {
     usageTokensByKind: withMissing(metrics.usageTokensByKind, ["usage.jsonl"]),
     usageTokensByKindByRuntime: withMissing(metrics.usageTokensByKindByRuntime, ["usage.jsonl"]),
     usageCostUsd: withMissing(metrics.usageCostUsd, ["usage.jsonl"]),
+    judgeFindingRate: withMissing(metrics.judgeFindingRate, ["events.jsonl", "usage.jsonl"]),
+    judgeCostShare: withMissing(metrics.judgeCostShare, ["usage.jsonl"]),
     blockingJudgeFirstPassRate: withMissing(metrics.blockingJudgeFirstPassRate, ["nodes.json", "events.jsonl"]),
     notifyReceiptRate: withMissing(metrics.notifyReceiptRate, ["notify.jsonl"]),
     silentStallRate: withMissing(metrics.silentStallRate, ["nodes.json", "events.jsonl"]),
@@ -397,7 +412,7 @@ function eventSpanOf(events) {
  * invocation is counted separately rather than folded into a measured zero.
  *
  * @param {unknown[]} usageRecords
- * @returns {{tokensByKind: Record<string, number>, tokensByKindByRuntime: Record<string, number>, tokenCount: number, costUsd: number|null, costCount: number, unknownCount: number, unknownCountByReason: Record<string, number>, unknownFractionByReason: Record<string, number>}}
+ * @returns {{tokensByKind: Record<string, number>, tokensByKindByRuntime: Record<string, number>, tokenCount: number, costUsd: number|null, judgeCostUsd: number, costCount: number, unknownCount: number, unknownJudgeCount: number, unknownCountByReason: Record<string, number>, unknownFractionByReason: Record<string, number>}}
  */
 function usageTotalsOf(usageRecords) {
   const tokensByKind = { inputTokens: 0, cacheReadInputTokens: 0, outputTokens: 0 };
@@ -405,8 +420,10 @@ function usageTotalsOf(usageRecords) {
   const tokensByKindByRuntime = {};
   let tokenCount = 0;
   let costUsd = 0;
+  let judgeCostUsd = 0;
   let costCount = 0;
   let unknownCount = 0;
+  let unknownJudgeCount = 0;
   /** @type {Record<string, number>} */
   const unknownCountByReason = {};
   const kinds = /** @type {("inputTokens"|"cacheReadInputTokens"|"outputTokens")[]} */ (["inputTokens", "cacheReadInputTokens", "outputTokens"]);
@@ -425,9 +442,11 @@ function usageTotalsOf(usageRecords) {
     if (measuredAny) tokenCount += 1;
     if (typeof record.costUsd === "number" && Number.isFinite(record.costUsd) && record.costProvenance !== UNKNOWN_COST_PROVENANCE) {
       costUsd += record.costUsd;
+      if (record.role === "judge") judgeCostUsd += record.costUsd;
       costCount += 1;
     } else {
       unknownCount += 1;
+      if (record.role === "judge") unknownJudgeCount += 1;
       const reason = typeof record.unknownReason === "string" && UNKNOWN_COST_REASONS.includes(record.unknownReason)
         ? record.unknownReason
         : "legacy";
@@ -443,13 +462,51 @@ function usageTotalsOf(usageRecords) {
     tokensByKindByRuntime,
     tokenCount,
     costUsd: costCount === 0 ? null : costUsd,
+    judgeCostUsd,
     costCount,
     unknownCount,
+    unknownJudgeCount,
     unknownCountByReason,
     unknownFractionByReason,
   };
 }
 
+/**
+ * Count logical nodes that reached a judge and those whose judge recorded at
+ * least one finding. A failed judge verdict is the durable ledger projection
+ * of a non-empty findings array; a complete-phase fail is included for
+ * advisory reviews that settle the node after reporting their finding.
+ *
+ * @param {JsonObject[]} events
+ * @param {unknown[]} usageRecords
+ * @returns {{judged: number, findings: number}}
+ */
+function judgeYieldOf(events, usageRecords) {
+  const judged = new Set();
+  const findings = new Set();
+  for (const raw of usageRecords) {
+    const record = jsonObjectOf(raw);
+    if (record === null || record.role !== "judge" || typeof record.nodeId !== "string") continue;
+    judged.add(logicalNodeKey(record.runId, record.nodeId));
+  }
+  for (const event of events) {
+    if (typeof event.node !== "string") continue;
+    const key = logicalNodeKey(event.runId, event.node);
+    if (event.phase === "judge") judged.add(key);
+    const hasFindingArray = Array.isArray(event.findings) && event.findings.length > 0;
+    if ((event.phase === "judge" || event.phase === "complete") && (event.verdict === "fail" || hasFindingArray)) {
+      judged.add(key);
+      findings.add(key);
+    }
+  }
+  return { judged: judged.size, findings: findings.size };
+}
+
+/** @param {unknown} runId @param {string} nodeId @returns {string} */
+function logicalNodeKey(runId, nodeId) {
+  return `${typeof runId === "string" ? runId : ""}:${nodeId}`;
+}
+
 /**
  * Fraction of blocking-gated checkpoints whose first recorded verdict passed,
  * per lane (the judge runtime that produced it). A node under `advisory` or

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/cli/contract.mjs

@@ -6,6 +6,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { parseArgs as parseFlags } from "node:util";
 import { loadPersistedContract, validateContract } from "../contract/index.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -13,7 +14,7 @@ import { loadPersistedContract, validateContract } from "../contract/index.mjs";
 /** Flags are scoped to the operation that declares them; all others are rejected. */
 /** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
 const OPERATION_OPTIONS = {
-  validate: {},
+  validate: { "strict-traceability": { type: "boolean" } },
 };
 
 /**
@@ -23,9 +24,17 @@ const OPERATION_OPTIONS = {
 export function contractCli(args) {
   const operation = args[0];
   if (!operation || !Object.hasOwn(OPERATION_OPTIONS, operation)) return usage();
-  const target = args[1];
-  if (!target || args.length > 2) return usage();
-  if (operation === "validate") validateContractFile(resolve(target));
+  let parsed;
+  try {
+    parsed = parseFlags({ args: args.slice(1), options: OPERATION_OPTIONS[operation], allowPositionals: true, strict: true });
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return usage();
+  }
+  const target = parsed.positionals[0];
+  if (!target || parsed.positionals.length > 1) return usage();
+  const values = /** @type {{"strict-traceability"?: boolean}} */ (parsed.values);
+  if (operation === "validate") validateContractFile(resolve(target), { strictTraceability: values["strict-traceability"] === true });
 }
 
 /**
@@ -38,19 +47,29 @@ export function contractCli(args) {
  * authoring validation, tree reads included.
  *
  * @param {string} path
+ * @param {{strictTraceability?: boolean}} [options]
  * @returns {ValidatedContract}
  */
-export function validateContractFile(path) {
+export function validateContractFile(path, { strictTraceability = false } = {}) {
   const runJsonPath = join(dirname(path), "run.json");
   const contract = existsSync(runJsonPath)
     ? loadPersistedContract(path, readRunDigest(runJsonPath))
     : validateContract(JSON.parse(readFileSync(path, "utf8")), path);
   const count = contract.warnings.length;
-  process.stdout.write(`valid${count ? ` (${count} warning${count === 1 ? "" : "s"})` : ""}\n`);
+  const blockingTraceability = strictTraceability
+    ? contract.warnings.filter((warning) => isTraceabilityFinding(warning))
+    : [];
+  process.stdout.write(`${blockingTraceability.length > 0 ? "invalid" : "valid"}${count ? ` (${count} warning${count === 1 ? "" : "s"})` : ""}\n`);
   for (const warning of contract.warnings) process.stdout.write(`[warn] ${warning}\n`);
+  if (blockingTraceability.length > 0) process.exitCode = 1;
   return contract;
 }
 
+/** @param {string} warning @returns {boolean} */
+function isTraceabilityFinding(warning) {
+  return warning.includes("judgment_without_reason") || warning.includes("judgment_beside_mechanical_proof");
+}
+
 /**
  * @param {string} runJsonPath
  * @returns {string|undefined}
@@ -62,7 +81,7 @@ function readRunDigest(runJsonPath) {
 
 /** @returns {void} */
 function usage() {
-  process.stderr.write("usage: faberun contract validate <contract.json>\n");
+  process.stderr.write("usage: faberun contract validate <contract.json> [--strict-traceability]\n");
   process.exitCode = 2;
 }
 

package/src/contract/definition-of-done.mjs

@@ -9,7 +9,7 @@ import { rejectUnknown, requireId, requireString } from "./assert.mjs";
 
 /** @typedef {{kind: "command"|"path"|"verification", ref: string}} DefinitionOfDoneProof */
 
-/** @typedef {{id: string, text: string, proof?: DefinitionOfDoneProof, judgment?: true}} DefinitionOfDoneItem */
+/** @typedef {{id: string, text: string, proof?: DefinitionOfDoneProof, judgment?: true, reason?: string}} DefinitionOfDoneItem */
 
 /**
  * @param {unknown} value
@@ -28,12 +28,16 @@ export function validateDefinitionOfDone(value, label, options = {}) {
       throw new TypeError(`${itemLabel} must be an object with id, text, and proof or judgment: true`);
     }
     const record = /** @type {Record<string, unknown>} */ (item);
-    rejectUnknown(record, new Set(["id", "text", "proof", "judgment"]), itemLabel);
+    rejectUnknown(record, new Set(["id", "text", "proof", "judgment", "reason"]), itemLabel);
     requireId(record.id, `${itemLabel}.id`);
     requireString(record.text, `${itemLabel}.text`);
     if (record.judgment !== undefined && record.judgment !== true) {
       throw new TypeError(`${itemLabel}.judgment must be true when present`);
     }
+    if (record.reason !== undefined) {
+      if (record.judgment !== true) throw new TypeError(`${itemLabel}.reason requires judgment: true`);
+      requireString(record.reason, `${itemLabel}.reason`);
+    }
     const proof = record.proof === undefined
       ? undefined
       : validateProof(record.proof, `${itemLabel}.proof`, options);
@@ -45,10 +49,34 @@ export function validateDefinitionOfDone(value, label, options = {}) {
       text: /** @type {string} */ (record.text),
       ...(proof === undefined ? {} : { proof }),
       ...(record.judgment === true ? { judgment: true } : {}),
+      ...(record.reason === undefined ? {} : { reason: /** @type {string} */ (record.reason) }),
     };
   });
 }
 
+/**
+ * Report judgment items that do not explain what mechanical verification cannot
+ * observe. These remain advisory because `contract validate` has no strict
+ * traceability flag; a later strict contract command can promote these codes.
+ *
+ * @param {DefinitionOfDoneItem[]} items
+ * @param {number} index
+ * @returns {string[]}
+ */
+export function judgmentReasonWarnings(items, index) {
+  const judgmentItems = items.filter((item) => item.judgment === true);
+  const warnings = items.flatMap((item, itemIndex) => item.judgment === true && item.reason === undefined
+    ? [`nodes[${index}] (definitionOfDone[${itemIndex}]): judgment_without_reason: judgment item must say what no command verifies`]
+    : []);
+  const hasMechanicalProof = items.some((item) => item.proof !== undefined);
+  if (judgmentItems.length > 0 && hasMechanicalProof && judgmentItems.every((item) => item.reason === undefined)) {
+    warnings.push(
+      `nodes[${index}]: judgment_beside_mechanical_proof: every judgment item shares this node with mechanical-proof items but declares no reason`,
+    );
+  }
+  return warnings;
+}
+
 /**
  * @param {unknown} value
  * @param {string} label
@@ -144,4 +172,3 @@ export function unquotedFilterValueWarnings(items, index) {
 
 /** The node:test filter flags a `kind: "command"` proof's shell can split on an unquoted value. */
 const TEST_FILTER_FLAGS = ["--test-name-pattern", "--test-skip-pattern"];
-

package/src/contract/index.mjs

@@ -3,7 +3,7 @@ import { readFileSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { loadTaskPacket, renderWorkerPrompt } from "./task-packet.mjs";
 import { RESERVED_ARTICLES } from "./articles.mjs";
-import { unquotedFilterValueWarnings, validateDefinitionOfDone } from "./definition-of-done.mjs";
+import { judgmentReasonWarnings, unquotedFilterValueWarnings, validateDefinitionOfDone } from "./definition-of-done.mjs";
 import { validateFinalVerification, validateSharedVerification } from "./final-verification.mjs";
 import { VERIFICATION_LIMITS, requirementProofWarnings } from "./verification.mjs";
 import {
@@ -378,6 +378,7 @@ export function validateContract(raw, contractPath, options = {}) {
     ...nodes.flatMap((node, index) => [
       ...commandCoverageWarnings(node, index),
       ...unquotedFilterValueWarnings(node.definitionOfDone ?? [], index),
+      ...judgmentReasonWarnings(node.definitionOfDone ?? [], index),
       ...(persisted ? [] : mirrorCoverageWarnings(node, index, cwd, contractCommands, contractWrites)),
       ...(persisted ? [] : unsnapshottedWriteWarnings(node, index, cwd)),
       ...(persisted ? [] : ignoreSourceWriteWarnings(node, index)),

package/src/engine/lifecycle.mjs

@@ -33,6 +33,8 @@ 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";
@@ -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) {

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/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/plan/proof-run.mjs

@@ -25,6 +25,13 @@ import { NOTIFY_SESSION_ENV } from "../notify/session.mjs";
 /** @typedef {{requirementId: string|null, kind: "command"|"path", ref: string, pass: boolean, detail: string}} RequirementProofResult */
 
 export const MEASURE_TIMEOUT_MS = 30_000;
+/**
+ * A proof is a test run, not a fact probe. Measured 2026-09-24: R6 of
+ * `evals-with-a-budget` takes 98 s pinned to its file, and under the 30 s fact
+ * bound the runner died on SIGTERM with exit 1, read as a failing proof. Ten
+ * minutes has no measurement behind it beyond covering the slowest proof seen.
+ */
+const PROOF_TIMEOUT_MS = 600_000;
 export const MEASURE_OUTPUT_CAP_BYTES = 4096;
 
 /** How much of a failing proof's own output a finding carries: enough to name the failure, never the whole log. */
@@ -82,9 +89,10 @@ export function runShellCapture(cwd, command, probes = {}) {
  * @param {string} cwd
  * @param {string} command
  * @param {MeasureProbes} [probes]
- * @returns {{output: string, exitCode: number|null, truncated: boolean}}
+ * @param {number} [timeoutMs]
+ * @returns {{output: string, exitCode: number|null, truncated: boolean, timedOut: boolean}}
  */
-function runShellFull(cwd, command, probes = {}) {
+function runShellFull(cwd, command, probes = {}, timeoutMs = MEASURE_TIMEOUT_MS) {
   const run = probes.run ?? spawnSync;
   const env = { ...process.env };
   for (const key of MEASURE_SIDE_EFFECT_ENV_KEYS) delete env[key];
@@ -92,9 +100,10 @@ function runShellFull(cwd, command, probes = {}) {
   // child and prints no result at all (measured 2026-09-21, AGENTS.md), so a
   // proof run from inside a test runner would have nothing to show.
   delete env.NODE_TEST_CONTEXT;
-  const result = run(command, { shell: true, cwd, timeout: MEASURE_TIMEOUT_MS, encoding: "utf8", env });
+  const result = run(command, { shell: true, cwd, timeout: timeoutMs, encoding: "utf8", env });
   const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-  return { output: combined, exitCode: result.status, truncated: Buffer.byteLength(combined, "utf8") > MEASURE_OUTPUT_CAP_BYTES };
+  const timedOut = /** @type {NodeJS.ErrnoException|undefined} */ (result.error)?.code === "ETIMEDOUT";
+  return { output: combined, exitCode: result.status, truncated: Buffer.byteLength(combined, "utf8") > MEASURE_OUTPUT_CAP_BYTES, timedOut };
 }
 
 /** `--test-name-pattern` in a shell command, quoted or bare, `=` or space. */
@@ -146,9 +155,11 @@ export function proveRequirements(cwd, requirements, probes = {}) {
     const proof = requirement.proof;
     if (!proof?.ref) continue;
     if (proof.kind === "command") {
-      const { output, exitCode } = runShellFull(cwd, proof.ref, probes);
+      const { output, exitCode, timedOut } = runShellFull(cwd, proof.ref, probes, PROOF_TIMEOUT_MS);
       const matched = exitCode === 0 ? patternMatchedATest(proof.ref, output) : null;
-      const detail = exitCode !== 0
+      const detail = timedOut
+        ? `timed out after ${PROOF_TIMEOUT_MS / 1000} s`
+        : exitCode !== 0
         ? `exit ${exitCode ?? "no exit code (killed or never started)"}${output.trim() ? `: ${output.trim().slice(0, PROOF_DETAIL_CAP)}` : ""}`
         : matched === false ? "exit 0, but its --test-name-pattern matched no test: the proof ran nothing" : "exit 0";
       results.push({ requirementId: requirement.id, kind: "command", ref: proof.ref, pass: exitCode === 0 && matched !== false, detail });

package/src/plan/template.mjs

@@ -111,7 +111,7 @@ const REQUIRED_INPUTS = Object.freeze({
 // run had already succeeded. The id charset is requireId's
 // (contract/assert.mjs) verbatim, because an id that is present but invalid
 // fails that same validator just as late.
-const PLAN_OUTPUT_SHAPE = '{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, scopeAcknowledged, definitionOfDone: [{id, text, proof?: {kind: "command"|"path"|"verification", ref}, judgment?: true}], verification: [{argv: [string], cwd?, timeoutSec?, repeat?, env?, mutation?: {threshold}}], expectedTurns?}], phases?: [{id, requirementIds: [string], nodeIds: [string], deliverable}], justification?}; every id in it (node, phase, node assignment, and definitionOfDone item) must match [A-Za-z0-9._-]+ and never be exactly "." or ".."';
+const PLAN_OUTPUT_SHAPE = '{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, scopeAcknowledged, definitionOfDone: [{id, text, proof?: {kind: "command"|"path"|"verification", ref}, judgment?: true, reason?: string}], verification: [{argv: [string], cwd?, timeoutSec?, repeat?, env?, mutation?: {threshold}}], expectedTurns?}], phases?: [{id, requirementIds: [string], nodeIds: [string], deliverable}], justification?}; every id in it (node, phase, node assignment, and definitionOfDone item) must match [A-Za-z0-9._-]+ and never be exactly "." or ".."';
 /**
  * The size guidance every draft and revise carries. measured 2026-09-20 over
  * stored runs: median 49 provider requests per worker turn; cost per turn

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