@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/copy-apply.js

@@ -1,758 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/copy-apply.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/copy-apply.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-//
-// scripts/gds/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/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 --batch --page <id> --unattended   (the auto-pickup worker: exit 5 = wrong page; any non-zero exit releases the round, task 1004678)
-//       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)
-//
-// 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/gds/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/gds/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/gds/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/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 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,
-};
+require('../bongos/forwarder.js').forward(module, 'copy-apply.js');