@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/codesign-plan.js

@@ -0,0 +1,68 @@
+"use strict";
+// Pure helpers for scripts/package-mcpb.js's darwin code-signing step.
+//
+// Dependency-free and unit-tested (npm/codesign-plan.test.js) so the packaging
+// script keeps the sign decision + argv rendering out of its execSync path:
+// signDarwinBinary stays thin boundary glue while every branch of "do we sign,
+// and with which command" is exercised here without invoking codesign.
+
+/**
+ * The `codesign` argv for a Developer ID signature with a secure timestamp.
+ * Pure — takes the identity and binary path, returns the flag list. `--force`
+ * replaces cargo's ad-hoc signature (codesign refuses an already-signed binary
+ * otherwise); `--timestamp` embeds the secure timestamp a later notarization
+ * needs.
+ */
+function codesignArgs(identity, binaryPath) {
+  return ["--force", "--timestamp", "--sign", identity, binaryPath];
+}
+
+/**
+ * The shell-quoted `codesign …` command string for signing `binaryPath` with
+ * `identity`. Pure: quotes each argv element so a path or identity with spaces
+ * survives the shell.
+ */
+function codesignCommand(identity, binaryPath) {
+  const quoted = codesignArgs(identity, binaryPath)
+    .map((a) => `"${a}"`)
+    .join(" ");
+  return `codesign ${quoted}`;
+}
+
+/**
+ * Decide whether/how to sign the staged darwin binary, given the target
+ * `platform`, the configured Developer ID `identity`, the `hostPlatform`
+ * (process.platform), and a `serverLabel` for the warning text. Pure — no I/O,
+ * no env, no clock — so the decision and its warnings are unit-testable.
+ *
+ * Returns `{ action: "sign", identity }` when a real Developer ID signature is
+ * possible, otherwise `{ action: "skip", warning? }`: the non-darwin target is a
+ * silent skip (its binary is not Mach-O), while a missing identity or a
+ * non-macOS host skips WITH a warning so an unsigned local bundle stays testable
+ * on the machine that built it rather than failing the build.
+ */
+function signPlan({ platform, identity, hostPlatform, serverLabel }) {
+  if (platform !== "darwin") {
+    return { action: "skip" };
+  }
+  if (!identity) {
+    return {
+      action: "skip",
+      warning:
+        `⚠️  ${serverLabel} is ad-hoc signed — set MCPB_SIGN_IDENTITY (or ` +
+        `APPLE_SIGNING_IDENTITY) to a Developer ID identity to sign it. An unsigned ` +
+        `binary has no stable Keychain identity and re-prompts for access.`,
+    };
+  }
+  if (hostPlatform !== "darwin") {
+    return {
+      action: "skip",
+      warning:
+        `⚠️  cannot codesign ${serverLabel} on ${hostPlatform} — ` +
+        `sign the darwin binary on a macOS host.`,
+    };
+  }
+  return { action: "sign", identity };
+}
+
+module.exports = { codesignArgs, codesignCommand, signPlan };

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 };

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,361 @@
+'use strict';
+
+const fc = require('./fleet-cleanup');
+const { parseRosterMarkers } = require('./fleet-early-roster');
+
+// 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 where a one-click retry
+// provably cannot orphan or duplicate a GCP box: either nothing was provisioned,
+// or the remaining work is re-entrant so the retry converges on the existing VM.
+// Both grounds are spelled out on ADD_FAILURE_RETRYABLE below. 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.
+// `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.
+//
+// A category earns membership on EITHER of two grounds — both of which
+// guarantee a one-click retry cannot silently orphan or duplicate a GCP box:
+//
+//   1. NOTHING WAS PROVISIONED. The classifier can prove no cloud resource was
+//      created (`preflight-drift` aborts before the first gcloud call;
+//      `instance-vanished` confirms the instance is gone). Retry starts clean.
+//
+//   2. THE REMAINING WORK IS RE-ENTRANT. A real VM exists, but every step the
+//      retry would re-run is skip-on-exists or re-attaching, so the retry
+//      CONVERGES on the existing box instead of building a second one.
+//      `project-bootstrap-timeout` is this shape: the VM is up and its detached
+//      bootstrap is still running, `ensureInstance` reuses the live instance,
+//      `ensureBootstrapped` skips on the present image, and
+//      `ensureProjectBootstrapped` re-attaches to the in-flight install rather
+//      than starting a second `npm install` over the first.
+//
+// Ground 2 is deliberately narrow — it is NOT "the VM probably still works".
+// `container-stuck` and `incomplete-workspace` also leave a live VM, but their
+// remaining work is NOT provably re-entrant, so they stay non-retryable.
+const ADD_FAILURE_RETRYABLE = new Set([
+  'preflight-drift',
+  'instance-vanished',
+  'project-bootstrap-timeout',
+]);
+
+// 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');
+}
+
+// True iff the provision transcript reached the early-roster marker (`CY_ROSTER
+// <n>`) — i.e. the instance exists and the container gate passed, so the VM is
+// rostered. Reuses parseRosterMarkers (npm/fleet-early-roster.js) so the
+// `CY_ROSTER` grammar has a single owner rather than a second inlined regex. Any
+// valid marker means "rostered"; the specific VM number is irrelevant here — a
+// provision transcript only ever carries its own VM's marker. Never throws.
+function transcriptRostered(logTail) {
+  return parseRosterMarkers(String(logTail || '')).length > 0;
+}
+
+// The categories that describe an add whose outcome is NOT yet proven bad — the
+// calm, in-flight side of the classifier. `converging` is a rostered box whose
+// ingress is still wiring; `verifying` is the residue: no failure signature
+// matched and nothing durable proves the VM is dead. Both render a calm card and
+// neither may use the word "failed". Consumed by holdConvergingBadge and by
+// deriveStatus (server.js) to pick the matching calm status.
+const CALM_ADD_CATEGORIES = new Set(['converging', 'verifying']);
+
+// Is a non-zero add outcome CORROBORATED by a durable fact — i.e. do we have
+// positive proof of death, rather than merely an absence of proof of life?
+//
+// This is the conjunction that gates the red `unknown` verdict. Before it, the
+// classifier's fallthrough treated "no recognized success signature" as failure,
+// so "we don't know" rendered as a terminal red "Add failed" telling the operator
+// to destroy a VM whose container was Up and whose editor answered /api/health
+// 200 (VM-4, 2026-07-31). Red now requires BOTH halves:
+//
+//   1. A non-zero exit code. A *missing* code is not proof of death — today it
+//      usually means the wrapper was signal-killed while its provision ran on,
+//      which is exactly the case that was misreading as failure. `null`,
+//      `undefined`, a non-integer, and 0 all fail this half.
+//   2. At least one durable corroborating fact:
+//        - `instanceAlive === false`   GCP says the instance is gone.
+//        - `containerHealthy === false` the in-VM editor was probed and is not
+//          answering — the box exists but never came up.
+//        - `wiringDeadlineBlown`       the wire-add-tail gave up (the failed
+//          marker is the tail's own honest deadline signal).
+//
+// Every fact is TRI-STATE on purpose: `undefined`/`null` means "not probed" and
+// corroborates nothing. Only an explicit `false` counts, so an unprobed VM can
+// never be escalated to red by absence of evidence.
+function addFailureCorroborated({ exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown } = {}) {
+  const code = exitCode == null ? NaN : Number(exitCode);
+  if (!Number.isInteger(code) || code === 0) return false;
+  return instanceAlive === false || containerHealthy === false || !!wiringDeadlineBlown;
+}
+
+// Resolve the two independent health signals into the single tri-state
+// `containerHealthy` fact addFailureCorroborated consumes. Pure so the precedence
+// — which decides whether a VM can be escalated to red — is unit-tested; the
+// server (addFailureFacts) supplies the live signals.
+//
+//   reachable    the editor answered over the LB.
+//   inVmHealthy  the STRAND_PROBE /api/health read from INSIDE the container.
+//
+// LB reachability wins when present: it is the stronger witness (it proves the
+// whole URL→ingress→backend path, not just the process). Otherwise the in-VM
+// witness answers — this is the still-wiring case, where the LB necessarily
+// cannot see a VM whose ingress is what we are waiting on, yet the editor itself
+// is demonstrably up.
+//
+// Returns `null` when NEITHER signal was gathered. That is the load-bearing case:
+// an unprobed VM must corroborate nothing, so it can never be escalated to red by
+// absence of evidence. `false` is reserved for a VM that was genuinely probed and
+// did not answer.
+function containerHealthWitness({ reachable, inVmHealthy } = {}) {
+  if (reachable) return true;
+  if (inVmHealthy != null) return !!inVmHealthy;
+  return null;
+}
+
+// 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
+//             and as the first half of the proof-of-death conjunction)
+//
+// The remaining inputs are the durable facts the server gathers (the module
+// stays pure — it never probes). All are tri-state; omit any that was not
+// probed and it corroborates nothing. See addFailureCorroborated.
+//
+//   instanceAlive        does GCP still list the instance?
+//   containerHealthy     did the in-VM editor answer /api/health?
+//   wiringDeadlineBlown  did the add-time wire tail drop its failed marker?
+//
+// 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, instanceAlive, containerHealthy, wiringDeadlineBlown } = {}) {
+  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. project-bootstrap-timeout — the VM came up and its DETACHED project
+  //    bootstrap is still running; we merely stopped waiting on it. This is the
+  //    VM-8 / six-self-host-VM incident: a heavy `npm install` (a ~293 MB
+  //    playwright postinstall, a large `git clone`) outran a local budget, the
+  //    SIGTERM'd gcloud child returned `status: null`, and the abort path read
+  //    that as a broken bootstrap script and DELETED A COMPLETELY HEALTHY VM.
+  //
+  //    Retryable on re-entrancy grounds (see ADD_FAILURE_RETRYABLE): the retry
+  //    re-attaches to the in-flight install rather than starting a second one.
+  //    Tested BEFORE cloud-up-failed because the provision shell echoes cloud:up's
+  //    tail, so this transcript ALSO carries the generic `cloud:up FAILED (exit N)`
+  //    line — matching that first would strip the safe recovery and steer the
+  //    operator to destroy a healthy, still-provisioning VM. The signature is the
+  //    wording ensureProjectBootstrapped (npm/cloud.js) throws for both its
+  //    overall-deadline and its launch-budget timeouts.
+  if (/project bootstrap exceeded the local/i.test(log)) {
+    return buildFailureVerdict('project-bootstrap-timeout', 'Still installing — we stopped waiting',
+      'The VM provisioned fine and its project bootstrap is still running on it; only the local wait budget elapsed. Nothing is broken and nothing was left half-built. Retry the add to re-attach to the running install — each bootstrap step is skip-on-exists. Do NOT destroy this VM.');
+  }
+
+  // 4. 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.');
+  }
+
+  // 5. incomplete-workspace — the container came up but the project was never
+  //    scaffolded: no `.codeyam/editor.json` exists under ~/projects on the VM,
+  //    so the greenfield `init` did not complete onboarding. This is specific
+  //    and more actionable than the generic cloud-up-failed below, so it is
+  //    tested first. The VM exists and is half-provisioned, so it is NOT
+  //    auto-retryable — reconcile finishes the scaffold, then re-add.
+  if (/no \.codeyam\/editor\.json found under ~\/projects/i.test(log)) {
+    return buildFailureVerdict('incomplete-workspace', 'Workspace never scaffolded',
+      'The container came up but the project was never scaffolded (no .codeyam/editor.json on the VM), so provisioning did not finish onboarding. Reconcile this VM to complete the scaffold, then re-add.');
+  }
+
+  // 6. 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.');
+  }
+
+  // 7. 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.');
+  }
+
+  // 8. converging — the add reached the early-roster marker (`CY_ROSTER`): the
+  //    container gate passed, the instance is real, and the VM is rostered, yet it
+  //    exited non-zero WITHOUT matching any specific hard-failure signature above.
+  //    By construction of the provision script, every genuine hard failure (drift,
+  //    instance-vanished, container-stuck, incomplete-workspace, cloud-up-failed,
+  //    interrupted) is printed BEFORE `CY_ROSTER`, so a rostered transcript that
+  //    fell through to here is a still-wiring box owned by the detached
+  //    wire-add-tail / reconcile-ingress — NOT an add failure. Surface it as an
+  //    honest in-flight state instead of the scary red `unknown`. Not retryable:
+  //    the VM exists and its detached wiring owns finishing it, so a one-click
+  //    retry could duplicate/orphan a live box. Tested LAST so a hard-failure
+  //    signature (all printed pre-roster) always wins — `converging` can never
+  //    shadow a proven failure.
+  if (transcriptRostered(log)) {
+    return buildFailureVerdict('converging', 'Add still converging',
+      'The container is up and the VM is rostered; the LB ingress is still wiring in the background. This resolves on its own once the editor is reachable over the LB — no action needed unless it persists past the wiring deadline.');
+  }
+
+  // 9. The residue: no failure signature above matched. The polarity here is
+  //    INVERTED from the original design. It used to read "no recognized success
+  //    signature ⇒ failed", which made red the DEFAULT for "we don't know" — so a
+  //    VM whose container was Up and whose editor answered /api/health 200 got a
+  //    terminal red "Add failed" card advising the operator to destroy it (VM-4,
+  //    2026-07-31; the wrapper had been killed mid-flight, so its transcript was
+  //    truncated before CY_ROSTER and it never reached the `converging` arm above).
+  //
+  //    Red now requires positive proof of death, and everything else is in-flight:
+  //
+  //    9a. unknown — a non-zero exit CORROBORATED by a durable fact (see
+  //        addFailureCorroborated). The box is provably dead or provably never
+  //        came up, so the loud, terminal escalation is warranted and unchanged.
+  //        Still never invites an unproven retry.
+  if (addFailureCorroborated({ exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown })) {
+    return buildFailureVerdict('unknown', 'Add failed',
+      'The add failed for an unclassified reason and the VM is confirmed dead or never came up — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+  }
+
+  //    9b. verifying — the honest default. No failure signature, and nothing
+  //        durable proves this VM is dead: it may still be provisioning or
+  //        wiring, and the ingress can keep propagating for minutes after the
+  //        wrapper is gone. Calm copy, transcript still one click away. NOT
+  //        retryable — nothing is proven about the box either way, so a one-click
+  //        retry could still duplicate a live GCP instance (the ADD_FAILURE_RETRYABLE
+  //        grounds are unchanged by this inversion).
+  return buildFailureVerdict('verifying', 'Add outcome unconfirmed',
+    'No failure signature was found in the transcript and nothing proves this VM is dead, so the add may still be converging — the ingress keeps propagating for minutes after the provision wrapper exits. Inspect the transcript below; reconcile this VM only if it is still unresolved past the wiring deadline.');
+}
+
+// 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 };
+}
+
+// Pure badge-hold predicate for deriveStatus (server.js): hold the calm in-flight
+// card — instead of the red add-failed — while the add is still converging.
+//
+// The hold used to require `addTailInflight`, i.e. that the detached wire-add-tail
+// PROCESS was still alive. That premise was wrong: the tail's exit says nothing
+// about LB convergence, because the EXTERNAL_MANAGED backend services keep
+// propagating for minutes afterwards. VM-4's backends were still being created at
+// 18:17-18:20Z, long after its job had been declared failed at 18:15Z — the tail
+// had exited, so the calm hold released and the card went red on a healthy VM.
+//
+// The hold is now driven by the question that actually matters: is this add still
+// converging, and has its wiring deadline genuinely blown? `wiringDeadlineBlown`
+// (the failed marker the tail drops when it gives up) stays the release signal —
+// tail liveness is no longer a requirement for calm, so the calm state survives
+// the multi-minute propagation window instead of ending at process exit.
+//
+// Both calm categories qualify (see CALM_ADD_CATEGORIES): a rostered box that is
+// still wiring, and the unproven residue. Any proven-failure category returns
+// false and falls through to the red add-failed status — the operator-chosen
+// escalation, which this predicate narrows but never softens. Kept pure (like
+// canRetryAdd / canClearBadge) so the badge decision is unit-tested without a
+// live dashboard.
+function holdConvergingBadge({ category, wiringDeadlineBlown } = {}) {
+  return CALM_ADD_CATEGORIES.has(category) && !wiringDeadlineBlown;
+}
+
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE };

