@codeyam-editor/codeyam-editor 0.1.4 → 0.1.5

package/npm/container.js

@@ -35,6 +35,9 @@ async function main() {
     14199,
   );
 
+  // A cloud container's stdin is not a TTY, so the cross-project takeover prompt
+  // in `ensureServer` resolves to "abort" (print-and-exit) here — never a silent
+  // kill of another project's editor in a headless context.
   const serverChild = await ensureServer(PORT);
   const url = `http://localhost:${PORT}`;
   console.error(`Container UI: ${url}`);

package/npm/disk-pressure.js

@@ -45,6 +45,63 @@ const PRUNABLE_CACHE_DIRS = [
   '.angular/cache',
 ];
 
+// The in-container mount of the persistent cargo build-target volume
+// (`cargo-target:/codeyam-build-target`, set as CARGO_TARGET_DIR in
+// docker-compose.cloud.template.yml). This is SEPARATE from PRUNABLE_CACHE_DIRS
+// on purpose: the frontend-cache allowlist deliberately excludes Rust target/
+// (expensive to rebuild), so it can never reclaim this volume — yet on a
+// self-host VM that builds codeyam-editor, this volume is exactly what fills the
+// disk (VM-3 grew it to ~69GB and wedged). The reclamation below is narrowly
+// keyed on this known mount path, NOT folded into the generic allowlist, so a
+// client project's own Rust target/ is never touched.
+//
+// Stack assumption: only self-host VMs that run cargo write to this volume;
+// guest/client VMs (Next.js, Vite, Tauri, Python, …) carry an empty or absent
+// volume, so cargoTargetReclaimPlan returns an empty plan there (a guaranteed
+// no-op — honoring the stack-agnosticism rule in CLAUDE.md).
+const CARGO_TARGET_DIR = '/codeyam-build-target';
+
+// Sub-dirs of CARGO_TARGET_DIR that are ALWAYS safe to delete: pure coverage
+// instrumentation, regenerated on every `llvm-cov` run. Reclaiming this costs
+// the warm incremental build nothing (~13GB on VM-3). Pruned at WARN already.
+const CARGO_TARGET_ALWAYS_PRUNE = ['llvm-cov-target'];
+
+// Sub-trees reclaimed ONLY at CRITICAL and ONLY when no build is in flight:
+// `debug/` is the incremental compile cache that keeps `rebuild-self` fast, so
+// deleting it forces a ~14-min cold recompile. We pay that cost only when the
+// disk is genuinely critical AND nothing is mid-build (else we'd sabotage an
+// in-flight compile to free space — the failure mode this tiering avoids).
+const CARGO_TARGET_CRITICAL_CLEAN = ['debug'];
+
+// Pure decision function for tiered cargo-target reclamation. Given the current
+// pressure `level`, whether a build is in flight, and whether this VM actually
+// has the cargo-target volume, return which sub-dirs to prune and whether the
+// heavy `debug` clean was deferred (so the caller can log it — no silent cap).
+//
+// Tiers (mirrored by the bash guard + watchdog):
+//   - no cargo-target (guest/client VM)      → prune nothing (total no-op)
+//   - warn                                   → ALWAYS_PRUNE only (llvm-cov)
+//   - critical & idle                        → ALWAYS_PRUNE + CRITICAL_CLEAN
+//   - critical & build in flight             → ALWAYS_PRUNE only, defer heavy
+//   - ok / unknown level                     → fail-safe: prune nothing
+function cargoTargetReclaimPlan({ level, buildInFlight, hasCargoTarget } = {}) {
+  if (!hasCargoTarget) return { prune: [], deferredHeavyClean: false };
+  if (level === 'warn') {
+    return { prune: [...CARGO_TARGET_ALWAYS_PRUNE], deferredHeavyClean: false };
+  }
+  if (level === 'critical') {
+    if (buildInFlight) {
+      return { prune: [...CARGO_TARGET_ALWAYS_PRUNE], deferredHeavyClean: true };
+    }
+    return {
+      prune: [...CARGO_TARGET_ALWAYS_PRUNE, ...CARGO_TARGET_CRITICAL_CLEAN],
+      deferredHeavyClean: false,
+    };
+  }
+  // 'ok', undefined, or any unknown level → do nothing (fail safe).
+  return { prune: [], deferredHeavyClean: false };
+}
+
 // 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
