@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

package/npm/fleet-build-data.js

@@ -0,0 +1,130 @@
+'use strict';
+
+// Assemble the per-VM wire object the dashboard's /data response carries to the
+// browser. This is the single source of truth for a card's transport shape: the
+// card UI (scripts/operator/fleet-dashboard/public/index.html) reads `v.<field>`
+// off each entry, so every field the card renders MUST be emitted here.
+//
+// It was split out of server.js's buildData() so the shape is unit-testable.
+// The regression that motivated the split: `currentProvider` (the VM's
+// configured build agent) was merged onto the poll state AND read by the card to
+// render the 🤖 agent badge, but it was silently missing from this envelope — so
+// it lived in server memory and never reached the browser, and the badge never
+// appeared. A hand-maintained object literal inside a 197KB monolith has no
+// guard against that drift; a pure function does.
+//
+// `v` is the merged poll state (state.vms[n]). `ctx` carries the derived,
+// cross-VM, and side-effecting values buildData computes per VM (status,
+// debounced broker tri-state, reconciled job, queue position, launch cfg, …) —
+// the things this pure function can't know on its own.
+function buildVmEnvelope(v, ctx) {
+  return {
+    n: ctx.n,
+    url: v.url || null,
+    reachable: !!v.reachable,
+    hasSession: !!v.hasSession,
+    // Three-state: true = broker confirmed up, false = confirmed down, null =
+    // editor unreachable so broker state is unknown. Never conflate "down" with
+    // "unreachable" — that mismatch is what made the card show "broker down"
+    // while a direct pgrep proved the broker was up.
+    brokerLive: v.reachable ? !!v.agentBrokerLive : null,
+    // Broker tri-state: 'down' | 'idle' | 'agent-live' | 'unknown' (derived
+    // upstream, debounced). Richer than brokerLive's is-an-agent-live boolean.
+    brokerStatus: ctx.brokerStatus,
+    awaitingInput: !!v.awaitingUserInput,
+    // True when the editor reports the build workflow reached its terminal step
+    // and is parked awaiting cleanup (session_info_response.rs emits it at
+    // step >= total). Flows onto poll state via the `...info` spread in server.js
+    // exactly like `feature`/`awaitingUserInput`; defaulted false here so a legacy
+    // editor that predates the field degrades to today's behavior. Consumed by
+    // fleet-live-status.js to read a parked-but-done agent as calm 'session-done'
+    // instead of active-green 'building'.
+    needsCleanup: !!v.needsCleanup,
+    feature: v.feature || null,
+    step: v.step != null ? v.step : null,
+    mode: v.mode || null,
+    label: v.label || null,
+    status: ctx.status,
+    orphan: ctx.orphan || null,
+    degradedReasons: ctx.degradedReasons || [],
+    // Derived presentation split of degradedReasons (vm: Dashboard 'Finishing
+    // setup' state): `setupSteps` are expected first-run wiring rendered as a
+    // calm blue checklist, `attentionReasons` are genuine problems kept in the
+    // amber ⚠ treatment. `degradedReasons` is left intact for the many places
+    // that still consume the flat list (filters, sort, reconcile); these two are
+    // purely additive. Both default to [] so a legacy/healthy VM renders neither
+    // block. See npm/fleet-setup-steps.js::classifyReasons.
+    setupSteps: Array.isArray(ctx.setupSteps) ? ctx.setupSteps : [],
+    attentionReasons: Array.isArray(ctx.attentionReasons) ? ctx.attentionReasons : [],
+    isHead: !!ctx.isHead,
+    // True when this VM holds the queue head but is unreachable (operator
+    // decides manually whether to release it).
+    headHolderUnreachable: !!ctx.headHolderUnreachable,
+    queuePos: ctx.queuePos != null ? ctx.queuePos : null,
+    queueLen: ctx.queueLen,
+    job: ctx.job || null,
+    config: ctx.config || null,
+    project: ctx.project != null ? ctx.project : null,
+    variant: ctx.variant != null ? ctx.variant : null,
+    cardIdentity: ctx.cardIdentity,
+    brokerHistory: Array.isArray(v.brokerHistory) ? v.brokerHistory : [],
+    brokerDeath: ctx.brokerDeath,
+    // Auth state + reason + token expiry. Only surfaced when the editor is
+    // reachable (an unreachable VM's cached auth is stale and misleading).
+    providerAuth: v.reachable && v.providerAuth ? v.providerAuth : null,
+    effects: v.effects || null,
+    // The VM's live-configured build agent (lowercase provider), reported by
+    // /api/session-info and merged (sticky) onto the poll state. Drives the
+    // card's 🤖 agent badge. null for an older VM whose editor predates the
+    // field (the card omits the badge rather than rendering a blank chip).
+    currentProvider: v.currentProvider || null,
+    // Raw workflow timestamps (ISO) surfaced by /api/session-info and merged onto
+    // the poll state via the `...info` spread, exactly like feature/step/label.
+    // The card live-ticks the elapsed minutes off these between polls. null for a
+    // legacy editor that predates the fields, or a VM with no active step.
+    startedAt: v.startedAt || null,
+    featureStartedAt: v.featureStartedAt || null,
+    // The server-computed stuck / needs-you verdict (npm/fleet-stuck-status.js):
+    // { stepElapsedMs, level: 'ok'|'slow'|'stuck', needsYou, needsYouElapsedMs }.
+    // The authoritative level only changes on poll; the card colors the step
+    // tenure badge by it. null when buildData couldn't compute one.
+    attention: ctx.attention || null,
+    // Per-VM card readiness derived upstream (npm/fleet-vm-readiness.js): one of
+    // READINESS_STATES. The card colors the border and GATES the editor link on
+    // it — a non-'ready' VM never presents its public URL as live, because the
+    // LB would 503. Computed in buildData where the broker tri-state / job / LB
+    // mode are on hand, then carried here so the browser needs no extra request.
+    readiness: ctx.readiness || null,
+    // The raw LB backend-health map { editor, preview } the readiness derivation
+    // consumed, surfaced so the card can show a precise tooltip (which surface
+    // is unwired). null in legacy mode or before the first slow probe lands.
+    backendHealth: v.backendHealth || null,
+    // The per-VM IAP access whitelist (the principals explicitly granted
+    // resource-level access to THIS VM, from the fleet-vm-access sidecar). Merged
+    // onto the poll state at server.js, it drives the card's 🔐 access line and
+    // the Manage access modal's "this VM only" list. It was previously dropped
+    // here — the exact currentProvider-style envelope drift this module guards
+    // against — so the line and list rendered empty even when the sidecar held
+    // principals. Defaults to [] for a VM with no list.
+    vmAccess: Array.isArray(v.vmAccess) ? v.vmAccess : [],
+  };
+}
+
+// The fields the card UI depends on being present in every /data VM entry. This
+// is the contract `buildVmEnvelope` must satisfy: the regression that prompted
+// this module was a field the card read but the envelope didn't emit, so the
+// test asserts the envelope keys are a superset of this list. Adding a field the
+// card renders means adding it here AND in buildVmEnvelope — the test fails loud
+// if you do one without the other.
+const REQUIRED_CARD_FIELDS = [
+  'n', 'url', 'reachable', 'hasSession', 'brokerLive', 'brokerStatus',
+  'awaitingInput', 'needsCleanup', 'feature', 'step', 'mode', 'label', 'status', 'orphan',
+  'degradedReasons', 'setupSteps', 'attentionReasons',
+  'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
+  'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
+  'brokerDeath', 'providerAuth', 'effects', 'currentProvider',
+  'readiness', 'backendHealth', 'vmAccess',
+  'startedAt', 'featureStartedAt', 'attention',
+];
+
+module.exports = { buildVmEnvelope, REQUIRED_CARD_FIELDS };

