@codeyam-editor/codeyam-editor 0.1.15 → 0.1.16

package/npm/fleet-preview-health.js

@@ -0,0 +1,156 @@
+'use strict';
+
+// The dashboard's honest preview verdict: does the path the load balancer uses
+// to reach a VM's Live Preview actually answer?
+//
+// Every older preview signal is blind to a dead preview by construction.
+// `previewServing` is the editor reporting on its OWN proxy, `previewIngress`
+// can be answered by the LB itself, and the LB's backend health checks the
+// editor port (14199), never the app. VM-15 (2026-10-17) read green on all of
+// them while its host published 3000 and the editor's proxy bound 4321, so
+// docker-proxy accepted every LB connection and reset it.
+//
+// Two detectors, because they answer different questions:
+//   • app-port drift (npm/app-port-drift.js) names the CAUSE — the published
+//     host port and the declared app port disagree;
+//   • the endpoint dial catches the whole accept-then-reset CLASS, including a
+//     dev server that died or a proxy wedged bound-but-not-accepting.
+// Pure: server.js owns the gcloud read and the dial, and feeds the results here.
+
+const { appPortDriftRemediations } = require('./app-port-drift');
+
+const PORT_DRIFT_RUNBOOK = 'docs/preview-port-drift.md';
+
+/** Parse `gcloud compute network-endpoint-groups list-network-endpoints
+ *  --format='value(networkEndpoint.ipAddress,networkEndpoint.port)'` output
+ *  into `[{ ip, port }]`. Lines that do not carry both an address and a valid
+ *  port are dropped — an unreadable endpoint is never dialed as a guess. */
+function parseNegEndpoints(stdout) {
+  if (typeof stdout !== 'string') return [];
+  const out = [];
+  for (const line of stdout.split('\n')) {
+    const [ip, portText] = line.trim().split(/\s+/);
+    const port = Number(portText);
+    if (!ip || !/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) continue;
+    if (!Number.isInteger(port) || port <= 0 || port >= 65536) continue;
+    out.push({ ip, port });
+  }
+  return out;
+}
+
+/** Classify one dial of a preview endpoint.
+ *
+ *  ANY HTTP response — 200, 307, 404, 500 — means the app answered, so the LB
+ *  can reach it: `answered`. A connection reset or refusal is the Envoy
+ *  "upstream connect error … connection termination" shape: `reset`. A dial
+ *  that hit its budget is `timeout`. Anything else is `unknown`, which never
+ *  raises an alarm. */
+function classifyPreviewDial({ statusCode, error, timedOut } = {}) {
+  if (Number.isInteger(statusCode)) return 'answered';
+  if (timedOut) return 'timeout';
+  const code = error && error.code;
+  if (code === 'ECONNRESET' || code === 'ECONNREFUSED' || code === 'EPIPE'
+    || /socket hang up/i.test(String(error && error.message))) {
+    return 'reset';
+  }
+  return 'unknown';
+}
+
+/** Fold the per-endpoint dial verdicts into one `{ verdict, endpoints }`.
+ *  Every endpoint the LB may pick must answer, so the worst verdict wins:
+ *  any `reset`/`timeout` is a dead preview; all `answered` is a live one; no
+ *  endpoints or any `unknown` leaves the verdict `unknown`. */
+function aggregatePreviewDials(dials) {
+  const list = Array.isArray(dials) ? dials : [];
+  const endpoints = list.map((d) => ({ ip: d.ip, port: d.port, verdict: d.verdict }));
+  const dead = list.find((d) => d.verdict === 'reset' || d.verdict === 'timeout');
+  if (dead) return { verdict: dead.verdict, endpoints };
+  if (list.length && list.every((d) => d.verdict === 'answered')) return { verdict: 'answered', endpoints };
+  return { verdict: 'unknown', endpoints };
+}
+
+/** Read a VM's preview NEG endpoints and dial every one, through injected I/O
+ *  so it runs with no gcloud and no network in tests. `deps.listEndpoints()`
+ *  resolves the gcloud list output (null on failure); `deps.dial(ep)` resolves
+ *  a `classifyPreviewDial` outcome. No endpoints → `unknown`, never dead. */
+async function collectPreviewEndpoint(deps) {
+  const endpoints = parseNegEndpoints(await deps.listEndpoints());
+  if (!endpoints.length) return { verdict: 'unknown', endpoints: [] };
+  const dials = await Promise.all(endpoints.map(async (ep) => (
+    { ...ep, verdict: classifyPreviewDial(await deps.dial(ep)) }
+  )));
+  return aggregatePreviewDials(dials);
+}
+
+/** The app-port-drift reason for the card's amber badge, or null. `drift` is a
+ *  `collectAppPortDrift` finding (or any `{ published, declared }`); the
+ *  remediations are recomputed when absent so a bare pair still names the fix. */
+function appPortDriftReason(drift, vmNumber) {
+  if (!drift || !Number.isInteger(drift.published) || !Number.isInteger(drift.declared)) return null;
+  if (drift.published === drift.declared) return null;
+  const remediations = Array.isArray(drift.remediations) && drift.remediations.length
+    ? drift.remediations
+    : appPortDriftRemediations({ vmNumber, declared: drift.declared, published: drift.published, idle: drift.idle || null });
+  return {
+    kind: 'app-port-drift',
+    published: drift.published,
+    declared: drift.declared,
+    fix: remediations[0].text,
+    runbook: PORT_DRIFT_RUNBOOK,
+  };
+}
+
+/** The dead-endpoint reason for the card's amber badge, or null. Only a
+ *  confirmed `reset`/`timeout` raises it; `answered` and `unknown` stay silent. */
+function previewEndpointReason(previewEndpoint) {
+  if (!previewEndpoint) return null;
+  const { verdict, endpoints } = previewEndpoint;
+  if (verdict !== 'reset' && verdict !== 'timeout') return null;
+  const dead = (endpoints || []).find((e) => e.verdict === verdict) || {};
+  return {
+    kind: 'endpoint-dead',
+    verdict,
+    endpoint: dead.ip && dead.port ? `${dead.ip}:${dead.port}` : null,
+    runbook: PORT_DRIFT_RUNBOOK,
+  };
+}
+
+/** Resolve the one `previewMisconfigured` reason the card renders, most
+ *  specific first: the preview-origin guard (its own shape, unchanged), then
+ *  the port drift that names the cause, then the bare dead endpoint. Null when
+ *  the VM is unreachable — its last-known readings are stale, and an
+ *  unreachable card has louder problems to report. */
+function resolvePreviewMisconfigured(v, vmNumber) {
+  if (!v || !v.reachable) return null;
+  return v.previewMisconfigured
+    || appPortDriftReason(v.appPortDrift, vmNumber)
+    || previewEndpointReason(v.previewEndpoint)
+    || null;
+}
+
+/** Re-derive `backendHealth.preview` so it never claims a health no check
+ *  established. The LB's own health check dials the editor port, so its
+ *  preview verdict says nothing about the app: `healthy` survives only when
+ *  the endpoint dial answered, becomes `unhealthy` when the dial was reset or
+ *  timed out, and `unverified` when no dial has landed. Non-healthy LB verdicts
+ *  (`absent`, `unhealthy`, `unknown`) pass through untouched, as does `editor`. */
+function gatePreviewBackendHealth(backendHealth, previewEndpoint) {
+  if (!backendHealth || typeof backendHealth !== 'object') return backendHealth || null;
+  if (backendHealth.preview !== 'healthy') return backendHealth;
+  const verdict = previewEndpoint && previewEndpoint.verdict;
+  let preview = 'unverified';
+  if (verdict === 'answered') preview = 'healthy';
+  else if (verdict === 'reset' || verdict === 'timeout') preview = 'unhealthy';
+  return { ...backendHealth, preview };
+}
+
+module.exports = {
+  parseNegEndpoints,
+  classifyPreviewDial,
+  aggregatePreviewDials,
+  collectPreviewEndpoint,
+  appPortDriftReason,
+  previewEndpointReason,
+  resolvePreviewMisconfigured,
+  gatePreviewBackendHealth,
+};

