@clear-capabilities/agentic-security-scanner 0.147.0 → 0.148.0

package/CHANGELOG.md

@@ -11,6 +11,210 @@
 
 
 
+## 0.148.0 - NIST SP 800-171 Rev. 3 (CUI / CMMC basis) as the 10th bundled framework
+
+Adds NIST SP 800-171 Rev. 3 to `/compliance --report <framework>` (aliases
+`800-171` and `cui`), `--walkthrough`, `--gap` and `--format oscal`, plus a
+standalone deep-attestation scanner at `scripts/nist-800-171/scan.py`.
+
+**All 97 requirements are carried, including the 43 this engine cannot assess.**
+Shipping only the code-observable subset would have been a smaller, better-looking
+artifact and a dishonest one, omission reads as coverage. Whole families
+(Awareness and Training, Personnel Security, Physical Protection) and most of
+Incident Response, Maintenance and Media Protection report as requiring manual
+evidence. Ratings: 16 `yes`, 38 `partial`, 43 `no`.
+
+**The `code_testable` rating is ours, not NIST's.** Unlike the AI 600-1 workbook,
+the 800-171 export rates no control for testability. That judgment lives in
+`scripts/nist-800-171/code-testability.json` with a per-requirement rationale, and
+is joined into the generated catalog by `build-catalog.py`. A control with no
+rating is a hard build failure, never a default, defaulting would either invent
+coverage or silently suppress a requirement. The generator is stdlib-only, so
+unlike the openpyxl-based AI 600-1 gate its drift check can never be unrunnable
+for a missing dependency.
+
+**Fixes a real pre-existing bug in the shared evaluator.** `evaluateFramework`,
+behind `--report`/`--walkthrough`/`--gap`/`--format oscal` for *all ten* frameworks
+had no vacuous-satisfaction guard: a scan that read zero files produced empty
+finding buckets, and an empty bucket rendered as `✓ no open findings`. Measured on
+800-171, **32 of 97 controls read `present` off a scan that examined nothing**. The
+guard existed only inside `privacy-framework.js`, whose own comment already named
+`evaluateFramework` as where the hazard originates. The fix reads three count
+fields (a real scan persists `scanned.files` and `_scanMeta.filesScanned` but *not*
+top-level `filesScanned`, which exists only on the in-memory object) and treats
+**absent as unknown, not zero**, degrading requires positive evidence that nothing
+was examined, so a genuinely clean project is unaffected. 2419/2419 posture tests
+pass with no test file modified.
+
+**One scanning engine, not two.** `scripts/nist-compliance/scan.py` now reads its
+framework identity from the catalog it is given rather than from hardcoded strings,
+and the 800-171 scanner is a thin wrapper supplying defaults. This keeps exactly one
+copy of the ReDoS-hardened matcher, two copies would mean a fix to one silently
+missing the other. The AI 600-1 scanner's md/csv/json output was pinned before and
+after and is byte-identical.
+
+**Fixes OSCAL documents that could not be attested.** Every compliance OSCAL export
+read its timestamp from `scan._scanMeta.startedAt`, a key scans do not have, they
+carry `startedAt` at the top level. So `_when()` fell through to `new Date()` at emit
+time, which that function's own comment says must never happen, because "two emits of
+one scan then differ and the artifact cannot be attested." Two emits of the same scan
+genuinely differed. Fixed at all three call sites (both in `bin/agentic-security.js`,
+one in `commands/compliance.md`); `last-modified` is now the scan's own clock, and with
+`AGENTIC_SECURITY_DETERMINISTIC=1` the document is byte-identical across runs. This
+affected every framework, not just the new one.
+
+Also: the `nist-catalog-freshness` release gate now iterates every generated catalog
+instead of naming one script path, `docs/compliance/nist-800-171-r3-coverage.md` is
+pointer-based rather than restating counts that would drift, and that page carries a
+recorded walkthrough (`docs/brand/nist-800-171-demo.tape`, regenerable with `vhs`)
+showing assess → remediate → re-assess against `examples/demo-app`.
+
+**Fixes `module:scan-history`, which could never resolve.** The evaluator's artifact table
+listed only `scan-history/` (a directory) while an ordinary scan writes `scan-history.json`
+(a file), both spellings are real in this codebase (`findings-memory.js` uses the
+directory; `security-trend.js` and `router.js` use the file), but only one was listed. Every
+control mapped to it reported the artifact missing even when the history existed, across
+five bundled frameworks. Table entries may now be an array of acceptable paths, and any one
+of them evidences the control.
+
+Measured effect, because a change that moves compliance verdicts should be quantified rather
+than asserted: **no control anywhere became `satisfied`**, `present` held at 43 across all
+five frameworks. Eight controls moved `manual` → `partial` (2 eu-ai-act, 1 hipaa, 4
+nist-800-171-r3, 1 nist-ai-600-1, 1 nist-privacy-1-1). Those are artifact-existence controls,
+which the honesty model already caps at `partial`, so finding the artifact can only move them
+out of "not assessed", never to satisfied. In OSCAL terms the reports get *stricter*, not
+more flattering: for 800-171 against the demo app, findings went 42 → 46 with satisfied
+unchanged at 28, i.e. four controls moved from unassessed into assessed-and-not-satisfied.
+
+No CMMC assessment and no SPRS score is produced or implied.
+
+## 0.147.5 — Fix: `bench:provenance:check`'s cold-memory sample size was unreliable on GitHub Actions
+
+`v0.147.4`'s tag was pushed but its hosted release-gate run failed before
+reaching `npm publish` — the `dataflow-watch` fix held (the full test suite
+passed cleanly), but `bench/provenance/runner.mjs`'s `bench:provenance:check`
+failed: "only 8/20 iterations produced a usable sample (need >= 10)" for
+`cold.memOverheadRatio`. This is the SAME failure `v0.147.3`'s release run
+also hit (7/20 that time) — two consecutive, reproducible failures on
+GitHub's runners specifically, while this bench passes cleanly (~20/20)
+every time locally, so this is a real platform gap, not one-off noise.
+
+Root cause: `cold.memOverheadRatio` is a per-iteration ratio against the
+without-provenance arm's own peak-RSS delta, and `measure()` skips the
+ratio entirely for an iteration where that delta is `0`
+(`if (without.rssDeltaBytes > 0) { ... }`) — the without-provenance scan is
+only ~40-60ms, short enough that the 10ms-interval peak-RSS poller can
+genuinely observe no net growth for it, especially under a shared runner's
+different GC pacing. `BASELINE.json` itself already records this as
+expected (`memOverheadRatio.n: 19`, one dropped iteration out of 20 even on
+the machine that captured it) — GitHub Actions just drops far more of them
+(a ~35-40% survival rate against RELIABLE_N=10 at N=20 leaves no margin).
+
+Raises `N` from 20 to 60 in `bench/provenance/runner.mjs` — the same
+already-established remedy this exact file used once before for a related
+small-sample fragility (doubling 10→20), extended further given the new,
+worse-than-expected survival rate. `RELIABLE_N` (10) and the regression
+thresholds are unchanged; `BASELINE.json`'s reference values were not
+touched (the measured overhead is well within budget — this was purely a
+sample-count reliability failure, not a regression). Verified locally:
+passes with real margin (cold memory p95 11.42x vs a 24.38x limit), at a
+real but bounded cost — this one bench step now takes ~2:23 instead of
+~40-60s, a release-time-only cost. `v0.147.4` was never published to any
+registry (confirmed via `npm view`). Carries the identical fixes from
+0.147.1-0.147.4 forward.
+
+## 0.147.4 — Fix: close a real fs.watch startup race in `dataflow watch` (test-only; no product behavior change)
+
+`v0.147.3`'s tag was pushed but its hosted release-gate run failed before
+reaching `npm publish` — again `cli/dataflow-watch-2`, but this time raising
+the wait timeout (0.147.3's own fix) did NOT help: it timed out at the
+*full* 90000ms budget with zero rescan output, which the real rescan
+pipeline (~1-2s once triggered) rules out as "merely slow." Root cause: `bin/
+agentic-security.js`'s `cmdDataflowWatch` prints its "watching ... Ctrl-C to
+stop" banner — the exact string these tests poll for as the "watcher is
+live" signal — *before* calling `watchProject()`, which is where
+`fs.watch()` actually arms its (possibly recursive, whole-tree-walking on
+Linux) inotify descriptors. A test file-write landing in that gap produces
+an event inotify never delivers at all — a permanent miss, not a delay —
+which a longer timeout cannot fix by construction.
+
+Fixed with a 1000ms settle delay in the test, inserted between seeing the
+startup banner and writing the trigger file, in both `dataflow-watch-1` and
+`dataflow-watch-2` (`test/cli/dataflow-watch.test.js`). No product code
+changed — `cmdDataflowWatch`'s banner-before-watchProject ordering is real,
+pre-existing behavior, unrelated to anything in 0.147.1-0.147.3, and left
+alone here rather than reordered under release time pressure without full
+confidence in every caller depending on today's ordering. `v0.147.3` was
+never published to any registry (confirmed via `npm view`). Carries the
+identical fixes from 0.147.1-0.147.3 forward.
+
+## 0.147.3 — CI fix: raise dataflow-watch's live-subprocess wait timeout (no functional change from 0.147.2)
+
+Same story as 0.147.2, different test: `v0.147.2`'s hosted release-gate run
+also failed before reaching `npm publish` — `test/cli/dataflow-watch.test.js`'s
+`cli/dataflow-watch-2` polls a real subprocess's live stderr for a
+`DRIFT POLICY VIOLATION` line after triggering a file-watch-driven rescan,
+with a 30000ms budget. That step completes in ~1.4s on a normal machine (a
+~20x margin) but still timed out on this run — this repo's watch mode uses
+Node's native `fs.watch(..., { recursive: true })`
+(`src/posture/watch-mode.js`), documented as slower/less reliable under
+Linux CI runners' inotify handling than on a dev machine. `v0.147.2` was
+never published to any registry (confirmed via `npm view`).
+
+Raises the wait budget from 30000ms to a shared `WAIT_TIMEOUT_MS = 90000`
+across both real-subprocess tests in that file (the ones that depend on the
+file-watch path — an unrelated fast-fail test in the same file was left
+untouched). No product code changed; this carries the identical fixes from
+0.147.1 and 0.147.2 forward.
+
+## 0.147.2 — CI fix: raise the headless-Chrome render timeout (no functional change from 0.147.1)
+
+`v0.147.1`'s tag was pushed but its hosted release-gate run failed before
+ever reaching `npm publish` — `scripts/export-image.mjs`'s `exportPng` test
+hit its own hardcoded 15000ms Chrome render timeout on a slower draw of the
+GitHub Actions runner (the same render took 7983ms on the immediately
+preceding v0.147.0 release run — a ~2x runner-speed swing well within
+normal CI variance, not a regression). `v0.147.1` was never published to
+any registry; this release carries the identical `explore`/`dataflow
+export --format html` fix described below under 0.147.1, plus this one
+timeout change: `RENDER_TIMEOUT_MS` default raised from 15000ms to 30000ms
+in `scripts/export-image.mjs`, giving roughly 4x headroom over the observed
+good-case render time. No other code changed.
+
+## 0.147.1 — Fix: `explore` and `dataflow export --format html` were broken for every real npm/npx install
+
+Both commands located the Data Flow Explorer frontend (`frontend/`, a
+repo-root sibling of `scanner/` in this monorepo) via a fixed relative path
+computed from each module's own `import.meta.url`
+(`path.resolve(HERE, '../../../frontend')` in `static-assets.js`,
+`'../../frontend'` in `generate-html-report.mjs`). That math was correct
+only for the unbundled dev checkout. Once `npm run build` (ncc) split those
+modules into their own `dist/*.index.js` chunks, `import.meta.url` inside
+them reflected `dist/`'s own, shallower location, and the same fixed
+relative math resolved *outside the installed package entirely* — and
+`frontend/` was never part of the published npm tarball to begin with. The
+practical effect: `agentic-security explore .` 404'd on `GET /` for every
+real `npx`/`npm install` user (`{"error":"not found"}`, never an
+index.html), and `dataflow export . --format html` failed outright
+(`ENOENT: no such file or directory, scandir '.../frontend/styles'`). Both
+only ever worked when run from a full monorepo clone.
+
+Fixed by shipping the frontend's servable files inside the published
+package: `scanner/scripts/copy-frontend.mjs` (new) copies `frontend/`'s
+allowlisted files (`index.html`, `src/**/*.js`, top-level `styles/*.css` —
+the exact same allowlist `static-assets.js` already enforced for serving)
+into `scanner/dist/frontend/` as part of `npm run build`; a new shared
+resolver, `scanner/src/shared/frontend-root.js`, replaces both hardcoded
+relative paths with a search-upward strategy that finds the frontend
+correctly regardless of bundling depth. Verified by packing a real tarball
+(`npm pack`) and installing it into an isolated directory with no monorepo
+present: `explore`'s `GET /` now returns 200 with the real `index.html`
+(previously 404), static JS/CSS assets and the token-authenticated
+`/api/v1/graph` endpoint both 200, and `dataflow export --format html`
+exits 0 and writes a real self-contained report (previously exited 2).
+`dpia`/`ropa` export formats were already unaffected (a separate,
+already-self-contained code path) and are unchanged.
+
 ## 0.147.0 — Documentation overhaul: a cohesive assurance-platform story, verified against the shipped code
 
 The 0.144.0 Assurance Hardening release shipped a real 3-state ship verdict,

package/bin/agentic-security.js

@@ -2447,7 +2447,7 @@ async function cmdCompliance(args) {
     if (fmt === 'oscal') {
       const { toOSCALCompliance, complianceRowsFromEvaluation } = await import('../src/report/oscal.js');
       writeStdout(JSON.stringify(
-        toOSCALCompliance(fw, complianceRowsFromEvaluation(evaluation), { startedAt: scan._scanMeta?.startedAt }),
+        toOSCALCompliance(fw, complianceRowsFromEvaluation(evaluation), { startedAt: scan.startedAt || scan._scanMeta?.startedAt }),
         null, 2) + '\n');
       return 0;
     }
@@ -2478,7 +2478,7 @@ async function cmdCompliance(args) {
     const { toOSCALCompliance, complianceRowsFromPrivacy } = await import('../src/report/oscal.js');
     const fwMeta = loadFramework(scanRoot, PRIVACY_FRAMEWORK_ID) || { id: PRIVACY_FRAMEWORK_ID, name: r.frameworkName };
     writeStdout(JSON.stringify(
-      toOSCALCompliance(fwMeta, complianceRowsFromPrivacy(r), { startedAt: scan._scanMeta?.startedAt }),
+      toOSCALCompliance(fwMeta, complianceRowsFromPrivacy(r), { startedAt: scan.startedAt || scan._scanMeta?.startedAt }),
       null, 2) + '\n');
     return args.flags['fail-on'] === 'gap' && r.summary.gap > 0 ? 1 : 0;
   }
@@ -6302,7 +6302,27 @@ async function cmdDataflowWatch(args) {
   // change that makes `scan --watch` exit before it ever watches anything.
 }
 
+// A version below the declared `engines.node` floor is still let through by
+// npm (EBADENGINE is a warning, not an install failure), so on an old Node
+// this file used to either crash deep inside a dependency with a confusing
+// stack, or — on the specific versions handled by the guard below — do
+// nothing at all. Fail fast, once, with a message that names the actual
+// requirement instead.
+function checkNodeVersionOrExit() {
+  const required = __require('../package.json').engines?.node;
+  const requiredMajor = Number(/(\d+)/.exec(required || '')?.[1]);
+  const actualMajor = Number(process.versions.node.split('.')[0]);
+  if (Number.isFinite(requiredMajor) && actualMajor < requiredMajor) {
+    console.error(
+      `agentic-security: requires Node.js ${required} — you're running Node ${process.versions.node}.\n` +
+      `Upgrade Node (e.g. 'nvm install ${requiredMajor}' or https://nodejs.org/) and try again.`
+    );
+    process.exit(1);
+  }
+}
+
 async function main() {
+  checkNodeVersionOrExit();
   const args = parseArgs(process.argv.slice(2));
   const cmd = args._[0];
   try {
@@ -6663,18 +6683,30 @@ async function main() {
 // @clear-capabilities/agentic-security-scanner` install path), Node
 // resolves `import.meta.url` to the symlink's realpath while
 // `process.argv[1]` stays the symlink path as invoked, so the two never
-// match, the guard is always false, and the CLI silently exits with no
-// output. `import.meta.main` is resolved correctly through a symlink —
-// verified live through an actual symlink, not just read about — see the
-// Task 17 fix report. It was added in Node v24.2.0 (backported to
-// v22.18.0) and is currently Stability 1.0 (early development) per Node's
-// own docs — NOT stable, and NOT available on v20.11 as an earlier
-// version of this comment incorrectly claimed. Concretely: it is
-// `undefined` on Node 24.0.0/24.1.x, which satisfy this repo's declared
-// `engines.node: ">=24.0.0"` floor, so `import.meta.main` alone would
-// reproduce this exact bug (main() silently never runs) on a plain
-// non-symlinked invocation under those two point releases. The `??`
-// fallback below covers that gap without bumping the engines floor.
-if (import.meta.main ?? (import.meta.url === `file://${process.argv[1]}`)) {
+// match under a naive comparison. `import.meta.main` is resolved correctly
+// through a symlink — verified live through an actual symlink, not just
+// read about — see the Task 17 fix report. It was added in Node v24.2.0
+// (backported to v22.18.0) and is currently Stability 1.0 (early
+// development) per Node's own docs — NOT stable, and NOT available on
+// v20.11 as an earlier version of this comment incorrectly claimed.
+// Concretely: it is `undefined` on Node 24.0.0/24.1.x, which satisfy this
+// repo's declared `engines.node: ">=24.0.0"` floor, so `import.meta.main`
+// alone would reproduce this exact bug (main() silently never runs) on
+// those two point releases when invoked through the symlinked bin (npx/
+// global install) — the common case, not the exception. The fallback
+// below resolves `process.argv[1]`'s realpath before comparing, so it
+// gives the right answer through a symlink too — verified live against a
+// real symlink, same as the `import.meta.main` claim above — instead of
+// silently exiting with no output on every Node version where
+// `import.meta.main` is undefined (also: <22.18.0, and 23.x).
+function isDirectCliInvocation() {
+  if (import.meta.main !== undefined) return import.meta.main;
+  try {
+    return import.meta.url === `file://${fs.realpathSync(process.argv[1])}`;
+  } catch {
+    return false;
+  }
+}
+if (isDirectCliInvocation()) {
   main();
 }

package/dist/1122.index.js

@@ -232,7 +232,12 @@ function export_image_validTimeoutMs(raw, fallback) {
   if (!Number.isSafeInteger(n) || n < 0 || Object.is(n, -0)) return fallback;
   return n;
 }
-const RENDER_TIMEOUT_MS = export_image_validTimeoutMs(process.env.AGENTIC_SECURITY_CHROME_RENDER_TIMEOUT_MS, 15000);
+// 15000 (the original default) left no headroom: the v0.147.0 release run
+// took 7983ms for this same render on a good draw of the CI runner, and the
+// v0.147.1 run timed out at ~15000ms on a slower draw — a 2x runner-speed
+// swing entirely within normal GitHub Actions variance, not a regression.
+// 30000 gives ~4x headroom over the observed good-case time.
+const RENDER_TIMEOUT_MS = export_image_validTimeoutMs(process.env.AGENTIC_SECURITY_CHROME_RENDER_TIMEOUT_MS, 30000);
 
 function _writeTempHtml(graph, opts) {
   const html = (0,generate_html_report.generateHtmlReport)(graph, opts);
@@ -592,6 +597,8 @@ function bundleFrontendModules(entryAbsPath) {
 
 // EXTERNAL MODULE: ./src/lineage/export-json.js
 var export_json = __webpack_require__(859);
+// EXTERNAL MODULE: ./src/shared/frontend-root.js
+var frontend_root = __webpack_require__(1185);
 ;// CONCATENATED MODULE: ./scripts/generate-html-report.mjs
 // generate-html-report.mjs — Milestone 4, sub-project Self-contained
 // HTML report. Assembles ONE offline-safe HTML document: inline CSS,
@@ -605,8 +612,14 @@ var export_json = __webpack_require__(859);
 
 
 
+
 const HERE = external_node_path_.dirname((0,external_node_url_.fileURLToPath)(import.meta.url));
-const FRONTEND_ROOT = external_node_path_.resolve(HERE, '../../frontend');
+// See src/shared/frontend-root.js: a hardcoded `../../frontend` resolved
+// correctly for this file's unbundled dev location (scanner/scripts/) but
+// broke for the published package, whose build now copies frontend/ into
+// scanner/dist/frontend/ — a different relative depth from this same
+// module once ncc bundles it into a dist/ chunk.
+const FRONTEND_ROOT = (0,frontend_root/* resolveFrontendRoot */.D)(HERE);
 const STYLES_DIR = external_node_path_.join(FRONTEND_ROOT, 'styles');
 const ENTRY_PATH = external_node_path_.join(FRONTEND_ROOT, 'src', 'export-entry.js');
 
@@ -697,6 +710,70 @@ ${bundledJs}
 }
 
 
+/***/ }),
+
+/***/ 1185:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   D: () => (/* binding */ resolveFrontendRoot)
+/* harmony export */ });
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3024);
+/* harmony import */ var node_path__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6760);
+// frontend-root.js — locates the Data Flow Explorer's `frontend/` assets
+// (index.html/src/styles) regardless of whether this code is running:
+//   - unbundled, straight out of scanner/src/ or scanner/scripts/ (dev/test —
+//     frontend/ is a monorepo sibling of scanner/, 2-3 levels up), or
+//   - bundled by `npm run build` (ncc splits a dynamic import() into its own
+//     chunk file physically written into scanner/dist/, so import.meta.url
+//     inside that chunk reflects dist/'s own location, not the original
+//     source file's — a fixed relative-levels-up path that was correct for
+//     one depth breaks silently at the other), or
+//   - installed from the published npm package, where the build copies
+//     frontend/'s servable files into scanner/dist/frontend/ (a sibling of
+//     the chunk file itself, i.e. 0 levels up) — see scripts/copy-frontend.mjs.
+//
+// Rather than hardcode one of those depths (the bug this file fixes: every
+// consumer used to hardcode the dev-only depth), search upward from the
+// caller's own directory and take the first candidate that actually has a
+// frontend/index.html on disk. Never guessed silently past that — a caller
+// with no match anywhere gets a clear, actionable error instead of a
+// downstream ENOENT/404 with no indication why.
+
+
+
+
+const MAX_LEVELS_UP = 4;
+
+/**
+ * @param {string} startDir - `path.dirname(fileURLToPath(import.meta.url))`
+ *   of the CALLING module (not this file) — each caller's own bundled/
+ *   unbundled location determines which candidate depth resolves.
+ * @returns {string} absolute path to a real `frontend/` directory containing
+ *   `index.html`.
+ * @throws if no candidate directory up to MAX_LEVELS_UP contains one.
+ */
+function resolveFrontendRoot(startDir) {
+  const tried = [];
+  for (let up = 0; up <= MAX_LEVELS_UP; up++) {
+    const candidate = node_path__WEBPACK_IMPORTED_MODULE_1__.resolve(startDir, ...Array(up).fill('..'), 'frontend');
+    tried.push(candidate);
+    // Every caller invokes resolveFrontendRoot() once, at module-load time,
+    // to compute a top-level FRONTEND_ROOT const (see static-assets.js /
+    // generate-html-report.mjs) — never per-request inside the explore
+    // server's request handler. At most MAX_LEVELS_UP+1 (5) sync stat calls
+    // at process startup is not a request-path DoS surface.
+    if (node_fs__WEBPACK_IMPORTED_MODULE_0__.existsSync(node_path__WEBPACK_IMPORTED_MODULE_1__.join(candidate, 'index.html'))) return candidate; // agentic-security-ignore: dos-sync-io
+  }
+  throw new Error(
+    `resolveFrontendRoot: no frontend/index.html found searching up from ${startDir}. ` +
+    `Tried: ${tried.join(', ')}. If you're running from a source checkout, run \`npm run build\` ` +
+    `first (it copies frontend/ into scanner/dist/frontend/); if you're running the published ` +
+    `package, this indicates a packaging defect — report it.`
+  );
+}
+
+
 /***/ })
 
 };

