@bongos/core 1.18.3 → 1.18.18

package/modules/platform-identity/tests/platform-identity.mjs

@@ -0,0 +1,388 @@
+// modules/platform-identity/tests/platform-identity.mjs
+//
+// DB-free unit suite for the hub identity-provider domain (ADR 0141, task #1002106).
+// Two layers: the pure crypto helpers (no DB), and the domain DB functions against
+// a RECORDING FAKE pool (asserts the SQL shape + params + the security invariants
+// without needing Postgres). Auto-run by scripts/gds/run-unit-tests.js ONLY when the
+// platform-identity module is enabled; run standalone:
+//   node modules/platform-identity/tests/platform-identity.mjs
+//
+// These assertions ARE the security spec for the grader-outage window: single-use
+// atomic redeem, code/secret hashed-at-rest, redirect_uri exact-match allow-list,
+// and identity-only redemption (never a rank).
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import crypto from 'node:crypto';
+
+const require = createRequire(import.meta.url);
+const P = require('../platform-identity.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// A recording fake pool: returns queued responses in order and records every call.
+function mockPool(responses = []) {
+  const calls = [];
+  let i = 0;
+  return {
+    calls,
+    query: async (text, params) => {
+      calls.push({ text: String(text), params: params || [] });
+      const r = responses[i++];
+      return r || { rows: [], rowCount: 0 };
+    },
+  };
+}
+
+console.log('pure crypto helpers:');
+
+t('sha256hex is deterministic + input-sensitive', () => {
+  assert.equal(P.sha256hex('abc'), P.sha256hex('abc'));
+  assert.notEqual(P.sha256hex('abc'), P.sha256hex('abd'));
+  assert.equal(P.sha256hex('abc'), crypto.createHash('sha256').update('abc').digest('hex'));
+});
+
+t('constantTimeEqualHex: equal → true, different → false, different length → false', () => {
+  const h = P.sha256hex('secret');
+  assert.equal(P.constantTimeEqualHex(h, h), true);
+  assert.equal(P.constantTimeEqualHex(h, P.sha256hex('other')), false);
+  assert.equal(P.constantTimeEqualHex(h, h.slice(0, 10)), false);
+  assert.equal(P.constantTimeEqualHex('', ''), true);
+});
+
+t('newOpaqueCode: url-safe, ~256-bit, unique across calls', () => {
+  const a = P.newOpaqueCode();
+  const b = P.newOpaqueCode();
+  assert.notEqual(a, b);
+  assert.match(a, /^[A-Za-z0-9_-]+$/, 'must be base64url (no +,/,=)');
+  // 32 bytes base64url → 43 chars.
+  assert.equal(a.length, 43);
+});
+
+t('clientSecretValid: correct secret true; wrong/absent false', () => {
+  const secret = 'a'.repeat(64);
+  const client = { secret_hash: P.sha256hex(secret) };
+  assert.equal(P.clientSecretValid(client, secret), true);
+  assert.equal(P.clientSecretValid(client, 'wrong'), false);
+  assert.equal(P.clientSecretValid(null, secret), false);
+  assert.equal(P.clientSecretValid({}, secret), false);
+});
+
+t('redirectUriAllowed: exact match only (no prefix/substring/host tricks)', () => {
+  const client = { redirect_uris: ['https://proj.cloudbongos.com/api/gds/auth/web/callback'] };
+  assert.equal(P.redirectUriAllowed(client, 'https://proj.cloudbongos.com/api/gds/auth/web/callback'), true);
+  // A longer path that has the allowed URI as a prefix must NOT match.
+  assert.equal(P.redirectUriAllowed(client, 'https://proj.cloudbongos.com/api/gds/auth/web/callback/evil'), false);
+  // A shorter/host-only variant must NOT match.
+  assert.equal(P.redirectUriAllowed(client, 'https://proj.cloudbongos.com'), false);
+  // A look-alike host must NOT match.
+  assert.equal(P.redirectUriAllowed(client, 'https://proj.cloudbongos.com.evil.test/api/gds/auth/web/callback'), false);
+  assert.equal(P.redirectUriAllowed(null, 'https://x'), false);
+  assert.equal(P.redirectUriAllowed({ redirect_uris: [] }, 'https://x'), false);
+});
+
+t('clientSecretValid fails closed for unknown/secretless client (decoy path, no throw)', () => {
+  // The decoy-hash path must still return false and must not throw — the timing is
+  // equalized, but an absent client can never authenticate.
+  assert.equal(P.clientSecretValid(undefined, 'anything'), false);
+  assert.equal(P.clientSecretValid({ status: 'suspended' }, 'anything'), false);
+  assert.equal(P.clientSecretValid({ secret_hash: '' }, 'anything'), false);
+});
+
+console.log('\nsessionUsableForFederation (the browser-leg deny gate):');
+
+t('a live full-authority web/cli session may federate', () => {
+  assert.deepEqual(
+    P.sessionUsableForFederation({ github_id: 1, status: 'active', source: 'web', system_role: null }),
+    { ok: true, reason: null });
+  assert.equal(P.sessionUsableForFederation({ github_id: 1, source: 'cli' }).ok, true);
+});
+
+t('a missing session → no_session (caller redirects to sign-in)', () => {
+  assert.deepEqual(P.sessionUsableForFederation(null), { ok: false, reason: 'no_session' });
+  assert.deepEqual(P.sessionUsableForFederation(undefined), { ok: false, reason: 'no_session' });
+});
+
+t('a deactivated account may NOT federate (mirrors requireBuilder status gate)', () => {
+  const r = P.sessionUsableForFederation({ github_id: 1, status: 'inactive', source: 'web' });
+  assert.deepEqual(r, { ok: false, reason: 'inactive' });
+});
+
+t('a dev-box-scoped token may NOT federate (outside the trust boundary)', () => {
+  const r = P.sessionUsableForFederation({ github_id: 1, status: 'active', source: 'box' });
+  assert.deepEqual(r, { ok: false, reason: 'box_scope' });
+});
+
+t('a service principal (system_role set) may NOT federate', () => {
+  const r = P.sessionUsableForFederation({ github_id: 1, status: 'active', source: 'web', system_role: 'bfg' });
+  assert.deepEqual(r, { ok: false, reason: 'service_principal' });
+});
+
+console.log('\naccounts:');
+
+await ta('upsertAccount upserts on github_id and returns the row', async () => {
+  const row = { id: '1', github_id: '42', github_login: 'octocat', display_name: 'Octo', avatar_url: 'a' };
+  const pool = mockPool([{ rows: [row] }]);
+  const out = await P.upsertAccount(
+    { githubId: 42, githubLogin: 'octocat', displayName: 'Octo', avatarUrl: 'a' }, { pool });
+  assert.deepEqual(out, row);
+  const c = pool.calls[0];
+  assert.match(c.text, /INSERT INTO platform_identity_accounts/);
+  assert.match(c.text, /ON CONFLICT \(github_id\) DO UPDATE/);
+  assert.deepEqual(c.params, [42, 'octocat', 'Octo', 'a']);
+});
+
+console.log('\nSSO client registry:');
+
+await ta('registerClient hashes the secret at rest — never stores the plaintext', async () => {
+  const secret = 'z'.repeat(64);
+  const pool = mockPool([{ rows: [{ client_id: 'c1' }] }]);
+  await P.registerClient(
+    { clientId: 'c1', secret, name: 'Proj', redirectUris: ['https://p/cb'], origin: 'https://p', ownerGithubId: 7 },
+    { pool });
+  const c = pool.calls[0];
+  assert.match(c.text, /INSERT INTO platform_identity_sso_clients/);
+  assert.match(c.text, /ON CONFLICT \(client_id\) DO UPDATE/);
+  // The secret param must be the HASH, and the plaintext must not appear anywhere.
+  assert.equal(c.params[1], P.sha256hex(secret), 'secret_hash param must be sha256(secret)');
+  assert.ok(!c.params.includes(secret), 'plaintext secret must never be a query param');
+  assert.deepEqual(c.params[3], ['https://p/cb'], 'redirect_uris array passed through');
+});
+
+await ta('getClient selects by client_id and returns null when unknown', async () => {
+  const pool = mockPool([{ rows: [] }]);
+  const out = await P.getClient('nope', { pool });
+  assert.equal(out, null);
+  assert.match(pool.calls[0].text, /FROM platform_identity_sso_clients WHERE client_id = \$1/);
+  assert.deepEqual(pool.calls[0].params, ['nope']);
+});
+
+await ta('getClientByOrigin resolves the ACTIVE client by normalized origin (the CLI-mint audience source)', async () => {
+  const pool = mockPool([{ rows: [{ client_id: 'c-victim', status: 'active' }] }]);
+  const out = await P.getClientByOrigin('https://victim.com/', { pool });
+  assert.equal(out.client_id, 'c-victim');
+  // Trailing slash normalized; gated to active clients only.
+  assert.deepEqual(pool.calls[0].params, ['https://victim.com']);
+  assert.match(pool.calls[0].text, /WHERE origin = \$1 AND status = 'active'/);
+});
+
+await ta('getClientByOrigin returns null for an unregistered origin (federation refuses)', async () => {
+  const pool = mockPool([{ rows: [] }]);
+  assert.equal(await P.getClientByOrigin('https://evil.example', { pool }), null);
+  // Empty / missing origin never hits the DB.
+  const pool2 = mockPool([]);
+  assert.equal(await P.getClientByOrigin('', { pool: pool2 }), null);
+  assert.equal(pool2.calls.length, 0);
+});
+
+console.log('\nprojects catalog + Explore (§5):');
+
+await ta('upsertProject upserts on normalized origin; update preserves tagline/art (COALESCE)', async () => {
+  const pool = mockPool([{ rows: [{ id: '1', origin: 'https://p', featured: false }] }]);
+  await P.upsertProject({ origin: 'https://p/', name: 'Proj' }, { pool });
+  const c = pool.calls[0];
+  assert.match(c.text, /INSERT INTO platform_identity_projects/);
+  assert.match(c.text, /ON CONFLICT \(origin\) DO UPDATE/);
+  assert.match(c.text, /tagline\s*=\s*COALESCE/);
+  assert.equal(c.params[0], 'https://p', 'trailing slash normalized');
+  // Never sets featured on upsert — that is Archon-only.
+  assert.doesNotMatch(c.text, /featured\s*=/);
+});
+
+await ta('listFeaturedProjects returns a PUBLIC projection (featured+active only, no owner/status)', async () => {
+  const pool = mockPool([{ rows: [{ origin: 'https://p', name: 'Proj', tagline: 't', art_url: null }] }]);
+  const out = await P.listFeaturedProjects({ pool });
+  assert.equal(out.length, 1);
+  const c = pool.calls[0];
+  assert.match(c.text, /WHERE featured = true AND status = 'active'/);
+  assert.doesNotMatch(c.text, /owner_github_id/, 'public projection must not leak owner id');
+});
+
+await ta('setProjectFeatured flips the flag (Archon curation)', async () => {
+  const pool = mockPool([{ rows: [{ id: '1', featured: true }] }]);
+  const out = await P.setProjectFeatured(1, true, { pool });
+  assert.equal(out.featured, true);
+  assert.match(pool.calls[0].text, /UPDATE platform_identity_projects SET featured = \$2/);
+  assert.deepEqual(pool.calls[0].params, [1, true]);
+});
+
+await ta('registerClient auto-catalogues the project (2nd query) when an origin is given', async () => {
+  const pool = mockPool([{ rows: [{ client_id: 'c1', origin: 'https://p' }] }, { rows: [{ id: '9' }] }]);
+  await P.registerClient({ clientId: 'c1', secret: 'z'.repeat(64), name: 'Proj', redirectUris: [], origin: 'https://p', ownerGithubId: 7 }, { pool });
+  assert.equal(pool.calls.length, 2, 'client insert + project upsert');
+  assert.match(pool.calls[1].text, /INSERT INTO platform_identity_projects/);
+});
+
+console.log('\nproject memberships (§3 check-in directory):');
+
+await ta('upsertMembership upserts on (client_id, github_id) with a coarse role', async () => {
+  const pool = mockPool([{ rows: [{ id: '1', client_id: 'c1', github_id: '42', role: 'owner' }] }]);
+  await P.upsertMembership({ clientId: 'c1', githubId: 42, role: 'owner' }, { pool });
+  const c = pool.calls[0];
+  assert.match(c.text, /INSERT INTO platform_identity_project_memberships/);
+  assert.match(c.text, /ON CONFLICT \(client_id, github_id\) DO UPDATE/);
+  assert.match(c.text, /last_active = now\(\)/);
+  assert.deepEqual(c.params, ['c1', 42, 'owner']);
+});
+
+await ta('upsertMembership clamps an unknown role to builder (never trusts a caller role blindly)', async () => {
+  const pool = mockPool([{ rows: [{}] }]);
+  await P.upsertMembership({ clientId: 'c1', githubId: 42, role: 'archon' }, { pool });
+  assert.equal(pool.calls[0].params[2], 'builder', 'a non-coarse role is clamped to builder');
+});
+
+await ta('removeMembership deletes the (client_id, github_id) row (self-service leave)', async () => {
+  const pool = mockPool([{ rowCount: 1 }]);
+  const n = await P.removeMembership('c1', 42, { pool });
+  assert.equal(n, 1);
+  assert.match(pool.calls[0].text, /DELETE FROM platform_identity_project_memberships WHERE client_id = \$1 AND github_id = \$2/);
+  assert.deepEqual(pool.calls[0].params, ['c1', 42]);
+});
+
+await ta('listMembershipsForAccount joins projects + excludes pending', async () => {
+  const pool = mockPool([{ rows: [{ client_id: 'c1', role: 'builder', project_name: 'Proj' }] }]);
+  const out = await P.listMembershipsForAccount(42, { pool });
+  assert.equal(out.length, 1);
+  const c = pool.calls[0];
+  assert.match(c.text, /FROM platform_identity_project_memberships m/);
+  assert.match(c.text, /LEFT JOIN platform_identity_sso_clients c/);
+  assert.match(c.text, /role <> 'pending'/);
+  assert.deepEqual(c.params, [42]);
+});
+
+console.log('\ninvitations (§5 — pre-seed pending membership):');
+
+await ta('inviteToProject pre-seeds a pending row, never clobbering an existing member', async () => {
+  const pool = mockPool([{ rows: [{ id: '1', role: 'pending' }] }]);
+  const out = await P.inviteToProject({ clientId: 'c1', githubId: 42 }, { pool });
+  assert.equal(out.invited, true);
+  const c = pool.calls[0];
+  assert.match(c.text, /INSERT INTO platform_identity_project_memberships/);
+  assert.match(c.text, /VALUES \(\$1, \$2, 'pending'\)/);
+  assert.match(c.text, /ON CONFLICT \(client_id, github_id\) DO NOTHING/, 'must not downgrade an existing member');
+});
+
+await ta('inviteToProject reports already-member when the row exists (DO NOTHING → no row)', async () => {
+  const pool = mockPool([{ rows: [] }]);
+  const out = await P.inviteToProject({ clientId: 'c1', githubId: 42 }, { pool });
+  assert.deepEqual(out, { invited: false, alreadyMember: true });
+});
+
+await ta('resolveInvite accept flips ONLY a pending row to builder', async () => {
+  const pool = mockPool([{ rows: [{ id: '1' }] }]);
+  const out = await P.resolveInvite({ clientId: 'c1', githubId: 42, accept: true }, { pool });
+  assert.deepEqual(out, { resolved: true, accepted: true });
+  const c = pool.calls[0];
+  assert.match(c.text, /UPDATE platform_identity_project_memberships SET role = 'builder'/);
+  assert.match(c.text, /AND role = 'pending'/, 'only touches pending — never a real member');
+});
+
+await ta('resolveInvite decline deletes ONLY a pending row', async () => {
+  const pool = mockPool([{ rowCount: 1 }]);
+  const out = await P.resolveInvite({ clientId: 'c1', githubId: 42, accept: false }, { pool });
+  assert.deepEqual(out, { resolved: true, accepted: false });
+  assert.match(pool.calls[0].text, /DELETE FROM platform_identity_project_memberships[\s\S]*AND role = 'pending'/);
+});
+
+await ta('getAccountByLogin resolves case-insensitively, newest first', async () => {
+  const pool = mockPool([{ rows: [{ github_id: '42', github_login: 'Octo' }] }]);
+  const out = await P.getAccountByLogin('octo', { pool });
+  assert.equal(out.github_id, '42');
+  assert.match(pool.calls[0].text, /lower\(github_login\) = lower\(\$1\)/);
+});
+
+console.log('\ncross-project activity (§4 scouting data plane):');
+
+await ta('upsertActivity upserts per (client_id, github_id) with the talent snapshot', async () => {
+  const pool = mockPool([{ rows: [{ id: '1' }] }]);
+  await P.upsertActivity({ clientId: 'c1', githubId: 42, credits: 100, tasksShipped: 5, karma: 3, rank: 'metic', disciplines: ['engineer'] }, { pool });
+  const c = pool.calls[0];
+  assert.match(c.text, /INSERT INTO platform_identity_builder_project_activity/);
+  assert.match(c.text, /ON CONFLICT \(client_id, github_id\) DO UPDATE/);
+  assert.deepEqual(c.params, ['c1', 42, 100, 5, 3, 'metic', ['engineer']]);
+});
+
+await ta('listScoutingRollup aggregates per builder across projects, ranked, joined to accounts', async () => {
+  const pool = mockPool([{ rows: [{ github_id: '42', github_login: 'octo', total_credits: 250, project_count: 2 }] }]);
+  const out = await P.listScoutingRollup({ pool, limit: 50 });
+  assert.equal(out.length, 1);
+  const c = pool.calls[0];
+  assert.match(c.text, /FROM platform_identity_builder_project_activity a/);
+  assert.match(c.text, /GROUP BY a\.github_id/);
+  assert.match(c.text, /sum\(a\.credits\)/);
+  assert.match(c.text, /ORDER BY total_credits DESC/);
+  assert.deepEqual(c.params, [50]);
+});
+
+console.log('\nauthorization codes:');
+
+await ta('mintAuthCode stores the HASH of the code (never the plaintext) + binds it', async () => {
+  const pool = mockPool([{ rows: [] }]);
+  const code = await P.mintAuthCode(
+    { clientId: 'c1', githubId: 42, githubLogin: 'octocat', displayName: 'Octo', avatarUrl: 'a',
+      redirectUri: 'https://p/cb' },
+    { pool });
+  assert.match(code, /^[A-Za-z0-9_-]{43}$/, 'returns a fresh opaque code');
+  const c = pool.calls[0];
+  assert.match(c.text, /INSERT INTO platform_identity_auth_codes/);
+  // param 0 is code_hash — it must equal sha256(returned code), and the plaintext
+  // code must NOT be among the params.
+  assert.equal(c.params[0], P.sha256hex(code), 'code_hash param must be sha256(code)');
+  assert.ok(!c.params.includes(code), 'plaintext code must never be a query param');
+  // Binding: client_id, github_id, redirect_uri present.
+  assert.equal(c.params[1], 'c1');
+  assert.equal(c.params[2], 42);
+  assert.equal(c.params[3], 'https://p/cb');
+  // expires_at (last param) is a Date in the near future (~<= default TTL).
+  const exp = c.params[7];
+  assert.ok(exp instanceof Date, 'expires_at is a Date');
+  const dt = exp.getTime() - Date.now();
+  assert.ok(dt > 0 && dt <= P.DEFAULT_CODE_TTL_MS + 1000, `TTL ~${P.DEFAULT_CODE_TTL_MS}ms`);
+});
+
+await ta('redeemAuthCode is an ATOMIC single-use redeem, bound + identity-only', async () => {
+  const identity = { github_id: '42', github_login: 'octocat', display_name: 'Octo', avatar_url: 'a', redirect_uri: 'https://p/cb' };
+  const pool = mockPool([{ rows: [identity] }]);
+  const code = 'plain-code-value';
+  const out = await P.redeemAuthCode({ code, clientId: 'c1' }, { pool });
+  assert.deepEqual(out, identity);
+  const c = pool.calls[0];
+  // Atomic single-use: one UPDATE that sets consumed_at AND guards on it being NULL.
+  assert.match(c.text, /UPDATE platform_identity_auth_codes/);
+  assert.match(c.text, /SET consumed_at = now\(\)/);
+  assert.match(c.text, /consumed_at IS NULL/);
+  assert.match(c.text, /expires_at > now\(\)/);
+  assert.match(c.text, /RETURNING/);
+  // Looked up by the HASH of the presented code + bound to the client.
+  assert.equal(c.params[0], P.sha256hex(code), 'looked up by sha256(code)');
+  assert.equal(c.params[1], 'c1');
+  // Identity-only: the RETURNING clause must not leak a rank / credits / token.
+  assert.doesNotMatch(c.text, /\brank\b/i, 'redeem must never return a rank');
+  assert.doesNotMatch(c.text, /\bcredits?\b/i, 'redeem must never return credits');
+  assert.doesNotMatch(c.text, /\btoken\b/i, 'redeem must never return a session token');
+});
+
+await ta('redeemAuthCode returns null on no-match (consumed/expired/wrong client)', async () => {
+  const pool = mockPool([{ rows: [] }]);
+  const out = await P.redeemAuthCode({ code: 'x', clientId: 'c1' }, { pool });
+  assert.equal(out, null);
+});
+
+await ta('sweepExpiredCodes deletes expired + long-consumed rows', async () => {
+  const pool = mockPool([{ rowCount: 3 }]);
+  const n = await P.sweepExpiredCodes({ pool });
+  assert.equal(n, 3);
+  assert.match(pool.calls[0].text, /DELETE FROM platform_identity_auth_codes/);
+  assert.match(pool.calls[0].text, /expires_at < now\(\)/);
+});
+
+console.log(`\nplatform-identity: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/modules/security/routes/reports.js

@@ -137,6 +137,12 @@ module.exports = function buildSecurityReportsRouter() {
     api.requireBuilder,
     api.requireRank('archon'),
     async (req, res) => {
+      // drachmae_awarded is OPTIONAL and deliberately UNTYPED here: the handler
+      // accepts a number, a stringified number, '' and null alike, and the inline
+      // check below is what enforces finite/non-negative. Declaring a type would
+      // narrow the live contract; declaring the field at all is what lets the
+      // validator reject UNKNOWN fields, which is the actual gap (BV1.R109c).
+      if (validateOrRespond(req, res, { drachmae_awarded: {} })) return;
       const id = parseId(req, res, { code: 'bad_report_id', positiveInt: true });
       if (id === null) return;
       const drachmaeRaw = req.body?.drachmae_awarded;
@@ -221,6 +227,10 @@ module.exports = function buildSecurityReportsRouter() {
     api.requireBuilder,
     api.requireRank('archon'),
     async (req, res) => {
+      // task_id is REQUIRED but untyped: the handler accepts a number or a
+      // stringified number and coerces below, so a type would narrow the live
+      // contract. Same idiom as POST /tasks/:id/dependencies (BV1.R109c).
+      if (validateOrRespond(req, res, { task_id: { required: true } })) return;
       const id = parseId(req, res, { code: 'bad_report_id', positiveInt: true });
       if (id === null) return;
       const taskIdRaw = req.body?.task_id;

package/modules/sessions/db.js

@@ -109,41 +109,184 @@ async function upsertSessionRecord(opts) {
   return upsertSessionRecordTx(pool, opts);
 }
 
+// awardSessionTokenRewardTx — resolve the economy `reward` port and book the
+// idempotent cost-plus session token reward on `client`, mirroring the granted
+// drachmae onto the session_records row for observability (the authoritative
+// payout is the credit_log row; token_reward_drachmae is a mirror — migration
+// 091). Returns the reward result ({ drachmae, awarded, ... }). Degrades to a
+// clean no-op when economy is disabled (no `reward` provider). Shared by BOTH
+// pay-on-land triggers (the upload-side gate below + the task.shipped listener
+// via awardDeferredSessionRewardForTask) so both book the reward identically;
+// per-session watermark idempotency (the SELECT fast-path + the
+// uniq_credit_session_token_reward_basis partial index) makes a double-attempt
+// safe, and lets a later, costlier ship in the same session book its increment.
+// task 1676: pass totalTokens so the reward can fall back to pricing the
+// session's real token total when modelUsage is empty/unpriceable — the
+// dev-box/CI agent path that historically paid $0 cost-plus (ADR 0097).
+async function awardSessionTokenRewardTx(client, { builderId, sessionId, modelUsage, totalTokens }) {
+  const reward = seams.resolveOptional('reward');
+  if (!reward) return { drachmae: 0, trueCostUsd: 0, awarded: false, unknownModels: [], deferred: false };
+  const tokenReward = await reward.awardSessionTokenReward(
+    client, builderId, sessionId, modelUsage || {}, totalTokens || 0
+  );
+  if (tokenReward && tokenReward.awarded && tokenReward.drachmae > 0) {
+    await client.query(
+      `UPDATE session_records
+          SET token_reward_drachmae = token_reward_drachmae + $2
+        WHERE session_id = $1 AND builder_id = $3`,
+      [sessionId, tokenReward.drachmae, builderId]
+    );
+  }
+  return tokenReward;
+}
+
 // upsertSessionRecordWithReward — ONE transaction: upsert the session digest
-// (incl. model_usage), then compute + award the idempotent cost-plus token
-// reward (task 1005, ADR 0054) and mirror token_reward_drachmae onto the row.
-// Returns the record augmented with { tokenReward }. The token reward is a
-// SEPARATE credit_log row (reason='session.token_reward'); total_credits is
+// (incl. model_usage), then — the UPLOAD-side half of ADR 0120 "pay on land" —
+// book the cost-plus token reward (task 1005, ADR 0054) ONLY IF the code has
+// already LANDED. Returns the record augmented with { tokenReward }. The reward
+// is a SEPARATE credit_log row (reason='session.token_reward'); total_credits is
 // bumped by the credit_log trigger only, never double-counted here.
+//
+// ADR 0120: the reward is contingent on the SHIP, not the upload. ship.js orders
+// differ by mode: sync/laptop mode LANDS the task (status='shipped') then uploads
+// the digest, so at upload time a task is already shipped → we award now. ci/async
+// mode UPLOADS the digest first and lands later, so no task is shipped yet → we
+// DEFER (record the digest, award nothing) and the reward books when the
+// task.shipped event fires (routes/sessions.js's listener →
+// awardDeferredSessionRewardForTask). Both triggers call the SAME idempotent
+// award, so exactly-once is guaranteed by the per-session_id credit_log
+// idempotency — never by which trigger wins the race.
 async function upsertSessionRecordWithReward(opts) {
   return api.withTx(async (client) => {
     const record = await upsertSessionRecordTx(client, opts);
-    let tokenReward = { drachmae: 0, trueCostUsd: 0, awarded: false, unknownModels: [] };
+    // Deferred by default (ADR 0120): the digest is recorded, but the token
+    // reward only books once at least one of the session's tasks has landed.
+    let tokenReward = { drachmae: 0, trueCostUsd: 0, awarded: false, unknownModels: [], deferred: true };
     if (record) {
       // record is non-null only when the ownership guard passed (the row is the
-      // caller's), so the reward is always attributed to the verified owner.
-      // Token reward lives in modules/economy/ (BV1.R77 / ADR 0093 §1-2):
-      // resolve the `reward` kernel port and award inside this same txn (the
-      // module↔module seam — no sibling require).
-      // task 1676: pass totalTokens so the reward can fall back to pricing the
-      // session's real token total when modelUsage is empty/unpriceable — the
-      // dev-box/CI agent path that historically paid $0 cost-plus (ADR 0097).
-      tokenReward = await seams.resolveOptional('reward').awardSessionTokenReward(
-        client, opts.builderId, opts.sessionId, opts.modelUsage || {}, opts.totalTokens || 0
-      );
-      if (tokenReward.awarded && tokenReward.drachmae > 0) {
-        await client.query(
-          `UPDATE session_records
-              SET token_reward_drachmae = token_reward_drachmae + $2
-            WHERE session_id = $1 AND builder_id = $3`,
-          [opts.sessionId, tokenReward.drachmae, opts.builderId]
+      // caller's), so any reward is always attributed to the verified owner.
+      // Gate on the SHIP: award now iff at least one of the session's task_ids
+      // has reached status='shipped'. Otherwise leave the deferred default.
+      const ids = Array.isArray(record.task_ids)
+        ? record.task_ids.map((n) => Number(n)).filter(Number.isFinite)
+        : [];
+      let landed = false;
+      if (ids.length > 0) {
+        const { rows } = await client.query(
+          `SELECT 1 FROM tasks WHERE id = ANY($1::bigint[]) AND status = 'shipped' LIMIT 1`,
+          [ids]
         );
+        landed = rows.length > 0;
+      }
+      if (landed) {
+        tokenReward = await awardSessionTokenRewardTx(client, {
+          builderId: opts.builderId,
+          sessionId: opts.sessionId,
+          modelUsage: opts.modelUsage || {},
+          totalTokens: opts.totalTokens || 0,
+        });
       }
     }
     return record ? { ...record, tokenReward } : null;
   });
 }
 
+// awardDeferredSessionRewardForTask — the LAND-side half of ADR 0120 "pay on
+// land". When a task reaches status='shipped', routes/sessions.js's task.shipped
+// listener calls this with the shipped task id. It finds every session_record
+// that shipped this task and books the cost-plus token reward for each — the
+// ci/async path, where the digest was uploaded (and DEFERRED) before the code
+// landed. Opens its own transaction.
+//
+// We do NOT pre-filter on token_reward_drachmae: awardSessionTokenReward is
+// idempotent per session_id, so a session that already collected at upload time
+// (sync mode) — or a re-fired event — is a clean no-op. The credit_log is the
+// single source of truth for "already paid"; the mirror column is only
+// observability, so it is never the idempotency key. Returns { sessions, awarded }
+// (rows scanned, rewards freshly booked).
+async function awardDeferredSessionRewardForTask(taskId) {
+  const id = Number(taskId);
+  if (!Number.isFinite(id)) return { sessions: 0, awarded: 0 };
+  return api.withTx(async (client) => {
+    const { rows } = await client.query(
+      `SELECT session_id, builder_id, model_usage, total_tokens
+         FROM session_records
+        WHERE task_ids @> ARRAY[$1]::bigint[]`,
+      [id]
+    );
+    let awarded = 0;
+    for (const r of rows) {
+      const tokenReward = await awardSessionTokenRewardTx(client, {
+        builderId: r.builder_id,
+        sessionId: r.session_id,
+        modelUsage: r.model_usage || {},
+        totalTokens: r.total_tokens || 0,
+      });
+      if (tokenReward && tokenReward.awarded && tokenReward.drachmae > 0) awarded += 1;
+    }
+    return { sessions: rows.length, awarded };
+  });
+}
+
+// reconcileUnbookedSessionRewards — the STATE-BASED safety net for the deferred
+// cost-plus session-token reward (ADR 0120). Today the reward books via two LIVE
+// triggers only: upsertSessionRecordWithReward (upload-time, iff a task the
+// session shipped is already status='shipped') and awardDeferredSessionRewardForTask
+// (driven by the in-process `task.shipped` event listener). Both MISS a task that
+// reaches status='shipped' OUT OF BAND — a direct-SQL / hotpatch flip, or a ship
+// performed in a DIFFERENT process — because no `task.shipped` event fires in THIS
+// server to release the deferred reward. Such a session's drachmae then strand
+// PERMANENTLY even though the code genuinely landed. (This is routine on a box that
+// hotpatches / ships with --skip-grade.) This idempotent sweep closes that gap:
+// it finds every session whose task is now genuinely 'shipped' but that carries no
+// session.token_reward row, and books it.
+//
+// Mirrors the task 1679 achievements reconcile — the accepted precedent for
+// "the event trigger missed some ships, so reconcile from durable STATE, not the
+// event." Design invariants:
+//   • STRICTLY pay-on-land: the JOIN requires t.status='shipped', so a task stuck
+//     at 'confirmed' is NEVER paid (ADR 0120 — never pay for code that didn't land).
+//   • Touches NO GitHub and sits behind NO push-credential guard — its whole point
+//     is to run on a CREDENTIAL-LESS box (the cloudbongos shape) and recover
+//     already-shipped work the reconciler-push-gap left unbooked.
+//   • Idempotent via the SAME watermark guard awardSessionTokenReward enforces (the
+//     SELECT fast-path + the uniq_credit_session_token_reward_basis partial index),
+//     so a re-sweep — or a race with a live trigger — never double-pays.
+// Returns { scanned, awarded }.
+async function reconcileUnbookedSessionRewards({ limit = 200 } = {}) {
+  // undefined → the destructuring default (200); a finite number clamps to
+  // [1, 1000] (so an explicit 0/negative floors at 1, never an unbounded scan);
+  // garbage (NaN, 'abc') falls back to 200.
+  const n = Number(limit);
+  const cap = Number.isFinite(n) ? Math.max(1, Math.min(1000, Math.trunc(n))) : 200;
+  return api.withTx(async (client) => {
+    const { rows } = await client.query(
+      `SELECT DISTINCT sr.session_id, sr.builder_id, sr.model_usage, sr.total_tokens
+         FROM session_records sr
+         JOIN tasks t ON t.id = ANY(sr.task_ids) AND t.status = 'shipped'
+        WHERE sr.session_id IS NOT NULL
+          AND NOT EXISTS (
+                SELECT 1 FROM credit_log cl
+                 WHERE cl.session_id = sr.session_id
+                   AND cl.reason = 'session.token_reward')
+        ORDER BY sr.session_id
+        LIMIT $1`,
+      [cap]
+    );
+    let awarded = 0;
+    for (const r of rows) {
+      const tokenReward = await awardSessionTokenRewardTx(client, {
+        builderId: r.builder_id,
+        sessionId: r.session_id,
+        modelUsage: r.model_usage || {},
+        totalTokens: r.total_tokens || 0,
+      });
+      if (tokenReward && tokenReward.awarded && tokenReward.drachmae > 0) awarded += 1;
+    }
+    return { scanned: rows.length, awarded };
+  });
+}
+
 // ---- 6D.2: session search + fetch (read side, ADR 0027) -------------------
 
 // Safe ORDER BY whitelist — the ONLY value interpolated into the search SQL, so
@@ -314,6 +457,8 @@ module.exports = {
   // write side (6D.1)
   upsertSessionRecord,
   upsertSessionRecordWithReward, // route entry point — upsert + token reward (task 1005)
+  awardDeferredSessionRewardForTask, // ADR 0120 land-side trigger — task.shipped listener calls it
+  reconcileUnbookedSessionRewards, // ADR 0120 state-based safety net — books rewards for out-of-band ships
   // search + fetch (6D.2)
   searchSessions,
   summarizeSessions,

package/modules/sessions/module.json

@@ -4,7 +4,7 @@
   "description": "The session-records corpus + its data plane (POST /sessions upload, the Archon-gated cross-builder /sessions/search + /sessions/:id deep-dive), the BFG 'read-the-room' cross-builder scorer (ADR 0026 §6B), and the session-pulse / stale-claim heartbeat helpers. A core-domain module carved out of the GDS core in BV1.R82 (ADR 0093 §1); default-on because every instance records its builders' sessions for the BFG. Like the memory module, sessions registers no port — core never calls back into it: the ship-time digest write is an HTTP POST to the module's own /sessions route, and the only outward dependency is the economy `reward` kernel PORT it resolves (session token reward + sumCreditsForTasks) at upload time.",
   "coreVersion": "^1.10.0",
   "default": true,
-  "contributes": { "routes": ["sessions"] },
+  "contributes": { "routes": ["sessions"], "pollers": ["session-reward-reconcile"] },
   "provides": [],
   "consumes": []
 }