@bongos/core 1.23.22 → 1.24.1

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,

package/modules/lifecycle/routes/task-write-routes.js

@@ -26,7 +26,7 @@ const { buildDependencyAdvisory } = require('../dependency-advisory');
 const { classifyTaskKind, VALID_KINDS, WRITABLE_DISCIPLINES, resolveWriteDiscipline, VOTABLE_TASK_STATUSES, TASK_FIELD_BOUNDS } = require('../task-classifier');
 const { isModuleKey, moduleKeys } = api.moduleScopeMap;
 const { validateOrRespond, LIMITS, parseId } = api;
-const { badKind, detectsMigration } = require('./task-route-helpers.js');
+const { badKind, badNeeds, detectsMigration } = require('./task-route-helpers.js');
 const { describeCheckViolation } = require('../pg-constraint-fail.js');
 const { goalNotOpenRefusal } = require('./goal-route-authz.js');
 const { resolveUpkeepHome, isUpkeepFiling, UPKEEP_HINT } = require('../upkeep-home.js'); // task 1004597
@@ -62,6 +62,7 @@ module.exports = function registerTaskWriteRoutes(router) {
       newcomer_friendly: { type: 'boolean' },  // V3.R15 #239 — Xenos-claimable flag
       security_sensitive: { type: 'boolean' },  // task 990 — Archon-only ship broadcast
       requires_rank: { type: 'string', maxLength: 16 },  // task 1498 / ADR 0084 — per-task rank floor (auto-derived; explicit value can only raise it)
+      needs: {},  // task 1004950 / ADR 0395 — ['owner'|'server'] or a comma list; checked inline
       auto_detect_touches: { type: 'boolean' },
       // task 438: link the new task to done-when criteria at creation time. Each
       // element is a criterion_id slug (required on a multi-goal version — task
@@ -169,6 +170,9 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('bad_requires_rank', { status: 400, message: `requires_rank must be one of ${db.LIVE_RANK_LADDER.join(' | ')}. The floor auto-derives from touches + security_sensitive; an explicit value can only raise it.`, details: { valid: db.LIVE_RANK_LADDER } });
       }
     }
