@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

package/npm/container.js

@@ -12,6 +12,8 @@ const {
   ensureServer,
   rootDir,
   killChildProcess,
+  isInteractiveLauncher,
+  logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
 } = require("./utils");
@@ -33,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}`);
@@ -41,6 +46,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,167 @@
+'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',
+];
+
+// 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
+// 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;
+}
+
+// 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,
@@ -35,6 +36,8 @@ const {
   ensureBinary,
   rootDir,
   killChildProcess,
+  isInteractiveLauncher,
+  logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
   staleBinaryBanner,
@@ -87,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:
@@ -112,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
@@ -248,7 +333,11 @@ function shouldOpenBrowser({ shouldRestart, wasRunning, freshInit }) {
 module.exports = {
   hasSubcommand,
   buildBinary,
+  buildUI,
+  buildLauncherArtifacts,
+  buildPassthroughArtifacts,
   shouldRebuildOnPassthrough,
+  passthroughExitCode,
   staleBinaryBanner,
   hasStartCommand,
   planPreflightAction,
@@ -266,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, {
@@ -274,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 ---
@@ -350,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
@@ -428,6 +511,15 @@ if (require.main === module) {
       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);

package/npm/editor.js

@@ -22,12 +22,15 @@ const {
   waitForPort,
   rootDir,
   killChildProcess,
+  isInteractiveLauncher,
+  logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
   resolveWrappedAppPort,
   classifyPortHolder,
+  fetchServerIdentity,
   formatForeignListenerError,
-  formatCrossProjectError,
+  resolveCrossProjectCollision,
   staleBinaryBanner,
   enforceFreshBinary,
 } = require("./utils");
@@ -45,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
@@ -179,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.
@@ -221,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}...`);
@@ -235,22 +271,44 @@ 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);
 
   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);
@@ -259,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 };