@bongos/core 1.19.153 → 1.19.155

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.153",
-  "core_contract": "1.19.153",
-  "source_commit": "1c17819c21e41fd19e87ef09db8074217573cfbc",
+  "core_version": "1.19.155",
+  "core_contract": "1.19.155",
+  "source_commit": "64b481f3953b847b3950e606203102e1d130fbc9",
   "source_ref": "HEAD",
-  "built_at": "2026-08-16T15:45:14.904Z",
+  "built_at": "2026-08-16T16:05:24.376Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 304,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1254,
+    "functional_verbatim": 1255,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1579,
-  "tree_sha256": "37dfe72cba7625d785b1ef4871d14fa1d8427c10d27429fd2fe7bccfe4eb492f",
+  "file_count": 1580,
+  "tree_sha256": "6da1e49fcc1c83ee83beaf54277f2ab817dba9dea35185de47e0528a4e9e53aa",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -4107,7 +4107,7 @@
     {
       "path": "modules/sessions/db.js",
       "mode": "0000644",
-      "sha256": "fde41184b9f82f51dc5fff5df081d3435d296c3132fb619183996c250d621692"
+      "sha256": "65cb78d4a3e0507df5d2b37ac99cdb3d762b98de5c34996f64c6de7ad38dc71a"
     },
     {
       "path": "modules/sessions/module.json",
@@ -4117,7 +4117,7 @@
     {
       "path": "modules/sessions/pollers/session-reward-reconcile.js",
       "mode": "0000644",
-      "sha256": "8d08704aa90f14c8f1a653bc7dc252ddca983dc309f7fa0e190070878a3856e3"
+      "sha256": "32942d1169776ff1b2a32b85269c285f52167a6f3a7add7e38f74f108a9f3f42"
     },
     {
       "path": "modules/sessions/pulse.js",
@@ -4187,12 +4187,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b4eb6ecd20ea8082543a6cc794599b8c4fa46fc6ba15b90823fd8ad98305de05"
+      "sha256": "356b00e692fa069d4f14d94317d0c126ef5c35879491be3fb41ea7c8536d3059"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "36635f9e27784771de1f3630b1a8d304e66cdba1be334a1aeefdf0bdba6f1584"
+      "sha256": "62448d273d09db942d8c9fa123c8a6238070ca9bf754a6ecf0ea664d2c170df5"
     },
     {
       "path": "public-docs/index.html",
@@ -4877,12 +4877,12 @@
     {
       "path": "scripts/gds/gen-repo-map.js",
       "mode": "0000644",
-      "sha256": "5b5a3a160dcf65745e052bb08a85a707cdae67ecab2228487fce15872783a673"
+      "sha256": "138c53e17099ef3d5f8809f1be6311e07c4bdd4bd7dd6def2c7c6c57a2e8ba67"
     },
     {
       "path": "scripts/gds/gen-session-index.js",
       "mode": "0000644",
-      "sha256": "93b76f22c490a28cdf64a62795c3e7f67bf3b86d2a5331d8d4eed2550a2d89db"
+      "sha256": "c7bdbd7f7a4d2647be17ad37b540afc35913db80d121000346256d57c065f9fa"
     },
     {
       "path": "scripts/gds/git-merge-regen.js",
@@ -5782,7 +5782,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "1be644246d1a0e4b152aecd23ce219d4315c5aca5b911b5b4ca7738ac92d9bcf"
+      "sha256": "bc766f15de530f14ccf76f0b280e58f4ec594efebea6570744012fc5483b98d4"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7457,7 +7457,7 @@
     {
       "path": "tests/repo_map.mjs",
       "mode": "0000644",
-      "sha256": "b88208852062b4e8c8efcb44380e13205cd4d5ece7eed4e6c340a0ea969b33a9"
+      "sha256": "12fe5a30bfebce58aa179767590df53cc5f220a1f7257bded08aef94fbe43507"
     },
     {
       "path": "tests/reward_gate.mjs",
@@ -7579,6 +7579,11 @@
       "mode": "0000644",
       "sha256": "921c24a356d0fc1f398563bab3e8bb6f0831919a6954d86b6d74fdc60ff3b5f9"
     },
+    {
+      "path": "tests/session_attach_from_claim.mjs",
+      "mode": "0000644",
+      "sha256": "e76a3baf5fb2cdee08ffe8d80c55630b5ab4f708046f3c63c07c480926ccda31"
+    },
     {
       "path": "tests/session_caps.mjs",
       "mode": "0000644",
@@ -7612,7 +7617,7 @@
     {
       "path": "tests/session_reward_on_land.mjs",
       "mode": "0000644",
-      "sha256": "62d0b356029aca4ea307957951aba7ec677598c152ce68caee5001c6c36f9323"
+      "sha256": "52be7bd7afd17f7f7d1c93efb9be32902d08062cd65f35e3e3709a0e3669050f"
     },
     {
       "path": "tests/session_reward_reconcile.mjs",

package/modules/sessions/db.js

@@ -191,6 +191,67 @@ async function upsertSessionRecordWithReward(opts) {
   });
 }
 
+// attachClaimSessionsToTaskTx — SERVER-SIDE task↔session attribution (task
+// 1002964). Every payout path keys on session_records.task_ids, and until this
+// existed exactly ONE thing ever populated that column: ship.js's client-side
+// upload (`task_ids: [taskId]`). When that upload skipped — no
+// CLAUDE_CODE_SESSION_ID, an unsafe id, or a transcript the client couldn't find
+// (classifyUploadSkip, scripts/gds/ship.js) — the session was left with an EMPTY
+// task_ids, which matches NOTHING in awardDeferredSessionRewardForTask,
+// reconcileUnbookedSessionRewards, or the upload-side gate. The reward then
+// stranded PERMANENTLY, not late: even the state-based safety net could not see
+// the row. Builder IAMMASTERQUA hit exactly this — 19 sessions, 19 empty, ~$730
+// of recorded session cost, zero paid, for ten weeks, with the only diagnostic
+// (recordUploadSkip's trace) written to their own laptop.
+//
+// The server does not need the client's help here: a claim already records WHO
+// shipped WHAT and WHEN. So we recover the link from durable state — the
+// builder's session_records whose activity window overlaps the claim window.
+//
+// Design notes:
+//   • OVERLAP, not containment: a session that was already running when the
+//     claim opened (or outlived it) still did that work. started_at/ended_at
+//     fall back to uploaded_at when the transcript carried no span.
+//   • OVER-ATTACHMENT IS FINANCIALLY SAFE. The reward is idempotent per
+//     session_id (the watermark SELECT + uniq_credit_session_token_reward_basis),
+//     so linking one session to several tasks pays it ONCE, never per task. The
+//     bounded downside is a longer task_ids list, not double-pay.
+//   • Bounded by `limit` so a pathological long-running session can't fan out
+//     an unbounded UPDATE.
+//   • Does NOT touch the landing gate. It only answers "which session did this
+//     task come from"; whether the task LANDED is still checked by every caller
+//     (ADR 0120 — never pay for code that didn't land).
+// Returns { attached } (rows freshly linked).
+async function attachClaimSessionsToTaskTx(client, taskId, { limit = 50 } = {}) {
+  const id = Number(taskId);
+  if (!Number.isFinite(id)) return { attached: 0 };
+  const n = Number(limit);
+  const cap = Number.isFinite(n) ? Math.max(1, Math.min(500, Math.trunc(n))) : 50;
+  const { rows } = await client.query(
+    `WITH cand AS (
+       SELECT DISTINCT sr.id
+         FROM claims c
+         JOIN session_records sr ON sr.builder_id = c.builder_id
+        WHERE c.task_id = $1
+          AND NOT (sr.task_ids @> ARRAY[$1]::bigint[])
+          AND COALESCE(sr.started_at, sr.uploaded_at) <= COALESCE(c.released_at, now())
+          AND COALESCE(sr.ended_at,   sr.uploaded_at) >= c.claimed_at
+        ORDER BY sr.id
+        LIMIT $2
+     )
+     UPDATE session_records sr
+        SET task_ids = (
+              SELECT COALESCE(array_agg(DISTINCT e ORDER BY e), '{}')
+                FROM unnest(sr.task_ids || ARRAY[$1]::bigint[]) AS e
+            )
+       FROM cand
+      WHERE cand.id = sr.id
+      RETURNING sr.session_id`,
+    [id, cap]
+  );
+  return { attached: rows.length };
+}
+
 // 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
@@ -198,16 +259,24 @@ async function upsertSessionRecordWithReward(opts) {
 // ci/async path, where the digest was uploaded (and DEFERRED) before the code
 // landed. Opens its own transaction.
 //
+// It first runs attachClaimSessionsToTaskTx (task 1002964) so a session whose
+// client-side upload skipped is still found: before that, an unsent task_ids
+// made the reward unreachable by every path, permanently.
+//
 // 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).
+// observability, so it is never the idempotency key.
+// Returns { sessions, awarded, attached } (rows scanned, rewards freshly booked,
+// links freshly recovered).
 async function awardDeferredSessionRewardForTask(taskId) {
   const id = Number(taskId);
-  if (!Number.isFinite(id)) return { sessions: 0, awarded: 0 };
+  if (!Number.isFinite(id)) return { sessions: 0, awarded: 0, attached: 0 };
   return api.withTx(async (client) => {
+    // Recover any link the client-side upload failed to send BEFORE looking for
+    // payable sessions — otherwise a skipped upload is unpayable forever.
+    const { attached } = await attachClaimSessionsToTaskTx(client, id);
     const { rows } = await client.query(
       `SELECT session_id, builder_id, model_usage, total_tokens
          FROM session_records
@@ -224,7 +293,7 @@ async function awardDeferredSessionRewardForTask(taskId) {
       });
       if (tokenReward && tokenReward.awarded && tokenReward.drachmae > 0) awarded += 1;
     }
-    return { sessions: rows.length, awarded };
+    return { sessions: rows.length, awarded, attached };
   });
 }
 
@@ -287,6 +356,64 @@ async function reconcileUnbookedSessionRewards({ limit = 200 } = {}) {
   });
 }
 
+// reconcileUnattachedClaimSessions — the ATTRIBUTION half of the safety net
+// (task 1002964), and the reason reconcileUnbookedSessionRewards alone was not
+// enough. That sweep starts from session_records.task_ids, so a session the
+// client never linked is invisible to it — the very rows most in need of rescue
+// are the ones it cannot see. This sweep runs FIRST and comes at it from the
+// other side: start from LANDED tasks, walk their claims, and link the claiming
+// builder's overlapping sessions. Once linked, the existing sweep pays them.
+//
+// Ordering matters: the poller calls this, then reconcileUnbookedSessionRewards.
+// Same idempotency story as attachClaimSessionsToTaskTx — a session already
+// carrying the task is skipped by the NOT (task_ids @> …) guard, and the payout
+// stays exactly-once per session regardless of how many tasks it links to.
+// Strictly pay-on-land: only tasks at status='shipped' are considered.
+//
+// ⚠️ LOOKBACK WINDOW — this is a SAFETY NET, NOT A BACKFILL. The reward sweep
+// runs immediately after this one, so every task linked here becomes payable on
+// the same tick. Unbounded, the first run would retro-link the ENTIRE history
+// (measured on cloudbongos.com 2026-08-16: 1383 tasks / 1157 sessions for one
+// builder alone) and mint a mass retroactive payout nobody authorised. Deliberate
+// historical back-pay is an Archon decision made with eyes open via
+// scripts/gds/backfill-task-rewards.js (dry-run by default, reviewed amounts) —
+// never a side effect of a poller starting up. So we only consider tasks that
+// landed inside the window: recent enough that a live client-side upload skip is
+// what we are recovering from. Widen it deliberately, never casually.
+// Returns { scanned, attached }.
+const ATTACH_LOOKBACK_DAYS = Number(process.env.SESSION_ATTACH_LOOKBACK_DAYS) || 7;
+
+async function reconcileUnattachedClaimSessions({ limit = 200, lookbackDays } = {}) {
+  const n = Number(limit);
+  const cap = Number.isFinite(n) ? Math.max(1, Math.min(1000, Math.trunc(n))) : 200;
+  const d = Number(lookbackDays ?? ATTACH_LOOKBACK_DAYS);
+  const days = Number.isFinite(d) ? Math.max(1, Math.min(365, Math.trunc(d))) : 7;
+  return api.withTx(async (client) => {
+    // Candidate LANDED tasks whose claiming builder has at least one overlapping
+    // session that is not yet linked. Bounded, newest first — a backlog drains
+    // over successive sweeps rather than in one unbounded UPDATE.
+    const { rows } = await client.query(
+      `SELECT DISTINCT c.task_id
+         FROM claims c
+         JOIN tasks t ON t.id = c.task_id AND t.status = 'shipped'
+         JOIN session_records sr ON sr.builder_id = c.builder_id
+        WHERE NOT (sr.task_ids @> ARRAY[c.task_id]::bigint[])
+          AND COALESCE(t.shipped_at, t.updated_at) >= now() - ($2 || ' days')::interval
+          AND COALESCE(sr.started_at, sr.uploaded_at) <= COALESCE(c.released_at, now())
+          AND COALESCE(sr.ended_at,   sr.uploaded_at) >= c.claimed_at
+        ORDER BY c.task_id DESC
+        LIMIT $1`,
+      [cap, String(days)]
+    );
+    let attached = 0;
+    for (const r of rows) {
+      const res = await attachClaimSessionsToTaskTx(client, r.task_id);
+      attached += res.attached;
+    }
+    return { scanned: rows.length, attached };
+  });
+}
+
 // ---- 6D.2: session search + fetch (read side, ADR 0027) -------------------
 
 // Safe ORDER BY whitelist — the ONLY value interpolated into the search SQL, so
@@ -459,6 +586,8 @@ module.exports = {
   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
+  attachClaimSessionsToTaskTx, // task 1002964 — server-side task↔session link, recovered from the claim
+  reconcileUnattachedClaimSessions, // task 1002964 — attribution sweep; must run BEFORE the reward sweep
   // search + fetch (6D.2)
   searchSessions,
   summarizeSessions,

package/modules/sessions/pollers/session-reward-reconcile.js

@@ -29,13 +29,25 @@ let intervalTimer = null;
 let firstTimer = null;
 
 async function runSweep() {
+  // ATTRIBUTION FIRST (task 1002964). reconcileUnbookedSessionRewards starts from
+  // session_records.task_ids, so a session whose client-side upload skipped — and
+  // which therefore carries an EMPTY task_ids — is invisible to it. Those are
+  // precisely the stranded rows worth rescuing, so recover the task↔session link
+  // from the claim before looking for unbooked rewards. Both halves are
+  // idempotent, so a re-sweep neither re-links nor double-pays.
+  const attach = await db.reconcileUnattachedClaimSessions({ limit: 200 });
+  if (attach && attach.attached > 0) {
+    console.log(
+      `[session-reward-reconcile] linked ${attach.attached} session(s) to landed tasks from claim state (scanned ${attach.scanned})`
+    );
+  }
   const res = await db.reconcileUnbookedSessionRewards({ limit: 200 });
   if (res && res.awarded > 0) {
     console.log(
       `[session-reward-reconcile] booked ${res.awarded} stranded session reward(s) (scanned ${res.scanned})`
     );
   }
-  return res;
+  return { ...res, attached: attach ? attach.attached : 0 };
 }
 
 // Start the periodic sweep. Idempotent (a second call is a no-op). Kill-switched by

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.153",
+  "version": "1.19.155",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.153",
+      "version": "1.19.155",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.153",
+  "version": "1.19.155",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/gen-repo-map.js

@@ -24,6 +24,9 @@
 //   node scripts/gds/gen-repo-map.js --check       # write nothing; exit 2 if EITHER bucket would change
 //   node scripts/gds/gen-repo-map.js --check-block # exit 2 only if a TRACKED nested block would change (the CI gate)
 //   node scripts/gds/gen-repo-map.js --check-whole # exit 2 only if docs/repo-map.md would change
+//   node scripts/gds/gen-repo-map.js --whole-only  # WRITE docs/repo-map.md only; never touch the
+//                                                  # tracked nested blocks (what a SPARSE dev-box
+//                                                  # checkout must use — task 1002962)
 // docs/repo-map.md is GITIGNORED + regenerated at deploy/box-fetch since ADR 0110 (task 1926);
 // only the nested-doc symbol blocks stay tracked, so CI gates the block bucket, not the whole file.
 //   node scripts/gds/gen-repo-map.js --json       # print the extracted model as JSON (debug)
@@ -463,6 +466,21 @@ function main() {
   const checkAll = process.argv.includes('--check');
   const checkWhole = process.argv.includes('--check-whole');
   const checkBlock = process.argv.includes('--check-block');
+  // WRITE-side bucket selection, the sibling of the --check-* flags above (task
+  // 1002962). --whole-only regenerates the GITIGNORED docs/repo-map.md and leaves
+  // the TRACKED nested blocks alone.
+  //
+  // WHY a caller ever needs this: a dev box is a SPARSE checkout (box-access.js
+  // materializes only the claim's module cone). The block ordering is
+  // `b.refs - a.refs || name`, and `refs` counts references across the VISIBLE
+  // corpus — so a box with 7 of 20 modules computes different counts and emits a
+  // legitimately different block. Written into a tracked file that dirties the
+  // working tree, and box-source-fetch.sh's NEXT `git pull` aborts with "local
+  // changes would be overwritten" — a silent, permanent sync deadlock (one box sat
+  // 257 commits behind for three days). A box CONSUMES these blocks; they arrive
+  // correct with the pull, generated by CI from the whole tree. Only a full
+  // checkout may produce them.
+  const wholeOnly = process.argv.includes('--whole-only');
   const model = buildModel();
 
   if (process.argv.includes('--json')) {
@@ -478,8 +496,9 @@ function main() {
   const mapCur = fs.existsSync(mapPath) ? fs.readFileSync(mapPath, 'utf8') : '';
   if (!sameContent(mapCur, mapNext)) writes.push({ full: mapPath, content: mapNext, rel: 'docs/repo-map.md', bucket: 'whole' });
 
-  // 2) nested CLAUDE.md generated blocks (tracked; the HARD-gated bucket)
-  for (const dir of NESTED_DIRS) {
+  // 2) nested CLAUDE.md generated blocks (tracked; the HARD-gated bucket).
+  //     Skipped entirely under --whole-only — see the flag's rationale above.
+  for (const dir of (wholeOnly ? [] : NESTED_DIRS)) {
     const docPath = path.join(REPO_ROOT, dir, 'CLAUDE.md');
     if (!fs.existsSync(docPath)) {
       console.error(`gen-repo-map: WARN nested doc missing, skipping: ${dir}/CLAUDE.md`);

package/scripts/gds/gen-session-index.js

@@ -25,6 +25,8 @@
 //   node scripts/gds/gen-session-index.js --check       # write nothing; exit 2 if EITHER bucket would change
 //   node scripts/gds/gen-session-index.js --check-block # exit 2 only if the tracked CLAUDE.md §13 snippet drifts (CI gate)
 //   node scripts/gds/gen-session-index.js --check-whole # exit 2 only if docs/session-log-index.md drifts
+//   node scripts/gds/gen-session-index.js --whole-only  # WRITE the index only; never touch the tracked
+//                                                       # CLAUDE.md snippet (sparse dev-box use; task 1002962)
 // docs/session-log-index.md is GITIGNORED + regenerated at deploy/box-fetch since ADR 0110 (task 1926).
 //   node scripts/gds/gen-session-index.js --json       # print the parsed entries as JSON (debug)
 
@@ -180,7 +182,15 @@ function main() {
     process.stdout.write(JSON.stringify(collectEntries(), null, 2) + '\n');
     return;
   }
-  const { writes } = computeWrites();
+  // WRITE-side bucket selection — the sibling of the --check-* flags (task 1002962,
+  // the gen-repo-map --whole-only twin). A dev box is a SPARSE checkout, so writing
+  // the TRACKED bucket there dirties the tree and the next `git pull` in
+  // box-source-fetch.sh aborts on "local changes would be overwritten" — a silent,
+  // permanent sync deadlock. A box regenerates only the gitignored artifact; the
+  // tracked CLAUDE.md §13 snippet arrives with the pull, generated from the whole tree.
+  const wholeOnly = process.argv.includes('--whole-only');
+  const all = computeWrites().writes;
+  const writes = wholeOnly ? all.filter((w) => w.bucket === 'whole') : all;
   if (checkAll || checkWhole || checkBlock) {
     const wantBlock = checkAll || checkBlock;
     const wantWhole = checkAll || checkWhole;

package/src/module-api.js

@@ -733,8 +733,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.151 with no explicit bump. run 31955923444. (task 1002620)
 //   1.19.153 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.152 with no explicit bump. run 31956560292. (task 1002620)
+//   1.19.154 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.153 with no explicit bump. run 31957052737. (task 1002620)
+//   1.19.155 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.154 with no explicit bump. run 31957556550. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.153'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.155'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/repo_map.mjs

@@ -2,7 +2,7 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
@@ -94,3 +94,42 @@ test('extractor parses functions, classes, arrow consts, and module.exports', ()
   const apiCall = model.allSyms.find((s) => s.name === 'apiCall' && s.file === 'scripts/gds/cli-lib.js');
   assert.ok(apiCall && apiCall.exported && apiCall.kind === 'fn', 'exported arrow/fn const detected with export flag');
 });
+
+test('--whole-only never writes a TRACKED nested block (the sparse-box deadlock guard, task 1002962)', () => {
+  // A dev box is a SPARSE checkout — box-access.js materializes only the claim's
+  // module cone. The block ordering is `b.refs - a.refs || name` and `refs` counts
+  // references across the VISIBLE corpus, so a box with 7 of 20 modules emits a
+  // legitimately different block. box-source-fetch.sh used to write it, dirtying
+  // tracked files, and the NEXT `git pull` aborted on "local changes would be
+  // overwritten" — a silent permanent sync deadlock (one box sat 257 commits behind
+  // for three days). A box CONSUMES these blocks; only a full checkout may write them.
+  //
+  // Asserted on CONTENT, not on the log line: dirty a tracked block, run --whole-only,
+  // and require the block to come back byte-identical. A regression that re-enabled the
+  // bucket would rewrite it and fail here even if the summary line still looked right.
+  const tracked = path.join(ROOT, 'scripts', 'gds', 'CLAUDE.md');
+  const pristine = readFileSync(tracked, 'utf8');
+  const drifted = `${pristine}\n<!-- simulated sparse-checkout drift -->\n`;
+  writeFileSync(tracked, drifted);
+  try {
+    const r = run(['--whole-only']);
+    assert.equal(r.code, 0, `--whole-only should exit 0, got ${r.code} ${r.stderr || ''}`);
+    assert.equal(
+      readFileSync(tracked, 'utf8'),
+      drifted,
+      '--whole-only rewrote a tracked nested block — this is the deadlock that stranded a box 257 commits behind',
+    );
+    assert.ok(!r.stdout.includes('CLAUDE.md'), `--whole-only must not report a nested-doc write; got: ${r.stdout.trim()}`);
+  } finally {
+    writeFileSync(tracked, pristine);
+  }
+});
+
+test('the default (no-flag) run still owns BOTH buckets', () => {
+  // --whole-only must be strictly opt-in: CI and a full-checkout dev run keep
+  // regenerating the tracked blocks, which is what makes them trustworthy in git.
+  const src = readFileSync(GEN, 'utf8');
+  assert.match(src, /wholeOnly \? \[\] : NESTED_DIRS/, 'bucket skip should be gated on the flag, not unconditional');
+  // and on a clean tree the tracked bucket is genuinely current
+  assert.equal(run(['--check-block']).code, 0, 'tracked blocks must be current on a clean checkout');
+});

package/tests/session_attach_from_claim.mjs

@@ -0,0 +1,188 @@
+// tests/session_attach_from_claim.mjs
+//
+// Regression guard for task 1002964 — SERVER-SIDE task↔session attribution.
+//
+// THE BUG. Every payout path keys on session_records.task_ids, and until this
+// fix exactly ONE thing populated that column: ship.js's client-side upload.
+// When that upload skipped (classifyUploadSkip: no_session_id /
+// unsafe_session_id / transcript_not_found) the session was left with an EMPTY
+// task_ids — which matches NOTHING in the upload-side gate,
+// awardDeferredSessionRewardForTask, or reconcileUnbookedSessionRewards. The
+// reward stranded PERMANENTLY, invisible even to the state-based safety net.
+// Builder IAMMASTERQUA hit exactly this: 19 sessions, 19 empty, ~$730 of
+// recorded session cost, zero paid, for ten weeks.
+//
+// THE FIX. The server recovers the link from durable claim state — the claiming
+// builder's session_records whose activity window overlaps the claim window —
+// so a client-side skip can no longer zero a builder's pay. What this must NOT
+// do is loosen the landing gate: ADR 0120 still pays only for code that landed.
+//
+// Run:  node tests/session_attach_from_claim.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+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();
+
+// Same priceable fixture the sibling reward tests use: Opus 110k input →
+// $0.55 true cost → ×1.20 → 1 drachma. A non-zero payout is what lets the
+// idempotency watermark SELECT run at all.
+const MODEL_USAGE = { 'claude-opus-4-8': { input: 110_000 } };
+const WATERMARK_RE = /COALESCE\(SUM\(delta\)/;
+
+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)));
+
+const ATTACH_RE = /WITH cand AS .* UPDATE session_records/;
+const PAYABLE_RE = /SELECT session_id, builder_id, model_usage, total_tokens FROM session_records WHERE task_ids @>/;
+
+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;
+  }
+}
+
+// =========================================================================
+// (1) The attach runs, and runs BEFORE the payable-session lookup
+// =========================================================================
+
+await test('awardDeferredSessionRewardForTask: attaches from the claim BEFORE selecting payable sessions', async () => {
+  const seen = [];
+  const { result, queries } = await withFakeTx(
+    (s) => {
+      seen.push(s);
+      if (ATTACH_RE.test(s)) return { rows: [{ session_id: 'sess-hook-only' }] };
+      if (PAYABLE_RE.test(s)) {
+        return { rows: [{ session_id: 'sess-hook-only', builder_id: 7, model_usage: MODEL_USAGE, total_tokens: 5000 }] };
+      }
+      if (WATERMARK_RE.test(s)) return { rows: [{ paid: 0, legacy: 0 }] };
+      if (/^INSERT INTO credit_log/.test(s)) return { rows: [{ id: 1 }] };
+      return null;
+    },
+    () => db.awardDeferredSessionRewardForTask(660)
+  );
+
+  const attachIdx = seen.findIndex((s) => ATTACH_RE.test(s));
+  const payableIdx = seen.findIndex((s) => PAYABLE_RE.test(s));
+  assert.ok(attachIdx >= 0, 'the claim-based attach UPDATE must run');
+  assert.ok(payableIdx >= 0, 'the payable-session SELECT must run');
+  assert.ok(attachIdx < payableIdx,
+    'the attach MUST precede the payable lookup — otherwise a skipped upload is unpayable forever');
+  assert.equal(result.attached, 1, 'the freshly-linked session is reported');
+  assert.equal(result.awarded, 1, 'the hook-only session is paid once linked');
+});
+
+// =========================================================================
+// (2) The end-to-end shape the bug produced: hook-only record gets paid
+// =========================================================================
+
+await test('a hook-only record (empty task_ids, empty model_usage) is attributed and paid from total_tokens', async () => {
+  // The exact Masterqua row shape: no task, no per-model usage — only a token
+  // total. Pricing must fall back to totalTokens (task 1676) or this still pays 0.
+  const { result, queries } = await withFakeTx(
+    (s) => {
+      if (ATTACH_RE.test(s)) return { rows: [{ session_id: 'sess-masterqua' }] };
+      if (PAYABLE_RE.test(s)) {
+        return { rows: [{ session_id: 'sess-masterqua', builder_id: 1000025, model_usage: {}, total_tokens: 77_403_545 }] };
+      }
+      if (WATERMARK_RE.test(s)) return { rows: [{ paid: 0, legacy: 0 }] };
+      if (/^INSERT INTO credit_log/.test(s)) return { rows: [{ id: 1 }] };
+      return null;
+    },
+    () => db.awardDeferredSessionRewardForTask(660)
+  );
+
+  const insert = find(queries, /^INSERT INTO credit_log/);
+  assert.ok(insert, 'an empty model_usage must still book a reward via the totalTokens fallback');
+  assert.equal(result.awarded, 1, 'the session that was stranded for ten weeks now pays');
+});
+
+// =========================================================================
+// (3) Idempotency + the landing gate (the two things this must not break)
+// =========================================================================
+
+await test('attach SQL skips sessions already carrying the task (no re-link, no double-pay)', async () => {
+  const { queries } = await withFakeTx(
+    (s) => {
+      if (ATTACH_RE.test(s)) return { rows: [] }; // nothing new to link
+      if (PAYABLE_RE.test(s)) return { rows: [] };
+      return null;
+    },
+    () => db.awardDeferredSessionRewardForTask(660)
+  );
+  const attach = find(queries, ATTACH_RE);
+  assert.ok(/NOT \(sr\.task_ids @> ARRAY/.test(norm(attach)),
+    'the attach must exclude sessions already linked to this task');
+  assert.equal(all(queries, /^INSERT INTO credit_log/).length, 0, 'nothing linked → nothing paid');
+});
+
+await test('attach is bounded by a LIMIT so one long session cannot fan out an unbounded UPDATE', async () => {
+  const { queries } = await withFakeTx(
+    (s) => (ATTACH_RE.test(s) || PAYABLE_RE.test(s) ? { rows: [] } : null),
+    () => db.awardDeferredSessionRewardForTask(660)
+  );
+  const attach = find(queries, ATTACH_RE);
+  assert.ok(/LIMIT \$2/.test(norm(attach)), 'the candidate set must be bounded');
+  assert.equal(attach.params[1], 50, 'default cap');
+});
+
+await test('reconcileUnattachedClaimSessions considers ONLY landed tasks (ADR 0120 unchanged)', async () => {
+  const { queries } = await withFakeTx(
+    (s) => (/FROM claims c JOIN tasks t/.test(s) ? { rows: [] } : null),
+    () => db.reconcileUnattachedClaimSessions({ limit: 5 })
+  );
+  const scan = find(queries, /FROM claims c JOIN tasks t/);
+  assert.ok(scan, 'the attribution sweep must scan claims joined to tasks');
+  assert.ok(/t\.status = 'shipped'/.test(norm(scan)),
+    "the sweep must require status='shipped' — never attribute-and-pay unlanded work");
+  assert.equal(scan.params[0], 5, 'the caller-supplied limit is honoured');
+});
+
+// The guard that keeps a safety net from becoming an unauthorised mass payout.
+// Without the window, the first sweep on cloudbongos.com would have retro-linked
+// 1383 tasks / 1157 sessions for a single builder and paid them on the same tick.
+await test('the sweep is WINDOWED — it can never become a retroactive mass backfill', async () => {
+  const { queries } = await withFakeTx(
+    (s) => (/FROM claims c JOIN tasks t/.test(s) ? { rows: [] } : null),
+    () => db.reconcileUnattachedClaimSessions({ limit: 5 })
+  );
+  const scan = find(queries, /FROM claims c JOIN tasks t/);
+  assert.ok(/shipped_at, t\.updated_at\) >= now\(\) - /.test(norm(scan)),
+    'the sweep MUST bound itself to recently-landed tasks — historical back-pay is a deliberate Archon decision, not a poller side effect');
+  assert.equal(scan.params[1], '7', 'conservative default lookback');
+});
+
+await test('lookbackDays is clamped to a sane range (no 0-day no-op, no 10-year backfill)', async () => {
+  for (const [given, expected] of [[0, '1'], [-5, '1'], [99999, '365'], ['junk', '7']]) {
+    const { queries } = await withFakeTx(
+      (s) => (/FROM claims c JOIN tasks t/.test(s) ? { rows: [] } : null),
+      () => db.reconcileUnattachedClaimSessions({ limit: 5, lookbackDays: given })
+    );
+    assert.equal(find(queries, /FROM claims c JOIN tasks t/).params[1], expected,
+      `lookbackDays ${given} must clamp to ${expected}`);
+  }
+});
+
+await test('a non-finite task id is a clean no-op (no SQL, no reward)', async () => {
+  const { result, queries } = await withFakeTx(() => null, () => db.awardDeferredSessionRewardForTask('nope'));
+  assert.equal(queries.length, 0, 'a garbage id must not reach the DB');
+  assert.deepEqual(result, { sessions: 0, awarded: 0, attached: 0 });
+});
+
+summary();

package/tests/session_reward_on_land.mjs

@@ -224,8 +224,10 @@ await test('awardDeferredSessionRewardForTask: no session shipped this task →
 
 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.
+  // `attached` joined the shape in task 1002964 (the claim-based attribution
+  // recovery that now runs ahead of the payable-session lookup).
   const out = await db.awardDeferredSessionRewardForTask('not-a-number');
-  assert.deepEqual(out, { sessions: 0, awarded: 0 });
+  assert.deepEqual(out, { sessions: 0, awarded: 0, attached: 0 });
 });
 
 // =========================================================================