package/npm/fleet-cleanup.js

@@ -175,13 +175,28 @@ function clearExitMarker(dir, n) {
   catch (_) { /* missing is fine */ }
 }
 
+// True when an integer exit code is the shell's "killed by signal N" encoding,
+// i.e. 128 + N for N in 1..37 — the realistic kills being 143 (SIGTERM, the
+// `launchctl bootout` graceful teardown), 137 (SIGKILL), 130 (SIGINT) and 129
+// (SIGHUP). Pure boundary check: 128 itself is NOT a signal kill (it's `exit
+// 128`, an ordinary failure code), so the range is the OPEN interval
+// (128, 165]. Anything outside it — a small `exit 1` from the addVm script's own
+// failure branches, 0, NaN, null — is not a signal kill. The split that matters:
+// "did a signal kill the provision shell" (interrupted → reconcile) vs "did the
+// provision logic itself decide it failed" (real error). Exported so the matrix
+// is unit-testable directly.
+function isSignalKillExit(code) {
+  return Number.isInteger(code) && code > 128 && code <= 165;
+}
+
 // Decide how a snapshot-restored `add` should be re-attached after a dashboard
 // restart, BEFORE any gcloud probe. Pure: takes the durable signals the boot
 // path gathers — whether the exit marker exists, its recorded code, and whether
 // the detached provision child is still alive (recorded pid, `kill -0`).
 //   verdict       when                                          dispatch
 //   'done'        marker present, exit code 0                   roster + recordLaunch, clear sidecar/marker
