@bongos/core 1.23.15 → 1.23.17

package/modules/copy-desk/page-status.js

@@ -184,10 +184,12 @@ function roundState(round) {
       return round.holder_worktree ? 'applying' : 'writing';
     case 'ready':
       if (p.batch) {
-        // submitted = a batch, and no applied block newer than the latest
-        // send-back. A sent-back round reads submitted again (the mock's
-        // "it comes back to the queue once it is re-applied").
-        if (!p.applied) return 'submitted';
+        // submitted = a batch whose WORDS were approved (task 1004900), and no
+        // applied block newer than the latest send-back. A sent-back round reads
+        // submitted again (the mock's "it comes back to the queue once it is
+        // re-applied"). A batch nobody has approved yet is words_review: it is
+        // not in the /tweak queue until its words are approved.
+        if (!p.applied) return p.words_approved ? 'submitted' : 'words_review';
         if (p.last_sent_back_at && (!p.applied_at || p.applied_at <= p.last_sent_back_at)) return 'submitted';
         return 'unknown';
       }
@@ -313,14 +315,15 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 const IN_FLIGHT = Object.freeze({
   draft: { word: 'Being written', stuck_after: null },
   writing: { word: 'Being written', stuck_after: null },
-  submitted: { word: 'Submitted, waiting to be applied', stuck_after: 3 * DAY_MS },
+  words_review: { word: 'Words waiting for review', stuck_after: 3 * DAY_MS },
+  submitted: { word: 'Approved, waiting to be applied', stuck_after: 3 * DAY_MS },
   applying: { word: 'Being applied', stuck_after: DAY_MS },
   // task 1004777: a review left 3 days is stuck too, so its artist is told on Home.
   waiting_for_artist: { word: 'Waiting for your review', stuck_after: 3 * DAY_MS },
   landing: { word: 'Approved, going live', stuck_after: DAY_MS },
   unknown: { word: 'Needs to be reviewed', stuck_after: 0 },
 });
-const IN_FLIGHT_ORDER = ['unknown', 'landing', 'applying', 'submitted', 'waiting_for_artist', 'writing', 'draft'];
+const IN_FLIGHT_ORDER = ['unknown', 'landing', 'applying', 'submitted', 'waiting_for_artist', 'words_review', 'writing', 'draft'];
 
 function inFlightFor(list, byPage, nowMs) {
   const out = [];
@@ -377,7 +380,8 @@ function stuckPageTweaks({ inventory, tasks, now = Date.now() }) {
       state_word: f.state_word,
       since: f.since,
       days: ms == null ? null : Math.max(0, Math.floor(ms / DAY_MS)),
-      waits_on: f.state === 'waiting_for_artist' ? 'artist' : 'appliers',
+      // Submitted words (task 1004900) wait on their artist's review, like an applied page.
+      waits_on: f.state === 'waiting_for_artist' || f.state === 'words_review' ? 'artist' : 'appliers',
       artist_id: f.artist_id,
     };
   });
