@codeyam-editor/codeyam-editor 0.1.14 → 0.1.15-staging.g8a9ebd4

package/npm/agent-cli-install.js

@@ -0,0 +1,102 @@
+'use strict';
+// How each build agent's CLI gets installed on a fleet VM, and the in-container
+// install script that does it. Pure — no I/O; npm/cloud.js runs the script over
+// SSH (ensureAgentCliInstalled) and owns the gates around it. Split out of
+// cloud.js so the install dimension is one concern with one test file.
+//
+// Two install kinds, mirroring the Rust `CliInstall::{Npm, Script}` split in
+// BuildAgentProvider::cli_spec() (crates/types/src/config/harness.rs):
+//   npm    — a global npm package (claude, codex, gemini)
+//   script — the agent's own install command, run verbatim (muse)
+
+// Muse is not on npm: it installs through Meta's curl launcher into
+// `~/.local/bin`. Mirrors `MUSE_INSTALL_COMMAND` in
+// crates/types/src/config/harness.rs (the spike-verified command — the launcher
+// download answers unauthenticated, so a VM needs no sign-in to install).
+// Cross-reference: keep the two strings identical.
+const MUSE_INSTALL_COMMAND =
+  'mkdir -p "$HOME/.local/bin" && curl -fsSL https://api.meta.ai/muse-launcher.sh -o "$HOME/.local/bin/muse" && chmod +x "$HOME/.local/bin/muse" && MUSE_LAUNCHER_INSTALL=1 "$HOME/.local/bin/muse"';
+
+const AGENT_CLI_INSTALLS = {
+  claude: { kind: "npm", package: "@anthropic-ai/claude-code" },
+  codex: { kind: "npm", package: "@openai/codex" },
+  gemini: { kind: "npm", package: "@google/gemini-cli" },
+  muse: { kind: "script", command: MUSE_INSTALL_COMMAND },
+};
+
+/** Map an agent name to how its CLI is installed — `{ kind: "npm", package }`
+ *  or `{ kind: "script", command }`. Throws on unknown agents so adding an
+ *  agent is a one-entry change in `AGENT_CLI_INSTALLS`. */
+function agentCliInstall(agent) {
+  if (!Object.prototype.hasOwnProperty.call(AGENT_CLI_INSTALLS, agent)) {
+    throw new Error(
+      `Unknown agent: ${agent}. Supported: ${Object.keys(AGENT_CLI_INSTALLS).join(", ")}`,
+    );
+  }
+  return AGENT_CLI_INSTALLS[agent];
+}
+
+/** The bash script that installs `agent`'s CLI inside the editor container,
+ *  dispatched on its install kind (see `agentCliInstall`). Pure — returns the
+ *  script text. Both kinds short-circuit when the binary already resolves. A
+ *  script install must end with a binary that runs and reports a version, so a
+ *  launcher that downloaded but cannot execute fails provisioning loudly (with
+ *  the install output attached by runFatalSshStep) instead of rostering a VM
+ *  whose CLI was never usable. */
+function buildAgentCliInstallScript(agent, install) {
+  const header = [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    `BINARY="${agent}"`,
+    "",
+  ];
+  if (install.kind === "script") {
+    return [
+      ...header,
+      "if command -v \"$BINARY\" >/dev/null 2>&1 || [ -x \"$HOME/.local/bin/$BINARY\" ]; then",
+      "  echo \"  ✓ $BINARY already installed\"",
+      "  exit 0",
+      "fi",
+      "",
+      "echo \"Installing $BINARY via its install script in container...\"",
+      install.command,
+      "RESOLVED=$(command -v \"$BINARY\" 2>/dev/null || echo \"$HOME/.local/bin/$BINARY\")",
+      "if [ ! -x \"$RESOLVED\" ]; then",
+      "  echo \"  ✗ $BINARY install script finished but no $BINARY binary was found (looked on PATH and in $HOME/.local/bin)\" >&2",
+      "  exit 1",
+      "fi",
+      "\"$RESOLVED\" --version",
+      "echo \"  ✓ Successfully installed $BINARY at $RESOLVED\"",
+    ].join("\n");
+  }
+  return [
+    ...header,
+    `PACKAGE="${install.package}"`,
+    `AGENT="${agent}"`,
+    "",
+    "if command -v \"$BINARY\" >/dev/null 2>&1; then",
+    "  echo \"  ✓ $BINARY already installed on PATH\"",
+    "  exit 0",
+    "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\"",
+    "  RESOLVED=$(find /usr/lib/node_modules/@anthropic-ai -name claude -type f -path '*linux-x64*' 2>/dev/null | head -1)",
+    "  if [ -n \"$RESOLVED\" ]; then",
+    "    ln -sf \"$RESOLVED\" /usr/local/bin/claude",
+    "  fi",
+    "else",
+    "  npm install -g \"$PACKAGE\"",
+    "fi",
+    "echo \"  ✓ Successfully installed $BINARY\"",
+  ].join("\n");
+}
+
+module.exports = {
+  MUSE_INSTALL_COMMAND,
+  AGENT_CLI_INSTALLS,
+  agentCliInstall,
+  buildAgentCliInstallScript,
+};

