@bongos/core 1.19.1063 → 1.19.1065

package/tests/hall_approval_queue.mjs

@@ -0,0 +1,327 @@
+// tests/hall_approval_queue.mjs — the Approval queue panel (task 1004323 /
+// BV2.TW12, ADR 0341 D7; docs/design/mocks/tweak-mode/Main.dc.html).
+//
+// Boots the REAL panel: approval-queue-lib.js and approval-queue.js in a vm
+// over a mini-DOM, against a stub client. What the client answers for the
+// queue is built by the REAL composer (page-status.js composeApprovals) over
+// round descriptions the REAL pages.js wrote, so the panel is tested on the
+// route's own shape, never a hand-written literal of it.
+//
+// The done-when, as far as a panel can prove it: open the queue from the studio
+// (1 of 2), flip before and after over the applied page's renders, approve and
+// ship (the page's next status and the next page named), send one back with a
+// note, with no terminal.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { makeRunner, makeEl, walk, settle } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PUB = path.join(ROOT, 'modules/hall-ui/public');
+const read = (f) => fs.readFileSync(path.join(PUB, f), 'utf8');
+const lib = require('../modules/hall-ui/public/approval-queue-lib.js');
+const pages = require('../modules/copy-desk/pages.js');
+const pageStatus = require('../modules/copy-desk/page-status.js');
+
+const { test, summary } = makeRunner();
+
+// ── the queue, through the real composer ───────────────────────────────────
+const INVENTORY = {
+  pages: [
+    { id: 'landing:index', surface: 'landing', title: '{{productName}}: {{tagline}}', path: '/' },
+    { id: 'landing:projects', surface: 'landing', title: 'Projects', path: '/projects' },
+  ],
+};
+const ME = '7';
+function round({ id, pageId, n, lines, refused = [], appliedAt, artist = ME }) {
+  const description = [
+    `Page tweak round ${n}.`,
+    pages.composeBatchBlock({ page_id: pageId, reading_hash: 'h', submitted_at: '2026-09-19T00:00:00Z', lines: lines.map((l) => ({ ...l, placement: 'placed', file: 'x.html', line: 1, string_id: 'a' })) }),
+    pages.composeAppliedBlock({ page_id: pageId, applied_at: appliedAt, reading_hash_after: 'h2', lines_after: lines.map((l) => l.after), refused }),
+  ].join('\n\n');
+  return { id, status: 'completed', grade_passed: true, description, source_ref: pages.roundSourceRef(pageId, n), holder_id: null, artist_id: artist, artist_login: 'me' };
+}
+const TASKS = [
+  { id: 40, status: 'shipped', description: '', source_ref: pages.roundSourceRef('landing:index', 1), shipped_at: '2026-09-01T00:00:00Z' },
+  round({
+    id: 41, pageId: 'landing:index', n: 2, appliedAt: '2026-09-21T00:00:00Z',
+    lines: [
+      { key: 'L0003', section: 'hero', before: 'AI agents claim tasks and ship the code.', after: 'Agents write the code.' },
+      { key: 'L0004', section: 'hero', before: '<img src=x onerror="window.pwned=1">', after: 'safe' },
+    ],
+    refused: [{ key: 'L0004', code: 'target_gone' }],
+  }),
+  round({ id: 42, pageId: 'landing:projects', n: 1, appliedAt: '2026-09-22T00:00:00Z', lines: [{ key: 'L0002', section: 'list', before: 'Every project', after: 'All the projects' }] }),
+];
+const queueFor = ({ crafts = ['artist'], tasks = TASKS } = {}) => ({ ok: true, ...pageStatus.composeApprovals({ inventory: INVENTORY, tasks, builderId: ME, crafts }) });
+const url = (task, slot) => `/api/bongos/task-visuals/task-${task}-${String(slot.length).padStart(2, '0')}${'ab'.repeat(7)}.jpg`;
+const slotsFor = (task, only = lib.PHASES.flatMap((p) => lib.DEVICES.flatMap((d) => lib.MODES.map((m) => lib.slotName(p, d, m))))) =>
+  ({ ok: true, task_id: String(task), slots: only.map((slot) => ({ slot, visual_url: url(task, slot), visual_alt: slot })) });
+
+// vm-born objects fail a strict deepEqual on their prototype, so what the panel
+// sent is compared through JSON.
+// ── the mini-DOM ────────────────────────────────────────────────────────────
+function augment(el) {
+  if (el._aug) return el;
+  el._aug = true;
+  Object.defineProperty(el, 'hidden', { get() { return 'hidden' in el.attrs; }, set(v) { if (v) el.attrs.hidden = ''; else delete el.attrs.hidden; }, configurable: true });
+  el.focus = () => { boot.focused = el; };
+  return el;
+}
+let boot = null;
+
+function bootPanel({ answers = {}, writes = null, mode = 'light' } = {}) {
+  const body = augment(makeEl('body', {}));
+  const classes = new Set();
+  const requests = [];
+  const counts = [];
+  const byId = (id) => walk(body, (c) => (c.id === id ? c : null));
+  const documentObj = {
+    body,
+    documentElement: {
+      getAttribute: (k) => (k === 'data-theme' ? mode : null),
+      classList: { add: (c) => classes.add(c), remove: (c) => classes.delete(c), contains: (c) => classes.has(c) },
+    },
+    getElementById: byId,
+    createElement: (tag) => augment(makeEl(tag, {})),
+    get activeElement() { return boot.focused || null; },
+  };
+  const api = {
+    async request(method, u, reqBody) {
+      requests.push({ method, url: u, body: reqBody });
+      const key = `${method} ${u}`;
+      const hit = answers[key];
+      const val = typeof hit === 'function' ? hit(reqBody) : hit;
+      if (val === undefined) return { ok: false, status: 404, data: { error: { code: 'no_answer', message: key } } };
+      return val.__status ? { ok: false, status: val.__status, data: val.data } : { ok: true, status: 200, data: val };
+    },
+  };
+  const win = { matchMedia: () => ({ matches: false }) };
+  const ctx = vm.createContext({ window: win, document: documentObj, console, setTimeout, clearTimeout, encodeURIComponent });
+  win.window = win;
+  vm.runInContext(read('approval-queue-lib.js'), ctx, { filename: 'approval-queue-lib.js' });
+  vm.runInContext(read('approval-queue.js'), ctx, { filename: 'approval-queue.js' });
+  const panel = win.OTBApprovalQueue.mount({
+    api,
+    apiBase: '/api/bongos',
+    writes: writes || {
+      approve: (p) => `/api/bongos/copy-desk/pages/${p}/approve`,
+      sendBack: (p) => `/api/bongos/copy-desk/pages/${p}/send-back`,
+    },
+    onCount: (n) => counts.push(n),
+  });
+  const scrim = body.children[0];
+  const q = (sel) => scrim.querySelector(sel);
+  const qa = (sel) => scrim.querySelectorAll(sel);
+  const click = async (el) => { assert.ok(el, 'the control exists'); scrim.fire('click', { target: el }); await settle(); await settle(); };
+  boot = { body, scrim, q, qa, click, requests, counts, panel, classes, win, focused: null };
+  return boot;
+}
+
+const APPROVALS = 'GET /api/bongos/copy-desk/approvals';
+const vis = (id) => `GET /api/bongos/tasks/${id}/visuals`;
+const text = (el) => (el ? el.textContent.replace(/\s+/g, ' ').trim() : null);
+
+// ── the pure rules: every word the panel says ──────────────────────────────
+
+await test('lib: the artboard\'s words, from the route\'s own shape', () => {
+  const [home, projects] = queueFor().queue;
+  assert.equal(lib.eyebrow(home), 'approval queue · 1 of 2');
+  assert.equal(lib.eyebrow(projects), 'approval queue · 2 of 2');
+  assert.equal(lib.displayTitle(home), 'Home', 'an apex template title is Home, the artboard\'s own word');
+  assert.equal(lib.subLine(home), '· landing · 1 line rewritten, applied · 1 not applied');
+  assert.equal(lib.subLine(projects), '· landing · 1 line rewritten, applied');
+  assert.equal(lib.doorDetail(2), '2 pages applied, waiting for you');
+  assert.equal(lib.doorDetail(1), '1 page applied, waiting for you');
+  assert.equal(lib.doorDetail(0), 'nothing waiting for you');
+  assert.equal(lib.approvedLine(home, { status_after: 'Text tweaked 3x', next: { page: { title: 'Contact' } } }),
+    'Approved. It ships now, and Home reads text tweaked 3x. Next in the queue: Contact.', 'the artboard line, word for word');
+  assert.equal(lib.approvedLine(home, { status_after: 'Text tweaked 2x', next: { page: null } }), 'Approved. It ships now, and Home reads text tweaked 2x. Nothing else is waiting.');
+  assert.equal(lib.sentBackLine(), 'Sent back with your note. It comes back to the queue once it is re-applied.');
+  assert.equal(lib.noteProblem('too long'), 'Say what needs changing in at least 10 characters.');
+  assert.equal(lib.noteProblem('The hero line is too long on a phone.'), null);
+});
+
+await test('lib: renders are picked by view, fall back to the nearest, and only server-minted URLs are kept', () => {
+  const idx = lib.renderIndex([
+    { slot: 'after-desktop-dark', visual_url: url(41, 'after-desktop-dark') },
+    { slot: 'after-phone-light', visual_url: url(41, 'after-phone-light') },
+    { slot: 'before-desktop-light', visual_url: 'https://evil.example/x.jpg' },
+    { slot: 'not-a-render', visual_url: url(41, 'not-a-render') },
+  ]);
+  assert.deepEqual(Object.keys(idx).sort(), ['after-desktop-dark', 'after-phone-light'], 'a foreign URL and an unknown slot are dropped');
+  const light = lib.pickRender(idx, { phase: 'after', device: 'desktop', mode: 'light' });
+  assert.equal(light.slot, 'after-desktop-dark');
+  assert.equal(light.exact, false, 'the other colour mode first, and it says so');
+  assert.equal(lib.pickRender(idx, { phase: 'after', device: 'phone', mode: 'light' }).exact, true);
+  assert.equal(lib.pickRender(idx, { phase: 'before', device: 'desktop', mode: 'light' }), null);
+});
+
+await test('lib: a changed line is marked after, and plain before; a refused line says why', () => {
+  const [home] = queueFor().queue;
+  const [ok, refused] = home.lines;
+  assert.deepEqual(lib.lineRow(ok, 'after'), { key: 'L0003', section: 'hero', text: 'Agents write the code.', marked: true, aside: 'was: AI agents claim tasks and ship the code.', refused: false });
+  assert.deepEqual(lib.lineRow(ok, 'before'), { key: 'L0003', section: 'hero', text: 'AI agents claim tasks and ship the code.', marked: false, aside: 'becomes: Agents write the code.', refused: false });
+  const r = lib.lineRow(refused, 'after');
+  assert.equal(r.marked, false, 'a refused line never looks applied');
+  assert.equal(r.aside, 'not applied: the page no longer shows it');
+});
+
+// ── the panel ───────────────────────────────────────────────────────────────
+
+await test('open: the queue\'s head, the applied page\'s render, and the words beside it', async () => {
+  const b = bootPanel({ answers: { [APPROVALS]: queueFor(), [vis(41)]: slotsFor(41) } });
+  assert.equal(b.scrim.hidden, true, 'closed until opened');
+  await b.panel.open();
+  await settle(); await settle();
+  assert.equal(b.scrim.hidden, false);
+  assert.ok(b.classes.has('aq-open'), 'the page behind stops scrolling');
+  assert.equal(text(b.q('.aq-eyebrow')), 'approval queue · 1 of 2');
+  assert.equal(text(b.q('.aq-title')), 'Home · landing · 1 line rewritten, applied · 1 not applied');
+  const img = b.q('img');
+  assert.equal(img.attrs.src, url(41, 'after-desktop-light'), 'the AFTER render, desktop, in the hall\'s own mode');
+  assert.equal(img.attrs.alt, 'Home, after, desktop, light');
+  assert.deepEqual(b.qa('[data-phase]').map((x) => [text(x), x.attrs['aria-pressed']]), [['before', 'false'], ['after', 'true']]);
+  assert.equal(b.qa('mark').length, 1, 'one applied line carries the mark');
+  assert.equal(text(b.q('mark')), 'Agents write the code.');
+  assert.match(text(b.q('.aq-line--refused')), /not applied: the page no longer shows it/);
+  assert.equal(b.body.querySelectorAll('img').length, 1, 'a hostile line is text, never markup');
+  assert.equal(b.win.pwned, undefined);
+  assert.equal(text(b.q('.aq-hint')), 'highlighted: the words you changed');
+  assert.deepEqual(b.counts, [2], 'the door hears how many wait');
+  assert.ok(!b.requests.some((r) => r.method !== 'GET'), 'opening writes nothing');
+});
+
+await test('the switches: before and after, desktop and phone, light and dark, each a render of the applied branch', async () => {
+  const b = bootPanel({ answers: { [APPROVALS]: queueFor(), [vis(41)]: slotsFor(41) } });
+  await b.panel.open(); await settle(); await settle();
+  await b.click(b.q('[data-phase="before"]'));
+  assert.equal(b.q('img').attrs.src, url(41, 'before-desktop-light'));
+  assert.equal(b.qa('mark').length, 0, 'before is the page as it was: nothing marked');
+  await b.click(b.q('[data-device="phone"]'));
+  assert.equal(b.q('img').attrs.src, url(41, 'before-phone-light'));
+  assert.match(b.q('img').attrs.class, /aq-render--phone/);
+  await b.click(b.q('[data-mode="dark"]'));
+  assert.equal(b.q('img').attrs.src, url(41, 'before-phone-dark'));
+  assert.equal(b.requests.filter((r) => r.url.endsWith('/visuals')).length, 1, 'the renders are read once per round');
+});
+
+await test('a missing render says what it shows instead; no renders at all means nothing to approve from', async () => {
+  const b = bootPanel({ answers: { [APPROVALS]: queueFor(), [vis(41)]: slotsFor(41, ['after-desktop-dark']) } });
+  await b.panel.open(); await settle(); await settle();
+  assert.equal(b.q('img').attrs.src, url(41, 'after-desktop-dark'));
+  assert.equal(text(b.q('.aq-frame__swap')), 'No desktop light render; showing desktop dark.');
+  const none = bootPanel({ answers: { [APPROVALS]: queueFor(), [vis(41)]: slotsFor(41, []) } });
+  await none.panel.open(); await settle(); await settle();
+  assert.equal(none.q('img'), null);
+  assert.match(text(none.q('.aq-frame__note')), /No render is attached/);
+  assert.ok(none.q('[data-approve]').disabled, 'approve waits for a picture of the page');
+  assert.ok(!none.q('[data-open-note]').disabled, 'sending it back does not');
+});
+
+await test('approve and ship: one POST through the host\'s write, then the artboard\'s line and the next page', async () => {
+  const b = bootPanel({
+    answers: {
+      [APPROVALS]: queueFor(),
+      [vis(41)]: slotsFor(41),
+      'POST /api/bongos/copy-desk/pages/landing:index/approve': { ok: true, outcome: 'approved', status_after: 'Text tweaked 2x', next: { count: 1, page: { page_id: 'landing:projects', title: 'Projects', path: '/projects' } } },
+    },
+  });
+  await b.panel.open(); await settle(); await settle();
+  await b.click(b.q('[data-approve]'));
+  const posts = JSON.parse(JSON.stringify(b.requests.filter((r) => r.method === 'POST')));
+  assert.deepEqual(posts, [{ method: 'POST', url: '/api/bongos/copy-desk/pages/landing:index/approve', body: { task_id: '41' } }], 'the round the artist looked at is pinned');
+  assert.equal(text(b.q('.aq-outcome')), 'Approved. It ships now, and Home reads text tweaked 2x. Next in the queue: Projects.');
+  assert.equal(b.q('[data-approve]'), null, 'decided: the buttons are gone');
+  assert.deepEqual(b.counts, [2, 1]);
+  await b.click(b.q('[data-next]'));
+  assert.equal(text(b.q('.aq-eyebrow')), 'approval queue · 2 of 2');
+  assert.equal(text(b.q('.aq-title')).startsWith('Projects'), true);
+});
+
+await test('send it back: the note opens in place, a short one is refused here, a real one is sent', async () => {
+  const b = bootPanel({
+    answers: {
+      [APPROVALS]: queueFor(),
+      [vis(41)]: slotsFor(41),
+      'POST /api/bongos/copy-desk/pages/landing:index/send-back': (body) => ({ ok: true, outcome: 'sent_back', sent_back: { note: body.note }, next: { count: 1, page: null } }),
+    },
+  });
+  await b.panel.open(); await settle(); await settle();
+  await b.click(b.q('[data-open-note]'));
+  const input = b.q('#aq-note');
+  assert.ok(input, 'the note field opens');
+  assert.equal(input.attrs.placeholder, 'The hero line is too long on a phone.');
+  assert.equal(b.q('[data-open-note]'), null, 'send it back gives way to the note and send');
+  input.value = 'too long';
+  await b.click(b.q('[data-send]'));
+  assert.equal(b.requests.filter((r) => r.method === 'POST').length, 0, 'a short note never leaves the panel');
+  assert.equal(text(b.q('.aq-error')), 'Say what needs changing in at least 10 characters.');
+  b.q('#aq-note').value = '  The hero line is   too long on a phone. ';
+  await b.click(b.q('[data-send]'));
+  const posts = JSON.parse(JSON.stringify(b.requests.filter((r) => r.method === 'POST')));
+  assert.deepEqual(posts.map((p) => [p.url, p.body]), [['/api/bongos/copy-desk/pages/landing:index/send-back', { task_id: '41', note: 'The hero line is too long on a phone.' }]]);
+  assert.equal(text(b.q('.aq-outcome')), 'Sent back with your note. It comes back to the queue once it is re-applied.');
+});
+
+await test('a refusal is the server\'s words, and nothing is marked decided', async () => {
+  const b = bootPanel({
+    answers: {
+      [APPROVALS]: queueFor(),
+      [vis(41)]: slotsFor(41),
+      'POST /api/bongos/copy-desk/pages/landing:index/approve': { __status: 409, data: { error: { code: 'round_moved', details: { what_this_means: 'The page waiting now is a different round.' } } } },
+    },
+  });
+  await b.panel.open(); await settle(); await settle();
+  await b.click(b.q('[data-approve]'));
+  assert.equal(text(b.q('.aq-error')), 'The page waiting now is a different round.');
+  assert.ok(b.q('[data-approve]'), 'still deciding');
+  assert.deepEqual(b.counts, [2]);
+});
+
+await test('a builder who may not decide reads the queue with a sentence, not two dead buttons', async () => {
+  const b = bootPanel({ answers: { [APPROVALS]: queueFor({ crafts: ['engineer'], tasks: TASKS.map((t) => ({ ...t, artist_id: '99' })) }), [vis(41)]: slotsFor(41) } });
+  await b.panel.open(); await settle(); await settle();
+  assert.equal(b.q('[data-approve]'), null);
+  assert.equal(b.q('[data-open-note]'), null);
+  assert.match(text(b.q('.aq-sealed')), /Only the artist who wrote this page, or another artist/);
+});
+
+await test('empty, closed with Escape, and focus goes back where it was', async () => {
+  const b = bootPanel({ answers: { [APPROVALS]: queueFor({ tasks: [] }) } });
+  const opener = { focus() { boot.focused = opener; } };
+  b.focused = opener;
+  await b.panel.open(); await settle();
+  assert.equal(text(b.q('.aq-title')), 'Nothing waiting');
+  assert.match(text(b.q('.aq-frame__note')), /Nothing is waiting for you/);
+  b.scrim.fire('keydown', { key: 'Escape', preventDefault() {}, target: b.scrim });
+  assert.equal(b.scrim.hidden, true);
+  assert.equal(b.focused, opener);
+  assert.ok(!b.classes.has('aq-open'));
+  assert.deepEqual(b.counts, [0]);
+});
+
+// ── the writes: only the host's, and the host's are the studio's allowlist ──
+
+await test('the panel writes only through the writes it is handed; the studio hands it its own WRITE_ROUTES', () => {
+  const src = read('approval-queue.js').replace(/^\s*\/\/.*$/gm, '');
+  const sites = [...src.matchAll(/\.request\(\s*'(POST|PATCH|PUT|DELETE)'\s*,\s*([^,)]+)/g)].map((m) => [m[1], m[2].trim()]);
+  assert.deepEqual(sites, [['POST', 'url']], 'exactly one write site');
+  assert.match(src, /const url = kind === 'approved' \? writes\.approve\(item\.page_id\) : writes\.sendBack\(item\.page_id\);/);
+  assert.equal(/copy-desk\/pages|\/visual\b|\/confirm\b|\/ship\b|\/claims\b|proposals/.test(src.replace(/\/copy-desk\/approvals|\/visuals`/g, '')), false,
+    'no route is named here but the two reads');
+  const studio = read('studio.js');
+  assert.match(studio, /approve: \(pageId\) => `\$\{API\}\/copy-desk\/pages\/\$\{pageId\}\/approve`,/);
+  assert.match(studio, /sendBack: \(pageId\) => `\$\{API\}\/copy-desk\/pages\/\$\{pageId\}\/send-back`,/);
+  assert.match(studio, /writes: \{ approve: WRITE_ROUTES\.approve, sendBack: WRITE_ROUTES\.sendBack \}/);
+  const html = read('studio.html');
+  assert.ok(html.indexOf('approval-queue-lib.js') < html.indexOf('approval-queue.js"') && html.indexOf('approval-queue.js"') < html.indexOf('studio.js?'), 'the lib, the panel, then the studio');
+  assert.match(html, /id="studio-approvals"[^>]*aria-haspopup="dialog"/);
+});
+
+summary();

package/tests/hall_audit.mjs

@@ -429,6 +429,10 @@ const LITERAL_EXEMPT = {
   // studio, the glass bar, and a sheet of PAPER that stays paper in both modes,
   // so its palette cannot be the hall's mode-flipping tier. The sky precedent.
   'tweak-editor.css': 'the tweak editor\'s stage is the artboard\'s own palette (task 1004321, the pixel contract: paper in both modes)',
+  // The Approval queue (task 1004323 / BV2.TW12): the glass dialog of
+  // docs/design/mocks/tweak-mode/Main.dc.html, built 1:1. Glass over the night
+  // studio in both modes, so its palette sits on the panel's own root.
+  'approval-queue.css': 'the Approval queue\'s glass is the artboard\'s own palette (task 1004323, the pixel contract: night glass in both modes)',
 };
 const COLOUR_PROPS = 'color|background|background-color|border|border-color|border-top-color|border-bottom-color|fill|stroke|outline|outline-color|box-shadow|text-shadow';
 const colourLiteralRe = () =>

package/tests/page_tweak_hold.mjs

@@ -0,0 +1,265 @@
+// tests/page_tweak_hold.mjs — a passed page tweak waits at completed for its
+// artist, and nothing else changes (task 1004322 / BV2.TW11; ADR 0341 D7).
+//
+// Four carriers, one per thing the TW03 builder listed:
+//   1. applyGrade does not promote a passed page tweak, and every OTHER grade
+//      sends the same SQL as before, plus exactly one read of `source`;
+//   2. publish-branch publishes a held pass without arming auto-merge;
+//   3. ship.js on a held pass publishes (never merges) and says it waits;
+//   4. strand-watch tells a held pass from a failed grade.
+// No DB, no network: fake pools, the real routers, stubbed GitHub reads.
+//
+// Run:  node tests/page_tweak_hold.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const achievements = require('../modules/economy/achievements.js');
+achievements.evaluateAfterShip = async () => [];
+achievements.evaluateAfterCreditAward = async () => [];
+achievements.evaluateAfterClaim = async () => [];
+achievements.reconcileBuilderAchievements = async () => [];
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const { applyGrade } = require('../modules/lifecycle/db.js');
+const hold = require('../modules/lifecycle/page-tweak-hold.js');
+
+const { test, summary } = makeRunner();
+
+const PASS = { score: 0.95, passed: true, threshold: 0.7, grader_kind: 'subagent', grader_version: 't', rubric_scores: {}, signals: {}, issues: [], notes_md: null };
+const FAIL = { ...PASS, score: 0.3, passed: false };
+
+function gradePool({ source }) {
+  return makeSqlAwareClient((s) => {
+    if (/SELECT id, title, status, credits_reward, kind FROM tasks/.test(s)) return { rows: [{ id: 7, title: 'x', status: 'completed', credits_reward: 30, kind: 'feature' }] };
+    if (/^SELECT source FROM tasks/.test(s)) return { rows: [{ source }] };
+    if (/SELECT builder_id FROM claims/.test(s)) return { rows: [{ builder_id: 25 }] };
+    return { rows: [] };
+  });
+}
+const flat = (q) => q.map((x) => String(x.sql).replace(/\s+/g, ' ').trim());
+
+// ---- 1. applyGrade ---------------------------------------------------------
+
+await test('a PASSED page tweak is recorded and HELD: no promotion, no merge, held=true', async () => {
+  const pool = gradePool({ source: 'page-tweak' });
+  const out = await applyGrade({ taskId: 7, builderId: 1, gradeResult: PASS }, { pool });
+  assert.equal(out.taskStatus, 'completed');
+  assert.equal(out.held, true);
+  assert.equal(out.advanceToMerge, false);
+  const q = flat(pool._client.queries);
+  assert.ok(q.some((s) => /^INSERT INTO task_grades/.test(s)), 'the grade row is still written');
+  assert.ok(!q.some((s) => /^UPDATE tasks/.test(s)), 'the task is NOT promoted to confirmed');
+});
+
+await test('an ordinary pass is promoted exactly as before: the same SQL plus ONE read of source', async () => {
+  const pool = gradePool({ source: 'planning-session' });
+  const out = await applyGrade({ taskId: 7, builderId: 1, gradeResult: PASS }, { pool });
+  assert.equal(out.taskStatus, 'confirmed');
+  assert.equal(out.held, false);
+  assert.equal(out.advanceToMerge, true);
+  const q = flat(pool._client.queries);
+  const reads = q.filter((s) => /^SELECT source FROM tasks/.test(s));
+  assert.equal(reads.length, 1, 'one extra read, and only one');
+  // The pre-change statement sequence, with that one read removed, is unchanged.
+  const legacy = q.filter((s) => !/^SELECT source FROM tasks/.test(s));
+  const pool2 = gradePool({ source: null });
+  await applyGrade({ taskId: 7, builderId: 1, gradeResult: PASS }, { pool: pool2 });
+  assert.deepEqual(flat(pool2._client.queries).filter((s) => !/^SELECT source FROM tasks/.test(s)), legacy, 'a null source takes the same path');
+  assert.ok(legacy.some((s) => /^UPDATE tasks SET status = 'confirmed'/.test(s)));
+});
+
+await test('a FAILED grade never asks about the source (the hold is asked only on a pass)', async () => {
+  for (const source of ['page-tweak', 'planning-session']) {
+    const pool = gradePool({ source });
+    const out = await applyGrade({ taskId: 7, builderId: 1, gradeResult: FAIL }, { pool });
+    assert.equal(out.taskStatus, 'completed');
+    assert.equal(out.held, false);
+    assert.ok(!flat(pool._client.queries).some((s) => /^SELECT source FROM tasks/.test(s)));
+  }
+});
+
+await test('the hold predicate: only a page tweak, only at completed, only a strict pass', () => {
+  const t = (source, status) => ({ source, status });
+  assert.equal(hold.isHeldForArtist(t('page-tweak', 'completed'), true), true);
+  assert.equal(hold.isHeldForArtist(t('page-tweak', 'completed'), false), false);
+  assert.equal(hold.isHeldForArtist(t('page-tweak', 'completed'), null), false);
+  assert.equal(hold.isHeldForArtist(t('page-tweak', 'confirmed'), true), false);
+  assert.equal(hold.isHeldForArtist(t('page-tweak-unplaced', 'completed'), true), false, 'the engineer task an unplaced line files is ordinary work');
+  assert.equal(hold.isHeldForArtist(t('copy-proposal', 'completed'), true), false);
+  assert.equal(hold.isHeldForArtist(null, true), false);
+});
+
+// ---- 2. publish-branch -----------------------------------------------------
+
+const express = require('express');
+const api = require('../src/module-api.js');
+const db = require('../modules/lifecycle/db.js');
+const gp = require('../modules/lifecycle/github-push.js');
+const prAssign = require('../modules/lifecycle/pr-assign.js');
+const pageTweakReads = require('../modules/lifecycle/page-tweak-reads.js');
+
+let heldNow = false;
+let armCalls = 0;
+api.requireBuilder = (req, res, next) => { req.builder = { id: 1, rank: 'archon', github_login: 'the-archon' }; next(); };
+db.getLastClaimHolder = async () => ({ builder_id: 5, github_login: 'some-builder' });
+db.setClaimPublishedSha = async () => {};
+gp.isConfigured = () => true;
+gp.pushBundle = async () => ({ head_sha: 'a'.repeat(40) });
+gp.openOrFindPullRequest = async () => ({ number: 77, url: 'https://github.com/o/r/pull/77', node_id: 'N' });
+gp.enableAutoMergeDetailed = async () => { armCalls++; return { ok: true }; };
+gp.setCommitStatus = async () => true;
+prAssign.assignPullRequest = async () => ({ assigned: true });
+pageTweakReads.heldForArtistFailClosed = async () => heldNow;
+
+const app = express();
+app.use((req, res, next) => { res.fail = (code, status, extra) => res.status(typeof status === 'number' ? status : (status && status.status) || 500).json({ error: code, ...(extra || {}) }); next(); });
+app.use(require('../modules/lifecycle/routes/tasks.js')());
+const server = http.createServer(app);
+await new Promise((r) => server.listen(0, '127.0.0.1', r));
+const base = `http://127.0.0.1:${server.address().port}`;
+const publish = async () => {
+  const res = await fetch(`${base}/tasks/5001/publish-branch`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ branch: 'task-5001', head_sha: 'a'.repeat(40), bundle_b64: Buffer.from('b').toString('base64'), value_summary: 'Page tweak.' }),
+  });
+  return { status: res.status, body: await res.json() };
+};
+
+await test('publish-branch on a HELD pass: the PR is opened, auto-merge is NOT armed, and the reason says why', async () => {
+  heldNow = true; armCalls = 0;
+  const r = await publish();
+  assert.equal(r.status, 201, JSON.stringify(r.body));
+  assert.equal(r.body.pr_url, 'https://github.com/o/r/pull/77', 'published: the Approval queue can show the branch');
+  assert.equal(r.body.auto_merge, false);
+  assert.equal(armCalls, 0, 'GitHub is never asked to arm it');
+  assert.match(r.body.auto_merge_reason, /artist/);
+});
+
+await test('publish-branch on every other task arms auto-merge exactly as before', async () => {
+  heldNow = false; armCalls = 0;
+  const r = await publish();
+  assert.equal(r.status, 201);
+  assert.equal(r.body.auto_merge, true);
+  assert.equal(armCalls, 1);
+  assert.equal(r.body.auto_merge_reason, undefined);
+});
+server.close();
+
+// ---- 3. ship.js ------------------------------------------------------------
+
+const shipMerge = require('../scripts/gds/ship-merge.js');
+const shipFinish = require('../scripts/gds/ship-finish.js');
+const shipLand = require('../scripts/gds/ship-land.js');
+
+await test('publishHeld publishes through the PR path with hold:true, after the same regeneration a land runs', async () => {
+  const calls = [];
+  const out = await shipMerge.publishHeld(5001, 'sum', {
+    currentBranch: () => 'task-5001',
+    regenerate: () => calls.push('regen'),
+    ciLand: async (id, branch, summary, opts) => { calls.push(['ciLand', id, branch, summary, opts]); return shipLand.landHeld({ prUrl: 'u' }); },
+  });
+  assert.deepEqual(calls, ['regen', ['ciLand', 5001, 'task-5001', 'sum', { hold: true }]]);
+  assert.equal(out.held, true);
+  assert.equal(out.ok, false, 'not a land');
+  assert.equal(out.pending, false, 'and not "landing automatically"');
+});
+
+await test('publishHeld on main has no branch to publish: a named bail, and nothing is pushed', async () => {
+  let pushed = false;
+  const out = await shipMerge.publishHeld(5001, 'sum', { currentBranch: () => 'main', localTaskBranchExists: () => true, regenerate: () => { pushed = true; }, ciLand: async () => { pushed = true; } });
+  assert.equal(pushed, false);
+  assert.equal(out.ok, false);
+  assert.match(out.reason, /not the task branch/);
+  assert.match(out.nextStep, /git checkout task-5001/);
+});
+
+await test('finishHeld says the page is WAITING FOR THE ARTIST, syncs the session, and never merges', async () => {
+  const printed = [];
+  const orig = console.log;
+  console.log = (m) => printed.push(String(m));
+  let synced = null;
+  try {
+    await shipFinish.finishHeld({ taskId: 5001, summary: 's', postGradeStatus: 'completed', card: null }, {
+      publishHeld: async () => shipLand.landHeld({ prUrl: 'https://github.com/o/r/pull/77' }),
+      postShipSync: async (id, status) => { synced = status; return null; },
+      printCompletionCard: async () => {},
+    });
+  } finally { console.log = orig; }
+  const text = printed.join('\n');
+  assert.match(text, /WAITING FOR THE ARTIST/);
+  assert.match(text, /pull\/77/);
+  assert.match(text, /auto-merge is NOT armed/);
+  assert.equal(synced, 'confirmed', 'the finished session is uploaded like a confirmed one');
+});
+
+await test('finishShip routes a held pass away from mergeAndDeploy (the source says so, and only when held)', async () => {
+  const fs = require('node:fs');
+  const src = fs.readFileSync(require.resolve('../scripts/gds/ship-finish.js'), 'utf8');
+  const body = src.slice(src.indexOf('async function finishShip('));
+  const holdAt = body.indexOf('if (held) return finishHeld(');
+  const mergeAt = body.indexOf('await mergeAndDeploy(');
+  assert.ok(holdAt > 0 && mergeAt > holdAt, 'the hold is decided BEFORE any merge is attempted');
+  const flow = fs.readFileSync(require.resolve('../scripts/gds/ship-flow.js'), 'utf8');
+  assert.equal((flow.match(/held = gradePost\.data\.held === true/g) || []).length, 1, 'shipMain reads the hold off the grade response');
+  assert.equal((flow.match(/held: gradePost\.data\.held === true/g) || []).length, 1, 'regradeMain does too');
+  assert.match(flow, /tweakHold\.isHeldForArtist\(task, tRes\.data\.grade/, 'a re-run of a held task re-publishes instead of re-grading');
+});
+
+// ---- 4. strand-watch -------------------------------------------------------
+
+const sw = require('../scripts/gds/strand-watch.js');
+const OLD = new Date(Date.now() - 3 * 86400000).toISOString();
+
+function fakeCall({ completed, grades, throwFor = new Set() }) {
+  const gradeReads = [];
+  const call = async (method, url) => {
+    const m = /\/tasks\/(\d+)\?include=grade/.exec(url);
+    if (m) {
+      gradeReads.push(m[1]);
+      if (throwFor.has(m[1])) throw new Error('boom');
+      return { ok: true, data: { task: {}, grade: grades[m[1]] ?? null } };
+    }
+    if (/status=completed/.test(url)) return { ok: true, data: { tasks: completed } };
+    return { ok: true, data: { tasks: [] } };
+  };
+  return { call, gradeReads };
+}
+
+await test('strand-watch: a held pass is WAITING, not a strand; a failed page tweak and ordinary work still are', async () => {
+  const completed = [
+    { id: '11', status: 'completed', source: 'page-tweak', updated_at: OLD },
+    { id: '12', status: 'completed', source: 'page-tweak', updated_at: OLD },
+    { id: '13', status: 'completed', source: 'planning-session', updated_at: OLD },
+  ];
+  const f = fakeCall({ completed, grades: { 11: { passed: true }, 12: { passed: false } } });
+  const r = await sw.check({ call: f.call });
+  assert.deepEqual(r.waiting.map((w) => w.id), ['11']);
+  assert.equal(r.waiting[0].shape, 'waiting_for_artist');
+  assert.deepEqual(r.strands.map((s) => s.id).sort(), ['12', '13']);
+  assert.deepEqual(f.gradeReads.sort(), ['11', '12'], 'grades are read for page tweaks only');
+  assert.ok(!(sw.line(r) || '').includes('task 11'), 'the session-start line never names a held pass');
+});
+
+await test('strand-watch: an unreadable grade stays LOUD (classified as usual), never explained away as a hold', async () => {
+  const f = fakeCall({ completed: [{ id: '11', status: 'completed', source: 'page-tweak', updated_at: OLD }], grades: {}, throwFor: new Set(['11']) });
+  const r = await sw.check({ call: f.call });
+  assert.deepEqual(r.waiting, []);
+  assert.deepEqual(r.strands.map((s) => s.id), ['11']);
+});
+
+await test('/grade-recover stops on a held pass instead of recovering it', () => {
+  const fs = require('node:fs');
+  const p = new URL('../.claude/skills/grade-recover/SKILL.md', import.meta.url);
+  if (!fs.existsSync(p)) return;
+  const md = fs.readFileSync(p, 'utf8');
+  assert.match(md, /waiting for the artist/);
+  assert.match(md, /page-tweak/);
+});
+
+summary();

package/tests/publish_status_branch.mjs

@@ -18,6 +18,10 @@ const require = createRequire(import.meta.url);
 
 const gp = require('../modules/lifecycle/github-push.js');
 const buildTasksRouter = require('../modules/lifecycle/routes/tasks.js');
+// task 1004322: the route asks whether the task is a page tweak held for its
+// artist before it nudges a merge. That read goes to the DB, so the harness
+// stubs it (false = an ordinary task, the case every test below was written for).
+const pageTweakReads = require('../modules/lifecycle/page-tweak-reads.js');
 
 let pass = 0;
 let fail = 0;
@@ -33,6 +37,8 @@ const CRED_KEYS = ['GITHUB_PUSH_TOKEN', 'GITHUB_APP_ID', 'GITHUB_APP_INSTALLATIO
 async function callRoute(query, stubs = {}) {
   const saved = {};
   for (const k of ['findTaskPullRequest', 'getPublishStatus', 'mergeIfGreen']) saved[k] = gp[k];
+  const savedHold = pageTweakReads.heldForArtistFailClosed;
+  pageTweakReads.heldForArtistFailClosed = async () => stubs.held === true;
   const savedEnv = CRED_KEYS.map((k) => [k, process.env[k]]);
   const calls = { findTaskPullRequest: [], getPublishStatus: [], mergeIfGreen: [] };
   gp.findTaskPullRequest = async (a) => { calls.findTaskPullRequest.push(a); return stubs.taskPr === undefined ? null : stubs.taskPr; };
@@ -58,6 +64,7 @@ async function callRoute(query, stubs = {}) {
     return { ...out, calls };
   } finally {
     Object.assign(gp, saved);
+    pageTweakReads.heldForArtistFailClosed = savedHold;
     for (const [k, v] of savedEnv) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
   }
 }
@@ -124,5 +131,21 @@ await t('a genuinely unsafe branch is still refused 400 — in a sentence, befor
   }
 });
 
+await t('a page tweak held for its artist is reported but NEVER nudged to merge (task 1004322, ADR 0341 D7)', async () => {
+  const r = await callRoute({}, { held: true, taskPr: { branch: 'task-1003747', pr_number: 673, pr_state: 'open', merged: false } });
+  assert.equal(r.failCode, null);
+  assert.equal(r.body.ok, true, 'the status is still answered: the Approval queue reads it');
+  assert.equal(r.body.pr_number, 673);
+  assert.deepEqual(r.calls.mergeIfGreen, [], 'a held pass must not be merged by a status poll');
+  assert.equal(r.body.merge_driver, null);
+});
+
+await t('the hold read failing is treated as held: fail-closed, no nudge (task 1004322)', async () => {
+  const real = pageTweakReads.heldForArtistFailClosed;
+  assert.equal(await real(1, async () => { throw new Error('db down'); }), true, 'a throwing read answers held');
+  assert.equal(await real(1, async () => ({ held: false })), false);
+  assert.equal(await real(1, async () => ({ held: true })), true);
+});
+
 console.log(`\npublish-status branch resolution (task 1003764): ${pass} passed, ${fail} failed`);
 process.exitCode = fail > 0 ? 1 : 0;