@@ -814,6 +818,10 @@ function approvalFor({ page, pageId, rounds, round, builderId, isArtist }) {
     round: round.round,
     status: round.status,
     state: roundState(round),
+    // task 1004900: 'words' is a batch whose words are reviewed BEFORE it is
+    // applied (no render yet); 'applied' is the applied page held for its artist.
+    kind: roundState(round) === 'words_review' ? 'words' : 'applied',
+    submitted_at: batch.ok ? iso(batch.batch.submitted_at) : null,
     applied_at: appliedAtOf(round),
     line_count: lines.length,
     applied_count: lines.filter((l) => !l.refused).length,
@@ -873,14 +881,15 @@ function composeApprovals({ inventory, tasks, builderId, crafts, now = Date.now(
   for (const [pageId, rounds] of byPage) {
     const open = rounds.filter((r) => !TERMINAL.has(r.status));
     const round = open.length ? open[open.length - 1] : null;
-    if (!round || roundState(round) !== 'waiting_for_artist') continue;
+    const st = round ? roundState(round) : null;
+    if (st !== 'waiting_for_artist' && st !== 'words_review') continue;
     queue.push(approvalFor({ page: invById.get(pageId) || null, pageId, rounds, round, builderId, isArtist }));
   }
   // Oldest applied first, the order they reached the artist; a round with no
   // readable applied block sorts by its task id after the dated ones.
   queue.sort((a, b) => {
-    const at = a.applied_at ? Date.parse(a.applied_at) : Infinity;
-    const bt = b.applied_at ? Date.parse(b.applied_at) : Infinity;
+    const at = (a.applied_at || a.submitted_at) ? Date.parse(a.applied_at || a.submitted_at) : Infinity;
+    const bt = (b.applied_at || b.submitted_at) ? Date.parse(b.applied_at || b.submitted_at) : Infinity;
     return at - bt || Number(a.task_id) - Number(b.task_id);
   });
   queue.forEach((q, i) => { q.position = i + 1; q.of = queue.length; });

package/modules/copy-desk/pages.js

@@ -11,6 +11,9 @@
 //   ```page-tweak-applied    what the applying session landed (TW11); its
 //                            lines_after is the baseline drift is measured from
 //   ```page-tweak-sent-back  one per send-back, appended, never replaced (TW12)
+//   ```page-tweak-words-approved  the batch's words approved BEFORE it is
+//                            applied (task 1004900); only an approved batch is
+//                            in the /tweak queue
 //
 // TW05 (task 1004316) is the first reader, so it lands the format whole: the
 // status, changelog and drift reads parse all four, and the later links write
@@ -30,6 +33,7 @@ const FENCES = Object.freeze({
   batch: 'page-tweak',
   applied: 'page-tweak-applied',
   sentBack: 'page-tweak-sent-back',
+  wordsApproved: 'page-tweak-words-approved',
 });
 
 // The page id shape the inventory's generator enforces: <surface>:<page>, both
@@ -202,11 +206,30 @@ function parseSentBackBlocks(markdown) {
   return out;
 }
 
+// The words of a frozen batch approved before it is applied (task 1004900). It
+// APPENDS like a send-back; a send-back of the words withdraws the batch and
+// every approval with it, so an approval always speaks for the batch beside it.
+function composeWordsApprovedBlock(a) {
+  return fenceBlock(FENCES.wordsApproved, { at: a.at, by: a.by });
+}
+
+function parseWordsApprovedBlocks(markdown) {
+  const out = [];
+  for (const raw of findBlocks(markdown, FENCES.wordsApproved)) {
+    try {
+      const v = JSON.parse(raw);
+      if (v && typeof v.at === 'string') out.push({ at: v.at, by: v.by == null ? null : v.by });
+    } catch { /* an unreadable approval is skipped, never read as one */ }
+  }
+  return out;
+}
+
 // Which blocks a description carries, without failing on any one of them. The
 // round-state derivation (ADR 0341 D7) reads presence and times, not contents.
 function blockPresence(markdown) {
   const sent = parseSentBackBlocks(markdown);
   const applied = parseAppliedBlock(markdown);
+  const approved = parseWordsApprovedBlocks(markdown);
   return {
     draft: findBlocks(markdown, FENCES.draft).length > 0,
     batch: findBlocks(markdown, FENCES.batch).length > 0,
@@ -214,6 +237,8 @@ function blockPresence(markdown) {
     applied_at: applied.ok ? (applied.applied.applied_at || null) : null,
     sent_back_count: sent.length,
     last_sent_back_at: sent.length ? sent.map((s) => s.at).sort().pop() : null,
+    words_approved: approved.length > 0,
+    words_approved_at: approved.length ? approved.map((a) => a.at).sort().pop() : null,
   };
 }
 
@@ -494,6 +519,38 @@ function appendSentBack(description, { at, by, note }) {
   return { ok: true, description: src.trimEnd() + (src.trim() ? '\n\n' : '') + composeSentBackBlock({ at, by, note }) };
 }
 
+// ---------------------------------------------------------------------------
+// Reviewing the words before they are applied (task 1004900).
+//
+// A submitted batch waits for its words to be approved; only then does /tweak
+// (or the runner) apply it. Approving appends an approval block. Sending the
+// words back takes the batch (and any approval) out again and appends the
+// note, so the round reads as a draft its artist can change and submit again:
+// the draft block was never removed by the submit.
+// ---------------------------------------------------------------------------
+
+function stripBlocks(description, fence) {
+  const re = new RegExp('\\n*```' + fence.replace(/-/g, '\\-') + '[ \\t]*\\r?\\n[\\s\\S]*?\\r?\\n```', 'g');
+  return String(description || '').replace(re, '');
+}
+
+function approveWords(description, { at, by }) {
+  const p = blockPresence(description);
+  if (!p.batch) return fail('no_batch');
+  if (p.words_approved) return fail('already_approved');
+  const src = String(description || '');
+  return { ok: true, description: src.trimEnd() + '\n\n' + composeWordsApprovedBlock({ at, by }) };
+}
+
+function sendBackWords(description, { at, by, note }) {
+  const p = blockPresence(description);
+  if (!p.batch) return fail('no_batch');
+  if (p.words_approved) return fail('already_approved');
+  if (p.applied) return fail('already_applied');
+  const withdrawn = stripBlocks(stripBlocks(description, FENCES.batch), FENCES.wordsApproved);
+  return appendSentBack(withdrawn, { at, by, note });
+}
+
 module.exports = {
   SCHEMA,
   SOURCE,
@@ -516,6 +573,10 @@ module.exports = {
   MAX_NOTE_CHARS,
   normalizeSentBackNote,
   appendSentBack,
+  composeWordsApprovedBlock,
+  parseWordsApprovedBlocks,
+  approveWords,
+  sendBackWords,
   blockPresence,
   roundOpenForWriting,
   MAX_LINE_CHARS,

package/modules/copy-desk/pollers/auto-close-rounds.js

@@ -0,0 +1,32 @@
+'use strict';
+
+// modules/copy-desk/pollers/auto-close-rounds.js — closes page rounds that hold
+// nothing to act on (task 1004899). Loader-started (contributes.pollers); the
+// rule lives in ../auto-close.js. Every 15 minutes by default
+// (COPY_AUTO_CLOSE_MS); COPY_AUTO_CLOSE_DISABLED=1 turns it off. Best-effort: a
+// failed sweep logs and tries again next interval.
+
+const api = require('../../../src/module-api');
+const autoClose = require('../auto-close');
+
+const log = api.logger('copy-desk');
+const INTERVAL_MS = Number(process.env.COPY_AUTO_CLOSE_MS) || 15 * 60_000;
+let timer = null;
+
+function tick() {
+  autoClose.runAutoClose()
+    .then((r) => { if (r.closed.length) log.info(`[auto-close-rounds] closed ${r.closed.length} empty page round(s)`); })
+    .catch((e) => log.error(e, '[auto-close-rounds] sweep failed'));
+}
+
+module.exports = {
+  start() {
+    if (process.env.COPY_AUTO_CLOSE_DISABLED === '1' || timer) return;
+    timer = setInterval(tick, INTERVAL_MS);
+    if (timer.unref) timer.unref();
+  },
+  stop() {
+    if (timer) clearInterval(timer);
+    timer = null;
+  },
+};

package/modules/copy-desk/routes/copy-desk.js

@@ -62,7 +62,7 @@ const pageStatus = require('../page-status');
 const pages = require('../pages');
 const guarded = require('../guarded-lines');
 const docx = require('../docx');
-const { openRoundOf, waitingRoundOrFail, refuseDecision, nextWaiting } = require('../page-decisions');
+const { openRoundOf, waitingRoundOrFail, refuseDecision, nextWaiting, decideWords } = require('../page-decisions');
 const { tallyCreditRows, readArtistStats } = require('../artist-stats');
 
 const { validateOrRespond } = api;
@@ -220,7 +220,7 @@ function alreadySubmitted(round, builderId, pageId) {
   if (!b.ok) return null;
   return {
     ok: true, outcome: 'already_submitted', page_id: pageId,
-    round: { task_id: String(round.id), state: 'submitted', status: 'ready' },
+    round: { task_id: String(round.id), state: pageStatus.roundState(round), status: 'ready' },
     batch: { line_count: b.batch.lines.length, submitted_at: b.batch.submitted_at, reading_hash: b.batch.reading_hash },
     unplaced_tasks: (b.batch.unplaced_tasks || []).map((id) => ({ task_id: String(id) })),
     warnings: b.batch.warnings || [],
@@ -1319,7 +1319,7 @@ module.exports = function buildCopyDeskRouter() {
         case 'submitted':
           return res.json({
             ok: true, outcome: 'submitted', page_id: pageId,
-            round: { task_id: String(r.task.id), state: 'submitted', status: r.task.status },
+            round: { task_id: String(r.task.id), state: 'words_review', status: r.task.status },
             batch: { line_count: frozen.batch.lines.length, submitted_at: submittedAt, reading_hash: frozen.batch.reading_hash },
             warnings: frozen.batch.warnings || [],
             unplaced_tasks: r.unplaced_tasks.map((u) => ({ task_id: u.id, key: u.key, created: u.created })),
@@ -1354,6 +1354,8 @@ module.exports = function buildCopyDeskRouter() {
   // queue), both through the lifecycle port. WHO DECIDES: the author or any
   // artist, checked by the port; the owner's escape hatch is the override
   // request. Anyone may READ the queue. Helpers: ../page-decisions.js.
+  // task 1004900: a submitted batch's WORDS are decided here first, before it
+  // is applied (approve: into the /tweak queue; send back: a draft again).
   // -------------------------------------------------------------------------
 
   // GET /copy-desk/approvals — every round waiting for its artist, oldest
@@ -1407,6 +1409,7 @@ module.exports = function buildCopyDeskRouter() {
       const waiting = await waitingRoundOrFail(res, lifecycle, pageId, req.body || {}, openRoundOf);
       if (!waiting) return;
       const { round } = waiting;
+      if (waiting.state === 'words_review') return decideWords(res, lifecycle, { pageId, round, builderId: req.builder.id, kind: 'approve', invData: inv.data });
       // What the page will read once this round ships, from ALL its rounds, read
       // before the approve moves this one on.
       const before = pageStatus.composeApprovals({ inventory: inv.data, tasks: waiting.rounds, builderId: req.builder.id, crafts: [] }).queue[0] || null;
@@ -1459,6 +1462,7 @@ module.exports = function buildCopyDeskRouter() {
       const waiting = await waitingRoundOrFail(res, lifecycle, pageId, req.body || {}, openRoundOf);
       if (!waiting) return;
       const { round } = waiting;
+      if (waiting.state === 'words_review') return decideWords(res, lifecycle, { pageId, round, builderId: req.builder.id, kind: 'send_back', note: note.note, invData: inv.data });
       const at = new Date().toISOString();
       const by = String(req.builder.id);
       const r = await lifecycle.sendBackHeldTweak({

package/modules/copy-desk/skills/tweak/SKILL.md

@@ -19,7 +19,7 @@ You are applying ONE page an artist rewrote in the studio (Tweak Mode, ADR 0341)
 node scripts/bongos/api.js GET /api/bongos/copy-desk/pages --quiet
 ```
 
-A round is in the queue when its page's `open_round.state` is `submitted`. Take the one with the lowest `open_round.task_id` (the oldest). None? Say "the tweak queue is empty" and stop.
+A round is in the queue when its page's `open_round.state` is `submitted`: its words have been approved in the studio (task 1004900). A round whose words still wait for review reads `words_review` and is not yours to apply. Take the one with the lowest `open_round.task_id` (the oldest). None? Say "the tweak queue is empty" and stop.
 
 Claim it in THIS worktree, on a fresh branch from `origin/main`:
 

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

@@ -70,7 +70,7 @@ const stripComments = (src) => src
 // Task 1004435 added routes/copy-desk-artist.js (one artist's approved pages, a
 // read) and artist-stats.js's readArtistPages under it.
 const ROUTE_FILES = fs.readdirSync(path.join(MODULE_DIR, 'routes')).filter((f) => f.endsWith('.js')).sort().map((f) => `routes/${f}`);
-const MODULE_FILES = ['registry.js', 'flags.js', 'proposals.js', 'pages.js', 'page-status.js', 'page-data.js', 'docx.js', 'page-decisions.js', 'artist-stats.js', ...ROUTE_FILES];
+const MODULE_FILES = ['registry.js', 'flags.js', 'proposals.js', 'pages.js', 'page-status.js', 'page-data.js', 'docx.js', 'page-decisions.js', 'artist-stats.js', 'auto-close.js', ...ROUTE_FILES];
 
 console.log('copy-desk: NO LIVE CMS');
 
@@ -310,6 +310,10 @@ await test('the module manifest declares no seam another module could write copy
   assert.deepEqual(manifest.provides, ['copy-desk.artistStats', 'copy-desk.stuckPageTweaksFor'], 'a provided port here would be a copy write path for every other module');
   const stuckSrc = stripComments(read('stuck-tweaks.js'));
   assert.equal(/writeFile|\.query\(|UPDATE |INSERT /.test(stuckSrc), false, 'the stuck-tweaks port writes nothing');
+  // task 1004899: the auto-close sweep only ABANDONS an empty round through the
+  // lifecycle port; it never hands a compose, so it cannot write a description.
+  const closeSrc = stripComments(read('auto-close.js'));
+  assert.equal(/writeFile|\.query\(|UPDATE |INSERT |compose/.test(closeSrc), false, 'the auto-close sweep abandons and writes nothing');
   const stats = read('artist-stats.js');
   assert.equal(/\b(pool|query|writeFile|appendFile|INSERT|UPDATE|DELETE)\b/.test(stats.replace(/\/\/.*$/gm, '')), false,
     'the artist-stats port reads through other ports and writes nothing');

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

@@ -0,0 +1,92 @@
+// modules/copy-desk/tests/copy_page_auto_close.mjs — a page round with nothing in
+// it closes itself (task 1004899).
+//
+// The done-when: a blank round and a round whose batch has no lines left are
+// abandoned by the sweep; a round with real lines, a draft, a held round, a
+// round waiting for its artist and a freshly touched one are never touched.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pages = require('../pages.js');
+const autoClose = require('../auto-close.js');
+
+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}`); }
+}
+
+const NOW = Date.parse('2026-10-27T12:00:00.000Z');
+const OLD = '2026-10-20T12:00:00.000Z';
+const PAGE = 'builders:collab';
+
+const line = { key: 'L0001', section: 'Top', before: 'Archive', after: 'Past Collabs', placement: 'placed' };
+const draft = pages.composeDraftBlock({ page_id: PAGE, reading_hash: 'h', saved_at: OLD, lines: [line] });
+const batch = (lines) => pages.composeBatchBlock({ page_id: PAGE, reading_hash: 'h', submitted_at: OLD, lines, unplaced_tasks: lines.length ? [] : ['1004692'] });
+
+const round = (over) => ({ id: '1', status: 'ready', description: 'Page tweak round 1.', holder_id: null, updated_at: OLD, created_at: OLD, ...over });
+
+const ROUNDS = {
+  blank: round({ id: '11' }),
+  empty_batch: round({ id: '12', description: `${draft}\n\n${batch([])}` }),
+  real_batch: round({ id: '13', description: `${draft}\n\n${batch([line])}` }),
+  draft_only: round({ id: '14', description: draft }),
+  held: round({ id: '15', status: 'active', holder_id: '7' }),
+  waiting: round({ id: '16', status: 'completed', description: `${draft}\n\n${batch([line])}` }),
+  fresh_blank: round({ id: '17', updated_at: new Date(NOW - 5 * 60_000).toISOString() }),
+  ready_but_held: round({ id: '18', holder_id: '7' }),
+};
+
+console.log('copy-desk: empty page rounds close themselves');
+
+await test('a blank round and an empty batch are the only two that close', () => {
+  const got = Object.fromEntries(Object.entries(ROUNDS).map(([k, t]) => [k, autoClose.closeReason(t, { now: NOW })]));
+  assert.deepEqual(got, {
+    blank: 'blank',
+    empty_batch: 'nothing_to_apply',
+    real_batch: null,
+    draft_only: null,
+    held: null,
+    waiting: null,
+    fresh_blank: null,
+    ready_but_held: null,
+  });
+});
+
+await test('the grace period is honoured: a round touched within it stays', () => {
+  const t = round({ updated_at: new Date(NOW - 59 * 60_000).toISOString() });
+  assert.equal(autoClose.closeReason(t, { now: NOW, graceMs: 60 * 60_000 }), null);
+  assert.equal(autoClose.closeReason(t, { now: NOW, graceMs: 30 * 60_000 }), 'blank');
+});
+
+await test('the sweep abandons through the lifecycle port, as the owner, with a plain note and no rewrite', async () => {
+  const calls = [];
+  const lifecycle = {
+    listPageTweakTasks: async () => Object.values(ROUNDS),
+    releaseStuckTweak: async (args) => { calls.push(args); return { outcome: 'abandoned' }; },
+  };
+  const r = await autoClose.runAutoClose({ now: NOW, resolve: () => lifecycle, founder: async () => ({ id: '1' }) });
+  assert.deepEqual(r.closed.map((c) => [c.task_id, c.why, c.outcome]), [['11', 'blank', 'abandoned'], ['12', 'nothing_to_apply', 'abandoned']]);
+  for (const c of calls) {
+    assert.equal(c.builderId, '1');
+    assert.equal(c.expectedStatus, 'ready');
+    assert.equal('compose' in c, false, 'no compose: the round is abandoned, never rewritten');
+    assert.ok(c.note.length >= pages.MIN_NOTE_CHARS && c.note.length <= pages.MAX_NOTE_CHARS, 'the note fits the release note floor and cap');
+  }
+});
+
+await test('nothing due, no owner read; no owner, no sweep; no lifecycle, no sweep', async () => {
+  let asked = 0;
+  const quiet = { listPageTweakTasks: async () => [ROUNDS.real_batch], releaseStuckTweak: async () => { throw new Error('must not run'); } };
+  assert.deepEqual(await autoClose.runAutoClose({ now: NOW, resolve: () => quiet, founder: async () => { asked++; return { id: '1' }; } }), { closed: [] });
+  assert.equal(asked, 0);
+  const due = { listPageTweakTasks: async () => [ROUNDS.blank], releaseStuckTweak: async () => { throw new Error('must not run'); } };
+  assert.equal((await autoClose.runAutoClose({ now: NOW, resolve: () => due, founder: async () => null })).skipped, 'no_owner');
+  assert.equal((await autoClose.runAutoClose({ now: NOW, resolve: () => null })).skipped, 'no_lifecycle');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

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

@@ -110,7 +110,7 @@ await test('held and in-flight pages are never recommended, and are named in ski
   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.skipped[1].state, 'words_review');
   assert.equal(out.resume, null);
 });
 

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

@@ -193,7 +193,10 @@ await test('every row of the D7 state table', () => {
     [{ status: 'active', holder_id: '7', holder_worktree: false }, 'writing'],
     [{ status: 'active', holder_id: '7', holder_worktree: true }, 'applying'],
     [{ status: 'ready', description: draft }, 'draft'],
-    [{ status: 'ready', description: batch }, 'submitted'],
+    [{ status: 'ready', description: batch }, 'words_review'],
+    [{ status: 'ready', description: `${batch}
+
+${pages.composeWordsApprovedBlock({ at: 't2', by: '7' })}` }, 'submitted'],
     [{ status: 'ready', description: sentBackAfterApply }, 'submitted'],
     [{ status: 'ready', description: applied }, 'unknown'],
     [{ status: 'completed', grade_passed: true }, 'waiting_for_artist'],
@@ -245,7 +248,9 @@ await test('in_flight: every open round, its plain state, how long, and stuck wh
   const pg = (id) => ({ id, surface: id.split(':')[0], title: id, path: '/', files: [] });
   const ids = ['landing:a', 'landing:b', 'landing:c', 'builders:d', 'builders:e', 'builders:f', 'builders:g', 'status:h'];
   const inventory = { surfaces: [{ id: 'landing' }, { id: 'builders' }, { id: 'status' }], pages: ids.map(pg) };
-  const batch = (id) => pages.composeBatchBlock({ page_id: id, reading_hash: 'h', submitted_at: ago(9), lines: [] });
+  const batch = (id) => `${pages.composeBatchBlock({ page_id: id, reading_hash: 'h', submitted_at: ago(9), lines: [] })}
+
+${pages.composeWordsApprovedBlock({ at: ago(9), by: '7' })}`;
   const round = (n, id, extra) => ({ id: String(n), source: 'page-tweak', source_ref: pages.roundSourceRef(id, 1), description: pages.roundTaskBody(pg(id), 1), ...extra });
   const tasks = [
     round(1, 'landing:a', { status: 'ready', description: `${pages.roundTaskBody(pg('landing:a'), 1)}\n\n${batch('landing:a')}`, updated_at: ago(9) }),
@@ -262,9 +267,9 @@ await test('in_flight: every open round, its plain state, how long, and stuck wh
     ['builders:f', 'unknown', 'Needs to be reviewed', true],
     ['landing:c', 'landing', 'Approved, going live', true],
     ['status:h', 'applying', 'Being applied', true],
-    ['landing:a', 'submitted', 'Submitted, waiting to be applied', true],
+    ['landing:a', 'submitted', 'Approved, waiting to be applied', true],
     ['builders:d', 'waiting_for_artist', 'Waiting for your review', true],
-    ['landing:b', 'submitted', 'Submitted, waiting to be applied', false],
+    ['landing:b', 'submitted', 'Approved, waiting to be applied', false],
     ['builders:e', 'writing', 'Being written', false],
   ], 'a shipped round is not in flight; writing is never stuck, and a review left 20 days is (task 1004777)');
   assert.equal(out.in_flight[1].since, ago(17));

package/modules/hall-ui/public/approval-queue-lib.js

@@ -83,6 +83,8 @@
   // there are any ("· 1 not applied").
   function subLine(item) {
     if (!item) return '';
+    // task 1004900: words reviewed before they are applied.
+    if (item.kind === 'words') return `· ${[item.surface_word || item.surface || '', `${plural(item.line_count, 'line', 'lines')} rewritten, not applied yet`].filter(Boolean).join(' · ')}`;
     const parts = [item.surface_word || item.surface || '', `${plural(item.applied_count, 'line', 'lines')} rewritten, applied`];
     if (item.refused_count > 0) parts.push(`${item.refused_count} not applied`);
     return `· ${parts.filter(Boolean).join(' · ')}`;
@@ -92,7 +94,7 @@
   function doorDetail(count) {
     if (count == null) return 'tweaks waiting for your sign-off';
     if (count === 0) return 'nothing waiting for you';
-    return `${plural(count, 'page', 'pages')} applied, waiting for you`;
+    return `${plural(count, 'page', 'pages')} waiting for you`;
   }
 
   // Why a line was not applied, in words (copy-apply.js's refusals).
@@ -140,7 +142,7 @@
       task_id: String(r.task_id),
       title: displayTitle(r),
       mark: 'not applied yet',
-      line: `${r.state_word}${waited ? ` · waiting ${waited}` : ''}. The words are waiting to be applied, so there is nothing to approve yet.`,
+      line: `${r.state_word}${waited ? ` · waiting ${waited}` : ''}. The words are approved and waiting to be put on the page.`,
     };
   }
 
@@ -156,6 +158,10 @@
   // server's re-read of the queue.
   function approvedLine(item, resp) {
     const name = displayTitle(item);
+    if (item && item.kind === 'words') {
+      const nxt = resp && resp.next && resp.next.page ? displayTitle(resp.next.page) : null;
+      return [`Words approved. ${name} will be updated on its own, and it ships once the update is checked.`, nxt ? `Next in the queue: ${nxt}.` : 'Nothing else is waiting.'].join(' ');
+    }
     const status = resp && resp.status_after ? resp.status_after.charAt(0).toLowerCase() + resp.status_after.slice(1) : null;
     const next = resp && resp.next && resp.next.page ? displayTitle(resp.next.page) : null;
     return [
@@ -164,7 +170,8 @@
     ].join(' ');
   }
 
-  function sentBackLine() {
+  function sentBackLine(item) {
+    if (item && item.kind === 'words') return 'Sent back with your note. The page is a draft again, so its writer can change the words and submit them.';
     return 'Sent back with your note. It comes back to the queue once it is re-applied.';
   }
 

package/modules/hall-ui/public/approval-queue.js

@@ -172,7 +172,7 @@
       if (!item.can_decide) {
         return '<div class="aq-foot"><p class="aq-sealed">Only the artist who wrote this page, or another artist, can approve it or send it back.</p><span class="aq-hint">highlighted: the words you changed</span></div>';
       }
-      const approve = `<button type="button" class="aq-accent" data-approve${state.busy ? ' disabled' : ''}>Approve and ship</button>`;
+      const approve = `<button type="button" class="aq-accent" data-approve${state.busy ? ' disabled' : ''}>${item.kind === 'words' ? 'Approve the words' : 'Approve and ship'}</button>`;
       const note = state.noteOpen
         ? `<div class="aq-note">
             <label for="aq-note" class="aq-sr">What needs changing</label>
@@ -187,6 +187,8 @@
     // The page as the artist would see it: closed until asked for, because a
     // picture that may not exist is no way to open a decision.
     function peekHtml(item) {
+      // task 1004900: submitted words have no page render yet.
+      if (item.kind === 'words') return '<p class="aq-frame__note">Not on the page yet. Once you approve the words, the page is updated and checked on its own.</p>';
       if (!state.peek) {
         return '<div class="aq-peek"><button type="button" class="aq-ghost aq-ghost--small" data-peek aria-expanded="false">See it on the page</button></div>';
       }
@@ -207,8 +209,8 @@
     function notAppliedHtml() {
       const rows = (state.notApplied || []).map((r) => L.notAppliedRow(r));
       if (!rows.length) return '';
-      return `<section class="aq-pending" aria-label="Submitted, not applied yet">
-          <h3 class="aq-pending__h">Submitted, not applied yet (${rows.length})</h3>
+      return `<section class="aq-pending" aria-label="Approved, not applied yet">
+          <h3 class="aq-pending__h">Approved, not applied yet (${rows.length})</h3>
           <ul class="aq-pending__list">${rows.map((r) => `
             <li class="aq-pending__row" data-task="${esc(r.task_id)}"><span class="aq-pending__title">${esc(r.title)}</span> <span class="aq-pending__mark">${esc(r.mark)}</span><span class="aq-pending__line">${esc(r.line)}</span></li>`).join('')}</ul>
         </section>`;
@@ -221,7 +223,7 @@
       const item = current();
       const close = '<button type="button" class="aq-close" data-close>close</button>';
       if (!item) {
-        const words = state.loadError || (state.loaded ? 'Nothing is waiting for you. A page shows up here once its tweaks have been applied and checked.' : 'Opening the Approval queue…');
+        const words = state.loadError || (state.loaded ? 'Nothing is waiting for you. A page shows up here when its words are submitted, and again once they have been applied and checked.' : 'Opening the Approval queue…');
         dialog.innerHTML = `
           <div class="aq-head"><span class="aq-eyebrow">approval queue</span><h2 class="aq-title" id="aq-title">${state.loaded ? 'Nothing waiting' : 'Approval queue'}</h2><span class="aq-head__gap"></span>${close}</div>
           <div class="aq-body aq-body--empty"><div class="aq-frame"><p class="aq-frame__note">${esc(words)}</p></div></div>
@@ -271,7 +273,7 @@
           state.error = errWords(res.data, 'That could not be recorded. Nothing changed.');
           return;
         }
-        state.outcome.set(item.task_id, { kind, line: kind === 'approved' ? L.approvedLine(item, res.data) : L.sentBackLine() });
+        state.outcome.set(item.task_id, { kind, line: kind === 'approved' ? L.approvedLine(item, res.data) : L.sentBackLine(item) });
         state.noteOpen = false;
         tellCount();
       } catch (_) {

package/modules/hall-ui/public/studio-lib.js

@@ -167,8 +167,9 @@
         state: p.state_word || 'Needs to be reviewed',
         age,
         stuck: !!p.stuck,
-        // A page waiting on a sign-off opens its approval card.
-        review: p.state === 'waiting_for_artist',
+        // A page waiting on a sign-off opens its approval card: its submitted
+        // words (task 1004900) or its applied page.
+        review: p.state === 'waiting_for_artist' || p.state === 'words_review',
         // A round the reads cannot name has no action of its own: the row offers
         // a release (task 1004837). task_id pins the round the viewer looked at.
         release: p.state === 'unknown',

package/modules/lifecycle/lifecycle.js

@@ -136,6 +136,8 @@ module.exports = {
   approveHeldTweak: (...a) => pageTweakApprove.approveHeldTweak(...a),
   sendBackHeldTweak: (...a) => pageTweakApprove.sendBackHeldTweak(...a),
   releaseStuckTweak: (...a) => pageTweakApprove.releaseStuckTweak(...a),
+  // task 1004900: approve or send back a submitted batch's WORDS before it is applied.
+  decideTweakWords: (...a) => pageTweakApprove.decideTweakWords(...a),
   // A builder's crafts (help-requests' reader, from builders.preferred_disciplines),
   // so the queue read can say whether the caller may decide before they try.
   builderCrafts: (...a) => helpRequests.craftsForBuilder(...a),

package/modules/lifecycle/page-tweak-approve.js

@@ -94,6 +94,14 @@ async function lockWaitingRound(client, { taskId, builderId }) {
   if (!hold.isHeldForArtist(task, grade ? grade.passed : null)) {
     return { outcome: 'not_waiting', task, grade_passed: grade ? grade.passed : null };
   }
+  const who = await deciderOf(client, { taskId, builderId, task });
+  if (who.outcome) return who;
+  return { task, grade, authorId: who.authorId };
+}
+
+// May this builder decide the round? Its author (latest web claim) or any
+// artist; an inactive builder never. Returns { authorId } or an outcome.
+async function deciderOf(client, { taskId, builderId, task }) {
   const { rows: b } = await client.query(
     'SELECT id, status, github_login, display_name FROM builders WHERE id = $1', [builderId]
   );
@@ -109,7 +117,7 @@ async function lockWaitingRound(client, { taskId, builderId }) {
     const crafts = await helpRequests.craftsForBuilder(builderId, { pool: client });
     if (!crafts.includes('artist')) return { outcome: 'not_an_artist', task, author_id: authorId };
   }
-  return { task, grade, authorId };
+  return { authorId };
 }
 
 async function inTx(deps, body) {
@@ -323,4 +331,44 @@ async function releaseStuckTweak({ taskId, builderId, expectedStatus, compose =
   return out;
 }
 
-module.exports = { approveHeldTweak, sendBackHeldTweak, releaseStuckTweak };
+// decideTweakWords({ taskId, builderId, compose }, deps)   (task 1004900)
+//
+// The review of a submitted batch's WORDS, before anything is applied. The
+// round must be a `ready` page tweak nobody holds (a held one is being
+// written or applied: round_moved); the same author-or-artist rule as the
+// other two decisions. copy-desk's compose says what the decision writes (an
+// approval block, or the batch withdrawn with a send-back note) and refuses a
+// round that is not under word review. Only the description changes: the task
+// stays `ready`, so an approved round is in the /tweak queue and a sent-back
+// one is a draft again. No PR exists yet, so none is touched.
+// Outcomes: decided | not_found | wrong_source | round_moved | not_an_artist |
+// builder_inactive | refused
+async function decideTweakWords({ taskId, builderId, compose }, deps = {}) {
+  const out = await inTx(deps, async (client) => {
+    const { rows } = await client.query(
+      `SELECT id, status, title, description, source, source_ref, version_id, goal_id, touches
+         FROM tasks WHERE id = $1 FOR UPDATE`,
+      [taskId]
+    );
+    const task = rows[0];
+    if (!task) return { outcome: 'not_found' };
+    if (!hold.isPageTweak(task)) return { outcome: 'wrong_source', task };
+    if (task.status !== 'ready') return { outcome: 'round_moved', task };
+    const { rows: open } = await client.query('SELECT id FROM claims WHERE task_id = $1 AND released_at IS NULL LIMIT 1', [taskId]);
+    if (open.length) return { outcome: 'round_moved', task };
+    const who = await deciderOf(client, { taskId, builderId, task });
+    if (who.outcome) return who;
+    const r = compose(task);
+    if (!r || !r.ok) return { outcome: 'refused', refusal: r, task };
+    const { rows: updated } = await client.query(
+      `UPDATE tasks SET description = $2, updated_at = now() WHERE id = $1
+       RETURNING id, status, description, source_ref, updated_at`,
+      [taskId, r.description]
+    );
+    return { commit: true, outcome: 'decided', task: updated[0], author_id: who.authorId };
+  });
+  delete out.commit;
+  return out;
+}
+
+module.exports = { approveHeldTweak, sendBackHeldTweak, releaseStuckTweak, decideTweakWords };

package/package-lock.json

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