@codeyam-editor/codeyam-editor 0.1.0-staging.g25ba0d1 → 0.1.0-staging.g296f8a2

package/npm/fleet-add-failure.js

@@ -96,6 +96,67 @@ function transcriptRostered(logTail) {
   return parseRosterMarkers(String(logTail || '')).length > 0;
 }
 
+// The categories that describe an add whose outcome is NOT yet proven bad — the
+// calm, in-flight side of the classifier. `converging` is a rostered box whose
+// ingress is still wiring; `verifying` is the residue: no failure signature
+// matched and nothing durable proves the VM is dead. Both render a calm card and
+// neither may use the word "failed". Consumed by holdConvergingBadge and by
+// deriveStatus (server.js) to pick the matching calm status.
+const CALM_ADD_CATEGORIES = new Set(['converging', 'verifying']);
+
+// Is a non-zero add outcome CORROBORATED by a durable fact — i.e. do we have
+// positive proof of death, rather than merely an absence of proof of life?
+//
+// This is the conjunction that gates the red `unknown` verdict. Before it, the
+// classifier's fallthrough treated "no recognized success signature" as failure,
+// so "we don't know" rendered as a terminal red "Add failed" telling the operator
+// to destroy a VM whose container was Up and whose editor answered /api/health
+// 200 (VM-4, 2026-07-31). Red now requires BOTH halves:
+//
+//   1. A non-zero exit code. A *missing* code is not proof of death — today it
+//      usually means the wrapper was signal-killed while its provision ran on,
+//      which is exactly the case that was misreading as failure. `null`,
+//      `undefined`, a non-integer, and 0 all fail this half.
+//   2. At least one durable corroborating fact:
+//        - `instanceAlive === false`   GCP says the instance is gone.
+//        - `containerHealthy === false` the in-VM editor was probed and is not
+//          answering — the box exists but never came up.
+//        - `wiringDeadlineBlown`       the wire-add-tail gave up (the failed
+//          marker is the tail's own honest deadline signal).
+//
+// Every fact is TRI-STATE on purpose: `undefined`/`null` means "not probed" and
+// corroborates nothing. Only an explicit `false` counts, so an unprobed VM can
+// never be escalated to red by absence of evidence.
+function addFailureCorroborated({ exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown } = {}) {
+  const code = exitCode == null ? NaN : Number(exitCode);
+  if (!Number.isInteger(code) || code === 0) return false;
+  return instanceAlive === false || containerHealthy === false || !!wiringDeadlineBlown;
+}
+
+// Resolve the two independent health signals into the single tri-state
+// `containerHealthy` fact addFailureCorroborated consumes. Pure so the precedence
+// — which decides whether a VM can be escalated to red — is unit-tested; the
+// server (addFailureFacts) supplies the live signals.
+//
+//   reachable    the editor answered over the LB.
+//   inVmHealthy  the STRAND_PROBE /api/health read from INSIDE the container.
+//
+// LB reachability wins when present: it is the stronger witness (it proves the
+// whole URL→ingress→backend path, not just the process). Otherwise the in-VM
+// witness answers — this is the still-wiring case, where the LB necessarily
+// cannot see a VM whose ingress is what we are waiting on, yet the editor itself
+// is demonstrably up.
+//
+// Returns `null` when NEITHER signal was gathered. That is the load-bearing case:
+// an unprobed VM must corroborate nothing, so it can never be escalated to red by
+// absence of evidence. `false` is reserved for a VM that was genuinely probed and
+// did not answer.
+function containerHealthWitness({ reachable, inVmHealthy } = {}) {
+  if (reachable) return true;
+  if (inVmHealthy != null) return !!inVmHealthy;
+  return null;
+}
+
 // Build a verdict, stamping `retryable` from the single-source-of-truth Set so it
 // can never drift from the category.
 function buildFailureVerdict(category, headline, recovery, extra) {
@@ -108,7 +169,16 @@ function buildFailureVerdict(category, headline, recovery, extra) {
 //
 //   logTail   the last lines of the provision transcript (string; '' when the
 //             log was unreadable — must never throw)
-//   exitCode  the provision's exit code (number; used for signal-kill detection)
+//   exitCode  the provision's exit code (number; used for signal-kill detection
+//             and as the first half of the proof-of-death conjunction)
+//
+// The remaining inputs are the durable facts the server gathers (the module
+// stays pure — it never probes). All are tri-state; omit any that was not
+// probed and it corroborates nothing. See addFailureCorroborated.
+//
+//   instanceAlive        does GCP still list the instance?
+//   containerHealthy     did the in-VM editor answer /api/health?
+//   wiringDeadlineBlown  did the add-time wire tail drop its failed marker?
 //
 // Returns { category, headline, recovery, retryable, files? }.
 //
@@ -118,7 +188,7 @@ function buildFailureVerdict(category, headline, recovery, extra) {
 // signature is therefore tested BEFORE the generic cloud-up-failed signature, or
 // a retryable drift would misclassify as a non-retryable cloud:up failure and the
 // operator would lose the safe one-click recovery.
-function classifyAddFailure({ logTail, exitCode } = {}) {
+function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown } = {}) {
   const log = String(logTail || '');
 
   // 1. preflight-drift — the streamed-script drift guard aborted BEFORE any
@@ -218,9 +288,34 @@ function classifyAddFailure({ logTail, exitCode } = {}) {
       'The container is up and the VM is rostered; the LB ingress is still wiring in the background. This resolves on its own once the editor is reachable over the LB — no action needed unless it persists past the wiring deadline.');
   }
 
-  // 9. unknown — fallback. Never invite an unproven retry.
-  return buildFailureVerdict('unknown', 'Add failed',
-    'The add failed for an unclassified reason — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+  // 9. The residue: no failure signature above matched. The polarity here is
+  //    INVERTED from the original design. It used to read "no recognized success
+  //    signature ⇒ failed", which made red the DEFAULT for "we don't know" — so a
+  //    VM whose container was Up and whose editor answered /api/health 200 got a
+  //    terminal red "Add failed" card advising the operator to destroy it (VM-4,
+  //    2026-07-31; the wrapper had been killed mid-flight, so its transcript was
+  //    truncated before CY_ROSTER and it never reached the `converging` arm above).
+  //
+  //    Red now requires positive proof of death, and everything else is in-flight:
+  //
+  //    9a. unknown — a non-zero exit CORROBORATED by a durable fact (see
+  //        addFailureCorroborated). The box is provably dead or provably never
+  //        came up, so the loud, terminal escalation is warranted and unchanged.
+  //        Still never invites an unproven retry.
+  if (addFailureCorroborated({ exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown })) {
+    return buildFailureVerdict('unknown', 'Add failed',
+      'The add failed for an unclassified reason and the VM is confirmed dead or never came up — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+  }
+
+  //    9b. verifying — the honest default. No failure signature, and nothing
+  //        durable proves this VM is dead: it may still be provisioning or
+  //        wiring, and the ingress can keep propagating for minutes after the
+  //        wrapper is gone. Calm copy, transcript still one click away. NOT
+  //        retryable — nothing is proven about the box either way, so a one-click
+  //        retry could still duplicate a live GCP instance (the ADD_FAILURE_RETRYABLE
+  //        grounds are unchanged by this inversion).
+  return buildFailureVerdict('verifying', 'Add outcome unconfirmed',
+    'No failure signature was found in the transcript and nothing proves this VM is dead, so the add may still be converging — the ingress keeps propagating for minutes after the provision wrapper exits. Inspect the transcript below; reconcile this VM only if it is still unresolved past the wiring deadline.');
 }
 
 // Pure guard for the operator "Retry add" action: given a VM number and its
@@ -238,15 +333,29 @@ function canRetryAdd({ n, job } = {}) {
 }
 
 // Pure badge-hold predicate for deriveStatus (server.js): hold the calm in-flight
-// `add-converging` card — instead of the red add-failed — ONLY when the add was
-// classified `converging` AND its detached first-wiring is still in flight. Once
-// the wire-add-tail fails/deadlines (`addTailFailed`) or is gone (`addTailInflight`
-// false), or the category is anything else, return false so the caller falls
-// through to the red add-failed status — the operator-chosen escalation. Kept pure
-// (like canRetryAdd / canClearBadge) so the badge decision is unit-tested without a
+// card — instead of the red add-failed — while the add is still converging.
+//
+// The hold used to require `addTailInflight`, i.e. that the detached wire-add-tail
+// PROCESS was still alive. That premise was wrong: the tail's exit says nothing
+// about LB convergence, because the EXTERNAL_MANAGED backend services keep
+// propagating for minutes afterwards. VM-4's backends were still being created at
+// 18:17-18:20Z, long after its job had been declared failed at 18:15Z — the tail
+// had exited, so the calm hold released and the card went red on a healthy VM.
+//
+// The hold is now driven by the question that actually matters: is this add still
+// converging, and has its wiring deadline genuinely blown? `wiringDeadlineBlown`
+// (the failed marker the tail drops when it gives up) stays the release signal —
+// tail liveness is no longer a requirement for calm, so the calm state survives
+// the multi-minute propagation window instead of ending at process exit.
+//
+// Both calm categories qualify (see CALM_ADD_CATEGORIES): a rostered box that is
+// still wiring, and the unproven residue. Any proven-failure category returns
+// false and falls through to the red add-failed status — the operator-chosen
+// escalation, which this predicate narrows but never softens. Kept pure (like
+// canRetryAdd / canClearBadge) so the badge decision is unit-tested without a
 // live dashboard.
-function holdConvergingBadge({ category, addTailInflight, addTailFailed } = {}) {
-  return category === 'converging' && !!addTailInflight && !addTailFailed;
+function holdConvergingBadge({ category, wiringDeadlineBlown } = {}) {
+  return CALM_ADD_CATEGORIES.has(category) && !wiringDeadlineBlown;
 }
 
-module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, ADD_FAILURE_RETRYABLE };
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE };

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"),
   };
 }