@codeyam-editor/codeyam-editor 0.1.8 → 0.1.9

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-revision.js

@@ -97,8 +97,116 @@ function projectDashboardRevision(memo = {}) {
   return { ...memo, level: classifyDashboardStaleness(memo) };
 }
 
+/** Is the CLI BINARY the dashboard shells out to as current as the checkout?
+ *
+ *  The sibling question to `classifyDashboardStaleness`, and until 2026-08-21
+ *  nobody was asking it. The operator host's checkout self-updates hourly while
+ *  the `codeyam-editor` binary beside it never did, so the control plane drifted
+ *  a little further behind every hour until a CLI-visible schema change broke it
+ *  outright: an `editor-shipped` glossarySkip reason merged at 05:12 could not be
+ *  parsed by a binary built 2026-07-19, and every CLI invocation the dashboard
+ *  made died at config load.
+ *
+ *  Why this needs its own signal rather than riding on `behind`: NOTHING that
+ *  normally means "down" was down. `dashboard-bes` stayed HEALTHY, `/healthz`
+ *  answered in 0.8 ms, all 14 VMs read reachable, and the checkout itself was at
+ *  tip — so a commits-behind chip reading 0 was correct AND useless. Two
+ *  artifacts deploy on this host and only one of them was ever measured.
+ *
+ *  Compares git SHAs, not versions: the published artifact stamps the source
+ *  commit it was built from (`org.opencontainers.image.revision`), and a semver
+ *  moves far more slowly than the schema does — `0.1.7` was both the working and
+ *  the broken binary.
+ *
+ *  Levels, deliberately the same four words `classifyDashboardStaleness` uses so
+ *  the two chips read as one family:
+ *    'stale'     — both SHAs known and different. The CLI predates the checkout;
+ *                  a schema change away from empty panels.
+ *    'current'   — both known and equal.
+ *    'unknown'   — cannot compare AND something failed. Includes the incident's
+ *                  own worst case: a binary too stale to answer what it is fails
+ *                  the very read that would have proven it stale, so "I could not
+ *                  tell" must never round down to 'current'.
+ *    'unchecked' — cannot compare and nothing failed (the boot window before the
+ *                  first slow-cycle read). Renders nothing.
+ *
+ *  Pure; no I/O. */
+function classifyBinaryStaleness({ installed, tip, error } = {}) {
+  const sha = (v) => ((typeof v === 'string' && v.trim()) ? v.trim() : null);
+  const a = sha(installed);
+  const b = sha(tip);
+  if (a === null || b === null) return error ? 'unknown' : 'unchecked';
+  return a === b ? 'current' : 'stale';
+}
+
+/** The `/data` view of the binary memo, with the verdict resolved server-side.
+ *
+ *  Same split, for the same reason, as `projectDashboardRevision`: `server.js`
+ *  has top-level side effects on require, so a projection defined there can
+ *  never be executed by a test and ships its bugs green.
+ *
+ *  Pure; no I/O. */
+function projectBinaryRevision(memo = {}) {
+  return { ...memo, level: classifyBinaryStaleness(memo) };
+}
+
+/** Why did the CLI shell-out fail — and is it the nameable one?
+ *
+ *  The 2026-08-21 outage surfaced ONLY as a truncated `queueFreshness.error`
+ *  reading `" Fix the file and re-run."` — two lines of tail from a multi-line
+ *  diagnostic, with the sentence naming the cause among the lines that got cut.
+ *  An operator looking at empty Queue and Plans panels had to infer that the CLI
+ *  was broken at all, and nothing on the page said so.
+ *
+ *  So classify the FULL stderr before it is tailed. Two phrasings both mean
+ *  "this binary cannot read this checkout's config", and BOTH must match:
+ *  the current wording, and the pre-2026-08-19 `Fix the file and re-run` — which
+ *  is not legacy trivia but the single most likely text to see here, because the
+ *  binary emitting it is by definition an old one.
+ *
+ *  Levels:
+ *    'ok'      — no error.
+ *    'config'  — the binary cannot read `.codeyam/editor.json`. Almost always a
+ *                CLI older than the checkout; the file is usually correct and
+ *                editing it is the wrong move, which is why the recovery text
+ *                says so out loud.
+ *    'failing' — the CLI failed for some other reason (git credentials, a
+ *                timeout). Still worth showing, still not this condition.
+ *
+ *  Pure; no I/O. */
+function classifyCliFailure(text) {
+  const s = (typeof text === 'string') ? text : '';
+  if (!s.trim()) return 'ok';
+  if (/cannot read [^\n]*editor\.json/i.test(s) || /Fix the file and re-run/i.test(s)) return 'config';
+  return 'failing';
+}
+
+/** The `/data` view of CLI health, with the verdict and its recovery resolved
+ *  server-side — so the panel renders a named condition instead of leaving the
+ *  operator to infer one from a blank list.
+ *
+ *  `recovery` is only populated for 'config', where the right action is
+ *  genuinely non-obvious and the intuitive one (edit the file) is wrong.
+ *
+ *  Pure; no I/O. */
+function projectCliHealth({ error } = {}) {
+  const level = classifyCliFailure(error);
+  return {
+    level,
+    broken: level !== 'ok',
+    error: (typeof error === 'string' && error.trim()) ? error.trim() : null,
+    recovery: level === 'config'
+      ? 'The codeyam-editor binary is older than the checkout it is reading — do NOT edit .codeyam/editor.json. Refresh the binary: scripts/operator/refresh-operator-repo.sh'
+      : null,
+  };
+}
+
 module.exports = {
   mergeDashboardRevision,
   classifyDashboardStaleness,
   projectDashboardRevision,
+  classifyBinaryStaleness,
+  projectBinaryRevision,
+  classifyCliFailure,
+  projectCliHealth,
 };

