@codeyam-editor/codeyam-editor 0.1.0-staging.gbaebe71 → 0.1.0-staging.gde2039f

package/npm/cloud.js

@@ -105,6 +105,10 @@ const {
 // edit (the invisible-VM gap improve38 closes). `readRoster` enumerates the
 // fleet for `reconcile-ingress`.
 const { addToRoster, readRoster } = require("./fleet-roster");
+// Tells a docker container-name conflict (a concurrent run already started this
+// container) apart from a real `docker compose up -d` failure, so the abort path
+// can converge instead of escalating to instance deletion.
+const { classifyComposeUpFailure } = require("./compose-conflict");
 
 // =============================================================================
 // Pure helpers — every export here is unit-tested in cloud.test.js without
@@ -845,6 +849,79 @@ function parseEditorComposeState(stdout) {
   return null;
 }
 
+/** Decide whether `cloud:up`'s abort handler may delete the instance it is
+ *  unwinding. Pure `{ createdThisRun, containerUp, rostered, probeInconclusive }
+ *  → 'delete' | 'keep'`, matching the `reapVerdict` / `reattachVerdict` /
+ *  `reconcileRosteredVm` pattern in npm/fleet-cleanup.js, so the whole matrix is
+ *  exhaustively testable without a VM.
+ *
+ *  `createdThisRun` stays a NECESSARY condition — never delete an instance this
+ *  run did not create — but 2026-08-07 proved it is not SUFFICIENT. It answers
+ *  "did I create this?", not "is it safe to destroy?", and in a concurrent
+ *  provision race the losing run legitimately owns the flag while the winner has
+ *  already brought the VM up and rostered it. Deleting there destroyed VM-4 and
+ *  VM-5. So authorization also requires CURRENT-STATE evidence that the VM is
+ *  out of service:
+ *
+ *  - `containerUp` — the editor container is running (per the compose-ps probe).
+ *    A VM serving an editor is in use by definition.
+ *  - `rostered` — the VM is in the fleet roster, the operator-visible source of
+ *    truth. Note this is true whether the winning run or THIS run rostered it;
+ *    either way the VM is visible in the dashboard and removable in one command,
+ *    so it is not the silent orphan teardown exists to prevent.
+ *  - `probeInconclusive` — liveness could not be determined. This must fail
+ *    SAFE: a failing probe is how we reach the abort handler in the first place,
+ *    so it can never count as evidence the VM is dead. An orphan costs one
+ *    `npm run cloud:destroy`; a wrong delete costs a 15-40 minute rebuild plus
+ *    any unpushed work on the VM. */
+function abortTeardownDecision({ createdThisRun, containerUp, rostered, probeInconclusive } = {}) {
+  if (!createdThisRun) return "keep";
+  if (probeInconclusive) return "keep";
+  if (containerUp) return "keep";
+  if (rostered) return "keep";
+  return "delete";
+}
+
+/** Gather the CURRENT-STATE inputs {@link abortTeardownDecision} needs, so the
+ *  abort handler reads gather → decide → act instead of inlining probes among
+ *  the delete calls.
+ *
+ *  Only runs the probes when `createdThisRun` is true — the decision is `keep`
+ *  regardless otherwise, and an abort path should not spend SSH round trips
+ *  proving something it already knows. In that case it returns the
+ *  probe-inconclusive shape, which is the safe default at every layer.
+ *
+ *  Both lookups are wrapped: a throwing probe or an unreadable roster must fail
+ *  SAFE (toward `keep`), never take a second exception path into the delete.
+ *  `deps` is injectable so the matrix is unit-tested without a VM. */
+function probeAbortTeardownState(cfg, createdThisRun, deps = {}) {
+  if (!createdThisRun) {
+    return { containerUp: false, rostered: false, probeInconclusive: true };
+  }
+  const probe = deps.probeEditorComposeState || probeEditorComposeState;
+  const roster = deps.readRoster || readRoster;
+  const resolveVm = deps.resolveFleetVmNumber || resolveFleetVmNumber;
+  const log = deps.log || ((m) => console.error(m));
+
+  let liveness = { state: null, inconclusive: true };
+  try {
+    liveness = probe(cfg);
+  } catch (e) {
+    log(`  (liveness probe failed: ${e && e.message})`);
+  }
+  let rostered = false;
+  try {
+    const vm = resolveVm(cfg.instanceName);
+    rostered = vm != null && (roster() || []).includes(vm);
+  } catch { /* unreadable roster — treated as not-rostered; liveness still guards */ }
+
+  return {
+    containerUp: liveness.state === "running",
+    rostered,
+    probeInconclusive: liveness.inconclusive,
+  };
+}
+
 /** Translate one of the wrapper's verbs into the exact `gcloud` argv. The
  *  switch's job is to keep every per-verb command shape in one reviewable
  *  place — tests assert the arrays without ever spawning a process. */
@@ -978,6 +1055,42 @@ function buildGcloudArgs(verb, cfg = {}, extras = {}) {
 // yet comfortably under the 600000 ms outer reconcile budget.
 const GCLOUD_CALL_TIMEOUT_MS = 120000;
 
+// The project bootstrap is NOT a probe: it runs `git clone` + `npm install` in
+// the repo root and every `apps[].dir`, each package's `postinstall`, then
+// `npm run setup` — minutes of remote work on a heavy repo. It once ran as ONE
+// blocking `runGcloud("ssh-script")` call, so it inherited GCLOUD_CALL_TIMEOUT_MS
+// (a budget whose own comment scopes it to "any single describe/update/SSH
+// probe"). That SIGTERMd the gcloud child mid-clone; `spawnSync` then returned
+// `status: null`, which `!== 0`, so the timeout was indistinguishable from a
+// genuine remote failure and the caller's abort path DELETED A COMPLETELY
+// HEALTHY VM.
+//
+// Observed twice: 2026-07-28 on client repo `lets-go-compost-portal` (a root
+// postinstall of `playwright install chromium`, ~293 MB), and 2026-07-29
+// provisioning six self-host `codeyam-editor` VMs, whose clone alone exceeds the
+// probe budget — all six were built, torn down mid-clone, and reported as
+// "scripts/gcp-project-bootstrap.sh failed on the VM".
+//
+// The install is now DETACHED (projectBootstrapLaunchCommand + a re-attaching
+// follow loop, outcome read from VM-side state), so no single call carries the
+// whole install any more. This constant is therefore the OVERALL deadline across
+// re-attaches — the point at which we stop waiting on a still-healthy VM and say
+// exactly that. Deliberately well above the outer reconcile budget: a long remote
+// install is not a step in a sweep, so the sweep-relative ceiling that governs
+// GCLOUD_CALL_TIMEOUT_MS does not apply to it.
+const PROJECT_BOOTSTRAP_TIMEOUT_MS = 40 * 60 * 1000;
+
+/** Whether a `spawnSync` result is a LOCAL timeout kill rather than a remote
+ *  failure. `spawnSync` reports a timeout as `status: null` plus an ETIMEDOUT
+ *  error, so a bare `status !== 0` check conflates the two — which is what made
+ *  a timed-out bootstrap look like a broken one. Pure. */
+function isSpawnTimeout(result) {
+  if (!result) return false;
+  if (result.status !== null && result.status !== undefined) return false;
+  const code = result.error && result.error.code;
+  return code === "ETIMEDOUT" || result.signal === "SIGTERM";
+}
+
 function runGcloud(args, opts = {}) {
   return spawnSync("gcloud", args, {
     stdio: opts.stdio || "inherit",
@@ -1586,6 +1699,267 @@ function bootstrapLogTail(cfg, lines = 40) {
   return String(r.stdout || "").trim() || "(log unavailable)";
 }
 
+// ─── Detached PROJECT bootstrap ──────────────────────────────────────────────
+//
+// The VM bootstrap above solved a problem the PROJECT bootstrap still had: read
+// success and failure from VM-SIDE STATE, never from the SSH exit code, so a
+// dropped follow-session over a healthy VM is not misreported as "failed on the
+// VM". The project bootstrap ran instead as ONE blocking ssh-script call, so a
+// local budget elapsing (or an SSH pipe breaking) was indistinguishable from a
+// genuine remote failure and the caller's abort path DELETED A HEALTHY VM.
+// Raising the budget alone just moves the cliff; these helpers remove it by
+// mirroring the VM-bootstrap contract — detached launch, re-attaching follow
+// loop, VM-side outcome probe.
+//
+// All VM-side paths are keyed by repo name so two projects on one VM never
+// collide, and they sit beside the `.done` marker projectBootstrapDoneMarker
+// already defines. Pure string builders (like their VM-bootstrap counterparts)
+// so the whole grammar is unit-testable without a live VM.
+function projectBootstrapScriptPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.sh`;
+}
+function projectBootstrapRunnerPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}-run.sh`;
+}
+function projectBootstrapLogPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.log`;
+}
+function projectBootstrapPidPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.pid`;
+}
+// The runner's recorded EXIT STATUS. Deliberately `.status`, NOT `.done`:
+// `.done` is already taken by scripts/gcp-project-bootstrap.sh's own terminal
+// SUCCESS marker (a timestamp, written only after `set -euo pipefail` carried
+// every step through — see projectBootstrapDoneMarker). Reusing `.done` for an
+// exit code would overwrite the success signal that both improve40's false-skip
+// fix and the follow loop below depend on. Two files, two distinct meanings:
+// `.done` = "the script reached its last line", `.status` = "the runner exited,
+// here is its code".
+function projectBootstrapStatusPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.status`;
+}
+const PROJECT_BOOTSTRAP_LAUNCHED_MARKER = "CODEYAM_PROJECT_BOOTSTRAP_LAUNCHED";
+const PROJECT_BOOTSTRAP_STATUS_MARKER = "CYPROJ";
+// One follow session caps at 15 min; the overall wait caps at
+// PROJECT_BOOTSTRAP_TIMEOUT_MS across re-attaches before we bail loudly with
+// the VM-side log location. Unlike the VM-bootstrap follow loop — whose follow
+// calls inherit the 120 s probe budget and so re-attach every two minutes over
+// a ~14-min build — the project follow call below is given an explicit local
+// budget just above this remote deadline, so a long install streams in one
+// session instead of churning re-attaches.
+const PROJECT_BOOTSTRAP_FOLLOW_SECS = 900;
+const PROJECT_BOOTSTRAP_FOLLOW_TIMEOUT_MS = (PROJECT_BOOTSTRAP_FOLLOW_SECS + 60) * 1000;
+
+// The tiny VM-side wrapper the detached launch execs: run the real bootstrap,
+// redirect all output to the per-repo log, and record the exit status in the
+// `.status` sentinel — the single source of truth for "did the runner exit, and
+// with what?" once the SSH follow-session is gone. Contains NO secrets (tokens
+// arrive via the launch env prefix, never written to disk).
+function projectBootstrapRunnerScript(repoName) {
+  return [
+    "#!/usr/bin/env bash",
+    "# Detached project-bootstrap runner (written by npm/cloud.js",
+    "# ensureProjectBootstrapped). Survives SSH disconnect: the laptop only",
+    "# *follows* the log below; this process keeps running under its own session",
+    "# if the follow drops. Records its own PID so the status probe can check",
+    "# liveness via `kill -0` (a `pgrep` on the script path would also match the",
+    "# probe command itself).",
+    `echo "$$" > "${projectBootstrapPidPath(repoName)}"`,
+    `bash "${projectBootstrapScriptPath(repoName)}" "$@" > "${projectBootstrapLogPath(repoName)}" 2>&1`,
+    "status=$?",
+    `echo "$status" > "${projectBootstrapStatusPath(repoName)}"`,
+    `rm -f "${projectBootstrapPidPath(repoName)}"`,
+    "",
+  ].join("\n");
+}
+
+// Build the remote command that (1) materializes the bootstrap script + runner
+// on the VM, (2) clears the stale sentinels, (3) launches the runner DETACHED
+// (`nohup setsid`, new session, stdio to /dev/null) so it outlives the SSH
+// session, and (4) prints a launched marker. The detach is the durable fix: the
+// install no longer dies when the laptop's SSH pipe breaks, and the VM is no
+// longer torn down because it did.
+//
+// BOTH sentinels are cleared, `.status` and `.done`. Clearing `.done` is what
+// makes the outcome probe honest: after a launch, a present `.done` can only
+// mean THIS run's script reached its terminal line, never a leftover from a
+// previous half-wired attempt.
+function projectBootstrapLaunchCommand(scriptBody, scriptArgs = [], envVars = {}, repoName) {
+  const scriptB64 = Buffer.from(scriptBody, "utf8").toString("base64");
+  const runnerB64 = Buffer.from(projectBootstrapRunnerScript(repoName), "utf8").toString("base64");
+  const argsString = scriptArgs.map(shQuote).join(" ");
+  const envPrefix = envAssignmentPrefix(envVars);
+  // Writes run synchronously (fast, before any backgrounding) so a decode error
+  // aborts before launch; then the runner is detached. The env prefix is on the
+  // setsid command so the tokens are inherited through nohup→setsid→bash but
+  // never appear in any argv. `& echo MARKER` (no `;` before echo) keeps the
+  // launch in the background while still confirming it fired.
+  const writes = [
+    `echo '${scriptB64}' | base64 -d > ${projectBootstrapScriptPath(repoName)}`,
+    `echo '${runnerB64}' | base64 -d > ${projectBootstrapRunnerPath(repoName)}`,
+    `rm -f ${projectBootstrapStatusPath(repoName)} ${projectBootstrapDoneMarker(repoName)}`,
+  ].join(" && ");
+  const launch =
+    `${envPrefix}nohup setsid bash ${projectBootstrapRunnerPath(repoName)} ${argsString}`.trimEnd() +
+    ` </dev/null >/dev/null 2>&1 &`;
+  return `${writes}; ${launch} echo ${PROJECT_BOOTSTRAP_LAUNCHED_MARKER}`;
+}
+
+// Build the remote command that FOLLOWS the detached install: tail the log live
+// for the operator, polling for the `.status` sentinel, and exit when the runner
+// finishes OR a per-session deadline elapses. If the SSH session drops
+// mid-follow this command dies but the detached install keeps going — the caller
+// then re-attaches.
+function projectBootstrapFollowCommand(repoName, deadlineSecs = PROJECT_BOOTSTRAP_FOLLOW_SECS) {
+  const log = projectBootstrapLogPath(repoName);
+  const status = projectBootstrapStatusPath(repoName);
+  return [
+    `touch ${log}`,
+    `tail -n +1 -F ${log} 2>/dev/null & TP=$!`,
+    `waited=0`,
+    `while [ ! -f ${status} ]; do ` +
+      `sleep 3; waited=$((waited+3)); ` +
+      `if [ "$waited" -ge ${deadlineSecs} ]; then kill "$TP" 2>/dev/null; exit 0; fi; ` +
+      `done`,
+    `sleep 1`,
+    `kill "$TP" 2>/dev/null`,
+  ].join("; ");
+}
+
+// Build the remote command that reports terminal VM state in one parseable
+// line: whether the script's terminal `.done` marker exists, the runner's
+// recorded exit status (or `none`), and whether the runner is still alive.
+// Cheap — runs over ssh-probe.
+function projectBootstrapStatusCommand(repoName) {
+  const pid = projectBootstrapPidPath(repoName);
+  const status = projectBootstrapStatusPath(repoName);
+  // Liveness via the runner's PID file + `kill -0`, NOT pgrep: the status
+  // command's own argv contains the bootstrap path, so a `pgrep -f` on it would
+  // match this very probe and always report running. A stale PID file from a
+  // killed runner reads as not-running because `kill -0` fails.
+  return [
+    `done=no; [ -f ${projectBootstrapDoneMarker(repoName)} ] && done=yes`,
+    `st=none; [ -f ${status} ] && st=$(cat ${status} 2>/dev/null)`,
+    `run=no; if [ -f ${pid} ]; then p=$(cat ${pid} 2>/dev/null); ` +
+      `{ [ -n "$p" ] && kill -0 "$p" 2>/dev/null; } && run=yes; fi`,
+    `echo "${PROJECT_BOOTSTRAP_STATUS_MARKER} done=$done status=$st running=$run"`,
+  ].join("; ");
+}
+
+// Parse the single status line emitted by projectBootstrapStatusCommand.
+// Returns `{ done, status, running }` or null when no status line is present
+// (e.g. the probe ssh itself failed and produced no stdout).
+function parseProjectBootstrapStatus(stdout) {
+  const m = String(stdout || "").match(
+    new RegExp(`${PROJECT_BOOTSTRAP_STATUS_MARKER} done=(\\S+) status=(\\S+) running=(\\S+)`),
+  );
+  if (!m) return null;
+  return { done: m[1], status: m[2], running: m[3] };
+}
+
+// Decide the project-bootstrap outcome from VM-side state alone — never the SSH
+// exit code. The `.done` marker is the real artifact (the script writes it only
+// after `set -euo pipefail` carried every step to success), so its presence is
+// success regardless of how the follow session ended — the same reasoning that
+// makes the docker image authoritative for the VM bootstrap. A live runner means
+// "re-attach". A recorded exit status without the marker means the install ran
+// and failed. Nothing at all means it was never started (or the probe could not
+// see it).
+function decideProjectBootstrapOutcome(status) {
+  if (!status) return "absent";
+  const { done, status: exitStatus, running } = status;
+  if (done === "yes") return "success";
+  if (running === "yes") return "running";
+  if (exitStatus && exitStatus !== "none") return "failed";
+  return "absent";
+}
+
+// Reduce one follow-loop iteration to an action: "success" | "failed" |
+// "timeout" | "reattach". Extracted as a pure function because its PRECEDENCE is
+// load-bearing — it decides whether an operator is told a VM is broken:
+//
+//   • success and failed outrank the deadline. Otherwise the final poll of a
+//     slow-but-successful bootstrap reports a timeout, and the operator is sent
+//     to reconcile a VM that actually finished.
+//   • a still-running install past the deadline is a TIMEOUT, never a failure.
+//     That is the VM-8 case: healthy VM, still installing, and saying so is what
+//     gets the add classified retryable instead of destroyed.
+//   • an unseen runner ("absent") before the deadline re-attaches rather than
+//     failing — "I could not see it" is not "it broke" — but is still bounded by
+//     the deadline so the loop cannot spin forever.
+function decideProjectBootstrapFollowAction({ outcome, now, deadline } = {}) {
+  if (outcome === "success") return "success";
+  if (outcome === "failed") return "failed";
+  if (now >= deadline) return "timeout";
+  return "reattach";
+}
+
+// Probe the VM for the detached project bootstrap's terminal state and reduce it
+// to a single outcome string ("success" | "failed" | "running" | "absent").
+// Used both for the idempotent re-attach decision and after each follow session.
+function probeProjectBootstrapOutcome(cfg, repoName) {
+  const r = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, { command: projectBootstrapStatusCommand(repoName) }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  return decideProjectBootstrapOutcome(parseProjectBootstrapStatus(r.stdout));
+}
+
+/** Assemble the env forwarded into the project-bootstrap shell on the VM.
+ *  Extracted from ensureProjectBootstrapped so its CONDITIONAL keys are testable
+ *  without a VM — previously you could not assert "FLEET_DOMAIN is omitted for a
+ *  non-fleet project" or "a re-provision without --admin stays non-admin"
+ *  without invoking the whole gcloud-touching bootstrap.
+ *
+ *  Keys, and why each is here:
+ *    GITHUB_TOKEN                  — clone a private client repo.
+ *    CY_GIT_USER_{NAME,EMAIL}      — rendered into the compose file, then written
+ *                                    to `git config --global` by the entrypoint so
+ *                                    plan_claim_refs::create_claim's commit-tree
+ *                                    call succeeds. Empty is legitimate (a CI
+ *                                    runner with no author); the entrypoint warns
+ *                                    and proceeds, so the keys stay present.
+ *    FLEET_DOMAIN                  — ONLY for a numbered fleet VM with a domain
+ *                                    configured, so the compose render publishes
+ *                                    on 0.0.0.0 for the LB NEG. Omitted entirely
+ *                                    otherwise, preserving the loopback-only
+ *                                    publish a plain client project expects.
+ *    <forwarded launch-form keys>  — DATABASE_URL et al, whitelisted by the
+ *                                    dashboard via CY_FORWARD_ENV_KEYS, so the
+ *                                    bootstrap-time `npm run setup` sees them on
+ *                                    the first try. Empty on plain `cloud:up`.
+ *    CODEYAM_ADMIN                 — the Home-tab Setup door. Defaults to the
+ *                                    strict non-admin "".
+ *
+ *  Later spreads win, matching the original inline assembly exactly. `deps` lets
+ *  a test supply the token and git identity instead of reading the real
+ *  environment and shelling out to git. */
+function projectBootstrapEnv(cfg = {}, { env = process.env, githubToken, gitIdentity } = {}) {
+  const git = gitIdentity || resolveLaptopGitIdentity();
+  const out = {
+    GITHUB_TOKEN: githubToken !== undefined ? githubToken : resolveGithubToken(),
+    CY_GIT_USER_NAME: git.name,
+    CY_GIT_USER_EMAIL: git.email,
+  };
+  const ingressPlan = ingressWiringPlan(cfg, env);
+  if (ingressPlan.wire) out.FLEET_DOMAIN = ingressPlan.domain;
+  Object.assign(out, resolveSetupForwardEnv(env));
+  Object.assign(out, buildProvisionEnv(env, cfg));
+  return out;
+}
+
+// Fetch the tail of the VM-side project-bootstrap log for an actionable failure
+// message — the operator sees WHY the install failed, not a bare exit code.
+function projectBootstrapLogTail(cfg, repoName, lines = 40) {
+  const r = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `tail -n ${lines} ${projectBootstrapLogPath(repoName)} 2>/dev/null`,
+    }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  return String(r.stdout || "").trim() || "(log unavailable)";
+}
+
 /** Assemble the extra provision-time env forwarded into the bootstrap shell,
  *  where it feeds the compose-render substitution. Currently just the admin
  *  toggle: CODEYAM_ADMIN gates the Home-tab Setup door and is read from the
@@ -1623,7 +1997,7 @@ function buildReconcileAdminCommand(repoName, value) {
   );
 }
 
-async function ensureProjectBootstrapped(cfg) {
+async function ensureProjectBootstrapped(cfg, { sleepFn } = {}) {
   const repoName = resolveProject(cfg).name;
   console.error(`Checking project bootstrap state for ${repoName}...`);
   // Gate on the TERMINAL completion marker the script writes as its very last
@@ -1653,49 +2027,154 @@ async function ensureProjectBootstrapped(cfg) {
   const scriptPath = path.join(rootDir, "scripts", "gcp-project-bootstrap.sh");
   const scriptBody = readStreamedScript(scriptPath, cfg);
   const scriptArgs = clientProjectBootstrapArgs(cfg);
-  // Forward the laptop's git author identity so the rendered compose file
-  // carries CY_GIT_USER_{NAME,EMAIL} → the entrypoint writes them to
-  // `git config --global` → plan_claim_refs::create_claim's commit-tree call
-  // succeeds. Empty strings are fine (laptop has no identity, e.g. a CI
-  // runner); the entrypoint warns and proceeds.
-  const laptopGit = resolveLaptopGitIdentity();
-  // Forward the operator's launch-form env keys (DATABASE_URL, etc.) into the
-  // bootstrap shell so the bootstrap-time `npm run setup` sees them on the
-  // first try — without this, Prisma `db:push`/`db:seed` fail for lack of
-  // env and the bootstrap's fail-soft branch leaves the app schema-less until
-  // the post-add `reapplyVmEnv` re-fires setup. See
-  // `improve37-launch-form-env-injected-into-cloud-up-bootstrap-not-just-applied-after`.
-  // Whitelisted by the dashboard via CY_FORWARD_ENV_KEYS — empty on the
-  // standalone `cloud:up` path, so that flow is unchanged.
-  const forwardEnv = resolveSetupForwardEnv();
-  // Forward the fleet domain so the bootstrap's compose render publishes the
-  // editor/app ports on 0.0.0.0 (the LB NEG reaches them on the VM's internal
-  // IP) instead of loopback-only. Only when a fleet domain is configured AND
-  // this is a numbered fleet VM — a non-fleet client project keeps the
-  // loopback-only publish (legacy parity). Absent ⇒ key omitted entirely.
-  const ingressEnv = {};
-  const ingressPlan = ingressWiringPlan(cfg);
-  if (ingressPlan.wire) ingressEnv.FLEET_DOMAIN = ingressPlan.domain;
-  // Forward the admin-mode toggle (Home-tab Setup door) into the compose
-  // render. cfg.admin carries the `--admin` flag; process.env.CODEYAM_ADMIN
-  // carries the `CODEYAM_ADMIN=1 npm run cloud:up` form. Default "" =
-  // non-admin, so this leaves the normal launch and re-provision unchanged.
-  const provisionEnv = buildProvisionEnv(process.env, cfg);
-  const command = sshScriptCommand(scriptBody, scriptArgs, {
-    GITHUB_TOKEN: resolveGithubToken(),
-    CY_GIT_USER_NAME: laptopGit.name,
-    CY_GIT_USER_EMAIL: laptopGit.email,
-    ...ingressEnv,
-    ...forwardEnv,
-    ...provisionEnv,
-  });
-  const result = runGcloud(
-    buildGcloudArgs("ssh-script", cfg, { command }),
-    { stdio: "inherit" },
+  // Git identity, forwarded launch-form keys, fleet-domain ingress and the admin
+  // toggle — see projectBootstrapEnv for what each key is for and when it is
+  // omitted. Extracted so those conditionals are testable without a VM.
+  const bootstrapEnv = projectBootstrapEnv(cfg);
+
+  // Idempotent re-attach: a prior cloud:up whose follow-session dropped may have
+  // left a detached install still running. Converge on it instead of starting a
+  // second `npm install` on top of the first.
+  //
+  // NOTE the deliberate asymmetry with ensureBootstrapped, which DOES return
+  // early on an outcome of "success". There, the done-probe and the outcome probe
+  // read the same artifact (the docker image), so they always agree. Here the
+  // done-probe above is a strictly STRONGER three-way AND (`.done` marker +
+  // ~/projects/<repo>/.codeyam + docker-compose.cloud.yml) than this probe's
+  // `.done`-alone success, and it has already said no. Honoring a bare `.done`
+  // here would re-open the improve40 VM-7 false-skip from the other side, so only
+  // "running" short-circuits the launch.
+  const initial = probeProjectBootstrapOutcome(cfg, repoName);
+  if (initial === "running") {
+    console.error("  ↺ a detached project bootstrap is already in progress — re-attaching to its log...");
+  } else {
+    // "absent" (never started), "failed" (a prior run died), or "success" (a bare
+    // marker the stricter done-probe rejected) → (re)launch a fresh detached
+    // install that will survive an SSH disconnect. Every step of
+    // gcp-project-bootstrap.sh is skip-on-exists, so re-entering is cheap.
+    console.error("  launching detached project bootstrap on the VM (survives SSH disconnect)...");
+    const launch = projectBootstrapLaunchCommand(scriptBody, scriptArgs, bootstrapEnv, repoName);
+    const launched = await runGcloudSshWithRetry(
+      "ssh-script",
+      cfg,
+      { command: launch },
+      { stdio: ["ignore", "pipe", "pipe"], label: "project bootstrap launch", sleepFn },
+    );
+    if (isSpawnTimeout(launched)) {
+      // The LOCAL budget elapsed and we SIGTERMd the gcloud child. Say so:
+      // the launch is a short write-and-detach, so this is an SSH-reachability
+      // problem, NOT a broken bootstrap script — and the VM may be perfectly
+      // healthy. Conflating the two is what destroyed VM-8.
+      throw new Error(
+        `launching the detached project bootstrap exceeded the local gcloud call budget ` +
+          `and was SIGTERMd locally — the VM may be healthy and simply unreachable over SSH ` +
+          `right now. Re-run to re-attach (each bootstrap step is skip-on-exists).`,
+      );
+    }
+    if (launched.status !== 0) {
+      throw new Error(
+        `failed to launch the detached project bootstrap on the VM (gcloud ssh exit ${launched.status}).\n` +
+          formatGcloudFailure(launched),
+      );
+    }
+  }
+
+  // Follow the live log, re-attaching across any follow-session drops, until the
+  // VM reports a terminal state or the overall deadline elapses. Success and
+  // failure are read from VM state (the `.done` marker + the `.status` sentinel),
+  // never the SSH exit code — so "my laptop's SSH dropped" or "a heavy npm
+  // install outran a local budget" no longer masquerades as a broken bootstrap
+  // and no longer gets a healthy VM deleted.
+  const deadline = Date.now() + PROJECT_BOOTSTRAP_TIMEOUT_MS;
+  for (;;) {
+    runGcloud(
+      buildGcloudArgs("ssh-script", cfg, { command: projectBootstrapFollowCommand(repoName) }),
+      { stdio: "inherit", timeout: PROJECT_BOOTSTRAP_FOLLOW_TIMEOUT_MS },
+    );
+    const outcome = probeProjectBootstrapOutcome(cfg, repoName);
+    const action = decideProjectBootstrapFollowAction({
+      outcome,
+      now: Date.now(),
+      deadline,
+    });
+    if (action === "success") {
+      console.error(`  ✓ ${repoName} bootstrap complete`);
+      return;
+    }
+    if (action === "failed") {
+      const tail = projectBootstrapLogTail(cfg, repoName);
+      throw new Error(
+        "scripts/gcp-project-bootstrap.sh failed on the VM. " +
+          `Last lines of ${projectBootstrapLogPath(repoName)}:\n${tail}`,
+      );
+    }
+    if (action === "timeout") {
+      // The install is STILL RUNNING on a healthy VM and we simply stopped
+      // waiting. This message is the signature npm/fleet-add-failure.js keys on
+      // to classify the add as `project-bootstrap-timeout` (retryable) instead of
+      // the non-retryable generic cloud-up-failed that tore down VM-8.
+      throw new Error(
+        `project bootstrap exceeded the local ${Math.round(PROJECT_BOOTSTRAP_TIMEOUT_MS / 60000)}-minute budget ` +
+          `— the VM and its detached bootstrap may be healthy and still running. ` +
+          `Re-run to re-attach (each bootstrap step is skip-on-exists), or inspect ` +
+          `${projectBootstrapLogPath(repoName)} on the VM.`,
+      );
+    }
+    // action === "reattach": the follow session ended but the install is alive
+    // (or the probe could not see it yet). Re-attach to its log.
+    console.error("  ↺ follow session ended but the project bootstrap is still running — re-attaching...");
+  }
+}
+
+/** Run the compose-ps liveness probe over SSH and report BOTH the editor
+ *  service's state and whether the probe itself could be trusted.
+ *
+ *  The `|| true` keeps the remote pipeline's exit status 0 whenever SSH itself
+ *  worked, so a non-zero `status` means the transport failed (auth/SSH/IAP) —
+ *  not that the container is down. Callers that must fail safe (the abort
+ *  teardown) need that distinction; `parseEditorComposeState` alone collapses
+ *  "no container" and "could not ask" into the same `null`.
+ *
+ *  Returns `{ state, inconclusive }` where `state` is the compose `State` string
+ *  (`"running"`, `"exited"`, …) or null when the service is absent, and
+ *  `inconclusive` is true only for a transport failure. */
+function probeEditorComposeState(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 (result.status !== 0) {
-    throw new Error("scripts/gcp-project-bootstrap.sh failed on the VM");
+  if (probe.status !== 0) {
+    return { state: null, inconclusive: true };
   }
+  return { state: parseEditorComposeState(probe.stdout), inconclusive: false };
+}
+
+/** Poll {@link probeEditorComposeState} until the editor service reads
+ *  `running`, returning true as soon as it does. Used to close the TOCTOU window
+ *  after a container-name conflict: the winning run may still be inside
+ *  `Creating`/`Created` when the conflict surfaces, so a single immediate probe
+ *  can under-read and report a healthy container as absent.
+ *
+ *  Deliberately short (default ~30s): this is not the multi-minute first-boot
+ *  budget `waitForContainerRunning` grants, it is the tail of a start that
+ *  another process has already begun. `sleepFn` and `probeFn` are injectable so
+ *  a unit test drives the whole loop with neither wall-clock delay nor a VM. */
+async function waitForEditorComposeRunning(cfg, { attempts = 6, delayMs = 5000, sleepFn, probeFn } = {}) {
+  const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const probe = probeFn || probeEditorComposeState;
+  for (let i = 0; i < attempts; i++) {
+    if (probe(cfg).state === "running") {
+      return true;
+    }
+    if (i < attempts - 1) {
+      await sleep(delayMs);
+    }
+  }
+  return false;
 }
 
 async function ensureEditorContainerUp(cfg) {
@@ -1705,13 +2184,7 @@ async function ensureEditorContainerUp(cfg) {
   // cloud variant when self-hosting (see gcp-project-bootstrap.sh).
   const composeCmd = `docker compose -f docker-compose.cloud.yml`;
   console.error("Checking editor container state...");
-  const probe = runGcloud(
-    buildGcloudArgs("ssh-probe", cfg, {
-      command: `cd ~/projects/${repoName} && ${composeCmd} ps --format json 2>/dev/null || true`,
-    }),
-    { stdio: ["ignore", "pipe", "ignore"] },
-  );
-  if (probe.status === 0 && parseEditorComposeState(probe.stdout) === "running") {
+  if (probeEditorComposeState(cfg).state === "running") {
     console.error("  ✓ editor container is already running");
     // containerStarted: the container is confirmed up, so the CLI install runs
     // its POST-start path with no wait — see the precondition on ensureAgentCliInstalled.
@@ -1719,14 +2192,47 @@ async function ensureEditorContainerUp(cfg) {
     return;
   }
   console.error("  starting editor container (docker compose up -d)...");
+  // CAPTURE rather than `stdio: "inherit"`: the daemon writes its container-name
+  // conflict to stderr, and with "inherit" that text went straight to our parent
+  // and was never observable here — so the conflict could not be told apart from
+  // a real failure (the 2026-08-07 VM-4/VM-5 delete). spawnSync cannot both
+  // stream and capture, so the operator's view is preserved by echoing the
+  // captured streams immediately below instead of live. Do NOT revert this to
+  // "inherit"; classification depends on it.
   const up = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
       command: `cd ~/projects/${repoName} && ${composeCmd} up -d`,
     }),
-    { stdio: "inherit" },
+    { stdio: ["ignore", "pipe", "pipe"] },
   );
+  if (up.stdout) process.stderr.write(up.stdout);
+  if (up.stderr) process.stderr.write(up.stderr);
   if (up.status !== 0) {
-    throw new Error("docker compose up -d failed on the VM");
+    const verdict = classifyComposeUpFailure({ status: up.status, stderr: `${up.stderr || ""}\n${up.stdout || ""}` });
+    if (verdict !== "name-conflict") {
+      throw new Error("docker compose up -d failed on the VM");
+    }
+    // A name conflict means a concurrent run already created this container —
+    // the goal we were about to pursue is being reached by someone else. Confirm
+    // that positively before converging: a conflict whose container never
+    // reaches `running` (e.g. a stale STOPPED container squatting the name) is a
+    // genuine problem and must still fail loudly, or convergence becomes a
+    // catch-all that papers over real breakage.
+    console.error(
+      "  a concurrent run already created the editor container — confirming it reaches running...",
+    );
+    if (!(await waitForEditorComposeRunning(cfg))) {
+      throw new Error(
+        "docker compose up -d hit a container-name conflict on the VM, but the conflicting " +
+          "container never reached running (a stale stopped container may be holding the name). " +
+          `Inspect with: gcloud compute ssh ${cfg.instanceName} --command 'cd ~/projects/${repoName} && ${composeCmd} ps -a'`,
+      );
+    }
+    console.error("  ✓ editor container is running (started by a concurrent run)");
+    // containerStarted: the container is confirmed up — same post-start contract
+    // as the already-running short-circuit above.
+    await ensureAgentCliInstalled(cfg, { containerStarted: true });
+    return;
   }
   // containerStarted: `up -d` returned 0, so the CLI install is legitimately a
   // post-start step. A brief wait-for-running here (slow boot settling) is
@@ -1742,18 +2248,10 @@ async function ensureEditorContainerUp(cfg) {
 // 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.
+// on. An inconclusive probe is not "running" here — a terminal gate must have
+// positive evidence, and the caller's job is to fail loudly without it.
 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")) {
+  if (probeEditorComposeState(cfg).state !== "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}`,
@@ -3771,7 +4269,27 @@ async function cmdUp(args, projectDir = rootDir) {
       );
     }
   } catch (err) {
-    if (createdThisRun) {
+    // `createdThisRun` alone MUST NOT authorize deletion. Gather what state the
+    // VM is in right now, then let the pure decision rule — see
+    // abortTeardownDecision's doc comment for why each input is load-bearing.
+    const state = probeAbortTeardownState(cfg, createdThisRun);
+    const verdict = abortTeardownDecision({ createdThisRun, ...state });
+    if (createdThisRun && verdict === "keep") {
+      // Deliberately loud and specific. The old blanket "tearing down the VM
+      // cloud:up created this run (no orphan left behind)" was actively
+      // misleading here — it asserted no orphan while deleting a working VM.
+      const why = state.probeInconclusive
+        ? "its liveness could not be confirmed (probe failed), and an unconfirmed VM is never deleted"
+        : state.containerUp
+          ? "its editor container is RUNNING — another run brought it up"
+          : "it is in the fleet roster and visible to the dashboard";
+      console.error(
+        `✗ provisioning aborted — the VM ${cfg.instanceName} was LEFT IN PLACE because ${why}.\n` +
+          `  This run created the instance, but that alone does not authorize deleting a VM that is in service.\n` +
+          `  If it really should go, remove it deliberately: npm run cloud:destroy`,
+      );
+    }
+    if (verdict === "delete") {
       console.error(
         `✗ provisioning aborted — tearing down the VM cloud:up created this run (no orphan left behind)`,
       );
@@ -3953,14 +4471,7 @@ async function cmdStatus(args, projectDir = rootDir) {
   const imgStatus = String(imgProbe.stdout || "").trim() || "?";
   console.error(`  image:            ${imgStatus}`);
 
-  const repoName = resolveProject(cfg).name;
-  const containerProbe = runGcloud(
-    buildGcloudArgs("ssh-probe", cfg, {
-      command: `cd ~/projects/${repoName} 2>/dev/null && docker compose -f docker-compose.cloud.yml ps --format json 2>/dev/null || echo`,
-    }),
-    { stdio: ["ignore", "pipe", "ignore"] },
-  );
-  const containerStatus = parseEditorComposeState(containerProbe.stdout) || "missing";
+  const containerStatus = probeEditorComposeState(cfg).state || "missing";
   console.error(`  editor container: ${containerStatus}`);
 
   const appPort = await readVmAppPort(cfg);
@@ -4368,7 +4879,14 @@ function sweepOrphanIngress({ cfg, domain, roster, projectDir = rootDir } = {},
     });
     const res = run(inv.command, inv.args, { encoding: "utf8", env: { ...process.env, ...inv.env } });
     const verdict = parseIngressTeardownVerdict((res && res.stdout) || "");
-    const outcome = classifyOrphanDownResult({ verdict, status: res ? res.status : null });
+    // Pass `signal` too: a teardown the caller's group-kill reaped has a NULL
+    // status, which the classifier would otherwise report as `spawn-failed`
+    // rather than the truthful `killed=SIGKILL`.
+    const outcome = classifyOrphanDownResult({
+      verdict,
+      status: res ? res.status : null,
+      signal: res ? res.signal : null,
+    });
     if (outcome.cleaned) {
       summary.cleaned.push(n);
       console.error(`  VM-${n}: orphaned ingress → auto-cleaned (verified clean)`);
@@ -4689,6 +5207,7 @@ async function cloudMain() {
 
 module.exports = {
   // pure helpers
+  isSpawnTimeout,
   agentEnvVarName,
   agentNpmPackage,
   AGENT_ENV_VARS,
@@ -4699,6 +5218,9 @@ module.exports = {
   assertAgentCliInstalled,
   probeContainerRunning,
   probeContainerState,
+  waitForEditorComposeRunning,
+  abortTeardownDecision,
+  probeAbortTeardownState,
   probeAgentBinaryInstalled,
   waitForContainerRunning,
   KNOWN_FLAGS,
@@ -4758,6 +5280,22 @@ module.exports = {
   decideBootstrapOutcome,
   projectBootstrapDoneMarker,
   projectBootstrapDoneProbeCommand,
+  projectBootstrapScriptPath,
+  projectBootstrapRunnerPath,
+  projectBootstrapLogPath,
+  projectBootstrapPidPath,
+  projectBootstrapStatusPath,
+  projectBootstrapRunnerScript,
+  projectBootstrapLaunchCommand,
+  projectBootstrapFollowCommand,
+  projectBootstrapStatusCommand,
+  parseProjectBootstrapStatus,
+  decideProjectBootstrapOutcome,
+  decideProjectBootstrapFollowAction,
+  projectBootstrapEnv,
+  PROJECT_BOOTSTRAP_LAUNCHED_MARKER,
+  PROJECT_BOOTSTRAP_FOLLOW_SECS,
+  ensureProjectBootstrapped,
   SSH_KEEPALIVE_FLAGS,
   resolveSetupForwardEnv,
   FORWARD_ENV_KEYS_ENV,