@codeyam-editor/codeyam-editor 0.1.8 → 0.1.10

package/npm/group-bounded-spawn.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * group-bounded-spawn.js — run a command synchronously under a wall-clock budget
+ * so that when the budget trips, the command's WHOLE process tree dies with it.
+ *
+ * `spawnSync`'s `timeout` signals only the direct child. `gcloud compute ssh` is a
+ * Python wrapper that runs `/usr/bin/ssh` as its own child, so a timed-out probe
+ * killed the wrapper and orphaned the ssh: re-parented to PID 1 and alive for tens
+ * of minutes against a 2-minute budget (twelve of them on one laptop, driving load
+ * to 14.8 — plan fleet--a-timed-out-gcloud-probe-leaks-its-ssh-session).
+ *
+ * The fix routes the spawn through this same file run as a tiny runner. The runner
+ * stays in the caller's process group, so a terminal Ctrl-C still reaches it; it
+ * starts the real command as the leader of a NEW process group, and on any
+ * terminating signal — including the SIGTERM spawnSync's own timeout sends — takes
+ * that entire group down before exiting with the same signal. The caller therefore
+ * sees exactly the result a plain spawnSync timeout produces (`status: null`,
+ * `signal: "SIGTERM"`, `error.code: "ETIMEDOUT"`), so isSpawnTimeout and
+ * formatGcloudFailure read it unchanged.
+ */
+
+const childProcess = require("child_process");
+const { reconcileGroupKillTarget } = require("./ingress-invoke");
+
+// Between the polite group SIGTERM and the SIGKILL that guarantees nothing
+// survives. Long enough for ssh to restore a raw-mode terminal on SIGTERM.
+const GROUP_KILL_GRACE_MS = 500;
+const TERMINATING_SIGNALS = ["SIGTERM", "SIGINT", "SIGHUP"];
+
+/** Drop-in for `spawnSync(command, args, opts)` whose `timeout` (and any
+ *  terminating signal) reaches every descendant, not only the direct child. */
+function spawnGroupBoundedSync(command, args, opts = {}) {
+  // `childProcess.spawnSync` is resolved at call time, not destructured at load,
+  // so a caller that swaps it (cloud.test.js does) sees every spawn.
+  // Platform assumption: process groups are POSIX. Windows has no group to
+  // signal, so it keeps plain spawnSync semantics (direct child only).
+  if (process.platform === "win32") return childProcess.spawnSync(command, args, opts);
+  return childProcess.spawnSync(process.execPath, [__filename, command, ...args], opts);
+}
+
+function killGroup(leaderPid, signal) {
+  // The shared target derivation refuses pid <= 1, where a negative kill would
+  // signal every process this user owns.
+  const target = reconcileGroupKillTarget(leaderPid);
+  if (target == null) return;
+  try {
+    process.kill(target, signal);
+  } catch {
+    // The group is already gone — nothing left to reap.
+  }
+}
+
+/** Exit the runner the way the wrapped command ended, so spawnSync's result
+ *  mirrors a direct spawn. A signal is re-raised on ourselves with its handler
+ *  removed, which is what makes `result.signal` read true. */
+function exitLike(code, signal) {
+  if (signal) {
+    for (const s of TERMINATING_SIGNALS) process.removeAllListeners(s);
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code == null ? 1 : code);
+}
+
+/** Take the whole group down: a polite SIGTERM so ssh can restore a raw-mode
+ *  terminal, a SIGKILL after the grace so nothing survives, then exit with the
+ *  signal that started it. */
+function beginGroupTermination(child, signal) {
+  killGroup(child.pid, "SIGTERM");
+  setTimeout(() => {
+    killGroup(child.pid, "SIGKILL");
+    exitLike(null, signal);
+  }, GROUP_KILL_GRACE_MS);
+}
+
+/** Runner body: `node group-bounded-spawn.js <command> [args...]`. */
+function runAsGroupLeader(command, args) {
+  const child = childProcess.spawn(command, args, { stdio: "inherit", detached: true });
+  let terminating = false;
+
+  for (const sig of TERMINATING_SIGNALS) {
+    process.on(sig, () => {
+      if (terminating) return;
+      terminating = true;
+      beginGroupTermination(child, sig);
+    });
+  }
+
+  child.on("error", (err) => {
+    // ENOENT and friends: the command never started. 127 is the shell's
+    // "command not found", and the message lands on stderr for the caller.
+    process.stderr.write(`${err.message}\n`);
+    process.exit(127);
+  });
+  child.on("exit", (code, signal) => {
+    // A termination in flight finishes on its own grace timer.
+    if (terminating) return;
+    // The leader died by a signal nobody sent through us (OOM, an external
+    // kill): its descendants are the same orphans, so take them down too.
+    if (signal) killGroup(child.pid, "SIGKILL");
+    exitLike(code, signal);
+  });
+}
+
+if (require.main === module) {
+  const [command, ...args] = process.argv.slice(2);
+  runAsGroupLeader(command, args);
+}
+
+module.exports = { spawnGroupBoundedSync };

