@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/copy-apply.js

@@ -0,0 +1,758 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/copy-apply.js — land a copy proposal as a real diff (R03 of goal
+// 1000074, the artist's loop; task 1003114).
+//
+// WHAT IT IS FOR. R03's done-when is that "an artist with no terminal can propose
+// a copy change that reaches main through a claim". The copy desk gives them the
+// first half: a proposal becomes a GDS task carrying a patch
+// (modules/copy-desk/proposals.js). This command is the second half — the thing
+// whoever claims that task runs. It is the direct analogue of `adapter.export()`
+// in the design half (ADR 0081, modules/ui-design/adapters/*): tool output lands
+// in the repo as a committed diff under a claim, with a path guard, and the repo
+// stays the source of truth. Nothing about the copy path bypasses the ledger,
+// because this command IS the ledger's hands.
+//
+// WHY IT RE-DERIVES INSTEAD OF TRUSTING THE PATCH. The patch names a file and a
+// line, but a line number is stale the moment anything above it changes, and the
+// registry's committed rows deliberately carry no character offsets (see the
+// note in copy-inventory.js's buildRegistry). So this re-runs R01's OWN
+// extractor over the working tree and finds the occurrence there. One set of
+// matching rules, in one file, used by both the inventory and the applier —
+// which is what stops this command from editing a byte the inventory would never
+// have called copy.
+//
+// THE REFUSALS ARE THE FEATURE. A copy change that lands on the wrong characters
+// is worse than one that does not land, so every ambiguity is a named refusal
+// with the reason on one line: the string is gone, it moved and is no longer
+// unique, its literal is escaped so no exact span exists, the placeholder
+// 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/bongos/copy-apply.js --batch            (a PAGE TWEAK round you hold: every line, task 1004322)
+//       node scripts/bongos/copy-apply.js --batch --batch-file round.md --dry-run   (a local round; writes nothing)
+//       node scripts/bongos/copy-apply.js --batch --page <id> --unattended   (the auto-pickup worker: exit 5 = wrong page; any non-zero exit releases the round, task 1004678)
+//       node scripts/bongos/copy-apply.js                    (the task you are HOLDING — the normal call)
+//       node scripts/bongos/copy-apply.js --dry-run          (say what would change, write nothing)
+//       node scripts/bongos/copy-apply.js --task 1234        (a claim you hold, when you hold more than one)
+//       node scripts/bongos/copy-apply.js --patch-file p.json  (a local patch — used by the tests)
+//
+// WHY THE BARE FORM DEFAULTS TO YOUR CLAIM rather than taking an id. The task a
+// proposal creates has to print the exact line that lands it, and it cannot know
+// its own id at the moment its description is written. Every workaround for that
+// is worse than the rule it would paper over: this command may only be run under
+// a claim (that is the whole point of the feature), and a claim already names a
+// task. So the bare call reads the claim, and holding no claim is a refusal that
+// says to go and claim the task — the methodology's own rule, enforced by the
+// command instead of restated in its output.
+//
+// --task DOES NOT OPT OUT OF THAT (task 1003493). It selects which of your
+// claims to act under when you hold several; it is checked against the same
+// /me claim list the bare call reads, and refuses `claim_not_held` for a task
+// you do not hold. The one path that never touches a task is --patch-file,
+// which reads a local JSON patch and is the tests' entry point — it lands
+// nothing a proposal task authorised, so there is no claim for it to prove.
+
+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, '..', '..');
+const PLACEHOLDER = proposals.PLACEHOLDER;
+
+// ---------------------------------------------------------------------------
+// PURE below this line, down to `main`. The tests drive these directly with
+// string sources — no fs, no network, no task.
+// ---------------------------------------------------------------------------
+
+// THE PATH GUARD, and it is the same rule the design adapter enforces: an export
+// may only write inside the surfaces the contract knows about. Here the surface
+// roots come from R01's own SURFACES table, so a patch can only ever touch a
+// directory the inventory actually walks. A patch naming anything else — a
+// traversal, a config file, a migration — is refused before a single byte is
+// read, not after.
+function surfaceRootFor(surfaceId) {
+  const surface = ci.SURFACES.find((s) => s.id === surfaceId);
+  return surface ? surface.at : null;
+}
+
+function checkPatchPath(patch) {
+  const root = surfaceRootFor(patch.surface);
+  if (!root) return { ok: false, code: 'unknown_surface', detail: { surface: patch.surface, known: ci.SURFACES.map((s) => s.id) } };
+  // Compare normalized, repo-relative, forward-slash paths — the same form the
+  // registry stores — and require the file to sit under its surface's root.
+  const rel = String(patch.file).replace(/\\/g, '/');
+  const abs = path.resolve(REPO_ROOT, rel);
+  const rootAbs = path.resolve(REPO_ROOT, root);
+  if (!abs.startsWith(rootAbs + path.sep)) {
+    return {
+      ok: false,
+      code: 'path_outside_surface',
+      detail: { file: rel, surface: patch.surface, must_be_under: root },
+    };
+  }
+  return { ok: true, rel, abs };
+}
+
+// Find the one occurrence this patch is about, in the tree as it stands now.
+//
+// Matching is on (origin, current text) within the file, NOT on the line: a line
+// number is the first thing to go stale, and the registry id is explicitly
+// designed to survive a string moving. The line is used only to disambiguate
+// when the same sentence appears at several sites in one file — which is the
+// duplicate case R01 already reports, and where guessing would be indefensible.
+function locateOccurrence(source, rel, patch) {
+  const rows = (path.extname(rel) === '.html'
+    ? ci.fromHtml({ source, rel })
+    : ci.fromJs({ source, rel }))
+    .filter((r) => r.origin === patch.origin && r.text === patch.current);
+
+  if (!rows.length) {
+    return {
+      ok: false,
+      code: 'target_gone',
+      detail: {
+        file: rel,
+        looked_for: patch.current,
+        what_this_means: 'That exact wording is no longer in this file — it has already been edited, or the proposal was written against an older tree. Nothing was changed. Re-read the string on the copy desk and propose again if it still needs work.',
+      },
+    };
+  }
+  let row = rows[0];
+  if (rows.length > 1) {
+    const onLine = rows.filter((r) => r.line === patch.line);
+    if (onLine.length !== 1) {
+      return {
+        ok: false,
+        code: 'ambiguous_target',
+        detail: {
+          file: rel,
+          occurrences: rows.length,
+          lines: rows.map((r) => r.line),
+          what_this_means: 'This sentence appears more than once in this file and the proposal cannot say which one it meant. That is the duplicate case the copy desk reports — decide whether they should all change, and land it as an ordinary edit under this claim.',
+        },
+      };
+    }
+    row = onLine[0];
+  }
+  if (row.start === undefined) {
+    return {
+      ok: false,
+      code: 'no_exact_span',
+      detail: {
+        file: rel,
+        line: row.line,
+        what_this_means: 'This string lives inside an escaped quoted literal, so the inventory cannot point at its exact characters and this command will not guess. Edit it by hand under this claim.',
+      },
+    };
+  }
+  return { ok: true, row };
+}
+
+// Rebuild the replacement text, re-injecting the source's own interpolations.
+//
+// The registry writes `{…}` where the source has `${expr}`, so the artist edits a
+// readable sentence with holes in it. Landing it means putting the ORIGINAL
+// expressions back, in order — the k-th hole takes the k-th expression. The
+// count was already checked when the proposal was made; it is checked again here
+// against the real source, because the source is what is about to be written.
+function reinjectInterpolations(rawSpan, proposedText) {
+  const expressions = String(rawSpan).match(/\$\{[^{}]*\}/g) || [];
+  const holes = proposals.placeholderCount(proposedText);
+  if (holes !== expressions.length) {
+    return {
+      ok: false,
+      code: 'placeholder_mismatch',
+      detail: {
+        expected: expressions.length,
+        got: holes,
+        placeholder: PLACEHOLDER,
+        what_this_means: 'The values this sentence drops in at render time do not line up with the proposed wording. Nothing was changed.',
+      },
+    };
+  }
+  let out = '';
+  let rest = String(proposedText);
+  for (const expr of expressions) {
+    const at = rest.indexOf(PLACEHOLDER);
+    out += rest.slice(0, at) + expr;
+    rest = rest.slice(at + PLACEHOLDER.length);
+  }
+  return { ok: true, text: out + rest };
+}
+
+// The whole edit, as a pure function of the file's current contents and a patch.
+// Returns the new source — or a named refusal. Writes nothing.
+function applyPatchToSource(source, rel, patch) {
+  const located = locateOccurrence(source, rel, patch);
+  if (!located.ok) return located;
+  const { row } = located;
+  const rawSpan = source.slice(row.start, row.end);
+  const rebuilt = reinjectInterpolations(rawSpan, patch.proposed);
+  if (!rebuilt.ok) return rebuilt;
+  return {
+    ok: true,
+    line: row.line,
+    before: rawSpan,
+    after: rebuilt.text,
+    source: source.slice(0, row.start) + rebuilt.text + source.slice(row.end),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The command.
+// ---------------------------------------------------------------------------
+
+function refuse(result) {
+  const detail = result.detail || {};
+  console.error(`copy-apply: REFUSED (${result.code})`);
+  if (detail.what_this_means) console.error(`  ${detail.what_this_means}`);
+  for (const [k, v] of Object.entries(detail)) {
+    if (k === 'what_this_means') continue;
+    console.error(`  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+  }
+  return 2;
+}
+
+// Every claim this session holds. One reader, so the bare call and --task are
+// answered from the same source of truth — the shape of bug where a rule is
+// enforced on one path and merely stated on the other (task 1003493).
+async function activeClaims() {
+  const me = await apiCall('GET', '/api/bongos/me');
+  if (!me.ok) return { ok: false, code: 'no_session', detail: { status: me.status, run: 'node scripts/bongos/setup.js' } };
+  return { ok: true, claims: me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []) };
+}
+
+// --task <id> names a task; this proves the caller actually HOLDS it. Without
+// this the header's "may only be run under a claim" was true of the bare call
+// and false of the named one — a rule stated three times in prose (here, ADR
+// 0233, modules/copy-desk/CLAUDE.md) and enforced on one of two paths. The
+// refusal names the claims you do hold, because the usual cause is a typo'd id.
+// Pure so the gate is testable without a session: given the id asked for and
+// the claims held, either accept or produce the named refusal.
+function claimGateFor(taskId, claims) {
+  const wanted = String(taskId);
+  const held = (claims || []).map((c) => String(c.task_id));
+  if (held.includes(wanted)) return { ok: true, taskId: wanted };
+  return {
+    ok: false,
+    code: 'claim_not_held',
+    detail: {
+      task: wanted,
+      held,
+      what_this_means: `A copy change lands under a claim like every other change, and you do not hold one on #${wanted}. Claim it first (node scripts/bongos/claim.js ${wanted}), then run this again.`,
+    },
+  };
+}
+
+async function claimOnTask(taskId) {
+  const held = await activeClaims();
+  if (!held.ok) return held;
+  return claimGateFor(taskId, held.claims);
+}
+
+// The task this session is holding. Returns a named refusal rather than an id
+// when there is nothing to act under — "claim it first" is the correct answer,
+// not an inconvenience to route around.
+async function claimedTaskId() {
+  const held = await activeClaims();
+  if (!held.ok) return held;
+  const claims = held.claims;
+  if (!claims.length) {
+    return {
+      ok: false,
+      code: 'no_active_claim',
+      detail: {
+        what_this_means: 'A copy change lands under a claim like every other change. Claim the proposal task first (node scripts/bongos/claim.js <id>), then run this again — or name one with --task <id>.',
+      },
+    };
+  }
+  if (claims.length > 1) {
+    return {
+      ok: false,
+      code: 'several_active_claims',
+      detail: {
+        held: claims.map((c) => c.task_id),
+        what_this_means: 'You hold more than one claim, so this command will not guess which proposal you meant. Name it with --task <id>.',
+      },
+    };
+  }
+  return { ok: true, taskId: claims[0].task_id };
+}
+
+async function loadPatch({ taskId, patchFile }) {
+  if (patchFile) {
+    let raw;
+    try {
+      raw = fs.readFileSync(path.resolve(process.cwd(), patchFile), 'utf8');
+    } catch (err) {
+      return { ok: false, code: 'patch_file_unreadable', detail: { reason: err.message } };
+    }
+    // A bare patch file is still parsed through the SAME reader the task path
+    // uses, so the local shortcut can never accept a shape the real path rejects.
+    return proposals.parseProposalBlock(raw.trim().startsWith('{')
+      ? ['```' + proposals.FENCE, raw.trim(), '```'].join('\n')
+      : raw);
+  }
+  const res = await apiCall('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) || {};
+  const parsed = proposals.parseProposalBlock(task.description || '');
+  if (!parsed.ok) return parsed;
+  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}`;
+
+// The {{token}} brand holes in a line, sorted (a hole may move within the line).
+function brandHoles(text) {
+  return (String(text == null ? '' : text).match(/\{\{[A-Za-z][A-Za-z0-9_]*\}\}/g) || []).sort();
+}
+
+// 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.' } };
+  }
+  // A {{token}} is a brand hole the server fills at serve time (ADR 0233's hole
+  // rule, for the instance's names; task 1004381). It is written back VERBATIM,
+  // so the same tokens must survive the rewrite: a dropped one would bake a
+  // brand value (or nothing) into brand-free source.
+  const wantHoles = brandHoles(line.before);
+  const gotHoles = brandHoles(line.after);
+  if (wantHoles.join('|') !== gotHoles.join('|')) {
+    return { ok: false, code: 'placeholder_mismatch', detail: { expected: wantHoles, got: gotHoles, what_this_means: 'The rewrite drops or adds a name the page fills in from the instance\'s branding ({{productName}} and the like).' } };
+  }
+  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 };
+}
+
+// findPinningTests({ applied, listTests, readFile }) -> [{ key, tests: [rel…] }]
+//
+// Task 1004775. A test that asserts a line's OLD words verbatim goes red the
+// moment the round lands, which used to surface only in CI, after the artist had
+// approved, and needed a person. So at APPLY time every applied line's old text is
+// searched for in the test files (tests/ and every module's own tests folder), and each test that
+// still carries it is named in the applied block and shown in the Approval queue.
+// Nothing is edited: a test may be guarding what the words MEAN, and only a person
+// can tell that apart from a test that pins the wording alone.
+//
+// The needle is the line's old text; where it has {…} holes, its longest literal
+// run between them, and a needle under MIN_PIN_NEEDLE characters is skipped (a
+// two-word label matches half the suite and would name nothing useful).
+const MIN_PIN_NEEDLE = 12;
+const PIN_TEST_RE = /\.(mjs|cjs|js)$/;
+
+function pinNeedle(text) {
+  const runs = String(text == null ? '' : text).split('{…}').map((s) => s.trim());
+  const longest = runs.reduce((a, b) => (b.length > a.length ? b : a), '');
+  return longest.length >= MIN_PIN_NEEDLE ? longest : null;
+}
+
+function listTestFiles({ root = REPO_ROOT, fsImpl = fs } = {}) {
+  const out = [];
+  const walk = (rel) => {
+    let ents;
+    try { ents = fsImpl.readdirSync(path.join(root, rel), { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const r = `${rel}/${e.name}`;
+      if (e.isDirectory()) { if (e.name !== 'node_modules' && e.name !== 'fixtures') walk(r); } else if (PIN_TEST_RE.test(e.name)) out.push(r);
+    }
+  };
+  walk('tests');
+  let mods = [];
+  try { mods = fsImpl.readdirSync(path.join(root, 'modules'), { withFileTypes: true }); } catch { mods = []; }
+  for (const m of mods) if (m.isDirectory()) walk(`modules/${m.name}/tests`);
+  return out.sort();
+}
+
+function findPinningTests({ applied, listTests = listTestFiles, readFile = (rel) => fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8') }) {
+  const wants = (applied || []).map((a) => ({ key: a.key, needle: pinNeedle(a.before) })).filter((w) => w.needle);
+  if (!wants.length) return [];
+  const hits = new Map();
+  for (const rel of listTests()) {
+    let src;
+    try { src = readFile(rel); } catch { continue; }
+    for (const w of wants) {
+      if (!src.includes(w.needle)) continue;
+      if (!hits.has(w.key)) hits.set(w.key, []);
+      hits.get(w.key).push(rel);
+    }
+  }
+  return wants.filter((w) => hits.has(w.key)).map((w) => ({ key: w.key, tests: hits.get(w.key) }));
+}
+
+// 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, pinnedTests = [] }) {
+  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 })),
+    ...(pinnedTests && pinnedTests.length ? { pinned_tests: pinnedTests.map((p) => ({ key: p.key, tests: p.tests.slice() })) } : {}),
+  };
+}
+
+// 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, pageId = null, 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;
+  // --page (task 1004678, ADR 0371 D8): the unattended worker names the page it was
+  // given, and a round for any other page is refused before a file is touched.
+  if (pageId && batch.page_id !== pageId) {
+    refuse({ ok: false, code: 'wrong_page', detail: { task: taskId, expected: pageId, round_page: batch.page_id, what_this_means: 'This round belongs to a different page than the one named with --page. Nothing was written.' } });
+    return 5;
+  }
+  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}`);
+  }
+  // task 1004776: the submit's guarded-line warnings, so whoever applies sees them too.
+  for (const w of batch.warnings || []) log(`  ${w.key} WARNING: no longer says what it must: ${w.must_still_say}${w.guarded_by ? ` (guarded by ${w.guarded_by})` : ''}`);
+  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/bongos/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 oldText = new Map(batch.lines.map((l) => [l.key, l.before]));
+  const pinnedTests = (deps.findPinningTests || findPinningTests)({ applied: result.applied.map((a) => ({ key: a.key, before: oldText.get(a.key) })) });
+  for (const p of pinnedTests) log(`  ${p.key} the old words are still asserted by: ${p.tests.join(', ')} (update the test or it fails once this lands)`);
+  const block = appliedBlockFor({ pageId: batch.page_id, readingPage, refused: result.refused, appliedAt: now(), pinnedTests });
+  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}`);
+    }
+    // --page <id> --unattended (task 1004678, ADR 0371 D8): never asks, and any exit
+    // that is not a clean apply releases the round with a plain note (tweak-halt.js).
+    const pageId = arg('--page') || null;
+    const code = await batchMain({ taskId, batchFile, dryRun, pageId });
+    if (hasFlag('--unattended') && code !== 0 && taskId && !batchFile && !dryRun) {
+      const halt = require('./tweak-halt');
+      halt.releaseWithNote(taskId, halt.haltForCopyApplyExit(code));
+    }
+    return cliExit(code);
+  }
+
+  if (!taskId && !patchFile) {
+    const held = await claimedTaskId();
+    if (!held.ok) return cliExit(refuse(held));
+    taskId = held.taskId;
+    console.log(`copy-apply: the task you are holding — #${taskId}`);
+  } else if (taskId) {
+    // --task picks WHICH claim to act under; it never substitutes for holding one.
+    const held = await claimOnTask(taskId);
+    if (!held.ok) return cliExit(refuse(held));
+    taskId = held.taskId;
+  }
+
+  const loaded = await loadPatch({ taskId, patchFile });
+  if (!loaded.ok) return cliExit(refuse(loaded));
+  const { patch } = loaded;
+
+  const guard = checkPatchPath(patch);
+  if (!guard.ok) return cliExit(refuse(guard));
+
+  let source;
+  try {
+    source = fs.readFileSync(guard.abs, 'utf8');
+  } catch (err) {
+    return cliExit(refuse({ code: 'file_unreadable', detail: { file: guard.rel, reason: err.message } }));
+  }
+
+  const applied = applyPatchToSource(source, guard.rel, patch);
+  if (!applied.ok) return cliExit(refuse(applied));
+
+  console.log(`copy-apply: ${guard.rel}:${applied.line} (${patch.origin})`);
+  console.log(`  -  ${applied.before}`);
+  console.log(`  +  ${applied.after}`);
+
+  if (dryRun) {
+    console.log('copy-apply: --dry-run, nothing written.');
+    return cliExit(0);
+  }
+
+  fs.writeFileSync(guard.abs, applied.source);
+
+  // Regenerate the inventory in the same breath. The registry is a committed
+  // artifact whose CI check fails on drift, so an applier that edited a surface
+  // and left the registry describing the old tree would hand the builder a
+  // red build and a puzzle. It also gives us the verification below.
+  const { reg } = ci.write();
+
+  // VERIFY OUR OWN WORK, because a copy change that lands on the wrong characters
+  // is the failure this whole command is shaped to avoid — and the registry we
+  // just rebuilt is an independent read of the file we just wrote.
+  const nowThere = reg.entries.some((e) => e.file === guard.rel && e.text === patch.proposed);
+  if (!nowThere) {
+    console.error('copy-apply: WROTE THE FILE, but the regenerated registry does not contain the new wording at that path.');
+    console.error('  The edit landed somewhere the inventory does not read as copy. Review `git diff` before doing anything else.');
+    return cliExit(3);
+  }
+
+  console.log(`copy-apply: applied, registry regenerated (${reg.counts.strings} strings).`);
+  console.log('  Review with `git diff`, then ship this task the normal way.');
+  return cliExit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`copy-apply: ${err && err.message ? err.message : err}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  // task 1004322: --batch, a page tweak round.
+  REFUSAL_CODES,
+  registryRowFor,
+  patchForBatchLine,
+  applyBatchToSources,
+  appliedBlockFor,
+  batchMain,
+  // task 1004775: tests that still assert a rewritten line's old words.
+  findPinningTests,
+  listTestFiles,
+  pinNeedle,
+  surfaceRootFor,
+  checkPatchPath,
+  locateOccurrence,
+  reinjectInterpolations,
+  applyPatchToSource,
+  claimGateFor,
+};