package/npm/fleet-asset-version.js

@@ -0,0 +1,37 @@
+'use strict';
+// Pure content-hash UI versioning for the fleet dashboard's cache-busting
+// (vm: Honest VM Card Display + Dashboard Cache-Busting).
+//
+// The dashboard serves its single-file UI (public/index.html) with `no-store`,
+// so a hard-refresh always fetches the new code — but an already-OPEN tab never
+// refetches the HTML and silently runs the pre-restart UI until the operator
+// manually reloads. To fix that, the server stamps a short content hash of the
+// served HTML into every /data response; the client records the version it
+// booted with and `location.reload()`s on a mismatch, so a dashboard restart
+// with new UI reaches an open tab automatically.
+//
+// This module is the PURE half — a deterministic hash of the HTML string, no
+// I/O — mirroring the pure/impure split the other fleet-* modules follow
+// (server.js owns reading the file; this owns turning bytes into a version).
+// Unit-tested in npm/fleet-asset-version.test.js.
+//
+// Stack note: this is fleet-operator dashboard infrastructure (the GCE fleet
+// that runs codeyam-editor itself). A project that never runs the dashboard
+// never reaches it.
+const crypto = require('crypto');
+
+// computeAssetVersion returns a stable, short (12 hex chars) fingerprint of the
+// served UI. Same HTML in ⇒ same version out (so an unchanged deploy never
+// spuriously reloads open tabs); any byte change ⇒ a different version (so a
+// real UI change always reloads them). 12 hex chars of SHA-1 is ample to make
+// an accidental collision between two distinct UI builds negligible while
+// keeping the badge short.
+function computeAssetVersion(html) {
+  return crypto
+    .createHash('sha1')
+    .update(String(html == null ? '' : html))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+module.exports = { computeAssetVersion };