@codeyam-editor/codeyam-editor 0.1.9 → 0.1.10

package/npm/cloud.js

@@ -23,6 +23,11 @@ const {
   killChildProcess,
 } = require("./utils");
 const { open } = require("./open");
+// Bounded gcloud/ssh spawns run through spawnGroupBoundedSync so a timeout takes
+// gcloud's ssh descendant down with it instead of orphaning it to PID 1; the
+// reaper sweeps sessions already leaked before that existed.
+const { spawnGroupBoundedSync } = require("./group-bounded-spawn");
+const { reapOrphanedFleetSsh } = require("./orphan-ssh-reaper");
 // `FORWARD_ENV_KEYS_ENV` is the env-var name (`CY_FORWARD_ENV_KEYS`) the
 // fleet dashboard sets on `cloud:up`'s child to name the subset of
 // `process.env` keys that came from the operator-supplied launch form.
@@ -1090,6 +1095,10 @@ function buildGcloudArgs(verb, cfg = {}, extras = {}) {
 // reference one value. 2 min is generous for any single describe/update/SSH probe
 // yet comfortably under the 600000 ms outer reconcile budget.
 //
+// All three spawn through spawnGroupBoundedSync, because a bare spawnSync timeout
+// signals only the direct child: gcloud died and its `ssh` survived, re-parented
+// to PID 1 — the budget bounded the wrapper, never the descendant.
+//
 // It is a PROBE budget, and provisioning is exempt — see
 // GCLOUD_PROVISION_TIMEOUT_MS below. Do not re-collapse the two: raising this
 // constant to accommodate a slow create would un-bound the reconcile sweep,
@@ -1161,7 +1170,7 @@ function isSpawnTimeout(result) {
 }
 
 function runGcloud(args, opts = {}) {
-  return spawnSync("gcloud", args, {
+  return spawnGroupBoundedSync("gcloud", args, {
     stdio: opts.stdio || "inherit",
     input: opts.input,
     encoding: opts.encoding || "utf8",
@@ -4966,6 +4975,10 @@ async function cmdIngressUp(args, projectDir = rootDir) {
 async function cmdReconcileIngress(args, projectDir = rootDir) {
   ensureGcloud();
   parseFlags(args);
+  // Clear ssh sessions earlier timed-out probes leaked before this sweep can add
+  // load of its own. Only PID-1 orphans with the fleet signature — never a live
+  // sweep's in-flight children.
+  reapOrphanedFleetSsh();
   const cfg = loadCloudConfig(projectDir) || {};
   const domain = resolveIngressDomain(cfg, process.env);
   if (!domain) {
@@ -4996,7 +5009,7 @@ async function cmdReconcileIngress(args, projectDir = rootDir) {
     // whole sweep. On timeout res.stdout is empty, so parseIngressStatusVerdict
     // returns null → an `unknown` verdict → selectIngressReconcileTargets SKIPS
     // this VM and the sweep continues to the next one.
-    const res = spawnSync(inv.command, inv.args, {
+    const res = spawnGroupBoundedSync(inv.command, inv.args, {
       env: { ...process.env, ...inv.env },
       encoding: "utf8",
       timeout: GCLOUD_CALL_TIMEOUT_MS,
@@ -5057,7 +5070,7 @@ async function cmdReconcileIngress(args, projectDir = rootDir) {
       // Bound the per-BES converge too: a hung `gcloud backend-services update`
       // returns a non-zero (timed-out) result, so it falls into the skip branch
       // below and the sweep moves on to the next BES rather than stalling.
-      const res = spawnSync(inv.command, inv.args, {
+      const res = spawnGroupBoundedSync(inv.command, inv.args, {
         encoding: "utf8",
         timeout: GCLOUD_CALL_TIMEOUT_MS,
       });

package/npm/fleet-auth-account.js

@@ -0,0 +1,61 @@
+'use strict';
+
+// npm/fleet-auth-account.js — the operator's chosen fleet Claude account
+// (`.codeyam/logs/fleet-auth-account.json`). This is the account a newly added
+// VM authenticates as: the Add path picks a credential donor holding it, and the
+// Add dialog preselects it. Persisted so the choice survives a dashboard restart,
+// and explicit so a background token refresh on some other VM can never re-point
+// it (the drift the derived default in fleet-auth.js is subject to).
+//
+// Shape on disk: { "email": "<account email>", "updatedAt": "<ISO>" }. A seam
+// modeled on fleet-vm-slugs.js: atomic temp-file + rename, tolerant of a
+// missing/malformed file (both read as "never chosen" → null).
+//
+// Env override: `FLEET_AUTH_ACCOUNT_FILE` relocates the file (mirrors
+// fleet-roster.js's `VMS_STATE_FILE`); resolved once at module load.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+const { isAccountEmail } = require('./fleet-auth');
+
+const FLEET_AUTH_ACCOUNT_FILE = process.env.FLEET_AUTH_ACCOUNT_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-auth-account.json');
+
+/** The chosen account email, or null when none has been chosen (file missing,
+ *  malformed, or carrying no email). */
+function readAuthAccount() {
+  try {
+    const data = JSON.parse(fs.readFileSync(FLEET_AUTH_ACCOUNT_FILE, 'utf8'));
+    if (data && typeof data.email === 'string' && data.email.trim()) return data.email.trim();
+  } catch { /* missing or malformed */ }
+  return null;
+}
+
+/** Persist `email` as the fleet's chosen account, atomically: write a temp file
+ *  then `rename` it over the target so a concurrent reader never observes a
+ *  half-written file. Returns the email written. A value that is not a
+ *  plausible email is rejected (nothing is written) — forgetting the choice is
+ *  `clearAuthAccount`. */
+function writeAuthAccount(email) {
+  const e = typeof email === 'string' ? email.trim() : '';
+  if (!isAccountEmail(e)) throw new Error(`not a valid account email: "${e}"`);
+  fs.mkdirSync(path.dirname(FLEET_AUTH_ACCOUNT_FILE), { recursive: true });
+  const tmp = `${FLEET_AUTH_ACCOUNT_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ email: e, updatedAt: new Date().toISOString() }));
+  fs.renameSync(tmp, FLEET_AUTH_ACCOUNT_FILE); // atomic replace
+  return e;
+}
+
+/** Forget the chosen account, so the fleet falls back to the derived default.
+ *  Removing an absent file is a no-op. */
+function clearAuthAccount() {
+  try {
+    fs.unlinkSync(FLEET_AUTH_ACCOUNT_FILE);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+}
+
+module.exports = { FLEET_AUTH_ACCOUNT_FILE, readAuthAccount, writeAuthAccount, clearAuthAccount };

package/npm/fleet-auth.js

@@ -108,9 +108,77 @@ function deriveDefaultAuthAccount(vms, lastAuthAt) {
   return best ? best.account : null;
 }
 
+// Enumerate the Claude accounts the fleet can seed a new VM from: one row per
+// distinct account email held by an authenticated VM, carrying the account
+// object and the VM numbers holding it (so the Add dialog can show
+// "jared@codeyam.com — VM-14"). Pure over the polled VM snapshot — the same
+// array deriveDefaultAuthAccount reads. Emails compare case-insensitively; rows
+// sort by email and each row's VM numbers ascend, so the result is deterministic.
+function listAvailableAccounts(vms) {
+  const byEmail = new Map();
+  for (const v of vms || []) {
+    const pa = v && v.providerAuth;
+    const acct = pa && pa.account;
+    if (!acct || !acct.email || pa.state !== 'authenticated') continue;
+    const key = String(acct.email).toLowerCase();
+    const row = byEmail.get(key) || { account: acct, vms: [] };
+    if (!row.vms.includes(v.n)) row.vms.push(v.n);
+    byEmail.set(key, row);
+  }
+  return [...byEmail.values()]
+    .map((r) => ({ account: r.account, vms: [...r.vms].sort((a, b) => a - b) }))
+    .sort((a, b) => String(a.account.email).localeCompare(String(b.account.email)));
+}
+
+// Pick the credential donor for a chosen account: the lowest-numbered VM in
+// `reachableDonors` whose authenticated account is `email`, or null when no
+// reachable VM holds it (or no email was asked for). `vms` is the per-VM poll
+// state keyed by VM number (`state.vms`). Pure.
+function selectDonorForAccount(reachableDonors, vms, email) {
+  if (!email) return null;
+  const want = String(email).toLowerCase();
+  for (const n of [...(reachableDonors || [])].sort((a, b) => a - b)) {
+    const pa = vms && vms[n] && vms[n].providerAuth;
+    const got = pa && pa.state === 'authenticated' && pa.account && pa.account.email;
+    if (got && String(got).toLowerCase() === want) return n;
+  }
+  return null;
+}
+
+// A plausible Claude account email: one "@", a dotted domain, no whitespace or
+// shell-significant characters. The shared guard for every place an operator
+// can name an account (the Add form's per-launch override, the set-default
+// action, the persisted sidecar). Deliberately NOT checked against the fleet,
+// whose roster can change between naming an account and provisioning with it.
+const ACCOUNT_EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
+function isAccountEmail(s) {
+  return typeof s === 'string' && ACCOUNT_EMAIL_RE.test(s.trim());
+}
+
+// Resolve the fleet's chosen Claude account email: the operator's persisted
+// choice (`saved`, read from npm/fleet-auth-account.js by the caller) when it is
+// a plausible email, else the derived default — the most recently auth-updated
+// VM's account — so a fleet that has never chosen behaves as it did before the
+// picker existed. Pure. Returns an email string, or null when neither exists.
+function resolveChosenAccount(saved, vms, lastAuthAt) {
+  if (isAccountEmail(saved)) return saved.trim();
+  const derived = deriveDefaultAuthAccount(vms, lastAuthAt);
+  return (derived && derived.email) || null;
+}
+
 // Return true if this one VM is eligible for an auth-start action now.
 function isAuthStartable(v, job) {
   return classifyAuthVm(v, job).eligible;
 }
 
-module.exports = { classifyAuthVm, selectAuthTargets, summarizeAuthBatch, deriveDefaultAuthAccount, isAuthStartable };
+module.exports = {
+  classifyAuthVm,
+  selectAuthTargets,
+  summarizeAuthBatch,
+  deriveDefaultAuthAccount,
+  listAvailableAccounts,
+  selectDonorForAccount,
+  isAccountEmail,
+  resolveChosenAccount,
+  isAuthStartable,
+};

package/npm/fleet-public-url.js

@@ -302,10 +302,32 @@ function ingressUnwiredReason({ url, domain, slug, n } = {}) {
  *  to all GFEs (VM5's CORRECT rule 503'd for ~minutes before flipping), so a
  *  per-cycle re-fire would storm the LB while a good change is still
  *  propagating. A missing/0 `lastRewireAt` means "never re-wired" → the window
- *  is satisfied. */
+ *  is satisfied.
+ *
+ *  FOURTH CASE — `routed === 'unrouted'` BYPASSES both `reachable` and the
+ *  `rewirable` backend test above, and that bypass is the whole point. A VM the
+ *  url-map carries no host rule for has no route from its public hostname to
+ *  anything, so it is unreachable BY CONSTRUCTION — gating its self-heal on
+ *  `reachable` gates it on the absence of the very symptom it exists to repair,
+ *  and it can therefore never fire. Observed 2026-09-08 on 3 of 3 freshly-added
+ *  self-host VMs: NEGs created, backend services created, NEGs ATTACHED, and no
+ *  host rule — the add's wiring tail died between the NEG attach and
+ *  `reconcile_host_rule_once`. The backend test misses it for an independent
+ *  reason: the backends WERE attached, so this reads as a genuinely-converging
+ *  'unhealthy' that the gate deliberately excludes. Both exclusions are correct
+ *  for a VM that answers and is merely mis-routed, and both are exactly inverted
+ *  for a VM with no route at all — hence a distinct entry condition rather than
+ *  a relaxation of the existing one. Do NOT "restore" the `reachable`
+ *  precondition on this branch as an obvious safety check; it is what made three
+ *  plainly-broken VMs invisible to the automation for a day.
+ *  'unknown' (the url-map read errored) is NOT 'unrouted' — absence of evidence
+ *  never authorizes a re-wire, matching classifyBackendAttachment's error case.
+ *  The add's own wiring tail is still excluded here by `inFlight`: a VM mid-
+ *  wiring is unrouted-so-far, not broken. */
 function shouldAutoRewireIngress({
   verdict,
   reachable,
+  routed,
   backendEditorHealth,
   backendEditorBackendless,
   inFlight,
@@ -314,21 +336,67 @@ function shouldAutoRewireIngress({
   debounceMs,
 } = {}) {
   if (verdict !== 'unwired') return false;
-  if (!reachable) return false;
-  // 'healthy' = host-rule drift (VM5); 'absent' = backend never created
-  // (interrupted-add VM-4); 'unhealthy' + backendless = BES exists with zero NEG
-  // backends (concurrent-add editor-band race) — it can't converge unaided, so it
-  // re-wires too. A genuinely-converging 'unhealthy' (backend attached, health
-  // flipping → backendless false) and 'unknown' stay excluded.
-  const rewirable =
-    backendEditorHealth === 'healthy' ||
-    backendEditorHealth === 'absent' ||
-    (backendEditorHealth === 'unhealthy' && backendEditorBackendless === true);
-  if (!rewirable) return false;
+  // An unrouted VM skips the reachability + backend-health tests below (see the
+  // FOURTH CASE note above), but never the in-flight and debounce guards — those
+  // are what keep one re-wire per VM per propagation window.
+  const unrouted = routed === 'unrouted';
+  if (!unrouted) {
+    if (!reachable) return false;
+    // 'healthy' = host-rule drift (VM5); 'absent' = backend never created
+    // (interrupted-add VM-4); 'unhealthy' + backendless = BES exists with zero NEG
+    // backends (concurrent-add editor-band race) — it can't converge unaided, so it
+    // re-wires too. A genuinely-converging 'unhealthy' (backend attached, health
+    // flipping → backendless false) and 'unknown' stay excluded.
+    const rewirable =
+      backendEditorHealth === 'healthy' ||
+      backendEditorHealth === 'absent' ||
+      (backendEditorHealth === 'unhealthy' && backendEditorBackendless === true);
+    if (!rewirable) return false;
+  }
   if (inFlight) return false;
   return (Number(now) - (Number(lastRewireAt) || 0)) >= Number(debounceMs);
 }
 
+/** Classify whether the shared fleet url-map routes `host` at all — the input
+ *  `shouldAutoRewireIngress`'s unrouted branch turns on, and a signal no backend
+ *  probe can give. `backendEditorHealth` describes the backend SERVICE; none of
+ *  its four values can express "nothing routes here", which is why all three of
+ *  the 2026-09-08 stranded VMs classified as a converging 'unhealthy' while
+ *  carrying no host rule at all. Reads:
+ *
+ *    'routed'   — `host` appears verbatim among the url-map's host rules.
+ *    'unrouted' — the read SUCCEEDED, listed at least one host rule, and `host`
+ *                 is not among them. This is the only reading that authorizes a
+ *                 re-wire, and it requires positive evidence of a populated map.
+ *    'unknown'  — the read errored, produced nothing, or no host was asked for.
+ *
+ *  EMPTY OUTPUT IS 'unknown', NOT 'unrouted', and the distinction is load-
+ *  bearing. A url-map that lists zero host rules is indistinguishable from a
+ *  read that silently returned nothing, and reading it as 'unrouted' would
+ *  authorize a simultaneous re-wire for EVERY VM in the fleet off a single
+ *  unreliable read — the re-wire storm classifyBackendAttachment's error case
+ *  exists to prevent, at fleet scale. Absence of evidence never manufactures a
+ *  fault.
+ *
+ *  Matching is by exact token, never substring: gcloud flattens
+ *  `value(hostRules.hosts)` with whitespace and `;` separators, and a substring
+ *  test would read `vm-2.editor.<domain>` as routed on the strength of an
+ *  unrelated `staging.vm-2.editor.<domain>` rule.
+ *
+ *  Takes the raw (err, stdout) pair rather than a VM number so it stays PURE and
+ *  needs no domain/slug derivation — the same I/O-edge / pure-half split
+ *  classifyBackendAttachment follows. The caller derives `host` from
+ *  google-ingress's `urlMapHostRules` / vmUrls and does the gcloud read. */
+function classifyUrlMapRouting(err, stdout, host) {
+  if (err) return 'unknown';
+  if (!host) return 'unknown';
+  const hosts = String(stdout == null ? '' : stdout)
+    .split(/[\s;,]+/)
+    .filter(Boolean);
+  if (hosts.length === 0) return 'unknown';
+  return hosts.includes(String(host)) ? 'routed' : 'unrouted';
+}
+
 /** Classify a `gcloud compute backend-services describe --format=value(backends[].group)`
  *  result into the attachment vocabulary — the signal `get-health` cannot give,
  *  because an empty health result is ambiguous between "no backend attached" and
@@ -390,5 +458,6 @@ module.exports = {
   ingressUnwiredReason,
   shouldAutoRewireIngress,
   classifyBackendAttachment,
+  classifyUrlMapRouting,
   classifyUrlWiringState,
 };

package/npm/fleet-reconcile.js

@@ -59,16 +59,33 @@ function strandedAdoptDecision({ stranded, streaks, threshold } = {}) {
   return { streaks: next, ready };
 }
 
+// Each entry maps a degraded-reason shape to the live witness that disconfirms
+// it. Extend the table as new degraded reasons gain a corresponding signal.
+//
+// TWO SHAPES PER CLASS, ON PURPOSE. The dashboard writes its auth reason under
+// the structured `claude-auth-not-seeded:` prefix (server.js, and the prefix
+// two other call sites key on), but the original free-text pattern needs a
+// SPACE — `/claude auth/` never matches the hyphenated prefix. Such reasons
+// cleared only because the canned message happens to contain the word "login";
+// phrased any other way they were retained forever, which is the reported bug
+// surviving in the one form the reconcile was aimed at. Matching the prefix
+// only would be the opposite mistake: reasons like `claude auth copy failed on
+// VM-2 (…)` are already recorded in live snapshots and carry no prefix at all,
+// so both shapes have to match.
+const REASON_WITNESSES = [
+  { match: /^\s*claude-auth-not-seeded\b/i, witness: 'authed' },
+  { match: /claude auth|claude\.json|login/i, witness: 'authed' },
+  { match: /container|never came up|provisioning failed/i, witness: 'reachableServing' },
+];
+
 // Map a single degraded reason to the live health signal that resolves it.
 // Returns true only when that signal now passes; a reason with no mapped signal
 // returns false (retained — a genuine config problem, never a false-green).
-// Start with the two observed classes (improve41); extend the table as new
-// degraded reasons gain a corresponding live signal.
 function reasonClearedByHealth(reason, { reachableServing, authed }) {
   const r = String(reason || '');
-  if (/claude auth|claude\.json|login/i.test(r)) return authed;
-  if (/container|never came up|provisioning failed/i.test(r)) return reachableServing;
-  return false;
+  const entry = REASON_WITNESSES.find((e) => e.match.test(r));
+  if (!entry) return false;
+  return entry.witness === 'authed' ? !!authed : !!reachableServing;
 }
 
 // Given a terminal add-job badge and the VM's live health, return the corrected
@@ -79,7 +96,14 @@ function reasonClearedByHealth(reason, { reachableServing, authed }) {
 // facts (I/O at the edge) and applies the result; the verdict itself is pure.
 //   job:    { state: 'done'|'error', degraded, degradedReasons }
 //   health: { reachable, editorHttpOk, providerAuthState }
-//   → null | { state, degraded, degradedReasons, transition }
+//   → null | { state, degraded, degradedReasons, retiredReasons, transition }
+//
+// `retiredReasons` names the reasons this verdict just dropped. Without it a
+// retired reason simply vanishes from the card, so an operator who saw amber
+// never learns it resolved — the shell renders these as the same muted
+// "recovered (was: …)" trace the reconciled error badge already leaves. What
+// that trace should SAY is the shell's call; naming what was retired is this
+// module's.
 function reconcileTerminalAddBadge({ job, health } = {}) {
   if (!job || !health) return null;
   const reachableServing = !!(health.reachable && health.editorHttpOk);
@@ -91,7 +115,13 @@ function reconcileTerminalAddBadge({ job, health } = {}) {
   if (job.state === 'error') {
     const reasons = job.degradedReasons || [];
     if (reasons.length === 0 && reachableServing) {
-      return { state: 'done', degraded: false, degradedReasons: [], transition: 'error→done (editor 200)' };
+      return {
+        state: 'done',
+        degraded: false,
+        degradedReasons: [],
+        retiredReasons: [],
+        transition: 'error→done (editor 200)',
+      };
     }
     return null;
   }
@@ -100,15 +130,20 @@ function reconcileTerminalAddBadge({ job, health } = {}) {
   // passes; retain the rest. Drop `degraded` only when no reasons remain.
   if (job.state === 'done' && job.degraded) {
     const reasons = job.degradedReasons || [];
-    const remaining = reasons.filter((reason) => !reasonClearedByHealth(reason, { reachableServing, authed }));
-    if (remaining.length === reasons.length) return null; // nothing cleared → no-op
-    const cleared = reasons.length - remaining.length;
+    const remaining = [];
+    const retired = [];
+    for (const reason of reasons) {
+      const bucket = reasonClearedByHealth(reason, { reachableServing, authed }) ? retired : remaining;
+      bucket.push(reason);
+    }
+    if (retired.length === 0) return null; // nothing cleared → no-op
     return {
       state: 'done',
       degraded: remaining.length > 0,
       degradedReasons: remaining,
+      retiredReasons: retired,
       transition: remaining.length > 0
-        ? `degraded: cleared ${cleared} reason(s), ${remaining.length} remain`
+        ? `degraded: cleared ${retired.length} reason(s), ${remaining.length} remain`
         : 'degraded→clear (health restored)',
     };
   }

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 };