faberun 0.22.0 → 0.23.1

package/src/cli/manual.mjs

@@ -10,13 +10,15 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { COMMAND_OPTIONS } from "../cli.mjs";
+import { METRICS_MANUAL } from "../campaign/metrics-command.mjs";
 import CAMPAIGN_OPERATIONS from "./campaign.mjs";
 import SEAT_OPERATIONS from "./seat.mjs";
 import CONTRACT_OPERATIONS from "./contract.mjs";
 import SKILLS_OPERATIONS from "./skills.mjs";
 import SPEC_OPERATIONS from "./spec.mjs";
 
-/** @typedef {{type: "string"|"boolean", multiple?: boolean}} FlagSpec */
+/** @typedef {{value: string, effect: string, default: string}} ManualFlag */
+/** @typedef {{type: "string"|"boolean", multiple?: boolean, manual?: ManualFlag}} FlagSpec */
 /** @typedef {{flags?: Record<string, FlagSpec>, operations?: Record<string, Record<string, FlagSpec>>}} VerbSurface */
 /** @typedef {{verbs: Record<string, VerbSurface>}} Surface */
 
@@ -51,7 +53,12 @@ const CONTAINER_OPERATIONS = {
 export function collectSurface() {
   /** @type {Record<string, VerbSurface>} */
   const verbs = {};
-  for (const [verb, flags] of Object.entries(COMMAND_OPTIONS)) verbs[verb] = { flags };
+  for (const [verb, flags] of Object.entries(COMMAND_OPTIONS)) {
+    const manualFlags = verb === "metrics"
+      ? Object.fromEntries(Object.entries(flags).map(([name, spec]) => [name, { ...spec, manual: METRICS_MANUAL[name] }]))
+      : flags;
+    verbs[verb] = { flags: manualFlags };
+  }
   if (verbs.supervise) verbs.supervise.operations = { campaign: CAMPAIGN_OPERATIONS.supervise };
   for (const [verb, operations] of Object.entries(CONTAINER_OPERATIONS)) verbs[verb] = { operations };
   return { verbs };
@@ -291,9 +298,10 @@ function buildRows(flags, existingRows) {
   }
   return names.map((name) => {
     const existing = existingRows.get(name);
-    const value = existing ? existing.value : "<value>";
-    const effect = existing ? existing.effect : "";
-    const fallback = existing ? existing.default : "—";
+    const manual = flags[name].manual;
+    const value = existing?.value && existing.value !== "<value>" ? existing.value : manual?.value ?? existing?.value ?? "<value>";
+    const effect = existing?.effect || manual?.effect || "";
+    const fallback = existing?.default && existing.default !== "—" ? existing.default : manual?.default ?? existing?.default ?? "—";
     return `| \`--${name}\` | ${value} | ${effect} | ${fallback} |`;
   });
 }

package/src/cli.mjs

@@ -39,7 +39,7 @@ import { updateCommand } from "./cli/update.mjs";
 import { contractCli, validateContractFile } from "./cli/contract.mjs";
 import { specCli } from "./cli/spec.mjs";
 import { planCli } from "./cli/plan.mjs";
-import { METRICS_OPTIONS, renderCampaignMetrics } from "./campaign/metrics.mjs";
+import { METRICS_OPTIONS, renderCampaignMetrics } from "./campaign/metrics-command.mjs";
 import { runContract } from "./engine/scheduler.mjs";
 import { resumeRun } from "./engine/resume.mjs";
 import { cancelRun } from "./engine/cancel.mjs";

package/src/engine/bulk-read.mjs

@@ -259,13 +259,14 @@ function accountDelegation(runtimeId, runtime, envelope, priced, observation) {
     nodeId,
     role: "worker",
     runtimeId,
+    harness: runtime.harness,
     model: runtime.model,
     usage: envelope.usage,
     costUsd: priced.costUsd,
     costProvenance: priced.costProvenance,
     startedAt: observation.startedAt,
     closedAt: new Date().toISOString(),
-  }));
+  }), { runtime });
 }
 
 /** @param {string} reason @returns {BulkReadResult} */

package/src/engine/dispatch.mjs

