@codeyam-editor/codeyam-editor 0.1.6 → 0.1.7

package/npm/fleet-cleanup.js

@@ -337,6 +337,132 @@ function reattachNextStep(verdict) {
   return 'probe'; // 'done' and 'reconcile' both confirm via the gcloud probe
 }
 
+// May the PERIODIC stranded-reconcile pass drive a recover/roster probe for this
+// VM, or is a provision already running that a second cloud:up would collide
+// with? This is the guard the boot re-attach path has always had and the
+// stranded path never did — the 2026-08-07 asymmetry that destroyed VM-4/VM-5.
+//
+// On that day an `add` job badge read `error` while its detached `cloud:up`
+// child was alive and healthy (a source-build bootstrap runs ~40 minutes;
+// `npm install` alone took 25m). `pollStrandedInstances` builds `activeAddNs`
+// from BADGE state and deliberately excludes an `error` add so the bounded
+// bootstrap-recovery budget can retry on a timer — so the VM read
+// running-but-unrostered, crossed STRANDED_ADOPT_THRESHOLD in ~3 minutes, and
+// the pass launched a SECOND cloud:up on top of the live one. The two raced on
+// `docker compose up -d`, the loser hit `Conflict. The container name
+// "/codeyam-editor-editor-1" is already in use`, and its abort handler deleted
+// the instance. The badge is a derived, lossy signal that was wrong for 30
+// minutes straight; LIVENESS is the ground truth, so this gate reads exactly
+// what `reattachAdd` reads — the exit marker plus a `kill -0` of the recorded
+// pid — and composes `reattachVerdict`/`reattachNextStep` rather than forking a
+// parallel matrix.
+//
+//   'watch'  no marker + a live child   → the provision is genuinely in flight.
+//                                         Re-attach and watch (mirroring
+//                                         runStartupReap); NEVER provision.
+//   'defer'  no marker, no live child, and no pid was EVER recorded, inside the
+//            ambiguity window            → we cannot tell whether a child is
+//                                         running. Do nothing this tick.
+//   'probe'  everything else             → existing behavior: drive the gcloud
+//                                         probe (reconcileViaGcloud →
+//                                         reapVerdict).
+//
+// The 'defer' rung exists because `childAlive` is FALSE-NEGATIVE-PRONE on one
+// specific path: when `strandedReconcileMeta` finds no sidecar it reconstructs
+// cfg from launch history and persists `{ cfg }` with NO pid, so `isPidAlive`
+// reads false for a VM whose child may well be alive — and, worse, that pid-less
+// sidecar is what every later tick reads back, blinding the guard permanently.
+// `pidRecorded` separates "we knew the pid and the process is gone" (real
+// evidence → probe) from "we never had a pid" (absence of evidence → defer).
+// Erring toward NOT provisioning is the asymmetric-cost choice: waiting one more
+// 60s tick costs nothing, being wrong costs a destroyed VM.
+//
+// The window is what keeps 'defer' from becoming a permanent refusal that would
+// break stranded adoption outright: once more than `ambiguityWindowMs` has
+// elapsed since we first saw the pid-less sidecar, no plausible provision child
+// is still running, so the probe proceeds and the self-heal path is preserved.
+// An unknown/unstamped elapsed is treated as "just noticed" (defer), again the
+// safe direction; a caller that supplies no window at all opts out entirely and
+// keeps the old probe-always behavior.
+//
+// Pure, so the whole matrix is testable without a VM: server.js maps the verdict
+// to its side effect.
+function strandedRecoverGate({
+  markerPresent,
+  exitCode,
+  childAlive,
+  pidRecorded,
+  sinceMs,
+  ambiguityWindowMs,
+} = {}) {
+  // A live child is a live child — reuse the existing classifier so 'running'
+  // keeps meaning exactly what the boot path means by it.
+  if (reattachNextStep(reattachVerdict({ markerPresent, exitCode, childAlive })) === 'watch') {
+    return 'watch';
+  }
+  // A marker is durable proof the child reached its EXIT trap: nothing is in
+  // flight, so the probe is safe. (Which probe outcome follows — roster,
+  // recover-bootstrap, surface-error — stays reapVerdict's call, not ours.)
+  if (markerPresent) return 'probe';
+  // We knew the pid and `kill -0` says it is gone: real evidence, so probe.
+  if (pidRecorded) return 'probe';
+  const window = Number(ambiguityWindowMs);
+  if (!Number.isFinite(window) || window <= 0) return 'probe'; // caller opted out
+  const elapsed = Number(sinceMs);
+  if (!Number.isFinite(elapsed)) return 'defer'; // unstamped — treat as just-noticed
+  return elapsed < window ? 'defer' : 'probe';
+}
+
+// Is an `add` genuinely IN FLIGHT for this VM right now?
+//
+// Extracted from pollVanishedInstances, where the inline expression was
+// `addPending.has(n) || !!(state.jobs[n] && state.jobs[n].action === 'add')` —
+// whose second clause is also true for a TERMINAL (`done` / `error`) add job.
+// That permanently marks the VM busy, so `reconcileRosteredVm` can never return
+// 'cleanup' and a rostered VM whose instance is gone can never be auto-reaped.
+// Live evidence from the same 2026-08-07 incident: VM-5's instance was deleted
+// at ~12:46 and its card logged `vanish-reconcile: VM-5 unreachable …` once a
+// minute for 50 consecutive polls, only clearing after a manual `clear-badge`
+// deleted the terminal job record.
+//
+// The on-disk sidecar clause is already correct and is preserved: a sidecar is
+// removed on the add's success path, so its presence really does mean in-flight.
+// The job clause now filters on job STATE the same way `activeAddNs` and
+// `pollStartupProbes` do. Pure so the caller's computation is directly
+// assertable — the bug was never in `reconcileRosteredVm`'s contract, it was in
+// what this expression fed it.
+const IN_FLIGHT_ADD_STATES = ['running', 'queued', 'recovering'];
+
+function hasInFlightAdd({ sidecarPending, job } = {}) {
+  if (sidecarPending) return true;
+  if (!job || job.action !== 'add') return false;
+  return IN_FLIGHT_ADD_STATES.includes(job.state);
+}
+
+// WHICH of reconcileRosteredVm's two distinct 'leave' causes fired, as a tag the
+// caller renders. Pure so the distinction is directly assertable.
+//
+// 'leave' is returned both when the GCP probe was INCONCLUSIVE (exists null /
+// undefined — absence of evidence, never act) and when the instance is
+// CONFIRMED gone but the VM is busy. The old single log line conflated them into
+// a self-contradiction — it announced "instance-gone unconfirmed (exists=false)"
+// when exists=false IS the confirmation — which cost hours of code-reading
+// during the 2026-08-07 incident to work out which branch was actually firing.
+//
+//   'probe-inconclusive'  exists is null/undefined — retry next tick
+//   'live-session'        instance confirmed gone but a session is live
+//   'in-flight-add'       instance confirmed gone but an add is in flight
+//   null                  not a 'leave' case at all
+//
+// Mirrors reconcileRosteredVm's own precedence (exists-uncertainty first, then
+// hasSession, then hasPendingAdd) so the tag can never disagree with the verdict.
+function vanishLeaveReason({ exists, hasSession, hasPendingAdd } = {}) {
+  if (exists === null || exists === undefined) return 'probe-inconclusive';
+  if (hasSession) return 'live-session';
+  if (hasPendingAdd) return 'in-flight-add';
+  return null;
+}
+
 // 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
