nsauditor-ai 0.2.53 → 0.2.55

package/utils/run_chain.mjs

@@ -0,0 +1,296 @@
+// Tamper-EVIDENCE for run records: a SHA-256 chain, no keys, no egress, no new dependency.
+//
+// ⚠️ SAY WHAT IT IS NOT. A chain stored on the same disk as the records it covers is defeated by
+// an attacker who recomputes every successor. This is evidence against accidental corruption,
+// partial restore and unsophisticated edits — NOT tamper-proofing against host-level access, and
+// NOT non-repudiation: nothing here is signed and nothing names an author. Ed25519 + custody is a
+// separate, heavier property. The delta engine carries that sentence into its own output, because
+// a limit that lives only in documentation is a limit the reader never meets.
+//
+// ⚠️ NO CANONICALISER, DELIBERATELY. The digest covers the EXACT BYTES ON DISK — read back, never
+// re-serialised from the in-memory object. Two recorded incidents say why: a hand-rolled
+// canonicaliser that serialised `new Date()` as `{}` (signer and verifier shared the bug, so it
+// was invisible in both directions), and the 2026-09-14 sample pack whose envelope digests were
+// computed over RAW bytes while the archive shipped SANITIZED ones — 72 of 96 digests named bytes
+// that were never in the archive. Hash what you PERSIST.
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+// ⚠️ SELF-CONTAINED BY NECESSITY: `run_record` imports the sealer from here, so importing the
+// path helper back from it would be a cycle. The filename shape is one line and is pinned by
+// the tests in both modules.
+const runRecordPath = (outRoot, runId) => path.join(outRoot, `scan_run_${runId}.json`);
+
+const RUN_FILE_RE = /^scan_run_(.+)\.json$/;
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+export function chainDigestPath(outRoot, runId) {
+  return path.join(outRoot, `scan_run_${runId}.sha256`);
+}
+
+// ⚠️ THE CHAIN COVERED THE INDEX AND NOT THE EVIDENCE, and the two are different files. The run
+// record carries no findings; the delta reads THESE, in each written host's directory. Until
+// 2026-09-20 nothing hashed them, so deleting a finding from a sealed baseline left the verdict at
+// `chain-verified` while the comparison moved — and five published surfaces said an altered
+// baseline is detected and refused. Hash what the CONSUMER reads, not merely what the writer
+// indexes.
+export const HOST_EVIDENCE_FILES = Object.freeze(['scan_conclusion_raw.json', 'scan_finding_queue.json']);
+
+/**
+ * Digest every evidence file of one written host directory, for sealing INTO the record.
+ * ⚠️ AN ABSENT FILE IS SEALED AS AN EXPLICIT `null`, NEVER OMITTED and never a fabricated digest.
+ * Omitting it would make its later APPEARANCE invisible, and adding a `scan_finding_queue.json` to
+ * a sealed baseline injects findings into the comparison — which moves rows out of `resolved` or
+ * into `new` just as surely as editing one does.
+ * A file that exists but cannot be READ is neither: it is left out and warned, because recording
+ * it as absent would accuse it of appearing later, and this module's rule is that not-measured
+ * must never render as tampering.
+ */
+export async function digestHostEvidence(outRoot, dir) {
+  const out = {};
+  for (const name of HOST_EVIDENCE_FILES) {
+    try {
+      out[name] = sha256(await fsp.readFile(path.join(outRoot, dir, name)));
+    } catch (e) {
+      if (e?.code === 'ENOENT') out[name] = null;
+      else console.warn(`[RunChain] could not digest ${dir}/${name}: ${e?.message || e}`);
+    }
+  }
+  return out;
+}
+
+// Sealed at FINALIZE and never before: the record is rewritten N+2 times per run (start, one
+// append per host, finalize), so a digest taken earlier names bytes that are meant to change.
+export async function sealRunRecord(outRoot, runId) {
+  try {
+    const digest = sha256(await fsp.readFile(runRecordPath(outRoot, runId)));
+    await fsp.writeFile(chainDigestPath(outRoot, runId), `${digest}\n`, 'utf8');
+    return digest;
+  } catch (e) {
+    console.warn(`[RunChain] could not seal run record: ${e?.message || e}`);
+    return null;
+  }
+}
+
+// The digest of the most recently finalized record in this out root, for the NEXT run to carry as
+// its `prevDigest`. Null when there is none — a first run is not a broken chain.
+// ⚠️ ONE ORDERING FOR THE CHAIN AND FOR `--since prior`, AND IT KEYS ON THE RECORD'S CONTENTS.
+// This used to sort run-record FILENAMES lexically and take the last. `newRunId()` is
+// `<ISO-to-the-SECOND>-<6 random hex>`, so for two records written inside the same second the
+// predecessor was decided by the RANDOM SUFFIX — the chain did not reliably reflect run order,
+// and `--since prior` resolves its baseline through that chain while the view's own comment says
+// silently changing a comparison's subject is the one thing the command does not do. A filename
+// sort is wrong at EVERY second boundary even with a monotonic id, which is why the repair is the
+// key and not the id. `startedAt` is millisecond-precise (`new Date().toISOString()`) and is
+// already what `listRunRecords` sorts on, so this ADOPTS that ordering rather than inventing one.
+//
+// STRICTLY PRECEDES: two runs that started in the same millisecond have no recoverable order, so
+// neither may claim the other — inventing one would be the same defect wearing a better key. Among
+// records sharing the newest qualifying `startedAt` the tie breaks on `runId`: arbitrary, but
+// DETERMINISTIC, which is the property that was missing.
+export function predecessorOf(records, startedAt) {
+  const before = (records ?? []).filter((r) => r?.startedAt && String(r.startedAt) < String(startedAt));
+  if (!before.length) return null;
+  return before.sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt))
+    || String(b.runId ?? '').localeCompare(String(a.runId ?? '')))[0];
+}
+
+// ⚠️ READS THE RECORDS RATHER THAN IMPORTING `listRunRecords`: `run_record.mjs` imports THIS
+// module, so importing it back would be a cycle. The parse is the same one, kept local.
+async function readRunRecords(outRoot) {
+  let names = [];
+  try { names = await fsp.readdir(outRoot); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    if (!RUN_FILE_RE.test(n)) continue;
+    try { out.push(JSON.parse(await fsp.readFile(path.join(outRoot, n), 'utf8'))); } catch { /* not a run */ }
+  }
+  return out;
+}
+
+/**
+ * Every run-record digest in this out root, hashed ONCE. `verifyRunChain` resolves `linkedTo`
+ * existentially — "does any record here still hash to it?" — and doing that per call makes a
+ * caller that verifies N records do N passes over N files.
+ *
+ * ⚠️ THE COST IS ON THE REFUSAL PATH, which is why it is worth closing even though nothing is
+ * wrong: `scan_delta_view` verifies every OTHER record only when it is already refusing, so the
+ * command got slowest exactly when a baseline was broken and an operator was waiting on the
+ * answer. Same "worst precisely when it matters" shape this repo records about gate:cascade's
+ * partial-fetch false clean — there it cost correctness, here only time.
+ *
+ * Pass the result as `opts.linkIndex` to `verifyRunChain`. Omitting it is unchanged behaviour,
+ * so no caller is obliged to know about this.
+ */
+export async function buildRunRecordDigestIndex(outRoot) {
+  const index = new Set();
+  let names = [];
+  try { names = await fsp.readdir(outRoot); } catch { return index; }
+  for (const n of names) {
+    if (!RUN_FILE_RE.test(n)) continue;
+    try { index.add(sha256(await fsp.readFile(path.join(outRoot, n)))); } catch { /* unreadable: not a link target */ }
+  }
+  return index;
+}
+
+/**
+ * The digest a run starting at `startedAt` should link to: the most recent SEALED record that
+ * started before it. SEALED is required here and only here — the chain can only link to a digest.
+ * `--since prior` deliberately does NOT skip an unsealed record: skipping would compare against an
+ * older run silently, while using it merely earns the disclosed `baseline-unchained` limit.
+ * Disclose, never substitute.
+ * ⚠️ `startedAt` is REQUIRED. Called without it the old whole-tree "latest" is not recoverable
+ * from a correct ordering, so it returns null rather than guessing — a wrong link is worse than
+ * an absent one, and an absent one reads as a chain head.
+ */
+export async function latestSealedDigest(outRoot, startedAt) {
+  if (!startedAt) return null;
+  const sealed = [];
+  for (const rec of await readRunRecords(outRoot)) {
+    if (!rec?.runId) continue;
+    try {
+      const d = (await fsp.readFile(chainDigestPath(outRoot, rec.runId), 'utf8')).trim();
+      if (d) sealed.push(rec);
+    } catch { /* unsealed: cannot be linked to */ }
+  }
+  const prev = predecessorOf(sealed, startedAt);
+  if (!prev) return null;
+  try { return (await fsp.readFile(chainDigestPath(outRoot, prev.runId), 'utf8')).trim() || null; }
+  catch { return null; }
+}
+
+/**
+ * @returns {{status:'chain-verified'|'chain-broken'|'chain-absent'|'chain-unreadable', reason:string,
+ *            digest?:string, linkedTo?:string|null, linkBroken?:boolean}}
+ * ⚠️ FOUR STATES, NOT TWO, AND THE DISTINCTION IS THE POINT. `chain-absent` (a record written
+ * before this shipped) and `chain-unreadable` (we could not measure) are NOT `chain-broken`.
+ * Rendering "nothing was checked" as "tampering" accuses honest evidence; rendering it as
+ * "verified" is the false clean. Both are their own verdict.
+ */
+export async function verifyRunChain(outRoot, runId, opts = {}) {
+  let bytes;
+  try { bytes = await fsp.readFile(runRecordPath(outRoot, runId)); }
+  catch { return { status: 'chain-unreadable', reason: 'the run record itself could not be read' }; }
+
+  // ⚠️ "PREDATES CHAINING" AND "WAS UNSEALED" ARE DIFFERENT FACTS, AND THEY ARE SEPARABLE
+  // DETERMINISTICALLY. This returned `chain-absent` for ANY missing sidecar — so deleting the
+  // sidecar, which is the unsophisticated edit the label claims to catch, downgraded a REFUSAL
+  // into a limit with a FALSE CAUSE: it told the operator the record was old. Every record
+  // `writeRunStart` has produced since chaining carries the `prevDigest` KEY, so a record that
+  // has the key and no sidecar was sealed and then unsealed. The key is checked rather than the
+  // sidecar's absence, so a genuinely pre-chaining record keeps its honest `chain-absent`.
+  let recorded;
+  try { recorded = (await fsp.readFile(chainDigestPath(outRoot, runId), 'utf8')).trim(); }
+  catch {
+    let parsed = null;
+    try { parsed = JSON.parse(bytes.toString('utf8')); } catch { /* unparseable: treat as pre-chaining */ }
+    if (parsed && typeof parsed === 'object' && 'prevDigest' in parsed) {
+      return { status: 'chain-unreadable',
+        reason: 'this record was written after chaining shipped (it carries a prevDigest) and its digest '
+          + 'sidecar is gone — removed, or never written; alteration can neither be confirmed nor ruled out' };
+    }
+    return { status: 'chain-absent', reason: 'no digest sidecar — this record predates chained run records' };
+  }
+
+  if (!/^[0-9a-f]{64}$/i.test(recorded)) {
+    return { status: 'chain-unreadable', reason: 'the digest sidecar is present but is not a SHA-256 digest' };
+  }
+  const actual = sha256(bytes);
+  if (actual !== recorded.toLowerCase()) {
+    return { status: 'chain-broken', digest: actual, reason: 'the run record does not match the digest recorded when it was sealed' };
+  }
+
+  // ── THE EVIDENCE, not just the index. Verified only after the record's own digest matches,
+  // because the digests being checked are READ FROM that record: checking them first would be
+  // trusting bytes that have not been vouched for yet.
+  let parsed = null;
+  try { parsed = JSON.parse(bytes.toString('utf8')); } catch { /* the digest matched, so this is a parse we can survive */ }
+  const written = Array.isArray(parsed?.hostsWritten) ? parsed.hostsWritten : [];
+  // TWO POPULATIONS, COUNTED SEPARATELY — see the coverage clause below for why one number lies.
+  let filesPresent = 0;
+  let filesAbsent = 0;
+  let hostsUncovered = 0;
+  for (const h of written) {
+    if (!h?.digests || typeof h.digests !== 'object') { hostsUncovered += 1; continue; }
+    for (const [name, expected] of Object.entries(h.digests)) {
+      const where = `${h.dir}/${name}`;
+      let actual = null;
+      try {
+        actual = sha256(await fsp.readFile(path.join(outRoot, h.dir, name)));
+      } catch (e) {
+        // ⚠️ ENOENT IS A MEASUREMENT ("it is not there"); anything else is a FAILURE to measure,
+        // and the two must not share a verdict. Reporting an unreadable file as missing would
+        // accuse honest evidence of having been deleted.
+        if (e?.code !== 'ENOENT') {
+          return { status: 'chain-unreadable',
+            reason: `the findings file ${where} is sealed with this record but could not be read, so alteration could neither be confirmed nor ruled out` };
+        }
+      }
+      if (expected === null && actual !== null) {
+        return { status: 'chain-broken',
+          reason: `the findings file ${where} did not exist when this record was sealed and exists now — findings added to a baseline after the fact change the comparison exactly as edited ones do` };
+      }
+      if (expected !== null && actual === null) {
+        return { status: 'chain-broken',
+          reason: `the findings file ${where} was sealed with this record and is now missing` };
+      }
+      if (expected !== null && actual !== expected) {
+        return { status: 'chain-broken', digest: actual,
+          reason: `the findings file ${where} does not match the digest sealed with the record` };
+      }
+      if (expected === null) filesAbsent += 1; else filesPresent += 1;
+    }
+  }
+
+  // The LINK. `prevDigest` names a digest, not an id, so the check is existential: does any record
+  // in this out root still hash to it? If none does, this record vouches for bytes that no longer
+  // exist — which is what a rewritten predecessor looks like from here.
+  const linkedTo = parsed?.prevDigest ?? null;
+  let linkBroken = false;
+  if (linkedTo) {
+    // ⚠️ AN INDEX IF THE CALLER SHARES ONE, THE SAME SCAN IF NOT. A caller verifying many records
+    // builds it once (`buildRunRecordDigestIndex`); a caller verifying one pays nothing extra and
+    // needs to know nothing. The two paths must answer identically — `tests/run_chain_link_cost`
+    // asserts the verdicts alongside the cost, because a cheaper loop that verifies less would
+    // satisfy a pure counting assertion perfectly.
+    if (opts?.linkIndex) {
+      linkBroken = !opts.linkIndex.has(linkedTo);
+    } else {
+      linkBroken = true;
+      let names = [];
+      try { names = await fsp.readdir(outRoot); } catch { /* unreadable dir */ }
+      for (const n of names) {
+        if (!RUN_FILE_RE.test(n)) continue;
+        try {
+          if (sha256(await fsp.readFile(path.join(outRoot, n))) === linkedTo) { linkBroken = false; break; }
+        } catch { /* skip */ }
+      }
+    }
+  }
+  // ⚠️ THE REASON STATES ITS OWN COVERAGE, because `chain-verified` over a record that sealed no
+  // findings files claims more than it measured — and the surfaces that quote this verdict say an
+  // altered BASELINE is refused, which is a claim about the findings.
+  // ⚠️ TWO POPULATIONS, NAMED SEPARATELY, AND THE FIRST DRAFT COLLAPSED THEM INTO ONE NUMBER THAT
+  // OVERSTATED. It read "6 sealed findings file(s)" on the first REAL record this clause ever
+  // described — a three-host cloud run where only THREE findings files exist and the other three
+  // entries are recorded ABSENCES sealed as `null`. A reader counts six files on disk; there are
+  // three. That is the count-that-says-more-than-it-measured class, inside the very sentence added
+  // to stop `chain-verified` from overclaiming, which is why it is named rather than rounded off.
+  const coverage = hostsUncovered > 0
+    ? `; the findings files of ${hostsUncovered} written host(s) were NOT covered by this record `
+      + '(it predates per-host sealing), so alteration of those files could not be ruled out'
+    : (written.length
+      ? `, together with ${filesPresent} findings file(s) verified · ${filesAbsent} recorded absent, `
+        + `verified still absent, across ${written.length} written host(s)`
+      : '');
+  return {
+    status: 'chain-verified',
+    digest: actual,
+    linkedTo,
+    linkBroken,
+    filesPresent,
+    filesAbsent,
+    hostsUncovered,
+    reason: `the record matches the digest recorded when it was sealed${coverage}`,
+  };
+}

