@codeyam-editor/codeyam-editor 0.1.0-staging.g6631ba2 → 0.1.0-staging.gc446a6f

package/npm/cloud.js

@@ -81,6 +81,8 @@ const {
   selectOrphanIngressTargets,
   classifyOrphanDownResult,
   backendServicesListInvocation,
+  negListInvocation,
+  instancesListInvocation,
   ingressConvergeDecision,
   detachedAddTailInvocation,
   ingressInflightMarkerPath,
@@ -157,11 +159,17 @@ const KNOWN_FLAGS = [
   // default is loud — a tokenless VM cannot sync plan claims and must never
   // report healthy silently. Use only when push genuinely isn't wanted.
   "allow-no-git-credentials",
+  // Provision the VM in admin mode: forward CODEYAM_ADMIN=1 into the container
+  // so the Home-tab Setup door renders. Equivalent to `CODEYAM_ADMIN=1 npm run
+  // cloud:up …`; absent = strict non-admin (the safe default). Survives
+  // re-provision because it rides the compose-render substitution, unlike a
+  // manual VM compose edit.
+  "admin",
 ];
 
 // Flags that take no value (presence = true). parseFlags must not demand a
 // value for these or `--no-tunnel` would error "requires a value".
-const BOOLEAN_FLAGS = ["no-tunnel", "skip-setup", "list", "allow-no-git-credentials"];
+const BOOLEAN_FLAGS = ["no-tunnel", "skip-setup", "list", "allow-no-git-credentials", "admin"];
 
 const FIREWALL_RULE_NAME = "codeyam-editor-iap-ssh";
 const INSTANCE_TAG = "codeyam-editor";
@@ -1494,6 +1502,43 @@ function bootstrapLogTail(cfg, lines = 40) {
   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
+ *  editor-server process env (handlers.rs::admin_enabled, strict literal "1").
+ *  The operator opts in with `CODEYAM_ADMIN=1 npm run cloud:up …` or `--admin`
+ *  (which lands as cfg.admin); anything else forwards "" so a normal launch —
+ *  and a re-provision without the flag — is strict non-admin. Pure over its
+ *  inputs so cloud.test.js can pin it without touching gcloud. */
+function buildProvisionEnv(env = process.env, flags = {}) {
+  const admin = flags.admin === true || env.CODEYAM_ADMIN === "1";
+  return { CODEYAM_ADMIN: admin ? "1" : "" };
+}
+
+/** Build the one-shot SSH shell command that reconciles a running VM's admin
+ *  mode without a full re-provision: rewrite the rendered compose's
+ *  CODEYAM_ADMIN line to `value` — or insert it under `environment:` on a legacy
+ *  VM whose compose predates the placeholder — then recreate the editor service
+ *  so admin_enabled() re-reads it. `value` is always "1" or "" (the caller
+ *  normalizes), so inlining it into sed is safe. Pure/string-only so
+ *  cloud.test.js can assert its shape without SSHing. */
+function buildReconcileAdminCommand(repoName, value) {
+  const f = "docker-compose.cloud.yml";
+  const entry = `      - CODEYAM_ADMIN=${value}`;
+  // Capture only the leading indentation (\1) and re-emit the literal key, so a
+  // value that starts with a digit (e.g. "1") never lands right after the
+  // backreference — `\11` would be read by sed as group 11, not `\1` + "1".
+  return (
+    `cd ~/projects/${repoName} && ` +
+    `if grep -qE '^[[:space:]]*- CODEYAM_ADMIN=' ${f}; then ` +
+    `sed -i -E 's#^([[:space:]]*)- CODEYAM_ADMIN=.*#\\1- CODEYAM_ADMIN=${value}#' ${f}; ` +
+    `else ` +
+    `sed -i -E 's#^([[:space:]]*environment:[[:space:]]*)$#\\1\\n${entry}#' ${f}; ` +
+    `fi && ` +
+    `docker compose -f ${f} up -d editor`
+  );
+}
+
 async function ensureProjectBootstrapped(cfg) {
   const repoName = resolveProject(cfg).name;
   console.error(`Checking project bootstrap state for ${repoName}...`);
@@ -1547,12 +1592,18 @@ async function ensureProjectBootstrapped(cfg) {
   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 }),
@@ -1840,6 +1891,15 @@ function classifyGitRemoteError(stderr) {
   ) {
     return "network";
   }
+  // A greenfield project (`--new-project` scaffold) has no origin remote and an
+  // unborn `main`, so `git ls-remote origin` fails with "does not appear to be a
+  // git repository". No token would fix this — there is simply nothing to push
+  // yet — so it is neither `credential` nor `network` nor `git-spawn`. Keep the
+  // match narrow: `repository not found` is a genuine access failure against a
+  // real remote and must NOT be swallowed here.
+  if (lower.includes("does not appear to be a git repository")) {
+    return "no-remote";
+  }
   return "other";
 }
 
@@ -1877,6 +1937,14 @@ function decideCredentialHeal({ stagingEmpty, lsRemoteOk, lsRemoteStderr }) {
         reason: "git binary failed to launch — not a credential gap, not re-seeding",
       };
     }