@@ -50,7 +50,7 @@ import { transition, writeNode } from "./state.mjs";
  * `dispatched`: a judge is running (or failed to start and the node is already
  * marked failed).
  *
- * @typedef {{kind: "rejected", verdict: JudgeVerdict}|{kind: "settle", gate: JudgeVerdict}|{kind: "dispatched"}} JudgeRound
+ * @typedef {{kind: "rejected", verdict: JudgeVerdict}|{kind: "settle", gate: JudgeVerdict|null}|{kind: "dispatched"}} JudgeRound
  */
 /** @typedef {import("./prompts.mjs").JudgeVerdict} JudgeVerdict */
 
@@ -439,6 +439,28 @@ export function startResultMaterialization(contract, node, state, runDir, runnin
     transition(runDir, state, "failed", { phase: "worker", error: { code: "result_materialization_failed", message: errorMessage(error) } }, lock);
   }
 }
+/**
+ * The mechanical half of the gate, for a node whose gate is disabled: its
+ * Definition of Done command and path proofs still run, and no judge is
+ * asked. Measured 2026-09-23 on evidence-you-can-recompute: every node carried
+ * `gate: false`, and not one of its declared proofs ran.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @returns {Promise<JudgeRound>}
+ */
+export async function startMechanicalGate(contract, node, state) {
+  const { verdict, results } = await deterministicGate(
+    node,
+    attemptWorkspace(state) ?? contract.cwd,
+    false,
+    gateProofTimeoutMs(node, contract),
+    /** @type {import("../contract/index.mjs").VerificationState|null} */ (state.verification),
+  );
+  if (verdict.verdict === "fail") return { kind: "rejected", verdict };
+  return { kind: "settle", gate: results.length ? verdict : null };
+}
 /**
  * Gate a completed worker: mechanical proofs gate first, the judge arbitrates
  * only judgment items and is skipped when the review mode is `none` or no

package/src/engine/lifecycle.mjs

@@ -52,7 +52,7 @@ import {
   workerResultPath,
 } from "./result-file.mjs";
 import { canReuseResultEvidence, checkResultMaterializationScope, checkWorkerScope, recordScopeFinding, sourceWorkerRuntime } from "./scope.mjs";
-import { startJudge, startResultMaterialization } from "./dispatch.mjs";
+import { startJudge, startMechanicalGate, startResultMaterialization } from "./dispatch.mjs";
 import { raiseNodeAttention, settleDone } from "./settle.mjs";
 import { applyRejection, applyVerificationFailure } from "./settle.mjs";
 import { emitNodeAdvisories } from "./notify-queue.mjs";
@@ -409,7 +409,7 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
       error: envelope.error ?? null,
       nextState: operationNextState(state),
     });
-    appendUsageRecord(runDir, state.invocations.find((invocation) => invocation.id === job.invocation.id));
+    appendUsageRecord(runDir, state.invocations.find((invocation) => invocation.id === job.invocation.id), { runtime: job.runtime });
     state.usage = invocationUsage(state);
     state.costUsd = invocationCost(state);
     // Checked before any other branch can act on how this invocation closed --
@@ -587,11 +587,10 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
         continue;
       }
       if (job.scopeViolation) recordScopeFinding(runDir, state, lock);
-      if (job.node.gate.enabled) {
-        await applyJudgeRound(await startJudge(contract, job.node, state, runDir, running, workerResult, lock, states, campaignPath),
-          contract, job.node, state, runDir, running, lock, states, campaignPath, workerResult);
-      }
-      else await settleDone(contract, job.node, state, runDir, lock, states, campaignPath, { phase: "complete", result: workerResult });
+      const round = job.node.gate.enabled
+        ? await startJudge(contract, job.node, state, runDir, running, workerResult, lock, states, campaignPath)
+        : await startMechanicalGate(contract, job.node, state);
+      await applyJudgeRound(round, contract, job.node, state, runDir, running, lock, states, campaignPath, workerResult);
       continue;
     }
   }
@@ -786,4 +785,3 @@ export async function applyInvalidWorkerResult(contract, node, state, runDir, ru
  * else there.
  *
  * @param {string} runDir @param {string} nodeId @returns {string} */
