@bongos/core 1.18.0 → 1.18.18

package/modules/dev-box/box-access.js

@@ -96,6 +96,11 @@ const STARTER_SPARSE_PATHS = [
   // stamped, and the "Connect to thy dev box" onboarding step never ticks. No
   // secrets live in infra/ (ADR 0022).
   'infra',
+  // tests/ — so a starter box can RUN the suite for the code it holds (BV1.R99,
+  // goal 1000052; same rationale as BASE_SPARSE_PATHS). Onboarding is "bare
+  // machine → first ship", and a newcomer proving their first change needs the
+  // top-level tests/ (tests/*.mjs + helpers.mjs), which sits beside src, not in it.
+  'tests',
 ];
 
 // States in which a box is (or is becoming) a running droplet that can actually
@@ -117,21 +122,99 @@ function cloneSpecForScope(scope) {
   return { scope: 'starter', mode: 'sparse', sparsePaths: [...STARTER_SPARSE_PATHS] };
 }
 
+// ---------------------------------------------------------------------------
+// PURE: the TASK-scoped surface (ADR 0148 / goal 1000051) — layered on BASE
+// ---------------------------------------------------------------------------
+
+// BASE_SPARSE_PATHS — the "pre-existing Bongos instance" every box carries no
+// matter what the builder claimed: enough for Claude to hold methodology context
+// and run the /builder-* CLI, but NONE of the product/game surface. It is the
+// NON-PRODUCT subset of STARTER_SPARSE_PATHS — .devcontainer, .claude, scripts,
+// src/bongos, docs, infra. (Top-level files like CLAUDE.md/server.js + the src/*.js
+// root files come AUTOMATICALLY via cone-mode ancestor inclusion, because src/bongos
+// is listed — see the STARTER note above.) A task's own module code (including the
+// product/game when a game task is claimed) layers on top via sparsePathsForScopeKeys.
+// This is the ADR 0148 move: scope the box to the code the claimed task needs, not
+// the whole repo.
+//
+// BEHAVIOR vs ADR 0052 (sandbox-for-everyone): BASE deliberately drops the game
+// (src/world, src/rooms, public) + art + modules/status-ui — a task-scoped box only
+// carries the live sandbox when the claimed work is scoped to the `game` module. The
+// pre-ADR-0148 "every box runs the sandbox" survives on the RANK fallback path
+// (decideSourceAccess with NO scopeKeys), so a vanilla instance without the lifecycle
+// port is unchanged.
+const BASE_SPARSE_PATHS = [
+  '.devcontainer', '.claude', 'scripts', 'src/bongos', 'docs', 'infra',
+  // tests/ — so a pulled module's build/test commands actually RUN on the box
+  // (BV1.R99, goal 1000052). Module tests live in the TOP-LEVEL tests/ dir
+  // (tests/box_*.mjs + the tests/helpers.mjs harness), NOT inside modules/<key>/,
+  // so a box holding the module source but not tests/ cannot verify a change.
+  // A cone-mode directory; it carries no product runtime, only test code.
+  'tests',
+];
+
+// sparsePathsForScopeKeys — PURE. Given the module KEYS a builder's active claims
+// put in scope (from the lifecycle port `moduleScopeForActiveClaims`, R92) and the
+// doorway `moduleScopeMap` (PASSED IN by the route — box-access imports no core
+// internal), compute the git cone-mode sparse-checkout set: BASE ∪ the DIRECTORY
+// globs of every scoped module.
+//
+// Cone-mode constraint (load-bearing, ADR 0148): `git sparse-checkout set` accepts
+// ONLY directories — a file path aborts the whole set. A module's scope_modules →
+// globs come in two shapes: directory globs (trailing '/', e.g. 'modules/dev-box/')
+// and file-list globs (exact paths, e.g. the kernel key's 'src/bongos/db.js'). We
+// KEEP the directory globs (normalized to no trailing slash, matching the BASE
+// style) and DROP the file globs — every file glob in the map sits under a BASE
+// directory (src/bongos, scripts) or is a top-level/ancestor file cone mode pulls
+// automatically, so base already materializes it. (A future non-cone sparse move
+// could pull individual files; out of scope — cone mode stays.) Deterministic:
+// BASE in declared order, then the module dirs sorted + deduped.
+function sparsePathsForScopeKeys(scopeKeys, moduleScopeMap) {
+  const base = [...BASE_SPARSE_PATHS];
+  const seen = new Set(base);
+  const extra = [];
+  for (const key of Array.isArray(scopeKeys) ? scopeKeys : []) {
+    const entry = moduleScopeMap && typeof moduleScopeMap.scopeForModule === 'function'
+      ? moduleScopeMap.scopeForModule(key)
+      : null;
+    if (!entry || !Array.isArray(entry.globs)) continue;
+    for (const glob of entry.globs) {
+      if (typeof glob !== 'string' || !glob.endsWith('/')) continue; // dirs only (cone mode)
+      const dir = glob.replace(/\/+$/, '');
+      if (!seen.has(dir)) { seen.add(dir); extra.push(dir); }
+    }
+  }
+  extra.sort();
+  return [...base, ...extra];
+}
+
 // ---------------------------------------------------------------------------
 // PURE: the per-fetch access decision (consumed by GET /box/source-access)
 // ---------------------------------------------------------------------------
 
 // Decide what source access a builder gets RIGHT NOW. The route reads the live
 // rank+status from the DB and passes them in; this stays pure + unit-tested so the