package/utils/run_record.mjs

@@ -11,6 +11,7 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { CE_RETENTION_MS } from './scan_history.mjs';
+import { sealRunRecord, latestSealedDigest, digestHostEvidence } from './run_chain.mjs';
 
 export const RUN_RECORD_SCHEMA = 1;
 const RUN_FILE_RE = /^scan_run_(.+)\.json$/;
@@ -131,10 +132,26 @@ export async function writeRunStart(outRoot, rec) {
       tier: rec.tier ?? null,
       ceVersion: rec.ceVersion ?? null,
       eeVersion: rec.eeVersion ?? null,
+      // Additive (MINOR per contract-v1 §9; the run record is not a frozen surface). Carries the
+      // digest of the previous finalized record in this out root, so the chain links. Null on a
+      // first run and on any run written before chaining shipped — neither is a broken chain.
+      // ⚠️ DEFAULTED HERE, NOT AT THE CALL SITE. The first version of this required every caller
+      // to pass `prevDigest` and to call `sealRunRecord` after finalizing — and the one shipped
+      // caller did neither, so `report --since` read a chain nothing ever wrote while three
+      // release surfaces said run records ARE sealed and chained. A contract a caller can forget
+      // is one a caller will forget; an explicit value still wins.
+      // ⚠️ `startedAt` IS PASSED, and that is the whole C2/C8 repair: the predecessor is the
+      // most recent SEALED record that STARTED before this one, never the one whose FILENAME
+      // sorts last. `newRunId()` is second-granular with a random suffix, so the old sort chose
+      // at random among runs started in the same second.
+      prevDigest: rec.prevDigest ?? await latestSealedDigest(outRoot, rec.startedAt),
       kevLoaded: Boolean(rec.kevLoaded),
       kevSnapshot: rec.kevSnapshot ?? null,
       epssLoaded: Boolean(rec.epssLoaded),
       epssSnapshot: rec.epssSnapshot ?? null,
+      // Additive (Enterprise 1.1.0 build 5, board item 23): WHERE the NVD store and response cache
+      // this run read live, and what the cache held when the run found it. Set at finalize.
+      nvdCache: rec.nvdCache ?? null,
     };
     return await writeJsonSafe(runRecordPath(outRoot, record.runId), record, 'run start');
   } catch (e) {
@@ -173,12 +190,25 @@ function withRunLock(runId, fn) {
 // scanned" on a client's cover — FALSE, because they WERE scanned; only the record was never
 // finalized. A false "not scanned" over scanned hosts is the exact false clean this record exists
 // to prevent, inverted.
-export async function appendHostWritten(outRoot, runId, { host, dir }) {
+export async function appendHostWritten(outRoot, runId, { host, dir, scopeScanned = null }) {
   return withRunLock(runId, async () => {
     const existing = await readRunRecord(outRoot, runId);
     if (!existing) return false;
+    const normalised = normaliseHost(host);
     existing.hostsWritten = [...(existing.hostsWritten ?? []),
-      { host: normaliseHost(host), dir: path.basename(String(dir ?? '')) }];
+      { host: normalised, dir: path.basename(String(dir ?? '')) }];
+    // ⚠️ WHAT THIS HOST ACTUALLY COVERED, recorded HERE and not at writeRunStart — because at
+    // START nothing has resolved yet, and the flag is not the answer. `--aws-region` is often
+    // omitted, and the set the scan then discovers and uses is the only honest subject. The host
+    // IS the provider on a cloud scan, so a per-host append is a per-provider record for free.
+    //
+    // ⚠️ MEASURED CONSEQUENCE OF NOT HAVING THIS: two live AWS passes differing only in
+    // `--aws-region` reported EIGHT unremediated `eu-west-1` findings as RESOLVED — GuardDuty
+    // NOT ENABLED, Inspector2 DISABLED, default EBS encryption DISABLED. Narrowing a follow-up
+    // scan is a normal operator action, and nothing in the record could tell it from a fix.
+    if (scopeScanned && typeof scopeScanned === 'object') {
+      existing.scopeScanned = { ...(existing.scopeScanned ?? {}), [normalised]: scopeScanned };
+    }
     return Boolean(await writeJsonSafe(runRecordPath(outRoot, runId), existing, 'host append'));
   });
 }
@@ -207,7 +237,31 @@ export async function finalizeRunRecord(outRoot, runId, opts = {}) {
     if ('kevSnapshot' in opts) existing.kevSnapshot = opts.kevSnapshot ?? null;
     if ('epssLoaded' in opts) existing.epssLoaded = Boolean(opts.epssLoaded);
     if ('epssSnapshot' in opts) existing.epssSnapshot = opts.epssSnapshot ?? null;
-    return Boolean(await writeJsonSafe(runRecordPath(outRoot, runId), existing, 'run finalize'));
+    if ('nvdCache' in opts) existing.nvdCache = opts.nvdCache ?? null;
+    // ⚠️ AN ABORTED RUN IS FINALISED AND SEALED TOO, WITH A STATUS (board item 2, CE 0.2.55). A scan
+    // that threw after its start record was written — the SSRF guard refusing an RFC1918 host is the
+    // measured instance — used to leave `finishedAt: null` and no sidecar, and every later report then
+    // labelled that honest refusal `chain-unreadable`: the verdict a STRIPPED sidecar earns. `status`
+    // is `finished` or `aborted`, and an aborted run records WHY. A true crash still leaves the record
+    // open; nothing can finalise from inside a process that no longer runs.
+    if ('status' in opts) existing.status = opts.status ?? null;
+    if ('abortReason' in opts) existing.abortReason = opts.abortReason ?? null;
+    // ⚠️ SEAL THE EVIDENCE, NOT ONLY THE INDEX — and do it HERE, before the record is written, so
+    // the digests are inside the bytes that `sealRunRecord` then covers. Sealing them afterwards
+    // would leave them vouched for by nothing, which is the defect one level up: a digest nobody
+    // digests. The delta reads the per-host findings files, not this record's contents, so a chain
+    // that stops at this file cannot support the published claim that an altered baseline is
+    // refused. Failure to digest one file is warned inside the helper and never fatal, for the
+    // same reason sealing is: a report-side fault must not fail a scan.
+    for (const h of (existing.hostsWritten ?? [])) {
+      if (h?.dir) h.digests = await digestHostEvidence(outRoot, h.dir);
+    }
+    const wrote = Boolean(await writeJsonSafe(runRecordPath(outRoot, runId), existing, 'run finalize'));
+    // SEALED HERE, and only here: the record is rewritten N+2 times per run, so a digest taken
+    // any earlier names bytes that are meant to change. Failure to seal is warned and never fatal —
+    // a report-side fault must not fail a scan, which is the whole promise of this file.
+    if (wrote) await sealRunRecord(outRoot, runId);
+    return wrote;
   });
 }
 