package/dist/3180.index.js

@@ -197,6 +197,8 @@ function bundleFrontendModules(entryAbsPath) {
 
 // EXTERNAL MODULE: ./src/lineage/export-json.js
 var export_json = __webpack_require__(859);
+// EXTERNAL MODULE: ./src/shared/frontend-root.js
+var frontend_root = __webpack_require__(1185);
 ;// CONCATENATED MODULE: ./scripts/generate-html-report.mjs
 // generate-html-report.mjs — Milestone 4, sub-project Self-contained
 // HTML report. Assembles ONE offline-safe HTML document: inline CSS,
@@ -210,8 +212,14 @@ var export_json = __webpack_require__(859);
 
 
 
+
 const HERE = external_node_path_.dirname((0,external_node_url_.fileURLToPath)(import.meta.url));
-const FRONTEND_ROOT = external_node_path_.resolve(HERE, '../../frontend');
+// See src/shared/frontend-root.js: a hardcoded `../../frontend` resolved
+// correctly for this file's unbundled dev location (scanner/scripts/) but
+// broke for the published package, whose build now copies frontend/ into
+// scanner/dist/frontend/ — a different relative depth from this same
+// module once ncc bundles it into a dist/ chunk.
+const FRONTEND_ROOT = (0,frontend_root/* resolveFrontendRoot */.D)(HERE);
 const STYLES_DIR = external_node_path_.join(FRONTEND_ROOT, 'styles');
 const ENTRY_PATH = external_node_path_.join(FRONTEND_ROOT, 'src', 'export-entry.js');
 
@@ -302,6 +310,70 @@ ${bundledJs}
 }
 
 
