@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/fleet-queue.js

@@ -74,4 +74,61 @@ function computeReorderTargets({ order, current }) {
   return { ok: true, targets };
 }
 
-module.exports = { decideAutoReleaseGoneHead, computeReorderTargets };
+/** Move one uuid within a desired order array.
+ *
+ *  The staged-draft panel shuffles a working uuid order before it is saved.
+ *  `delta > 0` raises priority (moves the entry TOWARD the head / index 0);
+ *  `delta < 0` lowers it (toward the tail). The target index is clamped to the
+ *  array bounds, so a nudge past an end is a no-op and a full-span negative
+ *  delta lands the entry at the very tail — which is exactly how Demote
+ *  (head → back of the line) is expressed: `nudgeQueueOrder(order, head, -(N-1))`.
+ *  Mirrors the editor UI's `useBranchQueueDraft.nudge` (arrayMove(from, from-delta)).
+ *
+ *  `order` is a uuid array; a uuid not present is returned unchanged. Pure — the
+ *  input array is never mutated.
+ */
+function nudgeQueueOrder(order, uuid, delta) {
+  const arr = (order || []).slice();
+  const from = arr.findIndex((u) => u === uuid);
+  if (from < 0 || !delta) return arr;
+  let to = from - delta;              // +delta → toward head; -delta → toward tail
+  if (to < 0) to = 0;
+  if (to > arr.length - 1) to = arr.length - 1;
+  if (to === from) return arr;
+  const [moved] = arr.splice(from, 1);
+  arr.splice(to, 0, moved);
+  return arr;
+}
+
+/** Merge a fresh poll's membership into a staged draft order without discarding
+ *  the operator's in-progress reorder.
+ *
+ *  - uuids still present live keep their DRAFT position (the working order wins);
+ *  - draft uuids that vanished upstream are dropped;
+ *  - live uuids not yet in the draft are appended at the tail so a sibling
+ *    session's newly-enqueued entry doesn't silently disappear.
+ *
+ *  Pure port of the editor UI's `reconcileDraft` order rule (uuid-only, no meta).
+ *  Both arguments are uuid arrays; returns the merged uuid array. Never mutates
+ *  its inputs.
+ */
+function reconcileQueueDraft(draftOrder, liveOrder) {
+  const live = liveOrder || [];
+  const liveSet = new Set(live);
+  const seen = new Set();
+  const out = [];
+  for (const u of draftOrder || []) {
+    if (liveSet.has(u) && !seen.has(u)) { out.push(u); seen.add(u); }
+  }
+  for (const u of live) {
+    if (!seen.has(u)) { out.push(u); seen.add(u); }
+  }
+  return out;
+}
+
+module.exports = {
+  decideAutoReleaseGoneHead,
+  computeReorderTargets,
+  nudgeQueueOrder,
+  reconcileQueueDraft,
+};

package/npm/fleet-reachability-debounce.js