-//   'error'       marker present, non-zero exit code            surface the real failure, clear sidecar/marker
+//   'reconcile'   marker present, SIGNAL-kill code (128<c≤165)  interrupted, not failed — gcloud probe decides
+//   'error'       marker present, other non-zero exit code      surface the real failure, clear sidecar/marker
 //   'running'     no marker yet, child still alive              RE-ATTACH: keep polling, do NOT mark error
 //   'reconcile'   child gone, no usable marker                  fall through to fc.reapVerdict (gcloud probe)
 // This is the durable fix's brain: a provision that survived the kill (still
@@ -192,20 +207,65 @@ function clearExitMarker(dir, n) {
 // `reconcile` hands that exact (exists, containerUp, projectWired) decision to
 // fc.reapVerdict. A marker whose first line isn't an integer is treated as
 // absent (parseExitMarker → null) so a corrupt marker reconciles rather than
-// asserting a bogus code. The matrix is exhaustively tested without a live VM.
+// asserting a bogus code.
+//
+// SIGNAL-kill codes (improve46): `setsid` shields the detached provision from a
+// dashboard-process-GROUP SIGKILL (the 2GB launchd hard cap), but NOT from a
+// `launchctl bootout`, which tears down the whole launchd job tree regardless of
+// session/process-group. A graceful SIGTERM then reaches the "detached" child and
+// its EXIT trap records 143 (128+SIGTERM) into the marker. That is an INTERRUPTED
+// add, not a failed one — the manual re-add succeeds in seconds off the image the
+// interrupted build already left on the VM. So a signal-kill code routes to
+// 'reconcile' (let the gcloud probe read ground truth and roster / recover) rather
+// than 'error' (a false add-failed that throws away a resumable build). A genuine
+// provision failure exits with a small non-zero code (e.g. `exit 1`), which STILL
+// classifies 'error'. The matrix is exhaustively tested without a live VM.
 function reattachVerdict({ markerPresent, exitCode, childAlive } = {}) {
   if (markerPresent) {
     // Guard the null/undefined coercion BEFORE Number() — `Number(null)` is 0,
     // which would masquerade as a clean exit. A marker with no parseable code
     // (half-written / corrupt) must reconcile, not assert success.
     const code = exitCode == null ? NaN : Number(exitCode);
-    if (Number.isInteger(code)) return code === 0 ? 'done' : 'error';
+    if (Number.isInteger(code)) {
+      if (code === 0) return 'done';
+      // A signal killed the provision shell (e.g. bootout SIGTERM → 143): the add
+      // was interrupted, not failed — reconcile against real VM state instead of
+      // surfacing a false add-failed and discarding a resumable build.
+      if (isSignalKillExit(code)) return 'reconcile';
+      return 'error';
+    }
     return 'reconcile'; // marker present but no parseable code — let gcloud decide
   }
   if (childAlive) return 'running';
   return 'reconcile';
 }
 
+// improve45 — map a reattachVerdict tag to the dashboard's NEXT action, now that
+// a clean exit marker is NECESSARY BUT NOT SUFFICIENT to roster. A detached
+// `cloud:up` can exit 0 AFTER the image build but BEFORE `docker compose up`
+// ever runs — an ssh broken-pipe or dashboard SIGKILL landing in that window,
+// with the wrapping EXIT trap still recording 0 (the live VM2 signature: built
+// image, repo cloned, ZERO editor containers). So 'done' no longer means "roster
+// it"; it means "confirm the container is actually up first." Both the clean-exit
+// ('done') and the no-usable-marker ('reconcile') cases therefore route through
+// the SAME gcloud container + wiring probe (reconcileViaGcloud → fc.reapVerdict),
+// which rosters only a genuinely-up + wired add and routes a half-provisioned one
+// to recover-bootstrap. 'error' (real non-zero exit) and 'running' (child still
+// alive) are unchanged. reattachVerdict stays the honest classifier of the
+// child's exit SIGNAL; this helper expresses how that signal is CONSUMED now that
+// exit-0 no longer implies rostering. Pure: server.js maps the returned action to
+// its side-effecting step, so the matrix is exhaustively testable without a VM.
+//   verdict       next step         meaning
+//   'done'        'probe'           confirm the container before rostering
+//   'reconcile'   'probe'           no usable marker — let the gcloud probe decide
+//   'error'       'surface-error'   real failure — show add-failed with the code
+//   'running'     'watch'           child still alive — keep polling for the marker
+function reattachNextStep(verdict) {
+  if (verdict === 'error') return 'surface-error';
+  if (verdict === 'running') return 'watch';
+  return 'probe'; // 'done' and 'reconcile' both confirm via the gcloud probe
+}
+
 // Anti-loop budget for the `recover-bootstrap` path. Pure: given the count of
 // recoveries ALREADY persisted on the sidecar, return the next attempt number,
 // whether the reap should proceed (re-run cloud:up) or treat the VM as
@@ -271,11 +331,87 @@ function orphanedAddsToReconcile({ jobs, sidecarKeys } = {}) {
 // posture). "Busy" (a live session or an in-flight add to this number) also
 // holds the entry for an operator rather than auto-removing — the shouldn't-
 // happen-but-fail-safe case where a vanished instance still reports a session.
-function reconcileRosteredVm({ exists, hasSession, hasPendingAdd } = {}) {
+//   verdict     when                                        dispatch
+//   'cleanup'   instance gone AND the VM is idle            runDestroyCleanup
+//   'leave'     exists uncertain (null), OR the VM is busy  do nothing this pass
+//   'keep'      instance still exists                       do nothing (healthy)
+//   'reset'     existing idle instance unreachable too long trigger auto-reset
+// Fail-safe by construction: cleanup fires ONLY on a DEFINITIVE absence
+// (exists === false) — a flaky/transient describe (null) is always 'leave', so a
+// gcloud blip can never evict a healthy VM (mirroring reapVerdict's `leave`
+// posture). "Busy" (a live session or an in-flight add to this number) also
+// holds the entry for an operator rather than auto-removing — the shouldn't-
+// happen-but-fail-safe case where a vanished instance still reports a session.
+// auto-reset escalation (vm: OOM Wedge Prevention):
+// When the VM has been unreachable for at least RESET_UNREACHABLE_THRESHOLD
+// (e.g. 200, which is roughly 10 minutes at a 3s poll rate), we issue a 'reset'
+// verdict. This auto-reset is guarded and bounded by a cooldown window (in ms)
+// and a max attempts limit to prevent infinite reboot loops.
+//
+// false-unreachable reboot safety (2026-06-25): "unreachable" as the dashboard
+// sees it means the LOCALLY-FORWARDED port is dark — which is ALSO the signature
+// of an operator-side fault (the laptop's gcloud auth expired, the ssh -L tunnel
+// zombied, a laptop network blip) where the VM itself is perfectly healthy.
+// Rebooting a healthy production VM off that signal interrupts a live session.
+// So three operator-fault guards are layered BEFORE the cooldown/attempts budget
+// (a reset is a last resort, never the response to a dark local port). Each is
+// OPT-IN: it only changes the verdict when the caller supplies the fact, so
+// legacy callers (and the OOM-wedge tests) that pass none keep the old behavior.
+//   operatorAuthDegraded  our own gcloud auth is broken → EVERY VM reads
+//                         unreachable; rebooting them all is exactly wrong → keep
+//   fleetWideUnreachable  a simultaneous N-VM "outage" is the operator (auth/
+//                         tunnel/network), not N dead VMs → keep
+//   gcpReachable          GCP-side confirmation: true  ⇒ the VM answers from
+//                         GCP's vantage, so the dark local port is a laptop
+//                         tunnel fault → 'respawn' (never reset); null ⇒ the
+//                         GCP-side probe was inconclusive → keep (don't escalate
+//                         a destructive reset on absence of evidence); false ⇒
+//                         genuinely unreachable from GCP too → fall through to
+//                         the cooldown/attempts budget and reset as before.
+function reconcileRosteredVm({ exists, hasSession, hasPendingAdd, streak, resetHistory, threshold, cooldownMs, maxAttempts, operatorAuthDegraded, fleetWideUnreachable, gcpReachable } = {}) {
   if (exists === null || exists === undefined) return "leave";
-  if (exists) return "keep";
-  if (hasSession || hasPendingAdd) return "leave";
-  return "cleanup";
+  if (!exists) {
+    if (hasSession || hasPendingAdd) return "leave";
+    return "cleanup";
+  }
+
+  // If the VM exists, check if it's dead-unreachable and eligible for auto-reset.
+  if (streak !== undefined && threshold !== undefined) {
+    if (streak >= threshold) {
+      if (hasSession || hasPendingAdd) {
+        // Do NOT auto-reset a VM that is busy (holding a live session or an in-flight add)
+        return "keep";
+      }
+
+      // Operator-fault guards — layered before the cooldown/attempts budget so a
+      // laptop-side fault never even consumes a reset attempt.
+      if (operatorAuthDegraded) return "keep";
+      if (fleetWideUnreachable) return "keep";
+      if (gcpReachable === true) return "respawn";
+      if (gcpReachable === null) return "keep";
+
+      const history = resetHistory || { count: 0, lastResetAt: 0 };
+      const attempts = history.count || 0;
+      const limit = maxAttempts !== undefined ? maxAttempts : 3;
+      
+      if (attempts >= limit) {
+        // Budget exhausted (VM wedges repeatedly) -> park (needs-manual-recovery status)
+        return "keep";
+      }
+      
+      const lastReset = history.lastResetAt || 0;
+      const cooldown = cooldownMs !== undefined ? cooldownMs : 600000; // default 10 minutes
+      const now = Date.now();
+      if (now - lastReset < cooldown) {
+        // Within cooldown window -> do not reset again yet
+        return "keep";
+      }
+
+      return "reset";
+    }
+  }
+
+  return "keep";
 }
 
 module.exports = {
@@ -293,5 +429,7 @@ module.exports = {
   parseExitMarker,
   readExitMarker,
   clearExitMarker,
+  isSignalKillExit,
   reattachVerdict,
+  reattachNextStep,
 };

package/npm/fleet-destroy-safety.js

@@ -0,0 +1,55 @@
+'use strict';
+// Pure decision + formatting helpers for the fleet dashboard's destroy/deroster
+// false-unreachable safety (2026-06-26 incident, where a reauth-triggered
+// false-unreachable cascade permanently deleted VM2/3/4). The dashboard's
+// server.js gathers the live operator-fault facts (state.operatorAuthDegraded +
+// fleetWideUnreachableNow) and runs the side effects (spawn the delete, log,
+// stop+deroster); the DECISIONS those facts drive — "is this destroy blocked,
+// and why" and "what does the attribution log line read" — live here so they
+// are unit-testable in isolation, the same pure/IO split npm/fleet-auth-health.js
+// (classifyOperatorAuth) and npm/fleet-cleanup.js (reconcileRosteredVm) follow.
+//
+// Pure logic only — no I/O, no env reads, no clock, no global state.
+
+// Classify whether a destructive removal (hard destroy or --shrink) must be
+// REFUSED because the operator's own side is faulted, from the two booleans
+// server.js computes. Returns { blocked, reason }: blocked is true when the
+// operator's gcloud auth is degraded OR a fleet-wide unreachable spike is in
+// progress — the signature of a laptop-side fault (which makes EVERY VM read
+// unreachable), NOT N genuinely-dead VMs. authDegraded takes precedence in the
+// reason because it is the upstream cause (a broken operator auth is what
+// produces the fleet-wide false-unreachable spike in the first place), so the
+// message points at the thing to fix.
+//   authDegraded  state.operatorAuthDegraded — operator gcloud auth is broken
+//   fleetWide     fleetWideUnreachableNow() — N+ VMs unreachable at once
+function classifyDestroyBlock({ authDegraded, fleetWide } = {}) {
+  if (authDegraded) {
+    return { blocked: true, reason: 'operator gcloud auth degraded' };
+  }
+  if (fleetWide) {
+    return { blocked: true, reason: 'fleet-wide unreachable spike in progress (operator-side fault signature)' };
+  }
+  return { blocked: false, reason: null };
+}
+
+// Build the single attributable destroy-decision log line. Mirrors the
+// performAutoReset "confirmed … not fleet-wide" template so every destroy —
+// proceed OR refused, across every trigger source — is diagnosable from one
+// grep. `remote` ({ ip, ua }) is the caller attribution whose absence made the
+// 2026-06-26 delete impossible to trace back to its trigger; null/absent renders
+// as `n/a` (e.g. the shrink / reap paths have no HTTP caller). All the flag
+// fields are normalized to real booleans so a missing field never reads as
+// `undefined` in the line.
+function formatDestroyDecision(info = {}) {
+  const remote = info.remote ? `${info.remote.ip || '?'}/${info.remote.ua || '?'}` : 'n/a';
+  return (
+    `destroy-decision: VM-${info.n} source=${info.source} force=${!!info.force} ` +
+    `override=${!!info.overrideSafety} remote=${remote} hasSession=${!!info.hasSession} ` +
+    `authDegraded=${!!info.authDegraded} fleetWide=${!!info.fleetWide} → ${info.outcome}`
+  );
+}
+
+module.exports = {
+  classifyDestroyBlock,
+  formatDestroyDecision,
+};

package/npm/fleet-effect-status.js

@@ -58,12 +58,10 @@ function resetReason({ agent, session, dirty, behind, codeyam }) {
 // meaningless for them).
 const ACTION_IDS = [
   'update-client-source',
-  'update-editor-source',
-  'reset-editor-source',
   'reset-client',
+  'end-session',
   'rebuild-binary',
   'update-reset-everything',
-  'run-setup',
 ];
 
 // facts (a plain object gathered by server.js — no I/O):
@@ -105,13 +103,6 @@ function computeButtonEffects(facts) {
       ? { effect: 'changes', reason: behindReason(client.behind, f.clientBranch) }
       : { effect: 'noop', reason: 'up to date with ' + originRef(f.clientBranch) };
 
-  // (2) Update editor — advance the editor source the binary builds from.
-  const updateEditor = editor == null
-    ? { effect: 'unknown', reason: 'editor state not checked' }
-    : editor.behind > 0
-      ? { effect: 'changes', reason: behindReason(editor.behind, f.editorBranch) }
-      : { effect: 'noop', reason: 'up to date with ' + originRef(f.editorBranch) };
-
   // (5) Rebuild binary — advances source then compiles. Changes iff the running
   // binary's build commit differs from the editor origin tip. Unknown when we
   // don't have both commits to compare.
@@ -121,25 +112,38 @@ function computeButtonEffects(facts) {
       ? { effect: 'changes', reason: `binary at ${short(editor.buildCommit)}, ${originRef(f.editorBranch)} at ${short(editor.originSha)}` }
       : { effect: 'noop', reason: 'binary built from ' + originRef(f.editorBranch) + ' tip' };
 
-  // (3) Reset editor — discards uncommitted + session, advances source, wipes
-  // .codeyam. No-op ONLY when clean at origin tip with no session.
+  // Reset editor (editor-state reset) — discards uncommitted + session, advances
+  // source, wipes .codeyam. No-op ONLY when clean at origin tip with no session.
+  // INTERNAL-ONLY: the standalone "Reset editor" button was removed; this
+  // predicate survives purely as an input to the "Reset all + rebuild" composite
+  // below (which still runs resetEditorStateScript), so it is NOT returned/keyed.
   const resetEditor = editor == null
     ? { effect: 'unknown', reason: 'editor state not checked' }
     : (brokerLive || hasSession || editor.dirty || editor.behind > 0 || codeyamDirty)
       ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: editor.dirty, behind: editor.behind > 0, codeyam: codeyamDirty }) }
       : { effect: 'noop', reason: 'already clean at origin tip, no session' };
 
-  // (3b) Reset client — hard-clean /workspace + .codeyam, drop the session.
-  // No source-advance, so `behind` is NOT part of this predicate.
+  // (2) Reset client — hard-clean /workspace + .codeyam, drop the session, now
+  // ADVANCING to origin tip. Since the reset advances source, a VM behind origin
+  // would be changed by a re-run, so `behind` IS part of this predicate.
   const resetClient = client == null
     ? { effect: 'unknown', reason: 'client state not checked' }
-    : (brokerLive || client.dirty || codeyamDirty || hasSession)
-      ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: client.dirty, behind: false, codeyam: codeyamDirty }) }
-      : { effect: 'noop', reason: 'already clean, no session' };
+    : (brokerLive || client.dirty || client.behind > 0 || codeyamDirty || hasSession)
+      ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: client.dirty, behind: client.behind > 0, codeyam: codeyamDirty }) }
+      : { effect: 'noop', reason: 'already clean at origin tip, no session' };
 