package/npm/cloud.js

@@ -139,13 +139,17 @@ const AGENT_ENV_VARS = {
   claude: "ANTHROPIC_API_KEY",
   codex: "OPENAI_API_KEY",
   gemini: "GEMINI_API_KEY",
+  muse: "META_API_KEY",
 };
 
-const AGENT_NPM_PACKAGES = {
-  claude: "@anthropic-ai/claude-code",
-  codex: "@openai/codex",
-  gemini: "@google/gemini-cli",
-};
+// How each agent's CLI is installed (npm package vs Muse's launcher script)
+// lives in its own module; re-exported below so existing importers keep working.
+const {
+  MUSE_INSTALL_COMMAND,
+  AGENT_CLI_INSTALLS,
+  agentCliInstall,
+  buildAgentCliInstallScript,
+} = require("./agent-cli-install");
 
 const KNOWN_FLAGS = [
   "repo", "branch", "instance-name", "project", "zone", "agent",
@@ -273,16 +277,6 @@ 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
@@ -3653,6 +3647,34 @@ async function healPreviewOriginAtReady(cfg, appPort = VITE_PORT, { resolveAppPo
   );
 }
 
+/** The notice cloud:up prints when the agent's API key is not set locally, so
+ *  only the provider is seeded. Names every way the operator can still
+ *  authenticate the agent on the VM. Muse also accepts an account login
+ *  (`muse login`, run once on the VM), which the editor's auth gate honours
+ *  in place of a key — so for Muse a key-less VM is "sign in on the VM", not
+ *  broken. Pure. */
+function noLocalKeySeedingNotice(agent) {
+  const varName = agentEnvVarName(agent);
+  const accountLogin =
+    agent === "muse"
+      ? `  • signing in once on the VM with \`muse login\` (a Meta account login; no key needed).\n`
+      : "";
+  const oauthCaveat =
+    agent === "muse"
+      ? ""
+      : `Interactive browser-based OAuth login (e.g. \`codex login\`) is not yet ` +
+        `supported headlessly on the VM.\n`;
+  return (
+    `\nNo ${varName} set locally — seeding provider only.\n` +
+    `Authenticate ${agent} on the VM by either:\n` +
+    `  • exporting ${varName} locally and re-running cloud:up, or\n` +
+    `  • pasting the key into the Build tab's auth gate in the editor${accountLogin ? ", or" : "."}\n` +
+    accountLogin +
+    `Each path flows the credential through to the agent process on the VM.\n` +
+    oauthCaveat
+  );
+}
+
 /** 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
@@ -3670,15 +3692,7 @@ async function seedAgentApiKey(cfg, { sleepFn } = {}) {
   const patch = buildEditorLocalEnvPatch(process.env, cfg.agent);
   const hasKey = Boolean(patch.env);
   if (!hasKey) {
-    console.error(
-      `\nNo ${agentEnvVarName(cfg.agent)} set locally — seeding provider only.\n` +
-        `Authenticate ${cfg.agent} on the VM by either:\n` +
-        `  • exporting ${agentEnvVarName(cfg.agent)} locally and re-running cloud:up, or\n` +
-        `  • pasting the key into the Build tab's auth gate in the editor.\n` +
-        `Either path now flows the key through to the agent process on the VM.\n` +
-        `Interactive browser-based OAuth login (e.g. \`codex login\`) is not yet ` +
-        `supported headlessly on the VM.\n`,
-    );
+    console.error(noLocalKeySeedingNotice(cfg.agent));
   }
   const repoName = resolveProject(cfg).name;
   const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
@@ -3833,7 +3847,10 @@ function probeAgentBinaryInstalled(cfg, container, binary) {
   // idempotent install (a fatal step) rather than a throw of its own.
   const probe = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
-      command: `docker exec ${container} bash -lc 'command -v ${binary}'`,
+      // `~/.local/bin` is checked too: a script-installed CLI (Muse) lands there,
+      // which a login shell's PATH need not include — the editor's own resolver
+      // scans the same dir, so it finds the binary either way.
+      command: `docker exec ${container} bash -lc 'command -v ${binary} || { test -x "$HOME/.local/bin/${binary}" && echo "$HOME/.local/bin/${binary}"; }'`,
     }),
     { stdio: ["ignore", "pipe", "ignore"] },
   );
@@ -3901,7 +3918,7 @@ async function waitForContainerRunning(
  *  pass `{ containerStarted: true }`. */
 async function ensureAgentCliInstalled(cfg, waitOpts = {}) {
   const agent = cfg.agent;
-  const pkg = agentNpmPackage(agent);
+  const install = agentCliInstall(agent);
   const container = process.env.CONTAINER || "codeyam-editor-editor-1";
 
   // The container may not be up the instant this runs — a slow `docker compose
@@ -3953,31 +3970,7 @@ async function ensureAgentCliInstalled(cfg, waitOpts = {}) {
 
   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",
-    "  echo \"  ✓ $BINARY already installed on PATH\"",
-    "  exit 0",
-    "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\"",
-    "  RESOLVED=$(find /usr/lib/node_modules/@anthropic-ai -name claude -type f -path '*linux-x64*' 2>/dev/null | head -1)",
-    "  if [ -n \"$RESOLVED\" ]; then",
-    "    ln -sf \"$RESOLVED\" /usr/local/bin/claude",
-    "  fi",
-    "else",
-    "  npm install -g \"$PACKAGE\"",
-    "fi",
-    "echo \"  ✓ Successfully installed $BINARY\"",
-  ].join("\n");
+  const containerScript = buildAgentCliInstallScript(agent, install);
 
   const hostCommand = `docker exec -i ${container} bash -s <<'EOF'\n${containerScript}\nEOF`;
 
@@ -3990,6 +3983,7 @@ async function ensureAgentCliInstalled(cfg, waitOpts = {}) {
   });
 }
 
