@codeyam-editor/codeyam-editor 0.1.7 → 0.1.9

package/npm/fleet-branch.js

@@ -46,4 +46,127 @@ function resolveFleetBranch({ envBranch, gitBranch, fallback } = {}) {
   return cleanBranch(fallback) || UNKNOWN_BRANCH;
 }
 
-module.exports = { UNKNOWN_BRANCH, cleanBranch, resolveFleetBranch };
+// ---------- Dead-pin detection ----------
+// `fleet-advance-to.sh` refuses to WRITE a pin for a branch absent from origin,
+// but that guard runs once and nothing re-checks the pin already in place —
+// while the branch it names can be deleted by anyone merging a PR with the
+// delete-branch box ticked. Observed 2026-08-15: PR #104 merged
+// `editor-improvements-72` and deleted it; hours later the operator host still
+// read `FLEET_BRANCH=editor-improvements-72` and nothing said so.
+//
+// The probe itself (`git ls-remote`) is I/O and belongs to server.js, on the
+// SLOW memo cadence rather than the ~3s /data poll. What lives here is the pure
+// classification of its outcome — which is the part a test can actually reach,
+// since a function defined in server.js can never be executed by a test (that
+// file has top-level side effects on require).
+//
+// The tri-state mirrors scripts/operator/lib/branch-on-origin.sh exactly, and
+// the mirroring is the point: `gone` is a DEFINITIVE absence, `indeterminate`
+// means absence was NOT proven (no network, no remote, auth trouble). Widening
+// `indeterminate` into `gone` would turn every offline operator host into a
+// fleet-wide "your pin is dead" alarm.
+
+/** Map a `git ls-remote --exit-code --heads` exit code to the shared tri-state.
+ *  0 -> 'live', 2 -> 'gone', anything else (including a non-numeric or absent
+ *  code) -> 'indeterminate'. Pure. */
+function lsRemoteStatus(exitCode) {
+  if (exitCode === 0) return 'live';
+  if (exitCode === 2) return 'gone';
+  return 'indeterminate';
+}
+
+/** Classify the health of the fleet's branch pin.
+ *
+ *  Returns `{ state, branch, pinned, dead, blocks, recovery }` where `state` is
+ *  'live' | 'gone' | 'indeterminate' | 'unknown'.
+ *
+ *  'unknown' is the un-probeable case — no branch, or the UNKNOWN_BRANCH
+ *  sentinel that `resolveFleetBranch` yields when there is neither a pin nor a
+ *  readable git HEAD. There is no ref to ask origin about, so reporting it as
+ *  `gone` would invent a deletion that never happened.
+ *
+ *  `dead` is true ONLY for 'gone'. It is the single field a caller should gate a
+ *  degradation banner on, so no consumer has to re-derive which states are
+ *  actionable.
+ *
+ *  `blocks` names what a dead pin is actively breaking — both consequences,
+ *  because neither announces itself: the operator-repo refresh cannot fetch a
+ *  deleted ref, and the pin also drives `cloud.json editorBranch`, so newly
+ *  provisioned VMs check out a ref that is not there. Pure; no I/O. */
+function classifyBranchPin({ branch, lsRemoteExitCode, pinned = false } = {}) {
+  const name = cleanBranch(branch);
+  const probeable = name !== null && name !== UNKNOWN_BRANCH;
+  const state = probeable ? lsRemoteStatus(lsRemoteExitCode) : 'unknown';
+  const dead = state === 'gone';
+  return {
+    state,
+    branch: name,
+    pinned: Boolean(pinned),
+    dead,
+    blocks: dead
+      ? [
+        'refresh-operator-repo.sh cannot fetch the pinned branch, so this host keeps serving whatever its clone already had',
+        'cloud.json editorBranch reads the same pin, so newly provisioned VMs check out a ref that does not exist',
+      ]
+      : [],
+    recovery: dead
+      ? `scripts/operator/fleet-advance-to.sh <BRANCH> — move the fleet to a live branch (it refuses a branch that is itself absent from origin)`
+      : null,
+  };
+}
+
+/** Decide whether the fleet pin should override a stored per-VM branch when an
+ *  add is RE-ISSUED, and report every override so the caller can log it.
+ *
+ *  Returns `{ config, overrides }` — a NEW config (the input is never mutated)
+ *  and `[{ field, from, to }]`, empty when nothing changed.
+ *
+ *  The problem this solves: a per-VM config that recorded `editor-improvements-75`
+ *  was not wrong when it was written — it EXPIRED, silently, the moment that
+ *  branch merged and origin pruned it. This repo prunes on merge, so every stored
+ *  feature-branch name has that property. The pin does not expire: it is the
+ *  durable statement of fleet-wide policy, and on 2026-08-25 it was correct
+ *  throughout while four retried cards each failed on their stale snapshot (a
+ *  fresh pool add read the pin and succeeded at the same moment).
+ *
+ *  Three guards, each declining to act rather than acting wrongly:
+ *   - `selfHost` false ⇒ untouched. A client VM's branch is a deliberate
+ *     per-project choice; overwriting it with a fleet pin would silently
+ *     retarget someone else's project. Only the self-host path, where the branch
+ *     IS fleet policy, falls back to the pin.
+ *   - no pin, or the UNKNOWN_BRANCH sentinel ⇒ untouched. There is no branch to
+ *     prefer, and stamping the sentinel would guarantee the failure this exists
+ *     to prevent.
+ *   - `pinState === 'gone'` ⇒ untouched. A pin PROVEN absent from origin is not
+ *     an improvement on a stale-but-possibly-live stored branch; swapping one
+ *     dead ref for another just moves the failure. Note the deliberate
+ *     asymmetry with 'indeterminate', which does NOT decline: absence was not
+ *     proven there, and refusing to converge every time the network blips would
+ *     strand the fleet on stale branches for the sake of a maybe.
+ *
+ *  Pure; no I/O. */
+function pinCorrectedBranches({ cfg, pin, selfHost = false, pinState } = {}) {
+  const config = { ...(cfg || {}) };
+  const overrides = [];
+  const name = cleanBranch(pin);
+  if (!selfHost || !name || name === UNKNOWN_BRANCH || pinState === 'gone') {
+    return { config, overrides };
+  }
+  for (const field of ['clientBranch', 'editorBranch']) {
+    const from = cleanBranch(config[field]);
+    if (from && from !== name) {
+      config[field] = name;
+      overrides.push({ field, from, to: name });
+    }
+  }
+  return { config, overrides };
+}
+
+module.exports = {
+  UNKNOWN_BRANCH,
+  cleanBranch,
+  resolveFleetBranch,
+  lsRemoteStatus,
+  classifyBranchPin,
+  pinCorrectedBranches,
+};