@@ -80,10 +137,31 @@ function parseDfUsedPct(dfOutput) {
   return null;
 }
 
+// Classify a disk-guard sidecar age (updatedAt vs current time).
+// If the sidecar is older than 600s (10 min), classify it as stale.
+function classifySidecarAge(updatedAt, currentEpoch) {
+  if (typeof updatedAt !== 'number' || typeof currentEpoch !== 'number') return 'stale';
+  const age = currentEpoch - updatedAt;
+  if (age > 600) return 'stale';
+  return 'healthy';
+}
+
+// Map or classify a general disk state level including 'unknown-exec-failed'
+function mapDiskStateLevel(usedPct, hasExecError) {
+  if (hasExecError) return 'unknown-exec-failed';
+  return classifyDiskPressure(usedPct);
+}
+
 module.exports = {
   DISK_WARN_PCT,
   DISK_CRITICAL_PCT,
   PRUNABLE_CACHE_DIRS,
+  CARGO_TARGET_DIR,
+  CARGO_TARGET_ALWAYS_PRUNE,
+  CARGO_TARGET_CRITICAL_CLEAN,
+  cargoTargetReclaimPlan,
   classifyDiskPressure,
   parseDfUsedPct,
+  classifySidecarAge,
+  mapDiskStateLevel,
 };

package/npm/editor-dev.js

@@ -28,6 +28,7 @@
 
 const { execSync, spawn, spawnSync } = require("child_process");
 const path = require("path");
+const os = require("os");
 const {
   ensureServer,
   restartServer,
@@ -89,6 +90,62 @@ function buildBinary() {
   }
 }
 