+
 async function openTunnel(cfg, appPort = VITE_PORT) {
   console.error(`Opening IAP tunnel to ${cfg.instanceName}...`);
   const child = spawn("gcloud", buildGcloudArgs("ssh-tunnel", cfg, { appPort }), { stdio: "inherit" });
@@ -6108,9 +6102,12 @@ module.exports = {
   provisionFailureMessage,
   GCLOUD_PROVISION_TIMEOUT_MS,
   agentEnvVarName,
-  agentNpmPackage,
+  agentCliInstall,
   AGENT_ENV_VARS,
-  AGENT_NPM_PACKAGES,
+  AGENT_CLI_INSTALLS,
+  MUSE_INSTALL_COMMAND,
+  buildAgentCliInstallScript,
+  noLocalKeySeedingNotice,
   ensureAgentCliInstalled,
   ensureEditorContainerUp,
   seedAgentApiKey,

package/npm/editor.js

@@ -24,6 +24,9 @@ const {
   killChildProcess,
   isInteractiveLauncher,
   logLauncherTeardownSignal,
+  ownServerIdentity,
+  waitForOwnServer,
+  formatServerNotAnsweringError,
   readMergedEditorConfig,
   resolveLauncherPort,
   resolveWrappedAppPort,
@@ -36,6 +39,7 @@ const {
   enforceFreshBinary,
 } = require("./utils");
 const { open } = require("./open");
+const { logLauncherBootEvent } = require("./launcher-boot-log");
 
 const shouldRestart = process.argv.includes("--restart");
 
@@ -299,6 +303,25 @@ async function main() {
     }
   }
 
+  // Only ever open the browser onto a confirmed-live server. The server can die
+  // between `ensureServer` and here (the Vite wait alone is up to 15s), and a
+  // page opened onto a dead port looks loaded but is frozen — so ask the server
+  // once more, and fail loudly instead of printing a cheerful URL.
+  // Judged against the same project dir `ensureServer` used (its default, cwd).
+  const projectDir = process.cwd();
+  const live = await waitForOwnServer(SERVER_PORT, {
+    ownServerIdentityFn: (p) => ownServerIdentity(p, projectDir),
+  });
+  logLauncherBootEvent(projectDir, "browser-gate", {
+    port: SERVER_PORT,
+    verdict: live ? "live" : "dead",
+    server_pid: live ? live.pid : undefined,
+  });
+  if (!live) {
+    console.error(formatServerNotAnsweringError(SERVER_PORT, projectDir));
+    process.exit(1);
+  }
+
   const url = `http://localhost:${SERVER_PORT}`;
   console.error(launcherMode ? `Project selector: ${url}` : `Editor UI: ${url}`);
   if (!launcherMode) {

package/npm/fleet-add-failure.js

@@ -446,6 +446,31 @@ function streamedLibraryMissingRecovery({ script, library, cleanTeardown } = {})
   );
 }
 
+// Did the OPERATOR HOST run out of filesystem? Node spells it `ENOSPC: no space
+// left on device`, the shell `No space left on device`, gcloud `OSError: [Errno
+// 28] No space left on device` — matched on the message, never on the errno
+// number, which means something else on other platforms. A transcript that says a
+// script "failed on the VM" is quoting the VM's own log tail (npm/cloud.js prints
+// that header above it), so an ENOSPC there is the VM's disk, not the host's, and
+// stays with the generic arm.
+const HOST_DISK_EXHAUSTED = /ENOSPC: no space left on device|No space left on device/i;
+
+function hostDiskExhausted(logTail) {
+  const log = String(logTail || '');
+  return HOST_DISK_EXHAUSTED.test(log) && !/failed on the VM/i.test(log);
+}
+
+// Operator-facing recovery copy for the host-disk-exhausted arm. The ENOSPC fires
+// on the operator host before `instances create`, so nothing exists on GCP; the
+// fix is freeing the host's filesystem, which every add needs first.
+function hostDiskExhaustedRecovery() {
+  return (
+    'The operator host ran out of filesystem space (bytes or inodes) before anything was created, so there is no VM to ' +
+    'reconcile or destroy. Prune old date directories under /root/.config/gcloud/logs — gcloud writes one log per ' +
+    'invocation and is the usual cause — and confirm with `df -i` and `df -h`. Every add fails the same way until then.'
+  );
+}
+
 // Operator-facing recovery copy for the generic cloud-up-failed arm. "A partial
 // instance may exist" is only true when the transcript does not show cloud:up
 // deleting what it created; saying it regardless sends the operator hunting for
@@ -700,9 +725,27 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
       streamedLibraryMissingRecovery({ ...missingLib, cleanTeardown: cleanTeardownReported(log) }));
   }
 
