@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

package/npm/fleet-sleep-status.js

@@ -0,0 +1,33 @@
+'use strict';
+// Pure status helpers for the Sleep / Wake feature on the Fleet Dashboard
+// (scripts/operator/fleet-dashboard/server.js requires this). Mirrors the
+// pure-module-plus-colocated-vitest-test shape of npm/fleet-effect-status.js:
+// server.js does the impure fact-gathering (the gcloud running-VM list, the
+// per-VM reachability probe); these predicates turn those facts into the two
+// new card statuses without any I/O, so the whole decision is unit-testable.
+
+// Map a RUNNING stop/start job to its in-flight status badge. A Sleep click
+// runs `gcloud compute instances stop` as a 'stop' job → 'stopping'; a Wake
+// click runs `...start` as a 'start' job → 'starting'. Returns null for every
+// other action so deriveStatus's existing per-action chain keeps owning it.
+function sleepJobStatus(action) {
+  if (action === 'stop') return 'stopping';
+  if (action === 'start') return 'starting';
+  return null;
+}
+
+// Classify an UNREACHABLE rostered VM. The dashboard already polls GCP for the
+// set of RUNNING fleet instances (runningFleetVms) on its slow 60s cycle, so we
+// reuse it at zero extra API cost: a VM GCP still lists as running but whose
+// control API we can't reach is genuinely 'unreachable' (booting, wedged, or
+// the cloudflared tunnel is down); one absent from the running list has been
+// stopped to pause billing — 'asleep'. A null/absent list is treated as "not
+// running" so a cold dashboard with no poll yet defaults to the safe 'asleep'
+// rather than masking a stopped VM as a red unreachable.
+function unreachableStatus(n, runningFleetVms) {
+  return Array.isArray(runningFleetVms) && runningFleetVms.includes(n)
+    ? 'unreachable'
+    : 'asleep';
+}
+
+module.exports = { sleepJobStatus, unreachableStatus };

package/npm/fleet-strand.js

