@codeyam-editor/codeyam-editor 0.1.1 → 0.1.3

package/npm/editor.js

@@ -16,14 +16,23 @@ const { execSync } = require("child_process");
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
-const { ensureServer, stopServer, isPortInUse, waitForPort, rootDir, killChildProcess } = require("./utils");
+const {
+  ensureServer,
+  stopServer,
+  waitForPort,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  resolveWrappedAppPort,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
+  staleBinaryBanner,
+  enforceFreshBinary,
+} = require("./utils");
 const { open } = require("./open");
 
-const SERVER_PORT = parseInt(process.env.CODEYAM_EDITOR_PORT || "14199", 10);
-const VITE_PORT = parseInt(process.env.PORT || "5173", 10);
-// The reverse proxy sits on VITE_PORT; the actual Vite dev server runs on
-// VITE_PORT + 1. We need to wait for the real Vite server, not the proxy.
-const VITE_INTERNAL_PORT = VITE_PORT + 1;
 const shouldRestart = process.argv.includes("--restart");
 
 function buildBinary() {
@@ -32,7 +41,6 @@ function buildBinary() {
     execSync("cargo build", { stdio: "inherit", cwd: rootDir });
     return true;
   } catch {
-    console.error("Failed to build Rust binary. Continuing with existing build (if any)...");
     return false;
   }
 }
@@ -47,17 +55,46 @@ function cargoBinDir() {
   return path.join(os.homedir(), ".cargo", "bin");
 }
 
-// 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.
+// Place a hardlink at `dstPath` pointing at the same inode as `srcPath`,
+// replacing any existing file at `dstPath`. On EXDEV (cross-filesystem,
+// rare; target/ on a separate mount from the cargo bin dir) falls back
+// to an atomic copy-and-rename via `tmpPath` so we still succeed — at
+// the cost of distinct inodes, which means the dev binary's
+// `stale_cargo_bin_message` check will fire on every boot.
 //
-// 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.
+// Hardlink-by-default is what keeps the stale-binary advisory silent on
+// `npm run editor`: the freshly-installed binary at <cargo_bin> shares
+// an inode with target/debug/codeyam-editor, so the inode-identity
+// check returns "same underlying file" and nothing is printed.
+function linkOrCopyBinary(srcPath, dstPath, tmpPath) {
+  try {
+    fs.unlinkSync(dstPath);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  try {
+    fs.linkSync(srcPath, dstPath);
+  } catch (err) {
+    if (err.code !== "EXDEV") throw err;
+    fs.copyFileSync(srcPath, tmpPath);
+    fs.chmodSync(tmpPath, 0o755);
+    fs.renameSync(tmpPath, dstPath);
+  }
+}
+
+// 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 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)) {
@@ -66,23 +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 });
-    fs.copyFileSync(srcPath, tmpPath);
-    fs.chmodSync(tmpPath, 0o755);
-    fs.renameSync(tmpPath, dstPath);
-    try {
-      fs.unlinkSync(linkPath);
-    } catch (e) {
-      if (e.code !== "ENOENT") throw e;
-    }
-    fs.linkSync(dstPath, linkPath);
+    linkOrCopyBinary(srcPath, dstPath, tmpPath);
   } 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 {}
   }
 }
 
@@ -98,32 +149,44 @@ function sweepStaleArtifacts() {
   }
 }
 
