@bongos/core 1.23.22 → 1.24.2

package/modules/lifecycle/page-notice.js

@@ -0,0 +1,124 @@
+// modules/lifecycle/page-notice.js — WHO IS UPDATING A PAGE, in one read (task 1004948).
+//
+// An artist's page claim is a marker (task 1004947), so nothing blocks anyone;
+// this is the other half: telling people. `heldPagesForTouches` answers, for the
+// files a task touches, which pages an artist is updating right now, who, and
+// since when. `engineeringActiveOnPage` answers the reverse for an artist: whose
+// engineering claims are open on files that page is made of. Information only:
+// nothing here refuses, gates or writes, and a failed read answers "no notice"
+// rather than throwing, because a heads-up must never break a claim.
+//
+// Every notice is `{ page_id, holder, since, task_id, line }`, the same shape on
+// every surface (claim output, GET /me, the Conductor). Names and ids that reach a
+// session as text are cleaned first: a display name is somebody else's words.
+// Engineering work is reported by holder only, never by title: a task's title can
+// belong to a goal the asking artist may not read (ADR 0112).
+//
+// Reads through the caller's executor (a pool or a transaction client) and the
+// doorway's path matcher, like the rest of the claim ladder.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { touchesOverlap } = api.pathMatch;
+const { PAGE_TWEAK_SOURCE, webClaimPredicate } = require('./page-tweak-artist.js');
+
+// Open page markers / claims are bounded by concurrent people; the cap is a backstop.
+const ROW_CAP = 500;
+
+// 'page-tweak/builders:studio/r2' -> 'builders:studio' ('' when malformed).
+function pageIdOf(sourceRef) {
+  const m = /^page-tweak\/([a-z0-9:-]{1,80})\/r[1-9][0-9]*$/.exec(String(sourceRef || ''));
+  return m ? m[1] : '';
+}
+
+// A name that is safe to print into a session's context: no control characters,
+// no newlines, at most 60 characters.
+function cleanName(raw, fallback) {
+  const s = String(raw == null ? '' : raw).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 60);
+  return s || fallback;
+}
+
+// One line a person or an AI session reads: gentle, never a refusal.
+function noticeLine(n) {
+  const since = n.since ? new Date(n.since).toISOString().slice(0, 10) : 'recently';
+  return `${n.page_id} is being updated by ${n.holder} (since ${since}) — expect copy changes on it.`;
+}
+
+// Every open page marker, with its holder: ONE read for any number of tasks.
+async function openMarkers(exec) {
+  const { rows } = await exec.query(
+    `SELECT t.id AS task_id, t.source_ref, t.touches, c.claimed_at,
+            COALESCE(b.display_name, b.github_login) AS holder
+       FROM claims c
+       JOIN tasks t ON t.id = c.task_id
+       JOIN builders b ON b.id = c.builder_id
+      WHERE c.released_at IS NULL
+        AND t.source = '${PAGE_TWEAK_SOURCE}'
+        AND ${webClaimPredicate('c')}
+      ORDER BY c.claimed_at
+      LIMIT ${ROW_CAP}`
+  );
+  return rows;
+}
+
+function noticesFor(touches, markers, exceptTaskId) {
+  if (!Array.isArray(touches) || touches.length === 0) return [];
+  return markers
+    .filter((r) => String(r.task_id) !== String(exceptTaskId) && touchesOverlap(touches, r.touches))
+    .map((r) => {
+      const n = { page_id: pageIdOf(r.source_ref), holder: cleanName(r.holder, 'an artist'), since: r.claimed_at, task_id: String(r.task_id) };
+      return { ...n, line: noticeLine(n) };
+    })
+    .filter((n) => n.page_id);
+}
+
+// heldPagesForTouches(touches, exec, { exceptTaskId }) -> notices  (empty on no overlap or any failure)
+async function heldPagesForTouches(touches, exec, { exceptTaskId = null } = {}) {
+  if (!Array.isArray(touches) || touches.length === 0) return [];
+  try {
+    return noticesFor(touches, await openMarkers(exec), exceptTaskId);
+  } catch (_) {
+    return [];
+  }
+}
+
+// noticesForClaims(claims, exec) -> Map(task_id -> notices): ONE read for all of a
+// builder's claims (GET /me), instead of one per claim. A claim with no touches or
+// no overlap maps to [].
+async function noticesForClaims(claims, exec = api.pool) {
+  const out = new Map();
+  const list = Array.isArray(claims) ? claims : [];
+  for (const c of list) out.set(String(c.task_id), []);
+  if (list.length === 0) return out;
+  try {
+    const markers = await openMarkers(exec);
+    for (const c of list) out.set(String(c.task_id), noticesFor(c.touches, markers, c.task_id));
+  } catch (_) { /* heads-up only */ }
+  return out;
+}
+
+// engineeringActiveOnPage(pageTouches, exec) -> [{ task_id, holder }]
+// Open worktree claims on real code work (never a page round, whoever holds it)
+// whose files overlap the page's files. No title: see the header.
+async function engineeringActiveOnPage(pageTouches, exec = api.pool) {
+  if (!Array.isArray(pageTouches) || pageTouches.length === 0) return [];
+  try {
+    const { rows } = await exec.query(
+      `SELECT t.id AS task_id, t.touches, COALESCE(b.display_name, b.github_login) AS holder
+         FROM claims c
+         JOIN tasks t ON t.id = c.task_id
+         JOIN builders b ON b.id = c.builder_id
+        WHERE c.released_at IS NULL
+          AND t.source IS DISTINCT FROM '${PAGE_TWEAK_SOURCE}'
+        LIMIT ${ROW_CAP}`
+    );
+    return rows
+      .filter((r) => touchesOverlap(pageTouches, r.touches))
+      .map((r) => ({ task_id: String(r.task_id), holder: cleanName(r.holder, 'an engineer') }));
+  } catch (_) {
+    return [];
+  }
+}
+
+module.exports = { heldPagesForTouches, noticesForClaims, engineeringActiveOnPage };