@@ -0,0 +1,69 @@
+'use strict';
+// Pure consecutive-failure debounce for the Fleet Dashboard's per-VM top-level
+// reachability. Mirrors npm/fleet-broker-debounce.js exactly: server.js does the
+// polling and threads the state; this decides the reachability the card renders.
+//
+// The bug this fixes (observed live 2026-07-01, VM6): a healthy VM briefly
+// flashed 'unreachable' and surfaced a reset-client-error even though it was up
+// the whole time. The dashboard polls each VM's editor over a laptop-side
+// SSH/cloudflared forward with NO fast respawner, so a single one-poll hiccup
+// returned reachable:false and the card instantly read 'unreachable' — which
+// then invited the destructive "Reset client" action on a perfectly healthy VM.
+// The single probe is left as-is on the poller side; the right seam for
+// absorbing a one-poll blip is here at the aggregation layer, just like broker.
+//
+// Asymmetric by design: ONLY the flip to 'unreachable' is debounced (it requires
+// `threshold` consecutive failed polls). A reachable poll takes effect
+// immediately — we never DELAY clearing a false alarm, only delay raising one.
+//
+// Three display states the card renders:
+//   'reachable'    — the editor answered this poll.
+//   'reconnecting' — a sub-threshold failure streak (1..N-1), OR the GCP side
+//                    confirms the editor answers over IAP while the local port
+//                    is dark (a laptop tunnel fault, never a dead VM). Calm; the
+//                    watchdog respawns the forward. A one-poll hiccup lives here.
+//   'unreachable'  — N consecutive failures AND no GCP-side confirmation. The
+//                    honest sustained-outage state.
+//
+// State carried across polls: { display, failStreak, lastConfirmed }.
+//   display       — the debounced value the card renders this poll.
+//   failStreak    — how many consecutive raw failed polls we've seen.
+//   lastConfirmed — the last raw 'reachable' we proved (informational; the card
+//                   holds 'reconnecting' during a pending sub-threshold streak).
+
+// ~9s at the dashboard's 3s poll cadence, matching the broker debounce: enough
+// to absorb a transient forward hiccup while still surfacing a real outage
+// quickly. Named so retuning is a one-line edit.
+const UNREACHABLE_DEBOUNCE_THRESHOLD = 3;
+
+function debounceReachability(prev, rawReachable, opts) {
+  const threshold = (opts && opts.threshold) || UNREACHABLE_DEBOUNCE_THRESHOLD;
+  const gcpConfirmedReachable = !!(opts && opts.gcpConfirmedReachable);
+  const lastConfirmed = prev ? prev.lastConfirmed : undefined;
+
+  // Confirmed reachable: the editor answered now. Render immediately, reset the
+  // streak, remember this as the last-confirmed value.
+  if (rawReachable) {
+    return { display: 'reachable', failStreak: 0, lastConfirmed: 'reachable' };
+  }
+
+  // Raw failure: count the streak.
+  const failStreak = (prev ? prev.failStreak : 0) + 1;
+
+  // GCP-side confirmation: the editor answers over IAP while the local port is
+  // dark. That's a laptop tunnel fault, NOT a dead VM — never escalate to
+  // 'unreachable' no matter how long the local forward has been down; the
+  // watchdog respawns the forward. Hold the calm 'reconnecting' state.
+  if (gcpConfirmedReachable) {
+    return { display: 'reconnecting', failStreak, lastConfirmed };
+  }
+
+  // Sub-threshold failure: stay calm ('reconnecting'). Only a SUSTAINED failure
+  // past the threshold escalates to the honest 'unreachable'.
+  if (failStreak >= threshold) {
+    return { display: 'unreachable', failStreak, lastConfirmed };
+  }
+  return { display: 'reconnecting', failStreak, lastConfirmed };
+}
+
+module.exports = { debounceReachability, UNREACHABLE_DEBOUNCE_THRESHOLD };

package/npm/fleet-reachability.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// The three-state reachability contract for the Fleet Dashboard.
+//
+// A VM's reachability has THREE states, not two:
+//   true  — a probe reached the VM's editor
+//   false — a probe RAN and FAILED (a confirmed outage)
+//   null  — no verdict at all (never polled, or held inconclusive)
+//
+// `npm/fleet-auth-health.js::classifyReachability` has always modelled this
+// correctly, deliberately returning `{ reachable: null }` for the inconclusive
+// case. Every consumer between it and the browser then coerced that care away
+// with `!!v.reachable` and `{ n, reachable: false }` placeholders, so the null
+// never survived to anyone who could act on it.
+//
+// On 2026-07-30 that collapse served all 13 rostered VMs as `reachable: false`
+// with NO `reachableSource`, while each card's own `backendHealth` read
+// `healthy` and operator auth read clean — a self-contradicting fleet-wide
+// "outage" that had never been probed. It blocked both sanctioned refresh paths
+// (`refresh-client-vm-editor.sh` exits 1, `fleet-advance-to.sh` classifies
+// SKIP-unreachable) and, in a storm, is the signal that has driven reconcile
+// into hard-rebooting healthy VMs.
+//
+// This module is the single home for that vocabulary so the distinction is
+// stated once and grepped, rather than re-derived inline at each consumer. Pure:
+// no I/O, no clock, no state.
+
+// The `reachableSource` value for a record carrying no reachability verdict.
+// `reachableSource` otherwise names the signal that DECIDED a verdict ('lb' |
+// 'backend' | 'local' | 'iap', from classifyReachability), which is what makes a
+// card self-diagnosing — a `reachable: false` with a missing source is exactly
+// the fingerprint that identified the 2026-07-30 incident as manufactured by the
+// serializer rather than reported by a probe. 'unpolled' extends that same
+// self-diagnosis to the no-verdict case instead of leaving a silent gap.
+const REACHABILITY_UNPOLLED = 'unpolled';
+
+// Does this VM have a DEFINITE reachability verdict — did anyone actually ask?
+// Only a real boolean counts; null/undefined (and any malformed value) read as
+// "no verdict". Consumers use this to tell "never asked" from "asked and got an
+// answer", which is the distinction the whole three-state contract exists for.
+function hasReachabilityVerdict(reachable) {
+  return reachable === true || reachable === false;
+}
+
+// Is this VM CONFIRMED unreachable — probed, and the probe failed?
+//
+// Safety-critical. Reboot, reconcile, and destroy paths must gate on THIS, never
+// on a falsy check: `!reachable` is also true for an unknown, so a `!reachable`
+// guard lets a VM nobody has polled walk into a path that ends in a hard reset.
+// An unknown is not evidence, and evidence is the bar for a destructive action.
+function isConfirmedUnreachable(reachable) {
+  return reachable === false;
+}
+
+// Normalize a raw poll record's reachability into the pair the wire envelope
+// carries: `{ reachable, reachableSource }`.
+//
+// This is the seam where the bug lived. `reachable` is preserved as a genuine
+// tri-state — an ABSENT verdict stays absent rather than being coerced to a
+// definite false — and `reachableSource` falls back to 'unpolled' so a card with
+// no verdict says so out loud instead of looking like an unexplained outage.
+//
+// `v` is the merged poll state (`state.vms[n]`), or a placeholder standing in
+// for a VM with no poll state at all.
+function normalizeReachability(v) {
+  const raw = v ? v.reachable : null;
+  const reachable = hasReachabilityVerdict(raw) ? raw : null;
+  return {
+    reachable,
+    reachableSource: (v && v.reachableSource)
+      || (reachable === null ? REACHABILITY_UNPOLLED : null),
+  };
+}
+
+module.exports = {
+  REACHABILITY_UNPOLLED,
+  hasReachabilityVerdict,
+  isConfirmedUnreachable,
+  normalizeReachability,
+};

