@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/ledger.mjs

@@ -38,6 +38,7 @@ export const KEY_LIMIT = 200;
 
 /** The classes a request is billed in, in the order a report prints them. */
 export const CLASSES = ["uncached", "written1h", "written5m", "writtenUnknown", "read", "output"];
+export const RECORDED_ROLES = ["implementer", "reviewer", "librarian", "supervisor", "local-worker"];
 
 export class LedgerError extends Error {
     constructor(message) {
@@ -84,33 +85,55 @@ export function mayHold(name, root) {
 }
 
 /** null for a record that is not an API response with usage; no content field is ever read. */
+export const INPUT_USAGE_MASK = 1 | 4 | 8;
+export const inputUnusable = r => Boolean((r.usageMissing & INPUT_USAGE_MASK) || (r.usageUnsafe & 1));
+
+export function usageOf(usage) {
+    const lifetimes = usage.cache_creation !== null && typeof usage.cache_creation === "object" ? usage.cache_creation : {};
+    const written1h = count(lifetimes.ephemeral_1h_input_tokens);
+    const written5m = count(lifetimes.ephemeral_5m_input_tokens);
+    const writeParts = (lifetimes.ephemeral_5m_input_tokens === undefined ? 0 : 1) | (lifetimes.ephemeral_1h_input_tokens === undefined ? 0 : 2);
+    const invalid = value => value !== undefined && (!Number.isSafeInteger(value) || value < 0);
+    const inputUnsafe = [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens, lifetimes.ephemeral_1h_input_tokens, lifetimes.ephemeral_5m_input_tokens].some(invalid) ||
+        !Number.isSafeInteger(count(usage.input_tokens) + Math.max(count(usage.cache_creation_input_tokens), written1h + written5m) + count(usage.cache_read_input_tokens)) ||
+        (usage.cache_creation_input_tokens !== undefined && count(usage.cache_creation_input_tokens) < written1h + written5m);
+    return {
+        usageMissing: (usage.input_tokens === undefined ? 1 : 0) | (usage.output_tokens === undefined ? 2 : 0) |
+            (usage.cache_read_input_tokens === undefined ? 4 : 0) | (usage.cache_creation_input_tokens === undefined && writeParts !== 3 ? 8 : 0),
+        usageUnsafe: (inputUnsafe ? 1 : 0) | (invalid(usage.output_tokens) ? 2 : 0),
+        writeTotal: Number.isSafeInteger(usage.cache_creation_input_tokens) && usage.cache_creation_input_tokens >= 0 ? usage.cache_creation_input_tokens : null,
+        writeParts,
+        uncached: count(usage.input_tokens),
+        written1h,
+        written5m,
+        writtenUnknown: Math.max(0, count(usage.cache_creation_input_tokens) - written1h - written5m),
+        read: count(usage.cache_read_input_tokens),
+        output: count(usage.output_tokens),
+    };
+}
+
 function requestOf(record) {
     if (record === null || typeof record !== "object" || record.type !== "assistant") return null;
     const message = record.message;
     if (message === null || typeof message !== "object") return null;
     const usage = message.usage;
     if (usage === null || typeof usage !== "object") return null;
-    // The host's own records, an interruption or an API error, with no request behind them.
+    // Synthetic host records have no request behind them.
     if (message.model === "<synthetic>") return { synthetic: true };
-    const lifetimes = usage.cache_creation !== null && typeof usage.cache_creation === "object" ? usage.cache_creation : {};
-    const written1h = count(lifetimes.ephemeral_1h_input_tokens);
-    const written5m = count(lifetimes.ephemeral_5m_input_tokens);
     const at = Date.parse(record.timestamp);
+    const roleParts = text(record.attributionAgent)?.split(":");
+    const role = roleParts?.every(part => /^[a-zA-Z0-9_-]+$/.test(part)) && RECORDED_ROLES.includes(roleParts.at(-1)) ? roleParts.at(-1) : null;
     return {
         id: text(message.id) ?? text(record.requestId) ?? text(record.uuid),
         model: text(message.model),
         effort: text(record.effort),
+        role,
+        ...usageOf(usage),
         branch: text(record.gitBranch),
         cwd: text(record.cwd),
         at: Number.isFinite(at) ? at : null,
         sidechain: record.isSidechain === true,
         agent: text(record.agentId),
-        uncached: count(usage.input_tokens),
-        written1h,
-        written5m,
-        writtenUnknown: Math.max(0, count(usage.cache_creation_input_tokens) - written1h - written5m),
-        read: count(usage.cache_read_input_tokens),
-        output: count(usage.output_tokens),
     };
 }
 
@@ -120,10 +143,63 @@ const writtenOf = (r) => r.written1h + r.written5m + r.writtenUnknown;
 
 const chainOf = (r) => (r.sidechain ? `agent:${r.agent ?? ""}` : "session");
 
+/** A whole-line local receipt is read wherever it appears. */
+const RECEIPT =
+    /^OK mode=([a-z]+) model=(\S+)(?: target=.+?)? attempts=([1-9]\d*) in=(?:(0|[1-9]\d*)t|\?) out=(?:(0|[1-9]\d*)t|\?) time=(?:(0|[1-9]\d*)ms|\?) rate=(?:(?:0|[1-9]\d*)(?:\.\d)?tok\/s|\?)(?: reasoning=(?:(0|[1-9]\d*)t|\?) cached-in=(?:(0|[1-9]\d*)t|\?))? spend=\$0\.00$/;
+
+/** A figure the runner printed as `?` is null, never 0. */
+export function receiptOf(line) {
+    const m = RECEIPT.exec(line);
+    if (m === null) return null;
+    const [attempts, input, output, time] = [m[3], m[4], m[5], m[6]].map((v) => (v === undefined ? null : Number(v)));
+    const [reasoning, cached] = [m[7], m[8]].map((v) => (v === undefined ? null : Number(v)));
+    if (![attempts, input, output, time, reasoning, cached].every((v) => v === null || Number.isSafeInteger(v))) return null;
+    if (reasoning !== null && (output === null || reasoning > output)) return null;
+    if (cached !== null && (input === null || cached > input)) return null;
+    return { mode: m[1], model: m[2], attempts, in: input, out: output, time };
+}
+
+/** The ids of the Bash calls a record makes: each block's type, name and id, and nothing it says. */
+function bashCallsOf(record) {
+    const content = record.message?.content;
+    if (!Array.isArray(content)) return [];
+    return content.filter((b) => b !== null && typeof b === "object" && b.type === "tool_use" && b.name === "Bash" && text(b.id) !== null).map((b) => b.id);
+}
+
+/** A tool result's output as the host writes it: a string, or text blocks and nothing else. */
+function outputOf(content) {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content) || !content.length || !content.every((b) => b?.type === "text" && typeof b.text === "string")) return null;
+    return content.map((b) => b.text).join("\n");
+}
+
+/** The receipts in a user record's tool results, each still to be matched to the Bash call it answers. */
+function resultsOf(record) {
+    if (record === null || typeof record !== "object" || record.type !== "user" || !Array.isArray(record.message?.content)) return [];
+    const at = Date.parse(record.timestamp);
+    const found = [];
+    for (const block of record.message.content) {
+        if (block === null || typeof block !== "object" || block.type !== "tool_result" || text(block.tool_use_id) === null) continue;
+        const receipts = (outputOf(block.content) ?? "").split("\n").map(receiptOf).filter((r) => r !== null);
+        if (!receipts.length) continue;
+        found.push({
+            call: block.tool_use_id,
+            receipts,
+            branch: text(record.gitBranch),
+            cwd: text(record.cwd),
+            at: Number.isFinite(at) ? at : null,
+            sidechain: record.isSidechain === true,
+            agent: text(record.agentId),
+        });
+    }
+    return found;
+}
+
 export function readLine(line) {
     const usageLike = line.includes('"usage":');
     const boundaryLike = line.includes('"compact_boundary"');
-    if (!usageLike && !boundaryLike) return null;
+    const resultLike = line.includes('"tool_result"') && line.includes("spend=$0.00");
+    if (!usageLike && !boundaryLike && !resultLike) return null;
     let record;
     try {
         record = JSON.parse(line);
@@ -134,16 +210,25 @@ export function readLine(line) {
         return { boundary: true, sidechain: record.isSidechain === true, agent: text(record.agentId) };
     }
     const request = requestOf(record);
-    return request === null ? null : { request };
+    if (request !== null) {
+        const calls = bashCallsOf(record);
+        return calls.length ? { request, calls } : { request };
+    }
+    const results = resultLike ? resultsOf(record) : [];
+    return results.length ? { results } : null;
 }
 
 /** Claude Code 2.1.280, undocumented: one record per content block, so one request per message id. */
-export function readTranscript(file) {
-    const source = fs.readFileSync(file, "utf8");
+export function readTranscript(file, { end = null } = {}) {
+    const bytes = fs.readFileSync(file, end === null ? "utf8" : undefined);
+    if (end !== null && (!Number.isSafeInteger(end) || end < 0 || end > bytes.length)) throw new LedgerError("the bounded transcript snapshot changed");
+    const source = end === null ? bytes : bytes.subarray(0, end).toString("utf8");
     const byId = new Map();
     const requests = [];
     const tally = { records: 0, duplicates: 0, malformed: 0, synthetic: 0, compactions: 0 };
-    const figures = sessionFigures();
+    let parentCompactions = 0;
+    const calls = new Set();
+    const receipts = [];
     // Compacted contexts awaiting their next request, by chain, so a subagent's compaction is never the session's.
     const awaiting = new Set();
     for (const line of source.split("\n")) {
@@ -154,13 +239,23 @@ export function readTranscript(file) {
             tally.malformed += 1;
             continue;
         }
-        foldFigures(figures, read);
+        if (read.results) {
+            // Only a Bash result is read for the format: an agent's report quoting a receipt is no second one.
+            for (const result of read.results) {
+                if (!calls.has(result.call)) continue;
+                const { call, receipts: lines, ...where } = result;
+                lines.forEach((receipt, i) => receipts.push({ key: `${call}#${i}`, ...receipt, ...where }));
+            }
+            continue;
+        }
         if (read.boundary) {
+            if (!read.sidechain) parentCompactions += 1;
             tally.compactions += 1;
             awaiting.add(chainOf(read));
             continue;
         }
         const request = read.request;
+        for (const id of read.calls ?? []) calls.add(id);
         tally.records += 1;
         if (request.synthetic) {
             tally.synthetic += 1;
@@ -168,16 +263,27 @@ export function readTranscript(file) {
         }
         const prior = request.id === null ? undefined : byId.get(request.id);
         if (prior !== undefined) {
-            // The host writes a request again per content block, and its output count may grow: keep each largest.
+            // Merge growing block counters; unclassified writes remain the residual of the reported total.
             tally.duplicates += 1;
             for (const c of CLASSES) prior[c] = Math.max(prior[c], request[c]);
+            prior.usageMissing &= request.usageMissing;
+            prior.writeParts |= request.writeParts;
+            prior.usageUnsafe |= request.usageUnsafe;
+            if (request.writeTotal !== null) prior.writeTotal = Math.max(prior.writeTotal ?? 0, request.writeTotal);
+            if (prior.writeTotal !== null || prior.writeParts === 3) prior.usageMissing &= ~8;
+            if (prior.writeTotal !== null) prior.writtenUnknown = Math.max(0, prior.writeTotal - prior.written1h - prior.written5m);
+            if (!Number.isSafeInteger(contextOf(prior)) || (prior.writeTotal !== null && prior.written1h + prior.written5m > prior.writeTotal)) prior.usageUnsafe |= 1;
             continue;
         }
         if (request.id !== null) byId.set(request.id, request);
         request.compacted = awaiting.delete(chainOf(request));
         requests.push(request);
     }
-    return { requests, figures, ...tally };
+    const figures = sessionFigures();
+    for (const r of requests) foldCanonical(figures, r);
+    figures.compactions = parentCompactions;
+    figures.pending = awaiting.has("session");
+    return { requests, receipts, figures, ...tally };
 }
 
 /** The lifetime a request's writes used, or null where it wrote nothing it named. */
@@ -212,7 +318,7 @@ export function markRebuilds(requests) {
     return requests;
 }
 
-/** Latest request ids remembered to pass over repeats: the host writes a request's blocks back to back. */
+/** Hot IDs only; raw streams need canonical confirmation. */
 const RECENT = 16;
 
 /** Every field JSON-safe: `./advisory.mjs` keeps these between calls and folds in only the lines since. */
@@ -229,8 +335,12 @@ export function foldFigures(figures, read) {
     }
     const r = read.request;
     if (r === undefined || r.synthetic || r.sidechain) return figures;
+    if (r.id !== null && figures.recent.includes(r.id)) return figures;
+    return foldUniqueRequest(figures, r);
+}
+
+function foldUniqueRequest(figures, r) {
     if (r.id !== null) {
-        if (figures.recent.includes(r.id)) return figures;
         figures.recent.push(r.id);
         if (figures.recent.length > RECENT) figures.recent.shift();
     }
@@ -247,11 +357,18 @@ export function foldFigures(figures, read) {
     return figures;
 }
 
+export function foldCanonical(figures, r) {
+    if (r.synthetic || r.sidechain) return figures;
+    if (r.compacted) { figures.compactions += 1; figures.pending = true; }
+    return foldUniqueRequest(figures, r);
+}
+
 /** Each test is the one `./doctor.mjs` applies to the same key, so a manifest `doctor` passes is one these take. */
 export const SPEND_FIGURES = {
     read: { holds: (v) => Number.isFinite(v) && v > 0 && v <= 1, is: "a number above 0 and at most 1" },
     write: { holds: (v) => Number.isFinite(v) && v >= 1, is: "a number of at least 1" },
     requests: { holds: (v) => Number.isInteger(v) && v > 0, is: "a positive integer" },
+    resume: { holds: (v) => Number.isFinite(v) && v >= 0, is: "a finite nonnegative number of input-equivalent tokens" },
 };
 
 /** What a crossed restart threshold does: `"advise"` says the line; `"block"` also holds the turn's end once. */
@@ -263,7 +380,7 @@ export function overflowingWrite({ read, write }) {
 
 /** Each part null where undeclared; throws at the first fault, since no reader may rely on `doctor` having run. */
 export function readSpend(value, where) {
-    if (value === undefined) return { multipliers: null, horizon: null, restart: null };
+    if (value === undefined) return { multipliers: null, horizon: null, restart: null, resume: null };
     const refuse = (what) => new LedgerError(`\`spend\` in ${where} ${what}; ../spec/slots.md gives its shape, and \`doctor\` names every finding`);
     const code = (key) => `\`${key}\``;
     const shaped = (v, at, keys, allRequired) => {
@@ -278,7 +395,7 @@ export function readSpend(value, where) {
         if (!SPEND_FIGURES[range].holds(v)) throw refuse(`${at}sets ${code(key)} to ${JSON.stringify(v)}, which is not ${SPEND_FIGURES[range].is}`);
         return v;
     };
-    shaped(value, "", ["multipliers", "horizon", "restart"], false);
+    shaped(value, "", ["multipliers", "horizon", "restart", "resume"], false);
     let multipliers = null;
     if (value.multipliers !== undefined) {
         const m = shaped(value.multipliers, "at `multipliers` ", ["read", "write"], true);
@@ -290,7 +407,8 @@ export function readSpend(value, where) {
     }
     const horizon = value.horizon === undefined ? null : figure(shaped(value.horizon, "at `horizon` ", ["requests"], true).requests, "at `horizon` ", "requests", "requests");
     if (value.restart !== undefined && !RESTARTS.includes(value.restart)) throw refuse(`sets \`restart\` to ${JSON.stringify(value.restart)}, which is neither ${RESTARTS.map((r) => `"${r}"`).join(" nor ")}`);
-    return { multipliers, horizon, restart: value.restart ?? null };
+    const resume = value.resume === undefined ? null : figure(shaped(value.resume, "at `resume` ", ["tokens"], true).tokens, "at `resume` ", "tokens", "resume");
+    return { multipliers, horizon, restart: value.restart ?? null, resume };
 }
 
 export function multipliers({ declared = null, lifetime = null } = {}) {
@@ -300,11 +418,14 @@ export function multipliers({ declared = null, lifetime = null } = {}) {
     return { read: GENERAL_READ, write: WRITE_BY_LIFETIME[at], lifetime: at, recorded, source: "undeclared" };
 }
 
-/** `C* ≈ F × (1 + m_w / (n × m_r))`, in whole tokens. */
-export function restartThreshold({ fresh, write, read, horizon = HORIZON }) {
+/** Break-even context including additional resume expense; display rounding never decides profitability. */
+export function restartThreshold({ fresh, write, read, horizon = HORIZON, resume = 0 }) {
     if (!(fresh > 0 && write > 0 && read > 0 && horizon > 0)) throw new LedgerError("a restart threshold needs a fresh context, both multipliers and a horizon, each above zero");
-    const threshold = Math.round(fresh * (1 + write / (horizon * read)));
-    if (!Number.isFinite(threshold)) throw new LedgerError(`the restart threshold ${fresh} × (1 + ${write} / (${horizon} × ${read})) overflows, so these multipliers give none`);
+    if (!SPEND_FIGURES.resume.holds(resume)) throw new LedgerError("resume expense must be finite and nonnegative");
+    const reads = horizon * read;
+    const expense = fresh * write + resume;
+    const threshold = Math.ceil(fresh + expense / reads);
+    if (![reads, expense, threshold].every(Number.isFinite)) throw new LedgerError(`the restart threshold ${fresh} × (1 + ${write} / (${horizon} × ${read})) with resume expense ${resume} overflows, so these figures give none`);
     return threshold;
 }
 
@@ -315,16 +436,33 @@ export function describeMultipliers(m) {
     return `multipliers undeclared: the general read ${m.read}× and the ${m.write}× of ${at}`;
 }
 
+export function restartSaving({ fresh, context, horizon, read, write, resume = 0 }) {
+    const gross = horizon * read * (context - fresh);
+    const written = write * fresh;
+    const saving = gross - written - resume;
+    if (![gross, written, resume, saving].every(Number.isFinite)) throw new LedgerError("the estimated restart saving overflows, so no comparison is usable");
+    // Eight rounding units at the largest operand bound these products and subtractions, without a fixed cost margin.
+    const error = Math.max(Math.abs(gross), Math.abs(written), Math.abs(resume)) * Number.EPSILON * 8;
+    return Math.abs(saving) <= error ? 0 : saving;
+}
+
 /** null with no request yet, or none since the last compaction: the context held is the one it replaced. */
-export function figureOf(figures, { declared = null, horizon = HORIZON } = {}) {
+export function figureOf(figures, { declared = null, horizon = null, resume = null } = {}) {
     if (figures.fresh === null || figures.pending || figures.fresh === 0) return null;
     const m = multipliers({ declared, lifetime: figures.freshLifetime ?? figures.lifetime });
-    const threshold = restartThreshold({ fresh: figures.fresh, write: m.write, read: m.read, horizon });
-    return { fresh: figures.fresh, context: figures.last, threshold, horizon, multipliers: m, compactions: figures.compactions, requests: figures.requests };
+    const n = horizon ?? HORIZON;
+    const threshold = restartThreshold({ fresh: figures.fresh, write: m.write, read: m.read, horizon: n, resume: resume ?? 0 });
+    const saving = restartSaving({ fresh: figures.fresh, context: figures.last, horizon: n, read: m.read, write: m.write, resume: resume ?? 0 });
+    return { fresh: figures.fresh, context: figures.last, threshold, horizon: n, horizonDeclared: horizon !== null, resume, saving, multipliers: m, compactions: figures.compactions, requests: figures.requests };
 }
 
 export function thresholdFor(transcript, options = {}) {
-    return figureOf(transcript.figures, options);
+    const main = transcript.requests?.filter(r => !r.sidechain) ?? [];
+    if (!main.length) return figureOf(transcript.figures, options);
+    const first = main[Math.max(0, main.findLastIndex(r => r.compacted))], last = main.at(-1);
+    if ([first, last].some(inputUnusable)) return { unavailable: "usage" };
+    const lifetime = main.findLast(r => lifetimeOf(r) !== null);
+    return figureOf({ ...transcript.figures, fresh: contextOf(first), last: contextOf(last), freshLifetime: lifetimeOf(first), lifetime: lifetime ? lifetimeOf(lifetime) : null }, options);
 }
 
 function listDir(dir) {
@@ -375,6 +513,8 @@ export function collect({ projects, roots }) {
     const contexts = [];
     const tally = { files: 0, records: 0, duplicates: 0, malformed: 0, synthetic: 0 };
     const seen = new Set();
+    const receipts = [];
+    const seenReceipts = new Set();
     for (const entry of transcriptFiles(projects, roots)) {
         let transcript;
         try {
@@ -400,8 +540,13 @@ export function collect({ projects, roots }) {
             tally.duplicates += inside.length - kept.length;
             if (kept.length) contexts.push({ file: entry.file, session: entry.session, agent, requests: kept, transcript: agent === null ? transcript : null });
         }
+        for (const r of transcript.receipts) {
+            if (!insideAny(r.cwd, roots) || seenReceipts.has(r.key)) continue;
+            seenReceipts.add(r.key);
+            receipts.push({ ...r, session: entry.session, agent: entry.agent ?? (r.sidechain ? `inline:${r.agent ?? "unnamed"}` : null) });
+        }
     }
-    return { contexts, ...tally };
+    return { contexts, receipts, ...tally };
 }
 
 const zero = () => ({ requests: 0, uncached: 0, written1h: 0, written5m: 0, writtenUnknown: 0, read: 0, output: 0 });
@@ -451,6 +596,20 @@ export function tally(contexts, branch) {
     };
 }
 
+/** What the lines in the receipt format on `branch` say, apart from every host figure: each null where none reported it. */
+export function tallyLocal(receipts, branch) {
+    const own = receipts.filter((r) => r.branch === branch);
+    const figure = (k) => (own.some((r) => r[k] !== null) ? own.reduce((sum, r) => sum + (r[k] ?? 0), 0) : null);
+    return {
+        receipts: own.length,
+        sessions: new Set(own.map((r) => r.session)).size,
+        in: figure("in"),
+        out: figure("out"),
+        time: figure("time"),
+        unreported: Object.fromEntries(["in", "out", "time"].map((k) => [k, own.filter((r) => r[k] === null).length])),
+    };
+}
+
 function sessionTotals(contexts) {
     const by = new Map();
     for (const c of contexts) {
@@ -572,35 +731,54 @@ export function ledger({ projects, config, roots, branch, lines = null, spend =
     const figures = tally(collected.contexts, branch);
     const host = config === null ? [] : compareHost(collected.contexts, hostTotals(config, roots));
     const latest = latestSession(collected.contexts, branch);
-    const priced = { declared: spend.multipliers, horizon: spend.horizon ?? HORIZON };
-    const restart = latest === null ? null : { session: latest.session, ...thresholdFor(latest.transcript, priced) };
-    return { projects, roots, branch, collected, figures, host, restart, lines, priced };
+    const priced = { declared: spend.multipliers, horizon: spend.horizon ?? null, resume: spend.resume ?? null };
+    const last = latest?.transcript.requests.findLast(r => !r.sidechain);
+    const restart = latest === null ? null : last?.branch !== branch || !latest.requests.includes(last)
+        ? { session: latest.session, unavailable: "branch-scope" }
+        : { session: latest.session, ...thresholdFor(latest.transcript, priced) };
+    const local = tallyLocal(collected.receipts, branch);
+    return { projects, roots, branch, collected, figures, local, host, restart, lines, priced };
 }
 
 const signed = (n) => (n > 0 ? `+${grouped(n)}` : n < 0 ? `−${grouped(-n)}` : "0");
 
 const short = (id) => id.slice(0, 8);
 
-function unjudged({ declared, horizon } = { declared: null, horizon: HORIZON }) {
+function unjudged({ declared, horizon, resume = null } = { declared: null, horizon: null }) {
     const m = declared ?? { read: GENERAL_READ, write: WRITE_BY_LIFETIME };
     return (
         "  restart: no session on this branch has a request with a time to judge; a threshold would take a horizon of " +
-        `${horizon} requests and ${declared === null ? "the general multipliers, undeclared" : "the declared multipliers"}: ` +
-        `read ${m.read}×, writes ${m.write["5m"]}× for five minutes and ${m.write["1h"]}× for an hour`
+        `${horizon ?? HORIZON} requests (${horizon === null ? "default" : "declared"}) and ${declared === null ? "the general multipliers, undeclared" : "the declared multipliers"}: ` +
+        `read ${m.read}×, writes ${m.write["5m"]}× for five minutes and ${m.write["1h"]}× for an hour; ${resume === null ? "resume cost unknown" : `resume expense ${resume} input-equivalent tokens`}`
+    );
+}
+
+function localLine({ local: l, branch }) {
+    if (l.receipts === 0) return `  local worker: no line in the runner's receipt format on ${branch} is recorded here`;
+    const figure = (k, unit) => {
+        if (l[k] === null) return `${k} unreported`;
+        return `${k} ${grouped(l[k])} ${unit}${l.unreported[k] ? ` (${grouped(l.unreported[k])} receipt(s) did not report it)` : ""}`;
+    };
+    return (
+        `  local worker: ${grouped(l.receipts)} line(s) in the runner's receipt format, from Bash results in ${grouped(l.sessions)} session(s), at $0.00, none of it in the host's tokens or the restart threshold: ` +
+        `${figure("in", "tokens")}, ${figure("out", "tokens")}, ${figure("time", "ms")}`
     );
 }
 
 export function print(report, say) {
     const { collected, figures: f, host, restart, lines, priced } = report;
-    say(`ledger: branch ${report.branch} — what this change spent, from Claude Code's own usage records (numbers only: nothing a context said is read)`);
+    say(`ledger: branch ${report.branch} — what this change spent, from Claude Code's own usage records (numbers only: nothing a context said is read but a line in the runner's receipt format in a Bash result)`);
     say(`  worktrees: ${report.roots.join(", ")}`);
     say(
         `  read: ${grouped(collected.files)} transcript(s) under ${report.projects}, ${grouped(collected.records)} usage record(s): ` +
             `${grouped(collected.duplicates)} per-block duplicate(s) counted once, ${grouped(collected.synthetic)} host-written record(s) with no request behind them, ` +
             `${grouped(collected.malformed)} line(s) that did not parse`,
     );
+    const uncertain = (collected.contexts ?? []).reduce((n, c) => n + c.requests.filter(r => r.usageMissing || r.usageUnsafe).length, 0);
+    if (uncertain) say(`  usage: ${grouped(uncertain)} owned request(s) have missing or invalid counters; totals are partial, sanitized zeros are not known observations`);
     if (f.main.requests + f.subagents.requests === 0) {
         say(`  no request on ${report.branch} is recorded here`);
+        say(localLine(report));
         say(unjudged(priced));
         return;
     }
@@ -613,6 +791,7 @@ export function print(report, say) {
     row("written, unstated", "writtenUnknown");
     row("read", "read");
     row("output", "output");
+    say(localLine(report));
     say(`  contexts opened: ${grouped(f.sessions + f.subagentContexts)} (${grouped(f.sessions)} session(s), ${grouped(f.subagentContexts)} subagent(s)); compactions: ${grouped(f.compactions)}`);
     say(`  largest context: ${grouped(f.largest)} tokens`);
     if (f.hitRate === null) say("  hit rate: none — no input was recorded, so none could be read from cache");
@@ -629,6 +808,14 @@ export function print(report, say) {
         const parts = ["uncached", "written", "read", "output"].map((k) => `${k} ${grouped(h.ledger[k])} of ${grouped(h.host[k])} (${signed(h.difference[k])})`);
         say(`  host totals, session ${short(h.session)} (the last the host saved for ${h.cwd}, every branch): ${parts.join(", ")}`);
     }
+    if (restart?.unavailable === "branch-scope") {
+        say("  restart: comparison unavailable — the latest session's main request is outside this branch's owned scope");
+        return;
+    }
+    if (restart?.unavailable === "usage") {
+        say("  restart: comparison unavailable — input usage counters are invalid or incomplete");
+        return;
+    }
     if (restart === null || restart.threshold === undefined) {
         say(unjudged(priced));
         return;
@@ -637,7 +824,9 @@ export function print(report, say) {
     say(
         `  restart: session ${short(restart.session)} is at ${grouped(restart.context)} tokens and ` +
             `${restart.context >= restart.threshold ? "has reached" : "is below"} its threshold of ${grouped(restart.threshold)} = ` +
-            `${grouped(restart.fresh)} × (1 + ${m.write} / (${restart.horizon} × ${m.read})); ${describeMultipliers(m)}`,
+            `${grouped(restart.fresh)} × (1 + ${m.write} / (${restart.horizon} × ${m.read})) + ${restart.resume ?? 0} / (${restart.horizon} × ${m.read}); ${describeMultipliers(m)}; ` +
+            `horizon ${restart.horizon} requests remaining (${restart.horizonDeclared ? "declared" : "default"}); ` +
+            `${restart.resume === null ? "resume cost unknown: threshold is a lower bound" : `resume expense ${restart.resume} input-equivalent tokens; estimated saving ${restart.saving}`}`,
     );
 }
 
@@ -665,6 +854,7 @@ export function pinned(report) {
         rebuilt: f.rebuilt,
         causes: f.causes,
         host: report.host.map((h) => ({ session: h.session, difference: h.difference })),
+        local: report.local,
         threshold: report.restart?.threshold ?? null,
     };
 }