-  // (4b) Update & Reset Everything — composite. Changes iff ANY component would
-  // change: rebuild-binary, reset-editor-source, or the client being
-  // behind/dirty. Reason summarizes which parts.
+  // (2b) End session — kills the live agent + clears session state. The ONLY
+  // thing it touches is the running session, so it changes the VM iff a live
+  // agent or a registered session exists; otherwise it's a clean no-op. Unlike
+  // the resets it ignores dirty/behind/.codeyam — it neither advances source nor
+  // wipes state.
+  const endSession = (brokerLive || hasSession)
+    ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession }) }
+    : { effect: 'noop', reason: 'no active session' };
+
+  // (4) Reset all + rebuild — composite. Changes iff ANY component would
+  // change: rebuild-binary, the editor-state reset (internal resetEditor
+  // predicate above), or the client being behind/dirty. Reason summarizes parts.
   const everything = (() => {
     if (editor == null || client == null) {
       return { effect: 'unknown', reason: 'state not checked' };
@@ -157,23 +161,20 @@ function computeButtonEffects(facts) {
     return { effect: 'noop', reason: 'everything already at origin tip, no session' };
   })();
 
-  // (run-setup) Honest soft signal — there is no cheap upstream proof that
-  // `npm run setup` would change nothing (DB/migration state isn't
-  // introspected). `recommended` when a reset/update landed after the last
-  // successful setup; otherwise `unknown`. Never a confident green no-op.
-  const runSetup = f.setupRanSince
-    ? { effect: 'unknown', reason: 'no setup-affecting change since last setup' }
-    : { effect: 'recommended', reason: 'a reset/update landed since the last setup' };
-
   return {
     'update-client-source': updateClient,
-    'update-editor-source': updateEditor,
-    'reset-editor-source': resetEditor,
     'reset-client': resetClient,
+    'end-session': endSession,
     'rebuild-binary': rebuild,
     'update-reset-everything': everything,
-    'run-setup': runSetup,
   };
 }
 
-module.exports = { computeButtonEffects, ACTION_IDS };
+// Decide whether a Live Preview SSH forward needs to be re-wired (improve41)
+function needsRewire(forwardAppPort, polledAppPort) {
+  if (typeof polledAppPort !== 'number' || isNaN(polledAppPort)) return false;
+  if (!forwardAppPort) return false;
+  return forwardAppPort !== polledAppPort;
+}
+
+module.exports = { computeButtonEffects, ACTION_IDS, needsRewire };

package/npm/fleet-host.js

@@ -0,0 +1,74 @@
+'use strict';
+// Pure operator-host placement resolution for the fleet dashboard
+// (vm-dashboard-on-gce).
+//
+// The dashboard runs in two homes: the operator's laptop (legacy fallback) and a
+// dedicated GCE "operator host" (the primary path). Three things differ by home —
+// how gcloud authenticates, what address the dashboard binds, and how a branch
+// pin is read from the env — and each used to be an inline ternary at the top of
+// server.js's 200KB monolith, untestable. This module is the single home for
+// those decisions, so server.js delegates the RULE and keeps only the I/O, the
+// same split npm/fleet-branch.js (resolveFleetBranch) follows.
+//
+// Pure logic only — no I/O, no env reads beyond the explicit `env` argument a
+// caller passes in — so it stays unit-testable in isolation (npm/fleet-host.test.js).
+
+// Env var the systemd unit sets on the GCE operator host. Its presence (truthy)
+// is what flips the dashboard from the laptop defaults to the on-GCE defaults.
+const FLEET_ON_GCE_ENV = 'FLEET_ON_GCE';
+
+/** True when the dashboard is running on the GCE operator host, read from the
+ *  `FLEET_ON_GCE` env. Accepts the conventional truthy spellings `1` / `true` /
+ *  `yes` (case-insensitive, trimmed); everything else — unset, empty, `0`,
+ *  `false`, garbage — is false, so a laptop run (which never sets it) stays on
+ *  the loopback + named-configuration defaults. */
+function onGce(env = {}) {
+  return /^(1|true|yes)$/i.test(String(env[FLEET_ON_GCE_ENV] || '').trim());
+}
+
+/** Resolve the gcloud invocation prefix the dashboard's `${GCLOUD}` chokepoint
+ *  uses. On the GCE operator host the attached SA authenticates from instance
+ *  metadata, so a plain `gcloud` is correct (no key file, no named config). Off
+ *  GCE (laptop) it pins the non-expiring SA configuration with
+ *  `--configuration=<config>` so background loops survive OAuth-token expiry.
+ *  Returns `'gcloud'` on GCE; throws if a non-GCE call omits the config name,
+ *  since silently emitting a bare `gcloud` there would run on the operator's
+ *  personal account — the exact regression the chokepoint exists to prevent. */
+function gcloudCommand({ onGce: gce, config } = {}) {
+  if (gce) return 'gcloud';
+  const c = typeof config === 'string' ? config.trim() : '';
+  if (!c) {
+    throw new Error('gcloudCommand requires a config name when not on GCE');
+  }
+  return `gcloud --configuration=${c}`;
+}
+
+/** Resolve the address the dashboard binds. An explicit `bind` (the DASH_BIND
+ *  override) always wins. Otherwise the host serves the LB's zonal NEG so it must
+ *  bind the instance's internal NIC (`0.0.0.0`, firewalled to the LB + IAP
+ *  ranges); a laptop run binds loopback only (`127.0.0.1`). A blank/whitespace
+ *  override counts as absent so a set-but-empty env doesn't bind to an empty
+ *  string. */
+function dashboardBind({ onGce: gce, bind } = {}) {
+  const explicit = typeof bind === 'string' ? bind.trim() : '';
+  if (explicit) return explicit;
+  return gce ? '0.0.0.0' : '127.0.0.1';
+}
+
+/** Resolve the explicit branch pin from the env, or null when unpinned. The
+ *  operator-host name is `FLEET_BRANCH`; `BRANCH` is the legacy laptop alias and
+ *  is honored as a fallback. A blank/whitespace value is "no pin" (so the
+ *  dashboard tracks live git HEAD via resolveFleetBranch). Returns the trimmed
+ *  pin or null. */
+function branchPin(env = {}) {
+  const pin = String(env.FLEET_BRANCH || env.BRANCH || '').trim();
+  return pin === '' ? null : pin;
+}
+
+module.exports = {
+  FLEET_ON_GCE_ENV,
+  onGce,
+  gcloudCommand,
+  dashboardBind,
+  branchPin,
+};

package/npm/fleet-job-badge.js

@@ -2,7 +2,7 @@
 
 // npm/fleet-job-badge.js — pure verdict for the fleet dashboard's failed-job
 // badge reconciliation (improve39). A VM's last terminal-error heavy job
-// (add/error, reset-all error, reset-editor error, …) used to stick on the
+// (add/error, reset-all error, reset-client error, …) used to stick on the
 // dashboard card indefinitely — even after the VM was recovered and is healthy
 // again — because the card renders the last job's error with no check against
 // the VM's live state, so a recovered VM keeps screaming a red error and
@@ -36,4 +36,48 @@ function shouldReconcileFailedBadge({ job, reachable, drifted, offBranch, degrad
   return true;
 }
 
-module.exports = { shouldReconcileFailedBadge };
+// Given a reconcile verdict (from shouldReconcileFailedBadge) and whether the VM
+// is now idle, decide whether the recovered badge should be FULLY CLEARED — the
+// job entry dropped from state.jobs so the card goes clean — rather than merely
+// muted as a "recovered (was: …)" note (improve41).
+//
+//   badgeReconciled  the shouldReconcileFailedBadge verdict for this VM
+//   idle             the VM answered this poll, is not running a build session,
+//                    and its broker is not actively serving an agent
+//
+// A recovered VM that is also idle has demonstrably finished recovering, so the
+// stale error is dropped entirely. A recovered-but-not-yet-idle VM (mid-build,
+// or a poll hasn't confirmed idle) keeps the muted note so the prior log stays
+// visible during that transient window. Never clears a badge that wasn't first
+// judged recovered — an unreachable / drifted / off-branch error stays surfaced.
+function shouldClearReconciledBadge({ badgeReconciled, idle } = {}) {
+  return !!badgeReconciled && !!idle;
+}
+
+// Pure guard for the operator "Clear badge" action (improve41). Decides whether
+// VM-n's persisted job entry may be dropped after an out-of-band recovery,
+// independent of the server's state / fs I/O so the cases are unit-tested
+// without a live dashboard. The shell (server.js) supplies the live signals and
+// turns the verdict into the {ok,msg} response + the actual delete + snapshot.
+//
+//   rostered  the VM number is in the live roster
+//   job       the carried job record ({ state, ... }) or null/undefined
+//
+// Only a TERMINAL job (error/done) on a rostered VM may be cleared, OR a terminal
+// failed add (add/error) on a non-rostered VM (which deletes the card + add-N sidecar):
+// any other job state / non-rostered combination is not clearable.
+// Returns { ok, reason, cleanup } — reason is a stable code the shell maps to an
+// operator message, and cleanup is the cleanup action to perform ('add-failed' vs 'badge-only').
+function canClearBadge({ rostered, job } = {}) {
+  if (!rostered) {
+    if (job && job.action === 'add' && job.state === 'error') {
+      return { ok: true, reason: null, cleanup: 'add-failed' };
+    }
+    return { ok: false, reason: 'not-rostered' };
+  }
+  if (!job) return { ok: false, reason: 'no-badge' };
+  if (job.state !== 'error' && job.state !== 'done') return { ok: false, reason: 'job-active' };
+  return { ok: true, reason: null, cleanup: 'badge-only' };
+}
+
+module.exports = { shouldReconcileFailedBadge, shouldClearReconciledBadge, canClearBadge };