@codeyam-editor/codeyam-editor 0.1.0-staging.4d8da9a → 0.1.0-staging.6286eae

package/npm/cloud-branch-switch.js

@@ -358,7 +358,7 @@ async function branchSwitchMain() {
     process.exit(1);
   }
 
-  const roster = readRoster();
+  const roster = readRoster() || [];
   if (!roster.length) {
     console.error('Error: roster is empty — no VMs to switch.');
     process.exit(1);

package/npm/cloud.js

@@ -411,6 +411,46 @@ function isRottedManagedPreviewOrigin(localJson, sameOriginSafe) {
   );
 }
 
+// A loopback / localhost previewOrigin: `http://127.0.0.1:<port>`,
+// `http://localhost:<port>`, `http://[::1]:<port>`, with or without a port,
+// path, or query. These are reachable only from the editor host itself (or a
+// laptop `-L` forward), never from a remote browser — exactly the dead-end the
+// dedicated_preview_origin fallback lands on when the seed was wrong-moded.
+const LOOPBACK_ORIGIN_RE =
+  /^https?:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?:[:/?#]|$)/i;
+
+/** Decide whether a VM's current `editor.local.json` carries a WRONG-MODE
+ *  previewOrigin for a stack that is NOT same-origin-safe (Next.js etc.) and so
+ *  must be self-healed to a dedicated origin. This is the inverse of
+ *  `isRottedManagedPreviewOrigin`: it fires when the stack.json race froze the
+ *  same-origin-safe default (or a loopback bootstrap) onto a client-routed
+ *  stack — the VM7 failure where the iframe shows `127.0.0.1 refused to
+ *  connect`. True iff BOTH hold:
+ *    - the stack is NOT same-origin-safe (a same-origin-safe stack legitimately
+ *      keeps the `/__codeyam_preview` subpath — never heal it; that is
+ *      `isRottedManagedPreviewOrigin`'s job in the other direction); and
+ *    - the `previewOrigin` is the same-origin subpath sentinel, any other
+ *      relative path, or a loopback/localhost origin — none of which a remote
+ *      browser can load for a dedicated-origin stack. A real dedicated origin
+ *      (an absolute non-loopback URL — quick-tunnel or named-tunnel host) is
+ *      left alone, so re-running the heal once a good origin is in place is a
+ *      no-op.
+ *  Symmetric with `isRottedManagedPreviewOrigin` and tested as a pair. Pure —
+ *  `localJson` is a parsed editor.local.json object. */
+function isWrongModePreviewOrigin(localJson, sameOriginSafe) {
+  if (sameOriginSafe) return false;
+  if (!localJson || typeof localJson !== "object") return false;
+  const origin = localJson.previewOrigin;
+  if (typeof origin !== "string" || origin.length === 0) return false;
+  // The reserved same-origin subpath, or any relative path (no scheme): these
+  // recurse into the editor SPA for a client-routed stack.
+  if (origin === SAME_ORIGIN_PREVIEW_PATH) return true;
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(origin)) return true;
+  // An absolute loopback/localhost origin: reachable only from the host, dead
+  // for a remote browser.
+  return LOOPBACK_ORIGIN_RE.test(origin);
+}
+
 /** Read the operator-laptop cloudflared-urls.json sidecar. Missing/unparseable
  *  → {} (the monitor may not have run yet; the seed falls back to localhost). */
 function readCloudflaredUrls() {
@@ -838,6 +878,14 @@ function loadOrInitCloudConfig(projectDir, flags) {
   const persist = (c) => { const { noTunnel, ...rest } = c; return rest; };
   if (existing) {
     const merged = reconcileProjectExclusivity({ ...existing, ...flags }, flags);
+    const { isPlaceholderProject } = require("./launch-config");
+    if (isPlaceholderProject(merged.project)) {
+      const configPath = cloudConfigPath(projectDir);
+      throw new Error(
+        `Failed to load cloud config: project '${merged.project}' in ${configPath} is a test-fixture placeholder. ` +
+          `Please configure a real GCP project or set the GCP_PROJECT environment variable.`
+      );
+    }
     const toSave = persist(merged);
     if (JSON.stringify(toSave) !== JSON.stringify(existing)) {
       saveCloudConfig(projectDir, toSave);
@@ -847,6 +895,15 @@ function loadOrInitCloudConfig(projectDir, flags) {
 
   const cfg = reconcileProjectExclusivity({ ...flags }, flags);
   cfg.project = cfg.project || gcloudGetValue("config-get-project");
+
+  const { isPlaceholderProject } = require("./launch-config");
+  if (isPlaceholderProject(cfg.project)) {
+    throw new Error(
+      `Failed to load cloud config: resolved project '${cfg.project}' is a test-fixture placeholder. ` +
+        `Please configure a real GCP project or set the GCP_PROJECT environment variable.`
+    );
+  }
+
   cfg.zone = cfg.zone || gcloudGetValue("config-get-zone");
   cfg.agent = cfg.agent || "claude";
   agentEnvVarName(cfg.agent);
@@ -1651,27 +1708,43 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
   );
 
   // Skip-on-already-set guard, EXCEPT for self-heal. A non-empty previewOrigin
-  // is normally a user pin or a good prior seed and is left untouched. The one
-  // exception is a ROTTED managed cloudflared quick-tunnel URL on a
-  // same-origin-safe VM (the VM-1/2/6 leftover from before the improve38
-  // same-origin migration): that frozen URL points at a dead rotated tunnel
-  // (NXDOMAIN / blank preview), so we heal it back to the same-origin path
-  // instead of preserving it. Because every dashboard action (Reset / Update /
-  // Add / bootstrap-recovery) re-runs this seed over cloud:up, the heal reaches
-  // every touch-point without a separate per-VM hand-fix.
+  // is normally a user pin or a good prior seed and is left untouched. There are
+  // TWO symmetric heal exceptions, both of which the frozen skip-guard would
+  // otherwise pin forever:
+  //   1. a ROTTED managed cloudflared quick-tunnel URL on a same-origin-safe VM
+  //      (the VM-1/2/6 leftover from before the improve38 same-origin
+  //      migration): that frozen URL points at a dead rotated tunnel (NXDOMAIN /
+  //      blank preview), so we heal it back to the same-origin path; and
+  //   2. a WRONG-MODE previewOrigin on a NOT-same-origin-safe VM (the VM7 race:
+  //      the first seed ran before onboarding wrote stack.json, defaulted to
+  //      `sameOriginSafe: true`, and seeded `/__codeyam_preview` — which a
+  //      remote browser then loads as `127.0.0.1 refused to connect`). Once
+  //      stack.json exists, heal it forward to the dedicated origin.
+  // Because every dashboard action (Reset / Update / Add / bootstrap-recovery)
+  // re-runs this seed over cloud:up, either heal reaches every touch-point the
+  // moment stack.json is present — closing the race without re-ordering
+  // provisioning, and without a separate per-VM hand-fix.
   const originAlreadySet =
     typeof current.previewOrigin === "string" && current.previewOrigin.length > 0;
   const healing =
-    originAlreadySet && isRottedManagedPreviewOrigin(current, sameOriginSafe);
+    originAlreadySet &&
+    (isRottedManagedPreviewOrigin(current, sameOriginSafe) ||
+      isWrongModePreviewOrigin(current, sameOriginSafe));
   if (originAlreadySet && !healing) {
     return;
   }
 
-  // On heal, also DROP the legacy `_managedPreviewOrigin` marker (deepMergeJson
-  // deletes any key whose overlay value is null) — the same-origin path is a
-  // constant the retired monitor push has nothing to manage, exactly matching
-  // the manual `config-override --unset _managedPreviewOrigin` fix.
-  const overlay = healing ? { ...seed, _managedPreviewOrigin: null } : seed;
+  // On heal, reconcile the `_managedPreviewOrigin` marker to the healed value's
+  // own shape. The rotted→same-origin heal (seed carries NO marker) DROPS any
+  // stale marker (deepMergeJson deletes a key whose overlay value is null) — the
+  // constant same-origin path has nothing for the monitor to manage, exactly
+  // matching the manual `config-override --unset _managedPreviewOrigin` fix. The
+  // wrong-mode→dedicated heal (seed carries the marker) KEEPS it — that origin
+  // IS managed (the monitor's gated rotation push owns it), so the marker must
+  // survive so the next respawn recognises the value as ours.
+  const overlay = healing
+    ? { ...seed, _managedPreviewOrigin: seed._managedPreviewOrigin ?? null }
+    : seed;
   console.error(
     healing
       ? `Healing rotted managed previewOrigin (${current.previewOrigin}) → ${seed.previewOrigin} in ${remotePath}...`
@@ -1691,6 +1764,82 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
   }
 }
 
+/** READY-probe auto-heal: after the editor container is verifiably Up, ask the
+ *  running editor's own `/api/config` for its stack verdict and effective
+ *  preview origin, and heal a wrong-moded seed in place — never failing the add.
+ *
+ *  The race this closes (VM7, 2026-06-10): the pre-container `seedPreviewOrigin`
+ *  at line ~1906 runs BEFORE onboarding writes stack.json, so it defaults to
+ *  `sameOriginSafe: true` and seeds the `/__codeyam_preview` subpath. For a
+ *  client-routed stack (Next.js) the editor then reports `previewSameOriginSafe:
+ *  false` but, with only the subpath in editor.local.json, falls its
+ *  `dedicated_preview_origin` back to `http://127.0.0.1:<appPort>` — which a
+ *  remote browser renders as "refused to connect". If stack.json appeared since
+ *  the first seed (the editor reads it live from disk), we re-run the seed — now
+ *  the wrong-mode heal fires (`isWrongModePreviewOrigin`) — and POST
+ *  `/api/editor-reload-config` so the running server serves the healed origin
+ *  with no restart.
+ *
+ *  Best-effort and non-fatal by contract: a probe failure, a still-absent
+ *  stack.json (verdict stays `true`), or a heal that can only reach a loopback
+ *  bootstrap origin (the operator's `<N>-preview` tunnel not published yet) all
+ *  leave the add green. The cloudflared-monitor's periodic tick (section 2) is
+ *  the durable owner that heals post-add flips — onboarding finishing minutes
+ *  after READY. */
+async function healPreviewOriginAtReady(cfg, appPort = VITE_PORT) {
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `curl -fsS --max-time 5 http://localhost:${EDITOR_PORT}/api/config 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (probe.status !== 0 || typeof probe.stdout !== "string") {
+    return;
+  }
+  let config;
+  try {
+    config = JSON.parse(probe.stdout);
+  } catch {
+    return;
+  }
+  if (!config || typeof config !== "object") return;
+
+  // The editor's own verdict (section 3's `/api/config` field) plus the
+  // wrong-mode predicate (a subpath / relative / loopback origin on a
+  // not-same-origin-safe stack) — the exact dead-end the dedicated-origin
+  // fallback lands on. Same-origin-safe stacks (verdict true) never enter here.
+  if (config.previewSameOriginSafe !== false) return;
+  if (!isWrongModePreviewOrigin(config, false)) return;
+
+  console.error(
+    `READY auto-heal: ${cfg.instanceName} reports a not-same-origin-safe stack ` +
+      `but a wrong-mode previewOrigin (${config.previewOrigin}); re-seeding...`,
+  );
+  // Re-run the seed: stack.json is now readable, so the wrong-mode heal writes
+  // the dedicated origin into editor.local.json (a published `<N>-preview`
+  // tunnel URL, else the localhost bootstrap for the window before the monitor's
+  // first tick).
+  await seedPreviewOrigin(cfg, appPort);
+  // Tell the running server to re-read editor.local.json — no restart (the
+  // footgun that killed VM7's live Claude session).
+  const reload = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `curl -fsS --max-time 5 -X POST http://localhost:${EDITOR_PORT}/api/editor-reload-config 2>/dev/null || true`,
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (reload.status !== 0) {
+    console.error(
+      `  Warning: heal wrote editor.local.json but /api/editor-reload-config did ` +
+        `not return cleanly — the next monitor tick or cloud:up touch-point will reconcile.`,
+    );
+  }
+  console.error(
+    `  Live Preview origin healed. If the operator <N>-preview tunnel is not ` +
+      `published yet, the cloudflared-monitor's periodic tick provides the ongoing heal.`,
+  );
+}
+
 /** 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
@@ -1787,22 +1936,18 @@ async function ensureAgentCliInstalled(cfg) {
     `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",
+    "  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\"",
-    "  ln -sf /usr/lib/node_modules/@anthropic-ai/claude-code/node_modules/@anthropic-ai/claude-code-linux-x64/claude /usr/local/bin/claude",
+    "  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",
@@ -1864,19 +2009,117 @@ function promptForInstanceName(expected) {
   });
 }
 
+const STREAMED_SCRIPTS = ["scripts/gcp-bootstrap.sh", "scripts/gcp-project-bootstrap.sh"];
+
+/** Check if the streamed bootstrap scripts have drifted from the remote repository
+ *  and abort provisioning if they are out of date to prevent silent container/VM failures. */
+function checkScriptDrift(cfg) {
+  if (process.env.CODEYAM_SKIP_SCRIPT_DRIFT_CHECK === "1") {
+    console.error("  [Warning] CODEYAM_SKIP_SCRIPT_DRIFT_CHECK=1 active. Skipping streamed-script drift preflight check.");
+    return;
+  }
+
+  const { editorBranch = "main" } = resolveEditorConfig(cfg);
+
+  console.error(`Checking streamed-script drift against origin/${editorBranch}...`);
+
+  // 1. git fetch origin <editorBranch>
+  const fetchResult = spawnSync("git", ["fetch", "origin", editorBranch], { encoding: "utf8" });
+  if (fetchResult.status !== 0) {
+    console.error(`  [Warning] Failed to fetch origin ${editorBranch} (${(fetchResult.stderr || "").trim() || "unknown error"}). Skipping drift check.`);
+    return;
+  }
+
+  // 2. Find the merge base between HEAD and origin/<editorBranch>
+  const mbResult = spawnSync("git", ["merge-base", "HEAD", `origin/${editorBranch}`], { encoding: "utf8" });
+  let mergeBase = null;
+  if (mbResult.status === 0) {
+    mergeBase = mbResult.stdout.trim();
+  }
+
+  const filesData = [];
+
+  for (const scriptPath of STREAMED_SCRIPTS) {
+    // a. localHash
+    const localHashResult = spawnSync("git", ["hash-object", scriptPath], { encoding: "utf8" });
+    if (localHashResult.status !== 0) {
+      console.error(`  [Warning] Failed to compute local hash for ${scriptPath}. Skipping drift check.`);
+      return;
+    }
+    const localHash = localHashResult.stdout.trim();
+
+    // b. remoteHash (from origin/<editorBranch>)
+    let remoteHash = null;
+    const remoteHashResult = spawnSync("git", ["rev-parse", `origin/${editorBranch}:${scriptPath}`], { encoding: "utf8" });
+    if (remoteHashResult.status === 0) {
+      remoteHash = remoteHashResult.stdout.trim();
+    }
+
+    // c. baseHash (from mergeBase)
+    let baseHash = null;
+    if (mergeBase) {
+      const baseHashResult = spawnSync("git", ["rev-parse", `${mergeBase}:${scriptPath}`], { encoding: "utf8" });
+      if (baseHashResult.status === 0) {
+        baseHash = baseHashResult.stdout.trim();
+      }
+    }
+
+    // d. dirty status
+    const statusResult = spawnSync("git", ["status", "--porcelain", scriptPath], { encoding: "utf8" });
+    const dirty = statusResult.status === 0 && statusResult.stdout.trim() !== "";
+
+    filesData.push({
+      path: scriptPath,
+      localHash,
+      remoteHash,
+      baseHash,
+      dirty
+    });
+  }
+
+  const { classifyScriptDrift } = require("./script-drift");
+  const verdictResult = classifyScriptDrift({ files: filesData });
+
+  if (verdictResult.verdict === "stale" || verdictResult.verdict === "diverged") {
+    console.error("");
+    console.error("================================================================================");
+    console.error(`✗ ERROR: Streamed scripts have drifted from origin/${editorBranch}!`);
+    console.error(`  Verdict: ${verdictResult.verdict.toUpperCase()}`);
+    console.error("  The following files are out of date on your machine:");
+    for (const f of verdictResult.staleFiles) {
+      console.error(`    - ${f}`);
+    }
+    console.error("");
+    console.error("  To proceed safely, please update your local checkout first:");
+    console.error(`    git pull --no-rebase origin ${editorBranch}`);
+    console.error("");
+    console.error("  If you must bypass this check (emergency provisioning), set:");
+    console.error("    CODEYAM_SKIP_SCRIPT_DRIFT_CHECK=1");
+    console.error("================================================================================");
+    console.error("");
+    process.exit(1);
+  } else if (verdictResult.verdict === "local-ahead") {
+    console.error("  [Warning] Streaming locally-modified scripts to VM (developer mode).");
+  } else {
+    console.error("  ✓ Streamed scripts are in sync with remote.");
+  }
+}
+
 // =============================================================================
 // Subcommand handlers
 // =============================================================================
 
-async function cmdUp(args) {
+async function cmdUp(args, projectDir = rootDir) {
   ensureGcloud();
   const flags = parseFlags(args);
-  const cfg = loadOrInitCloudConfig(rootDir, flags);
+  const cfg = loadOrInitCloudConfig(projectDir, flags);
   // Fail loud BEFORE creating a GCE instance if an unprovisionable editor
   // variant was requested — otherwise we'd spin up a VM, build a dev image,
   // and silently ignore the operator's staging/production intent.
   assertVariantProvisionable(resolveEditorConfig(cfg).editorVariant);
 
+  checkScriptDrift(cfg);
+
   await ensureFirewallRule(cfg);
   const { createdThisRun } = await ensureInstance(cfg);
 
@@ -1904,6 +2147,18 @@ async function cmdUp(args) {
     // 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);
+    // Now that the editor answers on its own surface, ask it whether the
+    // pre-container seed wrong-moded the previewOrigin (the stack.json race) and
+    // heal it in place. Best-effort, never fatal — wrapped so a probe hiccup
+    // can't abort an otherwise-green add.
+    try {
+      await healPreviewOriginAtReady(cfg, appPort);
+    } catch (healErr) {
+      console.error(
+        `  Warning: READY preview-origin auto-heal probe failed (${healErr.message}); ` +
+          `the cloudflared-monitor tick will reconcile.`,
+      );
+    }
   } catch (err) {
     if (createdThisRun) {
       console.error(
@@ -1940,10 +2195,10 @@ async function cmdUp(args) {
   attachKeepAliveAndTeardown(tunnelChild);
 }
 
-async function cmdTunnel(args) {
+async function cmdTunnel(args, projectDir = rootDir) {
   ensureGcloud();
   const flags = parseFlags(args);
-  const existing = loadCloudConfig(rootDir);
+  const existing = loadCloudConfig(projectDir);
   if (!existing) {
     throw new Error(
       "No .codeyam/cloud.json found. Run `npm run cloud:up -- --repo <url>` first.",
@@ -1971,10 +2226,10 @@ async function cmdTunnel(args) {
   attachKeepAliveAndTeardown(tunnelChild);
 }
 
-async function cmdStop(args) {
+async function cmdStop(args, projectDir = rootDir) {
   ensureGcloud();
   parseFlags(args);
-  const cfg = loadCloudConfig(rootDir);
+  const cfg = loadCloudConfig(projectDir);
   if (!cfg) {
     throw new Error("No .codeyam/cloud.json found. Nothing to stop.");
   }
@@ -1990,10 +2245,10 @@ async function cmdStop(args) {
   );
 }
 
-async function cmdDestroy(args) {
+async function cmdDestroy(args, projectDir = rootDir) {
   ensureGcloud();
   parseFlags(args);
-  const cfg = loadCloudConfig(rootDir);
+  const cfg = loadCloudConfig(projectDir);
   if (!cfg) {
     throw new Error("No .codeyam/cloud.json found. Nothing to destroy.");
   }
@@ -2027,17 +2282,17 @@ async function cmdDestroy(args) {
   }
 
   try {
-    fs.unlinkSync(cloudConfigPath(rootDir));
+    fs.unlinkSync(cloudConfigPath(projectDir));
     console.error("Deleted .codeyam/cloud.json");
   } catch (e) {
     if (e.code !== "ENOENT") throw e;
   }
 }
 
-async function cmdStatus(args) {
+async function cmdStatus(args, projectDir = rootDir) {
   ensureGcloud();
   parseFlags(args);
-  const cfg = loadCloudConfig(rootDir);
+  const cfg = loadCloudConfig(projectDir);
   if (!cfg) {
     console.error("No .codeyam/cloud.json found. Run `npm run cloud:up` first.");
     return;
@@ -2131,6 +2386,7 @@ module.exports = {
   resolveSeedPreviewOrigin,
   previewSameOriginSafeFromStack,
   isRottedManagedPreviewOrigin,
+  isWrongModePreviewOrigin,
   resolveEditorConfig,
   validateEditorVariant,
   assertVariantProvisionable,
@@ -2143,9 +2399,11 @@ module.exports = {
   cloudConfigPath,
   loadCloudConfig,
   saveCloudConfig,
+  loadOrInitCloudConfig,
   buildEditorLocalEnvPatch,
   buildEditorLocalSeedWriteCommand,
   seedPreviewOrigin,
+  healPreviewOriginAtReady,
   buildGcloudArgs,
   sshScriptCommand,
   bootstrapRunnerScript,
@@ -2167,6 +2425,8 @@ module.exports = {
   ensureInstance,
   ensureBootstrapped,
   assertEditorContainerRunning,
+  checkScriptDrift,
+  STREAMED_SCRIPTS,
   // side-effecting handlers
   cmdUp,
   cmdTunnel,

package/npm/disk-pressure.js

@@ -80,10 +80,27 @@ 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,
   classifyDiskPressure,
   parseDfUsedPct,
+  classifySidecarAge,
+  mapDiskStateLevel,
 };

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-cleanup.js

@@ -297,11 +297,59 @@ function orphanedAddsToReconcile({ jobs, sidecarKeys } = {}) {
 // posture). "Busy" (a live session or an in-flight add to this number) also
 // holds the entry for an operator rather than auto-removing — the shouldn't-
 // happen-but-fail-safe case where a vanished instance still reports a session.
-function reconcileRosteredVm({ exists, hasSession, hasPendingAdd } = {}) {
+//   verdict     when                                        dispatch
+//   'cleanup'   instance gone AND the VM is idle            runDestroyCleanup
+//   'leave'     exists uncertain (null), OR the VM is busy  do nothing this pass
+//   'keep'      instance still exists                       do nothing (healthy)
+//   'reset'     existing idle instance unreachable too long trigger auto-reset
+// Fail-safe by construction: cleanup fires ONLY on a DEFINITIVE absence
+// (exists === false) — a flaky/transient describe (null) is always 'leave', so a
+// gcloud blip can never evict a healthy VM (mirroring reapVerdict's `leave`
+// posture). "Busy" (a live session or an in-flight add to this number) also
+// holds the entry for an operator rather than auto-removing — the shouldn't-
+// happen-but-fail-safe case where a vanished instance still reports a session.
+// auto-reset escalation (vm: OOM Wedge Prevention):
+// When the VM has been unreachable for at least RESET_UNREACHABLE_THRESHOLD
+// (e.g. 200, which is roughly 10 minutes at a 3s poll rate), we issue a 'reset'
+// verdict. This auto-reset is guarded and bounded by a cooldown window (in ms)
+// and a max attempts limit to prevent infinite reboot loops.
+function reconcileRosteredVm({ exists, hasSession, hasPendingAdd, streak, resetHistory, threshold, cooldownMs, maxAttempts } = {}) {
   if (exists === null || exists === undefined) return "leave";
-  if (exists) return "keep";
-  if (hasSession || hasPendingAdd) return "leave";
-  return "cleanup";
+  if (!exists) {
+    if (hasSession || hasPendingAdd) return "leave";
+    return "cleanup";
+  }
+
+  // If the VM exists, check if it's dead-unreachable and eligible for auto-reset.
+  if (streak !== undefined && threshold !== undefined) {
+    if (streak >= threshold) {
+      if (hasSession || hasPendingAdd) {
+        // Do NOT auto-reset a VM that is busy (holding a live session or an in-flight add)
+        return "keep";
+      }
+      
+      const history = resetHistory || { count: 0, lastResetAt: 0 };
+      const attempts = history.count || 0;
+      const limit = maxAttempts !== undefined ? maxAttempts : 3;
+      
+      if (attempts >= limit) {
+        // Budget exhausted (VM wedges repeatedly) -> park (needs-manual-recovery status)
+        return "keep";
+      }
+      
+      const lastReset = history.lastResetAt || 0;
+      const cooldown = cooldownMs !== undefined ? cooldownMs : 600000; // default 10 minutes
+      const now = Date.now();
+      if (now - lastReset < cooldown) {
+        // Within cooldown window -> do not reset again yet
+        return "keep";
+      }
+
+      return "reset";
+    }
+  }
+
+  return "keep";
 }
 
 module.exports = {

package/npm/fleet-roster.js

@@ -31,16 +31,14 @@ function normalizeRoster(arr) {
   return [...new Set((arr || []).filter(Number.isInteger))].sort((a, b) => a - b);
 }
 
-// Read the roster, returning a normalized integer array. A missing or malformed
-// file is treated as the empty roster `[]` (the documented contract the previous
-// `readRoster`/`loadVmsState` duplicates shared) so a truncated write or an
-// absent file never throws into a consumer's poll loop.
+// Read the roster, returning a normalized integer array, or null if the file is
+// missing or malformed.
 function readRoster() {
   try {
     const data = JSON.parse(fs.readFileSync(VMS_STATE_FILE, 'utf8'));
     if (Array.isArray(data)) return normalizeRoster(data);
-  } catch { /* missing or malformed — treated as empty */ }
-  return [];
+  } catch { /* missing or malformed */ }
+  return null;
 }
 
 // Persist `arr` as the roster, atomically: write a temp file then `rename` it
@@ -62,13 +60,13 @@ function writeRoster(arr) {
 // onSuccess rosters again — is a harmless no-op, which is exactly what closes
 // the race where one writer's roster write could fail.
 function addToRoster(n) {
-  return writeRoster([...readRoster(), n]);
+  return writeRoster([...(readRoster() || []), n]);
 }
 
 // Remove `n` from the roster, returning the new roster. Removing an absent
 // entry is a no-op.
 function removeFromRoster(n) {
-  return writeRoster(readRoster().filter((x) => x !== n));
+  return writeRoster((readRoster() || []).filter((x) => x !== n));
 }
 
 module.exports = {

package/npm/launch-config.js

@@ -123,6 +123,18 @@ function variantImageTag(variant) {
   return null; // dev / unknown — no packaged image
 }
 
+/** Return true if the value matches a known test-fixture placeholder (e.g., "gcp-proj"),
+ *  is null, empty, or whitespace, signaling that it is not a valid GCP project name.
+ *  Documented as the home for future fixture sentinels. Pure; no I/O. */
+function isPlaceholderProject(value) {
+  if (!value) return true;
+  if (typeof value !== "string") return true;
+  const trimmed = value.trim();
+  if (trimmed === "") return true;
+  if (trimmed.toLowerCase() === "gcp-proj") return true;
+  return false;
+}
+
 /** Build the `cloud:up` flag array for a launch config + instance name. The
  *  editor source is the canonical codeyam-editor repo (dev variant builds the
  *  image from editorBranch); the client repo/branch is what lands in
@@ -137,9 +149,10 @@ function cloudUpArgs(cfg, instanceName, project) {
   // a persisted .codeyam/cloud.json `project` (cloud.js merges
   // `{ ...existing, ...flags }`), which a bare cloud:up reuses verbatim with no
   // gcloud fallback — the sticky-wrong-project failure mode where a stale
-  // "gcp-proj" in cloud.json wedges every re-provision with a firewall-create
-  // PERMISSION_DENIED. Omitted when unset to preserve the pre-existing arg shape
-  // (cloud.js then falls back to the gcloud default, as before).
+  // placeholder in cloud.json (validated via isPlaceholderProject) wedges every
+  // re-provision with a firewall-create PERMISSION_DENIED. Omitted when unset to
+  // preserve the pre-existing arg shape (cloud.js then falls back to the gcloud
+  // default, as before).
   if (project) args.push("--project", project);
   // Greenfield (new folder) vs clone an existing repo.
   if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
@@ -724,4 +737,5 @@ module.exports = {
   decideStartJob,
   getAuthRepoUrl,
   interpretLsRemote,
+  isPlaceholderProject,
 };