@codeyam-editor/codeyam-editor 0.1.7 → 0.1.9

package/npm/fleet-revision.js

@@ -97,8 +97,116 @@ function projectDashboardRevision(memo = {}) {
   return { ...memo, level: classifyDashboardStaleness(memo) };
 }
 
+/** Is the CLI BINARY the dashboard shells out to as current as the checkout?
+ *
+ *  The sibling question to `classifyDashboardStaleness`, and until 2026-08-21
+ *  nobody was asking it. The operator host's checkout self-updates hourly while
+ *  the `codeyam-editor` binary beside it never did, so the control plane drifted
+ *  a little further behind every hour until a CLI-visible schema change broke it
+ *  outright: an `editor-shipped` glossarySkip reason merged at 05:12 could not be
+ *  parsed by a binary built 2026-07-19, and every CLI invocation the dashboard
+ *  made died at config load.
+ *
+ *  Why this needs its own signal rather than riding on `behind`: NOTHING that
+ *  normally means "down" was down. `dashboard-bes` stayed HEALTHY, `/healthz`
+ *  answered in 0.8 ms, all 14 VMs read reachable, and the checkout itself was at
+ *  tip — so a commits-behind chip reading 0 was correct AND useless. Two
+ *  artifacts deploy on this host and only one of them was ever measured.
+ *
+ *  Compares git SHAs, not versions: the published artifact stamps the source
+ *  commit it was built from (`org.opencontainers.image.revision`), and a semver
+ *  moves far more slowly than the schema does — `0.1.7` was both the working and
+ *  the broken binary.
+ *
+ *  Levels, deliberately the same four words `classifyDashboardStaleness` uses so
+ *  the two chips read as one family:
+ *    'stale'     — both SHAs known and different. The CLI predates the checkout;
+ *                  a schema change away from empty panels.
+ *    'current'   — both known and equal.
+ *    'unknown'   — cannot compare AND something failed. Includes the incident's
+ *                  own worst case: a binary too stale to answer what it is fails
+ *                  the very read that would have proven it stale, so "I could not
+ *                  tell" must never round down to 'current'.
+ *    'unchecked' — cannot compare and nothing failed (the boot window before the
+ *                  first slow-cycle read). Renders nothing.
+ *
+ *  Pure; no I/O. */
+function classifyBinaryStaleness({ installed, tip, error } = {}) {
+  const sha = (v) => ((typeof v === 'string' && v.trim()) ? v.trim() : null);
+  const a = sha(installed);
+  const b = sha(tip);
+  if (a === null || b === null) return error ? 'unknown' : 'unchecked';
+  return a === b ? 'current' : 'stale';
+}
+
+/** The `/data` view of the binary memo, with the verdict resolved server-side.
+ *
+ *  Same split, for the same reason, as `projectDashboardRevision`: `server.js`
+ *  has top-level side effects on require, so a projection defined there can
+ *  never be executed by a test and ships its bugs green.
+ *
+ *  Pure; no I/O. */
+function projectBinaryRevision(memo = {}) {
+  return { ...memo, level: classifyBinaryStaleness(memo) };
+}
+
+/** Why did the CLI shell-out fail — and is it the nameable one?
+ *
+ *  The 2026-08-21 outage surfaced ONLY as a truncated `queueFreshness.error`
+ *  reading `" Fix the file and re-run."` — two lines of tail from a multi-line
+ *  diagnostic, with the sentence naming the cause among the lines that got cut.
+ *  An operator looking at empty Queue and Plans panels had to infer that the CLI
+ *  was broken at all, and nothing on the page said so.
+ *
+ *  So classify the FULL stderr before it is tailed. Two phrasings both mean
+ *  "this binary cannot read this checkout's config", and BOTH must match:
+ *  the current wording, and the pre-2026-08-19 `Fix the file and re-run` — which
+ *  is not legacy trivia but the single most likely text to see here, because the
+ *  binary emitting it is by definition an old one.
+ *
+ *  Levels:
+ *    'ok'      — no error.
+ *    'config'  — the binary cannot read `.codeyam/editor.json`. Almost always a
+ *                CLI older than the checkout; the file is usually correct and
+ *                editing it is the wrong move, which is why the recovery text
+ *                says so out loud.
+ *    'failing' — the CLI failed for some other reason (git credentials, a
+ *                timeout). Still worth showing, still not this condition.
+ *
+ *  Pure; no I/O. */
+function classifyCliFailure(text) {
+  const s = (typeof text === 'string') ? text : '';
+  if (!s.trim()) return 'ok';
+  if (/cannot read [^\n]*editor\.json/i.test(s) || /Fix the file and re-run/i.test(s)) return 'config';
+  return 'failing';
+}
+
+/** The `/data` view of CLI health, with the verdict and its recovery resolved
+ *  server-side — so the panel renders a named condition instead of leaving the
+ *  operator to infer one from a blank list.
+ *
+ *  `recovery` is only populated for 'config', where the right action is
+ *  genuinely non-obvious and the intuitive one (edit the file) is wrong.
+ *
+ *  Pure; no I/O. */
+function projectCliHealth({ error } = {}) {
+  const level = classifyCliFailure(error);
+  return {
+    level,
+    broken: level !== 'ok',
+    error: (typeof error === 'string' && error.trim()) ? error.trim() : null,
+    recovery: level === 'config'
+      ? 'The codeyam-editor binary is older than the checkout it is reading — do NOT edit .codeyam/editor.json. Refresh the binary: scripts/operator/refresh-operator-repo.sh'
+      : null,
+  };
+}
+
 module.exports = {
   mergeDashboardRevision,
   classifyDashboardStaleness,
   projectDashboardRevision,
+  classifyBinaryStaleness,
+  projectBinaryRevision,
+  classifyCliFailure,
+  projectCliHealth,
 };