package/npm/fleet-revision.js

@@ -150,6 +150,55 @@ function projectBinaryRevision(memo = {}) {
   return { ...memo, level: classifyBinaryStaleness(memo) };
 }
 
+/** The `/data` view of the pinned branch's PUBLISH state — whether new and
+ *  refreshed VMs will boot the tip's binary, or an older one.
+ *
+ *  `binaryRevision` above measures only this host's own CLI. The artifact every
+ *  newly provisioned VM pulls is a different thing, published on demand, and it
+ *  stayed invisible: on 2026-10-17 VMs 3 and 8 would have booted a build many
+ *  commits behind the tip, with nothing on this page saying so. The hourly
+ *  operator refresh (refresh-operator-repo.sh, step 9b) now publishes the tip
+ *  itself and records what it found in `auto-publish.state.json`; this reads
+ *  that record.
+ *
+ *  `lockAlive` is whether the publish that record started is still running. A
+ *  `publishing` record with a dead lock is a publish that ended between ticks —
+ *  it may have succeeded or failed, and only the next tick knows, so it reads
+ *  `behind` rather than claiming either.
+ *
+ *  Levels: 'published' | 'publishing' | 'behind' | 'unchecked'. 'unchecked'
+ *  covers no record yet and a record for a branch other than the pin (the pin
+ *  moved; the next tick rewrites it) — both render nothing rather than a
+ *  verdict about the wrong branch.
+ *
+ *  Pure; no I/O. */
+function projectBranchPublish({ doc, lockAlive = false, branch } = {}) {
+  const none = { level: 'unchecked', text: null };
+  if (!doc || typeof doc !== 'object' || typeof doc.state !== 'string') return none;
+  if (branch && doc.branch !== branch) return none;
+  const base = {
+    branch: doc.branch || null,
+    tip: doc.tip || null,
+    tag: doc.tag || null,
+    behind: Number.isInteger(doc.behind) ? doc.behind : null,
+    checkedAt: doc.checkedAt || null,
+  };
+  const gap = base.behind === null ? 'an older build' : `${base.behind} commit(s) behind`;
+  if (doc.state === 'published') {
+    return { ...base, level: 'published', text: 'branch binary published at tip' };
+  }
+  if (doc.state === 'code-identical') {
+    return { ...base, level: 'published', text: `branch binary current (${base.tag || 'newest artifact'} is code-identical to the tip)` };
+  }
+  if (doc.state === 'publishing' && lockAlive) {
+    return { ...base, level: 'publishing', text: `publishing the tip — new VMs boot ${base.tag || 'an older build'} (${gap}) until it lands` };
+  }
+  if (doc.state === 'publishing') {
+    return { ...base, level: 'behind', text: `tip binary not confirmed published — new VMs boot ${base.tag || 'an older build'} (${gap}); the next hourly refresh retries` };
+  }
+  return none;
+}
+
 /** Why did the CLI shell-out fail — and is it the nameable one?
  *
  *  The 2026-08-21 outage surfaced ONLY as a truncated `queueFreshness.error`
@@ -207,6 +256,7 @@ module.exports = {
   projectDashboardRevision,
   classifyBinaryStaleness,
   projectBinaryRevision,
+  projectBranchPublish,
   classifyCliFailure,
   projectCliHealth,
 };

package/npm/fleet-sticky-fields.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const fes = require('./fleet-effect-status');
+const fstrand = require('./fleet-strand');
+
+// npm/fleet-sticky-fields.js — the readings pollVMs (fleet-dashboard server.js)
+// carries across its 3s hot-path rebuild of a VM's record.
+//
+// Every field here is refreshed somewhere SLOWER than the 3s poll — the
+// EFFECT_POLL_MS gather, or an out-of-band action — so the rebuild must keep the
+// last-known value alive or the card would blank and flicker back every cycle.
+// Each fallback below is the one the field has always had, and they differ on
+// purpose: a tri-state reading defaults to null ("unknown, never a false
+// alarm"), a counter or timestamp to 0, an in-flight flag to false, and two
+// credential readings stay `undefined` so a VM never gathered reads as unknown.
+//
+// Pure: takes the VM's previous record (or undefined) and returns the carried
+// subset. pollVMs spreads it after the probe results, which is where these
+// fields always sat.
+function carriedSlowGatherFields(prev) {
+  const p = prev || {};
+  return {
+    // Per-button effect verdicts (improve39), refreshed in place by pollEffects.
+    effects: p.effects || null,
+    // Disk-pressure reading { usedPct, level }, folded into the effects gather.
+    disk: p.disk || null,
+    // Credential-integrity verdict (true | false | null) from the gather's CRED
+    // marker; pollVMs folds it into providerAuth, so donor selection and the
+    // card read it from the one record.
+    credentialIntact: prev ? prev.credentialIntact : undefined,
+    // Which Claude store is live (project|home), from the same slow gather.
+    claudeStore: prev ? prev.claudeStore : undefined,
+    // LB backend health { editor, preview } (vm: Card Readiness Display). Without
+    // the carry the readiness state would blank and the card flicker back to a
+    // clickable link every hot-path poll.
+    backendHealth: p.backendHealth || null,
+    // The two LB-path preview readings: `publishedAppPort` is the host port the
+    // editor container publishes (folded into the fact gather's SSH);
+    // `previewEndpoint` is the dial of the preview NEG endpoint the LB uses.
+    publishedAppPort: prev ? prev.publishedAppPort : null,
+    previewEndpoint: prev ? prev.previewEndpoint : null,
+    // IAP-access verdict ('granted'|'no-accessor'|'unknown'); without the carry
+    // the 'iap-access-missing' readiness state would blank every hot poll.
+    iapAccess: p.iapAccess || null,
+    // Live IAM member lists { editor, preview, all, partial }. null until the
+    // first successful gather and whenever a surface read errors — the card
+    // treats null as "not yet verified", never as "nobody has access".
+    iapMembers: p.iapMembers || null,
+    // Public-URL verdict 'wired'|'unwired'|'unknown' plus its auto-rewire
+    // debounce (vm: Dashboard validates the public ingress URL). The timestamp
+    // and in-flight flag MUST survive the rebuild or the re-wire would re-fire
+    // every 3s while a correct LB change is still propagating (VM5's correct
+    // rule 503'd for minutes before flipping).
+    publicUrlHealth: p.publicUrlHealth || null,
+    // Collapsed URL-wiring state (vm--add-time-url-wiring-converges-reliably),
+    // so the card's "wiring…" / clickable / "wiring-failed" read does not
+    // flicker between slow gathers. null in legacy quick-tunnel mode.
+    urlWiringState: p.urlWiringState || null,
+    lastIngressRewireAt: p.lastIngressRewireAt || 0,
+    ingressRewireInFlight: !!p.ingressRewireInFlight,
+    // "Editor BES exists but has zero NEG backends" (the backendless
+    // half-wire). Without the carry the auto-rewire gate reads undefined and
+    // suppresses the backendless self-heal until the next slow cycle.
+    backendEditorBackendless: !!p.backendEditorBackendless,
+    // Env-override verdict (applied/skipped + tagged repo), set out-of-band by
+    // reapplyVmEnv (recordEnvOverrideStatus), never on the 3s poll.
+    envOverride: p.envOverride || null,
+    // WS-usability signals (vm: Readiness Verifies Real Usability): the public
+    // WebSocket-upgrade verdict and the editor BES timeoutSec, so the 'ws-dead'
+    // readiness label does not flicker between slow cycles.
+    publicWsHealth: p.publicWsHealth || null,
+    backendTimeoutSec: p.backendTimeoutSec != null ? p.backendTimeoutSec : null,
+    // Launcher-strand verdict, its consecutive streak, and the recover debounce
+    // (vm: Fleet converges onto the launcher-strand fix). The debounce MUST
+    // survive the rebuild or the self-heal would re-fire every cycle while a
+    // heavy rebuild is still settling — the unreachableStreak pattern exactly.
+    strandVerdict: p.strandVerdict || null,
+    strandStreak: p.strandStreak || 0,
+    lastStrandRecoverAt: p.lastStrandRecoverAt || 0,
+    strandRecoverInFlight: !!p.strandRecoverInFlight,
+    // "Running binary predates the launcher-strand boot guard" { stale, reason }:
+    // the proactive signal for a VM serving fine now that will strand on its
+    // next re-exec.
+    binaryGuardStale: p.binaryGuardStale || null,
+  };
+}
+
+// The fields one in-container facts gather lands on a VM's record — the
+// producer side of the carry above. A failed gather yields only all-unknown
+// button effects; a successful one yields the effects, the disk reading, the
+// three readings the gather carries only when it reached its FACT marker (so a
+// fallback gather keeps the last-known verdict by omitting the key), and the
+// launcher-strand binary-guard verdict (vm: Fleet converges onto the
+// launcher-strand fix). `editorIdentity` is the VM's advertised identity, whose
+// `bootGuards` the guard check reads; `unknownEffects(reason)` builds the
+// all-unknown effects map. Pure: returns the patch, writes nothing.
+function factsGatherFields({ err, facts, editorIdentity, unknownEffects }) {
+  if (err || !facts) {
+    return { effects: unknownEffects(`effect check unavailable: ${err || 'no facts'}`) };
+  }
+  const out = {};
+  try { out.effects = fes.computeButtonEffects(facts); }
+  catch (e) { out.effects = unknownEffects(`effect check error: ${(e && e.message) || 'unknown'}`); }
+  out.disk = facts.disk || null;
+  for (const key of ['credentialIntact', 'claudeStore', 'publishedAppPort']) {
+    if (facts[key] !== undefined) out[key] = facts[key];
+  }
+  // Read the `bootGuards` the editor advertises, falling back to the editor
+  // source's behind-count when an older binary predates the field. Requires
+  // BOTH guards: a binary with serve_cwd_directly that predates
+  // capture_session_auth (VM-13) must still be flagged so its component
+  // captures don't silently 401 on the non-loopback bind.
+  try {
+    const g = fstrand.classifyBinaryGuard({
+      bootGuards: (editorIdentity && editorIdentity.bootGuards) || undefined,
+      editorBehind: (facts.editor && facts.editor.behind) || 0,
+      requiredGuard: [fstrand.SERVE_CWD_GUARD, fstrand.CAPTURE_AUTH_GUARD],
+    });
+    out.binaryGuardStale = g.stale ? g : null;
+  } catch (e) { /* best effort — never block the gather */ }
+  return out;
+}
+
+module.exports = { carriedSlowGatherFields, factsGatherFields };