package/npm/fleet-build-data.js

@@ -120,6 +120,17 @@ function buildVmEnvelope(v, ctx) {
     // unreachable VM's last-known config is stale, and an unreachable card has
     // louder problems to report than its preview origin.
     previewMisconfigured: (v.reachable && v.previewMisconfigured) || null,
+    // The project's DECLARED datastore and whether it is answering:
+    // { type, target, local, reachable, lastError }, or null when the project
+    // declares none (a Rust CLI, a static site) — which is the common case and
+    // must render nothing at all. `reachable` is tri-state exactly like
+    // previewServing/previewIngress above: true = probe reached it, false =
+    // confirmed down, null = unknown (editor just booted, or the probe went
+    // stale). Never conflate "down" with "unknown" — only a confirmed false
+    // raises the amber reason. Gated on `reachable` like providerAuth: an
+    // unreachable VM's last-known datastore verdict is stale, and it has louder
+    // problems to report.
+    datastore: (v.reachable && v.datastore) || 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
@@ -177,7 +188,7 @@ const REQUIRED_CARD_FIELDS = [
   'degradedReasons', 'setupSteps', 'attentionReasons',
   'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
   'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
-  'brokerDeath', 'providerAuth', 'previewMisconfigured', 'effects', 'currentProvider',
+  'brokerDeath', 'providerAuth', 'previewMisconfigured', 'datastore', 'effects', 'currentProvider',
   'readiness', 'backendHealth', 'vmAccess',
   'startedAt', 'featureStartedAt', 'attention', 'envOverride',
 ];

package/npm/fleet-cleanup.js

@@ -618,20 +618,37 @@ function reconcileRosteredVm({ exists, hasSession, hasPendingAdd, streak, resetH
 // The dashboard's `state` and `addVm` are injected so this stays a pure,
 // importable unit — `log`/`err` default to the console but are overridable in
 // tests. Behavior mirrors the previous inline server.js definition exactly.
+//
+// The exhausted branch records a TERMINAL DISPOSITION, not just a flag. The flag
+// alone was write-only: nothing destroys the instance and the only code that
+// clears the flag is a *subsequent* recovery attempt, which by definition never
+// comes once the budget is spent. VM-10 therefore ran empty and unrostered for a
+// full day on 2026-08-29, billing, while the dashboard rendered a generic
+// needs-manual-recovery card and clearing it needed hand-edited JSON.
+// `instancePresumedRunning` says the GCE instance is believed to still exist —
+// PRESUMED, because this ladder step never probes GCP; `exhaustedOrphanDisposition`
+// is what reconciles the presumption against reality. `exhaustedAt` anchors the
+// accrued-cost clock the card renders. `addVm` is still never called: that is the
+// safety property that stops a wedged VM looping cloud:up forever.
 function continueBootstrapRecovery(
   n,
   meta,
   cfg,
-  { state, addVm, log = console.log, err = console.error } = {},
+  { state, addVm, log = console.log, err = console.error, now = Date.now } = {},
 ) {
   const { attempt, proceed, max } = recoverBootstrapDecision({
     recoverAttempts: meta.recoverAttempts,
   });
   if (!proceed) {
     err(
-      `startup-reap: VM-${n} exceeded ${max} bootstrap-recovery attempts — leaving sidecar for manual action`,
+      `startup-reap: VM-${n} exceeded ${max} bootstrap-recovery attempts — instance presumed still running, leaving sidecar for manual action`,
     );
-    state.orphans[n] = { reason: "bootstrap-recovery-exhausted", attempts: attempt - 1 };
+    state.orphans[n] = {
+      reason: "bootstrap-recovery-exhausted",
+      attempts: attempt - 1,
+      instancePresumedRunning: true,
+      exhaustedAt: now(),
+    };
     return;
   }
   log(
@@ -643,6 +660,68 @@ function continueBootstrapRecovery(
   addVm(n, cfg, { recovering: true, recoverAttempt: attempt });
 }
 
+// The exit `continueBootstrapRecovery`'s exhausted flag never had. That flag is
+// written once and, until this verdict existed, could only be cleared by a
+// subsequent recovery attempt the spent budget guarantees will never run — so it
+// outlived the instance it described and had to be removed by hand-editing
+// `.codeyam/logs/dashboard-state.json`. This reconciles the flag's PRESUMPTION
+// (`instancePresumedRunning`) against two live facts the sweep supplies:
+//
+//   instanceExists  true  ⇒ the presumption holds, the box is still billing
+//                   false ⇒ the instance is gone (destroyed out-of-band) → 'clear',
+//                            so the card self-heals with no operator action
+//                   null  ⇒ the describe probe was INCONCLUSIVE. Never act on
+//                            absence of evidence — same discipline reapVerdict
+//                            applies to its own `exists === null`.
+//   rostered        false ⇒ flagged, billing, and in nobody's roster: invisible to
+//                            every roster-driven tool yet costing money → 'cost',
+//                            the distinct ownerless surface, NOT a generic
+//                            needs-manual-recovery card.
+//                   true  ⇒ still owned, so it is recoverable → 'keep'.
+//                   null  ⇒ roster unknown; keep rather than raise a cost alarm
+//                            that may be false (positive-signal-only, mirroring
+//                            how projectWired/agentReady downgrade).
+//
+// Deliberately NOT a destroy verdict. Destroying a VM is irreversible and a
+// half-provisioned box occasionally holds the clue that explains the failure, so
+// the terminal disposition is "surface it loudly and offer the button" — the
+// operator presses it.
+function exhaustedOrphanDisposition({ reason, instanceExists, rostered } = {}) {
+  if (reason !== 'bootstrap-recovery-exhausted') return 'leave';
+  if (instanceExists === null || instanceExists === undefined) return 'leave';
+  if (!instanceExists) return 'clear';
+  return rostered === false ? 'cost' : 'keep';
+}
+
+// Fold a 'cost'/'keep' verdict into the orphan entry the card renders. Split out
+// of the dashboard's poller because the stickiness rule below is the only real
+// logic in that branch, and inlined in server.js it was unreachable by any test:
+// the dashboard has top-level side effects on require, so its pollers can only be
+// covered by a source-scan wiring guard that cannot evaluate behavior.
+//
+// `ownerlessSince` dates the accrued cost from when the VM was FIRST confirmed
+// ownerless, not from the latest probe — re-stamping it every tick would peg the
+// card's elapsed time near zero forever and hide exactly the multi-day cost the
+// surface exists to reveal. It is dropped (not zeroed, not left stale) the moment
+// a VM stops being ownerless — an operator adopting it back into the roster flips
+// the verdict to 'keep', and a leftover `ownerlessSince` would let the cost card
+// resurrect itself with a fabricated start time if the VM ever went ownerless
+// again. `instanceConfirmedAt` records that the presumption was checked live.
+//
+// Returns a NEW entry; the caller decides where to store it. Both verdicts keep
+// the flag — the instance is real and only an operator may destroy it.
+function annotateOwnerlessCost(orphan, { verdict, now = Date.now() } = {}) {
+  const next = { ...orphan, instancePresumedRunning: true, instanceConfirmedAt: now };
+  if (verdict === 'cost') {
+    next.ownerlessCost = true;
+    next.ownerlessSince = (orphan && orphan.ownerlessSince) || now;
+    return next;
+  }
+  next.ownerlessCost = false;
+  delete next.ownerlessSince;
+  return next;
+}
+
 module.exports = {
   parsePendingJobFilename,
   persistPendingJob,
@@ -656,6 +735,8 @@ module.exports = {
   classifyLbReachableForReap,
   recoverBootstrapDecision,
   continueBootstrapRecovery,
+  exhaustedOrphanDisposition,
+  annotateOwnerlessCost,
   exitMarkerName,
   parseExitMarker,
   readExitMarker,

package/npm/fleet-datastore-health.js

@@ -0,0 +1,107 @@
+'use strict';
+
+// npm/fleet-datastore-health.js — pure classifier for the fleet dashboard's
+// "declared datastore unreachable" surface: is the datastore a VM's project
+// DECLARES actually answering?
+//
+// Nothing anywhere reported this, so a VM whose database was down read
+// perfectly green. On VM-12 (2026-08-24) the dashboard, the LB backend health,
+// the IAP edge and the editor's own server-identity all reported healthy while
+// every DB-backed route returned 500 — the only evidence was `ECONNREFUSED
+// 127.0.0.1:5432` buried in the container log, which nobody polls. The
+// 2026-08-14 occurrence on the same VM presented as previewServing=false with an
+// EMPTY degradedReasons list: the dashboard knew something was wrong and had
+// nothing to say about it. This module is the "something to say".
+//
+// The editor probes (it is the only party that knows what the project declares,
+// and the resolution already exists in-crate) and carries the result on the
+// existing session-info poll; this module decides, and server.js renders. Pure
+// like fleet-project-drift.js: all the decision logic lives here and unit-tests
+// without a VM, while server.js stays the thin I/O shell.
+//
+// A new `datastore-unreachable` code needs NO change to
+// fleet-setup-steps.js::classifyReasons — it routes unknown codes to
+// attentionReasons by design ("an unrecognized signal is surfaced loudly, never
+// silently hidden"), so this lands amber. It must NOT be added to SETUP_CODES: a
+// dead datastore is never expected first-run wiring.
+
+// Decide the datastore-health reasons for one VM.
+//
+//   declared   truthy when the project declares a datastore at all. A project
+//              with none (a Rust CLI, a static site) must never raise a reason.
+//   reachable  TRI-STATE, matching the editor's own discipline: true = the probe
+//              reached it, false = the probe failed, null/undefined = unknown
+//              (not probed yet, or the probe went stale). Only an explicit
+//              `false` raises a reason — collapsing unknown into false would
+//              light up every VM during the window between editor boot and the
+//              first probe, which is the failure mode that trains an operator to
+//              ignore the surface.
+//   target     credential-free rendering of where it lives ("127.0.0.1:5432/app",
+//              or a file path). Never the DSN — that carries credentials.
+//   shape      'file' (a database file on disk) or 'network' (a server on a
+//              socket). Published by the editor rather than inferred from `type`
+//              here, because "sqlite means file-shaped" is a per-stack fact this
+//              module would otherwise have to learn for every engine. It decides
+//              WHICH recovery applies at all: a down server gets started, a
+//              missing file gets restored.
+//   local      whether the datastore is something this VM is expected to host
+//              (loopback host, or a file database). Decides where the recovery
+//              points; a remote/managed datastore is still reported, but telling
+//              an operator to start it here would send them somewhere there is
+//              nothing to do.
+//   type       the declared engine ('postgresql' | 'sqlite' | 'mysql' | …), used
+//              only to name what is down.
+//   lastError  the probe's own failure string ("connection refused: …"), so the
+//              card says WHY rather than just that.
+//   n          the VM number, so a local recovery can name the VM to act on.
+//
+// Returns { unreachable, reasons }. `reasons` is [] whenever healthy, unknown, or
+// nothing is declared, so the caller spreads it unconditionally.
+function classifyDatastoreHealth({ declared, reachable, target, shape, local, type, lastError, n } = {}) {
+  // Explicit `false` only. `null`/`undefined` is unknown and never a fault —
+  // the same absence-of-evidence-is-not-a-fault rule the reachability and
+  // backend-health classifiers already follow.
+  const unreachable = !!declared && reachable === false;
+  if (!unreachable) return { unreachable: false, reasons: [] };
+  return {
+    unreachable: true,
+    reasons: [datastoreUnreachableReason({ type, target, shape, local, lastError, n })],
+  };
+}
+
+// Which recovery even applies, given what KIND of datastore this is and where
+// it lives. Its own function because "is it down?" and "what do you do about
+// it?" are separate decisions, and this is the one that grows a branch every
+// time a new datastore shape shows up.
+//
+// It follows the ingress-unwired precedent — the whole point of that reason was
+// carrying the exact fix instead of a bare complaint — but deliberately stops
+// short of naming a COMMAND. What an operator runs to start a datastore is a
+// property of the VM image, not of this module; naming one this module cannot
+// know is installed would be a confident lie on an amber card. What IS knowable,
+// and what actually unblocks someone, is which recovery applies and where to act.
+//
+// The `file` branch is not cosmetic: a file database has no server to start, so
+// routing it through the local branch would print the nonsensical "start it".
+function recoveryClause({ shape, local, n } = {}) {
+  if (shape === 'file') {
+    return 'Recover: this is a file database and the file is missing — restore or recreate it on the VM.';
+  }
+  if (local) {
+    return `Recover: start it on VM-${n} — it is declared local, so nothing outside the VM can be at fault.`;
+  }
+  return 'Recover: this is a remote/managed datastore — check the datastore service and the VM\'s network path. There is nothing local to start.';
+}
+
+// The single source for the `datastore-unreachable` reason string, mirroring
+// fleet-public-url.js::ingressUnwiredReason. Named and exported so the card
+// reason and any future log line cannot drift apart — the drift that a
+// template literal inlined at its one call site invites the moment a second
+// caller appears.
+function datastoreUnreachableReason({ type, target, shape, local, lastError, n } = {}) {
+  const what = `${type || 'declared'} datastore${target ? ` at ${target}` : ''}`;
+  const why = lastError ? ` (${lastError})` : '';
+  return `datastore-unreachable: the ${what} is not answering${why}. ${recoveryClause({ shape, local, n })}`;
+}
+
+module.exports = { classifyDatastoreHealth, recoveryClause, datastoreUnreachableReason };

package/npm/fleet-memory.js

@@ -290,8 +290,16 @@ function restoreFromSnapshot({ snapshot, maxAgeMs, nowIso, sidecarKeys } = {}) {
  *  Degrades to 'cgroup=unavailable' rather than printing zeros off-cgroup, so a
  *  laptop log cannot be misread as a cgroup at 0MB.
  *
+ *  `detachedWiringCount` — when supplied — appends `tails=N`, which is what makes
+ *  the RSS/cgroup gap ATTRIBUTABLE rather than merely visible. On 2026-08-11 the
+ *  cgroup read 2154MB against a 96MB RSS and the whole diagnosis was "those ~2GB
+ *  are this process's own transient add children, not a leak". `RSS=96MB
+ *  cgroup=2154MB tails=4` reads as a batch draining on its own; `RSS=1300MB
+ *  cgroup=1400MB tails=0` reads as a genuine leak. Omitted (the pre-existing
+ *  callers, and any host with no tail accounting) prints exactly as before.
+ *
  *  Pure; no I/O. */
-function formatMemoryText({ rssBytes, memoryCurrent, memoryHigh } = {}) {
+function formatMemoryText({ rssBytes, memoryCurrent, memoryHigh, detachedWiringCount } = {}) {
   const mb = (b) => (Number(b) / 1024 / 1024).toFixed(0);
   const current = Number(memoryCurrent);
   const high = Number(memoryHigh);
@@ -308,6 +316,8 @@ function formatMemoryText({ rssBytes, memoryCurrent, memoryHigh } = {}) {
   } else {
     parts.push('cgroup=unavailable');
   }
+  const tails = Number(detachedWiringCount);
+  if (Number.isFinite(tails) && tails >= 0) parts.push(`tails=${tails}`);
   return parts.join(' ');
 }
 
@@ -323,11 +333,26 @@ function formatMemoryText({ rssBytes, memoryCurrent, memoryHigh } = {}) {
  *  protecting. The dashboard's own self-update counts, being a heavy job by any
  *  other name.
  *
- *  Pure; no I/O — the caller passes state.jobs / state.dashboardUpdate. */
-function hasJobInFlight({ jobs, dashboardUpdate } = {}) {
+ *  `detachedWiringCount` is the THIRD source of busy, and the one this guard was
+ *  blind to: an Add settles at container-healthy while its detached wire-add-tail
+ *  keeps spawning gcloud children for another 5-10 min in the SAME cgroup. Judging
+ *  "safe to restart" off `state.jobs` alone reported no job in flight while that
+ *  work was live — on 2026-08-11 the escalation crossed the restart threshold at
+ *  86% of memory.high and the only thing that held it back was an unrelated job
+ *  happening to still be `running`. Had it settled thirty seconds earlier the
+ *  dashboard would have restarted itself mid-batch and orphaned four adds, which
+ *  is precisely the failure class the detached-provision work exists to prevent.
+ *  Omitting the key behaves exactly as before, so every current caller is
+ *  unaffected.
+ *
+ *  Pure; no I/O — the caller passes state.jobs / state.dashboardUpdate and the
+ *  live-tail count. */
+function hasJobInFlight({ jobs, dashboardUpdate, detachedWiringCount } = {}) {
   const busy = (j) => !!j && (j.state === 'running' || j.state === 'recovering');
   const anyJob = Object.values((jobs && typeof jobs === 'object') ? jobs : {}).some(busy);
-  return anyJob || !!(dashboardUpdate && dashboardUpdate.state === 'running');
+  const tails = Number(detachedWiringCount);
+  const anyTail = Number.isFinite(tails) && tails > 0;
+  return anyJob || anyTail || !!(dashboardUpdate && dashboardUpdate.state === 'running');
 }
 
 /** Should this escalation level be announced to the journal?

package/npm/fleet-queue.js

@@ -126,9 +126,150 @@ function reconcileQueueDraft(draftOrder, liveOrder) {
   return out;
 }
 
+// Consecutive failed reads before the panel stops trusting its mirror. At the
+// default QUEUE_POLL_MS of 5000 this is ~15s of sustained failure — long enough
+// that the ordinary 20s-timeout blip the next tick clears only ever reaches
+// 'degraded', short enough that a real credential outage is flagged in seconds.
+// Named rather than inlined so the verdict and the tooltip copy read the same
+// number from one place.
+const QUEUE_STALE_AFTER_FAILURES = 3;
+
+/** Merge one commit-queue poll result over the previous memo.
+ *
+ *  THE RULE: a failed read RETAINS the previous `entries` AND the previous
+ *  `readAt`, and records `error`. Retaining the entries is deliberate — a stale
+ *  order beats a blank panel for an operator mid-triage. Leaving `readAt`
+ *  untouched is what makes the staleness legible: it is the ONLY signal that
+ *  distinguishes a frozen view from a live one.
+ *
+ *  Advancing `readAt` on a failure is precisely the bug this exists to prevent.
+ *  On 2026-08-14 /etc/codeyam/git-credentials on the operator host went to 0
+ *  bytes and every origin git operation began failing; the queue panel went on
+ *  naming VM-5 as HEAD for 3.5 hours after VM-5 had released, while the real
+ *  queue was VM-2 -> VM-8 -> VM-4. Nothing on the page distinguished it from
+ *  live. This is the same lesson mergeDashboardRevision records from
+ *  2026-07-31, applied to the second poller.
+ *
+ *  A previous `readAt` of null (no successful read has EVER happened) stays
+ *  null and is not coerced to a timestamp — "never read" and "read a moment
+ *  ago" must stay distinguishable, the same reason mergeDashboardRevision
+ *  refuses to push a null `behind` through Number().
+ *
+ *  Success is the absence of `error`. Pure; no I/O. */
+function mergeQueuePoll({ prev, entries, readAt, error } = {}) {
+  const base = (prev && typeof prev === 'object') ? prev : {};
+  const str = (v) => ((typeof v === 'string' && v) ? v : null);
+  const prevEntries = Array.isArray(base.entries) ? base.entries : [];
+  const prevReadAt = str(base.readAt);
+  const prevFailures = (typeof base.consecutiveFailures === 'number'
+    && Number.isFinite(base.consecutiveFailures) && base.consecutiveFailures >= 0)
+    ? base.consecutiveFailures : 0;
+  const err = str(error);
+  if (err) {
+    return {
+      entries: prevEntries,
+      readAt: prevReadAt,
+      error: err,
+      consecutiveFailures: prevFailures + 1,
+    };
+  }
+  return {
+    entries: Array.isArray(entries) ? entries : [],
+    readAt: str(readAt) || prevReadAt,
+    error: null,
+    consecutiveFailures: 0,
+  };
+}
+
+/** What does the current queue memo mean for the operator?
+ *
+ *  Levels:
+ *    'fresh'    — the last read succeeded. Render exactly as before; every
+ *                 control stays live.
+ *    'degraded' — erroring, but under QUEUE_STALE_AFTER_FAILURES consecutive
+ *                 failures. A blip. Noted quietly, controls stay live — a
+ *                 single 20s-timeout hiccup that the next tick clears must not
+ *                 cry wolf or lock the operator out of their own queue.
+ *    'stale'    — erroring at or past the threshold. The mirror is not to be
+ *                 trusted and writes computed against it are blocked.
+ *    'unknown'  — erroring and NO read has ever succeeded (the boot window with
+ *                 broken credentials). Worth saying out loud: an empty-looking
+ *                 queue here means "we cannot see the queue", not "go".
+ *
+ *  AGE IS DELIBERATELY NOT AN INPUT. A genuinely quiet queue is not a broken
+ *  one, so escalation keys on consecutive read FAILURES only; age is carried by
+ *  projectQueueFreshness purely to phrase the message ("last read 3h 12m ago").
+ *  An hours-old `readAt` with no error is 'fresh' and must stay that way. Taking
+ *  a clock here would imply otherwise, so the signature omits one — the same
+ *  take-only-what-you-use shape as classifyDashboardStaleness.
+ *
+ *  Pure; no I/O. */
+function classifyQueueFreshness({ readAt, error, consecutiveFailures } = {}) {
+  if (!(typeof error === 'string' && error)) return 'fresh';
+  if (!(typeof readAt === 'string' && readAt)) return 'unknown';
+  const failures = (typeof consecutiveFailures === 'number' && Number.isFinite(consecutiveFailures))
+    ? consecutiveFailures : 0;
+  return failures >= QUEUE_STALE_AFTER_FAILURES ? 'stale' : 'degraded';
+}
+
+/** The `/data` view of the queue memo, with the freshness VERDICT resolved
+ *  server-side.
+ *
+ *  The panel is then a pure renderer. Two consumers re-deriving "is this stale"
+ *  from a raw timestamp would drift, and `public/index.html` is an inline
+ *  browser script with no module boundary — any decision left in it could only
+ *  ever be source-scan tested, which is how it ships bugs green. Same split, and
+ *  same reason, as projectDashboardRevision.
+ *
+ *  `now` is injected (epoch ms) rather than read from the clock so the
+ *  projection stays pure and its tests deterministic. `ageSec` is null when no
+ *  successful read has happened or no clock was supplied.
+ *
+ *  Pure; no I/O. */
+function projectQueueFreshness(memo = {}, now = null) {
+  const at = (typeof memo.readAt === 'string' && memo.readAt) ? Date.parse(memo.readAt) : NaN;
+  const clock = (typeof now === 'number' && Number.isFinite(now)) ? now : null;
+  const ageSec = (Number.isFinite(at) && clock !== null)
+    ? Math.max(0, Math.floor((clock - at) / 1000))
+    : null;
+  return { ...memo, level: classifyQueueFreshness(memo), ageSec };
+}
+
+/** The operator-facing reason a queue WRITE must be refused, or null when writes
+ *  are allowed.
+ *
+ *  A write computed against a mirror known to be frozen is never the right
+ *  action, and the silent-no-op outcome is worse than a refusal: a Release
+ *  fires at a uuid that no longer holds the head, reports "released head
+ *  bb65addf", changes nothing, and leaves the real head held. A reorder is
+ *  worse still — computeReorderTargets validates the posted order against the
+ *  very mirror that is wrong, so a doomed reorder looks perfectly valid.
+ *
+ *  The verbatim git error is interpolated rather than summarised to "poll
+ *  failed". On 2026-08-14 the entire recovery was legible from one line —
+ *  `could not read Username for 'https://github.com'` — and truncating it would
+ *  have cost the same 3.5 hours.
+ *
+ *  Lives here rather than in server.js so the refusal COPY is directly
+ *  assertable: server.js has top-level side effects on require, so a message
+ *  built there could only ever be source-scan tested. Pure; no I/O. */
+function queueWriteBlockReason(memo = {}) {
+  const level = classifyQueueFreshness(memo);
+  if (level !== 'stale' && level !== 'unknown') return null;
+  const why = (typeof memo.error === 'string' && memo.error) ? ` (${memo.error})` : '';
+  return level === 'unknown'
+    ? `commit queue has never been read successfully${why} — cannot act on an unknown queue`
+    : `commit queue read is failing${why} — the displayed order cannot be trusted; fix the read before changing the queue`;
+}
+
 module.exports = {
   decideAutoReleaseGoneHead,
   computeReorderTargets,
   nudgeQueueOrder,
   reconcileQueueDraft,
+  mergeQueuePoll,
+  classifyQueueFreshness,
+  projectQueueFreshness,
+  queueWriteBlockReason,
+  QUEUE_STALE_AFTER_FAILURES,
 };