+  // 10b. host-disk-exhausted — the OPERATOR HOST's filesystem is full. Observed
+  //    2026-10-16: six adds died in 5–27s on `ENOSPC: no space left on device`
+  //    writing `cloud.json.NNN.tmp`, with 6.4 GB free and 0 inodes free. No arm
+  //    matched, so all six landed on the calm `verifying` residue: the badge held
+  //    calm and Retry was refused as "still resolving", about adds that were dead.
+  //
+  //    NOT retryable even though nothing was provisioned: a retry before the disk
+  //    is freed fails identically — the streamed-library-missing reasoning. Not in
+  //    CALM_ADD_CATEGORIES: an explicit error proves the failure, so it reads red.
+  //
+  //    Tested BEFORE cloud-up-failed for the reason arm 6 documents: the provision
+  //    shell echoes cloud:up's tail, so this transcript ALSO carries the generic
+  //    `cloud:up FAILED (exit N)` line.
+  if (hostDiskExhausted(log)) {
+    return buildFailureVerdict('host-disk-exhausted', 'Operator host disk full',
+      hostDiskExhaustedRecovery());
+  }
+
   // 11. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
   //    vanished / stuck / stockout / missing-ref / wedged-insert / iap-not-ready /
-  //    streamed-library signatures above did not match. Not retryable. Whether a
+  //    streamed-library / host-disk signatures above did not match. Not retryable. Whether a
   //    partial instance may exist is read off the transcript's teardown evidence.
   if (/cloud:up FAILED \(exit/i.test(log)) {
     return buildFailureVerdict('cloud-up-failed', 'Provisioning failed',
@@ -977,4 +1020,12 @@ function tornDownRetryMessage(n) {
   );
 }
 
-module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, stockoutCapacityPhrase, missingBranchRefFacts, missingBranchRefRecovery, deadRefRetryMessage, wedgedInsertFacts, wedgedInsertRecovery, wedgedRetryMessage, iapNotReadyFacts, iapNotReadyRecovery, streamedLibraryMissingFacts, cleanTeardownReported, streamedLibraryMissingRecovery, cloudUpFailedRecovery, streamedLibraryRetryMessage, tornDownRetryMessage, settledAgeMs, instanceAliveSince, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE, CLASSIFY_TAIL_LINES };
+// Refusal copy for a one-click "Retry add" after the operator host ran out of
+// filesystem. The generic refusal's "half-provisioned instance" is false — the
+// ENOSPC fired before anything was created — and a retry fails identically until
+// the host is pruned, so the copy names the prune. Pure; no I/O.
+function hostDiskExhaustedRetryMessage(n) {
+  return `VM-${n} cannot be retried until the operator host has free space: ${hostDiskExhaustedRecovery()}`;
+}
+
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, stockoutCapacityPhrase, missingBranchRefFacts, missingBranchRefRecovery, deadRefRetryMessage, wedgedInsertFacts, wedgedInsertRecovery, wedgedRetryMessage, iapNotReadyFacts, iapNotReadyRecovery, streamedLibraryMissingFacts, cleanTeardownReported, streamedLibraryMissingRecovery, cloudUpFailedRecovery, streamedLibraryRetryMessage, tornDownRetryMessage, hostDiskExhausted, hostDiskExhaustedRecovery, hostDiskExhaustedRetryMessage, settledAgeMs, instanceAliveSince, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE, CLASSIFY_TAIL_LINES };