-

package/src/engine/scheduler.mjs

@@ -539,6 +539,7 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
         for (const job of jobs) envelopes.set(job.invocation.id, recordInvocationUsage(job, { accumulate: false }));
         for (const job of jobs) {
           const invocation = job.state.invocations?.find((item) => item.id === job.invocation.id) ?? job.invocation;
+          appendUsageRecord(runDir, invocation, { runtime: job.runtime, unknownReason: "invocation-killed" });
           const scopeOk = job.phase !== "worker" || checkWorkerScope(contract, runDir, job, lock);
           settleInvocation(runDir, invocation, {
             status: scopeOk ? "canceled" : "failed",
@@ -569,7 +570,7 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
         job.state.usage = invocationUsage(job.state);
         job.state.costUsd = invocationCost(job.state);
         const invocation = job.state.invocations?.find((item) => item.id === job.invocation.id) ?? job.invocation;
-        appendUsageRecord(runDir, invocation);
+        appendUsageRecord(runDir, invocation, { runtime: job.runtime, unknownReason: "invocation-killed" });
         if (job.phase === "worker" && !checkWorkerScope(contract, runDir, job, lock)) {
           settleInvocation(runDir, invocation, {
             status: "failed",

package/src/engine/settle.mjs

@@ -46,7 +46,7 @@ import { verifyCandidateWorkspace } from "./verify.mjs";
  * (`gate.maxRevisions`, default 1) whether or not the gate reviews: a red
  * deterministic verification earns the same fresh attempt with the failure in
  * front of the worker that a judge rejection does. Measured 2026-09-20 in the
- * orchestration-arms campaign: with the budget behind `gate.enabled`, a node
+ * `docs/campaigns/orchestration-arms/`: with the budget behind `gate.enabled`, a node
  * under `gate: false` died on one timing test that flaked under load, and its
  * dependant with it, while the judged twin of the same node got its retry.
  * @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {Map<string, Job>|null} running @param {LockHandle} lock @param {Map<string, NodeSnapshot>} states @param {string} campaignPath @param {JudgeVerdict} verdict @param {{code: string, label: string, phase?: "worker"|"judge", message?: string, forceFresh?: boolean}} options */

package/src/plan/proof-run.mjs

@@ -65,18 +65,60 @@ export const MEASURE_SIDE_EFFECT_ENV_KEYS = [
  * @returns {{output: string, exitCode: number|null, truncated: boolean}}
  */
 export function runShellCapture(cwd, command, probes = {}) {
+  const { output, exitCode, truncated } = runShellFull(cwd, command, probes);
+  const bytes = Buffer.from(output, "utf8");
+  return {
+    output: truncated ? bytes.subarray(0, MEASURE_OUTPUT_CAP_BYTES).toString("utf8") : output,
+    exitCode,
+    truncated,
+  };
+}
+
+/**
+ * The shell run behind `runShellCapture`, returning the whole output: a
+ * pinned-test check has to see every test the runner reported, and the
+ * matching line can sit far past the 4 KiB a measurement keeps.
+ *
+ * @param {string} cwd
+ * @param {string} command
+ * @param {MeasureProbes} [probes]
+ * @returns {{output: string, exitCode: number|null, truncated: boolean}}
+ */
+function runShellFull(cwd, command, probes = {}) {
   const run = probes.run ?? spawnSync;
   const env = { ...process.env };
   for (const key of MEASURE_SIDE_EFFECT_ENV_KEYS) delete env[key];
+  // A nested `node --test` that inherits NODE_TEST_CONTEXT stays a runner
+  // 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 combined = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-  const bytes = Buffer.from(combined, "utf8");
-  const truncated = bytes.length > MEASURE_OUTPUT_CAP_BYTES;
-  return {
-    output: truncated ? bytes.subarray(0, MEASURE_OUTPUT_CAP_BYTES).toString("utf8") : combined,
-    exitCode: result.status,
-    truncated,
-  };
+  return { output: combined, exitCode: result.status, truncated: Buffer.byteLength(combined, "utf8") > MEASURE_OUTPUT_CAP_BYTES };
+}
+
+/** `--test-name-pattern` in a shell command, quoted or bare, `=` or space. */
+const NAME_PATTERN_FLAG = /--test-name-pattern(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/u;
+/** A passing test as the spec reporter (`✔ name (1ms)`) or TAP (`ok 1 - name`) prints it. */
+const PASSING_TEST_LINE = /^\s*(?:\u2714\s+|ok \d+ - )(.+?)(?:\s+\(\d[\d.]*m?s\))?\s*$/gmu;
+
+/**
+ * Whether a `node --test --test-name-pattern=<p>` proof ran a test named by
+ * its pattern. Node exits 0 when the pattern matches nothing, printing only
+ * the file, so the exit code alone cannot tell a proof from its absence.
+ * Returns null when the command carries no pattern.
+ *
+ * @param {string} command
+ * @param {string} output
+ * @returns {boolean|null}
+ */
+function patternMatchedATest(command, output) {
+  if (!/\bnode\b[^|;&]*--test\b/u.test(command)) return null;
+  const flag = NAME_PATTERN_FLAG.exec(command);
+  if (!flag) return null;
+  const pattern = new RegExp(flag[1] ?? flag[2] ?? flag[3], "u");
+  const plain = output.replace(/\u001b\[[0-9;]*m/gu, "");
+  return [...plain.matchAll(PASSING_TEST_LINE)].some((line) => pattern.test(line[1]) && !/\.m?[jt]s$/u.test(line[1].trim()));
 }
 
 /**
@@ -104,11 +146,12 @@ export function proveRequirements(cwd, requirements, probes = {}) {
     const proof = requirement.proof;
     if (!proof?.ref) continue;
     if (proof.kind === "command") {
-      const { output, exitCode } = runShellCapture(cwd, proof.ref, probes);
-      const detail = exitCode === 0
-        ? "exit 0"
-        : `exit ${exitCode ?? "no exit code (killed or never started)"}${output.trim() ? `: ${output.trim().slice(0, PROOF_DETAIL_CAP)}` : ""}`;
-      results.push({ requirementId: requirement.id, kind: "command", ref: proof.ref, pass: exitCode === 0, detail });
+      const { output, exitCode } = runShellFull(cwd, proof.ref, probes);
+      const matched = exitCode === 0 ? patternMatchedATest(proof.ref, output) : null;
+      const detail = 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 });
       continue;
     }
     if (proof.kind === "path") {

package/src/repo/worktree.mjs

@@ -384,7 +384,10 @@ export function sealAttempt({ repo, path, baseSha, runId, nodeId, attempt, exclu
       // schedule it chose. The identity and signing overrides above are the
       // same argument: this commit answers to the factory, not to the repo's
       // conventions for human commits.
-      "commit", "--no-verify", "-qm", `faberun ${runId} ${nodeId} attempt ${attempt}`,
+      // Conventional, so a campaign branch passes a PR's commitlint check
+      // (measured 2026-09-23: every `faberun <run> <node> attempt N` seal was
+      // refused); the run id moves to the body to keep the header short.
+      "commit", "--no-verify", "-q", "-m", `chore(faberun): seal ${nodeId} attempt ${attempt}`, "-m", `run ${runId}`,
     ]);
   }
   const sha = gitHead(path);

package/src/report/metrics-report.mjs

@@ -13,7 +13,7 @@
  */
 
 /** @typedef {import("../campaign/metrics.mjs").CampaignMetrics} CampaignMetrics */
-/** @typedef {import("../campaign/metrics.mjs").MetricsSources} MetricsSources */
+/** @typedef {import("../campaign/metrics-command.mjs").MetricsSources} MetricsSources */
 
 /** Schema of the `--json` form; bumped when a consumer would have to change. */
 const METRICS_SCHEMA_VERSION = 2;
@@ -39,19 +39,30 @@ const HOURS_PRECISION = 10_000;
  * @returns {string}
  */
 export function renderMetricsReport(sources, metrics) {
+  const missingSources = sources.missingSources ?? [];
   const lines = [
     `[metrics] ${sources.campaignId} · ${sources.runIds.length} runs · ${sources.events.length} events · ${Object.keys(metrics).length} indicators`,
   ];
+  if (missingSources.length > 0) lines.push(`missing sources: ${missingSources.join(", ")}`);
   for (const [name, indicator] of Object.entries(metrics)) {
     const records = indicator.count === 1 ? "1 record" : `${indicator.count} records`;
     const unknown = typeof (/** @type {{unknownCount?: number}} */ (indicator).unknownCount) === "number"
-      ? ` · ${(/** @type {{unknownCount: number}} */ (indicator)).unknownCount} unknown`
+      ? `${unknownCostSuffix(/** @type {{unknownCount: number, unknownFractionByReason?: Record<string, number>}} */ (indicator))}`
       : "";
-    lines.push(`${name.padEnd(NAME_WIDTH)} ${indicator.direction.padEnd(11)} ${formatValue(name, indicator.value).padEnd(24)} · ${records}${unknown}`);
+    const missing = Array.isArray(indicator.missingSources) ? ` · missing ${indicator.missingSources.join(", ")}` : "";
+    lines.push(`${name.padEnd(NAME_WIDTH)} ${indicator.direction.padEnd(11)} ${formatValue(name, indicator.value).padEnd(24)} · ${records}${unknown}${missing}`);
   }
   return `${lines.join("\n")}\n`;
 }
 
+/** @param {{unknownCount: number, unknownFractionByReason?: Record<string, number>}} indicator @returns {string} */
+function unknownCostSuffix(indicator) {
+  const reasons = Object.entries(indicator.unknownFractionByReason ?? {})
+    .map(([reason, fraction]) => `${reason}=${fraction}`)
+    .join(", ");
+  return ` · ${indicator.unknownCount} unknown${reasons ? ` (${reasons})` : ""}`;
+}
+
 /**
  * The machine-readable form, one JSON line like `preflight --json`.
  *
@@ -60,11 +71,13 @@ export function renderMetricsReport(sources, metrics) {
  * @returns {string}
  */
 export function renderMetricsJson(sources, metrics) {
+  const missingSources = sources.missingSources ?? [];
   return `${JSON.stringify({
     schemaVersion: METRICS_SCHEMA_VERSION,
     campaignId: sources.campaignId,
     runs: sources.runIds.length,
     events: sources.events.length,
+    missingSources,
     indicators: metrics,
   })}\n`;
 }

package/src/run/lock.mjs

@@ -17,7 +17,7 @@ import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, rena
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { fsyncDirectory } from "./store.mjs";
-import { errorCode } from "../util.mjs";
+import { errorCode, sleepSync } from "../util.mjs";
 
 const LOCK_FILE = "controller.lock";
 const TAKEOVER_ATTEMPTS = 20;
@@ -84,7 +84,7 @@ export function processStartToken(pid) {
     // and report nothing for a pid that is already alive. One short retry
     // closes that window; a still-empty answer stays null.
     if (!pidAlive(pid)) return null;
-    sleepMs(20);
+    sleepSync(20);
     const retried = psStartTime(pid);
     return retried.length > 0 ? retried : null;
   }
@@ -106,16 +106,6 @@ function psStartTime(pid) {
   }
 }
 
-/**
- * Block without a timer so the synchronous darwin retry above can wait out the
- * spawn race. The duration is tiny and bounded, so blocking the loop is safe.
- *
- * @param {number} milliseconds
- */
-function sleepMs(milliseconds) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
-}
-
 /** @param {number|null|undefined} pid @returns {boolean} */
 export function pidAlive(pid) {
   if (!Number.isInteger(pid) || /** @type {number} */ (pid) <= 0) return false;

package/src/run/store.mjs

@@ -14,9 +14,19 @@ import {
 } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
-import { errorCode } from "../util.mjs";
+import { errorCode, sleepSync } from "../util.mjs";
 
 const BOOTSTRAP_FILE = "bootstrap.json";
+// Windows refuses to replace a file another process holds open: MoveFileEx
+// answers EPERM (or EACCES, EBUSY) while a reader, an indexer or a virus
+// scanner has the destination, where a POSIX rename replaces it regardless.
+// Measured 2026-09-23 on Windows 11 with node 24: one process polling a file
+// with readFileSync failed 882 of 2190 atomic writes onto it, and on CI that
+// killed controllers mid-run (a heartbeat write threw out of driveRun). The
+// retry and its bounds are graceful-fs's: back off 10 ms more per attempt up to
+// 100 ms, and give up after 60 s.
+const WINDOWS_RENAME_BUSY = new Set(["EPERM", "EACCES", "EBUSY"]);
+const RENAME_RETRY_BUDGET_MS = 60_000;
 const JSONL_RECOVERY_TAIL_BYTES = 64 * 1024;
 
 /**
@@ -51,7 +61,7 @@ export function writeTextAtomic(path, text) {
     } finally {
       closeSync(fd);
     }
-    renameSync(temporary, path);
+    renameReplacing(temporary, path);
     fsyncDirectory(dirname(path));
     committed = true;
   } catch (error) {
@@ -68,6 +78,24 @@ export function writeTextAtomic(path, text) {
   }
 }
 
+/**
+ * @param {string} from
+ * @param {string} to
+ */
+function renameReplacing(from, to) {
+  const deadline = Date.now() + RENAME_RETRY_BUDGET_MS;
+  for (let backoff = 0; ; backoff = Math.min(backoff + 10, 100)) {
+    try {
+      renameSync(from, to);
+      return;
+    } catch (error) {
+      const busy = process.platform === "win32" && WINDOWS_RENAME_BUSY.has(errorCode(error) ?? "");
+      if (!busy || Date.now() >= deadline) throw error;
+      sleepSync(backoff);
+    }
+  }
+}
+
 /**
  * @param {string} path
  * @param {unknown} value

package/src/run/usage.mjs

@@ -15,7 +15,7 @@ import { liveUsage } from "../harnesses/session-metrics.mjs";
 import { priceUsage } from "../engine/process.mjs";
 import { readBoundedTail, sessionLedger } from "../engine/transcript.mjs";
 import { writeNode } from "../engine/state.mjs";
-import { normalizeProviderResult } from "../harnesses/index.mjs";
+import { harnessCapabilities, normalizeProviderResult } from "../harnesses/index.mjs";
 
 // `priceUsage` is defined beside `invocationResult`, the second source point,
 // and re-exported here so the ledger's public surface is unchanged. This module
@@ -31,6 +31,15 @@ export { priceUsage };
 /** @typedef {ProviderEnvelope & {costProvenance?: "priced"}} PricedEnvelope */
 /** @typedef {{kind: "adopted"|"rejudge"|"restart"|"reconciled"|"exhausted"|"stalled", phase?: "worker"|"judge", result?: unknown, usage?: Usage, costUsd?: number|null, costProvenance?: "priced", exhaustedUntil?: string|null, error?: {code: string, message: string}|null, invocationId?: string, reason?: string}} RecoveryOutcome */
 /** @typedef {import("../contract/index.mjs").Usage} Usage */
+/** @typedef {"no-usage-stream"|"model-not-priced"|"provider-reported-nothing"|"invocation-killed"} UnknownCostReason */
+
+/** The only reasons a newly-written unknown cost may carry. `legacy` is read-only compatibility for older ledgers. */
+export const UNKNOWN_COST_REASONS = Object.freeze([
+  "no-usage-stream",
+  "model-not-priced",
+  "provider-reported-nothing",
+  "invocation-killed",
+]);
 
 /**
  * Extract the invocation's provider envelope from the bounded transcript tail
@@ -144,10 +153,15 @@ export function usageRecordIds(runDir) {
  *
  * @param {string} runDir
  * @param {Invocation|undefined|null} invocation
+ * @param {{runtime?: {harness?: string, capabilities?: {usage?: boolean}}, unknownReason?: UnknownCostReason}} [options]
  */
-export function appendUsageRecord(runDir, invocation) {
+export function appendUsageRecord(runDir, invocation, options = {}) {
   if (!invocation?.id || usageRecordIds(runDir).has(invocation.id)) return;
   const usage = /** @type {Usage} */ (invocation.usage ?? { inputTokens: null, outputTokens: null, cacheReadInputTokens: null });
+  const costProvenance = invocation.costProvenance ?? (typeof invocation.costUsd === "number" ? "provider" : "unknown");
+  const unknownReason = costProvenance === "unknown"
+    ? unknownCostReason(invocation, usage, options)
+    : undefined;
   appendJsonl(join(runDir, USAGE_LOG_NAME), {
     invocationId: invocation.id,
     runId: invocation.runId ?? basename(runDir),
@@ -162,12 +176,51 @@ export function appendUsageRecord(runDir, invocation) {
     costUsd: typeof invocation.costUsd === "number" ? invocation.costUsd : null,
     // A persisted `priced` marker wins; otherwise the pre-Phase-4 rule applies
     // unchanged: a reported number is `provider`, absence is `unknown`.
-    costProvenance: invocation.costProvenance ?? (typeof invocation.costUsd === "number" ? "provider" : "unknown"),
+    costProvenance,
+    ...(unknownReason === undefined ? {} : { unknownReason }),
     session: invocation.session ?? null,
     startedAt: invocation.startedAt ?? null,
     finishedAt: invocation.closedAt ?? null,
   });
 }
+
+/**
+ * Explain an unknown cost at the point where the invocation's counters and
+ * pricing have been resolved. A runtime can be supplied by the live engine;
+ * older or recovery callers fall back to the invocation's harness identity.
+ *
+ * @param {Invocation} invocation
+ * @param {Usage} usage
+ * @param {{runtime?: {harness?: string, capabilities?: {usage?: boolean}}, unknownReason?: UnknownCostReason}} [options]
+ * @returns {UnknownCostReason}
+ */
+function unknownCostReason(invocation, usage, options = {}) {
+  if (options.unknownReason !== undefined) return options.unknownReason;
+  if (invocation.signal !== null && invocation.signal !== undefined || invocation.status === "terminated") {
+    return "invocation-killed";
+  }
+  const runtimeUsage = options.runtime?.capabilities?.usage;
+  if (runtimeUsage === false || (runtimeUsage === undefined && invocation.harness !== undefined && !harnessHasUsage(invocation.harness))) {
+    return "no-usage-stream";
+  }
+  if (!hasMeasuredUsage(usage)) return "provider-reported-nothing";
+  // A partial token stream cannot be called "nothing". It also cannot be
+  // priced because one or more counters are absent, so the model-not-priced
+  // bucket is the only remaining vocabulary that preserves the unknown cost.
+  return "model-not-priced";
+}
+
+/** @param {string} harness @returns {boolean} */
+function harnessHasUsage(harness) {
+  try {
+    return harnessCapabilities({ harness }).usage;
+  } catch (error) {
+    // An unknown harness cannot prove that it emits usage; callers still get
+    // the provider-reported-nothing fallback rather than a guessed adapter.
+    void error;
+    return true;
+  }
+}
 /**
  * Recovery can discover usage after the run synchronized its records. Attach
  * it to the authoritative invocation first, then write the updated usage
@@ -201,7 +254,11 @@ export async function persistRecoveryUsage(runDir, state, recovery, lock) {
     writeNode(runDir, state, lock);
   }
   const updated = state.invocations?.find((invocation) => invocation.id === current.id);
-  if (updated) appendUsageRecord(runDir, updated);
+  if (updated) {
+    const killed = recovery.kind === "stalled"
+      || (recovery.kind === "restart" && /wall-clock budget|died without a completed stream/iu.test(recovery.reason ?? ""));
+    appendUsageRecord(runDir, updated, killed ? { unknownReason: "invocation-killed" } : {});
+  }
 }
 /**
  * @param {Usage|undefined} left

package/src/util.mjs

@@ -275,3 +275,13 @@ export function shellWords(text) {
   if (current !== null) words.push(current);
   return words;
 }
+
+/**
+ * Block the thread without a timer, for a synchronous path that has to wait
+ * out a short race. Callers keep the duration tiny and bounded.
+ *
+ * @param {number} milliseconds
+ */
+export function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}