faberun 0.3.0 → 0.7.0

package/src/report/render.mjs

@@ -22,9 +22,12 @@ const POINTER_ATTENTION_CHARS = 80;
 /** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
 /** @typedef {import("../contract/index.mjs").NodeStatus} NodeStatus */
 /** @typedef {Record<string, unknown>} JsonObject */
+/** @typedef {"priced"|"partial"|"unpriced"|"none"} CostProvenance */
+/** @typedef {{costUsd: number|null, costProvenance: CostProvenance, inputTokens: number, outputTokens: number, cacheReadInputTokens: number, pricedInvocations: number, unpricedInvocations: number}} RoleUsage */
 /** @typedef {{inputTokens: number|null, outputTokens: number|null, cacheReadInputTokens: number|null}} StatusPayloadUsage */
-/** @typedef {{id: string, status: NodeStatus, phase: string|null, executionPhase: string|null, runtime: string|null, workerRuntime: string|null, continuation: string, attempt: number, revisions: number, startedAt: string|null, updatedAt: string|null, usage: StatusPayloadUsage|null, costUsd: number|null, verdict: string|null, pendingHandoff: {runtime: string, reason: string}|null, note: string|null, scopeFindings: string[]|null, errorCode: string|null, blockedBy: string[]}} StatusPayloadNode */
-/** @typedef {{schemaVersion: 1, run: string, contractId: string, campaignId: string, goal: string, usage: {inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null}, controller: JsonObject, identityWarnings: string[], summary: string, nodes: StatusPayloadNode[]}} StatusPayload */
+/** @typedef {{index: number, total: number, argv: string}} VerificationProgress */
+/** @typedef {{id: string, status: NodeStatus, phase: string|null, executionPhase: string|null, runtime: string|null, workerRuntime: string|null, continuation: string, attempt: number, revisions: number, startedAt: string|null, updatedAt: string|null, usage: StatusPayloadUsage|null, costUsd: number|null, verdict: string|null, pendingHandoff: {runtime: string, reason: string}|null, note: string|null, scopeFindings: string[]|null, errorCode: string|null, blockedBy: string[], verificationProgress: VerificationProgress|null, declaredReadBytes: number|null}} StatusPayloadNode */
+/** @typedef {{schemaVersion: 1, run: string, contractId: string, campaignId: string, goal: string, usage: {inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null}, roles: {worker: RoleUsage, judge: RoleUsage}, controller: JsonObject, identityWarnings: string[], summary: string, nodes: StatusPayloadNode[]}} StatusPayload */
 
 /** The glyph each terminal state prints in a status table. */
 export const MARK = {
@@ -89,7 +92,8 @@ export function renderStatus(runDir) {
       node.note ?? "-",
     ]));
   }
-  lines.push("```", "", "## Cost", "", `in ${compactTokens(usage.inputTokens)} · out ${compactTokens(usage.outputTokens)} · cache ${compactTokens(usage.cacheReadInputTokens)} · cost ${compactCost(usage.costUsd)}`);
+  const readBytes = payload.nodes.reduce((total, node) => total + (node.declaredReadBytes ?? 0), 0);
+  lines.push("```", "", "## Cost", "", `in ${compactTokens(usage.inputTokens)} · out ${compactTokens(usage.outputTokens)} · cache ${compactTokens(usage.cacheReadInputTokens)} · worker ${formatRole(payload.roles.worker)} · judge ${formatRole(payload.roles.judge)} · cost ${compactCost(usage.costUsd)} · read ${compactTokens(readBytes)}`);
   return `${lines.join("\n")}\n`;
 }
 