package/npm/fleet-auth.js

@@ -14,6 +14,15 @@
 // instead of distributing a single token. See docs/cloud-editor-stability.md
 // "Fleet auth".
 
+// Whether VM `v` runs Claude as its build agent — the only agent the fleet's
+// Claude-credential machinery (batched `claude /login`, donor credential copy)
+// applies to. An editor that predates `currentProvider` reports null; that
+// editor could only run Claude, so null reads as Claude. Pure.
+function isClaudeVm(v) {
+  const p = v && v.currentProvider;
+  return !p || p === 'claude';
+}
+
 // Classify one VM for the fleet-auth pass. Returns { eligible, reason }.
 //
 // The guardrail mirrors Destroy / Reconfigure / roll: NEVER touch an active
@@ -31,6 +40,9 @@ function classifyAuthVm(v, job) {
   }
   if (!v || !v.reachable) return { eligible: false, reason: 'unreachable' };
   if (v.hasSession) return { eligible: false, reason: 'active-session' };
+  // The batch drives `claude /login`. A VM running another agent (Muse signs in
+  // with its own `muse login` on the VM) must not be swept into it.
+  if (!isClaudeVm(v)) return { eligible: false, reason: 'not-claude' };
   const state = v.providerAuth && v.providerAuth.state;
   if (state === 'authenticated') return { eligible: false, reason: 'already-authenticated' };
   if (state === 'needs-login') return { eligible: true, reason: 'needs-login' };