-// route and any future caller enforce the SAME rule. The scope is derived from the
-// LIVE rank (not the box's stored scope), so a just-graduated builder gets 'full'
-// on their very next fetch — before the slower box reconcile flips the stored column.
+// route and any future caller enforce the SAME rule.
+//
+// Rank still governs ALLOW/DENY + the provision floor (an inactive/below-floor
+// builder is still 403, unchanged). What rank NO LONGER decides — once a claim
+// drives it — is the module BREADTH (ADR 0148 / goal 1000051). The optional
+// `scopeKeys` (from the lifecycle port `moduleScopeForActiveClaims`, R92, resolved
+// + passed by the route in R94) selects the surface, three ways:
+//   - scopeKeys is a NON-EMPTY array → TASK scope: BASE ∪ the claims' module dirs
+//     (via sparsePathsForScopeKeys + the passed-in `moduleScopeMap`).
+//   - scopeKeys is an EMPTY array     → BASE-only (a live box with no active claim /
+//     no scoped goal — the pre-existing Bongos instance, nothing extra).
+//   - scopeKeys is ABSENT (undefined) → the pre-ADR-0148 RANK fallback (full for
+//     Metic+, else the starter sparse surface). This is the path a vanilla instance
+//     with no lifecycle port takes, and it preserves the old behavior EXACTLY — so
+//     shipping R93 before R94 wires the route changes nothing in production.
 //
 // Returns one of:
 //   { allowed:false, reason:'BUILDER_INACTIVE' }
 //   { allowed:false, reason:'INSUFFICIENT_RANK', required, actual }
 //   { allowed:true,  scope, spec }
-function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR } = {}) {
+function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, scopeKeys, moduleScopeMap } = {}) {
   if (status && status !== 'active') {
     return { allowed: false, reason: 'BUILDER_INACTIVE' };
   }
@@ -143,10 +226,41 @@ function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR } =
       actual: rank ?? null,
     };
   }
+  // Claim-driven task scope (present → the box asks for exactly its work's code).
+  if (Array.isArray(scopeKeys)) {
+    const sparsePaths = sparsePathsForScopeKeys(scopeKeys, moduleScopeMap);
+    const scope = scopeKeys.length > 0 ? 'task' : 'base';
+    return { allowed: true, scope, spec: { scope, mode: 'sparse', sparsePaths } };
+  }
+  // No claim signal (no lifecycle port on this instance): the pre-ADR-0148 rank fallback.
   const scope = boxScopeForRank(rank);
   return { allowed: true, scope, spec: cloneSpecForScope(scope) };
 }
 
