@bongos/core 1.19.357 → 1.19.359

package/tests/agents_spawn.mjs

@@ -0,0 +1,190 @@
+// tests/agents_spawn.mjs — the spawn seam (task 1002489, goal 1000038).
+//
+// Gates two criteria: agents-spawn-via-grade-port and agents-model-tier-default.
+//
+// Everything is dependency-injected — a fake pool, a fake runner, a fake clock. No
+// database, no subprocess, no model call. What is proven here is the DECISIONS: the
+// tier mapping, the ledger's shape, and the refusals.
+//
+// Run:  node tests/agents_spawn.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { spawnAgent, resolveModel, plannedRow, completedRow } = require('../modules/agents/spawn.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const MODELS = { main: 'opus', subagentDefault: 'opus', subagentRoutine: 'haiku' };
+const DEF = { id: 7, name: 'historian', model_tier: 'default', persona: 'observe and report' };
+
+// A pool that records every statement, so the LEDGER can be asserted on directly.
+function fakePool() {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      if (/^INSERT INTO agents_runs/.test(sql)) return { rows: [{ id: 42 }] };
+      return { rows: [] };
+    },
+    inserted() {
+      const c = calls.find((x) => /^INSERT INTO agents_runs/.test(x.sql));
+      if (!c) return null;
+      const cols = c.sql.match(/\(([^)]+)\) VALUES/)[1].split(',').map((s) => s.trim());
+      return Object.fromEntries(cols.map((k, i) => [k, c.params[i]]));
+    },
+    updated() {
+      const c = calls.find((x) => /^UPDATE agents_runs/.test(x.sql));
+      if (!c) return null;
+      const cols = [...c.sql.matchAll(/(\w+) = \$\d+/g)].map((m) => m[1]).filter((k) => k !== 'updated_at');
+      return Object.fromEntries(cols.map((k, i) => [k, c.params[i + 1]]));
+    },
+  };
+}
+
+// --- THE TIER MAPPING (criterion agents-model-tier-default) -----------------
+
+await test('tier resolves through BRANDING, not a constant in the module', () => {
+  assert.equal(resolveModel('default', MODELS), 'opus');
+  assert.equal(resolveModel('routine', MODELS), 'haiku');
+  // An instance that retunes its tiers must move the agents with it.
+  assert.equal(resolveModel('routine', { subagentDefault: 'sonnet', subagentRoutine: 'sonnet' }), 'sonnet');
+});
+
+await test('an UNKNOWN tier falls back to DEFAULT, never to the cheap tier', () => {
+  // Silently downgrading a malformed definition presents much later as
+  // mysteriously poor agent output — far harder to trace than an unexpected
+  // cost line. Fail toward capability.
+  for (const bad of ['cheap', '', null, undefined, 'ROUTINE']) {
+    assert.equal(resolveModel(bad, MODELS), 'opus', `${bad} must not resolve to the routine tier`);
+  }
+});
+
+await test('a missing branding map yields null rather than inventing a model id', () => {
+  assert.equal(resolveModel('default', {}), null);
+});
+
+// --- THE LEDGER SHAPE -------------------------------------------------------
+
+await test('a no-go is TERMINAL: skipped, no model, no output, no cost', () => {
+  const row = plannedRow({ definition: DEF, gate: { decision: 'no-go', reason: 'autonomy off' }, model: 'opus' });
+  assert.equal(row.gate_decision, 'no-go');
+  assert.equal(row.status, 'skipped', "'pending' would read as a run still in flight");
+  assert.equal(row.model, null, 'nothing ran, so no model was used');
+  assert.equal(row.gate_reason, 'autonomy off');
+});
+
+await test('a go starts PENDING so a crashed spawn is visible as unfinished', () => {
+  const row = plannedRow({ definition: DEF, gate: { decision: 'go' }, model: 'opus' });
+  assert.equal(row.status, 'pending');
+  assert.equal(row.model, 'opus', 'the CONCRETE model, so an old row is never re-read through a new tier map');
+});
+
+await test('the run stays attributable when the definition is gone', () => {
+  const row = plannedRow({ definition: DEF, gate: { decision: 'go' } });
+  assert.equal(row.agent_name, 'historian', 'denormalized name survives ON DELETE SET NULL');
+});
+
+await test('an errored run ALWAYS carries a code — the schema refuses otherwise', () => {
+  const c = completedRow({ ok: false });
+  assert.equal(c.status, 'error');
+  assert.ok(c.error_code, 'never null, even when the thrower named nothing');
+  assert.equal(c.output_ref, null, "a failed run's partial output is not a result");
+});
+
+// --- SPAWNING (criterion agents-spawn-via-grade-port) -----------------------
+
+await test('a go spawns through the injected grade port and completes the row', async () => {
+  const pool = fakePool();
+  let seen = null;
+  const r = await spawnAgent(
+    { definition: DEF, trigger: { type: 'event', ref: 'task.shipped:1' }, gate: { decision: 'go' } },
+    { pool, brandingModels: MODELS, now: (() => { let t = 1000; return () => (t += 250); })(),
+      runSubagentCached: async (a) => { seen = a; return { ok: true, cost_usd: 0.42, output_ref: 'grade:9' }; } },
+  );
+  assert.equal(r.ok, true);
+  assert.equal(r.ran, true);
+  assert.equal(seen.opts.model, 'opus', 'the resolved model reaches the port');
+  assert.equal(pool.updated().status, 'ok');
+  assert.equal(Number(pool.updated().cost_usd), 0.42, 'spend lands in the ledger');
+});
+
+await test('the port receives NO tool or permission knobs — v1 agents are read-only', async () => {
+  // Not policy: grader.js hardcodes `--tools Read`. Anything here that looked
+  // like granting a capability would be a bug, so assert the absence.
+  let seen = null;
+  await spawnAgent({ definition: DEF, gate: { decision: 'go' } }, {
+    pool: fakePool(), brandingModels: MODELS,
+    runSubagentCached: async (a) => { seen = a; return { ok: true }; },
+  });
+  for (const forbidden of ['tools', 'allowedTools', 'permissions', 'permissionMode', 'bypassPermissions']) {
+    assert.ok(!(forbidden in seen.opts), `opts must not carry ${forbidden}`);
+  }
+});
+
+await test('a NO-GO spawns nothing at all', async () => {
+  const pool = fakePool();
+  let ran = false;
+  const r = await spawnAgent({ definition: DEF, gate: { decision: 'no-go', reason: 'capped' } }, {
+    pool, brandingModels: MODELS, runSubagentCached: async () => { ran = true; return { ok: true }; },
+  });
+  assert.equal(ran, false, 'a refusal must not reach the model');
+  assert.equal(r.ran, false);
+  assert.equal(r.skipped, true);
+  assert.equal(pool.updated(), null, 'terminal at insert — nothing to complete');
+  assert.equal(pool.inserted().status, 'skipped');
+});
+
+await test('a refusal is still LEDGERED — an untraced no-go is unexplainable later', async () => {
+  const pool = fakePool();
+  await spawnAgent({ definition: DEF, gate: { decision: 'no-go', reason: 'autonomy gate closed' } },
+    { pool, brandingModels: MODELS });
+  const row = pool.inserted();
+  assert.ok(row, 'the row exists even though nothing ran');
+  assert.equal(row.gate_reason, 'autonomy gate closed', 'and says why');
+});
+
+await test('a missing grade port is a named ledger row, not a crash', async () => {
+  // An instance may run `agents` with `grading` disabled. resolveOptional is what
+  // makes that a refusal instead of a boot-time require failure.
+  const pool = fakePool();
+  const r = await spawnAgent({ definition: DEF, gate: { decision: 'go' } },
+    { pool, brandingModels: MODELS, runSubagentCached: null });
+  assert.equal(r.ok, false);
+  assert.equal(r.error_code, 'grade_port_unavailable');
+  assert.equal(pool.updated().status, 'error');
+  assert.equal(pool.updated().error_code, 'grade_port_unavailable');
+});
+
+await test('a throwing subagent is recorded, and never propagates', async () => {
+  // An event fabric must not be taken down by one agent's bad day.
+  const pool = fakePool();
+  const r = await spawnAgent({ definition: DEF, gate: { decision: 'go' } }, {
+    pool, brandingModels: MODELS,
+    runSubagentCached: async () => { throw Object.assign(new Error('boom'), { code: 'timeout' }); },
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.error_code, 'timeout');
+  assert.equal(pool.updated().status, 'error');
+});
+
+await test('an unledgerable fire does NOT spawn — unaccounted spend is worse', async () => {
+  let ran = false;
+  const r = await spawnAgent({ definition: DEF, gate: { decision: 'go' } }, {
+    pool: { query: async () => { throw new Error('db down'); } },
+    brandingModels: MODELS,
+    runSubagentCached: async () => { ran = true; return { ok: true }; },
+  });
+  assert.equal(ran, false, 'money must never be spent with nowhere to record it');
+  assert.equal(r.error_code, 'ledger_write_failed');
+});
+
+console.log(`\nagents_spawn: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/publish_manifest.mjs

@@ -204,16 +204,14 @@ t('every PROTECTED_GLOB is either topology-excluded or publishable (the methodol
 // Modules deliberately not published, on the record. An entry here is a decision
 // someone made, not a gap someone forgot — and every entry needs the task or idea that
 // records the decision, so this can never become a quiet parking lot.
-const KNOWN_UNPUBLISHED_MODULES = new Map([
-  // Same gap as copy-desk, found by the guard below the moment it was written. LATENT
-  // rather than live only because agents is default:false — the day a released instance
-  // enables it, the loader MODULE_NOT_FOUNDs, which is exactly what the provisioning
-  // (task 2135) and platform-identity (task 1002235) allowlist entries exist to prevent.
-  // Left for goal 1000038 rather than fixed here: deciding what the published core
-  // contains for the agents module is that goal's call, not a drive-by from a copy-desk
-  // task. Filed as idea 1000797 with the one-line fix.
-  ['agents', 'idea 1000797'],
-]);
+// Currently EMPTY, and that is the healthy state — every module on disk is either
+// allowlisted or denied on the record. The one entry it ever held ('agents', idea
+// 1000797) was retired by task 1002489: the copy-desk task that found the gap
+// deliberately left the call to goal 1000038, and task 1002489 IS that goal, so it
+// made it — agents is core-maintained, so it joined PUBLISH_ALLOWLIST rather than a
+// deny list. Keep the map (and the two guards below): the next module added without
+// a publish decision is caught the same way this one was.
+const KNOWN_UNPUBLISHED_MODULES = new Map([]);
 
 t('every module on disk is either publishable or deliberately unpublished (a new module cannot be silently invisible)', () => {
   const modulesDir = path.join(ROOT, 'modules');

package/tests/task_recommendations.mjs

@@ -0,0 +1,297 @@
+// tests/task_recommendations.mjs — passing a task RECOMMENDS it; it never
+// transfers the claim (task 1003173 / C03, goal 1000075; criterion
+// collab-pass-a-task, ADR 0187 §3).
+//
+// The criterion names four testable promises, and this file is organised around
+// them, because each one is a thing the code could plausibly have done instead:
+//   1. a pass creates a recommendation and never a claim;
+//   2. the recipient's claim is their own action;
+//   3. the recommendation and its author are readable afterwards;
+//   4. declining leaves no penalty on either party.
+//
+// Promises 1 and 4 are ABSENCE claims — "this code does not do X" — so they are
+// asserted against the source, which is the only place an absence is visible. A
+// behavioural test can show that a claim was not created on one path; it cannot
+// show that no path creates one.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const recs = require(path.join(ROOT, 'modules', 'lifecycle', 'task-recommendations.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const SRC = read('modules', 'lifecycle', 'task-recommendations.js');
+const ROUTES = read('modules', 'lifecycle', 'routes', 'recommendations.js');
+const SQL = read('modules', 'lifecycle', 'migrations', 'lifecycle_005_task_recommendations.sql');
+
+const SENDER = 7;
+const good = { task_id: 42, recommended_to: 9, reason: 'you shipped the last three hall surfaces' };
+const reasons = (input, sender = SENDER) => recs.validateRecommendation(input, sender).errors.map((e) => e.reason);
+
+// ── PROMISE 1: a pass creates a recommendation and NEVER a claim ────────────
+
+test('THE DECISION: nothing in this surface writes a claim', () => {
+  // The criterion exists because a pass that moved a claim would be a task
+  // quietly changing hands. Asserted as an absence over the whole surface: any
+  // INSERT/UPDATE against claims, from either file, is the thing forbidden.
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    assert.ok(!/\bINSERT\s+INTO\s+claims\b/i.test(src), `${name} must not insert a claim`);
+    assert.ok(!/\bUPDATE\s+claims\b/i.test(src), `${name} must not update a claim`);
+    assert.ok(!/\bDELETE\s+FROM\s+claims\b/i.test(src), `${name} must not delete a claim`);
+  }
+});
+
+test('and it does not reach the claim path indirectly either', () => {
+  // A require of the claim machinery would be the seam the decision refuses,
+  // even if today it went unused.
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    assert.ok(!/require\([^)]*claim/i.test(src), `${name} must not require the claim path`);
+    assert.ok(!/claimTask/.test(src), `${name} must not call claimTask`);
+  }
+});
+
+test('THE UNUSED SEAM: there is no transfer function, and no name promising one', () => {
+  // "Do NOT build a transfer path or a seam for one; the decision was
+  // recommend-only, and an unused seam is a cost." A function called transfer/
+  // reassign/handOff would read to the next author as an intention.
+  const exported = Object.keys(recs);
+  const suspect = exported.filter((k) => /transfer|reassign|handoff|hand_off|takeover/i.test(k));
+  assert.deepEqual(suspect, [], `no transfer-shaped export: ${suspect}`);
+});
+
+test('the schema has NO accepted status — accepting is claiming, which lives elsewhere', () => {
+  // A status saying "accepted" would be a second, weaker record of holding work,
+  // and would make this table look like the place claims come from.
+  assert.match(SQL, /status IN \('open', 'declined', 'withdrawn'\)/);
+  // Comments STRIPPED before asserting: both files DISCUSS why there is no
+  // accepted status, and matching the prose that explains the rule as a
+  // violation of it is the over-broad-source-assertion reflex of learning
+  // 1000196 — the same trap the sibling C01 test documents.
+  const sqlCode = SQL.replace(/^\s*--.*$/gm, '');
+  const routeCode = ROUTES.replace(/^\s*\/\/.*$/gm, '');
+  assert.ok(!/'accepted'/.test(sqlCode), 'no accepted status');
+  assert.ok(!/\baccept\b/i.test(routeCode), 'and no accept route');
+});
+
+test('the schema carries no transfer column', () => {
+  const body = SQL.slice(SQL.indexOf('CREATE TABLE'), SQL.indexOf('\n);'));
+  const columns = body.split('\n')
+    .map((l) => l.replace(/--.*$/, '').trim())
+    .filter((l) => l && !/^(CONSTRAINT|CHECK|\))/.test(l));
+  const suspect = columns.filter((l) => /transferred|claimed_by|assigned_to|accepted/i.test(l));
+  assert.deepEqual(suspect, [], `no transfer-shaped column: ${suspect}`);
+});
+
+// ── PROMISE 2: the recipient's claim is their own action ────────────────────
+
+test('the recipient read reports the TASK STATUS, not a claim grant', () => {
+  // What the recipient gets is enough to judge, and nothing that says they now
+  // hold it. Claimability stays the claim path's answer — duplicating that
+  // judgement here would be a second, staler copy of a rule that has an owner.
+  const fn = SRC.slice(SRC.indexOf('async function listForRecipient'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /t\.status\s+AS task_status/, 'the task\'s own status is reported');
+  assert.ok(!/can_claim|claimable|is_claimable/i.test(body), 'and no claimability verdict is invented');
+});
+
+test('a recommendation to yourself is refused', () => {
+  // Not a recommendation. Checked against the AUTHENTICATED sender, never a
+  // client-supplied id — which is why validateRecommendation takes it as an
+  // argument rather than reading it out of the body.
+  assert.ok(reasons({ ...good, recommended_to: SENDER }).includes('cannot_recommend_to_self'));
+  assert.match(ROUTES, /validateRecommendation\(req\.body, req\.builder\.id\)/,
+    'the sender comes from the session');
+});
+
+test('the not-self rule is in the schema too, so neither guard is the only one', () => {
+  assert.match(SQL, /recommended_by <> recommended_to/);
+});
+
+// ── PROMISE 3: the recommendation and its author are readable afterwards ────
+
+test('THE LEDGER: the reason is required, not optional', () => {
+  // The criterion's own argument: an untraced recommendation is indistinguishable
+  // from a task quietly changing hands. A reason the sender must write is what
+  // makes this a record of a judgement rather than a nudge.
+  for (const v of [undefined, null, '', '   ', '\n\t ']) {
+    assert.ok(reasons({ ...good, reason: v }).includes('required'),
+      `${JSON.stringify(v)} is not a reason`);
+  }
+  assert.deepEqual(reasons(good), [], 'a real reason validates');
+});
+
+test('the reason is enforced in the schema and the route body as well', () => {
+  // Three guards that agree: the CHECK is the authority, the validator names the
+  // field, and the route schema refuses before either runs.
+  assert.match(SQL, /reason\s+text NOT NULL/);
+  assert.match(SQL, /length\(btrim\(reason\)\) > 0/);
+  assert.match(ROUTES, /reason: \{ required: true, type: 'string', minLength: 1/);
+});
+
+test('an over-long reason is refused rather than truncated', () => {
+  assert.ok(reasons({ ...good, reason: 'x'.repeat(recs.MAX_REASON + 1) }).includes('too_long'));
+});
+
+test('the per-task history reads EVERY status, so a declined pass stays on the record', () => {
+  // "Readable afterwards" is the point. A history filtered to open would erase
+  // exactly the case the ledger exists to document.
+  const fn = SRC.slice(SRC.indexOf('async function listForTask'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /WHERE r\.task_id = \$1/);
+  assert.ok(!/status = 'open'/.test(body), 'the per-task history is not filtered to open');
+});
+
+test('the history names the AUTHOR, not just the recommendation', () => {
+  const fn = SRC.slice(SRC.indexOf('async function listForTask'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /sender\.github_login/, 'who recommended it');
+  assert.match(body, /r\.reason/, 'and why');
+});
+
+test("the sender's own list is unfiltered by default", () => {
+  const fn = SRC.slice(SRC.indexOf('async function listFromSender'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /\$2::text IS NULL OR r\.status = \$2/, 'status is an optional narrowing');
+});
+
+// ── PROMISE 4: declining leaves no penalty on either party ──────────────────
+
+test('THE NO-PENALTY RULE: declining touches nothing but its own row', () => {
+  // Asserted as an absence, because that is what "costs nothing" means. If a
+  // penalty ever appears for declining, it did not come from here.
+  const fn = SRC.slice(SRC.indexOf('async function declineRecommendation'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /UPDATE lifecycle_task_recommendations/);
+  assert.ok(!/builders|credits|karma|credit_log|peer_votes/i.test(body),
+    'declining writes nothing about either person');
+});
+
+test('and no penalty machinery is reachable from this surface at all', () => {
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    const code = src.replace(/^\s*\/\/.*$/gm, '');   // comments may DISCUSS karma
+    for (const forbidden of ['karma', 'credit', 'penalt', 'cooldown', 'strike']) {
+      assert.ok(!new RegExp(forbidden, 'i').test(code),
+        `${name} must not reach ${forbidden} machinery`);
+    }
+  }
+});
+
+test('a decline is NOT final — the same task can be recommended again', () => {
+  // A permanent unique key would quietly make declining final, which is a cost.
+  // The uniqueness is partial, on open rows only.
+  assert.match(SQL, /CREATE UNIQUE INDEX[^;]*lifecycle_task_recommendations_open_uniq[^;]*WHERE status = 'open'/s);
+});
+
+test('a duplicate OPEN recommendation is a named conflict, not a 500', () => {
+  // The same judgement repeated. Not something the sender can fix by changing
+  // the body, so it is not a validation error.
+  assert.match(SRC, /ON CONFLICT DO NOTHING/);
+  assert.match(SRC, /reason: 'already_open'/);
+  assert.match(ROUTES, /recommendation_already_open', 409/);
+});
+
+// ── who may settle what ─────────────────────────────────────────────────────
+
+test('the RECIPIENT declines and the SENDER withdraws — each scoped in the WHERE', () => {
+  const dec = SRC.slice(SRC.indexOf('async function declineRecommendation'));
+  assert.match(dec.slice(0, 600), /recommended_to = \$2/, 'ownership is in the WHERE, not in rank');
+  const wd = SRC.slice(SRC.indexOf('async function withdrawRecommendation'));
+  assert.match(wd.slice(0, 600), /recommended_by = \$2/);
+  for (const fn of [dec, wd]) {
+    assert.match(fn.slice(0, 600), /status = 'open'/, 'a settled recommendation cannot be re-settled');
+  }
+});
+
+test('the settle refusal does not let you enumerate ids', () => {
+  // ONE refusal for absent / not-yours / already-settled. Looking the row up to
+  // say which would leak existence — the lesson help-requests learned from its
+  // own grader round (task 1003171).
+  const patch = ROUTES.slice(ROUTES.indexOf("'PATCH /task-recommendations/:id'"));
+  const body = patch.slice(0, patch.indexOf('errorCode'));
+  assert.match(body, /recommendation_not_settleable', 404/);
+  assert.ok(!/getRecommendation|SELECT/i.test(body), 'no lookup before the refusal');
+});
+
+// ── the shape the module contract requires ──────────────────────────────────
+
+test('the table is module-owned and lifecycle-namespaced', () => {
+  // A NEW table the module owns outright, unlike tasks/builders which are core
+  // tables it only references — so fitness check 11 permits it (ADR 0083 §5).
+  assert.match(SQL, /CREATE TABLE IF NOT EXISTS lifecycle_task_recommendations/);
+  assert.ok(!/ALTER TABLE (?!lifecycle_)/.test(SQL), 'it alters no core table');
+});
+
+test('the migration registers itself', () => {
+  assert.match(SQL, /INSERT INTO schema_migrations \(version\) VALUES \('lifecycle_005_task_recommendations'\)/);
+});
+
+test('the route is registered in the module manifest', () => {
+  // A route file nothing mounts is a file, not a surface.
+  const manifest = JSON.parse(read('modules', 'lifecycle', 'module.json'));
+  assert.ok(manifest.contributes.routes.includes('recommendations'));
+});
+
+test('core reaches the count through the PORT, never by importing the module', () => {
+  // ADR 0093: core imports no module. /me needs the count for the needs roster,
+  // so the lifecycle port exposes it the same way it exposes the help-request one.
+  const lifecycle = read('modules', 'lifecycle', 'lifecycle.js');
+  assert.match(lifecycle, /openTaskRecommendationsFor:/);
+  const me = read('src', 'bongos', 'routes', 'me.js');
+  assert.match(me, /lifecycle\.openTaskRecommendationsFor/);
+  assert.ok(!/require\([^)]*task-recommendations/.test(me), 'core does not import the module');
+});
+
+// ── it reaches someone, rather than merely being stored ─────────────────────
+
+const needs = require(path.join(ROOT, 'modules', 'builder-settings', 'builder-needs.js'));
+
+test('a waiting recommendation produces a need, so it is surfaced and not just stored', () => {
+  // C01's grader round established the rule for its sibling: storing is not
+  // reaching. It lands in the needs roster the hall card and the CLI nudge
+  // already render, rather than in a second notification system beside it.
+  const n = needs.taskRecommendationsNeed({ openTaskRecommendations: 2 });
+  assert.ok(n, 'a pending recommendation produces a need');
+  assert.match(n.message, /2 tasks/);
+  assert.ok(n.action && n.action.href, 'and it says where to go');
+});
+
+test('the need says plainly that nothing has been assigned', () => {
+  // Wording that pressured the reader would BE the penalty the decision forbids.
+  const n = needs.taskRecommendationsNeed({ openTaskRecommendations: 1 });
+  assert.match(n.message, /Nothing has been assigned/);
+  assert.match(n.message, /declining costs nothing/);
+  assert.match(n.what, /suggestion, not an assignment/);
+});
+
+test('no recommendations produces NO need, not a cheerful empty state', () => {
+  for (const ctx of [{ openTaskRecommendations: 0 }, {}, { openTaskRecommendations: undefined }]) {
+    assert.equal(needs.taskRecommendationsNeed(ctx), null);
+  }
+});
+
+test('the need is registered, so every renderer picks it up', () => {
+  const roster = needs.computeNeeds({ openTaskRecommendations: 1, ownKeySet: true, rank: 'metic' });
+  assert.ok(roster.items.some((i) => i.id === 'task_recommendations'), 'it is in the roster');
+});
+
+// ── bounds ──────────────────────────────────────────────────────────────────
+
+test('reads are bounded, so an unsettled pile degrades the page and not the server', () => {
+  assert.equal(recs.capRows(0), recs.MAX_ROWS);
+  assert.equal(recs.capRows(-1), recs.MAX_ROWS);
+  assert.equal(recs.capRows(recs.MAX_ROWS + 1), recs.MAX_ROWS);
+  assert.equal(recs.capRows(1.5), recs.MAX_ROWS);
+  assert.equal(recs.capRows(25), 25);
+});
+
+test('task_id and recommended_to are required and must be positive ids', () => {
+  assert.ok(reasons({ reason: 'x' }).includes('required'));
+  assert.ok(reasons({ ...good, task_id: 0 }).includes('bad_task_id'));
+  assert.ok(reasons({ ...good, task_id: 1.5 }).includes('bad_task_id'));
+  assert.ok(reasons({ ...good, recommended_to: -3 }).includes('bad_builder_id'));
+});