@codeyam-editor/codeyam-editor 0.1.2 → 0.1.4

package/npm/container.js

@@ -12,6 +12,8 @@ const {
   ensureServer,
   rootDir,
   killChildProcess,
+  isInteractiveLauncher,
+  logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
 } = require("./utils");
@@ -41,6 +43,15 @@ async function main() {
   const keepAlive = setInterval(() => {}, 60_000);
 
   process.on("SIGINT", () => {
+    // The container launcher is inherently headless: a SIGINT here is stray
+    // (the server is torn down via API shutdown / orchestration, never an
+    // interactive Ctrl+C), so do NOT forward it — the detached server stays
+    // alive. Record the signal's process-group forensics for root-cause tracing.
+    const interactive = isInteractiveLauncher();
+    logLauncherTeardownSignal("SIGINT", rootDir, { interactive, forwarded: interactive });
+    if (!interactive) {
+      return;
+    }
     clearInterval(keepAlive);
     killChildProcess(serverChild);
     process.exit(0);

package/npm/disk-pressure.js

@@ -0,0 +1,89 @@
+'use strict';
+// Pure decision module for the VM root-disk guardrail. Given a single integer
+// percent (from `df`'s Use%/Capacity column), classify the pressure into
+// ok | warn | critical, and expose the allowlist of regenerable cache dirs the
+// watchdog may auto-prune at the critical threshold. No I/O — the watchdog
+// (bash) and the fleet dashboard (node) both consume these constants so the
+// decision boundary is testable without a live VM, mirroring the
+// pure-decision-vs-I/O split of npm/fleet-effect-status.js.
+//
+// Why two thresholds: warn (80%) is visibility only — a badge + log line so the
+// operator sees pressure building. critical (90%) authorizes a bounded
+// auto-prune of regenerable build caches, because a 100%-full disk cascades far
+// worse (it truncated ~/.claude.json mid-write and OOM-killed the broker on the
+// VM4 outage this guards against).
+
+const DISK_WARN_PCT = 80;
+const DISK_CRITICAL_PCT = 90;
+
+// Allowlist of regenerable dev/build cache directories that are safe to delete
+// on ANY stack because the toolchain rebuilds them on demand. This is an
+// allowlist (known-safe), NOT a denylist, so an unknown stack's important files
+// are never deleted — worst case we free less, never break a build.
+//
+// Stack assumption: each entry is a cache OUTPUT of a specific toolchain
+// (.next/.turbo → Next.js/Turborepo, .svelte-kit → SvelteKit, .vite → Vite,
+// .parcel-cache → Parcel, .angular/cache → Angular, node_modules/.cache →
+// generic JS build caches). A project on none of these stacks simply has none
+// of these dirs and the prune is a no-op.
+//
+// Deliberately disjoint from internal_paths.rs::ALWAYS_EXCLUDED_DIRS
+// (node_modules, .codeyam, .git, target): those mean "don't index," NOT "safe
+// to delete." node_modules is load-bearing and Rust target/ is expensive to
+// rebuild, so neither appears here.
+//
+// Follow-up: a future migration can move this into stack.json so each project
+// declares its own cache dirs; kept operator-side here to stay self-contained.
+const PRUNABLE_CACHE_DIRS = [
+  '.next/cache',
+  '.next/dev/cache',
+  'node_modules/.cache',
+  '.turbo',
+  '.svelte-kit',
+  '.vite',
+  '.parcel-cache',
+  '.angular/cache',
+];
+
+// Classify an integer disk-usage percent into a pressure level. A non-numeric,
+// non-finite, or out-of-range (<0 or >100) value is treated as a BAD READING
+// and classified 'ok' with no action — a misread must never escalate to a
+// destructive prune.
+function classifyDiskPressure(usedPct) {
+  if (typeof usedPct !== 'number' || !Number.isFinite(usedPct)) return 'ok';
+  if (usedPct < 0 || usedPct > 100) return 'ok';
+  if (usedPct >= DISK_CRITICAL_PCT) return 'critical';
+  if (usedPct >= DISK_WARN_PCT) return 'warn';
+  return 'ok';
+}
+
+// Parse the integer used-percent from a `df -P /` block. `df -P` (POSIX) emits a
+// header line then one data line whose Capacity field is like "82%". We find the
+// first NN% token on the data line, which is robust to a mount point containing
+// spaces (which would shift positional fields). Returns null on unparseable
+// input so the caller can fail safe rather than prune on garbage.
+function parseDfUsedPct(dfOutput) {
+  const lines = String(dfOutput == null ? '' : dfOutput)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+  // The data line is the second non-empty line (after the header). Fall back to
+  // scanning all lines so a header-less one-liner still parses.
+  const candidates = lines.length >= 2 ? [lines[1], ...lines] : lines;
+  for (const line of candidates) {
+    const m = line.match(/(\d+)%/);
+    if (m) {
+      const pct = parseInt(m[1], 10);
+      if (Number.isFinite(pct)) return pct;
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  DISK_WARN_PCT,
+  DISK_CRITICAL_PCT,
+  PRUNABLE_CACHE_DIRS,
+  classifyDiskPressure,
+  parseDfUsedPct,
+};

package/npm/editor-dev.js

@@ -33,9 +33,10 @@ const {
   restartServer,
   waitForPort,
   ensureBinary,
-  isSelfHostTarget,
   rootDir,
   killChildProcess,
+  isInteractiveLauncher,
+  logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
   staleBinaryBanner,
@@ -90,28 +91,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 +154,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 +187,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 +210,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 +255,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 +344,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 +395,74 @@ 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", () => {
+        // Forward a deliberate Ctrl+C (interactive launcher) to stop the editor.
+        // A SIGINT to a headless / agent-driven launcher is stray and must NOT
+        // reap the now-detached server, so swallow it and keep supervising.
+        // Record the signal's process-group forensics either way.
+        const interactive = isInteractiveLauncher();
+        logLauncherTeardownSignal("SIGINT", projectDir, { interactive, forwarded: interactive });
+        if (!interactive) {
+          return;
+        }
+        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

@@ -22,6 +22,8 @@ const {
   waitForPort,
   rootDir,
   killChildProcess,
+  isInteractiveLauncher,
+  logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
   resolveWrappedAppPort,
@@ -82,17 +84,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 +105,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 {}
   }
 }
 
@@ -233,6 +253,16 @@ async function main() {
   const keepAlive = setInterval(() => {}, 60_000);
 
   process.on("SIGINT", () => {
+    // Forward a deliberate Ctrl+C (interactive launcher) to stop the editor.
+    // A SIGINT to a headless / agent-driven launcher is stray — the editor is
+    // torn down via API shutdown / pidfile there, never an interactive Ctrl+C —
+    // so do NOT forward it: the detached server stays alive. Either way, record
+    // the signal's process-group forensics for root-cause tracing.
+    const interactive = isInteractiveLauncher();
+    logLauncherTeardownSignal("SIGINT", rootDir, { interactive, forwarded: interactive });
+    if (!interactive) {
+      return;
+    }
     clearInterval(keepAlive);
     killChildProcess(serverChild);
     process.exit(0);

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