+/***/ }),
+
+/***/ 1185:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   D: () => (/* binding */ resolveFrontendRoot)
+/* harmony export */ });
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3024);
+/* harmony import */ var node_path__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6760);
+// frontend-root.js — locates the Data Flow Explorer's `frontend/` assets
+// (index.html/src/styles) regardless of whether this code is running:
+//   - unbundled, straight out of scanner/src/ or scanner/scripts/ (dev/test —
+//     frontend/ is a monorepo sibling of scanner/, 2-3 levels up), or
+//   - bundled by `npm run build` (ncc splits a dynamic import() into its own
+//     chunk file physically written into scanner/dist/, so import.meta.url
+//     inside that chunk reflects dist/'s own location, not the original
+//     source file's — a fixed relative-levels-up path that was correct for
+//     one depth breaks silently at the other), or
+//   - installed from the published npm package, where the build copies
+//     frontend/'s servable files into scanner/dist/frontend/ (a sibling of
+//     the chunk file itself, i.e. 0 levels up) — see scripts/copy-frontend.mjs.
+//
+// Rather than hardcode one of those depths (the bug this file fixes: every
+// consumer used to hardcode the dev-only depth), search upward from the
+// caller's own directory and take the first candidate that actually has a
+// frontend/index.html on disk. Never guessed silently past that — a caller
+// with no match anywhere gets a clear, actionable error instead of a
+// downstream ENOENT/404 with no indication why.
+
+
+
+
+const MAX_LEVELS_UP = 4;
+
+/**
+ * @param {string} startDir - `path.dirname(fileURLToPath(import.meta.url))`
+ *   of the CALLING module (not this file) — each caller's own bundled/
+ *   unbundled location determines which candidate depth resolves.
+ * @returns {string} absolute path to a real `frontend/` directory containing
+ *   `index.html`.
+ * @throws if no candidate directory up to MAX_LEVELS_UP contains one.
+ */
+function resolveFrontendRoot(startDir) {
+  const tried = [];
+  for (let up = 0; up <= MAX_LEVELS_UP; up++) {
+    const candidate = node_path__WEBPACK_IMPORTED_MODULE_1__.resolve(startDir, ...Array(up).fill('..'), 'frontend');
+    tried.push(candidate);
+    // Every caller invokes resolveFrontendRoot() once, at module-load time,
+    // to compute a top-level FRONTEND_ROOT const (see static-assets.js /
+    // generate-html-report.mjs) — never per-request inside the explore
+    // server's request handler. At most MAX_LEVELS_UP+1 (5) sync stat calls
+    // at process startup is not a request-path DoS surface.
+    if (node_fs__WEBPACK_IMPORTED_MODULE_0__.existsSync(node_path__WEBPACK_IMPORTED_MODULE_1__.join(candidate, 'index.html'))) return candidate; // agentic-security-ignore: dos-sync-io
+  }
+  throw new Error(
+    `resolveFrontendRoot: no frontend/index.html found searching up from ${startDir}. ` +
+    `Tried: ${tried.join(', ')}. If you're running from a source checkout, run \`npm run build\` ` +
+    `first (it copies frontend/ into scanner/dist/frontend/); if you're running the published ` +
+    `package, this indicates a packaging defect — report it.`
+  );
+}
+
+
 /***/ })
 
 };

