@bongos/core 1.18.3 → 1.18.19

package/tests/session_digest.mjs

@@ -69,5 +69,49 @@ test('parseHookInput: partial payload (only session_id) leaves the rest for fall
   assert.equal(r.cwd, '/c'); // no cwd in payload → keeps the fallback
 });
 
+// --- snippetOf must never emit a NUL (task 1002507) -------------------------
+// Postgres rejects a literal NUL inside jsonb, and `detail` is stored as jsonb.
+// One NUL in one snippet therefore made POST /sessions answer 500 and discarded
+// the ENTIRE digest -- so the session recorded nothing and, on a cost-plus-only
+// instance, earned nothing. UTF-16LE tool output is the ordinary trigger.
+//
+// NUL is built with String.fromCharCode(0) so this FILE stays plain ASCII: a
+// literal NUL in the source would make git and grep treat it as binary.
+const ship = require('../scripts/gds/ship.js');
+const NUL = String.fromCharCode(0);
+const hasNul = (v) => typeof v === 'string' && v.indexOf(NUL) !== -1;
+
+test('snippetOf strips NUL from UTF-16LE-looking tool output', () => {
+  // `wsl --list` read as UTF-8: every other byte is a NUL.
+  const wsl = 'NAME'.split('').join(NUL) + NUL + ' STATE' + NUL;
+  const out = ship.snippetOf(wsl, []);
+  assert.ok(out, 'a NUL-laden string must still yield a snippet');
+  assert.equal(hasNul(out), false, 'snippet must carry no NUL');
+  assert.ok(out.includes('NAME'), 'the readable text must survive');
+});
+
+test('snippetOf leaves ordinary text unchanged apart from flattening', () => {
+  assert.equal(ship.snippetOf('hello   world\n\nagain', []), 'hello world again');
+});
+
+test('a NUL-only string yields no snippet rather than an empty-ish one', () => {
+  assert.equal(ship.snippetOf(NUL + NUL + NUL, []), undefined);
+});
+
+test('buildSessionDigest yields a digest whose detail carries no NUL', () => {
+  // The end-to-end guarantee the route depends on: whatever the transcript
+  // contained, the serialised detail must be storable as jsonb.
+  const entries = [
+    { type: 'assistant', timestamp: '2026-07-26T21:18:16.356Z',
+      message: { model: 'claude-opus-5', usage: { input_tokens: 5, output_tokens: 7 },
+                 content: [{ type: 'text', text: 'ran' + NUL + ' wsl --list' }] } },
+    { type: 'user', timestamp: '2026-07-26T21:19:00.000Z',
+      message: { content: [{ type: 'tool_result', content: 'N' + NUL + 'A' + NUL + 'M' + NUL + 'E' }] } },
+  ];
+  const digest = ship.buildSessionDigest(entries, {});
+  assert.equal(hasNul(JSON.stringify(digest.detail)), false, 'no NUL may reach the detail jsonb');
+  assert.ok(digest.totalTokens > 0, 'token accounting is unaffected by the strip');
+});
+
 console.log(`\nSessionEnd session-digest (#620) tests: ${passed} passed, ${failed} failed`);
 process.exit(failed > 0 ? 1 : 0);

package/tests/session_index.mjs

