@bongos/core 1.19.1063 → 1.19.1064

package/modules/lifecycle/routes/visuals.js

@@ -14,6 +14,12 @@
 //   DELETE /tasks/:id/visual    take it back off       (claim holder | Archon)
 //   GET    /task-visuals/:name  serve one              (see the audience note)
 //
+// NAMED SLOTS (task 1004322 / BV2.TW11, lifecycle_013) — the same store, the same
+// gate, the same audience, one picture per name:
+//   POST   /tasks/:id/visuals/:slot   attach or replace a named one (claim holder | Archon)
+//   DELETE /tasks/:id/visuals/:slot   take it back off              (claim holder | Archon)
+//   GET    /tasks/:id/visuals         list them by name              (any builder)
+//
 // The twin of routes/bug-attachments.js, for the image a builder attaches to
 // their own shipped task instead of one the bot pulled out of #bugs. Storage +
 // screening live in ../task-visuals.js; all three routes live here rather than
@@ -191,6 +197,82 @@ module.exports = function buildTaskVisualsRouter() {
     }
   });
 
+  // ==========================================================================
+  // NAMED SLOTS (task 1004322 / BV2.TW11; ADR 0341 D7, builder pick 9)
+  // --------------------------------------------------------------------------
+  // A page tweak carries eight renders of the applied page (before and after,
+  // desktop and phone, light and dark), and the Approval queue shows them by
+  // name. Each slot is stored and screened exactly as the one visual is, and
+  // served by the same GET /task-visuals/:name, whose audience comes from the
+  // task. The slot name is validated before any byte is read.
+
+  // POST /tasks/:id/visuals/:slot — attach (or replace) one named visual.
+  router.post('/tasks/:id/visuals/:slot', auth.requireBuilder, visualUpload, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const slot = req.params.slot;
+    if (!visuals.isSafeSlot(slot)) return res.fail('bad_slot', 400, { max_length: visuals.MAX_SLOT_LENGTH, example: visuals.TWEAK_RENDER_SLOTS[0] });
+    if (validateOrRespond(req, res, {
+      image_b64: { required: true, type: 'string', maxLength: VISUAL_B64_MAX, minLength: 1 },
+      content_type: { required: true, type: 'string', maxLength: 100, minLength: 1 },
+      alt: { type: 'string', maxLength: visuals.MAX_ALT_LENGTH },
+    })) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    const buf = Buffer.from(req.body.image_b64, 'base64');
+    const screened = visuals.screenImage(buf, req.body.content_type);
+    if (!screened.ok) {
+      return res.fail(`visual_${screened.reason}`, screened.reason === 'too_big' ? 413 : 400, {
+        max_bytes: visuals.MAX_BYTES,
+        accepted: Object.keys(visuals.EXT_BY_TYPE),
+      });
+    }
+    const task = await db.getTaskVisualAccess(id);
+    if (!task) return res.fail('task_not_found', 404);
+    try {
+      const stored = await visuals.persistImageBuffer(buf, { taskId: id, contentType: req.body.content_type });
+      if (!stored.ok) return res.fail(`visual_${stored.reason}`, 400);
+      const row = await db.setTaskVisualSlot({ taskId: id, slot, visualUrl: stored.url, visualAlt: visuals.normalizeAlt(req.body.alt) });
+      if (row && row.replaced_url && row.replaced_url !== stored.url) await visuals.deleteStored(row.replaced_url);
+      return res.status(201).json({ ok: true, slot, visual_url: row.visual_url, visual_alt: row.visual_alt, bytes: stored.bytes });
+    } catch (err) {
+      log.error({ taskId: id, slot, err: err && err.message }, 'task-visual slot upload failed');
+      return res.fail('visual_store_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // DELETE /tasks/:id/visuals/:slot — remove one named visual. Idempotent.
+  router.delete('/tasks/:id/visuals/:slot', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const slot = req.params.slot;
+    if (!visuals.isSafeSlot(slot)) return res.fail('bad_slot', 400);
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    try {
+      const url = await db.deleteTaskVisualSlot({ taskId: id, slot });
+      if (url) await visuals.deleteStored(url);
+      return res.json({ ok: true, slot, visual_url: null });
+    } catch (err) {
+      log.error({ taskId: id, slot, err: err && err.message }, 'task-visual slot delete failed');
+      return res.fail('visual_delete_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /tasks/:id/visuals — the task's named visuals. Any signed-in builder: it
+  // lists URLs only, and each image is still served under its own task's audience.
+  router.get('/tasks/:id/visuals', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    try {
+      const task = await db.getTaskVisualAccess(id);
+      if (!task) return res.fail('task_not_found', 404);
+      const rows = await db.listTaskVisualSlots(id);
+      return res.json({ ok: true, task_id: String(id), slots: rows.map((x) => ({ slot: x.slot, visual_url: x.visual_url, visual_alt: x.visual_alt, updated_at: x.updated_at })) });
+    } catch (err) {
+      log.error({ taskId: id, err: err && err.message }, 'task-visual slot list failed');
+      return res.fail('visual_list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // DELETE /tasks/:id/visual — remove it again. The counterpart to "always
   // optional": a builder who attached the wrong screenshot must be able to take
   // it back, and an image is not prose (the write-once rule of task 1003102

package/modules/lifecycle/task-visual-db.js

@@ -43,4 +43,43 @@ async function getTaskVisualAccess(taskId) {
   return rows[0] ?? null;
 }
 
-module.exports = { setTaskVisual, getTaskVisualAccess };
+// NAMED SLOTS (task 1004322, lifecycle_013). Status-blind, like the two above:
+// the routes decide who may write and who may see.
+//
+// Upsert one slot. Returns the stored row and the URL it REPLACED (null when the
+// slot was empty), read in the same statement so the route can unlink exactly the
+// superseded file.
+async function setTaskVisualSlot({ taskId, slot, visualUrl, visualAlt = null }) {
+  const { rows } = await pool.query(
+    `WITH prev AS (
+       SELECT visual_url FROM lifecycle_task_visual_slots WHERE task_id = $1 AND slot = $2
+     )
+     INSERT INTO lifecycle_task_visual_slots (task_id, slot, visual_url, visual_alt, updated_at)
+     VALUES ($1, $2, $3, $4, now())
+     ON CONFLICT (task_id, slot) DO UPDATE
+       SET visual_url = EXCLUDED.visual_url, visual_alt = EXCLUDED.visual_alt, updated_at = now()
+     RETURNING slot, visual_url, visual_alt, (SELECT visual_url FROM prev) AS replaced_url`,
+    [taskId, slot, visualUrl, visualAlt]
+  );
+  return rows[0] ?? null;
+}
+
+// Remove one slot. Returns the URL it held, or null when it was already empty.
+async function deleteTaskVisualSlot({ taskId, slot }) {
+  const { rows } = await pool.query(
+    `DELETE FROM lifecycle_task_visual_slots WHERE task_id = $1 AND slot = $2 RETURNING visual_url`,
+    [taskId, slot]
+  );
+  return rows[0] ? rows[0].visual_url : null;
+}
+
+// Every slot a task carries, by name.
+async function listTaskVisualSlots(taskId) {
+  const { rows } = await pool.query(
+    `SELECT slot, visual_url, visual_alt, updated_at FROM lifecycle_task_visual_slots WHERE task_id = $1 ORDER BY slot`,
+    [taskId]
+  );
+  return rows;
+}
+
+module.exports = { setTaskVisual, getTaskVisualAccess, setTaskVisualSlot, deleteTaskVisualSlot, listTaskVisualSlots };

package/modules/lifecycle/task-visuals.js

@@ -55,6 +55,24 @@ const TYPE_BY_EXT = {
 };
 
 const MAX_BYTES = 4 * 1024 * 1024; // 4 MB — a screenshot, not an asset library.
+
+// NAMED SLOTS (task 1004322 / BV2.TW11, lifecycle_013). A task may carry named
+// visuals beside its one ship-time picture. The shape is the column's own CHECK,
+// restated so a bad name is refused before any byte is stored.
+const SLOT_RE = /^[a-z0-9]+(-[a-z0-9]+){0,5}$/;
+const MAX_SLOT_LENGTH = 48;
+function isSafeSlot(slot) {
+  return typeof slot === 'string' && slot.length <= MAX_SLOT_LENGTH && SLOT_RE.test(slot);
+}
+// The eight renders /tweak attaches to a page tweak (ADR 0341 D7, builder pick 9):
+// the applied page before and after, desktop (1440) and phone (390), light and
+// dark. Declared ONCE: the renderer names its files with it, the attach step
+// uploads by it, and the Approval queue (TW12) reads the same names.
+const TWEAK_RENDER_PHASES = Object.freeze(['before', 'after']);
+const TWEAK_RENDER_DEVICES = Object.freeze({ desktop: 1440, phone: 390 });
+const TWEAK_RENDER_MODES = Object.freeze(['light', 'dark']);
+const TWEAK_RENDER_SLOTS = Object.freeze(TWEAK_RENDER_PHASES.flatMap((phase) =>
+  Object.keys(TWEAK_RENDER_DEVICES).flatMap((device) => TWEAK_RENDER_MODES.map((mode) => `${phase}-${device}-${mode}`))));
 const MAX_ALT_LENGTH = 300;        // the caption/alt text stored beside it.
 
 // Stored filenames are SERVER-generated, never user-supplied: a fixed shape we
@@ -249,6 +267,12 @@ async function deleteStored(nameOrUrl, { dir = visualsDir() } = {}) {
 }
 
 module.exports = {
+  isSafeSlot,
+  MAX_SLOT_LENGTH,
+  TWEAK_RENDER_PHASES,
+  TWEAK_RENDER_DEVICES,
+  TWEAK_RENDER_MODES,
+  TWEAK_RENDER_SLOTS,
   EXT_BY_TYPE,
   TYPE_BY_EXT,
   MAX_BYTES,

package/package-lock.json

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

package/package.json

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

package/release-notes.json

@@ -7679,5 +7679,11 @@
       "id": "1004321",
       "text": "Artists now have their own editor for a page. It shows every word of the page as one sheet of paper over the studio at night. You type over any line and it saves as you go. A changed line gets a small orange mark and shows wha"
     }
+  ],
+  "1.19.1064": [
+    {
+      "id": "1004322",
+      "text": "A session can now apply an artist's rewritten page. The new /tweak skill takes the next submitted page, applies every line in one pass, and photographs the page before and after, on a desktop and a phone, in light and dark, at"
+    }
   ]
 }

package/scripts/gds/copy-apply.js

@@ -30,7 +30,9 @@
 // arithmetic does not hold, or the file is outside a registry surface. None of
 // them means the wording was wrong — they mean a person should look.
 //
-// Run:  node scripts/gds/copy-apply.js                    (the task you are HOLDING — the normal call)
+// Run:  node scripts/gds/copy-apply.js --batch            (a PAGE TWEAK round you hold: every line, task 1004322)
+//       node scripts/gds/copy-apply.js --batch --batch-file round.md --dry-run   (a local round; writes nothing)
+//       node scripts/gds/copy-apply.js                    (the task you are HOLDING — the normal call)
 //       node scripts/gds/copy-apply.js --dry-run          (say what would change, write nothing)
 //       node scripts/gds/copy-apply.js --task 1234        (a claim you hold, when you hold more than one)
 //       node scripts/gds/copy-apply.js --patch-file p.json  (a local patch — used by the tests)
@@ -53,9 +55,12 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
 
 const ci = require('./copy-inventory.js');
 const proposals = require('../../modules/copy-desk/proposals.js');
+// The page tweak format's one reader and writer (ADR 0341 D4), for --batch.
+const pages = require('../../modules/copy-desk/pages.js');
 const { apiCall, arg, hasFlag, cliExit } = require('./cli-lib.js');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -305,11 +310,275 @@ async function loadPatch({ taskId, patchFile }) {
   return { ok: true, patch: parsed.patch, task };
 }
 
+
+// ---------------------------------------------------------------------------
+// --batch: a whole PAGE at once (task 1004322 / BV2.TW11; ADR 0341 D4).
+//
+// A page tweak's round carries a ```page-tweak``` block: every line the artist
+// rewrote, frozen at submit, each with its reading key, its section, the text the
+// page showed (`before`), the artist's wording (`after`) and where the registry
+// placed it (`file`, `line`, `string_id`). --batch lands every line through the
+// SAME rules one proposal lands by (ADR 0233): the span is re-derived from the
+// tree as it stands, the `${expr}` holes go back in, and every doubt is a named
+// refusal. What is new is only that there are many lines, and so:
+//
+//   * A REFUSED LINE IS NAMED, NEVER SKIPPED. It goes in the applied block's
+//     `refused` list with its code, and the artist sees it at approval. The rest
+//     of the batch still lands (D4: "the batch lands with the lines that applied").
+//   * ORDER IS BY SOURCE POSITION, BOTTOM UP, per file. A rewrite can change how
+//     many lines a span covers, which would move every later line number; the
+//     line number is only ever a tie-breaker between duplicates, but applying from
+//     the bottom keeps even the tie-breaker true for every line still to come.
+//   * A READING LINE MAY BE PART OF A REGISTRY STRING. The page reader places a
+//     visible fragment on the registry row that contains it (a word inside a
+//     sentence built around a hole), so `before` is either the row's whole text
+//     or appears in it exactly once; the rewrite replaces that one occurrence.
+//     Anything else is `no_exact_span` (absent) or `ambiguous_target` (twice).
+//   * TWO LINES ON ONE STRING compose: the second is resolved against the text the
+//     first one left, never against the stale registry row.
+//
+// Then the command regenerates the registry, re-reads the changed pages
+// (page-reader.js --stale, which opens a browser) and writes the
+// ```page-tweak-applied``` block from the NEW reading: reading_hash_after and
+// lines_after (the page's non-shared lines, the baseline drift is measured from,
+// D8) plus the refused list.
+// ---------------------------------------------------------------------------
+
+const REFUSAL_CODES = Object.freeze(['target_gone', 'ambiguous_target', 'no_exact_span', 'placeholder_mismatch', 'path_outside_surface', 'unknown_surface', 'file_unreadable']);
+
+function countOccurrences(haystack, needle) {
+  if (!needle) return 0;
+  let n = 0;
+  for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + needle.length)) n += 1;
+  return n;
+}
+
+// Which registry row a batch line means. A string id is a hash of (surface,
+// text), so the same sentence in two files shares one id: the row in the line's
+// own file wins, the nearest to its line if that file has it twice. Pure.
+function registryRowFor(line, registryById) {
+  const rows = (line && line.string_id && registryById.get(line.string_id)) || [];
+  if (rows.length <= 1) return rows[0] || null;
+  const inFile = rows.filter((e) => e.file === line.file);
+  const pool = inFile.length ? inFile : rows;
+  if (pool.length === 1) return pool[0];
+  const near = (e) => Math.abs((e.line || 0) - (line.line || 0));
+  return pool.slice().sort((a, b) => near(a) - near(b))[0];
+}
+
+const rowKey = (e) => `${e.id}|${e.file}|${e.line}`;
+
+// One batch line -> the single-proposal patch shape (proposals.js), resolved
+// against the registry row its string_id names. `texts` carries a row's text as
+// earlier lines of this batch left it. Pure.
+function patchForBatchLine(line, registryById, texts = new Map()) {
+  const entry = registryRowFor(line, registryById);
+  if (!entry) {
+    return { ok: false, code: 'target_gone', detail: { string_id: line && line.string_id, what_this_means: 'The copy registry no longer has the string this line was placed on: the page changed after the artist submitted.' } };
+  }
+  const want = proposals.placeholderCount(line.before);
+  const got = proposals.placeholderCount(line.after);
+  if (want !== got) {
+    return { ok: false, code: 'placeholder_mismatch', detail: { expected: want, got, what_this_means: 'The rewrite does not keep the values the page drops into this line.' } };
+  }
+  const current = texts.has(rowKey(entry)) ? texts.get(rowKey(entry)) : entry.text;
+  let proposed;
+  if (current === line.before) proposed = line.after;
+  else {
+    const n = countOccurrences(current, line.before);
+    if (n === 0) return { ok: false, code: 'no_exact_span', detail: { file: entry.file, looked_for: line.before, in: current, what_this_means: 'The line the page shows cannot be found inside the string the registry placed it on, so no exact span exists.' } };
+    if (n > 1) return { ok: false, code: 'ambiguous_target', detail: { file: entry.file, occurrences: n, what_this_means: 'The line appears more than once inside its string, and the batch cannot say which one it meant.' } };
+    proposed = current.replace(line.before, () => line.after);
+  }
+  return {
+    ok: true,
+    patch: { row: rowKey(entry), surface: entry.surface, file: entry.file, line: entry.line, origin: entry.origin, current, proposed },
+  };
+}
+
+// applyBatchToSources({ batch, registry, readSource }) -> { applied, refused, sources }
+//
+// The whole batch, as a pure function of the registry and the files' current
+// contents (readSource(rel) returns a file's text or throws). Writes nothing.
+// `applied` and `refused` come back in PAGE order (the batch's own order);
+// `sources` maps each changed file to its new contents.
+function applyBatchToSources({ batch, registry, readSource }) {
+  const registryById = new Map();
+  for (const e of (registry && registry.entries) || []) {
+    if (!registryById.has(e.id)) registryById.set(e.id, []);
+    registryById.get(e.id).push(e);
+  }
+  const lines = ((batch && batch.lines) || []).map((l, i) => ({ ...l, order: i }));
+  const byId = (l) => registryRowFor(l, registryById);
+  // Bottom up per file, by the registry's line (the tree's truth, not the batch's).
+  const work = lines.slice().sort((a, b) => {
+    const ea = byId(a), eb = byId(b);
+    const fa = ea ? ea.file : '', fb = eb ? eb.file : '';
+    if (fa !== fb) return fa < fb ? -1 : 1;
+    return ((eb && eb.line) || 0) - ((ea && ea.line) || 0) || a.order - b.order;
+  });
+  const sources = new Map();
+  const texts = new Map();
+  const applied = [];
+  const refused = [];
+  const refuse = (l, r) => refused.push({ key: l.key, section: l.section == null ? null : l.section, before: l.before, code: r.code, detail: r.detail || {} });
+  for (const l of work) {
+    const p = patchForBatchLine(l, registryById, texts);
+    if (!p.ok) { refuse(l, p); continue; }
+    const guard = checkPatchPath(p.patch);
+    if (!guard.ok) { refuse(l, guard); continue; }
+    let source = sources.get(guard.rel);
+    if (source === undefined) {
+      try { source = readSource(guard.rel); } catch (err) { refuse(l, { code: 'file_unreadable', detail: { file: guard.rel, reason: err.message } }); continue; }
+    }
+    const out = applyPatchToSource(source, guard.rel, p.patch);
+    if (!out.ok) { refuse(l, out); continue; }
+    sources.set(guard.rel, out.source);
+    texts.set(p.patch.row, p.patch.proposed);
+    applied.push({ key: l.key, section: l.section == null ? null : l.section, file: guard.rel, line: out.line, before: out.before, after: out.after, proposed: p.patch.proposed, order: l.order });
+  }
+  const byOrder = (x, y) => x.order - y.order;
+  const orderOf = new Map(lines.map((l) => [l.key, l.order]));
+  refused.sort((x, y) => orderOf.get(x.key) - orderOf.get(y.key));
+  return { applied: applied.sort(byOrder).map(({ order, ...rest }) => rest), refused, sources };
+}
+
+// The ```page-tweak-applied``` block's content, from the page's NEW reading.
+// lines_after is the non-shared lines' texts: shared shell lines are left out of
+// drift on both sides (D8, builder pick 7), so they must be left out here too or
+// every one of them would read as "removed" on the next drift check.
+function appliedBlockFor({ pageId, readingPage, refused, appliedAt }) {
+  return {
+    page_id: pageId,
+    applied_at: appliedAt,
+    reading_hash_after: readingPage ? readingPage.reading_hash : null,
+    lines_after: readingPage ? (readingPage.lines || []).filter((l) => l && l.placement !== 'shared').map((l) => String(l.text)) : [],
+    refused: (refused || []).map((x) => ({ key: x.key, code: x.code })),
+  };
+}
+
+// Load the round's batch: the task you hold, or a local file (the tests' and the
+// dry run's entry point). A file may hold a whole round description or a bare
+// batch object; either way it goes through pages.parseBatchBlock, the one reader.
+async function loadBatch({ taskId, batchFile, readFile = (p) => fs.readFileSync(p, 'utf8'), api = apiCall }) {
+  let description;
+  if (batchFile) {
+    let raw;
+    try { raw = readFile(path.resolve(process.cwd(), batchFile)); } catch (err) { return { ok: false, code: 'batch_file_unreadable', detail: { reason: err.message } }; }
+    description = raw.trim().startsWith('{') ? ['```' + pages.FENCES.batch, raw.trim(), '```'].join('\n') : raw;
+  } else {
+    const res = await api('GET', `/api/bongos/tasks/${taskId}`);
+    if (!res.ok) return { ok: false, code: 'task_unreadable', detail: { task: taskId, status: res.status } };
+    const task = (res.data && res.data.task) || {};
+    if (task.source !== pages.SOURCE) return { ok: false, code: 'not_a_page_tweak', detail: { task: taskId, source: task.source || null, what_this_means: '--batch applies a page tweak round. For a single copy proposal, run this without --batch.' } };
+    description = task.description || '';
+  }
+  const parsed = pages.parseBatchBlock(description);
+  if (!parsed.ok) return parsed;
+  return { ok: true, batch: parsed.batch, description };
+}
+
+// Re-read the pages whose files the batch changed (page-reader.js --stale: this
+// page, and any other page sharing a changed file). Opens a browser.
+function rereadStalePages({ spawn = spawnSync } = {}) {
+  const r = spawn(process.execPath, [path.join(__dirname, 'page-reader.js'), '--stale'], { cwd: REPO_ROOT, stdio: 'inherit' });
+  return r.status === 0 ? { ok: true } : { ok: false, code: r.status === 3 ? 'no_browser' : 'reread_failed', detail: { exit: r.status } };
+}
+
+function readingFor(pageId, { readFile = (p) => fs.readFileSync(p, 'utf8') } = {}) {
+  try {
+    const doc = JSON.parse(readFile(path.join(REPO_ROOT, 'docs', 'page-readings.json')));
+    return (doc.pages || []).find((p) => p.id === pageId) || null;
+  } catch { return null; }
+}
+
+// Write the applied block into the round's description (replacing an earlier one:
+// a re-apply after a send-back supersedes it), through PATCH /tasks/:id.
+async function writeAppliedBlock({ taskId, description, block, api = apiCall }) {
+  const next = pages.replaceBlock(description, pages.FENCES.applied, pages.composeAppliedBlock(block));
+  if (!next.ok) return next;
+  const res = await api('PATCH', `/api/bongos/tasks/${taskId}`, { description: next.description });
+  if (!res.ok) return { ok: false, code: 'task_write_failed', detail: { task: taskId, status: res.status, what_this_means: 'The files are applied, but the round does not yet record it. PATCH /tasks/:id needs the task.edit permission (Metic+).' } };
+  return { ok: true };
+}
+
+// The --batch command. `deps` is the test seam: every read, write, re-read and API
+// call can be replaced, so the whole path runs against a fixture round.
+async function batchMain({ taskId, batchFile, dryRun, now = () => new Date().toISOString() }, deps = {}) {
+  const readFile = deps.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+  const writeFile = deps.writeFile || ((p, s) => fs.writeFileSync(p, s));
+  const api = deps.api || apiCall;
+  const log = deps.log || console.log;
+  const loaded = await loadBatch({ taskId, batchFile, readFile, api });
+  if (!loaded.ok) return refuse(loaded);
+  const { batch } = loaded;
+  const registry = deps.registry || JSON.parse(readFile(path.join(REPO_ROOT, 'docs', 'copy-registry.json')));
+  const result = applyBatchToSources({ batch, registry, readSource: (rel) => readFile(path.join(REPO_ROOT, rel)) });
+
+  log(`copy-apply --batch: ${batch.page_id}, ${batch.lines.length} line(s): ${result.applied.length} applied, ${result.refused.length} refused.`);
+  for (const a of result.applied) {
+    log(`  ${a.key} ${a.file}:${a.line}`);
+    log(`    -  ${a.before}`);
+    log(`    +  ${a.after}`);
+  }
+  for (const x of result.refused) {
+    log(`  ${x.key} REFUSED (${x.code})${x.detail && x.detail.what_this_means ? `: ${x.detail.what_this_means}` : ''}`);
+    log(`    line: ${JSON.stringify(x.before)}`);
+  }
+  if (dryRun) { log('copy-apply --batch: --dry-run, nothing written.'); return 0; }
+
+  for (const [rel, source] of result.sources) writeFile(path.join(REPO_ROOT, rel), source);
+  const { reg } = (deps.regenerateRegistry || (() => ci.write()))();
+  const missing = result.applied.filter((a) => !reg.entries.some((e) => e.file === a.file && e.text === a.proposed));
+  if (missing.length) {
+    console.error(`copy-apply --batch: WROTE THE FILES, but the regenerated registry does not contain the new wording for ${missing.map((m) => m.key).join(', ')}.`);
+    console.error('  An edit landed somewhere the inventory does not read as copy. Review `git diff` before doing anything else.');
+    return 3;
+  }
+  log(`copy-apply --batch: files written, registry regenerated (${reg.counts ? reg.counts.strings : reg.entries.length} strings).`);
+
+  const reread = (deps.reread || rereadStalePages)();
+  if (!reread.ok) {
+    console.error(`copy-apply --batch: the page could not be re-read (${reread.code}). The files are applied; run node scripts/gds/page-reader.js --stale, then this command again to write the applied block.`);
+    return 4;
+  }
+  const readingPage = (deps.readingFor || ((id) => readingFor(id, { readFile })))(batch.page_id);
+  const block = appliedBlockFor({ pageId: batch.page_id, readingPage, refused: result.refused, appliedAt: now() });
+  if (batchFile) {
+    log('copy-apply --batch: the page-tweak-applied block (a --batch-file run writes no task):');
+    log(pages.composeAppliedBlock(block));
+  } else {
+    const wrote = await writeAppliedBlock({ taskId, description: loaded.description, block, api });
+    if (!wrote.ok) return refuse(wrote);
+    log(`copy-apply --batch: recorded the page-tweak-applied block on task ${taskId} (reading ${block.reading_hash_after}, ${block.lines_after.length} lines, ${block.refused.length} refused).`);
+  }
+  if (!result.applied.length) {
+    console.error('copy-apply --batch: NO line applied. Every refusal is recorded; there is nothing to ship until they are resolved.');
+    return 2;
+  }
+  log('  Review with `git diff`, render the page, then ship this task the normal way (it waits for the artist).');
+  return 0;
+}
+
 async function main() {
   let taskId = arg('--task');
   const patchFile = arg('--patch-file');
   const dryRun = hasFlag('--dry-run');
 
+  // --batch (task 1004322): a page tweak round. The claim gate is the same one the
+  // single proposal uses; --batch-file is the local, claim-free entry point, and
+  // like --patch-file it lands nothing a task authorised.
+  if (hasFlag('--batch')) {
+    const batchFile = arg('--batch-file');
+    if (!batchFile) {
+      const held = taskId ? await claimOnTask(taskId) : await claimedTaskId();
+      if (!held.ok) return cliExit(refuse(held));
+      taskId = held.taskId;
+      console.log(`copy-apply --batch: the round you are holding — task ${taskId}`);
+    }
+    return cliExit(await batchMain({ taskId, batchFile, dryRun }));
+  }
+
   if (!taskId && !patchFile) {
     const held = await claimedTaskId();
     if (!held.ok) return cliExit(refuse(held));
@@ -379,6 +648,13 @@ if (require.main === module) {
 }
 
 module.exports = {
+  // task 1004322: --batch, a page tweak round.
+  REFUSAL_CODES,
+  registryRowFor,
+  patchForBatchLine,
+  applyBatchToSources,
+  appliedBlockFor,
+  batchMain,
   surfaceRootFor,
   checkPatchPath,
   locateOccurrence,

package/scripts/gds/page-reader.js

@@ -671,4 +671,6 @@ module.exports = {
   filesHash, readingHash, buildMatcher, placeText, collectStrings, holeData,
   mergeStates, assembleReading, serialize, buildDoc, checkReadings, planRenders,
   captureInPage, mergeReadings,
+  // task 1004322: /tweak renders the page the reader reads, through the same harness.
+  startHarness, SURFACE_MODULE, PINNED_CLOCK,
 };

package/scripts/gds/ship-finish.js

@@ -17,7 +17,8 @@ const { uploadSessionOnShip } = require('./ship-session-upload.js');
 const { gitOk, shellOk } = require('./ship-git.js');
 const { fetchDeployedVersion } = require('./ship-deploy-target.js');
 const { landBailed, reconciledCardStatus } = require('./ship-land.js');
-const { autoMerge } = require('./ship-merge.js');
+const { autoMerge, publishHeld } = require('./ship-merge.js');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
 const { normalizeApiError, playShipBell, postLandShipOutcome } = require('./ship-io.js');
 const { getServerReward, noteServerReward } = require('./ship-state.js');
 
@@ -176,7 +177,10 @@ function postShipCloseout(taskId) {
   }
 }
 
-async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine, card, dbOnly = false }) {
+async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine, card, dbOnly = false, held = false }) {
+  // task 1004322 (ADR 0341 D7): a page tweak whose grade passed is HELD for its
+  // artist. It publishes its branch and PR and stops; nothing merges.
+  if (held) return finishHeld({ taskId, summary, postGradeStatus, card });
   // task 1002541: the land outcome carries WHY a land didn't happen. Without it
   // the card had only the status to go on and printed 'landing automatically'
   // over a merge that had already bailed.
@@ -226,6 +230,26 @@ async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGrad
   }
 }
 
+// finishHeld — the tail of a held pass (task 1004322). The session is finished
+// work, so it syncs exactly as a confirmed ship does (the applier's session
+// reward is computed from the upload, and pays on land). No bell and no tree
+// close-out: nothing landed, and a send-back brings the round back to be
+// re-applied. `deps` is a test seam only.
+async function finishHeld({ taskId, summary, postGradeStatus, card }, deps = {}) {
+  console.log('');
+  console.log('Publishing the applied branch for the artist (ADR 0341 D7):');
+  const land = await (deps.publishHeld || publishHeld)(taskId, summary);
+  if (land && land.held) {
+    for (const line of tweakHold.heldLines(taskId, { prUrl: land.prUrl })) console.log(line);
+  } else {
+    console.error(`  The branch did not publish${land && land.reason ? `: ${land.reason}` : ''}. The task stays at completed with its passed grade.`);
+    console.error(`  Re-run to publish it again (the grade is not re-run): node scripts/gds/ship.js ${taskId}`);
+  }
+  const usage = await (deps.postShipSync || postShipSync)(taskId, 'confirmed');
+  await (deps.printCompletionCard || printCompletionCard)({ taskId, postGradeStatus, card, usage, land });
+  return land;
+}
+
 // task 1275: sum the committed diffstat (added/removed lines) over baseline...HEAD.
 // Shared by the completion card and the in-review card. Best-effort: returns
 // nulls when there's no baseline or git is unavailable.
@@ -377,6 +401,7 @@ async function printCompletionCard({ taskId, postGradeStatus, card, usage, land
 module.exports = {
   diffstatFor,
   finishShip,
+  finishHeld,
   mergeAndDeploy,
   onboardingNudgeBestEffort,
   postShipSync,

package/scripts/gds/ship-flow.js

@@ -27,6 +27,7 @@ const { apiErrorLine, normalizeApiError, isUnknownFieldRejection } = require('./
 const { pushVia } = require('./ship-deploy-target.js');
 
 const { diffstatFor, finishShip } = require('./ship-finish.js');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
 const { evaluateRegradeEligibility, evaluateResumeAction, resumeMerge, shouldConfirmWithoutGrade } = require('./ship-resume.js');
 const { fileNoArtifactEscalation, noArtifactRefusalLines } = require('./ship-escalation.js');
 const { noteServerReward } = require('./ship-state.js');
@@ -583,6 +584,7 @@ async function shipMain() {
   let postGradeJustUnlocked = r.data.just_unlocked || [];
   let gradePassed = false;
   let advanceToMerge = false;
+  let held = false; // task 1004322: a page tweak's pass, held for its artist (ADR 0341 D7)
   let gradeObj = null; // task 1270: the grade result, hoisted for the completion card
   // V3.R27 (#247): credit breakdown surfaced from the grade or confirm
   // response. Kept separate from `credits` so we only print the multiplier
@@ -696,6 +698,7 @@ async function shipMain() {
     gradeObj = g;
     gradePassed = g.passed;
     advanceToMerge = gradePost.data.advanceToMerge;
+    held = gradePost.data.held === true;
     postGradeStatus = gradePost.data.taskStatus;
     credits = gradePost.data.creditsAwarded;
     postGradeJustUnlocked = gradePost.data.just_unlocked || [];
@@ -726,7 +729,7 @@ async function shipMain() {
     markShipProgress(postGradeStatus === 'shipped' ? 'landed' : 'graded', taskId);
   }
   await finishShip({
-    taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly,
+    taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly, held,
     // task 1270: data for the deterministic completion card.
     card: {
       title: ac.title,
@@ -895,6 +898,18 @@ async function regradeMain() {
     console.error(`  node scripts/gds/ship.js ${taskId} --verified`);
     process.exit(1);
   }
+  // task 1004322 (ADR 0341 D7): a page tweak already HELD for its artist has a
+  // passed grade. A plain re-run lands here (completed -> resume-grade), and
+  // re-grading would spend the panel again for the verdict it already has, so it
+  // only re-publishes the branch (the recovery for a publish that failed).
+  if (tweakHold.isHeldForArtist(task, tRes.data.grade ? tRes.data.grade.passed : null)) {
+    console.log(`Task #${taskId} already passed its grade and is waiting for the artist: re-publishing its branch, not re-grading.`);
+    await finishShip({
+      taskId, summary: summaryArg || task.value_summary || '', held: true, postGradeStatus: 'completed', doneLine: 'Done.',
+      card: { title: task.title, valueSummary: summaryArg || task.value_summary || '', notes: '' },
+    });
+    return;
+  }
   console.log(`Re-grading task #${taskId}: ${task.title}`);
   console.log(`  eligibility: ${elig.reason} (${elig.via})`);
 
@@ -1101,6 +1116,7 @@ async function regradeMain() {
   // normal ship (finishShip, #1093/C9) so a re-grade lands identically.
   await finishShip({
     taskId, summary, advanceToMerge: gradePost.data.advanceToMerge, skipMerge, dbOnly,
+    held: gradePost.data.held === true, // task 1004322: a page tweak's pass waits for its artist
     postGradeStatus,
     doneLine: g.passed ? 'Done — re-grade passed.' : 'Done — re-grade still failing; fix and try again.',
     // task 1270: completion card for the re-grade path too.