@bongos/core 1.19.443 → 1.19.445

package/scripts/gds/session-digest-build.js

@@ -87,6 +87,16 @@ const UNATTRIBUTED_MODEL = 'claude-opus-4-8';
 function buildSessionDigest(entries, opts = {}) {
   const extra = opts.extraSecrets || [];
   const MAX_TURNS = opts.maxTurns || 4000;
+  // usageOnly — build the token metrics but no `detail`. For the callers that
+  // want ONLY a transcript's model_usage (the subagents-subtree fold, task
+  // 1003435), where the per-turn rows would be discarded anyway and the snippet
+  // scrubbing is the expensive part. It exists so that fold can reuse THIS
+  // function — the one place the token semantics live — instead of a second copy
+  // that could drift, without paying for output nobody reads. The waste is worth
+  // avoiding on both upload paths, and on the SessionEnd one it is load-bearing:
+  // that hook runs under a 6-second watchdog, so a slow pass there doesn't just
+  // cost time, it drops the upload.
+  const usageOnly = opts.usageOnly === true;
   const seenMessageIds = new Set();
   const m = {
     assistant_turns: 0,
@@ -165,15 +175,17 @@ function buildSessionDigest(entries, opts = {}) {
           }
         }
       }
-      const row = { i, role: 'assistant', ts, in: tin, out: tout, cache_read: tcr, cache_creation: tcc };
-      // Marks a line that shares its API call with an earlier one, so a reader
-      // can tell a genuinely-zero-usage turn from a de-duplicated repeat.
-      if (dupUsage) row.dup = 1;
-      if (tools.length) row.tools = tools;
-      if (textLen) row.text_len = textLen;
-      const snip = snippetOf(firstText, extra);
-      if (snip) row.snippet = snip;
-      detail.push(row);
+      if (!usageOnly) {
+        const row = { i, role: 'assistant', ts, in: tin, out: tout, cache_read: tcr, cache_creation: tcc };
+        // Marks a line that shares its API call with an earlier one, so a reader
+        // can tell a genuinely-zero-usage turn from a de-duplicated repeat.
+        if (dupUsage) row.dup = 1;
+        if (tools.length) row.tools = tools;
+        if (textLen) row.text_len = textLen;
+        const snip = snippetOf(firstText, extra);
+        if (snip) row.snippet = snip;
+        detail.push(row);
+      }
       i++;
     } else if (e.type === 'user' && msg) {
       m.user_turns++;
@@ -206,13 +218,15 @@ function buildSessionDigest(entries, opts = {}) {
           }
         }
       }
-      const row = { i, role: 'user', ts };
-      if (results) row.tool_results = results;
-      if (errors) row.tool_errors = errors;
-      if (harnessRetries) row.harness_retries = harnessRetries;
-      const snip = snippetOf(firstResult, extra);
-      if (snip) row.snippet = snip;
-      detail.push(row);
+      if (!usageOnly) {
+        const row = { i, role: 'user', ts };
+        if (results) row.tool_results = results;
+        if (errors) row.tool_errors = errors;
+        if (harnessRetries) row.harness_retries = harnessRetries;
+        const snip = snippetOf(firstResult, extra);
+        if (snip) row.snippet = snip;
+        detail.push(row);
+      }
       i++;
     }
   }
@@ -258,4 +272,22 @@ function buildSessionDigest(entries, opts = {}) {
     detail: boundedDetail,
   };
 }