package/npm/launch-config.js

@@ -15,6 +15,15 @@ const { normalizeRepoUrl } = require("./fleet-env");
 const { API_BUDGET_DEFAULTS, wouldExceedApiBudget } = require("./fleet-api-budget");
 const { posix: posixPath } = require("node:path");
 const { hostDiskHeadroomCheck } = require("./operator-host-disk");
+const {
+  editorTunnelCmd,
+  previewTunnelCmd,
+  editorForwardSweepCmd,
+  previewForwardSweepCmd,
+  cloudUpSweepCmd,
+  cloudflaredTunnelSweepCmd,
+  localVmReapCmd,
+} = require("./vm-forwards");
 
 /** 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
@@ -736,6 +745,39 @@ function resolveCardIdentity(live, historyCfg) {
   };
 }
 
+const ADOPTION_STATES = ["adopted", "server-not-adopted", "aliases-diverged"];
+
+/** Resolve the card's adoption badges from the editor's live `editorAdoption`
+ *  — whether the deployment `resolveCardIdentity` reports is the binary the VM
+ *  is actually RUNNING. The deployment record is written at install time,
+ *  adopted or not, so on its own a half-applied refresh (VM 23, 2026-10-17)
+ *  read as healthy. The VM compares artifact digests and alias inodes itself;
+ *  this only normalizes its answer, so index.html renders it and never
+ *  re-derives it. Returns:
+ *   - adoptionState "adopted" | "server-not-adopted" | "aliases-diverged", or
+ *                  "unknown" when the editor reports none (older editor, no
+ *                  deployment record) or an unrecognized value. Unlike
+ *                  deployedState, both non-adopted values are real faults.
+ *   - aliasesDiverged / aliasesChecked the alias counts, for the hover; null
+ *                  when unreported.
+ *   - aliasesStale whether any CLI role alias is on a previous build, set even
+ *                  when adoptionState names the more urgent server fault — a
+ *                  server that never adopted the install usually left the
+ *                  aliases behind too (VM 23 had both), and the card shows each.
+ *  Pure; no I/O. */
+function resolveCardAdoption(live) {
+  const lea = live && live.editorAdoption;
+  const adoptionState = lea && ADOPTION_STATES.includes(lea.state) ? lea.state : "unknown";
+  const count = (n) => (Number.isInteger(n) ? n : null);
+  const aliasesDiverged = count(lea && lea.aliasesDiverged);
+  return {
+    adoptionState,
+    aliasesDiverged,
+    aliasesChecked: count(lea && lea.aliasesChecked),
+    aliasesStale: adoptionState === "aliases-diverged" || aliasesDiverged > 0,
+  };
+}
+
 /** 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
@@ -1028,18 +1070,6 @@ 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`;
-}
-
 /** The ONE definition of "a whole Claude `.credentials.json`": a positive
  *  plausible `expiresAt` (13+ digit millis, first digit non-zero — so
  *  `0`/negatives/tiny values fail), plus non-empty access + refresh tokens
@@ -1382,136 +1412,6 @@ function buildEnvApplyCommand({ gcloud, instance, zone, envFile, container, edit
   return `base64 < ${_shq(envFile)} | ${gcloud} compute ssh ${instance} --tunnel-through-iap --zone=${zone} --command=${_shq(sink)}`;
 }
 
-/** Build the `nohup … gcloud compute ssh … -N -L …` shell string that opens the
- *  EDITOR reachability forward (`editorPort` → VM:14199) as its OWN ssh process,
- *  logging to `/tmp/ssh-tunnel-vm-<n>.log`. The editor forward is the dashboard's
- *  reachability signal — the probe to `PORT_BASE+N` connects through it — so it
- *  must have a lifetime INDEPENDENT of the preview forward (whose port legitimately
- *  changes as the app's dev server is resolved). Splitting the two forwards into
- *  separate ssh processes is what makes a preview re-wire non-disruptive: a
- *  preview-port change restarts only the preview tunnel and never blips :14199, so
- *  the reachability probe can't flip the VM to a false "unreachable" (the
- *  VM-1/2/3 flapping observed 2026-06-22). Pairs with `previewTunnelCmd`; the two
- *  builders are the single source of truth for the attach (addVm) and re-wire call
- *  sites so neither forward's `-L` spec can drift back into the other's process.
- *  Pure; no I/O. */
-function editorTunnelCmd({ gcloud, inst, zone, editorPort, n } = {}) {
-  return `nohup ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} -- -N -L ${editorPort}:127.0.0.1:14199 > /tmp/ssh-tunnel-vm-${n}.log 2>&1 &`;
-}
-
-/** Build the `nohup … gcloud compute ssh … -N -L …` shell string that opens the
- *  LIVE-PREVIEW forward (`previewPort` → VM:<appPort>) as its OWN ssh process,
- *  logging to `/tmp/ssh-preview-vm-<n>.log`. The preview forward's target port
- *  changes whenever the app's dev-server port is (re)resolved, so it lives apart
- *  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. 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("; ");
-}
-
 /** Poll cadence for the Add's container gate, as `[{ untilSec, everySec }, …]`
  *  bands over elapsed time; the last band (no `untilSec`) runs to the deadline.
  *  A cold image build takes 15-25 min, so the old flat 10s cadence asked "is it
@@ -1717,6 +1617,7 @@ module.exports = {
   latestLaunchTs,
   recentlyLaunchedWithin,
   resolveCardIdentity,
+  resolveCardAdoption,
   stickyClientProject,
   stickyAppPort,
   stickyPreviewReachable,