+    // task 1004950 / ADR 0395: what the task needs beyond the build loop.
+    const createNeeds = api.taskNeeds.normalizeNeeds(body.needs);
+    if (!createNeeds.ok) return badNeeds(res, createNeeds.bad);
     // BV1.R53 (task 1422): validate module_key against MODULE_SCOPE_MAP.
     if (body.module_key != null && !isModuleKey(body.module_key)) {
       return res.fail('bad_module_key', { status: 400, message: `module_key must be one of the known module keys, or omitted. Valid keys: ${moduleKeys().join(', ')}.`, details: { valid: moduleKeys() } });
@@ -245,6 +249,7 @@ module.exports = function registerTaskWriteRoutes(router) {
         requiresRank: body.requires_rank ?? null,
         moduleKey: body.module_key ?? null,
         goalId: body.goal_id ?? null,
+        needs: createNeeds.needs,
         // task 1003278 — attribution, from the AUTHENTICATED request, never the
         // body: who created a task is a fact about the caller, not an input.
         createdBy: req.builder.id,
@@ -348,6 +353,7 @@ module.exports = function registerTaskWriteRoutes(router) {
       xenos_claimable: { type: 'boolean' },              // pre-rename alias for newcomer_friendly
       security_sensitive: { type: 'boolean' },           // task 990 — Archon-only ship broadcast
       automation_tag: { type: 'string', maxLength: 64 },
+      needs: {},                                         // task 1004950 — ['owner'|'server'], a comma list, or null/[] to clear; checked inline
       needs_migration: { type: 'boolean' },              // task 1002648 — correct the create-time heuristic's flag (the claim-time allocator keys off it)
       // task 1002647 (map s4.3): the task body is a load-bearing builder prompt
       // and was settable only at create — no route edited it at any rank. Now
@@ -397,6 +403,7 @@ module.exports = function registerTaskWriteRoutes(router) {
     const hasParallelSafe = Object.prototype.hasOwnProperty.call(body, 'parallel_safe');
     const hasSecuritySensitive = Object.prototype.hasOwnProperty.call(body, 'security_sensitive');
     const hasAutomationTag = Object.prototype.hasOwnProperty.call(body, 'automation_tag');
+    const hasNeeds = Object.prototype.hasOwnProperty.call(body, 'needs');
     const hasNeedsMigration = Object.prototype.hasOwnProperty.call(body, 'needs_migration');
     const hasRequiresRank = Object.prototype.hasOwnProperty.call(body, 'requires_rank');
     const hasModuleKey = Object.prototype.hasOwnProperty.call(body, 'module_key');
@@ -416,8 +423,8 @@ module.exports = function registerTaskWriteRoutes(router) {
     if (Object.prototype.hasOwnProperty.call(body, 'status')) {
       return res.fail('status_not_patchable', { status: 400, message: STATUS_HINT });
     }
-    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority && !hasValueSummary) {
-      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, value_summary, priority, parallel_safe, security_sensitive, automation_tag, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
+    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeeds && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority && !hasValueSummary) {
+      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, value_summary, priority, parallel_safe, security_sensitive, automation_tag, needs, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
     }
     // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
     // ---- FIRST write. The previous shape validated-and-wrote per field in ----
@@ -476,6 +483,8 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('bad_automation_tag', { status: 400, message: 'automation_tag must be one of overnight-safe | live-only | needs-input, or null to clear', details: { valid: Array.from(VALID_AUTOMATION_TAGS) } });
       }
     }
+    const patchNeeds = hasNeeds ? api.taskNeeds.normalizeNeeds(body.needs) : null;
+    if (patchNeeds && !patchNeeds.ok) return badNeeds(res, patchNeeds.bad);
     if (hasModuleKey) {
       // BV1.R53 (task 1422): assign or clear the module affinity label. null clears.
       if (body.module_key !== null && !isModuleKey(body.module_key)) {
@@ -577,6 +586,15 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('patch_failed', { status: 500, message: 'internal error' });
       }
     }
+    if (hasNeeds) {
+      try {
+        updated = await db.updateTaskNeeds(id, patchNeeds.needs);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        log.error('[gds] PATCH /tasks/:id needs', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
     if (hasNeedsMigration) {
       try {
         updated = await db.updateTaskNeedsMigration(id, body.needs_migration);

package/modules/lifecycle/routes/tasks.js

@@ -91,7 +91,7 @@ const PUBLISH_BUNDLE_MAX_BYTES = 20 * 1024 * 1024; // 20 MB decoded bundle
 // autolinks to GitHub's own issue space (dead links for GDS task ids — task 916).
 // Mirrors ship.js sanitizeGitHubRefs (which lives in scripts/ and isn't requirable
 // here).
-const { MIGRATION_KEYWORD_RE, VALID_FITS, badKind, deHashRefs, detectsMigration, gateTaskOwnership, graderBypassEnabled, isVerifyTask, peerVoteNet, postGateAuthorTrust, rankAttestsGateTrust } = require('./task-route-helpers.js');
+const { MIGRATION_KEYWORD_RE, VALID_FITS, badKind, badNeedsFilter, parseNeedsFilter, deHashRefs, detectsMigration, gateTaskOwnership, graderBypassEnabled, isVerifyTask, peerVoteNet, postGateAuthorTrust, rankAttestsGateTrust } = require('./task-route-helpers.js');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('lifecycle');
 const registerTaskWriteRoutes = require('./task-write-routes.js'); // task 1003206 — POST /tasks + PATCH /tasks/:id
@@ -176,10 +176,11 @@ module.exports = function buildTasksRouter() {
     if (limit && limit.bad) return res.fail('bad_limit', { status: 400, message: 'limit must be a positive integer up to 1000.' });
     const offset = posInt(offsetRaw, 'bad_offset');
     if (offset && offset.bad) return res.fail('bad_offset', { status: 400, message: 'offset must be a positive integer.' });
+    const needs = parseNeedsFilter(req.query.needs); if (needs && needs.bad) return badNeedsFilter(res); // task 1004950
 
     const tasks = await db.listTasks({
       versionId: version, status, kind, discipline, goalId,
-      createdBy, staleDays, limit, offset,
+      createdBy, staleDays, limit, offset, needs,
     });
     // ?include=deps (hall redesign task 1002439) — enrich each task with its
     // dependency summary (`blocked_by[]` with per-target satisfied state, and a
@@ -216,16 +217,15 @@ module.exports = function buildTasksRouter() {
     if (claimStaleDays && claimStaleDays.bad) return res.fail('bad_stale_days', { status: 400, message: 'stale_days must be a positive integer number of days.' });
     // ?limit=N — opt-in, for a caller that renders N rows (goal 1000072). It slices the
     // RETURNED feed, never the query — lifecycle/CLAUDE.md has the why.
+    const claimNeeds = parseNeedsFilter(req.query.needs); if (claimNeeds && claimNeeds.bad) return badNeedsFilter(res); // task 1004950
     const claimLimit = posInt(req.query.limit, 'bad_limit', 1000);
     if (claimLimit && claimLimit.bad) return res.fail('bad_limit', { status: 400, message: 'limit must be a positive integer (max 1000).' });
     const [feed, active] = await Promise.all([
       db.listClaimableTasks({
-        versionId: version || null,
-        builderId: req.builder.id,
-        discipline: discipline || null,
-        fit: fit || null,
+        versionId: version || null, builderId: req.builder.id,
+        discipline: discipline || null, fit: fit || null,
         createdBy: claimCreatedBy ?? null,
-        staleDays: claimStaleDays ?? null,
+        staleDays: claimStaleDays ?? null, needs: claimNeeds ?? null,
       }),
       req.query.group === 'goal' ? [] : db.listActiveClaims(),
     ]);
@@ -507,11 +507,11 @@ module.exports = function buildTasksRouter() {
   // the numeric done_when_criteria.id, mirroring DELETE deps/:depId).
   // rank: metic+archon — removes a criterion↔task edge; task-shaping, Metic+ (ADR 0090).
   router.delete('/tasks/:id/criteria/:criterionId', auth.requireBuilder, auth.requirePermission('task.criterion.manage'), async (req, res) => {
-    const id = Number(req.params.id);
-    const criterionId = Number(req.params.criterionId);
-    if (!Number.isFinite(id) || !Number.isFinite(criterionId)) {
-      return res.fail('bad_task_id', 400);
-    }
+    // task 1004984: whole positive ids only (Number.isFinite let 7.5 through).
+    const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
+    if (id === null) return;
+    const criterionId = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id', positiveInt: true });
+    if (criterionId === null) return;
     const removed = await db.removeTaskCriterion(id, criterionId);
     res.json({ ok: true, removed });
   });