@codeyam-editor/codeyam-editor 0.1.7 → 0.1.9

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

@@ -119,6 +119,79 @@ function validateLaunchConfig(cfg) {
   return { ok: true };
 }
 
+/** The branch refs a launch config asks git to resolve, as
+ *  `[{ field, repo, branch }]` — one entry per branch-carrying field that is
+ *  actually populated. This is the input to a ref-existence preflight; it lives
+ *  beside normalizeLaunchConfig (rather than in a second parser at the add
+ *  endpoint or in cloud.js) because it reads the SAME canonical field names that
+ *  normalizer produces, so a field rename can never leave the two disagreeing.
+ *
+ *  BOTH fields are reported, deliberately. In the 2026-08-25 incident the dead
+ *  ref sat in `clientBranch` AND `editorBranch`, and it was `clientBranch` that
+ *  actually killed the bootstrap — an editor-only check would have missed it.
+ *
+ *  A greenfield add (`newProjectName`, no `clientRepo`) has no client repo to
+ *  resolve a branch against, so its clientBranch is skipped rather than probed
+ *  against a repo URL that does not exist. `editorRepo` is passed in because the
+ *  launch config carries an editor BRANCH but not an editor REPO — the repo is
+ *  the caller's (cloud:up resolves it via resolveEditorConfig; the dashboard
+ *  holds it in REPO). Pure; no I/O. */
+function branchRefTargets(cfg, { editorRepo } = {}) {
+  const c = cfg || {};
+  const targets = [];
+  if (c.clientRepo && c.clientBranch) {
+    targets.push({ field: "clientBranch", repo: c.clientRepo, branch: c.clientBranch });
+  }
+  if (editorRepo && c.editorBranch) {
+    targets.push({ field: "editorBranch", repo: editorRepo, branch: c.editorBranch });
+  }
+  return targets;
+}
+
+/** Partition branchRefTargets by whether each ref still resolves, using an
+ *  INJECTED probe so the decision logic is unit-tested with no network and no
+ *  git. `refExists({ repo, branch })` returns true when the ref is present,
+ *  false when it is provably gone.
+ *
+ *  A probe that cannot reach the remote at all must NOT report false — a network
+ *  or credential fault is not evidence a branch was deleted, and treating it as
+ *  such would refuse every add the moment GitHub blipped. The probe signals that
+ *  by returning `null`/`undefined`, which this treats as "unknown, let it
+ *  through": the classifier arm downstream still catches a genuinely dead ref,
+ *  at the cost this preflight normally saves. Fail-open is the right default
+ *  here precisely because the preflight is an OPTIMIZATION over a failure that
+ *  is already handled, never the only line of defence. Pure; no I/O. */
+function missingBranchRefs(targets, refExists) {
+  const missing = [];
+  for (const t of targets || []) {
+    if (refExists(t) === false) missing.push(t);
+  }
+  return missing;
+}
+
+/** Operator-facing copy for a failed branch-ref preflight. States the OUTCOME
+ *  first (nothing was created), then the mechanism, then the remedy — and never
+ *  the "a partial instance may exist — reconcile or destroy it" language the
+ *  generic provisioning failure uses, which is what made the real incident
+ *  confusing: at preflight time no instance, disk, NEG or backend service has
+ *  been created, so there is nothing to reconcile and nothing to destroy.
+ *
+ *  Names which FIELD carried the dead ref, because the two are configured in
+ *  different places and an operator who only corrects one re-issues a request
+ *  that fails identically. Pure; no I/O. */
+function missingBranchRefMessage(missing) {
+  const list = (missing || [])
+    .map((m) => `${m.field}: branch '${m.branch}' is not on ${m.repo}`)
+    .join("; ");
+  return (
+    `Branch no longer exists on origin — ${list}. ` +
+    "Nothing was provisioned: this is checked before any instance is created, so " +
+    "there is no VM, disk or backend service to clean up. This repo prunes branches " +
+    "when they merge, so a stored branch name expires silently. Re-add on a live " +
+    "branch (the current fleet branch, or any branch that still exists on origin)."
+  );
+}
+
 /** Pre-flight the operator-host CONFIG a dashboard Add depends on, BEFORE
  *  spawning the ~20-min cloud:up. Pure classifier: it takes the ALREADY-resolved
  *  zone, project, and GitHub token (the side-effecting resolution — env lookups,
@@ -328,6 +401,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
@@ -480,11 +595,42 @@ function recentlyLaunchedWithin(ts, nowMs, graceMs) {
  *                  variant(@branch) fallback.
  *   - source       "live" when editorIdentity drove editorLabel, else
  *                  "history" — the affordance the card uses to mark inferred
- *                  data. Pure; no I/O. */
+ *                  data.
+ *   - deployedBranch the branch the fleet ADVANCED this VM to, from the editor's
+ *                  `editorDeployment` (which reads the record the refresh script
+ *                  writes at install time); null when the editor reports none.
+ *   - deployedTag  the full artifact tag behind that branch, for the hover.
+ *   - deployedSource "live" when the editor reported a deployment, else
+ *                  "unknown".
+ *   - deployedState the card's three-way presentation verdict, resolved HERE
+ *                  rather than in the browser so the rule is unit-tested in one
+ *                  place and index.html carries no copy of it (the compromise
+ *                  groupVmsByProject's own comment apologizes for, avoidable
+ *                  here because this value rides in the /data payload):
+ *                    "agrees"  deployment and provenance name the same branch
+ *                    "differs" they disagree — the EXPECTED plan-only-retag
+ *                              state, to be shown as a pair, never badged
+ *                    "unknown" no deployment reported
+ *
+ *  editorLabel and deployedBranch answer DIFFERENT questions and are routinely
+ *  expected to disagree. editorLabel is build provenance — what source the
+ *  binary was compiled from — and stays exactly as it was; it is the right
+ *  answer to "what code is this actually running?" and is what fragility #33's
+ *  fix was built for. deployedBranch is the deployment target. After a plan-only
+ *  advance, where fleet-advance-to.sh correctly retags the base branch's CI
+ *  binary, provenance `main` + deployment `editor-improvements-78` is the
+ *  CORRECT state, so the card must present the pair rather than badge it.
+ *
+ *  A missing deployment resolves to null / "unknown" and is NEVER filled in from
+ *  cfg.editorBranch, though that value is right there: it is written at
+ *  reconfigure and is not updated by a binary refresh, so it is stale for
+ *  precisely this question — the same live-over-history discipline the rest of
+ *  this function applies, and the same `source` honesty. Pure; no I/O. */
 function resolveCardIdentity(live, historyCfg) {
   const cfg = historyCfg || {};
   const lcp = live && live.clientProject;
   const lei = live && live.editorIdentity;
+  const led = live && live.editorDeployment;
 
   const historyName = cfg.clientRepo ? repoBasename(cfg.clientRepo) : (cfg.newProjectName || "");
   const project = (lcp && lcp.name) || historyName || null;
@@ -505,7 +651,24 @@ function resolveCardIdentity(live, historyCfg) {
     source = "history";
   }
 
-  return { project, clientBranch, editorLabel, source };
+  const deployedBranch = (led && led.branch) || null;
+  const deployedTag = (led && led.tag) || null;
+  const deployedSource = deployedBranch || deployedTag ? "live" : "unknown";
+  let deployedState;
+  if (!deployedBranch) deployedState = "unknown";
+  else if (deployedBranch === editorLabel) deployedState = "agrees";
+  else deployedState = "differs";
+
+  return {
+    project,
+    clientBranch,
+    editorLabel,
+    source,
+    deployedBranch,
+    deployedTag,
+    deployedSource,
+    deployedState,
+  };
 }
 
 /** Sticky-merge a VM poll's `clientProject` against the last-known-good value
@@ -1173,6 +1336,9 @@ module.exports = {
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
+  branchRefTargets,
+  missingBranchRefs,
+  missingBranchRefMessage,
   addPreflight,
   isVariantProvisionable,
   isVariantRebuildable,
@@ -1181,6 +1347,7 @@ module.exports = {
   cloudUpArgs,
   classifyContainerWait,
   decideAddSlot,
+  heavyChargeCount,
   HEAVY_ACTIONS,
   queuedStatusForAction,
   pushHistory,