@@ -39,7 +39,12 @@ test('--json yields parsed entries, newest first, with date + file + title', ()
   const r = run(['--json']);
   assert.equal(r.code, 0);
   const entries = JSON.parse(r.stdout);
-  assert.ok(entries.length > 40, 'should parse the whole session-logs corpus');
+  // Parses EVERY dated session-log file — corpus-agnostic (the neutral core carries no
+  // session logs; an instance carries many). Was a magic `> 40` that failed on a clean
+  // neutral-core checkout (task 1002234).
+  const logsDir = path.join(ROOT, 'docs', 'session-logs');
+  const onDiskCount = existsSync(logsDir) ? readdirSync(logsDir).filter((n) => gen.SESSION_FILE_RE.test(n)).length : 0;
+  assert.equal(entries.length, onDiskCount, 'parses every dated session-log file on disk');
   for (const e of entries) {
     assert.match(e.date, /^\d{4}-\d{2}-\d{2}$/, 'each entry has an ISO date');
     assert.match(e.file, /\.md$/, 'each entry references a markdown file');
@@ -55,12 +60,14 @@ test('EVERY index link resolves to a real file — the dangling-link bug is stru
   // docs/session-log-index.md is gitignored (ADR 0110) — assert on the generated index string.
   const idx = gen.renderIndex(gen.collectEntries());
   const links = [...idx.matchAll(/\]\(session-logs\/([^)]+\.md)\)/g)].map((m) => m[1]);
-  assert.ok(links.length > 40, 'index lists the corpus');
   for (const f of links) {
     assert.ok(existsSync(path.join(ROOT, 'docs', 'session-logs', f)), `index links a missing file: ${f}`);
   }
-  // and it covers every dated file on disk (no session silently dropped)
-  const onDisk = readdirSync(path.join(ROOT, 'docs', 'session-logs')).filter((n) => gen.SESSION_FILE_RE.test(n));
+  // Covers every dated file on disk (no session silently dropped) and no more — the
+  // real invariant, corpus-agnostic (0 on the neutral core; was a magic `> 40` that
+  // failed on a clean checkout — task 1002234).
+  const logsDir = path.join(ROOT, 'docs', 'session-logs');
+  const onDisk = existsSync(logsDir) ? readdirSync(logsDir).filter((n) => gen.SESSION_FILE_RE.test(n)) : [];
   assert.equal(links.length, onDisk.length, 'index entry count matches dated files on disk');
 });
 
@@ -70,7 +77,12 @@ test('CLAUDE.md carries the bounded generated snippet between markers, links res
   assert.ok(md.includes(gen.END), 'CLAUDE.md has the snippet end marker');
   const between = md.slice(md.indexOf(gen.BEGIN), md.indexOf(gen.END));
   const links = [...between.matchAll(/\]\(docs\/session-logs\/([^)]+\.md)\)/g)].map((m) => m[1]);
-  assert.equal(links.length, gen.SNIPPET_COUNT, `snippet is bounded to ${gen.SNIPPET_COUNT} recent sessions`);
+  // Bounded to at most SNIPPET_COUNT recent sessions: exactly that when the corpus is
+  // large enough, fewer (the whole corpus) when smaller — 0 on the neutral core, which
+  // carries no session logs (was a hard `=== SNIPPET_COUNT` that failed there — task 1002234).
+  const corpusCount = gen.collectEntries().length;
+  assert.equal(links.length, Math.min(corpusCount, gen.SNIPPET_COUNT),
+    `snippet is bounded to ${gen.SNIPPET_COUNT} recent sessions (or the whole corpus if smaller)`);
   for (const f of links) {
     assert.ok(existsSync(path.join(ROOT, 'docs', 'session-logs', f)), `snippet links a missing file: ${f}`);
   }
