altalandi 0.6.0 → 0.6.2

package/batch.mjs

@@ -1,620 +1,769 @@
-// `altalandi <folder | url>`: refine a whole folder of documents, one web page
-// or a site in one command, and write the Icelandic next to the original.
-//
-// The order of things is the safety story:
-//   1. plan      read every document and cut it into passages (segment.mjs,
-//                web.mjs); nothing is sent yet
-//   2. estimate  files, passages, characters and billing units, printed before
-//                anything is sent
-//   3. consent   a y/N question in a terminal, or --yes; with neither, nothing
-//                is sent (--dry-run stops here on purpose)
-//   4. refine    one call per passage, 2 at a time by default; a 429 waits for
-//                Retry-After, a 402 stops the run cleanly
-//   5. write     each file once all its passages are back; a passage whose
-//                meaning check did not pass keeps its original text; nothing is
-//                ever written inside the input
-//   6. report    one Markdown summary of every file and every change
-//
-// Every side effect is injectable (io), so the tests need no network, terminal
-// or API key.
-
-import { existsSync, statSync } from "node:fs";
-import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
-import path from "node:path";
-
-import { refine } from "./client.mjs";
-import { writeBatchReport } from "./report.mjs";
-import { assemble, FORMATS, isConfigJson, repairCodeSpans, segment, segmentMarkdown, splitForApi } from "./segment.mjs";
-import { pagePath, readPage, readSite, safeSegment, userAgent } from "./web.mjs";
-
-export const EXIT_OK = 0;
-export const EXIT_ERROR = 1;
-export const EXIT_KEPT = 2; // finished, but some passages kept their original text
-export const EXIT_CREDIT = 4; // stopped: out of credit or allowance (as for a single text)
-
-// altalandi-reports: the reports of earlier runs are not documents to refine.
-const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "altalandi-reports"]);
-const MAX_FILE_BYTES = 5 * 1024 * 1024;
-const MAX_RETRY_WAIT_MS = 5 * 60_000; // a longer Retry-After means "come back later"
-const MAX_RATE_LIMIT_RETRIES = 8;
-const MAX_TRANSIENT_RETRIES = 2;
-const ERRORS_IN_A_ROW_TO_STOP = 3;
-const DOMAINS = ["general", "marketing", "data-analysis", "childrens-fiction"];
-const REGISTERS = ["formal", "neutral", "warm"];
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const fmt = (n) => Math.round(n).toLocaleString("en-US");
-const plural = (n, one, many) => `${fmt(n)} ${n === 1 ? one : many}`;
-const fold = (p) => (process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p);
-const samePath = (a, b) => fold(path.resolve(a)) === fold(path.resolve(b));
-const isInside = (child, parent) => {
-  const rel = path.relative(fold(path.resolve(parent)), fold(path.resolve(child)));
-  return Boolean(rel) && !rel.startsWith("..") && !path.isAbsolute(rel);
-};
-const display = (p, cwd) => {
-  const rel = path.relative(cwd, p);
-  return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : p;
-};
-const preview = (s, n = 72) => {
-  const one = String(s).replace(/\s+/g, " ").trim();
-  return one.length > n ? `${one.slice(0, n - 1)}…` : one;
-};
-
-/** Every whitespace token is at least one billing unit; a long unbroken token
- *  is one unit per 20 characters (the server's rule, docs/api/README.md). */
-const billingTokens = (text) => text.split(/\s+/).filter(Boolean)
-  .reduce((n, t) => n + Math.max(1, Math.ceil(t.length / 20)), 0);
-
-/** The real path of p, or of its deepest existing ancestor plus the rest, so a
- *  symlinked --out is compared where it really points. */
-async function realish(p) {
-  const abs = path.resolve(p);
-  const rest = [];
-  let probe = abs;
-  for (;;) {
-    try {
-      return path.join(await realpath(probe), ...rest.reverse());
-    } catch {
-      const parent = path.dirname(probe);
-      if (parent === probe) return abs;
-      rest.push(path.basename(probe));
-      probe = parent;
-    }
-  }
-}
-
-async function walk(root) {
-  const files = [];
-  const visit = async (dir, rel) => {
-    const entries = await readdir(dir, { withFileTypes: true });
-    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-    for (const e of entries) {
-      // Hidden files and folders, and symlinks (no loops, no escaping the input).
-      if (e.name.startsWith(".") || e.isSymbolicLink()) continue;
-      const childRel = rel ? `${rel}/${e.name}` : e.name;
-      if (e.isDirectory()) {
-        if (!SKIP_DIRS.has(e.name)) await visit(path.join(dir, e.name), childRel);
-      } else if (e.isFile() && FORMATS[path.extname(e.name).toLowerCase()]) {
-        files.push(childRel);
-      }
-    }
-  };
-  await visit(root, "");
-  return files;
-}
-
-function usage(message) {
-  const e = new Error(message);
-  e.usage = true;
-  return e;
-}
-
-// ── plans ───────────────────────────────────────────────────────────────────
-
-async function planFolder(opts, io) {
-  const cwd = io.cwd || process.cwd();
-  const given = path.resolve(cwd, opts.target);
-  let input;
-  try { input = await realpath(given); } catch { throw usage(`No such folder: ${opts.target}`); }
-  if (!statSync(input).isDirectory()) throw usage(`${opts.target} is not a folder.`);
-  if (!path.basename(input)) throw usage("Give the output folder with --out.");
-  const output = path.resolve(cwd, opts.out || path.join(path.dirname(given), `${path.basename(given)}-is`));
-  const outputReal = await realish(output);
-  if (samePath(outputReal, input) || isInside(outputReal, input) || isInside(input, outputReal)) {
-    throw usage(`--out must be a separate folder, not the input folder, inside it or around it: ${output}`);
-  }
-  if (existsSync(output) && !statSync(output).isDirectory()) throw usage(`--out ${output} is a file; give a folder.`);
-
-  const files = [];
-  for (const rel of await walk(input)) {
-    const source = path.join(input, ...rel.split("/"));
-    const file = {
-      path: rel, source, target: path.join(output, ...rel.split("/")), format: FORMATS[path.extname(rel).toLowerCase()],
-    };
-    file.bytes = await readFile(source);
-    let text;
-    if (file.bytes.length > MAX_FILE_BYTES) file.note = "larger than 5 MB";
-    else {
-      try { text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(file.bytes); } catch { file.note = "not UTF-8 text"; }
-    }
-    if (text !== undefined) {
-      if (file.format === "json" && isConfigJson(path.basename(rel))) file.note = "configuration, not a string catalog";
-      else {
-        const seg = segment(text, file.format);
-        file.text = text;
-        file.units = seg.units;
-        file.note = seg.note || (seg.units.length ? undefined : "nothing to refine");
-      }
-    }
-    file.status = file.note ? "copy" : "refine";
-    files.push(file);
-  }
-  return { mode: "folder", label: opts.target, input, output, outputIsFolder: true, files };
-}
-
-const withSource = (page) => `<!-- Source: ${page.url} -->\n\n${page.markdown}\n`;
-
-function pageFile(page, rel, target) {
-  const text = withSource(page);
-  const { units } = segmentMarkdown(text);
-  return {
-    path: rel, source: page.url, target, format: "md", text, units,
-    status: units.length ? "refine" : "copy", note: units.length ? undefined : "nothing to refine",
-  };
-}
-
-async function planWeb(opts, io, log) {
-  const cwd = io.cwd || process.cwd();
-  const web = { fetch: io.fetch, sleep: io.sleep, userAgent: userAgent(io.version || "0") };
-  if (!opts.site) {
-    const page = await readPage(opts.target, web);
-    const last = pagePath(page.url).replace(/\.md$/, "").split("/").pop();
-    const name = `${last === "index" ? safeSegment(new URL(page.url).host) : last}-is.md`;
-    let target = path.resolve(cwd, opts.out || name);
-    if (existsSync(target) && statSync(target).isDirectory()) target = path.join(target, name);
-    return { mode: "page", label: opts.target, output: target, outputIsFolder: false, files: [pageFile(page, path.basename(target), target)] };
-  }
-  log(`Reading ${opts.target} (up to ${plural(opts.maxPages, "page", "pages")}) …`);
-  const { pages, skipped, source } = await readSite(opts.target, {
-    maxPages: opts.maxPages, io: web, onPage: (p) => log(`  read ${p.url}`),
-  });
-  const output = path.resolve(cwd, opts.out || `${safeSegment(new URL(pages[0].url).host)}-is`);
-  if (existsSync(output) && !statSync(output).isDirectory()) throw usage(`--out ${output} is a file; --site writes a folder.`);
-  const taken = new Set();
-  const files = pages.map((page) => {
-    let rel = pagePath(page.url);
-    for (let k = 2; taken.has(rel.toLowerCase()); k++) rel = pagePath(page.url).replace(/\.md$/, `-${k}.md`);
-    taken.add(rel.toLowerCase());
-    return pageFile(page, rel, path.join(output, ...rel.split("/")));
-  });
-  return { mode: "site", label: opts.target, output, outputIsFolder: true, files, skipped, discovery: source };
-}
-
-// ── calls ───────────────────────────────────────────────────────────────────
-
-/** One call per distinct piece of text: a passage seen twice is paid once. A
- *  passage over the API limit becomes several pieces cut at sentences. */
-function buildCalls(files, maxChars) {
-  const calls = new Map();
-  let budgetUsed = 0;
-  let overBudget = false;
-  for (const file of files) {
-    if (file.status !== "refine") continue;
-    const fresh = new Map();
-    for (const unit of file.units) {
-      const { pieces, joins } = splitForApi(unit.text);
-      unit.joins = joins;
-      unit.calls = pieces.map((text) => calls.get(text) || fresh.get(text) || fresh.set(text, { text, units: [] }).get(text));
-    }
-    const added = [...fresh.values()].reduce((n, c) => n + c.text.length, 0);
-    if (overBudget || (maxChars && budgetUsed + added > maxChars)) {
-      overBudget = true;
-      file.status = "over-budget";
-      continue;
-    }
-    budgetUsed += added;
-    for (const [text, call] of fresh) calls.set(text, call);
-    for (const unit of file.units) {
-      unit.file = file;
-      for (const call of new Set(unit.calls)) call.units.push(unit);
-    }
-  }
-  return [...calls.values()];
-}
-
-async function fetchPricing(baseUrl, fetchImpl) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 5000);
-  try {
-    const res = await fetchImpl(`${baseUrl}/v1/pricing`, { headers: { accept: "application/json" }, signal: controller.signal });
-    if (!res.ok) return null;
-    const p = JSON.parse(await res.text());
-    const lane = p?.tiers?.standard?.fast;
-    if (!Number.isFinite(p?.minimumBillableUnits) || !lane) return null;
-    return {
-      minUnits: p.minimumBillableUnits,
-      multiplier: Number(lane.multiplier) || 1,
-      iskPer1000: Number(lane.iskPer1000Units),
-      freeDaily: Number(p.accountFreeDailyUnits) || 0,
-    };
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-function estimateLines(plan, calls, pricing, opts) {
-  const refining = plan.files.filter((f) => f.status === "refine");
-  const passages = refining.reduce((n, f) => n + f.units.length, 0);
-  const chars = calls.reduce((n, c) => n + c.text.length, 0);
-  const lines = [
-    `${plural(refining.length, "file", "files")}, ${plural(passages, "passage", "passages")}, about ${fmt(chars)} characters`
-      + `${calls.length !== passages ? ` (${plural(calls.length, "call", "calls")}: repeated passages are sent once)` : ""}.`,
-  ];
-  const copied = plan.files.filter((f) => f.status === "copy").length;
-  if (copied) lines.push(`${plural(copied, "more file has", "more files have")} nothing to refine and ${copied === 1 ? "is" : "are"} copied unchanged.`);
-  const over = plan.files.filter((f) => f.status === "over-budget");
-  if (over.length) {
-    lines.push(`--max-chars ${fmt(opts.maxChars)}: ${plural(over.length, "file does", "files do")} not fit and will not be sent `
-      + `(from ${over[0].path} on).`);
-  }
-  if (pricing && calls.length) {
-    const units = calls.reduce((n, c) => n + Math.max(pricing.minUnits, billingTokens(c.text)), 0) * pricing.multiplier;
-    const isk = Number.isFinite(pricing.iskPer1000) ? `, about ${fmt((units * pricing.iskPer1000) / 1000)} kr if paid from credit` : "";
-    lines.push(`Billing: about ${fmt(units)} units (at least ${fmt(pricing.minUnits)} a call)${isk}.`
-      + `${pricing.freeDaily ? ` The free allowance is ${fmt(pricing.freeDaily)} units a day.` : ""}`);
-  }
-  return lines;
-}
-
-// ── the run ─────────────────────────────────────────────────────────────────
-
-const VERDICT = {
-  passed: "meaning verified",
-  changed: "the meaning may have changed",
-  reverted: "rewrite refused; original returned",
-  skipped: "meaning not checked",
-  unavailable: "the meaning check did not finish",
-};
-
-/** Decide a passage once all its calls are back. */
-function settle(unit) {
-  const results = unit.calls.map((c) => c.result);
-  const failed = results.find((r) => r.error);
-  if (failed) return Object.assign(unit, { status: "failed", reason: failed.error });
-  const data = results.map((r) => r.data);
-  const refined = data.map((d) => String(d.output ?? "").trim())
-    .reduce((acc, piece, k) => (k ? acc + (unit.joins[k - 1] ?? " ") + piece : piece), "");
-  const verified = data.every((d) => d.meaningCheck === "passed" && d.meaningPreserved === true);
-  const notPassed = data.find((d) => d.meaningCheck !== "passed");
-  const check = notPassed ? (notPassed.meaningCheck ?? null) : "passed";
-  Object.assign(unit, {
-    after: refined,
-    meaningCheck: check,
-    meaningPreserved: data.every((d) => d.meaningPreserved === true) ? true : data.some((d) => d.meaningPreserved === false) ? false : null,
-    ids: data.map((d) => d.id).filter(Boolean),
-  });
-  const unverified = check !== "passed"
-    ? VERDICT[check] || `meaning check: ${check ?? "missing"}`
-    : `meaning not verified (meaningPreserved: ${unit.meaningPreserved})`;
-  if (refined.replace(/\s+/g, " ") === unit.text.replace(/\s+/g, " ")) {
-    // The engine kept the text. That is a refusal of the meaning check only
-    // when it says so; "already fine" and its own quality veto are not.
-    const refused = data.find((d) => !d.candidateVetoFired && (d.meaningCheck === "reverted" || d.rejectionReason));
-    return Object.assign(unit, refused
-      ? { status: "kept", reason: refused.rejectionReason || VERDICT.reverted }
-      : { status: "unchanged" });
-  }
-  const mojibake = data.find((d) => d.quality?.encodingArtifacts?.length);
-  if (mojibake) return Object.assign(unit, { status: "kept", reason: "encoding artifacts in the output" });
-  if (!verified) return Object.assign(unit, { status: "kept", reason: unverified });
-  const repaired = repairCodeSpans(unit.text, refined);
-  const placed = unit.place(repaired);
-  if (!placed.ok) return Object.assign(unit, { status: "kept", reason: placed.reason });
-  return Object.assign(unit, { status: "changed", value: placed.value, after: repaired });
-}
-
-function passageSummary(unit, n) {
-  return {
-    n,
-    status: unit.status || "pending",
-    before: unit.text,
-    ...(unit.after !== undefined ? { after: unit.after } : {}),
-    ...(unit.meaningCheck !== undefined ? { meaningCheck: unit.meaningCheck, meaningPreserved: unit.meaningPreserved } : {}),
-    ...(unit.reason ? { reason: unit.reason } : {}),
-    ...(unit.ids?.length ? { ids: unit.ids } : {}),
-  };
-}
-
-/**
- * The whole command. Returns an exit code:
- *   0 done · 2 done, some passages kept their original · 4 out of credit · 1 error
- */
-export async function runBatch(opts, io = {}) {
-  const log = io.log || ((m) => process.stderr.write(`${m}\n`));
-  const print = io.print || ((m) => process.stdout.write(`${m}\n`));
-  const wait = io.sleep || sleep;
-  const now = io.now || Date.now;
-  const cwd = io.cwd || process.cwd();
-  const fetchImpl = io.fetch || globalThis.fetch;
-  const isUrl = /^https?:\/\//i.test(opts.target);
-
-  if (opts.fast) {
-    log("--fast skips the meaning check, and a folder or site run only writes verified changes. Leave --fast out.");
-    return EXIT_ERROR;
-  }
-  if (opts.review) {
-    log("--review is for one text. A folder or site run lists every change in its report: run it with --dry-run first, then --yes.");
-    return EXIT_ERROR;
-  }
-  const concurrency = opts.concurrency ?? 2;
-  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4) { log("--concurrency must be 1, 2, 3 or 4."); return EXIT_ERROR; }
-  if (opts.maxChars !== undefined && !(Number.isInteger(opts.maxChars) && opts.maxChars > 0)) { log("--max-chars must be a positive whole number."); return EXIT_ERROR; }
-  const maxPages = opts.maxPages ?? 20;
-  if (!Number.isInteger(maxPages) || maxPages < 1) { log("--max-pages must be a positive whole number."); return EXIT_ERROR; }
-  if (opts.site && !isUrl) { log("--site needs a URL, such as https://example.com"); return EXIT_ERROR; }
-  // Checked here, not by the API: a bad value would otherwise fail every call.
-  if (!DOMAINS.includes(opts.domain ?? "general")) { log(`--domain must be one of: ${DOMAINS.join(", ")}`); return EXIT_ERROR; }
-  if (!REGISTERS.includes(opts.register ?? "neutral")) { log(`--register must be one of: ${REGISTERS.join(", ")}`); return EXIT_ERROR; }
-  // Before reading anything, so a site is not crawled for nothing. --dry-run
-  // sends nothing and needs no key.
-  if (!opts.dryRun && !opts.key) { log("Not logged in. Run once:  npx altalandi login   (or set ALTALANDI_API_KEY)"); return EXIT_ERROR; }
-
-  let plan;
-  try {
-    plan = isUrl ? await planWeb({ ...opts, maxPages }, { ...io, fetch: fetchImpl, cwd }, log) : await planFolder(opts, { cwd });
-  } catch (e) {
-    log(e.usage ? e.message : `Could not read ${opts.target}: ${e.message}`);
-    return EXIT_ERROR;
-  }
-  const calls = buildCalls(plan.files, opts.maxChars);
-  const baseUrl = (opts.baseUrl || "https://altalandi.is/api").replace(/\/+$/, "");
-  const where = `${plan.label} → ${display(plan.output, cwd)}`;
-  const refining = () => plan.files.filter((f) => f.status === "refine");
-
-  if (opts.maxChars && !refining().length && plan.files.some((f) => f.status === "over-budget")) {
-    log(`Nothing fits in --max-chars ${fmt(opts.maxChars)}: ${plan.files.find((f) => f.status === "over-budget").path} alone is more.`);
-    return EXIT_ERROR;
-  }
-  // The public tariff: no key, no text sent, nothing charged.
-  const pricing = calls.length ? await fetchPricing(baseUrl, fetchImpl) : null;
-  const estimate = estimateLines(plan, calls, pricing, opts);
-
-  if (opts.dryRun) {
-    if (opts.json) {
-      print(JSON.stringify({
-        dryRun: true, input: plan.label, output: plan.output, estimate,
-        files: plan.files.map((f) => ({
-          path: f.path, source: f.source, status: f.status, ...(f.note ? { note: f.note } : {}),
-          passages: (f.units || []).map((u) => u.text),
-        })),
-      }, null, 2));
-      return EXIT_OK;
-    }
-    print(`Dry run: nothing is sent and nothing is written.\n${where}\n`);
-    for (const f of plan.files) {
-      if (f.status === "copy") { print(`${f.path}: copied unchanged (${f.note})`); continue; }
-      const chars = f.units.reduce((n, u) => n + u.text.length, 0);
-      print(`${f.path}: ${plural(f.units.length, "passage", "passages")}, ${fmt(chars)} characters${f.status === "over-budget" ? " (over --max-chars, not sent)" : ""}`);
-      f.units.forEach((u, k) => print(`  ${k + 1}. ${preview(u.text)}`));
-    }
-    print(`\n${estimate.join("\n")}`);
-    return EXIT_OK;
-  }
-
-  if (!refining().length) {
-    log(`${where}\nNothing to refine: no passages in ${plural(plan.files.length, "file", "files")}.`);
-  } else {
-    log(`${where}\n${estimate.join("\n")}`);
-    if (!opts.yes) {
-      const interactive = io.interactive ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
-      if (!interactive) {
-        log("Nothing was sent. Without a terminal to ask in, pass --yes to confirm (see the estimate above, or run with --dry-run first).");
-        return EXIT_ERROR;
-      }
-      const confirm = io.confirm || (async (q) => (await import("./update.mjs")).ask(q));
-      const n = refining().reduce((k, f) => k + f.units.length, 0);
-      if (!(await confirm(`Send ${plural(n, "passage", "passages")} to Altalandi?`))) {
-        log("Nothing was sent.");
-        return EXIT_ERROR;
-      }
-    }
-  }
-
-  // Never write inside the input, whatever the paths say.
-  const write = async (target, data) => {
-    if (plan.input && (samePath(target, plan.input) || isInside(target, plan.input))) {
-      throw new Error(`refusing to write inside the input: ${target}`);
-    }
-    if (plan.outputIsFolder ? !isInside(target, plan.output) : !samePath(target, plan.output)) {
-      throw new Error(`refusing to write outside the output: ${target}`);
-    }
-    await mkdir(path.dirname(target), { recursive: true });
-    await writeFile(target, data);
-  };
-
-  const state = { stop: null, pausedUntil: 0, errorsInARow: 0 };
-  const stop = (reason, message) => { if (!state.stop) state.stop = { reason, message }; };
-
-  for (const f of plan.files.filter((x) => x.status === "copy")) {
-    try { await write(f.target, f.bytes ?? f.text); } catch (e) { stop("error", `Could not write ${f.target}: ${e.message}`); }
-  }
-
-  const requestOptions = {
-    apiKey: opts.key, baseUrl, domain: opts.domain, register: opts.register,
-    // Only verified changes are written, so ask for the check explicitly.
-    preserveMeaning: true,
-    ...(opts.noStore ? { contribute: false } : {}),
-    ...(io.fetch ? { fetch: io.fetch } : {}),
-  };
-
-  const pause = async () => {
-    for (let left = state.pausedUntil - now(); left > 0; left = state.pausedUntil - now()) await wait(left);
-  };
-
-  const callOnce = async (call) => {
-    let rateLimited = 0;
-    let transient = 0;
-    for (;;) {
-      await pause();
-      if (state.stop) return { skipped: true };
-      try {
-        return { data: await refine(call.text, requestOptions) };
-      } catch (e) {
-        if (e.status === 429) {
-          rateLimited++;
-          const ms = Number.isFinite(e.retryAfterMs) ? e.retryAfterMs : Math.min(60_000, 2000 * 2 ** (rateLimited - 1));
-          if (ms > MAX_RETRY_WAIT_MS) {
-            stop("credit", `${e.message} Try again in about ${Math.ceil(ms / 60_000)} min.`);
-            return { skipped: true };
-          }
-          if (rateLimited > MAX_RATE_LIMIT_RETRIES) {
-            stop("error", `Still rate limited after ${MAX_RATE_LIMIT_RETRIES} retries: ${e.message}`);
-            return { skipped: true };
-          }
-          if (now() + ms > state.pausedUntil) {
-            state.pausedUntil = now() + ms;
-            log(`Rate limited (429): waiting ${Math.ceil(ms / 1000)} s, as the server asked.`);
-          }
-          continue;
-        }
-        if (e.status === 402) { stop("credit", e.message); return { skipped: true }; }
-        if (e.status === 401 || e.status === 403) { stop("error", `${e.message} → The key is invalid or revoked. Run:  npx altalandi login`); return { skipped: true }; }
-        // Network errors, timeouts and server errors get two more tries.
-        if ((!e.status || e.status === 408 || e.status >= 500) && transient < MAX_TRANSIENT_RETRIES) {
-          transient++;
-          await wait(1000 * 2 ** transient);
-          continue;
-        }
-        return { error: e.message };
-      }
-    }
-  };
-
-  const progress = (file) => {
-    const u = file.units;
-    const changed = u.filter((x) => x.status === "changed").length;
-    const kept = u.filter((x) => x.status === "kept").length;
-    const failed = u.filter((x) => x.status === "failed").length;
-    const extra = [kept && `${kept} kept as they were (check did not pass)`, failed && `${failed} failed`].filter(Boolean).join(", ");
-    log(`${kept || failed ? "!" : "✓"} ${file.path}: ${changed} of ${plural(u.length, "passage", "passages")} changed${extra ? `; ${extra}` : ""}`);
-  };
-
-  const finish = async (file) => {
-    file.status = "writing"; // before the first await, so no other worker writes it too
-    const values = new Map(file.units.filter((u) => u.status === "changed").map((u) => [u, u.value]));
-    try {
-      await write(file.target, values.size ? assemble(file.text, file.units, values) : (file.bytes ?? file.text));
-      file.status = values.size ? "written" : "unchanged";
-      progress(file);
-    } catch (e) {
-      file.status = "failed";
-      file.note = e.message;
-      stop("error", `Could not write ${file.target}: ${e.message}`);
-    }
-  };
-
-  const done = async (call) => {
-    if (call.result.skipped) return;
-    if (call.result.error) {
-      state.errorsInARow++;
-      if (state.errorsInARow >= ERRORS_IN_A_ROW_TO_STOP) stop("error", `${state.errorsInARow} calls in a row failed; the last: ${call.result.error}`);
-    } else {
-      state.errorsInARow = 0;
-    }
-    for (const unit of call.units) {
-      if (unit.status || !unit.calls.every((c) => c.result && !c.result.skipped)) continue;
-      settle(unit);
-      const file = unit.file;
-      if (file.status === "refine" && file.units.every((u) => u.status)) await finish(file);
-    }
-  };
-
-  const hadWork = refining().length > 0;
-  const queue = [...calls];
-  const worker = async () => {
-    while (queue.length && !state.stop) {
-      const call = queue.shift();
-      call.result = await callOnce(call);
-      await done(call);
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(concurrency, Math.max(1, calls.length)) }, worker));
-
-  for (const f of plan.files) if (f.status === "refine") f.status = "unfinished";
-
-  // ── results ───────────────────────────────────────────────────────────────
-  const files = plan.files.map((f) => ({
-    path: f.path,
-    ...(f.source && isUrl ? { source: f.source } : {}),
-    output: display(f.target, cwd),
-    status: f.status,
-    ...(f.note ? { note: f.note } : {}),
-    passages: (f.units || []).map((u, k) => passageSummary(u, k + 1)),
-  }));
-  const passages = files.flatMap((f) => f.passages);
-  const count = (s) => passages.filter((p) => p.status === s).length;
-  const summary = {
-    input: plan.label,
-    output: display(plan.output, cwd),
-    mode: plan.mode,
-    domain: opts.domain,
-    register: opts.register,
-    finishedAt: new Date(now()).toISOString(),
-    stopped: state.stop,
-    totals: {
-      files: files.length,
-      written: files.filter((f) => f.status === "written").length,
-      unchanged: files.filter((f) => f.status === "unchanged").length,
-      copied: files.filter((f) => f.status === "copy").length,
-      unfinished: files.filter((f) => f.status === "unfinished").length,
-      overBudget: files.filter((f) => f.status === "over-budget").length,
-      passages: passages.length,
-      changed: count("changed"),
-      unchangedPassages: count("unchanged"),
-      kept: count("kept"),
-      failed: count("failed"),
-      characters: calls.filter((c) => c.result && !c.result.skipped).reduce((n, c) => n + c.text.length, 0),
-    },
-    ...(plan.skipped?.length ? { skippedPages: plan.skipped } : {}),
-    files,
-  };
-
-  let exit = EXIT_OK;
-  if (summary.totals.kept) exit = EXIT_KEPT;
-  if (summary.totals.failed || summary.totals.overBudget || state.stop) exit = EXIT_ERROR;
-  if (state.stop?.reason === "credit") exit = EXIT_CREDIT;
-  summary.exitCode = exit;
-
-  if (passages.length) {
-    // Next to the output by default (./altalandi-reports for `altalandi ./docs`),
-    // and never inside the input, where the next run would pick it up.
-    const beside = path.join(path.dirname(plan.output), "altalandi-reports");
-    let reportDir = path.resolve(cwd, opts.reportDir || process.env.ALTALANDI_REPORT_DIR || beside);
-    if (plan.input && (samePath(reportDir, plan.input) || isInside(reportDir, plan.input))) reportDir = beside;
-    try {
-      summary.report = await writeBatchReport(summary, reportDir);
-    } catch (e) {
-      log(`Could not write the report: ${e.message}`);
-    }
-  }
-
-  const t = summary.totals;
-  if (state.stop) {
-    log(`\nStopped: ${state.stop.message}`);
-    if (state.stop.reason === "credit") log("→ Add credit at https://altalandi.is/portal, then run the same command for the rest.");
-    const finished = files.filter((f) => ["written", "unchanged"].includes(f.status)).map((f) => f.path);
-    const unfinished = files.filter((f) => f.status === "unfinished").map((f) => f.path);
-    log(`Finished (${finished.length}): ${finished.join(", ") || "none"}`);
-    log(`Not finished, not written (${unfinished.length}): ${unfinished.join(", ") || "none"}`);
-  }
-  log(`\n${state.stop ? "Partly done" : "Done"}: ${plural(t.written + t.unchanged + t.copied, "file", "files")} in ${display(plan.output, cwd)}`
-    + `${t.copied ? ` (${fmt(t.copied)} copied unchanged)` : ""}.`
-    + (hadWork ? ` Passages: ${fmt(t.changed)} changed, ${fmt(t.unchangedPassages)} needed no change, ${fmt(t.kept)} kept as they were, ${fmt(t.failed)} failed.` : ""));
-  if (t.kept) log(`${plural(t.kept, "passage keeps", "passages keep")} the original text because a check did not pass; the report lists ${t.kept === 1 ? "it" : "them"}.`);
-  if (t.overBudget) log(`${plural(t.overBudget, "file was", "files were")} left out for --max-chars.`);
-  if (summary.report) log(`Report: ${display(summary.report, cwd)}`);
-  if (opts.json) print(JSON.stringify(summary, null, 2));
-  return exit;
-}
+// `altalandi <folder | url>`: refine a whole folder of documents, one web page
+// or a site in one command, and write the Icelandic next to the original.
+//
+// The order of things is the safety story:
+//   1. plan      read every document and cut it into passages (segment.mjs,
+//                web.mjs); nothing is sent yet
+//   2. estimate  files, passages and the characters billed, with the price,
+//                printed before anything is sent
+//   3. consent   a y/N question in a terminal, or --yes; with neither, nothing
+//                is sent (--dry-run stops here on purpose)
+//   4. refine    short passages go together in batch requests (/v1/refine/batch),
+//                longer ones one call each; 2 requests at a time by default; a
+//                429 waits for Retry-After, a 402 stops the run cleanly
+//   5. write     each file once all its passages are back; a passage whose
+//                meaning check did not pass keeps its original text; nothing is
+//                ever written inside the input
+//   6. report    one Markdown summary of every file and every change
+//
+// Every side effect is injectable (io), so the tests need no network, terminal
+// or API key.
+
+import { existsSync, statSync } from "node:fs";
+import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { refine, refineBatch } from "./client.mjs";
+import { CHARS_PER_WORD, charsEquivalent, formatChars, formatIsk, writeBatchReport } from "./report.mjs";
+import { assemble, FORMATS, isConfigJson, repairCodeSpans, segment, segmentMarkdown, splitForApi } from "./segment.mjs";
+import { pagePath, readPage, readSite, safeSegment, userAgent } from "./web.mjs";
+
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_KEPT = 2; // finished, but some passages kept their original text
+export const EXIT_CREDIT = 4; // stopped: out of credit or allowance (as for a single text)
+
+// altalandi-reports: the reports of earlier runs are not documents to refine.
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "altalandi-reports"]);
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_RETRY_WAIT_MS = 5 * 60_000; // a longer Retry-After means "come back later"
+const MAX_RATE_LIMIT_RETRIES = 8;
+const MAX_TRANSIENT_RETRIES = 2;
+const ERRORS_IN_A_ROW_TO_STOP = 3;
+// Short passages go to /v1/refine/batch: each is billed at least 130 characters
+// there instead of the 250-character call minimum, which is paid once per
+// request. A request
+// stays small enough to come back well inside the web proxy's ~300 s timeout
+// (the server refines 4 at a time: ~40 short items take a minute or two).
+export const BATCH_PASSAGE_MAX_CHARS = 1500;
+export const BATCH_MAX_ITEMS = 40;
+export const BATCH_MAX_CHARS = 6000;
+// When /v1/pricing says neither (minimumBillableChars / batchItemMinimumChars)
+// nor the word units of an older engine.
+const MIN_BILLABLE_CHARS = 250;
+const BATCH_ITEM_MIN_CHARS = 130;
+const DOMAINS = ["general", "marketing", "data-analysis", "childrens-fiction"];
+const REGISTERS = ["formal", "neutral", "warm"];
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const fmt = (n) => Math.round(n).toLocaleString("en-US");
+const plural = (n, one, many) => `${fmt(n)} ${n === 1 ? one : many}`;
+const fold = (p) => (process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p);
+const samePath = (a, b) => fold(path.resolve(a)) === fold(path.resolve(b));
+const isInside = (child, parent) => {
+  const rel = path.relative(fold(path.resolve(parent)), fold(path.resolve(child)));
+  return Boolean(rel) && !rel.startsWith("..") && !path.isAbsolute(rel);
+};
+const display = (p, cwd) => {
+  const rel = path.relative(cwd, p);
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : p;
+};
+const preview = (s, n = 72) => {
+  const one = String(s).replace(/\s+/g, " ").trim();
+  return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+};
+
+/** Billable characters: every Unicode code point of the trimmed text, spaces,
+ *  punctuation and line breaks included (the server's rule). */
+export const billableChars = (text) => [...String(text).trim()].length;
+
+/** The real path of p, or of its deepest existing ancestor plus the rest, so a
+ *  symlinked --out is compared where it really points. */
+async function realish(p) {
+  const abs = path.resolve(p);
+  const rest = [];
+  let probe = abs;
+  for (;;) {
+    try {
+      return path.join(await realpath(probe), ...rest.reverse());
+    } catch {
+      const parent = path.dirname(probe);
+      if (parent === probe) return abs;
+      rest.push(path.basename(probe));
+      probe = parent;
+    }
+  }
+}
+
+async function walk(root) {
+  const files = [];
+  const visit = async (dir, rel) => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      // Hidden files and folders, and symlinks (no loops, no escaping the input).
+      if (e.name.startsWith(".") || e.isSymbolicLink()) continue;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) await visit(path.join(dir, e.name), childRel);
+      } else if (e.isFile() && FORMATS[path.extname(e.name).toLowerCase()]) {
+        files.push(childRel);
+      }
+    }
+  };
+  await visit(root, "");
+  return files;
+}
+
+function usage(message) {
+  const e = new Error(message);
+  e.usage = true;
+  return e;
+}
+
+// ── plans ───────────────────────────────────────────────────────────────────
+
+async function planFolder(opts, io) {
+  const cwd = io.cwd || process.cwd();
+  const given = path.resolve(cwd, opts.target);
+  let input;
+  try { input = await realpath(given); } catch { throw usage(`No such folder: ${opts.target}`); }
+  if (!statSync(input).isDirectory()) throw usage(`${opts.target} is not a folder.`);
+  if (!path.basename(input)) throw usage("Give the output folder with --out.");
+  const output = path.resolve(cwd, opts.out || path.join(path.dirname(given), `${path.basename(given)}-is`));
+  const outputReal = await realish(output);
+  if (samePath(outputReal, input) || isInside(outputReal, input) || isInside(input, outputReal)) {
+    throw usage(`--out must be a separate folder, not the input folder, inside it or around it: ${output}`);
+  }
+  if (existsSync(output) && !statSync(output).isDirectory()) throw usage(`--out ${output} is a file; give a folder.`);
+
+  const files = [];
+  for (const rel of await walk(input)) {
+    const source = path.join(input, ...rel.split("/"));
+    const file = {
+      path: rel, source, target: path.join(output, ...rel.split("/")), format: FORMATS[path.extname(rel).toLowerCase()],
+    };
+    file.bytes = await readFile(source);
+    let text;
+    if (file.bytes.length > MAX_FILE_BYTES) file.note = "larger than 5 MB";
+    else {
+      try { text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(file.bytes); } catch { file.note = "not UTF-8 text"; }
+    }
+    if (text !== undefined) {
+      if (file.format === "json" && isConfigJson(path.basename(rel))) file.note = "configuration, not a string catalog";
+      else {
+        const seg = segment(text, file.format);
+        file.text = text;
+        file.units = seg.units;
+        file.note = seg.note || (seg.units.length ? undefined : "nothing to refine");
+      }
+    }
+    file.status = file.note ? "copy" : "refine";
+    files.push(file);
+  }
+  return { mode: "folder", label: opts.target, input, output, outputIsFolder: true, files };
+}
+
+const withSource = (page) => `<!-- Source: ${page.url} -->\n\n${page.markdown}\n`;
+
+function pageFile(page, rel, target) {
+  const text = withSource(page);
+  const { units } = segmentMarkdown(text);
+  return {
+    path: rel, source: page.url, target, format: "md", text, units,
+    status: units.length ? "refine" : "copy", note: units.length ? undefined : "nothing to refine",
+  };
+}
+
+async function planWeb(opts, io, log) {
+  const cwd = io.cwd || process.cwd();
+  const web = { fetch: io.fetch, sleep: io.sleep, userAgent: userAgent(io.version || "0") };
+  if (!opts.site) {
+    const page = await readPage(opts.target, web);
+    const last = pagePath(page.url).replace(/\.md$/, "").split("/").pop();
+    const name = `${last === "index" ? safeSegment(new URL(page.url).host) : last}-is.md`;
+    let target = path.resolve(cwd, opts.out || name);
+    if (existsSync(target) && statSync(target).isDirectory()) target = path.join(target, name);
+    return { mode: "page", label: opts.target, output: target, outputIsFolder: false, files: [pageFile(page, path.basename(target), target)] };
+  }
+  log(`Reading ${opts.target} (up to ${plural(opts.maxPages, "page", "pages")}) …`);
+  const { pages, skipped, source } = await readSite(opts.target, {
+    maxPages: opts.maxPages, io: web, onPage: (p) => log(`  read ${p.url}`),
+  });
+  const output = path.resolve(cwd, opts.out || `${safeSegment(new URL(pages[0].url).host)}-is`);
+  if (existsSync(output) && !statSync(output).isDirectory()) throw usage(`--out ${output} is a file; --site writes a folder.`);
+  const taken = new Set();
+  const files = pages.map((page) => {
+    let rel = pagePath(page.url);
+    for (let k = 2; taken.has(rel.toLowerCase()); k++) rel = pagePath(page.url).replace(/\.md$/, `-${k}.md`);
+    taken.add(rel.toLowerCase());
+    return pageFile(page, rel, path.join(output, ...rel.split("/")));
+  });
+  return { mode: "site", label: opts.target, output, outputIsFolder: true, files, skipped, discovery: source };
+}
+
+// ── calls ───────────────────────────────────────────────────────────────────
+
+/** One call per distinct piece of text: a passage seen twice is paid once. A
+ *  passage over the API limit becomes several pieces cut at sentences. */
+function buildCalls(files, maxChars) {
+  const calls = new Map();
+  let budgetUsed = 0;
+  let overBudget = false;
+  for (const file of files) {
+    if (file.status !== "refine") continue;
+    const fresh = new Map();
+    for (const unit of file.units) {
+      const { pieces, joins } = splitForApi(unit.text);
+      unit.joins = joins;
+      unit.calls = pieces.map((text) => calls.get(text) || fresh.get(text) || fresh.set(text, { text, units: [] }).get(text));
+    }
+    const added = [...fresh.values()].reduce((n, c) => n + c.text.length, 0);
+    if (overBudget || (maxChars && budgetUsed + added > maxChars)) {
+      overBudget = true;
+      file.status = "over-budget";
+      continue;
+    }
+    budgetUsed += added;
+    for (const [text, call] of fresh) calls.set(text, call);
+    for (const unit of file.units) {
+      unit.file = file;
+      for (const call of new Set(unit.calls)) call.units.push(unit);
+    }
+  }
+  return [...calls.values()];
+}
+
+/** The requests of a run: short calls together in batches of at most
+ *  BATCH_MAX_ITEMS items and BATCH_MAX_CHARS characters, longer ones alone. */
+export function groupCalls(calls) {
+  const jobs = [];
+  let open = null;
+  for (const call of calls) {
+    if (call.text.length > BATCH_PASSAGE_MAX_CHARS) { jobs.push({ batch: false, calls: [call] }); continue; }
+    if (open && (open.calls.length >= BATCH_MAX_ITEMS || open.chars + call.text.length > BATCH_MAX_CHARS)) open = null;
+    if (!open) { open = { batch: true, calls: [], chars: 0 }; jobs.push(open); }
+    open.calls.push(call);
+    open.chars += call.text.length;
+  }
+  return jobs;
+}
+
+/** Characters a request is billed: the call minimum for one text; for a batch,
+ *  each item at least the item minimum, the call minimum once for the request. */
+function jobChars(job, pricing) {
+  if (!job.batch) return Math.max(pricing.minChars, billableChars(job.calls[0].text));
+  const items = job.calls.reduce((n, c) => n + Math.max(pricing.itemMinChars, billableChars(c.text)), 0);
+  return Math.max(pricing.minChars, items);
+}
+
+const fin = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+async function fetchPricing(baseUrl, fetchImpl) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    const res = await fetchImpl(`${baseUrl}/v1/pricing`, { headers: { accept: "application/json" }, signal: controller.signal });
+    if (!res.ok) return null;
+    const p = JSON.parse(await res.text());
+    const lane = p?.tiers?.standard?.fast;
+    if (!lane || typeof lane !== "object") return null;
+    // Characters (billingUnit "character"); an engine from before the switch
+    // gives word units, converted with charsPerWord.
+    const cpw = fin(p.charsPerWord) > 0 ? p.charsPerWord : CHARS_PER_WORD;
+    const chars = (c, u) => fin(p[c]) ?? (fin(p[u]) != null ? Math.round(p[u] * cpw) : null);
+    // The tier's price already carries its weight, as iskPer1000Units did.
+    const per100 = fin(lane.iskPer100Chars) ?? (fin(lane.iskPer1000Units) != null ? lane.iskPer1000Units / 10 / cpw : null);
+    return {
+      minChars: chars("minimumBillableChars", "minimumBillableUnits") ?? MIN_BILLABLE_CHARS,
+      itemMinChars: chars("batchItemMinimumChars", "batchItemMinimumUnits") ?? BATCH_ITEM_MIN_CHARS,
+      multiplier: Number(lane.multiplier) || 1,
+      iskPerChar: per100 != null ? per100 / 100 : null,
+      freeDaily: chars("accountFreeDailyChars", "accountFreeDailyUnits") ?? 0,
+      charsPerWord: cpw,
+    };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function estimateLines(plan, calls, jobs, pricing, opts) {
+  const refining = plan.files.filter((f) => f.status === "refine");
+  const passages = refining.reduce((n, f) => n + f.units.length, 0);
+  const chars = calls.reduce((n, c) => n + c.text.length, 0);
+  const lines = [
+    `${plural(refining.length, "file", "files")}, ${plural(passages, "passage", "passages")}, about ${fmt(chars)} characters`
+      + `${calls.length !== passages ? ` (${fmt(calls.length)} to send: repeated passages are sent once)` : ""}.`,
+  ];
+  const batches = jobs.filter((j) => j.batch);
+  if (calls.length) {
+    const together = batches.reduce((n, j) => n + j.calls.length, 0);
+    const alone = jobs.length - batches.length;
+    lines.push(`${plural(jobs.length, "request", "requests")}: `
+      + [together && `${plural(together, "short passage", "short passages")} together in ${plural(batches.length, "batch", "batches")}`,
+        alone && `${plural(alone, "longer passage", "longer passages")} one by one`].filter(Boolean).join(", ") + ".");
+  }
+  const copied = plan.files.filter((f) => f.status === "copy").length;
+  if (copied) lines.push(`${plural(copied, "more file has", "more files have")} nothing to refine and ${copied === 1 ? "is" : "are"} copied unchanged.`);
+  const over = plan.files.filter((f) => f.status === "over-budget");
+  if (over.length) {
+    lines.push(`--max-chars ${fmt(opts.maxChars)}: ${plural(over.length, "file does", "files do")} not fit and will not be sent `
+      + `(from ${over[0].path} on).`);
+  }
+  if (pricing && calls.length) {
+    // In Icelandic, as on the site: characters, one equivalent and krónur;
+    // never the rate per 100 characters.
+    const raw = jobs.reduce((n, j) => n + jobChars(j, pricing), 0);
+    const billed = raw * pricing.multiplier;
+    const isk = pricing.iskPerChar != null ? raw * pricing.iskPerChar : null;
+    const price = isk != null ? `, um ${formatIsk(isk >= 10 ? Math.round(isk) : isk)} ef greitt er af inneign` : "";
+    lines.push(`Kostnaður: um ${formatChars(billed)} (${charsEquivalent(billed)})${price}.`);
+    const rule = `Hvert kall telst minnst ${formatChars(pricing.minChars)}`
+      + (batches.length ? `; margir stuttir textar í einu kalli minnst ${formatChars(pricing.itemMinChars)} hver.` : ".");
+    lines.push(rule + (pricing.freeDaily ? ` ${formatChars(pricing.freeDaily)} á dag eru ókeypis.` : ""));
+  }
+  return lines;
+}
+
+// ── the run ─────────────────────────────────────────────────────────────────
+
+const VERDICT = {
+  passed: "meaning verified",
+  changed: "the meaning may have changed",
+  reverted: "rewrite refused; original returned",
+  skipped: "meaning not checked",
+  unavailable: "the meaning check did not finish",
+};
+
+/** Decide a passage once all its calls are back. */
+function settle(unit) {
+  const results = unit.calls.map((c) => c.result);
+  const failed = results.find((r) => r.error);
+  if (failed) return Object.assign(unit, { status: "failed", reason: failed.error });
+  const data = results.map((r) => r.data);
+  const refined = data.map((d) => String(d.output ?? "").trim())
+    .reduce((acc, piece, k) => (k ? acc + (unit.joins[k - 1] ?? " ") + piece : piece), "");
+  const verified = data.every((d) => d.meaningCheck === "passed" && d.meaningPreserved === true);
+  const notPassed = data.find((d) => d.meaningCheck !== "passed");
+  const check = notPassed ? (notPassed.meaningCheck ?? null) : "passed";
+  Object.assign(unit, {
+    after: refined,
+    meaningCheck: check,
+    meaningPreserved: data.every((d) => d.meaningPreserved === true) ? true : data.some((d) => d.meaningPreserved === false) ? false : null,
+    ids: data.map((d) => d.id).filter(Boolean),
+  });
+  const unverified = check !== "passed"
+    ? VERDICT[check] || `meaning check: ${check ?? "missing"}`
+    : `meaning not verified (meaningPreserved: ${unit.meaningPreserved})`;
+  if (refined.replace(/\s+/g, " ") === unit.text.replace(/\s+/g, " ")) {
+    // The engine kept the text. That is a refusal of the meaning check only
+    // when it says so; "already fine" and its own quality veto are not.
+    const refused = data.find((d) => !d.candidateVetoFired && (d.meaningCheck === "reverted" || d.rejectionReason));
+    return Object.assign(unit, refused
+      ? { status: "kept", reason: refused.rejectionReason || VERDICT.reverted }
+      : { status: "unchanged" });
+  }
+  const mojibake = data.find((d) => d.quality?.encodingArtifacts?.length);
+  if (mojibake) return Object.assign(unit, { status: "kept", reason: "encoding artifacts in the output" });
+  if (!verified) return Object.assign(unit, { status: "kept", reason: unverified });
+  const repaired = repairCodeSpans(unit.text, refined);
+  const placed = unit.place(repaired);
+  if (!placed.ok) return Object.assign(unit, { status: "kept", reason: placed.reason });
+  return Object.assign(unit, { status: "changed", value: placed.value, after: repaired });
+}
+
+function passageSummary(unit, n) {
+  return {
+    n,
+    status: unit.status || "pending",
+    before: unit.text,
+    ...(unit.after !== undefined ? { after: unit.after } : {}),
+    ...(unit.meaningCheck !== undefined ? { meaningCheck: unit.meaningCheck, meaningPreserved: unit.meaningPreserved } : {}),
+    ...(unit.reason ? { reason: unit.reason } : {}),
+    ...(unit.ids?.length ? { ids: unit.ids } : {}),
+  };
+}
+
+/**
+ * The whole command. Returns an exit code:
+ *   0 done · 2 done, some passages kept their original · 4 out of credit · 1 error
+ */
+export async function runBatch(opts, io = {}) {
+  const log = io.log || ((m) => process.stderr.write(`${m}\n`));
+  const print = io.print || ((m) => process.stdout.write(`${m}\n`));
+  const wait = io.sleep || sleep;
+  const now = io.now || Date.now;
+  const cwd = io.cwd || process.cwd();
+  const fetchImpl = io.fetch || globalThis.fetch;
+  const isUrl = /^https?:\/\//i.test(opts.target);
+
+  if (opts.fast) {
+    log("--fast skips the meaning check, and a folder or site run only writes verified changes. Leave --fast out.");
+    return EXIT_ERROR;
+  }
+  if (opts.review) {
+    log("--review is for one text. A folder or site run lists every change in its report: run it with --dry-run first, then --yes.");
+    return EXIT_ERROR;
+  }
+  const concurrency = opts.concurrency ?? 2;
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4) { log("--concurrency must be 1, 2, 3 or 4."); return EXIT_ERROR; }
+  if (opts.maxChars !== undefined && !(Number.isInteger(opts.maxChars) && opts.maxChars > 0)) { log("--max-chars must be a positive whole number."); return EXIT_ERROR; }
+  const maxPages = opts.maxPages ?? 20;
+  if (!Number.isInteger(maxPages) || maxPages < 1) { log("--max-pages must be a positive whole number."); return EXIT_ERROR; }
+  if (opts.site && !isUrl) { log("--site needs a URL, such as https://example.com"); return EXIT_ERROR; }
+  // Checked here, not by the API: a bad value would otherwise fail every call.
+  if (!DOMAINS.includes(opts.domain ?? "general")) { log(`--domain must be one of: ${DOMAINS.join(", ")}`); return EXIT_ERROR; }
+  if (!REGISTERS.includes(opts.register ?? "neutral")) { log(`--register must be one of: ${REGISTERS.join(", ")}`); return EXIT_ERROR; }
+  // Before reading anything, so a site is not crawled for nothing. --dry-run
+  // sends nothing and needs no key.
+  if (!opts.dryRun && !opts.key) { log("Not logged in. Run once:  npx altalandi login   (or set ALTALANDI_API_KEY)"); return EXIT_ERROR; }
+
+  let plan;
+  try {
+    plan = isUrl ? await planWeb({ ...opts, maxPages }, { ...io, fetch: fetchImpl, cwd }, log) : await planFolder(opts, { cwd });
+  } catch (e) {
+    log(e.usage ? e.message : `Could not read ${opts.target}: ${e.message}`);
+    return EXIT_ERROR;
+  }
+  const calls = buildCalls(plan.files, opts.maxChars);
+  const jobs = groupCalls(calls);
+  const baseUrl = (opts.baseUrl || "https://altalandi.is/api").replace(/\/+$/, "");
+  const where = `${plan.label} → ${display(plan.output, cwd)}`;
+  const refining = () => plan.files.filter((f) => f.status === "refine");
+
+  if (opts.maxChars && !refining().length && plan.files.some((f) => f.status === "over-budget")) {
+    log(`Nothing fits in --max-chars ${fmt(opts.maxChars)}: ${plan.files.find((f) => f.status === "over-budget").path} alone is more.`);
+    return EXIT_ERROR;
+  }
+  // The public tariff: no key, no text sent, nothing charged.
+  const pricing = calls.length ? await fetchPricing(baseUrl, fetchImpl) : null;
+  const estimate = estimateLines(plan, calls, jobs, pricing, opts);
+
+  if (opts.dryRun) {
+    if (opts.json) {
+      print(JSON.stringify({
+        dryRun: true, input: plan.label, output: plan.output, estimate,
+        files: plan.files.map((f) => ({
+          path: f.path, source: f.source, status: f.status, ...(f.note ? { note: f.note } : {}),
+          passages: (f.units || []).map((u) => u.text),
+        })),
+      }, null, 2));
+      return EXIT_OK;
+    }
+    print(`Dry run: nothing is sent and nothing is written.\n${where}\n`);
+    for (const f of plan.files) {
+      if (f.status === "copy") { print(`${f.path}: copied unchanged (${f.note})`); continue; }
+      const chars = f.units.reduce((n, u) => n + u.text.length, 0);
+      print(`${f.path}: ${plural(f.units.length, "passage", "passages")}, ${fmt(chars)} characters${f.status === "over-budget" ? " (over --max-chars, not sent)" : ""}`);
+      f.units.forEach((u, k) => print(`  ${k + 1}. ${preview(u.text)}`));
+    }
+    print(`\n${estimate.join("\n")}`);
+    return EXIT_OK;
+  }
+
+  if (!refining().length) {
+    log(`${where}\nNothing to refine: no passages in ${plural(plan.files.length, "file", "files")}.`);
+  } else {
+    log(`${where}\n${estimate.join("\n")}`);
+    if (!opts.yes) {
+      const interactive = io.interactive ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
+      if (!interactive) {
+        log("Nothing was sent. Without a terminal to ask in, pass --yes to confirm (see the estimate above, or run with --dry-run first).");
+        return EXIT_ERROR;
+      }
+      const confirm = io.confirm || (async (q) => (await import("./update.mjs")).ask(q));
+      const n = refining().reduce((k, f) => k + f.units.length, 0);
+      if (!(await confirm(`Send ${plural(n, "passage", "passages")} to Altalandi?`))) {
+        log("Nothing was sent.");
+        return EXIT_ERROR;
+      }
+    }
+  }
+
+  // Never write inside the input, whatever the paths say.
+  const write = async (target, data) => {
+    if (plan.input && (samePath(target, plan.input) || isInside(target, plan.input))) {
+      throw new Error(`refusing to write inside the input: ${target}`);
+    }
+    if (plan.outputIsFolder ? !isInside(target, plan.output) : !samePath(target, plan.output)) {
+      throw new Error(`refusing to write outside the output: ${target}`);
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, data);
+  };
+
+  const state = { stop: null, pausedUntil: 0, errorsInARow: 0, noBatch: false, billed: null, billedChars: null, approx: false };
+  // What a response says it billed: characters, or the word units of an
+  // engine from before the switch (converted, and marked as approximate).
+  const bill = (data) => {
+    const b = data?.billing || {};
+    const units = fin(b.units) ?? fin(data?.units);
+    if (units != null) state.billed = (state.billed ?? 0) + units;
+    const chars = fin(b.characters) ?? fin(data?.characters);
+    if (chars == null && units == null) return;
+    if (chars == null) state.approx = true;
+    state.billedChars = (state.billedChars ?? 0) + (chars ?? units * (pricing?.charsPerWord ?? CHARS_PER_WORD));
+  };
+  const stop = (reason, message) => { if (!state.stop) state.stop = { reason, message }; };
+
+  for (const f of plan.files.filter((x) => x.status === "copy")) {
+    try { await write(f.target, f.bytes ?? f.text); } catch (e) { stop("error", `Could not write ${f.target}: ${e.message}`); }
+  }
+
+  const requestOptions = {
+    apiKey: opts.key, baseUrl, domain: opts.domain, register: opts.register,
+    // Only verified changes are written, so ask for the check explicitly.
+    preserveMeaning: true,
+    ...(opts.noStore ? { contribute: false } : {}),
+    ...(io.fetch ? { fetch: io.fetch } : {}),
+  };
+
+  const pause = async () => {
+    for (let left = state.pausedUntil - now(); left > 0; left = state.pausedUntil - now()) await wait(left);
+  };
+
+  // One request with the run's retry rules: `send` is one /v1/refine or one
+  // /v1/refine/batch call. A batch endpoint the server does not have (404/405,
+  // an older self-hosted engine) answers { unsupported }.
+  const attempt = async (send, { batch = false } = {}) => {
+    let rateLimited = 0;
+    let transient = 0;
+    for (;;) {
+      await pause();
+      if (state.stop) return { skipped: true };
+      try {
+        return { data: await send() };
+      } catch (e) {
+        if (batch && (e.status === 404 || e.status === 405)) return { unsupported: true };
+        if (e.status === 429) {
+          rateLimited++;
+          const ms = Number.isFinite(e.retryAfterMs) ? e.retryAfterMs : Math.min(60_000, 2000 * 2 ** (rateLimited - 1));
+          if (ms > MAX_RETRY_WAIT_MS) {
+            stop("credit", `${e.message} Try again in about ${Math.ceil(ms / 60_000)} min.`);
+            return { skipped: true };
+          }
+          if (rateLimited > MAX_RATE_LIMIT_RETRIES) {
+            stop("error", `Still rate limited after ${MAX_RATE_LIMIT_RETRIES} retries: ${e.message}`);
+            return { skipped: true };
+          }
+          if (now() + ms > state.pausedUntil) {
+            state.pausedUntil = now() + ms;
+            log(`Rate limited (429): waiting ${Math.ceil(ms / 1000)} s, as the server asked.`);
+          }
+          continue;
+        }
+        if (e.status === 402) { stop("credit", e.message); return { skipped: true }; }
+        if (e.status === 401 || e.status === 403) { stop("error", `${e.message} → The key is invalid or revoked. Run:  npx altalandi login`); return { skipped: true }; }
+        // Network errors, timeouts and server errors get two more tries.
+        if ((!e.status || e.status === 408 || e.status >= 500) && transient < MAX_TRANSIENT_RETRIES) {
+          transient++;
+          await wait(1000 * 2 ** transient);
+          continue;
+        }
+        return { error: e.message };
+      }
+    }
+  };
+
+  const progress = (file) => {
+    const u = file.units;
+    const changed = u.filter((x) => x.status === "changed").length;
+    const kept = u.filter((x) => x.status === "kept").length;
+    const failed = u.filter((x) => x.status === "failed").length;
+    const extra = [kept && `${kept} kept as they were (check did not pass)`, failed && `${failed} failed`].filter(Boolean).join(", ");
+    log(`${kept || failed ? "!" : "✓"} ${file.path}: ${changed} of ${plural(u.length, "passage", "passages")} changed${extra ? `; ${extra}` : ""}`);
+  };
+
+  const finish = async (file) => {
+    file.status = "writing"; // before the first await, so no other worker writes it too
+    const values = new Map(file.units.filter((u) => u.status === "changed").map((u) => [u, u.value]));
+    try {
+      await write(file.target, values.size ? assemble(file.text, file.units, values) : (file.bytes ?? file.text));
+      file.status = values.size ? "written" : "unchanged";
+      progress(file);
+    } catch (e) {
+      file.status = "failed";
+      file.note = e.message;
+      stop("error", `Could not write ${file.target}: ${e.message}`);
+    }
+  };
+
+  const countError = (error) => {
+    state.errorsInARow++;
+    if (state.errorsInARow >= ERRORS_IN_A_ROW_TO_STOP) stop("error", `${state.errorsInARow} calls in a row failed; the last: ${error}`);
+  };
+
+  const done = async (job) => {
+    if (job.calls.some((c) => c.result?.skipped)) return;
+    if (job.failed) countError(job.failed); // a whole request failed: one error, not one per passage
+    else {
+      for (const call of job.calls) {
+        if (call.result.error) countError(call.result.error);
+        else state.errorsInARow = 0;
+      }
+    }
+    for (const call of job.calls) {
+      for (const unit of call.units) {
+        if (unit.status || !unit.calls.every((c) => c.result && !c.result.skipped)) continue;
+        settle(unit);
+        const file = unit.file;
+        if (file.status === "refine" && file.units.every((u) => u.status)) await finish(file);
+      }
+    }
+  };
+
+  const single = async (call) => {
+    const r = await attempt(() => refine(call.text, requestOptions));
+    if (r.data) bill(r.data);
+    return r;
+  };
+
+  /** One batch request; every item is mapped back to its call by id. */
+  const sendBatch = async (job) => {
+    const items = job.calls.map((c, k) => ({ id: String(k), text: c.text }));
+    const r = await attempt(() => refineBatch(items, requestOptions), { batch: true });
+    if (!r.data) return r;
+    const data = r.data;
+    bill(data);
+    const byId = new Map(data.items.map((it) => [String(it.id), it]));
+    const artifacts = data.quality?.encodingArtifacts || [];
+    job.calls.forEach((call, k) => {
+      const item = byId.get(String(k));
+      if (!item) call.result = { error: "the batch response has no result for this passage" };
+      else if (item.error) call.result = { error: String(item.error) };
+      else {
+        // The batch's quality block covers every item; keep the mojibake guard per item.
+        const own = artifacts.filter((a) => a && String(item.output).includes(a));
+        call.result = { data: { ...item, id: data.id || undefined, quality: { encodingArtifacts: own } } };
+      }
+    });
+    return { done: true };
+  };
+
+  const alone = (job) => job.calls.map((call) => ({ batch: false, calls: [call] }));
+  const hadWork = refining().length > 0;
+  const queue = [...jobs];
+  const worker = async () => {
+    while (queue.length && !state.stop) {
+      const job = queue.shift();
+      if (job.batch && state.noBatch) { queue.unshift(...alone(job)); continue; }
+      if (!job.batch) {
+        job.calls[0].result = await single(job.calls[0]);
+      } else {
+        const r = await sendBatch(job);
+        if (r.unsupported) {
+          if (!state.noBatch) {
+            state.noBatch = true;
+            log("Note: this server has no batch endpoint (/v1/refine/batch), so every passage is sent on its own "
+              + `(each call is billed at least ${fmt(pricing?.minChars ?? MIN_BILLABLE_CHARS)} characters).`);
+          }
+          queue.unshift(...alone(job));
+          fill(); // one batch became many calls: use every worker for them
+          continue;
+        }
+        if (!r.done) {
+          for (const call of job.calls) call.result = r;
+          if (r.error) job.failed = r.error;
+        }
+      }
+      await done(job);
+    }
+  };
+  const running = [];
+  let active = 0;
+  function fill() {
+    while (active < concurrency && queue.length && !state.stop) {
+      active++;
+      running.push(worker().finally(() => { active--; }));
+    }
+  }
+  fill();
+  while (running.length) await Promise.all(running.splice(0));
+
+  for (const f of plan.files) if (f.status === "refine") f.status = "unfinished";
+
+  // ── results ───────────────────────────────────────────────────────────────
+  const files = plan.files.map((f) => ({
+    path: f.path,
+    ...(f.source && isUrl ? { source: f.source } : {}),
+    output: display(f.target, cwd),
+    status: f.status,
+    ...(f.note ? { note: f.note } : {}),
+    passages: (f.units || []).map((u, k) => passageSummary(u, k + 1)),
+  }));
+  const passages = files.flatMap((f) => f.passages);
+  const count = (s) => passages.filter((p) => p.status === s).length;
+  const summary = {
+    input: plan.label,
+    output: display(plan.output, cwd),
+    mode: plan.mode,
+    domain: opts.domain,
+    register: opts.register,
+    finishedAt: new Date(now()).toISOString(),
+    stopped: state.stop,
+    totals: {
+      files: files.length,
+      written: files.filter((f) => f.status === "written").length,
+      unchanged: files.filter((f) => f.status === "unchanged").length,
+      copied: files.filter((f) => f.status === "copy").length,
+      unfinished: files.filter((f) => f.status === "unfinished").length,
+      overBudget: files.filter((f) => f.status === "over-budget").length,
+      passages: passages.length,
+      changed: count("changed"),
+      unchangedPassages: count("unchanged"),
+      kept: count("kept"),
+      failed: count("failed"),
+      characters: calls.filter((c) => c.result && !c.result.skipped).reduce((n, c) => n + c.text.length, 0),
+      // What the server says it billed, summed over the responses (null: none
+      // said). billedCharacters is what is shown; units is the word equivalent.
+      billedCharacters: state.billedChars == null ? null
+        : state.approx ? Math.round(state.billedChars / 10) * 10 : Math.round(state.billedChars),
+      ...(state.approx ? { billedCharactersApprox: true } : {}),
+      units: state.billed,
+    },
+    ...(plan.skipped?.length ? { skippedPages: plan.skipped } : {}),
+    files,
+  };
+
+  let exit = EXIT_OK;
+  if (summary.totals.kept) exit = EXIT_KEPT;
+  if (summary.totals.failed || summary.totals.overBudget || state.stop) exit = EXIT_ERROR;
+  if (state.stop?.reason === "credit") exit = EXIT_CREDIT;
+  summary.exitCode = exit;
+
+  if (passages.length) {
+    // Next to the output by default (./altalandi-reports for `altalandi ./docs`),
+    // and never inside the input, where the next run would pick it up.
+    const beside = path.join(path.dirname(plan.output), "altalandi-reports");
+    let reportDir = path.resolve(cwd, opts.reportDir || process.env.ALTALANDI_REPORT_DIR || beside);
+    if (plan.input && (samePath(reportDir, plan.input) || isInside(reportDir, plan.input))) reportDir = beside;
+    try {
+      summary.report = await writeBatchReport(summary, reportDir);
+    } catch (e) {
+      log(`Could not write the report: ${e.message}`);
+    }
+  }
+
+  const t = summary.totals;
+  if (state.stop) {
+    log(`\nStopped: ${state.stop.message}`);
+    if (state.stop.reason === "credit") log("→ Add credit at https://altalandi.is/stjornbord/inneign, then run the same command for the rest.");
+    const finished = files.filter((f) => ["written", "unchanged"].includes(f.status)).map((f) => f.path);
+    const unfinished = files.filter((f) => f.status === "unfinished").map((f) => f.path);
+    log(`Finished (${finished.length}): ${finished.join(", ") || "none"}`);
+    log(`Not finished, not written (${unfinished.length}): ${unfinished.join(", ") || "none"}`);
+  }
+  log(`\n${state.stop ? "Partly done" : "Done"}: ${plural(t.written + t.unchanged + t.copied, "file", "files")} in ${display(plan.output, cwd)}`
+    + `${t.copied ? ` (${fmt(t.copied)} copied unchanged)` : ""}.`
+    + (hadWork ? ` Passages: ${fmt(t.changed)} changed, ${fmt(t.unchangedPassages)} needed no change, ${fmt(t.kept)} kept as they were, ${fmt(t.failed)} failed.` : ""));
+  if (t.billedCharacters != null) {
+    log(`Rukkað: ${t.billedCharactersApprox ? "um " : ""}${formatChars(t.billedCharacters)} (${charsEquivalent(t.billedCharacters)}).`);
+  }
+  if (t.kept) log(`${plural(t.kept, "passage keeps", "passages keep")} the original text because a check did not pass; the report lists ${t.kept === 1 ? "it" : "them"}.`);
+  if (t.overBudget) log(`${plural(t.overBudget, "file was", "files were")} left out for --max-chars.`);
+  if (summary.report) log(`Report: ${display(summary.report, cwd)}`);
+  if (opts.json) print(JSON.stringify(summary, null, 2));
+  return exit;
+}