+    if (category === "no-remote") {
+      return {
+        heal: false,
+        category,
+        reason:
+          "no git remote configured — greenfield project, nothing to push yet (not a credential gap)",
+      };
+    }
     return {
       heal: true,
       category,
@@ -3697,22 +3765,31 @@ async function cmdReconcileIngress(args, projectDir = rootDir) {
   sweepOrphanIngress({ cfg, domain, roster, projectDir });
 }
 
-/** Auto-clean orphaned LB ingress (vm--auto-clean-orphaned-lb-ingress): backend
- *  services whose owning VM number is gone from the roster (a destroyed VM) and
- *  has no in-flight add. Enumerates the live backends, maps each name back to its
- *  VM number, subtracts the roster + in-flight adds (the false-orphan guards),
- *  and runs the VERIFIED `vm-ingress.sh <N> down` (asserts neg=no bes=no host=no,
- *  with retries) for each orphan — so an orphan is genuinely cleared or surfaced
- *  as a real failure, never a silent leak and never a manual command. Emits a
- *  machine-readable `CY_ORPHAN_SWEEP <json>` summary line the dashboard parses to
- *  reconcile its orphan-attention banner. Best-effort per VM: one `down` failing
- *  never aborts the rest of the sweep. Returns the `{ cleaned, failed, skipped }`
- *  summary (null when the enumeration itself failed) — the same shape it prints —
- *  so the flow is directly assertable. `deps` is injectable so the enumerate →
- *  select → down flow is testable without gcloud. */
+/** Auto-clean orphaned LB ingress (vm--auto-clean-orphaned-lb-ingress): LB
+ *  resources whose owning VM number is gone from the roster (a destroyed VM) and
+ *  has no in-flight add. Enumerates the live backend services AND zonal NEGs,
+ *  UNIONs their owning VM numbers (so a partial teardown whose NEG outlived its
+ *  backend service — the VM-5/6 case — still surfaces its VM as a candidate),
+ *  maps each name back to its VM number, subtracts the roster + in-flight adds +
+ *  live instances (the false-orphan guards), and runs the VERIFIED
+ *  `vm-ingress.sh <N> down` (asserts neg=no bes=no host=no, with retries) for
+ *  each orphan — so an orphan is genuinely cleared or surfaced as a real failure,
+ *  never a silent leak and never a manual command. Emits a machine-readable
+ *  `CY_ORPHAN_SWEEP <json>` summary line the dashboard parses to reconcile its
+ *  orphan-attention banner; the summary carries `stillPresent` (VM numbers that
+ *  still own ≥1 LB resource after the sweep) so the dashboard can clear a stale
+ *  banner for a VM that is now back in the roster or has no residual resources.
+ *  Best-effort per VM: one `down` failing never aborts the rest of the sweep.
+ *  Fail-safe: if the live-instance list can't be fetched, teardown is skipped for
+ *  this pass (a live-but-unrostered VM must never be torn down) while the banner
+ *  reconcile still runs. Returns the `{ cleaned, failed, skipped, stillPresent }`
+ *  summary (null when the backend-service enumeration itself failed) — the same
+ *  shape it prints — so the flow is directly assertable. `deps` is injectable so
+ *  the enumerate → select → down flow is testable without gcloud. */
 function sweepOrphanIngress({ cfg, domain, roster, projectDir = rootDir } = {}, deps = {}) {
   const gi = deps.googleIngress || require("./google-ingress.js");
   const fcl = deps.fleetCleanup || require("./fleet-cleanup.js");
+  const frecon = deps.fleetReconcile || require("./fleet-reconcile.js");
   const run = deps.spawnSync || spawnSync;
 
   const listInv = backendServicesListInvocation({ project: cfg && cfg.project });
@@ -3724,11 +3801,31 @@ function sweepOrphanIngress({ cfg, domain, roster, projectDir = rootDir } = {},
     console.error(`  orphan sweep skipped — could not list backend services (${tail}).`);
     return null;
   }
-  const ingressVmNumbers = String(listRes.stdout || "")
+  const besVmNumbers = String(listRes.stdout || "")
     .split("\n")
     .map((line) => gi.vmNumberFromResourceName(line.trim()))
     .filter((n) => n != null);
 
+  // Also enumerate zonal NEGs and union their owners in: a partial teardown can
+  // leave a `vm-<N>-<surface>-neg` behind after its backend service is already
+  // gone, so a backend-service-only candidate set misses that residue. Best-effort
+  // — a NEG-list failure never aborts the backend-service-driven sweep.
+  let negVmNumbers = [];
+  const negInv = negListInvocation({ project: cfg && cfg.project });
+  const negRes = run(negInv.command, negInv.args, { encoding: "utf8" });
+  if (negRes && negRes.status === 0) {
+    negVmNumbers = String(negRes.stdout || "")
+      .split("\n")
+      .map((line) => gi.vmNumberFromResourceName(line.trim()))
+      .filter((n) => n != null);
+  } else {
+    const tail = (
+      (negRes && (negRes.stderr || (negRes.error && negRes.error.message))) || ""
+    ).toString().trim().split("\n").pop() || "error";
+    console.error(`  orphan sweep: could not list NEGs (${tail}) — sweeping backend services only.`);
+  }
+  const ingressVmNumbers = [...new Set([...besVmNumbers, ...negVmNumbers])].sort((a, b) => a - b);
+
   // A VM in the roster, or with an in-flight `add-<n>.json` sidecar (provisioning,
   // not yet rostered), is live — never an orphan.
   const pendingDir = process.env.PENDING_JOBS_DIR || path.join(projectDir, ".codeyam/logs/pending-jobs");
@@ -3736,9 +3833,34 @@ function sweepOrphanIngress({ cfg, domain, roster, projectDir = rootDir } = {},
     .listPendingJobs(pendingDir)
     .filter((j) => j.action === "add")
     .map((j) => j.n);
-  const orphans = selectOrphanIngressTargets({ ingressVmNumbers, roster, inFlightAdds });
 
-  const summary = { cleaned: [], failed: [], skipped: inFlightAdds.slice() };
+  // Defensive live-instance guard: never tear down a VM whose GCP instance is
+  // actually running (a roster drift could leave a live VM unrostered; a teardown
+  // that SUCCEEDED against it would knock it offline). `liveVmNumbers === null`
+  // means the list couldn't be fetched — fail safe by skipping teardown this pass
+  // (below) rather than risk a false teardown. The banner reconcile still runs.
+  let liveVmNumbers = null;
+  const instInv = instancesListInvocation({ project: cfg && cfg.project });
+  const instRes = run(instInv.command, instInv.args, { encoding: "utf8" });
+  if (instRes && instRes.status === 0) {
+    liveVmNumbers = frecon.parseRunningFleetVms(instRes.stdout, fleetInstancePrefix());
+  } else {
+    const tail = (
+      (instRes && (instRes.stderr || (instRes.error && instRes.error.message))) || ""
+    ).toString().trim().split("\n").pop() || "error";
+    console.error(`  orphan sweep: could not list instances (${tail}) — skipping teardown this pass (banners still reconciled).`);
+  }
+
+  const orphans = liveVmNumbers === null
+    ? []
+    : selectOrphanIngressTargets({ ingressVmNumbers, roster, inFlightAdds, liveVmNumbers });
+
+  // stillPresent = every VM that owned an LB resource going in, minus the ones we
+  // verifiably clean below. The dashboard clears a banner for any orphan VM not in
+  // this set (or now back in the roster). Computed up front so the no-orphans and
+  // fail-safe-skip paths report it too — that is what unfreezes a VM-3-style banner
+  // (re-rostered, so never a sweep target) with no teardown at all.
+  const summary = { cleaned: [], failed: [], skipped: inFlightAdds.slice(), stillPresent: ingressVmNumbers.slice() };
   if (!orphans.length) {
     console.error("  orphan sweep: no orphaned LB ingress found.");
     console.log(`CY_ORPHAN_SWEEP ${JSON.stringify(summary)}`);
@@ -3775,6 +3897,11 @@ function sweepOrphanIngress({ cfg, domain, roster, projectDir = rootDir } = {},
       console.error(`  VM-${n}: orphaned ingress → auto-clean FAILED (${tail.slice(-200)})`);
     }
   }
+  // A verifiably-cleaned VM no longer owns any LB resource — drop it from
+  // stillPresent so the dashboard clears its banner (failed VMs stay, keeping
+  // their real attention item).
+  const cleanedSet = new Set(summary.cleaned);
+  summary.stillPresent = ingressVmNumbers.filter((n) => !cleanedSet.has(n));
   console.log(`CY_ORPHAN_SWEEP ${JSON.stringify(summary)}`);
   return summary;
 }
@@ -3880,6 +4007,39 @@ async function cmdReconcileCredentials(args, projectDir = rootDir) {
   );
 }
 
+/** `cloud:reconcile-admin` — flip admin mode on/off for an already-running VM
+ *  WITHOUT a full re-provision. Resolves the desired value from this invocation
+ *  (`--admin` / `CODEYAM_ADMIN`, else off), rewrites the rendered compose's
+ *  CODEYAM_ADMIN line, and recreates the editor service — matching what a manual
+ *  compose edit + `docker compose up -d editor` does today, so the durable admin
+ *  setting no longer requires a full re-provision to change. */
+async function cmdReconcileAdmin(args, projectDir = rootDir) {
+  ensureGcloud();
+  const flags = parseFlags(args);
+  const cfg = loadCloudConfig(projectDir);
+  if (!cfg) {
+    throw new Error("No .codeyam/cloud.json found. Run `npm run cloud:up` first.");
+  }
+  const desired =
+    buildProvisionEnv(process.env, flags).CODEYAM_ADMIN === "1" ? "1" : "";
+  const repoName = resolveProject(cfg).name;
+  console.error(
+    `Reconciling admin mode to ${desired === "1" ? "ON" : "off"} on ${cfg.instanceName}...`,
+  );
+  const result = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: buildReconcileAdminCommand(repoName, desired),
+    }),
+    { stdio: "inherit" },
+  );
+  if (result.status !== 0) {
+    throw new Error(`Failed to reconcile admin mode on ${cfg.instanceName}.`);
+  }
+  console.error(
+    `  ✓ editor service recreated; /api/config now reports admin=${desired === "1" ? "true" : "false"}.`,
+  );
+}
+
 /** Provision-time guarantee that a just-provisioned VM can actually reach
  *  GitHub. Probes the staging file + in-container `git ls-remote origin` and
  *  routes the outcome through the SAME {@link decideCredentialHeal} classifier
@@ -4011,6 +4171,7 @@ const HANDLERS = {
   "reconcile-ingress": cmdReconcileIngress,
   "wire-add-tail": cmdWireAddTail,
   "reconcile-credentials": cmdReconcileCredentials,
+  "reconcile-admin": cmdReconcileAdmin,
   access: cmdAccess,
 };
 
@@ -4080,6 +4241,9 @@ module.exports = {
   loadCloudConfig,
   saveCloudConfig,
   loadOrInitCloudConfig,
+  buildProvisionEnv,
+  buildReconcileAdminCommand,
+  cmdReconcileAdmin,
   buildEditorLocalEnvPatch,
   buildEditorLocalSeedWriteCommand,
   seedPreviewOrigin,

package/npm/empty-project-dir.js

@@ -1,13 +1,14 @@
 "use strict";
 
 /**
- * Launcher-side mirror of `is_empty_project_dir` in
+ * Launcher-side mirrors of `is_empty_project_dir` and
+ * `looks_like_onboardable_project` in
  * `crates/codeyam-editor/src/commands/init.rs`. The Rust side decides
- * which `/codeyam-…` skill the init binary points at; this JS mirror
- * decides the same for the launcher's post-launch tail banner. Keep
- * both in sync — the test `empty-project-dir.test.js` and Rust's
- * `is_empty_project_dir_ignores_hidden_entries` /
- * `is_empty_project_dir_detects_visible_entry` pin the contract.
+ * which `/codeyam-…` skill the init binary points at; these JS mirrors
+ * decide the same for the launcher's post-launch tail banner. Keep both
+ * predicates in sync with Rust — the test `empty-project-dir.test.js`
+ * and Rust's `is_empty_project_dir_*` / `looks_like_onboardable_project_*`
+ * tests pin the contracts.
  *
  * A "fresh" project directory has no non-hidden entries — only things
  * like `.git/`, `.gitignore`, or other dotfiles. Hidden entries don't
@@ -19,6 +20,7 @@
  */
 
 const fs = require("node:fs");