package/npm/fleet-run-setup.js

@@ -0,0 +1,66 @@
+'use strict';
+// Pure builder for the fleet dashboard's in-container `npm run setup` snippet
+// (scripts/operator/fleet-dashboard/server.js requires this). String
+// construction only — no I/O, no child processes — so the snippet's CONTENT is
+// unit-testable in isolation (npm/fleet-run-setup.test.js), exactly like
+// fleet-env.js. server.js itself has no unit-test harness, which is why this
+// lives here rather than inline in actionRunSetup.
+//
+// Named for the run-setup ACTION, not "setup" generally: npm/fleet-setup-steps.js
+// already exists and is a different concern (it is bound as `fsetup` in
+// server.js, so a `fleet-setup.js` here collided on both the filename and the
+// import identifier).
+
+// Seconds before a prompting or hanging setup is killed. Matches the
+// bootstrap's SETUP_TIMEOUT default so both paths time-box identically; the
+// dashboard job budget (11 min) is deliberately larger, to cover this plus ssh.
+const SETUP_TIMEOUT_SECS = 600;
+
+// How many trailing lines of setup's own output ride on the CY_DEGRADED line.
+// The marker is parsed line-by-line by the job-output reader, so these are
+// flattened onto one line — keep it small enough to stay readable on a card.
+const FAILURE_TAIL_LINES = 3;
+
+/**
+ * Build the bash snippet that runs the project's `npm run setup` inside VM-n's
+ * container and reports what actually broke.
+ *
+ * The failure line carries the setup command's OWN trailing output. It used to
+ * hardcode "set env (e.g. DATABASE_URL) via Env, then retry Run setup" — a
+ * guess, and on VM-11 (2026-08-26) a wrong one: DATABASE_URL was present in
+ * /workspace/.env the whole time and the real failure was that Postgres was not
+ * installed. The failing script had already printed a precise, actionable
+ * message and the wrapper talked over it, sending the operator to configure env
+ * that was already correct. Report what broke; do not theorize about it.
+ *
+ * Exits 0 even on failure, emitting a `CY_DEGRADED` marker line instead — so
+ * the cause persists on the VM card rather than vanishing as a transient error.
+ *
+ * @param {number|string} n VM number, used only to name the VM in the message.
+ * @returns {string} bash snippet suitable for `inContainer(n, …)`.
+ */
+function buildRunSetupScript(n) {
+  return [
+    'cd /workspace || { echo "no /workspace in container"; exit 1; }',
+    `setup="$(node -p "(require('./package.json').scripts||{}).setup||''" 2>/dev/null || true)"`,
+    'if [ -z "$setup" ]; then echo "no \'setup\' script in package.json — nothing to run"; exit 0; fi',
+    `echo "running 'npm run setup' (script: $setup; non-interactive, ${SETUP_TIMEOUT_SECS}s timeout)"`,
+    // tee so the full output still streams into the job log, while the tail is
+    // retained for the CY_DEGRADED line. ${PIPESTATUS[0]} is setup's exit code,
+    // not tee's — without it a failing setup would report success.
+    'log="$(mktemp)"',
+    `timeout ${SETUP_TIMEOUT_SECS} npm run setup </dev/null 2>&1 | tee "$log"; rc=\${PIPESTATUS[0]}`,
+    'if [ "$rc" -ne 0 ]; then',
+    `  why="$(grep -v '^[[:space:]]*$' "$log" | tail -n ${FAILURE_TAIL_LINES} | tr '\\n' '|' | sed 's/|$//; s/|/ | /g')"`,
+    `  [ -n "$why" ] || why="(no output — likely killed by the ${SETUP_TIMEOUT_SECS}s timeout)"`,
+    `  echo "CY_DEGRADED 'npm run setup' failed (exit $rc) on VM-${n}, in the container as root: $why"`,
+    'fi',
+    'rm -f "$log"',
+  ].join('\n');
+}
+
+module.exports = {
+  buildRunSetupScript,
+  SETUP_TIMEOUT_SECS,
+  FAILURE_TAIL_LINES,
+};

