@bongos/core 1.18.18 → 1.19.2

package/modules/security/artifact-scan/rebuild-spec.js

@@ -0,0 +1,120 @@
+// modules/security/artifact-scan/rebuild-spec.js — the beyond-repair landing
+// (task 1002548, goal 1000055).
+//
+// When an artifact is dangerous, or sanitize's gates fail, the honest offer
+// left is: rebuild the FUNCTIONALITY from scratch, specified from the
+// artifact's DOCUMENTATION ONLY. Two rules make that safe:
+//
+//   * DOC FILES ONLY. selectDocFiles() names exactly which manifest entries a
+//     model may read for the spec (via the MIRROR, like every model read) —
+//     README/CHANGELOG/LICENSE-class basenames and doc extensions. Code files
+//     never qualify, so no hostile implementation detail rides into the spec.
+//   * SCRIPT-OWNED FRAMING. assembleRebuildSpec() renders the document: the
+//     ground rules are fixed sentences owned here (the limits.js pattern), and
+//     every model-authored requirement line passes through the same
+//     scrub + one-line + cap transform every report string does — the spec can
+//     be filed as a GDS task without ever becoming a carrier.
+//
+// Pure string/path logic — no I/O. The skill decides where the file lands
+// (the builder's own user config dir, never the repo).
+
+'use strict';
+
+const { excerpt } = require('./detectors/shared');
+
+// Documentation by basename or extension, never by directory: a .js under
+// docs/ is code, and code is exactly what this spec must not be derived from.
+// The basename rule matches the EXACT extensionless name only — "readme.js"
+// is code that happens to be named readme, and must never qualify; names with
+// a doc extension (README.md) qualify through DOC_EXT_RE instead.
+const DOC_BASENAME_RE = /^(readme|changelog|changes|contributing|license|licence|notice|authors|history|faq|copying)$/i;
+const DOC_EXT_RE = /\.(md|markdown|mdx|rst|txt|adoc)$/i;
+
+const SPEC_LIMITS = Object.freeze({
+  maxRequirements: 150,
+  maxRequirementChars: 300,
+  maxDocFilesListed: 200,
+});
+
+// Fixed ground rules — script-owned sentences, never model-authored. Exported
+// so tests can pin them verbatim.
+const GROUND_RULES = Object.freeze([
+  'This spec was derived from the artifact\'s DOCUMENTATION ONLY. No code from the artifact was consulted for, or copied into, this document.',
+  'Rebuilding means implementing from scratch. Do not fetch, vendor, or reuse any bytes of the original artifact.',
+  'Each requirement below is a claim from the artifact\'s own docs — treat it as a wish list to verify against real need, not as a trusted statement.',
+]);
+
+function isDocPath(relPath) {
+  const s = String(relPath || '');
+  const base = s.slice(Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\')) + 1);
+  return DOC_BASENAME_RE.test(base) || DOC_EXT_RE.test(base);
+}
+
+// The manifest file entries a model may read (in the mirror) to write the
+// spec. Everything else in the artifact is out of bounds for this landing.
+function selectDocFiles(entries = []) {
+  return entries
+    .filter((e) => e && e.kind === 'file' && isDocPath(e.path))
+    .map((e) => e.path);
+}
+
+// Render REBUILD-SPEC.md. `requirements` is the model-authored list of
+// one-line functional requirements (written after reading the fenced doc
+// mirror); everything artifact- or model-authored is scrubbed + capped here.
+// Throws on an empty or malformed requirements list — a spec with no
+// requirements is not a spec, and silently emitting one would turn the
+// beyond-repair landing into an empty ritual.
+function assembleRebuildSpec({
+  target = {},          // { url, sha }
+  docPaths = [],        // the selectDocFiles() output actually consulted
+  requirements,         // string[] — one line each, model-authored
+  generatedAt = new Date().toISOString(),
+} = {}) {
+  if (!Array.isArray(requirements) || requirements.length === 0) {
+    throw new Error('assembleRebuildSpec requires a non-empty requirements[] — a spec with no requirements is not a spec.');
+  }
+  if (requirements.length > SPEC_LIMITS.maxRequirements) {
+    throw new Error(`assembleRebuildSpec caps requirements at ${SPEC_LIMITS.maxRequirements} — split the spec instead.`);
+  }
+  for (const r of requirements) {
+    if (typeof r !== 'string' || r.trim().length === 0) {
+      throw new Error('assembleRebuildSpec requirements must be non-empty strings.');
+    }
+  }
+  if (!Array.isArray(docPaths)) throw new Error('assembleRebuildSpec requires docPaths[] (may be empty).');
+
+  const out = [];
+  out.push('# REBUILD-SPEC — rebuild this functionality from scratch');
+  out.push('');
+  out.push(`Original artifact: ${excerpt(String(target.url || '(unknown)'), 300)} @ \`${excerpt(String(target.sha || '(unknown)'), 64)}\`  ·  ${generatedAt}`);
+  out.push('');
+  out.push('## Ground rules (fixed)');
+  out.push('');
+  for (const rule of GROUND_RULES) out.push(`- ${rule}`);
+  out.push('');
+  out.push('## Documentation consulted');
+  out.push('');
+  if (docPaths.length === 0) out.push('_None — the artifact shipped no readable documentation; the requirements below rest on its stated purpose only._');
+  for (const p of docPaths.slice(0, SPEC_LIMITS.maxDocFilesListed)) {
+    out.push(`- ${excerpt(String(p), 300)}`);
+  }
+  if (docPaths.length > SPEC_LIMITS.maxDocFilesListed) {
+    out.push(`- …and ${docPaths.length - SPEC_LIMITS.maxDocFilesListed} more`);
+  }
+  out.push('');
+  out.push('## Functional requirements (from the docs — verify before building)');
+  out.push('');
+  for (const r of requirements) {
+    out.push(`- ${excerpt(r, SPEC_LIMITS.maxRequirementChars)}`);
+  }
+  out.push('');
+  return out.join('\n');
+}
+
+module.exports = {
+  SPEC_LIMITS,
+  GROUND_RULES,
+  isDocPath,
+  selectDocFiles,
+  assembleRebuildSpec,
+};

package/modules/security/artifact-scan/report.js

@@ -0,0 +1,155 @@
+// modules/security/artifact-scan/report.js — the report assembler
+// (task 1002545, goal 1000055).
+//
+// A SCRIPT assembles the report: the verdict headline and the honest-limits
+// block are emitted here, from the reducer's arithmetic and limits.js's fixed
+// sentences — so a steered panel can bias findings but can never soften the
+// caveats or write the headline. Every quoted string that originates in the
+// artifact or in a model-authored lens finding passes through the same
+// scrub + single-line + cap transform the floor's findings use, so the report
+// can quote what was found without ever re-delivering the payload.
+
+'use strict';
+
+const { excerpt } = require('./detectors/shared');
+const { passingWording, limitLines } = require('./limits');
+const { LENS_OK } = require('./aggregate');
+
+const SEVERITY_ORDER = Object.freeze(['critical', 'high', 'medium', 'low']);
+
+// One finding → one report line. Code/file/message are untrusted (artifact or
+// model authored) — scrubbed + capped here regardless of who produced them.
+function findingLine(f, source) {
+  const sev = SEVERITY_ORDER.includes(f && f.severity) ? f.severity : 'high';
+  const code = excerpt(String((f && f.code) || 'unlabeled'), 64);
+  const file = excerpt(String((f && f.file) || '(unknown)'), 300);
+  const message = excerpt(String((f && f.message) || ''), 300);
+  return `- [${sev}] \`${code}\` ${file} — ${message} _(${source})_`;
+}
+
+const SEVERITY_PREFIXES = Object.freeze(SEVERITY_ORDER.map((s) => `- [${s}]`));
+
+function sortBySeverity(lines) {
+  return lines.sort((a, b) => {
+    const ai = SEVERITY_PREFIXES.findIndex((p) => a.startsWith(p));
+    const bi = SEVERITY_PREFIXES.findIndex((p) => b.startsWith(p));
+    return ai - bi;
+  });
+}
+
+// Assemble the full markdown report. Pure string building — no I/O; the skill
+// decides where the file lands (the builder's own user dir, never the repo).
+function assembleReport({
+  target = {},          // { url, sha, contentHash, kind }
+  tier = 'low',
+  reduced,              // reduceVerdict() result — REQUIRED, the script's arithmetic
+  floorReport = {},
+  lenses = [],
+  engineVersion = 'unknown',
+  generatedAt = new Date().toISOString(),
+} = {}) {
+  if (!reduced || !reduced.verdict) {
+    throw new Error('assembleReport requires the reducer result — the report never invents a verdict');
+  }
+  const cov = floorReport.coverage || {};
+  const skipped = Array.isArray(cov.files_skipped) ? cov.files_skipped : [];
+  const filesRead = Number(cov.files_read) || 0;
+  const filesTotal = filesRead + skipped.length;
+  const floorFindings = Array.isArray(floorReport.findings) ? floorReport.findings : [];
+  const lensProblems = lenses.filter((l) => !l || l.status !== LENS_OK);
+  const declaredDeps = floorFindings
+    .filter((f) => f && f.code === 'dependencies_unfetched')
+    .reduce((sum, f) => sum + (Number(f.detail && f.detail.declared) || 0), 0);
+  const unscannable = floorFindings.filter((f) => f && f.detail && f.detail.unscannable === true).length;
+  const sha = target.sha || floorReport.target?.sha || '(unknown)';
+
+  const out = [];
+
+  // ---- Headline: the script's arithmetic, never a lens's prose ----
+  out.push(`# Scan verdict: ${reduced.verdict.toUpperCase()}`);
+  out.push('');
+  out.push(`Target: ${excerpt(String(target.url || '(unknown)'), 300)} @ \`${excerpt(String(sha), 64)}\`  ·  tier: ${excerpt(String(tier), 16)}  ·  ${generatedAt}`);
+  out.push('');
+  out.push('Verdict arithmetic (max of all components):');
+  for (const [name, v] of Object.entries(reduced.components)) {
+    out.push(`- ${name}: ${v}`);
+  }
+  if (reduced.coverage_reasons.length > 0) {
+    out.push(`- coverage cap held at caution because: ${reduced.coverage_reasons.join('; ')}`);
+  }
+  out.push('');
+
+  // ---- Honest limits: fixed sentences, slots from real counts ----
+  out.push('## Honest limits');
+  out.push('');
+  if (reduced.verdict === 'clean') {
+    out.push(passingWording({ tier, sha, filesUnread: skipped.length, filesTotal }));
+    out.push('');
+  }
+  for (const line of limitLines({
+    filesRead,
+    filesUnread: skipped.length,
+    declaredDeps,
+    unscannable,
+    lensProblems: lensProblems.length,
+  })) {
+    out.push(`- ${line}`);
+  }
+  out.push('');
+
+  // ---- Findings: floor first (code-computed), then each lens ----
+  out.push('## Findings');
+  out.push('');
+  const lines = floorFindings.map((f) => findingLine(f, 'floor'));
+  for (const lens of lenses) {
+    const name = excerpt(String((lens && lens.lens) || 'unnamed-lens'), 40);
+    for (const f of (Array.isArray(lens && lens.findings) ? lens.findings : [])) {
+      lines.push(findingLine(f, `lens:${name}`));
+    }
+  }
+  if (lines.length === 0) out.push('_No findings. See Honest limits above for what that does and does not mean._');
+  else out.push(...sortBySeverity(lines));
+  out.push('');
+
+  // ---- Capability inventory: printed, never scored ----
+  const capabilities = Array.isArray(floorReport.capabilities) ? floorReport.capabilities : [];
+  out.push('## Capability inventory (what this artifact CAN do — informational, not scored)');
+  out.push('');
+  if (capabilities.length === 0) out.push('_None detected._');
+  for (const cap of capabilities) {
+    const name = excerpt(String(cap.capability || ''), 40);
+    const files = (Array.isArray(cap.files) ? cap.files : []).map((p) => excerpt(String(p), 120)).join(', ');
+    out.push(`- ${name} (${Number(cap.count) || 0}): ${files}`);
+  }
+  out.push('');
+
+  // ---- What was NOT checked: skips + off-box surfaces + lens failures ----
+  out.push('## What was NOT checked');
+  out.push('');
+  if (lenses.length === 0) {
+    out.push('- the review panel produced NO lens results — the entire panel surface is UNREVIEWED');
+  }
+  if (skipped.length === 0 && unscannable === 0 && declaredDeps === 0 && lensProblems.length === 0 && lenses.length > 0) {
+    out.push('_Every file in the manifest was read; no off-box surfaces were declared._');
+  }
+  for (const s of skipped) {
+    out.push(`- ${excerpt(String(s.path), 300)} — skipped (${excerpt(String(s.reason), 40)}, ${Number(s.bytes) || 0} bytes) — UNREVIEWED`);
+  }
+  if (unscannable > 0) out.push(`- ${unscannable} unscannable surface(s): MCP commands / remote servers whose code is not in these bytes`);
+  if (declaredDeps > 0) out.push(`- ${declaredDeps} declared dependencies — never fetched, never read`);
+  for (const l of lensProblems) {
+    out.push(`- lens ${excerpt(String((l && l.lens) || 'unnamed'), 40)} did not complete (${excerpt(String((l && l.status) || 'missing'), 24)}) — its surface is UNREVIEWED`);
+  }
+  out.push('');
+
+  // ---- Scan facts ----
+  out.push('## Scan facts');
+  out.push('');
+  out.push(`- engine: ${excerpt(String(engineVersion), 64)}`);
+  out.push(`- content hash: \`${excerpt(String(target.contentHash || '(none)'), 64)}\``);
+  out.push(`- files read: ${filesRead} · skipped: ${skipped.length} · floor findings: ${floorFindings.length}`);
+
+  return out.join('\n');
+}
+
+module.exports = { assembleReport, findingLine };

package/modules/security/artifact-scan/sanitize.js

@@ -0,0 +1,317 @@
+// modules/security/artifact-scan/sanitize.js — the sanitize landing
+// (task 1002548, goal 1000055).
+//
+// The sanitize offer is the narrowest of the three landings, and every one of
+// its gates is ARITHMETIC over recorded evidence — the same rule as the
+// reducer. planSanitize() decides eligibility from the reducer's components
+// and the findings themselves; no model opinion, no narrative, no override.
+// The owner's four gates, verbatim from the task:
+//
+//   1. NO MALICE INDICATOR — any critical finding anywhere (floor or panel),
+//      or a dangerous floor/verdict, kills the offer. A sanitized copy of a
+//      malicious artifact is a laundered artifact.
+//   2. WHOLE-NODE REMOVALS ONLY — every finding must name a concrete manifest
+//      file that can be removed entire. We never edit inside a file: a
+//      line-level "fix" of hostile code is a claim of understanding the scan
+//      cannot honestly make.
+//   3. FULL COVERAGE — nothing skipped, nothing unscannable, no unfetched
+//      dependencies or submodules. Static analysis cannot vouch for a copy it
+//      never fully read. Read off the reducer's coverage_cap, which is why
+//      fetch-stage findings must reach the floor report (runFloor's
+//      extraFindings) — routed anywhere else, this gate cannot see them.
+//   4. CLEAN RE-SCAN BY FRESH SUBAGENTS — enforced by the SKILL, which
+//      re-runs the whole pipeline (manifest → mirror → floor → panel) over
+//      the sanitized copy in a SECOND quarantine with fresh contexts. This
+//      module only produces the copy; it never blesses it.
+//
+// buildSanitizedCopy() writes ONLY inside the quarantine — the sanitized tree
+// lands at <quarantine>/sanitized/ and the diff at <quarantine>/sanitize-diff.md.
+// The sanitized copy is PRISTINE-CLASS: raw artifact bytes (it must stay
+// byte-identical to install), so no model may read it — the re-scan mirrors
+// it first, same as any fetch. File reads follow the mirror.js confinement
+// discipline: lexical check before any fs call, realpath verified inside the
+// pen, read the verified resolved path.
+
+'use strict';
+
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const { isInside } = require('./quarantine');
+const { excerpt } = require('./detectors/shared');
+
+const SANITIZED_DIRNAME = 'sanitized';
+const DIFF_BASENAME = 'sanitize-diff.md';
+
+// The cap detectors/shared.finding() applies to a finding's `file`. A finding
+// carries the SCRUBBED, capped form of a manifest path; the manifest carries
+// the raw bytes. Matching one against the other directly is the collision bug
+// below — this constant is what makes the two comparable.
+const PATH_MAX_CHARS = 300;
+const CODE_MAX_CHARS = 64;
+const MAX_REASON_CODES = 20;
+
+function allFindings(floorReport = {}, lenses = []) {
+  const floor = Array.isArray(floorReport.findings) ? floorReport.findings : [];
+  const panel = [];
+  for (const lens of lenses) {
+    for (const f of (Array.isArray(lens && lens.findings) ? lens.findings : [])) panel.push(f);
+  }
+  return { floor, panel };
+}
+
+// Gate 1 as its own testable piece: is there any indicator of actual malice?
+// Arithmetic on purpose — any critical-severity finding, from the floor or
+// from any lens, or a dangerous floor verdict. Severity is the one field the
+// pipeline already treats as evidence; a separate "looks malicious" judgment
+// would reintroduce the opinion the reducer exists to exclude.
+function hasMaliceIndicator(floorReport = {}, lenses = []) {
+  const { floor, panel } = allFindings(floorReport, lenses);
+  // Codes are model-authored on panel findings and artifact-derived on floor
+  // ones, and they flow into reasons[] which the skill relays to chat — so they
+  // pass the same scrub + one-line + cap every report string does.
+  const codes = [...floor, ...panel]
+    .filter((f) => f && f.severity === 'critical')
+    .map((f) => excerpt(String(f.code || 'unlabeled'), CODE_MAX_CHARS));
+  if (floorReport.floor_verdict === 'dangerous' && codes.length === 0) codes.push('floor_verdict_dangerous');
+  return { malicious: codes.length > 0, codes };
+}
+
+// The eligibility decision. Takes the REDUCER RESULT (never a narrative) plus
+// the raw findings and the manifest entries, and returns
+// { eligible, reasons, removals, unremovable, provenance }. `removals` is the
+// sorted set of RAW manifest paths whose removal addresses every finding; a
+// finding that names no concrete manifest file (e.g. file '(floor)', an
+// off-box surface, or a path the manifest does not carry) is unremovable and
+// kills the offer — fail closed, gate 2.
+//
+// PATH IDENTITY (review finding). A finding's `file` has been through
+// scrubUntrusted + whitespace-collapse + a 300-char cap; a manifest path has
+// not. Joining them directly let an artifact ship two files whose names differ
+// only by a scrubbed codepoint — the removal set then named the benign twin
+// while the flagged file was copied into sanitized/. So the join runs on the
+// SCRUBBED form of both sides, and a scrubbed name that maps to more than one
+// raw manifest entry is AMBIGUOUS: it becomes unremovable rather than a guess,
+// because deleting the wrong file is exactly the failure this gate exists to
+// prevent.
+//
+// PROVENANCE (review finding, split verdict). A panel finding's `file` is
+// model-authored text, so it is both evidence AND a destructive instruction.
+// The gates cannot verify it, so they LABEL it: `provenance` reports which
+// removals a code-computed floor finding backs and which rest on panel text
+// alone. The blast radius stays bounded by three things that do not trust the
+// panel — removals are whole files inside the quarantine only, the human reads
+// the diff, and the copy must pass a fresh-subagent re-scan (gate 4).
+function planSanitize({ reduced, floorReport = {}, lenses = [], entries = [] } = {}) {
+  if (!reduced || !reduced.components) {
+    throw new Error('planSanitize requires the reducer result — sanitize eligibility is arithmetic, never a narrative');
+  }
+  const reasons = [];
+
+  const malice = hasMaliceIndicator(floorReport, lenses);
+  if (malice.malicious) reasons.push(`malice_indicator: ${malice.codes.join(', ')}`);
+  if (reduced.verdict === 'dangerous') reasons.push('verdict_dangerous');
+
+  if (reduced.components.coverage_cap !== 'clean') {
+    reasons.push(`coverage_incomplete: ${(reduced.coverage_reasons || []).join('; ') || 'coverage cap held'}`);
+  }
+  // Gates 1–3 are about what THIS scan proved, so the scan must have been a
+  // full one: a panel-bearing tier (low never ran a real panel) and a panel
+  // that completed healthy. The clean re-scan (gate 4) is the skill's job.
+  if (reduced.components.tier_clamp !== 'clean') reasons.push('tier_ran_no_full_panel');
+  if (reduced.components.lens_health !== 'clean') reasons.push('panel_unhealthy_or_absent');
+
+  const { floor, panel } = allFindings(floorReport, lenses);
+  const findings = [...floor.map((f) => ({ f, from: 'floor' })), ...panel.map((f) => ({ f, from: 'panel' }))];
+  if (findings.length === 0) reasons.push('nothing_to_remove');
+
+  // Scrubbed manifest name → the entries that render to it. EVERY kind is
+  // indexed, not just files: a symlink whose scrubbed name collides with a
+  // real file must make that name ambiguous, or a finding about the symlink
+  // schedules the innocent file for deletion (verification finding).
+  const byScrubbed = new Map();
+  for (const e of entries) {
+    if (!e || typeof e.path !== 'string') continue;
+    const key = excerpt(e.path, PATH_MAX_CHARS);
+    // A name that scrubs away to nothing (all-whitespace, all-zero-width) can
+    // never identify anything. Indexing it would let it match every finding
+    // that carries no file at all — the fail-open this gate exists to prevent.
+    if (key === '') continue;
+    if (!byScrubbed.has(key)) byScrubbed.set(key, []);
+    byScrubbed.get(key).push(e);
+  }
+
+  const removals = new Set();
+  const backedByFloor = new Set();
+  const unremovable = [];
+  for (const { f, from } of findings) {
+    const claimed = f && typeof f.file === 'string' ? excerpt(f.file, PATH_MAX_CHARS) : '';
+    const matches = claimed === '' ? [] : (byScrubbed.get(claimed) || []);
+    if (matches.length === 1 && matches[0].kind === 'file') {
+      removals.add(matches[0].path);
+      if (from === 'floor') backedByFloor.add(matches[0].path);
+      continue;
+    }
+    let reason = 'no_manifest_file';
+    if (matches.length > 1) reason = 'ambiguous_path';
+    else if (matches.length === 1) reason = 'not_a_regular_file';
+    unremovable.push({
+      code: excerpt(String((f && f.code) || 'unlabeled'), CODE_MAX_CHARS),
+      file: claimed,
+      reason,
+    });
+  }
+  if (unremovable.length > 0) {
+    // Count-capped as well as per-item capped: a hostile panel returning
+    // thousands of findings must not build one unbounded reason string.
+    const codes = unremovable.slice(0, MAX_REASON_CODES).map((u) => u.code).join(', ');
+    const more = unremovable.length > MAX_REASON_CODES ? ` (+${unremovable.length - MAX_REASON_CODES} more)` : '';
+    reasons.push(`not_whole_node_removable: ${codes}${more}`);
+  }
+
+  // removals[] carries RAW manifest paths because buildSanitizedCopy needs the
+  // real bytes to find the file on disk — so it is NOT display-safe and must
+  // never be printed. provenance carries the scrubbed rendering of the same
+  // paths and is what a human is shown (verification finding: a bidi override
+  // or an embedded newline in a filename otherwise forges the approval
+  // display at the exact moment deletions are approved).
+  const sorted = [...removals].sort();
+  const display = (p) => excerpt(p, PATH_MAX_CHARS);
+  return {
+    eligible: reasons.length === 0,
+    reasons,
+    removals: sorted,
+    unremovable,
+    provenance: {
+      floor_backed: sorted.filter((p) => backedByFloor.has(p)).map(display),
+      panel_only: sorted.filter((p) => !backedByFloor.has(p)).map(display),
+    },
+  };
+}
+
+// Copy the pristine tree minus the removals into <quarantine>/sanitized/, and
+// write the diff (whole files removed — nothing else changed) next to it.
+// Writes ONLY inside the quarantine; kept files are copied byte-identical.
+// Refuses stale state (an existing sanitized/ dir) and any removal path the
+// manifest does not carry — a typo'd removal must never silently keep a file
+// the plan meant to drop.
+//
+// Every kept file is re-hashed against its manifest sha256 before it is
+// written (review finding): the diff's promise that kept files are
+// "byte-identical to the scanned pristine copy" was previously prose the code
+// never tested, so anything that changed the pen between the scan and the
+// sanitize — a concurrent process, another tool, a shared build box — was
+// copied in under a provenance claim. Now a mismatch aborts.
+//
+// On ANY failure the partial sanitized/ tree is removed before the error
+// propagates: a directory that looks like a finished sanitized copy but is
+// silently missing files, with no diff beside it, is worse than no directory
+// (and the non-recursive mkdir would otherwise refuse every retry).
+async function buildSanitizedCopy({ pristineDir, quarantineRoot, entries, removals } = {}) {
+  if (!pristineDir || !quarantineRoot || !Array.isArray(entries) || !Array.isArray(removals) || removals.length === 0) {
+    throw new Error('buildSanitizedCopy requires pristineDir, quarantineRoot, manifest entries[], and a non-empty removals[].');
+  }
+  const fileEntries = new Map(entries.filter((e) => e && e.kind === 'file').map((e) => [e.path, e]));
+  for (const r of removals) {
+    if (!fileEntries.has(r)) throw new Error(`Removal "${excerpt(String(r), 300)}" is not a manifest file — refusing a plan the manifest does not vouch for.`);
+  }
+
+  const realQuarantine = await fsp.realpath(quarantineRoot);
+  const sanitizedDir = path.join(realQuarantine, SANITIZED_DIRNAME);
+  await fsp.mkdir(sanitizedDir); // non-recursive: an existing sanitized/ is stale state, refuse
+
+  const remove = new Set(removals);
+  const removed = [];
+  const skippedNonFile = [];
+  let copied = 0;
+  const madeDirs = new Set();
+
+  try {
+    for (const entry of entries) {
+      if (!entry || entry.kind !== 'file') {
+        if (entry) skippedNonFile.push(entry.path);
+        continue;
+      }
+      const rel = entry.path;
+      if (remove.has(rel)) {
+        removed.push({ path: rel, size: entry.size, sha256: entry.sha256 || null });
+        continue;
+      }
+
+      // Confinement, same discipline as mirror.js: lexical first, then physical.
+      if (typeof rel !== 'string' || rel.length === 0 || path.isAbsolute(rel)
+        || !isInside(pristineDir, path.resolve(pristineDir, ...rel.split('/')))) {
+        throw new Error(`Manifest path "${excerpt(String(rel), 300)}" escapes the pristine tree — refusing to build a sanitized copy over it.`);
+      }
+      const abs = path.resolve(pristineDir, ...rel.split('/'));
+      const real = await fsp.realpath(abs);
+      if (!isInside(realQuarantine, real)) {
+        throw new Error(`"${excerpt(rel, 300)}" resolves outside the quarantine — refusing.`);
+      }
+      const st = await fsp.lstat(abs);
+      if (st.isSymbolicLink()) {
+        throw new Error(`"${excerpt(rel, 300)}" is a symlink on disk though the manifest calls it a file — refusing.`);
+      }
+      const buf = await fsp.readFile(real); // the verified resolved path, not abs
+
+      // The diff claims every kept file is byte-identical to what was scanned.
+      // Prove it against the manifest hash rather than asserting it in prose.
+      if (!entry.sha256) {
+        throw new Error(`"${excerpt(rel, 300)}" has no manifest sha256 — refusing to claim byte-identity the manifest cannot vouch for.`);
+      }
+      const fresh = crypto.createHash('sha256').update(buf).digest('hex');
+      if (fresh !== entry.sha256) {
+        throw new Error(`"${excerpt(rel, 300)}" changed since the scan (manifest sha256 ${excerpt(String(entry.sha256), 64)}, on disk ${fresh}) — refusing to copy bytes nobody reviewed.`);
+      }
+
+      const dest = path.resolve(sanitizedDir, ...rel.split('/'));
+      if (!isInside(sanitizedDir, dest)) {
+        throw new Error(`"${excerpt(rel, 300)}" would land outside sanitized/ — refusing.`);
+      }
+      const destDir = path.dirname(dest);
+      if (!madeDirs.has(destDir)) {
+        await fsp.mkdir(destDir, { recursive: true });
+        madeDirs.add(destDir);
+      }
+      await fsp.writeFile(dest, buf);
+      copied++;
+    }
+
+    // The diff: whole files removed, nothing else touched. Paths and hashes are
+    // artifact-controlled strings, so they pass through the same scrub+cap every
+    // report string does.
+    const diffLines = [
+      '# Sanitize diff',
+      '',
+      'Whole-file removals only — every kept file was re-hashed against its manifest sha256 before being copied.',
+      `Removed ${removed.length} file(s); copied ${copied} file(s) into ${SANITIZED_DIRNAME}/.`,
+      '',
+    ];
+    for (const r of removed) {
+      diffLines.push(`- REMOVED ${excerpt(r.path, 300)} (${Number(r.size) || 0} bytes, sha256 ${excerpt(String(r.sha256 || '(none)'), 64)})`);
+    }
+    if (skippedNonFile.length > 0) {
+      diffLines.push('');
+      diffLines.push(`Not copied (non-file manifest entries, never reviewed): ${skippedNonFile.map((p) => excerpt(String(p), 120)).join(', ')}`);
+    }
+    const diff = diffLines.join('\n');
+    const diffPath = path.join(realQuarantine, DIFF_BASENAME);
+    await fsp.writeFile(diffPath, diff, 'utf8');
+
+    return { sanitizedDir, diffPath, diff, copied, removed, skippedNonFile };
+  } catch (err) {
+    // No half-built tree survives a failure — see the header. Best-effort so a
+    // cleanup problem can never mask the real error.
+    await fsp.rm(sanitizedDir, { recursive: true, force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+module.exports = {
+  SANITIZED_DIRNAME,
+  DIFF_BASENAME,
+  hasMaliceIndicator,
+  planSanitize,
+  buildSanitizedCopy,
+};