+/**
+ * npm wrapper entry point for the editor binary: resolves ports from
+ * the merged editor config, ensures the Rust backend is running, and
+ * opens the editor UI.
+ */
 async function main() {
-  // Sync ports to editor.json so the Rust backend uses them
-  const editorJsonPath = path.join(rootDir, ".codeyam", "editor.json");
-  if (fs.existsSync(editorJsonPath)) {
-    const editorJson = JSON.parse(fs.readFileSync(editorJsonPath, "utf8"));
-    editorJson.port = VITE_PORT;
-    editorJson.startCommand = `cd ui && npx vite --port ${VITE_PORT}`;
-    
-    const uiApp = editorJson.apps?.find(a => a.dir === "ui");
-    if (uiApp) {
-      uiApp.port = VITE_PORT;
-      uiApp.startCommand = `npx vite --port ${VITE_PORT}`;
-    }
-    
-    if (editorJson.proxy) {
-      editorJson.proxy.controlPort = SERVER_PORT;
-      editorJson.proxy.httpPort = SERVER_PORT - 99;
-      editorJson.proxy.dbPort = SERVER_PORT - 98;
-    }
-    fs.writeFileSync(editorJsonPath, JSON.stringify(editorJson, null, 2));
-  }
+  // Read ports from the merged editor config (editor.json + per-developer
+  // editor.local.json). The Rust backend reads the same merged config on
+  // its own — we resolve here so the launcher's log lines, `waitForPort`
+  // calls, and `--port` arg agree with what the binary will actually
+  // bind. Env vars still win for scripted/CI invocations
+  // (CODEYAM_EDITOR_PORT, PORT), then the merged config, then a hard
+  // fallback for fresh checkouts with no override file.
+  const merged = readMergedEditorConfig(rootDir);
+  const SERVER_PORT = resolveLauncherPort(
+    process.env.CODEYAM_EDITOR_PORT,
+    merged.proxy && merged.proxy.controlPort,
+    14199,
+  );
+  // `resolveWrappedAppPort` mirrors `resolve_app_port` in
+  // `crates/codeyam-editor/src/commands/start.rs`: `env > apps[0].port >
+  // config.port`. Without this the launcher's log line and
+  // `waitForPort` probe targeted one port while the backend bound
+  // another, producing the misleading "Vite dev server not ready on
+  // port N" warning whenever apps[0] declared its own port.
+  const VITE_PORT = resolveWrappedAppPort(merged, process.env.PORT, 5173);
+  // The reverse proxy sits on VITE_PORT; the actual Vite dev server runs on
+  // VITE_PORT + 1. We need to wait for the real Vite server, not the proxy.
+  const VITE_INTERNAL_PORT = VITE_PORT + 1;
 
   // Rebuild the Rust binary so code changes are picked up on restart.
   // This script is only invoked from a source checkout (via `npm run editor`),
   // so Cargo.toml and the crates tree are always present.
   const buildOk = buildBinary();
+  // A failed rebuild means the server would boot on a stale binary that no
+  // longer matches the source. Refuse by default; CODEYAM_ALLOW_STALE=1
+  // forces the old behavior (continue with the last-good install).
+  enforceFreshBinary(buildOk, { action: "start the editor server" });
   // Refresh <cargo_bin>/codeyam-editor (and the pty-broker hardlink) so
   // the broker auto-spawn execs a binary that knows the `pty-broker
   // daemon` subcommand. Skip if the build failed — installing a stale
@@ -145,11 +208,27 @@ async function main() {
 
   // Start the Rust backend — it serves ui/dist/ and launches the Vite dev
   // server (configured via startCommand in editor.json) for Live Preview HMR.
-  // On --restart: stop the existing server first, sweep stale artifacts while
-  // target/ is idle (no process holding files open), then start fresh.
-  if (shouldRestart && (await isPortInUse(SERVER_PORT))) {
-    console.error(`Stopping existing server on port ${SERVER_PORT}...`);
-    await stopServer(SERVER_PORT);
+  // On --restart: identity-check first, then stop the existing server,
+  // sweep stale artifacts while target/ is idle, then start fresh.
+  //
+  // Stopping someone else's editor server on `--restart` is the worst
+  // possible outcome of a port collision — only stop the listener if
+  // the identity probe confirms it's this project's server.
+  if (shouldRestart) {
+    const holder = await classifyPortHolder(SERVER_PORT);
+    if (holder.kind === "foreign") {
+      console.error(formatForeignListenerError(SERVER_PORT));
+      process.exit(1);
+    }
+    if (holder.kind === "cross-project") {
+      console.error(formatCrossProjectError(SERVER_PORT, holder, "restart"));
+      process.exit(1);
+    }
+    if (holder.kind === "same-project") {
+      console.error(`Stopping existing server on port ${SERVER_PORT}...`);
+      await stopServer(SERVER_PORT);
+    }
+    // holder.kind === "free": nothing to stop, fall through to ensureServer.
   }
   if (shouldRestart) {
     sweepStaleArtifacts();
@@ -180,8 +259,10 @@ async function main() {
 
 module.exports = {
   buildBinary,
+  staleBinaryBanner,
   cargoBinDir,
   installBinary,
+  linkOrCopyBinary,
   main,
   sweepStaleArtifacts,
 };

package/npm/empty-project-dir.js

@@ -0,0 +1,33 @@
+"use strict";
+
+/**
+ * Launcher-side mirror of `is_empty_project_dir` in
+ * `crates/codeyam-editor/src/commands/init.rs`. The Rust side decides
+ * which `/codeyam-…` skill the init binary points at; this JS mirror
+ * decides the same for the launcher's post-launch tail banner. Keep
+ * both in sync — the test `empty-project-dir.test.js` and Rust's
+ * `is_empty_project_dir_ignores_hidden_entries` /
+ * `is_empty_project_dir_detects_visible_entry` pin the contract.
+ *
+ * A "fresh" project directory has no non-hidden entries — only things
+ * like `.git/`, `.gitignore`, or other dotfiles. Hidden entries don't
+ * count as project content, so a dir holding only `.git/` and
+ * `.gitignore` (the "I just ran `git init`" case) still reads as empty.
+ * A read error returns false, matching the Rust `Err(_) => false` branch:
+ * a missing / unreadable dir defaults to the existing-project path rather
+ * than falsely scaffolding over nothing.
+ */
+
+const fs = require("node:fs");
+
+function isEmptyProjectDir(projectDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(projectDir);
+  } catch {
+    return false;
+  }
+  return entries.every((name) => name.startsWith("."));
+}
+
+module.exports = { isEmptyProjectDir };

package/npm/fleet-auth.js

@@ -0,0 +1,111 @@
+'use strict';
+// Pure helpers for the fleet dashboard's "Authenticate idle VMs" batch flow
+// (scripts/operator/fleet-dashboard/server.js requires this). The decision of
+// WHICH VMs a fleet-auth pass touches — and how to summarize an in-flight
+// batch — lives here so server.js's HTTP orchestration stays thin and the
+// guardrail logic is unit-testable in isolation (npm/fleet-auth.test.js).
+//
+// Why per-VM real `claude /login` and not one shared credential: copying a
+// `.credentials.json` between VMs 401s (Claude rotates/binds the OAuth access
+// token to its originating VM), and the `CLAUDE_CODE_OAUTH_TOKEN` setup-token
+// is limited-scope + non-durable (lost on container recreate). So every VM
+// needs its own interactive login — this batches the human step across the
+// fleet (start every idle VM's login in parallel, approve them as one list)
+// instead of distributing a single token. See docs/cloud-editor-stability.md
+// "Fleet auth".
+
+// Classify one VM for the fleet-auth pass. Returns { eligible, reason }.
+//
+// The guardrail mirrors Destroy / Reconfigure / roll: NEVER touch an active
+// session (a mid-build agent must not have its editor driven into a login
+// PTY), and never start an auth pass on a VM that already has a running or
+// queued job. Only a reachable, idle VM the editor reports as `needs-login` is
+// a target. An `unknown` / absent auth state is deliberately NOT a target —
+// the probe is indeterminate (a transient failure on an otherwise-healthy VM),
+// and driving a login we can't confirm is needed risks disrupting a working
+// VM. `v` is the dashboard's per-VM poll state (`state.vms[n]`); `job` is
+// `state.jobs[n]` (may be undefined).
+function classifyAuthVm(v, job) {
+  if (job && (job.state === 'running' || job.state === 'queued')) {
+    return { eligible: false, reason: 'busy' };
+  }
+  if (!v || !v.reachable) return { eligible: false, reason: 'unreachable' };
+  if (v.hasSession) return { eligible: false, reason: 'active-session' };
+  const state = v.providerAuth && v.providerAuth.state;
+  if (state === 'authenticated') return { eligible: false, reason: 'already-authenticated' };
+  if (state === 'needs-login') return { eligible: true, reason: 'needs-login' };
+  return { eligible: false, reason: 'auth-state-unknown' };
+}
+
+// Select every VM the fleet-auth pass should drive a login on, plus the
+// skipped VMs each with the reason it was excluded (surfaced to the operator
+// so "why didn't VM-7 get authenticated?" is answerable without ssh).
+//
+// roster: number[] (the live VMS array). vms / jobs: maps keyed by VM number.
+// Returns { targets: number[], skipped: [{ n, reason }] }, both sorted by n.
+function selectAuthTargets({ roster, vms, jobs }) {
+  const targets = [];
+  const skipped = [];
+  for (const n of [...(roster || [])].sort((a, b) => a - b)) {
+    const c = classifyAuthVm((vms || {})[n], (jobs || {})[n]);
+    if (c.eligible) targets.push(n);
+    else skipped.push({ n, reason: c.reason });
+  }
+  return { targets, skipped };
+}
+
+// Aggregate an in-flight batch (map of n → { phase }) into counts for the
+// operator report. Phases mirror the editor's /api/auth/status states
+// ('starting' | 'url-ready' | 'authenticated' | 'failed') plus the
+// dashboard-side 'submitting' while a pasted code is being delivered. Pure
+// over the values; `done` is true once no VM is still mid-flight, which is
+// what lets the UI stop polling / show a final "N of M authenticated" line.
+function summarizeAuthBatch(batchVms) {
+  const counts = { total: 0, starting: 0, urlReady: 0, submitting: 0, authenticated: 0, failed: 0 };
+  for (const n of Object.keys(batchVms || {})) {
+    const phase = batchVms[n] && batchVms[n].phase;
+    counts.total++;
+    if (phase === 'starting') counts.starting++;
+    else if (phase === 'url-ready') counts.urlReady++;
+    else if (phase === 'submitting') counts.submitting++;
+    else if (phase === 'authenticated') counts.authenticated++;
+    else if (phase === 'failed') counts.failed++;
+  }
+  // In-flight = still starting, or awaiting a pasted code, or submitting one.
+  // A `failed` VM is terminal until the operator restarts the batch, and an
+  // `authenticated` VM is done — so neither counts as in-flight.
+  counts.inFlight = counts.starting + counts.urlReady + counts.submitting;
+  counts.done = counts.total > 0 && counts.inFlight === 0;
+  return counts;
+}
+
+// Derive the fleet's current default Claude account (improve38): the account a
+// newly launched VM should authenticate as. Defined as the account of the
+// rostered VM whose auth was updated most recently, where "auth-update time" =
+// max(dashboard-recorded login-completion `lastAuthAt[n]`, the editor-reported
+// `providerAuth.lastRefreshAt`). Re-authenticating ANY existing VM thus
+// re-points the default. Pure over the polled VM snapshot + the lastAuthAt map.
+//
+// Returns the winning VM's account object ({ email, organizationName,
+// organizationType, subscriptionType }), or null when no rostered VM reports an
+// account. Ties — and the no-timestamp case — resolve to the first such VM in
+// `vms` order, so the result is deterministic.
+function deriveDefaultAuthAccount(vms, lastAuthAt) {
+  const at = lastAuthAt || {};
+  let best = null;
+  for (const v of vms || []) {
+    const pa = v && v.providerAuth;
+    const acct = pa && pa.account;
+    if (!acct || !acct.email) continue;
+    const refreshMs = pa.lastRefreshAt ? Date.parse(pa.lastRefreshAt) : NaN;
+    const loginMs = at[v.n] ? Date.parse(at[v.n]) : NaN;
+    const score = Math.max(
+      Number.isFinite(refreshMs) ? refreshMs : -Infinity,
+      Number.isFinite(loginMs) ? loginMs : -Infinity,
+    );
+    if (!best || score > best.score) best = { account: acct, score };
+  }
+  return best ? best.account : null;
+}
+
+module.exports = { classifyAuthVm, selectAuthTargets, summarizeAuthBatch, deriveDefaultAuthAccount };

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 };