@@ -93,7 +105,7 @@ test('generated markdown is linkify-clean: no bare #NNN, no broken nested links'
 test('cleanTitle de-linkifies embedded refs, de-hashes bare #NNN, keeps genuine PR refs', () => {
   // embedded markdown link → its text, then bare #NNN → plain number (no nested link, linkify-clean)
   assert.equal(
-    gen.cleanTitle('# 2026-06-06 — Box-lane verify ([#720](https://amazonprimea.com/builders#/task/720))'),
+    gen.cleanTitle('# 2026-06-06 — Box-lane verify ([#720](https://example.com/builders#/task/720))'),
     '2026-06-06 — Box-lane verify (720)'
   );
   // "task #727" → "task 727"

package/tests/session_records.mjs

@@ -20,7 +20,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const { scrubSecrets, snippetOf, buildSessionDigest, resolveTranscriptPath } = require('../scripts/gds/ship.js');
+const { scrubSecrets, snippetOf, buildSessionDigest, resolveTranscriptPath, encodeProjectPath } = require('../scripts/gds/ship.js');
 
 // Secret-shaped fakes built at runtime — see the NOTE above.
 const FAKE = {
@@ -135,6 +135,44 @@ test('resolveTranscriptPath falls back to REPO_ROOT, else null', () => {
   assert.equal(resolveTranscriptPath(sid, ['/a', '/b'], { base, existsFn: () => false }), null);
 });
 
+// ---------- encodeProjectPath (task 1002471: win32 separators) ----------
+//
+// Claude Code encodes the project dir by replacing every NON-ALPHANUMERIC char
+// with '-' (the rule already documented + implemented in
+// scripts/gds/onboarding-config.js). ship.js replaced only '/' and '.', so on
+// Windows — where the separator is '\', the drive carries ':', and paths often
+// contain spaces — it produced a path that cannot exist, the transcript was
+// never found, no session_record was written, and the cost-plus reward could
+// never book (ADR 0146 makes that the only paid stream). Every Windows ship
+// paid 0. The win32 expectations below are the REAL directory names observed
+// under ~/.claude/projects on a win32 box.
+
+test('encodeProjectPath: win32 drive + backslashes + spaces', () => {
+  assert.equal(
+    encodeProjectPath('C:\\Users\\rocke\\OneDrive\\Desktop\\Cloud Bongos\\cloud-bongos'),
+    'C--Users-rocke-OneDrive-Desktop-Cloud-Bongos-cloud-bongos'
+  );
+});
+
+test('encodeProjectPath: win32 nested worktree path', () => {
+  assert.equal(
+    encodeProjectPath('C:\\Users\\rocke\\OneDrive\\Desktop\\Cloud Bongos\\cloud-bongos\\.claude\\worktrees\\task-1002467'),
+    'C--Users-rocke-OneDrive-Desktop-Cloud-Bongos-cloud-bongos--claude-worktrees-task-1002467'
+  );
+});
+
+test('encodeProjectPath: POSIX behaviour unchanged (regression guard)', () => {
+  // These are the exact shapes the pre-existing tests above and in
+  // tests/memory_pull.mjs pin — they must not move.
+  assert.equal(encodeProjectPath('/proj'), '-proj');
+  assert.equal(encodeProjectPath('/proj/.claude/worktrees/wt1'), '-proj--claude-worktrees-wt1');
+  assert.equal(encodeProjectPath('/Users/x/Desktop/Claude-OTB'), '-Users-x-Desktop-Claude-OTB');
+});
+
+test('encodeProjectPath: POSIX path containing a space', () => {
+  assert.equal(encodeProjectPath('/Users/x/My Project'), '-Users-x-My-Project');
+});
+
 // ---------- buildSessionDigest ----------
 
 // A small fixture in the real Claude Code transcript shape.

package/tests/session_reward_on_land.mjs

@@ -0,0 +1,381 @@
+// tests/session_reward_on_land.mjs
+//
+// Regression guard for ADR 0120 "pay on land" — the SESSION-TOKEN reward half
+// (the per-task credit half is pinned by tests/pay_on_land.mjs +
+// tests/confirm_attribution.mjs). The cost-plus session token reward
+// (reason='session.token_reward', task 1005/ADR 0054) must book only when the
+// code LANDS (a task the session shipped reaches status='shipped'), never at
+// upload time — so a session that strands at 'confirmed' collects nothing until
+// its code is on `main`.
+//
+// The design is a DUAL TRIGGER, both calling the SAME idempotent
+// awardSessionTokenReward (exactly-once via per-session_id idempotency):
+//   1. UPLOAD side — db.upsertSessionRecordWithReward awards inside the upload txn
+//      ONLY IF a task the session shipped is already status='shipped' (the
+//      sync/laptop order: land, then upload). Otherwise it DEFERS.
+//   2. LAND side — db.awardDeferredSessionRewardForTask(taskId), driven by
+//      routes/sessions.js's task.shipped listener, books the reward for every
+//      session that shipped that task (the ci/async order: upload, then land).
+//
+// The DB-free layer drives both db functions with a SQL-aware fake client:
+// upsertSessionRecordWithReward / awardDeferredSessionRewardForTask call
+// api.withTx(fn), so we patch api.withTx to hand fn our fake client, and register
+// the REAL economy `reward` port so the real awardSessionTokenReward SQL runs
+// against the fake (the confirm_attribution.mjs pattern). A guarded real-DB
+// block then proves the actual uniq_credit_session_token_reward_basis partial
+// index enforces exactly-once end-to-end, and that a costlier later ship tops up.
+//
+// Run:  node tests/session_reward_on_land.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+// The watermark idempotency SELECT (task 1002474) — replaced the old `SELECT 1 …`
+// existence probe, so the fakes must answer with { paid, legacy }.
+const WATERMARK_RE = /COALESCE\(SUM\(delta\)/;
+
+const require = createRequire(import.meta.url);
+// The session db slice resolves the economy `reward` kernel port; register it
+// (real provider) so awardSessionTokenReward's real SQL runs against our fake.
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const api = require('../src/module-api.js');
+const db = require('../modules/sessions/db.js');
+
+const { test, summary } = makeRunner();
+
+// Opus 110k input tokens → $0.55 true cost → $0.55 × 1.20 = 1 drachma (the same
+// priceable fixture credit_grant.mjs uses). A non-zero payout is what lets the
+// idempotency SELECT even run (awardSessionTokenReward short-circuits at $0).
+const MODEL_USAGE = { 'claude-opus-4-8': { input: 110_000 } };
+
+const norm = (q) => String(q.sql).replace(/\s+/g, ' ').trim();
+const find = (queries, re) => queries.find((q) => re.test(norm(q)));
+const all = (queries, re) => queries.filter((q) => re.test(norm(q)));
+
+// Drive a db function that opens api.withTx(fn) against a fake client whose
+// query() answers are dictated by `handler(normalizedSql)`. Returns the db
+// function's result + the recorded { sql, params } call log. Restores withTx.
+async function withFakeTx(handler, run) {
+  const fake = makeSqlAwareClient(handler);
+  const prev = api.withTx;
+  api.withTx = (fn) => fn(fake._client);
+  try {
+    const result = await run();
+    return { result, queries: fake.queries };
+  } finally {
+    api.withTx = prev;
+  }
+}
+
+// A session_records row as upsertSessionRecordTx's INSERT ... RETURNING yields it.
+function upsertReturns(sessionId, taskIds) {
+  return {
+    rows: [{
+      id: 101, session_id: sessionId, builder_id: 7, task_ids: taskIds,
+      drachmae_earned: 0, total_tokens: 5000, duration_seconds: 60,
+      uploaded_at: '2026-07-15T00:00:00Z',
+    }],
+  };
+}
+
+// =========================================================================
+// (1) UPLOAD side — DEFER when no shipped task (ci/async order)
+// =========================================================================
+
+await test('upsert: session task NOT shipped → NO reward INSERT (deferred), tokenReward.awarded === false', async () => {
+  const { result, queries } = await withFakeTx(
+    (s) => {
+      if (/^INSERT INTO session_records/.test(s)) return upsertReturns('sess-defer', [660]);
+      if (/SELECT 1 FROM tasks WHERE id = ANY/.test(s)) return { rows: [] }; // not landed yet
+      return null;
+    },
+    () => db.upsertSessionRecordWithReward({
+      sessionId: 'sess-defer', builderId: 7, taskIds: [660],
+      totalTokens: 5000, modelUsage: MODEL_USAGE,
+    })
+  );
+
+  // The land gate ran...
+  assert.ok(find(queries, /SELECT 1 FROM tasks WHERE id = ANY.*status = 'shipped'/),
+    'the pay-on-land gate (tasks status=shipped) must be consulted');
+  // ...found nothing shipped, so NO reward was booked.
+  assert.equal(all(queries, /INSERT INTO credit_log/).length, 0,
+    'a session with no landed task must NOT book a token reward at upload');
+  assert.equal(result.tokenReward.awarded, false, 'awarded must be false when deferred');
+  assert.equal(result.tokenReward.deferred, true, 'the deferred flag must be set');
+  // The digest itself is still recorded (the upsert ran + returned the row).
+  assert.ok(find(queries, /^INSERT INTO session_records/), 'the digest upsert still runs');
+  assert.equal(result.id, 101, 'the record is returned even when the reward defers');
+});
+
+await test('upsert: session with NO task_ids → deferred, gate not even queried', async () => {
+  const { result, queries } = await withFakeTx(
+    (s) => {
+      if (/^INSERT INTO session_records/.test(s)) return upsertReturns('sess-none', []);
+      return null;
+    },
+    () => db.upsertSessionRecordWithReward({
+      sessionId: 'sess-none', builderId: 7, taskIds: [],
+      totalTokens: 5000, modelUsage: MODEL_USAGE,
+    })
+  );
+  assert.equal(all(queries, /INSERT INTO credit_log/).length, 0, 'no tasks → no reward');
+  assert.ok(!find(queries, /FROM tasks WHERE id = ANY/), 'no task_ids → skip the gate query entirely');
+  assert.equal(result.tokenReward.awarded, false);
+});
+
+// =========================================================================
+// (2) UPLOAD side — AWARD when a task is already shipped (sync/laptop order)
+// =========================================================================
+
+await test('upsert: a task already shipped → awardSessionTokenReward runs (a session.token_reward INSERT)', async () => {
+  const { result, queries } = await withFakeTx(
+    (s) => {
+      if (/^INSERT INTO session_records/.test(s)) return upsertReturns('sess-land', [660]);
+      if (/SELECT 1 FROM tasks WHERE id = ANY/.test(s)) return { rows: [{ '?column?': 1 }] }; // landed
+      if (WATERMARK_RE.test(s)) return { rows: [{ paid: 0, legacy: 0 }] }; // nothing paid yet
+      if (/^INSERT INTO credit_log/.test(s)) return { rows: [{ id: 1 }] };
+      return null;
+    },
+    () => db.upsertSessionRecordWithReward({
+      sessionId: 'sess-land', builderId: 7, taskIds: [660],
+      totalTokens: 5000, modelUsage: MODEL_USAGE,
+    })
+  );
+
+  const insert = find(queries, /^INSERT INTO credit_log/);
+  assert.ok(insert, 'a credit_log INSERT must run once a task has landed');
+  assert.match(norm(insert), /session\.token_reward/, 'the reward reason must be session.token_reward');
+  // params: [builderId, drachmae, description, sessionId]
+  assert.equal(insert.params[0], 7, 'reward attributed to the session owner');
+  assert.equal(insert.params[1], 1, '$0.55 × 1.20 → 1 drachma');
+  assert.equal(insert.params[3], 'sess-land', 'idempotency key is the session_id');
+  assert.equal(result.tokenReward.awarded, true);
+  assert.equal(result.tokenReward.drachmae, 1);
+  // observability mirror onto session_records.token_reward_drachmae
+  assert.ok(find(queries, /^UPDATE session_records SET token_reward_drachmae/), 'mirror UPDATE runs on a fresh award');
+});
+
+// =========================================================================
+// (3) LAND side — awardDeferredSessionRewardForTask books the deferred reward
+// =========================================================================
+
+await test('awardDeferredSessionRewardForTask: session with the task + priceable usage → awards (INSERT for the session builder)', async () => {
+  const { result, queries } = await withFakeTx(
+    (s) => {
+      if (/^SELECT session_id, builder_id, model_usage, total_tokens FROM session_records/.test(s)) {
+        return { rows: [{ session_id: 'sess-ci', builder_id: 7, model_usage: MODEL_USAGE, total_tokens: 5000 }] };
+      }
+      if (WATERMARK_RE.test(s)) return { rows: [{ paid: 0, legacy: 0 }] }; // nothing paid yet
+      if (/^INSERT INTO credit_log/.test(s)) return { rows: [{ id: 2 }] };
+      return null;
+    },
+    () => db.awardDeferredSessionRewardForTask(660)
+  );
+
+  // The lookup is by task_ids array containment (the shipped task's id).
+  assert.ok(find(queries, /FROM session_records WHERE task_ids @> ARRAY/),
+    'sessions are found by task_ids containment of the shipped task');
+  const insert = find(queries, /^INSERT INTO credit_log/);
+  assert.ok(insert, 'a session.token_reward INSERT must run for the deferred session');
+  assert.match(norm(insert), /session\.token_reward/);
+  assert.equal(insert.params[0], 7, "attributed to the session record's builder_id");
+  assert.equal(insert.params[3], 'sess-ci', 'keyed on the session_id');
+  assert.equal(result.sessions, 1, 'one session scanned');
+  assert.equal(result.awarded, 1, 'one reward freshly booked');
+});
+
+await test('awardDeferredSessionRewardForTask: prior reward exists (idempotency SELECT returns a row) → NO second INSERT', async () => {
+  const { result, queries } = await withFakeTx(
+    (s) => {
+      if (/^SELECT session_id, builder_id, model_usage, total_tokens FROM session_records/.test(s)) {
+        return { rows: [{ session_id: 'sess-ci', builder_id: 7, model_usage: MODEL_USAGE, total_tokens: 5000 }] };
+      }
+      if (WATERMARK_RE.test(s)) return { rows: [{ paid: 999_999, legacy: 0 }] }; // ALREADY PAID IN FULL
+      return null;
+    },
+    () => db.awardDeferredSessionRewardForTask(660)
+  );
+
+  assert.ok(find(queries, WATERMARK_RE),
+    'the per-session watermark guard must be consulted');
+  assert.equal(all(queries, /INSERT INTO credit_log/).length, 0, 're-firing on a rewarded session is a no-op');
+  assert.ok(!find(queries, /^UPDATE session_records SET token_reward_drachmae/), 'no mirror UPDATE when nothing was booked');
+  assert.equal(result.sessions, 1);
+  assert.equal(result.awarded, 0, 'nothing freshly booked');
+});
+
+await test('awardDeferredSessionRewardForTask: no session shipped this task → clean no-op', async () => {
+  const { result, queries } = await withFakeTx(
+    (s) => {
+      if (/^SELECT session_id, builder_id, model_usage, total_tokens FROM session_records/.test(s)) return { rows: [] };
+      return null;
+    },
+    () => db.awardDeferredSessionRewardForTask(424242)
+  );
+  assert.equal(all(queries, /INSERT INTO credit_log/).length, 0);
+  assert.equal(result.sessions, 0);
+  assert.equal(result.awarded, 0);
+});
+
+await test('awardDeferredSessionRewardForTask: non-numeric id → immediate no-op (no DB touch)', async () => {
+  // No withTx patch — a bad id must return before opening a transaction.
+  const out = await db.awardDeferredSessionRewardForTask('not-a-number');
+  assert.deepEqual(out, { sessions: 0, awarded: 0 });
+});
+
+// =========================================================================
+// (4) REAL-DB — the actual uniq_credit_session_token_reward partial index
+//     enforces exactly-once across the two triggers. Guarded on DATABASE_URL
+//     (env.sh sets it); skipped cleanly otherwise.
+// =========================================================================
+
+if (process.env.DATABASE_URL) {
+  const pool = api.pool;
+  const suffix = `srol_${Date.now()}_${Math.floor(Math.random() * 1e6)}`;
+  const ctx = { builderId: null, versionId: `ver_${suffix}`, taskId: null };
+  let setupOk = false;
+  try {
+    const b = await pool.query(
+      `INSERT INTO builders (github_id, github_login, display_name) VALUES ($1,$2,$3) RETURNING id`,
+      [`gh_${suffix}`, `login_${suffix}`, `Test ${suffix}`]
+    );
+    ctx.builderId = Number(b.rows[0].id);
+    await pool.query(
+      `INSERT INTO versions (id, name, track, status) VALUES ($1,$2,'internal','planning')`,
+      [ctx.versionId, `V ${suffix}`]
+    );
+    const tk = await pool.query(
+      `INSERT INTO tasks (version_id, title, status) VALUES ($1,$2,'shipped') RETURNING id`,
+      [ctx.versionId, `shipped task ${suffix}`]
+    );
+    ctx.taskId = Number(tk.rows[0].id);
+    setupOk = true;
+  } catch (e) {
+    console.log(`  SKIP  real-DB block (setup failed: ${e.message})`);
+  }
+
+  if (setupOk) {
+    const rewardRows = (sessionId) => pool.query(
+      `SELECT delta FROM credit_log WHERE session_id = $1 AND reason = 'session.token_reward'`,
+      [sessionId]
+    );
+    try {
+      await test('real-DB: awardDeferredSessionRewardForTask books once + is idempotent (partial index)', async () => {
+        const sid = `sess-deferred-${suffix}`;
+        await pool.query(
+          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
+           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
+          [sid, ctx.builderId, ctx.taskId, 5000, JSON.stringify(MODEL_USAGE)]
+        );
+
+        const first = await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        assert.equal(first.awarded, 1, 'first land books the reward');
+        let rows = (await rewardRows(sid)).rows;
+        assert.equal(rows.length, 1, 'exactly one session.token_reward row');
+        assert.ok(rows[0].delta > 0, 'a positive drachmae payout landed');
+
+        const mirror = await pool.query(
+          `SELECT token_reward_drachmae FROM session_records WHERE session_id = $1`, [sid]
+        );
+        assert.ok(Number(mirror.rows[0].token_reward_drachmae) > 0, 'the drachmae is mirrored onto the row');
+
+        const second = await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        assert.equal(second.awarded, 0, 're-firing the land event is a no-op');
+        rows = (await rewardRows(sid)).rows;
+        assert.equal(rows.length, 1, 'the partial-unique index held — still exactly one row, no double payout');
+      });
+
+      // task 1002474 — the whole point of the watermark: a session that keeps
+      // spending after its first ship must be paid the difference, and the real
+      // (session_id, reward_basis) index must permit exactly that second row while
+      // still refusing a duplicate at the same basis.
+      await test('real-DB: a costlier later ship TOPS UP, and the top-up is itself idempotent', async () => {
+        const sid = `sess-topup-${suffix}`;
+        await pool.query(
+          `INSERT INTO session_records (session_id, builder_id, task_ids, total_tokens, model_usage)
+           VALUES ($1, $2, ARRAY[$3]::bigint[], $4, $5::jsonb)`,
+          [sid, ctx.builderId, ctx.taskId, 5000, JSON.stringify(MODEL_USAGE)]
+        );
+        await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        const afterFirst = (await rewardRows(sid)).rows;
+        assert.equal(afterFirst.length, 1, 'the first ship books one row');
+        const firstPaid = Number(afterFirst[0].delta);
+
+        // The session keeps working and gets much more expensive, then ships again.
+        const bigger = {};
+        for (const [model, usage] of Object.entries(MODEL_USAGE)) {
+          bigger[model] = Object.fromEntries(
+            Object.entries(usage).map(([k, v]) => [k, Number(v) * 40])
+          );
+        }
+        await pool.query(
+          `UPDATE session_records SET model_usage = $2::jsonb WHERE session_id = $1`,
+          [sid, JSON.stringify(bigger)]
+        );
+
+        const topup = await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        assert.equal(topup.awarded, 1, 'the grown session books a second row');
+        const afterTopup = (await rewardRows(sid)).rows;
+        assert.equal(afterTopup.length, 2, 'the (session_id, reward_basis) index PERMITS the increment');
+        const total = afterTopup.reduce((n, r) => n + Number(r.delta), 0);
+        assert.ok(total > firstPaid, 'the builder is now paid more than the first ship alone');
+        assert.ok(
+          afterTopup.every((r) => Number(r.delta) > 0),
+          'every row is a positive credit — a top-up never claws back'
+        );
+
+        // Re-firing at the SAME (unchanged) cost must add nothing.
+        const again = await db.awardDeferredSessionRewardForTask(ctx.taskId);
+        assert.equal(again.awarded, 0, 'no further payment when nothing changed');
+        assert.equal(
+          (await rewardRows(sid)).rows.length, 2,
+          'the index still refuses a duplicate at the same basis — exactly-once per level'
+        );
+      });
+
+      await test('real-DB: upsertSessionRecordWithReward DEFERS when the task is not shipped', async () => {
+        const sid = `sess-upload-defer-${suffix}`;
+        // A task id that is not status=shipped (nonexistent id → gate finds nothing).
+        const out = await db.upsertSessionRecordWithReward({
+          sessionId: sid, builderId: ctx.builderId, taskIds: [999_000_000 + Math.floor(Math.random() * 1000)],
+          totalTokens: 5000, modelUsage: MODEL_USAGE,
+        });
+        assert.equal(out.tokenReward.awarded, false, 'no landed task → deferred');
+        assert.equal(out.tokenReward.deferred, true);
+        assert.equal((await rewardRows(sid)).rows.length, 0, 'no reward row booked at upload');
+      });
+
+      await test('real-DB: upsertSessionRecordWithReward AWARDS when a task is already shipped', async () => {
+        const sid = `sess-upload-award-${suffix}`;
+        const out = await db.upsertSessionRecordWithReward({
+          sessionId: sid, builderId: ctx.builderId, taskIds: [ctx.taskId],
+          totalTokens: 5000, modelUsage: MODEL_USAGE,
+        });
+        assert.equal(out.tokenReward.awarded, true, 'a shipped task in the session → award at upload');
+        assert.ok(out.tokenReward.drachmae > 0);
+        assert.equal((await rewardRows(sid)).rows.length, 1, 'exactly one reward row');
+      });
+    } finally {
+      // FK-safe teardown (credit_log + session_records → builder; tasks → version).
+      try {
+        await pool.query(`DELETE FROM credit_log WHERE builder_id = $1`, [ctx.builderId]);
+        await pool.query(`DELETE FROM session_records WHERE builder_id = $1`, [ctx.builderId]);
+        await pool.query(`DELETE FROM tasks WHERE version_id = $1`, [ctx.versionId]);
+        await pool.query(`DELETE FROM versions WHERE id = $1`, [ctx.versionId]);
+        await pool.query(`DELETE FROM builders WHERE id = $1`, [ctx.builderId]);
+      } catch (e) {
+        console.log(`  WARN  real-DB teardown left rows (${e.message})`);
+      }
+    }
+  }
+} else {
+  console.log('  SKIP  real-DB block (no DATABASE_URL)');
+}
+
+// -------------------------------------------------------------------------
+summary();