@@ -537,4 +663,7 @@ module.exports = {
   isSignalKillExit,
   reattachVerdict,
   reattachNextStep,
+  strandedRecoverGate,
+  hasInFlightAdd,
+  vanishLeaveReason,
 };

package/npm/fleet-job-badge.js

@@ -15,21 +15,37 @@
 // Should the VM's last terminal-error job badge be reconciled against live
 // health — i.e. presented as "recovered" rather than a live red error?
 //
-//   job        the carried job record ({ state, action, ... }) or null
-//   reachable  the VM's editor answered this poll (true = healthy / responding)
-//   drifted    a project-dir-drift signal is present (reachable-but-unwired /
-//              half-provisioned add — genuinely needs-recovery, owned by the
-//              companion reconcile-inflight-jobs plan; never falsely cleared here)
-//   offBranch  the VM's live client branch differs from its target branch
-//   degraded   the job completed but a wiring sub-step is flagged degraded
+//   job          the carried job record ({ state, action, ... }) or null
+//   reachable    the VM's editor answered this poll over the LB (true = healthy)
+//   inVmHealthy  the in-VM editor answered /api/health from INSIDE the container
+//                (the STRAND_PROBE `HEALTH=1` witness gathered over docker-exec)
+//   drifted      a project-dir-drift signal is present (reachable-but-unwired /
+//                half-provisioned add — genuinely needs-recovery, owned by the
+//                companion reconcile-inflight-jobs plan; never falsely cleared here)
+//   offBranch    the VM's live client branch differs from its target branch
+//   degraded     the job completed but a wiring sub-step is flagged degraded
 //
 // Returns true only when the job is a terminal error AND the VM is demonstrably
