@codeyam-editor/codeyam-editor 0.1.8 → 0.1.10

package/npm/fleet-reconcile.js

@@ -59,16 +59,33 @@ function strandedAdoptDecision({ stranded, streaks, threshold } = {}) {
   return { streaks: next, ready };
 }
 
+// Each entry maps a degraded-reason shape to the live witness that disconfirms
+// it. Extend the table as new degraded reasons gain a corresponding signal.
+//
+// TWO SHAPES PER CLASS, ON PURPOSE. The dashboard writes its auth reason under
+// the structured `claude-auth-not-seeded:` prefix (server.js, and the prefix
+// two other call sites key on), but the original free-text pattern needs a
+// SPACE — `/claude auth/` never matches the hyphenated prefix. Such reasons
+// cleared only because the canned message happens to contain the word "login";
+// phrased any other way they were retained forever, which is the reported bug
+// surviving in the one form the reconcile was aimed at. Matching the prefix
+// only would be the opposite mistake: reasons like `claude auth copy failed on
+// VM-2 (…)` are already recorded in live snapshots and carry no prefix at all,
+// so both shapes have to match.
+const REASON_WITNESSES = [
+  { match: /^\s*claude-auth-not-seeded\b/i, witness: 'authed' },
+  { match: /claude auth|claude\.json|login/i, witness: 'authed' },
+  { match: /container|never came up|provisioning failed/i, witness: 'reachableServing' },
+];
+
 // Map a single degraded reason to the live health signal that resolves it.
 // Returns true only when that signal now passes; a reason with no mapped signal
 // returns false (retained — a genuine config problem, never a false-green).
-// Start with the two observed classes (improve41); extend the table as new
-// degraded reasons gain a corresponding live signal.
 function reasonClearedByHealth(reason, { reachableServing, authed }) {
   const r = String(reason || '');
-  if (/claude auth|claude\.json|login/i.test(r)) return authed;
-  if (/container|never came up|provisioning failed/i.test(r)) return reachableServing;
-  return false;
+  const entry = REASON_WITNESSES.find((e) => e.match.test(r));
+  if (!entry) return false;
+  return entry.witness === 'authed' ? !!authed : !!reachableServing;
 }
 
 // Given a terminal add-job badge and the VM's live health, return the corrected
@@ -79,7 +96,14 @@ function reasonClearedByHealth(reason, { reachableServing, authed }) {
 // facts (I/O at the edge) and applies the result; the verdict itself is pure.
 //   job:    { state: 'done'|'error', degraded, degradedReasons }
 //   health: { reachable, editorHttpOk, providerAuthState }
-//   → null | { state, degraded, degradedReasons, transition }
+//   → null | { state, degraded, degradedReasons, retiredReasons, transition }
+//
+// `retiredReasons` names the reasons this verdict just dropped. Without it a
+// retired reason simply vanishes from the card, so an operator who saw amber
+// never learns it resolved — the shell renders these as the same muted
+// "recovered (was: …)" trace the reconciled error badge already leaves. What
+// that trace should SAY is the shell's call; naming what was retired is this
+// module's.
 function reconcileTerminalAddBadge({ job, health } = {}) {
   if (!job || !health) return null;
   const reachableServing = !!(health.reachable && health.editorHttpOk);
@@ -91,7 +115,13 @@ function reconcileTerminalAddBadge({ job, health } = {}) {
   if (job.state === 'error') {
     const reasons = job.degradedReasons || [];
     if (reasons.length === 0 && reachableServing) {
-      return { state: 'done', degraded: false, degradedReasons: [], transition: 'error→done (editor 200)' };
+      return {
+        state: 'done',
+        degraded: false,
+        degradedReasons: [],
+        retiredReasons: [],
+        transition: 'error→done (editor 200)',
+      };
     }
     return null;
   }
@@ -100,15 +130,20 @@ function reconcileTerminalAddBadge({ job, health } = {}) {
   // passes; retain the rest. Drop `degraded` only when no reasons remain.
   if (job.state === 'done' && job.degraded) {
     const reasons = job.degradedReasons || [];
-    const remaining = reasons.filter((reason) => !reasonClearedByHealth(reason, { reachableServing, authed }));
-    if (remaining.length === reasons.length) return null; // nothing cleared → no-op
-    const cleared = reasons.length - remaining.length;
+    const remaining = [];
+    const retired = [];
+    for (const reason of reasons) {
+      const bucket = reasonClearedByHealth(reason, { reachableServing, authed }) ? retired : remaining;
+      bucket.push(reason);
+    }
+    if (retired.length === 0) return null; // nothing cleared → no-op
     return {
       state: 'done',
       degraded: remaining.length > 0,
       degradedReasons: remaining,
+      retiredReasons: retired,
       transition: remaining.length > 0
-        ? `degraded: cleared ${cleared} reason(s), ${remaining.length} remain`
+        ? `degraded: cleared ${retired.length} reason(s), ${remaining.length} remain`
         : 'degraded→clear (health restored)',
     };
   }

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-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