package/npm/fleet-reset.js

@@ -494,6 +494,36 @@ function needsReconfigureFallback(log) {
   return typeof log === 'string' && log.includes('CY_NEEDS_RECONFIGURE');
 }
 
+// The reset-family actions whose in-container recipe REBUILDS the codeyam-editor
+// binary before restart when the target is a self-host VM. Both resetClientScript
+// and resetEditorStateScript (default rebuildOnSelfHost=true) run selfHostRebuildStep,
+// so on a self-host VM either one triggers a full cargo compile (~10-14 min). The
+// composite reset-all budgets that rebuild separately; update-client (a non-destructive
+// ff-merge with NO rebuild/restart) is deliberately absent.
+const REBUILDS_ON_SELF_HOST = new Set(['reset-client', 'reset-editor']);
+
+// Default per-action SHORT budgets (ms) — the historical non-self-host timeout for
+// each reset action, kept so a genuine client-VM hang still surfaces promptly.
+const RESET_SHORT_TIMEOUT_MS = { 'reset-client': 300000, 'reset-editor': 600000 };
+// Default self-host REBUILD budget (ms): the same 27.5-min allowance reset-all
+// already uses for a self-host binary rebuild. Overridable via the rebuildMs arg
+// (server.js resolves it from RESET_REBUILD_TIMEOUT_MS).
+const RESET_REBUILD_TIMEOUT_MS = 1650000;
+
+// Select the startJob timeout (ms) for a reset-family action, accounting for the
+// self-host rebuild. On a self-host VM a rebuild-bearing reset (see
+// REBUILDS_ON_SELF_HOST) advances the editor's OWN source and MUST rebuild the
+// binary before restart, a ~10-14 min cargo compile the old flat 5-min budget
+// killed mid-compile — surfacing a false `error` badge on a reset that actually
+// succeeded. A non-self-host client reset genuinely does not rebuild and keeps its
+// short budget. Pure: budgets default to the constants above but are injectable for
+// env-tunability + tests. Unknown/non-rebuild action or non-self-host → short budget.
+function resetJobTimeoutMs({ action, selfHost, shortMs, rebuildMs } = {}) {
+  const short = Number.isFinite(shortMs) ? shortMs : RESET_SHORT_TIMEOUT_MS[action];
+  const rebuild = Number.isFinite(rebuildMs) ? rebuildMs : RESET_REBUILD_TIMEOUT_MS;
+  return selfHost && REBUILDS_ON_SELF_HOST.has(action) ? rebuild : short;
+}
+
 module.exports = {
   codeyamDeepCleanSteps,
   codeyamBrokerEnsureStep,
@@ -504,4 +534,6 @@ module.exports = {
   resetEditorStateScript,
   endSessionScript,
   verifyIdleOrEndSessionStep,
+  resetJobTimeoutMs,
+  REBUILDS_ON_SELF_HOST,
 };

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

@@ -0,0 +1,115 @@
+'use strict';
+
+// Resolve the running-plan fields a fleet card shows — feature, step, mode,
+// 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
+// restarted while the PTY broker kept the agent alive reports
+// `hasSession:false` / `sessionId:null` and session-info then OMITS
+// feature/step/mode/selectedPlan — so an actively-building VM showed a BLANK
+// card. `GET /api/step` reads `editor-step.json` directly, independent of
+// session registration, so it stays populated across that restart. This helper
+// makes `/api/step` the preferred source and falls back to session-info.
+//
+// Stickiness — the subtle part. The last-known `prev` is carried ONLY to bridge
+// a genuine probe failure (the editor answered NOTHING this poll), so a single
+// timed-out cycle can't blank a plan the card is already showing. It is NOT a
+// blanket fallback: when the editor DID answer, the fresh read is authoritative
+// for the plan the VM is executing NOW. Carrying prev unconditionally pinned a
+// COMPLETED plan's feature onto the next one — feature-complete deletes
+// editor-step.json (reset_step_state), and a plan's `feature` is null until
+// step 4, so a stale prev would win over the correct null and the card kept
+// showing plan A while the VM built plan B. So prev is carried only within the
+// SAME plan (matching selectedPlan); a plan change (or going idle) drops it.
+//
+// Precedence per field, when the editor answered: `/api/step` (session-
+// independent) > `/api/session-info` > same-plan `prev`. On a full probe
+// failure: `prev` verbatim. Pure; no I/O — unit-tested in
+// fleet-running-plan.test.js.
+//
+// @param {Object} params
+// @param {?Object} params.step  Parsed `/api/step` body (EditorStepState) or
+//   null when the VM has no `editor-step.json` (idle) / the probe failed.
+// @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/startedAt/
+//   featureStartedAt). null/undefined on the first poll.
+// @returns {{feature: ?string, step: ?number, mode: ?string,
+//   selectedPlan: ?string, holderSessionId: ?string, startedAt: ?string,
+//   featureStartedAt: ?string}}
+function resolveRunningPlan({ step, info, prev } = {}) {
+  const s = step || {};
+  const i = info || {};
+  const p = prev || {};
+
+  // Did the editor answer at all this poll? `/api/step` returning a body proves
+  // it; so does a reachable `/api/session-info`. If NEITHER answered, this is a
+  // transient outage — hold the last-known-good plan verbatim rather than blank
+  // the card for one cycle.
+  const editorAnswered = step != null || !!i.reachable;
+  if (!editorAnswered) {
+    return {
+      feature: p.feature || null,
+      step: p.step != null ? p.step : null,
+      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,
+    };
+  }
+
+  // Editor answered: the fresh read is authoritative for the current plan.
+  const freshSelectedPlan = s.selectedPlan || i.selectedPlan || null;
+  // Carry prev ONLY within the same plan — a blip-fallback for a momentarily
+  // missing field (e.g. /api/step timed out but session-info answered). Across
+  // a plan change or an idle poll, prev is stale and MUST be dropped.
+  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: pick("feature"),
+    step: stepNum,
+    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"),
+  };
+}
+
+module.exports = { resolveRunningPlan };

