@codeyam-editor/codeyam-editor 0.1.7 → 0.1.8

package/npm/fleet-vm-access.js

@@ -215,6 +215,161 @@ function noDefaultOperatorDegradedReasons({ ok, action, lbMode, resolvedOperator
   ];
 }
 
+/** The BLOCKED/Next-valid-action refusal for an Add that would create an
+ *  IAP-gated VM authorizing NOBODY — the front-door counterpart to
+ *  `noDefaultOperatorDegradedReasons`, which can only warn AFTER the VM exists.
+ *  Fires only in LB mode (`lbMode` — a fleet domain is configured, so the VM's
+ *  public URL is IAP-gated) on a numbered fleet VM (`vmNumber != null`) when the
+ *  intended principal set is empty (`intendedCount === 0`): no `--vm-access`
+ *  collaborators AND no default operator from any of the three tiers. The check
+ *  depends only on env + config, never on GCP state, so the caller can run it in
+ *  the add's preflight and refuse before an instance exists — provisioning a
+ *  machine nobody can open, then revoking the slot's prior tenant, is what
+ *  happened to VMs 4/5/6 on 2026-08-09.
+ *
+ *  Names all THREE resolution tiers because which one to populate depends on the
+ *  host: an automation-SA session (the dashboard) can only be fixed by env or
+ *  cloud.json, while a human gcloud session resolves tier 3 on its own and never
+ *  reaches this refusal. Returns null when the Add is fine (so the call site is a
+ *  bare `if (msg) throw`), else the two-line recovery pair. Pure — the resolve
+ *  happens at the call site and only its COUNT is passed in. */
+function unauthorizableAddRefusal({ lbMode, vmNumber, intendedCount } = {}) {
+  if (!lbMode || vmNumber == null || intendedCount !== 0) return null;
+  return (
+    `BLOCKED: this Add would create an IAP-gated VM (VM-${vmNumber}) that authorizes NOBODY.\n`
+    + `  ${DEFAULT_OPERATOR_ENV} is unset, .codeyam/cloud.json has no \`vmAccessDefault\`,\n`
+    + '  and the active gcloud identity is a service account (skipped by design).\n'
+    + 'Next valid action: add `"vmAccessDefault": "user:you@example.com"` to\n'
+    + '  .codeyam/cloud.json (durable, no env re-bake), or pass --vm-access.'
+  );
+}
+
+/** Is this IAM principal a service account — i.e. authorizes no HUMAN? Matches
+ *  both the typed form gcloud returns on a policy read (`serviceAccount:x@…`) and
+ *  a bare `*.gserviceaccount.com` address, so the read-back below cannot be
+ *  satisfied by the automation SA that `iap-access.sh` unions into every grant.
+ *  Read-path semantics, like parseProjectMembers: it inspects whatever IAM
+ *  already holds rather than validating a write, so it never throws. */
+function isServiceAccountPrincipal(principal) {
+  const p = String(principal == null ? '' : principal).trim().toLowerCase();
+  if (p === '') return false;
+  return p.startsWith('serviceaccount:') || /gserviceaccount\.com$/.test(p);
+}
+
+/** Does a finished job warrant the post-add IAP read-back at all? Only a SUCCESSFUL
+ *  `add` in LB mode has an IAP-gated public URL whose reachability is worth
+ *  proving — a failed job, another action, or legacy quick-tunnel mode each have
+ *  nothing to read back, and flagging them would bury a real failure under a wrong
+ *  one. Split out so the caller can skip the (gcloud) policy read entirely on the
+ *  cheap gates, and so that decision is stated in exactly one place instead of
+ *  being duplicated at the call site and inside the verdict below.
+ *
+ *  `wiringInFlight` is the fourth gate and the one that fixes the 2026-08-11 race:
+ *  the IAP grant is the LAST step of the detached `wire-add-tail` that the add path
+ *  spawns, and that tail runs for another 5–10 minutes after the Add settles at
+ *  container-healthy. A read-back fired while the tail is alive is therefore racing
+ *  the very step it checks for — it is GUARANTEED to observe zero accessor bindings
+ *  on a perfectly healthy VM, which is exactly how healthy VM-4 and VM-7 were failed
+ *  with "authorizes no human". A live tail means the grant provably has not run yet,
+ *  so there is nothing to read back. Defaults false, so an omitted fact behaves
+ *  exactly as before this input existed. */
+function shouldReadBackIapAccess({ ok, action, lbMode, wiringInFlight } = {}) {
+  return !!ok && action === 'add' && !!lbMode && !wiringInFlight;
+}
+
+/** Is `job` still the job a post-add read-back was started for? The policy read is
+ *  async, so a newer job can replace it mid-flight; downgrading THAT job would
+ *  report a stale verdict against work it never describes. */
+function readbackAppliesToJob(job) {
+  return !!job && job.action === 'add' && job.state === 'done';
+}
+
+/** Post-add read-back verdict: after a successful LB-mode Add, does VM-N's LIVE
+ *  IAP policy authorize at least one non-service-account principal? This is the
+ *  only thing that PROVES the end state is reachable — every other signal in the
+ *  add path reports intent (what we meant to grant), and on 2026-08-09 intent and
+ *  outcome disagreed: the job reported `done` while the URL authorized nobody.
+ *
+ *  `iapMembers` is the union of accessor members across surfaces
+ *  (`aggregateIapMembers(...).all`); `null` means a surface's read ERRORED, the
+ *  same absence-of-evidence posture aggregateIapMembers itself takes.
+ *
+ *  Reported as a discriminated outcome, so a caller can tell the four cases apart
+ *  instead of collapsing three of them onto `null`:
+ *
+ *    'skipped'       the check does not apply (not an ok LB-mode add, or the add's
+ *                    detached wiring is still in flight). Nothing to do.
+ *    'undetermined'  a surface's policy read ERRORED (`iapMembers` is not an array).
+ *                    This is absence of evidence, NOT a pass: the caller must
+ *                    re-arm and re-check rather than concluding. Collapsing it onto
+ *                    "authorized" is how VM-5 settled `done` on 2026-08-11 with its
+ *                    access never actually proven — a flaky gcloud call under load
+ *                    silently skipped the only check that proves reachability.
+ *    'authorized'    at least one non-service-account principal holds an accessor
+ *                    binding. The end state is provably reachable by a human.
+ *    'unauthorized'  the policy was read and authorizes no human. `reason` carries
+ *                    the BLOCKED / `Next valid action:` remedy.
+ *
+ *  `reason` is non-null only for 'unauthorized'. Pure — the gcloud read is the
+ *  caller's. */
+function iapReadbackOutcome({ ok, action, lbMode, wiringInFlight, iapMembers, vmNumber } = {}) {
+  if (!shouldReadBackIapAccess({ ok, action, lbMode, wiringInFlight })) {
+    return { outcome: 'skipped', reason: null };
+  }
+  if (!Array.isArray(iapMembers)) return { outcome: 'undetermined', reason: null };
+  if (iapMembers.some((p) => !isServiceAccountPrincipal(p))) return { outcome: 'authorized', reason: null };
+  const held = iapMembers.length > 0 ? iapMembers.join(', ') : '(none)';
+  return {
+    outcome: 'unauthorized',
+    reason: (
+      `BLOCKED: VM-${vmNumber} is up but its IAP policy authorizes no human — the public URL\n`
+      + `  returns "Error code 51" for everyone. Accessor bindings held: ${held}.\n`
+      + `Next valid action: configure a default operator (${DEFAULT_OPERATOR_ENV} or\n`
+      + '  .codeyam/cloud.json `vmAccessDefault`), then run\n'
+      + `      VM_ACCESS=user:you@example.com bash scripts/gcp/iap-access.sh ${vmNumber} grant`
+    ),
+  };
+}
+
+/** Timing policy for the DEFERRED post-add read-back: on this attempt, is there
+ *  anything worth reading yet? Separate from shouldReadBackIapAccess, which asks
+ *  whether the check applies AT ALL — this asks whether now is the moment.
+ *
+ *    wiringInFlight  the add's detached wiring tail is still running, and the IAP
+ *                    grant is its LAST step. Reading now can only observe the
+ *                    grant not having happened yet, so wait.
+ *    wiringFailed    the tail dropped its failed marker. A blown deadline is
+ *                    EVIDENCE, not a reason to keep waiting: read now and let a
+ *                    genuinely unauthorized VM escalate instead of waiting forever.
+ *    budgetSpent     the caller's total wait has elapsed. Read regardless — a
+ *                    crashed tail that never unlinked its marker must not defer the
+ *                    check indefinitely, and the classifier still renders the card
+ *                    calm while the wiring reads live.
+ *
+ *  Returns 'defer' (re-arm and ask again later) or 'read' (do the policy read). */
+function iapReadbackDeferral({ wiringInFlight, wiringFailed, budgetSpent } = {}) {
+  if (budgetSpent || wiringFailed) return 'read';
+  return wiringInFlight ? 'defer' : 'read';
+}
+
+/** What should the caller DO with an iapReadbackOutcome? Pure so the one rule that
+ *  cost us a silently-skipped check is stated and tested in one place:
+ *
+ *  An 'undetermined' read (a gcloud call that errored under load) must DEFER, never
+ *  settle. Treating it as a pass is how VM-5 reached `done` on 2026-08-11 with its
+ *  reachability never actually proven — the check that exists to catch an
+ *  unreachable VM was skipped entirely by one flaky call. It settles only once the
+ *  wait budget is spent, and even then it settles rather than failing: absence of
+ *  evidence must not manufacture a failed Add either.
+ *
+ *  Returns 'fail' (downgrade the job with the reason), 'defer' (re-arm and
+ *  re-check), or 'settle' (leave the job alone). */
+function iapReadbackNextAction({ outcome, budgetSpent } = {}) {
+  if (outcome === 'unauthorized') return 'fail';
+  if (outcome === 'undetermined') return budgetSpent ? 'settle' : 'defer';
+  return 'settle';
+}
+
 /** Union the default-operator principal(s) into an access list, deduped and
  *  order-preserving (explicit collaborators first, the operator appended if not
  *  already present). Both inputs are normalized. The result is what gets GRANTED;
@@ -391,6 +546,13 @@ module.exports = {
   resolveDefaultOperator,
   defaultCloudConfigRead,
   noDefaultOperatorDegradedReasons,
+  unauthorizableAddRefusal,
+  isServiceAccountPrincipal,
+  shouldReadBackIapAccess,
+  readbackAppliesToJob,
+  iapReadbackOutcome,
+  iapReadbackDeferral,
+  iapReadbackNextAction,
   withDefaultOperator,
   parseProjectMembers,
   reconcileVmAccess,

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
@@ -1181,6 +1223,7 @@ module.exports = {
   cloudUpArgs,
   classifyContainerWait,
   decideAddSlot,
+  heavyChargeCount,
   HEAVY_ACTIONS,
   queuedStatusForAction,
   pushHistory,

package/npm/scenario-check.js

@@ -966,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));
@@ -1378,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) {
@@ -1421,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,
   };
 }