package/modules/lifecycle/page-tweak-artist.js

@@ -24,6 +24,23 @@ function webClaimPredicate(alias = 'c') {
   return `${alias}.worktree_name IS NULL AND ${alias}.creator_session_id IS NULL`;
 }
 
+// A PAGE MARKER is an artist's web claim on a page-tweak round: it says "this
+// page is being updated" and nothing more. The file-overlap checks that guard
+// engineering work against engineering work (the claimable feed, claimTask,
+// the batch claim and its dry-run) leave markers out, so an artist writing a
+// page never hides or refuses coding work on the same files. That includes
+// claimTask's module-disjointness gate, which reads the same active-claim rows:
+// a page round carries no module_key, and a marker must never hold a module.
+// Returns a SQL condition that is true for every claim that is NOT a marker.
+// COALESCE keeps it TRUE (counted) when tasks.source is NULL: without it a
+// both-NULL claim on a source-less task would evaluate to NULL and vanish.
+// src/bongos/optimizer.js carries a hand copy (core cannot require a module);
+// tests/page_tweak_marker_sql.mjs pins the two together.
+// Aliases are code literals at every call site; never pass request input.
+function notPageMarkerSql(claimAlias = 'c', taskAlias = 't') {
+  return `NOT (COALESCE(${taskAlias}.source, '') = '${PAGE_TWEAK_SOURCE}' AND ${webClaimPredicate(claimAlias)})`;
+}
+
 // The newest claim first; the id breaks a same-instant tie the same way in
 // every reader.
 function latestFirst(alias = 'c') {
@@ -83,4 +100,4 @@ function helperJoinSql(alias = 't') {
            ) helper ON true`;
 }
 
-module.exports = { PAGE_TWEAK_SOURCE, webClaimPredicate, latestFirst, artistIdSql, shippedBySql, helperJoinSql };
+module.exports = { PAGE_TWEAK_SOURCE, webClaimPredicate, notPageMarkerSql, latestFirst, artistIdSql, shippedBySql, helperJoinSql };

package/modules/lifecycle/publish-reconciler.js

@@ -852,8 +852,6 @@ function loggers(deps = {}) {
   return { logFn: deps.log || console.log, errFn: deps.error || console.error };
 }
 
-// A single crash handler for the tick's fire-and-forget sweeps — same reason.
-const crashHandler = (name) => (e) => loggers().errFn(`[publish-reconciler] ${name} crashed: ${e && e.message}`);
 
 async function runCostSweep(deps = {}) {
   const { logFn, errFn } = loggers(deps);
@@ -958,19 +956,23 @@ async function runPromotionSweep(deps = {}) {
 
 // The craft-achievement backfill (task 1004438, WA6.RP08): the one badge a
 // migration cannot backfill, "A Whole Surface", needs the page inventory, which is
-// a file the database never sees. Run ONCE per process start, on the first tick,
-// through the reward port (economy is optional; no port, no sweep). Pure DB and
-// idempotent, so a restart that runs it again unlocks nothing twice; a failure is
-// logged and never touches the other sweeps.
-let craftBackfillDone = false;
+// a file the database never sees. Runs HOURLY (task 1004965) through the reward
+// port (economy is optional; no port, no sweep), and INCREMENTALLY: the first run
+// of a process scans every craft-paid builder and hands back a watermark (the
+// highest credit_log id it covered); every later run asks only about builders
+// paid since that id, so a caught-up backfill is one indexed read that finds
+// nothing. Pure DB and idempotent, so a restart that rescans unlocks nothing
+// twice; a failure keeps the watermark (the next run retries the same span) and
+// never touches the other sweeps.
+let craftWatermark = 0;
 async function runCraftAchievementBackfill(deps = {}) {
   const { logFn, errFn } = loggers(deps);
-  if (craftBackfillDone && !deps.forceCraftBackfill) return { skipped: 'already_ran' };
-  craftBackfillDone = true;
   const reward = deps.reward || seams.resolveOptional('reward');
   if (!reward || typeof reward.backfillCraftAchievements !== 'function') return { skipped: 'unsupported' };
   try {
-    const out = await reward.backfillCraftAchievements({});
+    const out = await reward.backfillCraftAchievements({ sinceId: craftWatermark });
+    const next = out ? Number(out.watermark) : NaN;
+    if (Number.isFinite(next) && next > craftWatermark) craftWatermark = next;
     if (out && out.unlocked) logFn(`[publish-reconciler] craft achievements: ${out.unlocked} unlocked across ${out.checked} builder(s)`);
     return out;
   } catch (e) {
@@ -979,6 +981,57 @@ async function runCraftAchievementBackfill(deps = {}) {
   }
 }
 
+// The sweeps one tick fires. Each is INDEPENDENT on purpose: the cost (task 1366)
+// and criterion (task 1002069) sweeps are pure DB — no push credential — and a
+// failure in either must never touch the confirmed→shipped work.
+//
+// CADENCE PER SWEEP (task 1004965): an entry's third element is its minimum gap
+// between runs; none means every tick (INTERVAL_MS). The publish, cost and
+// criterion sweeps keep the tick — a strand, an unpriced session and a newly
+// satisfiable criterion are all things someone is waiting on. The promotion sweep
+// and the craft backfill run HOURLY: the ship-time triggers already promote and
+// unlock on the event, so these are backlog drains, and a drain an hour late
+// costs nobody anything while running it every 5 minutes cost every instance
+// ~288 scans a day.
+const HOURLY_MS = 60 * 60_000;
+const SWEEPS = [
+  ['sweep', runSweep],
+  ['cost sweep', runCostSweep],
+  ['criterion sweep', runCriterionSweep],
+  ['promotion sweep', runPromotionSweep, HOURLY_MS],
+  ['craft achievement backfill', runCraftAchievementBackfill, HOURLY_MS],
+];
+
+// buildTick — one interval round, with a per-sweep overlap guard (task 1004924).
+// A sweep whose previous run has not settled is SKIPPED this tick, so a slow DB
+// or GitHub call can never stack rounds and hold several pool connections at
+// once. The flag is per sweep, so one slow sweep never starves the others, and
+// it clears whether the run resolves or rejects. `sweeps` is the test seam.
+//
+// A sweep with a cadence runs on the first tick, then again once its gap has
+// passed. Half a tick of slack, so timer jitter (a tick landing a few ms early)
+// never pushes an hourly sweep a whole tick late. `now` is the clock seam.
+function buildTick(deps = {}, sweeps = SWEEPS, { now = Date.now, tickMs = INTERVAL_MS } = {}) {
+  const inFlight = new Set();
+  const lastRun = new Map();
+  return () => {
+    const t = now();
+    for (const [name, fn, everyMs] of sweeps) {
+      if (everyMs && lastRun.has(name) && t - lastRun.get(name) < everyMs - tickMs / 2) continue; // not due yet
+      if (inFlight.has(name)) {
+        loggers(deps).logFn(`[publish-reconciler] ${name} still running from the last tick — skipped`);
+        continue;
+      }
+      lastRun.set(name, t);
+      inFlight.add(name);
+      Promise.resolve()
+        .then(() => fn(deps))
+        .catch((e) => loggers(deps).errFn(`[publish-reconciler] ${name} crashed: ${e && e.message}`))
+        .finally(() => inFlight.delete(name));
+    }
+  };
+}
+
 // Start the periodic sweep. Idempotent (a second call is a no-op). Kill-switched
 // by PUBLISH_RECONCILER_DISABLED=1 (purely additive bookkeeping, so it's ON by
 // default whenever a push credential is configured; the route's getPublishStatus
@@ -991,16 +1044,7 @@ function start(deps = {}) {
   }
   if (intervalTimer) return; // already started
 
-  // Each sweep is INDEPENDENT on purpose: the cost (task 1366) and criterion
-  // (task 1002069) sweeps are pure DB — no push credential — and a failure in
-  // either must never touch the confirmed→shipped work.
-  const tick = () => {
-    runSweep(deps).catch(crashHandler('sweep'));
-    runCostSweep(deps).catch(crashHandler('cost sweep'));
-    runCriterionSweep(deps).catch(crashHandler('criterion sweep'));
-    runPromotionSweep(deps).catch(crashHandler('promotion sweep'));
-    runCraftAchievementBackfill(deps).catch(crashHandler('craft achievement backfill'));
-  };
+  const tick = buildTick(deps);
 
   firstTimer = setTimeout(tick, FIRST_SWEEP_DELAY_MS);
   if (firstTimer.unref) firstTimer.unref();
@@ -1039,7 +1083,10 @@ module.exports = {
   runPromotionSweep,
   runCriterionSweep,
   runCraftAchievementBackfill,
+  buildTick,
   couldBeStaleGenerated,
   describeTarget,
   INTERVAL_MS,
+  HOURLY_MS,
+  SWEEPS,
 };

package/modules/lifecycle/routes/claims.js

@@ -305,7 +305,7 @@ module.exports = function buildClaimsRouter() {
         enforceOverlap: enforceTouches === true,
         autoPickup: autoPickup === true,
       });
-      const { just_unlocked: justUnlocked, overlap_warning: overlapWarning, sibling_overlap_warning: siblingOverlapWarning, ...claim } = claimResult;
+      const { just_unlocked: justUnlocked, overlap_warning: overlapWarning, sibling_overlap_warning: siblingOverlapWarning, page_notice: pageNotice, ...claim } = claimResult;
       const task = await db.getTask(Number(taskId));
       // task 1168: keep the evergreen newcomer-chore shelf full. If this claim
       // took a chore instance, stamp a replacement NOW (before responding) so
@@ -339,7 +339,7 @@ module.exports = function buildClaimsRouter() {
         const p = rw && typeof rw.rewardConfig === 'function' ? rw.rewardConfig() : null;
         if (p && typeof p.mode === 'string') rewardMode = { mode: p.mode, perTaskCredit: p.perTaskCredit !== false };
       } catch (_) { /* display-only: a claim must never fail over this */ }
-      res.status(201).json({ claim, task, just_unlocked: justUnlocked ?? [], overlap_warning: overlapWarning ?? null, sibling_overlap_warning: siblingOverlapWarning ?? null, reward: rewardMode });
+      res.status(201).json({ claim, task, just_unlocked: justUnlocked ?? [], overlap_warning: overlapWarning ?? null, sibling_overlap_warning: siblingOverlapWarning ?? null, page_notice: pageNotice ?? [], reward: rewardMode });
     } catch (err) {
       if (err && err.code) {
         const status =
@@ -388,6 +388,9 @@ module.exports = function buildClaimsRouter() {
           // block, not an authorization refusal). The refusal object already
           // carries `message` + `hint`, so no extra hint-building step needed.
           err.code === 'RELEVANCE_REVIEW_PENDING' ? 409 :
+          // task 1004950 / ADR 0395: the task needs hands on the live server and
+          // the claimer holds no server grant — an authorization refusal, like rank.
+          err.code === 'NEEDS_SERVER_ACCESS' ? 403 :
           // ADR 0371 D5/D6: a marked auto-pickup claim the project's switch, monthly
           // cap or per-round limit refuses. The round waits for a person.
           err.code === 'AUTO_PICKUP_NOT_A_TWEAK' ? 409 :

package/modules/lifecycle/routes/goals.js

@@ -1333,6 +1333,7 @@ module.exports = function buildGoalsRouter() {
       discipline: { type: 'string', maxLength: 64 },
       value_summary: { type: 'string', maxLength: LIMITS.VALUE_SUMMARY },
       parent_task_id: { type: 'integer', min: 1 },
+      needs: {}, // task 1004950 / ADR 0395 — ['owner'|'server']; a need narrows who is shown the task, it grants nothing
       // Deliberately NOT read from the client (validateOrRespond ignores unknown
       // fields, so any of these a client smuggles in are simply never used):
       //   • version_id  — derived from the goal (a member can't author cross-version);
@@ -1343,6 +1344,7 @@ module.exports = function buildGoalsRouter() {
     })) return;
 
     const body = req.body || {};
+    const goalNeeds = api.taskNeeds.normalizeNeeds(body.needs); if (!goalNeeds.ok) return require('./task-route-helpers.js').badNeeds(res, goalNeeds.bad);
     const touches = Array.isArray(body.touches) ? [...body.touches] : [];
 
     try {
@@ -1425,7 +1427,7 @@ module.exports = function buildGoalsRouter() {
         kind,
         discipline,
         source: 'goal-authored',
-        goalId: goal.id,
+        goalId: goal.id, needs: goalNeeds.needs,
         // task 1003278 — attribution from the authenticated request (never the body).
         createdBy: req.builder.id,
       });

package/modules/lifecycle/routes/notes.js

@@ -0,0 +1,91 @@
+// modules/lifecycle/routes/notes.js — notes on a task or a goal, read grouped by
+// purpose (task 1004745, goal 1000095).
+//
+// Four routes: read the notes on one task or goal (already grouped), add one, re-file
+// one under another purpose, and delete one. The grouping, the subject rule, who may
+// see a private goal's notes and who may change a note are all notes.js's; this surface
+// only gathers the request and renders the verdict.
+//
+// A note nobody may see answers 404, exactly as a missing one does, so the answer
+// never tells a non-member that a private goal has notes. Every write here is recorded
+// by the server's audit middleware, so a Metic's delete leaves a trail.
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const notes = require('../notes');
+
+const { asyncHandler, parseId, validateOrRespond } = api;
+
+module.exports = function buildNotesRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — notes are shared working information, readable by anyone
+  // signed in; a private goal's notes are narrowed to its members by notes.canSee.
+  router.get('/notes', api.requireBuilder, asyncHandler('GET /notes', async (req, res) => {
+    const subject = notes.subjectOf(req.query || {});
+    if (!subject) return res.fail('invalid_subject', 400, { hint: 'give exactly one of task_id or goal_id' });
+    if (!(await notes.canSee(req.builder, subject))) return res.fail('not_found', 404);
+    const rows = await notes.listNotes(subject);
+    return res.json({ count: rows.length, groups: notes.groupNotes(rows), kinds: notes.KINDS });
+  }, { errorCode: 'notes_read_failed' }));
+
+  // rank: any-builder — adding information is not a privileged act; the author is
+  // the caller and is never taken from the body.
+  router.post('/notes', api.requireBuilder, asyncHandler('POST /notes', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      body: { required: true, type: 'string', minLength: 1, maxLength: notes.MAX_BODY },
+      kind: { type: 'string', maxLength: 16 },
+      task_id: { type: 'integer', min: 1 },
+      goal_id: { type: 'integer', min: 1 },
+    })) return;
+    const body = req.body || {};
+    const v = notes.validateNote(body);
+    if (!v.ok) return res.fail('invalid_note', 400, { errors: v.errors, kinds: notes.KIND_KEYS });
+    const subject = notes.subjectOf(body);
+    if (!(await notes.canSee(req.builder, subject))) return res.fail('not_found', 404);
+    if ((await notes.countNotes(subject)) >= notes.MAX_NOTES_PER_SUBJECT) {
+      return res.fail('note_limit', 409, { limit: notes.MAX_NOTES_PER_SUBJECT });
+    }
+    const note = await notes.addNote({
+      taskId: subject.taskId ?? null,
+      goalId: subject.goalId ?? null,
+      authorId: req.builder.id,
+      body: v.body,
+      kind: v.kind,
+      kindSource: v.kindSource,
+    });
+    return res.status(201).json({ ok: true, note });
+  }, { errorCode: 'note_create_failed' }));
+
+  // rank: any-builder, narrowed in the handler — the author re-files their own note;
+  // a Metic or Archon may re-file anyone's (the grouping is a shared view).
+  router.patch('/notes/:id', api.requireBuilder, asyncHandler('PATCH /notes/:id', async (req, res) => {
+    if (validateOrRespond(req, res, { kind: { required: true, type: 'string', maxLength: 16 } })) return;
+    const id = parseId(req.params.id);
+    const kind = req.body.kind;
+    if (id == null) return res.fail('invalid_id', 400);
+    if (!notes.KIND_KEYS.includes(kind)) return res.fail('invalid_note', 400, { errors: [{ field: 'kind', reason: 'pick one of the listed groups' }], kinds: notes.KIND_KEYS });
+    const existing = await notes.getNote(id);
+    if (!existing || !(await notes.canSee(req.builder, notes.subjectOf(existing)))) return res.fail('not_found', 404);
+    if (!notes.canChange(req.builder, existing)) return res.fail('not_yours', 403);
+    const row = await notes.setKind(id, kind);
+    return res.json({ ok: true, note: row });
+  }, { errorCode: 'note_update_failed' }));
+
+  // rank: any-builder, narrowed in the handler exactly as the re-file above.
+  router.delete('/notes/:id', api.requireBuilder, asyncHandler('DELETE /notes/:id', async (req, res) => {
+    const id = parseId(req.params.id);
+    if (id == null) return res.fail('invalid_id', 400);
+    const existing = await notes.getNote(id);
+    if (!existing || !(await notes.canSee(req.builder, notes.subjectOf(existing)))) return res.fail('not_found', 404);
+    if (!notes.canChange(req.builder, existing)) return res.fail('not_yours', 403);
+    await notes.deleteNote(id);
+    return res.json({ ok: true });
+  }, { errorCode: 'note_delete_failed' }));
+
+  return router;
+};

package/modules/lifecycle/routes/project-settings.js

@@ -7,8 +7,9 @@
 // WHY THIS ROUTE EXISTS. Goal 1000072's thesis is that this project is legible to
 // Claude and illegible to a human: the system knows everything and exposes almost
 // none of it in a shape a person can hold. The five values here — the rot timer, the
-// category set, how credits are calculated, whether equity is real, and what share of
-// upmarket revenue is paid on credits — were each answerable only by reading source.
+// category set, how credits are calculated, what credits are (and are not) next to
+// equity, and whether a credit-weighted pool can pay out — were each answerable only
+// by reading source.
 // This route is the TRANSLATION LAYER, not a new capability: it invents no value and
 // stores nothing of its own.
 //
@@ -20,10 +21,11 @@
 // and say why.
 //
 // AND THE ONE THAT KEEPS IT HONEST: a fundamental with no knob behind it is reported
-// as ABSENT, never as a plausible zero. `upmarket_percent` is that row today — the
-// task asked for it, and no such knob exists anywhere in this codebase. Rendering it
-// as "0%" would be a fabricated fact about the project's economics; saying "there is
-// no such setting yet, and here is where it would live" is the legible answer.
+// as ABSENT or GATED, never as a plausible zero. `upmarket_percent` (shown as the
+// credit-weighted pool) is that row today: no such knob exists, and ADR 0385 gates
+// the pay type behind counsel and a signed rule. Rendering it as "0%" would be a
+// fabricated fact about the project's economics; saying "not available, and here is
+// what gates it" is the legible answer.
 //
 // MODULE BOUNDARY: reaches core only through the published doorway
 // `../../../src/module-api`; `../goal-category` is an intra-module sibling.
@@ -118,58 +120,64 @@ function creditRow() {
   // (ADR 0146). A page that showed the estimate without that sentence would be telling
   // a builder they will earn a number this instance has decided not to pay.
   const estimate = policy.perTaskCredit
-    ? 'A task’s own credit estimate is also paid, scaled by its kind.'
-    : 'A task’s credit estimate is an advertised guide only — this instance pays cost-plus and nothing else.';
+    ? 'A task’s own credit estimate is also awarded, scaled by its kind.'
+    : 'A task’s credit estimate is an advertised guide only — this instance awards cost-plus credits and nothing else.';
+  // Wording per ADR 0387: the formula's INPUT is USD, so the credits are "sized by"
+  // the session's cost — never "worth" dollars, and never money.
   return {
     key: 'credit_calculation',
     title: 'Credit calculation',
     editable: false,
     state: 'live',
     value: { marginPct: policy.marginPct, usdPeg: policy.usdPeg, mode: policy.mode, perTaskCredit: policy.perTaskCredit },
-    sentence: `A shipped session pays round(true cost in USD × ${mult}${pegNote}). ${estimate}`,
+    sentence: `A shipped session earns round(true cost in USD × ${mult}${pegNote}) credits, sized by the session’s cost in USD. Credits measure contribution; they are not money. ${estimate}`,
     source: 'branding pack → `reward`',
     reads: { file: 'config/branding.json → reward', adr: 'ADR 0054, ADR 0146' },
   };
 }
 
-// Equity. THE OWNER DECIDED THIS (2026-08-25) and the decision is that it is NOT REAL:
-// credits ARE the ownership stream today, and no legal equity is issued. The page says
-// that plainly rather than implying a cap table exists — an owner reading their own
-// settings page must not come away believing shares are being issued. If issuance ever
-// becomes real it gets its own decision record; the Board Room spec already parks
-// Howey / Subchapter T explicitly out of scope.
+// Equity. Bongos issues none, and credits are NOT equity. The owner's 2026-08-25
+// decision (no legal equity issued) stands; the older ADR 0054 framing that a credit
+// IS a unit of ownership was superseded on 2026-10-29 (ADR 0385 decisions 2-3, ADR
+// 0387): credits are a project-scoped contribution meter, and equity, if a project
+// offers any, is that project's own grant, one signature each. The page says that
+// plainly — an owner reading their own settings page must not come away believing
+// credits are shares or that a cap table exists. The key stays `equity_calculation`
+// so existing readers keep working.
 function equityRow() {
   return {
     key: 'equity_calculation',
-    title: 'Equity calculation',
+    title: 'Equity',
     editable: false,
     state: 'not-yet-real',
-    sentence: 'No legal equity is issued. Credits are the ownership stream this project actually runs — '
-      + 'the owner’s framing in ADR 0054 is that a credit IS a unit of ownership. There is no cap table, '
-      + 'no share class and no issuance behind this row.',
-    source: 'owner decision, 2026-08-25',
-    reads: { file: 'docs/adr/0054-drachmae-token-reward.md', adr: 'ADR 0054' },
+    sentence: 'Credits are a contribution meter, not ownership: they measure work on this project '
+      + 'and are never money, never redeemable and never equity. No legal equity is issued here. '
+      + 'Equity, if any, is granted by the project separately, one signed grant at a time — '
+      + 'there is no cap table and no share class behind this row.',
+    source: 'owner decisions, 2026-08-25 and 2026-10-29',
+    reads: { file: 'docs/adr/0054-session-token-reward-cost-plus.md', adr: 'ADR 0054 (superseded in part), ADR 0385, ADR 0387' },
   };
 }
 
-// The share of upmarket revenue paid out on credits. NO SUCH KNOB EXISTS — searched
-// across code, config, migrations and docs on this task and found only prose in an
-// unrelated competitive-analysis file. So this row reports ABSENCE and names where the
-// setting would live if it became real, which is the actionable fact. A rendered "0%"
-// would be a fabricated economic claim; an omitted row would leave the owner to
-// rediscover the gap by grep.
+// The credit-weighted pool: a project dividing a pool of its OWN money by credit
+// share (ADR 0387 decision 3). The row key stays `upmarket_percent` (its first name,
+// "share of upmarket revenue paid on credits") so existing readers keep working.
+// NO SUCH KNOB EXISTS, and ADR 0385's pay-type gates hold this one shut until the
+// wording rule is in force, the model's inputs are visible and a signed payout rule
+// exists — with counsel's answer on held item 2 first. So the row reports GATED,
+// never a rendered "0%", which would be a fabricated economic claim.
 function upmarketRow() {
   return {
     key: 'upmarket_percent',
-    title: 'Percent of upmarket revenue paid on credits',
+    title: 'Credit-weighted pool',
     editable: false,
-    state: 'absent',
-    sentence: 'This project has no such setting yet — nothing in the code, config or database '
-      + 'defines it, so there is no number to show. It would belong beside the other reward '
-      + 'terms in the branding pack’s `reward` block, and paying against it would need its own '
-      + 'decision record first.',
-    source: 'not configured anywhere',
-    reads: { file: 'config/branding.json → reward (where it would live)', adr: null },
+    state: 'gated',
+    sentence: 'Not available (gated). A project could one day divide a pool of its own money by '
+      + 'credit share, but that pay type stays switched off until counsel clears it and the '
+      + 'project signs a payout rule. Bongos sets no share and no rate, and no dollar value is '
+      + 'ever read off a credit.',
+    source: 'gated by ADR 0385 (pay-type gates)',
+    reads: { file: 'docs/adr/0385-money-lives-with-a-processor-credits-stay-a-project-meter.md', adr: 'ADR 0385, ADR 0387' },
   };
 }
 

package/modules/lifecycle/routes/task-route-helpers.js

@@ -251,10 +251,31 @@ function badKind(res) {
 }
 
 
+// task 1004950 / ADR 0395: a task's needs are a subset of TASK_NEEDS. Shared by
+// POST /tasks, PATCH /tasks/:id and POST /goals/:id/tasks so all three refuse alike.
+function badNeeds(res, bad) {
+  const valid = api.taskNeeds.TASK_NEEDS;
+  return res.fail('bad_needs', { status: 400, message: `needs must list only: ${valid.join(', ')} (unknown: ${bad.join(', ')}). Most tasks need neither.`, details: { valid } });
+}
+
+// ?needs= on GET /tasks and GET /tasks/claimable (task 1004950): one need
+// ('owner' | 'server') or 'none'. Shared so the two lists agree on the vocabulary.
+const NEEDS_FILTERS = new Set([...api.taskNeeds.TASK_NEEDS, 'none']);
+function parseNeedsFilter(raw) {
+  if (raw === undefined || raw === '') return undefined;
+  return NEEDS_FILTERS.has(raw) ? raw : { bad: 'bad_needs' };
+}
+function badNeedsFilter(res) {
+  return res.fail('bad_needs', { status: 400, message: `needs must be one of ${[...NEEDS_FILTERS].join(' | ')}.` });
+}
+
 module.exports = {
+  badNeedsFilter,
+  parseNeedsFilter,
   MIGRATION_KEYWORD_RE,
   VALID_FITS,
   badKind,
+  badNeeds,
   deHashRefs,
   detectsMigration,
   gateTaskOwnership,