@bongos/core 1.24.3 → 1.24.5

package/modules/copy-desk/auto-close.js

@@ -8,7 +8,11 @@
 // hand. Two shapes hold nothing:
 //
 //   blank             `ready`, no draft and no frozen batch: opened in the
-//                     studio, nothing written, the claim dropped.
+//                     studio, nothing written, the claim dropped. Closes once
+//                     untouched for page-status's BLANK_CLOSES_AFTER (1 day, the
+//                     owner's answer on task 1004971; task 1004972). Until then
+//                     it reads `blank` ("Opened, nothing written yet"), never
+//                     `unknown`.
 //   nothing_to_apply  `ready` with a frozen batch whose `lines` is empty: every
 //                     rewrite left the batch for an engineer task at submit
 //                     (unplaced, shared or removed lines), so /tweak has no line
@@ -32,18 +36,47 @@ const pageStatus = require('./page-status');
 const GRACE_MS = Number(process.env.COPY_AUTO_CLOSE_GRACE_MS) || 60 * 60_000;
 
 const NOTES = Object.freeze({
-  blank: 'Closed by itself: the round was opened but nothing was written in it.',
+  blank: 'Closed: nothing was written. The round was opened and left blank for a day; claim the page again to start one.',
   nothing_to_apply: 'Closed by itself: every rewritten line went to an engineer task, so nothing was left to apply on the page.',
   draft_expired: 'Closed by itself: the draft sat untouched for two weeks. Its words stay on this task; claim the page again to start over.',
+  orphaned_apply: 'Released: the apply stopped without finishing. Nobody holds this round any more, so it is back in the queue.',
 });
 
