@bongos/core 1.18.19 → 1.19.3

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

@@ -0,0 +1,158 @@
+// modules/security/artifact-scan/mirror.js — the reading-room copy of a
+// quarantined artifact (task 1002543, goal 1000055).
+//
+// Two copies of a fetched artifact exist in the quarantine: the PRISTINE copy
+// no model is ever allowed to read, and this mirror — where every readable
+// file has already been scrubbed of control/zero-width/bidi characters and
+// wrapped in an on-disk fence before any agent can open it. The defense is
+// structural: even a raw Read call against mirror/ returns data-never-
+// instructions, with no dependence on any agent's discipline.
+//
+// What does NOT get mirrored becomes a STUB RECORD instead: symlinks (never
+// followed), non-UTF8/binary files, oversize files, special files, and any
+// path that escapes the pen lexically or physically. Stub bytes are counted as
+// UNREVIEWED — downstream the reducer caps the verdict at caution over them,
+// because static analysis cannot clear what it never read.
+//
+// The walk is driven by the MANIFEST entries, not a fresh readdir: the mirror
+// renders exactly the inventory that was hashed, so "what we read" and "what
+// we fingerprinted" can never drift apart.
+//
+// Confinement is checked twice per file, fail-closed:
+//   1. lexically — a manifest path that is absolute or resolves above the
+//      pristine root is refused before any fs call touches it;
+//   2. physically — the file's realpath must live under the quarantine root,
+//      so a real on-disk symlink smuggled past kind detection still cannot
+//      pull outside bytes into the mirror.
+//
+// Fully async (fs.promises) for the same reason as manifest.js: a sync walk at
+// cap limits blocks the event loop for seconds.
+
+'use strict';
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { TextDecoder } = require('node:util');
+
+// Intra-module siblings (a module may require its own files, never another
+// module or a core internal).
+const { isInside } = require('./quarantine');
+const { newFenceDelim, fenceFile } = require('./fence-local');
+
+// Per-file readability budget. A "text" file past this size is recorded as a
+// stub rather than rendered readable — a 40 MB minified blob is unreviewable
+// text in practice, and unreviewable must always surface as unreviewed.
+const MIRROR_CAPS = Object.freeze({
+  maxFileBytes: 1024 * 1024, // 1 MiB per mirrored file
+});
+
+const INDEX_BASENAME = 'mirror-index.json';
+
+// Lexical containment for a manifest-relative path: must be relative, and must
+// stay under root after resolution. Directional — anything else is an escape.
+function relEscapes(rootDir, rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return true;
+  if (path.isAbsolute(rel)) return true;
+  return !isInside(rootDir, path.resolve(rootDir, ...rel.split('/')));
+}
+
+// Decode strictly as UTF-8. A single invalid sequence means "not text we can
+// honestly render" — the file becomes a stub, never a lossily-decoded mirror.
+// One shared decoder: non-streaming decode() keeps no state between calls.
+const UTF8_STRICT = new TextDecoder('utf-8', { fatal: true });
+function strictUtf8(buf) {
+  try {
+    return UTF8_STRICT.decode(buf);
+  } catch {
+    return null;
+  }
+}
+
+// Build the reading-room mirror for one scan.
+//   pristineDir    — the pristine snapshot (never modified here)
+//   mirrorDir      — where scrubbed+fenced copies are written
+//   quarantineRoot — the pen; every realpath must resolve under it
+//   entries        — manifest entries ({ path, kind, size, ... }) from buildManifest
+//   caps           — { maxFileBytes } override (tests); defaults MIRROR_CAPS
+//
+// Returns { mirrored, stubs, unreviewedBytes, fenceDelim, indexPath }. A stub
+// is { path, reason: symlink|special|oversize|non_utf8|path_escape|unreadable,
+// bytes }. Never throws on a per-file problem — a file the mirror cannot
+// honestly render is a recorded stub, not a crashed scan.
+async function buildMirror({ pristineDir, mirrorDir, quarantineRoot, entries, caps = {} }) {
+  if (!pristineDir || !mirrorDir || !quarantineRoot || !Array.isArray(entries)) {
+    throw new Error('buildMirror requires pristineDir, mirrorDir, quarantineRoot and manifest entries[].');
+  }
+  const maxFileBytes = caps.maxFileBytes ?? MIRROR_CAPS.maxFileBytes;
+  const realQuarantine = await fsp.realpath(quarantineRoot);
+  const fenceDelim = newFenceDelim();
+
+  const mirrored = [];
+  const stubs = [];
+  const madeDirs = new Set();
+  const stub = (rel, reason, bytes) => stubs.push({ path: rel, reason, bytes });
+
+  for (const entry of entries) {
+    const rel = entry.path;
+
+    if (entry.kind === 'symlink') { stub(rel, 'symlink', entry.size || 0); continue; }
+    if (entry.kind !== 'file') { stub(rel, 'special', entry.size || 0); continue; }
+
+    // 1. Lexical confinement — before any fs call touches the path.
+    if (relEscapes(pristineDir, rel)) { stub(rel, 'path_escape', entry.size || 0); continue; }
+    const abs = path.resolve(pristineDir, ...rel.split('/'));
+
+    if (entry.size > maxFileBytes) { stub(rel, 'oversize', entry.size); continue; }
+
+    // 2. Physical confinement — the realpath must stay inside the pen, so a
+    // real symlink mislabeled "file" cannot pull outside bytes into the mirror.
+    let buf;
+    try {
+      const real = await fsp.realpath(abs);
+      if (!isInside(realQuarantine, real)) { stub(rel, 'path_escape', entry.size || 0); continue; }
+      const st = await fsp.lstat(abs);
+      if (st.isSymbolicLink()) { stub(rel, 'path_escape', entry.size || 0); continue; }
+      // Read the VERIFIED resolved path, not the original — reading `abs` would
+      // reopen the race the realpath check just closed (TOCTOU: a swap between
+      // lstat and read would be followed silently).
+      buf = await fsp.readFile(real);
+    } catch {
+      // Missing/unreadable on disk though present in the manifest — that
+      // disagreement is itself worth surfacing, as unreviewed.
+      stub(rel, 'unreadable', entry.size || 0);
+      continue;
+    }
+
+    const text = strictUtf8(buf);
+    if (text === null) { stub(rel, 'non_utf8', buf.length); continue; }
+
+    const dest = path.resolve(mirrorDir, ...rel.split('/'));
+    if (!isInside(mirrorDir, dest)) { stub(rel, 'path_escape', buf.length); continue; }
+    const destDir = path.dirname(dest);
+    if (!madeDirs.has(destDir)) {
+      await fsp.mkdir(destDir, { recursive: true });
+      madeDirs.add(destDir);
+    }
+    await fsp.writeFile(dest, fenceFile(fenceDelim, rel, text), 'utf8');
+    mirrored.push({ path: rel, bytes: buf.length });
+  }
+
+  const unreviewedBytes = stubs.reduce((sum, s) => sum + (s.bytes || 0), 0);
+
+  // The index is the trusted record downstream stages (floor, reducer) read:
+  // which files are renderable, which bytes were never reviewed, and the fence
+  // delimiter the panel should expect. Written inside the pen, nowhere else.
+  const indexPath = path.join(realQuarantine, INDEX_BASENAME);
+  const index = {
+    fenceDelim,
+    mirrored,
+    stubs,
+    unreviewedBytes,
+    counts: { mirrored: mirrored.length, stubs: stubs.length },
+  };
+  await fsp.writeFile(indexPath, JSON.stringify(index, null, 2), 'utf8');
+
+  return { mirrored, stubs, unreviewedBytes, fenceDelim, indexPath };
+}
+
+module.exports = { buildMirror, MIRROR_CAPS, INDEX_BASENAME };

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

