@codeyam-editor/codeyam-editor 0.1.0-staging.01efa1a

package/npm/launch-config.js

@@ -0,0 +1,717 @@
+"use strict";
+// Pure helpers for the fleet-dashboard's parametrized launch + cached history.
+//
+// Dependency-free and unit-tested (npm/launch-config.test.js) so the dashboard
+// server (scripts/operator/fleet-dashboard/server.js) can require them without
+// pulling logic into its poll/HTTP path. A "launch config" is the operator's
+// choice of WHICH client project (repo/branch) + WHICH editor (variant/branch)
+// runs on a VM; the history is the cache that makes the last choice the default
+// and past launches one click to re-run.
+
+const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename, AGENT_ENV_VARS } = require("./cloud");
+
+/** The build agents a VM's editor terminal can run, as the keys of cloud.js's
+ *  AGENT_ENV_VARS. Deriving the selectable set from that map keeps it a single
+ *  source of truth with the agent→API-key-env-var mapping (cloud.js) and the
+ *  gcp-bootstrap CLI installer, so adding an agent is still a one-line change in
+ *  AGENT_ENV_VARS rather than a list to keep in sync here. */
+const AGENTS = Object.freeze(Object.keys(AGENT_ENV_VARS));
+
+const EMPTY_CONFIG = Object.freeze({
+  clientRepo: "",
+  clientBranch: "",
+  // Greenfield: when set (and clientRepo empty), launch against a NEW empty
+  // folder of this name instead of cloning a repo.
+  newProjectName: "",
+  editorVariant: "dev",
+  editorBranch: "",
+  // Build agent provider the VM's editor terminal runs (claude | codex | gemini).
+  // Defaults to claude; cloudUpArgs forwards it as cloud:up's --agent flag.
+  agent: "claude",
+});
+
+/** Coerce a raw form/query object into the canonical launch-config shape: trim
+ *  strings, default the variant to a known value. Never throws — validation is
+ *  a separate, explicit step. */
+function normalizeLaunchConfig(input = {}) {
+  const str = (v) => (typeof v === "string" ? v.trim() : "");
+  const editorVariant = EDITOR_VARIANTS.includes(input.editorVariant) ? input.editorVariant : "dev";
+  // Coerce an unknown/absent agent to the default rather than rejecting — the
+  // form's agent selector only ever submits a known value, so an out-of-set
+  // agent is a stale query param, not an error.
+  const agent = AGENTS.includes(input.agent) ? input.agent : "claude";
+  return {
+    clientRepo: str(input.clientRepo),
+    clientBranch: str(input.clientBranch),
+    newProjectName: str(input.newProjectName),
+    editorVariant,
+    editorBranch: str(input.editorBranch),
+    agent,
+  };
+}
+
+/** Validate a normalized config. Returns { ok, msg } so the HTTP layer can
+ *  surface the reason without a try/catch. */
+function validateLaunchConfig(cfg) {
+  const hasRepo = !!(cfg && cfg.clientRepo);
+  const hasNew = !!(cfg && cfg.newProjectName);
+  if (hasRepo && hasNew) {
+    return { ok: false, msg: "specify either a client repo or a new-project name, not both" };
+  }
+  if (!hasRepo && !hasNew) {
+    return { ok: false, msg: "a client repo or a new-project name is required" };
+  }
+  if (hasRepo && !/^(https?:\/\/|git@)/.test(cfg.clientRepo)) {
+    return { ok: false, msg: "client repo must be an https:// or git@ URL" };
+  }
+  if (hasNew && !/^[A-Za-z0-9._-]+$/.test(cfg.newProjectName)) {
+    return { ok: false, msg: "new-project name may contain only letters, numbers, dot, dash, underscore" };
+  }
+  if (!EDITOR_VARIANTS.includes(cfg.editorVariant)) {
+    return { ok: false, msg: `unknown editor variant: ${cfg.editorVariant}` };
+  }
+  return { ok: true };
+}
+
+/** Gate mirror of cloud.js::assertVariantProvisionable — which editor variants
+ *  can be provisioned onto a cloud VM. All three variants now provision: `dev`
+ *  builds the editor image from source, while `staging`/`production` run the
+ *  published npm package (gcp-bootstrap pulls/builds Dockerfile.npm keyed off
+ *  the variant). An unknown variant is excluded so a typo never reaches a
+ *  launch. Pure; no I/O. */
+function isVariantProvisionable(variant) {
+  return EDITOR_VARIANTS.includes(variant);
+}
+
+/** Gate for the in-place BINARY-REBUILD operations (the dashboard's "Rebuild
+ *  binary" / "Update & Reset Everything" actions, and reconfigure's trailing
+ *  binary refresh). Historically distinct from `isVariantProvisionable` because a
+ *  packaged variant's rebuild is an npm-reinstall (rebuildStrategy ===
+ *  "npm-reinstall") and that host-script path was not wired — so this stayed
+ *  dev-only and packaged rebuild buttons failed loud. With the npm-reinstall
+ *  branch now wired into `rebuildBinaryHostScript` (it rebuilds the Dockerfile.npm
+ *  image at the variant's dist-tag instead of source-building Dockerfile), every
+ *  provisionable variant is also rebuildable, so this now mirrors
+ *  `isVariantProvisionable` — only an unknown variant is rejected. Pure; no I/O. */
+function isVariantRebuildable(variant) {
+  return isVariantProvisionable(variant);
+}
+
+/** Map an editor variant to the npm dist-tag its package was published under.
+ *  CI publishes `codeyam.com` → "latest" (production) and `staging.codeyam.com`
+ *  → "staging" (see .github/workflows/cicd.yml "Set release variant"). `dev` has
+ *  no published package (it builds the image from source), so return null and let
+ *  callers reject it. This is the single source of truth for the variant→dist-tag
+ *  contract — the Dockerfile.npm build-arg, publish-editor-image.sh's `--from-npm`
+ *  mode, and the future reconfigure path all derive from it so they can't drift.
+ *  Pure; no I/O. */
+function variantNpmDistTag(variant) {
+  if (variant === "production") return "latest";
+  if (variant === "staging") return "staging";
+  return null; // dev / unknown — no packaged dist-tag
+}
+
+/** Map a packaged editor variant to the GHCR image-tag suffix the packaged
+ *  image is pushed under (`<registry>/codeyam-editor-npm:<suffix>`). Lives beside
+ *  `variantNpmDistTag` so the registry naming convention and the dist-tag mapping
+ *  stay one reviewable unit; `scripts/publish-editor-image.sh --from-npm` asserts
+ *  the literal string this returns. `dev` has no packaged image (built from
+ *  source), so return null. Pure; no I/O. */
+function variantImageTag(variant) {
+  if (variant === "production") return "production-latest";
+  if (variant === "staging") return "staging-latest";
+  return null; // dev / unknown — no packaged image
+}
+
+/** Build the `cloud:up` flag array for a launch config + instance name. The
+ *  editor source is the canonical codeyam-editor repo (dev variant builds the
+ *  image from editorBranch); the client repo/branch is what lands in
+ *  /workspace. The build agent rides on `cfg.agent` (normalizeLaunchConfig
+ *  guarantees a known value, defaulting to claude), so a single config object
+ *  carries every launch choice. Decoupled exactly as cloud.js consumes them. */
+function cloudUpArgs(cfg, instanceName) {
+  const args = ["--instance-name", instanceName];
+  // Greenfield (new folder) vs clone an existing repo.
+  if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
+  else args.push("--repo", cfg.clientRepo);
+  args.push("--agent", cfg.agent || "claude", "--editor-repo", CANONICAL_EDITOR_REPO, "--editor-variant", cfg.editorVariant);
+  if (!cfg.newProjectName && cfg.clientBranch) args.push("--branch", cfg.clientBranch);
+  if (cfg.editorBranch) args.push("--editor-branch", cfg.editorBranch);
+  // The dashboard opens its own per-VM tunnel, so cloud:up must NOT open one:
+  // it lets cloud:up exit cleanly and avoids parallel batches colliding on the
+  // fixed local ports 14199/5173 (the cause of multi-add "false failures").
+  args.push("--no-tunnel");
+  return args;
+}
+
+/** Classify one container-up wait tick into a terminal/continue decision from
+ *  what's been observed so far. This is the race-semantics seam fragility #33
+ *  got wrong (`scripts/operator/fleet-dashboard/server.js::addVm`): the wait
+ *  must poll container status on its own cadence and treat ANY single `Up` as
+ *  terminal success.
+ *
+ *  Rules:
+ *   - everSeenUp                  ⇒ "up"      any single `Up` is terminal —
+ *                                             transient probe blips before it
+ *                                             are irrelevant.
+ *   - instanceGone                ⇒ "failed"  fast-bail: the VM is gone, no
+ *                                             point waiting out the deadline.
+ *   - deadlineSec>0 & elapsed>=it ⇒ "failed"  genuine timeout, no `Up` ever seen
+ *                                             (a non-positive deadline means no
+ *                                             deadline set yet, so never fail).
+ *   - otherwise                   ⇒ "waiting"
+ *
+ *  Deliberately NOT an input: whether `cloud:up` is still alive (its `UP_PID`).
+ *  Under `--no-tunnel` cloud:up exits cleanly the instant the container is up
+ *  (see cloudUpArgs), so its death is the NORMAL success path and must never
+ *  decide failure. The bash loop mirrors this — `kill -0 $UP_PID` is logged as
+ *  informational only. Callers may pass `upPidAlive` for readable test intent;
+ *  it is ignored by design. */
+function classifyContainerWait({ everSeenUp = false, instanceGone = false, elapsedSec = 0, deadlineSec = 0 } = {}) {
+  if (everSeenUp) return "up";
+  if (instanceGone) return "failed";
+  if (deadlineSec > 0 && elapsedSec >= deadlineSec) return "failed";
+  return "waiting";
+}
+
+/** Decide whether a newly-reserved Add slot should start immediately or be
+ *  queued, given the current in-flight count + the configured cap. Pure: pulls
+ *  no globals, has no side effects.
+ *
+ *  Returns "start" when there is headroom under maxConcurrency; "queue"
+ *  otherwise. A non-positive or non-numeric maxConcurrency falls back to
+ *  unbounded ("start" always) — the historical behavior before throttling
+ *  existed, so a misconfigured env var degrades to "no throttle" instead of
+ *  silently freezing all adds.
+ *
+ *  The caller is responsible for the side effects: pushing to a pending
+ *  queue + posting a `queued` job entry on "queue", or starting addVm on
+ *  "start". Decoupling the decision from the I/O makes it unit-testable
+ *  against arbitrary (cap, active) tuples — the test signal the OOM bug
+ *  needed and the queue never had. */
+function decideAddSlot({ maxConcurrency, activeCount = 0 } = {}) {
+  const cap = Number(maxConcurrency);
+  if (!Number.isFinite(cap) || cap <= 0) return "start";
+  return Number(activeCount) < cap ? "start" : "queue";
+}
+
+/** Closed set of "heavy" action names — those that invoke `npm run cloud:up`
+ *  (over gcloud-ssh) and so contend for the shared spawn budget that prevents
+ *  the dashboard's launchd-managed node process from OOMing under burst. The
+ *  set is the single source of truth shared between server.js's throttle gate
+ *  (tryStartOrQueue) and the per-action queued-status mapping below; adding a
+ *  new heavy action means editing both this set and queuedStatusForAction.
+ *  Other actions (set-env, run-setup, reset-*, update-*, destroy) are a single
+ *  ssh round-trip with no long-running child and bypass the throttle entirely
+ *  — they can never OOM the dashboard on burst. */
+const HEAVY_ACTIONS = Object.freeze(["add", "rebuild", "reconfigure", "reset-all", "fleet-ready"]);
+
+/** Map a heavy action to its per-action "queued" UI status string. Used by
+ *  server.js's deriveStatus to render the throttled-but-not-yet-started card
+ *  with a status that matches the eventual running status family
+ *  (add → add-queued / adding, rebuild → rebuild-queued / rebuilding,
+ *  reconfigure → reconfigure-queued / reconfiguring). Returns null for any
+ *  action not in HEAVY_ACTIONS (so the caller can fall through to the
+ *  generic running-state branch). Pure; no I/O. */
+function queuedStatusForAction(action) {
+  switch (action) {
+    case "add": return "add-queued";
+    case "rebuild": return "rebuild-queued";
+    case "reconfigure": return "reconfigure-queued";
+    case "reset-all": return "reset-all-queued";
+    // fleet-ready runs cloud:up/redeploy children, and deriveStatus already
+    // renders a *running* fleet-ready job as "rebuilding"; its queued card
+    // mirrors that same family rather than introducing an unstyled
+    // fleet-ready-queued status the dashboard CSS has no class for.
+    case "fleet-ready": return "rebuild-queued";
+    default: return null;
+  }
+}
+
+/** Push a launch entry onto the newest-first history, capped to `cap`. No
+ *  cross-VM dedup at write time — the full log is what powers per-VM config
+ *  lookups (configForVm); the "recent launches" picker de-dups at read time
+ *  (distinctConfigs). Returns a new array; does not mutate the input. */
+function pushHistory(history, entry, cap = 30) {
+  const arr = Array.isArray(history) ? history.slice() : [];
+  arr.unshift(entry);
+  return arr.slice(0, Math.max(1, cap));
+}
+
+/** Distinct configs, newest-first, for the "recent launches" picker (so the
+ *  same config launched on several VMs shows once — the most-recent
+ *  occurrence). */
+function distinctConfigs(history, limit = 12) {
+  const seen = new Set();
+  const out = [];
+  for (const e of Array.isArray(history) ? history : []) {
+    const k = JSON.stringify(e && e.config);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(e);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/** Display-side companion to `distinctConfigs`: derive the two label strings the
+ *  "recent launches" picker renders for one config, so two configs that differ
+ *  only by build agent (or greenfield project name) look different instead of
+ *  collapsing to identical rows. `distinctConfigs` de-dups on the FULL config, so
+ *  the rows are genuinely distinct launches — the old inline label just never
+ *  surfaced the distinguishing fields (agent, greenfield name).
+ *
+ *  Returns { primary, secondary }:
+ *   - primary:   greenfield (`!clientRepo && newProjectName`) → `new: <name>` so
+ *                two different greenfield projects no longer both read `(none)`;
+ *                else `repoBasename(clientRepo)` + (`@<branch>` when set); else
+ *                `(none)` when there's neither a repo nor a project name.
+ *   - secondary: `editor <variant>` + (`@<editorBranch>` when set) + ` · <agent>`.
+ *
+ *  Normalizes through EMPTY_CONFIG so a pre-`agent` history entry still renders
+ *  `· claude`. Reuses `repoBasename` (cloud.js) so server/browser basename
+ *  semantics stay single-sourced. Pure; no I/O. */
+function recentLaunchDisplay(config) {
+  const cfg = { ...EMPTY_CONFIG, ...(config || {}) };
+  let primary;
+  if (!cfg.clientRepo && cfg.newProjectName) {
+    primary = `new: ${cfg.newProjectName}`;
+  } else if (cfg.clientRepo) {
+    primary = repoBasename(cfg.clientRepo) + (cfg.clientBranch ? `@${cfg.clientBranch}` : "");
+  } else {
+    primary = "(none)";
+  }
+  const secondary =
+    `editor ${cfg.editorVariant || "dev"}` +
+    (cfg.editorBranch ? `@${cfg.editorBranch}` : "") +
+    ` · ${cfg.agent || "claude"}`;
+  return { primary, secondary };
+}
+
+/** The default config to pre-fill the launch form: the most recent launch's
+ *  config, or an empty config when there's no history. */
+function defaultConfig(history) {
+  const h = Array.isArray(history) && history.length ? history[0] : null;
+  return h && h.config ? { ...EMPTY_CONFIG, ...h.config } : { ...EMPTY_CONFIG };
+}
+
+/** The most recent config used on a specific VM number (for the per-card
+ *  Reconfigure form + the card's project/variant display). null when unknown
+ *  (e.g. a VM launched before this feature existed). */
+function configForVm(history, n) {
+  const h = (Array.isArray(history) ? history : []).find((e) => e && e.vm === n);
+  return h && h.config ? { ...EMPTY_CONFIG, ...h.config } : null;
+}
+
+/** Resolve the card's display identity, preferring LIVE truth (the editor's
+ *  `/api/session-info` `clientProject` + `editorIdentity`) over STALE launch
+ *  history. This is the fix for fragility #33's lying label: a CLI branch
+ *  switch (`git checkout -B … && rebuild-self`) never updates launch history,
+ *  so a history-sourced label keeps showing the old branch — but the editor's
+ *  live self-report tracks the actual branch.
+ *
+ *  `live` is the polled VM object ({ clientProject?, editorIdentity? }); an
+ *  older VM whose editor predates this feature reports neither, so the result
+ *  falls back to `historyCfg` (a launch-config shape) field-by-field and
+ *  `source` flags the card as showing inferred-not-live data.
+ *
+ *  Returns { project, clientBranch, editorLabel, source }:
+ *   - project      bare project name (no @branch) — live name wins, else the
+ *                  history repo basename / new-project name.
+ *   - clientBranch live client branch wins, else historyCfg.clientBranch; null
+ *                  when neither (e.g. a non-git client project).
+ *   - editorLabel  from editorIdentity — the branch when kind === "branch",
+ *                  "npm v<version>" when kind === "npm"; else the history
+ *                  variant(@branch) fallback.
+ *   - source       "live" when editorIdentity drove editorLabel, else
+ *                  "history" — the affordance the card uses to mark inferred
+ *                  data. Pure; no I/O. */
+function resolveCardIdentity(live, historyCfg) {
+  const cfg = historyCfg || {};
+  const lcp = live && live.clientProject;
+  const lei = live && live.editorIdentity;
+
+  const historyName = cfg.clientRepo ? repoBasename(cfg.clientRepo) : (cfg.newProjectName || "");
+  const project = (lcp && lcp.name) || historyName || null;
+
+  const clientBranch = (lcp && lcp.branch) || cfg.clientBranch || null;
+
+  let editorLabel;
+  let source;
+  if (lei && lei.kind === "branch" && lei.branch) {
+    editorLabel = lei.branch;
+    source = "live";
+  } else if (lei && lei.kind === "npm") {
+    editorLabel = "npm v" + (lei.version || "?");
+    source = "live";
+  } else {
+    const variant = cfg.editorVariant || "dev";
+    editorLabel = variant + (cfg.editorBranch ? "@" + cfg.editorBranch : "");
+    source = "history";
+  }
+
+  return { project, clientBranch, editorLabel, source };
+}
+
+/** Sticky-merge a VM poll's `clientProject` against the last-known-good value
+ *  so a transient null poll (timeout / partial probe) does not clobber a
+ *  populated identity. The live `clientProject.branch` is the fleet
+ *  classifier's first-choice branch source (`plan_actions` in
+ *  fleet-roll-to-branch.sh); dropping it to null on a missed cycle would
+ *  regress classification to the stale launch-history branch. Mirrors how the
+ *  other live fields tolerate a missed poll: a populated `prev` survives a
+ *  null/absent fresh poll, and a populated fresh poll always wins. Pure; no I/O.
+ *
+ *  @param prev  the previous `state.vms[n].clientProject` (null/undefined ok)
+ *  @param info  the fresh poll result object (null when the probe failed)
+ *  @returns the clientProject to store: fresh value when present, else the
+ *           last-known-good `prev`, else null. */
+function stickyClientProject(prev, info) {
+  const fresh = info && info.clientProject;
+  if (fresh) return fresh;
+  return prev || null;
+}
+
+/** Classify a VM's project KIND as `"self-host"` vs `"guest"` from the live
+ *  identity reported in `/api/session-info` (`clientProject.repo`), with
+ *  launch-history `clientRepo` as a fallback when live is absent. A guest is
+ *  any VM whose repo basename differs from `CANONICAL_EDITOR_REPO`'s
+ *  (`codeyam-editor`) — Margo today, future guests tomorrow.
+ *
+ *  The dashboard surfaces the result with a small `🛡 guest` chip so the
+ *  "leave-the-margo-one-alone"-style caveats become a visible guardrail at
+ *  glance instead of a memo the operator has to remember. The kind is a
+ *  *type*, not an alert — the status badge remains the primary signal.
+ *
+ *  Defaults: both signals missing → `"self-host"` (the dominant fleet shape;
+ *  a falsely visible "guest" badge on a real self-host VM would be more
+ *  confusing than a missing one). Empty-string repos collapse to the same
+ *  unknown-→-self-host default. Reuses `CANONICAL_EDITOR_REPO` so the
+ *  self-host identity stays a single source of truth shared with
+ *  `cloudUpArgs`. Pure; no I/O. */
+function classifyProjectKind(live, historyCfg) {
+  const cfg = historyCfg || {};
+  const lcp = live && live.clientProject;
+  const liveRepo = lcp && typeof lcp.repo === "string" ? lcp.repo : "";
+  const repoUrl = liveRepo || (typeof cfg.clientRepo === "string" ? cfg.clientRepo : "");
+  if (!repoUrl) return "self-host";
+  const canonical = repoBasename(CANONICAL_EDITOR_REPO);
+  return repoBasename(repoUrl) === canonical ? "self-host" : "guest";
+}
+
+/** Resolve where a VM's codeyam-editor SOURCE lives, given its shape. This is
+ *  the load-bearing per-VM-shape branch for the dashboard's "update editor
+ *  source" + "rebuild binary" actions: the editor source — and how you rebuild
+ *  from it — differs between a self-host VM (the client project IS
+ *  codeyam-editor) and a non-self-host one (editing some other project).
+ *
+ *  - Self-host: the editor source IS the agent's workspace, so it's `/workspace`
+ *    INSIDE the container; the rebuild runs there in place (`rebuild-self`).
+ *  - Non-self-host: the editor binary comes from the `codeyam-editor:local`
+ *    image, built on the VM HOST. `scripts/gcp-bootstrap.sh` clones the editor
+ *    repo to `$HOME/codeyam-editor` and builds the image from there, so that is
+ *    the authoritative image source. A self-host VM ALSO carries a creds-bearing
+ *    workspace clone at `$HOME/projects/codeyam-editor` (docs/cloud-editor-stability.md
+ *    "VM-side paths"); the image-rebuild flow prefers it WHEN PRESENT (it can
+ *    `git pull` private repos), else falls back to the canonical image clone.
+ *    The caller checks `path` then `fallbackPath` on disk at runtime.
+ *
+ *  Stack assumption: this encodes the cloud-VM editor-source layout (Docker
+ *  image + ~/projects mount). A non-Docker editor host would need its own
+ *  resolver branch. Pure; no I/O. */
+function resolveEditorSource({ selfHost = false, home = "$HOME" } = {}) {
+  if (selfHost) {
+    return { selfHost: true, location: "container", path: "/workspace", fallbackPath: null };
+  }
+  return {
+    selfHost: false,
+    location: "host",
+    path: `${home}/projects/codeyam-editor`,
+    fallbackPath: `${home}/codeyam-editor`,
+  };
+}
+
+/** Emit the shell snippet that resolves the host editor-source clone ON THE
+ *  REMOTE VM, assigning the chosen path to `$ESRC`. Prefer the credentialed
+ *  projects clone (`src.path`); fall back to the image clone (`src.fallbackPath`)
+ *  only when the primary has no `.git`.
+ *
+ *  CRITICAL — the paths must EXPAND on the VM, not on the laptop. `resolveEditorSource`
+ *  returns `$HOME`-relative CONSTANTS (the dashboard doesn't know the VM's home dir),
+ *  so they go into DOUBLE quotes here, never `shq()`/single-quotes. Single-quoting a
+ *  `$HOME`-bearing path defeats remote expansion: `cd "$ESRC"` then fails with
+ *  `cd: $HOME/...: No such file or directory` on every non-self-host VM (the improve34
+ *  bug). These paths are fixed constants, not user input — no injection surface, so
+ *  `shq()` (which exists to neutralize user input) is the wrong tool. Pure; no I/O.
+ *
+ *  The primary clone is kept only when it is actually USABLE as an editor source,
+ *  not merely when a `.git` directory exists. A half-cloned / corrupt tree has a
+ *  `.git` dir yet can't build — `git rev-parse` fails and there's no Dockerfile, so
+ *  `docker build "$ESRC"` dies on `open Dockerfile: no such file or directory` (the
+ *  improve39 VM-9 bug). The gate therefore requires a valid work tree AND a
+ *  Dockerfile; otherwise it falls back to the canonical image clone
+ *  `$HOME/codeyam-editor` (the authoritative source provisioning built the image
+ *  from). This preserves the prefer-credentialed-clone behavior, but only when the
+ *  credentialed clone actually works. */
+function editorSourceShellResolve(src) {
+  const primary = `ESRC="${src.path}"`;
+  if (!src.fallbackPath) return primary;
+  return `${primary}; { git -C "$ESRC" rev-parse --is-inside-work-tree >/dev/null 2>&1 && [ -f "$ESRC/Dockerfile" ]; } || ESRC="${src.fallbackPath}"`;
+}
+
+/** Choose HOW to rebuild the editor binary on a VM, from its shape + the editor
+ *  variant. The three mechanisms map 1:1 to the EDITOR_VARIANTS contract:
+ *    - "rebuild-self"  — self-host `dev`: compile in place inside the container
+ *                        (`rebuild-self --force-in-container`); /workspace is the
+ *                        editor source.
+ *    - "image-rebuild" — non-self-host `dev`: the binary ships in the
+ *                        `codeyam-editor:local` image, so it needs a host-side
+ *                        `docker build` + container recreate.
+ *    - "npm-reinstall" — a packaged variant (`staging`/`production`): the binary
+ *                        is the published editor npm package, so a rebuild is a
+ *                        reinstall, not a compile.
+ *  Pure; no I/O. `rebuildBinaryHostScript` consumes this to pick its build line
+ *  (the npm-reinstall branch rebuilds the Dockerfile.npm image at the variant's
+ *  dist-tag); the self-host axis is detected at runtime
+ *  on the VM (the `[ -f /workspace/Cargo.toml ]` signal is authoritative even
+ *  for VMs the dashboard has no launch-history record for). */
+function rebuildStrategy({ selfHost = false, editorVariant = "dev" } = {}) {
+  if (editorVariant !== "dev") return "npm-reinstall";
+  return selfHost ? "rebuild-self" : "image-rebuild";
+}
+
+/** Decide whether a new per-VM job may start, given the VM's currently-tracked
+ *  job. `state.jobs[n]` is a SINGLE slot per VM, so a second `startJob` would
+ *  OVERWRITE an in-flight job's tracker — the bug where `reapplyVmEnv`'s
+ *  follow-on `set-env` clobbered a still-running Rebuild's card, so the operator
+ *  saw a `set-env` completion instead of the rebuild they asked for, with no
+ *  error surfaced. Any job already `running` blocks a new one:
+ *    - `idle`            — no in-flight job (or the slot's job already finished);
+ *                          the caller starts normally.
+ *    - `same-action`     — a job with the SAME action is already running; reject
+ *                          (the pre-existing duplicate-click guard).
+ *    - `different-action`— a DIFFERENT action is running; reject rather than
+ *                          clobber its tracker. Operators sequence the two jobs
+ *                          manually (the rare legitimate case).
+ *  Returns `{ decision: 'start' }` or
+ *  `{ decision: 'reject', reason, runningAction }` so the caller builds the
+ *  user-facing message (the two reject reasons word it differently). Pure; no
+ *  I/O — `existing` is the job record, `requested` the action about to start. */
+function decideStartJob({ existing, requested } = {}) {
+  if (!existing || existing.state !== "running") return { decision: "start" };
+  const runningAction = existing.action;
+  if (runningAction === requested) {
+    return { decision: "reject", reason: "same-action", runningAction };
+  }
+  return { decision: "reject", reason: "different-action", runningAction };
+}
+
+/** Decide where a freshly-added VM's credentials come from. The dashboard's
+ *  default is a container→container copy from a live donor VM, but a full
+ *  teardown empties the roster and leaves no donor — so Add must fall back to
+ *  operator-configured sources. Precedence, highest first:
+ *    - "donor"      — a reachable donor exists; copy claude + git from it (the
+ *                     unchanged default). `donor` = the chosen VM number.
+ *    - "host-stash" — no donor, but CLAUDE_CREDS_SRC points at a known-good
+ *                     .credentials.json to push into the new container.
+ *    - "token"      — no donor and no stash, but GITHUB_TOKEN is set (cloud:up
+ *                     seeds git creds at boot). claude auth is NOT seeded.
+ *    - "none"       — nothing available; wire + roster only, claude + git both
+ *                     unseeded.
+ *  Modes "token" and "none" carry no claude auth, so the caller marks the VM
+ *  add-degraded with a `claude /login` remediation. `reachableDonors` must be
+ *  pre-filtered to VMs that actually answered (a destroyed-but-rostered orphan
+ *  is not a donor — fragility #24). Pure; no I/O. */
+function resolveCredsSource({ reachableDonors = [], claudeCredsSrc = "", githubToken = "" } = {}) {
+  const donor = Array.isArray(reachableDonors) && reachableDonors.length ? reachableDonors[0] : null;
+  if (donor != null) return { mode: "donor", donor };
+  if (claudeCredsSrc) return { mode: "host-stash", donor: null };
+  if (githubToken) return { mode: "token", donor: null };
+  return { mode: "none", donor: null };
+}
+
+// Single-quote a string for safe inclusion in a remote shell command. Mirrors
+// the server.js helper so callers don't have to thread one through.
+function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
+
+/** Build the shell steps that seed a freshly-added VM's claude + git credentials,
+ *  for the resolved `mode` (see `resolveCredsSource`). Returns an array of shell
+ *  strings the caller newline-joins into the larger provisioning script — each
+ *  step is independent; a `CY_DEGRADED <message>` from one does not block the
+ *  next, and the dashboard's job-attribution path lifts those markers onto the
+ *  card as `degradedReasons`.
+ *
+ *  Donor mode (the default) copies, container→container from the donor VM:
+ *    1. host-file git credentials   → `$HOME/.codeyam-cloud-git-credentials`
+ *    2. claude `.credentials.json`  → `/root/.claude/.credentials.json`
+ *    3. claude `.claude.json`       → `/root/.claude.json`
+ *  Step 3 (onboarding state — `hasCompletedOnboarding` + sibling keys) is what
+ *  keeps the first interactive `claude` TUI from popping the welcome "Select
+ *  login method" menu; without it the non-interactive `claude --print` probe
+ *  still passes (so `/api/config` reports `authenticated`), but the Build tab
+ *  PTY stalls at the picker. Failure of any single step emits its own
+ *  `CY_DEGRADED` marker — the credentials copy is the load-bearing one; the
+ *  onboarding-state copy is recoverable via `claude /login`.
+ *
+ *  host-stash / token / none modes don't have a donor `.claude.json` to copy —
+ *  for now those paths still land degraded for the same reason; a separate plan
+ *  can extend host-stash with a sibling onboarding-stash env knob.
+ *
+ *  Pure; no I/O. */
+function buildCredsSteps({ mode, refInst = "", inst, container, gcloud, zone, n, claudeCredsSrc = "" } = {}) {
+  const claudeSink = `docker exec -i ${container} bash -c "umask 077; base64 -d > /root/.claude/.credentials.json && chmod 600 /root/.claude/.credentials.json"`;
+  const claudeJsonSink = `docker exec -i ${container} bash -c "umask 077; base64 -d > /root/.claude.json && chmod 600 /root/.claude.json"`;
+  const loginHint = `run: docker exec -it ${container} claude /login on ${inst}`;
+  if (mode === "donor") {
+    return [
+      `echo "copying git creds from ${refInst}..."`,
+      `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='cat $HOME/.codeyam-cloud-git-credentials' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command='umask 077; cat > $HOME/.codeyam-cloud-git-credentials' 2>/dev/null || echo "CY_DEGRADED git creds copy failed on VM-${n} — re-copy creds from a live donor (the agent can't git pull/push until then)"`,
+      `echo "copying claude auth from ${refInst} (container->container)..."`,
+      `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='docker exec ${container} base64 /root/.claude/.credentials.json' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeSink)} 2>/dev/null && echo "claude auth copied" || echo "CY_DEGRADED claude auth copy failed on VM-${n} — ${loginHint}"`,
+      `echo "copying claude.json (onboarding state) from ${refInst} (container->container)..."`,
+      `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='docker exec ${container} base64 /root/.claude.json' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeJsonSink)} 2>/dev/null && echo "claude.json copied" || echo "CY_DEGRADED claude.json copy failed on VM-${n} — first interactive claude launch may show 'Select login method' menu; ${loginHint} once to complete onboarding"`,
+    ];
+  }
+  if (mode === "host-stash") {
+    return [
+      `echo "no reachable donor — seeding claude auth from host stash..."`,
+      `base64 < ${_shq(claudeCredsSrc)} | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeSink)} 2>/dev/null && echo "claude auth seeded from host stash" || echo "WARN claude stash seed failed — ${loginHint}"`,
+    ];
+  }
+  if (mode === "token") {
+    return [
+      `echo "no reachable donor and no CLAUDE_CREDS_SRC — git creds seeded by cloud:up; claude auth NOT seeded. ${loginHint}"`,
+    ];
+  }
+  return [
+    `echo "no reachable donor and no configured creds source — wiring + rostering only; claude AND git auth NOT seeded. ${loginHint}, and set CLAUDE_CREDS_SRC/GITHUB_TOKEN in the dashboard env"`,
+  ];
+}
+
+/** Build the two host-side shell snippets that PRESERVE the container's
+ *  /root/.claude.json (claude onboarding state) across a non-self-host Rebuild's
+ *  container recreate. The whole /root/.claude DIRECTORY is bind-mounted from the
+ *  host ($HOME/.codeyam-cloud-claude → /root/.claude, see docker-compose.cloud.yml),
+ *  so /root/.claude/.credentials.json survives `docker compose down && up`. But
+ *  /root/.claude.json is a SIBLING in the container's EPHEMERAL fs — NOT in the
+ *  bind mount — so a recreate resets it to the image baseline, dropping the
+ *  operator's `hasCompletedOnboarding`. The first interactive `claude` TUI then
+ *  pops the "Select login method" welcome menu and the Build tab is blocked,
+ *  even though the non-interactive `claude --print` auth probe still passes
+ *  (improve36). The good copy is still in the LIVE container right up until
+ *  `docker compose down`, so we capture it to a host temp file, then restore it
+ *  into the freshly-recreated container — no donor required.
+ *
+ *  Returns { capture, restore }, each an array of shell lines for the on-host
+ *  rebuild script (run via gcloud-ssh, direct `docker exec` — same execution
+ *  context as gitReseedHostStep). `capture` runs BEFORE `docker compose down`;
+ *  `restore` runs AFTER `up`, BEFORE the editor verify probe. The lines share a
+ *  `bakVar` shell variable holding the temp-file path, so they MUST be spread
+ *  into the SAME bash invocation. A failed restore emits a `CY_DEGRADED` marker
+ *  (the dashboard lifts it onto the card as a degradedReason) with a
+ *  `claude /login` remediation — the rebuild itself still succeeded, so the job
+ *  lands `done`, not `error`. Pure; no I/O. */
+function buildClaudeJsonPreserveSteps({ container, n = "", bakVar = "CY_CLAUDE_JSON_BAK" } = {}) {
+  const loginHint = `run: docker exec -it ${container} claude /login`;
+  const capture = [
+    `${bakVar}=$(mktemp)`,
+    `if docker exec ${container} cat /root/.claude.json > "$${bakVar}" 2>/dev/null && [ -s "$${bakVar}" ]; then echo "captured /root/.claude.json ($(wc -c < "$${bakVar}") bytes) to preserve onboarding state across recreate"; else echo "no /root/.claude.json to preserve (new container will use the image baseline)"; : > "$${bakVar}"; fi`,
+  ];
+  const restore = [
+    `if [ -s "$${bakVar}" ]; then docker exec -i ${container} bash -c 'umask 077; cat > /root/.claude.json && chmod 600 /root/.claude.json' < "$${bakVar}" && echo "re-seeded /root/.claude.json (onboarding state preserved across recreate)" || echo "CY_DEGRADED claude.json re-seed failed on VM-${n} after Rebuild — first interactive claude launch may show 'Select login method'; ${loginHint} once to complete onboarding"; else echo "no preserved /root/.claude.json; ${loginHint} if the Build tab shows the welcome menu"; fi`,
+    `rm -f "$${bakVar}"`,
+  ];
+  return { capture, restore };
+}
+
+/** Build the shell command that base64-pipes a VM's persisted env over ssh +
+ *  docker-exec stdin into the container's /workspace/.env (umask 077, chmod
+ *  600), chowns it to the workspace owner so the bind-mounted host file is
+ *  readable by `docker compose --force-recreate` (Rebuild / Reconfigure /
+ *  Add — host-side, as the unprivileged SSH user, not root), and restarts
+ *  the dev server. The docker exec runs as root inside the container, so
+ *  without the chown the file lands `root:root 0600` on the host bind-mount
+ *  and the next compose recreate fails `open .env: permission denied`
+ *  (fragility — improve36). `chown --reference=/workspace` inherits whatever
+ *  uid the image's entrypoint assigned to the workspace (currently 1003 =
+ *  the host SSH user), so the fix is robust against future UID changes.
+ *  Values stay out of argv/logs: they ride as base64 over the ssh + docker
+ *  exec stdin, never as CLI arguments. Pure; no I/O. */
+function buildEnvApplyCommand({ gcloud, instance, zone, envFile, container, editorBin } = {}) {
+  const sink = `docker exec -i ${container} bash -lc "umask 077; base64 -d > /workspace/.env && chmod 600 /workspace/.env && chown --reference=/workspace /workspace/.env && cd /workspace && ${editorBin} editor restart-dev-server"`;
+  return `base64 < ${_shq(envFile)} | ${gcloud} compute ssh ${instance} --tunnel-through-iap --zone=${zone} --command=${_shq(sink)}`;
+}
+
+/** Get authenticated Git URL for checking client branch. */
+function getAuthRepoUrl(repo, token) {
+  if (!repo) return "";
+  if (!token) return repo;
+  const sshRegex = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/;
+  const sshMatch = repo.match(sshRegex);
+  if (sshMatch) {
+    return `https://x-access-token:${token}@github.com/${sshMatch[1]}/${sshMatch[2]}`;
+  }
+  if (repo.startsWith("https://github.com/")) {
+    return repo.replace(/^https:\/\/github\.com\//, `https://x-access-token:${token}@github.com/`);
+  }
+  return repo;
+}
+
+/** Interpret the output of git ls-remote to see if a branch exists. */
+function interpretLsRemote({ stdout = "", code = 0, err = null, repo = "", branch = "" } = {}) {
+  const b = (branch || "").trim();
+  if (!b) {
+    return { ok: true, msg: "using repo default branch" };
+  }
+  if (err || code !== 0) {
+    const errMsg = (err && (err.message || String(err))) || "command failed";
+    return {
+      ok: false,
+      soft: true,
+      msg: `couldn't verify branch: ${errMsg.trim()}`
+    };
+  }
+  const trimmed = (stdout || "").trim();
+  if (trimmed) {
+    return { ok: true };
+  } else {
+    return {
+      ok: false,
+      msg: `branch '${b}' not found in ${repo || "repository"}`
+    };
+  }
+}
+
+module.exports = {
+  AGENTS,
+  EMPTY_CONFIG,
+  normalizeLaunchConfig,
+  validateLaunchConfig,
+  isVariantProvisionable,
+  isVariantRebuildable,
+  variantNpmDistTag,
+  variantImageTag,
+  cloudUpArgs,
+  classifyContainerWait,
+  decideAddSlot,
+  HEAVY_ACTIONS,
+  queuedStatusForAction,
+  pushHistory,
+  distinctConfigs,
+  recentLaunchDisplay,
+  defaultConfig,
+  configForVm,
+  resolveCardIdentity,
+  stickyClientProject,
+  classifyProjectKind,
+  resolveCredsSource,
+  buildCredsSteps,
+  buildClaudeJsonPreserveSteps,
+  buildEnvApplyCommand,
+  resolveEditorSource,
+  editorSourceShellResolve,
+  rebuildStrategy,
+  decideStartJob,
+  getAuthRepoUrl,
+  interpretLsRemote,
+};