@codeyam-editor/codeyam-editor 0.1.2 → 0.1.3

package/npm/editor-dev.js

@@ -33,7 +33,6 @@ const {
   restartServer,
   waitForPort,
   ensureBinary,
-  isSelfHostTarget,
   rootDir,
   killChildProcess,
   readMergedEditorConfig,
@@ -90,28 +89,27 @@ function buildBinary() {
 
 /**
  * Decide whether the dev wrapper should rebuild the Rust binary (and the UI,
- * for the launcher path) before forwarding to it. Pure: takes injected cwd /
- * repoRoot / env so the four-way decision is testable without spawning cargo
- * or reading process.env.
+ * for the launcher path) before forwarding to it. The answer is always yes:
+ * `codeyam-editor-dev` ALWAYS rebuilds before running. Running fresh source is
+ * the entire purpose of the dev wrapper — if a developer wants a frozen tool
+ * that never rebuilds, the cargo-installed `codeyam-editor` binary is exactly
+ * that.
  *
- * The wrapper rebuilds in two cases:
- *   - The target IS the editor repo itself (developing the editor on its
- *     own checkout). This is the canonical self-host case.
- *   - `CODEYAM_DEV_REBUILD=1` is explicitly set (the documented opt-in for
- *     "editing the editor source while running it against an external client
- *     project", named in editor-dev.js's earlier history).
+ * `cargo build` is idempotent: a sub-second no-op that does not relink when
+ * nothing changed. So always-building costs nothing for a developer who only
+ * uses the editor as a tool against their own app (the binary never changes →
+ * the server-side stale-binary watcher never fires → zero mid-session
+ * restarts), and produces a rebuild+restart only when editor source actually
+ * changed — which is exactly when the developer wants the new code live.
  *
- * Otherwise — the common case where a developer uses the editor as a tool
- * against their own app — the wrapper skips the rebuild entirely. The
- * existing binary runs unchanged, and the server-side stale-binary watcher
- * (also gated on self-host) never SIGUSR1's. The combined effect is what the
- * plan calls out: an external-project session is never disrupted by a bare
- * commit, a fleet rebase, or any other event that would have relinked the
- * binary without changing what runs.
+ * The injected cwd / repoRoot / env are retained so the contract — "rebuild
+ * regardless of where you run it or what env is set" — is demonstrable in a
+ * unit test across the dimensions that used to gate the decision (self-host
+ * vs. external project, `CODEYAM_DEV_REBUILD` set or not). They no longer
+ * influence the result.
  */
-function shouldRebuildOnPassthrough({ cwd, repoRoot, env }) {
-  if (env.CODEYAM_DEV_REBUILD === "1") return true;
-  return isSelfHostTarget(cwd, repoRoot);
+function shouldRebuildOnPassthrough() {
+  return true;
 }
 
 /**
@@ -154,6 +152,12 @@ function hasStartCommand(mergedConfig) {
  * can migrate from the preserved classification, so auto-running init would
  * strand them. The Rust-side `start_preflight` stays the safety net for
  * direct `codeyam-editor start` calls; this launcher composes init + start.
+ *
+ * Intentional divergence (improve39): this launcher auto-inits ALL `none`
+ * projects (empty or existing-source); the Rust `start_preflight` now
+ * auto-inits only the EMPTY case and still bails (exit 2) on existing-source.
+ * That gap is pre-existing and deliberate — the dev launcher is a local
+ * convenience, not the direct-`start` contract.
  */
 function planPreflightAction(classification) {
   if (classification.kind === "legacy") {
@@ -181,16 +185,22 @@ function planPreflightAction(classification) {
  *
  *   action !== "init"          → null   (modern: proceed, no banner;
  *                                         legacy already bailed earlier)
- *   action "init", wasEmpty    → /codeyam-editor scaffold-from-scratch
+ *   action "init", wasEmpty    → greenfield message. /codeyam-editor is driven
+ *                                from inside the browser UI, never hand-invoked,
+ *                                so the wording follows `browserOpened`: if the
+ *                                launcher actually opened a tab, promise it; if
+ *                                not (e.g. --restart attach), point at the URL
+ *                                so the user still has a path forward. The
+ *                                banner must never promise a tab that didn't
+ *                                appear.
  *   action "init", !wasEmpty   → /codeyam-onboard migrate-existing
  */
-function postLaunchInitBanner({ preflightAction, wasEmpty }) {
+function postLaunchInitBanner({ preflightAction, wasEmpty, browserOpened, url }) {
   if (preflightAction !== "init") return null;
   if (wasEmpty) {
-    return (
-      "\nInitialized .codeyam/ in this directory. Open Claude Code here and " +
-      "run `/codeyam-editor` to scaffold a new project from scratch."
-    );
+    return browserOpened
+      ? "\nA browser window is opening where you can begin your project."
+      : `\nOpen ${url} in your browser to begin your project.`;
   }
   return (
     "\nInitialized .codeyam/ in this directory. To populate scenarios, " +
@@ -198,6 +208,43 @@ function postLaunchInitBanner({ preflightAction, wasEmpty }) {
   );
 }
 
+/**
+ * Decide whether the launcher should open a browser tab to the editor UI.
+ * Pure (no fs, no spawn) so the gating is unit-testable without a binary,
+ * mirroring `planPreflightAction` / `postLaunchInitBanner`.
+ *
+ * The browser open belongs ONLY on a genuine cold start — bringing the
+ * editor server up fresh against a not-yet-running port. Two cases must
+ * NOT re-pop a tab, because one is presumably already open:
+ *
+ *   shouldRestart → false   `--restart` (rebuild-self, restart-server routed
+ *                            through this wrapper, a manual --restart) tears
+ *                            down and respawns a server the user is already
+ *                            looking at. Re-opening spams tabs — the reported
+ *                            symptom. Mirrors the Rust `--no-open` restart
+ *                            spawn in restart_server.rs.
+ *   wasRunning   → false     `ensureServer` attached to an already-running
+ *                            same-project server (returned null) — no fresh
+ *                            process, so no new tab.
+ *
+ * Only a fresh spawn on a cold start (neither restart nor attach) opens the
+ * UI, matching the Rust `no_open`-gated `open_url` in start.rs.
+ *
+ *   freshInit    → true      A brand-new empty project that was just init'd
+ *                            this run. The entire greenfield onboarding flow
+ *                            is driven from inside the editor UI, and a
+ *                            project that didn't exist a moment ago has no
+ *                            pre-existing tab for the --restart tab-spam guard
+ *                            to protect. So a fresh init opens regardless of
+ *                            `shouldRestart` — UNLESS we merely attached to an
+ *                            already-running server (`wasRunning`), which
+ *                            implies a tab is already up.
+ */
+function shouldOpenBrowser({ shouldRestart, wasRunning, freshInit }) {
+  if (freshInit) return !wasRunning;
+  return !shouldRestart && !wasRunning;
+}
+
 module.exports = {
   hasSubcommand,
   buildBinary,
@@ -206,24 +253,19 @@ module.exports = {
   hasStartCommand,
   planPreflightAction,
   postLaunchInitBanner,
+  shouldOpenBrowser,
 };
 
 if (require.main === module) {
   // --- Passthrough mode: build binary, then forward to it ---
   if (hasSubcommand()) {
-    // Only rebuild when the target IS the editor repo itself, or when the
-    // developer has explicitly opted into the "edit editor against external
-    // project" workflow via CODEYAM_DEV_REBUILD=1. On any other project the
-    // editor binary is a fixed tool and a `cargo build` here ripples into a
-    // stale-binary SIGUSR1 re-exec that resets the user's session for no
-    // reason. `ensureBinary()` still builds once if no binary exists at all.
-    if (
-      shouldRebuildOnPassthrough({
-        cwd: process.cwd(),
-        repoRoot: rootDir,
-        env: process.env,
-      })
-    ) {
+    // Always rebuild before forwarding — running fresh source is the whole
+    // point of the dev wrapper. `cargo build` is a sub-second no-op when
+    // nothing changed (no relink → the server-side stale-binary watcher never
+    // fires), and relinks only when editor source actually changed, which is
+    // exactly when the developer wants the new code live. `ensureBinary()`
+    // still builds once if no binary exists at all.
+    if (shouldRebuildOnPassthrough()) {
       enforceFreshBinary(buildBinary(), { action: "run editor commands" });
     }
     const binary = ensureBinary();
@@ -300,19 +342,14 @@ if (require.main === module) {
       const projectMerged = readMergedEditorConfig(projectDir);
       const appPort = resolveLauncherPort(undefined, projectMerged.port, 3000);
 
-      // Same gate as the passthrough path: only rebuild the Rust binary +
-      // UI when the launcher target IS the editor repo itself, or when
-      // CODEYAM_DEV_REBUILD=1 is explicitly set. Launching the editor
-      // against an external project must not relink the binary — the
-      // server-side stale-binary watcher would otherwise SIGUSR1-restart
-      // the freshly-launched server immediately. `ensureBinary()` still
+      // Always rebuild the Rust binary + UI before launching — same contract
+      // as the passthrough path. The build runs BEFORE the server (re)starts
+      // below, so the new server records its start time after the relink and
+      // the stale-binary watcher reads it as fresh (no immediate SIGUSR1). A
+      // no-op `cargo build` (nothing changed) doesn't relink, so an external
+      // client-project launch is never disrupted. `ensureBinary()` still
       // builds once if no binary exists.
-      const shouldRebuildLaunch = shouldRebuildOnPassthrough({
-        cwd: projectDir,
-        repoRoot: rootDir,
-        env: process.env,
-      });
-      if (shouldRebuildLaunch) {
+      if (shouldRebuildOnPassthrough()) {
         enforceFreshBinary(buildBinary(), {
           action: "run editor commands",
           continueVerb: "launching with",
@@ -356,21 +393,65 @@ if (require.main === module) {
         console.error(`Live Preview: http://localhost:${appPort}`);
       }
       console.error(`Project: ${projectDir}`);
-      open(url);
+      // Open the browser only on a genuine cold start. On the --restart path
+      // (rebuild-self, restart-server, manual --restart) and when we attached
+      // to an already-running server, a tab is presumably already open — the
+      // `Editor UI: <url>` line above is the signal. `ensureServer` returns
+      // null when it attached rather than spawning, so that is `wasRunning`.
+      // Exception: a fresh greenfield init (`freshInit`) opens regardless of
+      // --restart, because a project that didn't exist a moment ago has no
+      // pre-existing tab to protect and the onboarding flow lives in the UI.
+      // Compute the open decision once and feed the SAME boolean into the
+      // banner so it can never promise a tab that didn't appear.
+      const freshInit = preflight.action === "init" && wasEmpty;
+      const openedBrowser = shouldOpenBrowser({
+        shouldRestart,
+        wasRunning: serverChild === null,
+        freshInit,
+      });
+      if (openedBrowser) {
+        open(url);
+      }
       const banner = postLaunchInitBanner({
         preflightAction: preflight.action,
         wasEmpty,
+        browserOpened: openedBrowser,
+        url,
       });
       if (banner) {
         console.error(banner);
       }
       const keepAlive = setInterval(() => {}, 60_000);
 
+      // Track launcher-initiated teardown so the unexpected-exit handler below
+      // can tell "we killed it on SIGINT" from "the server died on its own".
+      let tearingDown = false;
+
       process.on("SIGINT", () => {
+        tearingDown = true;
         clearInterval(keepAlive);
         killChildProcess(serverChild);
         process.exit(0);
       });
+
+      // Defense-in-depth against orphaned launchers: if the spawned server
+      // child exits and we did NOT initiate it (SIGINT), clear keepAlive and
+      // exit rather than lingering as a node process holding a dead child
+      // handle. We deliberately do NOT respawn — an exited server should let
+      // the launcher exit cleanly so stale supervisors can't accumulate across
+      // repeated launches. The in-place SIGUSR1 re-exec keeps the SAME pid, so
+      // it does NOT emit an "exit" here and does not trip this path; only a
+      // genuinely dead server does. `serverChild` is null when we attached to
+      // an already-running server (nothing of ours to watch).
+      if (serverChild) {
+        serverChild.on("exit", (code) => {
+          if (tearingDown) {
+            return;
+          }
+          clearInterval(keepAlive);
+          process.exit(code ?? 1);
+        });
+      }
     };
 
     launcherMain();

package/npm/editor.js

@@ -82,17 +82,19 @@ function linkOrCopyBinary(srcPath, dstPath, tmpPath) {
   }
 }
 
-// Install target/debug/codeyam-editor to <cargo_bin>/codeyam-editor
-// atomically (write to tmp in same dir, then rename), and refresh the
-// codeyam-editor-pty-broker hardlink so it points at the new inode.
+// Install target/debug/codeyam-editor to <cargo_bin>/codeyam-editor and
+// the dedicated target/debug/codeyam-editor-pty-broker to
+// <cargo_bin>/codeyam-editor-pty-broker, both atomically (write to a tmp
+// in the same dir, then rename).
 //
-// The PTY broker auto-spawn (control-api/src/pty_broker_startup.rs) always
-// resolves the *installed* path, NOT current_exe() — that was a deliberate
-// fix to prevent a fork-bomb where test binaries spawned themselves. So a
-// fresh `target/debug/codeyam-editor` is not enough; the install path must
-// be refreshed too. Without this, build tabs hang on "Reconnecting..."
-// because the broker daemon errors out (`unrecognized subcommand`) before
-// the UDS socket opens.
+// The broker is now its OWN binary (its own inode), NOT a hardlink of the
+// monolith — a dedicated executable file is what gives the long-lived
+// broker daemon a stable, honest process name on every platform
+// (especially macOS, where hardlink aliases share one vnode name cache
+// and bleed across roles). The PTY broker auto-spawn
+// (control-api/src/pty_broker_startup.rs) prefers this dedicated binary
+// next to the installed monolith; a stale or missing copy is what made
+// build tabs hang on "Reconnecting...", so both must be refreshed here.
 function installBinary() {
   const srcPath = path.join(rootDir, "target", "debug", "codeyam-editor");
   if (!fs.existsSync(srcPath)) {
@@ -101,21 +103,37 @@ function installBinary() {
   }
   const binDir = cargoBinDir();
   const dstPath = path.join(binDir, "codeyam-editor");
-  const linkPath = path.join(binDir, "codeyam-editor-pty-broker");
   const tmpPath = path.join(binDir, `.codeyam-editor.tmp.${process.pid}`);
   console.error(`Installing fresh binary to ${dstPath}...`);
   try {
     fs.mkdirSync(binDir, { recursive: true });
     linkOrCopyBinary(srcPath, dstPath, tmpPath);
-    try {
-      fs.unlinkSync(linkPath);
-    } catch (e) {
-      if (e.code !== "ENOENT") throw e;
-    }
-    fs.linkSync(dstPath, linkPath);
   } catch (err) {
     console.error(`Failed to install binary: ${err.message}`);
     try { fs.unlinkSync(tmpPath); } catch {}
+    return;
+  }
+
+  // Dedicated broker binary — install as its own file (own inode), not a
+  // hardlink. Best-effort: if cargo didn't build it (older workspace),
+  // the broker auto-spawn falls back to the monolith `editor pty-broker
+  // daemon` shim, so a missing broker binary is a warning, not fatal.
+  const brokerSrc = path.join(rootDir, "target", "debug", "codeyam-editor-pty-broker");
+  const brokerDst = path.join(binDir, "codeyam-editor-pty-broker");
+  const brokerTmp = path.join(binDir, `.codeyam-editor-pty-broker.tmp.${process.pid}`);
+  if (!fs.existsSync(brokerSrc)) {
+    console.error(
+      `Note: ${brokerSrc} not found — broker will fall back to the monolith shim. ` +
+      `Run \`cargo build -p codeyam-pty-broker\` to build it.`
+    );
+    return;
+  }
+  console.error(`Installing dedicated broker binary to ${brokerDst}...`);
+  try {
+    linkOrCopyBinary(brokerSrc, brokerDst, brokerTmp);
+  } catch (err) {
+    console.error(`Failed to install broker binary: ${err.message}`);
+    try { fs.unlinkSync(brokerTmp); } catch {}
   }
 }
 

package/npm/fleet-branch.js

@@ -0,0 +1,49 @@
+'use strict';
+// Pure branch-resolution precedence for the fleet dashboard (improve39 A).
+//
+// The dashboard's "current fleet branch" used to go stale: server.js read a
+// baked process.env.BRANCH (set once by the launchd plist at install time) and
+// a hardcoded 'editor-improvements-30' literal, so a `git checkout` to a new
+// fleet branch on the laptop was invisible until the operator re-ran
+// install-launchd-agents.sh (which then risked taking the dashboard down — the
+// (B) half of improve39). This module makes the resolution RULE a pure,
+// unit-tested function (npm/fleet-branch.test.js); server.js owns the I/O — the
+// execSync git read and the short-TTL memo on the ~3s /data poll path.
+//
+// Precedence: explicit env override -> live git HEAD -> fallback sentinel.
+// An operator can still pin a branch with BRANCH=... in the plist/env, but with
+// no pin the dashboard tracks the laptop checkout's live HEAD, so a branch bump
+// is just a `git checkout` — no re-install.
+
+// Returned when neither an explicit pin nor a live git read yields a branch — a
+// clearly-not-a-branch marker, chosen over a stale literal like
+// 'editor-improvements-30' that would silently point Reset/Update at a dead
+// branch. Callers can surface it as "unknown" instead of acting on it.
+const UNKNOWN_BRANCH = 'unknown-branch';
+
+/** Normalize a candidate branch value to a non-empty trimmed string, or null.
+ *  Anything non-string, empty, or whitespace-only counts as "absent" so a
+ *  failed git read (null) or an unset env var ('') falls through to the next
+ *  source. */
+function cleanBranch(v) {
+  if (typeof v !== 'string') return null;
+  const t = v.trim();
+  return t === '' ? null : t;
+}
+
+/** Resolve the fleet's active editor branch by precedence:
+ *
+ *    explicit env override -> live git HEAD -> fallback.
+ *
+ *  `fallback` defaults to the UNKNOWN_BRANCH sentinel, so a total failure
+ *  (no pin, no git) yields a marker rather than a stale branch literal.
+ *  Pure; no I/O. */
+function resolveFleetBranch({ envBranch, gitBranch, fallback } = {}) {
+  const pin = cleanBranch(envBranch);
+  if (pin) return pin;
+  const live = cleanBranch(gitBranch);
+  if (live) return live;
+  return cleanBranch(fallback) || UNKNOWN_BRANCH;
+}
+
+module.exports = { UNKNOWN_BRANCH, cleanBranch, resolveFleetBranch };

package/npm/fleet-broker-death.js

@@ -0,0 +1,44 @@
+'use strict';
+// Pure alarm-only classification for the Fleet Dashboard's broker-death line
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the rolling
+// `brokerHistory` forensics and the live tri-state `brokerStatus`, decide
+// whether the newest death is a LIVE problem worth alarming about. No I/O —
+// server.js does the polling.
+//
+// Contract (improve40): the death line alarms ONLY when the broker is provably
+// down right now. For every other status it returns null and the card omits the
+// row entirely.
+//
+// Why alarm-only: the live broker-status dot (renderBrokerStatus) already shows
+// current health. The death line's only job is to EXPLAIN a broker that is down
+// now (with the recorded reason / uptime / count). A death record for a broker
+// that is back up is superseded history — the old muted "↩ broker recovered"
+// footnote was noise. And a death we can't confirm (editor unreachable →
+// 'unknown') must not over-claim: "absence of evidence is never down" is the
+// established principle in npm/fleet-broker-status.js. The earlier
+// recovered/active/unconfirmed tri-state collapses to a single down-only alarm.
+//
+// `brokerStatus` here is the DEBOUNCED tri-state from
+// npm/fleet-broker-debounce.js, so a single transient probe timeout can never
+// reach this as 'down'.
+
+function classifyBrokerDeath(brokerHistory, brokerStatus) {
+  // Alarm only when the broker is confirmed down now. Every other status (up,
+  // unreachable, missing) → no death line.
+  if (brokerStatus !== 'down') return null;
+  // Common "broker never died" case → card renders nothing, unchanged.
+  if (!Array.isArray(brokerHistory) || brokerHistory.length === 0) return null;
+  const newest = brokerHistory[brokerHistory.length - 1];
+  if (!newest) return null;
+  // Mirror renderBrokerDeath's existing reason fallback chain.
+  const reason = newest.reason || newest.signalName || ('exit ' + newest.exitCode);
+  return {
+    reason,
+    // Passed through verbatim (may be null/absent — the renderer guards both).
+    atUnixSecs: newest.atUnixSecs,
+    uptimeSeconds: newest.uptimeSeconds,
+    count: brokerHistory.length,
+  };
+}
+
+module.exports = { classifyBrokerDeath };

package/npm/fleet-broker-debounce.js

@@ -0,0 +1,63 @@
+'use strict';
+// Pure consecutive-failure debounce for the Fleet Dashboard's broker tri-state
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the raw
+// single-poll status from npm/fleet-broker-status.js::deriveBrokerStatus and the
+// per-VM debounce state from the previous poll, decide the status the card
+// actually renders. No I/O — server.js does the polling and threads the state.
+//
+// The bug this fixes (observed live 2026-06-02, VM3): the dashboard polls each
+// VM's broker every 3s, and the editor probes the broker with a single 200ms
+// socket attempt. One transient timeout (IAP / SSH-tunnel congestion — the same
+// class of hiccup behind the known false "Editor stopped") instantly flipped a
+// healthy VM's card to 'down', which raised both the red broker-down dot and the
+// 💀 death alarm, even though the broker was fine (the build tab opened and chat
+// started immediately). The single probe is left as-is on the editor side; the
+// right seam for absorbing a one-poll blip is here at the aggregation layer.
+//
+// Asymmetric by design: ONLY the flip to 'down' is debounced (it requires
+// `threshold` consecutive 'down' polls). 'idle' / 'agent-live' / 'unknown' take
+// effect immediately — we never want to DELAY clearing a false alarm, only
+// delay raising one. And an unreachable editor ('unknown') breaks a pending
+// down-streak rather than escalating it, mirroring fleet-broker-status.js's
+// "absence of evidence is never down" rule.
+//
+// State shape carried across polls: { status, downStreak, lastConfirmed }.
+//   status        — the debounced value the card renders this poll.
+//   downStreak    — how many consecutive raw 'down' polls we've seen.
+//   lastConfirmed — the last raw 'idle'/'agent-live' we proved; held during a
+//                   pending (sub-threshold) down-streak so the card stays calm.
+
+// ~9s at the dashboard's 3s poll cadence: comfortably absorbs a transient probe
+// timeout and the brief down-window of a routine restart-server (broker down for
+// <3s between SIGTERM and respawn), while still surfacing a real outage quickly.
+// Named so retuning is a one-line edit.
+const DOWN_DEBOUNCE_THRESHOLD = 3;
+
+function debounceBrokerStatus(prev, rawStatus, opts) {
+  const threshold = (opts && opts.threshold) || DOWN_DEBOUNCE_THRESHOLD;
+  const lastConfirmed = prev ? prev.lastConfirmed : undefined;
+
+  // Confirmed up: the daemon answered now. Render immediately, reset the streak,
+  // and remember this as the last-confirmed-up value.
+  if (rawStatus === 'idle' || rawStatus === 'agent-live') {
+    return { status: rawStatus, downStreak: 0, lastConfirmed: rawStatus };
+  }
+
+  // Editor unreachable: we proved nothing. Never down — reset any pending
+  // down-streak and render 'unknown' (the card shows nothing for it).
+  if (rawStatus !== 'down') {
+    return { status: 'unknown', downStreak: 0, lastConfirmed };
+  }
+
+  // Raw 'down': only a real outage if it persists. Count the streak.
+  const downStreak = (prev ? prev.downStreak : 0) + 1;
+  if (downStreak >= threshold) {
+    // Confirmed down — surface the alarm.
+    return { status: 'down', downStreak, lastConfirmed };
+  }
+  // Pending (sub-threshold) down: hold the last confirmed up status if we have
+  // one, else 'unknown'. The card stays calm during the blip.
+  return { status: lastConfirmed || 'unknown', downStreak, lastConfirmed };
+}
+
+module.exports = { debounceBrokerStatus, DOWN_DEBOUNCE_THRESHOLD };

package/npm/fleet-broker-status.js

@@ -0,0 +1,45 @@
+'use strict';
+// Pure tri-state derivation for the Fleet Dashboard's per-VM broker indicator
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the raw
+// /api/session-info poll merge `v`, collapse it into the one label the card
+// renders. No I/O — server.js does the polling.
+//
+// The bug this fixes (observed live 2026-06-01): the old indicator was
+// `v.reachable ? !!v.agentBrokerLive : null`, where `agentBrokerLive` means
+// "a build-mode agent session is live in the broker" — NOT "broker daemon up".
+// So a perfectly IDLE VM (healthy broker daemon, no parked build agent) reported
+// `agentBrokerLive=false`, indistinguishable from a VM whose broker was actually
+// DOWN. An operator killed a working broker chasing that phantom. The editor now
+// also reports `brokerDaemonReachable` (the daemon answered its socket) and a
+// derived `brokerStatus`; this module layers the dashboard's own reachability on
+// top so the four states stay distinct:
+//
+//   'unknown'    — editor unreachable (can't probe the broker at all), OR an
+//                  older VM whose editor predates `brokerDaemonReachable`. Never
+//                  rendered as a problem: absence of evidence is not "down".
+//   'down'       — daemon unreachable → the real broker problem, the state that
+//                  had NO signal before. A VM here cannot start an agent session.
+//   'idle'       — daemon up, no build agent → a normal idle VM, not an error.
+//   'agent-live' — a live build-mode agent session in the broker's build slot.
+const BROKER_STATUSES = ['unknown', 'down', 'idle', 'agent-live'];
+
+function deriveBrokerStatus(v) {
+  // Editor unreachable: we polled nothing, so the broker state is unknowable.
+  // Reporting 'down' here is exactly the conflation that misled operators —
+  // an unreachable editor is not a dead broker.
+  if (!v || !v.reachable) return 'unknown';
+  // Prefer the editor's own tri-state when it reports one (newer VMs).
+  if (v.brokerStatus === 'down' || v.brokerStatus === 'idle' || v.brokerStatus === 'agent-live') {
+    return v.brokerStatus;
+  }
+  // Fallback derivation from the raw bits, for a VM reporting the bools but not
+  // the pre-derived `brokerStatus`. `agentBrokerLive` implies the daemon is up.
+  if (v.agentBrokerLive) return 'agent-live';
+  if (v.brokerDaemonReachable === true) return 'idle';
+  if (v.brokerDaemonReachable === false) return 'down';
+  // Older VM: reachable editor, but no broker-reachability field at all. Treat
+  // as 'unknown' (graceful fallback) — never falsely 'down'.
+  return 'unknown';
+}
+
+module.exports = { deriveBrokerStatus, BROKER_STATUSES };