@@ -154,12 +166,16 @@ function selectDonorForAccount(reachableDonors, vms, email) {
 // copied and those the integrity probe failed, so the add can drop the failed
 // ones BEFORE resolveCredsSource's first-donor fallback could pick one, and name
 // each dropped donor in the add log. Order is preserved; unprobed is usable.
+// A VM running a non-Claude agent (Muse) holds no Claude credential to copy, so
+// it is never a donor — left out of both lists, since it is not a failed probe.
 // Returns { usable: number[], skipped: number[] }. Pure.
 function partitionDonorsByIntegrity(reachableDonors, vms) {
   const usable = [];
   const skipped = [];
   for (const n of reachableDonors || []) {
-    const pa = vms && vms[n] && vms[n].providerAuth;
+    const v = vms && vms[n];
+    if (v && !isClaudeVm(v)) continue;
+    const pa = v && v.providerAuth;
     if (pa && pa.credentialIntact === false) skipped.push(n);
     else usable.push(n);
   }

package/npm/launch-config.js

@@ -14,6 +14,7 @@ const { normalizeAccessList } = require("./fleet-vm-access");
 const { normalizeRepoUrl } = require("./fleet-env");
 const { API_BUDGET_DEFAULTS, wouldExceedApiBudget } = require("./fleet-api-budget");
 const { posix: posixPath } = require("node:path");
+const { hostDiskHeadroomCheck } = require("./operator-host-disk");
 
 /** The build agents a VM's editor terminal can run, as the keys of cloud.js's
  *  AGENT_ENV_VARS. Deriving the selectable set from that map keeps it a single
@@ -30,7 +31,7 @@ const EMPTY_CONFIG = Object.freeze({
   newProjectName: "",
   editorVariant: "dev",
   editorBranch: "",
-  // Build agent provider the VM's editor terminal runs (claude | codex | gemini).
+  // Build agent provider the VM's editor terminal runs (claude | codex | gemini | muse).
   // Defaults to claude; cloudUpArgs forwards it as cloud:up's --agent flag.
   agent: "claude",
   // Optional human-readable hostname slug for a SINGLE VM. When set, cloudUpArgs
@@ -210,8 +211,22 @@ function missingBranchRefMessage(missing) {
  *   - no GitHub token → the fresh VM's bootstrap dies cloning the PRIVATE editor
  *     repo at `could not read Username for 'https://github.com'`.
  *  `allowNoGitCredentials` mirrors cloud:up's --allow-no-git-credentials opt-out
- *  for an intentionally read-only VM (no push token needed). Pure; no I/O. */
-function addPreflight({ zone, project, token, allowNoGitCredentials = false } = {}) {
+ *  for an intentionally read-only VM (no push token needed).
+ *
+ *
+ *  It also guards the operator host's own filesystem (the 2026-10-16 fault: six
+ *  adds died on ENOSPC with bytes free and 0 inodes free). The caller measures
+ *  `inodesFree` / `inodesTotal` / `bytesFree`; each is optional, and absent means
+ *  "not measured", never zero — see operator-host-disk.js. Pure; no I/O. */
+function addPreflight({
+  zone,
+  project,
+  token,
+  allowNoGitCredentials = false,
+  inodesFree,
+  inodesTotal,
+  bytesFree,
+} = {}) {
   const blank = (v) => typeof v !== "string" || v.trim() === "";
   if (blank(zone)) {
     return {
@@ -238,6 +253,8 @@ function addPreflight({ zone, project, token, allowNoGitCredentials = false } =
         "read-only VM with --allow-no-git-credentials.",
     };
   }
+  const diskFull = hostDiskHeadroomCheck({ inodesFree, inodesTotal, bytesFree });
+  if (diskFull) return { ok: false, msg: diskFull };
   return { ok: true };
 }
 

package/npm/launcher-boot-log.js

@@ -0,0 +1,57 @@
+/**
+ * Launch-attempt forensics for the npm launcher.
+ *
+ * One line per event of `ensureServer`'s boot — spawn, readiness verdict (and
+ * how it was decided), kill, retry, adoption, final outcome — plus the browser
+ * gate's verdict, appended to `.codeyam/logs/launcher-boot.log`. A launch that
+ * ends with no server, or with a server SIGTERM'd by its own launch, is then
+ * self-explaining from this file beside `editor-server.log`, even when nobody
+ * can reproduce it.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Format one launch-attempt trace line: an ISO-8601 UTC timestamp (the same
+ * shape `editor-server.log` uses, so the two files line up by eye), the event
+ * name, the launcher pid, then `key=value` fields in insertion order.
+ * `undefined` fields are dropped so callers can pass optional context without
+ * branching; a value containing whitespace is quoted so the line stays
+ * splittable on spaces.
+ */
+function formatLauncherBootRecord({ timestamp, launcherPid, event, fields = {} }) {
+  const parts = [`${timestamp} launcher-boot event=${event} launcher_pid=${launcherPid}`];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined) continue;
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    parts.push(`${key}=${/\s/.test(text) ? JSON.stringify(text) : text}`);
+  }
+  return parts.join(" ") + "\n";
+}
+
+/**
+ * Append one launch-attempt trace line to `<projectDir>/.codeyam/logs/
+ * launcher-boot.log`. Best-effort: never throws, so tracing can never change a
+ * launch's outcome.
+ */
+function logLauncherBootEvent(projectDir, event, fields) {
+  try {
+    const dir = path.join(projectDir, ".codeyam", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    const record = formatLauncherBootRecord({
+      timestamp: new Date().toISOString(),
+      launcherPid: process.pid,
+      event,
+      fields,
+    });
+    fs.appendFileSync(path.join(dir, "launcher-boot.log"), record);
+  } catch {
+    /* best-effort forensics — never change a launch's outcome on a logging failure */
+  }
+}
+
+module.exports = {
+  formatLauncherBootRecord,
+  logLauncherBootEvent,
+};

package/npm/operator-host-disk.js

@@ -0,0 +1,44 @@
+'use strict';
+
+// Filesystem headroom of the OPERATOR HOST, judged before a dashboard Add.
+//
+// On 2026-10-16 six adds died in 5–27s on `ENOSPC: no space left on device`
+// writing `cloud.json.NNN.tmp`, with 6.4 GB free and 0 of 3,268,608 inodes free.
+// So headroom is judged on BOTH axes: a bytes-only reading would have passed
+// every one of those adds through. Pure; the caller takes the readings.
+
+// A cloud:up writes only a handful of files, so these are "effectively
+// exhausted" floors, not capacity planning.
+const MIN_FREE_INODES = 1000;
+const MIN_FREE_BYTES = 256 * 1024 * 1024;
+
+// The remedy: gcloud's per-invocation log files are what filled the inode table.
+function hostDiskRemedy() {
+  return (
+    'free space on the operator host before adding a VM — prune old date directories ' +
+    'under /root/.config/gcloud/logs (gcloud writes a log file per invocation and is ' +
+    'the usual cause), then confirm with `df -i` and `df -h`. Nothing was provisioned.'
+  );
+}
+
+const measured = (v) => typeof v === 'number' && Number.isFinite(v);
+
+// Returns the refusal message when either axis is below its floor, else null.
+//
+// Every reading is optional: an absent (non-finite) value means "not measured"
+// and passes, never "zero", or an unmeasurable filesystem would refuse every add.
+// An `inodesTotal` of 0 means the filesystem does not count inodes (btrfs reports
+// this), so the inode axis is skipped there.
+function hostDiskHeadroomCheck({ inodesFree, inodesTotal, bytesFree } = {}) {
+  const countsInodes = !measured(inodesTotal) || inodesTotal > 0;
+  if (countsInodes && measured(inodesFree) && inodesFree < MIN_FREE_INODES) {
+    return `the operator host is out of inodes (${inodesFree} free) even if bytes remain — ${hostDiskRemedy()}`;
+  }
+  if (measured(bytesFree) && bytesFree < MIN_FREE_BYTES) {
+    const mb = Math.floor(bytesFree / (1024 * 1024));
+    return `the operator host is out of disk space (${mb} MB free) — ${hostDiskRemedy()}`;
+  }
+  return null;
+}
+
+module.exports = { hostDiskHeadroomCheck, hostDiskRemedy, MIN_FREE_INODES, MIN_FREE_BYTES };