@bongos/core 1.19.1064 → 1.19.1065

package/scripts/hall-preview/server.js

@@ -136,6 +136,9 @@ const FIXTURE_FALLBACKS = [
   // page id, since the editor shows one page. A page id carries a colon, which a
   // Windows file name cannot, so there is no per-id file to find first.
   [/^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/draft$/, 'copy-desk__pages__draft'],
+  // the Approval queue's renders (task 1004323): a round's named visuals, one
+  // fixture for any task id, as the editor read above serves any page.
+  [/^tasks\/\d+\/visuals$/, 'tasks__visuals'],
 ];
 
 // CANNED WRITES (task 1004321). The tweak editor's whole flow is writes (the
@@ -148,6 +151,10 @@ const CANNED_WRITES = [
   ['PUT', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/draft$/, 'copy-desk__pages__draft.put'],
   ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/submit$/, 'copy-desk__pages__submit.post'],
   ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/claim$/, 'copy-desk__pages__claim.post'],
+  // the Approval queue's two decisions (task 1004323), so the approved and
+  // sent-back lines the artboard draws render too.
+  ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/approve$/, 'copy-desk__pages__approve.post'],
+  ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/send-back$/, 'copy-desk__pages__send-back.post'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request
@@ -252,6 +259,17 @@ app.use((req, res, next) => {
   // frame, so the one thing being reviewed is the one thing you cannot see.
   // A generated stand-in; see scripts/hall-preview/task-visual.js.
   if (/^task-visuals\/[A-Za-z0-9._-]+$/.test(apiPath) && req.method === 'GET') {
+    // HALL_PREVIEW_VISUALS=<dir> serves a REAL image of that name from <dir>
+    // instead (task 1004323): the Approval queue's review sheet shows the renders
+    // /tweak really attached, copied under the fixture's names into a scratch
+    // dir. Nothing is committed; unset, every visual is the stand-in as before.
+    const realDir = process.env.HALL_PREVIEW_VISUALS;
+    const name = apiPath.slice('task-visuals/'.length);
+    const real = realDir && /^task-\d+-[0-9a-f]{16}\.(png|jpg)$/.test(name) ? path.join(realDir, name) : null;
+    if (real && fs.existsSync(real)) {
+      res.set({ 'content-type': name.endsWith('.png') ? 'image/png' : 'image/jpeg', 'cache-control': 'no-store' });
+      return res.end(fs.readFileSync(real));
+    }
     const png = require('./task-visual').placeholderPng();
     res.set({ 'content-type': 'image/png', 'cache-control': 'no-store' });
     return res.end(png);

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.1064'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1065'; // 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_page_approve.mjs

@@ -0,0 +1,307 @@
+// tests/copy_desk_page_approve.mjs — the Approval queue, the WHOLE path (task
+// 1004323 / BV2.TW12, ADR 0341 D7 and D11).
+//
+// The done-when: approve ships the page and advances its status; send-back
+// re-queues it with the note.
+//
+// Driven through the real copy-desk routes, the real lifecycle port
+// (approveHeldTweak, sendBackHeldTweak, the real promoteToConfirmed under
+// approve) and the real page reads, against the shared stateful fake ledger
+// (tests/fixtures/page-ledger.mjs). The reward port is a recording fake, so
+// the test sees exactly what the approve pays and to whom. GitHub is a stub
+// handed to the port directly for the land nudge and the PR close.
+
+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 ALICE = '7'; // the author of both rounds, an artist
+const BOB = '8';   // another artist
+const CARL = '9';  // the applier, an engineer
+const DAN = '10';  // neither author nor artist
+const { db } = installPageLedger(api, {
+  builders: [
+    { id: ALICE, github_login: 'alice', display_name: 'Alice', preferred_disciplines: ['artist'] },
+    { id: BOB, github_login: 'bob', display_name: 'Bob', preferred_disciplines: ['artist'] },
+    { id: CARL, github_login: 'carl', display_name: 'Carl', preferred_disciplines: ['engineer'] },
+    { id: DAN, github_login: 'dan', display_name: 'Dan', preferred_disciplines: ['engineer'] },
+  ],
+});
+
+api.requireBuilder = (req, res, next) => {
+  req.builder = { id: String(req.headers['x-builder'] || ALICE), rank: 'metic' };
+  next();
+};
+
+// The reward port, recording. Registered before the lifecycle port resolves it.
+const paid = [];
+const seams = require('../src/module-seams.js');
+const fakeReward = {
+  awardNetNegativeBonus: async (client, builderId, taskId, diffStats) => { paid.push(['net_negative', String(builderId), String(taskId), diffStats]); return { bonus: 2, justUnlocked: [] }; },
+  evaluateAfterShip: async (client, builderId, taskId, files) => { paid.push(['after_ship', String(builderId), String(taskId), files]); return ['subtractor']; },
+  reconcileBuilderAchievements: async (client, builderId) => { paid.push(['reconcile', String(builderId)]); return []; },
+  creditLedger: async () => ({ rows: [], total: 0 }),
+};
+if (seams.hasProvider('reward')) throw new Error('this test must own the reward port');
+seams.registerProvider('reward', fakeReward);
+const lifecyclePort = require('../modules/lifecycle/lifecycle.js');
+if (!seams.hasProvider('lifecycle')) seams.registerProvider('lifecycle', lifecyclePort);
+
+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: method === 'GET' ? undefined : JSON.stringify(body) });
+  return { status: r.status, body: await r.json() };
+}
+const errCode = (b) => (b && b.error && b.error.code) || null;
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'page-approve-'));
+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));
+pageData._setRoot(tmp);
+
+// ---- the ledger: rounds as /tweak leaves them ------------------------------
+
+let at = Date.parse('2026-09-20T00:00:00Z');
+const stamp = () => new Date(at += 60_000).toISOString();
+
+// A round of `pageId`, submitted by ALICE and applied by CARL: the artist's web
+// claim released by the submit, then the applier's CLI claim released by its
+// ship, the task at completed and its grade row as given.
+function appliedRound({ id, pageId, round, lines, refused = [], appliedAt, status = 'completed', passed = true, applierClaimOpen = false }) {
+  const description = [
+    `Page tweak round ${round} for ${pageId}.`,
+    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: 'abc' })) }),
+    pages.composeAppliedBlock({ page_id: pageId, applied_at: appliedAt, reading_hash_after: 'h2', lines_after: lines.map((l) => l.after), refused }),
+  ].join('\n\n');
+  db.tasks.push({ id: String(id), status, title: `Tweak: ${pageId}`, description, source: 'page-tweak', source_ref: pages.roundSourceRef(pageId, round), touches: [], version_id: 'V9', goal_id: '77', shipped_by: null });
+  db.claims.push({ id: String(++db.seq.claim), task_id: String(id), builder_id: ALICE, worktree_name: null, creator_session_id: null, claimed_at: stamp(), released_at: stamp(), outcome: 'partial' });
+  db.claims.push({ id: String(++db.seq.claim), task_id: String(id), builder_id: CARL, worktree_name: `task-${id}`, creator_session_id: 's1', claimed_at: stamp(), released_at: applierClaimOpen ? null : stamp(), outcome: applierClaimOpen ? null : 'shipped' });
+  if (passed !== undefined) db.grades.set(String(id), passed);
+  (db.gradeSignals = db.gradeSignals || new Map()).set(String(id), { diff_stats: { added: 2, removed: 2 } });
+}
+
+// landing:index already shipped once, so an approve makes it "Text tweaked 2x".
+db.tasks.push({ id: '4001', status: 'shipped', shipped_at: '2026-09-01T00:00:00Z', title: 'Tweak: Home', description: pages.composeBatchBlock({ page_id: 'landing:index', reading_hash: 'h0', submitted_at: '2026-08-30T00:00:00Z', lines: [] }), source: 'page-tweak', source_ref: pages.roundSourceRef('landing:index', 1), touches: [] });
+appliedRound({
+  id: 5001, pageId: 'landing:index', round: 2, appliedAt: '2026-09-21T10:00:00Z',
+  lines: [
+    { key: 'L0002', section: 'hero', before: 'Build here', after: 'Build it here' },
+    { key: 'L0005', section: 'hero', before: 'Start a project', after: 'Start yours' },
+  ],
+  refused: [{ key: 'L0005', code: 'target_gone' }],
+});
+appliedRound({
+  id: 5002, pageId: 'landing:projects', round: 1, appliedAt: '2026-09-22T10:00:00Z', applierClaimOpen: true,
+  lines: [{ key: 'L0002', section: 'list', before: 'Every project', after: 'All the projects' }],
+});
+// A completed round whose grade FAILED is still with its applier: not in the queue.
+appliedRound({
+  id: 5003, pageId: 'status:explore', round: 1, appliedAt: '2026-09-20T10:00:00Z', passed: false,
+  lines: [{ key: 'L0001', section: 'hero', before: 'Explore', after: 'Look around' }],
+});
+
+const task = (id) => db.tasks.find((t) => String(t.id) === String(id));
+const INDEX = '/copy-desk/pages/landing:index';
+const PROJECTS = '/copy-desk/pages/landing:projects';
+const { test, summary } = makeRunner();
+
+try {
+  await test('the queue: every round waiting for its artist, oldest applied first, "1 of 2"', async () => {
+    const r = await call('GET', '/copy-desk/approvals', BOB);
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.equal(r.body.count, 2, 'the failed-grade round is not waiting for the artist');
+    const [first, second] = r.body.queue;
+    assert.deepEqual([first.page_id, first.position, first.of], ['landing:index', 1, 2]);
+    assert.deepEqual([second.page_id, second.position, second.of], ['landing:projects', 2, 2]);
+    assert.equal(first.task_id, '5001');
+    assert.equal(first.title, 'Home');
+    assert.equal(first.surface_word, 'landing');
+    assert.equal(first.line_count, 2);
+    assert.equal(first.applied_count, 1);
+    assert.equal(first.refused_count, 1);
+    assert.deepEqual(first.lines.map((l) => [l.key, l.before, l.after, l.refused]), [
+      ['L0002', 'Build here', 'Build it here', null],
+      ['L0005', 'Start a project', 'Start yours', 'target_gone'],
+    ]);
+    assert.equal(first.status_label, 'Text tweaked 1x');
+    assert.equal(first.status_after_approval, 'Text tweaked 2x');
+    assert.deepEqual(first.visuals, { method: 'GET', path: '/tasks/5001/visuals' });
+    assert.deepEqual(first.author, { id: ALICE, login: 'alice' });
+    assert.equal(first.can_decide, true, 'another artist may decide');
+    assert.equal(first.by_you, false);
+  });
+
+  await test('who may decide: the author and any artist, never anyone else', async () => {
+    const alice = (await call('GET', '/copy-desk/approvals', ALICE)).body;
+    assert.equal(alice.queue[0].by_you, true);
+    assert.equal(alice.queue[0].can_decide, true);
+    const dan = (await call('GET', '/copy-desk/approvals', DAN)).body;
+    assert.equal(dan.is_artist, false);
+    assert.equal(dan.queue.every((q) => q.can_decide === false), true, 'Dan reads the queue but cannot decide');
+    const r = await call('POST', `${INDEX}/approve`, DAN);
+    assert.equal(r.status, 403);
+    assert.equal(errCode(r.body), 'not_an_artist');
+    assert.match(r.body.error.details.what_this_means, /override request/, 'the refusal names the owner\'s escape hatch');
+    assert.equal(task(5001).status, 'completed', 'nothing moved');
+    assert.equal(paid.length, 0, 'nothing was paid');
+  });
+
+  await test('an approve pinned to another round is refused round_moved', async () => {
+    const r = await call('POST', `${INDEX}/approve`, BOB, { task_id: '4001' });
+    assert.equal(r.status, 409);
+    assert.equal(errCode(r.body), 'round_moved');
+    assert.equal(task(5001).status, 'completed');
+  });
+
+  await test('approve: completed -> confirmed, the applier rewarded as a passed grade is, the next page named', async () => {
+    const r = await call('POST', `${INDEX}/approve`, BOB, { task_id: '5001' });
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.equal(r.body.outcome, 'approved');
+    assert.deepEqual(r.body.round, { task_id: '5001', state: 'landing', status: 'confirmed' });
+    assert.equal(r.body.status_after, 'Text tweaked 2x');
+    assert.deepEqual(r.body.next.page, { page_id: 'landing:projects', title: 'Projects', path: '/projects', task_id: '5002' });
+    assert.equal(r.body.next.count, 1);
+    assert.equal(task(5001).status, 'confirmed');
+    assert.equal(task(5001).shipped_by, CARL, 'attributed to the applier, never the approver');
+    assert.deepEqual(paid, [
+      ['net_negative', CARL, '5001', { added: 2, removed: 2 }],
+      ['after_ship', CARL, '5001', null],
+      ['reconcile', CARL],
+    ], 'the bonus and the achievements the held pass skipped, credited to the applier');
+    // No credential in this process: the land is the reconciler's.
+    assert.equal(r.body.land.lands_via, 'reconciler');
+    // The page reads landing; its count goes up when it ships.
+    const page = (await call('GET', INDEX, BOB)).body;
+    assert.equal(page.open_round.state, 'landing');
+    assert.equal(page.count, 1);
+  });
+
+  await test('an approved page is no longer waiting: a second approve or a send-back is not_waiting', async () => {
+    const again = await call('POST', `${INDEX}/approve`, BOB);
+    assert.equal(again.status, 409);
+    assert.equal(errCode(again.body), 'not_waiting');
+    const back = await call('POST', `${INDEX}/send-back`, BOB, { note: 'Too long on a phone.' });
+    assert.equal(back.status, 409);
+    assert.equal(errCode(back.body), 'not_waiting');
+    assert.equal(paid.length, 3, 'nothing paid twice');
+    const q = (await call('GET', '/copy-desk/approvals', BOB)).body;
+    assert.deepEqual(q.queue.map((x) => [x.page_id, x.position, x.of]), [['landing:projects', 1, 1]]);
+  });
+
+  await test('send-back needs a one-line note of ten characters; a short one moves nothing', async () => {
+    const r = await call('POST', `${PROJECTS}/send-back`, ALICE, { note: '  too  long ' });
+    assert.equal(r.status, 400);
+    assert.equal(errCode(r.body), 'note_too_short');
+    assert.equal(task(5002).status, 'completed');
+    assert.equal(db.grades.get('5002'), true);
+    const missing = await call('POST', `${PROJECTS}/send-back`, ALICE, {});
+    assert.equal(missing.status, 400, 'no note at all is refused by the schema');
+  });
+
+  await test('send-back: the note rests on the task, the claim is released, the stale pass dropped, the round back in /tweak', async () => {
+    const r = await call('POST', `${PROJECTS}/send-back`, ALICE, { note: 'The heading is too long on a phone.', task_id: '5002' });
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.equal(r.body.outcome, 'sent_back');
+    assert.deepEqual(r.body.round, { task_id: '5002', state: 'submitted', status: 'ready' });
+    assert.equal(r.body.sent_back.note, 'The heading is too long on a phone.');
+    assert.equal(r.body.sent_back.by, ALICE);
+    assert.equal(r.body.next.page, null);
+    assert.equal(r.body.next.count, 0);
+    const t = task(5002);
+    assert.equal(t.status, 'ready');
+    const sent = pages.parseSentBackBlocks(t.description);
+    assert.deepEqual(sent.map((s) => [s.by, s.note]), [[ALICE, 'The heading is too long on a phone.']]);
+    assert.equal(pages.parseBatchBlock(t.description).ok, true, 'the frozen batch stays for the next applier');
+    assert.equal(db.claims.filter((c) => c.task_id === '5002' && c.released_at == null).length, 0, 'the applier\'s open claim is released');
+    assert.equal(db.grades.has('5002'), false, 'the old pass cannot make the re-applied round look approved');
+    const page = (await call('GET', PROJECTS, ALICE)).body;
+    assert.equal(page.open_round.state, 'submitted', 'it reads submitted: the /tweak queue');
+    assert.equal((await call('GET', '/copy-desk/approvals', ALICE)).body.count, 0);
+  });
+
+  await test('re-applied after a send-back, the round waits again only once its NEW grade passes', async () => {
+    const t = task(5002);
+    // /tweak applies it again and ships: a newer applied block, completed, no grade yet.
+    t.description = pages.replaceBlock(t.description, pages.FENCES.applied, pages.composeAppliedBlock({
+      page_id: 'landing:projects', applied_at: new Date(Date.now() + 1000).toISOString(), reading_hash_after: 'h3', lines_after: ['All projects'], refused: [],
+    })).description;
+    t.status = 'completed';
+    const early = await call('POST', `${PROJECTS}/approve`, ALICE);
+    assert.equal(errCode(early.body), 'not_waiting', 'no grade yet: not approvable');
+    db.grades.set('5002', true);
+    const q = (await call('GET', '/copy-desk/approvals', ALICE)).body;
+    assert.equal(q.count, 1);
+    assert.equal(q.queue[0].sent_back_count, 1);
+  });
+
+  await test('the port nudges the merge once after an approve, and closes the PR after a send-back', async () => {
+    // Direct port calls with a GitHub stub: the reads the reconciler makes.
+    const calls = [];
+    const push = {
+      isConfigured: () => true,
+      findTaskPullRequest: async ({ taskId }) => { calls.push(['find', taskId]); return { branch: `task-${taskId}`, pr_number: 88, pr_state: 'open', merged: false }; },
+      mergeIfGreen: async ({ branch }) => { calls.push(['merge', branch]); return { merged: true, merged_now: true }; },
+      closePullRequest: async ({ number }) => { calls.push(['close', number]); return { closed: true, number }; },
+    };
+    const approved = await lifecyclePort.approveHeldTweak({ taskId: '5002', builderId: ALICE }, { push });
+    assert.equal(approved.outcome, 'approved');
+    assert.deepEqual(approved.land, { nudged: true, merged: true, merged_now: true, reason: null, pr_number: 88, lands_via: 'merged' });
+    assert.deepEqual(calls, [['find', 5002], ['merge', 'task-5002']]);
+    // A failing GitHub read never undoes the approve: the reconciler lands it.
+    task(5002).status = 'completed';
+    const broken = { ...push, findTaskPullRequest: async () => { throw new Error('rate limited'); } };
+    const again = await lifecyclePort.approveHeldTweak({ taskId: '5002', builderId: ALICE }, { push: broken });
+    assert.equal(again.outcome, 'approved');
+    assert.deepEqual(again.land, { nudged: false, reason: 'nudge_failed', lands_via: 'reconciler' });
+    // Send-back closes the open PR.
+    task(5002).status = 'completed';
+    calls.length = 0;
+    const back = await lifecyclePort.sendBackHeldTweak({
+      taskId: '5002', builderId: BOB,
+      compose: (t) => pages.appendSentBack(t.description, { at: new Date().toISOString(), by: BOB, note: 'Still too long on a phone.' }),
+    }, { push });
+    assert.equal(back.outcome, 'sent_back');
+    assert.deepEqual(back.pr, { closed: true, pr_number: 88 });
+    assert.deepEqual(calls, [['find', 5002], ['close', 88]]);
+    assert.equal(pages.parseSentBackBlocks(task(5002).description).length, 2, 'send-backs append');
+  });
+
+  await test('an ordinary task and a failed grade are never moved through the port', async () => {
+    db.tasks.push({ id: '6001', status: 'completed', title: 'x', description: '', source: 'planning-session', source_ref: 'x', touches: [] });
+    db.grades.set('6001', true);
+    assert.equal((await lifecyclePort.approveHeldTweak({ taskId: '6001', builderId: BOB })).outcome, 'wrong_source');
+    assert.equal(task(6001).status, 'completed');
+    assert.equal((await lifecyclePort.approveHeldTweak({ taskId: '5003', builderId: BOB })).outcome, 'not_waiting');
+    assert.equal(task(5003).status, 'completed');
+    const sent = await lifecyclePort.sendBackHeldTweak({ taskId: '5003', builderId: BOB, compose: () => ({ ok: true, description: 'x' }) });
+    assert.equal(sent.outcome, 'not_waiting');
+    assert.equal(db.grades.get('5003'), false, 'the failed grade stays for /grade-recover');
+  });
+} finally {
+  server.close();
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+summary();

package/tests/fixtures/page-ledger.mjs

@@ -11,7 +11,8 @@
 // An unknown statement THROWS: a route that sends SQL this ledger does not
 // model fails loudly instead of reading an empty answer.
 //
-// Shared by tests/copy_desk_page_claim.mjs, tests/copy_desk_page_next.mjs and
+// Shared by tests/copy_desk_page_claim.mjs, tests/copy_desk_page_next.mjs,
+// tests/copy_desk_page_approve.mjs and
 // tests/copy_desk_page_submit.mjs
 // (a fixture, not a test: the runner discovers tests/*.mjs only).
 
@@ -147,6 +148,45 @@ export function installPageLedger(api, { builders }) {
       if (c) Object.assign(c, { released_at: new Date().toISOString(), outcome: p[1] });
       return { rows: [] };
     }
+    // The Approval queue's decisions (task 1004323 / TW12,
+    // modules/lifecycle/page-tweak-approve.js): the grade row, the round's
+    // author (its latest WEB claim), the applier (its latest claim of any
+    // kind), applyGrade's promotion, and send-back's release and grade drop.
+    if (/^SELECT passed, signals FROM task_grades WHERE task_id = \$1$/.test(q)) {
+      const k = String(p[0]);
+      return { rows: db.grades.has(k) ? [{ passed: db.grades.get(k), signals: (db.gradeSignals && db.gradeSignals.get(k)) || {} }] : [] };
+    }
+    if (/^SELECT builder_id FROM claims WHERE task_id = \$1 AND worktree_name IS NULL AND creator_session_id IS NULL ORDER BY claimed_at DESC, id DESC LIMIT 1$/.test(q)) {
+      const web = db.claims.filter((c) => String(c.task_id) === String(p[0]) && isWeb(c)).slice(-1)[0];
+      return { rows: web ? [{ builder_id: web.builder_id }] : [] };
+    }
+    if (/^SELECT builder_id FROM claims WHERE task_id = \$1 ORDER BY claimed_at DESC, id DESC LIMIT 1$/.test(q)) {
+      const last = db.claims.filter((c) => String(c.task_id) === String(p[0])).slice(-1)[0];
+      return { rows: last ? [{ builder_id: last.builder_id }] : [] };
+    }
+    if (/^UPDATE tasks SET status = 'confirmed', shipped_by = COALESCE\(shipped_by, \$2\), updated_at = now\(\) WHERE id = \$1 AND status = 'completed'$/.test(q)) {
+      assert.ok(owner, 'the promotion runs inside the approve transaction');
+      const t = db.tasks.find((x) => String(x.id) === String(p[0]) && x.status === 'completed');
+      if (t) { t.status = 'confirmed'; if (t.shipped_by == null) t.shipped_by = String(p[1]); }
+      return { rows: [] };
+    }
+    if (/^(SAVEPOINT|RELEASE SAVEPOINT|ROLLBACK TO SAVEPOINT) ach_reconcile$/.test(q)) return { rows: [] };
+    if (/^UPDATE claims SET released_at = now\(\), outcome = 'partial' WHERE task_id = \$1 AND released_at IS NULL RETURNING id$/.test(q)) {
+      assert.ok(owner, 'the release runs inside the send-back transaction');
+      const hit = db.claims.filter((x) => String(x.task_id) === String(p[0]) && x.released_at == null);
+      for (const c of hit) Object.assign(c, { released_at: new Date().toISOString(), outcome: 'partial' });
+      return { rows: hit.map((c) => ({ id: c.id })) };
+    }
+    if (/^DELETE FROM task_grades WHERE task_id = \$1$/.test(q)) {
+      assert.ok(owner, 'the grade drop runs inside the send-back transaction');
+      db.grades.delete(String(p[0]));
+      return { rows: [] };
+    }
+    // The ships that touched a page since its last round (shippedTasksTouchingSince).
+    if (/^SELECT t\.id, t\.title, t\.shipped_at FROM tasks t WHERE t\.status = 'shipped' AND t\.shipped_at > \$2::timestamptz AND t\.touches && \$1::text\[\]/.test(q)) {
+      const since = Date.parse(p[1]);
+      return { rows: db.tasks.filter((t) => t.status === 'shipped' && Date.parse(t.shipped_at) > since && (t.touches || []).some((f) => p[0].includes(f))).map((t) => ({ id: t.id, title: t.title, shipped_at: t.shipped_at })) };
+    }
     // The page reads (listPageTweakTasks), computed from the ledger's state.
     if (/FROM tasks t LEFT JOIN task_grades g/.test(q)) {
       assert.match(q, /WHERE t\.source = 'page-tweak'/);

package/tests/gate_approvals.mjs

@@ -465,5 +465,98 @@ await t('route-rank auditor: gate-approval READ is metic+, APPROVE stays archon,
   assert.deepEqual(myFindings, [], 'no auditor findings on the gate-approval routes');
 });
 
+
+// ===========================================================================
+// Layer 3 — the page-tweak hold (task 1004323 / BV2.TW12, ADR 0341 D7). The
+// approve re-arms auto-merge on the reopened PR; a page tweak held for its
+// artist must be reopened (the check re-runs) but NEVER armed from here.
+// ===========================================================================
+
+const pageTweakReads = require('../modules/lifecycle/page-tweak-reads.js');
+async function withHold(fnHeld, body) {
+  const saved = pageTweakReads.heldForArtistFailClosed;
+  pageTweakReads.heldForArtistFailClosed = fnHeld;
+  try { return await body(); } finally { pageTweakReads.heldForArtistFailClosed = saved; }
+}
+async function approveWith(prNode) {
+  let rechecked = null;
+  const res = fakeRes();
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => [prNode],
+    setGateOwnerApproved: async () => true,
+    recheckPullRequest: async (args) => { rechecked = args; return { reopened: true, auto_merge: args.arm !== false }; },
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'post', '/gate-approvals/:pr/approve');
+    await handler({ builder: ARCHON, params: { pr: String(prNode.number) }, body: {} }, res);
+  });
+  return { res, rechecked };
+}
+
+await t('POST approve: a page tweak HELD for its artist is reopened but not re-armed', async () => {
+  const asked = [];
+  await withHold(async (id) => { asked.push(id); return true; }, async () => {
+    const { res, rechecked } = await approveWith(pr({ number: 301, title: 'task 5001: Tweak: Home (landing:index)', head_sha: SHA, checks: [gateCheck('FAILURE')] }));
+    assert.equal(res.statusCode, 200);
+    assert.deepEqual(asked, [5001], 'the hold is asked of the PR\'s own task');
+    assert.equal(rechecked.number, 301);
+    assert.equal(rechecked.arm, false, 'the recheck must not arm auto-merge');
+    assert.match(rechecked.heldReason, /held for the artist/);
+    assert.equal(res.body.held_for_artist, true);
+    assert.match(res.body.message, /waiting for its artist/);
+  });
+});
+
+await t('POST approve: an ordinary task is re-armed exactly as before (no arm flag sent)', async () => {
+  await withHold(async () => false, async () => {
+    const { rechecked, res } = await approveWith(pr({ number: 302, title: 'task 1163: x', head_sha: SHA, checks: [gateCheck('FAILURE')] }));
+    assert.deepEqual(rechecked, { number: 302 }, 'the pre-change call, byte for byte');
+    assert.equal(res.body.held_for_artist, false);
+  });
+});
+
+await t('POST approve: a PR naming no task is never asked about a hold', async () => {
+  let asked = 0;
+  await withHold(async () => { asked++; return true; }, async () => {
+    const { rechecked } = await approveWith(pr({ number: 303, title: 'chore: no task here', head_sha: SHA, checks: [gateCheck('FAILURE')] }));
+    assert.equal(asked, 0);
+    assert.deepEqual(rechecked, { number: 303 });
+  });
+});
+
+await t('POST approve: the REAL fail-closed read answers held when it cannot read the ledger', async () => {
+  // No stub: page-tweak-reads.heldForArtistFailClosed runs, its read throws
+  // (no pool in this process), and the route must then withhold the arm.
+  const { rechecked } = await approveWith(pr({ number: 304, title: 'task 5002: y', head_sha: SHA, checks: [gateCheck('FAILURE')] }));
+  assert.equal(rechecked.arm, false, 'an unreadable hold is treated as held');
+});
+
+await t('recheckPullRequest({ arm: false }): closes and reopens, and never calls the auto-merge mutation', async () => {
+  const calls = [];
+  const fetchImpl = async (url, opts) => {
+    const method = (opts && opts.method) || 'GET';
+    if (method === 'PATCH') { calls.push(JSON.parse(opts.body).state); return jsonRes(200, { node_id: 'N1' }); }
+    calls.push(`unexpected ${url}`);
+    return jsonRes(200, {});
+  };
+  const r = await gp.recheckPullRequest({ number: 205, arm: false, heldReason: 'held for the artist' }, { token: 'T', repoInfo: REPO, fetchImpl, reopenDelayMs: 0 });
+  assert.deepEqual(calls, ['closed', 'open']);
+  assert.equal(r.reopened, true);
+  assert.equal(r.auto_merge, false);
+  assert.equal(r.auto_merge_reason, 'held for the artist');
+});
+
+await t('closePullRequest (github-pr-close.js): one PATCH to state=closed, and a refusal is thrown by name', async () => {
+  const prClose = require('../modules/lifecycle/github-pr-close.js');
+  const calls = [];
+  const fetchImpl = async (url, opts) => { calls.push([url, opts.method, JSON.parse(opts.body)]); return jsonRes(200, {}); };
+  const r = await prClose.closePullRequest({ number: 77 }, { token: 'T', repoInfo: REPO, fetchImpl });
+  assert.deepEqual(r, { closed: true, number: 77 });
+  assert.deepEqual(calls, [['https://api.github.com/repos/someowner/somerepo/pulls/77', 'PATCH', { state: 'closed' }]]);
+  await assert.rejects(
+    prClose.closePullRequest({ number: 77 }, { token: 'T', repoInfo: REPO, fetchImpl: async () => jsonRes(422, { message: 'no' }) }),
+    (e) => e.code === 'PR_PATCH_FAILED'
+  );
+});
 console.log(`\n${pass} passed, ${fail} failed`);
 process.exit(fail === 0 ? 0 : 1);