package/npm/fleet-run-setup.js

@@ -0,0 +1,66 @@
+'use strict';
+// Pure builder for the fleet dashboard's in-container `npm run setup` snippet
+// (scripts/operator/fleet-dashboard/server.js requires this). String
+// construction only — no I/O, no child processes — so the snippet's CONTENT is
+// unit-testable in isolation (npm/fleet-run-setup.test.js), exactly like
+// fleet-env.js. server.js itself has no unit-test harness, which is why this
+// lives here rather than inline in actionRunSetup.
+//
+// Named for the run-setup ACTION, not "setup" generally: npm/fleet-setup-steps.js
+// already exists and is a different concern (it is bound as `fsetup` in
+// server.js, so a `fleet-setup.js` here collided on both the filename and the
+// import identifier).
+
+// Seconds before a prompting or hanging setup is killed. Matches the
+// bootstrap's SETUP_TIMEOUT default so both paths time-box identically; the
+// dashboard job budget (11 min) is deliberately larger, to cover this plus ssh.
+const SETUP_TIMEOUT_SECS = 600;
+
+// How many trailing lines of setup's own output ride on the CY_DEGRADED line.
+// The marker is parsed line-by-line by the job-output reader, so these are
+// flattened onto one line — keep it small enough to stay readable on a card.
+const FAILURE_TAIL_LINES = 3;
+
+/**
+ * Build the bash snippet that runs the project's `npm run setup` inside VM-n's
+ * container and reports what actually broke.
+ *
+ * The failure line carries the setup command's OWN trailing output. It used to
+ * hardcode "set env (e.g. DATABASE_URL) via Env, then retry Run setup" — a
+ * guess, and on VM-11 (2026-08-26) a wrong one: DATABASE_URL was present in
+ * /workspace/.env the whole time and the real failure was that Postgres was not
+ * installed. The failing script had already printed a precise, actionable
+ * message and the wrapper talked over it, sending the operator to configure env
+ * that was already correct. Report what broke; do not theorize about it.
+ *
+ * Exits 0 even on failure, emitting a `CY_DEGRADED` marker line instead — so
+ * the cause persists on the VM card rather than vanishing as a transient error.
+ *
+ * @param {number|string} n VM number, used only to name the VM in the message.
+ * @returns {string} bash snippet suitable for `inContainer(n, …)`.
+ */
+function buildRunSetupScript(n) {
+  return [
+    'cd /workspace || { echo "no /workspace in container"; exit 1; }',
+    `setup="$(node -p "(require('./package.json').scripts||{}).setup||''" 2>/dev/null || true)"`,
+    'if [ -z "$setup" ]; then echo "no \'setup\' script in package.json — nothing to run"; exit 0; fi',
+    `echo "running 'npm run setup' (script: $setup; non-interactive, ${SETUP_TIMEOUT_SECS}s timeout)"`,
+    // tee so the full output still streams into the job log, while the tail is
+    // retained for the CY_DEGRADED line. ${PIPESTATUS[0]} is setup's exit code,
+    // not tee's — without it a failing setup would report success.
+    'log="$(mktemp)"',
+    `timeout ${SETUP_TIMEOUT_SECS} npm run setup </dev/null 2>&1 | tee "$log"; rc=\${PIPESTATUS[0]}`,
+    'if [ "$rc" -ne 0 ]; then',
+    `  why="$(grep -v '^[[:space:]]*$' "$log" | tail -n ${FAILURE_TAIL_LINES} | tr '\\n' '|' | sed 's/|$//; s/|/ | /g')"`,
+    `  [ -n "$why" ] || why="(no output — likely killed by the ${SETUP_TIMEOUT_SECS}s timeout)"`,
+    `  echo "CY_DEGRADED 'npm run setup' failed (exit $rc) on VM-${n}, in the container as root: $why"`,
+    'fi',
+    'rm -f "$log"',
+  ].join('\n');
+}
+
+module.exports = {
+  buildRunSetupScript,
+  SETUP_TIMEOUT_SECS,
+  FAILURE_TAIL_LINES,
+};