+// scopeMetadata — PURE. The credential-FREE projection of a source-access
+// decision, for the read-only GET /box/scope companion (BV1.R100 / goal 1000051):
+// the laptop app (and R104's proof) needs to KNOW what a box holds — which module
+// dirs, which sparse set — WITHOUT being issued the pull credential. It is computed
+// from the SAME decideSourceAccess result the real fetch uses, so the answer can
+// never drift from the actual checkout.
+//
+// `modules` reports the resolved module KEYS a task-scope pulls (the raw scopeKeys
+// from moduleScopeForActiveClaims, deduped + sorted for a stable display) — or null
+// when the decision came from the RANK fallback (scopeKeys absent), where breadth is
+// rank-driven, not module-driven, so there is no per-module list to name.
+function scopeMetadata({ decision, scopeKeys } = {}) {
+  if (!decision || !decision.allowed) return null;
+  const modules = Array.isArray(scopeKeys)
+    ? [...new Set(scopeKeys.filter((k) => typeof k === 'string'))].sort()
+    : null;
+  return {
+    scope: decision.scope,
+    mode: decision.spec ? decision.spec.mode : null,
+    modules,
+    sparse_paths: decision.spec ? decision.spec.sparsePaths : null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // PURE: the clawback / reconcile decision (consumed by `box.js reconcile`)
 // ---------------------------------------------------------------------------
@@ -262,9 +376,12 @@ async function flagBoxReconcileForBuilder(db, builderId, { rank, status, floor =
 module.exports = {
   // pure — surface catalog
   STARTER_SPARSE_PATHS,
+  BASE_SPARSE_PATHS, // ADR 0148 / goal 1000051 — the non-product base a task-scoped box layers on
   SOURCE_HOLDING_STATES,
   boxCanHoldSource,
   cloneSpecForScope,
+  sparsePathsForScopeKeys, // ADR 0148 — BASE ∪ the claims' module dirs (cone-mode)
+  scopeMetadata, // BV1.R100 — credential-free projection for GET /box/scope
   // pure — decisions
   decideSourceAccess,
   reconcileSourceAccess,

package/modules/dev-box/boxes.js

@@ -783,6 +783,24 @@ function computeCodeStaleness({ state, provisionedAt, codeReportedAt, codeCommit
   return { stale: false, reason: 'current' };
 }
 
+// PURE: are the box's REPORTED SSH host keys older than the droplet now running?
+// A rebuild mints fresh host keys, and until the new box re-reports (~10 min) the
+// row can still carry its predecessor's identity — pinning that is the "Host denied
+// (verification failed)" lockout. A report that predates `active_since` therefore
+// describes a droplet that no longer exists; so does a missing timestamp on either
+// side. Callers must fall back to a live keyscan rather than pin a dead identity.
+function hostKeysAreStale({ hostKeysAt, activeSince } = {}) {
+  const toMs = (x) => {
+    if (x == null) return null;
+    const t = x instanceof Date ? x.getTime() : new Date(x).getTime();
+    return Number.isFinite(t) ? t : null;
+  };
+  const reported = toMs(hostKeysAt);
+  const activated = toMs(activeSince);
+  if (reported == null || activated == null) return true;
+  return reported < activated;
+}
+
 module.exports = {
   // pure — rank
   RANK_ORDER,
@@ -812,6 +830,8 @@ module.exports = {
   computeCodeStaleness,
   CODE_REPORT_GRACE_MS,
   CODE_STALE_LAG_MS,
+  // pure — host-key staleness (task 1002509)
+  hostKeysAreStale,
   // pure — droplet⇄row drift (task 1289)
   DROPLET_HOLDING_STATES,
   loginFromDroplet,

package/modules/dev-box/module.json

@@ -2,7 +2,7 @@
   "key": "dev-box",
   "title": "Dev boxes",
   "description": "Per-builder cloud dev environments (DigitalOcean + Cloudflare tunnels), sandbox preview, server-mediated branch publish.",
-  "coreVersion": "^1.2.0",
+  "coreVersion": "^1.12.0",
   "default": false,
   "contributes": {
     "routes": ["box"],

package/modules/dev-box/routes/box.js

@@ -152,6 +152,10 @@ function publicBox(row) {
     hostname: row.hostname,
     last_activity_at: row.last_activity_at,
     provisioned_at: row.provisioned_at,
+    // When the CURRENT droplet came up. provisioned_at is preserved across rebuilds,
+    // so this is the only timestamp a client can compare host_keys_at against to
+    // tell a fresh identity report from a dead box's (boxes.hostKeysAreStale).
+    active_since: row.active_since || null,
     parked_at: row.parked_at,
     compute_cost_usd: Number(row.compute_cost_usd || 0),
     claude_active: row.claude_active ?? false,
@@ -429,7 +433,26 @@ module.exports = function buildBoxRouter() {
       const builder = await gdsDb.getBuilderById(req.builder.id);
       const rank = builder ? builder.rank : null;
       const status = builder ? builder.status : 'inactive';
-      const decision = boxAccess.decideSourceAccess({ rank, status });
+
+      // R94 (ADR 0148 §4 / goal 1000051): scope the box to the CODE THE BUILDER'S
+      // CLAIMED TASK NEEDS. Resolve the lifecycle port (OPTIONAL — resolveOptional
+      // returns null on a vanilla instance without it) and read the set-union of the
+      // builder's active claims' module scope. scopeKeys drives the sparse BREADTH:
+      //   - array present → TASK scope (BASE ∪ the claims' module dirs; empty → BASE-only)
+      //   - undefined     → decideSourceAccess falls back to the RANK scope (the
+      //                     pre-ADR-0148 behavior, so a port-less instance is unchanged).
+      // NEVER fail the source fetch on a scope-read hiccup — degrade to rank scope.
+      const lifecycle = api.resolveOptional('lifecycle');
+      let scopeKeys;
+      if (lifecycle && typeof lifecycle.moduleScopeForActiveClaims === 'function') {
+        try {
+          scopeKeys = await lifecycle.moduleScopeForActiveClaims(req.builder.id);
+        } catch (scopeErr) {
+          console.error('[gds] source-access scope read (non-fatal, → rank scope)', scopeErr && scopeErr.message ? scopeErr.message : scopeErr);
+          scopeKeys = undefined;
+        }
+      }
+      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, moduleScopeMap: api.moduleScopeMap });
       const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
       const auditDeny = (reason, extra) =>
         box && boxAccess.recordSourceEvent(pool, {
@@ -452,7 +475,16 @@ module.exports = function buildBoxRouter() {
       }
 
       // Mint the scope-appropriate credential (operator-supplied; may be unconfigured).
-      const cred = boxCredential.defaultProvider.issue(decision.scope, { nowMs: Date.now() });
+      // ADR 0148 C4 leaves the TOKEN MODEL untouched: the credential (which repo +
+      // which token) stays RANK-based, exactly as before task-scoping. decision.scope
+      // may now be 'task'/'base' (the sparse BREADTH the box ASKS for), but the
+      // credential must still be the rank one — issue() only special-cases 'full', so
+      // passing 'task'/'base' would hand even a Metic+ the STARTER repo/token, which on
+      // a separate-starter-repo instance can't reach the task's module. Task-scope is
+      // the CLIENT-SIDE sparse ask; a hard per-claim credential ceiling is the deferred
+      // hardening (ADR 0148 Consequences).
+      const credScope = boxes.boxScopeForRank(rank); // 'starter' | 'full' — unchanged posture
+      const cred = boxCredential.defaultProvider.issue(credScope, { nowMs: Date.now() });
 
       // Audit the grant — scope + configured flag only, NEVER the token. Only a
       // REAL (configured) grant is logged: an unconfigured fetch issued no
@@ -465,7 +497,7 @@ module.exports = function buildBoxRouter() {
       if (box && cred.configured) {
         await boxAccess.recordSourceEvent(pool, {
           box, builderId: req.builder.id, event: 'source_grant',
-          detail: `scope=${decision.scope} mode=${decision.spec.mode}`,
+          detail: `scope=${decision.scope} cred=${credScope} mode=${decision.spec.mode}`,
           actor: 'api',
         }).catch(() => {});
       }
@@ -490,6 +522,58 @@ module.exports = function buildBoxRouter() {
     }
   });
 
+  // GET /box/scope — the credential-FREE companion to /box/source-access
+  // (BV1.R100 / goal 1000051). Answers "what code does my box hold RIGHT NOW?" —
+  // the resolved sparse set + the module keys of the builder's active claims —
+  // WITHOUT issuing the pull credential. The laptop app reads it to confirm
+  // "your box now has <module> for task N" after a pick+claim; R104's proof reads
+  // it to VERIFY the scope is minimal (excludes other modules). Same live rank+
+  // status + lifecycle-port scope logic as source-access, so the answer can't
+  // drift from the actual checkout — it just omits the secret.
+  //
+  // Deliberately NOT gated on a live box (boxCanHoldSource): the SCOPE is metadata,
+  // so a builder can ask "what WOULD my box hold for my current claims" the instant
+  // they claim, before the box has even synced. The ALLOW/DENY still comes from the
+  // live rank+status (a demoted/inactive builder gets the same 403 as source-access).
+  // allowBoxScope so it works both from the laptop app (full session) and on the box
+  // (box-scoped session) — safe here precisely because no credential is returned.
+  router.get('/box/scope', auth.allowBoxScope, auth.requireBuilder, async (req, res) => {
+    try {
+      // ONE consistent rank+status snapshot (the /box/source-access TOCTOU note).
+      const builder = await gdsDb.getBuilderById(req.builder.id);
+      const rank = builder ? builder.rank : null;
+      const status = builder ? builder.status : 'inactive';
+
+      // Resolve the claim-driven module scope exactly as source-access does
+      // (optional lifecycle port; degrade to rank scope on any hiccup).
+      const lifecycle = api.resolveOptional('lifecycle');
+      let scopeKeys;
+      if (lifecycle && typeof lifecycle.moduleScopeForActiveClaims === 'function') {
+        try {
+          scopeKeys = await lifecycle.moduleScopeForActiveClaims(req.builder.id);
+        } catch (scopeErr) {
+          console.error('[gds] /box/scope scope read (non-fatal, → rank scope)', scopeErr && scopeErr.message ? scopeErr.message : scopeErr);
+          scopeKeys = undefined;
+        }
+      }
+      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, moduleScopeMap: api.moduleScopeMap });
+      if (!decision.allowed) {
+        return res.fail('SOURCE_ACCESS_REVOKED', 403, {
+          reason: decision.reason,
+          required: decision.required ?? null,
+          actual: decision.actual ?? null,
+        });
+      }
+      const meta = boxAccess.scopeMetadata({ decision, scopeKeys });
+      // task_scope true only when a claim actually drove the breadth (scopeKeys is
+      // an array). false → the rank fallback (no active claim / no lifecycle port).
+      return res.json({ ...meta, task_scope: Array.isArray(scopeKeys) });
+    } catch (err) {
+      console.error('[gds] GET /box/scope', err);
+      res.fail('box_scope_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // POST /box/heartbeat — the box reports it is alive, resetting the idle clock.
   // rank: any authenticated builder (own resource write). Optional body:
   // { claude_active: bool } — when provided, records whether a `claude` process

package/modules/economy/credits.js

@@ -135,14 +135,45 @@ const IDEA_BONUS_FRACTION = 0.25; // 25% slice to the idea's original capturer
 // is `branding.currency.label`.
 const REWARD_MARGIN_PCT = 20; // cost-plus margin, percent — DEFAULT (task 1005)
 
+// Reward MODE — which reward streams an instance pays (task 1002270, ADR 0146).
+// The two streams (ADR 0054 "two drachma conventions, one ledger") are:
+//   (1) the per-task author ESTIMATE — credits_reward × kind multiplier (ADR 0023),
+//       a unitless bounty set when the task is authored; and
+//   (2) the COST-PLUS session reward — round(true_cost_usd × 1.20), 1 drachma = $1
+//       (ADR 0054), grounded in the session's real API spend.
+// mode picks which of the two an instance actually PAYS:
+//   'cost-plus-and-estimate' (DEFAULT) — pay both, the historical behavior. Every
+//       existing instance keeps paying exactly as before on upgrade.
+//   'cost-plus-only' — the cost-plus session reward is the SOLE equity reward; the
+//       per-task estimate PAYOUT is withheld (and its idea-promotion slice, being a
+//       fraction of it, cascades to 0). credits_reward still rides the task row for
+//       display + the no-zero-reward claim gate (ADR 0096) — only the payout is
+//       suppressed, so a credit means one dollar of cost-plus value and nothing
+//       else. Cloud Bongos's choice (owner decision, 2026-07-16).
+// Unknown/garbage mode → treated as the default (pay both): a config typo must
+// never silently zero out every builder's per-task reward.
+const REWARD_MODE_DEFAULT = 'cost-plus-and-estimate';
+const REWARD_MODE_COST_PLUS_ONLY = 'cost-plus-only';
+
+// Pure policy resolver — maps a raw branding.reward object to the effective reward
+// policy. Exported so a test can assert the mapping without touching the memoized
+// branding() cache (mirrors computeSessionTokenReward's pure/impure split). The
+// derived `perTaskCredit` boolean is what the per-task credit writer gates on.
+function rewardPolicy(rawReward) {
+  const r = rawReward || {};
+  const marginPct = Number.isFinite(Number(r.marginPct)) ? Number(r.marginPct) : REWARD_MARGIN_PCT;
+  const usdPeg = Number.isFinite(Number(r.usdPeg)) && Number(r.usdPeg) > 0 ? Number(r.usdPeg) : 1;
+  const mode = r.mode === REWARD_MODE_COST_PLUS_ONLY ? REWARD_MODE_COST_PLUS_ONLY : REWARD_MODE_DEFAULT;
+  const perTaskCredit = mode !== REWARD_MODE_COST_PLUS_ONLY;
+  return { marginPct, usdPeg, mode, perTaskCredit };
+}
+
 // Per-instance reward policy, resolved over the code defaults. Best-effort: a
 // branding hiccup falls back to the defaults so reward accrual never crashes.
 function rewardConfig() {
   let r = {};
   try { r = (branding().reward) || {}; } catch { r = {}; }
-  const marginPct = Number.isFinite(Number(r.marginPct)) ? Number(r.marginPct) : REWARD_MARGIN_PCT;
-  const usdPeg = Number.isFinite(Number(r.usdPeg)) && Number(r.usdPeg) > 0 ? Number(r.usdPeg) : 1;
-  return { marginPct, usdPeg };
+  return rewardPolicy(r);
 }
 
 // Pure helper — exported for tests. Returns { trueCostUsd, marginPct, drachmae,
@@ -182,18 +213,38 @@ function applyKindMultiplier(rawCredits, kind) {
 }
 
 // Write the primary task-ship credit_log row, applying the kind multiplier.
-// Caller must already have verified that no prior 'task.confirmed' row exists
-// for this task. Returns { creditsAwarded, multiplier, raw } where
+// Caller must already have verified that no prior row with the SAME `reason`
+// exists for this task. Returns { creditsAwarded, multiplier, raw } where
 // creditsAwarded is the multiplier-adjusted integer that landed.
-async function insertMultipliedConfirmCredit(client, builderId, taskId, rawCredits, kind) {
+//
+// `reason` is a parameter (default 'task.confirmed' for back-compat) so the
+// pay-on-land move (ADR 0120) can book the per-task credit at the SHIPPED
+// transition with reason='task.shipped' — the credit only exists once the code
+// is on `main`. The idempotency guard the caller runs must key on the SAME
+// reason it passes here.
+//
+// `config` (default: the resolved per-instance rewardConfig()) carries the reward
+// MODE (ADR 0146). Injectable so a test can drive the cost-plus-only gate without
+// touching the memoized branding() cache; the sole live caller (lifecycle
+// awardLandingCredit) omits it and gets the resolved instance policy per call.
+async function insertMultipliedConfirmCredit(client, builderId, taskId, rawCredits, kind, reason = 'task.confirmed', config = rewardConfig()) {
   const result = applyKindMultiplier(rawCredits, kind);
+  // Reward-mode gate (ADR 0146): in 'cost-plus-only' mode this instance pays no
+  // per-task estimate credit — the cost-plus session reward is the sole equity
+  // reward. Return the same zero-shape the effective<=0 path returns (so the
+  // caller's idea-promotion slice, a fraction of creditsAwarded, cascades to 0)
+  // but write NO credit_log row. The task's credits_reward still exists for
+  // display + the claim gate; only the payout is withheld.
+  if (config && config.perTaskCredit === false) {
+    return { creditsAwarded: 0, multiplier: result.multiplier, raw: result.raw, skipped: REWARD_MODE_COST_PLUS_ONLY };
+  }
   if (result.effective <= 0) {
     return { creditsAwarded: 0, multiplier: result.multiplier, raw: result.raw };
   }
   await client.query(
     `INSERT INTO credit_log (builder_id, task_id, delta, reason, description)
-     VALUES ($1, $2, $3, 'task.confirmed', $4)`,
-    [builderId, taskId, result.effective, result.description]
+     VALUES ($1, $2, $3, $4, $5)`,
+    [builderId, taskId, result.effective, reason, result.description]
   );
   return {
     creditsAwarded: result.effective,
@@ -277,9 +328,17 @@ async function maybeAwardIdeaPromotionBonus(client, taskId, shipperBuilderId, mu
 //                  empty/unpriceable model_usage → $0 reward; ADR 0097) still pays
 //                  the real cost-plus amount. This is NOT a fabricated dollar value
 //                  — it prices REAL token counts via the same locked PRICES table.
-// Returns { drachmae, trueCostUsd, awarded, unknownModels, pricedFromTotalTokens }.
-// awarded=false means a prior reward row for this session already existed
-// (re-upload / re-ship) — a true no-op, no second credit, no double payout.
+// Returns { drachmae, trueCostUsd, awarded, unknownModels, pricedFromTotalTokens,
+// settled? }. `drachmae` is the amount BOOKED BY THIS CALL, which for a session that
+// has already been paid something is the INCREMENT, not the session's whole value.
+//
+// The reward tops up (task 1002474). A session's cost keeps growing after its first
+// ship, and multi-ship sessions are normal — one claim at a time, but ship -> new
+// worktree -> claim again. So each landed ship books the difference between what the
+// whole session is now worth and what it has already been paid. awarded=false means
+// nothing was owed this time; `settled` says why — 'up_to_date' (already paid in
+// full, the ordinary idempotent case) or 'legacy' (a row predating reward_basis,
+// deliberately left for a signed-off backfill rather than paid out on deploy).
 async function awardSessionTokenReward(client, builderId, sessionId, modelUsage, totalTokens = 0) {
   const { true_cost_usd: pricedCostUsd, unknown_models: unknownModels } =
     priceModelUsage(modelUsage);
@@ -306,29 +365,58 @@ async function awardSessionTokenReward(client, builderId, sessionId, modelUsage,
     return { drachmae: 0, trueCostUsd, awarded: false, unknownModels, pricedFromTotalTokens };
   }
 
-  // Fast-path idempotency guard (the partial-unique index is the hard backstop
-  // against a race). Keyed on the literal reason + session_id.
-  const { rows: existing } = await client.query(
-    `SELECT 1 FROM credit_log
-      WHERE reason = 'session.token_reward' AND session_id = $1 LIMIT 1`,
+  // Watermark accounting. `drachmae` is what the WHOLE session is worth right now;
+  // book only the part not yet paid. Before this, any existing row made the whole
+  // call a no-op, so a session that shipped a second task was paid only for the cost
+  // it had at its FIRST ship — measured at ~65% of a three-ship session unrewarded.
+  //
+  // `legacy` counts rows booked before reward_basis existed (they default to 0).
+  // Topping those up would be an uncontrolled retroactive payout across every
+  // historical session, so we deliberately leave them settled; reconstructing what
+  // they are owed is a separate, owner-signed-off backfill.
+  const { rows: prior } = await client.query(
+    `SELECT COALESCE(SUM(delta), 0)::int AS paid,
+            COUNT(*) FILTER (WHERE reward_basis = 0)::int AS legacy
+       FROM credit_log
+      WHERE reason = 'session.token_reward' AND session_id = $1`,
     [sessionId]
   );
-  if (existing.length > 0) {
-    return { drachmae: 0, trueCostUsd, awarded: false, unknownModels, pricedFromTotalTokens };
+  const paid = Number(prior[0] && prior[0].paid) || 0;
+  const legacy = Number(prior[0] && prior[0].legacy) || 0;
+  if (legacy > 0) {
+    return {
+      drachmae: 0, trueCostUsd, awarded: false, unknownModels, pricedFromTotalTokens,
+      settled: 'legacy',
+    };
+  }
+
+  // Owed − paid. Zero when nothing changed (the idempotent case) and negative when a
+  // smaller/stale digest arrives late — never claw back, never write a negative row.
+  const owed = drachmae - paid;
+  if (owed <= 0) {
+    return {
+      drachmae: 0, trueCostUsd, awarded: false, unknownModels, pricedFromTotalTokens,
+      settled: 'up_to_date',
+    };
   }
 
+  const rowDescription = paid > 0
+    ? `${description} — top-up: +${owed} on ${paid} already paid`
+    : description;
+
   // Append-only ledger row. task_id = NULL (session-level, not task-level).
-  // ON CONFLICT DO NOTHING on the partial-unique index closes the race window:
-  // if a parallel upload inserted between our SELECT and here, we no-op cleanly.
+  // ON CONFLICT DO NOTHING still closes the race window, now keyed on
+  // (session_id, reward_basis): a parallel upload at the SAME cumulative basis
+  // collides and no-ops, while a genuinely larger basis books its own increment.
   const { rows } = await client.query(
-    `INSERT INTO credit_log (builder_id, task_id, delta, reason, description, session_id)
-     VALUES ($1, NULL, $2, 'session.token_reward', $3, $4)
-     ON CONFLICT (session_id) WHERE reason = 'session.token_reward' DO NOTHING
+    `INSERT INTO credit_log (builder_id, task_id, delta, reason, description, session_id, reward_basis)
+     VALUES ($1, NULL, $2, 'session.token_reward', $3, $4, $5)
+     ON CONFLICT (session_id, reward_basis) WHERE reason = 'session.token_reward' DO NOTHING
      RETURNING id`,
-    [builderId, drachmae, description, sessionId]
+    [builderId, owed, rowDescription, sessionId, drachmae]
   );
   const awarded = rows.length > 0;
-  return { drachmae: awarded ? drachmae : 0, trueCostUsd, awarded, unknownModels, pricedFromTotalTokens };
+  return { drachmae: awarded ? owed : 0, trueCostUsd, awarded, unknownModels, pricedFromTotalTokens };
 }
 
 // net-negative ship bonus — V3.R93 (#354). Simplification reward.
@@ -425,6 +513,9 @@ module.exports = {
   KIND_MULTIPLIERS,
   IDEA_BONUS_FRACTION,
   REWARD_MARGIN_PCT,
+  REWARD_MODE_DEFAULT,
+  REWARD_MODE_COST_PLUS_ONLY,
+  rewardPolicy,
   rewardConfig,
   computeSessionTokenReward,
   applyKindMultiplier,

package/modules/economy/reward.js

@@ -37,6 +37,14 @@ module.exports = {
   // pure helpers + constants (display / tests)
   applyKindMultiplier: (...a) => credits.applyKindMultiplier(...a),
   computeSessionTokenReward: (...a) => credits.computeSessionTokenReward(...a),
+  // The resolved per-instance reward POLICY (ADR 0146). Exposed on the port so
+  // display surfaces can ASK which streams this instance pays instead of
+  // re-deriving `mode !== 'cost-plus-only'` for themselves — the knob lives
+  // inside economy, and that is the whole point of the ADR. `rewardConfig()`
+  // resolves branding; `rewardPolicy(raw)` is the pure mapping for callers that
+  // already hold the raw object.
+  rewardConfig: (...a) => credits.rewardConfig(...a),
+  rewardPolicy: (...a) => credits.rewardPolicy(...a),
   get KIND_MULTIPLIERS() { return credits.KIND_MULTIPLIERS; },
   get IDEA_BONUS_FRACTION() { return credits.IDEA_BONUS_FRACTION; },
   get REWARD_MARGIN_PCT() { return credits.REWARD_MARGIN_PCT; },

package/modules/economy/streak.js

@@ -7,7 +7,8 @@
 //     shipped >=1 qualifying task.
 //   - A "qualifying ship" requires:
 //       * claim.outcome = 'shipped'           (builder declared done)
-//       * task.status IN ('confirmed','shipped')  (verification passed; credits landed)
+//       * task.status IN ('confirmed','shipped')  (verification passed; credits land
+//                                                  at 'shipped' — ADR 0120 pays on land)
 //       * task.est_minutes >= 15              (anti-gaming floor)
 //     NOTE: cleanup/refactor tasks DO now count (V3.R93 #354). The original
 //     PMS-V2 rule excluded kind='cleanup', which mildly penalized the exact

package/modules/governance/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._