@codeyam-editor/codeyam-editor 0.1.0-staging.g296f8a2 → 0.1.0-staging.g3858572

package/npm/cloud.js

@@ -59,6 +59,7 @@ const {
   normalizePrincipal,
   resolveDefaultOperator,
   withDefaultOperator,
+  unauthorizableAddRefusal,
   accessFor,
   setAccess,
   addAccess,
@@ -105,6 +106,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 +850,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. */
@@ -2049,20 +2127,65 @@ async function ensureProjectBootstrapped(cfg, { sleepFn } = {}) {
   }
 }
 
-async function ensureEditorContainerUp(cfg) {
+/** 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;
-  // -f docker-compose.cloud.yml everywhere: the editor repo's own
-  // docker-compose.yml does `build: .` from source and would shadow the
-  // 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`,
+      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 (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) {
+  const repoName = resolveProject(cfg).name;
+  // -f docker-compose.cloud.yml everywhere: the editor repo's own
+  // docker-compose.yml does `build: .` from source and would shadow the
+  // 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...");
+  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.
@@ -2070,14 +2193,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
@@ -2093,18 +2249,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}`,
@@ -3461,8 +3609,9 @@ function fleetInstancePrefix() {
  *  scripts/gcp/vm-ingress.sh with the resolved coordinates. Returns the spawnSync
  *  result so callers decide fatality — Add treats a non-zero as a loud warning
  *  (the VM is provisioned; ingress can be re-wired), Destroy likewise warns so a
- *  teardown still removes the instance. */
-function runVmIngress(cfg, action, vmNumber, domain, appPort, slug) {
+ *  teardown still removes the instance. `vmAccess` (up only) is the Add's intended
+ *  principal set, which the script's grant step uses in place of its sidecar read. */
+function runVmIngress(cfg, action, vmNumber, domain, appPort, slug, vmAccess) {
   const scriptPath = path.join(rootDir, "scripts", "gcp", "vm-ingress.sh");
   const inv = vmIngressInvocation({
     scriptPath,
@@ -3474,6 +3623,7 @@ function runVmIngress(cfg, action, vmNumber, domain, appPort, slug) {
     appPort,
     instancePrefix: fleetInstancePrefix(),
     slug,
+    vmAccess,
   });
   return spawnSync(inv.command, inv.args, {
     stdio: "inherit",
@@ -3504,17 +3654,77 @@ function runVmIngressGrantAccess(cfg, vmNumber, domain, slug) {
   });
 }
 
+/** THE principal set that must have IAP access to this VM after the Add: the
+ *  explicit `cfg.vmAccess` collaborators unioned with the resolved default
+ *  operator. Both add-time access paths consume this ONE function —
+ *  `wireVmIngressOnAdd` (which hands it to vm-ingress.sh's grant) and
+ *  `applyVmAccessOnAdd` (which grants it and subtracts it from the stale-revoke
+ *  set). They used to decide independently, and that is precisely how one path
+ *  granted `user:jared@codeyam.com` at 00:09:31 and the other revoked the same
+ *  principal 18 seconds later as a "stale prior tenant" (VMs 4/5/6, 2026-08-09):
+ *  the ingress path read the SIDECAR (still holding the prior tenant) while
+ *  `applyVmAccessOnAdd` resolved an empty operator. One source of truth removes
+ *  the whole class of disagreement. `env` is injectable for tests; the only I/O
+ *  is `resolveDefaultOperator`'s config/gcloud read. */
+function intendedVmPrincipals(cfg = {}, env = process.env) {
+  return withDefaultOperator(
+    normalizeAccessList(cfg.vmAccess || []),
+    resolveDefaultOperator({ env }),
+  );
+}
+
+/** Add preflight: throw — BEFORE any GCE instance exists — when this Add would
+ *  come up on an IAP-gated public URL that authorizes NOBODY. The whole condition
+ *  is env + config (`intendedVmPrincipals` needs no GCP state), which is why it
+ *  belongs beside cmdUp's other cheap boundary validations rather than after a
+ *  machine has been provisioned: checking later means a half-provisioned VM to
+ *  clean up. On 2026-08-09 the un-refused version of this Add reported `done` for
+ *  VMs 4/5/6, left three unreachable URLs, and revoked each slot's prior tenant on
+ *  the way.
+ *
+ *  Only fires in LB mode on a numbered fleet VM with nothing to grant; an explicit
+ *  `--vm-access` satisfies it with no default operator configured, so the
+ *  collaborator flow is unaffected, as is every legacy quick-tunnel Add. The
+ *  refusal text (and its `Next valid action:` remedy naming all three config
+ *  tiers) is the pure `unauthorizableAddRefusal`; this function is the composition
+ *  and the throw. */
+function assertAddCanAuthorizeSomeone(cfg, env = process.env) {
+  let plan;
+  try {
+    plan = ingressWiringPlan(cfg, env);
+  } catch {
+    // A malformed domain is `resolveIngressDomain`'s error to raise on the wiring
+    // path; it must not masquerade here as an authorization refusal.
+    plan = { wire: false };
+  }
+  const refusal = unauthorizableAddRefusal({
+    lbMode: !!plan.wire,
+    vmNumber: plan.wire ? plan.vmNumber : null,
+    intendedCount: plan.wire ? intendedVmPrincipals(cfg, env).length : null,
+  });
+  if (refusal) throw new Error(refusal);
+}
+
 /** Add-time hook: wire VM-N onto the shared LB when a fleet domain is set.
  *  Best-effort + loud — a wiring hiccup must never abort an otherwise-green Add
  *  (the VM is reachable operator-side over SSH regardless), so on failure it
  *  prints the exact re-run command rather than throwing. No-op (and silent) in
- *  legacy quick-tunnel mode or for a non-fleet client project. */
+ *  legacy quick-tunnel mode or for a non-fleet client project.
+ *
+ *  RETURNS the principals this call granted (`intendedVmPrincipals`), or [] when
+ *  it did not wire — the explicit dataflow `applyVmAccessOnAdd` needs to know what
+ *  the Add has already granted before it computes a stale-revoke. Returned on the
+ *  FAILURE path too: a non-zero `vm-ingress.sh up` may still have completed its
+ *  grant step, and a principal that was possibly granted must never be revoked. */
 function wireVmIngressOnAdd(cfg, appPort, env = process.env) {
   const plan = ingressWiringPlan(cfg, env);
-  if (!plan.wire) return;
+  if (!plan.wire) return [];
   const label = plan.slug || `vm-${plan.vmNumber}`;
+  // Hand the intended set to the script so its `apply_default_iap_access` grants
+  // THIS Add's principals instead of reading the sidecar's prior tenant.
+  const vmAccess = intendedVmPrincipals(cfg, env);
   console.error(`  wiring LB ingress for VM-${plan.vmNumber} on ${plan.domain}...`);
-  const res = runVmIngress(cfg, "up", plan.vmNumber, plan.domain, appPort, plan.slug);
+  const res = runVmIngress(cfg, "up", plan.vmNumber, plan.domain, appPort, plan.slug, vmAccess);
   if (res.status === 0) {
     console.error(`  ✓ LB ingress wired: https://${label}.editor.${plan.domain}`);
   } else {
@@ -3536,6 +3746,7 @@ function wireVmIngressOnAdd(cfg, appPort, env = process.env) {
         `(vm-ingress.sh up exited ${res.status == null ? "abnormally" : res.status}). Re-wire: ${rewire}`,
     );
   }
+  return vmAccess;
 }
 
 /** Destroy-time hook: unwire VM-N's LB backends before the instance is deleted,
@@ -3604,8 +3815,15 @@ function runIapAccess(cfg, vmNumber, action, principals) {
  *  a revoke/grant hiccup (e.g. the SA missing IAP-admin) prints the exact re-run
  *  command rather than aborting an otherwise-green Add. `cfg.vmAccess` is the
  *  array (or comma-separated string) cmdUp validated; absent ⇒ an empty desired
- *  list (the clean-slate case). */
-function applyVmAccessOnAdd(cfg, env = process.env) {
+ *  list (the clean-slate case).
+ *
+ *  `grantedThisRun` is what an EARLIER step of this same Add already granted —
+ *  `wireVmIngressOnAdd`'s return value. It is subtracted from the stale-revoke
+ *  set, so a principal this Add just authorized can never be revoked moments later
+ *  as a prior tenant. That is a second, cheaper guard than the shared
+ *  `intendedVmPrincipals` resolver above: it holds even if the two paths drift
+ *  apart again, which is exactly how VMs 4/5/6 broke on 2026-08-09. */
+function applyVmAccessOnAdd(cfg, env = process.env, { grantedThisRun = [] } = {}) {
   const desired = normalizeAccessList(cfg.vmAccess || []);
   let plan;
   try {
@@ -3622,11 +3840,15 @@ function applyVmAccessOnAdd(cfg, env = process.env) {
   // never inaccessible-by-default (the Error-51 footgun). The default operator is
   // NOT persisted to the sidecar (it's a standing grant, not a per-VM
   // collaborator), so `desired` alone drives the sidecar + stale-revoke below.
-  const toGrant = withDefaultOperator(desired, resolveDefaultOperator({ env }));
+  const toGrant = intendedVmPrincipals(cfg, env);
   const stale = accessFor(vmNumber);
   // Never revoke a principal we're about to (re-)grant — a prior tenant who was
-  // also the default operator must not be revoked-then-regranted for nothing.
-  const staleOnly = stale.filter((p) => !toGrant.includes(p));
+  // also the default operator must not be revoked-then-regranted for nothing —
+  // NOR one an earlier step of this same Add already granted. `toGrant` alone
+  // protected nothing when it was empty: the ingress step had granted the operator
+  // seconds earlier and this revoke took it straight back off (VMs 4/5/6).
+  const grantedAlready = new Set([...toGrant, ...normalizeAccessList(grantedThisRun || [])]);
+  const staleOnly = stale.filter((p) => !grantedAlready.has(p));
 
   if (plan.wire) {
     if (staleOnly.length > 0) {
@@ -3743,12 +3965,23 @@ async function convergeVmIngressOnAdd(cfg, appPort, env = process.env, deps = {}
   }
   if (!plan.wire) {
     // Nothing to converge — the no-op wire keeps the clean-slate invariant.
-    wireVmIngressOnAdd(cfg, appPort, env);
-    return { wired: true, reason: "no-wire" };
-  }
-
+    const granted = wireVmIngressOnAdd(cfg, appPort, env);
+    return { wired: true, reason: "no-wire", grantedThisRun: granted };
+  }
+
+  // The intended set, resolved ONCE and handed to every `up` attempt so each
+  // converge iteration grants the same principals — and reported back to the
+  // caller as `grantedThisRun` so the access reconcile that follows cannot revoke
+  // them. Every `up` runs the script's grant step, so these are granted whether
+  // the loop converges or hits its deadline. Injectable via `deps` like the rest
+  // of this loop's slow I/O: the resolve spawns `gcloud config get-value account`
+  // on its last tier, and a unit test must never depend on the gcloud identity
+  // that happens to be active on the machine running it.
+  const grantedThisRun =
+    deps.grantedThisRun != null ? deps.grantedThisRun : intendedVmPrincipals(cfg, env);
   const runUp =
-    deps.runUp || ((p) => runVmIngress(cfg, "up", p.vmNumber, p.domain, appPort, p.slug));
+    deps.runUp
+    || ((p) => runVmIngress(cfg, "up", p.vmNumber, p.domain, appPort, p.slug, grantedThisRun));
   const probeVerdict = deps.probeVerdict || ((p) => probeVmIngressVerdict(cfg, p));
   const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
   const now = deps.now || (() => Date.now());
@@ -3791,7 +4024,7 @@ async function convergeVmIngressOnAdd(cfg, appPort, env = process.env, deps = {}
     if (decision.done) {
       if (decision.wired) {
         console.error(`  ✓ LB ingress wired: https://${label}.editor.${plan.domain}`);
-        return { wired: true, reason: "wired", attempts: attempt + 1 };
+        return { wired: true, reason: "wired", attempts: attempt + 1, grantedThisRun };
       }
       const rewire =
         `FLEET_DOMAIN=${plan.domain}${plan.slug ? ` VM_SLUG=${plan.slug}` : ""} ` +
@@ -3808,7 +4041,7 @@ async function convergeVmIngressOnAdd(cfg, appPort, env = process.env, deps = {}
         `CY_DEGRADED ingress-wiring-failed: VM-${plan.vmNumber} public URL did not wire ` +
           `within the add window (last verdict=${verdict || "unknown"}). Re-wire: ${rewire}`,
       );
-      return { wired: false, reason: "deadline", attempts: attempt + 1 };
+      return { wired: false, reason: "deadline", attempts: attempt + 1, grantedThisRun };
     }
     attempt += 1;
     await sleep(decision.delayMs);
@@ -3837,8 +4070,8 @@ function startDetachedAddWiring(cfg, appPort, env = process.env) {
   if (!plan.wire) {
     // Nothing slow to detach: wiring is a no-op and the access reconcile is a cheap
     // sidecar write. Run them inline so the clean-slate invariant still holds.
-    wireVmIngressOnAdd(cfg, appPort, env);
-    applyVmAccessOnAdd(cfg, env);
+    const grantedThisRun = wireVmIngressOnAdd(cfg, appPort, env);
+    applyVmAccessOnAdd(cfg, env, { grantedThisRun });
     return;
   }
   const marker = ingressInflightMarkerPath(INGRESS_INFLIGHT_DIR, plan.vmNumber);
@@ -3870,8 +4103,8 @@ function startDetachedAddWiring(cfg, appPort, env = process.env) {
         `running it inline instead.`,
     );
     try { fs.unlinkSync(marker); } catch { /* marker may not exist */ }
-    wireVmIngressOnAdd(cfg, appPort, env);
-    applyVmAccessOnAdd(cfg, env);
+    const grantedThisRun = wireVmIngressOnAdd(cfg, appPort, env);
+    applyVmAccessOnAdd(cfg, env, { grantedThisRun });
   }
 }
 
@@ -3903,8 +4136,11 @@ async function cmdWireAddTail() {
     // Converge the URL to `verdict=wired` (retry-until-wired), not a single-shot
     // `up` left to the slow reconcile sweep — then the IAP access grant, in the
     // SAME order cmdUp ran them inline.
-    await convergeVmIngressOnAdd(cfg, appPort);
-    applyVmAccessOnAdd(cfg);
+    // Carry what the converge granted into the access reconcile, so the revoke
+    // step cannot take back a principal this same Add just authorized — the exact
+    // grant-then-revoke-18s-later sequence `/tmp/cy-wire-add-vm-4.log` recorded.
+    const { grantedThisRun } = await convergeVmIngressOnAdd(cfg, appPort);
+    applyVmAccessOnAdd(cfg, process.env, { grantedThisRun });
   } finally {
     if (marker) {
       try { fs.unlinkSync(marker); } catch { /* already gone — fine */ }
@@ -4016,6 +4252,8 @@ async function cmdUp(args, projectDir = rootDir) {
     }
   }
 
+  assertAddCanAuthorizeSomeone(cfg);
+
   checkScriptDrift(cfg);
 
   await ensureFirewallRule(cfg);
@@ -4122,7 +4360,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)`,
       );
@@ -4304,14 +4562,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);
@@ -5058,6 +5309,9 @@ module.exports = {
   assertAgentCliInstalled,
   probeContainerRunning,
   probeContainerState,
+  waitForEditorComposeRunning,
+  abortTeardownDecision,
+  probeAbortTeardownState,
   probeAgentBinaryInstalled,
   waitForContainerRunning,
   KNOWN_FLAGS,
@@ -5157,6 +5411,8 @@ module.exports = {
   ingressWiringPlan,
   fleetInstancePrefix,
   runVmIngress,
+  intendedVmPrincipals,
+  assertAddCanAuthorizeSomeone,
   wireVmIngressOnAdd,
   probeVmIngressVerdict,
   convergeVmIngressOnAdd,

package/npm/compose-conflict.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// npm/compose-conflict.js — classify a failed `docker compose up -d` on a fleet
+// VM, so `cloud:up` can tell "another run beat me to this container" apart from
+// "provisioning genuinely broke".
+//
+// Why this exists: on 2026-08-07 two concurrent `cloud:up` runs raced to start
+// the editor container on one fresh VM. The loser's `up -d` exited non-zero with
+// the docker daemon's container-name conflict, `cloud.js` flattened that into a
+// generic "docker compose up -d failed on the VM", and the abort handler
+// escalated it all the way to deleting a VM the winner had already brought up
+// and rostered. A name conflict is the opposite of a failure — it is proof the
+// shared goal (container running) was reached by someone else.
+//
+// Matching a daemon error string is exactly the kind of thing that rots when
+// docker rephrases it, so it lives here as a named, unit-tested function with
+// the real observed message pinned as a fixture — not as an inline regex at the
+// call site.
+
+// The stable fragments of the daemon's conflict message. The container id and
+// name vary per run and docker's exact phrasing has changed across versions, so
+// we require all three fragments rather than the whole sentence. Observed
+// verbatim in the VM-4 add log:
+//
+//   Error response from daemon: Conflict. The container name
+//   "/codeyam-editor-editor-1" is already in use by container "c9d448c6…".
+//   You have to remove (or rename) that container to be able to reuse that name.
+//
+// Compose emits it twice (once prefixed `service:editor:1`, once bare) and
+// interleaves its own progress lines, so the match is substring-based over the
+// whole captured stream rather than line- or anchor-based.
+const NAME_CONFLICT_FRAGMENTS = [/\bConflict\./i, /container name/i, /is already in use/i];
+
+/** Classify the outcome of `docker compose up -d`.
+ *
+ *  Returns one of:
+ *  - `'ok'` — the command succeeded; there is no failure to classify. Guards
+ *    against a caller that classifies unconditionally, so a zero status can
+ *    never be read as a conflict.
+ *  - `'name-conflict'` — the daemon refused because a container of that name
+ *    already exists, i.e. a concurrent run already started it. The caller
+ *    re-probes for a running container and converges instead of throwing.
+ *  - `'failed'` — anything else. Existing behavior: a real provisioning
+ *    failure.
+ *
+ *  Pure: `{ status, stderr } → tag`, with no I/O, so the whole matrix is
+ *  testable without a VM. `stderr` may be null/undefined (the pre-fix call site
+ *  captured nothing), which classifies as `'failed'` — the conservative
+ *  direction, since converging requires positive evidence of a conflict. */
+function classifyComposeUpFailure({ status, stderr } = {}) {
+  if (status === 0) return 'ok';
+  const text = String(stderr == null ? '' : stderr);
+  if (NAME_CONFLICT_FRAGMENTS.every((re) => re.test(text))) {
+    return 'name-conflict';
+  }
+  return 'failed';
+}
+
+module.exports = { classifyComposeUpFailure };