-function closeReason(task, { now = Date.now(), graceMs = GRACE_MS, draftExpiresMs = pageStatus.DRAFT_EXPIRES_AFTER } = {}) {
+// task 1004972 T2 (task 1004973): an ORPHANED round is `active` with no open
+// claim. The applier's claim was released (the runner's reconcile, a crashed
+// worker, a dropped session) but the status never moved, so it read `unknown`
+// and nothing ever picked it up again. A round someone still holds, a live and
+// heartbeating apply, is never touched: holder_id is the open claim, and the
+// lifecycle port re-checks that no claim was taken under its row lock.
+function orphanReason(task, { now = Date.now(), graceMs = GRACE_MS } = {}) {
+  if (!task || task.status !== 'active' || task.holder_id != null) return null;
+  const touched = Date.parse(task.updated_at || task.created_at || '');
+  if (!Number.isFinite(touched) || now - touched < graceMs) return null;
+  return 'orphaned_apply';
+}
+
+// The orphan goes back to `ready` with its description kept whole plus the
+// reason, as a sent-back block (pages.appendSentBack, the one writer of that
+// block, which only APPENDS). A frozen batch then reads `submitted` again and the
+// next applier reads why; a draft stays a draft. No word of the draft or the
+// batch is changed.
+function releaseKeeping(note, at, by) {
+  return (task) => pages.appendSentBack(task.description, { at, by, note });
+}
+
+function closeReason(task, {
+  now = Date.now(), graceMs = GRACE_MS,
+  draftExpiresMs = pageStatus.DRAFT_EXPIRES_AFTER, blankClosesMs = pageStatus.BLANK_CLOSES_AFTER,
+} = {}) {
   if (!task || task.status !== 'ready' || task.holder_id != null) return null;
   const touched = Date.parse(task.updated_at || task.created_at || '');
   if (!Number.isFinite(touched) || now - touched < graceMs) return null;
   const p = pages.blockPresence(task.description);
-  // task 1004901: a draft its artist left untouched for two weeks expires.
-  if (!p.batch) return p.draft ? (now - touched >= draftExpiresMs ? 'draft_expired' : null) : 'blank';
+  const age = now - touched;
+  // task 1004901: a draft its artist left untouched expires. task 1004972: a
+  // blank round closes after a day. A batch with lines is never touched here,
+  // and a draft only by its own expiry.
+  if (!p.batch) return p.draft ? (age >= draftExpiresMs ? 'draft_expired' : null) : (age >= blankClosesMs ? 'blank' : null);
   const b = pages.parseBatchBlock(task.description);
   if (b.ok && b.batch.lines.length === 0) return 'nothing_to_apply';
   return null;
@@ -58,16 +91,21 @@ async function runAutoClose({ now = Date.now(), resolve = (k) => (api.resolveOpt
     return { closed: [], skipped: 'no_lifecycle' };
   }
   const tasks = await lifecycle.listPageTweakTasks();
-  const due = tasks.map((t) => ({ t, why: closeReason(t, { now }) })).filter((x) => x.why);
+  const due = tasks.map((t) => ({ t, why: closeReason(t, { now }) || orphanReason(t, { now }) })).filter((x) => x.why);
   if (!due.length) return { closed: [] };
   const owner = await founder();
   if (!owner) return { closed: [], skipped: 'no_owner' };
   const closed = [];
+  const at = new Date(now).toISOString();
   for (const { t, why } of due) {
-    const r = await lifecycle.releaseStuckTweak({ taskId: t.id, builderId: owner.id, expectedStatus: 'ready', note: NOTES[why] });
+    const orphan = why === 'orphaned_apply';
+    const r = await lifecycle.releaseStuckTweak({
+      taskId: t.id, builderId: owner.id, expectedStatus: orphan ? 'active' : 'ready', note: NOTES[why],
+      ...(orphan ? { compose: releaseKeeping(NOTES[why], at, String(owner.id)) } : {}),
+    });
     closed.push({ task_id: String(t.id), why, outcome: r.outcome });
   }
   return { closed };
 }
 
-module.exports = { closeReason, runAutoClose };
+module.exports = { closeReason, orphanReason, runAutoClose };

package/modules/copy-desk/page-status.js

@@ -193,7 +193,11 @@ function roundState(round) {
         if (p.last_sent_back_at && (!p.applied_at || p.applied_at <= p.last_sent_back_at)) return 'submitted';
         return 'unknown';
       }
-      return p.draft ? 'draft' : 'unknown';
+      // task 1004972: opened and nothing written is a state of its own, not one
+      // the reads cannot name. It waits on its artist and closes itself after
+      // BLANK_CLOSES_AFTER (the auto-close sweep), so it never reads "Needs to be
+      // reviewed" or asks an applier to release it.
+      return p.draft ? 'draft' : 'blank';
     case 'completed':
       // A held pass waits for the artist; a failed grade stays with the applier.
       return round.grade_passed === true ? 'waiting_for_artist' : 'applying';
@@ -319,7 +323,10 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 // Home and in the daily digest). A draft nobody touches also EXPIRES
 // (expires_after): the auto-close sweep abandons it, its words kept on the task.
 const DRAFT_EXPIRES_AFTER = 14 * DAY_MS;
+// task 1004972 (owner, task 1004971): a round opened and left blank closes after a day.
+const BLANK_CLOSES_AFTER = DAY_MS;
 const IN_FLIGHT = Object.freeze({
+  blank: { word: 'Opened, nothing written yet', stuck_after: BLANK_CLOSES_AFTER, waits_on: 'artist', expires_after: BLANK_CLOSES_AFTER },
   draft: { word: 'Being written', stuck_after: 7 * DAY_MS, waits_on: 'artist', expires_after: DRAFT_EXPIRES_AFTER },
   writing: { word: 'Being written', stuck_after: 7 * DAY_MS, waits_on: 'artist' },
   words_review: { word: 'Words waiting for review', stuck_after: 3 * DAY_MS, waits_on: 'artist' },
@@ -330,7 +337,7 @@ const IN_FLIGHT = Object.freeze({
   landing: { word: 'Approved, going live', stuck_after: DAY_MS, waits_on: 'appliers' },
   unknown: { word: 'Needs to be reviewed', stuck_after: 0, waits_on: 'appliers' },
 });
-const IN_FLIGHT_ORDER = ['unknown', 'landing', 'applying', 'submitted', 'waiting_for_artist', 'words_review', 'writing', 'draft'];
+const IN_FLIGHT_ORDER = ['unknown', 'landing', 'applying', 'submitted', 'waiting_for_artist', 'words_review', 'writing', 'draft', 'blank'];
 
 function inFlightFor(list, byPage, nowMs) {
   const out = [];
@@ -980,4 +987,6 @@ module.exports = {
   stuckDigestText,
   // task 1004901: when an untouched draft expires (the auto-close sweep reads it).
   DRAFT_EXPIRES_AFTER,
+  // task 1004972: when a blank round closes (the auto-close sweep reads it).
+  BLANK_CLOSES_AFTER,
 };

package/modules/copy-desk/tests/copy_no_cms.mjs

@@ -312,8 +312,15 @@ await test('the module manifest declares no seam another module could write copy
   assert.equal(/writeFile|\.query\(|UPDATE |INSERT /.test(stuckSrc), false, 'the stuck-tweaks port writes nothing');
   // task 1004899: the auto-close sweep only ABANDONS an empty round through the
   // lifecycle port; it never hands a compose, so it cannot write a description.
+  // task 1004973: it may hand ONE compose, for an orphaned apply released back to
+  // the queue, and that compose is pages.appendSentBack: it appends the reason and
+  // changes no word (copy_page_auto_close.mjs proves the description is kept whole).
   const closeSrc = stripComments(read('auto-close.js'));
-  assert.equal(/writeFile|\.query\(|UPDATE |INSERT |compose/.test(closeSrc), false, 'the auto-close sweep abandons and writes nothing');
+  assert.equal(/writeFile|\.query\(|UPDATE |INSERT /.test(closeSrc), false, 'the auto-close sweep writes nothing itself');
+  const composes = closeSrc.match(/\bcompose\b[^\n]*/g) || [];
+  assert.deepEqual(composes.length, 1, 'one compose, for the orphan release');
+  assert.match(closeSrc, /\(task\) => pages\.appendSentBack\(task\.description, \{ at, by, note \}\)/, 'and it only appends the sent-back note');
+  assert.equal(/composeDraftBlock|composeBatchBlock|saveDraftInto|replaceBlock/.test(closeSrc), false, 'no draft or batch writer');
   const stats = read('artist-stats.js');
   assert.equal(/\b(pool|query|writeFile|appendFile|INSERT|UPDATE|DELETE)\b/.test(stats.replace(/\/\/.*$/gm, '')), false,
     'the artist-stats port reads through other ports and writes nothing');

package/modules/copy-desk/tests/copy_page_auto_close.mjs

@@ -65,9 +65,35 @@ await test('a draft left untouched for two weeks expires; a younger one stays (t
 });
 
 await test('the grace period is honoured: a round touched within it stays', () => {
-  const t = round({ updated_at: new Date(NOW - 59 * 60_000).toISOString() });
+  const t = round({ description: `${draft}\n\n${batch([])}`, updated_at: new Date(NOW - 59 * 60_000).toISOString() });
   assert.equal(autoClose.closeReason(t, { now: NOW, graceMs: 60 * 60_000 }), null);
-  assert.equal(autoClose.closeReason(t, { now: NOW, graceMs: 30 * 60_000 }), 'blank');
+  assert.equal(autoClose.closeReason(t, { now: NOW, graceMs: 30 * 60_000 }), 'nothing_to_apply');
+});
+
+// task 1004972 (owner, task 1004971): a blank round closes after one day, not an hour.
+await test('a blank round closes once a day old, and a round with a draft or a batch never closes as blank', () => {
+  const D = 86400000;
+  const at = (days, over = {}) => round({ updated_at: new Date(NOW - days * D).toISOString(), ...over });
+  assert.equal(autoClose.closeReason(at(0.9), { now: NOW }), null, 'under a day: it stays, reading "Opened, nothing written yet"');
+  assert.equal(autoClose.closeReason(at(1.1), { now: NOW }), 'blank');
+  assert.equal(autoClose.closeReason(at(1.1, { holder_id: '7' }), { now: NOW }), null, 'a held round is being written');
+  for (const [name, description] of [['draft', draft], ['batch with lines', `${draft}\n\n${batch([line])}`],
+    ['approved batch', `${batch([line])}\n\n${pages.composeWordsApprovedBlock({ at: OLD, by: '7' })}`]]) {
+    assert.notEqual(autoClose.closeReason(at(1.1, { description }), { now: NOW }), 'blank', `${name} is not blank`);
+  }
+  assert.equal(autoClose.closeReason(at(30, { description: `${draft}\n\n${batch([line])}` }), { now: NOW }), null, 'a batch with lines is never closed, however old');
+});
+
+await test('the blank note says nothing was written, and the sweep never writes words', async () => {
+  const calls = [];
+  const lifecycle = {
+    listPageTweakTasks: async () => [ROUNDS.blank],
+    releaseStuckTweak: async (args) => { calls.push(args); return { outcome: 'abandoned' }; },
+  };
+  await autoClose.runAutoClose({ now: NOW, resolve: () => lifecycle, founder: async () => ({ id: '1' }) });
+  assert.equal(calls.length, 1);
+  assert.match(calls[0].note, /^Closed: nothing was written\./);
+  assert.deepEqual(Object.keys(calls[0]).sort(), ['builderId', 'expectedStatus', 'note', 'taskId'], 'no compose, no description, no wording');
 });
 
 await test('the sweep abandons through the lifecycle port, as the owner, with a plain note and no rewrite', async () => {
@@ -86,6 +112,42 @@ await test('the sweep abandons through the lifecycle port, as the owner, with a
   }
 });
 
+// task 1004973: an apply that stopped without finishing is released with a reason.
+await test('an orphaned apply (active, nobody holds it) is released back to the queue with the reason; a live apply is not', async () => {
+  const approved = `${draft}\n\n${batch([line])}\n\n${pages.composeWordsApprovedBlock({ at: OLD, by: '7' })}`;
+  const orphan = round({ id: '21', status: 'active', holder_id: null, description: approved });
+  const orphanDraft = round({ id: '22', status: 'active', holder_id: null, description: draft });
+  const live = round({ id: '23', status: 'active', holder_id: '7', holder_worktree: true, description: approved });
+  const fresh = round({ id: '24', status: 'active', holder_id: null, description: approved, updated_at: new Date(NOW - 5 * 60_000).toISOString() });
+  assert.deepEqual([orphan, orphanDraft, live, fresh].map((t) => autoClose.orphanReason(t, { now: NOW })), ['orphaned_apply', 'orphaned_apply', null, null]);
+  assert.equal(autoClose.closeReason(orphan, { now: NOW }), null, 'the ready-round rules never see an active round');
+
+  const calls = [];
+  const lifecycle = {
+    listPageTweakTasks: async () => [orphan, orphanDraft, live, fresh, ROUNDS.real_batch],
+    releaseStuckTweak: async (args) => { calls.push(args); return { outcome: 'released' }; },
+  };
+  const r = await autoClose.runAutoClose({ now: NOW, resolve: () => lifecycle, founder: async () => ({ id: '1' }) });
+  assert.deepEqual(r.closed.map((c) => [c.task_id, c.why, c.outcome]), [['21', 'orphaned_apply', 'released'], ['22', 'orphaned_apply', 'released']],
+    'after one sweep no round sits active with nobody holding it; the live apply and the fresh one are left alone');
+  for (const c of calls) {
+    assert.equal(c.expectedStatus, 'active');
+    assert.match(c.note, /^Released: the apply stopped without finishing\./);
+    assert.equal(typeof c.compose, 'function', 'released back to the queue, not abandoned');
+  }
+  // The reason is on the round, and the words are kept whole: the compose only appends.
+  const [batchOut, draftOut] = calls.map((c, i) => c.compose([orphan, orphanDraft][i]));
+  assert.equal(batchOut.ok, true);
+  assert.ok(batchOut.description.startsWith(approved), 'the draft, batch and approval are unchanged');
+  assert.ok(draftOut.description.startsWith(draft), 'a draft stays as it was');
+  const p = pages.blockPresence(batchOut.description);
+  assert.equal(p.batch && p.words_approved && !!p.last_sent_back_at, true, 'the batch carries the sent-back reason');
+  const pageStatus = require('../page-status.js');
+  assert.equal(pageStatus.roundState({ status: 'ready', holder_id: null, description: batchOut.description }), 'submitted', 'back in the /tweak queue');
+  assert.equal(pageStatus.roundState({ status: 'ready', holder_id: null, description: draftOut.description }), 'draft', 'a draft is its artist\'s again');
+  assert.match(draftOut.description, /the apply stopped without finishing/);
+});
+
 await test('nothing due, no owner read; no owner, no sweep; no lifecycle, no sweep', async () => {
   let asked = 0;
   const quiet = { listPageTweakTasks: async () => [ROUNDS.real_batch], releaseStuckTweak: async () => { throw new Error('must not run'); } };

package/modules/copy-desk/tests/copy_page_status.mjs

@@ -199,6 +199,8 @@ await test('every row of the D7 state table', () => {
 ${pages.composeWordsApprovedBlock({ at: 't2', by: '7' })}` }, 'submitted'],
     [{ status: 'ready', description: sentBackAfterApply }, 'submitted'],
     [{ status: 'ready', description: applied }, 'unknown'],
+    // task 1004972: opened and nothing written is its own state, never "Needs to be reviewed".
+    [{ status: 'ready', description: 'Page tweak round 1.' }, 'blank'],
     [{ status: 'completed', grade_passed: true }, 'waiting_for_artist'],
     [{ status: 'completed', grade_passed: false }, 'applying'],
     [{ status: 'confirmed' }, 'landing'],
@@ -258,7 +260,9 @@ ${pages.composeWordsApprovedBlock({ at: ago(9), by: '7' })}`;
     round(3, 'landing:c', { status: 'confirmed', updated_at: ago(17) }),
     round(4, 'builders:d', { status: 'completed', grade_passed: true, updated_at: ago(20) }),
     round(5, 'builders:e', { status: 'active', holder_id: '7', holder_login: 'me', holder_worktree: false, updated_at: ago(5) }),
-    round(6, 'builders:f', { status: 'ready', updated_at: ago(0.2) }),
+    // An active round nobody holds is one the reads cannot name. (A blank ready
+    // round is no longer that: it reads 'blank', task 1004972.)
+    round(6, 'builders:f', { status: 'active', holder_id: null, updated_at: ago(0.2) }),
     round(7, 'builders:g', { status: 'shipped', shipped_at: ago(3), updated_at: ago(3) }),
     round(8, 'status:h', { status: 'active', holder_id: '8', holder_worktree: true, updated_at: ago(2) }),
   ];

package/modules/discord/ship-broadcast.js

@@ -96,6 +96,13 @@ async function postShipBroadcast(task, deps = {}) {
 
   const postWebhook = deps.postWebhook || require('./webhook').postWebhook;
   const log = deps.log || console.log;
+  // task 1004969 (ADR 0385 decision 9): an AI-written summary that calls credits
+  // or models an investment is FLAGGED in the log and posted unchanged — recorded,
+  // never blocked or rewritten. No economy module, no check.
+  const reward = deps.reward !== undefined ? deps.reward : require('../../src/module-api').resolveOptional('reward');
+  if (reward && typeof reward.flagInvestmentWording === 'function') {
+    result.wording_flags = reward.flagInvestmentWording(summary, { where: 'ship summary', ref: `task ${task.id}`, log }).length;
+  }
   const pageTweak = task.source === PAGE_TWEAK_SOURCE;
   const pageArtist = pageTweak && sec === false ? await pageArtistName(task, deps) : null;
   const targets = chooseBroadcastTargets({ securitySensitive: sec, taskId: task.id, summary, kind: task.kind, pageTweak, pageArtist });

package/modules/economy/credit-wording.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// modules/economy/credit-wording.js — finds investment wording next to credits
+// or models (task 1004969; ADR 0385 decision 9).
+//
+// WHY. Credits are a contribution meter, not money and not a stake (ADR 0385,
+// ADR 0387), and a module or a model is not something a builder invests in.
+// Wording that says otherwise keeps coming back — in code comments, onboarding
+// docs and AI-written ship summaries — and every time it does the project reads
+// as if it were selling a security. This is the one check for it.
+//
+// THE RULE. A sentence is flagged when an investment word (investment, return,
+// appreciation, passive income, equity, ownership) sits within NEAR_WORDS words
+// of a credit word or a model word. A sentence that DENIES it ("credits are not
+// an investment", "never equity") is the wording we want, so a negation shortly
+// before the investment word clears it.
+//
+// It only FINDS. Callers decide what to do: the wording test fails on a hit, and
+// the server publish paths log a flag and publish the text unchanged — never a
+// silent rewrite, never a block. PURE: no I/O, so it is safe on any path.
+
+const NEAR_WORDS = 12;
+const NEGATION_WORDS = 4;
+
+const ANCHOR_RE = /^(credits?|drachmae|models?)$/i;
+const NEGATION_RE = /^(not|never|no|nor|isn't|aren't|without|neither)$/i;
+
+// One entry per investment idea; `words` is the phrase as lower-case tokens.
+// "return" is the noun only: "returns" alone, or "return on"/"a return" — the
+// verb ("the task returns to ready") is everywhere and says nothing about money.
+const TERMS = [
+  { term: 'investment', match: (w) => /^invest(ment|ments|ing|or|ors|ed|s)?$/.test(w[0]) && 1 },
+  { term: 'return', match: (w, prev) => {
+    if (w[0] === 'return' && w[1] === 'on') return 2;
+    if (/^returns?$/.test(w[0]) && /^(a|any|financial|guaranteed|expected|your|their|high|higher)$/.test(prev || '')) return 1;
+    return 0;
+  } },
+  { term: 'appreciation', match: (w) => (w[0] === 'appreciation' ? 1 : (/^appreciat(e|es|ing)$/.test(w[0]) && w[1] === 'in' && w[2] === 'value' ? 3 : 0)) },
+  { term: 'passive income', match: (w) => (w[0] === 'passive' && w[1] === 'income' ? 2 : 0) },
+  { term: 'equity', match: (w) => (w[0] === 'equity' ? 1 : 0) },
+  { term: 'ownership', match: (w) => (w[0] === 'ownership' ? 1 : 0) },
+];
+
+function sentences(text) {
+  return String(text == null ? '' : text).split(/(?<=[.!?;])\s+|\n\s*\n|\n(?=\s*[-*|#>])/);
+}
+
+function tokens(sentence) {
+  return (sentence.toLowerCase().match(/[a-z][a-z']*/g) || []).map((t) => t.replace(/'s$/, ''));
+}
+
+// Every offending sentence in `text`: [{ term, phrase, anchor, sentence }]. Pure.
+function findInvestmentWording(text) {
+  const out = [];
+  for (const raw of sentences(text)) {
+    const sentence = raw.replace(/\s+/g, ' ').trim();
+    if (!sentence) continue;
+    const w = tokens(sentence);
+    const anchors = [];
+    w.forEach((t, i) => { if (ANCHOR_RE.test(t)) anchors.push(i); });
+    if (!anchors.length) continue;
+    for (let i = 0; i < w.length; i++) {
+      for (const T of TERMS) {
+        const len = T.match(w.slice(i, i + 3), w[i - 1]);
+        if (!len) continue;
+        const near = anchors.find((a) => Math.abs(a - i) <= NEAR_WORDS);
+        if (near === undefined) continue;
+        const negated = w.slice(Math.max(0, i - NEGATION_WORDS), i).some((t) => NEGATION_RE.test(t));
+        if (negated) continue;
+        out.push({ term: T.term, phrase: w.slice(i, i + len).join(' '), anchor: w[near], sentence });
+      }
+    }
+  }
+  return out;
+}
+
+// The server publish paths' half: find, write one log line per hit, return the
+// hits. The text is published unchanged whatever this finds, and it never
+// throws — a wording check must not be the reason a summary or an idea is lost.
+function flagInvestmentWording(text, { where = 'text', ref = null, log = console.warn } = {}) {
+  try {
+    const hits = findInvestmentWording(text);
+    for (const h of hits) {
+      log(`[credit-wording] flagged ${where}${ref == null ? '' : ` ${ref}`}: "${h.phrase}" near "${h.anchor}" in "${h.sentence.slice(0, 200)}" `
+        + '(ADR 0385 decision 9; published unchanged)');
+    }
+    return hits;
+  } catch (_) {
+    return [];
+  }
+}
+
+module.exports = { findInvestmentWording, flagInvestmentWording, NEAR_WORDS, NEGATION_WORDS };

package/modules/economy/credits.js

@@ -9,7 +9,7 @@
 // (db.applyGrade/confirmTask/upsertSessionRecordWithReward) resolves these
 // through the `reward` kernel PORT rather than importing this module.
 
-const { pool, branding, resolveOptional } = require('../../src/module-api');
+const { pool, branding, resolveOptional, logger } = require('../../src/module-api');
 const { priceModelUsage, PRICES } = require('../../src/module-api').llmPricing; // cost-plus session reward (task 1005)
 const achievements = require('./achievements');
 
@@ -143,12 +143,13 @@ const IDEA_GOVERNANCE_PASS_FLOOR = 30;  // owner: floor ~30 — see the note on
 // Both accrue to builders.total_credits (the contribution meter); ADR 0054 (+ its
 // 2026-06-15 amendment) records the scale and why the cents form existed.
 //
-// REWARD_MARGIN_PCT (and the 1:1 cost-to-drachma scale, `usdPeg`) are the code-default reward
+// REWARD_MARGIN_PCT (and the 1:1 sizing factor, `costScale` — formerly `usdPeg`,
+// task 1004968) are the code-default reward
 // POLICY. They stay a code-reviewed default — not a live UI knob — for the same
 // reasons KIND_MULTIPLIERS does: a policy decision deserves a commit trail and
 // the grader reads it deterministically. But the reward policy is also
 // PER-INSTANCE config (task 2009 / BONGOS-V1): an instance overrides the margin
-// + the drachmae:USD peg in `config/branding.json` `reward.{marginPct,usdPeg}`
+// + the sizing factor in `config/branding.json` `reward.{marginPct,costScale}`
 // (still a committed, code-reviewed change — just in the instance's config, not
 // the vendored core module). `rewardConfig()` resolves the instance value over
 // these defaults; the pure helper keeps its code defaults so tests stay
@@ -161,8 +162,13 @@ const IDEA_GOVERNANCE_PASS_FLOOR = 30;  // owner: floor ~30 — see the note on
 // (ADR 0146) and every existing caller is unchanged.
 const {
   REWARD_MARGIN_PCT, REWARD_MODE_DEFAULT, REWARD_MODE_COST_PLUS_ONLY, IDEA_DESCENT_DECAY, rewardPolicy,
+  rewardPolicyDeprecation,
 } = require('./reward-policy');
 
+// The usdPeg deprecation note prints ONCE per process, not once per award: this
+// resolver runs on every ship, and a line per ship would bury the logs.
+let usdPegNoteShown = false;
+
 // Per-instance reward policy, resolved over the code defaults. Stays HERE, not in
 // reward-policy.js: the branding read must go through the module port (ADR 0083),
 // and a file the CLI can share may not import the port. Best-effort — a branding
@@ -170,6 +176,11 @@ const {
 function rewardConfig() {
   let r = {};
   try { r = (branding().reward) || {}; } catch { r = {}; }
+  const note = rewardPolicyDeprecation(r);
+  if (note && !usdPegNoteShown) {
+    usdPegNoteShown = true;
+    logger('economy').warn(note);
+  }
   return rewardPolicy(r);
 }
 
@@ -205,22 +216,25 @@ function rewardConfig() {
 // absent/any-non-false → the default TRUE (a pre-ADR-0172 config keeps paying).
 
 // Pure helper — exported for tests. Returns { trueCostUsd, marginPct, drachmae,
-// description }. drachmae = round(cost × (1+margin) × usdPeg); at the 1:1 scale
+// description }. drachmae = round(cost × (1+margin) × costScale); at the 1:1 scale
 // one drachma is earned per dollar of cost-plus (task 1138) — sized by USD, not
 // worth USD (ADR 0387), e.g.
 //   "$15.00 true cost × 1.20 = 18 drachmae (token reward)"
-// NOTE a sub-$0.42 session (at the 1:1 peg) rounds to 0 drachmae — intended:
+// NOTE a sub-$0.42 session (at the 1:1 scale) rounds to 0 drachmae — intended:
 // sub-dollar sessions earn nothing. Kept pure (code-default params); the call
 // site resolves per-instance policy via rewardConfig() and passes it in.
-function computeSessionTokenReward(trueCostUsd, marginPct = REWARD_MARGIN_PCT, usdPeg = 1) {
+// A non-1 factor is written into the description as "× N scale" (it said
+// "× N peg" before task 1004968; only NEW rows carry the new word — no existing
+// credit_log row is rewritten). At the default 1 the description is unchanged.
+function computeSessionTokenReward(trueCostUsd, marginPct = REWARD_MARGIN_PCT, costScale = 1) {
   const cost = Number(trueCostUsd) || 0;
   const pct = Number(marginPct) || 0;
-  const peg = Number.isFinite(Number(usdPeg)) && Number(usdPeg) > 0 ? Number(usdPeg) : 1;
+  const scale = Number.isFinite(Number(costScale)) && Number(costScale) > 0 ? Number(costScale) : 1;
   const mult = 1 + pct / 100;
-  const drachmae = Math.round(cost * mult * peg);
-  const pegNote = peg !== 1 ? ` × ${peg} peg` : '';
+  const drachmae = Math.round(cost * mult * scale);
+  const scaleNote = scale !== 1 ? ` × ${scale} scale` : '';
   const description =
-    `$${cost.toFixed(2)} true cost × ${mult.toFixed(2)}${pegNote} = ${drachmae} drachmae (token reward)`;
+    `$${cost.toFixed(2)} true cost × ${mult.toFixed(2)}${scaleNote} = ${drachmae} drachmae (token reward)`;
   return { trueCostUsd: cost, marginPct: pct, drachmae, description };
 }
 
@@ -1026,8 +1040,8 @@ async function awardSessionTokenReward(
   const extraRaw = Number(extraCostUsd);
   const extra = Number.isFinite(extraRaw) ? Math.max(0, extraRaw) : 0;
   const trueCostUsd = Math.round((pricedCostUsd + extra) * 10000) / 10000;
-  const { marginPct, usdPeg } = rewardConfig();
-  const { drachmae, description } = computeSessionTokenReward(trueCostUsd, marginPct, usdPeg);
+  const { marginPct, costScale } = rewardConfig();
+  const { drachmae, description } = computeSessionTokenReward(trueCostUsd, marginPct, costScale);
 
   // Nothing priced (no real tokens) — record nothing, report cleanly.
   if (!(drachmae > 0)) {

package/modules/economy/reward-policy.js

@@ -2,7 +2,7 @@
 // (task 1003676).
 //
 // What it is: the reward defaults and the PURE function that resolves a branding
-// pack's `reward` block over them — margin, USD peg, mode, whether the per-task
+// pack's `reward` block over them — margin, cost scale, mode, whether the per-task
 // credit and the ideator lane are on.
 //
 // Why it is its own file, and why it imports NOTHING: this is the one piece of
@@ -50,13 +50,56 @@ const REWARD_MODE_COST_PLUS_ONLY = 'cost-plus-only';
 // code path to disable separately.
 const IDEA_DESCENT_DECAY = 0.5;
 
+// THE SIZING FACTOR IS `costScale` (task 1004968). It multiplies a session's
+// cost-plus figure into credits and is 1 by default. It used to be called
+// `usdPeg`, which read as an exchange rate between a credit and a dollar —
+// exactly what ADR 0387 rules out (a credit has no redemption price). The OLD
+// key is still accepted so no host pack breaks before every hosted pin has moved
+// past this release (ADR 0161); when both are set, `costScale` wins. Removing
+// `usdPeg` support is a later task. The formula itself does not change, and no
+// existing credit_log row is touched — this only renames how a pack spells it.
+// config/branding.neutral.json carries NEITHER key, on purpose: a host pack
+// deep-merges over neutral, so a neutral `costScale: 1` would beat a host's old
+// `usdPeg` and silently reset its awards. The default 1 lives here instead.
+const LEGACY_SCALE_KEY = 'usdPeg';
+const USD_PEG_DEPRECATION =
+  'branding reward.usdPeg is deprecated: rename it to reward.costScale (same value, same awards; ADR 0387).';
+
+function validScale(v) {
+  if (v == null) return NaN;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : NaN;
+}
+
+// PURE. Which sizing factor a raw block carries: costScale if it is valid, else
+// the legacy usdPeg, else the default 1. An INVALID costScale falls through to
+// usdPeg rather than to 1, so a typo in the new key cannot silently change the
+// awards of a pack that still carries a working old one.
+function resolveCostScale(rawReward) {
+  const r = rawReward || {};
+  const fromNew = validScale(r.costScale);
+  if (Number.isFinite(fromNew)) return fromNew;
+  const fromOld = validScale(r[LEGACY_SCALE_KEY]);
+  if (Number.isFinite(fromOld)) return fromOld;
+  return 1;
+}
+
+// PURE. The one-line deprecation note for a pack that still spells the factor the
+// old way, or null. Only when costScale is absent: a pack that has moved and kept
+// the old key beside it is not using it, because costScale wins.
+function rewardPolicyDeprecation(rawReward) {
+  const r = rawReward || {};
+  if (r[LEGACY_SCALE_KEY] != null && r.costScale == null) return USD_PEG_DEPRECATION;
+  return null;
+}
+
 // PURE. Resolves a raw branding `reward` block over the code defaults. Every field
 // is validated rather than trusted: a malformed pack degrades to the defaults
 // instead of poisoning an award.
 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 costScale = resolveCostScale(r);
   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;
   // Default-on, opt-out-only: only an explicit `false` withholds the ideator lane.
@@ -77,7 +120,7 @@ function rewardPolicy(rawReward) {
   const ideaDescentDecay = Number.isFinite(rawDecay) && rawDecay >= 0 && rawDecay < 1
     ? rawDecay
     : IDEA_DESCENT_DECAY;
-  return { marginPct, usdPeg, mode, perTaskCredit, ideatorCredit, artistCredit, ideaDescentDecay };
+  return { marginPct, costScale, mode, perTaskCredit, ideatorCredit, artistCredit, ideaDescentDecay };
 }
 
 module.exports = {
@@ -85,5 +128,8 @@ module.exports = {
   REWARD_MODE_DEFAULT,
   REWARD_MODE_COST_PLUS_ONLY,
   IDEA_DESCENT_DECAY,
+  USD_PEG_DEPRECATION,
+  resolveCostScale,
+  rewardPolicyDeprecation,
   rewardPolicy,
 };

package/modules/economy/reward.js

@@ -24,6 +24,7 @@ const ideaSizeHistorical = require('./idea-size-historical');
 const ideaBrightnessLib = require('./idea-brightness');
 const creditsByCraftLib = require('./credits-by-craft');
 const goalReward = require('./goal-reward');
+const creditWording = require('./credit-wording');
 
 module.exports = {
   // credit allocation — transaction-participant: caller passes its tx `client`
@@ -147,4 +148,8 @@ module.exports = {
   wouldExtendStreak: (...a) => streak.wouldExtendStreak(...a),
   // task 1004853: /me's batched form — one streak + one task query per request.
   streakPreviewsForTasks: (...a) => streak.streakPreviewsForTasks(...a),
+  // task 1004969 (ADR 0385 decision 9): investment wording next to credits or
+  // models. The publish paths flag and log it; they never block or rewrite.
+  findInvestmentWording: (...a) => creditWording.findInvestmentWording(...a),
+  flagInvestmentWording: (...a) => creditWording.flagInvestmentWording(...a),
 };

package/modules/government/routes/government.js

@@ -988,6 +988,13 @@ module.exports = function buildGovernmentRouter() {
         }
         return res.fail('invalid_proposal', 400, { reason: out.reason, ...(out.field ? { field: out.field } : {}), ...(out.expected ? { expected: out.expected } : {}) });
       }
+      // task 1004969 (ADR 0385 decision 9): a board rationale that calls credits
+      // or models an investment is FLAGGED in the log; the item opens unchanged.
+      // Optional and undeclared (the ideas.descent precedent): no economy, no check.
+      const wording = api.resolveOptional && api.resolveOptional('reward');
+      if (wording && typeof wording.flagInvestmentWording === 'function' && typeof req.body.rationale_md === 'string') {
+        wording.flagInvestmentWording(req.body.rationale_md, { where: 'board item', ref: out.item && out.item.id });
+      }
       res.status(201).json({ ok: true, amendment: out.amendment, item: out.item });
     } catch (err) {
       log.error('[gds] POST /government/board/items', err);

package/modules/hall-ui/public/tweak-editor.js

@@ -319,7 +319,8 @@
       notice('<p>The page changed after your draft was saved, so the draft is not shown over its new words. Rewrite the lines again here.</p>');
     }
     if (st.writable) { if (!st.ed.draft_on_older_reading) notice(''); return; }
-    if (!r || r.state === 'draft' || (r.state === 'writing' && !r.holder)) {
+    // A blank round (opened, nothing written; task 1004972) is free to take, like a draft.
+    if (!r || r.state === 'draft' || r.state === 'blank' || (r.state === 'writing' && !r.holder)) {
       notice('<p>Nobody is writing this page. Take it, and every line here is yours to type over.</p>'
         + '<button class="tw-notice__act" id="tw-claim" type="button">take this page</button>');
       return;

package/modules/ideas/routes/inbox.js

@@ -287,6 +287,12 @@ module.exports = function buildInboxRouter() {
         // hand every untrusted door the same power by typing one word.
         vector: 'api',
       });
+      // task 1004969 (ADR 0385 decision 9): an idea that calls credits or models
+      // an investment is FLAGGED in the log; the idea is stored unchanged.
+      const wording = api.resolveOptional && api.resolveOptional('reward');
+      if (wording && typeof wording.flagInvestmentWording === 'function') {
+        wording.flagInvestmentWording([body.title, body.body_md, ...Object.values(body.field_values || {})].filter((v) => typeof v === 'string').join('\n\n'), { where: 'idea', ref: idea.id });
+      }
       let grade_warning;
       if (grade === 'full') {
         // The idea is captured; from here every failure is FAIL-OPEN (the

package/modules/lifecycle/db-claims.js

@@ -39,7 +39,7 @@ const { unsatisfiedDeps } = require('./db-deps-criteria.js');
 const { depRefusalRow } = require('./dead-deps.js');
 const { siblingOverlaps, RESOLVED_STATUSES } = require('./goal-conflicts.js');
 const { claimGate, claimPermissionsFor, disambiguateWorktreeName, foldWorktreeName } = require('./db-rank-authz.js');
-const { sealSessionLog } = require('./db-shared.js');
+const { idKey, sealSessionLog } = require('./db-shared.js');
 const { gatingRebaseTasksForBuilder, shouldRefuseClaimResolve } = require('./db-ship.js');
 const { splitRebaseGate, rebaseRefusalTasks } = require('./rebase-gate.js');
 const { REWARD_SUGGESTION_CAP, rewardGateAssignment } = require('./db-tasks.js');
@@ -898,7 +898,7 @@ async function releaseClaimsBatch({ claimIds, builderId, resolverSessionId, reso
     for (const claimId of uniqIds) {
       const claim = byId.get(claimId);
       if (!claim) { failures.push({ claim_id: claimId, reason: 'CLAIM_NOT_FOUND' }); continue; }
-      if (claim.builder_id !== builderId) { failures.push({ claim_id: claimId, reason: 'NOT_YOUR_CLAIM' }); continue; }
+      if (idKey(claim.builder_id) !== idKey(builderId)) { failures.push({ claim_id: claimId, reason: 'NOT_YOUR_CLAIM' }); continue; }
       if (claim.released_at) { failures.push({ claim_id: claimId, reason: 'ALREADY_RESOLVED' }); continue; }
       // task 1003767: the SAME decision resolveClaim uses, not a third copy of
       // the auth-session compare (this was the second of three). Batch release