-// fine (reachable, not drifted, on-branch, not degraded). An unreachable /
-// drifted / off-branch VM keeps its error surfaced — a real problem must stay
-// visible.
-function shouldReconcileFailedBadge({ job, reachable, drifted, offBranch, degraded } = {}) {
+// fine (healthy, not drifted, on-branch, not degraded). A drifted / off-branch /
+// unwitnessed VM keeps its error surfaced — a real problem must stay visible.
+//
+// HEALTH IS WITNESSED TWO WAYS, and either suffices. `reachable` alone made the
+// self-heal unable to fire in exactly the case that needs it most: on the GCE
+// operator host `reachable` is derived from the LB probe, which needs the very
+// ingress the add is still wiring. That is a circular dependency — the badge
+// needs reachable, reachable needs ingress, and ingress is what we are waiting
+// for — so a still-wiring VM sat at unreachableStreak 9 with a red add-error it
+// could not clear by construction (VM-4, 2026-07-31). The dashboard already held
+// the disconfirming evidence: gatherLauncherStrand runs STRAND_PROBE over
+// docker-exec for exactly these unreachable-with-streak VMs and reads HEALTH=1
+// from the in-VM /api/health.
+//
+// This widens ONE input; it does not relax the verdict. Every other guard is
+// untouched, and the "absence of evidence never auto-acts" posture holds — an
+// unprobed VM has neither witness and stays unreconciled.
+function shouldReconcileFailedBadge({ job, reachable, inVmHealthy, drifted, offBranch, degraded } = {}) {
   if (!job || job.state !== 'error') return false;
-  if (!reachable) return false;
+  if (!reachable && !inVmHealthy) return false;
   if (drifted) return false;
   if (offBranch) return false;
   if (degraded) return false;

package/npm/fleet-memory.js

@@ -356,6 +356,49 @@ function shouldAnnounceMemoryLevel({ level, lastLevel } = {}) {
   return !QUIET_MEMORY_LEVELS.includes(level);
 }
 
+/** Resolve the directory holding THIS process's memory.current / memory.high,
+ *  or null when no cgroup-derived reading is available.
+ *
+ *  The cgroup-v2 hierarchy ROOT exposes no memory.current and no memory.high —
+ *  only a leaf cgroup does. Reading `/sys/fs/cgroup/memory.current` directly is
+ *  therefore ENOENT on every systemd host, and that is exactly what made the
+ *  2026-07-30 memory remedy inert: both reads failed, every cgroup number
+ *  degraded to null, decideMemoryRestart answered 'no-cgroup-limit' on every
+ *  tick forever, and the drain silently fell back to the RSS threshold the
+ *  incident had already proven cannot fire before the event loop stalls.
+ *
+ *  Takes the CONTENTS of /proc/self/cgroup rather than reading it, so the path
+ *  derivation — the part that was wrong — is unit-testable on a macOS dev box
+ *  with no cgroup filesystem at all. That untestability is why a root-vs-leaf
+ *  path error shipped green.
+ *
+ *  Returns null for every shape that has no leaf memory file to read:
+ *    • the unified line `0::/` — the process IS in the root cgroup, which
+ *      genuinely has no memory files; this must NOT look like a valid path;
+ *    • cgroup v1 (`N:controller:/path` lines, no `0::` entry);
+ *    • empty, unreadable, or malformed input (a non-Linux host has no
+ *      /proc/self/cgroup at all, and the caller passes the null through).
+ *
+ *  Pure; no I/O. */
+function resolveCgroupMemoryDir({ procSelfCgroup, root } = {}) {
+  if (typeof procSelfCgroup !== 'string') return null;
+  const base = (typeof root === 'string' && root)
+    ? root.replace(/\/+$/, '')
+    : '/sys/fs/cgroup';
+  for (const line of procSelfCgroup.split('\n')) {
+    const trimmed = line.trim();
+    // cgroup v2 unified hierarchy is the single `0::<path>` entry. v1 lines
+    // (`N:controller:/path`) never match, which is the intended null path.
+    if (!trimmed.startsWith('0::')) continue;
+    const rel = trimmed.slice(3);
+    if (!rel.startsWith('/')) return null;
+    const clean = rel.replace(/\/+$/, '');
+    if (!clean) return null;
+    return base + clean;
+  }
+  return null;
+}
+
 /** Keep only the restart timestamps still inside the rolling window.
  *
  *  Split out from decideMemoryRestart so the "how many restarts have I already
@@ -386,6 +429,7 @@ module.exports = {
   formatMemoryText,
   hasJobInFlight,
   shouldAnnounceMemoryLevel,
+  resolveCgroupMemoryDir,
   pruneRestartWindow,
   buildStateSnapshot,
   decodeStateSnapshot,

package/npm/fleet-probe-transport.js

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

package/npm/fleet-revision.js

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

package/npm/fleet-running-plan.js

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