@codeyam-editor/codeyam-editor 0.1.6 → 0.1.8

package/npm/fleet-probe-transport.js

@@ -0,0 +1,155 @@
+'use strict';
+// The fleet dashboard's two LB-path HTTP probe transports, extracted from
+// scripts/operator/fleet-dashboard/server.js so their SOCKET LIFETIME is
+// testable.
+//
+// The undici contract, which is the whole reason this module exists: a `fetch`
+// response body is a stream that holds its connection open until it is read to
+// completion or explicitly cancelled. IGNORING `res.body` is NOT the same as
+// releasing it — the socket stays checked out of the agent's pool, and once the
+// peer sends FIN it parks in CLOSE-WAIT forever. Node's `http` module is the
+// opposite (an unread response pauses the socket, hence the `res.resume(); //
+// drain so the socket can close` in server.js's localGetJson), and that
+// asymmetry is what got missed when the fetch path was added.
+//
+// On 2026-08-01 that leaked 10,749 CLOSE-WAIT sockets to the fleet LB
+// (8.228.227.92:443) holding 128MB of unread IAP-login HTML in kernel receive
+// queues — ~460 sockets/hour, a ~1-day fuse — driving the dashboard cgroup into
+// swap-thrash until the node event loop stalled in `D` state and dashboard-bes
+// went UNHEALTHY while systemd still reported the unit active.
+//
+// So: EVERY return path here consumes or cancels the body. `fetch` is injected
+// rather than closed over, so a test can drive every branch with a body that
+// records whether it was cancelled.
+
+const fpt = require('./fleet-vm-probe-target');
+
+/** Release the connection behind a response we are not going to read.
+ *
+ *  Swallows its own failure deliberately. `cancel()` rejects when the body was
+ *  already consumed or already errored — in both cases the connection is
+ *  released anyway, so there is nothing to recover from and nothing to report.
+ *  Letting it throw would be actively harmful: these calls sit inside the
+ *  transports' `try`, so a rejection would be caught by the transport's own
+ *  catch and misclassify a perfectly good HTTP response as `unreachable`.
+ */
+async function disposeBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+    // Already consumed, already errored, or no body at all — connection is
+    // released either way.
+  }
+}
+
+/** GET JSON from a resolved LB target.
+ *
+ *  Uses redirect:'manual' so IAP's 302→accounts.google.com surfaces as a
+ *  classifiable response instead of the fetch silently following it and handing
+ *  us a login page that fails JSON parsing — which would read as "VM is down"
+ *  when the real fault is our token. That 302 carries a full HTML login page,
+ *  which is exactly why the non-ok return below must dispose of the body.
+ *
+ *  `deps` injects the transport's collaborators for tests: `fetchImpl` (default
+ *  global fetch) and `warn` (default console.warn).
+ */
+async function lbGetJson(target, timeout, deps = {}) {
+  const { fetchImpl = globalThis.fetch, warn = console.warn } = deps;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeout);
+  try {
+    const res = await fetchImpl(target.url, {
+      headers: target.headers,
+      redirect: 'manual',
+      signal: ctl.signal,
+    });
+    const outcome = fpt.classifyProbeResponse({
+      status: res.status,
+      location: res.headers.get('location'),
+    });
+    if (outcome !== 'ok') {
+      // 401 and 403 share one outcome but have opposite fixes (OAuth client vs
+      // IAM grant). Name which one we hit, so the next misconfig is diagnosable
+      // from the log instead of a live curl against the backend.
+      const why = fpt.describeAuthMisconfig(res.status);
+      if (why) warn(`probe ${target.url}: HTTP ${res.status} — ${why}`);
+      await disposeBody(res);
+      return { outcome, json: null, status: res.status };
+    }
+    // `status` rides on every return so a caller can NAME the HTTP status in a
+    // fault warning. Without it a reachable-but-unusable body was indiscernible
+    // from a dead VM in the log — see probeBodyFault.
+    //
+    // Both branches below are body-safe without an explicit cancel: `res.text()`
+    // reads the stream to completion, so the connection is already released by
+    // the time JSON.parse runs or throws.
+    try { return { outcome: 'ok', json: JSON.parse(await res.text()), status: res.status }; }
+    catch { return { outcome: 'unreachable', json: null, error: 'bad-json', status: res.status }; }
+  } catch (err) {
+    // No response to dispose of — the request never produced one.
+    return {
+      outcome: 'unreachable',
+      json: null,
+      error: err && err.name === 'AbortError' ? 'timeout' : 'error',
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Reachability-only transport for the PUBLIC preview ingress over the IAP-LB
+ *  seam.
+ *
+ *  Unlike lbGetJson it does not PARSE a body — the preview root returns HTML, so
+ *  routing it through lbGetJson would fail-close on the non-JSON parse. It must
+ *  still DISPOSE of that body on every path; "does not parse" was historically
+ *  written as "does not touch", and that is precisely what leaked.
+ *
+ *  Classifies purely on the HTTP response:
+ *    any non-auth HTTP response (200, or even 404/502 — the LB routed to a
+ *                                backend that answered) → true (ingress wired);
+ *    auth-misconfigured (302→Google login / 401 / 403) → null (UNKNOWN, never
+ *                        false): the preview backend is a SEPARATE IAP backend
+ *                        service whose audience/accessor may differ from the
+ *                        editor backend the operator token is minted for, so an
+ *                        auth challenge here proves nothing about the URL wiring;
+ *    transport error / timeout                          → false (nothing answered).
+ *
+ *  Uses redirect:'manual' so an IAP login 302 surfaces as classifiable instead
+ *  of fetch silently following it to a login page.
+ */
+async function lbProbeReachable(target, timeout, deps = {}) {
+  const { fetchImpl = globalThis.fetch, warn = console.warn } = deps;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeout);
+  try {
+    const res = await fetchImpl(target.url, {
+      headers: target.headers,
+      redirect: 'manual',
+      signal: ctl.signal,
+    });
+    const outcome = fpt.classifyProbeResponse({
+      status: res.status,
+      location: res.headers.get('location'),
+    });
+    if (outcome === 'auth-misconfigured') {
+      const why = fpt.describeAuthMisconfig(res.status);
+      if (why) warn(`preview ingress ${target.url}: HTTP ${res.status} — ${why}`);
+      await disposeBody(res);
+      return null;
+    }
+    await disposeBody(res);
+    return true;
+  } catch {
+    // No response to dispose of — the request never produced one.
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+module.exports = {
+  disposeBody,
+  lbGetJson,
+  lbProbeReachable,
+};

package/npm/fleet-queue.js

@@ -126,9 +126,150 @@ function reconcileQueueDraft(draftOrder, liveOrder) {
   return out;
 }
 
+// Consecutive failed reads before the panel stops trusting its mirror. At the
+// default QUEUE_POLL_MS of 5000 this is ~15s of sustained failure — long enough
+// that the ordinary 20s-timeout blip the next tick clears only ever reaches
+// 'degraded', short enough that a real credential outage is flagged in seconds.
+// Named rather than inlined so the verdict and the tooltip copy read the same
+// number from one place.
+const QUEUE_STALE_AFTER_FAILURES = 3;
+
+/** Merge one commit-queue poll result over the previous memo.
+ *
+ *  THE RULE: a failed read RETAINS the previous `entries` AND the previous
+ *  `readAt`, and records `error`. Retaining the entries is deliberate — a stale
+ *  order beats a blank panel for an operator mid-triage. Leaving `readAt`
+ *  untouched is what makes the staleness legible: it is the ONLY signal that
+ *  distinguishes a frozen view from a live one.
+ *
+ *  Advancing `readAt` on a failure is precisely the bug this exists to prevent.
+ *  On 2026-08-14 /etc/codeyam/git-credentials on the operator host went to 0
+ *  bytes and every origin git operation began failing; the queue panel went on
+ *  naming VM-5 as HEAD for 3.5 hours after VM-5 had released, while the real
+ *  queue was VM-2 -> VM-8 -> VM-4. Nothing on the page distinguished it from
+ *  live. This is the same lesson mergeDashboardRevision records from
+ *  2026-07-31, applied to the second poller.
+ *
+ *  A previous `readAt` of null (no successful read has EVER happened) stays
+ *  null and is not coerced to a timestamp — "never read" and "read a moment
+ *  ago" must stay distinguishable, the same reason mergeDashboardRevision
+ *  refuses to push a null `behind` through Number().
+ *
+ *  Success is the absence of `error`. Pure; no I/O. */
+function mergeQueuePoll({ prev, entries, readAt, error } = {}) {
+  const base = (prev && typeof prev === 'object') ? prev : {};
+  const str = (v) => ((typeof v === 'string' && v) ? v : null);
+  const prevEntries = Array.isArray(base.entries) ? base.entries : [];
+  const prevReadAt = str(base.readAt);
+  const prevFailures = (typeof base.consecutiveFailures === 'number'
+    && Number.isFinite(base.consecutiveFailures) && base.consecutiveFailures >= 0)
+    ? base.consecutiveFailures : 0;
+  const err = str(error);
+  if (err) {
+    return {
+      entries: prevEntries,
+      readAt: prevReadAt,
+      error: err,
+      consecutiveFailures: prevFailures + 1,
+    };
+  }
+  return {
+    entries: Array.isArray(entries) ? entries : [],
+    readAt: str(readAt) || prevReadAt,
+    error: null,
+    consecutiveFailures: 0,
+  };
+}
+
+/** What does the current queue memo mean for the operator?
+ *
+ *  Levels:
+ *    'fresh'    — the last read succeeded. Render exactly as before; every
+ *                 control stays live.
+ *    'degraded' — erroring, but under QUEUE_STALE_AFTER_FAILURES consecutive
+ *                 failures. A blip. Noted quietly, controls stay live — a
+ *                 single 20s-timeout hiccup that the next tick clears must not
+ *                 cry wolf or lock the operator out of their own queue.
+ *    'stale'    — erroring at or past the threshold. The mirror is not to be
+ *                 trusted and writes computed against it are blocked.
+ *    'unknown'  — erroring and NO read has ever succeeded (the boot window with
+ *                 broken credentials). Worth saying out loud: an empty-looking
+ *                 queue here means "we cannot see the queue", not "go".
+ *
+ *  AGE IS DELIBERATELY NOT AN INPUT. A genuinely quiet queue is not a broken
+ *  one, so escalation keys on consecutive read FAILURES only; age is carried by
+ *  projectQueueFreshness purely to phrase the message ("last read 3h 12m ago").
+ *  An hours-old `readAt` with no error is 'fresh' and must stay that way. Taking
+ *  a clock here would imply otherwise, so the signature omits one — the same
+ *  take-only-what-you-use shape as classifyDashboardStaleness.
+ *
+ *  Pure; no I/O. */
+function classifyQueueFreshness({ readAt, error, consecutiveFailures } = {}) {
+  if (!(typeof error === 'string' && error)) return 'fresh';
+  if (!(typeof readAt === 'string' && readAt)) return 'unknown';
+  const failures = (typeof consecutiveFailures === 'number' && Number.isFinite(consecutiveFailures))
+    ? consecutiveFailures : 0;
+  return failures >= QUEUE_STALE_AFTER_FAILURES ? 'stale' : 'degraded';
+}
+
+/** The `/data` view of the queue memo, with the freshness VERDICT resolved
+ *  server-side.
+ *
+ *  The panel is then a pure renderer. Two consumers re-deriving "is this stale"
+ *  from a raw timestamp would drift, and `public/index.html` is an inline
+ *  browser script with no module boundary — any decision left in it could only
+ *  ever be source-scan tested, which is how it ships bugs green. Same split, and
+ *  same reason, as projectDashboardRevision.
+ *
+ *  `now` is injected (epoch ms) rather than read from the clock so the
+ *  projection stays pure and its tests deterministic. `ageSec` is null when no
+ *  successful read has happened or no clock was supplied.
+ *
+ *  Pure; no I/O. */
+function projectQueueFreshness(memo = {}, now = null) {
+  const at = (typeof memo.readAt === 'string' && memo.readAt) ? Date.parse(memo.readAt) : NaN;
+  const clock = (typeof now === 'number' && Number.isFinite(now)) ? now : null;
+  const ageSec = (Number.isFinite(at) && clock !== null)
+    ? Math.max(0, Math.floor((clock - at) / 1000))
+    : null;
+  return { ...memo, level: classifyQueueFreshness(memo), ageSec };
+}
+
+/** The operator-facing reason a queue WRITE must be refused, or null when writes
+ *  are allowed.
+ *
+ *  A write computed against a mirror known to be frozen is never the right
+ *  action, and the silent-no-op outcome is worse than a refusal: a Release
+ *  fires at a uuid that no longer holds the head, reports "released head
+ *  bb65addf", changes nothing, and leaves the real head held. A reorder is
+ *  worse still — computeReorderTargets validates the posted order against the
+ *  very mirror that is wrong, so a doomed reorder looks perfectly valid.
+ *
+ *  The verbatim git error is interpolated rather than summarised to "poll
+ *  failed". On 2026-08-14 the entire recovery was legible from one line —
+ *  `could not read Username for 'https://github.com'` — and truncating it would
+ *  have cost the same 3.5 hours.
+ *
+ *  Lives here rather than in server.js so the refusal COPY is directly
+ *  assertable: server.js has top-level side effects on require, so a message
+ *  built there could only ever be source-scan tested. Pure; no I/O. */
+function queueWriteBlockReason(memo = {}) {
+  const level = classifyQueueFreshness(memo);
+  if (level !== 'stale' && level !== 'unknown') return null;
+  const why = (typeof memo.error === 'string' && memo.error) ? ` (${memo.error})` : '';
+  return level === 'unknown'
+    ? `commit queue has never been read successfully${why} — cannot act on an unknown queue`
+    : `commit queue read is failing${why} — the displayed order cannot be trusted; fix the read before changing the queue`;
+}
+
 module.exports = {
   decideAutoReleaseGoneHead,
   computeReorderTargets,
   nudgeQueueOrder,
   reconcileQueueDraft,
+  mergeQueuePoll,
+  classifyQueueFreshness,
+  projectQueueFreshness,
+  queueWriteBlockReason,
+  QUEUE_STALE_AFTER_FAILURES,
 };

package/npm/fleet-revision.js

@@ -0,0 +1,104 @@
+'use strict';
+// Pure helpers for the fleet dashboard's DEPLOYED-REVISION staleness signal
+// (scripts/operator/fleet-dashboard/server.js requires this; unit tests in
+// npm/fleet-revision.test.js).
+//
+// The dashboard header has always shown the branch name, which says nothing
+// about WHICH COMMIT of that branch is serving. On 2026-07-31 the operator
+// host's /opt/codeyam-editor sat 104 commits behind origin/editor-improvements-66,
+// so the deployed dashboard predated its own memory fix and was
+// indistinguishable from one at tip — the third recurrence of a landed fix
+// surviving because the served checkout was behind (the June VM-5 slug bug was
+// the same shape).
+//
+// server.js owns the I/O — the bounded `git fetch` / `rev-parse` / `rev-list`
+// children and the slow-cycle memo. The two rules that actually matter are here
+// and are pure: how a failed check merges over the last good one, and what
+// verdict a given count means. Both were previously inline in an async IIFE
+// that no test could reach.
+
+/** Merge one revision-check result over the previous memo.
+ *
+ *  THE RULE: a failed check RETAINS the previous `behind` and records `error` —
+ *  it never reports zero. This is what makes the staleness chip sticky. A
+ *  broken `git fetch` that reset the count to 0 would present a stale dashboard
+ *  as current, which is precisely the failure this whole signal exists to catch;
+ *  degrading to "last known count, plus a note that the check is failing" is
+ *  the honest answer.
+ *
+ *  A `behind` that is absent, negative, or unparseable counts as no reading and
+ *  falls back to the previous value the same way. `sha` and `branch` likewise
+ *  retain their last known values rather than blanking the header on a hiccup.
+ *
+ *  A previous `behind` of null (never successfully counted) stays null — it is
+ *  deliberately NOT coerced through Number(), because `Number(null) === 0` is
+ *  the exact coercion that made "no reading" and "zero" indistinguishable in
+ *  readCgroupMemory.
+ *
+ *  Pure; no I/O. */
+function mergeDashboardRevision({ prev, sha, branch, behind, checkedAt, error } = {}) {
+  const base = (prev && typeof prev === 'object') ? prev : {};
+  const str = (next, fallback) => ((typeof next === 'string' && next) ? next : (typeof fallback === 'string' && fallback ? fallback : null));
+  // Strictly a number: a string or null is NOT coerced, so a caller cannot
+  // accidentally turn "no reading" into 0 the way Number(null) would.
+  const count = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null);
+  const counted = count(behind);
+  return {
+    sha: str(sha, base.sha),
+    branch: str(branch, base.branch),
+    behind: counted === null ? count(base.behind) : counted,
+    checkedAt: str(checkedAt, base.checkedAt),
+    error: str(error, null),
+  };
+}
+
+/** What does the current revision memo mean for the operator?
+ *
+ *  Split out from the header chip so the verdict is a readable table rather
+ *  than branches buried in string concatenation — the same reason
+ *  operatorAuthRecovery was split out of operatorAuthBannerHtml, and the same
+ *  reason resolveCgroupMemoryDir was split out of readCgroupMemory: logic that
+ *  can only be reached through a browser inline script or a real cgroup
+ *  filesystem is logic that ships its bugs green.
+ *
+ *  Levels:
+ *    'stale'     — behind > 0. Landed fixes are not live; the chip warns.
+ *    'current'   — behind === 0. Clears the chip, and clears it even when the
+ *                  latest check errored: the count reaching zero is the ONLY
+ *                  thing that clears the warning, and once it has, a later
+ *                  failed fetch has no stale count to keep showing.
+ *    'unknown'   — no count has ever succeeded AND the check is failing. Worth
+ *                  saying out loud rather than rendering the reassuring nothing
+ *                  that an at-tip dashboard renders.
+ *    'unchecked' — no count yet and nothing has failed (the boot window before
+ *                  the first slow-cycle refresh). Renders nothing.
+ *
+ *  Pure; no I/O. */
+function classifyDashboardStaleness({ behind, error } = {}) {
+  const counted = (typeof behind === 'number' && Number.isFinite(behind) && behind >= 0) ? behind : null;
+  if (counted === null) return error ? 'unknown' : 'unchecked';
+  return counted > 0 ? 'stale' : 'current';
+}
+
+/** The `/data` view of the revision memo, with the staleness VERDICT resolved
+ *  server-side.
+ *
+ *  The chip is then a pure renderer: `public/index.html` is an inline browser
+ *  script with no module boundary, so any decision left in it could only ever
+ *  be source-scan tested — assertions on text rather than on behavior.
+ *
+ *  Lives here rather than in `server.js` for the same reason
+ *  `classifyDashboardStaleness` does: `server.js` has top-level side effects on
+ *  require (createServer/listen/setInterval), so nothing there can be executed
+ *  by a test and a projection defined inside it ships its bugs green.
+ *
+ *  Pure; no I/O. */
+function projectDashboardRevision(memo = {}) {
+  return { ...memo, level: classifyDashboardStaleness(memo) };
+}
+
+module.exports = {
+  mergeDashboardRevision,
+  classifyDashboardStaleness,
+  projectDashboardRevision,
+};

package/npm/fleet-running-plan.js

@@ -1,8 +1,15 @@
 'use strict';
 
 // Resolve the running-plan fields a fleet card shows — feature, step, mode,
-// selectedPlan, holderSessionId — from the two independent per-VM probes plus
-// the last-known-good state.
+// selectedPlan, holderSessionId, startedAt, featureStartedAt — from the two
+// independent per-VM probes plus the last-known-good state.
+//
+// The two timestamps ride here because they share the restart problem below and
+// nothing else resolves them: `startedAt` / `featureStartedAt` drive the card's
+// "on step" / "on feature" tenure badges AND the server-side slow/stuck/needs-you
+// verdict (fleet-stuck-status.js deriveAttention keys on `startedAt`). A null
+// degrades that verdict to level:'ok', needsYou:false — so a VM whose editor
+// restarted was silently exempt from the very detection it most needed.
 //
 // Why this exists: the card used to hang these fields off `/api/session-info`
 // alone (spread as `...info` in server.js). But a VM whose editor server
@@ -35,10 +42,11 @@
 // @param {?Object} params.info  Parsed `/api/session-info` body (carries
 //   `reachable`), or null on a failed/timed-out probe.
 // @param {?Object} params.prev  The previous `state.vms[n]` (carries the
-//   last-known feature/step/mode/selectedPlan/holderSessionId). null/undefined
-//   on the first poll.
+//   last-known feature/step/mode/selectedPlan/holderSessionId/startedAt/
+//   featureStartedAt). null/undefined on the first poll.
 // @returns {{feature: ?string, step: ?number, mode: ?string,
-//   selectedPlan: ?string, holderSessionId: ?string}}
+//   selectedPlan: ?string, holderSessionId: ?string, startedAt: ?string,
+//   featureStartedAt: ?string}}
 function resolveRunningPlan({ step, info, prev } = {}) {
   const s = step || {};
   const i = info || {};
@@ -56,6 +64,10 @@ function resolveRunningPlan({ step, info, prev } = {}) {
       mode: p.mode || null,
       selectedPlan: p.selectedPlan || null,
       holderSessionId: p.holderSessionId || null,
+      // Carried verbatim like the rest: a single timed-out cycle must not blink
+      // the tenure badges off and reset the stuck timer back to zero.
+      startedAt: p.startedAt || null,
+      featureStartedAt: p.featureStartedAt || null,
     };
   }
 
@@ -67,18 +79,36 @@ function resolveRunningPlan({ step, info, prev } = {}) {
   const samePlan = freshSelectedPlan != null && freshSelectedPlan === (p.selectedPlan || null);
   const carry = samePlan ? p : {};
 
+  // The module's precedence rule, in ONE place: /api/step (session-independent)
+  // > /api/session-info > same-plan carry. Four fields resolve exactly this way,
+  // so hoisting it keeps a future precedence change from being applied to some
+  // of them and not others. The two fields that deviate stay longhand below, and
+  // their being longhand is the signal that they deviate: `step` needs an
+  // explicit null check (0 is a real step number, and `||` would swallow it),
+  // and holderSessionId deliberately skips session-info, which never carries it.
+  const pick = (key) => s[key] || i[key] || carry[key] || null;
+
   const stepNum =
     s.step != null ? s.step : i.step != null ? i.step : carry.step != null ? carry.step : null;
 
   return {
-    feature: s.feature || i.feature || carry.feature || null,
+    feature: pick("feature"),
     step: stepNum,
-    mode: s.mode || i.mode || carry.mode || null,
+    mode: pick("mode"),
     selectedPlan: freshSelectedPlan || carry.selectedPlan || null,
     // session-info never carries holderSessionId — it comes from /api/step
     // (editor-step.json) or the same-plan carry. This is what lets a claim map
     // to the executing VM after an editor restart drops the live sessionId.
     holderSessionId: s.holderSessionId || carry.holderSessionId || null,
+    // Workflow tenure timers. /api/step wins because EditorStepState serializes
+    // `started_at` (non-optional, camelCase) straight out of editor-step.json —
+    // session-independent, so it survives the editor restart that makes
+    // session-info report hasSession:false and omit them entirely. The same-plan
+    // `carry` applies unchanged: a completed plan's startedAt must never be
+    // pinned onto the next plan, or the badges would show a tenure the new plan
+    // has not accrued.
+    startedAt: pick("startedAt"),
+    featureStartedAt: pick("featureStartedAt"),
   };
 }
 

package/npm/fleet-vm-access.js

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