@@ -0,0 +1,149 @@
+// modules/security/artifact-scan/quarantine.js — the holding pen an untrusted
+// artifact is fetched into.
+//
+// The scan engine's first rule is that a suspect artifact never gets a chance to
+// act. Everything downstream (the mirror, the detectors, the panel) assumes the
+// bytes it reads live somewhere that satisfies three location properties:
+//
+//   1. OUTSIDE THE REPO — so a scanned artifact can never be mistaken for our
+//      own source, land in a diff, or be picked up by a fitness/lint sweep.
+//   2. OUTSIDE ONEDRIVE (or any sync root) — a synced folder uploads whatever
+//      lands in it. Fetching malware into a synced directory copies it to the
+//      builder's cloud storage and every other machine on that account.
+//   3. OUTSIDE EVERY WORKSPACE ROOT — this is the subtle one. A Claude session
+//      auto-loads CLAUDE.md and .claude/ from directories inside its workspace.
+//      An artifact carrying its own CLAUDE.md, dropped inside a workspace root,
+//      is prompt injection delivered through the harness itself rather than
+//      through any file an agent chose to read. Callers pass their workspace
+//      roots in `forbiddenRoots`; we refuse to build a quarantine under one.
+//
+// The pen also holds the three neutralizing fixtures the hardened clone needs:
+// an EMPTY REAL hooks directory (git's core.hooksPath must be a real directory
+// — /dev/null works on macOS and is not a directory on Windows), and an empty
+// gitconfig used for both GIT_CONFIG_GLOBAL and GIT_CONFIG_SYSTEM so the
+// builder's own git config (insteadOf URL rewrites, a global hooksPath, a
+// credential helper) cannot influence the fetch.
+//
+// Pure-ish: filesystem only. No DB, no network, no doorway — so it is unit
+// testable and safe to require from a CLI.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// modules/security/artifact-scan/ -> modules/security/ -> modules/ -> repo root
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+// Fail-closed budget. Exceeding any of these aborts the scan and records a
+// finding — it never silently truncates, because a scan that quietly stopped
+// reading at 80% of a repo and still says "no findings" is a lie.
+const CAPS = Object.freeze({
+  maxFiles: 5000,
+  maxBytes: 64 * 1024 * 1024, // 64 MiB across the whole artifact
+  cloneTimeoutMs: 120_000,
+});
+
+// A directory is "sync-backed" if any segment names a known consumer-sync root.
+// Deliberately a name test rather than a path test: OneDrive/Dropbox relocate,
+// and the property we care about ("anything written here is uploaded") travels
+// with the folder, not with one machine's absolute path.
+const SYNC_SEGMENTS = ['onedrive', 'dropbox', 'google drive', 'icloud drive'];
+
+function isSyncBacked(p) {
+  return path
+    .resolve(p)
+    .split(/[\\/]/)
+    .some((seg) => SYNC_SEGMENTS.includes(seg.toLowerCase()));
+}
+
+// Lexical containment: is `candidate` equal to, or under, `root`? Directional on
+// purpose — path.relative escaping upward ('..') or returning an absolute path
+// both mean "outside". Used to reject a quarantine site, and by callers to keep
+// derived paths inside the pen.
+function isInside(root, candidate) {
+  const rel = path.relative(path.resolve(root), path.resolve(candidate));
+  if (rel === '') return true;
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// Why a chosen site is unusable, or null when it is fine. Split out from
+// createQuarantine so the rule set is directly testable without touching disk.
+function siteRefusal(site, forbiddenRoots) {
+  if (isInside(REPO_ROOT, site)) return `inside the repository (${REPO_ROOT})`;
+  if (isSyncBacked(site)) return 'inside a cloud-sync folder (it would upload the artifact)';
+  for (const root of forbiddenRoots) {
+    if (!root) continue;
+    if (isInside(root, site)) return `inside a workspace root (${root}) where its CLAUDE.md could auto-load`;
+  }
+  return null;
+}
+
+// Build a fresh, uniquely-named pen.
+//
+// `forbiddenRoots` is REQUIRED, not optional-with-an-empty-default. Workspace
+// isolation is the primary defense against an artifact's own CLAUDE.md being
+// auto-loaded as instructions, and a defense that silently does nothing when a
+// caller forgets a parameter is not a defense. Callers with genuinely no
+// workspace roots must say so by passing [] explicitly. The repo root and sync
+// folders are refused unconditionally regardless.
+//
+// Returns { root, pristineDir, mirrorDir, hooksDir, gitConfigFile, cleanup() }.
+// pristineDir holds the bytes no model is ever allowed to read; mirrorDir is
+// where the scrubbed reading-room copy is written (task 1002543).
+function createQuarantine({ tmpRoot = os.tmpdir(), forbiddenRoots } = {}) {
+  if (!Array.isArray(forbiddenRoots)) {
+    throw new Error(
+      'createQuarantine requires forbiddenRoots: string[] — the workspace roots a quarantine must never live under. ' +
+        'Pass [] explicitly if this caller genuinely has none.'
+    );
+  }
+  const refusal = siteRefusal(tmpRoot, forbiddenRoots);
+  if (refusal) {
+    throw new Error(
+      `Refusing to create a quarantine under ${tmpRoot} — it is ${refusal}. ` +
+        'Pass a different tmpRoot outside the repo, outside any sync folder, and outside every workspace root.'
+    );
+  }
+
+  const root = fs.mkdtempSync(path.join(tmpRoot, 'bongos-scan-'));
+  // mkdtemp resolves through whatever tmpRoot really is (on macOS /tmp is a
+  // symlink to /private/tmp), so re-check the REAL location before we trust it.
+  const realRoot = fs.realpathSync(root);
+  const realRefusal = siteRefusal(realRoot, forbiddenRoots);
+  if (realRefusal) {
+    fs.rmSync(root, { recursive: true, force: true });
+    throw new Error(`Refusing to use quarantine ${realRoot} — it resolves ${realRefusal}.`);
+  }
+
+  const pristineDir = path.join(realRoot, 'pristine');
+  const mirrorDir = path.join(realRoot, 'mirror');
+  const hooksDir = path.join(realRoot, 'empty-hooks');
+  const gitConfigFile = path.join(realRoot, 'empty-gitconfig');
+
+  fs.mkdirSync(mirrorDir);
+  fs.mkdirSync(hooksDir); // must exist and be EMPTY: git's core.hooksPath target
+  fs.writeFileSync(gitConfigFile, '', 'utf8');
+  // pristineDir is deliberately NOT created — `git clone` wants to create it.
+
+  return {
+    root: realRoot,
+    pristineDir,
+    mirrorDir,
+    hooksDir,
+    gitConfigFile,
+    cleanup() {
+      fs.rmSync(realRoot, { recursive: true, force: true });
+    },
+  };
+}
+
+module.exports = {
+  CAPS,
+  REPO_ROOT,
+  createQuarantine,
+  siteRefusal,
+  isSyncBacked,
+  isInside,
+};

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 };