@@ -0,0 +1,150 @@
+'use strict';
+// Pure classification + self-heal predicates for the fleet dashboard's
+// launcher-strand detection (vm: Fleet converges onto the launcher-strand fix
+// and self-heals the strand regardless of trigger).
+//
+// A cloud VM can strand off its control port `:14199` in bare Project Launcher
+// mode: the editor re-execs into the launcher on an EPHEMERAL port instead of
+// serving its one /workspace project on the contract port, so the dashboard's
+// local-forward probe gets connection-refused and reports a generic
+// "unreachable" — indistinguishable from a real outage. Diagnosed on VM-4
+// (2026-06-25): an add-time binary that predated the `serve_cwd_directly`
+// launcher-strand guard fell through `decide_launch` to the launcher because a
+// stale `/tmp` test-fixture project padded `registry_count` to 2.
+//
+// The completed predecessor plan fixed the editor CODE PATH (serve the cwd
+// project on :14199); this module is the dashboard-side SAFETY NET that detects
+// the strand CONTINUOUSLY — by its trigger-independent SIGNAL SHAPE, not by what
+// caused it — so a running fleet can't silently sit on the landmine. This is the
+// PURE half (classification + decision), mirroring npm/fleet-public-url.js: the
+// docker-exec / curl I/O lives in scripts/operator/fleet-dashboard/server.js's
+// gatherLauncherStrand, the same gather-edge / pure-half split
+// classifyPublicUrlHealth follows. Unit-tested in npm/fleet-strand.test.js.
+//
+// Stack note: this is fleet-operator infrastructure (the GCE fleet that runs
+// codeyam-editor itself). A project that never joins the fleet never reaches it.
+
+// The boot guard whose presence makes a binary safe from the launcher-mode
+// strand. Single source so the classifier, the capability field the editor
+// advertises, and any log line agree on the string.
+const SERVE_CWD_GUARD = 'serve_cwd_directly';
+
+/** Classify a VM's in-container probe into the launcher-strand vocabulary. The
+ *  DECISIVE, trigger-independent signal is observable in-VM regardless of what
+ *  caused the strand (a stale add-time binary, a wiped open-project pointer, any
+ *  future cause):
+ *
+ *    'serving'        — `editorHealthOk`: the control port answers /api/health,
+ *                       so the editor is serving its project. Nothing to heal.
+ *    'launcher-strand'— container up, control port has NO listener, AND a
+ *                       codeyam-editor process is serving the Project Launcher on
+ *                       an ephemeral port. THIS is the strand: :14199 is dark but
+ *                       the editor is alive on the wrong port.
+ *    'down'           — container up, control port dark, and NO launcher process
+ *                       either: a genuine outage (crashed editor / dead tunnel).
+ *                       Left to the existing unreachable handling — must NOT
+ *                       auto-rebuild, a rebuild is the wrong hammer for a crash.
+ *    'unknown'        — anything else (container not up, probe failed): absence
+ *                       of evidence, never auto-acts (mirrors
+ *                       classifyPublicUrlHealth's 'unknown' contract).
+ *
+ *  `editorHealthOk` wins first: once the control port answers, the VM is serving
+ *  no matter what else a slow/racy probe reported. */
+function classifyLauncherStrand({
+  controlPortListening,
+  containerUp,
+  launcherServing,
+  editorHealthOk,
+} = {}) {
+  if (editorHealthOk) return 'serving';
+  if (containerUp && !controlPortListening && launcherServing) return 'launcher-strand';
+  if (containerUp && !controlPortListening && !launcherServing) return 'down';
+  return 'unknown';
+}
+
+/** Decide whether a just-landed strand verdict warrants an auto-recovery, the
+ *  PURE gate the standing self-heal fires through — debounced exactly like
+ *  shouldAutoRewireIngress so a recovery that doesn't immediately clear can't
+ *  loop and a single transient poll during a legitimate restart can't act:
+ *    - `verdict` is 'launcher-strand' (only the strand self-heals; 'down' is a
+ *      genuine outage the unreachable path owns, 'serving'/'unknown' need nothing),
+ *    - `strandStreak` has reached `minStreak` consecutive strand polls (a single
+ *      transient dark-port poll during a restart must not trigger a heavy rebuild),
+ *    - no recovery is `alreadyRecovering` (one heavy job per VM), AND
+ *    - the `cooldownMs` window has elapsed since `lastRecoverAt` so a recovery
+ *      still settling can't re-fire every slow cycle.
+ *  `hasSession` deliberately does NOT gate: a stranded editor has no live project
+ *  session to protect (same rationale as the post-reset force=true fallback). A
+ *  missing/0 `lastRecoverAt` means "never recovered" → the cooldown is satisfied. */
+function shouldAutoRecoverStrand({
+  verdict,
+  strandStreak,
+  alreadyRecovering,
+  lastRecoverAt,
+  now,
+  cooldownMs,
+  minStreak = 2,
+} = {}) {
+  if (verdict !== 'launcher-strand') return false;
+  if (alreadyRecovering) return false;
+  if (Number(strandStreak) < Number(minStreak)) return false;
+  return (Number(now) - (Number(lastRecoverAt) || 0)) >= Number(cooldownMs);
+}
+
+/** Choose the recovery SHAPE for a launcher-strand by binary currency. A plain
+ *  reconfigure KEEPS the editor image, so recreating the container with the SAME
+ *  pre-guard binary would immediately re-strand — the wrong hammer when a stale
+ *  binary caused the strand. Returns:
+ *    'rebuild'     — advance source to origin tip → rebuild-self → restart (the
+ *                    update-reset-everything shape) when the binary is stale OR
+ *                    its currency is UNKNOWN. The dark-control-port strand can't
+ *                    advertise its capability live, and re-stranding on a kept
+ *                    image is the worse failure, so unknown defaults to rebuild.
+ *    'reconfigure' — image-kept container recreate, correct ONLY when the running
+ *                    binary is already CURRENT (e.g. a wiped-pointer strand on a
+ *                    fresh binary), where a rebuild would be a needless ~8-min build.
+ *  `binaryCurrent === true` is the only input that yields 'reconfigure'; null /
+ *  undefined / false all yield 'rebuild'. */
+function strandRecoveryAction({ binaryCurrent } = {}) {
+  return binaryCurrent === true ? 'reconfigure' : 'rebuild';
+}
+
+/** Classify whether a STILL-SERVING VM's running binary is at risk of the
+ *  launcher-strand on its next re-exec — the PROACTIVE convergence signal (step
+ *  5), distinct from the strand verdict above (which fires only once a VM is
+ *  ALREADY dark). Whether a binary is guard-capable is answered most robustly by
+ *  the editor advertising the capability (the `bootGuards` array on the
+ *  health/session-info payload it already serves) rather than the dashboard
+ *  guessing from commit ancestry:
+ *    - `bootGuards` IS an array → authoritative: stale iff it lacks the guard.
+ *    - `bootGuards` ABSENT (an older binary that predates the field — which are
+ *      exactly the at-risk ones) → fall back to the build-commit comparison the
+ *      dashboard already computes: flag stale only when the editor source is
+ *      `editorBehind > 0` commits behind origin, so a current binary that merely
+ *      predates the FIELD isn't falsely flagged while a genuinely-behind one is.
+ *  Returns `{ stale, reason }`; `reason` is null when not stale. */
+function classifyBinaryGuard({ bootGuards, editorBehind, requiredGuard = SERVE_CWD_GUARD } = {}) {
+  if (Array.isArray(bootGuards)) {
+    if (bootGuards.includes(requiredGuard)) return { stale: false, reason: null };
+    return {
+      stale: true,
+      reason: `running binary advertises bootGuards [${bootGuards.join(', ')}] without '${requiredGuard}'; rebuild to converge`,
+    };
+  }
+  const behind = Number(editorBehind);
+  if (Number.isFinite(behind) && behind > 0) {
+    return {
+      stale: true,
+      reason: `running binary predates the boot-guard capability and editor source is ${behind} commit(s) behind origin; rebuild to converge`,
+    };
+  }
+  return { stale: false, reason: null };
+}
+
+module.exports = {
+  SERVE_CWD_GUARD,
+  classifyLauncherStrand,
+  shouldAutoRecoverStrand,
+  strandRecoveryAction,
+  classifyBinaryGuard,
+};