package/npm/fleet-session-activity.js

@@ -0,0 +1,162 @@
+'use strict';
+// Pure session-activity classification and stickiness for the Fleet Dashboard
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the raw
+// per-poll `hasSession` / `sessionIdleSeconds` the editor's /api/session-info
+// reports, decide what the card renders and what the maintenance gate reads. No
+// I/O — server.js does the polling and threads the state.
+//
+// The problem this fixes (observed live 2026-08-30, VMs 1 and 9): `hasSession`
+// is a bare boolean with no notion of activity age, so a session wedged two days
+// ago is indistinguishable from one someone is actively driving. Both hold a
+// live agent process, so both report `true`, and every refresh was refused with
+// the same `BLOCKED: VM-N has a live session`. The only way through was
+// `--force` — the same flag used to step over genuinely live work — which is how
+// `--force` stops meaning anything. `hasSession` also flapped `false` → `true`
+// between polls minutes apart, so even an operator watching the card could not
+// tell the two apart by eye.
+//
+// Two independent fixes live here, deliberately separate:
+//
+//   debounceHasSession    — stops the flap. A value that alternates between
+//                           adjacent polls is not a usable gate input at any
+//                           age, so this is fixed first and on its own.
+//   classifySessionActivity — adds the age dimension the boolean lacks.
+//
+// Asymmetric by design, mirroring npm/fleet-broker-debounce.js: only the flip to
+// `false` (no session) is debounced. `true` takes effect immediately, because
+// the dangerous error is proceeding over live work — we never delay RAISING the
+// block, only delay clearing it. An unreachable editor (`hasSession` neither
+// true nor false) proves nothing and breaks a pending clear-streak rather than
+// advancing it, the same "absence of evidence is never down" rule
+// fleet-broker-status.js follows.
+//
+// State shape carried across polls: { hasSession, clearStreak, lastConfirmed }.
+//   hasSession    — the debounced value the card and the gate read this poll.
+//   clearStreak   — how many consecutive raw `false` polls we have seen.
+//   lastConfirmed — the last raw boolean we actually proved; held during a
+//                   pending (sub-threshold) clear-streak so the gate keeps
+//                   blocking through a blip.
+
+// ~9s at the dashboard's 3s poll cadence, matching DOWN_DEBOUNCE_THRESHOLD in
+// npm/fleet-broker-debounce.js. Named so retuning is a one-line edit.
+const CLEAR_DEBOUNCE_THRESHOLD = 3;
+
+// A full day of zero on-disk activity. Chosen to sit well clear of the longest
+// legitimate idle a live session has: an agent parked at a confirmation gate
+// overnight is waiting for its operator, not wedged, and forcing past it costs
+// them their place. The observed wedge was two days cold, so this catches it
+// with a wide margin rather than racing it.
+const STALE_SESSION_IDLE_SECONDS = 24 * 60 * 60;
+
+function debounceHasSession(prev, rawHasSession, opts) {
+  const threshold = (opts && opts.threshold) || CLEAR_DEBOUNCE_THRESHOLD;
+  const lastConfirmed = prev ? prev.lastConfirmed : undefined;
+
+  // Confirmed present: a session is live right now. Render immediately, reset
+  // the streak, and remember it as the last confirmed value.
+  if (rawHasSession === true) {
+    return { hasSession: true, clearStreak: 0, lastConfirmed: true };
+  }
+
+  // Neither true nor false — the editor was unreachable or answered no
+  // session-info at all, so we proved nothing. Never let that advance the
+  // clear-streak toward "no session"; hold what we last proved.
+  if (rawHasSession !== false) {
+    return {
+      hasSession: lastConfirmed === true,
+      clearStreak: 0,
+      lastConfirmed,
+    };
+  }
+
+  // Raw `false`: only believed once it persists. Count the streak.
+  const clearStreak = (prev ? prev.clearStreak : 0) + 1;
+  if (clearStreak >= threshold) {
+    return { hasSession: false, clearStreak, lastConfirmed: false };
+  }
+  // Pending (sub-threshold) clear: hold the last confirmed value, so a single
+  // dropped poll cannot open a window for maintenance to step over live work.
+  return {
+    hasSession: lastConfirmed === true,
+    clearStreak,
+    lastConfirmed,
+  };
+}
+
+// Classify a VM's session into the verdict the card renders and the maintenance
+// gate branches on:
+//
+//   'none'    — no session at all. Maintenance proceeds; nothing to step over.
+//   'active'  — a session with recent activity. Blocks exactly as it does
+//               today; only `--force` steps over it.
+//   'stale'   — a session idle beyond the threshold. Still blocks, but is
+//               eligible for the narrower stale-session override.
+//   'unknown' — a session whose age could not be determined, because the editor
+//               is too old to report `sessionIdleSeconds` or could read no
+//               evidence. Treated as POSSIBLY LIVE and blocks like 'active'.
+//
+// That last mapping is the load-bearing one. An unknown age must never resolve
+// toward 'stale': the override exists to skip work nobody is doing, and handing
+// it out on absent evidence would step over live sessions on exactly the VMs
+// whose reporting is broken. `classify_vm`'s `reachable` tri-state in
+// scripts/operator/refresh-client-vm-editor.sh is the cautionary precedent —
+// collapsing its unknown to a definite verdict once refused all 13 VMs at once
+// on evidence that had never been gathered.
+function classifySessionActivity(input) {
+  const hasSession = !!(input && input.hasSession);
+  if (!hasSession) return 'none';
+
+  const idleSeconds = input.idleSeconds;
+  if (typeof idleSeconds !== 'number' || !Number.isFinite(idleSeconds)) {
+    return 'unknown';
+  }
+
+  const threshold =
+    typeof input.thresholdSeconds === 'number' && Number.isFinite(input.thresholdSeconds)
+      ? input.thresholdSeconds
+      : STALE_SESSION_IDLE_SECONDS;
+
+  return idleSeconds >= threshold ? 'stale' : 'active';
+}
+
+// Render an idle age as the short human string the card and the refusal message
+// both show ("2d", "5h", "3m", "12s"). Returns 'unknown' when there is no age,
+// so a caller never has to decide how to word an absent value — and so the
+// operator sees the word rather than a blank that reads as zero.
+function formatIdleAge(idleSeconds) {
+  if (typeof idleSeconds !== 'number' || !Number.isFinite(idleSeconds) || idleSeconds < 0) {
+    return 'unknown';
+  }
+  const s = Math.floor(idleSeconds);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+
+// Does this VM read as WEDGED rather than merely busy? A card showing
+// `status: building` with no feature named and the workflow still at step 1 is
+// describing a session that never got started, and when its last on-disk
+// activity is also days old there is nothing left that "busy" explains. This is
+// the combination VMs 1 and 9 presented, and the card rendered it as work in
+// progress.
+//
+// Deliberately narrower than `classifySessionActivity(...) === 'stale'`: a
+// long-running step that is genuinely mid-feature is stale-but-working, and
+// labelling it wedged would train operators to ignore the label.
+function isWedgedShape(input) {
+  if (!input) return false;
+  if (classifySessionActivity(input) !== 'stale') return false;
+  if (input.status !== 'building') return false;
+  if (input.feature) return false;
+  return input.step === 1 || input.step === undefined || input.step === null;
+}
+
+module.exports = {
+  debounceHasSession,
+  classifySessionActivity,
+  formatIdleAge,
+  isWedgedShape,
+  CLEAR_DEBOUNCE_THRESHOLD,
+  STALE_SESSION_IDLE_SECONDS,
+};