@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/fleet-stuck-status.js

@@ -0,0 +1,117 @@
+'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, 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'.
+//   - "Needs you" flips true ONLY for the genuinely-blocked `waiting` state (a
+//     running task awaiting a human), once its elapsed >= needsYouMs. An 'idle'
+//     VM (parked at its prompt, no task running) is deliberately NOT flagged no
+//     matter how long it sits — idle means "ready for you to start something",
+//     not "a task is blocked on you" (observed live 2026-06-30, VM-1, which
+//     false-flagged "Needs You" while merely idle). `awaitingInput` alone no
+//     longer drives this: liveSessionStatus already collapses an idle awaiting
+//     agent to 'idle' and a blocked one to 'waiting', so the status IS the
+//     discriminator.
+//   - 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);
+
+  let level = 'ok';
+  let needsYou = false;
+  let needsYouElapsedMs = null;
+
+  if (o.status === 'waiting') {
+    // A task genuinely blocked on a human — never "stuck"; flag "needs you" past
+    // its threshold. An 'idle' VM never reaches this branch.
+    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,404 @@
+'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;
+}
+
+// The env/config key holding the standing default-operator principal(s) — the
+// fleet owner / ops identity that must ALWAYS be able to reach an IAP-secured VM.
+// Comma-separated `user:`/`group:`/`domain:` principals (a bare email defaults to
+// `user:`), e.g. `VM_ACCESS_DEFAULT=user:jared@codeyam.com`. Read from config, not
+// hardcoded here, so the default operator is tenant-configurable.
+const DEFAULT_OPERATOR_ENV = 'VM_ACCESS_DEFAULT';
+
+// The default gcloud-account resolver, split out so it is the ONLY function that
+// touches child_process — the module stays side-effect-free at load, and
+// resolveDefaultOperator takes an injectable `exec` so its fallback is unit
+// testable without a real gcloud. Returns the active account email, or '' when
+// gcloud is absent / errors (never throws to the caller).
+function defaultGcloudAccountExec() {
+  const { spawnSync } = require('child_process');
+  const r = spawnSync('gcloud', ['config', 'get-value', 'account'], { encoding: 'utf8' });
+  if (!r || r.status !== 0) return '';
+  return String(r.stdout || '').trim();
+}
+
+// Read the standing default-operator principal(s) from `.codeyam/cloud.json`'s
+// `vmAccessDefault` key — the durable per-project config that resolves the default
+// operator even when a launchd/systemd env was never re-baked with
+// `VM_ACCESS_DEFAULT`. Returns the raw config value ('' when the file is missing or
+// malformed, or the key is absent / not a string) so a broken cloud.json is treated
+// as "no config" and never throws. Split out (like defaultGcloudAccountExec) so the
+// cloud.json layer of resolveDefaultOperator is injectable/unit-testable without a
+// real file. `.codeyam/cloud.json` is resolved via `rootDir` — the same repo root
+// the access sidecar and other state files use. `cloudJsonPath` is a parameter
+// (defaulting to that resolved path) so the reader is unit-testable against a temp
+// file, the same injectable-for-testability posture as defaultGcloudAccountExec.
+// The path also honors `VM_ACCESS_CLOUD_JSON` — the same env-override isolation
+// posture as `VM_ACCESS_FILE` above — so a test process (or an operator) can point
+// this read at a throwaway path and never pick up the developer's real
+// `.codeyam/cloud.json` `vmAccessDefault`.
+function defaultCloudConfigRead(
+  cloudJsonPath = process.env.VM_ACCESS_CLOUD_JSON || path.join(rootDir, '.codeyam', 'cloud.json'),
+) {
+  try {
+    const raw = fs.readFileSync(cloudJsonPath, 'utf8');
+    const data = JSON.parse(raw);
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+      return typeof data.vmAccessDefault === 'string' ? data.vmAccessDefault : '';
+    }
+  } catch { /* missing or malformed cloud.json → no config */ }
+  return '';
+}
+
+/** Resolve the standing default-operator principal(s) that must be granted IAP
+ *  access whenever a VM's IAP is enabled — the fix for "IAP enabled but nobody
+ *  granted" (the Error-51-by-default footgun). Config first, most-specific to
+ *  least:
+ *    1. `VM_ACCESS_DEFAULT` (the env knob) — normalized and returned.
+ *    2. `.codeyam/cloud.json`'s `vmAccessDefault` — the DURABLE per-project config,
+ *       consulted when the env var is unset. This closes the gap that made every
+ *       fleet Add grant nobody: the dashboard/Add runs as the automation SERVICE
+ *       ACCOUNT, and with no `VM_ACCESS_DEFAULT` in the (un-re-baked) launchd env
+ *       the resolver used to fall straight through to the gcloud fallback and skip
+ *       the SA — resolving `[]`. Reading cloud.json here means every caller
+ *       (iap-access.sh, cloud.js, the dashboard) inherits the default operator
+ *       without an env re-bake.
+ *    3. Fallback: the active gcloud account, so a HUMAN operator running these
+ *       scripts locally gets access with no extra config. A SERVICE-ACCOUNT
+ *       session (the automation SA, whose account ends in `gserviceaccount.com`)
+ *       is skipped — granting the automation SA to itself is a pointless no-op,
+ *       and the human/ops identity it should grant is unknowable from the SA
+ *       session, so config (env or cloud.json) is REQUIRED there.
+ *  Returns a normalized principal array (possibly empty — callers treat empty as
+ *  "no default operator configured" and keep their prior behavior). `exec` and
+ *  `readCloudConfig` are injectable so the gcloud and cloud.json fallbacks are
+ *  unit-testable without a real gcloud / file. */
+function resolveDefaultOperator({ env = process.env, exec, readCloudConfig } = {}) {
+  const configured = env[DEFAULT_OPERATOR_ENV];
+  if (configured != null && String(configured).trim() !== '') {
+    try { return normalizeAccessList(configured); } catch { return []; }
+  }
+  let fromCloud = '';
+  try { fromCloud = String((readCloudConfig || defaultCloudConfigRead)() || '').trim(); }
+  catch { fromCloud = ''; }
+  if (fromCloud !== '') {
+    try { return normalizeAccessList(fromCloud); } catch { return []; }
+  }
+  let account = '';
+  try { account = String((exec || defaultGcloudAccountExec)() || '').trim(); }
+  catch { account = ''; }
+  if (account === '' || /gserviceaccount\.com$/i.test(account)) return [];
+  try { return normalizeAccessList(account); } catch { return []; }
+}
+
+/** The loud degraded reason(s) to attach to a freshly-added VM whose IAP would
+ *  authorize NOBODY. Fires only for a SUCCESSFUL `add` (`ok`) in LB mode (`lbMode`
+ *  — a FLEET_DOMAIN is configured so the VM's public URL is IAP-gated) when the
+ *  default operator resolved empty (`resolvedOperatorCount === 0`): the automation-
+ *  SA identity with no `VM_ACCESS_DEFAULT` env AND no `.codeyam/cloud.json`
+ *  `vmAccessDefault` fallback (the 2026-07-09 footgun). In that case the URL comes
+ *  up authorizing nobody yet the add reads as "done" — so we surface the exact
+ *  remedy on the card instead of a silently gated URL. `resolvedOperatorCount` is
+ *  `null` when the caller skipped the (gcloud) resolve because the cheap gates
+ *  already failed; the `!== 0` test covers both null and a positive count. Returns a
+ *  single actionable reason or [] so the dashboard can spread it into
+ *  `degradedReasons` with no conditional at the call site. Pure (no I/O): the string
+ *  lives in exactly one place and the trigger is unit-testable. */
+function noDefaultOperatorDegradedReasons({ ok, action, lbMode, resolvedOperatorCount, vmNumber } = {}) {
+  if (!ok || action !== 'add' || !lbMode || resolvedOperatorCount !== 0) return [];
+  return [
+    'iap-default-operator-missing: IAP default operator not configured — set '
+      + 'VM_ACCESS_DEFAULT or cloud.json vmAccessDefault (the public URL will '
+      + `authorize nobody; run scripts/gcp/iap-access.sh ${vmNumber} grant after configuring).`,
+  ];
+}
+
+/** 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;
+ *  the per-VM sidecar still records only the explicit collaborators, so the
+ *  always-present operator never pollutes the per-VM whitelist display or a
+ *  reused number's stale-revoke computation. */
+function withDefaultOperator(list, defaultOperator) {
+  const base = normalizeAccessList(list);
+  const seen = new Set(base);
+  const out = base.slice();
+  for (const p of normalizeAccessList(defaultOperator)) {
+    if (!seen.has(p)) { seen.add(p); out.push(p); }
+  }
+  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;
+}
+
+/** Reconcile a VM's LOCAL access sidecar against LIVE IAM. PURE — the caller
+ *  does the two reads (the sidecar file, the gcloud IAP probe) and hands both in,
+ *  so this decision logic is unit-testable without the fleet dashboard's
+ *  untestable server shell around it.
+ *
+ *  `sidecar` is the recorded principal list (what someone asked to grant);
+ *  `iapMembers` is the aggregated live-IAM result from
+ *  fleet-public-url.js::aggregateIapMembers, or null/undefined when that read has
+ *  not landed or a surface errored. Returns:
+ *
+ *    live    — the principals IAM actually authorizes. The display truth.
+ *    drift   — sidecar principals live IAM does NOT confirm. These are failed
+ *              grants; a caller renders them flagged, never as access.
+ *    pending — the live read is unavailable, so NEITHER list is verified.
+ *    partial — a principal holds the role on some ingress surfaces but not all.
+ *
+ *  The pending distinction is the whole point. Treating an unavailable read as an
+ *  empty policy would render a genuinely-granted collaborator as missing — the
+ *  same false report as the bug this replaces, merely inverted. So when
+ *  `iapMembers` is absent, `live` is empty, every sidecar principal lands in
+ *  `drift`, and `pending` is true to tell the caller not to assert either way.
+ *
+ *  Comparison is case-insensitive: parseProjectMembers lowercases for
+ *  dedup-stability while the sidecar holds whatever normalizePrincipal produced. */
+function reconcileVmAccess(sidecar, iapMembers) {
+  const recorded = Array.isArray(sidecar) ? sidecar : [];
+  if (!iapMembers || !Array.isArray(iapMembers.all)) {
+    return { live: [], drift: recorded, pending: true, partial: false };
+  }
+  const live = new Set(iapMembers.all.map((m) => String(m).toLowerCase()));
+  return {
+    live: iapMembers.all,
+    drift: recorded.filter((p) => !live.has(String(p).toLowerCase())),
+    pending: false,
+    partial: iapMembers.partial === true,
+  };
+}
+
+/** 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,
+  DEFAULT_OPERATOR_ENV,
+  normalizePrincipal,
+  normalizeAccessList,
+  resolveDefaultOperator,
+  defaultCloudConfigRead,
+  noDefaultOperatorDegradedReasons,
+  withDefaultOperator,
+  parseProjectMembers,
+  reconcileVmAccess,
+  readAccess,
+  writeAccess,
+  accessFor,
+  setAccess,
+  addAccess,
+  removeAccess,
+  clearAccess,
+};