package/npm/fleet-stuck-status.js

@@ -0,0 +1,111 @@
+'use strict';
+
+// Pure stuck / needs-you attention policy for the Fleet Dashboard's per-VM card
+// (scripts/operator/fleet-dashboard/server.js requires this). It answers a
+// single question the existing status label deliberately does NOT: given how
+// long a VM has been parked on its CURRENT workflow step, is it progressing
+// normally, slowing down, or likely STUCK — and if it is merely waiting on a
+// human, has that wait dragged on long enough to flag "needs you"?
+//
+// Why the STEP timer, not the feature timer: the workflow cursor advances
+// (resetting `started_at` in crates/types/src/step.rs) every time a signature
+// command runs, so step-elapsed is the tightest "is it making progress?" proxy
+// we have. A long feature is normal; a long single step is the smell.
+//
+// This is an ADDITIVE overlay — it never changes the building/waiting/idle
+// status label (that stays in fleet-live-status.js). It only decorates a card
+// with a soft 'slow' note, a hard 'stuck' alarm, or a distinct 'needs you'
+// badge. The split mirrors the established dashboard pure-module pattern
+// (fleet-live-status.js, fleet-broker-status.js, fleet-vm-readiness.js):
+// server.js does the Date.now() I/O and passes the verdict to buildVmEnvelope;
+// the browser renders it.
+
+const DEFAULT_SLOW_MINUTES = 15;
+const DEFAULT_STUCK_MINUTES = 30;
+const DEFAULT_NEEDS_YOU_MINUTES = 10;
+
+// Parse an env var that should hold a positive number of minutes, falling back
+// to `fallback` when it is unset, empty, non-numeric, or non-positive. Keeping
+// this tolerant means a fat-fingered override degrades to the documented
+// default rather than producing a NaN threshold that no elapsed time can cross.
+function minutesFromEnv(raw, fallback) {
+  if (raw == null || raw === '') return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return n;
+}
+
+// Resolve the three thresholds (in milliseconds) from a process-env-shaped
+// object. Defaults live here so they are documented and unit-testable in one
+// place: slow 15m, stuck 30m, needs-you 10m. Env overrides:
+// FLEET_STUCK_STEP_SLOW_MINUTES, FLEET_STUCK_STEP_STUCK_MINUTES,
+// FLEET_NEEDS_YOU_MINUTES.
+function resolveThresholds(env) {
+  const e = env || {};
+  return {
+    slowMs: minutesFromEnv(e.FLEET_STUCK_STEP_SLOW_MINUTES, DEFAULT_SLOW_MINUTES) * 60_000,
+    stuckMs: minutesFromEnv(e.FLEET_STUCK_STEP_STUCK_MINUTES, DEFAULT_STUCK_MINUTES) * 60_000,
+    needsYouMs: minutesFromEnv(e.FLEET_NEEDS_YOU_MINUTES, DEFAULT_NEEDS_YOU_MINUTES) * 60_000,
+  };
+}
+
+// Compute elapsed ms from an ISO timestamp to nowMs, or null when the timestamp
+// is missing / unparseable. A null elapsed is the graceful-degrade path for an
+// older editor whose /api/session-info predates startedAt/featureStartedAt.
+function elapsedMs(iso, nowMs) {
+  if (!iso) return null;
+  const started = Date.parse(iso);
+  if (!Number.isFinite(started)) return null;
+  const delta = nowMs - started;
+  return delta >= 0 ? delta : 0;
+}
+
+// Derive the attention verdict for one VM.
+//
+//   deriveAttention({ status, stepStartedAt, awaitingInput, nowMs, thresholds })
+//     -> { stepElapsedMs, level, needsYou, needsYouElapsedMs }
+//
+// Rules:
+//   - `level` ('ok' | 'slow' | 'stuck') is computed ONLY for an actively-
+//     building VM (status === 'building'). Thresholds are inclusive:
+//     >= stuckMs -> 'stuck', else >= slowMs -> 'slow', else 'ok'.
+//   - A VM awaiting input (status === 'waiting' or awaitingInput true) never
+//     reads 'slow'/'stuck' — it is legitimately blocked on a human. Instead
+//     `needsYou` flips true once its elapsed >= needsYouMs.
+//   - Missing/unparseable stepStartedAt degrades to stepElapsedMs:null,
+//     level:'ok', needsYou:false (older editor, no crash).
+function deriveAttention(opts) {
+  const o = opts || {};
+  const thresholds = o.thresholds || resolveThresholds({});
+  const nowMs = o.nowMs;
+  const stepElapsed = elapsedMs(o.stepStartedAt, nowMs);
+  const awaiting = o.status === 'waiting' || !!o.awaitingInput;
+
+  let level = 'ok';
+  let needsYou = false;
+  let needsYouElapsedMs = null;
+
+  if (awaiting) {
+    // Waiting on a human — never "stuck"; flag "needs you" past its threshold.
+    needsYouElapsedMs = stepElapsed;
+    needsYou = stepElapsed != null && stepElapsed >= thresholds.needsYouMs;
+  } else if (o.status === 'building' && stepElapsed != null) {
+    if (stepElapsed >= thresholds.stuckMs) level = 'stuck';
+    else if (stepElapsed >= thresholds.slowMs) level = 'slow';
+  }
+
+  return {
+    stepElapsedMs: stepElapsed,
+    level,
+    needsYou,
+    needsYouElapsedMs,
+  };
+}
+
+module.exports = {
+  deriveAttention,
+  resolveThresholds,
+  DEFAULT_SLOW_MINUTES,
+  DEFAULT_STUCK_MINUTES,
+  DEFAULT_NEEDS_YOU_MINUTES,
+};