@@ -97,7 +101,9 @@ export function renderStatus(runDir) {
  * The node the operator should look at right now, formatted the same way
  * the dashboard's now strip is (TECH-SPEC lean, section 4, item 1): the
  * active node's elapsed time and cost so far, or an idle line once every
- * node has settled.
+ * node has settled. A node awaiting a controller verification command
+ * appends which one, `k/n`, and its argv, so a minutes-long suite is not
+ * silent between ticks.
  *
  * @param {StatusPayload} payload
  * @param {number} now epoch ms
@@ -105,11 +111,29 @@ export function renderStatus(runDir) {
  */
 function nowLine(payload, now) {
   const active = activeStatusNode(payload.nodes);
-  if (active) return `now: ${active.id} ${active.status} (${formatElapsed(active, now)}) · ${active.runtime ?? "-"} · ${compactCost(active.costUsd)}`;
+  if (active) {
+    const progress = active.verificationProgress;
+    const verification = progress ? ` · verification ${progress.index}/${progress.total} · ${progress.argv}` : "";
+    return `now: ${active.id} ${active.status} (${formatElapsed(active, now)}) · ${active.runtime ?? "-"} · ${compactCost(active.costUsd)}${verification}`;
+  }
   const allTerminal = payload.nodes.every((node) => SUCCESS.has(node.status));
   return allTerminal ? `now: idle · run done · ${compactCost(payload.usage.costUsd)}` : "now: idle";
 }
 
+/**
+ * The `verificationProgress` a controller verification pass leaves on a
+ * running node's persisted `verification` record — nested there rather than
+ * as its own node-snapshot field, since `VerificationState`'s own validator
+ * accepts extra keys where the node snapshot's does not.
+ *
+ * @param {NodeSnapshot} node
+ * @returns {VerificationProgress|null}
+ */
+function verificationProgress(node) {
+  const verification = /** @type {{progress?: VerificationProgress}|null|undefined} */ (node.verification);
+  return verification?.progress ?? null;
+}
+
 /**
  * A node's wall-clock elapsed time: `startedAt` to `updatedAt` once it has
  * settled into a terminal state, `startedAt` to `now` while it is still
@@ -179,30 +203,39 @@ function buildStatusPayload(runDir, contract, nodes, identityWarnings, usage) {
       cacheReadInputTokens: usage.cacheReadInputTokens,
       costUsd: usage.costUsd,
     },
+    roles: roleUsage(nodes),
     controller: controllerStatus(runDir, nodes).status,
     identityWarnings,
     summary: [...counts].map(([status, count]) => `${count} ${status}`).join(" · "),
-    nodes: nodes.map((node) => ({
-      id: node.id,
-      status: node.status,
-      phase: contract.nodes.find((candidate) => candidate.id === node.id)?.phase ?? null,
-      executionPhase: node.phase,
-      runtime: node.runtime ? `${node.runtime.harness}/${node.runtime.model}` : null,
-      workerRuntime: workerRuntimeLabel(node),
-      continuation: continuationMode(node),
-      attempt: node.attempt,
-      revisions: node.revisions,
-      startedAt: node.startedAt ?? null,
-      updatedAt: node.updatedAt ?? null,
-      usage: node.usage ? { inputTokens: node.usage.inputTokens ?? null, outputTokens: node.usage.outputTokens ?? null, cacheReadInputTokens: node.usage.cacheReadInputTokens ?? null } : null,
-      costUsd: typeof node.costUsd === "number" ? node.costUsd : null,
-      verdict: node.gate?.verdict ?? null,
-      pendingHandoff: pendingHandoff(node),
-      note: statusNote(node),
-      scopeFindings: node.scopeFindings?.unexpectedPaths ?? null,
-      errorCode: node.error?.code ?? null,
-      blockedBy: node.blockedBy ?? [],
-    })),
+    nodes: nodes.map((node) => {
+      const progress = verificationProgress(node);
+      return {
+        id: node.id,
+        status: node.status,
+        phase: contract.nodes.find((candidate) => candidate.id === node.id)?.phase ?? null,
+        // A running controller verification command does not move
+        // `node.phase` (it stays `worker`, the phase that dispatched it), so
+        // the surface that shows it is computed here rather than persisted.
+        executionPhase: progress ? "verification" : node.phase,
+        runtime: node.runtime ? `${node.runtime.harness}/${node.runtime.model}` : null,
+        workerRuntime: workerRuntimeLabel(node),
+        continuation: continuationMode(node),
+        attempt: node.attempt,
+        revisions: node.revisions,
+        startedAt: node.startedAt ?? null,
+        updatedAt: node.updatedAt ?? null,
+        usage: node.usage ? { inputTokens: node.usage.inputTokens ?? null, outputTokens: node.usage.outputTokens ?? null, cacheReadInputTokens: node.usage.cacheReadInputTokens ?? null } : null,
+        costUsd: typeof node.costUsd === "number" ? node.costUsd : null,
+        verdict: node.gate?.verdict ?? null,
+        pendingHandoff: pendingHandoff(node),
+        note: statusNote(node),
+        scopeFindings: node.scopeFindings?.unexpectedPaths ?? null,
+        errorCode: node.error?.code ?? null,
+        blockedBy: node.blockedBy ?? [],
+        verificationProgress: progress,
+        declaredReadBytes: typeof node.declaredReadBytes === "number" ? node.declaredReadBytes : null,
+      };
+    }),
   };
 }
 
@@ -361,8 +394,8 @@ export function renderReport(runDir) {
     lines.push(row([MARK[node.status] ?? "[?]", node.id, node.status, node.attempt ?? 0, node.revisions ?? 0, runtime, compactTokens(usage.inputTokens), compactTokens(usage.outputTokens), compactTokens(usage.cacheReadInputTokens), formatCost(cost), note]));
   }
   totals.costUsd = aggregateCost.costUsd;
-  const roles = roleCosts(nodes);
-  lines.push("```", "", `totals · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · worker ${compactCost(roles.worker)} · judge ${compactCost(roles.judge)} · cost ${formatCost(aggregateCost)}`);
+  const roles = roleUsage(nodes);
+  lines.push("```", "", `totals · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · worker ${formatRole(roles.worker)} · judge ${formatRole(roles.judge)} · cost ${formatCost(aggregateCost)}`);
   return `${lines.join("\n")}\n`;
 }
 
@@ -376,13 +409,14 @@ export function renderReportJson(runDir) {
   const { contract, nodes } = loadRun(runDir);
   const counts = new Map();
   for (const node of nodes) counts.set(node.status, (counts.get(node.status) ?? 0) + 1);
-  /** @type {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null, costStatus: string, workerCostUsd: number|null, judgeCostUsd: number|null}} */
-  const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, costUsd: null, costStatus: "ambiguous", workerCostUsd: null, judgeCostUsd: null };
+  /** @type {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null, costStatus: string, workerCostUsd: number|null, judgeCostUsd: number|null, declaredReadBytes: number}} */
+  const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, costUsd: null, costStatus: "ambiguous", workerCostUsd: null, judgeCostUsd: null, declaredReadBytes: 0 };
   const costs = nodes.map(costProjection);
   const listed = nodes.map((node, index) => {
     const usage = node.usage ?? { inputTokens: null, outputTokens: null, cacheReadInputTokens: null };
     for (const key of /** @type {("inputTokens"|"outputTokens"|"cacheReadInputTokens")[]} */ (["inputTokens", "outputTokens", "cacheReadInputTokens"])) totals[key] = (totals[key] ?? 0) + (usage[key] ?? 0);
     const cost = costs[index];
+    totals.declaredReadBytes += typeof node.declaredReadBytes === "number" ? node.declaredReadBytes : 0;
     return {
       id: node.id,
       status: node.status,
@@ -396,14 +430,15 @@ export function renderReportJson(runDir) {
       costStatus: cost.status,
       continuation: continuationMode(node),
       note: nodeNote(node),
+      declaredReadBytes: typeof node.declaredReadBytes === "number" ? node.declaredReadBytes : null,
     };
   });
   const aggregateCost = aggregateCostProjection(costs);
   totals.costUsd = aggregateCost.costUsd;
   totals.costStatus = aggregateCost.status;
-  const roles = roleCosts(nodes);
-  totals.workerCostUsd = roles.worker;
-  totals.judgeCostUsd = roles.judge;
+  const roles = roleUsage(nodes);
+  totals.workerCostUsd = roles.worker.costUsd;
+  totals.judgeCostUsd = roles.judge.costUsd;
   const payload = {
     schemaVersion: 1,
     run: basename(runDir),
@@ -411,6 +446,7 @@ export function renderReportJson(runDir) {
     campaignId: contract.campaignId,
     summary: [...counts].map(([status, count]) => `${count} ${status}`).join(" · "),
     totals,
+    roles,
     nodes: listed,
   };
   return `${JSON.stringify(payload, null, 2)}\n`;
@@ -621,39 +657,86 @@ function nodeNote(node) {
 /** @typedef {{costUsd: number|null, status: "known"|"estimated"|"ambiguous"}} CostProjection */
 
 /**
- * Per-role cost, summed from the invocation ledger alone. A role that appears
- * only on invocations that all carry a provider cost is `known`; a role with no
- * invocation at all, or with any invocation whose cost is missing, is `null`.
- * That is deliberately not zero: an unavailable or partial role cost must not
- * fabricate `$0`, and summing only the known invocations would understate a
- * partial one. The invocation ledger is the single source, so the node's own
- * `costUsd` (itself the sum of these invocations) is never added on top and
- * cannot double-count.
+ * Per-role usage from the invocation ledger alone, with the provenance that
+ * says whether the role's cost total is honest. A role whose invocations all
+ * carry a provider cost is `priced` and its `costUsd` is the sum; a role with
+ * any unpriced invocation is `partial` (some priced) or `unpriced` (none), and
+ * its `costUsd` stays null rather than summing the known half and understating
+ * it. A role with no invocation is `none`. Token totals are always carried, so
+ * a role the provider would not price still reads as work.
  *
  * @param {NodeSnapshot[]} nodes
- * @returns {{worker: number|null, judge: number|null}}
+ * @returns {{worker: RoleUsage, judge: RoleUsage}}
  */
-export function roleCosts(nodes) {
-  /** @type {Record<"worker"|"judge", {total: number, present: number, unknown: number}>} */
+export function roleUsage(nodes) {
+  /** @type {Record<"worker"|"judge", {total: number, priced: number, unpriced: number, inputTokens: number, outputTokens: number, cacheReadInputTokens: number}>} */
   const roles = {
-    worker: { total: 0, present: 0, unknown: 0 },
-    judge: { total: 0, present: 0, unknown: 0 },
+    worker: { total: 0, priced: 0, unpriced: 0, inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 },
+    judge: { total: 0, priced: 0, unpriced: 0, inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 },
   };
   for (const node of nodes) {
     for (const invocation of node.invocations ?? []) {
       if (invocation.role !== "worker" && invocation.role !== "judge") continue;
       const bucket = roles[invocation.role];
       const cost = finite(invocation.costUsd);
-      if (cost === null) bucket.unknown += 1;
+      if (cost === null) bucket.unpriced += 1;
       else {
-        bucket.present += 1;
+        bucket.priced += 1;
         bucket.total += cost;
       }
+      bucket.inputTokens += finite(invocation.usage?.inputTokens) ?? 0;
+      bucket.outputTokens += finite(invocation.usage?.outputTokens) ?? 0;
+      bucket.cacheReadInputTokens += finite(invocation.usage?.cacheReadInputTokens) ?? 0;
     }
   }
-  const complete = (/** @type {{present: number, unknown: number, total: number}} */ bucket) =>
-    bucket.present > 0 && bucket.unknown === 0 ? bucket.total : null;
-  return { worker: complete(roles.worker), judge: complete(roles.judge) };
+  return { worker: summarizeRole(roles.worker), judge: summarizeRole(roles.judge) };
+}
+
+/**
+ * @param {{total: number, priced: number, unpriced: number, inputTokens: number, outputTokens: number, cacheReadInputTokens: number}} bucket
+ * @returns {RoleUsage}
+ */
+function summarizeRole(bucket) {
+  const costProvenance = bucket.priced > 0
+    ? (bucket.unpriced > 0 ? "partial" : "priced")
+    : (bucket.unpriced > 0 ? "unpriced" : "none");
+  return {
+    costUsd: costProvenance === "priced" ? bucket.total : null,
+    costProvenance,
+    inputTokens: bucket.inputTokens,
+    outputTokens: bucket.outputTokens,
+    cacheReadInputTokens: bucket.cacheReadInputTokens,
+    pricedInvocations: bucket.priced,
+    unpricedInvocations: bucket.unpriced,
+  };
+}
+
+/**
+ * Per-role cost, summed from the invocation ledger alone. Kept for the closing
+ * artifacts, which render only the dollar cell; `roleUsage` carries the
+ * provenance that cell cannot express.
+ *
+ * @param {NodeSnapshot[]} nodes
+ * @returns {{worker: number|null, judge: number|null}}
+ */
+export function roleCosts(nodes) {
+  const roles = roleUsage(nodes);
+  return { worker: roles.worker.costUsd, judge: roles.judge.costUsd };
+}
+
+/**
+ * A role's cell in a totals line: the dollar total when every invocation is
+ * priced, `unpriced` with the token totals it did record when any invocation
+ * has no cost, and `-` only when the role has no invocation at all. An
+ * unpriced role reads as real work instead of vanishing into a dash.
+ *
+ * @param {RoleUsage} role
+ * @returns {string}
+ */
+function formatRole(role) {
+  if (role.costUsd !== null) return compactCost(role.costUsd);
+  if (role.costProvenance === "none") return "-";
+  return `unpriced (in ${compactTokens(role.inputTokens)} · out ${compactTokens(role.outputTokens)} · cache ${compactTokens(role.cacheReadInputTokens)})`;
 }
 
 /**

package/src/web/index.html

@@ -208,7 +208,7 @@ function handoffHtml(handoff) {
 }
 
 function renderSectionsHtml(snapshot) {
-  if (!snapshot?.selectedCampaignId) return `<p class="empty">no campaign found under .runs; initialize one with: runner.mjs campaign init</p>`;
+  if (!snapshot?.selectedCampaignId) return `<p class="empty">no campaign found under .runs; initialize one with: faberun campaign init</p>`;
   return nowHtml(snapshot.now) + needsYouHtml(snapshot.needsYou) + runsHtml(snapshot.runs, state.runId) + drawerHtml(snapshot.drawer, state.tab) + handoffHtml(snapshot.handoff);
 }