-module.exports = { snippetOf, buildSessionDigest, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL };
+// mergeModelUsage — fold one model_usage map into another, in place, so a
+// session's tokens can be summed across the several transcripts one session
+// actually writes (the interactive thread + its subagent subtree — task
+// 1003435). PURE apart from mutating `target`, which the caller owns. The four
+// buckets are the session_records model_usage shape, NOT the transcript
+// *_input_tokens shape; keep them in step with buildSessionDigest above.
+function mergeModelUsage(target, addition) {
+  for (const [model, u] of Object.entries(addition || {})) {
+    const bucket = target[model] || (target[model] =
+      { input: 0, output: 0, cache_read: 0, cache_creation: 0 });
+    bucket.input += Number(u && u.input) || 0;
+    bucket.output += Number(u && u.output) || 0;
+    bucket.cache_read += Number(u && u.cache_read) || 0;
+    bucket.cache_creation += Number(u && u.cache_creation) || 0;
+  }
+  return target;
+}
+
+module.exports = { snippetOf, buildSessionDigest, mergeModelUsage, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL };

package/scripts/gds/session-digest.js

@@ -34,7 +34,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { cliClient, loadSession, arg } = require('./cli-lib');
-const { buildSessionDigest, collectEnvSecrets } = require('./ship');
+const { buildSessionDigest, collectEnvSecrets, foldSubagentUsage } = require('./ship');
 
 
 // Claude Code encodes a project transcript dir by replacing every non-alnum
