@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/launch-config.js

@@ -119,6 +119,52 @@ function validateLaunchConfig(cfg) {
   return { ok: true };
 }
 
+/** Pre-flight the operator-host CONFIG a dashboard Add depends on, BEFORE
+ *  spawning the ~20-min cloud:up. Pure classifier: it takes the ALREADY-resolved
+ *  zone, project, and GitHub token (the side-effecting resolution — env lookups,
+ *  `gh auth token`, gcloud defaults — is the caller's job) and returns { ok, msg }
+ *  naming the exact fix for the FIRST blocking gap. This turns a config fault into
+ *  a seconds-fast, actionable add-rejection instead of a cryptic `cloud:up FAILED
+ *  (exit 1)` the operator has to dig out of a 20-min job log.
+ *
+ *  It guards the two config faults that silently broke every fleet add on
+ *  2026-07-20:
+ *   - no resolvable compute zone → cloud:up aborts at its own --zone check in ~15s
+ *     before creating any instance;
+ *   - no GitHub token → the fresh VM's bootstrap dies cloning the PRIVATE editor
+ *     repo at `could not read Username for 'https://github.com'`.
+ *  `allowNoGitCredentials` mirrors cloud:up's --allow-no-git-credentials opt-out
+ *  for an intentionally read-only VM (no push token needed). Pure; no I/O. */
+function addPreflight({ zone, project, token, allowNoGitCredentials = false } = {}) {
+  const blank = (v) => typeof v !== "string" || v.trim() === "";
+  if (blank(zone)) {
+    return {
+      ok: false,
+      msg:
+        "no compute zone configured — set ZONE in /etc/codeyam/operator-host.env " +
+        "(or `gcloud config set compute/zone <zone>`) before adding a VM.",
+    };
+  }
+  if (blank(project)) {
+    return {
+      ok: false,
+      msg:
+        "no GCP project configured — set GCP_PROJECT (or a non-placeholder " +
+        "project in .codeyam/cloud.json) before adding a VM.",
+    };
+  }
+  if (!allowNoGitCredentials && blank(token)) {
+    return {
+      ok: false,
+      msg:
+        "no GitHub token — set GITHUB_TOKEN/GH_TOKEN in /etc/codeyam/operator-host.env " +
+        "(the VM bootstrap needs it to clone the private editor repo), or provision a " +
+        "read-only VM with --allow-no-git-credentials.",
+    };
+  }
+  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
@@ -186,8 +232,10 @@ function isPlaceholderProject(value) {
  *  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, project) {
+ *  carries every launch choice. Decoupled exactly as cloud.js consumes them.
+ *  `zone` is the resolved compute zone (the dashboard's ZONE); passing it
+ *  explicitly is what keeps an add off the ambient gcloud default. */
+function cloudUpArgs(cfg, instanceName, project, zone) {
   const args = ["--instance-name", instanceName];
   // Pass the authoritative GCP project (the dashboard's resolved PROJECT)
   // explicitly so cloud:up never relies on the spawning shell's ambient
@@ -200,6 +248,13 @@ function cloudUpArgs(cfg, instanceName, project) {
   // preserve the pre-existing arg shape (cloud.js then falls back to the gcloud
   // default, as before).
   if (project) args.push("--project", project);
+  // Pass the resolved compute zone explicitly, for the SAME reason as --project:
+  // a bare cloud:up otherwise falls back to `gcloud config get-value
+  // compute/zone`, and an operator host with no default compute/zone aborts
+  // EVERY add at cloud:up's own --zone check in ~15s, before any instance is
+  // created (the 2026-07-20 fleet-wide add failure). Omitted only when the caller
+  // resolves no zone, preserving the pre-existing arg shape for legacy callers.
+  if (zone) args.push("--zone", zone);
   // Greenfield (new folder) vs clone an existing repo.
   if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
   else args.push("--repo", cfg.clientRepo);
@@ -497,6 +552,61 @@ function stickyAppPort(prevAppPort, info) {
   return typeof prevAppPort === 'number' && !Number.isNaN(prevAppPort) ? prevAppPort : null;
 }
 
+/** Resolve a VM's preview-tunnel reachability stickily, mirroring `stickyAppPort`.
+ *  A single flaky preview probe must not blink the 👁 Live Preview link off:
+ *  an explicit `true`/`false` from the fresh poll passes through (a genuine
+ *  dead/alive transition always wins), but a missing / null / undefined
+ *  `info.previewReachable` (transient poll — the probe was skipped, timed out,
+ *  or the whole probe object is absent) retains the last-known-good
+ *  `prevPreviewReachable` instead of blanking it to null. `null` results only
+ *  when neither a fresh boolean nor a previous boolean exists — the true
+ *  never-probed first-poll case. Pure; no I/O.
+ *
+ *  @param prevPreviewReachable the previous `state.vms[n].previewReachable`
+ *  @param info                 the fresh probe result ({ previewReachable } | null)
+ *  @returns true | false | null per the rules above. */
+function stickyPreviewReachable(prevPreviewReachable, info) {
+  const fresh = info && info.previewReachable;
+  if (fresh === true || fresh === false) return fresh;
+  return prevPreviewReachable === true || prevPreviewReachable === false
+    ? prevPreviewReachable
+    : null;
+}
+
+/** Resolve a VM's preview-SERVING signal — "is the VM's dev server up?" —
+ *  stickily from the `previewState` field the editor already emits on
+ *  `/api/session-info`. This is the operator-host-safe replacement for the
+ *  loopback-only `previewReachable` probe: session-info reaches every VM over
+ *  the IAP-LB seam on the GCE operator host, where the `127.0.0.1` preview
+ *  forward `previewReachable` depended on cannot exist (so it read `false`
+ *  fleet-wide there). It measures the SAME thing the old loopback probe did —
+ *  "the dev server serves" — not public LB ingress; that is `previewIngress`'s job.
+ *
+ *  `compute_preview_state` classifies it authoritatively from inside the VM
+ *  (immune to tunnel flakiness, with a recompile-grace debounce):
+ *    `"forwarding"`   → true  (dev server up / serving).
+ *    `"placeholder"`  → false (dev server down or never started).
+ *    anything else    → sticky: a missing field (legacy editor predating
+ *                       `previewState`, or `info` null on a transient/failed
+ *                       poll) retains the last-known-good `prevPreviewServing`
+ *                       rather than blinking the 👁 link off. `null` only when
+ *                       neither a fresh state nor a previous boolean exists —
+ *                       the true never-probed first-poll case. Pure; no I/O.
+ *
+ *  Mirrors `stickyPreviewReachable`'s tri-state stickiness exactly.
+ *
+ *  @param prevPreviewServing the previous `state.vms[n].previewServing`
+ *  @param info               the fresh `/api/session-info` result ({ previewState } | null)
+ *  @returns true | false | null per the rules above. */
+function stickyPreviewServing(prevPreviewServing, info) {
+  const state = info && info.previewState;
+  if (state === 'forwarding') return true;
+  if (state === 'placeholder') return false;
+  return prevPreviewServing === true || prevPreviewServing === false
+    ? prevPreviewServing
+    : 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
@@ -674,6 +784,73 @@ function claudeAuthSeeded(mode) {
 // the server.js helper so callers don't have to thread one through.
 function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
 
+// Assemble a `pkill -f` whose ERE is ANCHORED at the target's own executable:
+// `^`, an optional directory prefix, then `exe`. Every sweep builder in this
+// module routes through here so the anchor is structural rather than remembered
+// — an unanchored `pkill -f` matches the FULL command line, which for the fleet
+// dashboard's `sh -c '<add script>'` wrapper includes the script text itself.
+// See the "Self-match-safe process sweeps" block below for the full failure
+// mode. `argv` is an ERE fragment matched after the executable; escape any
+// literal dots in it.
+function _anchoredSweep({ exe, argv } = {}) {
+  return `pkill -f "^([^ ]*/)?${exe} ${argv}" 2>/dev/null`;
+}
+
+/** Build a `docker exec … bash -c` sink that stages stdin to a same-directory
+ *  `.cytmp` sibling and only `mv`s it onto `target` when the staged file is
+ *  NON-EMPTY — exiting 1 (so the caller's `… || echo CY_DEGRADED` fires) and
+ *  leaving any existing `target` UNTOUCHED on empty/unreadable input.
+ *
+ *  Closes the truncate-to-0 hazard the plan targets: an empty/unreadable donor's
+ *  `base64 -d > /root/.claude/.credentials.json` used to clobber the live creds
+ *  to a 0-byte file AND still report success, because the pipeline's exit status
+ *  is the sink's, not the empty upstream's. This mirrors the non-empty `-s` guard
+ *  the git-cred cache path already uses (scripts/cloud-editor-entrypoint.sh).
+ *
+ *  `decode:true` base64-decodes stdin (the donor / host-stash cred copies);
+ *  `decode:false` copies stdin verbatim (the Rebuild onboarding-state re-seed).
+ *
+ *  `requireCredentialShape:true` adds, ON TOP of the non-empty guard, a Claude
+ *  `.credentials.json` shape check before the `mv`: a positive plausible
+ *  `expiresAt` (rejects the observed corrupt-write `expiresAt: 0`) AND non-empty
+ *  access/refresh tokens. A non-empty-but-malformed donor (valid-looking file
+ *  with a sentinel expiry or empty tokens) therefore never overwrites the
+ *  target — closing the remaining gap the non-empty `[ -s ]` guard alone leaves.
+ *  The checks are quote-free single-quoted ERE patterns (no `"`), which stay
+ *  intact through the ssh→docker→`bash -c "…"` quoting layers without escaping.
+ *  The editor-side self-heal (control-api `creds_refresh` / `auth_session`)
+ *  remains the durable defense against a bad credential from ANY writer; this
+ *  hardens the in-repo copy path so it is not itself a source.
+ *
+ *  Deliberately uses NO shell variables or command substitution: a fixed
+ *  `<target>.cytmp` sibling keeps the script free of `$var`, which the VM-host
+ *  shell that runs the `gcloud … --command` would otherwise expand (to empty)
+ *  before docker exec ever sees it. The `.cytmp` sibling sits in the same
+ *  directory as `target`, so the `mv` is an atomic same-filesystem rename. */
+function verifyBeforeMoveSink(
+  container,
+  target,
+  { decode = true, requireCredentialShape = false } = {},
+) {
+  const tmp = `${target}.cytmp`;
+  const read = decode ? "base64 -d" : "cat";
+  // Positive plausible `expiresAt` (13+ digit millis, first digit non-zero — so
+  // `0`/negatives/tiny values fail), plus non-empty access + refresh tokens
+  // (≥20 token-ish chars). `[^0-9-]*` / `[^A-Za-z0-9]*` bridge the `":"`
+  // punctuation without literal quotes; the value `0` in a corrupt file is a
+  // digit that blocks the skip, so the pattern can't false-match a later field.
+  const shape = requireCredentialShape
+    ? ` && grep -Eq 'expiresAt[^0-9-]*[1-9][0-9]{12,}' ${tmp}` +
+      ` && grep -Eq 'accessToken[^A-Za-z0-9]*[A-Za-z0-9_-]{20,}' ${tmp}` +
+      ` && grep -Eq 'refreshToken[^A-Za-z0-9]*[A-Za-z0-9_-]{20,}' ${tmp}`
+    : "";
+  const script =
+    `umask 077; ${read} > ${tmp}; ` +
+    `if [ -s ${tmp} ]${shape}; then mv ${tmp} ${target} && chmod 600 ${target}; ` +
+    `else rm -f ${tmp}; exit 1; fi`;
+  return `docker exec -i ${container} bash -c "${script}"`;
+}
+
 /** 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
@@ -699,15 +876,22 @@ function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
  *
  *  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"`;
+  // The `.credentials.json` copy additionally validates the donor's credential
+  // shape (positive `expiresAt`, non-empty tokens) before overwriting — a
+  // non-empty-but-corrupt donor must not clobber a working target. The
+  // `.claude.json` (onboarding-state) copy has a different shape, so it keeps
+  // the plain non-empty guard.
+  const claudeSink = verifyBeforeMoveSink(container, "/root/.claude/.credentials.json", {
+    requireCredentialShape: true,
+  });
+  const claudeJsonSink = verifyBeforeMoveSink(container, "/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}"`,
+      `${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} (empty/unreadable/malformed donor — existing creds left untouched, not overwritten with a corrupt credential) — ${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"`,
     ];
@@ -758,7 +942,7 @@ function buildClaudeJsonPreserveSteps({ container, n = "", bakVar = "CY_CLAUDE_J
     `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`,
+    `if [ -s "$${bakVar}" ]; then ${verifyBeforeMoveSink(container, "/root/.claude.json", { decode: false })} < "$${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 };
@@ -806,13 +990,112 @@ function editorTunnelCmd({ gcloud, inst, zone, editorPort, n } = {}) {
  *  from the editor reachability forward (`editorTunnelCmd`): a preview re-wire
  *  pkills + respawns ONLY this process, leaving the editor :14199 forward — and
  *  the reachability probe riding it — untouched. The preview local port is unique
- *  per VM and never collides with the editor port, so the re-wire/destroy
- *  `pkill -f "<previewPort>:127.0.0.1:"` targets exactly this process. Pure; no
- *  I/O. */
+ *  per VM and never collides with the editor port. Sweep it through
+ *  `previewForwardSweepCmd` — the bare `pkill -f "<previewPort>:127.0.0.1:"` this
+ *  comment used to call "targets exactly this process" did NOT: it also matched
+ *  every `sh -c '<add script>'` wrapper carrying that literal. Pure; no I/O. */
 function previewTunnelCmd({ gcloud, inst, zone, previewPort, appPort, n } = {}) {
   return `nohup ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} -- -N -L ${previewPort}:127.0.0.1:${appPort} > /tmp/ssh-preview-vm-${n}.log 2>&1 &`;
 }
 
+/* ── Self-match-safe process sweeps ─────────────────────────────────────────
+ *
+ *  Every builder below emits a `pkill -f` whose match expression is ANCHORED at
+ *  the TARGET's executable — a leading `^`, an optional directory prefix, then
+ *  the program name (`ssh`, `node`, `cloudflared`). That anchor is the entire
+ *  point of these builders, not decoration.
+ *
+ *  `pkill -f` matches the FULL command line. The fleet dashboard runs an Add as
+ *  `/bin/sh -c '<the entire add script text>'`, and that script text EMBEDS these
+ *  very sweep lines — so an unanchored pattern like `pkill -f
+ *  "14199:127.0.0.1:14199"` is a substring of the wrapper's own argv. It SIGTERMs
+ *  the wrapper that is running it, and every concurrent SIBLING add wrapper too.
+ *  The wrapper then dies from an uncaught signal, so its EXIT trap never writes
+ *  the `add-<n>.exit` marker that `fc.readExitMarker` / `fc.reattachVerdict` exist
+ *  to consume; `startJob`'s exec callback reports a red "Add failed" on a VM that
+ *  is fine; and the detached `cloud:up` it started — whose own argv does NOT carry
+ *  the pattern — is orphaned to init and keeps provisioning, after which
+ *  stranded-reconcile declares the VM half-provisioned and stacks a SECOND
+ *  `cloud:up` on top of it. That is the 2026-07-31 VM-3..8 batch, whose containers
+ *  were Up and answering /api/health 200 throughout.
+ *
+ *  Excluding `$$` / `$PPID` does NOT fix this: the processes being wrongly killed
+ *  are SIBLINGS, not self or parent. The pattern itself must be incapable of
+ *  matching a `sh -c '<script>'` command line, and anchoring at the executable is
+ *  what guarantees that — a wrapper's argv always begins with the shell, never
+ *  with `ssh` / `node` / `cloudflared`.
+ *
+ *  Same trap, same lesson as `npm/cloud.js` bootstrapStatusCommand (:1446) and
+ *  projectBootstrapStatusCommand (:1760), which document it explicitly ("the
+ *  status command's own argv contains the bootstrap path, so a `pgrep -f` on it
+ *  would match this very probe") and dodge it with a PID file + `kill -0`. A PID
+ *  file cannot replace THESE sweeps: they deliberately target STRAY processes left
+ *  by a prior add, a crashed watchdog respawn, or an earlier container generation
+ *  — processes this script never owned and holds no PID for. So the sweep stays
+ *  pattern-based; only the pattern's blast radius changes.
+ *
+ *  Keep every sweep in this family behind one of these builders. Re-inlining a
+ *  bare `pkill -f` at a call site is exactly how the bug got in the first time. */
+
+/** Sweep a stray EDITOR reachability forward — the `-L <localPort>:127.0.0.1:14199`
+ *  ssh process `editorTunnelCmd` opens.
+ *
+ *  Targets the `ssh` CHILD, not the `gcloud compute ssh` python parent. The child
+ *  is what binds the local listening socket, so killing it is what actually
+ *  releases the port; the parent is only waiting on it and exits on its own once
+ *  it goes. Only the child's argv starts with `ssh`, which is also what makes the
+ *  anchor safe. Pure; no I/O. */
+function editorForwardSweepCmd({ localPort } = {}) {
+  return _anchoredSweep({ exe: "ssh", argv: `.*-L ${localPort}:127\\.0\\.0\\.1:14199` });
+}
+
+/** Sweep a stray LIVE-PREVIEW forward — the `-L <localPort>:127.0.0.1:<appPort>`
+ *  ssh process `previewTunnelCmd` opens. The remote port is left open because the
+ *  app's dev-server port legitimately drifts; the per-VM preview local port is the
+ *  identifying half and never collides with the editor port. Same ssh-child
+ *  targeting as `editorForwardSweepCmd`. Pure; no I/O. */
+function previewForwardSweepCmd({ localPort } = {}) {
+  return _anchoredSweep({ exe: "ssh", argv: `.*-L ${localPort}:127\\.0\\.0\\.1:` });
+}
+
+/** Sweep a wedged `cloud:up` provision for one instance.
+ *
+ *  Targets the `node npm/cloud.js up --instance-name <inst>` process, NOT the
+ *  `npm run cloud:up` parent — call sites already hold the npm child's PID and
+ *  `kill` it directly; this reaps the node grandchild that PID does not cover.
+ *  `--instance-name` is the first pair `cloudUpArgs` emits, so the literal stays
+ *  adjacent to `up`. Pure; no I/O. */
+function cloudUpSweepCmd({ inst } = {}) {
+  return _anchoredSweep({ exe: "node", argv: `.*cloud\\.js up --instance-name ${inst}` });
+}
+
+/** Sweep the cloudflared quick-tunnel fronting a VM's editor port.
+ *
+ *  Anchored for the same reason as its siblings, with one extra bite: this sweep
+ *  runs inside a `sh -c` compound built by `exec()`, so unanchored it matched its
+ *  OWN parent shell — killing the compound before the editor/preview sweeps that
+ *  follow it on the same line ever ran. Pure; no I/O. */
+function cloudflaredTunnelSweepCmd({ localPort } = {}) {
+  return _anchoredSweep({ exe: "cloudflared", argv: `tunnel --url http://localhost:${localPort}` });
+}
+
+/** Build the destroy-time local reap compound for one VM: free the editor port,
+ *  then sweep the cloudflared quick-tunnel and BOTH split ssh forwards.
+ *
+ *  Lives here rather than inline in `cleanLocalVmArtifacts` because the ORDERING
+ *  is load-bearing and was previously untestable: the whole compound runs as one
+ *  `sh -c`, so the unanchored cloudflared sweep used to match that shell's own
+ *  argv and kill it BEFORE the two forward sweeps behind it ever ran — meaning a
+ *  destroy silently orphaned both forwards. Pure; no I/O. */
+function localVmReapCmd({ port, previewPort } = {}) {
+  return [
+    `lsof -ti:${port} 2>/dev/null | xargs -r kill`,
+    cloudflaredTunnelSweepCmd({ localPort: port }),
+    editorForwardSweepCmd({ localPort: port }),
+    previewForwardSweepCmd({ localPort: previewPort }),
+  ].join("; ");
+}
+
 /** Build the shell snippet the Add script runs to AWAIT cloud:up's clean exit at
  *  container-healthy instead of reaping it mid-flight.
  *
@@ -837,7 +1120,7 @@ function awaitWiringCmd({ inst, deadlineSec = 180, pidVar = "UP_PID" } = {}) {
     `while kill -0 $${pidVar} 2>/dev/null; do`,
     `  if [ "$__cy_wiring_waited" -ge ${deadlineSec} ]; then`,
     `    echo "WARN cloud:up still running after ${deadlineSec}s (wedged before the container-healthy early return) — reaping it (the dashboard self-heal will converge any half-wired backend)"`,
-    `    kill $${pidVar} 2>/dev/null; pkill -f "cloud.js up --instance-name ${inst}" 2>/dev/null; break`,
+    `    kill $${pidVar} 2>/dev/null; ${cloudUpSweepCmd({ inst })}; break`,
     `  fi`,
     `  sleep 5; __cy_wiring_waited=$((__cy_wiring_waited + 5))`,
     `done`,
@@ -890,6 +1173,7 @@ module.exports = {
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
+  addPreflight,
   isVariantProvisionable,
   isVariantRebuildable,
   variantNpmDistTag,
@@ -909,10 +1193,13 @@ module.exports = {
   resolveCardIdentity,
   stickyClientProject,
   stickyAppPort,
+  stickyPreviewReachable,
+  stickyPreviewServing,
   classifyProjectKind,
   resolveCredsSource,
   claudeAuthSeeded,
   buildCredsSteps,
+  verifyBeforeMoveSink,
   buildClaudeJsonPreserveSteps,
   buildEnvApplyCommand,
   resolveEditorSource,
@@ -921,6 +1208,11 @@ module.exports = {
   decideStartJob,
   editorTunnelCmd,
   previewTunnelCmd,
+  editorForwardSweepCmd,
+  previewForwardSweepCmd,
+  cloudUpSweepCmd,
+  cloudflaredTunnelSweepCmd,
+  localVmReapCmd,
   awaitWiringCmd,
   getAuthRepoUrl,
   interpretLsRemote,