package/npm/fleet-session-token-cache.js

@@ -0,0 +1,65 @@
+'use strict';
+// Per-VM editor session-token cache for the fleet dashboard's gated probes.
+//
+// The post-501766261 editor runs FAIL-CLOSED: every control-API request must
+// carry that VM's own editor session token in `Authorization`, or the editor
+// answers 401. The dashboard reads each token once over the existing SSH/
+// docker-exec path (server.js supplies the impure `fetchToken`) and caches it
+// per VM — the token is stable for the container's lifetime, so re-reading it
+// on every poll would be a wasted gcloud-ssh fork per VM per cycle.
+//
+// Pure logic only — no I/O, no env reads, no clock — so it stays unit-testable
+// in isolation (npm/fleet-session-token-cache.test.js), exactly like the
+// createIapTokenProvider it mirrors. The caller injects `fetchToken(n)`.
+
+/** Build a per-VM session-token cache.
+ *
+ *  `fetchToken(n)` resolves to the VM's session token string (or null/'' when
+ *  it cannot be read). Returns `{ getToken, invalidate }`:
+ *
+ *    getToken(n)   — resolves the cached token, fetching once on a cold entry.
+ *                    Concurrent cold calls for the same VM share ONE in-flight
+ *                    fetch (the poll cycle probes several endpoints per VM at
+ *                    once). A null/empty/failed fetch resolves to null and is
+ *                    NOT cached, so the next poll retries rather than sticking a
+ *                    VM on a missing token.
+ *    invalidate(n) — drop a VM's cached token so the next getToken re-fetches.
+ *                    Called on a fail-closed 401, which is how a container
+ *                    recreate / token rotation self-heals.
+ */
+function createSessionTokenCache({ fetchToken } = {}) {
+  if (typeof fetchToken !== 'function') {
+    throw new Error('createSessionTokenCache requires a fetchToken(n) function');
+  }
+
+  const cache = new Map();     // n -> non-empty token string
+  const inFlight = new Map();  // n -> Promise<string|null>
+
+  async function getToken(n) {
+    if (cache.has(n)) return cache.get(n);
+    if (inFlight.has(n)) return inFlight.get(n);
+
+    const p = Promise.resolve()
+      .then(() => fetchToken(n))
+      .then((tok) => {
+        const value = tok == null ? '' : String(tok).trim();
+        // Only a real token is cached; a null/empty/errored read degrades to
+        // today's behavior (probe with no session token) and retries next poll.
+        if (value !== '') cache.set(n, value);
+        return value === '' ? null : value;
+      })
+      .catch(() => null)
+      .finally(() => { inFlight.delete(n); });
+
+    inFlight.set(n, p);
+    return p;
+  }
+
+  function invalidate(n) {
+    cache.delete(n);
+  }
+
+  return { getToken, invalidate };
+}
+
+module.exports = { createSessionTokenCache };