package/npm/fleet-vm-access.js

@@ -0,0 +1,234 @@
+'use strict';
+
+// npm/fleet-vm-access.js — the per-VM IAP access whitelist sidecar
+// (`.codeyam/logs/fleet-vm-access.json`). It records which principals may reach
+// a specific fleet VM's IAP-secured surfaces, keyed by VM number:
+// `{ "<N>": ["user:a@x.com", "group:team@x.com", "domain:partner.com"], ... }`.
+//
+// Why a sidecar and not the roster: the roster (`npm/fleet-roster.js`) is a flat
+// integer array with a hard "sorted, de-duped set of integers" invariant bash
+// consumers depend on. Access is a per-VM list, a different shape, so it lives in
+// a SEPARATE map fronted by a read+write seam modeled exactly on
+// npm/fleet-vm-slugs.js (atomic temp-file + rename, tolerant of a missing or
+// malformed file). The slug sidecar maps a VM number to one hostname label; this
+// one maps a VM number to an access list — same persistence contract, sibling
+// concern.
+//
+// IAP access is granted at the resource level on a VM's per-surface backend
+// services (`vm-<N>-<surface>-bes`); this file is only the source-of-truth list,
+// the gcloud binding is applied by scripts/gcp/iap-access.sh. The owner's
+// project-wide grant (scripts/gcp/google-ingress.sh) is independent — these lists
+// only ADD collaborators to specific VMs.
+//
+// Env override: `VM_ACCESS_FILE` relocates the file (mirrors fleet-vm-slugs.js's
+// `VM_SLUGS_FILE`); resolved once at module load.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+const { normalizeVmNumber } = require('./vm-urls');
+
+const VM_ACCESS_FILE = process.env.VM_ACCESS_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-vm-access.json');
+
+// The IAM principal types IAP accepts on a backend-service binding. A bare email
+// (no type prefix) defaults to `user:`.
+const PRINCIPAL_TYPES = Object.freeze(['user', 'group', 'domain']);
+
+// A DNS domain: at least two dot-separated labels, each a lowercase
+// letters/digits/hyphen label (no leading/trailing hyphen). Used to validate a
+// `domain:` principal and the domain half of a `user:`/`group:` email — a typo'd
+// principal must fail loud before reaching gcloud.
+const DOMAIN_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
+
+/** Validate + normalize one IAM principal into the `<type>:<value>` form gcloud
+ *  expects. Accepts `user:a@x.com`, `group:team@x.com`, `domain:x.com`; a bare
+ *  `a@x.com` defaults to `user:`. Rejects (loudly) a malformed value so junk
+ *  never reaches `gcloud iap web add-iam-policy-binding` — the same
+ *  fail-at-the-boundary posture as normalizeVmSlug. Returns the lowercased,
+ *  trimmed, type-prefixed principal. */
+function normalizePrincipal(raw) {
+  if (raw == null) throw new Error('access principal is required');
+  const trimmed = String(raw).trim();
+  if (trimmed === '') throw new Error('access principal must not be empty');
+  const lower = trimmed.toLowerCase();
+  const colon = lower.indexOf(':');
+  const hasType = colon !== -1 && PRINCIPAL_TYPES.includes(lower.slice(0, colon));
+  const type = hasType ? lower.slice(0, colon) : 'user';
+  const value = hasType ? lower.slice(colon + 1) : lower;
+  if (value === '') {
+    throw new Error(`access principal "${raw}" has an empty value after "${type}:"`);
+  }
+  if (type === 'domain') {
+    if (value.includes('@') || !DOMAIN_RE.test(value)) {
+      throw new Error(
+        `access principal "${raw}" is not a valid domain (e.g. domain:example.com)`,
+      );
+    }
+  } else {
+    const at = value.indexOf('@');
+    if (at <= 0 || value.indexOf('@', at + 1) !== -1) {
+      throw new Error(
+        `access principal "${raw}" is not a valid ${type} email ` +
+          `(exactly one "@", e.g. ${type}:a@example.com)`,
+      );
+    }
+    const domain = value.slice(at + 1);
+    if (!DOMAIN_RE.test(domain)) {
+      throw new Error(`access principal "${raw}" has an invalid email domain "${domain}"`);
+    }
+  }
+  return `${type}:${value}`;
+}
+
+/** Normalize a whole access list — an array of principals or a comma-separated
+ *  string — into a deduped, validated array of `<type>:<value>` principals.
+ *  Blank entries are skipped; a single malformed entry throws (the list is
+ *  rejected as a whole rather than silently dropping the bad one). Order of first
+ *  appearance is preserved. */
+function normalizeAccessList(input) {
+  const raw = Array.isArray(input)
+    ? input
+    : String(input == null ? '' : input).split(',');
+  const out = [];
+  const seen = new Set();
+  for (const item of raw) {
+    const s = String(item).trim();
+    if (s === '') continue;
+    const principal = normalizePrincipal(s);
+    if (!seen.has(principal)) {
+      seen.add(principal);
+      out.push(principal);
+    }
+  }
+  return out;
+}
+
+// Read the access sidecar, returning a `{ [vmNumber]: principal[] }` object, or
+// null if the file is missing or malformed (treated as "no access lists"). Keys
+// are the string form JSON emits; callers look them up by `String(n)`.
+function readAccess() {
+  try {
+    const data = JSON.parse(fs.readFileSync(VM_ACCESS_FILE, 'utf8'));
+    if (data && typeof data === 'object' && !Array.isArray(data)) return data;
+  } catch { /* missing or malformed */ }
+  return null;
+}
+
+// Persist `map` as the sidecar, atomically: write a pid-stamped temp file then
+// `rename` it over the target so a concurrent reader never observes a
+// half-written file (mirrors fleet-vm-slugs.js::writeSlugs). Returns the written
+// map.
+function writeAccess(map) {
+  const next = map && typeof map === 'object' && !Array.isArray(map) ? map : {};
+  fs.mkdirSync(path.dirname(VM_ACCESS_FILE), { recursive: true });
+  const tmp = `${VM_ACCESS_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next));
+  fs.renameSync(tmp, VM_ACCESS_FILE); // atomic replace
+  return next;
+}
+
+/** The access list for VM `n` — the principals whitelisted onto its surfaces —
+ *  or an empty array when it has none (or the file is absent). The number is
+ *  validated so junk can't sneak through as a lookup key. */
+function accessFor(n) {
+  const num = normalizeVmNumber(n);
+  const map = readAccess();
+  const list = map && map[String(num)];
+  return Array.isArray(list) ? list.filter((p) => typeof p === 'string' && p) : [];
+}
+
+/** Replace VM `n`'s access list wholesale with `principals` (validated + deduped
+ *  via normalizeAccessList). An empty result removes the VM's entry entirely so
+ *  the sidecar never accumulates empty arrays. Returns the stored list. */
+function setAccess(n, principals) {
+  const num = normalizeVmNumber(n);
+  const list = normalizeAccessList(principals);
+  const map = { ...(readAccess() || {}) };
+  if (list.length === 0) delete map[String(num)];
+  else map[String(num)] = list;
+  writeAccess(map);
+  return list;
+}
+
+/** Add a single principal to VM `n`'s access list (validated + deduped). Adding
+ *  one already present is an idempotent no-op-shaped write. Returns the new list. */
+function addAccess(n, principal) {
+  const num = normalizeVmNumber(n);
+  const p = normalizePrincipal(principal);
+  const next = accessFor(num);
+  if (!next.includes(p)) next.push(p);
+  const map = { ...(readAccess() || {}) };
+  map[String(num)] = next;
+  writeAccess(map);
+  return next;
+}
+
+/** Remove a single principal from VM `n`'s access list. Removing an absent
+ *  principal is a no-op; emptying the list removes the VM's entry. Returns the
+ *  new list. */
+function removeAccess(n, principal) {
+  const num = normalizeVmNumber(n);
+  const p = normalizePrincipal(principal);
+  const next = accessFor(num).filter((x) => x !== p);
+  const map = { ...(readAccess() || {}) };
+  if (next.length === 0) delete map[String(num)];
+  else map[String(num)] = next;
+  writeAccess(map);
+  return next;
+}
+
+/** Parse the raw stdout of `gcloud projects get-iam-policy ...
+ *  --format='value(bindings.members)'` into a deduped, trimmed array of
+ *  principals. gcloud separates members within a binding by `;` and (when not
+ *  flattened) bindings by newline, so we split on BOTH. Order of first
+ *  appearance is preserved.
+ *
+ *  This is deliberately NOT normalizePrincipal: it is a *read* of whatever IAM
+ *  already holds, so it must surface principals verbatim (lowercased only for
+ *  dedup-stability) — including `serviceAccount:` members that the strict
+ *  write-path validator would reject. The one thing it drops, besides blanks, is
+ *  gcloud's `deleted:` tombstone members (e.g.
+ *  `deleted:user:x@x.com?uid=123`), which name principals that no longer exist
+ *  and can't be acted on. */
+function parseProjectMembers(stdout) {
+  const out = [];
+  const seen = new Set();
+  for (const raw of String(stdout == null ? '' : stdout).split(/[;\n]/)) {
+    const s = raw.trim();
+    if (s === '') continue;
+    if (s.toLowerCase().startsWith('deleted:')) continue;
+    const principal = s.toLowerCase();
+    if (!seen.has(principal)) {
+      seen.add(principal);
+      out.push(principal);
+    }
+  }
+  return out;
+}
+
+/** Drop VM `n`'s entire access list, returning the new map. Clearing an absent
+ *  entry is a no-op. Called on Destroy so a number freed and later re-used
+ *  doesn't inherit a stale whitelist. */
+function clearAccess(n) {
+  const num = normalizeVmNumber(n);
+  const map = { ...(readAccess() || {}) };
+  delete map[String(num)];
+  return writeAccess(map);
+}
+
+module.exports = {
+  VM_ACCESS_FILE,
+  PRINCIPAL_TYPES,
+  normalizePrincipal,
+  normalizeAccessList,
+  parseProjectMembers,
+  readAccess,
+  writeAccess,
+  accessFor,
+  setAccess,
+  addAccess,
+  removeAccess,
+  clearAccess,
+};

package/npm/fleet-vm-readiness.js

@@ -0,0 +1,104 @@
+'use strict';
+// Pure readiness derivation for the Fleet Dashboard's per-VM card
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the merged
+// poll state `v` and the derived `ctx` the card builder already computes,
+// collapse the VM into a single readiness label the card renders. No I/O —
+// server.js owns the polling (including the slow-cadence LB backend-health
+// probe that fills `v.backendHealth`).
+//
+// The bug this fixes: a VM card rendered as idle with a CLICKABLE editor URL the
+// moment the VM was rostered + SSH-tunnel-reachable, even when its public LB URL
+// (vm-<N>.editor.<domain>) would return Envoy "no healthy upstream" (503). The
+// card reflected only SSH-tunnel reachability to :14199, never whether the load
+// balancer actually routes to a HEALTHY backend. Two situations cause the 503,
+// and the card had zero visibility into either:
+//
+//   transient half-wire — the editor is serving but the LB health check hasn't
+//                         marked the backend HEALTHY yet during cold start. It
+//                         resolves on its own; the card should say 'starting'.
+//   permanent half-wire — the per-VM LB backend service was never created (e.g.
+//                         the Add ran under a service account lacking
+//                         compute.backendServices.create), so the URL 503s
+//                         forever until re-wired. The card should say
+//                         'half-wired', visibly distinct from 'starting'.
+//
+// SSH reachability (v.reachable from probeVM over the tunnel) is necessary but
+// not sufficient: the tunnel is up in BOTH 503 cases. Only the LB backend health
+// (gcloud compute backend-services get-health, gathered into v.backendHealth)
+// distinguishes ready / starting / half-wired. The editor's own /healthz can't
+// see the half-wire, so it is not enough on its own.
+//
+//   'provisioning' — an Add/recover job is in flight; the VM is still being
+//                    built, so judging its public-URL readiness is premature.
+//   'unreachable'  — the editor did not answer over the tunnel. Nothing
+//                    downstream (broker, LB health) is meaningful; the link is
+//                    gated exactly as today.
+//   'half-wired'   — LB mode, the editor backend service is ABSENT (never
+//                    created). The permanent 503 case — the public URL will fail
+//                    until re-wired. The state that had NO signal before.
+//   'starting'     — LB mode, the editor backend exists but is UNHEALTHY (LB has
+//                    not yet marked it HEALTHY). The transient 503 case; flips to
+//                    'ready' on its own once the health check passes.
+//   'broker-down'  — reachable + LB-healthy (or legacy mode), but the broker
+//                    daemon is down, so the VM cannot start an agent session.
+//   'ready'        — reachable, broker up, and (LB mode) the editor backend is
+//                    HEALTHY. The only state whose editor link is live + green.
+//
+// Legacy mode (FLEET_DOMAIN unset ⇒ ctx.lbMode falsey, or no backendHealth
+// supplied): there is no LB to health-check, so the backend-health branch is
+// skipped and readiness degrades to today's reachability/broker behavior — no
+// regression, no gcloud calls.
+const READINESS_STATES = [
+  'provisioning',
+  'unreachable',
+  'half-wired',
+  'starting',
+  'broker-down',
+  'ready',
+];
+
+// A VM mid-provision: an Add (incl. its recovering re-run) that is queued
+// (number reserved, cloud:up not started) or running. Its public URL has no
+// meaningful readiness yet, so this takes precedence over every other signal —
+// a freshly-reserved VM must not flash 'half-wired' before its backend exists.
+function isProvisioning(job) {
+  if (!job) return false;
+  if (job.action === 'add' && (job.state === 'running' || job.state === 'queued')) return true;
+  if (job.recovering && job.state === 'running') return true;
+  return false;
+}
+
+// `v` is the merged poll state (state.vms[n]); `ctx` carries the derived values
+// the card builder already has on hand:
+//   ctx.job          — the active job (or null), for the provisioning check.
+//   ctx.brokerStatus — the debounced broker tri-state ('down'|'idle'|
+//                      'agent-live'|'unknown') the card already derives.
+//   ctx.lbMode       — true when FLEET_DOMAIN is set (the LB fronts the URLs).
+//                      When false, the backend-health branch is skipped.
+function deriveVmReadiness(v, ctx) {
+  const c = ctx || {};
+  // 1. Still being built — don't judge a half-built VM as ready or half-wired.
+  if (isProvisioning(c.job)) return 'provisioning';
+  // 2. Editor unreachable over the tunnel: we polled nothing, so broker / LB
+  //    health are unknowable. Link gated, exactly as the pre-readiness card did.
+  if (!v || !v.reachable) return 'unreachable';
+  // 3. LB mode only: the public URL's fate is the editor backend's LB health.
+  //    Skipped entirely in legacy mode (no LB) or before the first probe lands
+  //    (no backendHealth) — both fall through to the reachability/broker path.
+  const bh = v.backendHealth;
+  if (c.lbMode && bh) {
+    // Backend service never created ⇒ permanent 503 until re-wired.
+    if (bh.editor === 'absent') return 'half-wired';
+    // Backend exists but not yet HEALTHY ⇒ transient 503 during cold start.
+    if (bh.editor === 'unhealthy') return 'starting';
+    // 'healthy' falls through to ready; 'unknown' (get-health errored) is
+    // absence-of-evidence — never rendered as a problem, falls through too.
+  }
+  // 4. Reachable but the broker daemon is down: the VM can't start a session.
+  if (c.brokerStatus === 'down') return 'broker-down';
+  // 5. Reachable, broker up, and (LB mode) the editor backend is HEALTHY —
+  //    genuinely ready: green, clickable, public URL actually routes.
+  return 'ready';
+}
+
+module.exports = { deriveVmReadiness, READINESS_STATES, isProvisioning };