package/npm/fleet-session-activity.js

@@ -0,0 +1,162 @@
+'use strict';
+// Pure session-activity classification and stickiness for the Fleet Dashboard
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the raw
+// per-poll `hasSession` / `sessionIdleSeconds` the editor's /api/session-info
+// reports, decide what the card renders and what the maintenance gate reads. No
+// I/O — server.js does the polling and threads the state.
+//
+// The problem this fixes (observed live 2026-08-30, VMs 1 and 9): `hasSession`
+// is a bare boolean with no notion of activity age, so a session wedged two days
+// ago is indistinguishable from one someone is actively driving. Both hold a
+// live agent process, so both report `true`, and every refresh was refused with
+// the same `BLOCKED: VM-N has a live session`. The only way through was
+// `--force` — the same flag used to step over genuinely live work — which is how
+// `--force` stops meaning anything. `hasSession` also flapped `false` → `true`
+// between polls minutes apart, so even an operator watching the card could not
+// tell the two apart by eye.
+//
+// Two independent fixes live here, deliberately separate:
+//
+//   debounceHasSession    — stops the flap. A value that alternates between
+//                           adjacent polls is not a usable gate input at any
+//                           age, so this is fixed first and on its own.
+//   classifySessionActivity — adds the age dimension the boolean lacks.
+//
+// Asymmetric by design, mirroring npm/fleet-broker-debounce.js: only the flip to
+// `false` (no session) is debounced. `true` takes effect immediately, because
+// the dangerous error is proceeding over live work — we never delay RAISING the
+// block, only delay clearing it. An unreachable editor (`hasSession` neither
+// true nor false) proves nothing and breaks a pending clear-streak rather than
+// advancing it, the same "absence of evidence is never down" rule
+// fleet-broker-status.js follows.
+//
+// State shape carried across polls: { hasSession, clearStreak, lastConfirmed }.
+//   hasSession    — the debounced value the card and the gate read this poll.
+//   clearStreak   — how many consecutive raw `false` polls we have seen.
+//   lastConfirmed — the last raw boolean we actually proved; held during a
+//                   pending (sub-threshold) clear-streak so the gate keeps
+//                   blocking through a blip.
+
+// ~9s at the dashboard's 3s poll cadence, matching DOWN_DEBOUNCE_THRESHOLD in
+// npm/fleet-broker-debounce.js. Named so retuning is a one-line edit.
+const CLEAR_DEBOUNCE_THRESHOLD = 3;
+
+// A full day of zero on-disk activity. Chosen to sit well clear of the longest
+// legitimate idle a live session has: an agent parked at a confirmation gate
+// overnight is waiting for its operator, not wedged, and forcing past it costs
+// them their place. The observed wedge was two days cold, so this catches it
+// with a wide margin rather than racing it.
+const STALE_SESSION_IDLE_SECONDS = 24 * 60 * 60;
+
+function debounceHasSession(prev, rawHasSession, opts) {
+  const threshold = (opts && opts.threshold) || CLEAR_DEBOUNCE_THRESHOLD;
+  const lastConfirmed = prev ? prev.lastConfirmed : undefined;
+
+  // Confirmed present: a session is live right now. Render immediately, reset
+  // the streak, and remember it as the last confirmed value.
+  if (rawHasSession === true) {
+    return { hasSession: true, clearStreak: 0, lastConfirmed: true };
+  }
+
+  // Neither true nor false — the editor was unreachable or answered no
+  // session-info at all, so we proved nothing. Never let that advance the
+  // clear-streak toward "no session"; hold what we last proved.
+  if (rawHasSession !== false) {
+    return {
+      hasSession: lastConfirmed === true,
+      clearStreak: 0,
+      lastConfirmed,
+    };
+  }
+
+  // Raw `false`: only believed once it persists. Count the streak.
+  const clearStreak = (prev ? prev.clearStreak : 0) + 1;
+  if (clearStreak >= threshold) {
+    return { hasSession: false, clearStreak, lastConfirmed: false };
+  }
+  // Pending (sub-threshold) clear: hold the last confirmed value, so a single
+  // dropped poll cannot open a window for maintenance to step over live work.
+  return {
+    hasSession: lastConfirmed === true,
+    clearStreak,
+    lastConfirmed,
+  };
+}
+
+// Classify a VM's session into the verdict the card renders and the maintenance
+// gate branches on:
+//
+//   'none'    — no session at all. Maintenance proceeds; nothing to step over.
+//   'active'  — a session with recent activity. Blocks exactly as it does
+//               today; only `--force` steps over it.
+//   'stale'   — a session idle beyond the threshold. Still blocks, but is
+//               eligible for the narrower stale-session override.
+//   'unknown' — a session whose age could not be determined, because the editor
+//               is too old to report `sessionIdleSeconds` or could read no
+//               evidence. Treated as POSSIBLY LIVE and blocks like 'active'.
+//
+// That last mapping is the load-bearing one. An unknown age must never resolve
+// toward 'stale': the override exists to skip work nobody is doing, and handing
+// it out on absent evidence would step over live sessions on exactly the VMs
+// whose reporting is broken. `classify_vm`'s `reachable` tri-state in
+// scripts/operator/refresh-client-vm-editor.sh is the cautionary precedent —
+// collapsing its unknown to a definite verdict once refused all 13 VMs at once
+// on evidence that had never been gathered.
+function classifySessionActivity(input) {
+  const hasSession = !!(input && input.hasSession);
+  if (!hasSession) return 'none';
+
+  const idleSeconds = input.idleSeconds;
+  if (typeof idleSeconds !== 'number' || !Number.isFinite(idleSeconds)) {
+    return 'unknown';
+  }
+
+  const threshold =
+    typeof input.thresholdSeconds === 'number' && Number.isFinite(input.thresholdSeconds)
+      ? input.thresholdSeconds
+      : STALE_SESSION_IDLE_SECONDS;
+
+  return idleSeconds >= threshold ? 'stale' : 'active';
+}
+
+// Render an idle age as the short human string the card and the refusal message
+// both show ("2d", "5h", "3m", "12s"). Returns 'unknown' when there is no age,
+// so a caller never has to decide how to word an absent value — and so the
+// operator sees the word rather than a blank that reads as zero.
+function formatIdleAge(idleSeconds) {
+  if (typeof idleSeconds !== 'number' || !Number.isFinite(idleSeconds) || idleSeconds < 0) {
+    return 'unknown';
+  }
+  const s = Math.floor(idleSeconds);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+
+// Does this VM read as WEDGED rather than merely busy? A card showing
+// `status: building` with no feature named and the workflow still at step 1 is
+// describing a session that never got started, and when its last on-disk
+// activity is also days old there is nothing left that "busy" explains. This is
+// the combination VMs 1 and 9 presented, and the card rendered it as work in
+// progress.
+//
+// Deliberately narrower than `classifySessionActivity(...) === 'stale'`: a
+// long-running step that is genuinely mid-feature is stale-but-working, and
+// labelling it wedged would train operators to ignore the label.
+function isWedgedShape(input) {
+  if (!input) return false;
+  if (classifySessionActivity(input) !== 'stale') return false;
+  if (input.status !== 'building') return false;
+  if (input.feature) return false;
+  return input.step === 1 || input.step === undefined || input.step === null;
+}
+
+module.exports = {
+  debounceHasSession,
+  classifySessionActivity,
+  formatIdleAge,
+  isWedgedShape,
+  CLEAR_DEBOUNCE_THRESHOLD,
+  STALE_SESSION_IDLE_SECONDS,
+};

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,

package/npm/fleet-vm-readiness.js

@@ -71,6 +71,12 @@
 //   'cli-missing'  — the editor is up but the build-agent CLI isn't installed
 //                    (`providerAuth.cliInstalled === false`): a provisioning
 //                    fault, not a usable VM.
+//   'cli-broken'   — the CLI IS installed but will not execute
+//                    (`providerAuth.cliRunnable === false`): a provisioning
+//                    fault whose remedy is repair/reinstall, not a fresh
+//                    install and not re-authentication. Distinct from
+//                    'cli-missing' because sending an operator to "install it"
+//                    when it is already installed wastes the incident.
 //   'auth-unsettled' — the auth probe is wedged at `unknown` (timing out — the
 //                    exact VM5 auth shape): we can't even tell if login is
 //                    needed. A provisioning fault distinct from a clean
@@ -89,6 +95,7 @@ const READINESS_STATES = [
   'broker-down',
   'ws-dead',
   'cli-missing',
+  'cli-broken',
   'auth-unsettled',
   'needs-login',
   'ready',
@@ -100,23 +107,41 @@ const fpub = require('./fleet-public-url');
 
 // Classify the build-agent usability axis from the editor's own `providerAuth`
 // subtree (vm: Readiness Verifies Real Usability). control-api emits the SAME
-// `providerAuth` (with `cliInstalled` + settled `state`) on BOTH /api/config and
-// /api/session-info via build_provider_auth_json, so the dashboard reads it
-// straight off the gathered VM record — no re-derivation. Returns one verdict:
+// `providerAuth` (with `cliInstalled` + `cliRunnable` + settled `state`) on BOTH
+// /api/config and /api/session-info via build_provider_auth_json, so the
+// dashboard reads it straight off the gathered VM record — no re-derivation.
+// Returns one verdict:
 //   'cli-missing'    — `cliInstalled === false`: a provisioning fault.
-//   'auth-unsettled' — CLI installed but `state === 'unknown'` (probe wedged /
-//                      timing out — the VM5 shape): a provisioning fault.
-//   'needs-login'    — CLI installed, `state === 'needs-login'`: a LEGITIMATE,
+//   'cli-broken'     — CLI installed but `cliRunnable === false`: it resolves
+//                      and will not execute. A provisioning fault.
+//   'auth-unsettled' — CLI installed and runnable (or unprobed) but
+//                      `state === 'unknown'` (probe wedged / timing out — the
+//                      VM5 shape): a provisioning fault.
+//   'needs-login'    — CLI usable, `state === 'needs-login'`: a LEGITIMATE,
 //                      actionable state, not a fault.
-//   'ready'          — CLI installed, `state === 'authenticated'`: usable.
+//   'ready'          — CLI usable, `state === 'authenticated'`: usable.
 //   'unknown'        — providerAuth absent (older editor / probe never landed),
 //                      or any other shape: absence of evidence, never a fault.
-// Only an EXPLICIT `cliInstalled === false` / `state === 'unknown'` is a fault;
-// missing fields stay 'unknown' so an older editor never reads as broken.
+// Only an EXPLICIT `cliInstalled === false` / `cliRunnable === false` /
+// `state === 'unknown'` is a fault; missing fields stay 'unknown' so an older
+// editor never reads as broken.
+//
+// The `cli-broken` check sits BEFORE the state checks deliberately, and that
+// ordering IS the fix. A CLI that will not execute cannot have authenticated,
+// so `state: 'authenticated'` alongside `cliRunnable: false` is not a
+// contradiction to be resolved in the state's favour — it is precisely the
+// false green observed on VM-2 and VM-7 through the whole 2026-08-19/20 npm
+// publish race, where the card read `cliInstalled: true, state: "authenticated"`
+// while both boxes were unusable and the breakage was found only by ssh.
+//
+// `cliRunnable` is deliberately NOT required to be `true` to proceed: an older
+// editor server omits it entirely (`undefined`), and treating that as a fault
+// would mark every not-yet-upgraded VM in the fleet broken.
 function classifyAgentUsability(providerAuth) {
   if (!providerAuth || typeof providerAuth !== 'object') return 'unknown';
   if (providerAuth.cliInstalled === false) return 'cli-missing';
   if (providerAuth.cliInstalled !== true) return 'unknown';
+  if (providerAuth.cliRunnable === false) return 'cli-broken';
   if (providerAuth.state === 'unknown') return 'auth-unsettled';
   if (providerAuth.state === 'needs-login') return 'needs-login';
   if (providerAuth.state === 'authenticated') return 'ready';
@@ -126,8 +151,13 @@ function classifyAgentUsability(providerAuth) {
 // Map the agent-usability verdict to the tri-state the rostering gate
 // (fleet-cleanup's reapVerdict) consumes, mirroring `projectWired`'s
 // true|false|null contract so a flaky probe can never strand a healthy VM:
-//   false — a PROVISIONING FAULT ('cli-missing' / 'auth-unsettled'): the box is
-//           not usable, so don't roster it as healthy (the VM5 false-green).
+//   false — a PROVISIONING FAULT ('cli-missing' / 'cli-broken' /
+//           'auth-unsettled'): the box is not usable, so don't roster it as
+//           healthy (the VM5 false-green). 'cli-broken' joins the fault set
+//           because a CLI that will not execute makes the VM exactly as
+//           unusable as one that was never installed — the two differ only in
+//           the remedy an operator should reach for, not in whether the box can
+//           do work.
 //   true  — usable enough to roster: 'ready', or a legitimate 'needs-login'
 //           (the user must auth, but that's an expected state, not a
 //           half-provisioned box that should be held back).
@@ -135,7 +165,13 @@ function classifyAgentUsability(providerAuth) {
 //           evidence must NEVER block rostering, exactly like reapVerdict's null
 //           tolerance for projectWired.
 function agentRosterReady(verdict) {
-  if (verdict === 'cli-missing' || verdict === 'auth-unsettled') return false;
+  if (
+    verdict === 'cli-missing' ||
+    verdict === 'cli-broken' ||
+    verdict === 'auth-unsettled'
+  ) {
+    return false;
+  }
   if (verdict === 'ready' || verdict === 'needs-login') return true;
   return null;
 }
@@ -206,12 +242,17 @@ function deriveVmReadiness(v, ctx) {
     if (v.publicWsHealth === 'unwired' && !(bh && bh.editor === 'healthy')) return 'ws-dead';
   }
   // 6. Agent usability: the box is up and the WS path carries frames, but the
-  //    build agent itself may not be usable — CLI not installed, or the auth
-  //    probe wedged at 'unknown'. A legitimate 'needs-login' surfaces as its own
-  //    actionable state (Authenticate), distinct from a provisioning fault.
-  //    Absence of providerAuth (older editor / unprobed) falls through to ready.
+  //    build agent itself may not be usable — CLI not installed, CLI installed
+  //    but not executable, or the auth probe wedged at 'unknown'. A legitimate
+  //    'needs-login' surfaces as its own actionable state (Authenticate),
+  //    distinct from a provisioning fault. Absence of providerAuth (older
+  //    editor / unprobed) falls through to ready.
   const usability = classifyAgentUsability(v.providerAuth);
   if (usability === 'cli-missing') return 'cli-missing';
+  // Surfaced as its own readiness state rather than folded into 'cli-missing':
+  // the card's whole job here is to send an operator to the right remedy, and
+  // "reinstall the broken CLI" is not "install the missing one".
+  if (usability === 'cli-broken') return 'cli-broken';
   if (usability === 'auth-unsettled') return 'auth-unsettled';
   if (usability === 'needs-login') return 'needs-login';
   // 6b. Preview-host IAP gap: the editor surface grants access (the URL routes