@codeyam-editor/codeyam-editor 0.1.0 → 0.1.2

package/npm/fleet-roster.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// npm/fleet-roster.js — the fleet roster (`.codeyam/logs/fleet-vms.json`) is a
+// shared contract: the dashboard, the CLI provisioner (`cloud:up`), the
+// `cloud:branch-switch` orchestrator, the vm-watchdog, and the bash tunnel
+// publishers (`vm-urls.sh` / `cloudflared-monitor.sh`) all read it to learn
+// which VMs exist. Before improve38 the *writer* lived only inside the dashboard
+// process (`server.js::saveVmsState`), so a VM provisioned by the CLI never
+// appeared until someone hand-edited the file. This module is the single
+// read+write seam every Node consumer shares, so the writer is no longer locked
+// inside the dashboard.
+//
+// File format (unchanged): a JSON array of VM-number integers. Readers tolerate
+// a missing or malformed file by treating it as the empty roster.
+//
+// Env override: `VMS_STATE_FILE` relocates the file (honored by server.js and
+// cloud-branch-switch.js already); resolved once at module load.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+
+const VMS_STATE_FILE = process.env.VMS_STATE_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-vms.json');
+
+// Canonical roster shape: a sorted, de-duped set of integers. Every read and
+// write funnels through here so on-disk content stays normalized regardless of
+// which consumer last wrote it (or hand-edited it).
+function normalizeRoster(arr) {
+  return [...new Set((arr || []).filter(Number.isInteger))].sort((a, b) => a - b);
+}
+
+// Read the roster, returning a normalized integer array. A missing or malformed
+// file is treated as the empty roster `[]` (the documented contract the previous
+// `readRoster`/`loadVmsState` duplicates shared) so a truncated write or an
+// absent file never throws into a consumer's poll loop.
+function readRoster() {
+  try {
+    const data = JSON.parse(fs.readFileSync(VMS_STATE_FILE, 'utf8'));
+    if (Array.isArray(data)) return normalizeRoster(data);
+  } catch { /* missing or malformed — treated as empty */ }
+  return [];
+}
+
+// Persist `arr` as the roster, atomically: write a temp file then `rename` it
+// over the target so a concurrent reader never observes a half-written file.
+// The temp name carries the pid so two *processes* writing at once (CLI +
+// dashboard) don't clobber each other's temp file before their renames land.
+// Returns the normalized roster that was written.
+function writeRoster(arr) {
+  const next = normalizeRoster(arr);
+  fs.mkdirSync(path.dirname(VMS_STATE_FILE), { recursive: true });
+  const tmp = `${VMS_STATE_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next));
+  fs.renameSync(tmp, VMS_STATE_FILE); // atomic replace
+  return next;
+}
+
+// Append `n` to the roster if absent (idempotent), returning the new roster.
+// A double-roster — e.g. the CLI rosters on `cloud:up` and the dashboard's Add
+// onSuccess rosters again — is a harmless no-op, which is exactly what closes
+// the race where one writer's roster write could fail.
+function addToRoster(n) {
+  return writeRoster([...readRoster(), n]);
+}
+
+// Remove `n` from the roster, returning the new roster. Removing an absent
+// entry is a no-op.
+function removeFromRoster(n) {
+  return writeRoster(readRoster().filter((x) => x !== n));
+}
+
+module.exports = {
+  VMS_STATE_FILE,
+  normalizeRoster,
+  readRoster,
+  writeRoster,
+  addToRoster,
+  removeFromRoster,
+};

package/npm/launch-config.js

@@ -0,0 +1,544 @@
+"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 } = require("./cloud");
+
+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: "",
+});
+
+/** 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";
+  return {
+    clientRepo: str(input.clientRepo),
+    clientBranch: str(input.clientBranch),
+    newProjectName: str(input.newProjectName),
+    editorVariant,
+    editorBranch: str(input.editorBranch),
+  };
+}
+
+/** 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 };
+}
+
+/** Phase-1 gate mirror of cloud.js::assertVariantProvisionable — only `dev`
+ *  provisions today; staging/production are Phase 2. */
+function isVariantProvisionable(variant) {
+  return variant === "dev";
+}
+
+/** 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. Decoupled exactly as cloud.js consumes them. */
+function cloudUpArgs(cfg, instanceName, agent = "claude") {
+  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", agent, "--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;
+}
+
+/** 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 };
+}
+
+/** 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. */
+function editorSourceShellResolve(src) {
+  const primary = `ESRC="${src.path}"`;
+  if (!src.fallbackPath) return primary;
+  return `${primary}; [ -d "$ESRC/.git" ] || 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`, Phase 2):
+ *                        the binary is the published editor npm package, so a
+ *                        rebuild is a reinstall, not a compile.
+ *  Pure; no I/O. The dashboard reuses `isVariantProvisionable` to gate the
+ *  not-yet-wired npm-reinstall path; 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)}`;
+}
+
+module.exports = {
+  EMPTY_CONFIG,
+  normalizeLaunchConfig,
+  validateLaunchConfig,
+  isVariantProvisionable,
+  cloudUpArgs,
+  classifyContainerWait,
+  decideAddSlot,
+  HEAVY_ACTIONS,
+  queuedStatusForAction,
+  pushHistory,
+  distinctConfigs,
+  defaultConfig,
+  configForVm,
+  resolveCardIdentity,
+  classifyProjectKind,
+  resolveCredsSource,
+  buildCredsSteps,
+  buildClaudeJsonPreserveSteps,
+  buildEnvApplyCommand,
+  resolveEditorSource,
+  editorSourceShellResolve,
+  rebuildStrategy,
+  decideStartJob,
+};