package/dist/5051.index.js

@@ -25,6 +25,8 @@ var security = __webpack_require__(6944);
 var routes = __webpack_require__(4268);
 // EXTERNAL MODULE: external "node:url"
 var external_node_url_ = __webpack_require__(3136);
+// EXTERNAL MODULE: ./src/shared/frontend-root.js
+var frontend_root = __webpack_require__(1185);
 ;// CONCATENATED MODULE: ./src/server/static-assets.js
 // static-assets.js — Milestone 3, sub-project Wire.
 //
@@ -43,13 +45,18 @@ var external_node_url_ = __webpack_require__(3136);
 
 
 
-// Located the SAME way scanner/src/mcp/server.js locates files relative to
-// its own module (path.dirname(fileURLToPath(import.meta.url))) — the real,
-// existing precedent for this pattern in this codebase, not a new one.
-// scanner/src/server/ -> ../../../frontend, computed (not guessed) and
-// confirmed to resolve to the real frontend/ directory.
+
+// Located relative to this module's own directory (path.dirname(
+// fileURLToPath(import.meta.url)), the same pattern scanner/src/mcp/server.js
+// uses), but via resolveFrontendRoot's search-upward strategy rather than a
+// single hardcoded relative depth — a fixed `../../../frontend` resolved
+// correctly for this file's unbundled dev location but broke (silently, at
+// runtime, for every real npx/npm user) once `npm run build` split this
+// module into its own dist/ chunk, whose import.meta.url reflects dist/'s
+// own shallower location. See src/shared/frontend-root.js for the full story
+// and scripts/copy-frontend.mjs for the build-time copy this now finds.
 const _here = external_node_path_.dirname((0,external_node_url_.fileURLToPath)(import.meta.url));
