@bongos/core 1.19.1059 → 1.19.1060

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

@@ -0,0 +1,184 @@
+// modules/copy-desk/tests/copy_page_next.mjs — the recommendation, pure
+// (task 1004318 / BV2.TW07, ADR 0341 D8).
+//
+// The done-when: the recommendation follows the order on a fixture and skips
+// held pages. The fixture below has a page in every tier and every way a page
+// can be left out:
+//
+//   asked      builders:work (2 askers), landing:privacy (1, the OLDER ask),
+//              builders:tasks (1, the newer ask)
+//   changed    builders:goals (4 lines, alice's pass), status:board (1 line,
+//              bob's pass)
+//   untweaked  landing:index, builders:ideas (an unheld draft, taken over),
+//              status:explore: surface order, though the inventory lists
+//              builders first
+//   tweaked    landing:projects (twice, no drift): last
+//   skipped    builders:studio (held by bob, and asked for), landing:about
+//              (submitted: in flight)
+//
+// "Take next" through the real claim is tests/copy_desk_page_next.mjs (root).
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pages = require('../pages.js');
+const status = require('../page-status.js');
+const F = require('./fixtures/page-tweak.cjs');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+// --- the fixture: F's four pages plus six more -----------------------------
+const page = (id, title) => ({ id, surface: id.split(':')[0], title, path: `/${id.split(':')[1]}`, files: [`${id}.html`] });
+const INVENTORY = {
+  schema: 1,
+  surfaces: F.INVENTORY.surfaces,
+  pages: [
+    ...F.INVENTORY.pages,
+    page('builders:work', 'Work'),
+    page('builders:goals', 'Goals'),
+    page('builders:tasks', 'Tasks'),
+    page('builders:ideas', 'Ideas'),
+    page('landing:privacy', 'Privacy'),
+    page('landing:about', 'About'),
+    page('status:board', 'Board'),
+  ],
+};
+const line = (key, text, placement = 'placed') => ({ key, section: 'body', text, placement });
+const READINGS = {
+  schema: 1,
+  pages: [
+    ...F.READINGS.pages,
+    { id: 'builders:goals', lines: [line('L0001', 'Nav', 'shared'), line('L0002', 'A'), line('L0003', 'W'), line('L0004', 'X'), line('L0005', 'Y'), line('L0006', 'Z')] },
+    { id: 'status:board', lines: [line('L0001', 'One'), line('L0002', 'Two, reworded')] },
+  ],
+};
+const shipped = (id, pageId, n, artist, linesAfter, at) => F.row({
+  id, status: 'shipped', source_ref: pages.roundSourceRef(pageId, n), shipped_at: new Date(at), grade_passed: true,
+  artist_id: artist.id, artist_login: artist.login,
+  description: F.describe({ pageId, submittedAt: at, lines: [{ key: 'L0002', section: 'body', before: 'b', after: 'a' }], appliedAt: at, linesAfter }),
+});
+const TASKS = [
+  ...F.TASKS,
+  shipped('401', 'builders:goals', 1, F.ALICE, ['A', 'B', 'C', 'D', 'E'], '2026-09-10T10:00:00Z'),
+  shipped('402', 'status:board', 1, F.BOB, ['One', 'Two'], '2026-09-11T10:00:00Z'),
+  // An unheld draft: released without submitting. The claim takes it over.
+  F.row({
+    id: '403', status: 'ready', source_ref: pages.roundSourceRef('builders:ideas', 1),
+    description: F.describe({ pageId: 'builders:ideas', submittedAt: '2026-09-20T10:00:00Z', draft: true, lines: [] }),
+  }),
+  // Submitted: a frozen batch, no holder. In flight.
+  F.row({
+    id: '404', status: 'ready', source_ref: pages.roundSourceRef('landing:about', 1),
+    description: F.describe({ pageId: 'landing:about', submittedAt: '2026-09-21T10:00:00Z', lines: [{ key: 'L0002', section: 'body', before: 'x', after: 'y' }] }),
+  }),
+];
+const ASKS = [
+  { page_id: 'builders:work', askers: 2, oldest_ask_at: new Date('2026-09-15T00:00:00Z') },
+  { page_id: 'landing:privacy', askers: 1, oldest_ask_at: new Date('2026-09-01T00:00:00Z') },
+  { page_id: 'builders:tasks', askers: 1, oldest_ask_at: new Date('2026-09-20T00:00:00Z') },
+  { page_id: 'builders:studio', askers: 3, oldest_ask_at: new Date('2026-08-01T00:00:00Z') },
+  { page_id: 'landing:gone', askers: 5, oldest_ask_at: new Date('2026-08-01T00:00:00Z') }, // not in the inventory
+];
+
+const next = (builderId, over = {}) => status.composeNext({ inventory: INVENTORY, readings: READINGS, tasks: TASKS, asks: ASKS, builderId, alternatives: 99, ...over });
+const order = (out) => [out.recommended, ...out.alternatives].filter(Boolean).map((c) => c.page_id);
+
+const EXPECTED = [
+  'builders:work', 'landing:privacy', 'builders:tasks',
+  'builders:goals', 'status:board',
+  'landing:index', 'builders:ideas', 'status:explore',
+  'landing:projects',
+];
+
+await test('the order on the fixture: asked, changed, untweaked (surface order), tweaked last', () => {
+  const out = next(F.ALICE.id);
+  assert.deepEqual(order(out), EXPECTED);
+  assert.deepEqual([...new Set([out.recommended, ...out.alternatives].map((c) => c.tier))], ['asked', 'changed', 'untweaked', 'tweaked']);
+  assert.equal(out.candidates, EXPECTED.length);
+});
+
+await test('held and in-flight pages are never recommended, and are named in skipped', () => {
+  const out = next(F.ALICE.id);
+  assert.ok(!order(out).includes('builders:studio'), 'held by bob, though three people asked for it');
+  assert.ok(!order(out).includes('landing:about'), 'submitted: in flight');
+  assert.deepEqual(out.skipped.map((s) => [s.page_id, s.reason]), [['builders:studio', 'page_held'], ['landing:about', 'page_in_flight']]);
+  assert.deepEqual(out.skipped[0].holder, { id: F.BOB.id, login: 'bob' });
+  assert.equal(out.skipped[1].state, 'submitted');
+  assert.equal(out.resume, null);
+});
+
+await test("the caller's own held page is Resume, not a recommendation", () => {
+  const out = next(F.BOB.id);
+  assert.equal(out.resume.page_id, 'builders:studio');
+  assert.equal(out.resume.task_id, '202');
+  assert.equal(out.resume.take.path, '/copy-desk/pages/builders:studio/claim');
+  assert.ok(!order(out).includes('builders:studio'));
+  assert.ok(!out.skipped.some((s) => s.page_id === 'builders:studio'));
+});
+
+await test("the caller's own CLI claim (applying) is in flight, not Resume", () => {
+  const tasks = TASKS.map((t) => (t.id === '202' ? { ...t, holder_worktree: true } : t));
+  const out = next(F.BOB.id, { tasks });
+  assert.equal(out.resume, null);
+  assert.deepEqual(out.skipped.find((s) => s.page_id === 'builders:studio').reason, 'page_in_flight');
+});
+
+await test('each candidate carries its why, in the mock\'s words', () => {
+  const out = next(F.ALICE.id);
+  const by = (id) => [out.recommended, ...out.alternatives].find((c) => c.page_id === id);
+  assert.equal(out.recommended.why, '2 people asked for it');
+  assert.equal(out.recommended.why_line, 'builders hall · 2 people asked for it · untweaked');
+  assert.equal(by('landing:privacy').why_line, 'landing · 1 person asked for it · untweaked');
+  assert.equal(by('builders:goals').why, '4 lines changed since your last pass', 'alice made the last pass');
+  assert.equal(by('builders:goals').changed_lines, 4, 'shared lines never count');
+  assert.equal(by('status:board').why, '1 line changed since the last pass', 'bob made it, not the caller');
+  assert.equal(by('status:explore').why_line, 'status · untweaked');
+  assert.equal(by('landing:projects').why, 'text tweaked 2x, nothing changed since');
+  assert.equal(by('builders:ideas').draft_round.task_id, '403', 'the draft the claim takes over is named');
+  assert.equal(out.recommended.take.path, '/copy-desk/pages/builders:work/claim');
+});
+
+await test('ties: more askers first, then the oldest ask; more changed lines first', () => {
+  const asks = [
+    { page_id: 'landing:privacy', askers: 1, oldest_ask_at: new Date('2026-09-25T00:00:00Z') },
+    { page_id: 'builders:tasks', askers: 1, oldest_ask_at: new Date('2026-09-02T00:00:00Z') },
+  ];
+  assert.deepEqual(order(next(F.ALICE.id, { asks })).slice(0, 2), ['builders:tasks', 'landing:privacy'], 'oldest ask wins the tie');
+  const more = [{ page_id: 'builders:tasks', askers: 3, oldest_ask_at: new Date('2026-09-26T00:00:00Z') }, ...asks];
+  assert.equal(next(F.ALICE.id, { asks: more }).recommended.page_id, 'builders:tasks');
+});
+
+await test('asked_pages counts every inventory page with an open ask, held ones too', () => {
+  assert.equal(next(F.ALICE.id).asked_pages, 4);
+});
+
+await test('pick another: the next few, four by default', () => {
+  const out = status.composeNext({ inventory: INVENTORY, readings: READINGS, tasks: TASKS, asks: ASKS, builderId: F.ALICE.id });
+  assert.equal(out.alternatives.length, status.NEXT_ALTERNATIVES);
+  assert.equal(status.NEXT_ALTERNATIVES, 4);
+  assert.deepEqual(order(out), EXPECTED.slice(0, 5));
+});
+
+await test('no readings: drift is unknown, so no page is "changed", and tweaked pages sort last', () => {
+  const out = next(F.ALICE.id, { readings: null });
+  assert.ok(![out.recommended, ...out.alternatives].some((c) => c.tier === 'changed'));
+  assert.deepEqual(order(out).slice(-3), ['landing:projects', 'builders:goals', 'status:board']);
+  assert.equal(out.alternatives.find((c) => c.page_id === 'builders:goals').why, 'text tweaked 1x');
+});
+
+await test('nothing left to take: recommended is null, never a held page', () => {
+  const inventory = { ...INVENTORY, pages: INVENTORY.pages.filter((p) => ['builders:studio', 'landing:about'].includes(p.id)) };
+  const out = next(F.ALICE.id, { inventory });
+  assert.equal(out.recommended, null);
+  assert.deepEqual(out.alternatives, []);
+  assert.equal(out.skipped.length, 2);
+});
+
+console.log(`\ncopy_page_next: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1059",
+  "version": "1.19.1060",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1059",
+      "version": "1.19.1060",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1059",
+  "version": "1.19.1060",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -7655,5 +7655,11 @@
       "id": "1004317",
       "text": "An artist can now claim a whole page to rewrite in one step. If the page has no open round, one is created for them. If someone else is already on it, they are told who. Anyone, artist or not, can ask for a page to be worked o"
     }
+  ],
+  "1.19.1060": [
+    {
+      "id": "1004318",
+      "text": "An artist can now ask \"what should I tweak next?\" and get one page back, with the reason in plain words, such as \"2 people asked for it\". Pages people asked for come first, then pages whose words changed since their last tweak"
+    }
   ]
 }

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1059'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1060'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/copy_desk_flags_db.mjs

@@ -285,6 +285,18 @@ await test('resolvePageAsks closes the open asks filed before the ship, stamped
   assert.equal(await flagsLib.countPageAskers(SURF), 0);
 });
 
+// The recommendation's read (task 1004318 / TW07): one grouped row per page
+// with an open ask, distinct askers and the oldest open ask.
+await test('pageAskSummary groups open asks by page: distinct askers, the oldest ask', async () => {
+  assert.equal((await flagsLib.pageAskSummary()).some((r) => r.page_id === SURF), false, 'resolved asks are not counted');
+  const first = (await pageIns({ by: B })).rows[0];
+  await pool.query("UPDATE copy_desk_flags SET flagged_at = now() - interval '2 days' WHERE id = $1", [first.id]);
+  await pageIns({ by: A });
+  const row = (await flagsLib.pageAskSummary()).find((r) => r.page_id === SURF);
+  assert.equal(row.askers, 2);
+  assert.equal(new Date(row.oldest_ask_at).getTime(), new Date((await pool.query('SELECT flagged_at FROM copy_desk_flags WHERE id = $1', [first.id])).rows[0].flagged_at).getTime());
+});
+
 // --- cleanup --------------------------------------------------------------
 await clean();
 await pool.query('DELETE FROM builders WHERE id = ANY($1)', [[A, B]]).catch(() => {});

package/tests/copy_desk_page_claim.mjs

@@ -18,140 +18,25 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { makeRunner } from './helpers.mjs';
+import { installPageLedger } from './fixtures/page-ledger.mjs';
 
 process.env.NODE_ENV = 'test';
 const require = createRequire(import.meta.url);
 const F = require('../modules/copy-desk/tests/fixtures/page-tweak.cjs');
 const api = require('../src/module-api.js');
 
-// --- the ledger -------------------------------------------------------------
-const db = {
-  builders: new Map([
-    ['7', { id: '7', status: 'active', github_login: 'alice', display_name: 'Alice', preferred_disciplines: ['artist'] }],
-    ['8', { id: '8', status: 'active', github_login: 'bob', display_name: 'Bob', preferred_disciplines: ['engineer', 'artist'] }],
-    ['9', { id: '9', status: 'active', github_login: 'carol', display_name: 'Carol', preferred_disciplines: ['engineer'] }],
-  ]),
-  tasks: [],
-  claims: [],
-  flags: [],
-  seq: { task: 5000, claim: 9000, flag: 100 },
-  building: true,
-};
+// --- the ledger: the shared stateful fake (tests/fixtures/page-ledger.mjs) ---
+const { db, seen } = installPageLedger(api, {
+  builders: [
+    { id: '7', github_login: 'alice', display_name: 'Alice', preferred_disciplines: ['artist'] },
+    { id: '8', github_login: 'bob', display_name: 'Bob', preferred_disciplines: ['engineer', 'artist'] },
+    { id: '9', github_login: 'carol', display_name: 'Carol', preferred_disciplines: ['engineer'] },
+  ],
+});
 const ALICE = '7';
 const BOB = '8';
 const CAROL = '9';
 
-// The advisory lock, as a mutex per key: a second locker waits until the first
-// commits or rolls back. That is what makes the race case below a real race.
-const locks = new Map();
-async function lock(key, owner) {
-  while (locks.has(key)) await locks.get(key).done;
-  let release;
-  const done = new Promise((r) => { release = r; });
-  locks.set(key, { owner, done, release });
-}
-function unlockAll(owner) {
-  for (const [k, v] of [...locks]) if (v.owner === owner) { locks.delete(k); v.release(); }
-}
-
-const flat = (sql) => String(sql).replace(/\s+/g, ' ').trim();
-const seen = [];
-let clientSeq = 0;
-
-async function answer(q, p, owner) {
-  seen.push(q);
-  // Yield on every statement, so two concurrent requests really interleave:
-  // without the page lock, both would read "no open round" and both create.
-  await new Promise((r) => setImmediate(r));
-  if (/^(BEGIN|COMMIT|ROLLBACK)$/.test(q)) {
-    if (q !== 'BEGIN') unlockAll(owner);
-    return { rows: [] };
-  }
-  if (/pg_advisory_xact_lock\(hashtext\(\$1\)\)/.test(q)) {
-    assert.ok(owner, 'the page lock must be taken on the transaction client');
-    await lock(p[0], owner);
-    return { rows: [] };
-  }
-  if (/^SELECT id, status, github_login, display_name FROM builders WHERE id = \$1/.test(q)) {
-    const b = db.builders.get(String(p[0]));
-    return { rows: b ? [b] : [] };
-  }
-  if (/^SELECT preferred_disciplines FROM builders WHERE id = \$1/.test(q)) {
-    const b = db.builders.get(String(p[0]));
-    return { rows: b ? [{ preferred_disciplines: b.preferred_disciplines }] : [] };
-  }
-  if (/FROM tasks WHERE source = \$1 AND left\(source_ref, length\(\$2\)\) = \$2 ORDER BY id ASC FOR UPDATE/.test(q)) {
-    return { rows: db.tasks.filter((t) => t.source === p[0] && String(t.source_ref).startsWith(p[1])).map((t) => ({ ...t })) };
-  }
-  if (/FROM claims c JOIN builders b ON b\.id = c\.builder_id WHERE c\.task_id = \$1 AND c\.released_at IS NULL/.test(q)) {
-    const c = db.claims.find((x) => String(x.task_id) === String(p[0]) && x.released_at == null);
-    if (!c) return { rows: [] };
-    const b = db.builders.get(String(c.builder_id));
-    return { rows: [{ ...c, github_login: b.github_login, display_name: b.display_name }] };
-  }
-  if (/^INSERT INTO claims \(task_id, builder_id, worktree_name, requested_worktree_name, head_sha, creator_session_id\) VALUES \(\$1, \$2, NULL, NULL, NULL, NULL\)/.test(q)) {
-    if (db.claims.some((x) => String(x.task_id) === String(p[0]) && x.released_at == null)) {
-      throw Object.assign(new Error('duplicate key'), { code: '23505', constraint: 'uniq_active_claim_per_task' });
-    }
-    const c = { id: String(++db.seq.claim), task_id: String(p[0]), builder_id: String(p[1]), worktree_name: null, creator_session_id: null, claimed_at: new Date().toISOString(), released_at: null };
-    db.claims.push(c);
-    return { rows: [{ ...c }] };
-  }
-  if (/^UPDATE tasks SET status = 'active', updated_at = now\(\) WHERE id = \$1/.test(q)) {
-    db.tasks.find((t) => String(t.id) === String(p[0])).status = 'active';
-    return { rows: [] };
-  }
-  // createTask's reads: the catch-all goal of the version, and its scope.
-  if (/FROM goals g JOIN versions v ON v\.id = g\.version_id WHERE g\.version_id = \$1 AND g\.title = \$2/.test(q)) {
-    return { rows: [{ id: '77', version_status: 'building' }] };
-  }
-  if (/^SELECT scope_modules FROM goals WHERE id = \$1/.test(q)) return { rows: [{ scope_modules: [] }] };
-  if (/^INSERT INTO tasks \(version_id, title, description, status, touches,/.test(q)) {
-    assert.ok(owner, 'the round must be created inside the claim transaction');
-    const t = {
-      id: String(++db.seq.task), version_id: p[0], title: p[1], description: p[2], status: p[3], touches: p[4],
-      credits_reward: p[10], source: p[11], source_ref: p[12], kind: p[14], discipline: p[15], requires_rank: p[20], goal_id: p[22], created_by: p[23],
-    };
-    db.tasks.push(t);
-    return { rows: [{ ...t }] };
-  }
-  if (/^SELECT id, name, status, scope_doc_path, started_at, shipped_at, done_when FROM versions/.test(q)) {
-    return { rows: db.building ? [{ id: 'V9', name: 'V9', status: 'building' }] : [{ id: 'V8', name: 'V8', status: 'shipped' }] };
-  }
-  // The flag SQL (the page ask).
-  if (/FROM copy_desk_flags f WHERE f\.scope = 'page' AND f\.page_id = \$1 AND f\.flagged_by = \$2 AND f\.status = 'open'/.test(q)) {
-    return { rows: db.flags.filter((x) => x.scope === 'page' && x.page_id === p[0] && String(x.flagged_by) === String(p[1]) && x.status === 'open').slice(0, 1) };
-  }
-  if (/^INSERT INTO copy_desk_flags/.test(q)) {
-    const [scope, surface, stringId, reason, kind, , , , , by, pageId] = p;
-    // The CHECKs of copy_desk_002, so the fake refuses what Postgres would.
-    assert.equal((scope === 'page'), (pageId != null), 'copy_desk_flags_target_chk');
-    if (scope === 'page') assert.equal(surface, pageId, 'copy_desk_flags_page_surface_chk');
-    const dup = db.flags.find((x) => x.status === 'open' && String(x.flagged_by) === String(by) && x.surface === surface && (x.string_id || '') === (stringId || ''));
-    if (dup) throw Object.assign(new Error('dup'), { code: '23505' });
-    const row = { id: String(++db.seq.flag), scope, surface, string_id: stringId, page_id: pageId, reason, kind, flagged_by: String(by), flagged_at: new Date().toISOString(), status: 'open' };
-    db.flags.push(row);
-    return { rows: [{ ...row }] };
-  }
-  if (/COUNT\(DISTINCT flagged_by\)::int AS askers FROM copy_desk_flags WHERE scope = 'page' AND page_id = \$1 AND status = 'open'/.test(q)) {
-    return { rows: [{ askers: new Set(db.flags.filter((x) => x.scope === 'page' && x.page_id === p[0] && x.status === 'open').map((x) => x.flagged_by)).size }] };
-  }
-  if (/^UPDATE copy_desk_flags SET status = 'resolved', resolved_task_id = \$2, resolved_by = \$3/.test(q)) {
-    const hit = db.flags.filter((x) => x.scope === 'page' && x.page_id === p[0] && x.status === 'open' && new Date(x.flagged_at) <= new Date(p[3]));
-    for (const x of hit) Object.assign(x, { status: 'resolved', resolved_task_id: String(p[1]), resolved_by: String(p[2]), resolution_note: p[4] });
-    return { rows: hit.map((x) => ({ id: x.id })) };
-  }
-  throw new Error(`unexpected SQL: ${q.slice(0, 160)}`);
-}
-
-api.pool = {
-  query: (sql, params = []) => answer(flat(sql), params, null),
-  async connect() {
-    const owner = ++clientSeq;
-    return { query: (sql, params = []) => answer(flat(sql), params, owner), release() { unlockAll(owner); } };
-  },
-};
-
 api.requireBuilder = (req, res, next) => {
   req.builder = { id: String(req.headers['x-builder'] || ALICE), rank: 'metic' };
   next();

package/tests/copy_desk_page_next.mjs

@@ -0,0 +1,172 @@
+// tests/copy_desk_page_next.mjs — "recommend the next page" and "take next",
+// the WHOLE path (task 1004318 / BV2.TW07, ADR 0341 D5, D8, D11).
+//
+// The done-when: the recommendation follows the order on a fixture, skips held
+// pages, and "take next" claims the recommended page in one call.
+//
+// modules/copy-desk/tests/copy_page_next.mjs proves the order on hand-shaped
+// rows. This drives the path those rows travel: GET /copy-desk/next through
+// the real route, the real lifecycle read (listPageTweakTasks) and the real
+// page-ask summary SQL, then POST the recommendation's own `take` path through
+// the real page claim (webClaimPageTweak, createTask), all against one stateful
+// fake ledger (tests/fixtures/page-ledger.mjs). So a claim made by "take next"
+// is what the next read sees, with no hand-built rows in between.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { makeRunner } from './helpers.mjs';
+import { installPageLedger } from './fixtures/page-ledger.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const F = require('../modules/copy-desk/tests/fixtures/page-tweak.cjs');
+const pages = require('../modules/copy-desk/pages.js');
+const api = require('../src/module-api.js');
+
+const { db } = installPageLedger(api, {
+  builders: [
+    { id: '7', github_login: 'alice', display_name: 'Alice', preferred_disciplines: ['artist'] },
+    { id: '8', github_login: 'bob', display_name: 'Bob', preferred_disciplines: ['artist'] },
+    { id: '9', github_login: 'carol', display_name: 'Carol', preferred_disciplines: ['engineer'] },
+  ],
+});
+const ALICE = '7';
+const BOB = '8';
+const CAROL = '9';
+
+api.requireBuilder = (req, res, next) => {
+  req.builder = { id: String(req.headers['x-builder'] || ALICE), rank: 'thetes' };
+  next();
+};
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('lifecycle')) seams.registerProvider('lifecycle', require('../modules/lifecycle/lifecycle.js'));
+
+const pageData = require('../modules/copy-desk/page-data.js');
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRouter = require('../modules/copy-desk/routes/copy-desk.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use(buildRouter());
+const server = await new Promise((resolve) => { const s = app.listen(0, '127.0.0.1', () => resolve(s)); });
+const base = `http://127.0.0.1:${server.address().port}`;
+
+async function call(method, p, builder, body) {
+  const r = await fetch(base + p, {
+    method, headers: { 'content-type': 'application/json', 'x-builder': builder },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+  return { status: r.status, body: await r.json() };
+}
+const getNext = (builder) => call('GET', '/copy-desk/next', builder);
+const errCode = (b) => (b && b.error && b.error.code) || null;
+const order = (b) => [b.recommended, ...b.alternatives].filter(Boolean).map((c) => c.page_id);
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'page-next-'));
+fs.mkdirSync(path.join(tmp, 'docs'), { recursive: true });
+fs.writeFileSync(path.join(tmp, 'docs/page-inventory.json'), JSON.stringify(F.INVENTORY));
+fs.writeFileSync(path.join(tmp, 'docs/page-readings.json'), JSON.stringify(F.READINGS));
+
+// The world before anyone asks: builders:studio was tweaked once by alice
+// (her web claim, released at submit), and has drifted since ("Welcome home"
+// became "Welcome back"). Every other page is untweaked.
+db.tasks.push({
+  id: '4001', status: 'shipped', title: 'Tweak: Studio (builders:studio)', source: 'page-tweak',
+  source_ref: pages.roundSourceRef('builders:studio', 1), touches: F.STUDIO_FILES,
+  shipped_at: '2026-09-20T10:00:00.000Z',
+  description: F.describe({
+    pageId: 'builders:studio', submittedAt: '2026-09-19T10:00:00Z',
+    lines: [{ key: 'L0002', section: 'greeting', before: 'Welcome', after: 'Welcome home' }],
+    appliedAt: '2026-09-19T18:00:00Z', linesAfter: ['Welcome home', 'Resume'],
+  }),
+});
+db.claims.push({ id: '8001', task_id: '4001', builder_id: ALICE, worktree_name: null, creator_session_id: null, claimed_at: '2026-09-18T10:00:00.000Z', released_at: '2026-09-19T10:00:00.000Z' });
+db.grades.set('4001', true);
+
+const { test, summary } = makeRunner();
+
+try {
+  pageData._setRoot(tmp);
+
+  await test('anyone asks; the recommendation reads asked, then changed, then untweaked', async () => {
+    assert.equal((await call('POST', '/copy-desk/pages/landing:projects/asks', CAROL, { reason: 'The project cards all read the same.' })).status, 201);
+    assert.equal((await call('POST', '/copy-desk/pages/landing:projects/asks', BOB, { reason: 'Agreed, the cards need a line each.' })).status, 201);
+    assert.equal((await call('POST', '/copy-desk/pages/status:explore/asks', CAROL, { reason: 'Explore does not say what it shows.' })).status, 201);
+
+    const { status, body } = await getNext(ALICE);
+    assert.equal(status, 200, JSON.stringify(body));
+    assert.deepEqual(order(body), ['landing:projects', 'status:explore', 'builders:studio', 'landing:index']);
+    assert.equal(body.recommended.why, '2 people asked for it');
+    assert.equal(body.recommended.why_line, 'landing · 2 people asked for it · untweaked');
+    assert.equal(body.alternatives[1].why, '1 line changed since your last pass', 'the round artist is the web claim, alice');
+    assert.equal(body.asked_pages, 2);
+    assert.equal(body.resume, null);
+    assert.deepEqual(body.skipped, []);
+    assert.equal(body.readings.ok, true);
+  });
+
+  await test('"take next" claims the recommended page in one call', async () => {
+    const { body: next } = await getNext(ALICE);
+    const before = db.tasks.length;
+    const take = await call(next.recommended.take.method, next.recommended.take.path, ALICE, {});
+    assert.equal(take.status, 201, JSON.stringify(take.body));
+    assert.equal(take.body.outcome, 'created');
+    assert.equal(take.body.page_id, next.recommended.page_id);
+    assert.equal(take.body.round.source_ref, 'page-tweak/landing:projects/r1');
+    assert.equal(db.tasks.length, before + 1);
+    const claim = db.claims.find((c) => c.task_id === take.body.round.task_id && c.released_at == null);
+    assert.deepEqual([claim.builder_id, claim.worktree_name, claim.creator_session_id], [ALICE, null, null], 'a web claim');
+  });
+
+  await test('the held page is Resume for its holder, and skipped (holder named) for everyone else', async () => {
+    const mine = (await getNext(ALICE)).body;
+    assert.equal(mine.resume.page_id, 'landing:projects');
+    assert.ok(!order(mine).includes('landing:projects'));
+    assert.equal(mine.recommended.page_id, 'status:explore');
+
+    const bobs = (await getNext(BOB)).body;
+    assert.equal(bobs.resume, null);
+    assert.ok(!order(bobs).includes('landing:projects'), 'never a page someone else holds, however many asked');
+    assert.deepEqual(bobs.skipped, [{ page_id: 'landing:projects', reason: 'page_held', state: 'writing', holder: { id: ALICE, login: 'alice' } }]);
+    assert.equal(bobs.recommended.page_id, 'status:explore');
+    assert.equal(bobs.alternatives[0].why, '1 line changed since the last pass', 'bob did not make that pass');
+  });
+
+  await test('take next for a second artist gets the next page, not the held one', async () => {
+    const { body: next } = await getNext(BOB);
+    const take = await call('POST', next.recommended.take.path, BOB, {});
+    assert.equal(take.status, 201, JSON.stringify(take.body));
+    assert.equal(take.body.page_id, 'status:explore');
+    const after = (await getNext(CAROL)).body;
+    assert.deepEqual(after.skipped.map((s) => s.page_id).sort(), ['landing:projects', 'status:explore']);
+    assert.deepEqual(order(after), ['builders:studio', 'landing:index']);
+  });
+
+  await test('a submitted round is in flight: skipped, and the claim agrees', async () => {
+    const round = db.tasks.find((t) => t.source_ref === 'page-tweak/status:explore/r1');
+    db.claims.find((c) => c.task_id === round.id && c.released_at == null).released_at = new Date().toISOString();
+    round.status = 'ready';
+    round.description += '\n\n' + pages.composeBatchBlock({ page_id: 'status:explore', reading_hash: 'h', submitted_at: 'x', lines: [{ key: 'L0001', section: 'hero', before: 'Explore', after: 'Look around', placement: 'placed', file: 'x', line: 1, string_id: 'a' }] });
+    const next = (await getNext(ALICE)).body;
+    assert.deepEqual(next.skipped, [{ page_id: 'status:explore', reason: 'page_in_flight', state: 'submitted' }]);
+    const refused = await call('POST', '/copy-desk/pages/status:explore/claim', ALICE, {});
+    assert.equal(errCode(refused.body), 'page_in_flight');
+  });
+
+  await test('no page inventory: a named 503, never a crash', async () => {
+    pageData._setRoot(fs.mkdtempSync(path.join(os.tmpdir(), 'page-next-empty-')));
+    const r = await getNext(ALICE);
+    assert.equal(r.status, 503);
+    assert.equal(errCode(r.body), 'page_inventory_missing');
+  });
+} finally {
+  server.close();
+  pageData._setRoot(null);
+}
+summary();