@@ -144,6 +144,10 @@ async function main() {
     if (session.token) extraSecrets.push(session.token);
 
     const digest = buildSessionDigest(parseTranscript(transcriptPath), { extraSecrets });
+    // task 1003435: fold this session's subagents subtree into model_usage, the
+    // same way the on-ship upload does — the whole session's tokens, not just the
+    // interactive thread's.
+    foldSubagentUsage(digest, transcriptPath, sessionId);
 
     // task_ids:[] — the server upsert UNIONs task_ids, so the on-ship task
     // attribution is preserved; this end-of-session upload's job is to refresh
@@ -157,6 +161,12 @@ async function main() {
       ended_at: digest.endedAt,
       detail: digest.detail,
       metrics: digest.metrics,
+      // model_usage is its OWN column, and the upsert overwrites it from the
+      // body — so omitting it here (as this hook did until task 1003435) wiped
+      // the map the on-ship upload had just stored, leaving the reward with
+      // nothing to price. It is the LAST upload of the session, so it must carry
+      // the fullest picture, not the emptiest.
+      model_usage: digest.metrics.model_usage || {},
     };
     const api = await cliClient({ allowUnauthenticated: true });
     const r = await api.sessions.postSessions({ body: payload });

package/scripts/gds/ship-session-upload.js

@@ -43,9 +43,16 @@ const {
 // shared with session-digest.js. Re-exported below so this file's public surface
 // and tests/session_records.mjs are unchanged.
 const {
-  snippetOf, buildSessionDigest, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL,
+  snippetOf, buildSessionDigest, mergeModelUsage, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL,
 } = require('./session-digest-build');
 
+// The subagent subtree walker + the grader-transcript signature live in
+// session-cost.js, which already prices that subtree for the SPEND ledger. The
+// reward reads the same tokens, so it must use the SAME two definitions or the
+// two ledgers describe different sessions (task 1003435). session-cost.js guards
+// its own entry point behind require.main, so importing it is side-effect free.
+const { listJsonlRecursive, looksLikeGraderTranscript } = require('./session-cost.js');
+
 
 // classifyUploadSkip — PURE decision for whether the session upload must skip,
 // and the clear, actionable reason why. Separated from I/O so it is unit-tested
@@ -109,6 +116,94 @@ function recordUploadSkip(taskId, { code, reason }, opts = {}) {
   }
 }
 
+// parseJsonl — one transcript file's text into parsed entries, skipping any
+// malformed line (best-effort, exactly like the rest of this path).
+function parseJsonl(raw) {
+  const entries = [];
+  for (const line of String(raw || '').split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      entries.push(JSON.parse(t));
+    } catch (_) {
+      /* skip a malformed line — best-effort */
+    }
+  }
+  return entries;
+}
+
+// subagentModelUsage — the per-model TOKEN counts this session's ad-hoc
+// subagents burned, so the cost-plus reward (ADR 0054) can see them.
+//
+// WHY (task 1003435): Agent/Task-tool spawns persist in a sibling subtree,
+// <project-dir>/<session-id>/subagents/*.jsonl — never in the main transcript.
+// session-cost.js already prices that subtree into a `session:subagent` cost_log
+// row, so the SPEND ledger sees it; the digest read one file, so the REWARD did
+// not. That paid a builder who follows CLAUDE.md's "delegate freely" less than
+// one who did identical work in the main thread, and made the two ledgers
+// disagree about the same session.
+//
+// Grader transcripts are excluded BY SIGNATURE, not by location: a grader run
+// can nest inside a subagents/ dir, and its cost is already captured via the
+// worker envelope, so pricing it here would double-count (the ADR 0028
+// invariant). Each file goes through buildSessionDigest so the token semantics —
+// dedup by message.id, skip `<synthetic>`, fold unlabeled turns into a priceable
+// bucket — are the ONE implementation, never a second one that can drift.
+function subagentModelUsage(sessionDir) {
+  const modelUsage = {};
+  let files = 0;
+  let tokens = 0;
+  let graderSkipped = 0;
+  for (const f of listJsonlRecursive(sessionDir)) {
+    if (looksLikeGraderTranscript(f)) { graderSkipped++; continue; }
+    let digest;
+    try {
+      digest = buildSessionDigest(parseJsonl(fs.readFileSync(f, 'utf8')), { usageOnly: true });
+    } catch (_) {
+      continue; // an unreadable subagent file must never fail a ship
+    }
+    if (!(digest.totalTokens > 0)) continue;
+    files++;
+    tokens += digest.totalTokens;
+    mergeModelUsage(modelUsage, digest.metrics.model_usage);
+  }
+  return { modelUsage, files, tokens, graderSkipped };
+}
+
+// foldSubagentUsage — add the session's subagent tokens to `digest`'s
+// model_usage, IN PLACE, and record what was folded.
+//
+// model_usage ONLY, deliberately (task 1003435). model_usage is the reward's
+// input, so it must describe the whole session. `detail`, `metrics.tokens`,
+// `assistant_turns` and `total_tokens` stay the INTERACTIVE thread's record:
+// they feed the BFG corpus + the inefficiency evaluator, which reason about one
+// agent's turn-by-turn behaviour, and splicing N subagent transcripts into that
+// per-turn story would distort the very signal it exists to measure (and bloat
+// the payload). The three subagent_* counters are how a reader tells the two
+// apart instead of inferring a discrepancy from a mismatch.
+function foldSubagentUsage(digest, transcriptPath, sessionId) {
+  if (!digest || !digest.metrics || !transcriptPath || !sessionId) return digest;
+  // Path-traversal guard. The session id is interpolated into a filesystem path
+  // below, and what comes out of that path is priced into a payout — so a value
+  // carrying `../` could aim the walk at an arbitrary directory and fold
+  // fabricated token counts into the reward's input. Guarded HERE rather than at
+  // each call site: uploadSessionOnShip already screens the id before resolving
+  // the transcript, but the SessionEnd hook takes it straight off stdin, and any
+  // future caller would inherit the same hole. Same shape as the check in
+  // uploadSessionOnShip — a plain UUID-ish token, nothing else.
+  if (!/^[A-Za-z0-9_-]+$/.test(String(sessionId))) return digest;
+  const sessionDir = path.join(path.dirname(transcriptPath), sessionId);
+  const sub = subagentModelUsage(sessionDir);
+  if (sub.files === 0 && sub.graderSkipped === 0) return digest;
+  digest.metrics.model_usage = mergeModelUsage(
+    digest.metrics.model_usage || {}, sub.modelUsage
+  );
+  digest.metrics.subagent_files = sub.files;
+  digest.metrics.subagent_tokens = sub.tokens;
+  digest.metrics.subagent_grader_skipped = sub.graderSkipped;
+  return digest;
+}
+
 async function uploadSessionOnShip(taskId) {
   try {
     const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
@@ -135,17 +230,7 @@ async function uploadSessionOnShip(taskId) {
       recordUploadSkip(taskId, decision);
       return null;
     }
-    const raw = fs.readFileSync(transcriptPath, 'utf8');
-    const entries = [];
-    for (const line of raw.split('\n')) {
-      const t = line.trim();
-      if (!t) continue;
-      try {
-        entries.push(JSON.parse(t));
-      } catch (_) {
-        /* skip a malformed line — best-effort */
-      }
-    }
+    const entries = parseJsonl(fs.readFileSync(transcriptPath, 'utf8'));
     // Dynamic secrets to scrub: every secret-shaped env VALUE (Apple/MAC_* CI
     // creds, a baked GDS/DO token, GITHUB_TOKEN, ANTHROPIC_API_KEY, …) plus this
     // run's live GDS session token. Defense in depth on top of the pattern +
@@ -157,6 +242,10 @@ async function uploadSessionOnShip(taskId) {
     const s = await loadSession();
     if (s && s.token) extraSecrets.push(s.token);
     const digest = buildSessionDigest(entries, { extraSecrets });
+    // task 1003435: the interactive transcript is only part of what this session
+    // spent — fold the subagents subtree into model_usage so the cost-plus reward
+    // prices the same tokens the cost ledger already bills.
+    foldSubagentUsage(digest, transcriptPath, sessionId);
     // task 1270: surface the session usage so the completion card can show
     // Claude tokens + an estimated cost. Returned even when the POST below fails
     // (we already have the digest) — the card is best-effort either way.
@@ -215,4 +304,5 @@ module.exports = {
   classifyUploadSkip,
   recordUploadSkip,
   uploadSessionOnShip,
+  foldSubagentUsage,
 };

package/scripts/gds/ship.js

@@ -99,7 +99,9 @@ const {
   resolveInstanceBase,
   shouldBailOnFetchFailure,
 } = require('./ship-deploy-target.js');
-const { classifyUploadSkip, recordUploadSkip } = require('./ship-session-upload.js');
+const {
+  classifyUploadSkip, recordUploadSkip, foldSubagentUsage,
+} = require('./ship-session-upload.js');
 const {
   classifyLandOutcome,
   formatPublishFailure,
@@ -176,6 +178,10 @@ module.exports = {
   // secret corpus test (tests/scrubber_corpus.mjs) can exercise each layer + tune.
   shannonEntropy, looksHighEntropySecret, redactHighEntropy, collectEnvSecrets,
   classifyUploadSkip, recordUploadSkip,
+  // task 1003435: the subagents-subtree fold, shared with the SessionEnd hook —
+  // both uploads must send the SAME whole-session model_usage or whichever runs
+  // last decides what the builder is paid for.
+  foldSubagentUsage,
   // #678: re-grade path + the grade-step helpers it shares with shipMain.
   // Exporting these formalizes learning #43 (which had to "replicate ~10
   // lines" because runSubagentGrader wasn't reachable).

package/src/module-api.js

@@ -33,7 +33,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.443'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.445'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/backfill_subagent_rewards.mjs

@@ -0,0 +1,308 @@
+// tests/backfill_subagent_rewards.mjs
+//
+// Unit tests for the subagent cost-plus backfill planner (task 1003436, ADR 0054).
+//
+// This script decides who gets paid real credits, so the whole decision table is
+// pure and pinned here with no DB: which sessions are payable, which are refused
+// and WHY, and — the part that actually protects the ledger — that the classes
+// which cannot be trusted (pre-de-dup-fix inflated rows, unrecoverable sessions,
+// the ADR 0173 legacy class) never reach the mint.
+//
+// Run:  node tests/backfill_subagent_rewards.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const {
+  CLASSES, DEDUP_FIX_AT, classifySession, buildBackfillPlan, renderReport,
+} = require('../scripts/gds/backfill-subagent-rewards.js');
+const {
+  computeSessionTokenReward, sessionTrueCostUsd, awardSessionTokenReward,
+} = require('../modules/economy/credits.js');
+
+const { test, summary } = makeRunner();
+
+const AFTER = '2026-08-25T00:00:00Z';  // safely after the de-dup cutoff
+const BEFORE = '2026-08-20T00:00:00Z'; // safely before it
+const OPTS = { cutoffMs: Date.parse(DEDUP_FIX_AT), marginPct: 20, usdPeg: 1 };
+
+// 1M opus input tokens = $5.00 interactive (PRICES.opus.input = $5/M).
+const OPUS_1M = { 'claude-opus-4-8': { input: 1_000_000 } };
+
+function row(over = {}) {
+  return {
+    session_id: 'sess-aaaaaaaa',
+    builder_id: 7,
+    model_usage: OPUS_1M,
+    total_tokens: 1_000_000,
+    subagent_usd: 3.0,
+    subagent_recorded_at: AFTER,
+    has_pre_split_cost_row: false,
+    has_folded_usage: false, // pre-1003435 digest: model_usage is interactive-only
+    paid: 6, // round(5.00 x 1.20) — what the subagent-blind reward paid
+    legacy_rows: 0,
+    ...over,
+  };
+}
+
+// =========================================================================
+// classifySession — the decision table
+// =========================================================================
+
+await test('payable: owed is priced on interactive + subagent, minus what was paid', () => {
+  const r = classifySession(row(), OPTS);
+  assert.equal(r.klass, CLASSES.PAYABLE);
+  assert.equal(r.interactiveUsd, 5.0);
+  assert.equal(r.subagentUsd, 3.0);
+  assert.equal(r.trueCostUsd, 8.0);
+  assert.equal(r.owed, 10);  // round(8.00 x 1.20) = 9.6 -> 10
+  assert.equal(r.paid, 6);
+  assert.equal(r.delta, 4);
+});
+
+await test('payable: the interactive side comes from the SAME function the reward books from', () => {
+  // If these ever diverge the backfill would silently re-price what was already
+  // paid instead of only adding the missing leg.
+  const r = classifySession(row(), OPTS);
+  const { trueCostUsd } = sessionTrueCostUsd(OPUS_1M, 1_000_000);
+  assert.equal(r.interactiveUsd, trueCostUsd);
+  assert.equal(r.owed, computeSessionTokenReward(trueCostUsd + 3.0, 20, 1).drachmae);
+});
+
+await test('up_to_date: a session already paid its full worth mints nothing', () => {
+  const r = classifySession(row({ paid: 10 }), OPTS);
+  assert.equal(r.klass, CLASSES.UP_TO_DATE);
+  assert.equal(r.delta, 0);
+});
+
+await test('overpaid: paid ABOVE its worth is reported, never clawed back', () => {
+  const r = classifySession(row({ paid: 25 }), OPTS);
+  assert.equal(r.klass, CLASSES.OVERPAID);
+  assert.equal(r.excess, 15);
+  assert.equal(r.delta, 0, 'a negative delta must never become a mint');
+});
+
+await test('pre_dedup_fix: an inflated cost row is NEVER paid from', () => {
+  // Rows written before task 1003217 price one API call once per transcript line
+  // (~2.22x). Paying from them would overpay, so they are refused by DATE.
+  const r = classifySession(row({ subagent_recorded_at: BEFORE }), OPTS);
+  assert.equal(r.klass, CLASSES.PRE_DEDUP_FIX);
+  assert.equal(r.delta, 0);
+});
+
+await test('--since moves the trust cutoff (a machine on an older core keeps writing inflated rows)', () => {
+  const late = { ...OPTS, cutoffMs: Date.parse('2026-08-28T00:00:00Z') };
+  assert.equal(classifySession(row(), late).klass, CLASSES.PRE_DEDUP_FIX);
+  assert.equal(classifySession(row(), OPTS).klass, CLASSES.PAYABLE);
+});
+
+await test('no_subagent_record: no cost row means unrecoverable — never guessed at', () => {
+  const r = classifySession(row({ subagent_usd: null, subagent_recorded_at: null }), OPTS);
+  assert.equal(r.klass, CLASSES.NO_SUBAGENT_RECORD);
+  assert.equal(r.delta, 0);
+  assert.equal(r.subagentUsd, undefined, 'no invented figure');
+});
+
+await test('pre_split: a legacy single `session` row lumps both legs and cannot be separated', () => {
+  const r = classifySession(
+    row({ subagent_usd: null, subagent_recorded_at: null, has_pre_split_cost_row: true }), OPTS
+  );
+  assert.equal(r.klass, CLASSES.PRE_SPLIT);
+  assert.equal(r.delta, 0);
+});
+
+// -------------------------------------------------------------------------
+// The double-count guard. This is the one that would actually mint bad money:
+// after task 1003435 the digest folds the subagents subtree INTO model_usage, so
+// adding the cost_log subagent row on top pays the same leg twice.
+// -------------------------------------------------------------------------
+
+await test('already_folded: a post-1003435 digest already prices the subagent leg — never topped up', () => {
+  const r = classifySession(row({ has_folded_usage: true }), OPTS);
+  assert.equal(r.klass, CLASSES.ALREADY_FOLDED);
+  assert.equal(r.delta, 0, 'adding the cost row here would DOUBLE-COUNT and overpay');
+});
+
+await test('already_folded is decided BEFORE any money is computed', () => {
+  // A large subagent row must not be able to leak a figure into the plan via a
+  // field that later code reads.
+  const r = classifySession(row({ has_folded_usage: true, subagent_usd: 500 }), OPTS);
+  assert.equal(r.klass, CLASSES.ALREADY_FOLDED);
+  assert.equal(r.owed, undefined);
+  assert.equal(r.subagentUsd, undefined);
+});
+
+await test('the guard keys on the DATA, not a date — a re-uploaded old session is caught too', () => {
+  // A session that shipped before the fix but whose SessionEnd digest was
+  // re-uploaded after it has folded model_usage AND an old subagent cost row.
+  // The date would say "payable"; the counters say "already whole".
+  const r = classifySession(
+    row({ has_folded_usage: true, subagent_recorded_at: BEFORE }), OPTS
+  );
+  assert.equal(r.klass, CLASSES.ALREADY_FOLDED);
+});
+
+await test('a folded session never reaches the mint, and is reported', () => {
+  const plan = buildBackfillPlan([
+    row({ session_id: 's1' }),                            // +4
+    row({ session_id: 's2', has_folded_usage: true }),    // excluded
+  ], { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+  assert.equal(plan.grandTotal, 4, 'only the un-folded session is paid');
+  assert.equal(plan.counts[CLASSES.ALREADY_FOLDED], 1);
+  assert.match(renderReport(plan).text, /already_folded/);
+});
+
+await test('legacy: the reward_basis=0 class ADR 0173 declined is never folded in here', () => {
+  const r = classifySession(row({ legacy_rows: 2 }), OPTS);
+  assert.equal(r.klass, CLASSES.LEGACY);
+  assert.equal(r.delta, 0);
+});
+
+await test('legacy wins over payable — the class is decided before any money is computed', () => {
+  const r = classifySession(row({ legacy_rows: 1, subagent_usd: 100 }), OPTS);
+  assert.equal(r.klass, CLASSES.LEGACY);
+  assert.equal(r.owed, undefined);
+});
+
+// =========================================================================
+// buildBackfillPlan — grouping + the grand total the owner signs off on
+// =========================================================================
+
+await test('the plan groups payables by builder and totals them', () => {
+  const plan = buildBackfillPlan([
+    row({ session_id: 's1', builder_id: 7 }),                       // +4
+    row({ session_id: 's2', builder_id: 7, subagent_usd: 10 }),     // owed round(15x1.2)=18, -6 => +12
+    row({ session_id: 's3', builder_id: 9 }),                       // +4
+    row({ session_id: 's4', builder_id: 9, legacy_rows: 1 }),       // not paid
+    row({ session_id: 's5', builder_id: 9, subagent_recorded_at: BEFORE }), // not paid
+  ], { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+
+  assert.equal(plan.totalCandidates, 5);
+  assert.equal(plan.plans.length, 2);
+  assert.deepEqual(plan.plans.map((p) => [p.builderId, p.toMint]), [[7, 16], [9, 4]]);
+  assert.equal(plan.grandTotal, 20);
+  assert.equal(plan.counts[CLASSES.PAYABLE], 3);
+  assert.equal(plan.counts[CLASSES.LEGACY], 1);
+  assert.equal(plan.counts[CLASSES.PRE_DEDUP_FIX], 1);
+});
+
+await test('the plan reports what it does NOT settle (ADR 0173 objected to a silent partial)', () => {
+  const plan = buildBackfillPlan([
+    row({ session_id: 's1', subagent_usd: 7.5, subagent_recorded_at: BEFORE }),
+    row({ session_id: 's2', paid: 25 }),
+  ], { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+  assert.equal(plan.unpaidSubagentUsd, 7.5, 'inflated-but-real spend is surfaced, not hidden');
+  assert.equal(plan.overpaidExcess, 15, 'correcting in one direction only is stated');
+  assert.equal(plan.grandTotal, 0);
+});
+
+await test('an empty ledger plans nothing and totals zero', () => {
+  const plan = buildBackfillPlan([], { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+  assert.equal(plan.grandTotal, 0);
+  assert.equal(plan.plans.length, 0);
+  assert.match(renderReport(plan).text, /NOTHING PAYABLE/);
+});
+
+await test('the report leads with the grand total and names every refusal reason', () => {
+  const plan = buildBackfillPlan([row(), row({ session_id: 's2', legacy_rows: 1 })],
+    { since: DEDUP_FIX_AT, marginPct: 20, usdPeg: 1 });
+  const { text, total } = renderReport(plan, { loginFor: (id) => (id === 7 ? 'jaxri' : null) });
+  assert.equal(total, 4);
+  assert.match(text, /GRAND TOTAL to mint: 4 credits/);
+  assert.match(text, /jaxri: \+4/);
+  for (const k of [CLASSES.PRE_DEDUP_FIX, CLASSES.NO_SUBAGENT_RECORD, CLASSES.PRE_SPLIT, CLASSES.LEGACY]) {
+    assert.ok(text.includes(k), `the report must name the ${k} class`);
+  }
+});
+
+// =========================================================================
+// The mint path — idempotency + the forward-path invariant.
+//
+// These are the properties that keep a backfill from corrupting the ledger, so
+// they are asserted against the REAL writer with a fake client, not described.
+// =========================================================================
+
+function fakeClient(ledgerRows) {
+  const queries = [];
+  const responses = [...ledgerRows];
+  return {
+    queries,
+    async query(sql, params) {
+      queries.push({ sql, params });
+      return { rows: responses.shift() || [] };
+    },
+  };
+}
+const ledger = (paid = 0, legacy = 0) => [{ paid, legacy }];
+
+await test('the mint goes through the real reward writer, so extraCostUsd raises the basis', async () => {
+  const client = fakeClient([ledger(6, 0), [{ id: 1 }]]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-aaaaaaaa', OPUS_1M, 1_000_000, 3.0);
+  assert.equal(res.awarded, true);
+  assert.equal(res.trueCostUsd, 8.0, 'interactive $5 + recovered subagent $3');
+  assert.equal(res.drachmae, 4, 'books only the INCREMENT over what was paid');
+  const insert = client.queries[1];
+  assert.match(insert.sql, /session\.token_reward/);
+  assert.match(insert.sql, /ON CONFLICT \(session_id, reward_basis\)/);
+  // reward_basis is the CUMULATIVE owed total — the last positional.
+  assert.equal(insert.params[insert.params.length - 1], 10);
+  assert.equal(insert.params[1], 4, 'delta booked = owed - paid');
+});
+
+await test('re-running the backfill is a no-op — the watermark, not a private reason key', async () => {
+  // Second run: the ledger now shows the topped-up total, so owed - paid = 0.
+  const client = fakeClient([ledger(10, 0)]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-aaaaaaaa', OPUS_1M, 1_000_000, 3.0);
+  assert.equal(res.awarded, false);
+  assert.equal(res.drachmae, 0);
+  assert.equal(res.settled, 'up_to_date');
+  assert.equal(client.queries.length, 1, 'SELECT only — no second INSERT');
+});
+
+await test('FORWARD PATH: a later ship in a backfilled session books only its own increment', async () => {
+  // The reason the backfill is written under the NORMAL reason rather than its
+  // own key: the watermark reads reason='session.token_reward', so a private key
+  // would be invisible to it and the next ship would pay the subagent leg AGAIN.
+  // Here the next ship uploads a digest whose model_usage now INCLUDES the
+  // subagent tokens (task 1003435) — $8 of usage, already backfilled to 10.
+  const eight = { 'claude-opus-4-8': { input: 1_600_000 } }; // 1.6M x $5/M = $8.00
+  const client = fakeClient([ledger(10, 0)]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-aaaaaaaa', eight, 1_600_000);
+  assert.equal(res.trueCostUsd, 8.0);
+  assert.equal(res.awarded, false, 'must NOT re-pay the leg the backfill settled');
+  assert.equal(client.queries.length, 1);
+});
+
+await test('a backfill can never clawback: a smaller basis books nothing, never a negative row', async () => {
+  const client = fakeClient([ledger(99, 0)]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-aaaaaaaa', OPUS_1M, 1_000_000, 3.0);
+  assert.equal(res.awarded, false);
+  assert.equal(res.drachmae, 0);
+  assert.equal(client.queries.length, 1, 'no INSERT — the ledger is append-only');
+});
+
+await test('the legacy refusal still bites at the writer, not only in the planner', async () => {
+  const client = fakeClient([ledger(3, 1)]); // one reward_basis=0 row
+  const res = await awardSessionTokenReward(client, 7, 'sess-legacy', OPUS_1M, 1_000_000, 3.0);
+  assert.equal(res.awarded, false);
+  assert.equal(res.settled, 'legacy', 'ADR 0173 class is refused twice over');
+});
+
+await test('extraCostUsd defaults to 0, so every pre-existing call site is unchanged', async () => {
+  const client = fakeClient([ledger(0, 0), [{ id: 9 }]]);
+  const res = await awardSessionTokenReward(client, 7, 'sess-plain', OPUS_1M, 1_000_000);
+  assert.equal(res.trueCostUsd, 5.0);
+  assert.equal(res.drachmae, 6);
+});
+
+await test('a negative, infinite or garbage extraCostUsd cannot inflate a payout', async () => {
+  for (const bad of [-100, NaN, Infinity, -Infinity, 'lots', null, undefined]) {
+    const client = fakeClient([ledger(0, 0), [{ id: 1 }]]);
+    const res = await awardSessionTokenReward(client, 7, 'sess-x', OPUS_1M, 1_000_000, bad);
+    assert.equal(res.trueCostUsd, 5.0, `extraCostUsd ${String(bad)} must be treated as 0`);
+  }
+});
+
+summary();