package/npm/fleet-setup-steps.js

@@ -39,15 +39,6 @@ function parseDriftReason(reason) {
   return m ? { expected: m[1].trim(), running: m[2].trim() } : { expected: null, running: null };
 }
 
-// The re-wire command the ingress-unwired reason embeds after "Re-wire: " (see
-// fleet-public-url.js::ingressUnwiredReason). Surfaced as the setup step's
-// inline action so the calm checklist row carries the exact command, not just a
-// label. null when the reason carries no command tail.
-function parseIngressAction(reason) {
-  const m = /Re-wire:\s*(.+)$/.exec(reason);
-  return m ? m[1].trim() : null;
-}
-
 // Partition degradedReasons into { setupSteps, attentionReasons }.
 //
 //   setupSteps        ordered [{ code, label, detail, action? }] — expected
@@ -66,11 +57,14 @@ function classifyReasons(degradedReasons = []) {
     if (reason.startsWith('claude-auth-not-seeded')) {
       setupSteps.push({ code: 'auth', label: 'Claude login', detail: reason });
     } else if (reason.startsWith('ingress-unwired')) {
+      // System-handled: the dashboard reconcile wires the public URL
+      // automatically (incl. down+up self-heal for reused-slug orphans). NO
+      // operator `action`/command — render as in-progress, never a to-do.
       setupSteps.push({
         code: 'ingress',
         label: 'Public URL wiring',
-        detail: reason,
-        action: parseIngressAction(reason),
+        detail: 'Wiring the public URL — this happens automatically.',
+        auto: true,
       });
     } else if (reason.startsWith('project-dir-drift')) {
       const { expected, running } = parseDriftReason(reason);
@@ -102,4 +96,17 @@ function hasOnlySetup(degradedReasons = []) {
   return setupSteps.length > 0 && attentionReasons.length === 0;
 }
 
-module.exports = { classifyReasons, hasOnlySetup, SETUP_CODES, SCAFFOLD_PROJECT_DIR };
+// True when a VM's reasons are ALL expected setup steps AND every one of them is
+// the SAME given code — e.g. `onlySetupCode(reasons, 'auth')` is the gate for the
+// calm, first-class `needs-login` status: the ONLY outstanding item is Claude
+// login, nothing else. A MIXED set (auth + ingress) is not `onlySetupCode('auth')`
+// — it reads the generic `finishing-setup` instead. Builds on the same classifier
+// as hasOnlySetup, so an empty list or any attention reason is false.
+function onlySetupCode(degradedReasons = [], code) {
+  const { setupSteps, attentionReasons } = classifyReasons(degradedReasons);
+  return setupSteps.length > 0
+    && attentionReasons.length === 0
+    && setupSteps.every((s) => s.code === code);
+}
+
+module.exports = { classifyReasons, hasOnlySetup, onlySetupCode, SETUP_CODES, SCAFFOLD_PROJECT_DIR };