package/npm/launch-config.js

@@ -11,6 +11,7 @@
 const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename, AGENT_ENV_VARS } = require("./cloud");
 const { normalizeVmSlug } = require("./vm-urls");
 const { normalizeAccessList } = require("./fleet-vm-access");
+const { normalizeRepoUrl } = require("./fleet-env");
 
 /** 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
@@ -119,6 +120,79 @@ function validateLaunchConfig(cfg) {
   return { ok: true };
 }
 
+/** The branch refs a launch config asks git to resolve, as
+ *  `[{ field, repo, branch }]` — one entry per branch-carrying field that is
+ *  actually populated. This is the input to a ref-existence preflight; it lives
+ *  beside normalizeLaunchConfig (rather than in a second parser at the add
+ *  endpoint or in cloud.js) because it reads the SAME canonical field names that
+ *  normalizer produces, so a field rename can never leave the two disagreeing.
+ *
+ *  BOTH fields are reported, deliberately. In the 2026-08-25 incident the dead
+ *  ref sat in `clientBranch` AND `editorBranch`, and it was `clientBranch` that
+ *  actually killed the bootstrap — an editor-only check would have missed it.
+ *
+ *  A greenfield add (`newProjectName`, no `clientRepo`) has no client repo to
+ *  resolve a branch against, so its clientBranch is skipped rather than probed
+ *  against a repo URL that does not exist. `editorRepo` is passed in because the
+ *  launch config carries an editor BRANCH but not an editor REPO — the repo is
+ *  the caller's (cloud:up resolves it via resolveEditorConfig; the dashboard
+ *  holds it in REPO). Pure; no I/O. */
+function branchRefTargets(cfg, { editorRepo } = {}) {
+  const c = cfg || {};
+  const targets = [];
+  if (c.clientRepo && c.clientBranch) {
+    targets.push({ field: "clientBranch", repo: c.clientRepo, branch: c.clientBranch });
+  }
+  if (editorRepo && c.editorBranch) {
+    targets.push({ field: "editorBranch", repo: editorRepo, branch: c.editorBranch });
+  }
+  return targets;
+}
+
+/** Partition branchRefTargets by whether each ref still resolves, using an
+ *  INJECTED probe so the decision logic is unit-tested with no network and no
+ *  git. `refExists({ repo, branch })` returns true when the ref is present,
+ *  false when it is provably gone.
+ *
+ *  A probe that cannot reach the remote at all must NOT report false — a network
+ *  or credential fault is not evidence a branch was deleted, and treating it as
+ *  such would refuse every add the moment GitHub blipped. The probe signals that
+ *  by returning `null`/`undefined`, which this treats as "unknown, let it
+ *  through": the classifier arm downstream still catches a genuinely dead ref,
+ *  at the cost this preflight normally saves. Fail-open is the right default
+ *  here precisely because the preflight is an OPTIMIZATION over a failure that
+ *  is already handled, never the only line of defence. Pure; no I/O. */
+function missingBranchRefs(targets, refExists) {
+  const missing = [];
+  for (const t of targets || []) {
+    if (refExists(t) === false) missing.push(t);
+  }
+  return missing;
+}
+
+/** Operator-facing copy for a failed branch-ref preflight. States the OUTCOME
+ *  first (nothing was created), then the mechanism, then the remedy — and never
+ *  the "a partial instance may exist — reconcile or destroy it" language the
+ *  generic provisioning failure uses, which is what made the real incident
+ *  confusing: at preflight time no instance, disk, NEG or backend service has
+ *  been created, so there is nothing to reconcile and nothing to destroy.
+ *
+ *  Names which FIELD carried the dead ref, because the two are configured in
+ *  different places and an operator who only corrects one re-issues a request
+ *  that fails identically. Pure; no I/O. */
+function missingBranchRefMessage(missing) {
+  const list = (missing || [])
+    .map((m) => `${m.field}: branch '${m.branch}' is not on ${m.repo}`)
+    .join("; ");
+  return (
+    `Branch no longer exists on origin — ${list}. ` +
+    "Nothing was provisioned: this is checked before any instance is created, so " +
+    "there is no VM, disk or backend service to clean up. This repo prunes branches " +
+    "when they merge, so a stored branch name expires silently. Re-add on a live " +
+    "branch (the current fleet branch, or any branch that still exists on origin)."
+  );
+}
+
 /** 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,
@@ -406,21 +480,51 @@ function queuedStatusForAction(action) {
 /** 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) {
+ *  (distinctProjectConfigs). Returns a new array; does not mutate the input.
+ *
+ *  The cap is deliberately generous: this log is the ONLY source the picker can
+ *  draw distinct projects from, so it bounds how far back "recent projects" can
+ *  reach, and one project relaunched in a burst must not be able to evict every
+ *  other project from the window. Entries are ~390 bytes, so 100 of them is
+ *  ~39 KB — no meaningful cost, and it also lengthens the reach of the per-VM
+ *  lookups (configForVm / latestLaunchTs) for VMs not relaunched recently. */
+function pushHistory(history, entry, cap = 100) {
   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) {
+/** The identity the "recent launches" picker de-dups on: WHICH PROJECT a launch
+ *  was against, not which exact configuration it used.
+ *
+ *  Per-launch and per-VM fields (clientBranch, editorVariant, editorBranch,
+ *  agent, vmSlug, vmAccess) must NOT participate: they are the variant details
+ *  the operator edits in the form *after* picking a project, so keying on them
+ *  fragments one hot project into many near-identical rows and crowds every
+ *  other project off the list.
+ *
+ *  Repo identity goes through `normalizeRepoUrl` (fleet-env.js), so the scp-like
+ *  and https spellings of one repo — and a `.git` suffix — collapse to one row.
+ *  `repoBasename` is deliberately NOT the key: two owners' repos can share a
+ *  basename. Greenfield launches key on the project name, so two different
+ *  greenfield projects stay two rows. Normalizes through EMPTY_CONFIG so a
+ *  legacy history entry with missing fields cannot throw. Pure; no I/O. */
+function launchProjectKey(config) {
+  const cfg = { ...EMPTY_CONFIG, ...(config || {}) };
+  if (cfg.clientRepo) return `repo:${normalizeRepoUrl(cfg.clientRepo)}`;
+  if (cfg.newProjectName) return `new:${String(cfg.newProjectName).trim().toLowerCase()}`;
+  return "none";
+}
+
+/** Newest config per PROJECT, newest-first, for the "recent launches" picker —
+ *  repo identity or greenfield name (launchProjectKey), so one project launched
+ *  many times shows once, carrying its most recent launch as the row's prefill.
+ *  `limit` bounds the rows returned. */
+function distinctProjectConfigs(history, limit = 12) {
   const seen = new Set();
   const out = [];
   for (const e of Array.isArray(history) ? history : []) {
-    const k = JSON.stringify(e && e.config);
+    const k = launchProjectKey(e && e.config);
     if (seen.has(k)) continue;
     seen.add(k);
     out.push(e);
@@ -429,12 +533,12 @@ function distinctConfigs(history, limit = 12) {
   return out;
 }
 
-/** Display-side companion to `distinctConfigs`: derive the two label strings the
+/** Display-side companion to `distinctProjectConfigs`: 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).
+ *  collapsing to identical rows. `distinctProjectConfigs` de-dups on project identity,
+ *  so each row is one project carrying its most recent launch — and these labels
+ *  are what say which branch / editor variant / agent that launch used.
  *
  *  Returns { primary, secondary }:
  *   - primary:   greenfield (`!clientRepo && newProjectName`) → `new: <name>` so
@@ -522,11 +626,42 @@ function recentlyLaunchedWithin(ts, nowMs, graceMs) {
  *                  variant(@branch) fallback.
  *   - source       "live" when editorIdentity drove editorLabel, else
  *                  "history" — the affordance the card uses to mark inferred
- *                  data. Pure; no I/O. */
+ *                  data.
+ *   - deployedBranch the branch the fleet ADVANCED this VM to, from the editor's
+ *                  `editorDeployment` (which reads the record the refresh script
+ *                  writes at install time); null when the editor reports none.
+ *   - deployedTag  the full artifact tag behind that branch, for the hover.
+ *   - deployedSource "live" when the editor reported a deployment, else
+ *                  "unknown".
+ *   - deployedState the card's three-way presentation verdict, resolved HERE
+ *                  rather than in the browser so the rule is unit-tested in one
+ *                  place and index.html carries no copy of it (the compromise
+ *                  groupVmsByProject's own comment apologizes for, avoidable
+ *                  here because this value rides in the /data payload):
+ *                    "agrees"  deployment and provenance name the same branch
+ *                    "differs" they disagree — the EXPECTED plan-only-retag
+ *                              state, to be shown as a pair, never badged
+ *                    "unknown" no deployment reported
+ *
+ *  editorLabel and deployedBranch answer DIFFERENT questions and are routinely
+ *  expected to disagree. editorLabel is build provenance — what source the
+ *  binary was compiled from — and stays exactly as it was; it is the right
+ *  answer to "what code is this actually running?" and is what fragility #33's
+ *  fix was built for. deployedBranch is the deployment target. After a plan-only
+ *  advance, where fleet-advance-to.sh correctly retags the base branch's CI
+ *  binary, provenance `main` + deployment `editor-improvements-78` is the
+ *  CORRECT state, so the card must present the pair rather than badge it.
+ *
+ *  A missing deployment resolves to null / "unknown" and is NEVER filled in from
+ *  cfg.editorBranch, though that value is right there: it is written at
+ *  reconfigure and is not updated by a binary refresh, so it is stale for
+ *  precisely this question — the same live-over-history discipline the rest of
+ *  this function applies, and the same `source` honesty. Pure; no I/O. */
 function resolveCardIdentity(live, historyCfg) {
   const cfg = historyCfg || {};
   const lcp = live && live.clientProject;
   const lei = live && live.editorIdentity;
+  const led = live && live.editorDeployment;
 
   const historyName = cfg.clientRepo ? repoBasename(cfg.clientRepo) : (cfg.newProjectName || "");
   const project = (lcp && lcp.name) || historyName || null;
@@ -547,7 +682,24 @@ function resolveCardIdentity(live, historyCfg) {
     source = "history";
   }
 
-  return { project, clientBranch, editorLabel, source };
+  const deployedBranch = (led && led.branch) || null;
+  const deployedTag = (led && led.tag) || null;
+  const deployedSource = deployedBranch || deployedTag ? "live" : "unknown";
+  let deployedState;
+  if (!deployedBranch) deployedState = "unknown";
+  else if (deployedBranch === editorLabel) deployedState = "agrees";
+  else deployedState = "differs";
+
+  return {
+    project,
+    clientBranch,
+    editorLabel,
+    source,
+    deployedBranch,
+    deployedTag,
+    deployedSource,
+    deployedState,
+  };
 }
 
 /** Sticky-merge a VM poll's `clientProject` against the last-known-good value
@@ -798,13 +950,29 @@ function decideStartJob({ existing, requested } = {}) {
  *  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 };
+ *  is not a donor — fragility #24).
+ *
+ *  `preferredDonor` (the reachable VM holding the operator's chosen Claude
+ *  account) wins over `reachableDonors[0]` when it is itself reachable. When a
+ *  `requestedAccount` was asked for, the result also carries
+ *  `requestedAccountUnavailable` — true when no preferred donor could honor it —
+ *  so the caller can raise a degraded reason without re-deriving why. With no
+ *  account requested the result shape is unchanged. Pure; no I/O. */
+function resolveCredsSource({
+  reachableDonors = [],
+  preferredDonor = null,
+  requestedAccount = "",
+  claudeCredsSrc = "",
+  githubToken = "",
+} = {}) {
+  const donors = Array.isArray(reachableDonors) ? reachableDonors : [];
+  const preferred = preferredDonor != null && donors.includes(preferredDonor) ? preferredDonor : null;
+  const extra = requestedAccount ? { requestedAccountUnavailable: preferred == null } : {};
+  const donor = preferred != null ? preferred : (donors.length ? donors[0] : null);
+  if (donor != null) return { mode: "donor", donor, ...extra };
+  if (claudeCredsSrc) return { mode: "host-stash", donor: null, ...extra };
+  if (githubToken) return { mode: "token", donor: null, ...extra };
+  return { mode: "none", donor: null, ...extra };
 }
 
 /** True when the resolved creds `mode` (see `resolveCredsSource`) carries a real
@@ -917,7 +1085,12 @@ function verifyBeforeMoveSink(
  *  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 = "" } = {}) {
+function buildCredsSteps({ mode, refInst = "", inst, container, gcloud, zone, n, claudeCredsSrc = "", account = "" } = {}) {
+  // The donor's Claude account, named in the add log so it says WHICH account
+  // was seeded, not only which VM it came from. Reduced to email-safe characters
+  // because it is interpolated into a double-quoted shell `echo`.
+  const acct = String(account).replace(/[^A-Za-z0-9@._+-]/g, "");
+  const acctNote = acct ? ` (account ${acct})` : "";
   // 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
@@ -932,7 +1105,7 @@ function buildCredsSteps({ mode, refInst = "", inst, container, gcloud, zone, n,
     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)..."`,
+      `echo "copying claude auth from ${refInst}${acctNote} (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} (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"`,
@@ -954,6 +1127,21 @@ function buildCredsSteps({ mode, refInst = "", inst, container, gcloud, zone, n,
   ];
 }
 
+/** The CY_DEGRADED reason for an Add whose requested Claude account no
+ *  reachable VM holds: names the account asked for and what was seeded instead
+ *  (the fallback donor's account, the host stash's account, or none for the
+ *  token/none modes), plus the remediation. Fall back loudly, never silently —
+ *  the dashboard lifts this line onto the new VM's card as an amber badge. The
+ *  caller shell-quotes it. Pure. */
+function accountFallbackMessage({ requested = "", seeded = "", mode = "none", donor = null, inst = "" } = {}) {
+  const fallback = {
+    donor: donor != null ? `VM-${donor}'s account` : "an unknown account",
+    "host-stash": "the host credential stash's account",
+  };
+  const got = seeded || fallback[mode] || "no Claude account";
+  return `CY_DEGRADED requested Claude account ${requested} is not on any reachable VM — seeded ${got} instead; run claude /login on ${inst} to switch it to ${requested}`;
+}
+
 /** 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
@@ -1215,6 +1403,9 @@ module.exports = {
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
+  branchRefTargets,
+  missingBranchRefs,
+  missingBranchRefMessage,
   addPreflight,
   isVariantProvisionable,
   isVariantRebuildable,
@@ -1227,7 +1418,8 @@ module.exports = {
   HEAVY_ACTIONS,
   queuedStatusForAction,
   pushHistory,
-  distinctConfigs,
+  launchProjectKey,
+  distinctProjectConfigs,
   recentLaunchDisplay,
   defaultConfig,
   configForVm,
@@ -1242,6 +1434,7 @@ module.exports = {
   resolveCredsSource,
   claudeAuthSeeded,
   buildCredsSteps,
+  accountFallbackMessage,
   verifyBeforeMoveSink,
   buildClaudeJsonPreserveSteps,
   buildEnvApplyCommand,

package/npm/orphan-ssh-reaper.js

@@ -0,0 +1,81 @@
+/**
+ * orphan-ssh-reaper.js — sweep the fleet SSH sessions a timed-out gcloud probe
+ * already leaked, before this machine's next sweep adds to them.
+ *
+ * group-bounded-spawn.js stops NEW leaks. A machine that ran the sweep before
+ * that fix may still carry orphans: `gcloud compute ssh` requests a TTY (`-t`),
+ * so an orphaned session has no EOF to notice and no parent to report to — it
+ * simply waits, and they accumulate rather than drain.
+ *
+ * A process is reaped only when BOTH hold:
+ *   - it is an `ssh` carrying the fleet's `HostKeyAlias=compute.` signature
+ *     (gcloud sets the alias to `compute.<instance-id>`), which separates it
+ *     from any other ssh the operator runs; AND
+ *   - it has been re-parented to PID 1. A live sweep's in-flight ssh still has
+ *     its gcloud parent, so the command line alone is never enough.
+ * Limitation: on a Linux host with a user-session subreaper, orphans re-parent
+ * to that subreaper instead of PID 1 and are left alone — the safe direction.
+ */
+
+const { spawnSync } = require("child_process");
+
+const FLEET_SSH_SIGNATURE = /HostKeyAlias=compute\./;
+// The ssh binary itself (`ssh …` or `/usr/bin/ssh …`) — never the gcloud
+// wrapper, whose command line reads `… gcloud.py compute ssh …`.
+const SSH_BINARY = /(^|\/)ssh\s/;
+
+/** Parse `ps -A -o pid=,ppid=,command=` stdout into `{ pid, ppid, command }`
+ *  rows, skipping anything malformed. Pure. */
+function parsePsRows(stdout) {
+  return String(stdout || "")
+    .split("\n")
+    .map((line) => /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line))
+    .filter(Boolean)
+    .map((m) => ({ pid: Number(m[1]), ppid: Number(m[2]), command: m[3] }));
+}
+
+/** Whether one `ps` row is a leaked fleet ssh session. Pure. */
+function isOrphanedFleetSsh(row) {
+  return (
+    row.ppid === 1 &&
+    SSH_BINARY.test(row.command) &&
+    FLEET_SSH_SIGNATURE.test(row.command)
+  );
+}
+
+function defaultRunPs() {
+  return spawnSync("ps", ["-A", "-o", "pid=,ppid=,command="], { encoding: "utf8" });
+}
+
+/** SIGKILL every orphaned fleet ssh and report each one. Returns the reaped
+ *  rows. Best-effort: a `ps` failure logs and reaps nothing, never throws. */
+function reapOrphanedFleetSsh({
+  runPs = defaultRunPs,
+  kill = (pid, signal) => process.kill(pid, signal),
+  log = (line) => console.error(line),
+} = {}) {
+  // Platform assumption: PID-1 re-parenting and `ps -o` are POSIX.
+  if (process.platform === "win32") return [];
+  const res = runPs();
+  if (res.error || res.status !== 0) {
+    const why = (res.error && res.error.message) || `ps exited ${res.status}`;
+    log(`  orphaned-ssh sweep skipped: could not list processes (${why})`);
+    return [];
+  }
+  const reaped = [];
+  for (const row of parsePsRows(res.stdout).filter(isOrphanedFleetSsh)) {
+    try {
+      kill(row.pid, "SIGKILL");
+    } catch {
+      continue; // exited between the listing and the kill
+    }
+    reaped.push(row);
+    log(`  reaped orphaned fleet ssh pid=${row.pid} :: ${row.command.slice(0, 120)}`);
+  }
+  if (reaped.length) {
+    log(`  orphaned-ssh sweep: reaped ${reaped.length} leaked session(s) left by earlier timed-out probes`);
+  }
+  return reaped;
+}
+
+module.exports = { parsePsRows, isOrphanedFleetSsh, reapOrphanedFleetSsh };