-const FRONTEND_ROOT = external_node_path_.resolve(_here, '..', '..', '..', 'frontend');
+const FRONTEND_ROOT = (0,frontend_root/* resolveFrontendRoot */.D)(_here);
 
 const CONTENT_TYPE_MAP = Object.freeze({
   '.html': 'text/html; charset=utf-8',
@@ -765,6 +772,70 @@ function isValidHost(hostHeader, expectedPort) {
 const CSP_HEADER_VALUE = "default-src 'none'; frame-ancestors 'none'";
 
 
+/***/ }),
+
+/***/ 1185:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   D: () => (/* binding */ resolveFrontendRoot)
+/* harmony export */ });
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3024);
+/* harmony import */ var node_path__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6760);
+// frontend-root.js — locates the Data Flow Explorer's `frontend/` assets
+// (index.html/src/styles) regardless of whether this code is running:
+//   - unbundled, straight out of scanner/src/ or scanner/scripts/ (dev/test —
+//     frontend/ is a monorepo sibling of scanner/, 2-3 levels up), or
+//   - bundled by `npm run build` (ncc splits a dynamic import() into its own
+//     chunk file physically written into scanner/dist/, so import.meta.url
+//     inside that chunk reflects dist/'s own location, not the original
+//     source file's — a fixed relative-levels-up path that was correct for
+//     one depth breaks silently at the other), or
+//   - installed from the published npm package, where the build copies
+//     frontend/'s servable files into scanner/dist/frontend/ (a sibling of
+//     the chunk file itself, i.e. 0 levels up) — see scripts/copy-frontend.mjs.
+//
+// Rather than hardcode one of those depths (the bug this file fixes: every
+// consumer used to hardcode the dev-only depth), search upward from the
+// caller's own directory and take the first candidate that actually has a
+// frontend/index.html on disk. Never guessed silently past that — a caller
+// with no match anywhere gets a clear, actionable error instead of a
+// downstream ENOENT/404 with no indication why.
+
+
+
+
+const MAX_LEVELS_UP = 4;
+
+/**
+ * @param {string} startDir - `path.dirname(fileURLToPath(import.meta.url))`
+ *   of the CALLING module (not this file) — each caller's own bundled/
+ *   unbundled location determines which candidate depth resolves.
+ * @returns {string} absolute path to a real `frontend/` directory containing
+ *   `index.html`.
+ * @throws if no candidate directory up to MAX_LEVELS_UP contains one.
+ */
+function resolveFrontendRoot(startDir) {
+  const tried = [];
+  for (let up = 0; up <= MAX_LEVELS_UP; up++) {
+    const candidate = node_path__WEBPACK_IMPORTED_MODULE_1__.resolve(startDir, ...Array(up).fill('..'), 'frontend');
+    tried.push(candidate);
+    // Every caller invokes resolveFrontendRoot() once, at module-load time,
+    // to compute a top-level FRONTEND_ROOT const (see static-assets.js /
+    // generate-html-report.mjs) — never per-request inside the explore
+    // server's request handler. At most MAX_LEVELS_UP+1 (5) sync stat calls
+    // at process startup is not a request-path DoS surface.
+    if (node_fs__WEBPACK_IMPORTED_MODULE_0__.existsSync(node_path__WEBPACK_IMPORTED_MODULE_1__.join(candidate, 'index.html'))) return candidate; // agentic-security-ignore: dos-sync-io
+  }
+  throw new Error(
+    `resolveFrontendRoot: no frontend/index.html found searching up from ${startDir}. ` +
+    `Tried: ${tried.join(', ')}. If you're running from a source checkout, run \`npm run build\` ` +
+    `first (it copies frontend/ into scanner/dist/frontend/); if you're running the published ` +
+    `package, this indicates a packaging defect — report it.`
+  );
+}
+
+
 /***/ })
 
 };