@@ -239,3 +293,49 @@ export async function pruneRunRecordsForCE(outRoot, now = Date.now()) {
   }
   return removed;
 }
+
+/**
+ * THE NVD LOCATION A RUN READ, aggregated across its written hosts (Enterprise 1.1.0 build 5, board
+ * item 23). The CVE set a scan reports depends on which NVD store and response cache it consulted, and
+ * that was a hidden, cwd-relative input nothing recorded. Enterprise now reports it per host
+ * (`nvdStore.path` · `source` · `state` · `responseCache`); this is the run-level claim, and it is
+ * ALL-OR-NOTHING for the same reason `aggregateStoreLoad` is: a location true for some hosts and wrong
+ * for others is worse than none.
+ *   · no host reported one (Community alone, or enrichment never ran) → null, and nothing to say;
+ *   · some hosts did and some did not → null, with a warning naming the counts;
+ *   · the hosts disagree on path or source → null, with a warning naming them;
+ *   · they agree → the location, with `state` and `responseCache` from the FIRST written host: the
+ *     cache as this run found it, before any host of the run wrote to it.
+ * @param {Array<object|null>} perHost - each written host's reported NVD location, in written order
+ * @returns {{ value: object|null, warning: string|null }}
+ */
+export function aggregateNvdCache(perHost) {
+  const all = Array.isArray(perHost) ? perHost : [];
+  const reported = all.filter((v) => v && typeof v.path === 'string' && v.path.length > 0);
+  if (reported.length === 0) return { value: null, warning: null };
+  if (reported.length < all.length) {
+    return { value: null, warning: `NVD location was reported for only ${reported.length} of ${all.length} `
+      + 'written host(s) — recording it as unknown for this run.' };
+  }
+  const distinct = [...new Set(reported.map((v) => `${v.path} (${v.source ?? 'unknown'})`))];
+  if (distinct.length > 1) {
+    return { value: null, warning: `NVD location disagreed across written hosts (${distinct.join(', ')}) — `
+      + 'recording it as unknown for this run.' };
+  }
+  const first = reported[0];
+  return {
+    value: { path: first.path, source: first.source ?? null, state: first.state ?? null,
+      responseCache: first.responseCache ?? null },
+    warning: null,
+  };
+}
+
+/**
+ * The reason an aborted run records: the error's code (else its name) and the FIRST line of its
+ * message, capped at 300 characters — never a stack, which carries local paths (board item 2 (iv)).
+ */
+export function abortReasonOf(err) {
+  const code = err?.code ?? err?.name ?? 'Error';
+  const first = String(err?.message ?? err).split('\n')[0].slice(0, 300);
+  return `${code}: ${first}`;
+}