+/**
+ * Build the React UI from the editor repo into ui/dist/. A failed build is
+ * non-fatal: log a warning and continue on the last-good bundle so a transient
+ * vite failure doesn't block launch. The cargo build embeds ui/dist/ at compile
+ * time via include_dir! (crates/control-api/src/embedded_ui.rs), so this MUST
+ * run before buildBinary() or the binary embeds the *previous* launch's bundle.
+ */
+function buildUI() {
+  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)...");
+  }
+}
+
+/**
+ * Build the launcher artifacts in embed-correct order: UI first (so the fresh
+ * ui/dist/ is on disk), then the Rust binary (which embeds that dist via
+ * include_dir!). build.rs declares `cargo:rerun-if-changed=ui/dist`, so a fresh
+ * bundle on disk before compilation forces cargo to recompile and embed it in
+ * the same launch — fixing the one-generation-stale UI bug. Only the launcher
+ * (no-subcommand) path calls this; the passthrough path rebuilds only the Rust
+ * binary and embeds no fresh UI, which is correct for non-launcher commands.
+ * Side-effecting steps are injectable so the ordering can be unit-tested.
+ */
+function buildLauncherArtifacts(deps = {}) {
+  const {
+    buildUI: doBuildUI = buildUI,
+    buildBinary: doBuildBinary = buildBinary,
+    enforceFreshBinary: doEnforceFreshBinary = enforceFreshBinary,
+  } = deps;
+  // UI build FIRST — the fresh bundle must be on disk before cargo embeds it.
+  doBuildUI();
+  doEnforceFreshBinary(doBuildBinary(), {
+    action: "run editor commands",
+    continueVerb: "launching with",
+  });
+}
+
+/**
+ * Rebuild artifacts for the passthrough path (a known subcommand like
+ * `editor step`/`advance`): the Rust binary ONLY, no UI build. Non-launcher
+ * commands never serve a fresh UI, so embedding a rebuilt bundle would be
+ * wasted work — and pulling vite into every CLI invocation would slow the
+ * common `editor advance` round-trip. Side-effecting steps are injectable so
+ * the "no UI build on passthrough" contract is unit-testable.
+ */
+function buildPassthroughArtifacts(deps = {}) {
+  const {
+    buildBinary: doBuildBinary = buildBinary,
+    enforceFreshBinary: doEnforceFreshBinary = enforceFreshBinary,
+  } = deps;
+  doEnforceFreshBinary(doBuildBinary(), { action: "run editor commands" });
+}
+
 /**
  * Decide whether the dev wrapper should rebuild the Rust binary (and the UI,
  * for the launcher path) before forwarding to it. The answer is always yes:
@@ -114,6 +171,32 @@ function shouldRebuildOnPassthrough() {
   return true;
 }
 
+/**
+ * Translate a passthrough child's exit into the code the dev wrapper should
+ * forward. A subcommand passthrough must report the inner editor binary's OWN
+ * outcome faithfully so every caller (gates, scripts, the agent) can trust the
+ * exit code:
+ *
+ *   - A real exit code (including 0) is forwarded verbatim — a successful
+ *     `analyze-imports` that printed valid JSON and exited 0 stays exit 0,
+ *     never a spurious 1.
+ *   - A null/undefined code means the child was terminated by a signal (e.g.
+ *     SIGPIPE after it already produced its output, or SIGTERM at teardown).
+ *     Report it distinctly via the conventional 128+signum so a clean run that
+ *     was merely signalled at the end is not collapsed into a generic `1` that
+ *     reads as a command failure. The previous `code ?? 1` erased that
+ *     distinction, surfacing a successful inner command as exit 1.
+ *
+ * Pure (no process.exit) so the mapping is unit-testable.
+ */
+function passthroughExitCode(code, signal) {
+  if (code !== null && code !== undefined) {
+    return code;
+  }
+  const signum = signal ? os.constants.signals[signal] : undefined;
+  return signum ? 128 + signum : 1;
+}
+
 /**
  * Returns true when the merged project config has a non-empty start
  * command — either at `apps[0].startCommand` (per-app, preferred) or at
@@ -250,7 +333,11 @@ function shouldOpenBrowser({ shouldRestart, wasRunning, freshInit }) {
 module.exports = {
   hasSubcommand,
   buildBinary,
+  buildUI,
+  buildLauncherArtifacts,
+  buildPassthroughArtifacts,
   shouldRebuildOnPassthrough,
+  passthroughExitCode,
   staleBinaryBanner,
   hasStartCommand,
   planPreflightAction,
@@ -268,7 +355,7 @@ if (require.main === module) {
     // 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" });
+      buildPassthroughArtifacts();
     }
     const binary = ensureBinary();
     const child = spawn(binary, args, {
@@ -276,8 +363,11 @@ if (require.main === module) {
       cwd: process.cwd(),
       env: process.env,
     });
-    child.on("exit", (code) => {
-      process.exit(code ?? 1);
+    child.on("exit", (code, signal) => {
+      // Forward the inner editor binary's OWN outcome faithfully — exit 0
+      // stays 0, a signal-terminated child reports 128+signum, not a generic
+      // 1 that would mask a successful command (see passthroughExitCode).
+      process.exit(passthroughExitCode(code, signal));
     });
   } else {
     // --- Launcher mode: build everything, start server, open browser ---
@@ -352,18 +442,9 @@ if (require.main === module) {
       // client-project launch is never disrupted. `ensureBinary()` still
       // builds once if no binary exists.
       if (shouldRebuildOnPassthrough()) {
-        enforceFreshBinary(buildBinary(), {
-          action: "run editor commands",
-          continueVerb: "launching with",
-        });
-
-        // Build the UI from the editor repo
-        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)...");
-        }
+        // Embed-correct order: UI build → cargo build (embeds the fresh
+        // ui/dist via include_dir!). See buildLauncherArtifacts.
+        buildLauncherArtifacts();
       }
 
       const serverChild = shouldRestart

package/npm/editor.js

@@ -28,8 +28,9 @@ const {
   resolveLauncherPort,
   resolveWrappedAppPort,
   classifyPortHolder,
+  fetchServerIdentity,
   formatForeignListenerError,
-  formatCrossProjectError,
+  resolveCrossProjectCollision,
   staleBinaryBanner,
   enforceFreshBinary,
 } = require("./utils");
@@ -47,6 +48,58 @@ function buildBinary() {
   }
 }
 
+// Build the React UI into ui/dist/. A failed build is non-fatal: we log a
+// warning and continue on the last-good bundle (a transient vite failure must
+// not block launch). The cargo build embeds ui/dist/ at compile time via
+// include_dir! (crates/control-api/src/embedded_ui.rs), so this MUST run
+// before buildBinary() or the binary embeds the *previous* launch's bundle.
+function buildUI() {
+  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)...");
+  }
+}
+
+// Build the launch artifacts in embed-correct order: UI first (so the fresh
+// ui/dist/ is on disk), then the Rust binary (which embeds that dist via
+// include_dir!), then install the freshly-compiled binary. build.rs declares
+// `cargo:rerun-if-changed=ui/dist`, so a fresh bundle on disk before
+// compilation forces cargo to recompile and embed it in the same launch —
+// fixing the one-generation-stale UI bug. Side-effecting steps are injectable
+// so the ordering can be unit-tested without shelling out to vite/cargo.
+function buildArtifacts(deps = {}) {
+  const {
+    buildUI: doBuildUI = buildUI,
+    buildBinary: doBuildBinary = buildBinary,
+    enforceFreshBinary: doEnforceFreshBinary = enforceFreshBinary,
+    installBinary: doInstallBinary = installBinary,
+  } = deps;
+
+  // UI build FIRST — the fresh bundle must be on disk before cargo embeds it.
+  doBuildUI();
+  // Rebuild the Rust binary so code changes (and the just-built UI) 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 = doBuildBinary();
+  // 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).
+  doEnforceFreshBinary(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) {
+    doInstallBinary();
+  }
+  return buildOk;
+}
+
 // 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
@@ -181,32 +234,9 @@ async function main() {
   // 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)...");
-  }
+  // Build the launch artifacts in embed-correct order: UI build → cargo build
+  // (embeds the fresh ui/dist via include_dir!) → install. See buildArtifacts.
+  buildArtifacts();
 
   // Start the Rust backend — it serves ui/dist/ and launches the Vite dev
   // server (configured via startCommand in editor.json) for Live Preview HMR.
@@ -223,8 +253,12 @@ async function main() {
       process.exit(1);
     }
     if (holder.kind === "cross-project") {
-      console.error(formatCrossProjectError(SERVER_PORT, holder, "restart"));
-      process.exit(1);
+      const outcome = await resolveCrossProjectCollision(SERVER_PORT, holder, "restart");
+      if (outcome.action !== "took-over") {
+        // "abort" (non-TTY) or "declined": resolver already printed the message.
+        process.exit(1);
+      }
+      // took-over: stopServer freed the port; fall through to the fresh-boot path.
     }
     if (holder.kind === "same-project") {
       console.error(`Stopping existing server on port ${SERVER_PORT}...`);
@@ -237,17 +271,29 @@ async function main() {
   }
   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.`);
+  // With 2+ projects registered the launch diverts to the Project Launcher
+  // (selector) on SERVER_PORT — there is no wrapped app, so the Vite wait and
+  // the "Live Preview" line don't apply. Probe the identity to detect it;
+  // best-effort, a missed detection only yields a harmless "Vite not ready"
+  // warning, never a failure.
+  const identity = await fetchServerIdentity(SERVER_PORT);
+  const launcherMode = Boolean(identity && identity.role === "launcher");
+
+  if (!launcherMode) {
+    // 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(launcherMode ? `Project selector: ${url}` : `Editor UI: ${url}`);
+  if (!launcherMode) {
+    console.error(`Live Preview: http://localhost:${VITE_PORT}`);
+  }
   console.error(`Logs: ${path.join(rootDir, ".codeyam", "logs")}`);
   open(url);
   const keepAlive = setInterval(() => {}, 60_000);
@@ -271,6 +317,8 @@ async function main() {
 
 module.exports = {
   buildBinary,
+  buildUI,
+  buildArtifacts,
   staleBinaryBanner,
   cargoBinDir,
   installBinary,

package/npm/fleet-auth-health.js

@@ -0,0 +1,75 @@
+'use strict';
+// Pure decision helpers for the fleet dashboard's false-unreachable reboot
+// safety (2026-06-25 incident). The dashboard's server.js execs gcloud and reads
+// its in-memory state; the DECISIONS those I/O results drive live here so they
+// are unit-testable in isolation (npm/fleet-auth-health.test.js), the same
+// split npm/fleet-cleanup.js (reconcileRosteredVm) and npm/fleet-host.js
+// (gcloudCommand) follow.
+//
+// Pure logic only — no I/O, no env reads, no clock.
+
+// Classify operator gcloud auth health from the facts server.js gathers via the
+// ${GCLOUD} chokepoint. Returns { degraded, reason }: degraded true means the
+// operator's own auth is broken (which makes EVERY VM read unreachable), so the
+// reset gate must suppress all reboots and the UI must surface a banner.
+//   account       trimmed `gcloud config list account` output (may be empty)
+//   accountErrMsg non-null when the account-resolve exec itself errored
+//   tokenOk       true/false when `auth print-access-token` was run; null when
+//                 it was not (account-only phase) — a valid SA account with
+//                 tokenOk null is "account looks fine, token not yet proven",
+//                 which is NOT degraded, so the caller can proceed to the mint.
+function classifyOperatorAuth({ account, accountErrMsg, tokenOk } = {}) {
+  const acct = typeof account === 'string' ? account.trim() : '';
+  if (accountErrMsg || !acct) {
+    return {
+      degraded: true,
+      reason: `operator gcloud could not resolve an account (${accountErrMsg || 'empty output'})`,
+    };
+  }
+  if (!/\.gserviceaccount\.com$/.test(acct)) {
+    return {
+      degraded: true,
+      reason: `operator gcloud is on a non-service-account '${acct}' — config drift; run scripts/operator/setup-service-account.sh`,
+    };
+  }
+  if (tokenOk === false) {
+    return {
+      degraded: true,
+      reason: `operator gcloud cannot mint a token for ${acct} (expired/absent credentials); run scripts/operator/setup-service-account.sh`,
+    };
+  }
+  return { degraded: false, reason: null };
+}
+
+// True when at least `fleetWideThreshold` VMs are simultaneously past the
+// reset-unreachable `threshold` — the signature of an operator-side fault
+// (auth/tunnel/network on the dashboard host) rather than independent VM
+// failures. A real VM failure is isolated; a simultaneous N-VM "outage" is the
+// operator, and the reset gate uses this to refuse rebooting the whole fleet.
+// `vms` is an array of per-VM state objects (missing/null entries are ignored).
+function isFleetWideUnreachable(vms, threshold, fleetWideThreshold) {
+  let count = 0;
+  for (const vm of Array.isArray(vms) ? vms : []) {
+    if (vm && !vm.reachable && (vm.unreachableStreak || 0) >= threshold) count++;
+  }
+  return count >= fleetWideThreshold;
+}
+
+// Classify a one-shot GCP-side IAP editor probe (server.js execs the SSH+curl).
+// true  → editor answered 200 from GCP's vantage (VM healthy; the dark local
+//         port is a laptop tunnel fault → respawn, never reset);
+// false → the VM is up but the editor does not answer (genuinely unreachable);
+// null  → the IAP probe itself failed (inconclusive — never escalate a reset).
+// The HTTP code is read from the LAST three chars of stdout because gcloud/ssh
+// can prepend banner noise before curl's `%{http_code}` output.
+function classifyIapEditorProbe({ err, stdout } = {}) {
+  if (err) return null;
+  const code = String(stdout || '').trim().slice(-3);
+  return code === '200';
+}
+
+module.exports = {
+  classifyOperatorAuth,
+  isFleetWideUnreachable,
+  classifyIapEditorProbe,
+};

package/npm/fleet-auth.js

@@ -108,4 +108,9 @@ function deriveDefaultAuthAccount(vms, lastAuthAt) {
   return best ? best.account : null;
 }
 
-module.exports = { classifyAuthVm, selectAuthTargets, summarizeAuthBatch, deriveDefaultAuthAccount };
+// Return true if this one VM is eligible for an auth-start action now.
+function isAuthStartable(v, job) {
+  return classifyAuthVm(v, job).eligible;
+}
+
+module.exports = { classifyAuthVm, selectAuthTargets, summarizeAuthBatch, deriveDefaultAuthAccount, isAuthStartable };

package/npm/fleet-build-data.js

@@ -32,6 +32,14 @@ function buildVmEnvelope(v, ctx) {
     // upstream, debounced). Richer than brokerLive's is-an-agent-live boolean.
     brokerStatus: ctx.brokerStatus,
     awaitingInput: !!v.awaitingUserInput,
+    // True when the editor reports the build workflow reached its terminal step
+    // and is parked awaiting cleanup (session_info_response.rs emits it at
+    // step >= total). Flows onto poll state via the `...info` spread in server.js
+    // exactly like `feature`/`awaitingUserInput`; defaulted false here so a legacy
+    // editor that predates the field degrades to today's behavior. Consumed by
+    // fleet-live-status.js to read a parked-but-done agent as calm 'session-done'
+    // instead of active-green 'building'.
+    needsCleanup: !!v.needsCleanup,
     feature: v.feature || null,
     step: v.step != null ? v.step : null,
     mode: v.mode || null,
@@ -39,6 +47,15 @@ function buildVmEnvelope(v, ctx) {
     status: ctx.status,
     orphan: ctx.orphan || null,
     degradedReasons: ctx.degradedReasons || [],
+    // Derived presentation split of degradedReasons (vm: Dashboard 'Finishing
+    // setup' state): `setupSteps` are expected first-run wiring rendered as a
+    // calm blue checklist, `attentionReasons` are genuine problems kept in the
+    // amber ⚠ treatment. `degradedReasons` is left intact for the many places
+    // that still consume the flat list (filters, sort, reconcile); these two are
+    // purely additive. Both default to [] so a legacy/healthy VM renders neither
+    // block. See npm/fleet-setup-steps.js::classifyReasons.
+    setupSteps: Array.isArray(ctx.setupSteps) ? ctx.setupSteps : [],
+    attentionReasons: Array.isArray(ctx.attentionReasons) ? ctx.attentionReasons : [],
     isHead: !!ctx.isHead,
     // True when this VM holds the queue head but is unreachable (operator
     // decides manually whether to release it).
@@ -61,6 +78,35 @@ function buildVmEnvelope(v, ctx) {
     // card's 🤖 agent badge. null for an older VM whose editor predates the
     // field (the card omits the badge rather than rendering a blank chip).
     currentProvider: v.currentProvider || null,
+    // Raw workflow timestamps (ISO) surfaced by /api/session-info and merged onto
+    // the poll state via the `...info` spread, exactly like feature/step/label.
+    // The card live-ticks the elapsed minutes off these between polls. null for a
+    // legacy editor that predates the fields, or a VM with no active step.
+    startedAt: v.startedAt || null,
+    featureStartedAt: v.featureStartedAt || null,
+    // The server-computed stuck / needs-you verdict (npm/fleet-stuck-status.js):
+    // { stepElapsedMs, level: 'ok'|'slow'|'stuck', needsYou, needsYouElapsedMs }.
+    // The authoritative level only changes on poll; the card colors the step
+    // tenure badge by it. null when buildData couldn't compute one.
+    attention: ctx.attention || null,
+    // Per-VM card readiness derived upstream (npm/fleet-vm-readiness.js): one of
+    // READINESS_STATES. The card colors the border and GATES the editor link on
+    // it — a non-'ready' VM never presents its public URL as live, because the
+    // LB would 503. Computed in buildData where the broker tri-state / job / LB
+    // mode are on hand, then carried here so the browser needs no extra request.
+    readiness: ctx.readiness || null,
+    // The raw LB backend-health map { editor, preview } the readiness derivation
+    // consumed, surfaced so the card can show a precise tooltip (which surface
+    // is unwired). null in legacy mode or before the first slow probe lands.
+    backendHealth: v.backendHealth || null,
+    // The per-VM IAP access whitelist (the principals explicitly granted
+    // resource-level access to THIS VM, from the fleet-vm-access sidecar). Merged
+    // onto the poll state at server.js, it drives the card's 🔐 access line and
+    // the Manage access modal's "this VM only" list. It was previously dropped
+    // here — the exact currentProvider-style envelope drift this module guards
+    // against — so the line and list rendered empty even when the sidecar held
+    // principals. Defaults to [] for a VM with no list.
+    vmAccess: Array.isArray(v.vmAccess) ? v.vmAccess : [],
   };
 }
 
@@ -72,10 +118,13 @@ function buildVmEnvelope(v, ctx) {
 // if you do one without the other.
 const REQUIRED_CARD_FIELDS = [
   'n', 'url', 'reachable', 'hasSession', 'brokerLive', 'brokerStatus',
-  'awaitingInput', 'feature', 'step', 'mode', 'label', 'status', 'orphan',
-  'degradedReasons', 'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
+  'awaitingInput', 'needsCleanup', 'feature', 'step', 'mode', 'label', 'status', 'orphan',
+  'degradedReasons', 'setupSteps', 'attentionReasons',
+  'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
   'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
   'brokerDeath', 'providerAuth', 'effects', 'currentProvider',
+  'readiness', 'backendHealth', 'vmAccess',
+  'startedAt', 'featureStartedAt', 'attention',
 ];
 
 module.exports = { buildVmEnvelope, REQUIRED_CARD_FIELDS };