faberun 0.22.0 → 0.23.0

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/lifecycle.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 --
@@ -786,4 +786,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/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/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