+const path = require("node:path");
 
 function isEmptyProjectDir(projectDir) {
   let entries;
@@ -30,4 +32,87 @@ function isEmptyProjectDir(projectDir) {
   return entries.every((name) => name.startsWith("."));
 }
 
-module.exports = { isEmptyProjectDir };
+// Root files that signal a real project: dependency/build manifests,
+// lockfiles, and the static-site `index.html`. Mirror of the Rust
+// `MANIFEST_MARKERS` list.
+const MANIFEST_MARKERS = new Set([
+  "package.json",
+  "Cargo.toml",
+  "pyproject.toml",
+  "requirements.txt",
+  "setup.py",
+  "go.mod",
+  "Gemfile",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "composer.json",
+  "pubspec.yaml",
+  "Package.swift",
+  "mix.exs",
+  "deno.json",
+  "CMakeLists.txt",
+  "Makefile",
+  "tsconfig.json",
+  "index.html",
+]);
+
+// Subdirectories that signal an organized source tree. Mirror of the Rust
+// `SOURCE_DIR_MARKERS` list.
+const SOURCE_DIR_MARKERS = new Set([
+  "src",
+  "app",
+  "lib",
+  "pages",
+  "components",
+  "crates",
+  "packages",
+  "source",
+  "include",
+]);
+
+/**
+ * Does this directory contain a *project* worth onboarding, as opposed to
+ * being empty or holding only a stray file or two? Mirror of Rust
+ * `looks_like_onboardable_project`. A folder "contains a project" when it
+ * holds a recognized manifest / lockfile, a `.csproj` / `.xcodeproj`, a root
+ * `index.html`, OR an organized source subdirectory. Intentionally
+ * marker-based, not file-count based: a home dir full of loose files is still
+ * not a project. A read error returns false (not a project → the
+ * auto-init/open path), matching Rust's `Err(_) => false`.
+ */
+function looksLikeOnboardableProject(projectDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(projectDir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    const name = entry.name;
+    if (MANIFEST_MARKERS.has(name)) {
+      return true;
+    }
+    if (name.endsWith(".csproj") || name.endsWith(".xcodeproj")) {
+      return true;
+    }
+    // Source-tree markers only count as directories, not like-named files.
+    if (SOURCE_DIR_MARKERS.has(name)) {
+      let isDir = entry.isDirectory();
+      // A symlinked source dir surfaces as a symlink Dirent; resolve it.
+      if (!isDir && entry.isSymbolicLink()) {
+        try {
+          isDir = fs.statSync(path.join(projectDir, name)).isDirectory();
+        } catch {
+          isDir = false;
+        }
+      }
+      if (isDir) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+module.exports = { isEmptyProjectDir, looksLikeOnboardableProject };

package/npm/fleet-add-failure.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const fc = require('./fleet-cleanup');
+
+// npm/fleet-add-failure.js — pure classifier for a FAILED fleet-dashboard `add`
+// provision. Before this, every failed add rendered an identical red "add error"
+// badge whose only action was "Clear badge", and a restart mid-add collapsed the
+// message to a content-free `(re-attached after restart — detached provision
+// exited 1)`. The real cause — captured to the provision transcript on disk — was
+// thrown away. This happened live with VM9/VM10: both aborted at the streamed-
+// script drift guard because a bootstrap script had uncommitted local edits, but
+// the operator saw only "exited 1" and had to dig through /tmp/dash-add-vm-N.log.
+//
+// classifyAddFailure turns a transcript tail + exit code into a differentiated,
+// ACTIONABLE verdict: a plain-language headline, a concrete recovery instruction,
+// and — crucially — a `retryable` flag that is true ONLY for failures where the
+// classifier can PROVE nothing was provisioned, so a one-click retry can never
+// silently orphan or duplicate a half-provisioned GCP box. The decision logic
+// lives here as a pure module (like fleet-job-badge.js::canClearBadge) so the
+// whole failure matrix is unit-tested without a live VM; server.js is the thin
+// I/O shell that gathers the transcript and turns the verdict into a card + a
+// server-re-guarded retry action.
+
+// The SINGLE source of truth for which categories are safe to auto-retry: only
+// failures where nothing was provisioned. `retryable` on every returned verdict
+// is stamped from this Set, so the invariant `retryable === has(category)` holds
+// by construction and the server can re-guard a retry against the same Set.
+const ADD_FAILURE_RETRYABLE = new Set(['preflight-drift', 'instance-vanished']);
+
+// Collect the `    - <path>` bullets the drift guard prints AFTER the "following
+// files differ" header (see npm/cloud.js), stopping at the first non-bullet line
+// so an unrelated "- " elsewhere in the transcript can't leak in. Returns [] when
+// no drift block is present.
+function extractDriftFiles(logTail) {
+  const lines = String(logTail || '').split('\n');
+  const files = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (!inBlock) {
+      if (/following files differ/i.test(line)) inBlock = true;
+      continue;
+    }
+    const m = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (m) { files.push(m[1]); continue; }
+    break; // first non-bullet after the header ends the block
+  }
+  return files;
+}
+
+// Pure transform: the last `maxLines` non-empty lines of a transcript, each
+// right-trimmed. Extracted from readProvisionTail (server.js) so the aggregation
+// is unit-tested and that function stays a thin filesystem-boundary call. Returns
+// '' for empty/whitespace-only input.
+function lastNonEmptyLines(text, maxLines = 50) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((l) => l.replace(/\s+$/, ''))
+    .filter((l) => l.length > 0)
+    .slice(-maxLines);
+  return lines.join('\n');
+}
+
+// Build a verdict, stamping `retryable` from the single-source-of-truth Set so it
+// can never drift from the category.
+function buildFailureVerdict(category, headline, recovery, extra) {
+  const out = { category, headline, recovery, retryable: ADD_FAILURE_RETRYABLE.has(category) };
+  if (extra && extra.files) out.files = extra.files;
+  return out;
+}
+
+// Classify a failed add from its transcript tail + exit code.
+//
+//   logTail   the last lines of the provision transcript (string; '' when the
+//             log was unreadable — must never throw)
+//   exitCode  the provision's exit code (number; used for signal-kill detection)
+//
+// Returns { category, headline, recovery, retryable, files? }.
+//
+// Detection is ORDER-SENSITIVE. The provision shell echoes cloud:up's tail, so a
+// drift / instance-vanished / container-stuck transcript ALSO contains the
+// generic `cloud:up FAILED (exit N)` line. Each specific (and every retryable)
+// signature is therefore tested BEFORE the generic cloud-up-failed signature, or
+// a retryable drift would misclassify as a non-retryable cloud:up failure and the
+// operator would lose the safe one-click recovery.
+function classifyAddFailure({ logTail, exitCode } = {}) {
+  const log = String(logTail || '');
+
+  // 1. preflight-drift — the streamed-script drift guard aborted BEFORE any
+  //    gcloud call, so nothing was provisioned. Retryable once the file is fixed.
+  //    We match the unambiguous abort header / verdict label, NOT the bare
+  //    `CODEYAM_SKIP_SCRIPT_DRIFT_CHECK` token: that token ALSO appears in the
+  //    "bypass active — skipping drift check" warning, so keying on it would
+  //    misclassify a bypass-active add that later failed for a real reason as a
+  //    (retryable!) drift — inviting an unsafe retry. The header below is printed
+  //    only on a genuine drift abort.
+  if (/Streamed scripts carry unreviewed local content/i.test(log)
+      || /UNCOMMITTED LOCAL EDITS/.test(log)) {
+    const files = extractDriftFiles(log);
+    const fileList = files.length ? files.join(', ') : 'the streamed scripts';
+    const fix = files.length
+      ? `Commit & push them, or discard with \`git checkout -- ${files.join(' ')}\`, then Retry add.`
+      : 'Commit & push them, or discard the local edits, then Retry add.';
+    return buildFailureVerdict('preflight-drift', 'Blocked by local edits',
+      `Uncommitted local edits in ${fileList} tripped the streamed-script drift guard, which aborts before any cloud resource is created. ${fix}`,
+      { files });
+  }
+
+  // 2. instance-vanished — the GCP instance is confirmed gone; nothing to orphan.
+  if (/instance .* is gone/i.test(log)) {
+    return buildFailureVerdict('instance-vanished', 'Instance never came up',
+      'The GCP instance is gone — provisioning failed before the container started, so nothing was left behind. Retrying the add is safe.');
+  }
+
+  // 3. container-stuck — the instance exists but the editor container never
+  //    became healthy, so a half-provisioned box may exist. Not retryable.
+  if (/container never came up/i.test(log)) {
+    return buildFailureVerdict('container-stuck', 'Container never became healthy',
+      'The instance came up but the editor container never became healthy — it may be half-provisioned. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 4. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
+  //    vanished / stuck signatures above did not match. A partial instance may
+  //    exist, so not retryable.
+  if (/cloud:up FAILED \(exit/i.test(log)) {
+    return buildFailureVerdict('cloud-up-failed', 'Provisioning failed',
+      'cloud:up failed during provisioning, so a partial instance may exist. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 5. interrupted — a signal kill (OOM 137, SIGTERM 143, …) or an explicit
+  //    Killed / out-of-memory marker. The real VM state is unknown. Not retryable.
+  if (fc.isSignalKillExit(Number(exitCode)) || /\bKilled\b/.test(log) || /Out of memory/i.test(log)) {
+    return buildFailureVerdict('interrupted', 'Provisioning interrupted',
+      'The provision was interrupted (killed or out of memory), so the VM state is unknown. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 6. unknown — fallback. Never invite an unproven retry.
+  return buildFailureVerdict('unknown', 'Add failed',
+    'The add failed for an unclassified reason — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+}
+
+// Pure guard for the operator "Retry add" action: given a VM number and its
+// carried job, decide whether a one-click retry is SAFE. Retry is allowed ONLY
+// for a terminal add-error whose classifier verdict is retryable (a category
+// where nothing was provisioned). Returns { ok, reason } — reason is a stable
+// code the server shell (actionRetryAdd) maps to an operator message. Mirrors
+// fleet-job-badge.js::canClearBadge so the handler stays a thin I/O shell and the
+// safety decision is unit-tested without a live dashboard.
+function canRetryAdd({ n, job } = {}) {
+  if (!Number.isInteger(n) || n < 1) return { ok: false, reason: 'invalid-vm' };
+  if (!job || job.action !== 'add' || job.state !== 'error') return { ok: false, reason: 'no-failed-add' };
+  if (!job.retryable) return { ok: false, reason: 'not-retryable' };
+  return { ok: true, reason: null };
+}
+
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, ADD_FAILURE_RETRYABLE };