@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/backfill-subagent-rewards.js

@@ -0,0 +1,485 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/backfill-subagent-rewards.js — retroactive cost-plus top-up for the
+// subagent leg the reward could not see before task 1003435 (ADR 0054).
+//
+// THE GAP. The ADR 0054 reward prices `session_records.model_usage`, and until
+// task 1003435 that map was built from ONE file — the interactive transcript.
+// Claude Code persists Agent/Task-tool spawns in a sibling subtree, so a parallel
+// session was paid round(interactive x 1.20) when it was owed
+// round((interactive + subagent) x 1.20). CLAUDE.md tells builders to delegate
+// freely; following it moved real spend into a bucket the reward never counted.
+//
+// WHERE THE MISSING NUMBER COMES FROM. Not from transcripts — those live only on
+// builders' machines and are frequently gone. The SPEND ledger recorded the leg
+// all along: session-cost.js writes a `cost_log` row with source ending
+// ':subagent' and source_ref '<session-id>:sub' (ADR 0028). That row is the
+// recoverable evidence, priced through the same locked PRICES table the reward
+// uses. This script reads it and tops the session up.
+//
+// READ THIS BEFORE PROPOSING TO RUN --apply — two prior decisions bound it:
+//
+//   * ADR 0173 (2026-08-16, blocker 1000113) declined a STRUCTURALLY SIMILAR
+//     backfill — the pre-`core_196` legacy multi-ship shortfall — for reasons
+//     that partly apply here: reconstruction was incomplete, so paying only the
+//     traceable part was arbitrary, and overpayment was not corrected
+//     symmetrically. This script therefore REPORTS those same asymmetries
+//     instead of hiding them, and never touches the legacy class at all.
+//   * Task 1003217 (landed 2026-08-23T21:50Z) fixed a ~2.22x over-count in BOTH
+//     the cost ledger and the digest: one API call is written as several
+//     transcript lines that repeat the same usage block, and every one was being
+//     priced. Cost rows recorded BEFORE that fix are inflated, so paying from
+//     them would OVERPAY. They are reported as their own class and never paid.
+//     The cutoff is a LOWER BOUND, not a guarantee: a machine still running an
+//     older core kept writing inflated rows after that date. --since moves it.
+//
+// SAFETY MODEL (mirrors scripts/bongos/backfill-task-rewards.js, ADR 0097):
+//   * DRY-RUN BY DEFAULT. With no flags it prints the full plan + grand total and
+//     writes NOTHING. A live mint requires ALL of: --apply, Archon rank verified
+//     server-side via GET /api/bongos/me, and a typed y/N confirmation (--yes skips
+//     only the typing).
+//   * IDEMPOTENT BY CONSTRUCTION, not by a new bookkeeping key. Every mint goes
+//     through the REAL reward writer (modules/economy/credits.js
+//     awardSessionTokenReward) with the recovered subagent dollars passed as
+//     `extraCostUsd`. That means the watermark, the no-clawback rule, the legacy
+//     refusal and the (session_id, reward_basis) unique index all keep applying:
+//     a backfill row is simply a top-up at a higher basis. Re-running computes
+//     the same basis, finds it already paid, and books nothing.
+//   * THE FORWARD PATH STAYS CORRECT. Because the top-up is booked under the
+//     normal reason, a later ship in a backfilled session still sees it in the
+//     watermark and books only its own increment — it cannot re-pay the leg this
+//     script settled. That is the whole reason for not inventing a private
+//     reason key.
+//   * NEVER ACTS ON require/import. All work is inside main(), which only runs as
+//     a CLI. The test imports the pure planners and touches no DB.
+//
+// NOT A MIGRATION. A fresh instance has no underpaid history; migrations run
+// everywhere. Same call as ADR 0097 made for the sibling script.
+//
+// WHERE IT RUNS: it needs Postgres, so it runs on the box, by the owner.
+//
+// USAGE:
+//   node scripts/bongos/backfill-subagent-rewards.js --help
+//   node scripts/bongos/backfill-subagent-rewards.js                  # dry-run
+//   node scripts/bongos/backfill-subagent-rewards.js --json           # dry-run, machine-readable
+//   node scripts/bongos/backfill-subagent-rewards.js --since 2026-08-25
+//   node scripts/bongos/backfill-subagent-rewards.js --apply          # Archon-only live mint
+
+const path = require('node:path');
+const readline = require('node:readline');
+
+const credits = require('../../modules/economy/credits');
+const { arg, hasFlag, cliClient } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// When task 1003217's de-duplication fix landed (commit 760c92d4,
+// 2026-08-23T17:50:15-04:00). Cost rows recorded before it over-count a single
+// API call once per transcript line — measured 2.22x across 12 real transcripts —
+// so their dollar amounts cannot be paid from. See the header.
+const DEDUP_FIX_AT = '2026-08-23T21:50:15Z';
+
+// The classes a candidate session can land in. Only `payable` ever mints.
+const CLASSES = Object.freeze({
+  PAYABLE: 'payable',
+  ALREADY_FOLDED: 'already_folded',
+  UP_TO_DATE: 'up_to_date',
+  OVERPAID: 'overpaid',
+  PRE_DEDUP_FIX: 'pre_dedup_fix',
+  NO_SUBAGENT_RECORD: 'no_subagent_record',
+  PRE_SPLIT: 'pre_split',
+  LEGACY: 'legacy',
+});
+
+// Why each non-payable class is not paid — printed in the report so the owner is
+// reading reasons, not a bare bucket count.
+const CLASS_NOTE = Object.freeze({
+  [CLASSES.ALREADY_FOLDED]: 'its digest was built AFTER task 1003435, so model_usage already prices the subagent leg — adding the cost row on top would DOUBLE-COUNT',
+  [CLASSES.UP_TO_DATE]: 'already paid at or above this basis — nothing owed',
+  [CLASSES.OVERPAID]: 'paid ABOVE its worth; ADR 0054 is append-only, so never clawed back',
+  [CLASSES.PRE_DEDUP_FIX]: 'subagent cost row predates the task-1003217 de-dup fix (~2.22x inflated) — paying it would OVERPAY',
+  [CLASSES.NO_SUBAGENT_RECORD]: 'no subagent cost row: the cost hook never ran (no token / hard kill / 401). Unrecoverable — never guessed at',
+  [CLASSES.PRE_SPLIT]: 'only a pre-split single `session` cost row, which lumps interactive + subagent and cannot be separated',
+  [CLASSES.LEGACY]: 'reward_basis=0 legacy row — a DIFFERENT gap that ADR 0173 already declined to backfill; not folded in here',
+});
+
+const round4 = (n) => Math.round((Number(n) || 0) * 10000) / 10000;
+
+// classifySession — PURE. Decide what one candidate session is owed, and if it is
+// not payable, exactly why. Split from the SQL so the whole decision table is
+// unit-tested with no DB (tests/backfill_subagent_rewards.mjs).
+//
+// `row` is the shape fetchCandidates() returns. `cutoffMs` is the dedup-fix
+// boundary; `marginPct`/`usdPeg` come from the instance reward policy so the
+// arithmetic matches what actually pays.
+function classifySession(row, { cutoffMs, marginPct, usdPeg } = {}) {
+  const sessionId = String(row.session_id);
+  const builderId = Number(row.builder_id);
+  const paid = Number(row.paid) || 0;
+  const base = { sessionId, builderId, paid, delta: 0 };
+
+  // ADR 0173 territory. awardSessionTokenReward refuses these anyway (it returns
+  // settled:'legacy'), so minting here would silently no-op — but reporting it as
+  // its own class is the honest form, and keeps the two gaps from being conflated.
+  if ((Number(row.legacy_rows) || 0) > 0) return { ...base, klass: CLASSES.LEGACY };
+
+  // THE DOUBLE-COUNT GUARD — the one that would actually mint bad money.
+  //
+  // Task 1003435 made the digest fold the subagents subtree INTO model_usage. So
+  // for any session whose digest was written after that landed, model_usage
+  // ALREADY prices interactive + subagent, and adding the cost_log subagent row
+  // on top would pay the same leg twice. This backfill exists only for the
+  // sessions priced BEFORE that fix.
+  //
+  // The test is the DATA, not a date: the fold stamps subagent_files /
+  // subagent_tokens / subagent_grader_skipped into metrics, so their presence
+  // means "this row's model_usage is already whole". That also handles the case a
+  // date could not — a session that shipped before the fix but whose SessionEnd
+  // digest was re-uploaded after it, overwriting model_usage with the folded map.
+  if (row.has_folded_usage) return { ...base, klass: CLASSES.ALREADY_FOLDED };
+
+  if (row.subagent_usd == null) {
+    return {
+      ...base,
+      klass: row.has_pre_split_cost_row ? CLASSES.PRE_SPLIT : CLASSES.NO_SUBAGENT_RECORD,
+    };
+  }
+
+  const subagentUsd = round4(row.subagent_usd);
+  const recordedMs = Date.parse(row.subagent_recorded_at);
+  if (Number.isFinite(cutoffMs) && Number.isFinite(recordedMs) && recordedMs < cutoffMs) {
+    return { ...base, klass: CLASSES.PRE_DEDUP_FIX, subagentUsd };
+  }
+
+  // Take the interactive side from the SAME function the reward books from, so
+  // the top-up only ever ADDS the missing leg and never silently re-prices what
+  // was already paid.
+  const { trueCostUsd: interactiveUsd } = credits.sessionTrueCostUsd(
+    row.model_usage, row.total_tokens
+  );
+  const trueCostUsd = round4(interactiveUsd + subagentUsd);
+  const { drachmae: owed } = credits.computeSessionTokenReward(trueCostUsd, marginPct, usdPeg);
+  const delta = owed - paid;
+
+  if (delta > 0) {
+    return {
+      ...base, klass: CLASSES.PAYABLE, delta, owed, interactiveUsd, subagentUsd, trueCostUsd,
+    };
+  }
+  if (delta === 0) return { ...base, klass: CLASSES.UP_TO_DATE, owed, subagentUsd };
+  return { ...base, klass: CLASSES.OVERPAID, owed, excess: -delta, subagentUsd };
+}
+
+// buildBackfillPlan — PURE. Classify every candidate, group the payable ones by
+// builder, and total everything. The grand total is the number the owner signs
+// off on, so it is computed here (tested) and never re-derived in the renderer.
+function buildBackfillPlan(rows, opts = {}) {
+  const cutoffMs = Date.parse(opts.since || DEDUP_FIX_AT);
+  const marginPct = opts.marginPct;
+  const usdPeg = opts.usdPeg;
+
+  const sessions = (Array.isArray(rows) ? rows : [])
+    .map((r) => classifySession(r, { cutoffMs, marginPct, usdPeg }));
+
+  const counts = {};
+  for (const k of Object.values(CLASSES)) counts[k] = 0;
+  for (const s of sessions) counts[s.klass]++;
+
+  const byBuilder = new Map();
+  let grandTotal = 0;
+  for (const s of sessions) {
+    if (s.klass !== CLASSES.PAYABLE) continue;
+    if (!byBuilder.has(s.builderId)) {
+      byBuilder.set(s.builderId, { builderId: s.builderId, sessions: [], toMint: 0 });
+    }
+    const b = byBuilder.get(s.builderId);
+    b.sessions.push(s);
+    b.toMint += s.delta;
+    grandTotal += s.delta;
+  }
+  const plans = [...byBuilder.values()].sort((a, b) => a.builderId - b.builderId);
+
+  // Exposure the owner should see even though this run will not pay it: the
+  // unpaid classes are where the remaining, unrecoverable-or-untrustworthy money
+  // sits, and ADR 0173's objection was precisely about paying a partial set
+  // without stating the rest.
+  const unpaidSubagentUsd = round4(sessions
+    .filter((s) => s.klass === CLASSES.PRE_DEDUP_FIX)
+    .reduce((t, s) => t + (s.subagentUsd || 0), 0));
+  const overpaidExcess = sessions
+    .filter((s) => s.klass === CLASSES.OVERPAID)
+    .reduce((t, s) => t + (s.excess || 0), 0);
+
+  return {
+    plans, sessions, counts, grandTotal, unpaidSubagentUsd, overpaidExcess,
+    cutoff: new Date(cutoffMs).toISOString(),
+    totalCandidates: sessions.length,
+  };
+}
+
+// renderReport — PURE. The dry-run text. Leads with what WILL be paid, then every
+// class that will not, each with its reason.
+function renderReport(plan, { loginFor = () => null } = {}) {
+  const out = [];
+  const name = (id) => loginFor(id) || `builder ${id}`;
+  out.push('Subagent cost-plus backfill — plan (task 1003436, ADR 0054)');
+  out.push(`  candidates: ${plan.totalCandidates} session(s); trust cutoff ${plan.cutoff}`);
+  out.push('');
+
+  if (plan.plans.length === 0) {
+    out.push('  NOTHING PAYABLE — no session qualifies for a top-up.');
+  } else {
+    out.push('TO MINT');
+    for (const p of plan.plans) {
+      out.push(`  ${name(p.builderId)}: +${p.toMint} across ${p.sessions.length} session(s)`);
+      for (const s of p.sessions) {
+        out.push(
+          `    ${s.sessionId.slice(0, 8)}  +${s.delta}`
+          + `  (owed ${s.owed} on $${s.trueCostUsd.toFixed(4)}`
+          + ` = $${s.interactiveUsd.toFixed(4)} interactive + $${s.subagentUsd.toFixed(4)} subagent;`
+          + ` already paid ${s.paid})`
+        );
+      }
+    }
+  }
+
+  out.push('');
+  out.push('NOT PAID (and why)');
+  for (const k of [CLASSES.ALREADY_FOLDED, CLASSES.UP_TO_DATE, CLASSES.OVERPAID,
+    CLASSES.PRE_DEDUP_FIX, CLASSES.NO_SUBAGENT_RECORD, CLASSES.PRE_SPLIT, CLASSES.LEGACY]) {
+    out.push(`  ${String(plan.counts[k]).padStart(5)}  ${k} — ${CLASS_NOTE[k]}`);
+  }
+
+  out.push('');
+  out.push('WHAT THIS RUN DOES NOT SETTLE (state it before deciding — ADR 0173 §Rationale 2/3)');
+  out.push(`  $${plan.unpaidSubagentUsd.toFixed(2)} of subagent spend sits in pre-dedup-fix rows that are ~2.22x inflated and cannot be paid from.`);
+  out.push(`  ${plan.overpaidExcess} credits of existing OVERpayment are not recovered; this corrects in one direction only.`);
+  out.push('  Sessions whose cost hook never ran left no trace at all and are unrecoverable.');
+  out.push('');
+  out.push(`GRAND TOTAL to mint: ${plan.grandTotal} credits`);
+  return { text: out.join('\n'), total: plan.grandTotal };
+}
+
+// ---------------------------------------------------------------------------
+// DB side. Nothing below runs on require.
+// ---------------------------------------------------------------------------
+
+// Lazy + guarded: --help must not need a database.
+function loadPool() {
+  // eslint-disable-next-line global-require
+  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  return pool;
+}
+
+// One row per session_record, carrying: its stored usage (the interactive side),
+// the recovered subagent cost row if any, whether only a pre-split `session` row
+// exists, and what the cost-plus stream has already paid it.
+async function fetchCandidates(pool) {
+  const { rows } = await pool.query(
+    `SELECT sr.session_id,
+            sr.builder_id,
+            sr.model_usage,
+            sr.total_tokens,
+            sub.amount_usd::float8            AS subagent_usd,
+            sub.recorded_at                   AS subagent_recorded_at,
+            (pre.id IS NOT NULL)              AS has_pre_split_cost_row,
+            -- task 1003435 stamps these counters whenever the digest folded the
+            -- subagents subtree into model_usage. Their presence means this row's
+            -- model_usage is ALREADY whole, so the backfill must skip it or it
+            -- pays the same leg twice. Written with -> rather than the jsonb
+            -- key-exists operator, whose symbol collides with driver placeholders.
+            (sr.metrics -> 'subagent_files' IS NOT NULL
+              OR sr.metrics -> 'subagent_tokens' IS NOT NULL
+              OR sr.metrics -> 'subagent_grader_skipped' IS NOT NULL)
+                                              AS has_folded_usage,
+            COALESCE(cl.paid, 0)::int         AS paid,
+            COALESCE(cl.legacy_rows, 0)::int  AS legacy_rows
+       FROM session_records sr
+       -- cost_log.source_ref has no dedicated index; this is a one-time batch run
+       -- by hand on the box, not a hot path, so a seq scan here is acceptable and
+       -- an index migration would be schema churn for a script that runs once.
+       LEFT JOIN LATERAL (
+         SELECT id, amount_usd, recorded_at
+           FROM cost_log
+          WHERE source_ref = sr.session_id || ':sub'
+            AND source LIKE '%:subagent'
+          ORDER BY recorded_at ASC
+          LIMIT 1
+       ) sub ON true
+       LEFT JOIN LATERAL (
+         SELECT id FROM cost_log
+          WHERE source_ref = sr.session_id AND source = 'session'
+          LIMIT 1
+       ) pre ON true
+       LEFT JOIN LATERAL (
+         SELECT COALESCE(SUM(delta), 0)::int AS paid,
+                COUNT(*) FILTER (WHERE reward_basis = 0)::int AS legacy_rows
+           FROM credit_log
+          WHERE reason = 'session.token_reward' AND session_id = sr.session_id
+       ) cl ON true
+      ORDER BY sr.builder_id, sr.session_id`
+  );
+  return rows;
+}
+
+// Mint. Routes every top-up through the REAL reward writer so the watermark and
+// the uniqueness index do the idempotency — see the header. Deliberately does NOT
+// touch builders.total_credits: trg_credit_log_apply (migration 003) bumps it on
+// INSERT, so an extra UPDATE here would double-credit.
+async function applyPlan(pool, plan, rowsBySession) {
+  const client = await pool.connect();
+  let mintedRows = 0;
+  let mintedCredits = 0;
+  const skipped = [];
+  try {
+    await client.query('BEGIN');
+    for (const p of plan.plans) {
+      for (const s of p.sessions) {
+        const row = rowsBySession.get(s.sessionId);
+        if (!row) { skipped.push({ sessionId: s.sessionId, why: 'row vanished between plan and apply' }); continue; }
+        const res = await credits.awardSessionTokenReward(
+          client, s.builderId, s.sessionId, row.model_usage, row.total_tokens, s.subagentUsd
+        );
+        if (res && res.awarded && res.drachmae > 0) {
+          mintedRows++;
+          mintedCredits += res.drachmae;
+        } else {
+          skipped.push({ sessionId: s.sessionId, why: (res && res.settled) || 'nothing owed at apply time' });
+        }
+      }
+    }
+    await client.query('COMMIT');
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+  return { mintedRows, mintedCredits, skipped };
+}
+
+function printHelp() {
+  console.log(`
+backfill-subagent-rewards — top up the cost-plus reward for the subagent leg it
+could not see before task 1003435.
+
+  (no flags)        dry-run: print the plan + grand total, write nothing
+  --json            dry-run as JSON
+  --since <ISO>     trust cutoff for subagent cost rows (default ${DEDUP_FIX_AT},
+                    when the task-1003217 ~2.22x over-count fix landed)
+  --apply           mint (Archon only, typed confirmation)
+  --yes             skip the typed confirmation (still needs --apply + Archon)
+  --help            this
+
+Runs where Postgres is reachable — i.e. on the box. Read the file header before
+--apply: ADR 0173 declined a structurally similar backfill, and rows written
+before the cutoff are inflated and are never paid from.
+`.trim());
+}
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a); }));
+}
+
+async function main() {
+  if (hasFlag('--help')) { printHelp(); return 0; }
+
+  const apply = hasFlag('--apply');
+  const since = arg('--since') || DEDUP_FIX_AT;
+  if (!Number.isFinite(Date.parse(since))) {
+    console.error(`--since is not a parseable date: ${since}`);
+    return 2;
+  }
+
+  const { marginPct, usdPeg } = credits.rewardConfig();
+  const pool = loadPool();
+  let plan;
+  let rows;
+  try {
+    rows = await fetchCandidates(pool);
+    plan = buildBackfillPlan(rows, { since, marginPct, usdPeg });
+  } catch (err) {
+    console.error(`could not read the ledger: ${err && err.message ? err.message : err}`);
+    await pool.end().catch(() => {});
+    return 2;
+  }
+
+  if (hasFlag('--json')) {
+    console.log(JSON.stringify(plan, null, 2));
+    await pool.end().catch(() => {});
+    return 0;
+  }
+
+  console.log(renderReport(plan).text);
+
+  if (!apply) {
+    console.log('');
+    console.log('DRY RUN — nothing was written. Re-run with --apply to mint (Archon only).');
+    await pool.end().catch(() => {});
+    return 0;
+  }
+
+  if (plan.grandTotal <= 0) {
+    console.log('\nNothing to mint. Exiting without writing.');
+    await pool.end().catch(() => {});
+    return 0;
+  }
+
+  // Rank is authority, and authority lives on the server (ADR 0016). Never infer
+  // it from anything local.
+  let me;
+  try {
+    const api = await cliClient();
+    const r = await api.me.getMe();
+    me = r && r.ok ? r.data : null;
+  } catch (_) { me = null; }
+  const rank = me && (me.builder ? me.builder.rank : me.rank);
+  if (rank !== 'archon') {
+    console.error(`\n--apply is Archon-only; this session is ${rank || 'unauthenticated'}. Nothing written.`);
+    await pool.end().catch(() => {});
+    return 3;
+  }
+
+  if (!hasFlag('--yes')) {
+    const a = await ask(`\nMint ${plan.grandTotal} credits across ${plan.plans.length} builder(s)? [y/N] `);
+    if (!/^y(es)?$/i.test(String(a).trim())) {
+      console.log('Aborted. Nothing written.');
+      await pool.end().catch(() => {});
+      return 0;
+    }
+  }
+
+  const rowsBySession = new Map(rows.map((r) => [String(r.session_id), r]));
+  try {
+    const res = await applyPlan(pool, plan, rowsBySession);
+    console.log(`\nMinted ${res.mintedCredits} credits across ${res.mintedRows} session(s).`);
+    if (res.skipped.length) {
+      console.log(`Skipped ${res.skipped.length} (already settled between plan and apply):`);
+      for (const s of res.skipped.slice(0, 20)) console.log(`  ${s.sessionId.slice(0, 8)} — ${s.why}`);
+    }
+  } catch (err) {
+    console.error(`\nApply FAILED and rolled back: ${err && err.message ? err.message : err}`);
+    await pool.end().catch(() => {});
+    return 2;
+  }
+  await pool.end().catch(() => {});
+  return 0;
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }).catch((err) => {
+    console.error(err);
+    process.exitCode = 2;
+  });
+}
+
+module.exports = {
+  CLASSES,
+  CLASS_NOTE,
+  DEDUP_FIX_AT,
+  classifySession,
+  buildBackfillPlan,
+  renderReport,
+};