@bongos/core 1.21.174 → 1.21.176

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

@@ -1,485 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/backfill-subagent-rewards.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/backfill-subagent-rewards.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-
-// scripts/gds/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/gds/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/gds/backfill-subagent-rewards.js --help
-//   node scripts/gds/backfill-subagent-rewards.js                  # dry-run
-//   node scripts/gds/backfill-subagent-rewards.js --json           # dry-run, machine-readable
-//   node scripts/gds/backfill-subagent-rewards.js --since 2026-08-25
-//   node scripts/gds/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,
-};
+require('../bongos/forwarder.js').forward(module, 'backfill-subagent-rewards.js');