@codeyam-editor/codeyam-editor 0.1.4 → 0.1.5

package/npm/fleet-setup-steps.js

@@ -0,0 +1,105 @@
+'use strict';
+
+// npm/fleet-setup-steps.js — partition a VM's degradedReasons into expected
+// first-run SETUP steps vs genuine ATTENTION problems for the fleet dashboard
+// (vm: Dashboard 'Finishing setup' state for expected add steps).
+//
+// A clean greenfield Add lands with a wall of amber `⚠ Add degraded` badges
+// because every unfinished post-provision wiring step is funneled into one flat
+// `degradedReasons` string array and rendered identically. There is no
+// distinction between *expected first-run setup that just hasn't finished yet*
+// (Claude login not seeded, ingress host-rule not wired, project dir still the
+// scaffold `workspace`, no start command on a brand-new project) and *something
+// that actually broke* (broker death, half-provisioned orphan, off-branch
+// drift). This module draws that line: it parses the existing reason-code
+// prefixes and classifies each reason as a calm `setup` step or an `attention`
+// problem, keeping the rules in a tested pure function the way fleet-job-badge.js
+// / fleet-public-url.js do — server.js stays thin and the card colors finally
+// tell the truth (blue = still wiring up, amber = look at this).
+//
+// Stack note: this is fleet-operator infrastructure (the GCE fleet that runs
+// codeyam-editor itself), GCP-specific by design — the same posture as the
+// scripts it backstops. The classification is pure string parsing, no network,
+// so it unit-tests with no fixtures.
+
+// The setup-step codes this module emits. A single source so server.js and the
+// card UI agree on the vocabulary.
+const SETUP_CODES = ['auth', 'ingress', 'project-dir', 'start-command'];
+
+// The scaffold default project directory a brand-new (not-yet-created) VM runs
+// under. project-dir-drift AWAY from this is a real problem (two real project
+// names disagree); drift while still ON it is just "the greenfield project
+// hasn't been created yet" — an expected setup step.
+const SCAFFOLD_PROJECT_DIR = 'workspace';
+
+// Parse `project-dir-drift (expected: X, running: Y)` into its two names.
+// Returns { expected, running } with null fields when the shape doesn't match.
+function parseDriftReason(reason) {
+  const m = /expected:\s*([^,]+?)\s*,\s*running:\s*([^)]+?)\s*\)/.exec(reason);
+  return m ? { expected: m[1].trim(), running: m[2].trim() } : { expected: null, running: null };
+}
+
+// The re-wire command the ingress-unwired reason embeds after "Re-wire: " (see
+// fleet-public-url.js::ingressUnwiredReason). Surfaced as the setup step's
+// inline action so the calm checklist row carries the exact command, not just a
+// label. null when the reason carries no command tail.
+function parseIngressAction(reason) {
+  const m = /Re-wire:\s*(.+)$/.exec(reason);
+  return m ? m[1].trim() : null;
+}
+
+// Partition degradedReasons into { setupSteps, attentionReasons }.
+//
+//   setupSteps        ordered [{ code, label, detail, action? }] — expected
+//                     first-run wiring the card renders as a calm checklist.
+//   attentionReasons  the original reason strings that signal a genuine
+//                     problem — rendered amber with the existing ⚠ treatment.
+//
+// Unknown reason codes default to attentionReasons: an unrecognized signal is
+// surfaced loudly, never silently hidden in the calm checklist.
+function classifyReasons(degradedReasons = []) {
+  const setupSteps = [];
+  const attentionReasons = [];
+  const list = Array.isArray(degradedReasons) ? degradedReasons : [];
+  for (const raw of list) {
+    const reason = String(raw);
+    if (reason.startsWith('claude-auth-not-seeded')) {
+      setupSteps.push({ code: 'auth', label: 'Claude login', detail: reason });
+    } else if (reason.startsWith('ingress-unwired')) {
+      setupSteps.push({
+        code: 'ingress',
+        label: 'Public URL wiring',
+        detail: reason,
+        action: parseIngressAction(reason),
+      });
+    } else if (reason.startsWith('project-dir-drift')) {
+      const { expected, running } = parseDriftReason(reason);
+      if (running === SCAFFOLD_PROJECT_DIR) {
+        setupSteps.push({
+          code: 'project-dir',
+          label: expected ? `Create project ${expected}` : 'Create project',
+          detail: reason,
+        });
+      } else {
+        // Drift between two REAL project names is a genuine problem, not setup.
+        attentionReasons.push(reason);
+      }
+    } else if (reason.startsWith('start-command')) {
+      setupSteps.push({ code: 'start-command', label: 'Start command', detail: reason });
+    } else {
+      attentionReasons.push(reason);
+    }
+  }
+  return { setupSteps, attentionReasons };
+}
+
+// True when a VM's reasons are ALL expected setup steps with zero genuine
+// problems — the gate for the calm `finishing-setup` status. Requires at least
+// one setup step (an empty reason list is not "finishing setup", it's just a
+// healthy VM with nothing left to do) and zero attention reasons.
+function hasOnlySetup(degradedReasons = []) {
+  const { setupSteps, attentionReasons } = classifyReasons(degradedReasons);
+  return setupSteps.length > 0 && attentionReasons.length === 0;
+}
+
+module.exports = { classifyReasons, hasOnlySetup, SETUP_CODES, SCAFFOLD_PROJECT_DIR };

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,
+};