@codeyam-editor/codeyam-editor 0.1.6 → 0.1.8

package/npm/ingress-invoke.js

@@ -78,7 +78,15 @@ function regionFromZone(zone) {
  *  stand. An optional `slug` becomes `VM_SLUG`, which makes the script route the
  *  VM's custom `<slug>.<surface>.<domain>` host (the same slug must be passed on
  *  `down` so the matching host rule is removed); omit it to keep the numeric
- *  `vm-<N>` host. */
+ *  `vm-<N>` host.
+ *
+ *  `vmAccess` (an array or comma-separated string, `up` only) becomes VM_ACCESS —
+ *  the Add's INTENDED principal set, which the script's `apply_default_iap_access`
+ *  grants instead of reading the per-VM sidecar. Passing it is what stops the
+ *  ingress path granting a reused slot's prior tenant that the very next step then
+ *  revokes as stale (VMs 4/5/6, 2026-08-09). Omit it (or pass an empty list) to
+ *  leave the script's sidecar-read fallback in place — the standalone/reconcile
+ *  path, where no Add is deciding the intent. */
 function vmIngressInvocation({
   scriptPath,
   vmNumber,
@@ -89,6 +97,7 @@ function vmIngressInvocation({
   appPort,
   instancePrefix,
   slug,
+  vmAccess,
 } = {}) {
   if (!scriptPath) throw new Error('vmIngressInvocation requires scriptPath');
   if (action !== 'up' && action !== 'down') {
@@ -105,6 +114,8 @@ function vmIngressInvocation({
   if (appPort != null && String(appPort).trim() !== '') env.APP_PORT = String(appPort);
   if (instancePrefix) env.INSTANCE_PREFIX = instancePrefix;
   if (slug != null && String(slug).trim() !== '') env.VM_SLUG = String(slug).trim();
+  const access = (Array.isArray(vmAccess) ? vmAccess.join(',') : String(vmAccess == null ? '' : vmAccess)).trim();
+  if (action === 'up' && access !== '') env.VM_ACCESS = access;
   return { command: 'bash', args: [scriptPath, String(n), action], env };
 }
 
@@ -427,6 +438,13 @@ function detachedAddTailInvocation({ nodePath, scriptPath, cfg, appPort } = {})
   return { command: nodePath, args: [scriptPath, 'wire-add-tail'], env };
 }
 
+/** Basename prefix of the in-flight marker, shared by the path BUILDER below and
+ *  the `inflightMarkerVmNumber` PARSER beneath it so the naming has exactly one
+ *  owner. The two must agree exactly: the parser is how the dashboard counts live
+ *  tails fleet-wide, and a prefix that drifted on one side only would silently
+ *  count zero — which reads identically to a quiet fleet. */
+const INFLIGHT_MARKER_BASENAME_PREFIX = 'cy-ingress-inflight-vm-';
+
 /** The per-VM marker file the detached add-tail holds while its wiring is still
  *  running, so the dashboard's auto-rewire gather skips a VM whose FIRST wiring
  *  attempt is in flight (never firing a competing `vm-ingress.sh up`). Pure path
@@ -438,7 +456,32 @@ function ingressInflightMarkerPath(dir, vmNumber) {
   if (!Number.isInteger(n) || n <= 0) {
     throw new Error(`ingressInflightMarkerPath requires a positive VM number, got: ${vmNumber}`);
   }
-  return `${dir.replace(/\/+$/, '')}/cy-ingress-inflight-vm-${n}`;
+  return `${dir.replace(/\/+$/, '')}/${INFLIGHT_MARKER_BASENAME_PREFIX}${n}`;
+}
+
+/** Inverse of `ingressInflightMarkerPath`'s basename: given ONE directory entry
+ *  name, the VM number it is an in-flight marker for, or null if it is not one.
+ *
+ *  This is what lets the dashboard count live wiring tails FLEET-WIDE by scanning
+ *  the marker directory, rather than per-VM against a roster — the population that
+ *  matters is exactly the one a roster lags behind, since a batch of adds is when
+ *  VMs appear and their tails outlive their jobs. That count feeds both the
+ *  heavy-job concurrency budget and the memory guard's restart refusal.
+ *
+ *  Deliberately strict, because the marker directory is `os.tmpdir()` and the
+ *  add's own siblings live there too: `cy-ingress-failed-vm-3` (a different
+ *  marker), `cy-wire-add-vm-5.log` (the tail's log), and any `<marker>.tmp`.
+ *  Counting one of those as a live tail would charge a phantom slot against a cap
+ *  of 4 and, worse, hold the memory self-restart off forever. Accepts exactly what
+ *  the builder emits: a positive integer with no leading zeros and nothing after.
+ *
+ *  Pure; no I/O — the caller does the readdir. */
+function inflightMarkerVmNumber(fileName) {
+  if (typeof fileName !== 'string') return null;
+  if (!fileName.startsWith(INFLIGHT_MARKER_BASENAME_PREFIX)) return null;
+  const rest = fileName.slice(INFLIGHT_MARKER_BASENAME_PREFIX.length);
+  if (!/^[1-9][0-9]*$/.test(rest)) return null;
+  return Number(rest);
 }
 
 /** The per-VM marker file the detached add-tail drops when its converge loop
@@ -762,6 +805,7 @@ module.exports = {
   ingressConvergeDecision,
   detachedAddTailInvocation,
   ingressInflightMarkerPath,
+  inflightMarkerVmNumber,
   ingressFailedMarkerPath,
   isWiringInflight,
   iapAccessInvocation,

package/npm/launch-config.js

@@ -328,6 +328,48 @@ function decideAddSlot({ maxConcurrency, activeCount = 0 } = {}) {
   return Number(activeCount) < cap ? "start" : "queue";
 }
 
+/** How many concurrency slots the fleet's heavy work is ACTUALLY occupying —
+ *  the `activeCount` `decideAddSlot` above should be judging against.
+ *
+ *  Two populations, not one. `runningVms` are the VMs with a heavy job in the
+ *  `running` state; `wiringVms` are the VMs whose Add has already settled at
+ *  container-healthy but whose DETACHED wire-add-tail is still spawning gcloud
+ *  children for another 5-10 minutes. Charging only the first is what let a
+ *  six-VM batch put 32 `gcloud.py compute` children on a 16-vCPU host at load
+ *  38.23 against a cap of 4: each Add released its slot the instant the job
+ *  settled, while its real work ran on invisibly.
+ *
+ *  A VM present in BOTH lists is charged ONCE, and that is the subtle part.
+ *  `cmdUp` writes the in-flight marker BEFORE the Add settles, so every add has
+ *  a window where its job is still `running` and its marker already exists;
+ *  summing the two lists would charge that Add two of the four slots for the
+ *  overlap. Counting the union instead makes an Add hold exactly one slot
+ *  continuously across the job -> tail handoff, which is the property the cap
+ *  needs in both directions — never over-charging during the overlap, never
+ *  releasing early after it.
+ *
+ *  Non-integer, non-positive, and duplicate entries are dropped from either
+ *  list, so a caller's readdir glitch or a malformed job key degrades toward
+ *  under-counting (admitting work) rather than manufacturing a phantom slot
+ *  that would freeze admission forever.
+ *
+ *  Pure: pulls no globals, has no side effects. */
+function heavyChargeCount({ runningVms = [], wiringVms = [] } = {}) {
+  const numbers = (list) => {
+    const out = new Set();
+    for (const raw of Array.isArray(list) ? list : []) {
+      const n = Number(raw);
+      if (Number.isInteger(n) && n > 0) out.add(n);
+    }
+    return out;
+  };
+  const running = numbers(runningVms);
+  const wiring = numbers(wiringVms);
+  let untrackedTails = 0;
+  for (const n of wiring) if (!running.has(n)) untrackedTails += 1;
+  return running.size + untrackedTails;
+}
+
 /** Closed set of "heavy" action names — those that invoke `npm run cloud:up`
  *  (over gcloud-ssh) and so contend for the shared spawn budget that prevents
  *  the dashboard's launchd-managed node process from OOMing under burst. The
@@ -784,6 +826,18 @@ function claudeAuthSeeded(mode) {
 // the server.js helper so callers don't have to thread one through.
 function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
 
+// Assemble a `pkill -f` whose ERE is ANCHORED at the target's own executable:
+// `^`, an optional directory prefix, then `exe`. Every sweep builder in this
+// module routes through here so the anchor is structural rather than remembered
+// — an unanchored `pkill -f` matches the FULL command line, which for the fleet
+// dashboard's `sh -c '<add script>'` wrapper includes the script text itself.
+// See the "Self-match-safe process sweeps" block below for the full failure
+// mode. `argv` is an ERE fragment matched after the executable; escape any
+// literal dots in it.
+function _anchoredSweep({ exe, argv } = {}) {
+  return `pkill -f "^([^ ]*/)?${exe} ${argv}" 2>/dev/null`;
+}
+
 /** Build a `docker exec … bash -c` sink that stages stdin to a same-directory
  *  `.cytmp` sibling and only `mv`s it onto `target` when the staged file is
  *  NON-EMPTY — exiting 1 (so the caller's `… || echo CY_DEGRADED` fires) and
@@ -978,13 +1032,112 @@ function editorTunnelCmd({ gcloud, inst, zone, editorPort, n } = {}) {
  *  from the editor reachability forward (`editorTunnelCmd`): a preview re-wire
  *  pkills + respawns ONLY this process, leaving the editor :14199 forward — and
  *  the reachability probe riding it — untouched. The preview local port is unique
- *  per VM and never collides with the editor port, so the re-wire/destroy
- *  `pkill -f "<previewPort>:127.0.0.1:"` targets exactly this process. Pure; no
- *  I/O. */
+ *  per VM and never collides with the editor port. Sweep it through
+ *  `previewForwardSweepCmd` — the bare `pkill -f "<previewPort>:127.0.0.1:"` this
+ *  comment used to call "targets exactly this process" did NOT: it also matched
+ *  every `sh -c '<add script>'` wrapper carrying that literal. Pure; no I/O. */
 function previewTunnelCmd({ gcloud, inst, zone, previewPort, appPort, n } = {}) {
   return `nohup ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} -- -N -L ${previewPort}:127.0.0.1:${appPort} > /tmp/ssh-preview-vm-${n}.log 2>&1 &`;
 }
 
+/* ── Self-match-safe process sweeps ─────────────────────────────────────────
+ *
+ *  Every builder below emits a `pkill -f` whose match expression is ANCHORED at
+ *  the TARGET's executable — a leading `^`, an optional directory prefix, then
+ *  the program name (`ssh`, `node`, `cloudflared`). That anchor is the entire
+ *  point of these builders, not decoration.
+ *
+ *  `pkill -f` matches the FULL command line. The fleet dashboard runs an Add as
+ *  `/bin/sh -c '<the entire add script text>'`, and that script text EMBEDS these
+ *  very sweep lines — so an unanchored pattern like `pkill -f
+ *  "14199:127.0.0.1:14199"` is a substring of the wrapper's own argv. It SIGTERMs
+ *  the wrapper that is running it, and every concurrent SIBLING add wrapper too.
+ *  The wrapper then dies from an uncaught signal, so its EXIT trap never writes
+ *  the `add-<n>.exit` marker that `fc.readExitMarker` / `fc.reattachVerdict` exist
+ *  to consume; `startJob`'s exec callback reports a red "Add failed" on a VM that
+ *  is fine; and the detached `cloud:up` it started — whose own argv does NOT carry
+ *  the pattern — is orphaned to init and keeps provisioning, after which
+ *  stranded-reconcile declares the VM half-provisioned and stacks a SECOND
+ *  `cloud:up` on top of it. That is the 2026-07-31 VM-3..8 batch, whose containers
+ *  were Up and answering /api/health 200 throughout.
+ *
+ *  Excluding `$$` / `$PPID` does NOT fix this: the processes being wrongly killed
+ *  are SIBLINGS, not self or parent. The pattern itself must be incapable of
+ *  matching a `sh -c '<script>'` command line, and anchoring at the executable is
+ *  what guarantees that — a wrapper's argv always begins with the shell, never
+ *  with `ssh` / `node` / `cloudflared`.
+ *
+ *  Same trap, same lesson as `npm/cloud.js` bootstrapStatusCommand (:1446) and
+ *  projectBootstrapStatusCommand (:1760), which document it explicitly ("the
+ *  status command's own argv contains the bootstrap path, so a `pgrep -f` on it
+ *  would match this very probe") and dodge it with a PID file + `kill -0`. A PID
+ *  file cannot replace THESE sweeps: they deliberately target STRAY processes left
+ *  by a prior add, a crashed watchdog respawn, or an earlier container generation
+ *  — processes this script never owned and holds no PID for. So the sweep stays
+ *  pattern-based; only the pattern's blast radius changes.
+ *
+ *  Keep every sweep in this family behind one of these builders. Re-inlining a
+ *  bare `pkill -f` at a call site is exactly how the bug got in the first time. */
+
+/** Sweep a stray EDITOR reachability forward — the `-L <localPort>:127.0.0.1:14199`
+ *  ssh process `editorTunnelCmd` opens.
+ *
+ *  Targets the `ssh` CHILD, not the `gcloud compute ssh` python parent. The child
+ *  is what binds the local listening socket, so killing it is what actually
+ *  releases the port; the parent is only waiting on it and exits on its own once
+ *  it goes. Only the child's argv starts with `ssh`, which is also what makes the
+ *  anchor safe. Pure; no I/O. */
+function editorForwardSweepCmd({ localPort } = {}) {
+  return _anchoredSweep({ exe: "ssh", argv: `.*-L ${localPort}:127\\.0\\.0\\.1:14199` });
+}
+
+/** Sweep a stray LIVE-PREVIEW forward — the `-L <localPort>:127.0.0.1:<appPort>`
+ *  ssh process `previewTunnelCmd` opens. The remote port is left open because the
+ *  app's dev-server port legitimately drifts; the per-VM preview local port is the
+ *  identifying half and never collides with the editor port. Same ssh-child
+ *  targeting as `editorForwardSweepCmd`. Pure; no I/O. */
+function previewForwardSweepCmd({ localPort } = {}) {
+  return _anchoredSweep({ exe: "ssh", argv: `.*-L ${localPort}:127\\.0\\.0\\.1:` });
+}
+
+/** Sweep a wedged `cloud:up` provision for one instance.
+ *
+ *  Targets the `node npm/cloud.js up --instance-name <inst>` process, NOT the
+ *  `npm run cloud:up` parent — call sites already hold the npm child's PID and
+ *  `kill` it directly; this reaps the node grandchild that PID does not cover.
+ *  `--instance-name` is the first pair `cloudUpArgs` emits, so the literal stays
+ *  adjacent to `up`. Pure; no I/O. */
+function cloudUpSweepCmd({ inst } = {}) {
+  return _anchoredSweep({ exe: "node", argv: `.*cloud\\.js up --instance-name ${inst}` });
+}
+
+/** Sweep the cloudflared quick-tunnel fronting a VM's editor port.
+ *
+ *  Anchored for the same reason as its siblings, with one extra bite: this sweep
+ *  runs inside a `sh -c` compound built by `exec()`, so unanchored it matched its
+ *  OWN parent shell — killing the compound before the editor/preview sweeps that
+ *  follow it on the same line ever ran. Pure; no I/O. */
+function cloudflaredTunnelSweepCmd({ localPort } = {}) {
+  return _anchoredSweep({ exe: "cloudflared", argv: `tunnel --url http://localhost:${localPort}` });
+}
+
+/** Build the destroy-time local reap compound for one VM: free the editor port,
+ *  then sweep the cloudflared quick-tunnel and BOTH split ssh forwards.
+ *
+ *  Lives here rather than inline in `cleanLocalVmArtifacts` because the ORDERING
+ *  is load-bearing and was previously untestable: the whole compound runs as one
+ *  `sh -c`, so the unanchored cloudflared sweep used to match that shell's own
+ *  argv and kill it BEFORE the two forward sweeps behind it ever ran — meaning a
+ *  destroy silently orphaned both forwards. Pure; no I/O. */
+function localVmReapCmd({ port, previewPort } = {}) {
+  return [
+    `lsof -ti:${port} 2>/dev/null | xargs -r kill`,
+    cloudflaredTunnelSweepCmd({ localPort: port }),
+    editorForwardSweepCmd({ localPort: port }),
+    previewForwardSweepCmd({ localPort: previewPort }),
+  ].join("; ");
+}
+
 /** Build the shell snippet the Add script runs to AWAIT cloud:up's clean exit at
  *  container-healthy instead of reaping it mid-flight.
  *
@@ -1009,7 +1162,7 @@ function awaitWiringCmd({ inst, deadlineSec = 180, pidVar = "UP_PID" } = {}) {
     `while kill -0 $${pidVar} 2>/dev/null; do`,
     `  if [ "$__cy_wiring_waited" -ge ${deadlineSec} ]; then`,
     `    echo "WARN cloud:up still running after ${deadlineSec}s (wedged before the container-healthy early return) — reaping it (the dashboard self-heal will converge any half-wired backend)"`,
-    `    kill $${pidVar} 2>/dev/null; pkill -f "cloud.js up --instance-name ${inst}" 2>/dev/null; break`,
+    `    kill $${pidVar} 2>/dev/null; ${cloudUpSweepCmd({ inst })}; break`,
     `  fi`,
     `  sleep 5; __cy_wiring_waited=$((__cy_wiring_waited + 5))`,
     `done`,
@@ -1070,6 +1223,7 @@ module.exports = {
   cloudUpArgs,
   classifyContainerWait,
   decideAddSlot,
+  heavyChargeCount,
   HEAVY_ACTIONS,
   queuedStatusForAction,
   pushHistory,
@@ -1097,6 +1251,11 @@ module.exports = {
   decideStartJob,
   editorTunnelCmd,
   previewTunnelCmd,
+  editorForwardSweepCmd,
+  previewForwardSweepCmd,
+  cloudUpSweepCmd,
+  cloudflaredTunnelSweepCmd,
+  localVmReapCmd,
   awaitWiringCmd,
   getAuthRepoUrl,
   interpretLsRemote,

package/npm/scenario-check.js

@@ -191,14 +191,40 @@ const {
 // inject it here from the on-box 0600 token file.
 const SESSION_COOKIE = "cy_session";
 
+// The loopback names the editor can be addressed by. A cookie is scoped by
+// HOST, and the jar does NOT treat these as interchangeable: a cookie stored for
+// `localhost` is simply not sent to `127.0.0.1`. That matters because the two
+// token-gated capture routes resolve their origin differently — the harness
+// route via `resolveHarnessOrigin()` (typically `localhost`), the preview-proxy
+// route via `PROXY_CAPTURE_LOOPBACK` in handlers.rs, which is deliberately
+// IPv4-pinned to `127.0.0.1` so it matches the forwarder's own pinning. Scoping
+// the cookie to `localhost` alone therefore authenticated the harness route and
+// left every `/__codeyam_preview` capture with no credential, so `preview-verify`
+// / `preview-interact` / `preview-flow` all 401'd on a non-loopback bind.
+// Emitting one cookie per alias is the fix: same token, same on-box editor,
+// whichever name the capture URL happens to use.
+const LOOPBACK_COOKIE_DOMAINS = ["localhost", "127.0.0.1"];
+
+// Extract the host from an origin string, or null when it is unparseable.
+function originHost(origin) {
+  try {
+    return new URL(origin).hostname;
+  } catch (_) {
+    return null;
+  }
+}
+
 // Build the Playwright cookie array that authenticates the capture context to
 // the editor's token-gated control-API. Reads the on-box `.codeyam/session-token`
-// (0600) and scopes a `cy_session` cookie to `localhost` (localhost cookies are
-// port-agnostic, so the same cookie covers the harness origin on the control
-// port and any `/api` call on the app-proxy port). Returns `[]` — a no-op — when
-// there is no token file (a loopback bind that never persisted one) or no
-// resolvable harness origin, so a laptop capture is completely unaffected.
-// `deps` is injectable so the builder is unit-testable without disk.
+// (0600) and emits a `cy_session` cookie for every host the capture might address
+// the editor by (see `LOOPBACK_COOKIE_DOMAINS`); cookies are port-agnostic, so
+// one per host covers the harness origin on the control port, the preview-proxy
+// route, and any `/api` call on the app-proxy port. A non-loopback harness origin
+// (a cloud tunnel domain) additionally gets its own host, since no loopback alias
+// would match it. Returns `[]` — a no-op — when there is no token file (a
+// loopback bind that never persisted one) or no resolvable harness origin, so a
+// laptop capture is completely unaffected. `deps` is injectable so the builder is
+// unit-testable without disk.
 function buildSessionTokenCookies({
   readTokenFile = () => {
     const p = path.join(process.cwd(), ".codeyam", "session-token");
@@ -209,16 +235,19 @@ function buildSessionTokenCookies({
   try {
     const token = readTokenFile();
     if (!token || !harnessOrigin) return [];
-    return [
-      {
-        name: SESSION_COOKIE,
-        value: token,
-        domain: "localhost",
-        path: "/",
-        httpOnly: true,
-        sameSite: "Lax",
-      },
-    ];
+    const host = originHost(harnessOrigin);
+    const domains = [...LOOPBACK_COOKIE_DOMAINS];
+    // A tunnelled/cloud harness origin is not a loopback alias, so it needs its
+    // own entry or the harness navigation goes out uncredentialed.
+    if (host && !domains.includes(host)) domains.push(host);
+    return domains.map((domain) => ({
+      name: SESSION_COOKIE,
+      value: token,
+      domain,
+      path: "/",
+      httpOnly: true,
+      sameSite: "Lax",
+    }));
   } catch (_) {
     // A missing/unreadable token file must never break capture on a loopback
     // bind where the token isn't required anyway — degrade to no cookie.
@@ -817,9 +846,14 @@ async function runScenarioCheck(
   config,
   { preflight = assertAppPortReachable, harnessOrigin } = {},
 ) {
-  const resolvedHarnessOrigin =
-    harnessOrigin !== undefined ? harnessOrigin : resolveHarnessOrigin();
   const { url, outputPath, width, height, httpMocks = {} } = config;
+  // The harness host mirrors the capture target's host so the framed load stays
+  // SAME-SITE — see `resolveHarnessOrigin`. A cross-site frame withholds the
+  // SameSite=Lax `cy_session` cookie and every token-gated route 401s.
+  const resolvedHarnessOrigin =
+    harnessOrigin !== undefined
+      ? harnessOrigin
+      : resolveHarnessOrigin({ targetUrl: url });
   // Per-scenario capture-check allowances (see `CaptureAllowances` /
   // `ScenarioDefinition` on the Rust side). Default false so the guards keep
   // their strict behavior for every scenario that does not opt in.
@@ -932,7 +966,11 @@ async function runScenarioCheck(
   // wait out an in-flight fetch that would otherwise be screenshotted as a
   // loading skeleton.
   const networkTracker = createNetworkTracker(page);
-  await attachHttpMocks(page, httpMocks);
+  // The observer tallies which declared mocks actually fulfilled and inventories
+  // every request the page made, grouped by origin. `appOrigin` lets it split
+  // same-origin from cross-origin — a third-party host the scenario has no
+  // opinion about becomes visible rather than inferred.
+  const mockObserver = await attachHttpMocks(page, httpMocks, { appOrigin });
 
   page.on("pageerror", (error) => {
     pushIssue(issues, handlePageError(error));
@@ -1344,6 +1382,8 @@ async function runScenarioCheck(
       outputPath,
       url: frame.url() || url,
       unmockedRoutes,
+      mockUsage: { used: mockObserver.used, unused: mockObserver.unused },
+      externalRequests: mockObserver.externalRequests,
     });
 
     if (config.interaction) {
@@ -1387,6 +1427,10 @@ async function runScenarioCheck(
       outputPath,
       url,
       unmockedRoutes,
+      // A capture that threw still made requests; the inventory it collected up
+      // to the failure is often exactly what explains the failure.
+      mockUsage: { used: mockObserver.used, unused: mockObserver.unused },
+      externalRequests: mockObserver.externalRequests,
     });
   } finally {
     await browser.close();

package/npm/scenario-handlers.js

@@ -135,6 +135,15 @@ ${webSocketStub}
   `;
 }
 
+// Third mirror of SUPPRESSION_PATTERN in ui/src/hooks/useViteHmrAutoReload.ts
+// and VITE_WS_NOISE_PATTERN in crates/proxy-http/src/error_capture.js. All
+// three surfaces silence the same harness-owned Vite HMR reconnect noise; keep
+// in sync. The capture path is the one that was missing it, which made every
+// preview-flow / preview-interact against a proxy-wrapped route fail its
+// console check on noise the editor itself produces.
+const VITE_WS_NOISE_PATTERN =
+  /vite.*failed to connect to websocket|WebSocket closed without opened/i;
+
 function handleConsoleMessage(message) {
   if (message.type() !== "error") return null;
   const text = message.text();
@@ -144,6 +153,14 @@ function handleConsoleMessage(message) {
   const advisory = insecureContextAdvisory(text);
   if (advisory) return advisory;
 
+  // Vite's reconnect banner ("[vite] failed to connect to websocket." plus the
+  // `(browser) … <--[WebSocket (failing)]--> … (server)` diagram) contains none
+  // of the substrings the ignore list below matches, so it fell through and
+  // vetoed the capture. Matched narrowly — the `vite`-anchored alternative and
+  // the exact-phrase second alternative both leave a genuine app-authored error
+  // mentioning websockets surfacing as a real issue.
+  if (VITE_WS_NOISE_PATTERN.test(text)) return null;
+
   // Ignore known dev-server WebSocket/HMR errors from Vite proxy, plus the
   // crxjs/Vite dynamic-import reload race: dev loaders `import()` the app entry
   // with a `?t=<timestamp>` cache-buster, and a rapid scenario-reactivation
@@ -219,4 +236,5 @@ module.exports = {
   insecureContextAdvisory,
   INSECURE_CONTEXT_SIGNATURES,
   INSECURE_HOST_ADVISORY_MESSAGE,
+  VITE_WS_NOISE_PATTERN,
 };

package/npm/scenario-issues.js

@@ -24,6 +24,8 @@ function buildResult({
   outputPath,
   url,
   unmockedRoutes = [],
+  mockUsage = { used: [], unused: [] },
+  externalRequests = [],
 }) {
   return {
     ok: loaded && hasContent && issues.length === 0,
@@ -37,6 +39,15 @@ function buildResult({
     // the actionable route list the failure message and `stub-unmocked-routes`
     // consume. Defaults to `[]` so callers that omit it are unchanged.
     unmockedRoutes,
+    // Diagnostic-only, and deliberately NOT part of `ok`: an unused mock is not
+    // automatically an error (a scenario may legitimately declare a mock for a
+    // request the page makes only on interaction). Reporting it turns a silent
+    // inertness into a visible fact; failing on it would break working scenarios
+    // for a heuristic.
+    mockUsage,
+    // Requests grouped by origin, split mocked/unmocked and same/cross-origin.
+    // The line that ends a "why is this page blank" misdiagnosis.
+    externalRequests,
   };
 }