@codeyam-editor/codeyam-editor 0.1.3 → 0.1.4

package/npm/cloud.js

@@ -51,6 +51,12 @@ const AGENT_ENV_VARS = {
   gemini: "GEMINI_API_KEY",
 };
 
+const AGENT_NPM_PACKAGES = {
+  claude: "@anthropic-ai/claude-code",
+  codex: "@openai/codex",
+  gemini: "@google/gemini-cli",
+};
+
 const KNOWN_FLAGS = [
   "repo", "branch", "instance-name", "project", "zone", "agent",
   // Editor-source selection, decoupled from the client project (repo/branch):
@@ -129,6 +135,17 @@ function agentEnvVarName(agent) {
   return AGENT_ENV_VARS[agent];
 }
 
+/** Map an agent name to its global npm package. Throws on unknown agents so
+ *  adding an agent is a one-entry change in `AGENT_NPM_PACKAGES`. */
+function agentNpmPackage(agent) {
+  if (!Object.prototype.hasOwnProperty.call(AGENT_NPM_PACKAGES, agent)) {
+    throw new Error(
+      `Unknown agent: ${agent}. Supported: ${Object.keys(AGENT_NPM_PACKAGES).join(", ")}`,
+    );
+  }
+  return AGENT_NPM_PACKAGES[agent];
+}
+
 /** Parse `--flag value` argv into an object. Unknown flags or missing values
  *  throw with a usage hint — silently dropping them would let typos like
  *  `--branchh main` succeed with no branch flag at all. */
@@ -540,14 +557,26 @@ function saveCloudConfig(projectDir, cfg) {
 }
 
 /** Build the JSON patch to merge into the VM's `editor.local.json` so the
- *  configured agent picks up the user's local API key on first launch.
- *  Returns `null` when the key isn't set locally — the wrapper then prints
- *  the interactive-auth fallback line instead of writing an empty patch. */
+ *  configured agent becomes the editor's build-agent provider AND (when the
+ *  key is available) picks up the user's local API key on first launch. The
+ *  top-level `provider` field (lowercase — matching `BuildAgentProvider`'s
+ *  serde) makes the VM's editor default to the chosen agent instead of Claude;
+ *  `editor.local.json` is deep-merged over `editor.json` on the VM, so this
+ *  overrides the packaged default.
+ *
+ *  The patch ALWAYS carries `provider` — the agent is a launch *choice* that
+ *  must persist on the VM regardless of whether the operator happens to have
+ *  the agent's API key exported locally (Gemini, for instance, is normally
+ *  authenticated interactively on the VM). `env.<KEY>` is the separate,
+ *  opportunistic seed: it's included only when the matching key is set in
+ *  `localEnv`. The function never returns `null`. Writing `provider: "claude"`
+ *  when claude is the default deep-merges to a no-op, so the provider can be
+ *  written unconditionally without special-casing the default. */
 function buildEditorLocalEnvPatch(localEnv, agent) {
   const varName = agentEnvVarName(agent);
   const value = localEnv[varName];
-  if (!value) return null;
-  return { env: { [varName]: value } };
+  if (!value) return { provider: agent };
+  return { provider: agent, env: { [varName]: value } };
 }
 
 /** Parse `docker compose ps --format json` (compose v2 — one JSON object per
@@ -700,6 +729,72 @@ function runGcloud(args, opts = {}) {
   });
 }
 
+// Build a bounded, de-noised failure detail from a runGcloud (spawnSync)
+// result: prefer stderr, fall back to stdout, and surface a spawn-level error
+// (e.g. ENOENT when gcloud is not on PATH) when there is no captured output.
+// Trims the known gcloud noise lines — the same `/WARNING|NumPy|google.com/iap/`
+// filter the dashboard's tailLog applies — and keeps the last ~15 lines so the
+// actionable message is not buried under auth/IAP warnings. Pure: result in,
+// string out, so it is unit-testable without spawning gcloud.
+function formatGcloudFailure(result) {
+  const denoise = (text) =>
+    String(text || "")
+      .split("\n")
+      .map((l) => l.replace(/\r$/, ""))
+      .filter((l) => l.trim() !== "")
+      .filter((l) => !/WARNING|NumPy|google\.com\/iap/.test(l))
+      .slice(-15)
+      .join("\n");
+
+  const stderr = denoise(result && result.stderr);
+  if (stderr) return stderr;
+  const stdout = denoise(result && result.stdout);
+  if (stdout) return stdout;
+  if (result && result.error && result.error.message) {
+    return result.error.message;
+  }
+  return "(no output captured from gcloud)";
+}
+
+// A bounded, pure classifier that keys on status === 255 (gcloud-ssh's exit
+// for an ssh failure) and a signature match against known transient strings.
+function isTransientSshFailure(result) {
+  if (!result || result.status !== 255) {
+    return false;
+  }
+  const output = String(result.stderr || "") + String(result.stdout || "");
+  const transientRegex = /kex_exchange_identification|Connection closed|failed to connect to backend|Failed to connect to port 22|Connection refused|Connection reset|Connection timed out|4003|4047/i;
+  return transientRegex.test(output);
+}
+
+// A retry wrapper for gcloud ssh-script calls that handles transient connection drops
+// with exponential backoff, mimicking the IAP ready backoff.
+async function runGcloudSshWithRetry(verb, cfg, extras, { stdio, retries = 5, label, sleepFn } = {}) {
+  let lastResult;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    const result = runGcloud(buildGcloudArgs(verb, cfg, extras), { stdio });
+    if (result.status === 0) {
+      return result;
+    }
+    lastResult = result;
+    if (isTransientSshFailure(result)) {
+      if (attempt < retries) {
+        const delay = Math.min(2000 * Math.pow(1.5, attempt - 1), 8000);
+        console.error(`  ↺ transient SSH failure (attempt ${attempt}/${retries}) [${label || verb}] ... retrying in ${delay / 1000}s`);
+        if (sleepFn) {
+          await sleepFn(delay);
+        } else {
+          await new Promise((r) => setTimeout(r, delay));
+        }
+        continue;
+      }
+    }
+    // For non-transient failure, return immediately, or if we exhausted our attempts.
+    return result;
+  }
+  return lastResult;
+}
+
 function ensureGcloud() {
   const result = spawnSync("gcloud", ["version"], { stdio: "ignore" });
   if (result.error || result.status !== 0) {
@@ -799,9 +894,11 @@ async function ensureFirewallRule(cfg) {
 async function ensureInstance(cfg) {
   console.error(`Checking instance ${cfg.instanceName}...`);
   const initialState = fetchInstanceState(cfg);
+  const createdThisRun = initialState === null;
+
   if (initialState === "RUNNING") {
     console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
-    return;
+    return { createdThisRun };
   }
   if (initialState === "TERMINATED") {
     console.error(`  ${cfg.instanceName} is TERMINATED — starting...`);
@@ -823,7 +920,7 @@ async function ensureInstance(cfg) {
     if (fetchInstanceState(cfg) === "RUNNING") {
       console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
       await waitForIapReady(cfg);
-      return;
+      return { createdThisRun };
     }
     await new Promise((r) => setTimeout(r, 2000));
   }
@@ -1079,7 +1176,7 @@ function sshScriptCommand(scriptBody, scriptArgs = [], envVars = {}) {
   return `echo '${b64}' | base64 -d | ${envPrefix}bash -s -- ${argsString}`.trim();
 }
 
-async function ensureBootstrapped(cfg) {
+async function ensureBootstrapped(cfg, { sleepFn } = {}) {
   console.error("Checking VM bootstrap state...");
   const probe = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
@@ -1140,12 +1237,17 @@ async function ensureBootstrapped(cfg) {
     // fresh detached build that will survive an SSH disconnect.
     console.error("  launching detached bootstrap on the VM (survives SSH disconnect; ~1-14 min)...");
     const launch = bootstrapLaunchCommand(scriptBody, bootstrapArgs, bootstrapEnv);
-    const launched = runGcloud(
-      buildGcloudArgs("ssh-script", cfg, { command: launch }),
-      { stdio: ["ignore", "pipe", "pipe"] },
+    const launched = await runGcloudSshWithRetry(
+      "ssh-script",
+      cfg,
+      { command: launch },
+      { stdio: ["ignore", "pipe", "pipe"], label: "bootstrap launch", sleepFn }
     );
     if (launched.status !== 0) {
-      throw new Error("failed to launch the detached bootstrap on the VM");
+      const detail = formatGcloudFailure(launched);
+      throw new Error(
+        `failed to launch the detached bootstrap on the VM (gcloud ssh exit ${launched.status}).\n${detail}`,
+      );
     }
   }
 
@@ -1280,6 +1382,7 @@ async function ensureEditorContainerUp(cfg) {
   );
   if (probe.status === 0 && parseEditorComposeState(probe.stdout) === "running") {
     console.error("  ✓ editor container is already running");
+    await ensureAgentCliInstalled(cfg);
     return;
   }
   console.error("  starting editor container (docker compose up -d)...");
@@ -1292,6 +1395,34 @@ async function ensureEditorContainerUp(cfg) {
   if (up.status !== 0) {
     throw new Error("docker compose up -d failed on the VM");
   }
+  await ensureAgentCliInstalled(cfg);
+}
+
+// Hard gate: provisioning success REQUIRES a running editor container. Reuses
+// the exact compose-ps probe ensureEditorContainerUp uses, but as a TERMINAL
+// re-check rather than a precondition — `docker compose up -d` can exit 0 over
+// a container that then crash-loops or exits, and an upstream phase that never
+// ran leaves no /workspace at all. Either way `cmdUp` would otherwise report
+// success. This throws (non-zero exit) when the editor service isn't
+// `running`, converting a silent partial provision into a loud, actionable
+// failure the operator (and the dashboard's fail-fast-on-nonzero path) can act
+// on. The `|| true` keeps the probe's exit status 0 so the real signal is the
+// parsed compose state, not the SSH/cd exit code.
+async function assertEditorContainerRunning(cfg) {
+  const repoName = resolveProject(cfg).name;
+  const composeCmd = `docker compose -f docker-compose.cloud.yml`;
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} 2>/dev/null && ${composeCmd} ps --format json 2>/dev/null || true`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (!(probe.status === 0 && parseEditorComposeState(probe.stdout) === "running")) {
+    throw new Error(
+      `provisioning incomplete: editor container is not running on ${cfg.instanceName} ` +
+        `(no /workspace or container). Re-run: npm run cloud:up -- --instance-name ${cfg.instanceName}`,
+    );
+  }
 }
 
 /** Read the laptop's git author identity (`user.name`, `user.email`) so
@@ -1560,20 +1691,35 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
   }
 }
 
+/** Write the chosen agent provider and local API keys into editor.local.json on
+ *  the VM BEFORE compose up so the file exists when the bind-mount happens —
+ *  the provider seed MUST run before ensureEditorContainerUp, because the editor
+ *  caches config.provider at startup and reports it as currentProvider; a post-start
+ *  seed leaves the running editor (and therefore the dashboard badge) on the default
+ *  "claude" until a config reload. */
 async function seedAgentApiKey(cfg) {
+  // The provider seed is unconditional — `buildEditorLocalEnvPatch` always
+  // returns a patch carrying `provider`, so the chosen agent always lands on
+  // the VM. The API-key seed is opportunistic: when the matching key isn't set
+  // locally the patch carries `provider` only, and we still print the
+  // interactive-auth fallback line so the operator knows to authenticate the
+  // agent on the VM later (Gemini's normal path).
   const patch = buildEditorLocalEnvPatch(process.env, cfg.agent);
-  if (!patch) {
+  const hasKey = Boolean(patch.env);
+  if (!hasKey) {
     console.error(
-      `\nNo ${agentEnvVarName(cfg.agent)} set locally — skipping agent auth seed.\n` +
+      `\nNo ${agentEnvVarName(cfg.agent)} set locally — seeding provider only.\n` +
         `Authenticate ${cfg.agent} later with:\n` +
         `  gcloud compute ssh ${cfg.instanceName} --project ${cfg.project} --zone ${cfg.zone} ` +
         `--tunnel-through-iap -- ${cfg.agent} auth login\n`,
     );
-    return;
   }
   const repoName = resolveProject(cfg).name;
   const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
-  console.error(`Seeding ${agentEnvVarName(cfg.agent)} into ${remotePath}...`);
+  const seedLabel = hasKey
+    ? `Seeding ${agentEnvVarName(cfg.agent)} into ${remotePath}...`
+    : `Seeding provider '${cfg.agent}' into ${remotePath}...`;
+  console.error(seedLabel);
 
   const read = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
@@ -1606,6 +1752,75 @@ async function seedAgentApiKey(cfg) {
   if (write.status !== 0) {
     throw new Error(`Failed to write ${remotePath} on VM`);
   }
+
+  await ensureAgentCliInstalled(cfg);
+}
+
+/** Install the selected agent's CLI inside the editor container on the live VM */
+async function ensureAgentCliInstalled(cfg) {
+  const agent = cfg.agent;
+  const pkg = agentNpmPackage(agent);
+  const container = process.env.CONTAINER || "codeyam-editor-editor-1";
+
+  // First, check if the container is running on the VM host.
+  // If the container is not running, we do nothing and return.
+  const checkProbe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `docker ps --filter name=^/${container}$ --filter status=running --format '{{.Name}}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+
+  const isRunning = checkProbe.status === 0 && checkProbe.stdout.trim() !== "";
+  if (!isRunning) {
+    console.error(`  Container ${container} is not running. Skipping build-agent CLI install for now.`);
+    return;
+  }
+
+  console.error(`Ensuring build-agent CLI for '${agent}' is installed in container '${container}'...`);
+
+  const containerScript = [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    `BINARY="${agent}"`,
+    `PACKAGE="${pkg}"`,
+    `AGENT="${agent}"`,
+    "",
+    "if command -v \"$BINARY\" >/dev/null 2>&1; then",
+    "  if [ \"$AGENT\" = \"claude\" ]; then",
+    "    if [ -x /usr/local/bin/claude ]; then",
+    "      echo \"  ✓ $BINARY already installed and executable at /usr/local/bin/claude\"",
+    "      exit 0",
+    "    fi",
+    "  else",
+    "    echo \"  ✓ $BINARY already installed on PATH\"",
+    "    exit 0",
+    "  fi",
+    "fi",
+    "",
+    "echo \"Installing $PACKAGE globally in container...\"",
+    "if [ \"$AGENT\" = \"claude\" ]; then",
+    "  rm -rf /usr/lib/node_modules/@anthropic-ai/.claude-code-*",
+    "  npm install -g \"$PACKAGE\"",
+    "  ln -sf /usr/lib/node_modules/@anthropic-ai/claude-code/node_modules/@anthropic-ai/claude-code-linux-x64/claude /usr/local/bin/claude",
+    "else",
+    "  npm install -g \"$PACKAGE\"",
+    "fi",
+    "echo \"  ✓ Successfully installed $BINARY\"",
+  ].join("\n");
+
+  const hostCommand = `docker exec -i ${container} bash -s <<'EOF'\n${containerScript}\nEOF`;
+
+  const installCmd = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: hostCommand,
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] }
+  );
+
+  if (installCmd.status !== 0) {
+    throw new Error(`Failed to install build-agent CLI in container for agent: ${agent}`);
+  }
 }
 
 async function openTunnel(cfg, appPort = VITE_PORT) {
@@ -1663,24 +1878,55 @@ async function cmdUp(args) {
   assertVariantProvisionable(resolveEditorConfig(cfg).editorVariant);
 
   await ensureFirewallRule(cfg);
-  await ensureInstance(cfg);
-  await ensureBootstrapped(cfg);
-  await ensureProjectBootstrapped(cfg);
-  // Resolve the app's dev-server port from the VM's now-bootstrapped config so
-  // the previewOrigin seed and the laptop tunnel both target it (not 5173).
-  const appPort = await readVmAppPort(cfg);
-  await seedPreviewOrigin(cfg, appPort);
-  // Write the GitHub token BEFORE compose up so the credentials file exists
-  // when the bind-mount happens — bind-mounting a missing file would silently
-  // create a directory instead and the agent's first `git pull` would fail.
-  await seedGithubCredentials(cfg);
-  await ensureEditorContainerUp(cfg);
-  await seedAgentApiKey(cfg);
-  // Roster the VM into the fleet dashboard NOW that it's provisioned and the
-  // editor container is up. Runs BEFORE the --no-tunnel early-return so the
-  // dashboard's own `cloud:up --no-tunnel` Add path also rosters (idempotent
-  // with the dashboard's onSuccess roster — a double-add is a harmless no-op).
-  rosterProvisionedVm(cfg.instanceName);
+  const { createdThisRun } = await ensureInstance(cfg);
+
+  try {
+    await ensureBootstrapped(cfg);
+    await ensureProjectBootstrapped(cfg);
+    // Resolve the app's dev-server port from the VM's now-bootstrapped config so
+    // the previewOrigin seed and the laptop tunnel both target it (not 5173).
+    const appPort = await readVmAppPort(cfg);
+    await seedPreviewOrigin(cfg, appPort);
+    // Write the GitHub token BEFORE compose up so the credentials file exists
+    // when the bind-mount happens — bind-mounting a missing file would silently
+    // create a directory instead and the agent's first `git pull` would fail.
+    await seedGithubCredentials(cfg);
+    await seedAgentApiKey(cfg);
+    await ensureEditorContainerUp(cfg);
+    // Roster the VM into the fleet dashboard NOW that it's provisioned and the
+    // editor container is up. Runs BEFORE the --no-tunnel early-return so the
+    // dashboard's own `cloud:up --no-tunnel` Add path also rosters (idempotent
+    // with the dashboard's onSuccess roster — a double-add is a harmless no-op).
+    rosterProvisionedVm(cfg.instanceName);
+    // Terminal gate: provisioning is NOT "done" until the editor container is
+    // verifiably Up. Placed BEFORE the --no-tunnel early-return so the dashboard's
+    // own `cloud:up --no-tunnel` Add path is covered too (it's the path that bit
+    // us — a run reported success with no container). A failure here is a loud
+    // non-zero exit, which the dashboard fail-fast-on-nonzero path acts on.
+    await assertEditorContainerRunning(cfg);
+  } catch (err) {
+    if (createdThisRun) {
+      console.error(
+        `✗ provisioning aborted — tearing down the VM cloud:up created this run (no orphan left behind)`,
+      );
+      try {
+        console.error(`Deleting instance ${cfg.instanceName}...`);
+        const del = runGcloud(buildGcloudArgs("instances-delete", cfg));
+        if (del.status !== 0) {
+          console.error(
+            `  Warning: failed to delete instance ${cfg.instanceName} during abort teardown. ` +
+              `Please delete it manually with 'npm run cloud:destroy'.`,
+          );
+        }
+      } catch (delErr) {
+        console.error(
+          `  Warning: error deleting instance ${cfg.instanceName} during abort teardown: ${delErr.message}. ` +
+            `Please delete it manually with 'npm run cloud:destroy'.`,
+        );
+      }
+    }
+    throw err;
+  }
   // --no-tunnel: provisioning-only mode (the fleet dashboard opens its own
   // per-VM tunnel). Skipping openTunnel lets cloud:up EXIT cleanly instead of
   // hanging on a tunnel, and — critically for parallel multi-add — avoids N
@@ -1861,7 +2107,10 @@ async function cloudMain() {
 module.exports = {
   // pure helpers
   agentEnvVarName,
+  agentNpmPackage,
   AGENT_ENV_VARS,
+  AGENT_NPM_PACKAGES,
+  ensureAgentCliInstalled,
   KNOWN_FLAGS,
   FIREWALL_RULE_NAME,
   INSTANCE_TAG,
@@ -1912,6 +2161,12 @@ module.exports = {
   FORWARD_ENV_KEYS_ENV,
   parseEditorComposeState,
   fetchInstanceState,
+  formatGcloudFailure,
+  isTransientSshFailure,
+  runGcloudSshWithRetry,
+  ensureInstance,
+  ensureBootstrapped,
+  assertEditorContainerRunning,
   // side-effecting handlers
   cmdUp,
   cmdTunnel,

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

@@ -35,6 +35,8 @@ const {
   ensureBinary,
   rootDir,
   killChildProcess,
+  isInteractiveLauncher,
+  logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
   staleBinaryBanner,
@@ -428,6 +430,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,6 +22,8 @@ const {
   waitForPort,
   rootDir,
   killChildProcess,
+  isInteractiveLauncher,
+  logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
   resolveWrappedAppPort,
@@ -251,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);