faberun 0.26.3 → 0.28.0

package/src/repo/workspace.mjs

@@ -17,7 +17,7 @@ import { Buffer } from "node:buffer";
 import { gitArguments } from "../host/platform.mjs";
 import { VERIFICATION_LIMITS } from "../contract/verification.mjs";
 import { basename, isAbsolute, relative, resolve } from "node:path";
-import { closeSync, lstatSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, statSync } from "node:fs";
+import { closeSync, lstatSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { errorCode } from "../util.mjs";
 import { execFileSync } from "node:child_process";
@@ -28,10 +28,14 @@ import { RUNS_DIR_NAME } from "../run/paths.mjs";
 /** A `node_modules` directory at any depth, matched as a whole path segment. */
 const NODE_MODULES_SEGMENT = /(?:^|\/)node_modules(?:\/|$)/u;
 
+/** Ignore sources at most this large are kept verbatim so base rules can be replayed. */
+const IGNORE_SOURCE_CONTENT_LIMIT = 64 * 1024;
+
 /**
- * One entry of a workspace snapshot.
+ * One entry of a workspace snapshot. `content` is present on text ignore
+ * sources small enough to replay the base ignore rules for a declared edit.
  *
- * @typedef {{path: string, kind: "file"|"symlink"|"missing", digest?: string, size?: number}} SnapshotEntry
+ * @typedef {{path: string, kind: "file"|"symlink"|"missing", digest?: string, size?: number, content?: string}} SnapshotEntry
  */
 /** @typedef {{entries: SnapshotEntry[], ignoreSources: SnapshotEntry[], truncated: boolean}} WorkspaceSnapshot */
 /** @typedef {{literal: string, paths: string[]}} WorkspaceScopeOrigin */
@@ -55,15 +59,29 @@ export function captureWorkspaceSnapshot(cwd, expectedIgnoreSources) {
   if (expectedIgnoreSources !== undefined && !sameSnapshotEntries(expectedIgnoreSources, ignoreSources)) {
     throw ignoreSourcesChanged(expectedIgnoreSources, ignoreSources);
   }
+  return { entries: captureWorkspaceEntries(root, relevantWorkspacePaths(root)), ignoreSources, truncated: false };
+}
+/**
+ * Hash the observable workspace paths into snapshot entries. This is separate
+ * from `captureWorkspaceSnapshot` so a declared ignore-source edit can be
+ * enumerated with the base ignore rules and still hash the current file
+ * content, which is what makes the edit count as a declared write.
+ *
+ * @param {string} root
+ * @param {string[]} paths
+ * @returns {SnapshotEntry[]}
+ */
+function captureWorkspaceEntries(root, paths) {
   /** @type {SnapshotEntry[]} */
   const entries = [];
-  const add = (/** @type {SnapshotEntry} */ entry) => {
+  /** @param {SnapshotEntry} entry */
+  const add = (entry) => {
     if (entries.length >= VERIFICATION_LIMITS.snapshotEntries) {
       throw fail("snapshot_too_large", `workspace snapshot exceeds ${VERIFICATION_LIMITS.snapshotEntries} entries`);
     }
     entries.push(entry);
   };
-  for (const rel of relevantWorkspacePaths(root)) {
+  for (const rel of paths) {
     if (Buffer.byteLength(rel, "utf8") > VERIFICATION_LIMITS.snapshotPathBytes) {
       throw fail("snapshot_path_too_long", `workspace path exceeds ${VERIFICATION_LIMITS.snapshotPathBytes} bytes: ${rel.slice(0, 128)}`);
     }
@@ -99,7 +117,7 @@ export function captureWorkspaceSnapshot(cwd, expectedIgnoreSources) {
       throw fail("snapshot_unsupported_entry", `unsupported workspace entry: ${rel}`);
     }
   }
-  return { entries, ignoreSources, truncated: false };
+  return entries;
 }
 /**
  * @param {WorkspaceSnapshot|undefined} before
@@ -121,10 +139,22 @@ export function compareWorkspaceSnapshot(before, cwd, scope = {}) {
       files: expandScopePaths(root, normalizeScopePaths(scope.files ?? [], "files")),
       roots: expandScopePaths(root, normalizeScopePaths(scope.roots ?? [], "roots")),
     });
-  const after = captureWorkspaceSnapshot(cwd, before.ignoreSources);
-  if (!sameSnapshotEntries(before.ignoreSources, after.ignoreSources)) {
-    throw ignoreSourcesChanged(before.ignoreSources, after.ignoreSources);
+  const currentIgnoreSources = captureIgnoreSources(root);
+  const changedIgnoreSources = changedSnapshotPaths(before.ignoreSources, currentIgnoreSources);
+  // A changed ignore source inside the declared scope is the node's own work:
+  // it is judged under the base rules instead of failing. Anything outside the
+  // scope still fails closed before scope matching.
+  if (changedIgnoreSources.some((path) => !isDeclaredScopePath(allowed, path))) {
+    throw ignoreSourcesChanged(before.ignoreSources, currentIgnoreSources);
   }
+  /** @type {WorkspaceSnapshot} */
+  const after = {
+    entries: changedIgnoreSources.length
+      ? captureWorkspaceEntriesUnderBaseRules(root, before.ignoreSources, changedIgnoreSources)
+      : captureWorkspaceEntries(root, relevantWorkspacePaths(root)),
+    ignoreSources: currentIgnoreSources,
+    truncated: false,
+  };
   const prior = new Map(before.entries.map((/** @type {SnapshotEntry} */ entry) => [entry.path, JSON.stringify(entry)]));
   const current = new Map(after.entries.map((/** @type {SnapshotEntry} */ entry) => [entry.path, JSON.stringify(entry)]));
   const changed = new Set();
@@ -142,6 +172,143 @@ export function compareWorkspaceSnapshot(before, cwd, scope = {}) {
     !directoryRoots.some((scopeRoot) => path === scopeRoot || path.startsWith(`${scopeRoot}/`)));
   return { after, changedPaths, unexpectedPaths };
 }
+/**
+ * Whether a workspace-relative path falls inside the captured scope boundary,
+ * using the same file-root versus directory-root rule as the entry comparison.
+ *
+ * @param {WorkspaceScopeBoundary} allowed
+ * @param {string} path
+ * @returns {boolean}
+ */
+function isDeclaredScopePath(allowed, path) {
+  const fileRoots = new Set(allowed.fileRoots ?? []);
+  if (allowed.files.includes(path) || fileRoots.has(path)) return true;
+  return allowed.roots.some((scopeRoot) => !fileRoots.has(scopeRoot) && (path === scopeRoot || path.startsWith(`${scopeRoot}/`)));
+}
+/**
+ * The ignore sources whose fingerprint moved between two snapshots.
+ *
+ * @param {SnapshotEntry[]} before
+ * @param {SnapshotEntry[]} after
+ * @returns {string[]}
+ */
+function changedSnapshotPaths(before, after) {
+  const prior = new Map(before.map((entry) => [entry.path, snapshotEntryKey(entry)]));
+  const current = new Map(after.map((entry) => [entry.path, snapshotEntryKey(entry)]));
+  return [...new Set([...prior.keys(), ...current.keys()])].filter((path) => prior.get(path) !== current.get(path)).sort();
+}
+/**
+ * The identity of a snapshot entry for comparison. `content` is deliberately
+ * excluded: it is only carried to replay base ignore rules, so a persisted
+ * snapshot captured before that field existed still compares equal.
+ *
+ * @param {SnapshotEntry} entry
+ * @returns {string}
+ */
+function snapshotEntryKey(entry) {
+  return JSON.stringify({ path: entry.path, kind: entry.kind, digest: entry.digest, size: entry.size });
+}
+/**
+ * The after entries for a declared ignore-source edit. Paths are enumerated
+ * with the ignore rules captured before the attempt, so a worker cannot edit a
+ * declared ignore file to hide a change the base rules would have shown. The
+ * changed sources are put back afterwards and hashed from their current
+ * content, so the edit itself still counts as a declared write.
+ *
+ * @param {string} root
+ * @param {SnapshotEntry[]} beforeIgnoreSources
+ * @param {string[]} changedIgnoreSources
+ * @returns {SnapshotEntry[]}
+ */
+function captureWorkspaceEntriesUnderBaseRules(root, beforeIgnoreSources, changedIgnoreSources) {
+  const beforeByPath = new Map(beforeIgnoreSources.map((entry) => [entry.path, entry]));
+  /** @type {{path: string, saved: ReplayableFileState}[]} */
+  const restorations = [];
+  /** @type {string[]} */
+  let paths = [];
+  try {
+    for (const path of changedIgnoreSources) {
+      const beforeEntry = beforeByPath.get(path);
+      if (beforeEntry !== undefined && typeof beforeEntry.content !== "string") continue;
+      const child = ignoreSourceAbsolutePath(root, path);
+      const saved = readReplayableFileState(child);
+      if (saved === undefined) continue;
+      restorations.push({ path: child, saved });
+      if (beforeEntry === undefined) removeReplayableFile(child);
+      else if (typeof beforeEntry.content === "string") writeReplayableFile(child, beforeEntry.content);
+    }
+    paths = relevantWorkspacePaths(root);
+  } finally {
+    for (const { path, saved } of restorations.reverse()) restoreReplayableFileState(path, saved);
+  }
+  const observable = new Set(paths);
+  // A source the worker created is new under the base rules, so the walk above
+  // cannot list it; the declared edit still has to appear as a write.
+  for (const path of changedIgnoreSources) {
+    if (!path.startsWith(".git/")) observable.add(path);
+  }
+  return captureWorkspaceEntries(root, [...observable].sort());
+}
+/** @typedef {{missing: true}|{missing: false, content: string, mode: number}} ReplayableFileState */
+/**
+ * @param {string} path
+ * @returns {ReplayableFileState|undefined} undefined when replay would be unsafe
+ */
+function readReplayableFileState(path) {
+  let metadata;
+  try {
+    metadata = lstatSync(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR") return { missing: true };
+    return undefined;
+  }
+  if (!metadata.isFile()) return undefined;
+  try {
+    return { missing: false, content: readFileSync(path, "utf8"), mode: metadata.mode };
+  } catch {
+    return undefined;
+  }
+}
+/** @param {string} path @param {string} content @returns {void} */
+function writeReplayableFile(path, content) {
+  writeFileSync(path, content);
+}
+/** @param {string} path @returns {void} */
+function removeReplayableFile(path) {
+  rmSync(path, { force: true });
+}
+/** @param {string} path @param {ReplayableFileState} saved @returns {void} */
+function restoreReplayableFileState(path, saved) {
+  if (saved.missing) {
+    rmSync(path, { force: true });
+    return;
+  }
+  writeFileSync(path, saved.content, { mode: saved.mode });
+}
+/**
+ * The on-disk file behind an ignore source. `.git/config` and
+ * `.git/info/exclude` may live outside the workspace in a linked worktree, so
+ * ask Git for their real path.
+ *
+ * @param {string} root
+ * @param {string} path
+ * @returns {string}
+ */
+function ignoreSourceAbsolutePath(root, path) {
+  if (path === ".git/config" || path === ".git/info/exclude") {
+    const name = path === ".git/config" ? "config" : "info/exclude";
+    try {
+      const value = execFileSync("git", gitArguments(["-C", root, "rev-parse", "--git-path", name]), {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+      if (value) return isAbsolute(value) ? value : resolve(root, value);
+    } catch {
+      // Fall through to the literal workspace path.
+    }
+  }
+  return resolve(root, path);
+}
 /**
  * Resolve a declared worker scope before an untrusted worker starts. The
  * returned paths are the literal declarations plus the contained target paths
@@ -295,9 +462,7 @@ export function isIgnoreSource(path) {
  * @returns {Error}
  */
 function ignoreSourcesChanged(before, after) {
-  const prior = new Map(before.map((entry) => [entry.path, JSON.stringify(entry)]));
-  const current = new Map(after.map((entry) => [entry.path, JSON.stringify(entry)]));
-  const changed = [...new Set([...prior.keys(), ...current.keys()])].filter((path) => prior.get(path) !== current.get(path)).sort();
+  const changed = changedSnapshotPaths(before, after);
   return fail("snapshot_ignore_changed", `workspace ignore sources changed during worker execution: ${changed.join(", ")}`);
 }
 
@@ -437,14 +602,24 @@ function captureIgnoreSources(root) {
       const bytes = Buffer.byteLength(relevant, "utf8");
       return [{ path, kind: "file", digest: `config:${createHash("sha256").update(relevant).digest("hex")}:${bytes}`, size: bytes }];
     }
-    return [{ path, kind: "file", digest: fileIdentity(child, metadata).digest, size: metadata.size }];
+    const identity = fileIdentity(child, metadata);
+    /** @type {SnapshotEntry} */
+    const entry = { path, kind: "file", digest: identity.digest, size: metadata.size };
+    if (metadata.size <= IGNORE_SOURCE_CONTENT_LIMIT) {
+      try {
+        entry.content = readFileSync(child, "utf8");
+      } catch {
+        // Content is only needed to replay base rules for a declared edit.
+      }
+    }
+    return [entry];
   };
   return [...paths].sort().flatMap(capturePath);
 }
 /** @param {SnapshotEntry[]} before @param {SnapshotEntry[]} after @returns {boolean} */
 function sameSnapshotEntries(before, after) {
   if (before.length !== after.length) return false;
-  return before.every((entry, index) => JSON.stringify(entry) === JSON.stringify(after[index]));
+  return before.every((entry, index) => snapshotEntryKey(entry) === snapshotEntryKey(after[index]));
 }
 /** @param {string} root @param {string[]} paths @returns {string[]} */
 function expandScopePaths(root, paths) {

package/src/report/campaign-brief.mjs

@@ -90,6 +90,10 @@ function renderIdentity(model) {
     `- Frozen plan: ${link(identity.planPath)}`,
     `- Plan digest: \`${identity.planDigest}\``,
     `- Contract digest: \`${identity.contractDigest}\``,
+    // R36: the effective mode the launch recorded on the run snapshot, read
+    // back here rather than re-derived from the contract; absent reads as the
+    // cross-vendor default.
+    `- Judge independence: \`${identity.judgeIndependence ?? "cross-vendor"}\``,
     `- Journal cursor: \`${identity.journalCursor}\``,
     `- Usage sample cutoff: \`${identity.usageSampleCutoff ?? "not recorded"}\``,
   ].join("\n");

package/src/report/message.mjs

@@ -24,6 +24,7 @@
  */
 import { renderStatusJson } from "./render.mjs";
 import { buildCampaignProgress, remainingEstimateMs } from "./progress.mjs";
+import { attemptCosts, retriesOutspendFirst } from "../run/usage.mjs";
 import { chooseLanguage, labelsFor } from "./locale.mjs";
 import { readNodeSnapshot } from "../run/node-store.mjs";
 import { campaignDir } from "../campaign/layout.mjs";
@@ -39,9 +40,11 @@ import { basename, dirname, join } from "node:path";
 /** @typedef {import("./render.mjs").RoleUsage} RoleUsage */
 /** @typedef {import("../notify/index.mjs").NotifyEvent} NotifyEvent */
 /** @typedef {import("./locale.mjs").Language} Language */
-/** @typedef {{campaignId: string, usage: {inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null}, roles: {worker: RoleUsage, judge: RoleUsage}, nodes: StatusPayloadNode[]}} Payload */
+/** @typedef {{attempt: number, costUsd: number|null}} AttemptCost */
+/** @typedef {StatusPayloadNode & {attemptCosts: AttemptCost[], retriesOutspendFirst: boolean}} MessageNode */
+/** @typedef {{campaignId: string, usage: {inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null}, roles: {worker: RoleUsage, judge: RoleUsage}, nodes: MessageNode[]}} Payload */
 /** @typedef {{id: string, goal: string|null, percentDone: number, nodesTotal: number, phasesDone: number, phasesTotal: number, costTotalUsd: number|null, elapsedMs: number|null, nextCommand: string|null}} CampaignSummary */
-/** @typedef {{runDir: string, runId: string, payload: Payload, objectives: Map<string, string|null>, snapshots: Map<string, Record<string, unknown>>, campaign: CampaignSummary|null, label: (key: string) => string, subject: StatusPayloadNode}} View */
+/** @typedef {{runDir: string, runId: string, payload: Payload, objectives: Map<string, string|null>, snapshots: Map<string, Record<string, unknown>>, campaign: CampaignSummary|null, label: (key: string) => string, subject: MessageNode}} View */
 
 /**
  * The message's byte ceiling. Measured 2026-09-21 on the live campaign's
@@ -105,6 +108,15 @@ export function renderRunProgress(runDir, event) {
   const runsDir = dirname(runDir);
   const objectives = readObjectives(runDir);
   const snapshots = new Map(payload.nodes.map((node) => [node.id, readSnapshotSafe(runDir, node.id)]));
+  // R31: the status payload's nodes carry their per-attempt cost, the same
+  // `usage.mjs` reader the campaign roll-up uses, so the message's text line
+  // can mark a node whose retries out-spent the first attempt without
+  // re-deriving the comparison here.
+  for (const node of payload.nodes) {
+    const snapshot = /** @type {import("../contract/index.mjs").NodeSnapshot} */ (/** @type {unknown} */ (snapshots.get(node.id) ?? {}));
+    node.attemptCosts = attemptCosts(snapshot);
+    node.retriesOutspendFirst = retriesOutspendFirst(snapshot);
+  }
   const campaign = campaignSummary(runsDir, payload.campaignId);
   const label = labelsFor(chooseLanguage(process.env, [campaign?.goal], journalTexts(runsDir, payload.campaignId), [...objectives.values()]));
   const subject = subjectNode(payload.nodes, event.nodeId ?? null);
@@ -130,7 +142,7 @@ function nodeTerminal(view) {
   const ending = QUIET_STATES.has(subject.status) && !SUCCESS.has(subject.status)
     ? label(subject.status === "running" ? "running" : "pending")
     : `${label(OUTCOME_LABEL[subject.status] ?? "doneIn")} ${shortSpan(subject)}`;
-  const headline = `${OUTCOME[subject.status] ?? "❔"} ${subject.id} · ${ending} · ${formatUsd(subject.costUsd)}${model}${error}`;
+  const headline = `${OUTCOME[subject.status] ?? "❔"} ${subject.id} · ${ending} · ${formatUsd(subject.costUsd)}${model}${error}${retryOutspendMark(subject)}`;
   const pad = padder(label, ["asked", "did", "proof"]);
   return [
     headline,
@@ -199,7 +211,7 @@ function attention(view) {
   const { subject, label, snapshots, objectives, runDir } = view;
   const snapshot = snapshots.get(subject.id) ?? {};
   const reason = subject.errorCode ?? subject.status;
-  const headline = `👀 ${subject.id} ${label("needsYou")} · ${reason} · ${label("attempt")} ${subject.attempt} · ${shortSpan(subject)} · ${formatUsd(subject.costUsd)}`;
+  const headline = `👀 ${subject.id} ${label("needsYou")} · ${reason} · ${label("attempt")} ${subject.attempt} · ${shortSpan(subject)} · ${formatUsd(subject.costUsd)}${retryOutspendMark(subject)}`;
   const pad = padder(label, ["why", "asked", "do"]);
   return [
     headline,
@@ -461,9 +473,10 @@ function workerSummary(snapshot) {
  * most recently settled node (a `run.terminal` event names the run, not a
  * node), else the run's first node.
  *
- * @param {StatusPayloadNode[]} nodes
+ * @template {{id: string, status: import("../contract/index.mjs").NodeStatus, updatedAt?: string|null}} T
+ * @param {T[]} nodes
  * @param {string|null} nodeId
- * @returns {StatusPayloadNode}
+ * @returns {T}
  */
 function subjectNode(nodes, nodeId) {
   const named = nodeId ? nodes.find((node) => node.id === nodeId) : undefined;
@@ -577,6 +590,24 @@ function formatUsd(value) {
   return `$${value.toFixed(2)}`;
 }
 
+/**
+ * R31's mark for a node's text line: when the attempts after the first
+ * together out-spend the first, the line says so and quotes both sides, so a
+ * reader sees the size of the overrun rather than only that one exists. Empty
+ * when the comparison cannot be made -- a single attempt, or an attempt on
+ * either side that is not fully priced -- because an unknown comparison is
+ * not a warning.
+ *
+ * @param {MessageNode} node
+ * @returns {string}
+ */
+function retryOutspendMark(node) {
+  if (!node.retriesOutspendFirst) return "";
+  const [first, ...retries] = node.attemptCosts;
+  const retryTotal = retries.reduce((total, entry) => total + /** @type {number} */ (entry.costUsd), 0);
+  return ` · ⚠️ retries out-spend the first attempt (${formatUsd(retryTotal)} vs ${formatUsd(/** @type {number} */ (first.costUsd))})`;
+}
+
 /** Whole dollars once a campaign passes a hundred: `$132`, not `$132.21`, in a footer. @param {number|null} value @returns {string} */
 function formatUsdCompact(value) {
   if (typeof value === "number" && Number.isFinite(value) && value >= 100) return `$${Math.round(value)}`;

package/src/report/progress.mjs

@@ -32,6 +32,7 @@
  */
 import { formatDuration, readRunUsage, renderStatusJson, roleUsage } from "./render.mjs";
 import { nodeSnapshotPath, readNodeSnapshot } from "../run/node-store.mjs";
+import { attemptCosts, retriesOutspendFirst } from "../run/usage.mjs";
 import { finite } from "../util.mjs";
 import { SETTLED, SUCCESS } from "../engine/prompts.mjs";
 import { campaignDir } from "../campaign/layout.mjs";
@@ -128,7 +129,7 @@ function campaignCumulativeCostUsd(runsDir, campaignId) {
 }
 
 /**
- * @typedef {{id: string, dependsOn: string[], status: string, attempt: number, workerRuntime: string|null, judgeRuntime: string|null, elapsedSpan: string|null, costUsd: number|null, runDir: string|null, workerLogPath: string|null, judgeLogPaths: string[], verificationRecordPath: string|null, attemptBranch: string|null, sealCommit: string|null}} RollupNode
+ * @typedef {{id: string, dependsOn: string[], status: string, attempt: number, workerRuntime: string|null, judgeRuntime: string|null, elapsedSpan: string|null, costUsd: number|null, attemptCosts: import("../run/usage.mjs").AttemptCost[], retriesOutspendFirst: boolean, runDir: string|null, workerLogPath: string|null, judgeLogPaths: string[], verificationRecordPath: string|null, attemptBranch: string|null, sealCommit: string|null}} RollupNode
  * `status` carries every `NodeStatus` plus two the manifest alone can
  * explain: `not_started` (the contract has no run yet) and `unreadable` (a
  * run exists but this node's own snapshot does not).
@@ -138,6 +139,10 @@ function campaignCumulativeCostUsd(runsDir, campaignId) {
  * three points), so a single `runtime` field reads as though the judge did
  * the worker's job. `judgeRuntime` is `null` for a node with no gate, or one
  * whose gate never ran -- never the worker's own runtime repeated.
+ * `attemptCosts` is the per-attempt cost R31 adds to the payload, derived
+ * from the snapshot's own invocations by the ledger's shared reader;
+ * `retriesOutspendFirst` is the flag that marks the notification's text line
+ * when those retries together cost more than the first attempt.
  */
 /**
  * `counts.done` and `counts.settled` are two different numbers: `done` is
@@ -411,7 +416,7 @@ function judgeRuntimeLabel(invocations) {
 function rollupNode(node, contractId, runDir, hasRun, settledCandidates, workerRuntimeById) {
   const id = String(node.id);
   const dependsOn = Array.isArray(node.dependsOn) ? node.dependsOn.map(String) : [];
-  const empty = { id, dependsOn, attempt: 0, workerRuntime: null, judgeRuntime: null, elapsedSpan: null, costUsd: null, workerLogPath: null, judgeLogPaths: /** @type {string[]} */ ([]), attemptBranch: null, sealCommit: null };
+  const empty = { id, dependsOn, attempt: 0, workerRuntime: null, judgeRuntime: null, elapsedSpan: null, costUsd: null, attemptCosts: /** @type {import("../run/usage.mjs").AttemptCost[]} */ ([]), retriesOutspendFirst: false, workerLogPath: null, judgeLogPaths: /** @type {string[]} */ ([]), attemptBranch: null, sealCommit: null };
   if (!hasRun) return { ...empty, status: "not_started", runDir: null, verificationRecordPath: null };
 
   let snapshot;
@@ -429,6 +434,10 @@ function rollupNode(node, contractId, runDir, hasRun, settledCandidates, workerR
     .map((invocation) => invocation.stdoutPath)
     .filter((path) => typeof path === "string");
   const worktree = snapshot.worktree && typeof snapshot.worktree === "object" ? /** @type {Record<string, unknown>} */ (snapshot.worktree) : null;
+  // The snapshot reader returns the raw persisted object; the ledger's
+  // per-attempt reader wants the validated shape, and only its `invocations`
+  // are read here.
+  const attemptState = /** @type {import("../contract/index.mjs").NodeSnapshot} */ (/** @type {unknown} */ (snapshot));
 
   return {
     id,
@@ -439,6 +448,8 @@ function rollupNode(node, contractId, runDir, hasRun, settledCandidates, workerR
     judgeRuntime: judgeRuntimeLabel(invocations),
     elapsedSpan: spanOf({ startedAt: typeof snapshot.startedAt === "string" ? snapshot.startedAt : null, updatedAt: typeof snapshot.updatedAt === "string" ? snapshot.updatedAt : null }),
     costUsd: typeof snapshot.costUsd === "number" ? snapshot.costUsd : null,
+    attemptCosts: attemptCosts(attemptState),
+    retriesOutspendFirst: retriesOutspendFirst(attemptState),
     runDir,
     workerLogPath: typeof worker?.stdoutPath === "string" ? worker.stdoutPath : null,
     judgeLogPaths,

package/src/run/paths.mjs

@@ -17,7 +17,7 @@
  * run, because answering the home side of a not-yet-migrated repository would
  * split its state across two layouts.
  */
-import { existsSync } from "node:fs";
+import { existsSync, rmSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { campaignDir, campaignsDir } from "../campaign/layout.mjs";
 import { faberunHome } from "../host/home.mjs";
@@ -134,6 +134,19 @@ export function runDirectory(cwd, runId) {
   return join(runsRoot(cwd), runId);
 }
 
+/**
+ * Remove one run's directory and everything under it. The caller owns the
+ * decision that the directory may go; keeping the erasure here means no other
+ * module re-derives `<runs>/<id>` to delete it and the layout stays in one
+ * place.
+ *
+ * @param {string} runDir
+ * @returns {void}
+ */
+export function removeRunDirectory(runDir) {
+  rmSync(runDir, { recursive: true, force: true });
+}
+
 /**
  * The live-preflight verdict store, at the top of the home. Whether a
  * provider answers is a fact about this machine and this operator -- the same

package/src/run/usage.mjs

@@ -8,7 +8,7 @@
  */
 import { appendJsonl, writeJsonAtomic } from "./store.mjs";
 import { basename, join } from "node:path";
-import { errorMessage, stableJson } from "../util.mjs";
+import { errorMessage, finite, stableJson } from "../util.mjs";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { liveUsage } from "../harnesses/session-metrics.mjs";
 
@@ -129,6 +129,71 @@ export function invocationCost(state) {
     .filter((cost) => typeof cost === "number" && Number.isFinite(cost)));
   return costs.length ? costs.reduce((total, cost) => total + cost, 0) : undefined;
 }
+/** @typedef {{attempt: number, costUsd: number|null}} AttemptCost */
+/**
+ * The cost of each attempt a node made, derived from the invocation ledger the
+ * snapshot already stores and nothing else: every invocation carrying the same
+ * `attempt` is one attempt, and its cost is the sum of the prices those
+ * invocations recorded. An attempt with any unpriced invocation reports `null`
+ * rather than a partial sum -- the same refusal `roleUsage` makes for a role,
+ * because dollars that are partly missing are not a total. An invocation that
+ * predates the `attempt` field is read as the first attempt rather than
+ * dropped.
+ *
+ * Attempts come back in the order they ran; a snapshot with no invocations
+ * yields an empty list, never a fabricated zero-attempt.
+ *
+ * @param {NodeSnapshot} state
+ * @returns {AttemptCost[]}
+ */
+export function attemptCosts(state) {
+  /** @type {Map<number, {costUsd: number, unpriced: number}>} */
+  const byAttempt = new Map();
+  for (const invocation of state.invocations ?? []) {
+    const attempt = typeof invocation.attempt === "number" && Number.isFinite(invocation.attempt) ? invocation.attempt : 1;
+    const bucket = byAttempt.get(attempt) ?? { costUsd: 0, unpriced: 0 };
+    const cost = finite(invocation.costUsd);
+    if (cost === null) bucket.unpriced += 1;
+    else bucket.costUsd += cost;
+    byAttempt.set(attempt, bucket);
+  }
+  return [...byAttempt.entries()]
+    .sort((left, right) => left[0] - right[0])
+    .map(([attempt, bucket]) => ({ attempt, costUsd: bucket.unpriced > 0 ? null : bucket.costUsd }));
+}
+/**
+ * The two sides of R31's comparison: the first attempt's cost and the sum of
+ * every attempt after it. `null` when they cannot be compared -- fewer than
+ * two attempts, or any attempt on either side is not fully priced -- so a
+ * caller never reads an invented number.
+ *
+ * @param {NodeSnapshot} state
+ * @returns {{firstCostUsd: number, retryCostUsd: number}|null}
+ */
+export function retryOutspend(state) {
+  const costs = attemptCosts(state);
+  if (costs.length < 2) return null;
+  const [first, ...retries] = costs;
+  if (first.costUsd === null || retries.some((entry) => entry.costUsd === null)) return null;
+  return {
+    firstCostUsd: first.costUsd,
+    retryCostUsd: retries.reduce((total, entry) => total + /** @type {number} */ (entry.costUsd), 0),
+  };
+}
+/**
+ * Whether the retries together out-spend the first attempt. The one predicate
+ * every surface shares -- the campaign payload and the notification's text
+ * line -- so a node that cost more to redo than to do is named the same way
+ * everywhere, against the first attempt's own recorded cost rather than a
+ * guessed threshold.
+ *
+ * @param {NodeSnapshot} state
+ * @returns {boolean}
+ */
+export function retriesOutspendFirst(state) {
+  const outspend = retryOutspend(state);
+  return outspend !== null && outspend.retryCostUsd > outspend.firstCostUsd;
+}
 /**
  * Invocation ids already present in the run's usage.jsonl. The append path
  * uses this to stay idempotent across resume and replay.

package/src/util.mjs

@@ -239,8 +239,13 @@ export function finite(value) {
  * outside them separates.
  *
  * Deliberately not a shell: no expansion, no substitution, no operators, and
- * no backslash escape -- on Windows a backslash is a path separator and
- * `C:\Users\x` must survive this intact. The question both callers ask is
+ * no backslash escape outside double quotes -- on Windows a backslash is a
+ * path separator and `C:\Users\x` must survive this intact. Inside double
+ * quotes a backslash before `"` or `\` is the escape POSIX gives it, and any
+ * other backslash stays literal, so a quoted Windows path is still intact.
+ * Measured 2026-09-27: a `node -e "<script with \"fs\">"` proof, the shape
+ * `JSON.stringify` writes, split at the escaped quote and read as a script
+ * that did not parse. The question both callers ask is
  * "which words does this command name", and a quoted path holding a space is
  * one word: splitting it on whitespace produced two fragments that matched no
  * file, so a proof naming a real path read as naming none.
@@ -255,6 +260,7 @@ export function shellWords(text) {
   let current = null;
   /** @type {string|null} */
   let quote = null;
+  let escaped = false;
   for (const character of text) {
     if (quote === null && /\s/u.test(character)) {
       if (current !== null) words.push(current);
@@ -266,12 +272,22 @@ export function shellWords(text) {
       current ??= "";
       continue;
     }
+    if (escaped) {
+      current = (current ?? "") + (character === '"' || character === "\\" ? character : `\\${character}`);
+      escaped = false;
+      continue;
+    }
+    if (quote === '"' && character === "\\") {
+      escaped = true;
+      continue;
+    }
     if (quote === character) {
       quote = null;
       continue;
     }
     current = (current ?? "") + character;
   }
+  if (escaped) current = `${current ?? ""}\\`;
   if (current !== null) words.push(current);
   return words;
 }