@codeyam-editor/codeyam-editor 0.1.0-staging.01efa1a

package/npm/editor.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+/**
+ * Start the editor.
+ *
+ * 1. Builds the React UI into ui/dist/ (stable outer shell, no HMR)
+ * 2. Starts the Rust backend which:
+ *    - Serves ui/dist/ as static files on port 14199
+ *    - Launches the Vite dev server (startCommand) on port 5173 for Live Preview HMR
+ *    - Provides the API, WebSocket, and screenshot endpoints
+ * 3. Waits for the Vite dev server to be ready (so the Live Preview iframe works)
+ * 4. Opens http://localhost:14199 in the browser
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  ensureServer,
+  stopServer,
+  waitForPort,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  resolveWrappedAppPort,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
+  staleBinaryBanner,
+  enforceFreshBinary,
+} = require("./utils");
+const { open } = require("./open");
+
+const shouldRestart = process.argv.includes("--restart");
+
+function buildBinary() {
+  console.error("Building Rust binary...");
+  try {
+    execSync("cargo build", { stdio: "inherit", cwd: rootDir });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Resolve <CARGO_HOME>/bin (falling back to $HOME/.cargo/bin). Mirrors
+// `installed_binary_path()` in crates/control-api/src/pty_broker_startup.rs
+// — the Rust broker auto-spawn execs the binary at this path, so we MUST
+// keep it in sync with the freshly-built debug binary or `npm run editor`
+// will start a server whose PTY-broker auto-spawn execs a stale install.
+function cargoBinDir() {
+  if (process.env.CARGO_HOME) return path.join(process.env.CARGO_HOME, "bin");
+  return path.join(os.homedir(), ".cargo", "bin");
+}
+
+// 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.
+//
+// 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)) {
+    console.error(`Skipping install: ${srcPath} not found.`);
+    return;
+  }
+  const binDir = cargoBinDir();
+  const dstPath = path.join(binDir, "codeyam-editor");
+  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);
+  } 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 {}
+  }
+}
+
+// Evict Rust build artifacts not touched in the last day so target/ doesn't
+// grow unboundedly. Must run after the old server is stopped (it holds files
+// in target/debug/ open) and before the new server starts. Non-fatal.
+function sweepStaleArtifacts() {
+  console.error("Sweeping stale Rust build artifacts (idle >1 day)...");
+  try {
+    execSync("cargo sweep --time 1", { stdio: "inherit", cwd: rootDir });
+  } catch {
+    console.error("cargo-sweep failed (install with `cargo install cargo-sweep`). Continuing.");
+  }
+}
+
+/**
+ * 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() {
+  // 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
+  // debug binary over a working install is worse than leaving it.
+  if (buildOk) {
+    installBinary();
+  }
+
+  // Build the UI so the backend can serve it as static files
+  console.error("Building UI...");
+  try {
+    execSync("npx vite build", {
+      stdio: "inherit",
+      cwd: path.join(rootDir, "ui"),
+    });
+  } catch {
+    console.error("Failed to build UI. Continuing with existing build (if any)...");
+  }
+
+  // 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: 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();
+  }
+  const serverChild = await ensureServer(SERVER_PORT);
+
+  // Wait for the actual Vite dev server on the internal port (not the reverse
+  // proxy on VITE_PORT, which starts immediately with the Rust binary).
+  console.error("Waiting for Vite dev server...");
+  const viteReady = await waitForPort(VITE_INTERNAL_PORT, 15000, 300);
+  if (!viteReady) {
+    console.error(`Warning: Vite dev server not ready on port ${VITE_INTERNAL_PORT}. Live Preview may not work initially.`);
+  }
+
+  const url = `http://localhost:${SERVER_PORT}`;
+  console.error(`Editor UI: ${url}`);
+  console.error(`Live Preview: http://localhost:${VITE_PORT}`);
+  console.error(`Logs: ${path.join(rootDir, ".codeyam", "logs")}`);
+  open(url);
+  const keepAlive = setInterval(() => {}, 60_000);
+
+  process.on("SIGINT", () => {
+    clearInterval(keepAlive);
+    killChildProcess(serverChild);
+    process.exit(0);
+  });
+}
+
+module.exports = {
+  buildBinary,
+  staleBinaryBanner,
+  cargoBinDir,
+  installBinary,
+  linkOrCopyBinary,
+  main,
+  sweepStaleArtifacts,
+};
+
+if (require.main === module) {
+  main();
+}

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