@bongos/core 1.23.21 → 1.24.1

package/modules/lifecycle/notes.js

@@ -0,0 +1,219 @@
+// modules/lifecycle/notes.js — notes on a task or goal, grouped by purpose
+// (task 1004745, goal 1000095).
+//
+// A note is a short piece of information that helps scope a task or goal or helps
+// finish it. A long thread of them reads badly, so they are shown GROUPED BY
+// PURPOSE — what is decided, what is still a question, what to read, what is
+// risky — with the newest few open in each group and the rest folded away.
+//
+// THE PURPOSE IS CHOSEN BY THE AUTHOR, AND GUESSED WHEN THEY DO NOT. Guessing by
+// text likeness would need a model call per note and could regroup a reader's page
+// under them; a stored purpose is stable, cheap and the author's own word. The
+// guess (`suggestKind`) is a few plain rules (a link, a question mark, "decided",
+// "risk") used only when no purpose was given, and is stored with
+// kind_source 'auto' so it can be told from a deliberate choice.
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const api = require('../../src/module-api');
+
+const { pool } = api;
+
+const MAX_BODY = 4000;
+
+// The most notes one task or goal carries, so no one can bury a page in them.
+const MAX_NOTES_PER_SUBJECT = 500;
+
+// Display order is the order a person scoping work wants to read: what the work is,
+// what was decided, what is still open, what is risky, how far along it is, what to
+// read, and everything else last.
+const KINDS = Object.freeze([
+  { key: 'scope', label: 'Scope', hint: 'What is in and out' },
+  { key: 'decision', label: 'Decisions', hint: 'What was settled, and why' },
+  { key: 'question', label: 'Open questions', hint: 'What still needs an answer' },
+  { key: 'risk', label: 'Risks', hint: 'What could go wrong' },
+  { key: 'progress', label: 'Progress', hint: 'How far along it is' },
+  { key: 'reference', label: 'Links & reading', hint: 'Where to look' },
+  { key: 'other', label: 'Other', hint: 'Anything else' },
+]);
+const KIND_KEYS = Object.freeze(KINDS.map((k) => k.key));
+
+// How many notes a group shows before folding the rest behind "show more".
+const OPEN_PER_GROUP = 3;
+
+// A purpose from the words, for a note written without one. Order matters: the
+// first rule that matches wins, and 'other' is the honest answer when none does.
+function suggestKind(body) {
+  const t = String(body == null ? '' : body).trim().toLowerCase();
+  if (!t) return 'other';
+  if (/\b(decided|decision|we will|we'll go with|going with|agreed|chose|chosen)\b/.test(t)) return 'decision';
+  if (/\b(risk|danger|could break|might break|breaks|careful|watch out|blocker|blocked)\b/.test(t)) return 'risk';
+  if (t.includes('?') || /^(how|what|why|should|can|could|does|do|is|are|who|when|where)\b/.test(t)) return 'question';
+  if (/\b(in scope|out of scope|scope|must|should include|needs to|acceptance|done when)\b/.test(t)) return 'scope';
+  if (/\b(done|finished|shipped|merged|started|working on|in progress|so far|next step)\b/.test(t)) return 'progress';
+  if (/https?:\/\/|\bsee (the )?(docs?|adr|spec|page|link)\b|\bdocs?\b|\badr\b|\bspec\b/.test(t)) return 'reference';
+  return 'other';
+}
+
+// Which of the two subjects a request names: { taskId } or { goalId }, else null.
+// Exactly one id must be present and a positive integer.
+function subjectOf(src) {
+  const num = (v) => (v == null || v === '' ? null : (Number.isInteger(Number(v)) && Number(v) > 0 ? Number(v) : NaN));
+  const taskId = num(src.task_id);
+  const goalId = num(src.goal_id);
+  if (Number.isNaN(taskId) || Number.isNaN(goalId)) return null;
+  if ((taskId == null) === (goalId == null)) return null;
+  return taskId != null ? { taskId } : { goalId };
+}
+
+// Validate an incoming note; `kind` may be absent (then guessed).
+function validateNote(input) {
+  const errors = [];
+  const body = input && typeof input.body === 'string' ? input.body.trim() : '';
+  if (!body) errors.push({ field: 'body', reason: 'required' });
+  else if (body.length > MAX_BODY) errors.push({ field: 'body', reason: `at most ${MAX_BODY} characters` });
+  const kind = input ? input.kind : undefined;
+  if (kind != null && !KIND_KEYS.includes(kind)) errors.push({ field: 'kind', reason: `pick a group: ${KINDS.map((k) => k.label).join(', ')}` });
+  if (!subjectOf(input || {})) errors.push({ field: 'subject', reason: 'say whether the note is on a task or on a goal, not both' });
+  if (errors.length) return { ok: false, errors };
+  return {
+    ok: true,
+    body,
+    kind: kind == null ? suggestKind(body) : kind,
+    kindSource: kind == null ? 'auto' : 'author',
+  };
+}
+
+// Rows (newest first, or any order) -> the grouped view the page renders. Empty
+// groups are left out; within a group newest comes first; `open` is what shows
+// at once and `folded` is what waits behind "show more".
+function groupNotes(rows, { openPerGroup = OPEN_PER_GROUP } = {}) {
+  const byKind = new Map(KIND_KEYS.map((k) => [k, []]));
+  for (const r of rows || []) {
+    const k = byKind.has(r.kind) ? r.kind : 'other';
+    byKind.get(k).push(r);
+  }
+  const groups = [];
+  for (const meta of KINDS) {
+    const list = byKind.get(meta.key).slice().sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
+    if (!list.length) continue;
+    groups.push({
+      kind: meta.key,
+      label: meta.label,
+      hint: meta.hint,
+      count: list.length,
+      latest_at: list[0].created_at,
+      open: list.slice(0, openPerGroup),
+      folded: list.slice(openPerGroup),
+    });
+  }
+  return groups;
+}
+
+const COLS = 'n.id, n.task_id, n.goal_id, n.author_id, n.body, n.kind, n.kind_source, n.created_at, n.updated_at, '
+  + 'b.github_login AS author_login, b.display_name AS author_name, b.avatar_url AS author_avatar_url';
+
+// Every note on one task or goal, newest first. `subject` is { taskId } or { goalId }.
+async function listNotes(subject, deps = {}) {
+  const db = deps.pool || pool;
+  const col = subject.taskId != null ? 'n.task_id' : 'n.goal_id';
+  const id = subject.taskId != null ? subject.taskId : subject.goalId;
+  const { rows } = await db.query(
+    `SELECT ${COLS} FROM lifecycle_notes n JOIN builders b ON b.id = n.author_id
+      WHERE ${col} = $1 ORDER BY n.created_at DESC, n.id DESC LIMIT $2`,
+    [id, MAX_NOTES_PER_SUBJECT]
+  );
+  return rows;
+}
+
+// How many notes a task or goal already carries (for the per-subject cap).
+async function countNotes(subject, deps = {}) {
+  const db = deps.pool || pool;
+  const col = subject.taskId != null ? 'task_id' : 'goal_id';
+  const id = subject.taskId != null ? subject.taskId : subject.goalId;
+  const { rows } = await db.query(`SELECT count(*)::int AS n FROM lifecycle_notes WHERE ${col} = $1`, [id]);
+  return rows[0].n;
+}
+
+async function addNote({ taskId = null, goalId = null, authorId, body, kind, kindSource }, deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = await db.query(
+    `WITH ins AS (
+       INSERT INTO lifecycle_notes (task_id, goal_id, author_id, body, kind, kind_source)
+       VALUES ($1, $2, $3, $4, $5, $6) RETURNING *
+     )
+     SELECT ${COLS} FROM ins n JOIN builders b ON b.id = n.author_id`,
+    [taskId, goalId, authorId, body, kind, kindSource]
+  );
+  return rows[0];
+}
+
+// Re-file a note under another purpose. Only its author or a Metic+ may (the route
+// decides who; this just writes), and the choice is now the author's.
+async function setKind(id, kind, deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = await db.query(
+    `UPDATE lifecycle_notes SET kind = $2, kind_source = 'author', updated_at = now()
+      WHERE id = $1 RETURNING id, kind, kind_source, author_id`,
+    [id, kind]
+  );
+  return rows[0] || null;
+}
+
+async function getNote(id, deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = await db.query('SELECT id, author_id, kind, task_id, goal_id FROM lifecycle_notes WHERE id = $1', [id]);
+  return rows[0] || null;
+}
+
+async function deleteNote(id, deps = {}) {
+  const db = deps.pool || pool;
+  const { rowCount } = await db.query('DELETE FROM lifecycle_notes WHERE id = $1', [id]);
+  return rowCount > 0;
+}
+
+// May this builder see notes on this task or goal? A private goal's notes (and those of
+// its tasks) are for its members and an Archon only, the same wall the goal's own title
+// and prose sit behind (ADR 0112). Anything else is open to every signed-in builder.
+// A task or goal that does not exist answers false too, so the route gives the same
+// 404 for "missing" and "not yours to see" from ONE read.
+async function canSee(builder, subject, deps = {}) {
+  const db = deps.pool || pool;
+  const { rows } = subject.taskId != null
+    ? await db.query('SELECT g.id AS goal_id, g.visibility FROM tasks t LEFT JOIN goals g ON g.id = t.goal_id WHERE t.id = $1', [subject.taskId])
+    : await db.query('SELECT g.id AS goal_id, g.visibility FROM goals g WHERE g.id = $1', [subject.goalId]);
+  const g = rows[0];
+  if (!g) return false;
+  if (g.visibility !== 'private' || api.rankMeetsThreshold(builder.rank, ['archon'])) return true;
+  const m = await db.query('SELECT 1 FROM goal_members WHERE goal_id = $1 AND builder_id = $2', [g.goal_id, builder.id]);
+  return m.rows.length > 0;
+}
+
+// Who may re-file or delete a note: its author, or a Metic or above. The rank is the live
+// one on the authenticated request (ADR 0016), compared through the kernel's own ladder.
+function canChange(builder, note) {
+  if (String(builder.id) === String(note.author_id)) return true;
+  return api.rankMeetsThreshold(builder.rank, ['metic', 'archon']);
+}
+
+module.exports = {
+  KINDS,
+  MAX_NOTES_PER_SUBJECT,
+  subjectOf,
+  canSee,
+  canChange,
+  countNotes,
+  KIND_KEYS,
+  MAX_BODY,
+  suggestKind,
+  validateNote,
+  groupNotes,
+  listNotes,
+
+  addNote,
+  setKind,
+  getNote,
+  deleteNote,
+};

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;
+};